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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 499 - (hide annotations) (download) (as text)
Fri Apr 15 11:54:22 2005 UTC (18 years, 11 months ago) by schoenebeck
File MIME type: text/xml
File size: 169020 byte(s)
* little correction in LSCP specification document (patch by Grigor Iliev)

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

  ViewVC Help
Powered by ViewVC