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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3502 - (show annotations) (download) (as text)
Mon Mar 11 15:42:54 2019 UTC (16 months, 3 weeks ago) by schoenebeck
File MIME type: text/xml
File size: 502284 byte(s)
- LSCP Reference doc: Fixed xml2rfc conversion error.

1 <?xml version="1.0" encoding="UTF-8"?>
2
3 <!-- NOTE: Use xml2rfc -n switch to avoid irrelevant DTD errors for now. -->
4
5 <!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
6 <!ENTITY rfc2119 PUBLIC ''
7 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
8 ]>
9
10 <?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
11
12 <?rfc toc="yes" ?>
13 <?rfc symrefs="yes" ?>
14 <?rfc sortrefs="yes"?>
15 <?rfc iprnotified="no" ?>
16
17 <!-- FIXME: next attribute should actually be "yes", temporarily disbled due
18 to an annoying "missing Normative/Informative References" error message -->
19 <?rfc strict="no" ?>
20
21 <rfc category="info" ipr="noDerivativesTrust200902" docName="LSCP 1.7">
22 <front>
23 <title>LinuxSampler Control Protocol</title>
24 <author initials='C.S.' surname="Schoenebeck" fullname='C.
25 Schoenebeck' role="editor">
26 <organization>
27 LinuxSampler.org
28 </organization>
29 <address>
30 <postal>
31 <street>Crudebyte Engineering</street>
32 <street>Hofgartenstr. 3</street>
33 <!-- <code>74081</code> -->
34 <city>74189 Weinsberg</city>
35 <country>Germany</country>
36 </postal>
37 <phone>+49 7134 911614</phone>
38 <email>cuse@users.sf.net</email>
39 </address>
40 </author>
41 <date month="March" year="2019"/>
42 <workgroup>LinuxSampler Developers</workgroup>
43 <keyword>LSCP</keyword>
44 <abstract>
45 <t>The LinuxSampler Control Protocol (LSCP) is an
46 application-level protocol primarily intended for local and
47 remote controlling the LinuxSampler backend application, which is a
48 sophisticated server-like console application essentially playing
49 back audio samples and manipulating the samples in real time to
50 certain extent.</t>
51 </abstract>
52 </front>
53
54 <middle>
55 <section title="Requirements notation">
56 <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
57 "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
58 and "OPTIONAL" in this document are to be interpreted as
59 described in <xref target="RFC2119"/>.</t>
60
61 <t>This protocol is always case-sensitive if not explicitly
62 claimed the opposite.</t>
63
64 <t>In examples, "C:" and "S:" indicate lines sent by the client
65 (front-end) and server (LinuxSampler) respectively. Lines in
66 examples must be interpreted as every line being CRLF
67 terminated (carriage return character followed by line feed
68 character as defined in the ASCII standard <xref target="RFC20"/>),
69 thus the following example:</t>
70
71 <t>
72 <list>
73 <t>C: "some line"</t>
74 <t>&nbsp;&nbsp;&nbsp;"another line"</t>
75 </list>
76 </t>
77
78 <t>must actually be interpreted as client sending the following
79 message:</t>
80
81 <t>
82 <list>
83 <t>"some line&lt;CR&gt;&lt;LF&gt;another
84 line&lt;CR&gt;&lt;LF&gt;"</t>
85 </list>
86 </t>
87
88 <t>where &lt;CR&gt; symbolizes the carriage return character and
89 &lt;LF&gt; the line feed character as defined in the ASCII
90 standard.</t>
91
92 <t>Due to technical reasons, messages can arbitrary be
93 fragmented, means the following example:</t>
94
95 <t>
96 <list>
97 <t>S: "abcd"</t>
98 </list>
99 </t>
100
101 <t>could also happen to be sent in three messages like in the
102 following sequence scenario:</t>
103
104 <t>
105 <list style="symbols">
106 <t>server sending message "a"</t>
107 <t>followed by a delay (pause) with
108 arbitrary duration</t>
109 <t>followed by server sending message
110 "bcd&lt;CR&gt;"</t>
111 <t>again followed by a delay (pause) with arbitrary
112 duration</t>
113 <t>followed by server sending the message
114 "&lt;LF&gt;"</t>
115 </list>
116 </t>
117
118 <t>where again &lt;CR&gt; and &lt;LF&gt; symbolize the carriage
119 return and line feed characters respectively.</t>
120 </section>
121
122 <section title="Versioning of this specification" anchor="LSCP versioning">
123 <t>LSCP will certainly be extended and enhanced by-and-by. Each official
124 release of the LSCP specification will be tagged with a unique version
125 tuple. The version tuple consists at least of a major and minor version
126 number like:
127 </t>
128 <t>
129 <list>
130 <t>"1.2"</t>
131 </list>
132 </t>
133 <t>
134 In this example the major version number would be "1" and the minor
135 version number would be "2". Note that the version tuple might also
136 have more than two elements. The major version number defines a
137 group of backward compatible versions. That means a frontend is
138 compatible to the connected sampler if and only if the LSCP versions
139 to which each of the two parties complies to, match both of the
140 following rules:
141 </t>
142 <t>Compatibility:</t>
143 <t>
144 <list style="numbers">
145 <t>The frontend's LSCP major version and the sampler's LSCP
146 major version are exactly equal.</t>
147 <t>The frontend's LSCP minor version is less or equal than
148 the sampler's LSCP minor version.</t>
149 </list>
150 </t>
151 <t>
152 Compatibility can only be claimed if both rules are true.
153 The frontend can use the
154 <xref target="GET SERVER INFO">"GET SERVER INFO"</xref> command to
155 get the version of the LSCP specification the sampler complies with.
156 </t>
157 </section>
158
159 <section title="Introduction">
160 <t>LinuxSampler is a so called software sampler application
161 capable to playback audio samples from a computer's Random
162 Access Memory (RAM) as well as directly streaming it from disk.
163 LinuxSampler is designed to be modular. It provides several so
164 called "sampler engines" where each engine is specialized for a
165 certain purpose. LinuxSampler has virtual channels which will be
166 referred in this document as "sampler channels". The channels
167 are in such way virtual as they can be connected to an
168 arbitrary MIDI input method and arbitrary MIDI channel (e.g.
169 sampler channel 17 could be connected to an ALSA sequencer
170 device 64:0 and listening to MIDI channel 1 there). Each sampler
171 channel will be associated with an instance of one of the available
172 sampler engines (e.g. GigEngine, DLSEngine). The audio output of
173 each sampler channel can be routed to an arbitrary audio output
174 method (ALSA / JACK) and an arbitrary audio output channel
175 there.</t>
176 </section>
177
178 <section title="Focus of this protocol">
179 <t>Main focus of this protocol is to provide a way to configure
180 a running LinuxSampler instance and to retrieve information
181 about it. The focus of this protocol is not to provide a way to
182 control synthesis parameters or even to trigger or release
183 notes. Or in other words; the focus are those functionalities
184 which are not covered by MIDI or which may at most be handled
185 via MIDI System Exclusive Messages.</t>
186 </section>
187
188 <section title="Communication Overview">
189 <t>There are two distinct methods of communication between a
190 running instance of LinuxSampler and one or more control
191 applications, so called "front-ends": a simple request/response
192 communication method used by the clients to give commands to the
193 server as well as to inquire about server's status and a
194 subscribe/notify communication method used by the client to
195 subscribe to and receive notifications of certain events as they
196 happen on the server. The latter needs more effort to be
197 implemented in the front-end application. The two communication
198 methods will be described next.</t>
199
200 <section title="Request/response communication method">
201 <t>This simple communication method is based on
202 <xref target="RFC793">TCP</xref>. The
203 front-end application establishes a TCP connection to the
204 LinuxSampler instance on a certain host system. Then the
205 front-end application will send certain ASCII based commands
206 as defined in this document (every command line must be CRLF
207 terminated - see "Conventions used in this document" at the
208 beginning of this document) and the LinuxSampler application
209 will response after a certain process time with an
210 appropriate ASCII based answer, also as defined in this
211 document. So this TCP communication is simply based on query
212 and answer paradigm. That way LinuxSampler is only able to
213 answer on queries from front-ends, but not able to
214 automatically send messages to the client if it's not asked
215 to. The fronted should not reconnect to LinuxSampler for
216 every single command, instead it should keep the connection
217 established and simply resend message(s) for subsequent
218 commands. To keep information in the front-end up-to-date
219 the front-end has to periodically send new requests to get
220 the current information from the LinuxSampler instance. This
221 is often referred to as "polling". While polling is simple
222 to implement and may be OK to use in some cases, there may
223 be disadvantages to polling such as network traffic overhead
224 and information being out of date.
225 It is possible for a client or several clients to open more
226 than one connection to the server at the same time. It is
227 also possible to send more than one request to the server
228 at the same time but if those requests are sent over the
229 same connection server MUST execute them sequentially. Upon
230 executing a request server will produce a result set and
231 send it to the client. Each and every request made by the
232 client MUST result in a result set being sent back to the
233 client. No other data other than a result set may be sent by
234 a server to a client. No result set may be sent to a client
235 without the client sending request to the server first. On
236 any particular connection, result sets MUST be sent in their
237 entirety without being interrupted by other result sets. If
238 several requests got queued up at the server they MUST be
239 processed in the order they were received and result sets
240 MUST be sent back in the same order.</t>
241
242 <section title="Result format">
243 <t>Result set could be one of the following types:</t>
244 <t>
245 <list style="numbers">
246 <t>Normal</t>
247 <t>Warning</t>
248 <t>Error</t>
249 </list>
250 </t>
251 <t>Warning and Error result sets MUST be single line and
252 have the following format:</t>
253 <t>
254 <list style="symbols">
255 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;"</t>
256 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;"</t>
257 </list>
258 </t>
259 <t>Where &lt;warning-code&gt; and &lt;error-code&gt; are
260 numeric unique identifiers of the warning or error and
261 &lt;warning-message&gt; and &lt;error-message&gt; are
262 human readable descriptions of the warning or error
263 respectively.</t>
264 <t>Examples:</t>
265 <t>
266 <list>
267 <t>C: "LOAD INSTRUMENT '/home/me/Boesendorfer24bit.gig" 0 0</t>
268 <t>S: "WRN:32:This is a 24 bit patch which is not supported natively yet."</t>
269 </list>
270 </t>
271 <t>
272 <list>
273 <t>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA EAR"</t>
274 <t>S: "ERR:3456:Audio output driver 'ALSA' does not have a parameter 'EAR'."</t>
275 </list>
276 </t>
277 <t>
278 <list>
279 <t>C: "GET AUDIO_OUTPUT_DEVICE INFO 123456"</t>
280 <t>S: "ERR:9:There is no audio output device with index 123456."</t>
281 </list>
282 </t>
283 <t>Normal result sets could be:</t>
284 <t>
285 <list style="numbers">
286 <t>Empty</t>
287 <t>Single line</t>
288 <t>Multi-line</t>
289 </list>
290 </t>
291 <t> Empty result set is issued when the server only
292 needed to acknowledge the fact that the request was
293 received and it was processed successfully and no
294 additional information is available. This result set has
295 the following format:</t>
296 <t>
297 <list>
298 <t>"OK"</t>
299 </list>
300 </t>
301 <t>Example:</t>
302 <t>
303 <list>
304 <t>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 CHANNELS=4"</t>
305 <t>S: "OK"</t>
306 </list>
307 </t>
308 <t>Single line result sets are command specific. One
309 example of a single line result set is an empty line.
310 Multi-line result sets are command specific and may
311 include one or more lines of information. They MUST
312 always end with the following line:</t>
313 <t>
314 <list>
315 <t>"."</t>
316 </list>
317 </t>
318 <t>Example:</t>
319 <t>
320 <list>
321 <t>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"</t>
322 <t>S: "DRIVER: ALSA"</t>
323 <t>&nbsp;&nbsp;&nbsp;"CHANNELS: 2"</t>
324 <t>&nbsp;&nbsp;&nbsp;"SAMPLERATE: 44100"</t>
325 <t>&nbsp;&nbsp;&nbsp;"ACTIVE: true"</t>
326 <t>&nbsp;&nbsp;&nbsp;"FRAGMENTS: 2"</t>
327 <t>&nbsp;&nbsp;&nbsp;"FRAGMENTSIZE: 128"</t>
328 <t>&nbsp;&nbsp;&nbsp;"CARD: '0,0'"</t>
329 <t>&nbsp;&nbsp;&nbsp;"."</t>
330 </list>
331 </t>
332 <t>In addition to above mentioned formats, warnings and
333 empty result sets MAY be indexed. In this case, they
334 have the following formats respectively:</t>
335 <t>
336 <list style="symbols">
337 <t>"WRN[&lt;index&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;"</t>
338 <t>"OK[&lt;index&gt;]"</t>
339 </list>
340 </t>
341 <t>where &lt;index&gt; is command specific and is used
342 to indicate channel number that the result set was
343 related to or other integer value.</t>
344 <t>Each line of the result set MUST end with
345 &lt;CRLF&gt;.</t>
346 <t>Examples:</t>
347 <t>
348 <list>
349 <t>C: "ADD CHANNEL"</t>
350 <t>S: "OK[12]"</t>
351 </list>
352 </t>
353 <t>
354 <list>
355 <t>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"</t>
356 <t>S: "WRN[0]:32:Sample rate not supported, using 44100 instead."</t>
357 </list>
358 </t>
359 </section>
360 </section>
361 <section title="Subscribe/notify communication method">
362 <t>This more sophisticated communication method is actually
363 only an extension of the simple request/response
364 communication method. The front-end still uses a TCP
365 connection and sends the same commands on the TCP
366 connection. Two extra commands are SUBSCRIBE and UNSUBSCRIBE
367 commands that allow a client to tell the server that it is
368 interested in receiving notifications about certain events
369 as they happen on the server. The SUBSCRIBE command has the
370 following syntax:</t>
371
372 <t>
373 <list>
374 <t>SUBSCRIBE &lt;event-id&gt;</t>
375 </list>
376 </t>
377
378 <t>where &lt;event-id&gt; will be replaced by the respective
379 event that client wants to subscribe to. Upon receiving such
380 request, server SHOULD respond with OK and start sending
381 EVENT notifications when a given even has occurred to the
382 front-end when an event has occurred. It MAY be possible
383 certain events may be sent before OK response during real
384 time nature of their generation. Event messages have the
385 following format:</t>
386
387 <t>
388 <list>
389 <t>NOTIFY:&lt;event-id&gt;:&lt;custom-event-data&gt;</t>
390 </list>
391 </t>
392
393 <t>where &lt;event-id&gt; uniquely identifies the event that
394 has occurred and &lt;custom-event-data&gt; is event
395 specific.</t>
396
397 <t>Several rules must be followed by the server when
398 generating events:</t>
399
400 <t>
401 <list style="numbers">
402 <t>Events MUST NOT be sent to any client who has not
403 issued an appropriate SUBSCRIBE command.</t>
404 <t>Events MUST only be sent using the same
405 connection that was used to subscribe to them.</t>
406 <t>When response is being sent to the client, event
407 MUST be inserted in the stream before or after the
408 response, but NOT in the middle. Same is true about
409 the response. It should never be inserted in the
410 middle of the event message as well as any other
411 response.</t>
412 </list>
413 </t>
414
415 <t>If the client is not interested in a particular event
416 anymore it MAY issue UNSUBSCRIBE command using the following
417 syntax:</t>
418
419 <t>
420 <list>
421 <t>UNSUBSCRIBE &lt;event-id&gt;</t>
422 </list>
423 </t>
424
425 <t>where &lt;event-id&gt; will be replace by the respective
426 event that client is no longer interested in receiving. For
427 a list of supported events see <xref target="events" />.</t>
428
429 <t>Example: the fill states of disk stream buffers have
430 changed on sampler channel 4 and the LinuxSampler instance
431 will react by sending the following message to all clients
432 who subscribed to this event:</t>
433
434 <t>
435 <list>
436 <t>NOTIFY:CHANNEL_BUFFER_FILL:4 [35]62%,[33]80%,[37]98%</t>
437 </list>
438 </t>
439
440 <t>Which means there are currently three active streams on
441 sampler channel 4, where the stream with ID "35" is filled
442 by 62%, stream with ID 33 is filled by 80% and stream with
443 ID 37 is filled by 98%.</t>
444
445 <t>Clients may choose to open more than one connection to
446 the server and use some connections to receive notifications
447 while using other connections to issue commands to the
448 back-end. This is entirely legal and up to the
449 implementation. This does not change the protocol in any way
450 and no special restrictions exist on the server to allow or
451 disallow this or to track what connections belong to what
452 front-ends. Server will listen on a single port, accept
453 multiple connections and support protocol described in this
454 specification in it's entirety on this single port on each
455 connection that it accepted.</t>
456
457 <t>Due to the fact that TCP is used for this communication,
458 dead peers will be detected automatically by the OS TCP
459 stack. While it may take a while to detect dead peers if no
460 traffic is being sent from server to client (TCP keep-alive
461 timer is set to 2 hours on many OSes) it will not be an
462 issue here as when notifications are sent by the server,
463 dead client will be detected quickly.</t>
464
465 <t>When connection is closed for any reason server MUST
466 forget all subscriptions that were made on this connection.
467 If client reconnects it MUST resubscribe to all events that
468 it wants to receive.</t>
469
470 </section>
471 </section>
472
473 <section title="Description for control commands" anchor="control_commands">
474 <t>This chapter will describe the available control commands
475 that can be sent on the TCP connection in detail. Some certain
476 commands (e.g. <xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref>
477 or <xref target="GET ENGINE INFO">"GET ENGINE INFO"</xref>) lead to
478 multiple-line responses. In this case LinuxSampler signals the
479 end of the response by a "." (single dot) line.</t>
480
481 <section title="Ignored lines and comments">
482 <t>White lines, that is lines which only contain space and
483 tabulator characters, and lines that start with a "#"
484 character are ignored, thus it's possible for example to
485 group commands and to place comments in a LSCP script
486 file.</t>
487 </section>
488
489 <section title="Configuring audio drivers">
490 <t>Instances of drivers in LinuxSampler are called devices.
491 You can use multiple audio devices simultaneously, e.g. to
492 output the sound of one sampler channel using the ALSA audio
493 output driver, and on another sampler channel you might want
494 to use the JACK audio output driver. For particular audio
495 output systems it's also possible to create several devices
496 of the same audio output driver, e.g. two separate ALSA
497 audio output devices for using two different sound cards at
498 the same time. This chapter describes all commands to
499 configure LinuxSampler's audio output devices and their
500 parameters.</t>
501
502 <t>Instead of defining commands and parameters for each
503 driver individually, all possible parameters, their meanings
504 and possible values have to be obtained at runtime. This
505 makes the protocol a bit abstract, but has the advantage,
506 that front-ends can be written independently of what drivers
507 are currently implemented and what parameters these drivers
508 are actually offering. This means front-ends can even handle
509 drivers which are implemented somewhere in future without
510 modifying the front-end at all.</t>
511
512 <t>Note: examples in this chapter showing particular
513 parameters of drivers are not meant as specification of the
514 drivers' parameters. Driver implementations in LinuxSampler
515 might have complete different parameter names and meanings
516 than shown in these examples or might change in future, so
517 these examples are only meant for showing how to retrieve
518 what parameters drivers are offering, how to retrieve their
519 possible values, etc.</t>
520
521 <section title="Getting amount of available audio output drivers" anchor="GET AVAILABLE_AUDIO_OUTPUT_DRIVERS" lscp_cmd="true">
522 <t>Use the following command to get the number of
523 audio output drivers currently available for the
524 LinuxSampler instance:</t>
525 <t>
526 <list>
527 <t>GET AVAILABLE_AUDIO_OUTPUT_DRIVERS</t>
528 </list>
529 </t>
530 <t>Possible Answers:</t>
531 <t>
532 <list>
533 <t>LinuxSampler will answer by sending the
534 number of audio output drivers.</t>
535 </list>
536 </t>
537 <t>Example:</t>
538 <t>
539 <list>
540 <t>C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"</t>
541 <t>S: "2"</t>
542 </list>
543 </t>
544 </section>
545
546 <section title="Getting all available audio output drivers" anchor="LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" lscp_cmd="true">
547 <t>Use the following command to list all audio output
548 drivers currently available for the LinuxSampler
549 instance:</t>
550 <t>
551 <list>
552 <t>LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS</t>
553 </list>
554 </t>
555 <t>Possible Answers:</t>
556 <t>
557 <list>
558 <t>LinuxSampler will answer by sending comma
559 separated character strings, each symbolizing an
560 audio output driver.</t>
561 </list>
562 </t>
563 <t>Example:</t>
564 <t>
565 <list>
566 <t>C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"</t>
567 <t>S: "ALSA,JACK"</t>
568 </list>
569 </t>
570 </section>
571
572 <section title="Getting information about a specific audio
573 output driver" anchor="GET AUDIO_OUTPUT_DRIVER INFO" lscp_cmd="true">
574 <t>Use the following command to get detailed information
575 about a specific audio output driver:</t>
576 <t>
577 <list>
578 <t>GET AUDIO_OUTPUT_DRIVER INFO
579 &lt;audio-output-driver&gt;</t>
580 </list>
581 </t>
582 <t>Where &lt;audio-output-driver&gt; is the name of the
583 audio output driver, returned by the
584 <xref target="LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"</xref> command.</t>
585 <t>Possible Answers:</t>
586 <t>
587 <list>
588 <t>LinuxSampler will answer by sending a
589 &lt;CRLF&gt; separated list. Each answer line
590 begins with the information category name
591 followed by a colon and then a space character
592 &lt;SP&gt; and finally the info character string
593 to that info category. At the moment the
594 following information categories are
595 defined:</t>
596
597 <t>
598 <list>
599 <t>DESCRIPTION -
600 <list>
601 <t> character string describing the
602 audio output driver</t>
603 </list>
604 </t>
605
606 <t>VERSION -
607 <list>
608 <t>character string reflecting the
609 driver's version</t>
610 </list>
611 </t>
612
613 <t>PARAMETERS -
614 <list>
615 <t>comma separated list of all
616 parameters available for the given
617 audio output driver, at least
618 parameters 'channels', 'samplerate'
619 and 'active' are offered by all audio
620 output drivers</t>
621 </list>
622 </t>
623 </list>
624 </t>
625
626 <t>The mentioned fields above don't have to be
627 in particular order.</t>
628 </list>
629 </t>
630 <t>Example:</t>
631 <t>
632 <list>
633 <t>C: "GET AUDIO_OUTPUT_DRIVER INFO ALSA"</t>
634 <t>S: "DESCRIPTION: Advanced Linux Sound
635 Architecture"</t>
636 <t>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"</t>
637 <t>&nbsp;&nbsp;&nbsp;"PARAMETERS:
638 DRIVER,CHANNELS,SAMPLERATE,ACTIVE,FRAGMENTS,
639 FRAGMENTSIZE,CARD"</t>
640 <t>&nbsp;&nbsp;&nbsp;"."</t>
641 </list>
642 </t>
643 </section>
644
645 <section title="Getting information about specific audio
646 output driver parameter" anchor="GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO" lscp_cmd="true">
647 <t>Use the following command to get detailed information
648 about a specific audio output driver parameter:</t>
649 <t>
650 <list>
651 <t>GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO &lt;audio&gt; &lt;prm&gt; [&lt;deplist&gt;]</t>
652 </list>
653 </t>
654 <t>Where &lt;audio&gt; is the name of the audio output
655 driver as returned by the <xref target="LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">
656 "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"</xref> command,
657 &lt;prm&gt; a specific parameter name for which information should be
658 obtained (as returned by the
659 <xref target="GET AUDIO_OUTPUT_DRIVER INFO">"GET AUDIO_OUTPUT_DRIVER INFO"</xref> command) and
660 &lt;deplist&gt; is an optional list of parameters on which the sought
661 parameter &lt;prm&gt; depends on, &lt;deplist&gt; is a list of key-value
662 pairs in form of "key1=val1 key2=val2 ...", where character string values
663 are encapsulated into apostrophes ('). Arguments given with &lt;deplist&gt;
664 which are not dependency parameters of &lt;prm&gt; will be ignored, means
665 the front-end application can simply put all parameters into &lt;deplist&gt;
666 with the values already selected by the user.</t>
667 <t>Possible Answers:</t>
668 <t>
669 <list>
670 <t>LinuxSampler will answer by sending a
671 &lt;CRLF&gt; separated list.
672 Each answer line begins with the information category name
673 followed by a colon and then a space character &lt;SP&gt; and
674 finally
675 the info character string to that info category. There are
676 information which is always returned, independently of the
677 given driver parameter and there are optional information
678 which is only shown dependently to given driver parameter. At
679 the moment the following information categories are defined:</t>
680 </list>
681 </t>
682
683 <t>
684 <list>
685 <t>TYPE -
686 <list>
687 <t>either "BOOL" for boolean value(s) or
688 "INT" for integer
689 value(s) or "FLOAT" for dotted number(s) or "STRING" for
690 character string(s)
691 (always returned, no matter which driver parameter)</t>
692 </list>
693 </t>
694
695 <t>DESCRIPTION -
696 <list>
697 <t>arbitrary text describing the purpose of the parameter
698 (always returned, no matter which driver parameter)</t>
699 </list>
700 </t>
701
702 <t>MANDATORY -
703 <list>
704 <t>either true or false, defines if this parameter must be
705 given when the device is to be created with the
706 <xref target="CREATE AUDIO_OUTPUT_DEVICE">'CREATE AUDIO_OUTPUT_DEVICE'</xref>
707 command (always returned, no matter which driver parameter)</t>
708 </list>
709 </t>
710
711 <t>FIX -
712 <list>
713 <t>either true or false, if false then this parameter can
714 be changed at any time, once the device is created by
715 the <xref target="CREATE AUDIO_OUTPUT_DEVICE">'CREATE AUDIO_OUTPUT_DEVICE'</xref>
716 command (always returned, no matter which driver parameter)</t>
717 </list>
718 </t>
719
720 <t>MULTIPLICITY -
721 <list>
722 <t>either true or false, defines if this parameter allows
723 only one value or a list of values, where true means
724 multiple values and false only a single value allowed
725 (always returned, no matter which driver parameter)</t>
726 </list>
727 </t>
728
729 <t>DEPENDS -
730 <list>
731 <t>comma separated list of parameters this parameter depends
732 on, means the values for fields 'DEFAULT', 'RANGE_MIN',
733 'RANGE_MAX' and 'POSSIBILITIES' might depend on these
734 listed parameters, for example assuming that an audio
735 driver (like the ALSA driver) offers parameters 'card'
736 and 'samplerate' then parameter 'samplerate' would
737 depend on 'card' because the possible values for
738 'samplerate' depends on the sound card which can be
739 chosen by the 'card' parameter
740 (optionally returned, dependent to driver parameter)</t>
741 </list>
742 </t>
743
744 <t>DEFAULT -
745 <list>
746 <t>reflects the default value for this parameter which is
747 used when the device is created and not explicitly
748 given with the <xref target="CREATE AUDIO_OUTPUT_DEVICE">
749 'CREATE AUDIO_OUTPUT_DEVICE'</xref> command,
750 in case of MULTIPLCITY=true, this is a comma separated
751 list, that's why character strings are encapsulated into
752 apostrophes (')
753 (optionally returned, dependent to driver parameter)</t>
754 </list>
755 </t>
756
757 <t>RANGE_MIN -
758 <list>
759 <t>defines lower limit of the allowed value range for this
760 parameter, can be an integer value as well as a dotted
761 number, this parameter is often used in conjunction
762 with RANGE_MAX, but may also appear without
763 (optionally returned, dependent to driver parameter)</t>
764 </list>
765 </t>
766
767 <t>RANGE_MAX -
768 <list>
769 <t>defines upper limit of the allowed value range for this
770 parameter, can be an integer value as well as a dotted
771 number, this parameter is often used in conjunction with
772 RANGE_MIN, but may also appear without
773 (optionally returned, dependent to driver parameter)</t>
774 </list>
775 </t>
776
777 <t>POSSIBILITIES -
778 <list>
779 <t>comma separated list of possible values for this
780 parameter, character strings are encapsulated into
781 apostrophes
782 (optionally returned, dependent to driver parameter)</t>
783 </list>
784 </t>
785 </list>
786 </t>
787
788 <t>The mentioned fields above don't have to be in particular order.</t>
789
790 <t>Examples:</t>
791 <t>
792 <list>
793 <t>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA CARD"</t>
794 <t>S: "DESCRIPTION: sound card to be used"</t>
795 <t>&nbsp;&nbsp;&nbsp;"TYPE: STRING"</t>
796 <t>&nbsp;&nbsp;&nbsp;"MANDATORY: false"</t>
797 <t>&nbsp;&nbsp;&nbsp;"FIX: true"</t>
798 <t>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"</t>
799 <t>&nbsp;&nbsp;&nbsp;"DEFAULT: '0,0'"</t>
800 <t>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: '0,0','1,0','2,0'"</t>
801 <t>&nbsp;&nbsp;&nbsp;"."</t>
802 </list>
803 </t>
804 <t>
805 <list>
806 <t>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE"</t>
807 <t>S: "DESCRIPTION: output sample rate in Hz"</t>
808 <t>&nbsp;&nbsp;&nbsp;"TYPE: INT"</t>
809 <t>&nbsp;&nbsp;&nbsp;"MANDATORY: false"</t>
810 <t>&nbsp;&nbsp;&nbsp;"FIX: false"</t>
811 <t>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"</t>
812 <t>&nbsp;&nbsp;&nbsp;"DEPENDS: card"</t>
813 <t>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"</t>
814 <t>&nbsp;&nbsp;&nbsp;"."</t>
815 </list>
816 </t>
817 <t>
818 <list>
819 <t>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE CARD='0,0'"</t>
820 <t>S: "DESCRIPTION: output sample rate in Hz"</t>
821 <t>&nbsp;&nbsp;&nbsp;"TYPE: INT"</t>
822 <t>&nbsp;&nbsp;&nbsp;"MANDATORY: false"</t>
823 <t>&nbsp;&nbsp;&nbsp;"FIX: false"</t>
824 <t>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"</t>
825 <t>&nbsp;&nbsp;&nbsp;"DEPENDS: card"</t>
826 <t>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"</t>
827 <t>&nbsp;&nbsp;&nbsp;"RANGE_MIN: 22050"</t>
828 <t>&nbsp;&nbsp;&nbsp;"RANGE_MAX: 96000"</t>
829 <t>&nbsp;&nbsp;&nbsp;"."</t>
830 </list>
831 </t>
832 </section>
833
834 <section title="Creating an audio output device" anchor="CREATE AUDIO_OUTPUT_DEVICE" lscp_cmd="true">
835 <t>Use the following command to create a new audio output device for the desired audio output system:</t>
836
837 <t>
838 <list>
839 <t>CREATE AUDIO_OUTPUT_DEVICE &lt;audio-output-driver&gt; [&lt;param-list&gt;]</t>
840 </list>
841 </t>
842
843 <t>Where &lt;audio-output-driver&gt; should be replaced by the desired audio
844 output system as returned by the
845 <xref target="LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"</xref>
846 command and &lt;param-list&gt; by an optional list of driver
847 specific parameters in form of "key1=val1 key2=val2 ...", where
848 character string values should be encapsulated into apostrophes (').
849 Note that there might be drivers which require parameter(s) to be
850 given with this command. Use the previously described commands in
851 this chapter to get this information.</t>
852
853 <t>Possible Answers:</t>
854 <t>
855 <list>
856 <t>"OK[&lt;device-id&gt;]" -
857 <list>
858 <t>in case the device was successfully created, where
859 &lt;device-id&gt; is the numerical ID of the new device</t>
860 </list>
861 </t>
862 <t>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
863 <list>
864 <t>in case the device was created successfully, where
865 &lt;device-id&gt; is the numerical ID of the new device, but there
866 are noteworthy issue(s) related (e.g. sound card doesn't
867 support given hardware parameters and the driver is using
868 fall-back values), providing an appropriate warning code and
869 warning message</t>
870 </list>
871 </t>
872 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
873 <list>
874 <t>in case it failed, providing an appropriate error code and error message</t>
875 </list>
876 </t>
877 </list>
878 </t>
879 <t>Examples:</t>
880 <t>
881 <list>
882 <t>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA"</t>
883 <t>S: "OK[0]"</t>
884 </list>
885 </t>
886 <t>
887 <list>
888 <t>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"</t>
889 <t>S: "OK[1]"</t>
890 </list>
891 </t>
892 </section>
893
894 <section title="Destroying an audio output device" anchor="DESTROY AUDIO_OUTPUT_DEVICE" lscp_cmd="true">
895 <t>Use the following command to destroy a created output device:</t>
896 <t>
897 <list>
898 <t>DESTROY AUDIO_OUTPUT_DEVICE &lt;device-id&gt;</t>
899 </list>
900 </t>
901 <t>Where &lt;device-id&gt; should be replaced by the numerical ID of the
902 audio output device as given by the
903 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
904 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
905 command.</t>
906 <t>Possible Answers:</t>
907 <t>
908 <list>
909 <t>"OK" -
910 <list>
911 <t>in case the device was successfully destroyed</t>
912 </list>
913 </t>
914 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
915 <list>
916 <t>in case the device was destroyed successfully, but there are
917 noteworthy issue(s) related (e.g. an audio over ethernet
918 driver was unloaded but the other host might not be
919 informed about this situation), providing an appropriate
920 warning code and warning message</t>
921 </list>
922 </t>
923 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
924 <list>
925 <t>in case it failed, providing an appropriate error code and
926 error message</t>
927 </list>
928 </t>
929 </list>
930 </t>
931 <t>Example:</t>
932 <t>
933 <list>
934 <t>C: "DESTROY AUDIO_OUTPUT_DEVICE 0"</t>
935 <t>S: "OK"</t>
936 </list>
937 </t>
938 </section>
939
940 <section title="Getting all created audio output device count" anchor="GET AUDIO_OUTPUT_DEVICES">
941 <t>Use the following command to count all created audio output devices:</t>
942 <t>
943 <list>
944 <t>GET AUDIO_OUTPUT_DEVICES</t>
945 </list>
946 </t>
947 <t>Possible Answers:</t>
948 <t>
949 <list>
950 <t>LinuxSampler will answer by sending the current number of all
951 audio output devices.</t>
952 </list>
953 </t>
954 <t>Example:</t>
955 <t>
956 <list>
957 <t>C: "GET AUDIO_OUTPUT_DEVICES"</t>
958 <t>S: "4"</t>
959 </list>
960 </t>
961 </section>
962
963 <section title="Getting all created audio output device list" anchor="LIST AUDIO_OUTPUT_DEVICES" lscp_cmd="true">
964 <t>Use the following command to list all created audio output devices:</t>
965 <t>
966 <list>
967 <t>LIST AUDIO_OUTPUT_DEVICES</t>
968 </list>
969 </t>
970 <t>Possible Answers:</t>
971 <t>
972 <list>
973 <t>LinuxSampler will answer by sending a comma separated list with
974 the numerical IDs of all audio output devices.</t>
975 </list>
976 </t>
977 <t>Example:</t>
978 <t>
979 <list>
980 <t>C: "LIST AUDIO_OUTPUT_DEVICES"</t>
981 <t>S: "0,1,4,5"</t>
982 </list>
983 </t>
984 </section>
985
986 <section title="Getting current settings of an audio output device" anchor="GET AUDIO_OUTPUT_DEVICE INFO" lscp_cmd="true">
987 <t>Use the following command to get current settings of a specific, created audio output device:</t>
988 <t>
989 <list>
990 <t>GET AUDIO_OUTPUT_DEVICE INFO &lt;device-id&gt;</t>
991 </list>
992 </t>
993 <t>Where &lt;device-id&gt; should be replaced by numerical ID
994 of the audio output device as e.g. returned by the
995 <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref> command.</t>
996 <t>Possible Answers:</t>
997 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
998 Each answer line begins with the information category name
999 followed by a colon and then a space character &lt;SP&gt; and finally
1000 the info character string to that info category. As some
1001 parameters might allow multiple values, character strings are
1002 encapsulated into apostrophes ('). At the moment the following
1003 information categories are defined (independently of device):</t>
1004 <t>
1005 <list>
1006 <t>DRIVER -
1007 <list>
1008 <t>identifier of the used audio output driver, as also
1009 returned by the
1010 <xref target="LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">
1011 "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"</xref>
1012 command</t>
1013 </list>
1014 </t>
1015 <t>CHANNELS -
1016 <list>
1017 <t>amount of audio output channels this device currently
1018 offers</t>
1019 </list>
1020 </t>
1021 <t>SAMPLERATE -
1022 <list>
1023 <t>playback sample rate the device uses</t>
1024 </list>
1025 </t>
1026 <t>ACTIVE -
1027 <list>
1028 <t>either true or false, if false then the audio device is
1029 inactive and doesn't output any sound, nor do the
1030 sampler channels connected to this audio device render
1031 any audio</t>
1032 </list>
1033 </t>
1034 </list>
1035 </t>
1036 <t>The mentioned fields above don't have to be in particular
1037 order. The fields above are only those fields which are
1038 returned by all audio output devices. Every audio output driver
1039 might have its own, additional driver specific parameters (see
1040 <xref target="GET AUDIO_OUTPUT_DRIVER INFO" />)
1041 which are also returned by this command.</t>
1042 <t>Example:</t>
1043 <t>
1044 <list>
1045 <t>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"</t>
1046 <t>S: "DRIVER: ALSA"</t>
1047 <t>&nbsp;&nbsp;&nbsp;"CHANNELS: 2"</t>
1048 <t>&nbsp;&nbsp;&nbsp;"SAMPLERATE: 44100"</t>
1049 <t>&nbsp;&nbsp;&nbsp;"ACTIVE: true"</t>
1050 <t>&nbsp;&nbsp;&nbsp;"FRAGMENTS: 2"</t>
1051 <t>&nbsp;&nbsp;&nbsp;"FRAGMENTSIZE: 128"</t>
1052 <t>&nbsp;&nbsp;&nbsp;"CARD: '0,0'"</t>
1053 <t>&nbsp;&nbsp;&nbsp;"."</t>
1054 </list>
1055 </t>
1056 </section>
1057
1058
1059 <section title="Changing settings of audio output devices" anchor="SET AUDIO_OUTPUT_DEVICE_PARAMETER" lscp_cmd="true">
1060 <t>Use the following command to alter a specific setting of a created audio output device:</t>
1061 <t>
1062 <list>
1063 <t>SET AUDIO_OUTPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;</t>
1064 </list>
1065 </t>
1066 <t>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1067 audio output device as given by the
1068 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
1069 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
1070 command, &lt;key&gt; by the name of the parameter to change
1071 and &lt;value&gt; by the new value for this parameter.</t>
1072 <t>Possible Answers:</t>
1073 <t>
1074 <list>
1075 <t>"OK" -
1076 <list>
1077 <t>in case setting was successfully changed</t>
1078 </list>
1079 </t>
1080 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1081 <list>
1082 <t>in case setting was changed successfully, but there are
1083 noteworthy issue(s) related, providing an appropriate
1084 warning code and warning message</t>
1085 </list>
1086 </t>
1087 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1088 <list>
1089 <t>in case it failed, providing an appropriate error code and
1090 error message</t>
1091 </list>
1092 </t>
1093 </list>
1094 </t>
1095 <t>Example:</t>
1096 <t>
1097 <list>
1098 <t>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"</t>
1099 <t>S: "OK"</t>
1100 </list>
1101 </t>
1102 </section>
1103
1104 <section title="Getting information about an audio channel" anchor="GET AUDIO_OUTPUT_CHANNEL INFO" lscp_cmd="true">
1105 <t>Use the following command to get information about an audio channel:</t>
1106 <t>
1107 <list>
1108 <t>GET AUDIO_OUTPUT_CHANNEL INFO &lt;device-id&gt; &lt;audio-chan&gt;</t>
1109 </list>
1110 </t>
1111 <t>Where &lt;device-id&gt; is the numerical ID of the audio output device as given by the
1112 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
1113 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
1114 command and &lt;audio-chan&gt; the audio channel number.</t>
1115 <t>Possible Answers:</t>
1116 <t>
1117 <list>
1118 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1119 Each answer line begins with the information category name
1120 followed by a colon and then a space character &lt;SP&gt; and finally
1121 the info character string to that info category. At the moment
1122 the following information categories are defined:</t>
1123
1124 <t>
1125 <list>
1126 <t>NAME -
1127 <list>
1128 <t>arbitrary character string naming the channel, which
1129 doesn't have to be unique (always returned by all audio channels)</t>
1130 </list>
1131 </t>
1132 <t>IS_MIX_CHANNEL -
1133 <list>
1134 <t>either true or false, a mix-channel is not a real,
1135 independent audio channel, but a virtual channel which
1136 is mixed to another real channel, this mechanism is
1137 needed for sampler engines which need more audio
1138 channels than the used audio system might be able to offer
1139 (always returned by all audio channels)</t>
1140 </list>
1141 </t>
1142 <t>MIX_CHANNEL_DESTINATION -
1143 <list>
1144 <t>numerical ID (positive integer including 0)
1145 which reflects the real audio channel (of the same audio
1146 output device) this mix channel refers to, means where
1147 the audio signal actually will be routed / added to
1148 (only returned in case the audio channel is mix channel)</t>
1149 </list>
1150 </t>
1151 </list>
1152 </t>
1153 </list>
1154 </t>
1155
1156 <t>The mentioned fields above don't have to be in particular
1157 order. The fields above are only those fields which are
1158 generally returned for the described cases by all audio
1159 channels regardless of the audio driver. Every audio channel
1160 might have its own, additional driver and channel specific
1161 parameters.</t>
1162
1163 <t>Examples:</t>
1164
1165 <t>
1166 <list>
1167 <t>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 0"</t>
1168 <t>S: "NAME: studio monitor left"</t>
1169 <t>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"</t>
1170 <t>&nbsp;&nbsp;&nbsp;"."</t>
1171 </list>
1172 </t>
1173
1174 <t>
1175 <list>
1176 <t>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 1"</t>
1177 <t>S: "NAME: studio monitor right"</t>
1178 <t>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"</t>
1179 <t>&nbsp;&nbsp;&nbsp;"."</t>
1180 </list>
1181 </t>
1182
1183 <t>
1184 <list>
1185 <t>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"</t>
1186 <t>S: "NAME: studio monitor left"</t>
1187 <t>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: true"</t>
1188 <t>&nbsp;&nbsp;&nbsp;"MIX_CHANNEL_DESTINATION: 1"</t>
1189 <t>&nbsp;&nbsp;&nbsp;"."</t>
1190 </list>
1191 </t>
1192
1193 <t>
1194 <list>
1195 <t>C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"</t>
1196 <t>S: "NAME: 'ardour (left)'"</t>
1197 <t>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"</t>
1198 <t>&nbsp;&nbsp;&nbsp;"JACK_BINDINGS: 'ardour:0'"</t>
1199 <t>&nbsp;&nbsp;&nbsp;"."</t>
1200 </list>
1201 </t>
1202 </section>
1203
1204 <section title="Getting information about specific audio channel parameter" anchor="GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO" lscp_cmd="true">
1205 <t>Use the following command to get detailed information about specific audio channel parameter:</t>
1206
1207 <t>
1208 <list>
1209 <t>GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO &lt;dev-id&gt; &lt;chan&gt; &lt;param&gt;</t>
1210 </list>
1211 </t>
1212
1213 <t>Where &lt;dev-id&gt; is the numerical ID of the audio output device as returned by the
1214 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
1215 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
1216 command, &lt;chan&gt; the audio channel number
1217 and &lt;param&gt; a specific channel parameter name for which information should
1218 be obtained (as returned by the <xref target="GET AUDIO_OUTPUT_CHANNEL INFO">
1219 "GET AUDIO_OUTPUT_CHANNEL INFO"</xref> command).</t>
1220 <t>Possible Answers:</t>
1221
1222 <t>
1223 <list>
1224 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1225 Each answer line begins with the information category name
1226 followed by a colon and then a space character &lt;SP&gt; and finally
1227 the info character string to that info category. There are
1228 information which is always returned, independently of the
1229 given channel parameter and there is optional information
1230 which is only shown dependently to the given audio channel. At
1231 the moment the following information categories are defined:</t>
1232 <t>
1233 <list>
1234 <t>TYPE -
1235 <list>
1236 <t>either "BOOL" for boolean value(s) or "INT" for integer
1237 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1238 character string(s)
1239 (always returned)</t>
1240 </list>
1241 </t>
1242 <t>DESCRIPTION -
1243 <list>
1244 <t>arbitrary text describing the purpose of the parameter (always returned)</t>
1245 </list>
1246 </t>
1247 <t>FIX -
1248 <list>
1249 <t>either true or false, if true then this parameter is
1250 read only, thus cannot be altered
1251 (always returned)</t>
1252 </list>
1253 </t>
1254 <t>MULTIPLICITY -
1255 <list>
1256 <t>either true or false, defines if this parameter allows
1257 only one value or a list of values, where true means
1258 multiple values and false only a single value allowed
1259 (always returned)</t>
1260 </list>
1261 </t>
1262 <t>RANGE_MIN -
1263 <list>
1264 <t>defines lower limit of the allowed value range for this
1265 parameter, can be an integer value as well as a dotted
1266 number, usually used in conjunction with 'RANGE_MAX',
1267 but may also appear without
1268 (optionally returned, dependent to driver and channel
1269 parameter)</t>
1270 </list>
1271 </t>
1272 <t>RANGE_MAX -
1273 <list>
1274 <t>defines upper limit of the allowed value range for this
1275 parameter, can be an integer value as well as a dotted
1276 number, usually used in conjunction with 'RANGE_MIN',
1277 but may also appear without
1278 (optionally returned, dependent to driver and channel
1279 parameter)</t>
1280 </list>
1281 </t>
1282 <t>POSSIBILITIES -
1283 <list>
1284 <t>comma separated list of possible values for this
1285 parameter, character strings are encapsulated into
1286 apostrophes
1287 (optionally returned, dependent to driver and channel
1288 parameter)</t>
1289 </list>
1290 </t>
1291 </list>
1292 </t>
1293 <t>The mentioned fields above don't have to be in particular order.</t>
1294 </list>
1295 </t>
1296 <t>Example:</t>
1297 <t>
1298 <list>
1299 <t>C: "GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO 1 0 JACK_BINDINGS"</t>
1300 <t>S: "DESCRIPTION: bindings to other JACK clients"</t>
1301 <t>&nbsp;&nbsp;&nbsp;"TYPE: STRING"</t>
1302 <t>&nbsp;&nbsp;&nbsp;"FIX: false"</t>
1303 <t>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"</t>
1304 <t>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"</t>
1305 <t>&nbsp;&nbsp;&nbsp;"."</t>
1306 </list>
1307 </t>
1308 </section>
1309
1310 <section title="Changing settings of audio output channels" anchor="SET AUDIO_OUTPUT_CHANNEL_PARAMETER" lscp_cmd="true">
1311 <t>Use the following command to alter a specific setting of an audio output channel:</t>
1312 <t>
1313 <list>
1314 <t>SET AUDIO_OUTPUT_CHANNEL_PARAMETER &lt;dev-id&gt; &lt;chn&gt; &lt;key&gt;=&lt;value&gt;</t>
1315 </list>
1316 </t>
1317 <t>Where &lt;dev-id&gt; should be replaced by the numerical ID of the audio output device as returned by the
1318 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
1319 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
1320 command, &lt;chn&gt; by the audio channel number, &lt;key&gt; by the name of the
1321 parameter to change and &lt;value&gt; by the new value for this parameter.</t>
1322 <t>Possible Answers:</t>
1323 <t>
1324 <list>
1325 <t>"OK" -
1326 <list>
1327 <t>in case setting was successfully changed</t>
1328 </list>
1329 </t>
1330 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1331 <list>
1332 <t>in case setting was changed successfully, but there are
1333 noteworthy issue(s) related, providing an appropriate
1334 warning code and warning message</t>
1335 </list>
1336 </t>
1337 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1338 <list>
1339 <t>in case it failed, providing an appropriate error code and
1340 error message</t>
1341 </list>
1342 </t>
1343 </list>
1344 </t>
1345 <t>Example:</t>
1346 <t>
1347 <list>
1348 <t>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"</t>
1349 <t>S: "OK"</t>
1350 </list>
1351 </t>
1352 <t>
1353 <list>
1354 <t>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"</t>
1355 <t>S: "OK"</t>
1356 </list>
1357 </t>
1358 </section>
1359 </section>
1360
1361 <section title="Configuring MIDI input drivers">
1362 <t>Instances of drivers in LinuxSampler are called devices. You can use
1363 multiple MIDI devices simultaneously, e.g. to use MIDI over ethernet as
1364 MIDI input on one sampler channel and ALSA as MIDI input on another sampler
1365 channel. For particular MIDI input systems it's also possible to create
1366 several devices of the same MIDI input type. This chapter describes all
1367 commands to configure LinuxSampler's MIDI input devices and their parameters.</t>
1368
1369 <t>Instead of defining commands and parameters for each driver individually,
1370 all possible parameters, their meanings and possible values have to be obtained
1371 at runtime. This makes the protocol a bit abstract, but has the advantage, that
1372 front-ends can be written independently of what drivers are currently implemented
1373 and what parameters these drivers are actually offering. This means front-ends can
1374 even handle drivers which are implemented somewhere in future without modifying
1375 the front-end at all.</t>
1376
1377 <t>Commands for configuring MIDI input devices are pretty much the same as the
1378 commands for configuring audio output drivers, already described in the last
1379 chapter.</t>
1380
1381 <t>Note: examples in this chapter showing particular parameters of drivers are
1382 not meant as specification of the drivers' parameters. Driver implementations in
1383 LinuxSampler might have complete different parameter names and meanings than shown
1384 in these examples or might change in future, so these examples are only meant for
1385 showing how to retrieve what parameters drivers are offering, how to retrieve their
1386 possible values, etc.</t>
1387
1388 <section title="Getting amount of available MIDI input drivers" anchor="GET AVAILABLE_MIDI_INPUT_DRIVERS" lscp_cmd="true">
1389 <t>Use the following command to get the number of
1390 MIDI input drivers currently available for the
1391 LinuxSampler instance:</t>
1392 <t>
1393 <list>
1394 <t>GET AVAILABLE_MIDI_INPUT_DRIVERS</t>
1395 </list>
1396 </t>
1397 <t>Possible Answers:</t>
1398 <t>
1399 <list>
1400 <t>LinuxSampler will answer by sending the
1401 number of available MIDI input drivers.</t>
1402 </list>
1403 </t>
1404 <t>Example:</t>
1405 <t>
1406 <list>
1407 <t>C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"</t>
1408 <t>S: "2"</t>
1409 </list>
1410 </t>
1411 </section>
1412
1413 <section title="Getting all available MIDI input drivers" anchor="LIST AVAILABLE_MIDI_INPUT_DRIVERS" lscp_cmd="true">
1414 <t>Use the following command to list all MIDI input drivers currently available
1415 for the LinuxSampler instance:</t>
1416 <t>
1417 <list>
1418 <t>LIST AVAILABLE_MIDI_INPUT_DRIVERS</t>
1419 </list>
1420 </t>
1421 <t>Possible Answers:</t>
1422 <t>
1423 <list>
1424 <t>LinuxSampler will answer by sending comma separated character
1425 strings, each symbolizing a MIDI input driver.</t>
1426 </list>
1427 </t>
1428 <t>Example:</t>
1429 <t>
1430 <list>
1431 <t>C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"</t>
1432 <t>S: "ALSA,JACK"</t>
1433 </list>
1434 </t>
1435 </section>
1436
1437 <section title="Getting information about a specific MIDI input driver" anchor="GET MIDI_INPUT_DRIVER INFO" lscp_cmd="true">
1438 <t>Use the following command to get detailed information about a specific MIDI input driver:</t>
1439 <t>
1440 <list>
1441 <t>GET MIDI_INPUT_DRIVER INFO &lt;midi-input-driver&gt;</t>
1442 </list>
1443 </t>
1444 <t>Where &lt;midi-input-driver&gt; is the name of the MIDI input driver as returned
1445 by the <xref target="LIST AVAILABLE_MIDI_INPUT_DRIVERS">
1446 "LIST AVAILABLE_MIDI_INPUT_DRIVERS"</xref> command.</t>
1447 <t>Possible Answers:</t>
1448 <t>
1449 <list>
1450 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1451 Each answer line begins with the information category name
1452 followed by a colon and then a space character &lt;SP&gt; and finally
1453 the info character string to that info category. At the moment
1454 the following information categories are defined:</t>
1455
1456 <t>
1457 <list>
1458 <t>DESCRIPTION -
1459 <list>
1460 <t>arbitrary description text about the MIDI input driver</t>
1461 </list>
1462 </t>
1463 <t>VERSION -
1464 <list>
1465 <t>arbitrary character string regarding the driver's version</t>
1466 </list>
1467 </t>
1468 <t>PARAMETERS -
1469 <list>
1470 <t>comma separated list of all parameters available for the given MIDI input driver</t>
1471 </list>
1472 </t>
1473 </list>
1474 </t>
1475
1476 <t>The mentioned fields above don't have to be in particular order.</t>
1477 </list>
1478 </t>
1479
1480 <t>Example:</t>
1481
1482 <t>
1483 <list>
1484 <t>C: "GET MIDI_INPUT_DRIVER INFO ALSA"</t>
1485 <t>S: "DESCRIPTION: Advanced Linux Sound Architecture"</t>
1486 <t>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"</t>
1487 <t>&nbsp;&nbsp;&nbsp;"PARAMETERS: DRIVER,ACTIVE"</t>
1488 <t>&nbsp;&nbsp;&nbsp;"."</t>
1489 </list>
1490 </t>
1491 </section>
1492
1493 <section title="Getting information about specific MIDI input driver parameter" anchor="GET MIDI_INPUT_DRIVER_PARAMETER INFO" lscp_cmd="true">
1494 <t>Use the following command to get detailed information about a specific parameter of a specific MIDI input driver:</t>
1495 <t>
1496 <list>
1497 <t>GET MIDI_INPUT_DRIVER_PARAMETER INFO &lt;midit&gt; &lt;param&gt; [&lt;deplist&gt;]</t>
1498 </list>
1499 </t>
1500
1501 <t>Where &lt;midit&gt; is the name of the MIDI input driver as returned
1502 by the <xref target="LIST AVAILABLE_MIDI_INPUT_DRIVERS">
1503 "LIST AVAILABLE_MIDI_INPUT_DRIVERS"</xref> command, &lt;param&gt; a specific
1504 parameter name for which information should be obtained (as returned by the
1505 <xref target="GET MIDI_INPUT_DRIVER INFO">
1506 "GET MIDI_INPUT_DRIVER INFO"</xref> command) and &lt;deplist&gt; is an optional list
1507 of parameters on which the sought parameter &lt;param&gt; depends on,
1508 &lt;deplist&gt; is a key-value pair list in form of "key1=val1 key2=val2 ...",
1509 where character string values are encapsulated into apostrophes ('). Arguments
1510 given with &lt;deplist&gt; which are not dependency parameters of &lt;param&gt;
1511 will be ignored, means the front-end application can simply put all parameters
1512 in &lt;deplist&gt; with the values selected by the user.</t>
1513
1514 <t>Possible Answers:</t>
1515
1516 <t>LinuxSampler will answer by sending a &lt;CRLF> separated list.
1517 Each answer line begins with the information category name
1518 followed by a colon and then a space character &lt;SP> and finally
1519 the info character string to that info category. There is
1520 information which is always returned, independent of the
1521 given driver parameter and there is optional information
1522 which is only shown dependent to given driver parameter. At
1523 the moment the following information categories are defined:</t>
1524
1525 <t>
1526 <list>
1527 <t>TYPE -
1528 <list>
1529 <t>either "BOOL" for boolean value(s) or "INT" for integer
1530 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1531 character string(s)
1532 (always returned, no matter which driver parameter)</t>
1533 </list>
1534 </t>
1535
1536 <t>DESCRIPTION -
1537 <list>
1538 <t>arbitrary text describing the purpose of the parameter
1539 (always returned, no matter which driver parameter)</t>
1540 </list>
1541 </t>
1542
1543 <t>MANDATORY -
1544 <list>
1545 <t>either true or false, defines if this parameter must be
1546 given when the device is to be created with the
1547 <xref target="CREATE MIDI_INPUT_DEVICE">
1548 'CREATE MIDI_INPUT_DEVICE'</xref> command
1549 (always returned, no matter which driver parameter)</t>
1550 </list>
1551 </t>
1552
1553 <t>FIX -
1554 <list>
1555 <t>either true or false, if false then this parameter can
1556 be changed at any time, once the device is created by
1557 the <xref target="CREATE MIDI_INPUT_DEVICE">
1558 'CREATE MIDI_INPUT_DEVICE'</xref> command
1559 (always returned, no matter which driver parameter)</t>
1560 </list>
1561 </t>
1562
1563 <t>MULTIPLICITY -
1564 <list>
1565 <t>either true or false, defines if this parameter allows
1566 only one value or a list of values, where true means
1567 multiple values and false only a single value allowed
1568 (always returned, no matter which driver parameter)</t>
1569 </list>
1570 </t>
1571
1572 <t>DEPENDS -
1573 <list>
1574 <t>comma separated list of parameters this parameter depends
1575 on, means the values for fields 'DEFAULT', 'RANGE_MIN',
1576 'RANGE_MAX' and 'POSSIBILITIES' might depend on these
1577 listed parameters, for example assuming that an audio
1578 driver (like the ALSA driver) offers parameters 'card'
1579 and 'samplerate' then parameter 'samplerate' would
1580 depend on 'card' because the possible values for
1581 'samplerate' depends on the sound card which can be
1582 chosen by the 'card' parameter
1583 (optionally returned, dependent to driver parameter)</t>
1584 </list>
1585 </t>
1586
1587 <t>DEFAULT -
1588 <list>
1589 <t>reflects the default value for this parameter which is
1590 used when the device is created and not explicitly
1591 given with the <xref target="CREATE MIDI_INPUT_DEVICE">
1592 'CREATE MIDI_INPUT_DEVICE'</xref> command,
1593 in case of MULTIPLCITY=true, this is a comma separated
1594 list, that's why character strings are encapsulated into
1595 apostrophes (')
1596 (optionally returned, dependent to driver parameter)</t>
1597 </list>
1598 </t>
1599
1600 <t>RANGE_MIN -
1601 <list>
1602 <t>defines lower limit of the allowed value range for this
1603 parameter, can be an integer value as well as a dotted
1604 number, this parameter is often used in conjunction
1605 with RANGE_MAX, but may also appear without
1606 (optionally returned, dependent to driver parameter)</t>
1607 </list>
1608 </t>
1609
1610 <t>RANGE_MAX -
1611 <list>
1612 <t>defines upper limit of the allowed value range for this
1613 parameter, can be an integer value as well as a dotted
1614 number, this parameter is often used in conjunction with
1615 RANGE_MIN, but may also appear without
1616 (optionally returned, dependent to driver parameter)</t>
1617 </list>
1618 </t>
1619
1620 <t>POSSIBILITIES -
1621 <list>
1622 <t>comma separated list of possible values for this
1623 parameter, character strings are encapsulated into
1624 apostrophes
1625 (optionally returned, dependent to driver parameter)</t>
1626 </list>
1627 </t>
1628 </list>
1629 </t>
1630
1631 <t>The mentioned fields above don't have to be in particular order.</t>
1632
1633 <t>Example:</t>
1634 <t>
1635 <list>
1636 <t>C: "GET MIDI_INPUT_DRIVER_PARAMETER INFO ALSA ACTIVE"</t>
1637 <t>S: "DESCRIPTION: Whether device is enabled"</t>
1638 <t>&nbsp;&nbsp;&nbsp;"TYPE: BOOL"</t>
1639 <t>&nbsp;&nbsp;&nbsp;"MANDATORY: false"</t>
1640 <t>&nbsp;&nbsp;&nbsp;"FIX: false"</t>
1641 <t>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"</t>
1642 <t>&nbsp;&nbsp;&nbsp;"DEFAULT: true"</t>
1643 <t>&nbsp;&nbsp;&nbsp;"."</t>
1644 </list>
1645 </t>
1646 </section>
1647
1648 <section title="Creating a MIDI input device" anchor="CREATE MIDI_INPUT_DEVICE" lscp_cmd="true">
1649 <t>Use the following command to create a new MIDI input device for the desired MIDI input system:</t>
1650 <t>
1651 <list>
1652 <t>CREATE MIDI_INPUT_DEVICE &lt;midi-input-driver&gt; [&lt;param-list&gt;]</t>
1653 </list>
1654 </t>
1655
1656 <t>Where &lt;midi-input-driver&gt; should be replaced by the desired MIDI input system as returned
1657 by the <xref target="LIST AVAILABLE_MIDI_INPUT_DRIVERS">
1658 "LIST AVAILABLE_MIDI_INPUT_DRIVERS"</xref> command and &lt;param-list&gt; by an
1659 optional list of driver specific parameters in form of "key1=val1 key2=val2 ...", where
1660 character string values should be encapsulated into apostrophes (').
1661 Note that there might be drivers which require parameter(s) to be
1662 given with this command. Use the previously described commands in
1663 this chapter to get that information.</t>
1664
1665 <t>Possible Answers:</t>
1666 <t>
1667 <list>
1668 <t>"OK[&lt;device-id&gt;]" -
1669 <list>
1670 <t>in case the device was successfully created, where
1671 &lt;device-id&gt; is the numerical ID of the new device</t>
1672 </list>
1673 </t>
1674 <t>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1675 <list>
1676 <t>in case the driver was loaded successfully, where
1677 &lt;device-id&gt; is the numerical ID of the new device, but
1678 there are noteworthy issue(s) related, providing an
1679 appropriate warning code and warning message</t>
1680 </list>
1681 </t>
1682 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1683 <list>
1684 <t>in case it failed, providing an appropriate error code and error message</t>
1685 </list>
1686 </t>
1687 </list>
1688 </t>
1689 <t>Example:</t>
1690 <t>
1691 <list>
1692 <t>C: "CREATE MIDI_INPUT_DEVICE ALSA"</t>
1693 <t>S: "OK[0]"</t>
1694 </list>
1695 </t>
1696 </section>
1697
1698 <section title="Destroying a MIDI input device" anchor="DESTROY MIDI_INPUT_DEVICE" lscp_cmd="true">
1699 <t>Use the following command to destroy a created MIDI input device:</t>
1700 <t>
1701 <list>
1702 <t>DESTROY MIDI_INPUT_DEVICE &lt;device-id&gt;</t>
1703 </list>
1704 </t>
1705 <t>Where &lt;device-id&gt; should be replaced by the device's numerical ID as returned by the
1706 <xref target="CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</xref>
1707 or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
1708 command.</t>
1709 <t>Possible Answers:</t>
1710 <t>
1711 <list>
1712 <t>"OK" -
1713 <list>
1714 <t>in case the device was successfully destroyed</t>
1715 </list>
1716 </t>
1717 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1718 <list>
1719 <t>in case the device was destroyed, but there are noteworthy
1720 issue(s) related, providing an appropriate warning code and
1721 warning message</t>
1722 </list>
1723 </t>
1724 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1725 <list>
1726 <t>in case it failed, providing an appropriate error code and error message</t>
1727 </list>
1728 </t>
1729 </list>
1730 </t>
1731 <t>Example:</t>
1732 <t>
1733 <list>
1734 <t>C: "DESTROY MIDI_INPUT_DEVICE 0"</t>
1735 <t>S: "OK"</t>
1736 </list>
1737 </t>
1738 </section>
1739
1740 <section title="Getting all created MIDI input device count" anchor="GET MIDI_INPUT_DEVICES" lscp_cmd="true">
1741 <t>Use the following command to count all created MIDI input devices:</t>
1742 <t>
1743 <list>
1744 <t>GET MIDI_INPUT_DEVICES</t>
1745 </list>
1746 </t>
1747 <t>Possible Answers:</t>
1748 <t>
1749 <list>
1750 <t>LinuxSampler will answer by sending the current number of all
1751 MIDI input devices.</t>
1752 </list>
1753 </t>
1754 <t>Example:</t>
1755 <t>
1756 <list>
1757 <t>C: "GET MIDI_INPUT_DEVICES"</t>
1758 <t>S: "3"</t>
1759 </list>
1760 </t>
1761 </section>
1762
1763
1764 <section title="Getting all created MIDI input device list" anchor="LIST MIDI_INPUT_DEVICES" lscp_cmd="true">
1765 <t>Use the following command to list all created MIDI input devices:</t>
1766 <t>
1767 <list>
1768 <t>LIST MIDI_INPUT_DEVICES</t>
1769 </list>
1770 </t>
1771 <t>Possible Answers:</t>
1772 <t>
1773 <list>
1774 <t>LinuxSampler will answer by sending a comma separated list
1775 with the numerical Ids of all created MIDI input devices.</t>
1776 </list>
1777 </t>
1778 <t>Examples:</t>
1779 <t>
1780 <list>
1781 <t>C: "LIST MIDI_INPUT_DEVICES"</t>
1782 <t>S: "0,1,2"</t>
1783 </list>
1784 </t>
1785 <t>
1786 <list>
1787 <t>C: "LIST MIDI_INPUT_DEVICES"</t>
1788 <t>S: "1,3"</t>
1789 </list>
1790 </t>
1791 </section>
1792
1793 <section title="Getting current settings of a MIDI input device" anchor="GET MIDI_INPUT_DEVICE INFO" lscp_cmd="true">
1794 <t>Use the following command to get current settings of a specific, created MIDI input device:</t>
1795 <t>
1796 <list>
1797 <t>GET MIDI_INPUT_DEVICE INFO &lt;device-id&gt;</t>
1798 </list>
1799 </t>
1800 <t>Where &lt;device-id&gt; is the numerical ID of the MIDI input device as returned by the
1801 <xref target="CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</xref>
1802 or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
1803 command.</t>
1804 <t>Possible Answers:</t>
1805 <t>
1806 <list>
1807 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1808 Each answer line begins with the information category name
1809 followed by a colon and then a space character &lt;SP&gt; and finally
1810 the info character string to that info category. As some
1811 parameters might allow multiple values, character strings are
1812 encapsulated into apostrophes ('). At the moment the following
1813 information categories are defined (independent of driver):</t>
1814
1815 <t>
1816 <list>
1817 <t>DRIVER -
1818 <list>
1819 <t>identifier of the used MIDI input driver, as e.g.
1820 returned by the <xref target="LIST AVAILABLE_MIDI_INPUT_DRIVERS">
1821 "LIST AVAILABLE_MIDI_INPUT_DRIVERS"</xref>
1822 command</t>
1823 </list>
1824 </t>
1825 </list>
1826 <list>
1827 <t>ACTIVE -
1828 <list>
1829 <t>either true or false, if false then the MIDI device is
1830 inactive and doesn't listen to any incoming MIDI events
1831 and thus doesn't forward them to connected sampler
1832 channels</t>
1833 </list>
1834 </t>
1835 </list>
1836 </t>
1837 </list>
1838 </t>
1839
1840 <t>The mentioned fields above don't have to be in particular
1841 order. The fields above are only those fields which are
1842 returned by all MIDI input devices. Every MIDI input driver
1843 might have its own, additional driver specific parameters (see
1844 <xref target="GET MIDI_INPUT_DRIVER INFO">
1845 "GET MIDI_INPUT_DRIVER INFO"</xref> command) which are also returned
1846 by this command.</t>
1847
1848 <t>Example:</t>
1849 <t>
1850 <list>
1851 <t>C: "GET MIDI_INPUT_DEVICE INFO 0"</t>
1852 <t>S: "DRIVER: ALSA"</t>
1853 <t>&nbsp;&nbsp;&nbsp;"ACTIVE: true"</t>
1854 <t>&nbsp;&nbsp;&nbsp;"."</t>
1855 </list>
1856 </t>
1857 </section>
1858
1859 <section title="Changing settings of MIDI input devices" anchor="SET MIDI_INPUT_DEVICE_PARAMETER" lscp_cmd="true">
1860 <t>Use the following command to alter a specific setting of a created MIDI input device:</t>
1861 <t>
1862 <list>
1863 <t>SET MIDI_INPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;</t>
1864 </list>
1865 </t>
1866
1867 <t>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1868 MIDI input device as returned by the
1869 <xref target="CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</xref>
1870 or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
1871 command, &lt;key&gt; by the name of the parameter to change and
1872 &lt;value&gt; by the new value for this parameter.</t>
1873
1874 <t>Possible Answers:</t>
1875 <t>
1876 <list>
1877 <t>"OK" -
1878 <list>
1879 <t>in case setting was successfully changed</t>
1880 </list>
1881 </t>
1882 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1883 <list>
1884 <t>in case setting was changed successfully, but there are
1885 noteworthy issue(s) related, providing an appropriate
1886 warning code and warning message</t>
1887 </list>
1888 </t>
1889 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1890 <list>
1891 <t>in case it failed, providing an appropriate error code and error message</t>
1892 </list>
1893 </t>
1894 </list>
1895 </t>
1896 <t>Example:</t>
1897 <t>
1898 <list>
1899 <t>C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"</t>
1900 <t>S: "OK"</t>
1901 </list>
1902 </t>
1903 </section>
1904
1905 <section title="Getting information about a MIDI port" anchor="GET MIDI_INPUT_PORT INFO" lscp_cmd="true">
1906 <t>Use the following command to get information about a MIDI port:</t>
1907 <t>
1908 <list>
1909 <t>GET MIDI_INPUT_PORT INFO &lt;device-id&gt; &lt;midi-port&gt;</t>
1910 </list>
1911 </t>
1912 <t>Where &lt;device-id&gt; is the numerical ID of the MIDI input device as returned by the
1913 <xref target="CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</xref>
1914 or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
1915 command and &lt;midi-port&gt; the MIDI input port number.</t>
1916 <t>Possible Answers:</t>
1917 <t>
1918 <list>
1919 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1920 Each answer line begins with the information category name
1921 followed by a colon and then a space character &lt;SP&gt; and finally
1922 the info character string to that info category. At the moment
1923 the following information categories are defined:</t>
1924
1925 <t>NAME -
1926 <list>
1927 <t>arbitrary character string naming the port</t>
1928 </list>
1929 </t>
1930 </list>
1931 </t>
1932
1933 <t>The field above is only the one which is returned by all MIDI
1934 ports regardless of the MIDI driver and port. Every MIDI port
1935 might have its own, additional driver and port specific
1936 parameters.</t>
1937
1938 <t>Example:</t>
1939 <t>
1940 <list>
1941 <t>C: "GET MIDI_INPUT_PORT INFO 0 0"</t>
1942 <t>S: "NAME: 'Masterkeyboard'"</t>
1943 <t>&nbsp;&nbsp;&nbsp;"ALSA_SEQ_BINDINGS: '64:0'"</t>
1944 <t>&nbsp;&nbsp;&nbsp;"."</t>
1945 </list>
1946 </t>
1947 </section>
1948
1949 <section title="Getting information about specific MIDI port parameter" anchor="GET MIDI_INPUT_PORT_PARAMETER INFO" lscp_cmd="true">
1950 <t>Use the following command to get detailed information about specific MIDI port parameter:</t>
1951 <t>
1952 <list>
1953 <t>GET MIDI_INPUT_PORT_PARAMETER INFO &lt;dev-id&gt; &lt;port&gt; &lt;param&gt;</t>
1954 </list>
1955 </t>
1956
1957 <t>Where &lt;dev-id&gt; is the numerical ID of the MIDI input device as returned by the
1958 <xref target="CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</xref>
1959 or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
1960 command, &lt;port&gt; the MIDI port number and
1961 &lt;param&gt; a specific port parameter name for which information should be
1962 obtained (as returned by the <xref target="GET MIDI_INPUT_PORT INFO">
1963 "GET MIDI_INPUT_PORT INFO"</xref> command).</t>
1964
1965 <t>Possible Answers:</t>
1966 <t>
1967 <list>
1968 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1969 Each answer line begins with the information category name
1970 followed by a colon and then a space character &lt;SP&gt; and finally
1971 the info character string to that info category. There is
1972 information which is always returned, independently of the
1973 given channel parameter and there is optional information
1974 which are only shown dependently to the given MIDI port. At the
1975 moment the following information categories are defined:</t>
1976
1977 <t>TYPE -
1978 <list>
1979 <t>either "BOOL" for boolean value(s) or "INT" for integer
1980 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1981 character string(s)
1982 (always returned)</t>
1983 </list>
1984 </t>
1985 <t>DESCRIPTION -
1986 <list>
1987 <t>arbitrary text describing the purpose of the parameter
1988 (always returned)</t>
1989 </list>
1990 </t>
1991 <t>FIX -
1992 <list>
1993 <t>either true or false, if true then this parameter is
1994 read only, thus cannot be altered
1995 (always returned)</t>
1996 </list>
1997 </t>
1998 <t>MULTIPLICITY -
1999 <list>
2000 <t>either true or false, defines if this parameter allows
2001 only one value or a list of values, where true means
2002 multiple values and false only a single value allowed
2003 (always returned)</t>
2004 </list>
2005 </t>
2006 <t>RANGE_MIN -
2007 <list>
2008 <t>defines lower limit of the allowed value range for this
2009 parameter, can be an integer value as well as a dotted
2010 number, this parameter is usually used in conjunction
2011 with 'RANGE_MAX' but may also appear without
2012 (optionally returned, dependent to driver and port
2013 parameter)</t>
2014 </list>
2015 </t>
2016 <t>RANGE_MAX -
2017 <list>
2018 <t>defines upper limit of the allowed value range for this
2019 parameter, can be an integer value as well as a dotted
2020 number, this parameter is usually used in conjunction
2021 with 'RANGE_MIN' but may also appear without
2022 (optionally returned, dependent to driver and port
2023 parameter)</t>
2024 </list>
2025 </t>
2026 <t>POSSIBILITIES -
2027 <list>
2028 <t>comma separated list of possible values for this
2029 parameter, character strings are encapsulated into
2030 apostrophes
2031 (optionally returned, dependent to device and port
2032 parameter)</t>
2033 </list>
2034 </t>
2035 </list>
2036 </t>
2037
2038 <t>The mentioned fields above don't have to be in particular order.</t>
2039
2040 <t>Example:</t>
2041 <t>
2042 <list>
2043 <t>C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"</t>
2044 <t>S: "DESCRIPTION: bindings to other ALSA sequencer clients"</t>
2045 <t>&nbsp;&nbsp;&nbsp;"TYPE: STRING"</t>
2046 <t>&nbsp;&nbsp;&nbsp;"FIX: false"</t>
2047 <t>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"</t>
2048 <t>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: '64:0','68:0','68:1'"</t>
2049 <t>&nbsp;&nbsp;&nbsp;"."</t>
2050 </list>
2051 </t>
2052 </section>
2053
2054 <section title="Changing settings of MIDI input ports" anchor="SET MIDI_INPUT_PORT_PARAMETER" lscp_cmd="true">
2055 <t>Use the following command to alter a specific setting of a MIDI input port:</t>
2056 <t>
2057 <list>
2058 <t>SET MIDI_INPUT_PORT_PARAMETER &lt;device-id&gt; &lt;port&gt; &lt;key&gt;=&lt;value&gt;</t>
2059 </list>
2060 </t>
2061
2062 <t>Where &lt;device-id&gt; should be replaced by the numerical ID of the
2063 MIDI device as returned by the
2064 <xref target="CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</xref>
2065 or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
2066 command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of
2067 the parameter to change and &lt;value&gt; by the new value for this
2068 parameter (encapsulated into apostrophes) or NONE (not encapsulated into apostrophes)
2069 for specifying no value for parameters allowing a list of values.</t>
2070
2071 <t>Possible Answers:</t>
2072 <t>
2073 <list>
2074 <t>"OK" -
2075 <list>
2076 <t>in case setting was successfully changed</t>
2077 </list>
2078 </t>
2079 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2080 <list>
2081 <t>in case setting was changed successfully, but there are
2082 noteworthy issue(s) related, providing an appropriate
2083 warning code and warning message</t>
2084 </list>
2085 </t>
2086 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2087 <list>
2088 <t>in case it failed, providing an appropriate error code and error message</t>
2089 </list>
2090 </t>
2091 </list>
2092 </t>
2093 <t>Example:</t>
2094 <t>
2095 <list>
2096 <t>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='20:0'"</t>
2097 <t>S: "OK"</t>
2098 </list>
2099 </t>
2100 <t>
2101 <list>
2102 <t>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE"</t>
2103 <t>S: "OK"</t>
2104 </list>
2105 </t>
2106 </section>
2107 </section>
2108
2109 <section title="Configuring sampler channels">
2110 <t>The following commands describe how to add and remove sampler channels, associate a
2111 sampler channel with a sampler engine, load instruments and connect sampler channels to
2112 MIDI and audio devices.</t>
2113
2114 <section title="Loading an instrument" anchor="LOAD INSTRUMENT" lscp_cmd="true">
2115 <t>An instrument file can be loaded and assigned to a sampler channel by one of the following commands:</t>
2116 <t>
2117 <list>
2118 <t>LOAD INSTRUMENT [NON_MODAL] '&lt;filename&gt;' &lt;instr-index&gt; &lt;sampler-channel&gt;</t>
2119 </list>
2120 </t>
2121
2122 <t>Where &lt;filename&gt; is the name of the instrument file on the
2123 LinuxSampler instance's host system, &lt;instr-index&gt; the index of the
2124 instrument in the instrument file and &lt;sampler-channel> is the
2125 number of the sampler channel the instrument should be assigned to.
2126 Each sampler channel can only have one instrument.</t>
2127
2128 <t>Notice: since LSCP 1.2 the &lt;filename&gt; argument supports
2129 escape characters for special characters (see chapter
2130 "<xref target="character_set">Character Set and Escape Sequences</xref>"
2131 for details) and accordingly backslash characters in the filename
2132 MUST now be escaped as well!</t>
2133
2134 <t>The difference between regular and NON_MODAL versions of the command
2135 is that the regular command returns OK only after the instrument has been
2136 fully loaded and the channel is ready to be used while NON_MODAL version
2137 returns immediately and a background process is launched to load the instrument
2138 on the channel. The <xref target="GET CHANNEL INFO">GET CHANNEL INFO</xref>
2139 command can be used to obtain loading
2140 progress from INSTRUMENT_STATUS field. LOAD command will perform sanity checks
2141 such as making sure that the file could be read and it is of a proper format
2142 and SHOULD return ERR and SHOULD not launch the background process should any
2143 errors be detected at that point.</t>
2144
2145 <t>Possible Answers:</t>
2146 <t>
2147 <list>
2148 <t>"OK" -
2149 <list>
2150 <t>in case the instrument was successfully loaded</t>
2151 </list>
2152 </t>
2153 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2154 <list>
2155 <t>in case the instrument was loaded successfully, but there
2156 are noteworthy issue(s) related (e.g. Engine doesn't support
2157 one or more patch parameters provided by the loaded
2158 instrument file), providing an appropriate warning code and
2159 warning message</t>
2160 </list>
2161 </t>
2162 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2163 <list>
2164 <t>in case it failed, providing an appropriate error code and error message</t>
2165 </list>
2166 </t>
2167 </list>
2168 </t>
2169 <t>Example (Unix):</t>
2170 <t>
2171 <list>
2172 <t>C: LOAD INSTRUMENT '/home/joe/gigs/cello.gig' 0 0</t>
2173 <t>S: OK</t>
2174 </list>
2175 </t>
2176 <t>Example (Windows):</t>
2177 <t>
2178 <list>
2179 <t>C: LOAD INSTRUMENT 'D:/MySounds/cello.gig' 0 0</t>
2180 <t>S: OK</t>
2181 </list>
2182 </t>
2183 </section>
2184
2185 <section title="Loading a sampler engine" anchor="LOAD ENGINE">
2186 <t>A sampler engine type can be associated to a specific sampler
2187 channel by the following command:</t>
2188 <t>
2189 <list>
2190 <t>LOAD ENGINE &lt;engine-name&gt; &lt;sampler-channel&gt;</t>
2191 </list>
2192 </t>
2193
2194 <t>Where &lt;engine-name&gt; is an engine name as obtained by the
2195 <xref target="LIST AVAILABLE_ENGINES">
2196 "LIST AVAILABLE_ENGINES"</xref> command and &lt;sampler-channel&gt;
2197 the sampler channel as returned by the
2198 <xref target="ADD CHANNEL">"ADD CHANNEL"</xref> or
2199 <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command where
2200 the engine type should be assigned to. This command should be issued
2201 after adding a new sampler channel and before any other control
2202 commands on the new sampler channel. It can also be used to change
2203 the engine type of a sampler channel. This command has (currently) no
2204 way to define or force if a new engine instance should be created and
2205 assigned to the given sampler channel or if an already existing
2206 instance of that engine type, shared with other sampler channels,
2207 should be used.</t>
2208
2209 <t>Possible Answers:</t>
2210 <t>
2211 <list>
2212 <t>"OK" -
2213 <list>
2214 <t>in case the engine was successfully deployed</t>
2215 </list>
2216 </t>
2217 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2218 <list>
2219 <t>in case the engine was deployed successfully, but there
2220 are noteworthy issue(s) related, providing an appropriate
2221 warning code and warning message</t>
2222 </list>
2223 </t>
2224 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2225 <list>
2226 <t>in case it failed, providing an appropriate error code and
2227 error message</t>
2228 </list>
2229 </t>
2230 </list>
2231 </t>
2232 <t>Example:</t>
2233 <t>
2234 <list>
2235 <t></t>
2236 </list>
2237 </t>
2238 </section>
2239
2240 <section title="Getting all created sampler channel count" anchor="GET CHANNELS" lscp_cmd="true">
2241 <t>The number of sampler channels can change on runtime. To get the
2242 current amount of sampler channels, the front-end can send the
2243 following command:</t>
2244 <t>
2245 <list>
2246 <t>GET CHANNELS</t>
2247 </list>
2248 </t>
2249 <t>Possible Answers:</t>
2250 <t>
2251 <list>
2252 <t>LinuxSampler will answer by returning the current number of sampler channels.</t>
2253 </list>
2254 </t>
2255 <t>Example:</t>
2256 <t>
2257 <list>
2258 <t>C: "GET CHANNELS"</t>
2259 <t>S: "12"</t>
2260 </list>
2261 </t>
2262 </section>
2263
2264 <section title="Getting all created sampler channel list" anchor="LIST CHANNELS" lscp_cmd="true">
2265 <t>The number of sampler channels can change on runtime. To get the
2266 current list of sampler channels, the front-end can send the
2267 following command:</t>
2268 <t>
2269 <list>
2270 <t>LIST CHANNELS</t>
2271 </list>
2272 </t>
2273 <t>Possible Answers:</t>
2274 <t>
2275 <list>
2276 <t>LinuxSampler will answer by returning a comma separated list
2277 with all sampler channels numerical IDs.</t>
2278 </list>
2279 </t>
2280 <t>Example:</t>
2281 <t>
2282 <list>
2283 <t>C: "LIST CHANNELS"</t>
2284 <t>S: "0,1,2,3,4,5,6,9,10,11,15,20"</t>
2285 </list>
2286 </t>
2287 </section>
2288
2289 <section title="Adding a new sampler channel" anchor="ADD CHANNEL" lscp_cmd="true">
2290 <t>A new sampler channel can be added to the end of the sampler
2291 channel list by sending the following command:</t>
2292 <t>
2293 <list>
2294 <t>ADD CHANNEL</t>
2295 </list>
2296 </t>
2297 <t>This will increment the sampler channel count by one and the new
2298 sampler channel will be appended to the end of the sampler channel
2299 list. The front-end should send the respective, related commands
2300 right after to e.g. load an engine, load an instrument and setting
2301 input, output method and eventually other commands to initialize
2302 the new channel. The front-end should use the sampler channel
2303 returned by the answer of this command to perform the previously
2304 recommended commands, to avoid race conditions e.g. with other
2305 front-ends that might also have sent an "ADD CHANNEL" command.</t>
2306 <t>Possible Answers:</t>
2307 <t>
2308 <list>
2309 <t>"OK[&lt;sampler-channel&gt;]" -
2310 <list>
2311 <t>in case a new sampler channel could be added, where
2312 &lt;sampler-channel&gt; reflects the channel number of the new
2313 created sampler channel which should be used to set up
2314 the sampler channel by sending subsequent initialization
2315 commands</t>
2316 </list>
2317 </t>
2318 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2319 <list>
2320 <t>in case a new channel was added successfully, but there are
2321 noteworthy issue(s) related, providing an appropriate
2322 warning code and warning message</t>
2323 </list>
2324 </t>
2325 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2326 <list>
2327 <t>in case it failed, providing an appropriate error code and
2328 error message</t>
2329 </list>
2330 </t>
2331 </list>
2332 </t>
2333 <t>Example:</t>
2334 <t>
2335 <list>
2336 <t></t>
2337 </list>
2338 </t>
2339 </section>
2340
2341 <section title="Removing a sampler channel" anchor="REMOVE CHANNEL" lscp_cmd="true">
2342 <t>A sampler channel can be removed by sending the following command:</t>
2343 <t>
2344 <list>
2345 <t>REMOVE CHANNEL &lt;sampler-channel&gt;</t>
2346 </list>
2347 </t>
2348
2349 <t>Where &lt;sampler-channel&gt; should be replaced by the
2350 number of the sampler channel as given by the
2351 <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
2352 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref>
2353 command. The channel numbers of all subsequent sampler channels
2354 remain the same.</t>
2355
2356 <t>Possible Answers:</t>
2357 <t>
2358 <list>
2359 <t>"OK" -
2360 <list>
2361 <t>in case the given sampler channel could be removed</t>
2362 </list>
2363 </t>
2364 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2365 <list>
2366 <t>in case the given channel was removed, but there are
2367 noteworthy issue(s) related, providing an appropriate
2368 warning code and warning message</t>
2369 </list>
2370 </t>
2371 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2372 <list>
2373 <t>in case it failed, providing an appropriate error code and
2374 error message</t>
2375 </list>
2376 </t>
2377 </list>
2378 </t>
2379 <t>Example:</t>
2380 <t>
2381 <list>
2382 <t></t>
2383 </list>
2384 </t>
2385 </section>
2386
2387 <section title="Getting amount of available engines" anchor="GET AVAILABLE_ENGINES" lscp_cmd="true">
2388 <t>The front-end can ask for the number of available engines by sending the following command:</t>
2389 <t>
2390 <list>
2391 <t>GET AVAILABLE_ENGINES</t>
2392 </list>
2393 </t>
2394 <t>Possible Answers:</t>
2395 <t>
2396 <list>
2397 <t>LinuxSampler will answer by sending the number of available engines.</t>
2398 </list>
2399 </t>
2400 <t>Example:</t>
2401 <t>
2402 <list>
2403 <t>C: "GET AVAILABLE_ENGINES"</t>
2404 <t>S: "4"</t>
2405 </list>
2406 </t>
2407 </section>
2408
2409 <section title="Getting all available engines" anchor="LIST AVAILABLE_ENGINES" lscp_cmd="true">
2410 <t>The front-end can ask for a list of all available engines by sending the following command:</t>
2411 <t>
2412 <list>
2413 <t>LIST AVAILABLE_ENGINES</t>
2414 </list>
2415 </t>
2416 <t>Possible Answers:</t>
2417 <t>
2418 <list>
2419 <t>LinuxSampler will answer by sending a comma separated list
2420 of the engines' names encapsulated into apostrophes (').
2421 Engine names can consist of lower and upper cases,
2422 digits and underlines ("_" character).</t>
2423 </list>
2424 </t>
2425 <t>Example:</t>
2426 <t>
2427 <list>
2428 <t>C: "LIST AVAILABLE_ENGINES"</t>
2429 <t>S: "'gig','sfz','sf2'"</t>
2430 </list>
2431 </t>
2432 </section>
2433
2434 <section title="Getting information about an engine" anchor="GET ENGINE INFO" lscp_cmd="true">
2435 <t>The front-end can ask for information about a specific engine by
2436 sending the following command:</t>
2437 <t>
2438 <list>
2439 <t>GET ENGINE INFO &lt;engine-name&gt;</t>
2440 </list>
2441 </t>
2442 <t>Where &lt;engine-name&gt; is an engine name as obtained by the
2443 <xref target="LIST AVAILABLE_ENGINES">
2444 "LIST AVAILABLE_ENGINES"</xref> command.</t>
2445 <t>Possible Answers:</t>
2446 <t>
2447 <list>
2448 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2449 Each answer line begins with the information category name
2450 followed by a colon and then a space character &lt;SP&gt; and finally
2451 the info character string to that info category. At the moment
2452 the following categories are defined:</t>
2453
2454 <t>
2455 <list>
2456 <t>DESCRIPTION -
2457 <list>
2458 <t>arbitrary description text about the engine
2459 (note that the character string may contain
2460 <xref target="character_set">escape sequences</xref>)</t>
2461 </list>
2462 </t>
2463 <t>VERSION -
2464 <list>
2465 <t>arbitrary character string regarding the engine's version</t>
2466 </list>
2467 </t>
2468 </list>
2469 </t>
2470 </list>
2471 </t>
2472
2473 <t>The mentioned fields above don't have to be in particular order.</t>
2474
2475 <t>Examples:</t>
2476 <t>
2477 <list>
2478 <t>C: "GET ENGINE INFO gig"</t>
2479 <t>S: "DESCRIPTION: GigaSampler Format Engine"</t>
2480 <t>&nbsp;&nbsp;&nbsp;"VERSION: 1.110"</t>
2481 <t>&nbsp;&nbsp;&nbsp;"."</t>
2482 <t>C: "GET ENGINE INFO sf2"</t>
2483 <t>S: "DESCRIPTION: SoundFont Format Engine"</t>
2484 <t>&nbsp;&nbsp;&nbsp;"VERSION: 1.4"</t>
2485 <t>&nbsp;&nbsp;&nbsp;"."</t>
2486 <t>C: "GET ENGINE INFO sfz"</t>
2487 <t>S: "DESCRIPTION: SFZ Format Engine"</t>
2488 <t>&nbsp;&nbsp;&nbsp;"VERSION: 1.11"</t>
2489 <t>&nbsp;&nbsp;&nbsp;"."</t>
2490 </list>
2491 </t>
2492 </section>
2493
2494 <section title="Getting sampler channel information" anchor="GET CHANNEL INFO" lscp_cmd="true">
2495 <t>The front-end can ask for the current settings of a sampler channel
2496 by sending the following command:</t>
2497 <t>
2498 <list>
2499 <t>GET CHANNEL INFO &lt;sampler-channel&gt;</t>
2500 </list>
2501 </t>
2502 <t>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
2503 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
2504 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
2505 <t>Possible Answers:</t>
2506 <t>
2507 <list>
2508 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2509 Each answer line begins with the settings category name
2510 followed by a colon and then a space character &lt;SP&gt; and finally
2511 the info character string to that setting category. At the
2512 moment the following categories are defined:</t>
2513
2514 <t>
2515 <list>
2516 <t>ENGINE_NAME -
2517 <list>
2518 <t>name of the engine that is associated with the sampler
2519 channel, "NONE" if there's no engine associated yet for
2520 this sampler channel</t>
2521 </list>
2522 </t>
2523 <t>AUDIO_OUTPUT_DEVICE -
2524 <list>
2525 <t>numerical ID of the audio output device which is
2526 currently connected to this sampler channel to output
2527 the audio signal, "-1" if there's no device
2528 connected to this sampler channel</t>
2529 </list>
2530 </t>
2531 <t>AUDIO_OUTPUT_CHANNELS -
2532 <list>
2533 <t>number of output channels the sampler channel offers
2534 (dependent to used sampler engine and loaded instrument)</t>
2535 </list>
2536 </t>
2537 <t>AUDIO_OUTPUT_ROUTING -
2538 <list>
2539 <t>comma separated list which reflects to which audio
2540 channel of the selected audio output device each
2541 sampler output channel is routed to, e.g. "0,3" would
2542 mean the engine's output channel 0 is routed to channel
2543 0 of the audio output device and the engine's output
2544 channel 1 is routed to the channel 3 of the audio
2545 output device</t>
2546 </list>
2547 </t>
2548 <t>INSTRUMENT_FILE -
2549 <list>
2550 <t>the file name of the loaded instrument, "NONE" if
2551 there's no instrument yet loaded for this sampler
2552 channel (note: since LSCP 1.2 this path may contain
2553 <xref target="character_set">escape sequences</xref>)</t>
2554 </list>
2555 </t>
2556 <t>INSTRUMENT_NR -
2557 <list>
2558 <t>the instrument index number of the loaded instrument,
2559 "-1" if there's no instrument loaded for this sampler
2560 channel</t>
2561 </list>
2562 </t>
2563 <t>INSTRUMENT_NAME -
2564 <list>
2565 <t>the instrument name of the loaded instrument
2566 (note: since LSCP 1.2 this character string may contain
2567 <xref target="character_set">escape sequences</xref>)</t>
2568 </list>
2569 </t>
2570 <t>INSTRUMENT_STATUS -
2571 <list>
2572 <t>Integer values 0 to 100 indicating loading progress
2573 percentage for the instrument. Negative
2574 value indicates a loading exception (also returns "-1" in case no
2575 instrument was yet to be loaded on the sampler channel).
2576 Value of 100 indicates that the instrument is fully
2577 loaded.</t>
2578 </list>
2579 </t>
2580 <t>MIDI_INPUT_DEVICE -
2581 <list>
2582 <t>DEPRECATED: THIS FIELD WILL DISAPPEAR!</t>
2583 <t>numerical ID of the MIDI input device which is
2584 currently connected to this sampler channel to deliver
2585 MIDI input commands, "-1" if there's no device
2586 connected to this sampler channel</t>
2587 <t>Should not be used anymore as of LSCP v1.6 and younger.
2588 This field is currently only preserved for backward compatibility.
2589 </t>
2590 <t>This field a relict from times where only one MIDI input per
2591 sampler channel was allowed. Use <xref target="LIST CHANNEL MIDI_INPUTS">"GET CHANNEL MIDI_INPUTS"</xref>
2592 instead.</t>
2593 </list>
2594 </t>
2595 <t>MIDI_INPUT_PORT -
2596 <list>
2597 <t>DEPRECATED: THIS FIELD WILL DISAPPEAR!</t>
2598 <t>port number of the MIDI input device (in case a
2599 MIDI device was already assigned to the sampler
2600 channel)</t>
2601 <t>Should not be used anymore as of LSCP v1.6 and younger.
2602 This field is currently only preserved for backward compatibility.
2603 </t>
2604 <t>This field a relict from times where only one MIDI input per
2605 sampler channel was allowed. Use <xref target="LIST CHANNEL MIDI_INPUTS">"GET CHANNEL MIDI_INPUTS"</xref>
2606 instead.</t>
2607 </list>
2608 </t>
2609 <t>MIDI_INPUT_CHANNEL -
2610 <list>
2611 <t>the MIDI input channel number this sampler channel
2612 should listen to or "ALL" to listen on all MIDI channels</t>
2613 </list>
2614 </t>
2615 <t>VOLUME -
2616 <list>
2617 <t>optionally dotted number for the channel volume factor
2618 (where a value &lt; 1.0 means attenuation and a value >
2619 1.0 means amplification)</t>
2620 </list>
2621 </t>
2622 <t>MUTE -
2623 <list>
2624 <t>Determines whether the channel is muted, "true" if the
2625 channel is muted, "false" if the channel is not muted, and
2626 "MUTED_BY_SOLO" if the channel is muted because of the
2627 presence of a solo channel and will be unmuted when
2628 there are no solo channels left</t>
2629 </list>
2630 </t>
2631 <t>SOLO -
2632 <list>
2633 <t>Determines whether this is a solo channel, "true" if
2634 the channel is a solo channel; "false" otherwise</t>
2635 </list>
2636 </t>
2637 <t>MIDI_INSTRUMENT_MAP -
2638 <list>
2639 <t>Determines to which MIDI instrument map this sampler
2640 channel is assigned to. Read chapter
2641 <xref target="SET CHANNEL MIDI_INSTRUMENT_MAP">"SET CHANNEL MIDI_INSTRUMENT_MAP"</xref>
2642 for a list of possible values.</t>
2643 </list>
2644 </t>
2645 </list>
2646 </t>
2647 </list>
2648 </t>
2649 <t>The mentioned fields above don't have to be in particular order.</t>
2650
2651 <t>Example:</t>
2652 <t>
2653 <list>
2654 <t>C: "GET CHANNEL INFO 34"</t>
2655 <t>S: "ENGINE_NAME: gig"</t>
2656 <t>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"</t>
2657 <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_DEVICE: 0"</t>
2658 <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_CHANNELS: 2"</t>
2659 <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 0,1"</t>
2660 <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"</t>
2661 <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"</t>
2662 <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NAME: Fazioli Piano"</t>
2663 <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_STATUS: 100"</t>
2664 <t>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_DEVICE: 0"</t>
2665 <t>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_PORT: 0"</t>
2666 <t>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_CHANNEL: 5"</t>
2667 <t>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"</t>
2668 <t>&nbsp;&nbsp;&nbsp;"MUTE: false"</t>
2669 <t>&nbsp;&nbsp;&nbsp;"SOLO: false"</t>
2670 <t>&nbsp;&nbsp;&nbsp;"MIDI_INSTRUMENT_MAP: NONE"</t>
2671 <t>&nbsp;&nbsp;&nbsp;"."</t>
2672 </list>
2673 </t>
2674 </section>
2675
2676 <section title="Current number of active voices" anchor="GET CHANNEL VOICE_COUNT" lscp_cmd="true">
2677 <t>The front-end can ask for the current number of active voices on a
2678 sampler channel by sending the following command:</t>
2679 <t>
2680 <list>
2681 <t>GET CHANNEL VOICE_COUNT &lt;sampler-channel&gt;</t>
2682 </list>
2683 </t>
2684 <t>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
2685 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
2686 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
2687
2688 <t>Possible Answers:</t>
2689 <t>
2690 <list>
2691 <t>LinuxSampler will answer by returning the number of active
2692 voices on that channel.</t>
2693 </list>
2694 </t>
2695 <t>Example:</t>
2696 <t>
2697 <list>
2698 <t></t>
2699 </list>
2700 </t>
2701 </section>
2702
2703 <section title="Current number of active disk streams" anchor="GET CHANNEL STREAM_COUNT" lscp_cmd="true">
2704 <t>The front-end can ask for the current number of active disk streams
2705 on a sampler channel by sending the following command:</t>
2706 <t>
2707 <list>
2708 <t>GET CHANNEL STREAM_COUNT &lt;sampler-channel&gt;</t>
2709 </list>
2710 </t>
2711 <t>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
2712 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
2713 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
2714
2715 <t>Possible Answers:</t>
2716 <t>
2717 <list>
2718 <t>LinuxSampler will answer by returning the number of active
2719 disk streams on that channel in case the engine supports disk
2720 streaming, if the engine doesn't support disk streaming it will
2721 return "NA" for not available.</t>
2722 </list>
2723 </t>
2724 <t>Example:</t>
2725 <t>
2726 <list>
2727 <t></t>
2728 </list>
2729 </t>
2730 </section>
2731
2732 <section title="Current fill state of disk stream buffers" anchor="GET CHANNEL BUFFER_FILL" lscp_cmd="true">
2733 <t>The front-end can ask for the current fill state of all disk streams
2734 on a sampler channel by sending the following command:</t>
2735 <t>
2736 <list>
2737 <t>GET CHANNEL BUFFER_FILL BYTES &lt;sampler-channel&gt;</t>
2738 </list>
2739 </t>
2740 <t>to get the fill state in bytes or</t>
2741 <t>
2742 <list>
2743 <t>GET CHANNEL BUFFER_FILL PERCENTAGE &lt;sampler-channel&gt;</t>
2744 </list>
2745 </t>
2746 <t>to get the fill state in percent, where &lt;sampler-channel&gt; is the
2747 sampler channel number the front-end is interested in
2748 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
2749 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
2750
2751 <t>Possible Answers:</t>
2752 <t>
2753 <list>
2754 <t>LinuxSampler will either answer by returning a comma separated
2755 string with the fill state of all disk stream buffers on that
2756 channel or an empty line if there are no active disk streams or
2757 "NA" for *not available* in case the engine which is deployed
2758 doesn't support disk streaming. Each entry in the answer list
2759 will begin with the stream's ID in brackets followed by the
2760 numerical representation of the fill size (either in bytes or
2761 percentage). Note: due to efficiency reasons the fill states in
2762 the response are not in particular order, thus the front-end has
2763 to sort them by itself if necessary.</t>
2764 </list>
2765 </t>
2766 <t>Examples:</t>
2767 <t>
2768 <list>
2769 <t>C: "GET CHANNEL BUFFER_FILL BYTES 4"</t>
2770 <t>S: "[115]420500,[116]510300,[75]110000,[120]230700"</t>
2771 </list>
2772
2773 <list>
2774 <t>C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"</t>
2775 <t>S: "[115]90%,[116]98%,[75]40%,[120]62%"</t>
2776 </list>
2777
2778 <list>
2779 <t>C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"</t>
2780 <t>S: ""</t>
2781 </list>
2782 </t>
2783 </section>
2784
2785 <section title="Setting audio output device" anchor="SET CHANNEL AUDIO_OUTPUT_DEVICE" lscp_cmd="true">
2786 <t>The front-end can set the audio output device on a specific sampler
2787 channel by sending the following command:</t>
2788 <t>
2789 <list>
2790 <t>SET CHANNEL AUDIO_OUTPUT_DEVICE &lt;sampler-channel&gt; &lt;audio-device-id&gt;</t>
2791 </list>
2792 </t>
2793 <t>Where &lt;sampler-channel&gt; is the respective sampler channel
2794 number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
2795 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command and
2796 &lt;audio-device-id&gt; is the numerical ID of the audio output device as given by the
2797 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
2798 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
2799 command.</t>
2800
2801 <t>Possible Answers:</t>
2802 <t>
2803 <list>
2804 <t>"OK" -
2805 <list>
2806 <t>on success</t>
2807 </list>
2808 </t>
2809 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2810 <list>
2811 <t>if audio output device was set, but there are noteworthy
2812 issue(s) related, providing an appropriate warning code and
2813 warning message</t>
2814 </list>
2815 </t>
2816 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2817 <list>
2818 <t>in case it failed, providing an appropriate error code and error message</t>
2819 </list>
2820 </t>
2821 </list>
2822 </t>
2823 <t>Examples:</t>
2824 <t>
2825 <list>
2826 <t></t>
2827 </list>
2828 </t>
2829 </section>
2830
2831 <section title="Setting audio output type" anchor="SET CHANNEL AUDIO_OUTPUT_TYPE" lscp_cmd="true">
2832 <t>DEPRECATED: THIS COMMAND WILL DISAPPEAR!</t>
2833
2834 <t>The front-end can alter the audio output type on a specific sampler
2835 channel by sending the following command:</t>
2836 <t>
2837 <list>
2838 <t>SET CHANNEL AUDIO_OUTPUT_TYPE &lt;sampler-channel&gt; &lt;audio-output-type&gt;</t>
2839 </list>
2840 </t>
2841 <t>Where &lt;audio-output-type&gt; is currently either "ALSA" or "JACK" and
2842 &lt;sampler-channel&gt; is the respective sampler channel number.</t>
2843
2844 <t>Possible Answers:</t>
2845 <t>
2846 <list>
2847 <t>"OK" -
2848 <list>
2849 <t>on success</t>
2850 </list>
2851 </t>
2852 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2853 <list>
2854 <t>if audio output type was set, but there are noteworthy
2855 issue(s) related, providing an appropriate warning code and
2856 warning message</t>
2857 </list>
2858 </t>
2859 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2860 <list>
2861 <t>in case it failed, providing an appropriate error code and error message</t>
2862 </list>
2863 </t>
2864 </list>
2865 </t>
2866 <t>Examples:</t>
2867 <t>
2868 <list>
2869 <t></t>
2870 </list>
2871 </t>
2872 <t>Deprecated:</t>
2873 <t>
2874 <list>
2875 <t>Should not be used anymore. This command is currently only preserved for backward compatibility.</t>
2876 <t>This command is a relict from times where there was no sophisticated driver management yet. Use <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref> and <xref target="SET CHANNEL AUDIO_OUTPUT_DEVICE">"SET CHANNEL AUDIO_OUTPUT_DEVICE"</xref> instead.</t>
2877 </list>
2878 </t>
2879 </section>
2880
2881 <section title="Setting audio output channel" anchor="SET CHANNEL AUDIO_OUTPUT_CHANNEL" lscp_cmd="true">
2882 <t>The front-end can alter the audio output channel on a specific
2883 sampler channel by sending the following command:</t>
2884 <t>
2885 <list>
2886 <t>SET CHANNEL AUDIO_OUTPUT_CHANNEL &lt;sampler-chan&gt; &lt;audio-out&gt; &lt;audio-in&gt;</t>
2887 </list>
2888 </t>
2889 <t>Where &lt;sampler-chan&gt; is the sampler channel number
2890 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
2891 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command, &lt;audio-out&gt; is the
2892 numerical ID of the sampler channel's audio output channel which should be
2893 rerouted and &lt;audio-in&gt; is the numerical ID of the audio channel of the selected audio
2894 output device where &lt;audio-out&gt; should be routed to.</t>
2895
2896 <t>Possible Answers:</t>
2897 <t>
2898 <list>
2899 <t>"OK" -
2900 <list>
2901 <t>on success</t>
2902 </list>
2903 </t>
2904 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2905 <list>
2906 <t>if audio output channel was set, but there are noteworthy
2907 issue(s) related, providing an appropriate warning code and
2908 warning message</t>
2909 </list>
2910 </t>
2911 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2912 <list>
2913 <t>in case it failed, providing an appropriate error code and error message</t>
2914 </list>
2915 </t>
2916 </list>
2917 </t>
2918 <t>Examples:</t>
2919 <t>
2920 <list>
2921 <t></t>
2922 </list>
2923 </t>
2924 </section>
2925
2926 <section title="Add MIDI input to sampler channel" anchor="ADD CHANNEL MIDI_INPUT" lscp_cmd="true">
2927 <t>The front-end can add a MIDI input on a specific sampler
2928 channel by sending the following command:</t>
2929 <t>
2930 <list>
2931 <t>ADD CHANNEL MIDI_INPUT &lt;sampler-channel&gt; &lt;midi-device-id&gt; [&lt;midi-input-port&gt;]</t>
2932 </list>
2933 </t>
2934 <t>Where &lt;sampler-channel&gt; is the sampler channel number
2935 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
2936 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command
2937 and &lt;midi-device-id&gt; is the numerical ID of the MIDI input
2938 device as returned by the
2939 <xref target="CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</xref>
2940 or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref> command,
2941 and &lt;midi-input-port&gt; is an optional MIDI input port number of that
2942 MIDI input device. If &lt;midi-input-port&gt; is omitted,
2943 then the MIDI input device's first port (port number 0) is
2944 used.
2945 </t>
2946
2947 <t>Possible Answers:</t>
2948 <t>
2949 <list>
2950 <t>"OK" -
2951 <list>
2952 <t>on success</t>
2953 </list>
2954 </t>
2955 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2956 <list>
2957 <t>if MIDI input port was connected, but there are noteworthy
2958 issue(s) related, providing an appropriate warning code and
2959 warning message</t>
2960 </list>
2961 </t>
2962 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2963 <list>
2964 <t>in case it failed, providing an appropriate error code and error message</t>
2965 </list>
2966 </t>
2967 </list>
2968 </t>
2969 <t>Examples:</t>
2970 <t>
2971 <list>
2972 <t>C: "ADD CHANNEL MIDI_INPUT 0 0"</t>
2973 <t>S: "OK"</t>
2974 <t>C: "ADD CHANNEL MIDI_INPUT 1 0"</t>
2975 <t>S: "OK"</t>
2976 <t>C: "ADD CHANNEL MIDI_INPUT 1 1 1"</t>
2977 <t>S: "OK"</t>
2978 <t>C: "ADD CHANNEL MIDI_INPUT 1 2 0"</t>
2979 <t>S: "OK"</t>
2980 </list>
2981 </t>
2982 <t>Since:</t>
2983 <t>
2984 <list>
2985 <t>Introduced with LSCP v1.6</t>
2986 </list>
2987 </t>
2988 </section>
2989
2990 <section title="Remove MIDI input(s) from sampler channel" anchor="REMOVE CHANNEL MIDI_INPUT" lscp_cmd="true">
2991 <t>The front-end can remove one ore more MIDI input(s) on a
2992 specific sampler channel by sending the following command:</t>
2993 <t>
2994 <list>
2995 <t>REMOVE CHANNEL MIDI_INPUT &lt;sampler-channel&gt; [&lt;midi-device-id&gt; [&lt;midi-input-port&gt;]]</t>
2996 </list>
2997 </t>
2998 <t>Where &lt;sampler-channel&gt; is the sampler channel number
2999 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3000 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command
3001 and &lt;midi-device-id&gt; and &lt;midi-input-port&gt; are
3002 optional numerical IDs defining the MIDI input device and
3003 one of its MIDI ports as returned by the
3004 <xref target="LIST CHANNEL MIDI_INPUTS">"LIST CHANNEL MIDI_INPUTS"</xref> command.
3005 </t>
3006
3007 <t>
3008 If &lt;midi-input-port&gt; is omitted, then all MIDI input
3009 ports of &lt;midi-device-id&gt; are disconnected from this
3010 sampler channel.
3011 </t>
3012
3013 <t>
3014 If both, &lt;midi-device-id&gt; and &lt;midi-input-port&gt;
3015 are omitted, then all MIDI input ports currently connected
3016 to this sampler channel are disconnected from this sampler
3017 channel.
3018 </t>
3019
3020 <t>Possible Answers:</t>
3021 <t>
3022 <list>
3023 <t>"OK" -
3024 <list>
3025 <t>on success</t>
3026 </list>
3027 </t>
3028 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3029 <list>
3030 <t>if MIDI input porst were disconnected, but there are noteworthy
3031 issue(s) related, providing an appropriate warning code and
3032 warning message</t>
3033 </list>
3034 </t>
3035 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3036 <list>
3037 <t>in case it failed, providing an appropriate error code and error message</t>
3038 </list>
3039 </t>
3040 </list>
3041 </t>
3042 <t>Examples:</t>
3043 <t>
3044 <list>
3045 <t>C: "REMOVE CHANNEL MIDI_INPUT 0"</t>
3046 <t>S: "OK"</t>
3047 <t>C: "REMOVE CHANNEL MIDI_INPUT 1"</t>
3048 <t>S: "OK"</t>
3049 <t>C: "REMOVE CHANNEL MIDI_INPUT 1 2 0"</t>
3050 <t>S: "OK"</t>
3051 </list>
3052 </t>
3053 <t>Since:</t>
3054 <t>
3055 <list>
3056 <t>Introduced with LSCP v1.6</t>
3057 </list>
3058 </t>
3059 </section>
3060
3061 <section title="Getting all MIDI inputs of a sampler channel" anchor="LIST CHANNEL MIDI_INPUTS" lscp_cmd="true">
3062 <t>The front-end can query a list of all currently connected
3063 MIDI inputs of a certain sampler channel by sending the following
3064 command:</t>
3065 <t>
3066 <list>
3067 <t>LIST CHANNEL MIDI_INPUTS &lt;sampler-channel&gt;</t>
3068 </list>
3069 </t>
3070 <t>Where &lt;sampler-channel&gt; is the sampler channel number
3071 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3072 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.
3073 </t>
3074
3075 <t>Possible Answers:</t>
3076 <t>
3077 <list>
3078 <t>The sampler will answer by sending a comma separated
3079 list of MIDI input device ID - MIDI input port number pairs, where
3080 each pair is encapsulated into curly braces. The
3081 list is returned in one single line. The MIDI input
3082 device ID corresponds to the number returned by
3083 <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
3084 and the port number is the index of the respective MIDI
3085 port of that MIDI input device.</t>
3086 </list>
3087 </t>
3088
3089 <t>Example:</t>
3090 <t>
3091 <list>
3092 <t>C: "LIST CHANNEL MIDI_INPUTS 0"</t>
3093 <t>S: "{0,0},{1,3},{2,0}"</t>
3094 </list>
3095 </t>
3096
3097 <t>Since:</t>
3098 <t>
3099 <list>
3100 <t>Introduced with LSCP v1.6</t>
3101 </list>
3102 </t>
3103 </section>
3104
3105 <section title="Setting MIDI input device" anchor="SET CHANNEL MIDI_INPUT_DEVICE" lscp_cmd="true">
3106 <t>DEPRECATED: THIS COMMAND WILL DISAPPEAR!</t>
3107
3108 <t>The front-end can set the MIDI input device on a specific sampler
3109 channel by sending the following command:</t>
3110 <t>
3111 <list>
3112 <t>SET CHANNEL MIDI_INPUT_DEVICE &lt;sampler-channel&gt; &lt;midi-device-id&gt;</t>
3113 </list>
3114 </t>
3115 <t>Where &lt;sampler-channel&gt; is the sampler channel number
3116 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3117 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command
3118 and &lt;midi-device-id&gt; is the numerical ID of the MIDI input device as returned by the
3119 <xref target="CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</xref>
3120 or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref> command.</t>
3121
3122 <t>
3123 If more than 1 MIDI inputs are currently connected to this
3124 sampler channel: Sending this command will disconnect ALL
3125 currently connected MIDI input ports connected to this
3126 sampler channel before establishing the new MIDI input
3127 connection. So this command does NOT add the connection,
3128 it replaces all existing ones instead. This behavior is due
3129 to preserving full behavior backward compatibility.
3130 </t>
3131
3132 <t>Possible Answers:</t>
3133 <t>
3134 <list>
3135 <t>"OK" -
3136 <list>
3137 <t>on success</t>
3138 </list>
3139 </t>
3140 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3141 <list>
3142 <t>if MIDI input device was set, but there are noteworthy
3143 issue(s) related, providing an appropriate warning code and
3144 warning message</t>
3145 </list>
3146 </t>
3147 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3148 <list>
3149 <t>in case it failed, providing an appropriate error code and error message</t>
3150 </list>
3151 </t>
3152 </list>
3153 </t>
3154 <t>Examples:</t>
3155 <t>
3156 <list>
3157 <t></t>
3158 </list>
3159 </t>
3160 <t>Deprecated:</t>
3161 <t>
3162 <list>
3163 <t>Should not be used anymore as of LSCP v1.6 and younger. This command is currently only preserved for backward compatibility.</t>
3164 <t>This command is a relict from times where only one MIDI input per sampler channel was allowed. Use <xref target="ADD CHANNEL MIDI_INPUT">"ADD CHANNEL MIDI_INPUT"</xref> and <xref target="REMOVE CHANNEL MIDI_INPUT">"REMOVE CHANNEL MIDI_INPUT"</xref> instead.</t>
3165 </list>
3166 </t>
3167 </section>
3168
3169 <section title="Setting MIDI input type" anchor="SET CHANNEL MIDI_INPUT_TYPE" lscp_cmd="true">
3170 <t>DEPRECATED: THIS COMMAND WILL DISAPPEAR!</t>
3171
3172 <t>The front-end can alter the MIDI input type on a specific sampler
3173 channel by sending the following command:</t>
3174 <t>
3175 <list>
3176 <t>SET CHANNEL MIDI_INPUT_TYPE &lt;sampler-channel&gt; &lt;midi-input-type&gt;</t>
3177 </list>
3178 </t>
3179 <t>Where &lt;midi-input-type&gt; is currently only "ALSA" and
3180 &lt;sampler-channel&gt; is the respective sampler channel number.</t>
3181
3182 <t>
3183 If more than 1 MIDI inputs are currently connected to this
3184 sampler channel: Sending this command will disconnect ALL
3185 currently connected MIDI input ports connected to this
3186 sampler channel before establishing the new MIDI input
3187 connection. So this command does NOT add the connection,
3188 it replaces all existing ones instead. This behavior is due
3189 to preserving full behavior backward compatibility.
3190 </t>
3191
3192 <t>Possible Answers:</t>
3193 <t>
3194 <list>
3195 <t>"OK" -
3196 <list>
3197 <t>on success</t>
3198 </list>
3199 </t>
3200 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3201 <list>
3202 <t>if MIDI input type was set, but there are noteworthy
3203 issue(s) related, providing an appropriate warning code and
3204 warning message</t>
3205 </list>
3206 </t>
3207 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3208 <list>
3209 <t>in case it failed, providing an appropriate error code and error message</t>
3210 </list>
3211 </t>
3212 </list>
3213 </t>
3214 <t>Examples:</t>
3215 <t>
3216 <list>
3217 <t></t>
3218 </list>
3219 </t>
3220 <t>Deprecated:</t>
3221 <t>
3222 <list>
3223 <t>Should not be used anymore. This command is currently only preserved for backward compatibility.</t>
3224 <t>This command is a relict from times where only 1 MIDI input per sampler channels was allowed and where no sophisticated driver management existed yet. Use <xref target="ADD CHANNEL MIDI_INPUT">"ADD CHANNEL MIDI_INPUT"</xref> and <xref target="REMOVE CHANNEL MIDI_INPUT">"REMOVE CHANNEL MIDI_INPUT"</xref> instead.</t>
3225 </list>
3226 </t>
3227 </section>
3228
3229 <section title="Setting MIDI input port" anchor="SET CHANNEL MIDI_INPUT_PORT" lscp_cmd="true">
3230 <t>DEPRECATED: THIS COMMAND WILL DISAPPEAR!</t>
3231
3232 <t>The front-end can alter the MIDI input port on a specific sampler
3233 channel by sending the following command:</t>
3234 <t>
3235 <list>
3236 <t>SET CHANNEL MIDI_INPUT_PORT &lt;sampler-channel&gt; &lt;midi-input-port&gt;</t>
3237 </list>
3238 </t>
3239 <t>Where &lt;midi-input-port&gt; is a MIDI input port number of the
3240 MIDI input device connected to the sampler channel given by
3241 &lt;sampler-channel&gt;.</t>
3242
3243 <t>
3244 If more than 1 MIDI inputs are currently connected to this
3245 sampler channel: Sending this command will switch the
3246 connection of the first (and only the first) MIDI input port
3247 currently being connected to this sampler channel, to
3248 another port of the same MIDI input device. Or in other
3249 words: the first MIDI input port currently connected to
3250 this sampler channel will be disconnected, and the requested
3251 other port of its MIDI input device will be connected to
3252 this sampler channel instead. This behavior is due
3253 to preserving full behavior backward compatibility.
3254 </t>
3255
3256 <t>Possible Answers:</t>
3257 <t>
3258 <list>
3259 <t>"OK" -
3260 <list>
3261 <t>on success</t>
3262 </list>
3263 </t>
3264 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3265 <list>
3266 <t>if MIDI input port was set, but there are noteworthy
3267 issue(s) related, providing an appropriate warning code and
3268 warning message</t>
3269 </list>
3270 </t>
3271 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3272 <list>
3273 <t>in case it failed, providing an appropriate error code and error message</t>
3274 </list>
3275 </t>
3276 </list>
3277 </t>
3278 <t>Examples:</t>
3279 <t>
3280 <list>
3281 <t></t>
3282 </list>
3283 </t>
3284 <t>Deprecated:</t>
3285 <t>
3286 <list>
3287 <t>Should not be used anymore. This command is currently only preserved for backward compatibility.</t>
3288 <t>This command is a relict from times where only one MIDI input per sampler channel was allowed. Use <xref target="ADD CHANNEL MIDI_INPUT">"ADD CHANNEL MIDI_INPUT"</xref> and <xref target="REMOVE CHANNEL MIDI_INPUT">"REMOVE CHANNEL MIDI_INPUT"</xref> instead.</t>
3289 </list>
3290 </t>
3291 </section>
3292
3293 <section title="Setting MIDI input channel" anchor="SET CHANNEL MIDI_INPUT_CHANNEL" lscp_cmd="true">
3294 <t>The front-end can alter the MIDI channel a sampler channel should
3295 listen to by sending the following command:</t>
3296 <t>
3297 <list>
3298 <t>SET CHANNEL MIDI_INPUT_CHANNEL &lt;sampler-channel&gt; &lt;midi-input-chan&gt;</t>
3299 </list>
3300 </t>
3301 <t>Where &lt;midi-input-chan&gt; is the number
3302 of the new MIDI input channel (zero indexed!) where
3303 &lt;sampler-channel&gt; should listen to, or "ALL" to listen on all 16 MIDI
3304 channels.</t>
3305
3306 <t>Possible Answers:</t>
3307 <t>
3308 <list>
3309 <t>"OK" -
3310 <list>
3311 <t>on success</t>
3312 </list>
3313 </t>
3314 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3315 <list>
3316 <t>if MIDI input channel was set, but there are noteworthy
3317 issue(s) related, providing an appropriate warning code and
3318 warning message</t>
3319 </list>
3320 </t>
3321 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3322 <list>
3323 <t>in case it failed, providing an appropriate error code and error message</t>
3324 </list>
3325 </t>
3326 </list>
3327 </t>
3328 <t>Examples:</t>
3329 <t>
3330 <list>
3331 <t>C: "SET CHANNEL MIDI_INPUT_CHANNEL 0 0"</t>
3332 <t>S: "OK"</t>
3333 <t>C: "SET CHANNEL MIDI_INPUT_CHANNEL 1 ALL"</t>
3334 <t>S: "OK"</t>
3335 </list>
3336 </t>
3337 </section>
3338
3339 <section title="Setting channel volume" anchor="SET CHANNEL VOLUME" lscp_cmd="true">
3340 <t>The front-end can alter the volume of a sampler channel by sending
3341 the following command:</t>
3342 <t>
3343 <list>
3344 <t>SET CHANNEL VOLUME &lt;sampler-channel&gt; &lt;volume&gt;</t>
3345 </list>
3346 </t>
3347 <t>Where &lt;volume&gt; is an optionally dotted positive number (a value
3348 smaller than 1.0 means attenuation, whereas a value greater than
3349 1.0 means amplification) and &lt;sampler-channel&gt; defines the sampler
3350 channel where this volume factor should be set.</t>
3351
3352 <t>Possible Answers:</t>
3353 <t>
3354 <list>
3355 <t>"OK" -
3356 <list>
3357 <t>on success</t>
3358 </list>
3359 </t>
3360 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3361 <list>
3362 <t>if channel volume was set, but there are noteworthy
3363 issue(s) related, providing an appropriate warning code and
3364 warning message</t>
3365 </list>
3366 </t>
3367 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3368 <list>
3369 <t>in case it failed, providing an appropriate error code and error message</t>
3370 </list>
3371 </t>
3372 </list>
3373 </t>
3374 <t>Examples:</t>
3375 <t>
3376 <list>
3377 <t></t>
3378 </list>
3379 </t>
3380 </section>
3381
3382 <section title="Muting a sampler channel" anchor="SET CHANNEL MUTE" lscp_cmd="true">
3383 <t>The front-end can mute/unmute a specific sampler
3384 channel by sending the following command:</t>
3385 <t>
3386 <list>
3387 <t>SET CHANNEL MUTE &lt;sampler-channel&gt; &lt;mute&gt;</t>
3388 </list>
3389 </t>
3390 <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3391 number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3392 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command and
3393 &lt;mute&gt; should be replaced either by "1" to mute the channel or "0"
3394 to unmute the channel.</t>
3395
3396 <t>Possible Answers:</t>
3397 <t>
3398 <list>
3399 <t>"OK" -
3400 <list>
3401 <t>on success</t>
3402 </list>
3403 </t>
3404 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3405 <list>
3406 <t>if the channel was muted/unmuted, but there are noteworthy
3407 issue(s) related, providing an appropriate warning code and
3408 warning message</t>
3409 </list>
3410 </t>
3411 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3412 <list>
3413 <t>in case it failed, providing an appropriate error code and error message</t>
3414 </list>
3415 </t>
3416 </list>
3417 </t>
3418 <t>Examples:</t>
3419 <t>
3420 <list>
3421 <t></t>
3422 </list>
3423 </t>
3424 </section>
3425
3426 <section title="Soloing a sampler channel" anchor="SET CHANNEL SOLO" lscp_cmd="true">
3427 <t>The front-end can solo/unsolo a specific sampler channel
3428 by sending the following command:</t>
3429 <t>
3430 <list>
3431 <t>SET CHANNEL SOLO &lt;sampler-channel&gt; &lt;solo&gt;</t>
3432 </list>
3433 </t>
3434 <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3435 number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3436 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command and
3437 &lt;solo&gt; should be replaced either by "1" to solo the channel or "0"
3438 to unsolo the channel.</t>
3439
3440 <t>Possible Answers:</t>
3441 <t>
3442 <list>
3443 <t>"OK" -
3444 <list>
3445 <t>on success</t>
3446 </list>
3447 </t>
3448 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3449 <list>
3450 <t>if the channel was soloed/unsoloed, but there are noteworthy
3451 issue(s) related, providing an appropriate warning code and
3452 warning message</t>
3453 </list>
3454 </t>
3455 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3456 <list>
3457 <t>in case it failed, providing an appropriate error code and error message</t>
3458 </list>
3459 </t>
3460 </list>
3461 </t>
3462 <t>Examples:</t>
3463 <t>
3464 <list>
3465 <t></t>
3466 </list>
3467 </t>
3468 </section>
3469
3470 <section title="Assigning a MIDI instrument map to a sampler channel" anchor="SET CHANNEL MIDI_INSTRUMENT_MAP" lscp_cmd="true">
3471 <t>The front-end can assign a MIDI instrument map to a specific sampler channel
3472 by sending the following command:</t>
3473 <t>
3474 <list>
3475 <t>SET CHANNEL MIDI_INSTRUMENT_MAP &lt;sampler-channel&gt; &lt;map&gt;</t>
3476 </list>
3477 </t>
3478 <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3479 number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3480 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command and
3481 &lt;map&gt; can have the following possibilites:</t>
3482 <t>
3483 <list>
3484 <t>"NONE" -
3485 <list>
3486 <t>This is the default setting. In this case
3487 the sampler channel is not assigned any MIDI
3488 instrument map and thus will ignore all MIDI
3489 program change messages.</t>
3490 </list>
3491 </t>
3492 <t>"DEFAULT" -
3493 <list>
3494 <t>The sampler channel will always use the
3495 default MIDI instrument map to handle MIDI
3496 program change messages.</t>
3497 </list>
3498 </t>
3499 <t>numeric ID -
3500 <list>
3501 <t>You can assign a specific MIDI instrument map
3502 by replacing &lt;map&gt; with the respective numeric
3503 ID of the MIDI instrument map as returned by the
3504 <xref target="LIST MIDI_INSTRUMENT_MAPS">"LIST MIDI_INSTRUMENT_MAPS"</xref>
3505 command. Once that map will be deleted, the sampler
3506 channel would fall back to "NONE".</t>
3507 </list>
3508 </t>
3509 </list>
3510 </t>
3511 <t>Read chapter <xref target="MIDI Instrument Mapping">"MIDI Instrument Mapping"</xref>
3512 for details regarding MIDI instrument mapping.</t>
3513
3514 <t>Possible Answers:</t>
3515 <t>
3516 <list>
3517 <t>"OK" -
3518 <list>
3519 <t>on success</t>
3520 </list>
3521 </t>
3522 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3523 <list>
3524 <t>in case it failed, providing an appropriate error code and error message</t>
3525 </list>
3526 </t>
3527 </list>
3528 </t>
3529
3530 <t>Examples:</t>
3531 <t>
3532 <list>
3533 <t></t>
3534 </list>
3535 </t>
3536 </section>
3537
3538 <section title="Adding an effect send to a sampler channel" anchor="CREATE FX_SEND" lscp_cmd="true">
3539 <t>The front-end can create an additional effect send on a specific sampler channel
3540 by sending the following command:</t>
3541 <t>
3542 <list>
3543 <t>CREATE FX_SEND &lt;sampler-channel&gt; &lt;midi-ctrl&gt; [&lt;name&gt;]</t>
3544 </list>
3545 </t>
3546 <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3547 number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3548 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command, that is the
3549 sampler channel on which the effect send should be created on, &lt;midi-ctrl&gt;
3550 is a number between 0..127 defining the MIDI controller which can alter the
3551 effect send level and &lt;name&gt; is an optional argument defining a name
3552 for the effect send entity. The name does not have to be unique, but MUST be
3553 encapsulated into apostrophes and supports escape sequences as described in chapter
3554 "<xref target="character_set">Character Set and Escape Sequences</xref>".</t>
3555
3556 <t>Note: there are two possible approaches to apply audio effects with FX sends:
3557 you can either use a) internal effects or b) external effects.
3558 By default, that is as initial routing, effect sends are automatically routed
3559 directly to the sampler channel's audio output device and the effect send's
3560 audio channels are by default automatically routed to the last audio channels
3561 of that audio output device (for the purpose of applying effects externally that is,
3562 e.g. by using another application), that way you can i.e. first increase the
3563 amount of audio channels on the audio output device for having dedicated effect
3564 send output channels and when "CREATE FX_SEND" is called, those channels will
3565 automatically be picked. You can alter the destination channels however with
3566 <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">"SET FX_SEND AUDIO_OUTPUT_CHANNEL"</xref>.
3567 If your intention is rather to use internal effects instead of external effects,
3568 then you first need to <xref target="effects">load those internal effects</xref>
3569 and then assign the FX sends to the desired internal effect by sending
3570 <xref target="SET FX_SEND EFFECT">"SET FX_SEND EFFECT"</xref>.
3571 </t>
3572
3573 <t>Note: Create effect sends on a sampler channel only when needed, because having effect
3574 sends on a sampler channel will decrease runtime performance, because for implementing channel
3575 effect sends, separate (sampler channel local) audio buffers are needed to render and mix
3576 the voices and route the audio signal afterwards to the master outputs and effect send
3577 outputs (along with their respective effect send levels). A sampler channel without effect
3578 sends however can mix its voices directly into the audio output devices's audio buffers
3579 and is thus faster.
3580 </t>
3581
3582 <t>Possible Answers:</t>
3583 <t>
3584 <list>
3585 <t>"OK[&lt;fx-send-id&gt;]" -
3586 <list>
3587 <t>in case a new effect send could be added to the
3588 sampler channel, where &lt;fx-send-id&gt; reflects the
3589 unique ID of the newly created effect send entity</t>
3590 </list>
3591 </t>
3592 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3593 <list>
3594 <t>when a new effect send could not be added, i.e.
3595 due to invalid parameters</t>
3596 </list>
3597 </t>
3598 </list>
3599 </t>
3600
3601 <t>Examples:</t>
3602 <t>
3603 <list>
3604 <t>C: "CREATE FX_SEND 0 91 'Reverb Send'"</t>
3605 <t>S: "OK[0]"</t>
3606 </list>
3607 </t>
3608 <t>
3609 <list>
3610 <t>C: "CREATE FX_SEND 0 93"</t>
3611 <t>S: "OK[1]"</t>
3612 </list>
3613 </t>
3614 </section>
3615
3616 <section title="Removing an effect send from a sampler channel" anchor="DESTROY FX_SEND" lscp_cmd="true">
3617 <t>The front-end can remove an existing effect send on a specific sampler channel
3618 by sending the following command:</t>
3619 <t>
3620 <list>
3621 <t>DESTROY FX_SEND &lt;sampler-channel&gt; &lt;fx-send-id&gt;</t>
3622 </list>
3623 </t>
3624 <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3625 number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3626 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command, that is the
3627 sampler channel from which the effect send should be removed from and
3628 &lt;fx-send-id&gt; is the respective effect send number as returned by the
3629 <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3630 or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command.</t>
3631
3632 <t>Possible Answers:</t>
3633 <t>
3634 <list>
3635 <t>"OK" -
3636 <list>
3637 <t>on success</t>
3638 </list>
3639 </t>
3640 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3641 <list>
3642 <t>in case it failed, providing an appropriate error code and
3643 error message</t>
3644 </list>
3645 </t>
3646 </list>
3647 </t>
3648
3649 <t>Example:</t>
3650 <t>
3651 <list>
3652 <t>C: "DESTROY FX_SEND 0 0"</t>
3653 <t>S: "OK"</t>
3654 </list>
3655 </t>
3656 </section>
3657
3658 <section title="Getting amount of effect sends on a sampler channel" anchor="GET FX_SENDS" lscp_cmd="true">
3659 <t>The front-end can ask for the amount of effect sends on a specific sampler channel
3660 by sending the following command:</t>
3661 <t>
3662 <list>
3663 <t>GET FX_SENDS &lt;sampler-channel&gt;</t>
3664 </list>
3665 </t>
3666 <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3667 number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3668 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
3669
3670 <t>Possible Answers:</t>
3671 <t>
3672 <list>
3673 <t>The sampler will answer by returning the number of effect
3674 sends on the given sampler channel.</t>
3675 </list>
3676 </t>
3677
3678 <t>Example:</t>
3679 <t>
3680 <list>
3681 <t>C: "GET FX_SENDS 0"</t>
3682 <t>S: "2"</t>
3683 </list>
3684 </t>
3685 </section>
3686
3687 <section title="Listing all effect sends on a sampler channel" anchor="LIST FX_SENDS" lscp_cmd="true">
3688 <t>The front-end can ask for a list of effect sends on a specific sampler channel
3689 by sending the following command:</t>
3690 <t>
3691 <list>
3692 <t>LIST FX_SENDS &lt;sampler-channel&gt;</t>
3693 </list>
3694 </t>
3695 <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3696 number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3697 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
3698
3699 <t>Possible Answers:</t>
3700 <t>
3701 <list>
3702 <t>The sampler will answer by returning a comma separated list
3703 with all effect sends' numerical IDs on the given sampler
3704 channel.</t>
3705 </list>
3706 </t>
3707
3708 <t>Examples:</t>
3709 <t>
3710 <list>
3711 <t>C: "LIST FX_SENDS 0"</t>
3712 <t>S: "0,1"</t>
3713 </list>
3714 </t>
3715 <t>
3716 <list>
3717 <t>C: "LIST FX_SENDS 1"</t>
3718 <t>S: ""</t>
3719 </list>
3720 </t>
3721 </section>
3722
3723 <section title="Getting effect send information" anchor="GET FX_SEND INFO" lscp_cmd="true">
3724 <t>The front-end can ask for the current settings of an effect send entity
3725 by sending the following command:</t>
3726 <t>
3727 <list>
3728 <t>GET FX_SEND INFO &lt;sampler-channel&gt; &lt;fx-send-id&gt;</t>
3729 </list>
3730 </t>
3731 <t>Where &lt;sampler-channel&gt; is the sampler channel number
3732 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3733 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command and
3734 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3735 as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3736 or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command.
3737 </t>
3738
3739 <t>Possible Answers:</t>
3740 <t>
3741 <list>
3742 <t>The sampler will answer by sending a &lt;CRLF&gt; separated list.
3743 Each answer line begins with the settings category name
3744 followed by a colon and then a space character &lt;SP&gt; and finally
3745 the info character string to that setting category. At the
3746 moment the following categories are defined:</t>
3747
3748 <t>
3749 <list>
3750 <t>NAME -
3751 <list>
3752 <t>name of the effect send entity
3753 (note that this character string may contain
3754 <xref target="character_set">escape sequences</xref>)</t>
3755 </list>
3756 </t>
3757 <t>MIDI_CONTROLLER -
3758 <list>
3759 <t>a value between 0 and 127 reflecting the MIDI controller
3760 which is able to modify the effect send's send level</t>
3761 </list>
3762 </t>
3763 <t>LEVEL -
3764 <list>
3765 <t>optionally dotted number reflecting the effect send's
3766 current send level (where a value &lt; 1.0 means attenuation
3767 and a value > 1.0 means amplification)</t>
3768 </list>
3769 </t>
3770 <t>AUDIO_OUTPUT_ROUTING -
3771 <list>
3772 <t>comma separated list which reflects to which audio
3773 channel of the selected audio output device each
3774 effect send output channel is routed to, e.g. "0,3" would
3775 mean the effect send's output channel 0 is routed to channel
3776 0 of the audio output device and the effect send's output
3777 channel 1 is routed to the channel 3 of the audio
3778 output device (see
3779 <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">"SET FX_SEND AUDIO_OUTPUT_CHANNEL"</xref>
3780 for details), if an internal send
3781 effect is assigned to the effect
3782 send, then this setting defines the
3783 audio channel routing to that
3784 effect instance respectively</t>
3785 </list>
3786 </t>
3787 <t>EFFECT -
3788 <list>
3789 <t>destination send effect chain ID
3790 and destination effect chain
3791 position, separated by comma in the
3792 form "&lt;effect-chain&gt;,&lt;chain-pos&gt;"
3793 or "NONE" if there is no send effect
3794 assigned to the effect send</t>
3795 </list>
3796 </t>
3797 </list>
3798 </t>
3799 </list>
3800 </t>
3801 <t>The mentioned fields above don't have to be in particular order.</t>
3802
3803 <t>Example:</t>
3804 <t>
3805 <list>
3806 <t>C: "GET FX_SEND INFO 0 0"</t>
3807 <t>S: "NAME: Reverb Send"</t>
3808 <t>&nbsp;&nbsp;&nbsp;"MIDI_CONTROLLER: 91"</t>
3809 <t>&nbsp;&nbsp;&nbsp;"LEVEL: 0.3"</t>
3810 <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 2,3"</t>
3811 <t>&nbsp;&nbsp;&nbsp;"EFFECT: NONE"</t>
3812 <t>&nbsp;&nbsp;&nbsp;"."</t>
3813 </list>
3814 </t>
3815 <t>
3816 <list>
3817 <t>C: "GET FX_SEND INFO 0 1"</t>
3818 <t>S: "NAME: Delay Send (Internal)"</t>
3819 <t>&nbsp;&nbsp;&nbsp;"MIDI_CONTROLLER: 93"</t>
3820 <t>&nbsp;&nbsp;&nbsp;"LEVEL: 0.51"</t>
3821 <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 1,2"</t>
3822 <t>&nbsp;&nbsp;&nbsp;"EFFECT: 2,0"</t>
3823 <t>&nbsp;&nbsp;&nbsp;"."</t>
3824 </list>
3825 </t>
3826 </section>
3827
3828 <section title="Changing effect send's name" anchor="SET FX_SEND NAME" lscp_cmd="true">
3829 <t>The front-end can alter the current name of an effect
3830 send entity by sending the following command:</t>
3831 <t>
3832 <list>
3833 <t>SET FX_SEND NAME &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;name&gt;</t>
3834 </list>
3835 </t>
3836 <t>Where &lt;sampler-chan&gt; is the sampler channel number
3837 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3838 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3839 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3840 as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3841 or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3842 &lt;name&gt; is the new name of the effect send entity, which
3843 does not have to be unique (name MUST be encapsulated into apostrophes
3844 and supports escape sequences as described in chapter
3845 "<xref target="character_set">Character Set and Escape Sequences</xref>").
3846 </t>
3847
3848 <t>Possible Answers:</t>
3849 <t>
3850 <list>
3851 <t>"OK" -
3852 <list>
3853 <t>on success</t>
3854 </list>
3855 </t>
3856 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3857 <list>
3858 <t>in case it failed, providing an appropriate error code and error message</t>
3859 </list>
3860 </t>
3861 </list>
3862 </t>
3863 <t>Example:</t>
3864 <t>
3865 <list>
3866 <t>C: "SET FX_SEND NAME 0 0 'Fx Send 1'"</t>
3867 <t>S: "OK"</t>
3868 </list>
3869 </t>
3870 </section>
3871
3872 <section title="Altering effect send's audio routing" anchor="SET FX_SEND AUDIO_OUTPUT_CHANNEL" lscp_cmd="true">
3873 <t>The front-end can alter the destination of an effect send's audio channel on a specific
3874 sampler channel by sending the following command:</t>
3875 <t>
3876 <list>
3877 <t>SET FX_SEND AUDIO_OUTPUT_CHANNEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;audio-src&gt; &lt;audio-dst&gt;</t>
3878 </list>
3879 </t>
3880 <t>Where &lt;sampler-chan&gt; is the sampler channel number
3881 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3882 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3883 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3884 as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3885 or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command,
3886 &lt;audio-src&gt; is the numerical ID of the effect send's audio channel
3887 which should be rerouted and &lt;audio-dst&gt; is the numerical ID of
3888 either a) the audio output channel of the sampler channel's audio output
3889 device (i.e. if external effect shall be applied) or b) of the audio
3890 input channel of an internal effect assigned to the FX send where
3891 &lt;audio-src&gt; should be routed to.</t>
3892
3893 <t>Note that effect sends can only route audio to the same audio output
3894 device as assigned to the effect send's sampler channel. Also note that an
3895 effect send entity does always have exactly as much audio channels as its
3896 sampler channel. So if the sampler channel is stereo, the effect send does
3897 have two audio channels as well. Also keep in mind that the amount of audio
3898 channels on a sampler channel might be dependant not only to the deployed
3899 sampler engine on the sampler channel, but also dependant to the instrument
3900 currently loaded. However you can (effectively) turn an i.e. stereo effect
3901 send into a mono one by simply altering its audio routing appropriately.</t>
3902
3903 <t>Possible Answers:</t>
3904 <t>
3905 <list>
3906 <t>"OK" -
3907 <list>
3908 <t>on success</t>
3909 </list>
3910 </t>
3911 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3912 <list>
3913 <t>if audio output channel was set, but there are noteworthy
3914 issue(s) related, providing an appropriate warning code and
3915 warning message</t>
3916 </list>
3917 </t>
3918 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3919 <list>
3920 <t>in case it failed, providing an appropriate error code and error message</t>
3921 </list>
3922 </t>
3923 </list>
3924 </t>
3925 <t>Example:</t>
3926 <t>
3927 <list>
3928 <t>C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2"</t>
3929 <t>S: "OK"</t>
3930 </list>
3931 </t>
3932 </section>
3933
3934 <section title="Assigning destination effect to an effect send" anchor="SET FX_SEND EFFECT" lscp_cmd="true">
3935 <t>The front-end can (re-)assign an internal destination effect to an
3936 effect send by sending the following command:</t>
3937 <t>
3938 <list>
3939 <t>SET FX_SEND EFFECT &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;effect-chain&gt; &lt;chain-pos&gt;</t>
3940 </list>
3941 </t>
3942 <t>Where &lt;sampler-chan&gt; is the sampler channel number
3943 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3944 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3945 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3946 as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3947 or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command,
3948 &lt;effect-chain&gt; by the numerical ID of the destination
3949 effect chain as returned by the
3950 <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
3951 or
3952 <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
3953 command and &lt;chain-pos&gt; reflects the exact effect
3954 chain position in the effect chain which hosts the actual
3955 destination effect.</t>
3956
3957 <t>Note: This command MUST NOT be used if you want to apply
3958 audio effects externally! By default FX sends are routed directly
3959 to the audio output device for that purpose.
3960 You can also revert this command later on by sending
3961 <xref target="REMOVE FX_SEND EFFECT">"REMOVE FX_SEND EFFECT"</xref>,
3962 which will cause the FX send to be routed directly to the sampler channel's
3963 audio output device instead (i.e. for using external effects instead of
3964 internal effects).
3965 </t>
3966
3967 <t>Possible Answers:</t>
3968 <t>
3969 <list>
3970 <t>"OK" -
3971 <list>
3972 <t>on success</t>
3973 </list>
3974 </t>
3975 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3976 <list>
3977 <t>in case it failed, providing an appropriate error code and error message</t>
3978 </list>
3979 </t>
3980 </list>
3981 </t>
3982 <t>Example:</t>
3983 <t>
3984 <list>
3985 <t>C: "SET FX_SEND EFFECT 0 0 2 5"</t>
3986 <t>S: "OK"</t>
3987 </list>
3988 </t>
3989 </section>
3990
3991 <section title="Removing destination effect from an effect send" anchor="REMOVE FX_SEND EFFECT" lscp_cmd="true">
3992 <t>The front-end can (re-)assign a destination effect to an
3993 effect send by sending the following command:</t>
3994 <t>
3995 <list>
3996 <t>REMOVE FX_SEND EFFECT &lt;sampler-chan&gt; &lt;fx-send-id&gt;</t>
3997 </list>
3998 </t>
3999 <t>Where &lt;sampler-chan&gt; is the sampler channel number
4000 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
4001 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
4002 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
4003 as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
4004 or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command.</t>
4005
4006 <t>After the destination effect has been removed from the
4007 effect send, the audio signal of the effect send will be
4008 routed directly to the audio output device, according to the
4009 audio channel routing setting of the effect send.
4010 </t>
4011
4012 <t>Possible Answers:</t>
4013 <t>
4014 <list>
4015 <t>"OK" -
4016 <list>
4017 <t>on success</t>
4018 </list>
4019 </t>
4020 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4021 <list>
4022 <t>in case it failed, providing an appropriate error code and error message</t>
4023 </list>
4024 </t>
4025 </list>
4026 </t>
4027 <t>Example:</t>
4028 <t>
4029 <list>
4030 <t>C: "REMOVE FX_SEND EFFECT 0 0"</t>
4031 <t>S: "OK"</t>
4032 </list>
4033 </t>
4034 </section>
4035
4036 <section title="Altering effect send's MIDI controller" anchor="SET FX_SEND MIDI_CONTROLLER" lscp_cmd="true">
4037 <t>The front-end can alter the MIDI controller of an effect
4038 send entity by sending the following command:</t>
4039 <t>
4040 <list>
4041 <t>SET FX_SEND MIDI_CONTROLLER &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;midi-ctrl&gt;</t>
4042 </list>
4043 </t>
4044 <t>Where &lt;sampler-chan&gt; is the sampler channel number
4045 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
4046 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
4047 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
4048 as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
4049 or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
4050 &lt;midi-ctrl&gt; reflects the MIDI controller which shall be
4051 able to modify the effect send's send level.</t>
4052
4053 <t>Possible Answers:</t>
4054 <t>
4055 <list>
4056 <t>"OK" -
4057 <list>
4058 <t>on success</t>
4059 </list>
4060 </t>
4061 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4062 <list>
4063 <t>if MIDI controller was set, but there are noteworthy
4064 issue(s) related, providing an appropriate warning code and
4065 warning message</t>
4066 </list>
4067 </t>
4068 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4069 <list>
4070 <t>in case it failed, providing an appropriate error code and error message</t>
4071 </list>
4072 </t>
4073 </list>
4074 </t>
4075 <t>Example:</t>
4076 <t>
4077 <list>
4078 <t>C: "SET FX_SEND MIDI_CONTROLLER 0 0 91"</t>
4079 <t>S: "OK"</t>
4080 </list>
4081 </t>
4082 </section>
4083
4084 <section title="Altering effect send's send level" anchor="SET FX_SEND LEVEL" lscp_cmd="true">
4085 <t>The front-end can alter the current send level of an effect
4086 send entity by sending the following command:</t>
4087 <t>
4088 <list>
4089 <t>SET FX_SEND LEVEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;volume&gt;</t>
4090 </list>
4091 </t>
4092 <t>Where &lt;sampler-chan&gt; is the sampler channel number
4093 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
4094 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
4095 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
4096 as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
4097 or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
4098 &lt;volume&gt; is an optionally dotted positive number (a value
4099 smaller than 1.0 means attenuation, whereas a value greater than
4100 1.0 means amplification) reflecting the new send level.</t>
4101
4102 <t>Possible Answers:</t>
4103