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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 494 - (show annotations) (download) (as text)
Wed Apr 6 19:24:39 2005 UTC (18 years, 11 months ago) by schoenebeck
File MIME type: text/xml
File size: 168804 byte(s)
* fixed couple of mistakes in the LSCP specification document

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

  ViewVC Help
Powered by ViewVC