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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 561 - (hide annotations) (download) (as text)
Sat May 21 20:01:32 2005 UTC (18 years, 10 months ago) by schoenebeck
File MIME type: text/xml
File size: 176401 byte(s)
- minor fixes, mostly typos (patch by Grigor Iliev)
- added Grigor Iliev to "Acknowledgments" chapter

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

  ViewVC Help
Powered by ViewVC