/[svn]/linuxsampler/trunk/Documentation/lscp.xml
ViewVC logotype

Annotation of /linuxsampler/trunk/Documentation/lscp.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 206 - (hide annotations) (download) (as text)
Wed Jul 14 19:27:53 2004 UTC (19 years, 8 months ago) by schoenebeck
File MIME type: text/xml
File size: 164409 byte(s)
fixed little accident in section 5.4.10 that happened by the conversion
from the document's old OpenOffice format

1 schoenebeck 151 <?xml version="1.0" encoding="UTF-8"?>
2    
3     <!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
4     <!ENTITY rfc2119 PUBLIC ''
5     'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
6     ]>
7    
8     <?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
9    
10     <?rfc toc="yes" ?>
11     <?rfc symrefs="yes" ?>
12     <?rfc sortrefs="yes"?>
13     <?rfc iprnotified="no" ?>
14     <?rfc strict="yes" ?>
15    
16     <rfc category="std" ipr="full2026" docName="lscp.txt">
17     <front>
18     <title>LinuxSampler Control Protocol</title>
19     <author initials='C.S.' surname="Schoenebeck" fullname='C.
20     Schoenebeck'>
21     <organization>
22     Interessengemeinschaft Software Engineering e. V.
23     </organization>
24     <address>
25     <postal>
26     <street>Max-Planck-Str. 39</street>
27     <!-- <code>74081</code> -->
28     <city>74081 Heilbronn</city>
29     <country>Germany</country>
30     </postal>
31     <email>schoenebeck at software minus engineering dot org</email>
32     </address>
33     </author>
34     <date month="June" year="2004"/>
35     <workgroup>LinuxSampler Developers</workgroup>
36     <keyword>LSCP</keyword>
37     <abstract>
38     <t>The LinuxSampler Control Protocol (LSCP) is an
39     application-level protocol primarily intended for local and
40     remote controlling the LinuxSampler main application, which is a
41     sophisticated console application essentially playing back audio
42     samples and manipulating the samples in real time to certain
43     extent.</t>
44     </abstract>
45     </front>
46    
47     <middle>
48     <section title="Requirements notation">
49     <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
50     "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
51     and "OPTIONAL" in this document are to be interpreted as
52     described in <xref target="RFC2119"/>.</t>
53    
54     <t>This protocol is always case-sensitive if not explicitly
55     claimed the opposite.</t>
56    
57     <t>In examples, "C:" and "S:" indicate lines sent by the client
58     (front-end) and server (LinuxSampler) respectively. Lines in
59     examples must be interpreted as every line being CRLF
60     terminated (carriage return character followed by line feed
61     character as defined in the ASCII standard), thus the following
62     example:</t>
63    
64     <t>
65     <list>
66     <t>C: "some line"</t>
67     <t>&nbsp;&nbsp;&nbsp;"another line"</t>
68     </list>
69     </t>
70    
71     <t>must actually be interpreted as client sending the following
72     message:</t>
73    
74     <t>
75     <list>
76     <t>"some line&lt;CR&gt;&lt;LF&gt;another
77     line&lt;CR&gt;&lt;LF&gt;"</t>
78     </list>
79     </t>
80    
81     <t>where &lt;CR&gt; symbolizes the carriage return character and
82     &lt;LF&gt; the line feed character as defined in the ASCII
83     standard.</t>
84    
85     <t>Due to technical reasons, messages can arbitrary be
86     fragmented, means the following example:</t>
87    
88     <t>
89     <list>
90     <t>S: "abcd"</t>
91     </list>
92     </t>
93    
94     <t>could also happen to be sent in three messages like in the
95     following sequence scenario:</t>
96    
97     <t>
98     <list style="symbols">
99     <t>server sending message "a"</t>
100     <t>followed by a delay (pause) with
101     arbitrary duration</t>
102     <t>followed by server sending message
103     "bcd&lt;CR&gt;"</t>
104     <t>again followed by a delay (pause) with arbitrary
105     duration</t>
106     <t>followed by server sending the message
107     "&lt;LF&gt;"</t>
108     </list>
109     </t>
110    
111     <t>where again &lt;CR&gt; and &lt;LF&gt; symbolize the carriage
112     return and line feed characters respectively.</t>
113     </section>
114    
115     <section title="Introduction">
116     <t>LinuxSampler is a so called software sampler application
117     capable to playback audio samples from a computer's Random
118     Access Memory (RAM) as well as directly streaming it from disk.
119     LinuxSampler is designed to be modular. It provides several so
120     called "sampler engines" where each engine is specialized for a
121     certain purpose. LinuxSampler has virtual channels which will be
122     referred in this document as "sampler channels". The channels
123     are in such way virtual as they can be connected to an
124     arbitrary MIDI input method and arbitrary MIDI channel (e.g.
125     sampler channel 17 could be connected to an Alsa sequencer
126     device 64:0 and listening to MIDI channel 1 there). Each sampler
127     engine will be assigned an own instance of one of the available
128     sampler engines (e.g. GigEngine, DLSEngine). The audio output of
129     each sampler channel can be routed to an arbitrary audio output
130     method (Alsa / Jack) and an arbitrary audio output channel
131     there.</t>
132     </section>
133    
134     <section title="Focus of this protocol">
135     <t>Main focus of this protocol is to provide a way to configure
136     a running LinuxSampler instance and to retrieve information
137     about it. The focus of this protocol is not to provide a way to
138     control synthesis parameters or even to trigger or release
139     notes. Or in other words; the focus are those functionalities
140     which are not covered by MIDI or which may at most be handled
141     via MIDI System Exclusive Messages.</t>
142     </section>
143    
144     <section title="Communication Overview">
145     <t>There are two distinct methods of communication between a
146     running instance of LinuxSampler and one or more control
147     applications, so called "front-ends": a simple request/response
148     communication method used by the clients to give commands to the
149     server as well as to inquire about server's status and a
150     subscribe/notify communication method used by the client to
151     subscribe to and receive notifications of certain events as they
152     happen on the server. The latter needs more effort to be
153     implemented in the front-end application. The two communication
154     methods will be described next.</t>
155    
156     <section title="Request/response communication method">
157     <t>This simple communication method is based on TCP. The
158     front-end application establishes a TCP connection to the
159     LinuxSampler instance on a certain host system. Then the
160     front-end application will send certain ASCII based commands
161     as defined in this document (every command line must be CRLF
162     terminated - see "Conventions used in this document" at the
163     beginning of this document) and the LinuxSampler application
164     will response after a certain process time with an
165     appropriate ASCII based answer, also as defined in this
166     document. So this TCP communication is simply based on query
167     and answer paradigm. That way LinuxSampler is only able to
168     answer on queries from front-ends, but not able to
169     automatically send messages to the client if it's not asked
170     to. The fronted should not reconnect to LinuxSampler for
171     every single command, instead it should keep the connection
172     established and simply resend message(s) for subsequent
173     commands. To keep information in the front-end up-to-date
174     the front-end has to periodically send new requests to get
175     the current information from the LinuxSampler instance. This
176     is often referred to as "polling". While polling is simple
177     to implement and may be OK to use in some cases, there may
178     be disadvantages to polling such as network traffic overhead
179     and information being out of date.
180     It is possible for a client or several clients to open more
181     than one connection to the server at the same time. It is
182     also possible to send more than one request to the server
183     at the same time but if those requests are sent over the
184     same connection server MUST execute them sequentially. Upon
185     executing a request server will produce a result set and
186     send it to the client. Each and every request made by the
187     client MUST result in a result set being sent back to the
188     client. No other data other than a result set may be sent by
189     a server to a client. No result set may be sent to a client
190     without the client sending request to the server first. On
191     any particular connection, result sets MUST be sent in their
192     entirety without being interrupted by other result sets. If
193     several requests got queued up at the server they MUST be
194     processed in the order they were received and result sets
195     MUST be sent back in the same order.</t>
196    
197     <section title="Result format">
198     <t>Result set could be one of the following types:</t>
199     <t>
200     <list style="numbers">
201     <t>Normal</t>
202     <t>Warning</t>
203     <t>Error</t>
204     </list>
205     </t>
206     <t>Warning and Error result sets MUST be single line and
207     have the following format:</t>
208     <t>
209     <list style="symbols">
210     <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;"</t>
211     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;"</t>
212     </list>
213     </t>
214     <t>Where &lt;warning-code&gt; and &lt;error-code&gt; are
215     numeric unique identifiers of the warning or error and
216     &lt;warning-message&gt; and &lt;error-message&gt; are
217     human readable descriptions of the warning or error
218     respectively.</t>
219     <t>Normal result sets could be:</t>
220     <t>
221     <list style="numbers">
222     <t>Empty</t>
223     <t>Single line</t>
224     <t>Multi-line</t>
225     </list>
226     </t>
227     <t> Empty result set is issued when the server only
228     needed to acknowledge the fact that the request was
229     received and it was processed successfully and no
230     additional information is available. This result set has
231     the following format:</t>
232     <t>
233     <list>
234     <t>"OK"</t>
235     </list>
236     </t>
237     <t>Single line result sets are command specific. One
238     example of a single line result set is an empty line.
239     Multi-line result sets are command specific and may
240     include one or more lines of information. They MUST
241     always end with the following line:</t>
242     <t>
243     <list>
244     <t>"."</t>
245     </list>
246     </t>
247     <t>In addition to above mentioned formats, warnings and
248     empty result sets MAY be indexed. In this case, they
249     have the following formats respectively:</t>
250     <t>
251     <list style="symbols">
252     <t>"WRN[&lt;index&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;"</t>
253     <t>"OK[&lt;index&gt;]"</t>
254     </list>
255     </t>
256     <t>where &lt;index&gt; is command specific and is used
257     to indicate channel number that the result set was
258     related to or other integer value.</t>
259     <t>Each line of the result set MUST end with
260     &lt;CRLF&gt;.</t>
261     </section>
262     </section>
263     <section title="Subscribe/notify communication method">
264     <t>This more sophisticated communication method is actually
265     only an extension of the simple request/response
266     communication method. The front-end still uses a TCP
267     connection and sends the same commands on the TCP
268     connection. Two extra commands are SUBSCRIBE and UNSUBSCRIBE
269     commands that allow a client to tell the server that it is
270     interested in receiving notifications about certain events
271     as they happen on the server. The SUBSCRIBE command has the
272     following syntax:</t>
273    
274     <t>
275     <list>
276     <t>SUBSCRIBE &lt;event-id&gt;</t>
277     </list>
278     </t>
279    
280     <t>where &lt;event-id&gt; will be replaced by the respective
281     event that client wants to subscribe to. Upon receiving such
282     request, server SHOULD respond with OK and start sending
283     EVENT notifications when a given even has occurred to the
284     front-end when an event has occurred. It MAY be possible
285     certain events may be sent before OK response during real
286     time nature of their generation. Event messages have the
287     following format:</t>
288    
289     <t>
290     <list>
291     <t>NOTIFY:&lt;event-id&gt;:&lt;custom-event-data&gt;</t>
292     </list>
293     </t>
294    
295     <t>where &lt;event-id&gt; uniquely identifies the event that
296     has occurred and &lt;custom-event-data&gt; is event
297     specific.</t>
298    
299     <t>Several rules must be followed by the server when
300     generating events:</t>
301    
302     <t>
303     <list style="numbers">
304     <t>Events MUST NOT be sent to any client who has not
305     issued an appropriate SUBSCRIBE command.</t>
306     <t>Events MUST only be sent using the same
307     connection that was used to subscribe to them.</t>
308     <t>When response is being sent to the client, event
309     MUST be inserted in the stream before or after the
310     response, but NOT in the middle. Same is true about
311     the response. It should never be inserted in the
312     middle of the event message as well as any other
313     response.</t>
314     </list>
315     </t>
316    
317     <t>If the client is not interested in a particular event
318     anymore it MAY issue UNSUBSCRIBE command using the following
319     syntax:</t>
320    
321     <t>
322     <list>
323     <t>UNSUBSCRIBE &lt;event-id&gt;</t>
324     </list>
325     </t>
326    
327     <t>where &lt;event-id&gt; will be replace by the respective
328     event that client is no longer interested in receiving. For
329     a list of supported events see chapter 6.</t>
330    
331     <t>Example: the fill states of disk stream buffers have
332     changed on sampler channel 4 and the LinuxSampler instance
333     will react by sending the following message to all clients
334     who subscribed to this event:</t>
335    
336     <t>
337     <list>
338     <t>NOTIFY:CHANNEL_BUFFER_FILL:4 [35]62%,[33]80%,[37]98%</t>
339     </list>
340     </t>
341    
342     <t>Which means there are currently three active streams on
343     sampler channel 4, where the stream with ID "35" is filled
344     by 62%, stream with ID 33 is filled by 80% and stream with
345     ID 37 is filled by 98%.</t>
346    
347     <t>Clients may choose to open more than one connection to
348     the server and use some connections to receive notifications
349     while using other connections to issue commands to the
350     back-end. This is entirely legal and up to the
351     implementation. This does not change the protocol in any way
352     and no special restrictions exist on the server to allow or
353     disallow this or to track what connections belong to what
354     front-ends. Server will listen on a single port, accept
355     multiple connections and support protocol described in this
356     specification in it's entirety on this single port on each
357     connection that it accepted.</t>
358    
359     <t>Due to the fact that TCP is used for this communication,
360     dead peers will be detected automatically by the OS TCP
361     stack. While it may take a while to detect dead peers if no
362     traffic is being sent from server to client (TCP keep-alive
363     timer is set to 2 hours on many OSes) it will not be an
364     issue here as when notifications are sent by the server,
365     dead client will be detected quickly.</t>
366    
367     <t>When connection is closed for any reason server MUST
368     forget all subscriptions that were made on this connection.
369     If client reconnects it MUST resubscribe to all events that
370     it wants to receive.</t>
371    
372     </section>
373     </section>
374    
375     <section title="Description for control commands">
376     <t>This chapter will describe the available control commands
377     that can be sent on the TCP connection in detail. Some certain
378     commands (e.g. "GET CHANNEL INFO" or "GET ENGINE INFO") lead to
379     multiple-line responses. In this case LinuxSampler signals the
380     end of the response by a "." (single dot) line.</t>
381    
382     <section title="Ignored lines and comments">
383     <t>White lines, that is lines which only contain space and
384     tabulator characters, and lines that start with a "#"
385     character are ignored, thus it's possible for example to
386     group commands and to place comments in a LSCP script
387     file.</t>
388     </section>
389    
390     <section title="Configuring audio drivers">
391     <t>Instances of drivers in LinuxSampler are called devices.
392     You can use multiple audio devices simultaneously, e.g. to
393     output the sound of one sampler channel using the Alsa audio
394     output driver, and on another sampler channel you might want
395     to use the Jack audio output driver. For particular audio
396     output systems it's also possible to create several devices
397     of the same audio output driver, e.g. two separate Alsa
398     audio output devices for using two different sound cards at
399     the same time. This chapter describes all commands to
400     configure LinuxSampler's audio output devices and their
401     parameters.</t>
402    
403     <t>Instead of defining commands and parameters for each
404     driver individually, all possible parameters, their meanings
405     and possible values have to be obtained at runtime. This
406     makes the protocol a bit abstract, but has the advantage,
407     that front-ends can be written independently of what drivers
408     are currently implemented and what parameters these drivers
409     are actually offering. This means front-ends can even handle
410     drivers which are implemented somewhere in future without
411     modifying the front-end at all.</t>
412    
413     <t>Note: examples in this chapter showing particular
414     parameters of drivers are not meant as specification of the
415     drivers' parameters. Driver implementations in LinuxSampler
416     might have complete different parameter names and meanings
417     than shown in these examples or might change in future, so
418     these examples are only meant for showing how to retrieve
419     what parameters drivers are offering, how to retrieve their
420     possible values, etc.</t>
421    
422     <section title="Getting all available audio output drivers">
423     <t>Use the following command to list all audio output
424     drivers currently available for the LinuxSampler
425     instance:</t>
426     <t>
427     <list>
428     <t>GET AVAILABLE_AUDIO_OUTPUT_DRIVERS</t>
429     </list>
430     </t>
431     <t>Possible Answers:</t>
432     <t>
433     <list>
434     <t>LinuxSampler will answer by sending comma
435     separated character strings, each symbolizing an
436     audio output driver.</t>
437     </list>
438     </t>
439     <t>Example:</t>
440     <t>
441     <list>
442     <t>C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"</t>
443     <t>S: "Alsa,Jack"</t>
444     </list>
445     </t>
446     </section>
447    
448     <section title="Getting information about a specific audio
449     output driver">
450     <t>Use the following command to get detailed information
451     about a specific audio output driver:</t>
452     <t>
453     <list>
454     <t>GET AUDIO_OUTPUT_DRIVER INFO
455     &lt;audio-output-driver&gt;</t>
456     </list>
457     </t>
458     <t>Where &lt;audio-output-driver&gt; is the name of the
459     audio output driver, returned by the "GET
460     AVAILABLE_AUDIO_OUTPUT_DRIVERS" command.</t>
461     <t>Possible Answers:</t>
462     <t>
463     <list>
464     <t>LinuxSampler will answer by sending a
465     &lt;CRLF&gt; separated list. Each answer line
466     begins with the information category name
467     followed by a colon and then a space character
468     &lt;SP&gt; and finally the info character string
469     to that info category. At the moment the
470     following information categories are
471     defined:</t>
472    
473     <t>
474     <list>
475     <t>DESCRIPTION -
476     <list>
477     <t> character string describing the
478     audio output driver</t>
479     </list>
480     </t>
481    
482     <t>VERSION -
483     <list>
484     <t>character string reflecting the
485     driver's version</t>
486     </list>
487     </t>
488    
489     <t>PARAMETERS -
490     <list>
491     <t>comma separated list of all
492     parameters available for the given
493     audio output driver, at least
494     parameters 'channels', 'samplerate'
495     and 'active' are offered by all audio
496     output drivers</t>
497     </list>
498     </t>
499     </list>
500     </t>
501    
502     <t>The mentioned fields above don't have to be
503     in particular order.</t>
504     </list>
505     </t>
506     <t>Example:</t>
507     <t>
508     <list>
509     <t>C: "GET AUDIO_OUTPUT_DRIVER INFO Alsa"</t>
510     <t>S: "DESCRIPTION: Advanced Linux Sound
511     Architecture"</t>
512     <t>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"</t>
513     <t>&nbsp;&nbsp;&nbsp;"PARAMETERS:
514     driver,channels,samplerate,active,fragments,
515     fragmentsize,card"</t>
516     <t>&nbsp;&nbsp;&nbsp;"."</t>
517     </list>
518     </t>
519     </section>
520    
521     <section title="Getting information about specific audio
522     output driver parameter">
523     <t>Use the following command to get detailed information
524     about a specific audio output driver parameter:</t>
525     <t>
526     <list>
527     <t>GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO &lt;audio&gt; &lt;prm&gt; [&lt;deplist&gt;]</t>
528     </list>
529     </t>
530     <t>Where &lt;audio&gt; is the name of the audio output
531     driver as returned by the "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS" command,
532     &lt;prm&gt; a specific parameter name for which information should be
533     obtained (as returned by the "GET AUDIO_OUTPUT_DRIVER INFO" command) and
534     &lt;deplist&gt; is an optional list of parameters on which the sought
535     parameter &lt;prm&gt; depends on, &lt;deplist&gt; is a list of key-value
536     pairs in form of "key1=val1 key2=val2 ...", where character string values
537     are encapsulated into apostrophes ('). Arguments given with &lt;deplist&gt;
538     which are not dependency parameters of &lt;prm&gt; will be ignored, means
539     the front-end application can simply put all parameters into &lt;deplist&gt;
540     with the values already selected by the user.</t>
541     <t>Possible Answers:</t>
542     <t>
543     <list>
544     <t>LinuxSampler will answer by sending a
545     &lz;CRLF&gt; separated list.
546     Each answer line begins with the information category name
547     followed by a colon and then a space character &lt;SP&gt; and
548     finally
549     the info character string to that info category. There are
550     information which is always returned, independently of the
551     given driver parameter and there are optional information
552     which is only shown dependently to given driver parameter. At
553     the moment the following information categories are defined:</t>
554     </list>
555     </t>
556    
557     <t>
558     <list>
559     <t>TYPE -
560     <list>
561     <t>either "BOOL" for boolean value(s) or
562     "INT" for integer
563     value(s) or "FLOAT" for dotted number(s) or "STRING" for
564     character string(s)
565     (always returned, no matter which driver parameter)</t>
566     </list>
567     </t>
568    
569     <t>DESCRIPTION -
570     <list>
571     <t>arbitrary text describing the purpose of the parameter
572     (always returned, no matter which driver parameter)</t>
573     </list>
574     </t>
575    
576     <t>MANDATORY -
577     <list>
578     <t>either true or false, defines if this parameter must be
579     given when the device is to be created with the
580     'CREATE AUDIO_OUTPUT_DEVICE' command
581     (always returned, no matter which driver parameter)</t>
582     </list>
583     </t>
584    
585     <t>FIX -
586     <list>
587     <t>either true or false, if false then this parameter can
588     be changed at any time, once the device is created by
589     the 'CREATE AUDIO_OUTPUT_DEVICE' command
590     (always returned, no matter which driver parameter)</t>
591     </list>
592     </t>
593    
594     <t>MULTIPLICITY -
595     <list>
596     <t>either true or false, defines if this parameter allows
597     only one value or a list of values, where true means
598     multiple values and false only a single value allowed
599     (always returned, no matter which driver parameter)</t>
600     </list>
601     </t>
602    
603     <t>DEPENDS -
604     <list>
605     <t>comma separated list of paramters this parameter depends
606     on, means the values for fields 'DEFAULT', 'RANGE_MIN',
607     'RANGE_MAX' and 'POSSIBILITIES' might depend on these
608     listed parameters, for example assuming that an audio
609     driver (like the Alsa driver) offers parameters 'card'
610     and 'samplerate' then parameter 'samplerate' would
611     depend on 'card' because the possible values for
612     'samplerate' depends on the sound card which can be
613     chosen by the 'card' parameter
614     (optionally returned, dependent to driver parameter)</t>
615     </list>
616     </t>
617    
618     <t>DEFAULT -
619     <list>
620     <t>reflects the default value for this parameter which is
621     used when the device is created and not explicitly
622     given with the 'CREATE AUDIO_OUTPUT_DEVICE' command,
623     in case of MULTIPLCITY=true, this is a comma separated
624     list, that's why character strings are encapsulated into
625     apostrophes (')
626     (optionally returned, dependent to driver parameter)</t>
627     </list>
628     </t>
629    
630     <t>RANGE_MIN -
631     <list>
632     <t>defines lower limit of the allowed value range for this
633     parameter, can be an integer value as well as a dotted
634     number, this parameter is often used in conjunction
635     with RANGE_MAX, but may also appear without
636     (optionally returned, dependent to driver parameter)</t>
637     </list>
638     </t>
639    
640     <t>RANGE_MAX -
641     <list>
642     <t>defines upper limit of the allowed value range for this
643     parameter, can be an integer value as well as a dotted
644     number, this parameter is often used in conjunction with
645     RANGE_MIN, but may also appear without
646     (optionally returned, dependent to driver parameter)</t>
647     </list>
648     </t>
649    
650     <t>POSSIBILITES -
651     <list>
652     <t>comma separated list of possible values for this
653     parameter, character strings are encapsulated into
654     apostrophes
655     (optionally returned, dependent to driver parameter)</t>
656     </list>
657     </t>
658     </list>
659     </t>
660    
661     <t>The mentioned fields above don't have to be in particular order.</t>
662    
663     <t>Examples:</t>
664     <t>
665     <list>
666     <t>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO Alsa card"</t>
667     <t>S: "DESCRIPTION: sound card to be used"</t>
668     <t>&nbsp;&nbsp;&nbsp;"TYPE: STRING"</t>
669     <t>&nbsp;&nbsp;&nbsp;"MANDATORY: false"</t>
670     <t>&nbsp;&nbsp;&nbsp;"FIX: true"</t>
671     <t>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"</t>
672     <t>&nbsp;&nbsp;&nbsp;"DEFAULT: '0,0'"</t>
673     <t>&nbsp;&nbsp;&nbsp;"POSSIBILITES: '0,0','1,0','2,0'"</t>
674     <t>&nbsp;&nbsp;&nbsp;"."</t>
675     </list>
676     </t>
677     <t>
678     <list>
679     <t>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO Alsa samplerate"</t>
680     <t>S: "DESCRIPTION: output sample rate in Hz"</t>
681     <t>&nbsp;&nbsp;&nbsp;"TYPE: INT"</t>
682     <t>&nbsp;&nbsp;&nbsp;"MANDATORY: false"</t>
683     <t>&nbsp;&nbsp;&nbsp;"FIX: false"</t>
684     <t>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"</t>
685     <t>&nbsp;&nbsp;&nbsp;"DEPENDS: card"</t>
686     <t>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"</t>
687     <t>&nbsp;&nbsp;&nbsp;"."</t>
688     </list>
689     </t>
690     <t>
691     <list>
692     <t>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO Alsa samplerate card='0,0'"</t>
693     <t>S: "DESCRIPTION: output sample rate in Hz"</t>
694     <t>&nbsp;&nbsp;&nbsp;"TYPE: INT"</t>
695     <t>&nbsp;&nbsp;&nbsp;"MANDATORY: false"</t>
696     <t>&nbsp;&nbsp;&nbsp;"FIX: false"</t>
697     <t>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"</t>
698     <t>&nbsp;&nbsp;&nbsp;"DEPENDS: card"</t>
699     <t>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"</t>
700     <t>&nbsp;&nbsp;&nbsp;"RANGE_MIN: 22050"</t>
701     <t>&nbsp;&nbsp;&nbsp;"RANGE_MAX: 96000"</t>
702     <t>&nbsp;&nbsp;&nbsp;"."</t>
703     </list>
704     </t>
705     </section>
706    
707     <section title="Creating an audio output device">
708     <t>Use the following command to create a new audio output device for the desired audio output system:</t>
709    
710     <t>
711     <list>
712     <t>CREATE AUDIO_OUTPUT_DEVICE &lt;audio-output-driver&gt; [&lt;param-list&gt;]</t>
713     </list>
714     </t>
715    
716     <t>Where &lt;audio-output-driver&gt; should be replaced by the desired audio
717     output system and &lt;param-list&gt; by an optional list of driver
718     specific parameters in form of "key1=val1 key2=val2 ...", where
719     character string values should be encapsulated into apostrophes (').
720     Note that there might be drivers which require parameter(s) to be
721     given with this command. Use the previously described commands in
722     this chapter to get this information.</t>
723    
724     <t>Possible Answers:</t>
725     <t>
726     <list>
727     <t>"OK[&lt;device-id&gt;]" -
728     <list>
729     <t>in case the device was successfully created, where
730     &lt;device-id&gt; is the numerical ID of the new device</t>
731     </list>
732     </t>
733     <t>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
734     <list>
735     <t>in case the device was created successfully, where
736     &lt;device-id&gt; is the numerical ID of the new device, but there
737     are noteworthy issue(s) related (e.g. sound card doesn't
738     support given hardware parameters and the driver is using
739     fall-back values), providing an appropriate warning code and
740     warning message</t>
741     </list>
742     </t>
743     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
744     <list>
745     <t>in case it failed, providing an appropriate error code and error message</t>
746     </list>
747     </t>
748     </list>
749     </t>
750     <t>Examples:</t>
751     <t>
752     <list>
753     <t>C: "CREATE AUDIO_OUTPUT_DEVICE Alsa"</t>
754     <t>S: "OK[0]"</t>
755     </list>
756     </t>
757     <t>
758     <list>
759     <t>C: "CREATE AUDIO_OUTPUT_DEVICE Alsa card='2,0' samplerate=96000"</t>
760     <t>S: "OK[1]"</t>
761     </list>
762     </t>
763     </section>
764    
765     <section title="Destroying an audio output device">
766     <t>Use the following command to destroy a created output device:</t>
767     <t>
768     <list>
769     <t>DESTROY AUDIO_OUTPUT_DEVICE &lt;device-id&gt;</t>
770     </list>
771     </t>
772     <t>Where &lt;device-id&gt; should be replaced by the numerical ID of the
773     audio output device as given by the "CREATE AUDIO_OUTPUT_DEVICE" or
774     "GET AUDIO_OUTPUT_DEVICES" command.</t>
775     <t>Possible Answers:</t>
776     <t>
777     <list>
778     <t>"OK" -
779     <list>
780     <t>in case the device was successfully destroyed</t>
781     </list>
782     </t>
783     <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
784     <list>
785     <t>in case the device was destroyed successfully, but there are
786     noteworthy issue(s) related (e.g. an audio over ethernet
787     driver was unloaded but the other host might not be
788     informed about this situation), providing an appropriate
789     warning code and warning message</t>
790     </list>
791     </t>
792     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
793     <list>
794     <t>in case it failed, providing an appropriate error code and
795     error message</t>
796     </list>
797     </t>
798     </list>
799     </t>
800     <t>Example:</t>
801     <t>
802     <list>
803     <t>C: "DESTROY AUDIO_OUTPUT_DEVICE 0"</t>
804     <t>S: "OK"</t>
805     </list>
806     </t>
807     </section>
808    
809     <section title="Getting all created audio output device count">
810     <t>Use the following command to count all created audio output devices:</t>
811     <t>
812     <list>
813     <t>GET AUDIO_OUTPUT_DEVICES</t>
814     </list>
815     </t>
816     <t>Possible Answers:</t>
817     <t>
818     <list>
819     <t>LinuxSampler will answer by sending the current number of all
820     audio output devices.</t>
821     </list>
822     </t>
823     <t>Example:</t>
824     <t>
825     <list>
826     <t>C: "GET AUDIO_OUTPUT_DEVICES"</t>
827     <t>S: "4"</t>
828     </list>
829     </t>
830     </section>
831    
832     <section title="Getting all created audio output device list">
833     <t>Use the following command to list all created audio output devices:</t>
834     <t>
835     <list>
836     <t>LIST AUDIO_OUTPUT_DEVICES</t>
837     </list>
838     </t>
839     <t>Possible Answers:</t>
840     <t>
841     <list>
842     <t>LinuxSampler will answer by sending a comma separated list with
843     the numerical IDs of all audio output devices.</t>
844     </list>
845     </t>
846     <t>Example:</t>
847     <t>
848     <list>
849     <t>C: "LIST AUDIO_OUTPUT_DEVICES"</t>
850     <t>S: "0,1,4,5"</t>
851     </list>
852     </t>
853     </section>
854    
855     <section title="Getting current settings of an audio output device">
856     <t>Use the following command to get current settings of a specific, created audio output device:</t>
857     <t>
858     <list>
859     <t>GET AUDIO_OUTPUT_DEVICE INFO &lt;device-id&gt;</t>
860     </list>
861     </t>
862     <t>Where &lt;device-id&gt; should be replaced by be numerical ID
863     of the audio output device as e.g. returned by the
864     "GET AUDIO_OUTPUT_DEVICES" command.</t>
865     <t>Possible Answers:</t>
866     <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
867     Each answer line begins with the information category name
868     followed by a colon and then a space character &lt;SP&gt; and finally
869     the info character string to that info category. As some
870     parameters might allow multiple values, character strings are
871     encapsulated into apostrophes ('). At the moment the following
872     information categories are defined (independently of device):</t>
873     <t>
874     <list>
875     <t>driver -
876     <list>
877     <t>identifier of the used audio output driver, as also
878     returned by the "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
879     command</t>
880     </list>
881     </t>
882     <t>channels -
883     <list>
884     <t>amount of audio output channels this device currently
885     offers</t>
886     </list>
887     </t>
888     <t>samplerate -
889     <list>
890     <t>playback sample rate the device uses</t>
891     </list>
892     </t>
893     <t>active -
894     <list>
895     <t>either true or false, if false then the audio device is
896     inactive and doesn't output any sound, nor do the
897     sampler channels connected to this audio device render
898     any audio</t>
899     </list>
900     </t>
901     </list>
902     </t>
903     <t>The mentioned fields above don't have to be in particular
904     order. The fields above are only those fields which are
905     returned by all audio output devices. Every audio output driver
906     might have its own, additional driver specific parameters (see
907     "GET AUDIO_OUTPUT_DRIVER INFO" command) which are also returned
908     by this command.</t>
909     <t>Example:</t>
910     <t>
911     <list>
912     <t>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"</t>
913     <t>S: "driver: Alsa"</t>
914     <t>&nbsp;&nbsp;&nbsp;"channels: 2"</t>
915     <t>&nbsp;&nbsp;&nbsp;"samplerate: 44100"</t>
916     <t>&nbsp;&nbsp;&nbsp;"active: true"</t>
917     <t>&nbsp;&nbsp;&nbsp;"fragments: 2"</t>
918     <t>&nbsp;&nbsp;&nbsp;"fragmentsize: 128"</t>
919     <t>&nbsp;&nbsp;&nbsp;"card: '0,0'"</t>
920     <t>&nbsp;&nbsp;&nbsp;"."</t>
921     </list>
922     </t>
923     </section>
924    
925    
926     <section title="Changing settings of audio output devices">
927     <t>Use the following command to alter a specific setting of a created audio output device:</t>
928     <t>
929     <list>
930     <t>SET AUDIO_OUTPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;</t>
931     </list>
932     </t>
933     <t>Where &lt;device-id&gt; should be replaced by the numerical ID of the
934     audio output device, &lt;key&gt; by the name of the parameter to change
935     and &lt;value&gt; by the new value for this parameter.</t>
936     <t>Possible Answers:</t>
937     <t>
938     <list>
939     <t>"OK" -
940     <list>
941     <t>in case setting was successfully changed</t>
942     </list>
943     </t>
944     <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
945     <list>
946     <t>in case setting was changed successfully, but there are
947     noteworthy issue(s) related, providing an appropriate
948     warning code and warning message</t>
949     </list>
950     </t>
951     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
952     <list>
953     <t>in case it failed, providing an appropriate error code and
954     error message</t>
955     </list>
956     </t>
957     </list>
958     </t>
959     <t>Example:</t>
960     <t>
961     <list>
962     <t>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 fragmentsize=128"</t>
963     <t>S: "OK"</t>
964     </list>
965     </t>
966     </section>
967    
968     <section title="Getting information about an audio channel">
969     <t>Use the following command to get information about an audio channel:</t>
970     <t>
971     <list>
972     <t>GET AUDIO_OUTPUT_CHANNEL INFO &lt;device-id&gt; &lt;audio-chan&gt;</t>
973     </list>
974     </t>
975     <t>Where &lt;device-id&gt; is the numerical ID of the audio output device
976     and &lt;audio-chan&gt; the audio channel number.</t>
977     <t>Possible Answers:</t>
978     <t>
979     <list>
980     <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
981     Each answer line begins with the information category name
982     followed by a colon and then a space character &lt;SP&gt; and finally
983     the info character string to that info category. At the moment
984     the following information categories are defined:</t>
985    
986     <t>
987     <list>
988     <t>NAME -
989     <list>
990     <t>arbitrary character string naming the channel, which
991     doesn't have to be unique (always returned by all audio channels)</t>
992     </list>
993     </t>
994     <t>IS_MIX_CHANNEL -
995     <list>
996     <t>either true or false, a mix-channel is not a real,
997     independent audio channel, but a virtual channel which
998     is mixed to another real channel, this mechanism is
999     needed for sampler engines which need more audio
1000     channels than the used audio system might be able to offer
1001     (always returned by all audio channels)</t>
1002     </list>
1003     </t>
1004     <t>MIX_CHANNEL_DESTINATION -
1005     <list>
1006     <t>reflects the real audio channel (of the same audio
1007     output device) this mix channel refers to, means where
1008     the audio signal actually will be routed / added to
1009     (only returned in case the audio channel is mix channel)</t>
1010     </list>
1011     </t>
1012     </list>
1013     </t>
1014     </list>
1015     </t>
1016    
1017     <t>The mentioned fields above don't have to be in particular
1018     order. The fields above are only those fields which are
1019     generally returned for the described cases by all audio
1020     channels regardless of the audio driver. Every audio channel
1021     might have its own, additional driver and channel specific
1022     parameters.</t>
1023    
1024     <t>Examples:</t>
1025    
1026     <t>
1027     <list>
1028     <t>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 0"</t>
1029     <t>S: "NAME: studio monitor left"</t>
1030     <t>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"</t>
1031     <t>&nbsp;&nbsp;&nbsp;"."</t>
1032     </list>
1033     </t>
1034    
1035     <t>
1036     <list>
1037     <t>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 1"</t>
1038     <t>S: "NAME: studio monitor right"</t>
1039     <t>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"</t>
1040     <t>&nbsp;&nbsp;&nbsp;"."</t>
1041     </list>
1042     </t>
1043    
1044     <t>
1045     <list>
1046     <t>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"</t>
1047     <t>S: "NAME: studio monitor left"</t>
1048     <t>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: true"</t>
1049     <t>&nbsp;&nbsp;&nbsp;"MIX_CHANNEL_DESTINATION: 1"</t>
1050     <t>&nbsp;&nbsp;&nbsp;"."</t>
1051     </list>
1052     </t>
1053    
1054     <t>
1055     <list>
1056     <t>C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"</t>
1057     <t>S: "NAME: 'ardour (left)'"</t>
1058     <t>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"</t>
1059     <t>&nbsp;&nbsp;&nbsp;"jack_bindings: 'ardour:0'"</t>
1060     <t>&nbsp;&nbsp;&nbsp;"."</t>
1061     </list>
1062     </t>
1063     </section>
1064    
1065     <section title="Getting information about specific audio channel parameter">
1066     <t>Use the following command to get detailed information about specific audio channel parameter:</t>
1067    
1068     <t>
1069     <list>
1070     <t>GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO &lt;dev-id&gt; &lt;chan&gt; &lt;param&gt;</t>
1071     </list>
1072     </t>
1073    
1074     <t>Where &lt;dev-id&gt; is the numerical ID of the audio output device as returned
1075     by the "GET AUDIO_OUTPUT_DEVICES" command, &lt;chan&gt; the audio channel number
1076     and &lt;param&gt; a specific channel parameter name for which information should
1077     be obtained (as returned by the "GET AUDIO_OUTPUT_CHANNEL INFO" command).</t>
1078     <t>Possible Answers:</t>
1079    
1080     <t>
1081     <list>
1082     <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1083     Each answer line begins with the information category name
1084     followed by a colon and then a space character &lt;SP&gt; and finally
1085     the info character string to that info category. There are
1086     information which is always returned, independently of the
1087     given channel parameter and there is optional information
1088     which is only shown dependently to the given audio channel. At
1089     the moment the following information categories are defined:</t>
1090     <t>
1091     <list>
1092     <t>TYPE -
1093     <list>
1094     <t>either "BOOL" for boolean value(s) or "INT" for integer
1095     value(s) or "FLOAT" for dotted number(s) or "STRING" for
1096     character string(s)
1097     (always returned)</t>
1098     </list>
1099     </t>
1100     <t>DESCRIPTION -
1101     <list>
1102     <t>arbitrary text describing the purpose of the parameter (always returned)</t>
1103     </list>
1104     </t>
1105     <t>FIX -
1106     <list>
1107     <t>either true or false, if true then this parameter is
1108     read only, thus cannot be altered
1109     (always returned)</t>
1110     </list>
1111     </t>
1112     <t>MULTIPLICITY -
1113     <list>
1114     <t>either true or false, defines if this parameter allows
1115     only one value or a list of values, where true means
1116     multiple values and false only a single value allowed
1117     (always returned)</t>
1118     </list>
1119     </t>
1120     <t>RANGE_MIN -
1121     <list>
1122     <t>defines lower limit of the allowed value range for this
1123     parameter, can be an integer value as well as a dotted
1124     number, usually used in conjunction with 'RANGE_MAX',
1125     but may also appear without
1126     (optionally returned, dependent to driver and channel
1127     parameter)</t>
1128     </list>
1129     </t>
1130     <t>RANGE_MAX -
1131     <list>
1132     <t>defines upper limit of the allowed value range for this
1133     parameter, can be an integer value as well as a dotted
1134     number, usually used in conjunction with 'RANGE_MIN',
1135     but may also appear without
1136     (optionally returned, dependent to driver and channel
1137     parameter)</t>
1138     </list>
1139     </t>
1140     <t>POSSIBILITES -
1141     <list>
1142     <t>comma separated list of possible values for this
1143     parameter, character strings are encapsulated into
1144     apostrophes
1145     (optionally returned, dependent to driver and channel
1146     parameter)</t>
1147     </list>
1148     </t>
1149     </list>
1150     </t>
1151     <t>The mentioned fields above don't have to be in particular order.</t>
1152     </list>
1153     </t>
1154     <t>Example:</t>
1155     <t>
1156     <list>
1157     <t>C: "GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO 1 0 jack_bindings"</t>
1158     <t>S: "DESCRIPTION: bindings to other Jack clients"</t>
1159     <t>&nbsp;&nbsp;&nbsp;"TYPE: STRING"</t>
1160     <t>&nbsp;&nbsp;&nbsp;"FIX: false"</t>
1161     <t>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"</t>
1162     <t>&nbsp;&nbsp;&nbsp;"POSSIBILITES: 'PCM:0','PCM:1','ardour:0','ardour:1'"</t>
1163     <t>&nbsp;&nbsp;&nbsp;"."</t>
1164     </list>
1165     </t>
1166     </section>
1167    
1168     <section title="Changing settings of audio output channels">
1169     <t>Use the following command to alter a specific setting of an audio output channel:</t>
1170     <t>
1171     <list>
1172     <t>SET AUDIO_OUTPUT_CHANNEL_PARAMETER &lt;dev-id&gt; &lt;chn&gt; &lt;key&gt;=&lt;value&gt;</t>
1173     </list>
1174     </t>
1175     <t>Where &lt;dev-id&gt; should be replaced by the numerical ID of the audio
1176     device, &lt;chn&gt; by the audio channel number, &lt;key&gt; by the name of the
1177     parameter to change and &lt;value&gt; by the new value for this parameter.</t>
1178     <t>Possible Answers:</t>
1179     <t>
1180     <list>
1181     <t>"OK" -
1182     <list>
1183     <t>in case setting was successfully changed</t>
1184     </list>
1185     </t>
1186     <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1187     <list>
1188     <t>in case setting was changed successfully, but there are
1189     noteworthy issue(s) related, providing an appropriate
1190     warning code and warning message</t>
1191     </list>
1192     </t>
1193     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1194     <list>
1195     <t>in case it failed, providing an appropriate error code and
1196     error message</t>
1197     </list>
1198     </t>
1199     </list>
1200     </t>
1201     <t>Example:</t>
1202     <t>
1203     <list>
1204     <t>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 jack_bindings='PCM:0'"</t>
1205     <t>S: "OK"</t>
1206     </list>
1207     </t>
1208     <t>
1209     <list>
1210     <t>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"</t>
1211     <t>S: "OK"</t>
1212     </list>
1213     </t>
1214     </section>
1215     </section>
1216    
1217     <section title="Configuring MIDI input drivers">
1218     <t>Instances of drivers in LinuxSampler are called devices. You can use
1219     multiple MIDI devices simultaneously, e.g. to use MIDI over ethernet as
1220     MIDI input on one sampler channel and Alsa as MIDI input on another sampler
1221     channel. For particular MIDI input systems it's also possible to create
1222     several devices of the same MIDI input type. This chapter describes all
1223     commands to configure LinuxSampler's MIDI input devices and their parameters.</t>
1224    
1225     <t>Instead of defining commands and parameters for each driver individually,
1226     all possible parameters, their meanings and possible values have to be obtained
1227     at runtime. This makes the protocol a bit abstract, but has the advantage, that
1228     front-ends can be written independently of what drivers are currently implemented
1229     and what parameters these drivers are actually offering. This means front-ends can
1230     even handle drivers which are implemented somewhere in future without modifying
1231     the front-end at all.</t>
1232    
1233     <t>Commands for configuring MIDI input devices are pretty much the same as the
1234     commands for configuring audio output drivers, already described in the last
1235     chapter.</t>
1236    
1237     <t>Note: examples in this chapter showing particular parameters of drivers are
1238     not meant as specification of the drivers' parameters. Driver implementations in
1239     LinuxSampler might have complete different parameter names and meanings than shown
1240     in these examples or might change in future, so these examples are only meant for
1241     showing how to retrieve what parameters drivers are offering, how to retrieve their
1242     possible values, etc.</t>
1243    
1244     <section title="Getting all available MIDI input drivers">
1245     <t>Use the following command to list all MIDI input drivers currently available
1246     for the LinuxSampler instance:</t>
1247     <t>
1248     <list>
1249     <t>GET AVAILABLE_MIDI_INPUT_DRIVERS</t>
1250     </list>
1251     </t>
1252     <t>Possible Answers:</t>
1253     <t>
1254     <list>
1255     <t>LinuxSampler will answer by sending comma separated character
1256     strings, each symbolizing a MIDI input driver.</t>
1257     </list>
1258     </t>
1259     <t>Example:</t>
1260     <t>
1261     <list>
1262     <t>C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"</t>
1263     <t>S: "Alsa,Jack"</t>
1264     </list>
1265     </t>
1266     </section>
1267    
1268     <section title="Getting information about a specific MIDI input driver">
1269     <t>Use the following command to get detailed information about a specific MIDI input driver:</t>
1270     <t>
1271     <list>
1272     <t>GET MIDI_INPUT_DRIVER INFO &lt;midi-input-driver&gt;</t>
1273     </list>
1274     </t>
1275     <t>Where &lt;midi-input-driver&gt; is the name of the MIDI input driver.</t>
1276     <t>Possible Answers:</t>
1277     <t>
1278     <list>
1279     <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1280     Each answer line begins with the information category name
1281     followed by a colon and then a space character &lt;SP&gt; and finally
1282     the info character string to that info category. At the moment
1283     the following information categories are defined:</t>
1284    
1285     <t>
1286     <list>
1287     <t>DESCRIPTION -
1288     <list>
1289     <t>arbitrary description text about the MIDI input driver</t>
1290     </list>
1291     </t>
1292     <t>VERSION -
1293     <list>
1294     <t>arbitrary character string regarding the driver's version</t>
1295     </list>
1296     </t>
1297     <t>PARAMETERS -
1298     <list>
1299     <t>comma separated list of all parameters available for the given MIDI input driver</t>
1300     </list>
1301     </t>
1302     </list>
1303     </t>
1304    
1305     <t>The mentioned fields above don't have to be in particular order.</t>
1306     </list>
1307     </t>
1308    
1309     <t>Example:</t>
1310    
1311     <t>
1312     <list>
1313     <t>C: "GET MIDI_INPUT_DRIVER INFO Alsa"</t>
1314     <t>S: "DESCRIPTION: Advanced Linux Sound Architecture"</t>
1315     <t>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"</t>
1316     <t>&nbsp;&nbsp;&nbsp;"PARAMETERS: driver,active"</t>
1317     <t>&nbsp;&nbsp;&nbsp;"."</t>
1318     </list>
1319     </t>
1320     </section>
1321    
1322     <section title="Getting information about specific MIDI input driver parameter">
1323     <t>Use the following command to get detailed information about a specific parameter of a specific MIDI input driver:</t>
1324     <t>
1325     <list>
1326     <t>GET MIDI_INPUT_DRIVER_PARAMETER INFO &lt;midit&gt; &lt;param&gt; [&lt;deplist&gt;]</t>
1327     </list>
1328     </t>
1329    
1330     <t>Where &lt;midi-t&gt; is the name of the MIDI input driver as returned
1331     by the "GET AVAILABLE_MIDI_INPUT_DRIVERS" command, &lt;param&gt; a specific
1332     parameter name for which information should be obtained (as returned by the
1333     "GET MIDI_INPUT_DRIVER INFO" command) and &lt;deplist&gt; is an optional list
1334     of parameters on which the sought parameter &lt;param&gt; depends on,
1335     &lt;deplist&gt; is a key-value pair list in form of "key1=val1 key2=val2 ...",
1336     where character string values are encapsulated into apostrophes ('). Arguments
1337     given with &lt;deplist&gt; which are not dependency parameters of &lt;param&gt;
1338     will be ignored, means the front-end application can simply put all parameters
1339     in &lt;deplist&gt; with the values selected by the user.</t>
1340    
1341     <t>Possible Answers:</t>
1342    
1343     <t>LinuxSampler will answer by sending a &lt;CRLF> separated list.
1344     Each answer line begins with the information category name
1345     followed by a colon and then a space character &lt;SP> and finally
1346     the info character string to that info category. There is
1347     information which is always returned, independent of the
1348     given driver parameter and there is optional information
1349     which is only shown dependent to given driver parameter. At
1350     the moment the following information categories are defined:</t>
1351    
1352     <t>
1353     <list>
1354     <t>TYPE -
1355     <list>
1356     <t>either "BOOL" for boolean value(s) or "INT" for integer
1357     value(s) or "FLOAT" for dotted number(s) or "STRING" for
1358     character string(s)
1359     (always returned, no matter which driver parameter)</t>
1360     </list>
1361     </t>
1362    
1363     <t>DESCRIPTION -
1364     <list>
1365     <t>arbitrary text describing the purpose of the parameter
1366     (always returned, no matter which driver parameter)</t>
1367     </list>
1368     </t>
1369    
1370     <t>MANDATORY -
1371     <list>
1372     <t>either true or false, defines if this parameter must be
1373     given when the device is to be created with the
1374     'CREATE MIDI_INPUT_DEVICE' command
1375     (always returned, no matter which driver parameter)</t>
1376     </list>
1377     </t>
1378    
1379     <t>FIX -
1380     <list>
1381     <t>either true or false, if false then this parameter can
1382     be changed at any time, once the device is created by
1383     the 'CREATE MIDI_INPUT_DEVICE' command
1384     (always returned, no matter which driver parameter)</t>
1385     </list>
1386     </t>
1387    
1388     <t>MULTIPLICITY -
1389     <list>
1390     <t>either true or false, defines if this parameter allows
1391     only one value or a list of values, where true means
1392     multiple values and false only a single value allowed
1393     (always returned, no matter which driver parameter)</t>
1394     </list>
1395     </t>
1396    
1397     <t>DEPENDS -
1398     <list>
1399     <t>comma separated list of paramters this parameter depends
1400     on, means the values for fields 'DEFAULT', 'RANGE_MIN',
1401     'RANGE_MAX' and 'POSSIBILITIES' might depend on these
1402     listed parameters, for example assuming that an audio
1403     driver (like the Alsa driver) offers parameters 'card'
1404     and 'samplerate' then parameter 'samplerate' would
1405     depend on 'card' because the possible values for
1406     'samplerate' depends on the sound card which can be
1407     chosen by the 'card' parameter
1408     (optionally returned, dependent to driver parameter)</t>
1409     </list>
1410     </t>
1411    
1412     <t>DEFAULT -
1413     <list>
1414     <t>reflects the default value for this parameter which is
1415     used when the device is created and not explicitly
1416     given with the 'CREATE MIDI_INPUT_DEVICE' command,
1417     in case of MULTIPLCITY=true, this is a comma separated
1418     list, that's why character strings are encapsulated into
1419     apostrophes (')
1420     (optionally returned, dependent to driver parameter)</t>
1421     </list>
1422     </t>
1423    
1424     <t>RANGE_MIN -
1425     <list>
1426     <t>defines lower limit of the allowed value range for this
1427     parameter, can be an integer value as well as a dotted
1428     number, this parameter is often used in conjunction
1429     with RANGE_MAX, but may also appear without
1430     (optionally returned, dependent to driver parameter)</t>
1431     </list>
1432     </t>
1433    
1434     <t>RANGE_MAX -
1435     <list>
1436     <t>defines upper limit of the allowed value range for this
1437     parameter, can be an integer value as well as a dotted
1438     number, this parameter is often used in conjunction with
1439     RANGE_MIN, but may also appear without
1440     (optionally returned, dependent to driver parameter)</t>
1441     </list>
1442     </t>
1443    
1444     <t>POSSIBILITES -
1445     <list>
1446     <t>comma separated list of possible values for this
1447     parameter, character strings are encapsulated into
1448     apostrophes
1449     (optionally returned, dependent to driver parameter)</t>
1450     </list>
1451     </t>
1452     </list>
1453     </t>
1454    
1455     <t>The mentioned fields above don't have to be in particular order.</t>
1456    
1457     <t>Example:</t>
1458     <t>
1459     <list>
1460     <t>C: "GET MIDI_INPUT_DRIVER_PARAMETER INFO Alsa active"</t>
1461     <t>S: "DESCRIPTION: Whether device is enabled"</t>
1462     <t>&nbsp;&nbsp;&nbsp;"TYPE: BOOL"</t>
1463     <t>&nbsp;&nbsp;&nbsp;"MANDATORY: false"</t>
1464     <t>&nbsp;&nbsp;&nbsp;"FIX: false"</t>
1465     <t>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"</t>
1466     <t>&nbsp;&nbsp;&nbsp;"DEFAULT: true"</t>
1467     <t>&nbsp;&nbsp;&nbsp;"."</t>
1468     </list>
1469     </t>
1470     </section>
1471    
1472     <section title="Creating a MIDI input device">
1473     <t>Use the following command to create a new MIDI input device for the desired MIDI input system:</t>
1474     <t>
1475     <list>
1476     <t>CREATE MIDI_INPUT_DEVICE &lt;midi-input-driver&gt; [&lt;param-list&gt;]</t>
1477     </list>
1478     </t>
1479    
1480     <t>Where &lt;midi-input-driver&gt; should be replaced by the desired MIDI input system and &lt;param-list&gt; by an
1481     optional list of driver specific parameters in form of "key1=val1 key2=val2 ...", where
1482     character string values should be encapsulated into apostrophes (').
1483     Note that there might be drivers which require parameter(s) to be
1484     given with this command. Use the previously described commands in
1485     this chapter to get that information.</t>
1486    
1487     <t>Possible Answers:</t>
1488     <t>
1489     <list>
1490     <t>"OK[&lt;device-id&gt;]" -
1491     <list>
1492     <t>in case the device was successfully created, where
1493     &lt;device-id&gt; is the numerical ID of the new device</t>
1494     </list>
1495     </t>
1496     <t>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1497     <list>
1498     <t>in case the driver was loaded successfully, where
1499     &lt;device-id&gt; is the numerical ID of the new device, but
1500     there are noteworthy issue(s) related, providing an
1501     appropriate warning code and warning message</t>
1502     </list>
1503     </t>
1504     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1505     <list>
1506     <t>in case it failed, providing an appropriate error code and error message</t>
1507     </list>
1508     </t>
1509     </list>
1510     </t>
1511     <t>Example:</t>
1512     <t>
1513     <list>
1514     <t>C: "CREATE MIDI_INPUT_DEVICE Alsa"</t>
1515     <t>S: "OK[0]"</t>
1516     </list>
1517     </t>
1518     </section>
1519    
1520     <section title="Destroying a MIDI input device">
1521     <t>Use the following command to destroy a created MIDI input device:</t>
1522     <t>
1523     <list>
1524     <t>DESTROY MIDI_INPUT_DEVICE &lt;device-id&gt;</t>
1525     </list>
1526     </t>
1527     <t>Where &lt;device-id&gt; should be replaced by the device's numerical ID.</t>
1528     <t>Possible Answers:</t>
1529     <t>
1530     <list>
1531     <t>"OK" -
1532     <list>
1533     <t>in case the device was successfully destroyed</t>
1534     </list>
1535     </t>
1536     <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1537     <list>
1538     <t>in case the device was destroyed, but there are noteworthy
1539     issue(s) related, providing an appropriate warning code and
1540     warning message</t>
1541     </list>
1542     </t>
1543     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1544     <list>
1545     <t>in case it failed, providing an appropriate error code and error message</t>
1546     </list>
1547     </t>
1548     </list>
1549     </t>
1550     <t>Example:</t>
1551     <t>
1552     <list>
1553     <t>C: "DESTROY MIDI_INPUT_DEVICE 0"</t>
1554     <t>S: "OK"</t>
1555     </list>
1556     </t>
1557     </section>
1558    
1559     <section title="Getting all created MIDI input device count">
1560     <t>Use the following command to count all created MIDI input devices:</t>
1561     <t>
1562     <list>
1563     <t>GET MIDI_INPUT_DEVICES</t>
1564     </list>
1565     </t>
1566     <t>Possible Answers:</t>
1567     <t>
1568     <list>
1569     <t>LinuxSampler will answer by sending the current number of all
1570     MIDI input devices.</t>
1571     </list>
1572     </t>
1573     <t>Example:</t>
1574     <t>
1575     <list>
1576     <t>C: "GET MIDI_INPUT_DEVICES"</t>
1577     <t>S: "3"</t>
1578     </list>
1579     </t>
1580     </section>
1581    
1582    
1583     <section title="Getting all created MIDI input device list">
1584     <t>Use the following command to list all created MIDI input devices:</t>
1585     <t>
1586     <list>
1587     <t>LIST MIDI_INPUT_DEVICES</t>
1588     </list>
1589     </t>
1590     <t>Possible Answers:</t>
1591     <t>
1592     <list>
1593     <t>LinuxSampler will answer by sending a comma separated list
1594     with the numerical Ids of all created MIDI input devices.</t>
1595     </list>
1596     </t>
1597     <t>Examples:</t>
1598     <t>
1599     <list>
1600     <t>C: "LIST MIDI_INPUT_DEVICES"</t>
1601     <t>S: "0,1,2"</t>
1602     </list>
1603     </t>
1604     <t>
1605     <list>
1606     <t>C: "LIST MIDI_INPUT_DEVICES"</t>
1607     <t>S: "1,3"</t>
1608     </list>
1609     </t>
1610     </section>
1611    
1612     <section title="Getting current settings of a MIDI input device">
1613     <t>Use the following command to get current settings of a specific, created MIDI input device:</t>
1614     <t>
1615     <list>
1616     <t>GET MIDI_INPUT_DEVICE INFO &lt;device-id&gt;</t>
1617     </list>
1618     </t>
1619     <t>Where &lt;device-id&gt; is the numerical ID of the MIDI input device.</t>
1620     <t>Possible Answers:</t>
1621     <t>
1622     <list>
1623     <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1624     Each answer line begins with the information category name
1625     followed by a colon and then a space character &lt;SP&gt; and finally
1626     the info character string to that info category. As some
1627     parameters might allow multiple values, character strings are
1628     encapsulated into apostrophes ('). At the moment the following
1629     information categories are defined (independent of driver):</t>
1630    
1631     <t>
1632     <list>
1633     <t>DRIVER -
1634     <list>
1635     <t>identifier of the used MIDI input driver, as e.g.
1636     returned by the "GET AVAILABLE_MIDI_INPUT_DRIVERS"
1637     command</t>
1638     </list>
1639     </t>
1640     </list>
1641     <list>
1642     <t>ACTIVE -
1643     <list>
1644     <t>either true or false, if false then the MIDI device is
1645     inactive and doesn't listen to any incoming MIDI events
1646     and thus doesn't forward them to connected sampler
1647     channels</t>
1648     </list>
1649     </t>
1650     </list>
1651     </t>
1652     </list>
1653     </t>
1654    
1655     <t>The mentioned fields above don't have to be in particular
1656     order. The fields above are only those fields which are
1657     returned by all MIDI input devices. Every MIDI input driver
1658     might have its own, additional driver specific parameters (see
1659     "GET MIDI_INPUT_DRIVER INFO" command) which are also returned
1660     by this command.</t>
1661    
1662     <t>Example:</t>
1663     <t>
1664     <list>
1665     <t>C: "GET MIDI_INPUT_DEVICE INFO 0"</t>
1666     <t>S: "driver: Alsa"</t>
1667     <t>&nbsp;&nbsp;&nbsp;"active: true"</t>
1668     <t>&nbsp;&nbsp;&nbsp;"."</t>
1669     </list>
1670     </t>
1671     </section>
1672    
1673     <section title="Changing settings of audio output devices">
1674     <t>Use the following command to alter a specific setting of a created MIDI input device:</t>
1675     <t>
1676     <list>
1677     <t>SET MIDI_INPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;</t>
1678     </list>
1679     </t>
1680    
1681     <t>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1682     MIDI input device, &lt;key&gt; by the name of the parameter to change and
1683     &lt;value&gt; by the new value for this parameter.</t>
1684    
1685     <t>Possible Answers:</t>
1686     <t>
1687     <list>
1688     <t>"OK" -
1689     <list>
1690     <t>in case setting was successfully changed</t>
1691     </list>
1692     </t>
1693     <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1694     <list>
1695     <t>in case setting was changed successfully, but there are
1696     noteworthy issue(s) related, providing an appropriate
1697     warning code and warning message</t>
1698     </list>
1699     </t>
1700     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1701     <list>
1702     <t>in case it failed, providing an appropriate error code and error message</t>
1703     </list>
1704     </t>
1705     </list>
1706     </t>
1707     <t>Example:</t>
1708     <t>
1709     <list>
1710     <t>C: "SET MIDI_INPUT_DEVICE PARAMETER 0 ACTIVE=false"</t>
1711     <t>S: "OK"</t>
1712     </list>
1713     </t>
1714     </section>
1715    
1716     <section title="Getting information about a MIDI port">
1717     <t>Use the following command to get information about a MIDI port:</t>
1718     <t>
1719     <list>
1720     <t>GET MIDI_INPUT_PORT INFO &lt;device-id&gt; &lt;midi-port&gt;</t>
1721     </list>
1722     </t>
1723     <t>Where &lt;device-id&gt; is the numerical ID of the MIDI input device
1724     and &lt;midi-port&gt; the MIDI input port number.</t>
1725     <t>Possible Answers:</t>
1726     <t>
1727     <list>
1728     <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1729     Each answer line begins with the information category name
1730     followed by a colon and then a space character &lt;SP&gt; and finally
1731     the info character string to that info category. At the moment
1732     the following information categories are defined:</t>
1733    
1734     <t>NAME -
1735     <list>
1736     <t>arbitrary character string naming the port</t>
1737     </list>
1738     </t>
1739     </list>
1740     </t>
1741    
1742     <t>The field above is only the one which is returned by all MIDI
1743     ports regardless of the MIDI driver and port. Every MIDI port
1744     might have its own, additional driver and port specific
1745     parameters.</t>
1746    
1747     <t>Example:</t>
1748     <t>
1749     <list>
1750     <t>C: "GET MIDI_INPUT_PORT INFO 0 0"</t>
1751     <t>S: "name: 'Masterkeyboard'"</t>
1752     <t>&nbsp;&nbsp;&nbsp;"alsa_seq_bindings: '64:0'"</t>
1753     <t>&nbsp;&nbsp;&nbsp;"."</t>
1754     </list>
1755     </t>
1756     </section>
1757    
1758     <section title="Getting information about specific MIDI port parameter">
1759     <t>Use the following command to get detailed information about specific MIDI port parameter:</t>
1760     <t>
1761     <list>
1762     <t>GET MIDI_INPUT_PORT_PARAMETER INFO &lt;dev-id&gt; &lt;port&gt; &lt;param&gt;</t>
1763     </list>
1764     </t>
1765    
1766     <t>Where &lt;dev-id&gt; is the numerical ID of the MIDI input device as returned
1767     by the "GET MIDI_INPUT_DEVICES" command, &lt;port&gt; the MIDI port number and
1768     &lt;param&gt; a specific port parameter name for which information should be
1769     obtained (as returned by the "GET MIDI_INPUT_PORT INFO" command).</t>
1770    
1771     <t>Possible Answers:</t>
1772     <t>
1773     <list>
1774     <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1775     Each answer line begins with the information category name
1776     followed by a colon and then a space character &lt;SP&gt; and finally
1777     the info character string to that info category. There is
1778     information which is always returned, independently of the
1779     given channel parameter and there is optional information
1780     which are only shown dependently to the given MIDI port. At the
1781     moment the following information categories are defined:</t>
1782    
1783     <t>TYPE -
1784     <list>
1785     <t>either "BOOL" for boolean value(s) or "INT" for integer
1786     value(s) or "FLOAT" for dotted number(s) or "STRING" for
1787     character string(s)
1788     (always returned)</t>
1789     </list>
1790     </t>
1791     <t>DESCRIPTION -
1792     <list>
1793     <t>arbitrary text describing the purpose of the parameter
1794     (always returned)</t>
1795     </list>
1796     </t>
1797     <t>FIX -
1798     <list>
1799     <t>either true or false, if true then this parameter is
1800     read only, thus cannot be altered
1801     (always returned)</t>
1802     </list>
1803     </t>
1804     <t>MULTIPLICITY -
1805     <list>
1806     <t>either true or false, defines if this parameter allows
1807     only one value or a list of values, where true means
1808     multiple values and false only a single value allowed
1809     (always returned)</t>
1810     </list>
1811     </t>
1812     <t>RANGE_MIN -
1813     <list>
1814     <t>defines lower limit of the allowed value range for this
1815     parameter, can be an integer value as well as a dotted
1816     number, this parameter is usually used in conjunction
1817     with 'RANGE_MAX' but may also appear without
1818     (optionally returned, dependent to driver and port
1819     parameter)</t>
1820     </list>
1821     </t>
1822     <t>RANGE_MAX -
1823     <list>
1824     <t>defines upper limit of the allowed value range for this
1825     parameter, can be an integer value as well as a dotted
1826     number, this parameter is usually used in conjunction
1827     with 'RANGE_MIN' but may also appear without
1828     (optionally returned, dependent to driver and port
1829     parameter)</t>
1830     </list>
1831     </t>
1832     <t>POSSIBILITES -
1833     <list>
1834     <t>comma separated list of possible values for this
1835     parameter, character strings are encapsulated into
1836     apostrophes
1837     (optionally returned, dependent to device and port
1838     parameter)</t>
1839     </list>
1840     </t>
1841     </list>
1842     </t>
1843    
1844     <t>The mentioned fields above don't have to be in particular order.</t>
1845    
1846     <t>Example:</t>
1847     <t>
1848     <list>
1849     <t>C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 alsa_seq_bindings"</t>
1850     <t>S: "DESCRIPTION: bindings to other Alsa sequencer clients"</t>
1851     <t>"TYPE: STRING"</t>
1852     <t>&nbsp;&nbsp;&nbsp;"FIX: false"</t>
1853     <t>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"</t>
1854     <t>&nbsp;&nbsp;&nbsp;"POSSIBILITES: '64:0','68:0','68:1'"</t>
1855     <t>&nbsp;&nbsp;&nbsp;"."</t>
1856     </list>
1857     </t>
1858     </section>
1859    
1860     <section title="Changing settings of MIDI input ports">
1861     <t>Use the following command to alter a specific setting of a MIDI input port:</t>
1862     <t>
1863     <list>
1864     <t>SET MIDI_INPUT_PORT PARAMETER &lt;device-id&gt; &lt;port&gt; &lt;key&gt;=&lt;value&gt;</t>
1865     </list>
1866     </t>
1867    
1868     <t>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1869     MIDI device, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of
1870     the parameter to change and &lt;value&gt; by the new value for this
1871     parameter.</t>
1872    
1873     <t>Possible Answers:</t>
1874     <t>
1875     <list>
1876     <t>"OK" -
1877     <list>
1878     <t>in case setting was successfully changed</t>
1879     </list>
1880     </t>
1881     <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1882     <list>
1883     <t>in case setting was changed successfully, but there are
1884     noteworthy issue(s) related, providing an appropriate
1885     warning code and warning message</t>
1886     </list>
1887     </t>
1888     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1889     <list>
1890     <t>in case it failed, providing an appropriate error code and error message</t>
1891     </list>
1892     </t>
1893     </list>
1894     </t>
1895     <t>Example:</t>
1896     <t>
1897     <list>
1898     <t></t>
1899     </list>
1900     </t>
1901     </section>
1902     </section>
1903    
1904     <section title="Configuring sampler channels">
1905     <t>The following commands describe how to add and remove sampler channels, deploy
1906     sampler engines, load instruments and connect sampler channels to MIDI and audio devices.</t>
1907    
1908     <section title="Loading an instrument">
1909     <t>An instrument file can be loaded and assigned to a sampler channel by one of the following commands:</t>
1910     <t>
1911     <list>
1912     <t>LOAD INSTRUMENT [NON_MODAL] '&lt;filename&gt;' &lt;instr-index&gt; &lt;sampler-channel&gt;</t>
1913     </list>
1914     </t>
1915    
1916     <t>Where &lt;filename&gt; is the name of the instrument file on the
1917     LinuxSampler instance's host system, &lt;instr-index&gt; the index of the
1918     instrument in the instrument file and &lt;sampler-channel> is the
1919     number of the sampler channel the instrument should be assigned to.
1920     Each sampler channel can only have one instrument.</t>
1921    
1922     <t>The difference between regular and NON_MODAL versions of the command
1923     is that the regular command returns OK only after the instrument has been
1924     fully loaded and the channel is ready to be used while NON_MODAL version
1925     returns immediately and a background process is launched to load the instrument
1926     on the channel. GET CHANNEL INFO command can be used to obtain loading
1927     progress from INSTRUMENT_STATUS field. LOAD command will perform sanity checks
1928     such as making sure that the file could be read and it is of a proper format
1929     and SHOULD return ERR and SHOULD not launch the background process should any
1930     errors be detected at that point.</t>
1931    
1932     <t>Possible Answers:</t>
1933     <t>
1934     <list>
1935     <t>"OK" -
1936     <list>
1937     <t>in case the instrument was successfully loaded</t>
1938     </list>
1939     </t>
1940     <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1941     <list>
1942     <t>in case the instrument was loaded successfully, but there
1943     are noteworthy issue(s) related (e.g. Engine doesn't support
1944     one or more patch parameters provided by the loaded
1945     instrument file), providing an appropriate warning code and
1946     warning message</t>
1947     </list>
1948     </t>
1949     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1950     <list>
1951     <t>in case it failed, providing an appropriate error code and error message</t>
1952     </list>
1953     </t>
1954     </list>
1955     </t>
1956     <t>Example:</t>
1957     <t>
1958     <list>
1959     <t></t>
1960     </list>
1961     </t>
1962     </section>
1963    
1964     <section title="Loading a sampler engine">
1965     <t>A sample engine can be deployed and assigned to a specific sampler
1966     channel by the following command:</t>
1967     <t>
1968     <list>
1969     <t>LOAD ENGINE &lt;engine-name&gt; &lt;sampler-channel&gt;</t>
1970     </list>
1971     </t>
1972    
1973     <t>Where &lt;engine-name&gt; is usually the C++ class name of the engine
1974     implementation and &lt;sampler-channel&gt; the sampler channel the
1975     deployed engine should be assigned to. Even if the respective
1976     sampler channel has already a deployed engine with that engine
1977     name, a new engine instance will be assigned to the sampler channel.</t>
1978    
1979     <t>Possible Answers:</t>
1980     <t>
1981     <list>
1982     <t>"OK" -
1983     <list>
1984     <t>in case the engine was successfully deployed</t>
1985     </list>
1986     </t>
1987     <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1988     <list>
1989     <t>in case the engine was deployed successfully, but there
1990     are noteworthy issue(s) related, providing an appropriate
1991     warning code and warning message</t>
1992     </list>
1993     </t>
1994     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1995     <list>
1996     <t>in case it failed, providing an appropriate error code and
1997     error message</t>
1998     </list>
1999     </t>
2000     </list>
2001     </t>
2002     <t>Example:</t>
2003     <t>
2004     <list>
2005     <t></t>
2006     </list>
2007     </t>
2008     </section>
2009    
2010     <section title="Getting all created sampler channel count">
2011     <t>The number of sampler channels can change on runtime. To get the
2012     current amount of sampler channels, the front-end can send the
2013     following command:</t>
2014     <t>
2015     <list>
2016     <t>GET CHANNELS</t>
2017     </list>
2018     </t>
2019     <t>Possible Answers:</t>
2020     <t>
2021     <list>
2022     <t>LinuxSampler will answer by returning the current number of sampler channels.</t>
2023     </list>
2024     </t>
2025     <t>Example:</t>
2026     <t>
2027     <list>
2028     <t>C: "GET CHANNELS"</t>
2029     <t>S: "12"</t>
2030     </list>
2031     </t>
2032     </section>
2033    
2034     <section title="Getting all created sampler channel list">
2035     <t>The number of sampler channels can change on runtime. To get the
2036     current list of sampler channels, the front-end can send the
2037     following command:</t>
2038     <t>
2039     <list>
2040     <t>LIST CHANNELS</t>
2041     </list>
2042     </t>
2043     <t>Possible Answers:</t>
2044     <t>
2045     <list>
2046     <t>LinuxSampler will answer by returning a comma separated list
2047     with all sampler channels numerical IDs.</t>
2048     </list>
2049     </t>
2050     <t>Example:</t>
2051     <t>
2052     <list>
2053     <t>C: "LIST CHANNELS"</t>
2054     <t>S: "0,1,2,3,4,5,6,9,10,11,15,20"</t>
2055     </list>
2056     </t>
2057     </section>
2058    
2059     <section title="Adding a new sampler channel">
2060     <t>A new sampler channel can be added to the end of the sampler
2061     channel list by sending the following command:</t>
2062     <t>
2063     <list>
2064     <t>ADD CHANNEL</t>
2065     </list>
2066     </t>
2067     <t>This will increment the sampler channel count by one and the new
2068     sampler channel will be appended to the end of the sampler channel
2069     list. The front-end should send the respective, related commands
2070     right after to e.g. load an engine, load an instrument and setting
2071     input, output method and eventually other commands to initialize
2072     the new channel. The front-end should use the sampler channel
2073     returned by the answer of this command to perform the previously
2074     recommended commands, to avoid race conditions e.g. with other
2075     front-ends that might also have sent an "ADD CHANNEL" command.</t>
2076     <t>Possible Answers:</t>
2077     <t>
2078     <list>
2079     <t>"OK[&lt;sampler-channel&gt;]" -
2080     <list>
2081     <t>in case a new sampler channel could be added, where
2082     &lt;sampler-channel&gt; reflects the channel number of the new
2083     created sampler channel which should the be used to set up
2084     the sampler channel by sending subsequent intialization
2085     commands</t>
2086     </list>
2087     </t>
2088     <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2089     <list>
2090     <t>in case a new channel was added successfully, but there are
2091     noteworthy issue(s) related, providing an appropriate
2092     warning code and warning message</t>
2093     </list>
2094     </t>
2095     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2096     <list>
2097     <t>in case it failed, providing an appropriate error code and
2098     error message</t>
2099     </list>
2100     </t>
2101     </list>
2102     </t>
2103     <t>Example:</t>
2104     <t>
2105     <list>
2106     <t></t>
2107     </list>
2108     </t>
2109     </section>
2110    
2111     <section title="Removing a sampler channel">
2112     <t>A sampler channel can be removed by sending the following command:</t>
2113     <t>
2114     <list>
2115     <t>REMOVE CHANNEL &lt;sampler-channel&gt;</t>
2116     </list>
2117     </t>
2118    
2119     <t>This will decrement the sampler channel count by one and also
2120     decrement the channel numbers of all subsequent sampler channels by
2121     one.</t>
2122    
2123     <t>Possible Answers:</t>
2124     <t>
2125     <list>
2126     <t>"OK" -
2127     <list>
2128     <t>in case the given sampler channel could be removed</t>
2129     </list>
2130     </t>
2131     <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2132     <list>
2133     <t>in case the given channel was removed, but there are
2134     noteworthy issue(s) related, providing an appropriate
2135     warning code and warning message</t>
2136     </list>
2137     </t>
2138     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2139     <list>
2140     <t>in case it failed, providing an appropriate error code and
2141     error message</t>
2142     </list>
2143     </t>
2144     </list>
2145     </t>
2146     <t>Example:</t>
2147     <t>
2148     <list>
2149     <t></t>
2150     </list>
2151     </t>
2152     </section>
2153    
2154     <section title="Getting all available engines">
2155     <t>The front-end can ask for all available engines by sending the following command:</t>
2156     <t>
2157     <list>
2158     <t>GET AVAILABLE_ENGINES</t>
2159     </list>
2160     </t>
2161     <t>Possible Answers:</t>
2162     <t>
2163     <list>
2164     <t>LinuxSampler will answer by sending a comma separated character
2165     string of the engines' C++ class names.</t>
2166     </list>
2167     </t>
2168     <t>Example:</t>
2169     <t>
2170     <list>
2171     <t>C: "GET AVAILABLE_ENGINES"</t>
2172     <t>S: "GigEngine,AkaiEngine,DLSEngine,JoesCustomEngine"</t>
2173     </list>
2174     </t>
2175     </section>
2176    
2177     <section title="Getting information about an engine">
2178     <t>The front-end can ask for information about a specific engine by
2179     sending the following command:</t>
2180     <t>
2181     <list>
2182     <t>GET ENGINE INFO &lt;engine-name&gt;</t>
2183     </list>
2184     </t>
2185     <t>Where &lt;engine-name&gt; is usually the C++ class name of the engine implementation.</t>
2186     <t>Possible Answers:</t>
2187     <t>
2188     <list>
2189     <t>LinuxSampler will answer by sending &lt;&gt; separated list.
2190     Each answer line begins with the information category name
2191     followed by a colon and then a space character &lt;SP&gt; and finally
2192     the info character string to that info category. At the moment
2193     the following categories are defined:</t>
2194    
2195     <t>
2196     <list>
2197     <t>DESCRIPTION -
2198     <list>
2199     <t>arbitrary description text about the engine</t>
2200     </list>
2201     </t>
2202     <t>VERSION -
2203     <list>
2204     <t>arbitrary character string regarding the engine's version</t>
2205     </list>
2206     </t>
2207     </list>
2208     </t>
2209     </list>
2210     </t>
2211    
2212     <t>The mentioned fields above don't have to be in particular order.</t>
2213    
2214     <t>Example:</t>
2215     <t>
2216     <list>
2217     <t>C: "GET ENGINE INFO JoesCustomEngine"</t>
2218     <t>S: "DESCRIPTION: this is Joe's custom sampler engine"</t>
2219     <t>&nbsp;&nbsp;&nbsp;"VERSION: testing-1.0"</t>
2220     <t>&nbsp;&nbsp;&nbsp;"."</t>
2221     </list>
2222     </t>
2223     </section>
2224    
2225     <section title="Getting sampler channel information">
2226     <t>The front-end can ask for the current settings of a sampler channel
2227     by sending the following command:</t>
2228     <t>
2229     <list>
2230     <t>GET CHANNEL INFO &lt;sampler-channel&gt;</t>
2231     </list>
2232     </t>
2233     <t>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in.</t>
2234     <t>Possible Answers:</t>
2235     <t>
2236     <list>
2237     <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2238     Each answer line begins with the settings category name
2239     followed by a colon and then a space character &lt;SP&gt; and finally
2240     the info character string to that setting category. At the
2241     moment the following categories are defined:</t>
2242    
2243     <t>
2244     <list>
2245     <t>ENGINE_NAME -
2246     <list>
2247     <t>name of the engine that is deployed on the sampler
2248     channel, "NONE" if there's no engine deployed yet for
2249     this sampler channel</t>
2250     </list>
2251     </t>
2252     <t>AUDIO_OUTPUT_DEVICE -
2253     <list>
2254     <t>numerical ID of the audio output device which is
2255     currently connected to this sampler channel to output
2256     the audio signal, "NONE" if there's no device
2257     connected to this sampler channel</t>
2258     </list>
2259     </t>
2260     <t>AUDIO_OUTPUT_CHANNELS -
2261     <list>
2262     <t>number of output channels the sampler channel offers
2263     (dependent to used sampler engine and loaded instrument)</t>
2264     </list>
2265     </t>
2266     <t>AUDIO_OUTPUT_ROUTING -
2267     <list>
2268     <t>comma separated list which reflects to which audio
2269     channel of the selected audio output device each
2270     sampler output channel is routed to, e.g. "0,3" would
2271     mean the engine's output channel 0 is routed to channel
2272     0 of the audio output device and the engine's output
2273     channel 1 is routed to the channel 3 of the audio
2274     output device</t>
2275     </list>
2276     </t>
2277     <t>INSTRUMENT_FILE -
2278     <list>
2279     <t>the file name of the loaded instrument, "NONE" if
2280     there's no instrument yet loaded for this sampler
2281     channel</t>
2282     </list>
2283     </t>
2284     <t>INSTRUMENT_NR -
2285     <list>
2286     <t>the instrument index number of the loaded instrument</t>
2287     </list>
2288     </t>
2289     <t>INSTRUMENT_STATUS -
2290     <list>
2291     <t>integer values 0 to 100 indicating loading progress percentage for the instrument. Negative
2292     value indicates a loading exception. Value of 100 indicates that the instrument is fully
2293     loaded.</t>
2294     </list>
2295     </t>
2296     <t>MIDI_INPUT_DEVICE -
2297     <list>
2298     <t>numerical ID of the MIDI input device which is
2299     currently connected to this sampler channel to deliver
2300     MIDI input commands, "NONE" if there's no device
2301     connected to this sampler channel</t>
2302     </list>
2303     </t>
2304     <t>MIDI_INPUT_PORT -
2305     <list>
2306     <t>port number of the MIDI input device</t>
2307     </list>
2308     </t>
2309     <t>MIDI_INPUT_CHANNEL -
2310     <list>
2311     <t>the MIDI input channel number this sampler channel
2312     should listen to or "ALL" to listen on all MIDI channels</t>
2313     </list>
2314     </t>
2315     <t>VOLUME -
2316     <list>
2317     <t>optionally dotted number for the channel volume factor
2318     (where a value < 1.0 means attenuation and a value >
2319     1.0 means amplification)</t>
2320     </list>
2321     </t>
2322     </list>
2323     </t>
2324     </list>
2325     </t>
2326     <t>The mentioned fields above don't have to be in particular order.</t>
2327    
2328     <t>Example:</t>
2329     <t>
2330     <list>
2331     <t>C: "GET CHANNEL INFO 34"</t>
2332     <t>S: "ENGINE_NAME: GigEngine"</t>
2333     <t>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"</t>
2334     <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_DEVICE: 0"</t>
2335     <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_CHANNELS: 2"</t>
2336     <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 0,1"</t>
2337     <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"</t>
2338     <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"</t>
2339     <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_STATUS: 100"</t>
2340     <t>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_DEVICE: 0"</t>
2341     <t>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_PORT: 0"</t>
2342     <t>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_CHANNEL: 5"</t>
2343     <t>&nbsp;&nbsp;&nbsp;"."</t>
2344     </list>
2345     </t>
2346     </section>
2347    
2348     <section title="Current number of active voices">
2349     <t>The front-end can ask for the current number of active voices on a
2350     sampler channel by sending the following command:</t>
2351     <t>
2352     <list>
2353 schoenebeck 206 <t>GET CHANNEL VOICE_COUNT &lt;sampler-channel&gt;</t>
2354 schoenebeck 151 </list>
2355     </t>
2356 schoenebeck 206 <t>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in.</t>
2357    
2358 schoenebeck 151 <t>Possible Answers:</t>
2359     <t>
2360     <list>
2361     <t>LinuxSampler will answer by returning the number of active
2362     voices on that channel.</t>
2363     </list>
2364     </t>
2365     <t>Example:</t>
2366     <t>
2367     <list>
2368     <t></t>
2369     </list>
2370     </t>
2371     </section>
2372    
2373     <section title="Current number of active disk streams">
2374     <t>The front-end can ask for the current number of active disk streams
2375     on a sampler channel by sending the following command:</t>
2376     <t>
2377     <list>
2378     <t>GET CHANNEL STREAM_COUNT &lt;sampler-channel&gt;</t>
2379     </list>
2380     </t>
2381     <t>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in.</t>
2382    
2383     <t>Possible Answers:</t>
2384     <t>
2385     <list>
2386     <t>LinuxSampler will answer by returning the number of active
2387     disk streams on that channel in case the engine supports disk
2388     streaming, if the engine doesn't support disk streaming it will
2389     return "NA" for not available.</t>
2390     </list>
2391     </t>
2392     <t>Example:</t>
2393     <t>
2394     <list>
2395     <t></t>
2396     </list>
2397     </t>
2398     </section>
2399    
2400     <section title="Current fill state of disk stream buffers">
2401     <t>The front-end can ask for the current fill state of all disk streams
2402     on a sampler channel by sending the following command:</t>
2403     <t>
2404     <list>
2405     <t>GET CHANNEL BUFFER_FILL BYTES &lt;sampler-channel&gt;</t>
2406     </list>
2407     </t>
2408     <t>to get the fill state in bytes or</t>
2409     <t>
2410     <list>
2411     <t>GET CHANNEL BUFFER_FILL PERCENTAGE &lt;sampler-channel&gt;</t>
2412     </list>
2413     </t>
2414     <t>to get the fill state in percent, where &lt;sampler-channel&gt; is the
2415     sampler channel number the front-end is interested in.</t>
2416    
2417     <t>Possible Answers:</t>
2418     <t>
2419     <list>
2420     <t>LinuxSampler will either answer by returning a comma separated
2421     string with the fill state of all disk stream buffers on that
2422     channel or an empty line if there are no active disk streams or
2423     "NA" for *not available* in case the engine which is deployed
2424     doesn't support disk streaming. Each entry in the answer list
2425     will begin with the stream's ID in brackets followed by the
2426     numerical representation of the fill size (either in bytes or
2427     percentage). Note: due to efficiency reasons the fill states in
2428     the response are not in particular order, thus the front-end has
2429     to sort them by itself if necessary.</t>
2430     </list>
2431     </t>
2432     <t>Examples:</t>
2433     <t>
2434     <list>
2435     <t>C: "GET CHANNEL BUFFER_FILL BYTES 4"</t>
2436     <t>S: "[115]420500,[116]510300,[75]110000,[120]230700"</t>
2437     </list>
2438    
2439     <list>
2440     <t>C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"</t>
2441     <t>S: "[115]90%,[116]98%,[75]40%,[120]62%"</t>
2442     </list>
2443    
2444     <list>
2445     <t>C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"</t>
2446     <t>S: ""</t>
2447     </list>
2448     </t>
2449     </section>
2450    
2451     <section title="Setting audio output device">
2452     <t>The front-end can set the audio output device on a specific sampler
2453     channel by sending the following command:</t>
2454     <t>
2455     <list>
2456     <t>SET CHANNEL AUDIO_OUTPUT_DEVICE &lt;sampler-channel&gt; &lt;audio-device-id&gt;</t>
2457     </list>
2458     </t>
2459     <t>Where &lt;audio-device-id&gt; is the numerical ID of the audio output
2460     device and &lt;sampler-channel&gt; is the respective sampler channel
2461     number.</t>
2462    
2463     <t>Possible Answers:</t>
2464     <t>
2465     <list>
2466     <t>"OK" -
2467     <list>
2468     <t>on success</t>
2469     </list>
2470     </t>
2471     <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2472     <list>
2473     <t>if audio output device was set, but there are noteworthy
2474     issue(s) related, providing an appropriate warning code and
2475     warning message</t>
2476     </list>
2477     </t>
2478     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2479     <list>
2480     <t>in case it failed, providing an appropriate error code and error message</t>
2481     </list>
2482     </t>
2483     </list>
2484     </t>
2485     <t>Examples:</t>
2486     <t>
2487     <list>
2488     <t></t>
2489     </list>
2490     </t>
2491     </section>
2492    
2493     <section title="Setting audio output type">
2494     <t>DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!</t>
2495    
2496     <t>The front-end can alter the audio output type on a specific sampler
2497     channel by sending the following command:</t>
2498     <t>
2499     <list>
2500     <t>SET CHANNEL AUDIO_OUTPUT_TYPE &lt;sampler-channel&gt; &lt;audio-output-type&gt;</t>
2501     </list>
2502     </t>
2503     <t>Where &lt;audio-output-type&gt; is currently either "Alsa" or "Jack" and
2504     &lt;sampler-channel&gt; is the respective sampler channel number.</t>
2505    
2506     <t>Possible Answers:</t>
2507     <t>
2508     <list>
2509     <t>"OK" -
2510     <list>
2511     <t>on success</t>
2512     </list>
2513     </t>
2514     <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2515     <list>
2516     <t>if audio output type was set, but there are noteworthy
2517     issue(s) related, providing an appropriate warning code and
2518     warning message</t>
2519     </list>
2520     </t>
2521     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2522     <list>
2523     <t>in case it failed, providing an appropriate error code and error message</t>
2524     </list>
2525     </t>
2526     </list>
2527     </t>
2528     <t>Examples:</t>
2529     <t>
2530     <list>
2531     <t></t>
2532     </list>
2533     </t>
2534     </section>
2535    
2536     <section title="Setting audio output channel">
2537     <t>The front-end can alter the audio output channel on a specific
2538     sampler channel by sending the following command:</t>
2539     <t>
2540     <list>
2541     <t>SET CHANNEL AUDIO_OUTPUT_CHANNEL &lt;sampler-chan&gt; &lt;audio-out&gt; &lt;audio-in&gt;</t>
2542     </list>
2543     </t>
2544     <t>Where &lt;sampler-chan&gt; is the sampler channel, &lt;audio-out&gt; is the
2545     sampler channel's audio output channel which should be
2546     rerouted and &lt;audio-in&gt; the audio channel of the selected audio
2547     output device where &lt;audio-out&gt; should be routed to.</t>
2548    
2549     <t>Possible Answers:</t>
2550     <t>
2551     <list>
2552     <t>"OK" -
2553     <list>
2554     <t>on success</t>
2555     </list>
2556     </t>
2557     <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2558     <list>
2559     <t>if audio output channel was set, but there are noteworthy
2560     issue(s) related, providing an appropriate warning code and
2561     warning message</t>
2562     </list>
2563     </t>
2564     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2565     <list>
2566     <t>in case it failed, providing an appropriate error code and error message</t>
2567     </list>
2568     </t>
2569     </list>
2570     </t>
2571     <t>Examples:</t>
2572     <t>
2573     <list>
2574     <t></t>
2575     </list>
2576     </t>
2577     </section>
2578    
2579     <section title="Setting MIDI input device">
2580     <t>The front-end can set the MIDI input device on a specific sampler
2581     channel by sending the following command:</t>
2582     <t>
2583     <list>
2584     <t>SET CHANNEL MIDI_INPUT_DEVICE &lt;sampler-channel&gt; &lt;midi-device-id&gt;</t>
2585     </list>
2586     </t>
2587     <t></t>
2588    
2589     <t>Possible Answers:</t>
2590     <t>
2591     <list>
2592     <t>"OK" -
2593     <list>
2594     <t>on success</t>
2595     </list>
2596     </t>
2597     <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2598     <list>
2599     <t>if MIDI input device was set, but there are noteworthy
2600     issue(s) related, providing an appropriate warning code and
2601     warning message</t>
2602     </list>
2603     </t>
2604     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2605     <list>
2606     <t>in case it failed, providing an appropriate error code and error message</t>
2607     </list>
2608     </t>
2609     </list>
2610     </t>
2611     <t>Examples:</t>
2612     <t>
2613     <list>
2614     <t></t>
2615     </list>
2616     </t>
2617     </section>
2618    
2619     <section title="Setting MIDI input type">
2620     <t>DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!</t>
2621    
2622     <t>The front-end can alter the MIDI input type on a specific sampler
2623     channel by sending the following command:</t>
2624     <t>
2625     <list>
2626     <t>SET CHANNEL MIDI_INPUT_TYPE &lt;sampler-channel&gt; &lt;midi-input-type&gt;</t>
2627     </list>
2628     </t>
2629     <t>Where &lt;midi-input-type&gt; is currently only "Alsa" and
2630     &lt;sampler-channel&gt; is the respective sampler channel number.</t>
2631    
2632     <t>Possible Answers:</t>
2633     <t>
2634     <list>
2635     <t>"OK" -
2636     <list>
2637     <t>on success</t>
2638     </list>
2639     </t>
2640     <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2641     <list>
2642     <t>if MIDI input type was set, but there are noteworthy
2643     issue(s) related, providing an appropriate warning code and
2644     warning message</t>
2645     </list>
2646     </t>
2647     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2648     <list>
2649     <t>in case it failed, providing an appropriate error code and error message</t>
2650     </list>
2651     </t>
2652     </list>
2653     </t>
2654     <t>Examples:</t>
2655     <t>
2656     <list>
2657     <t></t>
2658     </list>
2659     </t>
2660     </section>
2661    
2662     <section title="Setting MIDI input port">
2663     <t>The front-end can alter the input MIDI port on a specific sampler
2664     channel by sending the following command:</t>
2665     <t>
2666     <list>
2667     <t>SET CHANNEL MIDI_INPUT_PORT &lt;sampler-channel&gt; &lt;midi-input-port&gt;</t>
2668     </list>
2669     </t>
2670     <t>Where &lt;midi-input-port&gt; is a MIDI input port number of the
2671     MIDI input device connected to the sampler channel given by
2672     &lt;sampler-channel&gt;.</t>
2673    
2674     <t>Possible Answers:</t>
2675     <t>
2676     <list>
2677     <t>"OK" -
2678     <list>
2679     <t>on success</t>
2680     </list>
2681     </t>
2682     <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2683     <list>
2684     <t>if MIDI input port was set, but there are noteworthy
2685     issue(s) related, providing an appropriate warning code and
2686     warning message</t>
2687     </list>
2688     </t>
2689     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2690     <list>
2691     <t>in case it failed, providing an appropriate error code and error messag</t>
2692     </list>
2693     </t>
2694     </list>
2695     </t>
2696     <t>Examples:</t>
2697     <t>
2698     <list>
2699     <t></t>
2700     </list>
2701     </t>
2702     </section>
2703    
2704     <section title="Setting MIDI input channel">
2705     <t>The front-end can alter the MIDI channel a sampler channel should
2706     listen to by sending the following command:</t>
2707     <t>
2708     <list>
2709     <t>SET CHANNEL MIDI_INPUT_CHANNEL &lt;sampler-channel&gt; &lt;midi-input-chan&gt;</t>
2710     </list>
2711     </t>
2712     <t>Where &lt;midi-input-chan&gt; is the new MIDI input channel where
2713     &lt;sampler-channel&gt; should listen to or "ALL" to listen on all 16 MIDI
2714     channels.</t>
2715    
2716     <t>Possible Answers:</t>
2717     <t>
2718     <list>
2719     <t>"OK" -
2720     <list>
2721     <t>on success</t>
2722     </list>
2723     </t>
2724     <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2725     <list>
2726     <t>if MIDI input channel was set, but there are noteworthy
2727     issue(s) related, providing an appropriate warning code and
2728     warning message</t>
2729     </list>
2730     </t>
2731     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2732     <list>
2733     <t>in case it failed, providing an appropriate error code and error message</t>
2734     </list>
2735     </t>
2736     </list>
2737     </t>
2738     <t>Examples:</t>
2739     <t>
2740     <list>
2741     <t></t>
2742     </list>
2743     </t>
2744     </section>
2745    
2746     <section title="Setting channel volume">
2747     <t>The front-end can alter the volume of a sampler channel by sending
2748     the following command:</t>
2749     <t>
2750     <list>
2751     <t>SET CHANNEL VOLUME &lt;sampler-channel&gt; &lt;volume&gt;</t>
2752     </list>
2753     </t>
2754     <t>Where &lt;volume&gt; is an optionally dotted positive number (a value
2755     smaller than 1.0 means attenuation, whereas a value greater than
2756     1.0 means amplification) and &lt;sampler-channel&gt; defines the sampler
2757     channel where this volume factor should be set.</t>
2758    
2759     <t>Possible Answers:</t>
2760     <t>
2761     <list>
2762     <t>"OK" -
2763     <list>
2764     <t>on success</t>
2765     </list>
2766     </t>
2767     <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2768     <list>
2769     <t>if channel volume was set, but there are noteworthy
2770     issue(s) related, providing an appropriate warning code and
2771     warning message</t>
2772     </list>
2773     </t>
2774     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2775     <list>
2776     <t>in case it failed, providing an appropriate error code and error message</t>
2777     </list>
2778     </t>
2779     </list>
2780     </t>
2781     <t>Examples:</t>
2782     <t>
2783     <list>
2784     <t></t>
2785     </list>
2786     </t>
2787     </section>
2788    
2789     <section title="Resetting a sampler channel">
2790     <t>The front-end can reset a particular sampler channel by sending the following command:</t>
2791     <t>
2792     <list>
2793     <t>RESET CHANNEL &lt;sampler-channel&gt;</t>
2794     </list>
2795     </t>
2796     <t>
2797     Where &lt;sampler-channel&gt; defines the sampler channel to be reset.
2798     This will cause the engine on that sampler channel, its voices and
2799     eventually disk streams and all control and status variables to be
2800     reset.</t>
2801    
2802     <t>Possible Answers:</t>
2803     <t>
2804     <list>
2805     <t>"OK" -
2806     <list>
2807     <t>on success</t>
2808     </list>
2809     </t>
2810     <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2811     <list>
2812     <t>if channel was reset, but there are noteworthy issue(s)
2813     related, providing an appropriate warning code and warning
2814     message</t>
2815     </list>
2816     </t>
2817     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2818     <list>
2819     <t>in case it failed, providing an appropriate error code and
2820     error message</t>
2821     </list>
2822     </t>
2823     </list>
2824     </t>
2825     <t>Examples:</t>
2826     <t>
2827     <list>
2828     <t></t>
2829     </list>
2830     </t>
2831     </section>
2832     </section>
2833    
2834     <section title="Controlling connection">
2835     <t>The following commands are used to control the connection to LinuxSampler.</t>
2836    
2837     <section title="Register front-end for receiving event messages">
2838     <t>The front-end can register itself to the LinuxSampler application to
2839     be informed about noteworthy events by sending this command:</t>
2840     <t>
2841     <list>
2842     <t>SUBSCRIBE &lt;event-id&gt;</t>
2843     </list>
2844     </t>
2845     <t>where &lt;event-id&gt; will be replaced by the respective event that
2846     client wants to subscribe to.</t>
2847    
2848     <t>Possible Answers:</t>
2849     <t>
2850     <list>
2851     <t>"OK" -
2852     <list>
2853     <t>on success</t>
2854     </list>
2855     </t>
2856     <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2857     <list>
2858     <t>if registration succeeded, but there are noteworthy
2859     issue(s) related, providing an appropriate warning code and
2860     warning message</t>
2861     </list>
2862     </t>
2863     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2864     <list>
2865     <t>in case it failed, providing an appropriate error code and
2866     error message</t>
2867     </list>
2868     </t>
2869     </list>
2870     </t>
2871     <t>Examples:</t>
2872     <t>
2873     <list>
2874     <t></t>
2875     </list>
2876     </t>
2877     </section>
2878    
2879     <section title="Unregister front-end for not receiving UDP event messages anymore">
2880     <t>The front-end can unregister itself if it doesn't want to receive event
2881     messages anymore by sending the following command:</t>
2882     <t>
2883     <list>
2884     <t>UNSUBSCRIBE &lt;event-id&gt;</t>
2885     </list>
2886     </t>
2887     <t>Where &lt;event-id&gt; will be replaced by the respective event that
2888     client doesn't want to receive anymore.</t>
2889    
2890     <t>Possible Answers:</t>
2891     <t>
2892     <list>
2893     <t>"OK" -
2894     <list>
2895     <t>on success</t>
2896     </list>
2897     </t>
2898     <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2899     <list>
2900     <t>if unregistration succeeded, but there are noteworthy
2901     issue(s) related, providing an appropriate warning code and
2902     warning message</t>
2903     </list>
2904     </t>
2905     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2906     <list>
2907     <t>in case it failed, providing an appropriate error code and
2908     error message</t>
2909     </list>
2910     </t>
2911     </list>
2912     </t>
2913     <t>Examples:</t>
2914     <t>
2915     <list>
2916     <t></t>
2917     </list>
2918     </t>
2919     </section>
2920    
2921     <section title="Enable or disable echo of commands">
2922     <t>To enable or disable back sending of commands to the client the following command can be used:</t>
2923     <t>
2924     <list>
2925     <t>SET ECHO &lt;value&gt;</t>
2926     </list>
2927     </t>
2928     <t>Where &lt;value&gt; should be replaced either by "1" to enable echo mode
2929     or "0" to disable echo mode. When echo mode is enabled, all
2930     commands send to LinuxSampler will be immediately send back and
2931     after this echo the actual response to the command will be
2932     returned. Echo mode will only be altered for the client connection
2933     that issued the "SET ECHO" command, not globally for all client
2934     connections.</t>
2935    
2936     <t>Possible Answers:</t>
2937     <t>
2938     <list>
2939     <t>"OK" -
2940     <list>
2941     <t>usually</t>
2942     </list>
2943     </t>
2944     <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2945     <list>
2946     <t>on syntax error, e.g. non boolean value</t>
2947     </list>
2948     </t>
2949     </list>
2950     </t>
2951     <t>Examples:</t>
2952     <t>
2953     <list>
2954     <t></t>
2955     </list>
2956     </t>
2957     </section>
2958    
2959     <section title="Close client connection">
2960     <t>The client can close its network connection to LinuxSampler by sending the following command:</t>
2961     <t>
2962     <list>
2963     <t>QUIT</t>
2964     </list>
2965     </t>
2966     <t>This is probably more interesting for manual telnet connections to
2967     LinuxSampler than really useful for a front-end implementation.</t>
2968     </section>
2969     </section>
2970     </section>
2971    
2972     <section title="Command Syntax">
2973     <t>TODO: will soon automatically included from src/network/lscp.y</t>
2974     </section>
2975    
2976     <section title="Events">
2977     <t>This chapter will describe all currently defined events supported by LinuxSampler.</t>
2978    
2979     <section title="Number of sampler channels changed">
2980     <t>Client may want to be notified when the total number of channels on the
2981     back-end changes by issuing the following command:</t>
2982     <t>
2983     <list>
2984     <t>SUBSCRIBE CHANNELS</t>
2985     </list>
2986     </t>
2987     <t>Server will start sending the following notification messages:</t>
2988     <t>
2989     <list>
2990     <t>"NOTIFY:CHANNELS:&lt;channels&gt;"</t>
2991     </list>
2992     </t>
2993     <t>where &lt;channels&gt; will be replaced by the new number
2994     of sampler channels.</t>
2995     </section>
2996    
2997     <section title="Number of active voices changed">
2998     <t>Client may want to be notified when the number of voices on the
2999     back-end changes by issuing the following command:</t>
3000     <t>
3001     <list>
3002     <t>SUBSCRIBE VOICE_COUNT</t>
3003     </list>
3004     </t>
3005     <t>Server will start sending the following notification messages:</t>
3006     <t>
3007     <list>
3008     <t>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices>&gt;</t>
3009     </list>
3010     </t>
3011     <t>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
3012     voice count change occurred and &lt;voices>&gt; by the new number of
3013     active voices on that channel.</t>
3014     </section>
3015    
3016     <section title="Number of active disk streams changed">
3017     <t>Client may want to be notified when the number of streams on the back-end
3018     changes by issuing the following command: SUBSCRIBE STREAM_COUNT</t>
3019     <t>
3020     <list>
3021     <t>SUBSCRIBE STREAM_COUNT</t>
3022     </list>
3023     </t>
3024     <t>Server will start sending the following notification messages:</t>
3025     <t>
3026     <list>
3027     <t>"NOTIFY:STREAM_COUNT:&lt;sampler-channel&gt; &lt;streams&gt;"</t>
3028     </list>
3029     </t>
3030     <t>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
3031     stream count change occurred and &lt;streams&gt; by the new number of
3032     active disk streams on that channel.</t>
3033     </section>
3034    
3035     <section title="Disk stream buffer fill state changed">
3036     <t>Client may want to be notified when the number of streams on the back-end
3037     changes by issuing the following command:</t>
3038     <t>
3039     <list>
3040     <t>SUBSCRIBE BUFFER_FILL</t>
3041     </list>
3042     </t>
3043     <t>Server will start sending the following notification messages:</t>
3044     <t>
3045     <list>
3046     <t>"NOTIFY:BUFFER_FILL:&lt;sampler-channel&gt; &lt;fill-data&gt;"</t>
3047     </list>
3048     </t>
3049     <t>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
3050     buffer fill state change occurred and &lt;fill-data&gt; will be replaced by the
3051     buffer fill data for this channel as described in 4.4.12 as if the
3052     "GET CHANNEL BUFFER_FILL PERCENTAGE" was issued on this channel.</t>
3053     </section>
3054    
3055     <section title="Channel information changed">
3056     <t>Client may want to be notified when changes were made to sampler channels on the
3057     back-end changes by issuing the following command:</t>
3058     <t>
3059     <list>
3060     <t>SUBSCRIBE INFO</t>
3061     </list>
3062     </t>
3063     <t>Server will start sending the following notification messages:</t>
3064     <t>
3065     <list>
3066     <t>"NOTIFY:INFO:&lt;sampler-channel&gt;"</t>
3067     </list>
3068     </t>
3069     <t>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
3070     channel info change occurred. The front-end will have to send
3071     the respective command to actually get the channel info. Because these messages
3072     will be triggered by LSCP commands issued by other clients rather than real
3073     time events happening on the server, it is believed that an empty notification
3074     message is sufficient here.</t>
3075     </section>
3076    
3077     <section title="Miscellaneous and debugging events">
3078     <t>Client may want to be notified of miscellaneous and debugging events occurring at
3079     the server by issuing the following command:</t>
3080     <t>
3081     <list>
3082     <t>SUBSCRIBE MISCELLANEOUS</t>
3083     </list>
3084     </t>
3085     <t>Server will start sending the following notification messages:</t>
3086     <t>
3087     <list>
3088     <t>"NOTIFY:MISCELLANEOUS:&lt;string&gt;"</t>
3089     </list>
3090     </t>
3091     <t>where &lt;string&gt; will be replaced by whatever data server
3092     wants to send to the client. Client MAY display this data to the
3093     user AS IS to facilitate debugging.</t>
3094     </section>
3095     </section>
3096    
3097     <section title="Security Considerations">
3098     <t>As there is so far no method of authentication and authorization
3099     defined and so not required for a client applications to succeed to
3100     connect, running LinuxSampler might be a security risk for the host
3101     system the LinuxSampler instance is running on.</t>
3102     </section>
3103    
3104     <section title="Acknowledgments">
3105     <t>This document has benefited greatly from the comments of the
3106     following people, discussed on the LinuxSampler developer's mailing
3107     list:</t>
3108     <t>
3109     <list>
3110     <t>Rui Nuno Capela</t>
3111     <t>Vladimir Senkov</t>
3112     <t>Mark Knecht</t>
3113     </list>
3114     </t>
3115     </section>
3116    
3117     </middle>
3118    
3119     <back>
3120     <references>&rfc2119;</references>
3121     </back>
3122    
3123     </rfc>

  ViewVC Help
Powered by ViewVC