/[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 (5 years 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 <t>
4104 <list>
4105 <t>"OK" -
4106 <list>
4107 <t>on success</t>
4108 </list>
4109 </t>
4110 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4111 <list>
4112 <t>if new send level was set, but there are noteworthy
4113 issue(s) related, providing an appropriate warning code and
4114 warning message</t>
4115 </list>
4116 </t>
4117 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4118 <list>
4119 <t>in case it failed, providing an appropriate error code and error message</t>
4120 </list>
4121 </t>
4122 </list>
4123 </t>
4124 <t>Example:</t>
4125 <t>
4126 <list>
4127 <t>C: "SET FX_SEND LEVEL 0 0 0.15"</t>
4128 <t>S: "OK"</t>
4129 </list>
4130 </t>
4131 </section>
4132
4133 <section title="Sending MIDI messages to sampler channel" anchor="SEND CHANNEL MIDI_DATA" lscp_cmd="true">
4134 <t>The front-end can send MIDI events to a specific sampler channel
4135 by sending the following command:</t>
4136 <t>
4137 <list>
4138 <t>SEND CHANNEL MIDI_DATA &lt;midi-msg&gt; &lt;sampler-chan&gt; &lt;arg1&gt; &lt;arg2&gt;</t>
4139 </list>
4140 </t>
4141 <t>Where &lt;sampler-chan&gt; is the sampler channel number
4142 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
4143 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
4144 &lt;arg1&gt; and &lt;arg2&gt; arguments depend on the &lt;midi-msg&gt; argument, which
4145 specifies the MIDI message type. Currently, the following MIDI messages are supported:</t>
4146 <t>
4147 <list>
4148 <t>"NOTE_ON" -
4149 <list>
4150 <t>For turning on MIDI notes, where &lt;arg1&gt;
4151 specifies the key number and &lt;arg2&gt; the velocity
4152 as described in the MIDI specification.</t>
4153 </list>
4154 </t>
4155 <t>"NOTE_OFF" -
4156 <list>
4157 <t>For turning a currently playing MIDI note off, where &lt;arg1&gt;
4158 specifies the key number and &lt;arg2&gt; the velocity
4159 as described in the MIDI specification.</t>
4160 </list>
4161 </t>
4162 <t>"CC" -
4163 <list>
4164 <t>For changing a MIDI controller, where &lt;arg1&gt;
4165 specifies the controller number and &lt;arg2&gt; the
4166 new value of the controller as described in the Control
4167 Change section of the MIDI specification.</t>
4168 </list>
4169 </t>
4170 </list>
4171 </t>
4172 <t>CAUTION: This command is provided for implementations of virtual MIDI keyboards
4173 and no realtime guarantee whatsoever will be made!</t>
4174 <t>Possible Answers:</t>
4175 <t>
4176 <list>
4177 <t>"OK" -
4178 <list>
4179 <t>on success</t>
4180 </list>
4181 </t>
4182 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4183 <list>
4184 <t>in case it failed, providing an appropriate error code and error message</t>
4185 </list>
4186 </t>
4187 </list>
4188 </t>
4189 <t>Example:</t>
4190 <t>
4191 <list>
4192 <t>C: "SEND CHANNEL MIDI_DATA NOTE_ON 0 56 112"</t>
4193 <t>S: "OK"</t>
4194 </list>
4195 </t>
4196 </section>
4197
4198 <section title="Resetting a sampler channel" anchor="RESET CHANNEL" lscp_cmd="true">
4199 <t>The front-end can reset a particular sampler channel by sending the following command:</t>
4200 <t>
4201 <list>
4202 <t>RESET CHANNEL &lt;sampler-channel&gt;</t>
4203 </list>
4204 </t>
4205 <t>
4206 Where &lt;sampler-channel&gt; defines the sampler channel to be reset.
4207 This will cause the engine on that sampler channel, its voices and
4208 eventually disk streams and all control and status variables to be
4209 reset.</t>
4210
4211 <t>Possible Answers:</t>
4212 <t>
4213 <list>
4214 <t>"OK" -
4215 <list>
4216 <t>on success</t>
4217 </list>
4218 </t>
4219 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4220 <list>
4221 <t>if channel was reset, but there are noteworthy issue(s)
4222 related, providing an appropriate warning code and warning
4223 message</t>
4224 </list>
4225 </t>
4226 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4227 <list>
4228 <t>in case it failed, providing an appropriate error code and
4229 error message</t>
4230 </list>
4231 </t>
4232 </list>
4233 </t>
4234 <t>Examples:</t>
4235 <t>
4236 <list>
4237 <t></t>
4238 </list>
4239 </t>
4240 </section>
4241 </section>
4242
4243 <section title="Controlling connection">
4244 <t>The following commands are used to control the connection to LinuxSampler.</t>
4245
4246 <section title="Register front-end for receiving event messages" anchor="SUBSCRIBE" lscp_cmd="true">
4247 <t>The front-end can register itself to the LinuxSampler application to
4248 be informed about noteworthy events by sending this command:</t>
4249 <t>
4250 <list>
4251 <t>SUBSCRIBE &lt;event-id&gt;</t>
4252 </list>
4253 </t>
4254 <t>where &lt;event-id&gt; will be replaced by the respective event that
4255 client wants to subscribe to.</t>
4256
4257 <t>Possible Answers:</t>
4258 <t>
4259 <list>
4260 <t>"OK" -
4261 <list>
4262 <t>on success</t>
4263 </list>
4264 </t>
4265 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4266 <list>
4267 <t>if registration succeeded, but there are noteworthy
4268 issue(s) related, providing an appropriate warning code and
4269 warning message</t>
4270 </list>
4271 </t>
4272 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4273 <list>
4274 <t>in case it failed, providing an appropriate error code and
4275 error message</t>
4276 </list>
4277 </t>
4278 </list>
4279 </t>
4280 <t>Examples:</t>
4281 <t>
4282 <list>
4283 <t></t>
4284 </list>
4285 </t>
4286 </section>
4287
4288 <section title="Unregister front-end for not receiving event messages" anchor="UNSUBSCRIBE" lscp_cmd="true">
4289 <t>The front-end can unregister itself if it doesn't want to receive event
4290 messages anymore by sending the following command:</t>
4291 <t>
4292 <list>
4293 <t>UNSUBSCRIBE &lt;event-id&gt;</t>
4294 </list>
4295 </t>
4296 <t>Where &lt;event-id&gt; will be replaced by the respective event that
4297 client doesn't want to receive anymore.</t>
4298
4299 <t>Possible Answers:</t>
4300 <t>
4301 <list>
4302 <t>"OK" -
4303 <list>
4304 <t>on success</t>
4305 </list>
4306 </t>
4307 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4308 <list>
4309 <t>if unregistration succeeded, but there are noteworthy
4310 issue(s) related, providing an appropriate warning code and
4311 warning message</t>
4312 </list>
4313 </t>
4314 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4315 <list>
4316 <t>in case it failed, providing an appropriate error code and
4317 error message</t>
4318 </list>
4319 </t>
4320 </list>
4321 </t>
4322 <t>Examples:</t>
4323 <t>
4324 <list>
4325 <t></t>
4326 </list>
4327 </t>
4328 </section>
4329
4330 <section title="Enable or disable echo of commands" anchor="SET ECHO" lscp_cmd="true">
4331 <t>To enable or disable back sending of commands to the client the following command can be used:</t>
4332 <t>
4333 <list>
4334 <t>SET ECHO &lt;value&gt;</t>
4335 </list>
4336 </t>
4337 <t>Where &lt;value&gt; should be replaced either by "1" to enable echo mode
4338 or "0" to disable echo mode. When echo mode is enabled, all
4339 commands send to LinuxSampler will be immediately send back and
4340 after this echo the actual response to the command will be
4341 returned. Echo mode will only be altered for the client connection
4342 that issued the "SET ECHO" command, not globally for all client
4343 connections.</t>
4344
4345 <t>Possible Answers:</t>
4346 <t>
4347 <list>
4348 <t>"OK" -
4349 <list>
4350 <t>usually</t>
4351 </list>
4352 </t>
4353 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4354 <list>
4355 <t>on syntax error, e.g. non boolean value</t>
4356 </list>
4357 </t>
4358 </list>
4359 </t>
4360 <t>Examples:</t>
4361 <t>
4362 <list>
4363 <t></t>
4364 </list>
4365 </t>
4366 </section>
4367
4368 <section title="Close client connection" anchor="QUIT" lscp_cmd="true">
4369 <t>The client can close its network connection to LinuxSampler by sending the following command:</t>
4370 <t>
4371 <list>
4372 <t>QUIT</t>
4373 </list>
4374 </t>
4375 <t>This is probably more interesting for manual telnet connections to
4376 LinuxSampler than really useful for a front-end implementation.</t>
4377 </section>
4378 </section>
4379
4380 <section title="Global commands">
4381 <t>The following commands have global impact on the sampler.</t>
4382
4383 <section title="Current number of active voices" anchor="GET TOTAL_VOICE_COUNT" lscp_cmd="true">
4384 <t>The front-end can ask for the current number of active voices on
4385 the sampler by sending the following command:</t>
4386 <t>
4387 <list>
4388 <t>GET TOTAL_VOICE_COUNT</t>
4389 </list>
4390 </t>
4391
4392 <t>Possible Answers:</t>
4393 <t>
4394 <list>
4395 <t>LinuxSampler will answer by returning the number of all active
4396 voices on the sampler.</t>
4397 </list>
4398 </t>
4399 </section>
4400
4401 <section title="Maximum amount of active voices" anchor="GET TOTAL_VOICE_COUNT_MAX" lscp_cmd="true">
4402 <t>The front-end can ask for the maximum number of active voices
4403 by sending the following command:</t>
4404 <t>
4405 <list>
4406 <t>GET TOTAL_VOICE_COUNT_MAX</t>
4407 </list>
4408 </t>
4409
4410 <t>Possible Answers:</t>
4411 <t>
4412 <list>
4413 <t>LinuxSampler will answer by returning the maximum number
4414 of active voices.</t>
4415 </list>
4416 </t>
4417 </section>
4418
4419 <section title="Current number of active disk streams" anchor="GET TOTAL_STREAM_COUNT" lscp_cmd="true">
4420 <t>The front-end can ask for the current number of active disk streams on
4421 the sampler by sending the following command:</t>
4422 <t>
4423 <list>
4424 <t>GET TOTAL_STREAM_COUNT</t>
4425 </list>
4426 </t>
4427
4428 <t>Possible Answers:</t>
4429 <t>
4430 <list>
4431 <t>LinuxSampler will answer by returning the number of all active
4432 disk streams on the sampler.</t>
4433 </list>
4434 </t>
4435 </section>
4436
4437 <section title="Reset sampler" anchor="RESET">
4438 <t>The front-end can reset the whole sampler by sending the following command:</t>
4439 <t>
4440 <list>
4441 <t>RESET</t>
4442 </list>
4443 </t>
4444
4445 <t>Possible Answers:</t>
4446 <t>
4447 <list>
4448 <t>"OK" -
4449 <list>
4450 <t>always</t>
4451 </list>
4452 </t>
4453 </list>
4454 </t>
4455 <t>Examples:</t>
4456 <t>
4457 <list>
4458 <t></t>
4459 </list>
4460 </t>
4461 </section>
4462
4463 <section title="General sampler information" anchor="GET SERVER INFO" lscp_cmd="true">
4464 <t>The client can ask for general information about the LinuxSampler
4465 instance by sending the following command:</t>
4466 <t>
4467 <list>
4468 <t>GET SERVER INFO</t>
4469 </list>
4470 </t>
4471 <t>Possible Answers:</t>
4472 <t>
4473 <list>
4474 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
4475 Each answer line begins with the information category name
4476 followed by a colon and then a space character &lt;SP&gt; and finally
4477 the info character string to that information category. At the
4478 moment the following categories are defined:
4479 </t>
4480 <t>
4481 <list>
4482 <t>DESCRIPTION -
4483 <list>
4484 <t>arbitrary textual description about the sampler
4485 (note that the character string may contain
4486 <xref target="character_set">escape sequences</xref>)</t>
4487 </list>
4488 </t>
4489 <t>VERSION -
4490 <list>
4491 <t>version of the sampler</t>
4492 </list>
4493 </t>
4494 <t>PROTOCOL_VERSION -
4495 <list>
4496 <t>version of the LSCP specification the sampler
4497 complies with (see <xref target="LSCP versioning" /> for details)</t>
4498 </list>
4499 </t>
4500 <t>INSTRUMENTS_DB_SUPPORT -
4501 <list>
4502 <t>either yes or no, specifies whether the
4503 sampler is build with instruments database support.</t>
4504 </list>
4505 </t>
4506 </list>
4507 </t>
4508 </list>
4509 </t>
4510 <t>The mentioned fields above don't have to be in particular order.
4511 Other fields might be added in future.</t>
4512
4513 <t>Example:</t>
4514 <t>
4515 <list>
4516 <t>C: "GET SERVER INFO"</t>
4517 <t>S: "DESCRIPTION: LinuxSampler - modular, streaming capable sampler"</t>
4518 <t>&nbsp;&nbsp;&nbsp;"VERSION: 1.0.0.svn23"</t>
4519 <t>&nbsp;&nbsp;&nbsp;"PROTOCOL_VERSION: 1.5"</t>
4520 <t>&nbsp;&nbsp;&nbsp;"INSTRUMENTS_DB_SUPPORT: no"</t>
4521 <t>&nbsp;&nbsp;&nbsp;"."</t>
4522 </list>
4523 </t>
4524 </section>
4525
4526 <section title="Getting global volume attenuation" anchor="GET VOLUME" lscp_cmd="true">
4527 <t>The client can ask for the current global sampler-wide volume
4528 attenuation by sending the following command:</t>
4529 <t>
4530 <list>
4531 <t>GET VOLUME</t>
4532 </list>
4533 </t>
4534 <t>Possible Answers:</t>
4535 <t>
4536 <list>
4537 <t>The sampler will always answer by returning the optional
4538 dotted floating point coefficient, reflecting the current
4539 global volume attenuation.
4540 </t>
4541 </list>
4542 </t>
4543 <t>Note: it is up to the respective sampler engine whether to obey
4544 that global volume parameter or not, but in general all engines SHOULD
4545 use this parameter.</t>
4546 </section>
4547
4548 <section title="Setting global volume attenuation" anchor="SET VOLUME" lscp_cmd="true">
4549 <t>The client can alter the current global sampler-wide volume
4550 attenuation by sending the following command:</t>
4551 <t>
4552 <list>
4553 <t>SET VOLUME &lt;volume&gt;</t>
4554 </list>
4555 </t>
4556 <t>Where &lt;volume&gt; should be replaced by the optional dotted
4557 floating point value, reflecting the new global volume parameter.
4558 This value might usually be in the range between 0.0 and 1.0, that
4559 is for attenuating the overall volume.</t>
4560
4561 <t>Possible Answers:</t>
4562 <t>
4563 <list>
4564 <t>"OK" -
4565 <list>
4566 <t>on success</t>
4567 </list>
4568 </t>
4569 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4570 <list>
4571 <t>if the global volume was set, but there are noteworthy
4572 issue(s) related, providing an appropriate warning code and
4573 warning message</t>
4574 </list>
4575 </t>
4576 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4577 <list>
4578 <t>in case it failed, providing an appropriate error code and error message</t>
4579 </list>
4580 </t>
4581 </list>
4582 </t>
4583 </section>
4584
4585 <section title="Getting global voice limit" anchor="GET VOICES" lscp_cmd="true">
4586 <t>The client can ask for the current global sampler-wide limit
4587 for maximum voices by sending the following command:</t>
4588 <t>
4589 <list>
4590 <t>GET VOICES</t>
4591 </list>
4592 </t>
4593 <t>Possible Answers:</t>
4594 <t>
4595 <list>
4596 <t>LinuxSampler will answer by returning the number for
4597 the current limit of maximum voices.</t>
4598 </list>
4599 </t>
4600
4601 <t>The voice limit setting defines how many voices should maximum
4602 be processed by the sampler at the same time. If the user
4603 triggers new notes which would exceed that voice limit, the
4604 sampler engine will react by stealing old voices for those
4605 newly triggered notes. Note that the amount of voices triggered
4606 by a new note can be larger than one and is dependent to the
4607 respective instrument and probably further criterias.</t>
4608 </section>
4609
4610 <section title="Setting global voice limit" anchor="SET VOICES" lscp_cmd="true">
4611 <t>The client can alter the current global sampler-wide limit
4612 for maximum voices by sending the following command:</t>
4613 <t>
4614 <list>
4615 <t>SET VOICES &lt;max-voices&gt;</t>
4616 </list>
4617 </t>
4618 <t>Where &lt;max-voices&gt; should be replaced by the integer
4619 value, reflecting the new global amount limit of maximum voices.
4620 This value has to be larger than 0.</t>
4621
4622 <t>Possible Answers:</t>
4623 <t>
4624 <list>
4625 <t>"OK" -
4626 <list>
4627 <t>on success</t>
4628 </list>
4629 </t>
4630 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4631 <list>
4632 <t>if the voice limit was set, but there are noteworthy
4633 issue(s) related, providing an appropriate warning code and
4634 warning message</t>
4635 </list>
4636 </t>
4637 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4638 <list>
4639 <t>in case it failed, providing an appropriate error code and error message</t>
4640 </list>
4641 </t>
4642 </list>
4643 </t>
4644
4645 <t>Note: the given value will be passed to all sampler engine instances.
4646 The total amount of maximum voices on the running system might thus
4647 be as big as the given value multiplied by the current amount of engine
4648 instances.</t>
4649
4650 <t>Caution: when adjusting the voice limit, you SHOULD also
4651 adjust the disk stream limit respectively and vice versa.</t>
4652 </section>
4653
4654 <section title="Getting global disk stream limit" anchor="GET STREAMS" lscp_cmd="true">
4655 <t>The client can ask for the current global sampler-wide limit
4656 for maximum disk streams by sending the following command:</t>
4657 <t>
4658 <list>
4659 <t>GET STREAMS</t>
4660 </list>
4661 </t>
4662 <t>Possible Answers:</t>
4663 <t>
4664 <list>
4665 <t>LinuxSampler will answer by returning the number for
4666 the current limit of maximum disk streams.</t>
4667 </list>
4668 </t>
4669
4670 <t>The disk stream limit setting defines how many disk streams should
4671 maximum be processed by a sampler engine at the same time. The
4672 higher this value, the more memory (RAM) will be occupied, since
4673 every disk streams allocates a certain buffer size for being able
4674 to perform its streaming operations.</t>
4675 </section>
4676
4677 <section title="Setting global disk stream limit" anchor="SET STREAMS" lscp_cmd="true">
4678 <t>The client can alter the current global sampler-wide limit
4679 for maximum disk streams by sending the following command:</t>
4680 <t>
4681 <list>
4682 <t>SET STREAMS &lt;max-streams&gt;</t>
4683 </list>
4684 </t>
4685 <t>Where &lt;max-streams&gt; should be replaced by the integer
4686 value, reflecting the new global amount limit of maximum disk streams.
4687 This value has to be positive.</t>
4688
4689 <t>Possible Answers:</t>
4690 <t>
4691 <list>
4692 <t>"OK" -
4693 <list>
4694 <t>on success</t>
4695 </list>
4696 </t>
4697 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4698 <list>
4699 <t>if the disk stream limit was set, but there are noteworthy
4700 issue(s) related, providing an appropriate warning code and
4701 warning message</t>
4702 </list>
4703 </t>
4704 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4705 <list>
4706 <t>in case it failed, providing an appropriate error code and error message</t>
4707 </list>
4708 </t>
4709 </list>
4710 </t>
4711
4712 <t>Note: the given value will be passed to all sampler engine instances.
4713 The total amount of maximum disk streams on the running system might
4714 thus be as big as the given value multiplied by the current amount of
4715 engine instances.</t>
4716
4717 <t>Caution: when adjusting the disk stream limit, you SHOULD also
4718 adjust the voice limit respectively and vice versa.</t>
4719 </section>
4720
4721 </section>
4722
4723
4724 <section title="MIDI Instrument Mapping" anchor="MIDI Instrument Mapping">
4725 <t>The MIDI protocol provides a way to switch between instruments
4726 by sending so called MIDI bank select and MIDI program change
4727 messages which are essentially just numbers. The following commands
4728 allow to actually map arbitrary MIDI bank select / program change
4729 numbers with real instruments.</t>
4730 <t>The sampler allows to manage an arbitrary amount of MIDI
4731 instrument maps which define which instrument to load on
4732 which MIDI program change message.</t>
4733 <t>By default, that is when the sampler is launched, there is no
4734 map, thus the sampler will simply ignore all program change
4735 messages. The front-end has to explicitly create at least one
4736 map, add entries to the map and tell the respective sampler
4737 channel(s) which MIDI instrument map to use, so the sampler
4738 knows how to react on a given program change message on the
4739 respective sampler channel, that is by switching to the
4740 respectively defined engine type and loading the respective
4741 instrument. See command
4742 <xref target="SET CHANNEL MIDI_INSTRUMENT_MAP">"SET CHANNEL MIDI_INSTRUMENT_MAP"</xref>
4743 for how to assign a MIDI instrument map to a sampler channel.</t>
4744 <t>Also note per MIDI specification a bank select message does not
4745 cause to switch to another instrument. Instead when receiving a
4746 bank select message the bank value will be stored and a subsequent
4747 program change message (which may occur at any time) will finally
4748 cause the sampler to switch to the respective instrument as
4749 reflected by the current MIDI instrument map.</t>
4750
4751 <section title="Create a new MIDI instrument map" anchor="ADD MIDI_INSTRUMENT_MAP" lscp_cmd="true">
4752 <t>The front-end can add a new MIDI instrument map by sending
4753 the following command:</t>
4754 <t>
4755 <list>
4756 <t>ADD MIDI_INSTRUMENT_MAP [&lt;name&gt;]</t>
4757 </list>
4758 </t>
4759 <t>Where &lt;name&gt; is an optional argument allowing to
4760 assign a custom name to the new map. MIDI instrument Map
4761 names do not have to be unique, but MUST be encapsulated
4762 into apostrophes and support escape sequences as described
4763 in chapter "<xref target="character_set">Character Set and Escape Sequences</xref>".
4764 </t>
4765
4766 <t>Possible Answers:</t>
4767 <t>
4768 <list>
4769 <t>"OK[&lt;map&gt;]" -
4770 <list>
4771 <t>in case a new MIDI instrument map could
4772 be added, where &lt;map&gt; reflects the
4773 unique ID of the newly created MIDI
4774 instrument map</t>
4775 </list>
4776 </t>
4777 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4778 <list>
4779 <t>when a new map could not be created, which
4780 might never occur in practice</t>
4781 </list>
4782 </t>
4783 </list>
4784 </t>
4785
4786 <t>Examples:</t>
4787 <t>
4788 <list>
4789 <t>C: "ADD MIDI_INSTRUMENT_MAP 'Standard Map'"</t>
4790 <t>S: "OK[0]"</t>
4791 </list>
4792 </t>
4793 <t>
4794 <list>
4795 <t>C: "ADD MIDI_INSTRUMENT_MAP 'Standard Drumkit'"</t>
4796 <t>S: "OK[1]"</t>
4797 </list>
4798 </t>
4799 <t>
4800 <list>
4801 <t>C: "ADD MIDI_INSTRUMENT_MAP"</t>
4802 <t>S: "OK[5]"</t>
4803 </list>
4804 </t>
4805 </section>
4806
4807 <section title="Delete one particular or all MIDI instrument maps" anchor="REMOVE MIDI_INSTRUMENT_MAP" lscp_cmd="true">
4808 <t>The front-end can delete a particular MIDI instrument map
4809 by sending the following command:</t>
4810 <t>
4811 <list>
4812 <t>REMOVE MIDI_INSTRUMENT_MAP &lt;map&gt;</t>
4813 </list>
4814 </t>
4815 <t>Where &lt;map&gt; reflects the unique ID of the map to delete
4816 as returned by the <xref target="LIST MIDI_INSTRUMENT_MAPS">"LIST MIDI_INSTRUMENT_MAPS"</xref>
4817 command.</t>
4818 <t>The front-end can delete all MIDI instrument maps by
4819 sending the following command:</t>
4820 <t>
4821 <list>
4822 <t>REMOVE MIDI_INSTRUMENT_MAP ALL</t>
4823 </list>
4824 </t>
4825
4826 <t>Possible Answers:</t>
4827 <t>
4828 <list>
4829 <t>"OK" -
4830 <list>
4831 <t>in case the map(s) could be deleted</t>
4832 </list>
4833 </t>
4834 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4835 <list>
4836 <t>when the given map does not exist</t>
4837 </list>
4838 </t>
4839 </list>
4840 </t>
4841
4842 <t>Examples:</t>
4843 <t>
4844 <list>
4845 <t>C: "REMOVE MIDI_INSTRUMENT_MAP 0"</t>
4846 <t>S: "OK"</t>
4847 </list>
4848 </t>
4849 <t>
4850 <list>
4851 <t>C: "REMOVE MIDI_INSTRUMENT_MAP ALL"</t>
4852 <t>S: "OK"</t>
4853 </list>
4854 </t>
4855 </section>
4856
4857 <section title="Get amount of existing MIDI instrument maps" anchor="GET MIDI_INSTRUMENT_MAPS" lscp_cmd="true">
4858 <t>The front-end can retrieve the current amount of MIDI
4859 instrument maps by sending the following command:</t>
4860 <t>
4861 <list>
4862 <t>GET MIDI_INSTRUMENT_MAPS</t>
4863 </list>
4864 </t>
4865
4866 <t>Possible Answers:</t>
4867 <t>
4868 <list>
4869 <t>The sampler will answer by returning the current
4870 number of MIDI instrument maps.</t>
4871 </list>
4872 </t>
4873
4874 <t>Example:</t>
4875 <t>
4876 <list>
4877 <t>C: "GET MIDI_INSTRUMENT_MAPS"</t>
4878 <t>S: "2"</t>
4879 </list>
4880 </t>
4881 </section>
4882
4883 <section title="Getting all created MIDI instrument maps" anchor="LIST MIDI_INSTRUMENT_MAPS" lscp_cmd="true">
4884 <t>The number of MIDI instrument maps can change on runtime. To get the
4885 current list of MIDI instrument maps, the front-end can send the
4886 following command:</t>
4887 <t>
4888 <list>
4889 <t>LIST MIDI_INSTRUMENT_MAPS</t>
4890 </list>
4891 </t>
4892 <t>Possible Answers:</t>
4893 <t>
4894 <list>
4895 <t>The sampler will answer by returning a comma separated list
4896 with all MIDI instrument maps' numerical IDs.</t>
4897 </list>
4898 </t>
4899 <t>Example:</t>
4900 <t>
4901 <list>
4902 <t>C: "LIST MIDI_INSTRUMENT_MAPS"</t>
4903 <t>S: "0,1,5,12"</t>
4904 </list>
4905 </t>
4906 </section>
4907
4908 <section title="Getting MIDI instrument map information" anchor="GET MIDI_INSTRUMENT_MAP INFO" lscp_cmd="true">
4909 <t>The front-end can ask for the current settings of a MIDI
4910 instrument map by sending the following command:</t>
4911 <t>
4912 <list>
4913 <t>GET MIDI_INSTRUMENT_MAP INFO &lt;map&gt;</t>
4914 </list>
4915 </t>
4916 <t>Where &lt;map&gt; is the numerical ID of the map the
4917 front-end is interested in as returned by the
4918 <xref target="LIST MIDI_INSTRUMENT_MAPS">"LIST MIDI_INSTRUMENT_MAPS"</xref>
4919 command.</t>
4920
4921 <t>Possible Answers:</t>
4922 <t>
4923 <list>
4924 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
4925 Each answer line begins with the settings category name
4926 followed by a colon and then a space character &lt;SP&gt; and finally
4927 the info character string to that setting category. At the
4928 moment the following categories are defined:</t>
4929
4930 <t>
4931 <list>
4932 <t>NAME -
4933 <list>
4934 <t>custom name of the given map,
4935 which does not have to be unique
4936 (note that this character string may contain
4937 <xref target="character_set">escape sequences</xref>)</t>
4938 </list>
4939 </t>
4940 <t>DEFAULT -
4941 <list>
4942 <t>either true or false,
4943 defines whether this map is the default map</t>
4944 </list>
4945 </t>
4946 </list>
4947 </t>
4948 </list>
4949 </t>
4950 <t>The mentioned fields above don't have to be in particular order.</t>
4951
4952 <t>Example:</t>
4953 <t>
4954 <list>
4955 <t>C: "GET MIDI_INSTRUMENT_MAP INFO 0"</t>
4956 <t>S: "NAME: Standard Map"</t>
4957 <t>&nbsp;&nbsp;&nbsp;"DEFAULT: true"</t>
4958 <t>&nbsp;&nbsp;&nbsp;"."</t>
4959 </list>
4960 </t>
4961 </section>
4962
4963 <section title="Renaming a MIDI instrument map" anchor="SET MIDI_INSTRUMENT_MAP NAME" lscp_cmd="true">
4964 <t>The front-end can alter the custom name of a MIDI
4965 instrument map by sending the following command:</t>
4966 <t>
4967 <list>
4968 <t>SET MIDI_INSTRUMENT_MAP NAME &lt;map&gt; &lt;name&gt;</t>
4969 </list>
4970 </t>
4971 <t>Where &lt;map&gt; is the numerical ID of the map and
4972 &lt;name&gt; the new custom name of the map, which does not
4973 have to be unique (name MUST be encapsulated into apostrophes
4974 and supports escape sequences as described in chapter
4975 "<xref target="character_set">Character Set and Escape Sequences</xref>").
4976 </t>
4977
4978 <t>Possible Answers:</t>
4979 <t>
4980 <list>
4981 <t>"OK" -
4982 <list>
4983 <t>on success</t>
4984 </list>
4985 </t>
4986 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4987 <list>
4988 <t>in case the given map does not exist</t>
4989 </list>
4990 </t>
4991 </list>
4992 </t>
4993
4994 <t>Example:</t>
4995 <t>
4996 <list>
4997 <t>C: "SET MIDI_INSTRUMENT_MAP NAME 0 'Foo instruments'"</t>
4998 <t>S: "OK"</t>
4999 </list>
5000 </t>
5001 </section>
5002
5003 <section title="Create or replace a MIDI instrument map entry" anchor="MAP MIDI_INSTRUMENT" lscp_cmd="true">
5004 <t>The front-end can create a new or replace an existing entry
5005 in a sampler's MIDI instrument map by sending the following
5006 command:</t>
5007 <t>
5008 <list>
5009 <t>MAP MIDI_INSTRUMENT [NON_MODAL] &lt;map&gt;
5010 &lt;midi_bank&gt; &lt;midi_prog&gt; &lt;engine_name&gt;
5011 &lt;filename&gt; &lt;instrument_index&gt; &lt;volume_value&gt;
5012 [&lt;instr_load_mode&gt;] [&lt;name&gt;]</t>
5013 </list>
5014 </t>
5015 <t>Where &lt;map&gt; is the numeric ID of the map to alter,
5016 &lt;midi_bank&gt; is an integer value between
5017 0..16383 reflecting the MIDI bank select index,
5018 &lt;midi_prog&gt; an
5019 integer value between 0..127 reflecting the MIDI program change
5020 index, &lt;engine_name&gt; a sampler engine name as returned by
5021 the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>
5022 command (not encapsulated into apostrophes), &lt;filename&gt; the name
5023 of the instrument's file to be deployed (encapsulated into apostrophes,
5024 supporting escape sequences as described in chapter
5025 "<xref target="character_set">Character Set and Escape Sequences</xref>"),
5026 &lt;instrument_index&gt; the index (integer value) of the instrument
5027 within the given file, &lt;volume_value&gt; reflects the master
5028 volume of the instrument as optionally dotted number (where a
5029 value &lt; 1.0 means attenuation and a value > 1.0 means
5030 amplification). This parameter easily allows to adjust the
5031 volume of all intruments within a custom instrument map
5032 without having to adjust their instrument files. The
5033 OPTIONAL &lt;instr_load_mode&gt; argument defines the life
5034 time of the instrument, that is when the instrument should
5035 be loaded, when freed and has exactly the following
5036 possibilities:</t>
5037 <t>
5038 <list>
5039 <t>"ON_DEMAND" -
5040 <list>
5041 <t>The instrument will be loaded when needed,
5042 that is when demanded by at least one sampler
5043 channel. It will immediately be freed from memory
5044 when not needed by any sampler channel anymore.</t>
5045 </list>
5046 </t>
5047 <t>"ON_DEMAND_HOLD" -
5048 <list>
5049 <t>The instrument will be loaded when needed,
5050 that is when demanded by at least one sampler
5051 channel. It will be kept in memory even when
5052 not needed by any sampler channel anymore.
5053 Instruments with this mode are only freed
5054 when the sampler is reset or all mapping
5055 entries with this mode (and respective
5056 instrument) are explicitly changed to
5057 "ON_DEMAND" and no sampler channel is using
5058 the instrument anymore.</t>
5059 </list>
5060 </t>
5061 <t>"PERSISTENT" -
5062 <list>
5063 <t>The instrument will immediately be loaded
5064 into memory when this mapping
5065 command is sent and the instrument is kept all
5066 the time. Instruments with this mode are
5067 only freed when the sampler is reset or all
5068 mapping entries with this mode (and
5069 respective instrument) are explicitly
5070 changed to "ON_DEMAND" and no sampler
5071 channel is using the instrument anymore.</t>
5072 </list>
5073 </t>
5074 <t>not supplied -
5075 <list>
5076 <t>In case there is no &lt;instr_load_mode&gt;
5077 argument given, it will be up to the
5078 InstrumentManager to decide which mode to use.
5079 Usually it will use "ON_DEMAND" if an entry
5080 for the given instrument does not exist in
5081 the InstrumentManager's list yet, otherwise
5082 if an entry already exists, it will simply
5083 stick with the mode currently reflected by
5084 the already existing entry, that is it will
5085 not change the mode.</t>
5086 </list>
5087 </t>
5088 </list>
5089 </t>
5090 <t>
5091 The &lt;instr_load_mode&gt; argument thus allows to define an
5092 appropriate strategy (low memory consumption vs. fast
5093 instrument switching) for each instrument individually. Note, the
5094 following restrictions apply to this argument: "ON_DEMAND_HOLD" and
5095 "PERSISTENT" have to be supported by the respective sampler engine
5096 (which is technically the case when the engine provides an
5097 InstrumentManager for its format). If this is not the case the
5098 argument will automatically fall back to the default value
5099 "ON_DEMAND". Also the load mode of one instrument may
5100 automatically change the laod mode of other instrument(s), i.e.
5101 because the instruments are part of the same file and the
5102 engine does not allow a way to manage load modes for them
5103 individually. Due to this, in case the frontend shows the
5104 load modes of entries, the frontend should retrieve the actual
5105 mode by i.e. sending
5106 <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>
5107 command(s). Finally the OPTIONAL &lt;name&gt; argument allows to set a custom name
5108 (encapsulated into apostrophes, supporting escape sequences as described in chapter
5109 "<xref target="character_set">Character Set and Escape Sequences</xref>") for the
5110 mapping entry, useful for frontends for displaying an appropriate name for
5111 mapped instruments (using
5112 <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).
5113 </t>
5114 <t>
5115 By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is
5116 completely established in the sampler. The OPTIONAL "NON_MODAL" argument
5117 however causes the respective "MAP MIDI_INSTRUMENT" command to return
5118 immediately, that is to let the sampler establish the mapping in the
5119 background. So this argument might be especially useful for mappings with
5120 a "PERSISTENT" type, because these have to load the respective instruments
5121 immediately and might thus block for a very long time. It is recommended
5122 however to use the OPTIONAL "NON_MODAL" argument only if really necessary,
5123 because it has the following drawbacks: as "NON_MODAL" instructions return
5124 immediately, they may not necessarily return an error i.e. when the given
5125 instrument file turns out to be corrupt, beside that subsequent commands
5126 in a LSCP instruction sequence might fail, because mandatory mappings are
5127 not yet completed.
5128 </t>
5129
5130 <t>Possible Answers:</t>
5131 <t>
5132 <list>
5133 <t>"OK" -
5134 <list>
5135 <t>usually</t>
5136 </list>
5137 </t>
5138 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5139 <list>
5140 <t>when the given map or engine does not exist or a value
5141 is out of range</t>
5142 </list>
5143 </t>
5144 </list>
5145 </t>
5146
5147 <t>Examples:</t>
5148 <t>
5149 <list>
5150 <t>C: "MAP MIDI_INSTRUMENT 0 3 0 gig '/usr/share/Steinway D.gig' 0 0.8 PERSISTENT"</t>
5151 <t>S: "OK"</t>
5152 </list>
5153 </t>
5154 <t>
5155 <list>
5156 <t>C: "MAP MIDI_INSTRUMENT 0 4 50 gig '/home/john/foostrings.gig' 7 1.0"</t>
5157 <t>S: "OK"</t>
5158 </list>
5159 </t>
5160 <t>
5161 <list>
5162 <t>C: "MAP MIDI_INSTRUMENT 0 0 0 gig '/usr/share/piano.gig' 0 1.0 'Normal Piano'"</t>
5163 <t>S: "OK"</t>
5164 <t>C: "MAP MIDI_INSTRUMENT 0 1 0 gig '/usr/share/piano.gig' 0 0.25 'Silent Piano'"</t>
5165 <t>S: "OK"</t>
5166 </list>
5167 </t>
5168 <t>
5169 <list>
5170 <t>C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"</t>
5171 <t>S: "OK"</t>
5172 </list>
5173 </t>
5174 </section>
5175
5176 <section title="Getting amount of MIDI instrument map entries" anchor="GET MIDI_INSTRUMENTS" lscp_cmd="true">
5177 <t>The front-end can query the amount of currently existing
5178 entries in a MIDI instrument map by sending the following
5179 command:</t>
5180 <t>
5181 <list>
5182 <t>GET MIDI_INSTRUMENTS &lt;map&gt;</t>
5183 </list>
5184 </t>
5185 <t>The front-end can query the amount of currently existing
5186 entries in all MIDI instrument maps by sending the following
5187 command:</t>
5188 <t>
5189 <list>
5190 <t>GET MIDI_INSTRUMENTS ALL</t>
5191 </list>
5192 </t>
5193 <t>Possible Answers:</t>
5194 <t>
5195 <list>
5196 <t>The sampler will answer by sending the current number of
5197 entries in the MIDI instrument map(s).</t>
5198 </list>
5199 </t>
5200
5201 <t>Example:</t>
5202 <t>
5203 <list>
5204 <t>C: "GET MIDI_INSTRUMENTS 0"</t>
5205 <t>S: "234"</t>
5206 </list>
5207 </t>
5208 <t>
5209 <list>
5210 <t>C: "GET MIDI_INSTRUMENTS ALL"</t>
5211 <t>S: "954"</t>
5212 </list>
5213 </t>
5214 </section>
5215
5216 <section title="Getting indeces of all entries of a MIDI instrument map" anchor="LIST MIDI_INSTRUMENTS" lscp_cmd="true">
5217 <t>The front-end can query a list of all currently existing
5218 entries in a certain MIDI instrument map by sending the following
5219 command:</t>
5220 <t>
5221 <list>
5222 <t>LIST MIDI_INSTRUMENTS &lt;map&gt;</t>
5223 </list>
5224 </t>
5225 <t>Where &lt;map&gt; is the numeric ID of the MIDI instrument map.</t>
5226 <t>The front-end can query a list of all currently existing
5227 entries of all MIDI instrument maps by sending the following
5228 command:</t>
5229 <t>
5230 <list>
5231 <t>LIST MIDI_INSTRUMENTS ALL</t>
5232 </list>
5233 </t>
5234
5235 <t>Possible Answers:</t>
5236 <t>
5237 <list>
5238 <t>The sampler will answer by sending a comma separated
5239 list of map ID - MIDI bank - MIDI program triples, where
5240 each triple is encapsulated into curly braces. The
5241 list is returned in one single line. Each triple
5242 just reflects the key of the respective map entry,
5243 thus subsequent
5244 <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>
5245 command(s) are necessary to retrieve detailed information
5246 about each entry.</t>
5247 </list>
5248 </t>
5249
5250 <t>Example:</t>
5251 <t>
5252 <list>
5253 <t>C: "LIST MIDI_INSTRUMENTS 0"</t>
5254 <t>S: "{0,0,0},{0,0,1},{0,0,3},{0,1,4},{1,127,127}"</t>
5255 </list>
5256 </t>
5257 </section>
5258
5259 <section title="Remove an entry from the MIDI instrument map" anchor="UNMAP MIDI_INSTRUMENT" lscp_cmd="true">
5260 <t>The front-end can delete an entry from a MIDI instrument
5261 map by sending the following command:</t>
5262 <t>
5263 <list>
5264 <t>UNMAP MIDI_INSTRUMENT &lt;map&gt; &lt;midi_bank&gt; &lt;midi_prog&gt;</t>
5265 </list>
5266 </t>
5267 <t>
5268 Where &lt;map&gt; is the numeric ID of the MIDI instrument map,
5269 &lt;midi_bank&gt; is an integer value between 0..16383
5270 reflecting the MIDI bank value and
5271 &lt;midi_prog&gt; an integer value between
5272 0..127 reflecting the MIDI program value of the map's entrie's key
5273 index triple.
5274 </t>
5275
5276 <t>Possible Answers:</t>
5277 <t>
5278 <list>
5279 <t>"OK" -
5280 <list>
5281 <t>usually</t>
5282 </list>
5283 </t>
5284 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5285 <list>
5286 <t>when index out of bounds</t>
5287 </list>
5288 </t>
5289 </list>
5290 </t>
5291
5292 <t>Example:</t>
5293 <t>
5294 <list>
5295 <t>C: "UNMAP MIDI_INSTRUMENT 0 2 127"</t>
5296 <t>S: "OK"</t>
5297 </list>
5298 </t>
5299 </section>
5300
5301 <section title="Get current settings of MIDI instrument map entry" anchor="GET MIDI_INSTRUMENT INFO" lscp_cmd="true">
5302 <t>The front-end can retrieve the current settings of a certain
5303 instrument map entry by sending the following command:</t>
5304 <t>
5305 <list>
5306 <t>GET MIDI_INSTRUMENT INFO &lt;map&gt; &lt;midi_bank&gt; &lt;midi_prog&gt;</t>
5307 </list>
5308 </t>
5309 <t>
5310 Where &lt;map&gt; is the numeric ID of the MIDI instrument map,
5311 &lt;midi_bank&gt; is an integer value between 0..16383
5312 reflecting the MIDI bank value, &lt;midi_bank&gt;
5313 and &lt;midi_prog&gt; an integer value between
5314 0..127 reflecting the MIDI program value of the map's entrie's key
5315 index triple.
5316 </t>
5317
5318 <t>Possible Answers:</t>
5319 <t>
5320 <list>
5321 <t>LinuxSampler will answer by sending a &lt;CRLF&gt;
5322 separated list. Each answer line begins with the
5323 information category name followed by a colon and then
5324 a space character &lt;SP&gt; and finally the info
5325 character string to that info category. At the moment
5326 the following categories are defined:</t>
5327 <t>"NAME" -
5328 <list>
5329 <t>Name for this MIDI instrument map entry (if defined).
5330 This name shall be used by frontends for displaying a
5331 name for this mapped instrument. It can be set and
5332 changed with the
5333 <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref>
5334 command and does not have to be unique.
5335 (note that this character string may contain
5336 <xref target="character_set">escape sequences</xref>)</t>
5337 </list>
5338 </t>
5339 <t>"ENGINE_NAME" -
5340 <list>
5341 <t>Name of the engine to be deployed for this
5342 instrument.</t>
5343 </list>
5344 </t>
5345 <t>"INSTRUMENT_FILE" -
5346 <list>
5347 <t>File name of the instrument
5348 (note that this path may contain
5349 <xref target="character_set">escape sequences</xref>).</t>
5350 </list>
5351 </t>
5352 <t>"INSTRUMENT_NR" -
5353 <list>
5354 <t>Index of the instrument within the file.</t>
5355 </list>
5356 </t>
5357 <t>"INSTRUMENT_NAME" -
5358 <list>
5359 <t>Name of the loaded instrument as reflected by its file.
5360 In contrast to the "NAME" field, the "INSTRUMENT_NAME" field
5361 cannot be changed (note that this character string may contain
5362 <xref target="character_set">escape sequences</xref>).</t>
5363 </list>
5364 </t>
5365 <t>"LOAD_MODE" -
5366 <list>
5367 <t>Life time of instrument
5368 (see <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref> for details about this setting).</t>
5369 </list>
5370 </t>
5371 <t>"VOLUME" -
5372 <list>
5373 <t>master volume of the instrument as optionally
5374 dotted number (where a value &lt; 1.0 means attenuation
5375 and a value > 1.0 means amplification)</t>
5376 </list>
5377 </t>
5378 <t>The mentioned fields above don't have to be in particular order.</t>
5379 </list>
5380 </t>
5381
5382 <t>Example:</t>
5383 <t>
5384 <list>
5385 <t>C: "GET MIDI_INSTRUMENT INFO 1 45 120"</t>
5386 <t>S: "NAME: Drums for Foo Song"</t>
5387 <t>&nbsp;&nbsp;&nbsp;"ENGINE_NAME: GigEngine"</t>
5388 <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_FILE: /usr/share/joesdrumkit.gig"</t>
5389 <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"</t>
5390 <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NAME: Joe's Drumkit"</t>
5391 <t>&nbsp;&nbsp;&nbsp;"LOAD_MODE: PERSISTENT"</t>
5392 <t>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"</t>
5393 <t>&nbsp;&nbsp;&nbsp;"."</t>
5394 </list>
5395 </t>
5396 </section>
5397
5398 <section title="Clear MIDI instrument map" anchor="CLEAR MIDI_INSTRUMENTS" lscp_cmd="true">
5399 <t>The front-end can clear a whole MIDI instrument map, that
5400 is delete all its entries by sending the following command:</t>
5401 <t>
5402 <list>
5403 <t>CLEAR MIDI_INSTRUMENTS &lt;map&gt;</t>
5404 </list>
5405 </t>
5406 <t>Where &lt;map&gt; is the numeric ID of the map to clear.</t>
5407 <t>The front-end can clear all MIDI instrument maps, that
5408 is delete all entries of all maps by sending the following
5409 command:</t>
5410 <t>
5411 <list>
5412 <t>CLEAR MIDI_INSTRUMENTS ALL</t>
5413 </list>
5414 </t>
5415 <t>The command "CLEAR MIDI_INSTRUMENTS ALL" does not delete the
5416 maps, only their entries, thus the map's settings like
5417 custom name will be preservevd.</t>
5418
5419 <t>Possible Answers:</t>
5420 <t>
5421 <list>
5422 <t>"OK" -
5423 <list>
5424 <t>always</t>
5425 </list>
5426 </t>
5427 </list>
5428 </t>
5429
5430 <t>Examples:</t>
5431 <t>
5432 <list>
5433 <t>C: "CLEAR MIDI_INSTRUMENTS 0"</t>
5434 <t>S: "OK"</t>
5435 </list>
5436 </t>
5437 <t>
5438 <list>
5439 <t>C: "CLEAR MIDI_INSTRUMENTS ALL"</t>
5440 <t>S: "OK"</t>
5441 </list>
5442 </t>
5443 </section>
5444 </section>
5445
5446
5447 <section title="Managing Instruments Database" anchor="Managing Instruments Database">
5448 <t>The following commands describe how to use and manage
5449 the instruments database.</t>
5450 <t>Notice:</t>
5451 <t>
5452 <list>
5453 <t>All command arguments representing a path or
5454 instrument/directory name support escape sequences as described in chapter
5455 "<xref target="character_set">Character Set and Escape Sequences</xref>".
5456 </t>
5457 <t>All occurrences of a forward slash in instrument and directory
5458 names are escaped with its hex (\x2f) or octal (\057) escape sequence.
5459 </t>
5460 </list>
5461 </t>
5462
5463 <section title="Creating a new instrument directory" anchor="ADD DB_INSTRUMENT_DIRECTORY" lscp_cmd="true">
5464 <t>The front-end can add a new instrument directory to the
5465 instruments database by sending the following command:</t>
5466 <t>
5467 <list>
5468 <t>ADD DB_INSTRUMENT_DIRECTORY &lt;dir&gt;</t>
5469 </list>
5470 </t>
5471 <t>Where &lt;dir&gt; is the absolute path name of the directory
5472 to be created (encapsulated into apostrophes).</t>
5473
5474 <t>Possible Answers:</t>
5475 <t>
5476 <list>
5477 <t>"OK" -
5478 <list>
5479 <t>on success</t>
5480 </list>
5481 </t>
5482 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5483 <list>
5484 <t>when the directory could not be created, which
5485 can happen if the directory already exists or the
5486 name contains not allowed symbols</t>
5487 </list>
5488 </t>
5489 </list>
5490 </t>
5491
5492 <t>Examples:</t>
5493 <t>
5494 <list>
5495 <t>C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'"</t>
5496 <t>S: "OK"</t>
5497 </list>
5498 </t>
5499 </section>
5500
5501 <section title="Deleting an instrument directory" anchor="REMOVE DB_INSTRUMENT_DIRECTORY" lscp_cmd="true">
5502 <t>The front-end can delete a particular instrument directory
5503 from the instruments database by sending the following command:</t>
5504 <t>
5505 <list>
5506 <t>REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] &lt;dir&gt;</t>
5507 </list>
5508 </t>
5509 <t>Where &lt;dir&gt; is the absolute path name of the directory
5510 to delete. The optional FORCE argument can be used to
5511 force the deletion of a non-empty directory and all its content.</t>
5512
5513 <t>Possible Answers:</t>
5514 <t>
5515 <list>
5516 <t>"OK" -
5517 <list>
5518 <t>if the directory is deleted successfully</t>
5519 </list>
5520 </t>
5521 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5522 <list>
5523 <t>if the given directory does not exist, or
5524 if trying to delete a non-empty directory,
5525 without using the FORCE argument.</t>
5526 </list>
5527 </t>
5528 </list>
5529 </t>
5530
5531 <t>Examples:</t>
5532 <t>
5533 <list>
5534 <t>C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'"</t>
5535 <t>S: "OK"</t>
5536 </list>
5537 </t>
5538 </section>
5539
5540 <section title="Getting amount of instrument directories" anchor="GET DB_INSTRUMENT_DIRECTORIES" lscp_cmd="true">
5541 <t>The front-end can retrieve the current amount of
5542 directories in a specific directory by sending the following command:</t>
5543 <t>
5544 <list>
5545 <t>GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
5546 </list>
5547 </t>
5548 <t>Where &lt;dir&gt; should be replaced by the absolute path
5549 name of the directory. If RECURSIVE is specified, the number of
5550 all directories, including those located in subdirectories of the
5551 specified directory, will be returned.</t>
5552
5553 <t>Possible Answers:</t>
5554 <t>
5555 <list>
5556 <t>The current number of instrument directories
5557 in the specified directory.</t>
5558 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5559 <list>
5560 <t>if the given directory does not exist.</t>
5561 </list>
5562 </t>
5563 </list>
5564 </t>
5565
5566 <t>Example:</t>
5567 <t>
5568 <list>
5569 <t>C: "GET DB_INSTRUMENT_DIRECTORIES '/'"</t>
5570 <t>S: "2"</t>
5571 </list>
5572 </t>
5573 </section>
5574
5575 <section title="Listing all directories in specific directory" anchor="LIST DB_INSTRUMENT_DIRECTORIES" lscp_cmd="true">
5576 <t>The front-end can retrieve the current list of directories
5577 in specific directory by sending the following command:</t>
5578 <t>
5579 <list>
5580 <t>LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
5581 </list>
5582 </t>
5583 <t>Where &lt;dir&gt; should be replaced by the absolute path
5584 name of the directory. If RECURSIVE is specified, the absolute path names
5585 of all directories, including those located in subdirectories of the
5586 specified directory, will be returned.</t>
5587
5588 <t>Possible Answers:</t>
5589 <t>
5590 <list>
5591 <t>A comma separated list of all instrument directories
5592 (encapsulated into apostrophes) in the specified directory.</t>
5593 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5594 <list>
5595 <t>if the given directory does not exist.</t>
5596 </list>
5597 </t>
5598 </list>
5599 </t>
5600 <t>Example:</t>
5601 <t>
5602 <list>
5603 <t>C: "LIST DB_INSTRUMENT_DIRECTORIES '/'"</t>
5604 <t>S: "'Piano Collection','Percussion Collection'"</t>
5605 </list>
5606 </t>
5607 <t>
5608 <list>
5609 <t>C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'"</t>
5610 <t>S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano Collection/Acoustic/New','/Percussion Collection'"</t>
5611 </list>
5612 </t>
5613 </section>
5614
5615 <section title="Getting instrument directory information" anchor="GET DB_INSTRUMENT_DIRECTORY INFO" lscp_cmd="true">
5616 <t>The front-end can ask for the current settings of an
5617 instrument directory by sending the following command:</t>
5618 <t>
5619 <list>
5620 <t>GET DB_INSTRUMENT_DIRECTORY INFO &lt;dir&gt;</t>
5621 </list>
5622 </t>
5623 <t>Where &lt;dir&gt; should be replaced by the absolute path
5624 name of the directory the front-end is interested in.</t>
5625
5626 <t>Possible Answers:</t>
5627 <t>
5628 <list>
5629 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
5630 Each answer line begins with the settings category name
5631 followed by a colon and then a space character &lt;SP&gt; and finally
5632 the info character string to that setting category. At the
5633 moment the following categories are defined:</t>
5634
5635 <t>
5636 <list>
5637 <t>DESCRIPTION -
5638 <list>
5639 <t>A brief description of the directory content.
5640 Note that the character string may contain
5641 <xref target="character_set">escape sequences</xref>.</t>
5642 </list>
5643 </t>
5644 <t>CREATED -
5645 <list>
5646 <t>The creation date and time of the directory,
5647 represented in "YYYY-MM-DD HH:MM:SS" format</t>
5648 </list>
5649 </t>
5650 <t>MODIFIED -
5651 <list>
5652 <t>The date and time of the last modification of the
5653 directory, represented in "YYYY-MM-DD HH:MM:SS" format</t>
5654 </list>
5655 </t>
5656 </list>
5657 </t>
5658 </list>
5659 </t>
5660 <t>The mentioned fields above don't have to be in particular order.</t>
5661
5662 <t>Example:</t>
5663 <t>
5664 <list>
5665 <t>C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'"</t>
5666 <t>S: "DESCRIPTION: Piano collection of instruments in GigaSampler format."</t>
5667 <t>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"</t>
5668 <t>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"</t>
5669 <t>&nbsp;&nbsp;&nbsp;"."</t>
5670 </list>
5671 </t>
5672 </section>
5673
5674 <section title="Renaming an instrument directory" anchor="SET DB_INSTRUMENT_DIRECTORY NAME" lscp_cmd="true">
5675 <t>The front-end can alter the name of a specific
5676 instrument directory by sending the following command:</t>
5677 <t>
5678 <list>
5679 <t>SET DB_INSTRUMENT_DIRECTORY NAME &lt;dir&gt; &lt;name&gt;</t>
5680 </list>
5681 </t>
5682 <t>Where &lt;dir&gt; is the absolute path name of the directory and
5683 &lt;name&gt; is the new name for that directory.</t>
5684
5685 <t>Possible Answers:</t>
5686 <t>
5687 <list>
5688 <t>"OK" -
5689 <list>
5690 <t>on success</t>
5691 </list>
5692 </t>
5693 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5694 <list>
5695 <t>in case the given directory does not exists,
5696 or if a directory with name equal to the new
5697 name already exists.</t>
5698 </list>
5699 </t>
5700 </list>
5701 </t>
5702
5703 <t>Example:</t>
5704 <t>
5705 <list>
5706 <t>C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic' 'Acoustic'"</t>
5707 <t>S: "OK"</t>
5708 </list>
5709 </t>
5710 </section>
5711
5712 <section title="Moving an instrument directory" anchor="MOVE DB_INSTRUMENT_DIRECTORY" lscp_cmd="true">
5713 <t>The front-end can move a specific
5714 instrument directory by sending the following command:</t>
5715 <t>
5716 <list>
5717 <t>MOVE DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
5718 </list>
5719 </t>
5720 <t>Where &lt;dir&gt; is the absolute path name of the directory
5721 to move and &lt;dst&gt; is the location where the directory will
5722 be moved to.</t>
5723
5724 <t>Possible Answers:</t>
5725 <t>
5726 <list>
5727 <t>"OK" -
5728 <list>
5729 <t>on success</t>
5730 </list>
5731 </t>
5732 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5733 <list>
5734 <t>in case a given directory does not exists,
5735 or if a directory with name equal to the name
5736 of the specified directory already exists in
5737 the destination directory. Error is also thrown
5738 when trying to move a directory to a subdirectory
5739 of itself.</t>
5740 </list>
5741 </t>
5742 </list>
5743 </t>
5744
5745 <t>Example:</t>
5746 <t>
5747 <list>
5748 <t>C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/Acoustic'"</t>
5749 <t>S: "OK"</t>
5750 </list>
5751 </t>
5752 </section>
5753
5754 <section title="Copying instrument directories" anchor="COPY DB_INSTRUMENT_DIRECTORY" lscp_cmd="true">
5755 <t>The front-end can copy a specific
5756 instrument directory by sending the following command:</t>
5757 <t>
5758 <list>
5759 <t>COPY DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
5760 </list>
5761 </t>
5762 <t>Where &lt;dir&gt; is the absolute path name of the directory
5763 to copy and &lt;dst&gt; is the location where the directory will
5764 be copied to.</t>
5765
5766 <t>Possible Answers:</t>
5767 <t>
5768 <list>
5769 <t>"OK" -
5770 <list>
5771 <t>on success</t>
5772 </list>
5773 </t>
5774 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5775 <list>
5776 <t>in case a given directory does not exists,
5777 or if a directory with name equal to the name
5778 of the specified directory already exists in
5779 the destination directory. Error is also thrown
5780 when trying to copy a directory to a subdirectory
5781 of itself.</t>
5782 </list>
5783 </t>
5784 </list>
5785 </t>
5786
5787 <t>Example:</t>
5788 <t>
5789 <list>
5790 <t>C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic' '/Acoustic/Pianos'"</t>
5791 <t>S: "OK"</t>
5792 </list>
5793 </t>
5794 </section>
5795
5796 <section title="Changing the description of directory" anchor="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION" lscp_cmd="true">
5797 <t>The front-end can alter the description of a specific
5798 instrument directory by sending the following command:</t>
5799 <t>
5800 <list>
5801 <t>SET DB_INSTRUMENT_DIRECTORY DESCRIPTION &lt;dir&gt; &lt;desc&gt;</t>
5802 </list>
5803 </t>
5804 <t>Where &lt;dir&gt; is the absolute path name of the directory and
5805 &lt;desc&gt; is the new description for the directory
5806 (encapsulated into apostrophes, supporting escape sequences as described in chapter
5807 "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5808
5809 <t>Possible Answers:</t>
5810 <t>
5811 <list>
5812 <t>"OK" -
5813 <list>
5814 <t>on success</t>
5815 </list>
5816 </t>
5817 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5818 <list>
5819 <t>in case the given directory does not exists.</t>
5820 </list>
5821 </t>
5822 </list>
5823 </t>
5824
5825 <t>Example:</t>
5826 <t>
5827 <list>
5828 <t>C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A collection of piano instruments in various format.'"</t>
5829 <t>S: "OK"</t>
5830 </list>
5831 </t>
5832 </section>
5833
5834 <section title="Finding directories" anchor="FIND DB_INSTRUMENT_DIRECTORIES" lscp_cmd="true">
5835 <t>The front-end can search for directories
5836 in specific directory by sending the following command:</t>
5837 <t>
5838 <list>
5839 <t>FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
5840 </list>
5841 </t>
5842 <t>Where &lt;dir&gt; should be replaced by the absolute path
5843 name of the directory to search in. If NON_RECURSIVE is specified, the
5844 directories located in subdirectories of the specified directory will not
5845 be searched. &lt;criteria-list&gt; is a list of search criterias
5846 in form of "key1=val1 key2=val2 ...". The following criterias are
5847 allowed:</t>
5848 <t>
5849 <t>NAME='&lt;search-string&gt;'
5850 <list>
5851 <t>Restricts the search to directories, which names
5852 satisfy the supplied search string (encapsulated into apostrophes,
5853 supporting escape sequences as described in chapter
5854 "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5855 </list>
5856 </t>
5857
5858 <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5859 <list>
5860 <t>Restricts the search to directories, which creation
5861 date satisfies the specified period, where &lt;date-after&gt;
5862 and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
5863 If &lt;date-after&gt; is omitted the search is restricted to
5864 directories created before &lt;date-before&gt;. If
5865 &lt;date-before&gt; is omitted, the search is restricted
5866 to directories created after &lt;date-after&gt;.</t>
5867 </list>
5868 </t>
5869
5870 <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5871 <list>
5872 <t>Restricts the search to directories, which
5873 date of last modification satisfies the specified period, where
5874 &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
5875 format. If &lt;date-after&gt; is omitted the search is restricted to
5876 directories, which are last modified before &lt;date-before&gt;. If
5877 &lt;date-before&gt; is omitted, the search is restricted to directories,
5878 which are last modified after &lt;date-after&gt;.</t>
5879 </list>
5880 </t>
5881
5882 <t>DESCRIPTION='&lt;search-string&gt;'
5883 <list>
5884 <t>Restricts the search to directories with description
5885 that satisfies the supplied search string
5886 (encapsulated into apostrophes, supporting escape
5887 sequences as described in chapter
5888 "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5889 </list>
5890 </t>
5891 </t>
5892
5893 <t>Where &lt;search-string&gt; is either a regular expression, or a
5894 word list separated with spaces for OR search and with '+' for AND search.</t>
5895
5896 <t>Possible Answers:</t>
5897 <t>
5898 <list>
5899 <t>A comma separated list with the absolute path names (encapsulated into
5900 apostrophes) of all directories in the specified directory that satisfy
5901 the supplied search criterias.</t>
5902 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5903 <list>
5904 <t>if the given directory does not exist.</t>
5905 </list>
5906 </t>
5907 </list>
5908 </t>
5909 <t>Example:</t>
5910 <t>
5911 <list>
5912 <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'"</t>
5913 <t>S: "'/Piano Collection'"</t>
5914 </list>
5915 </t>
5916 <t>
5917 <list>
5918 <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:30:13'"</t>
5919 <t>S: "'/Piano Collection','/Percussions'"</t>
5920 </list>
5921 </t>
5922 </section>
5923
5924 <section title="Adding instruments to the instruments database" anchor="ADD DB_INSTRUMENTS" lscp_cmd="true">
5925 <t>The front-end can add one or more instruments
5926 to the instruments database by sending the following command:</t>
5927 <t>
5928 <list>
5929 <t>ADD DB_INSTRUMENTS [NON_MODAL] [&lt;mode&gt;[ FILE_AS_DIR]] &lt;db_dir&gt; &lt;file_path&gt; [&lt;instr_index&gt;]</t>
5930 </list>
5931 </t>
5932 <t>Where &lt;db_dir&gt; is the absolute path name of a directory
5933 (encapsulated into apostrophes) in the instruments database in which
5934 only the new instruments (that are not already in the database) will
5935 be added, &lt;file_path&gt; is the absolute path name of a file or
5936 directory in the file system (encapsulated into apostrophes). In case
5937 an instrument file is supplied, only the instruments in the specified
5938 file will be added to the instruments database. If the optional
5939 &lt;instr_index&gt; (the index of the instrument within the given file)
5940 is supplied too, then only the specified instrument will be added.
5941 In case a directory is supplied, the instruments in that directory
5942 will be added. The OPTIONAL &lt;mode&gt; argument is only applied
5943 when a directory is provided as &lt;file_path&gt; and specifies how the
5944 scanning will be done and has exactly the following possibilities:</t>
5945 <t>
5946 <list>
5947 <t>"RECURSIVE" -
5948 <list>
5949 <t>All instruments will be processed, including those
5950 in the subdirectories, and the respective subdirectory
5951 tree structure will be recreated in the instruments
5952 database</t>
5953 </list>
5954 </t>
5955 <t>"NON_RECURSIVE" -
5956 <list>
5957 <t>Only the instruments in the specified directory
5958 will be added, the instruments in the subdirectories
5959 will not be processed.</t>
5960 </list>
5961 </t>
5962 <t>"FLAT" -
5963 <list>
5964 <t>All instruments will be processed, including those
5965 in the subdirectories, but the respective subdirectory
5966 structure will not be recreated in the instruments
5967 database. All instruments will be added directly in
5968 the specified database directory.</t>
5969 </list>
5970 </t>
5971 </list>
5972 </t>
5973
5974 <t> If FILE_AS_DIR argument is supplied, all instruments in an instrument
5975 file will be added to a separate directory in the instruments database, which
5976 name will be the name of the instrument file with the file extension stripped off.
5977 </t>
5978 <t>The difference between regular and NON_MODAL versions of the command
5979 is that the regular command returns when the scanning is finished
5980 while NON_MODAL version returns immediately and a background process is launched.
5981 The <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5982 command can be used to monitor the scanning progress.</t>
5983
5984 <t>Possible Answers:</t>
5985 <t>
5986 <list>
5987 <t>"OK" -
5988 <list>
5989 <t>on success when NON_MODAL is not supplied</t>
5990 </list>
5991 </t>
5992 <t>"OK[&lt;job-id&gt;]" -
5993 <list>
5994 <t>on success when NON_MODAL is supplied, where &lt;job-id&gt;
5995 is a numerical ID used to obtain status information about the job progress.
5996 See <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5997 </t>
5998 </list>
5999 </t>
6000 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6001 <list>
6002 <t>if an invalid path is specified.</t>
6003 </list>
6004 </t>
6005 </list>
6006 </t>
6007
6008 <t>Examples:</t>
6009 <t>
6010 <list>
6011 <t>C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI Bosendorfer 290.gig' 0"</t>
6012 <t>S: "OK"</t>
6013 </list>
6014 </t>
6015 </section>
6016
6017 <section title="Removing an instrument" anchor="REMOVE DB_INSTRUMENT" lscp_cmd="true">
6018 <t>The front-end can remove a particular instrument
6019 from the instruments database by sending the following command:</t>
6020 <t>
6021 <list>
6022 <t>REMOVE DB_INSTRUMENT &lt;instr_path&gt;</t>
6023 </list>
6024 </t>
6025 <t>Where &lt;instr_path&gt; is the absolute path name
6026 (in the instruments database) of the instrument to remove.</t>
6027
6028 <t>Possible Answers:</t>
6029 <t>
6030 <list>
6031 <t>"OK" -
6032 <list>
6033 <t>if the instrument is removed successfully</t>
6034 </list>
6035 </t>
6036 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6037 <list>
6038 <t>if the given path does not exist or
6039 is a directory.</t>
6040 </list>
6041 </t>
6042 </list>
6043 </t>
6044
6045 <t>Examples:</t>
6046 <t>
6047 <list>
6048 <t>C: "REMOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'"</t>
6049 <t>S: "OK"</t>
6050 </list>
6051 </t>
6052 </section>
6053
6054 <section title="Getting amount of instruments" anchor="GET DB_INSTRUMENTS" lscp_cmd="true">
6055 <t>The front-end can retrieve the current amount of
6056 instruments in a specific directory by sending the following command:</t>
6057 <t>
6058 <list>
6059 <t>GET DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
6060 </list>
6061 </t>
6062 <t>Where &lt;dir&gt; should be replaced by the absolute path name
6063 of the directory. If RECURSIVE is specified, the number of all
6064 instruments, including those located in subdirectories of the
6065 specified directory, will be returned.</t>
6066
6067 <t>Possible Answers:</t>
6068 <t>
6069 <list>
6070 <t>The current number of instruments
6071 in the specified directory.</t>
6072 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6073 <list>
6074 <t>if the given directory does not exist.</t>
6075 </list>
6076 </t>
6077 </list>
6078 </t>
6079
6080 <t>Example:</t>
6081 <t>
6082 <list>
6083 <t>C: "GET DB_INSTRUMENTS '/Piano Collection'"</t>
6084 <t>S: "2"</t>
6085 </list>
6086 </t>
6087 </section>
6088
6089 <section title="Listing all instruments in specific directory" anchor="LIST DB_INSTRUMENTS" lscp_cmd="true">
6090 <t>The front-end can retrieve the current list of instruments
6091 in specific directory by sending the following command:</t>
6092 <t>
6093 <list>
6094 <t>LIST DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
6095 </list>
6096 </t>
6097 <t>Where &lt;dir&gt; should be replaced by the absolute path
6098 name of the directory. If RECURSIVE is specified, the absolute path
6099 names of all instruments, including those located in subdirectories
6100 of the specified directory, will be returned.</t>
6101
6102 <t>Possible Answers:</t>
6103 <t>
6104 <list>
6105 <t>A comma separated list of all instruments
6106 (encapsulated into apostrophes) in the specified directory.</t>
6107 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6108 <list>
6109 <t>if the given directory does not exist.</t>
6110 </list>
6111 </t>
6112 </list>
6113 </t>
6114 <t>Example:</t>
6115 <t>
6116 <list>
6117 <t>C: "LIST DB_INSTRUMENTS '/Piano Collection'"</t>
6118 <t>S: "'Bosendorfer 290','Steinway D'"</t>
6119 </list>
6120 </t>
6121 <t>
6122 <list>
6123 <t>C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'"</t>
6124 <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D','/Piano Collection/Lite/Free Piano'"</t>
6125 </list>
6126 </t>
6127 </section>
6128
6129 <section title="Getting instrument information" anchor="GET DB_INSTRUMENT INFO" lscp_cmd="true">
6130 <t>The front-end can ask for the current settings of an
6131 instrument by sending the following command:</t>
6132 <t>
6133 <list>
6134 <t>GET DB_INSTRUMENT INFO &lt;instr_path&gt;</t>
6135 </list>
6136 </t>
6137 <t>Where &lt;instr_path&gt; should be replaced by the absolute path
6138 name of the instrument the front-end is interested in.</t>
6139
6140 <t>Possible Answers:</t>
6141 <t>
6142 <list>
6143 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6144 Each answer line begins with the settings category name
6145 followed by a colon and then a space character &lt;SP&gt; and finally
6146 the info character string to that setting category. At the
6147 moment the following categories are defined:</t>
6148
6149 <t>
6150 <list>
6151 <t>INSTRUMENT_FILE -
6152 <list>
6153 <t>File name of the instrument.
6154 Note that the character string may contain
6155 <xref target="character_set">escape sequences</xref>.</t>
6156 </list>
6157 </t>
6158 <t>INSTRUMENT_NR -
6159 <list>
6160 <t>Index of the instrument within the file.</t>
6161 </list>
6162 </t>
6163 <t>FORMAT_FAMILY -
6164 <list>
6165 <t>The format family of the instrument.</t>
6166 </list>
6167 </t>
6168 <t>FORMAT_VERSION -
6169 <list>
6170 <t>The format version of the instrument.</t>
6171 </list>
6172 </t>
6173 <t>SIZE -
6174 <list>
6175 <t>The size of the instrument in bytes.</t>
6176 </list>
6177 </t>
6178 <t>CREATED -
6179 <list>
6180 <t>The date and time when the instrument is added
6181 in the instruments database, represented in
6182 "YYYY-MM-DD HH:MM:SS" format</t>
6183 </list>
6184 </t>
6185 <t>MODIFIED -
6186 <list>
6187 <t>The date and time of the last modification of the
6188 instrument's database settings, represented in
6189 "YYYY-MM-DD HH:MM:SS" format</t>
6190 </list>
6191 </t>
6192 <t>DESCRIPTION -
6193 <list>
6194 <t>A brief description of the instrument.
6195 Note that the character string may contain
6196 <xref target="character_set">escape sequences</xref>.</t>
6197 </list>
6198 </t>
6199 <t>IS_DRUM -
6200 <list>
6201 <t>either true or false, determines whether the
6202 instrument is a drumkit or a chromatic instrument</t>
6203 </list>
6204 </t>
6205 <t>PRODUCT -
6206 <list>
6207 <t>The product title of the instrument.
6208 Note that the character string may contain
6209 <xref target="character_set">escape sequences</xref>.</t>
6210 </list>
6211 </t>
6212 <t>ARTISTS -
6213 <list>
6214 <t>Lists the artist names.
6215 Note that the character string may contain
6216 <xref target="character_set">escape sequences</xref>.</t>
6217 </list>
6218 </t>
6219 <t>KEYWORDS -
6220 <list>
6221 <t>Provides a list of keywords that refer to the instrument.
6222 Keywords are separated with semicolon and blank.
6223 Note that the character string may contain
6224 <xref target="character_set">escape sequences</xref>.</t>
6225 </list>
6226 </t>
6227 </list>
6228 </t>
6229 </list>
6230 </t>
6231 <t>The mentioned fields above don't have to be in particular order.</t>
6232
6233 <t>Example:</t>
6234 <t>
6235 <list>
6236 <t>C: "GET DB_INSTRUMENT INFO '/Piano Collection/Bosendorfer 290'"</t>
6237 <t>S: "INSTRUMENT_FILE: /home/me/gigs/Bosendorfer 290.gig"</t>
6238 <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"</t>
6239 <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
6240 <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 2"</t>
6241 <t>&nbsp;&nbsp;&nbsp;"SIZE: 2050871870"</t>
6242 <t>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"</t>
6243 <t>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"</t>
6244 <t>&nbsp;&nbsp;&nbsp;"DESCRIPTION: "</t>
6245 <t>&nbsp;&nbsp;&nbsp;"IS_DRUM: false"</t>
6246 <t>&nbsp;&nbsp;&nbsp;"PRODUCT: GRANDIOSO Bosendorfer 290"</t>
6247 <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Post Musical Instruments"</t>
6248 <t>&nbsp;&nbsp;&nbsp;"KEYWORDS: Bosendorfer"</t>
6249 <t>&nbsp;&nbsp;&nbsp;"."</t>
6250 </list>
6251 </t>
6252 </section>
6253
6254 <section title="Renaming an instrument" anchor="SET DB_INSTRUMENT NAME" lscp_cmd="true">
6255 <t>The front-end can alter the name of a specific
6256 instrument by sending the following command:</t>
6257 <t>
6258 <list>
6259 <t>SET DB_INSTRUMENT NAME &lt;instr&gt; &lt;name&gt;</t>
6260 </list>
6261 </t>
6262 <t>Where &lt;instr&gt; is the absolute path name of the instrument and
6263 &lt;name&gt; is the new name for that instrument.</t>
6264
6265 <t>Possible Answers:</t>
6266 <t>
6267 <list>
6268 <t>"OK" -
6269 <list>
6270 <t>on success</t>
6271 </list>
6272 </t>
6273 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6274 <list>
6275 <t>in case the given instrument does not exists,
6276 or if an instrument with name equal to the new
6277 name already exists.</t>
6278 </list>
6279 </t>
6280 </list>
6281 </t>
6282
6283 <t>Example:</t>
6284 <t>
6285 <list>
6286 <t>C: "SET DB_INSTRUMENT NAME '/Piano Collection/Bosendorfer' 'Bosendorfer 290'"</t>
6287 <t>S: "OK"</t>
6288 </list>
6289 </t>
6290 </section>
6291
6292 <section title="Moving an instrument" anchor="MOVE DB_INSTRUMENT" lscp_cmd="true">
6293 <t>The front-end can move a specific instrument to another directory by
6294 sending the following command:</t>
6295 <t>
6296 <list>
6297 <t>MOVE DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
6298 </list>
6299 </t>
6300 <t>Where &lt;instr&gt; is the absolute path name of the instrument
6301 to move and &lt;dst&gt; is the directory where the instrument will
6302 be moved to.</t>
6303
6304 <t>Possible Answers:</t>
6305 <t>
6306 <list>
6307 <t>"OK" -
6308 <list>
6309 <t>on success</t>
6310 </list>
6311 </t>
6312 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6313 <list>
6314 <t>in case the given instrument does not exists,
6315 or if an instrument with name equal to the name of the
6316 specified instrument already exists in the destination
6317 directory.</t>
6318 </list>
6319 </t>
6320 </list>
6321 </t>
6322
6323 <t>Example:</t>
6324 <t>
6325 <list>
6326 <t>C: "MOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Piano Collection/Acoustic'"</t>
6327 <t>S: "OK"</t>
6328 </list>
6329 </t>
6330 </section>
6331
6332 <section title="Copying instruments" anchor="COPY DB_INSTRUMENT" lscp_cmd="true">
6333 <t>The front-end can copy a specific instrument to another directory by
6334 sending the following command:</t>
6335 <t>
6336 <list>
6337 <t>COPY DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
6338 </list>
6339 </t>
6340 <t>Where &lt;instr&gt; is the absolute path name of the instrument
6341 to copy and &lt;dst&gt; is the directory where the instrument will
6342 be copied to.</t>
6343
6344 <t>Possible Answers:</t>
6345 <t>
6346 <list>
6347 <t>"OK" -
6348 <list>
6349 <t>on success</t>
6350 </list>
6351 </t>
6352 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6353 <list>
6354 <t>in case the given instrument does not exists,
6355 or if an instrument with name equal to the name of the
6356 specified instrument already exists in the destination
6357 directory.</t>
6358 </list>
6359 </t>
6360 </list>
6361 </t>
6362
6363 <t>Example:</t>
6364 <t>
6365 <list>
6366 <t>C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Acoustic/Pianos/'"</t>
6367 <t>S: "OK"</t>
6368 </list>
6369 </t>
6370 </section>
6371
6372 <section title="Changing the description of instrument" anchor="SET DB_INSTRUMENT DESCRIPTION" lscp_cmd="true">
6373 <t>The front-end can alter the description of a specific
6374 instrument by sending the following command:</t>
6375 <t>
6376 <list>
6377 <t>SET DB_INSTRUMENT DESCRIPTION &lt;instr&gt; &lt;desc&gt;</t>
6378 </list>
6379 </t>
6380 <t>Where &lt;instr&gt; is the absolute path name of the instrument and
6381 &lt;desc&gt; is the new description for the instrument
6382 (encapsulated into apostrophes, supporting escape sequences as described in chapter
6383 "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6384
6385 <t>Possible Answers:</t>
6386 <t>
6387 <list>
6388 <t>"OK" -
6389 <list>
6390 <t>on success</t>
6391 </list>
6392 </t>
6393 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6394 <list>
6395 <t>in case the given instrument does not exists.</t>
6396 </list>
6397 </t>
6398 </list>
6399 </t>
6400
6401 <t>Example:</t>
6402 <t>
6403 <list>
6404 <t>C: "SET DB_INSTRUMENT DESCRIPTION '/Piano Collection/Acoustic/Bosendorfer 290' 'No comment :)'"</t>
6405 <t>S: "OK"</t>
6406 </list>
6407 </t>
6408 </section>
6409
6410 <section title="Finding instruments" anchor="FIND DB_INSTRUMENTS" lscp_cmd="true">
6411 <t>The front-end can search for instruments
6412 in specific directory by sending the following command:</t>
6413 <t>
6414 <list>
6415 <t>FIND DB_INSTRUMENTS [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
6416 </list>
6417 </t>
6418 <t>Where &lt;dir&gt; should be replaced by the absolute path
6419 name of the directory to search in. If NON_RECURSIVE is specified, the
6420 directories located in subdirectories of the specified directory will not
6421 be searched. &lt;criteria-list&gt; is a list of search criterias
6422 in form of "key1=val1 key2=val2 ...". The following criterias are
6423 allowed:</t>
6424 <t>
6425 <t>NAME='&lt;search-string&gt;'
6426 <list>
6427 <t>Restricts the search to instruments, which names
6428 satisfy the supplied search string (encapsulated into apostrophes,
6429 supporting escape sequences as described in chapter
6430 "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6431 </list>
6432 </t>
6433
6434 <t>SIZE=[&lt;min&gt;]..[&lt;max&gt;]
6435 <list>
6436 <t>Restricts the search to instruments, which
6437 size is in the specified range. If &lt;min&gt; is omitted,
6438 the search results are restricted to instruments with size less then
6439 or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the
6440 search is restricted to instruments with size greater then
6441 or equal to &lt;min&gt;.</t>
6442 </list>
6443 </t>
6444
6445 <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
6446 <list>
6447 <t>Restricts the search to instruments, which creation
6448 date satisfies the specified period, where &lt;date-after&gt;
6449 and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
6450 If &lt;date-after&gt; is omitted the search is restricted to
6451 instruments created before &lt;date-before&gt;. If
6452 &lt;date-before&gt; is omitted, the search is restricted
6453 to instruments created after &lt;date-after&gt;.</t>
6454 </list>
6455 </t>
6456
6457 <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
6458 <list>
6459 <t>Restricts the search to instruments, which
6460 date of last modification satisfies the specified period, where
6461 &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
6462 format. If &lt;date-after&gt; is omitted the search is restricted to
6463 instruments, which are last modified before &lt;date-before&gt;. If
6464 &lt;date-before&gt; is omitted, the search is restricted to instruments,
6465 which are last modified after &lt;date-after&gt;.</t>
6466 </list>
6467 </t>
6468
6469 <t>DESCRIPTION='&lt;search-string&gt;'
6470 <list>
6471 <t>Restricts the search to instruments with description
6472 that satisfies the supplied search string (encapsulated into apostrophes,
6473 supporting escape sequences as described in chapter
6474 "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6475 </list>
6476 </t>
6477
6478 <t>PRODUCT='&lt;search-string&gt;'
6479 <list>
6480 <t>Restricts the search to instruments with product info
6481 that satisfies the supplied search string (encapsulated into apostrophes,
6482 supporting escape sequences as described in chapter
6483 "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6484 </list>
6485 </t>
6486
6487 <t>ARTISTS='&lt;search-string&gt;'
6488 <list>
6489 <t>Restricts the search to instruments with artists info
6490 that satisfies the supplied search string (encapsulated into apostrophes,
6491 supporting escape sequences as described in chapter
6492 "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6493 </list>
6494 </t>
6495
6496 <t>KEYWORDS='&lt;search-string&gt;'
6497 <list>
6498 <t>Restricts the search to instruments with keyword list
6499 that satisfies the supplied search string (encapsulated into apostrophes,
6500 supporting escape sequences as described in chapter
6501 "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6502 </list>
6503 </t>
6504
6505 <t>IS_DRUM=true | false
6506 <list>
6507 <t>Either true or false. Restricts the search to
6508 drum kits or chromatic instruments.</t>
6509 </list>
6510 </t>
6511
6512 <t>FORMAT_FAMILIES='&lt;format-list&gt;'
6513 <list>
6514 <t>Restricts the search to instruments of the supplied format families,
6515 where &lt;format-list&gt; is a comma separated list of format families.</t>
6516 </list>
6517 </t>
6518 </t>
6519
6520 <t>Where &lt;search-string&gt; is either a regular expression, or a
6521 word list separated with spaces for OR search and with '+' for AND search.</t>
6522
6523 <t>Possible Answers:</t>
6524 <t>
6525 <list>
6526 <t>A comma separated list with the absolute path names (encapsulated into
6527 apostrophes) of all instruments in the specified directory that satisfy
6528 the supplied search criterias.</t>
6529 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6530 <list>
6531 <t>if the given directory does not exist.</t>
6532 </list>
6533 </t>
6534 </list>
6535 </t>
6536 <t>Example:</t>
6537 <t>
6538 <list>
6539 <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+290'"</t>
6540 <t>S: "'/Piano Collection/Bosendorfer 290'"</t>
6541 </list>
6542 </t>
6543 <t>
6544 <list>
6545 <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01 09:30:13..'"</t>
6546 <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D'"</t>
6547 </list>
6548 </t>
6549 </section>
6550
6551 <section title="Getting job status information" anchor="GET DB_INSTRUMENTS_JOB INFO" lscp_cmd="true">
6552 <t>The front-end can ask for the current status of a
6553 particular database instruments job by sending the following command:</t>
6554 <t>
6555 <list>
6556 <t>GET DB_INSTRUMENTS_JOB INFO &lt;job-id&gt;</t>
6557 </list>
6558 </t>
6559 <t>Where &lt;job-id&gt; should be replaced by the numerical ID
6560 of the job the front-end is interested in.</t>
6561
6562 <t>Possible Answers:</t>
6563 <t>
6564 <list>
6565 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6566 Each answer line begins with the settings category name
6567 followed by a colon and then a space character &lt;SP&gt; and finally
6568 the info character string to that setting category. At the
6569 moment the following categories are defined:</t>
6570
6571 <t>
6572 <list>
6573 <t>FILES_TOTAL -
6574 <list>
6575 <t>The total number of files scheduled for scanning</t>
6576 </list>
6577 </t>
6578 <t>FILES_SCANNED -
6579 <list>
6580 <t>The current number of scanned files</t>
6581 </list>
6582 </t>
6583 <t>SCANNING -
6584 <list>
6585 <t>The absolute path name of the file which is currently
6586 being scanned</t>
6587 </list>
6588 </t>
6589 <t>STATUS -
6590 <list>
6591 <t>An integer value between 0 and 100 indicating the
6592 scanning progress percentage of the file which is
6593 currently being scanned</t>
6594 </list>
6595 </t>
6596 </list>
6597 </t>
6598 </list>
6599 </t>
6600 <t>The mentioned fields above don't have to be in particular order.</t>
6601
6602 <t>Example:</t>
6603 <t>
6604 <list>
6605 <t>C: "GET DB_INSTRUMENTS_JOB INFO 2"</t>
6606 <t>S: "FILES_TOTAL: 12"</t>
6607 <t>&nbsp;&nbsp;&nbsp;"FILES_SCANNED: 7"</t>
6608 <t>&nbsp;&nbsp;&nbsp;"SCANNING: /home/me/gigs/Bosendorfer 290.gig"</t>
6609 <t>&nbsp;&nbsp;&nbsp;"STATUS: 42"</t>
6610 <t>&nbsp;&nbsp;&nbsp;"."</t>
6611 </list>
6612 </t>
6613 </section>
6614
6615 <section title="Formatting the instruments database" anchor="FORMAT INSTRUMENTS_DB" lscp_cmd="true">
6616 <t>The front-end can remove all instruments and directories and re-create
6617 the instruments database structure (e.g., in case of a database corruption)
6618 by sending the following command:</t>
6619 <t>
6620 <list>
6621 <t>FORMAT INSTRUMENTS_DB</t>
6622 </list>
6623 </t>
6624
6625 <t>Possible Answers:</t>
6626 <t>
6627 <list>
6628 <t>"OK" -
6629 <list>
6630 <t>on success</t>
6631 </list>
6632 </t>
6633 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6634 <list>
6635 <t>If the formatting of the instruments database
6636 failed.</t>
6637 </list>
6638 </t>
6639 </list>
6640 </t>
6641 </section>
6642
6643 <section title="Checking for lost instrument files" anchor="FIND LOST DB_INSTRUMENT_FILES" lscp_cmd="true">
6644 <t>The front-end can retrieve the list of all instrument files in the instruments database
6645 that don't exist in the filesystem by sending the following command:</t>
6646 <t>
6647 <list>
6648 <t>FIND LOST DB_INSTRUMENT_FILES</t>
6649 </list>
6650 </t>
6651
6652 <t>Possible Answers:</t>
6653 <t>
6654 <list>
6655 <t>A comma separated list with the absolute path names
6656 (encapsulated into apostrophes) of all lost instrument files.</t>
6657 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6658 <list>
6659 <t>in case it failed, providing an appropriate error code and error message.</t>
6660 </list>
6661 </t>
6662 </list>
6663 </t>
6664 <t>Example:</t>
6665 <t>
6666 <list>
6667 <t>C: "FIND LOST DB_INSTRUMENT_FILES"</t>
6668 <t>S: "'/gigs/Bosendorfer 290.gig','/gigs/Steinway D.gig','/gigs/Free Piano.gig'"</t>
6669 </list>
6670 </t>
6671 </section>
6672
6673 <section title="Replacing an instrument file" anchor="SET DB_INSTRUMENT FILE_PATH" lscp_cmd="true">
6674 <t>The front-end can substitute all occurrences of an instrument file
6675 in the instruments database with a new one by sending the following command:</t>
6676 <t>
6677 <list>
6678 <t>SET DB_INSTRUMENT FILE_PATH &lt;old_path&gt; &lt;new_path&gt;</t>
6679 </list>
6680 </t>
6681 <t>Where &lt;old_path&gt; is the absolute path name of the instrument file
6682 to substitute with &lt;new_path&gt;.</t>
6683
6684 <t>Possible Answers:</t>
6685 <t>
6686 <list>
6687 <t>"OK" -
6688 <list>
6689 <t>on success</t>
6690 </list>
6691 </t>
6692 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6693 <list>
6694 <t>in case it failed, providing an appropriate error code and error message.</t>
6695 </list>
6696 </t>
6697 </list>
6698 </t>
6699
6700 <t>Example:</t>
6701 <t>
6702 <list>
6703 <t>C: "SET DB_INSTRUMENT FILE_PATH '/gigs/Bosendorfer 290.gig' '/gigs/pianos/Bosendorfer 290.gig'"</t>
6704 <t>S: "OK"</t>
6705 </list>
6706 </t>
6707 </section>
6708
6709 </section>
6710
6711
6712
6713 <section title="Editing Instruments" anchor="editing_instruments">
6714 <t>The sampler allows to edit instruments while playing with the
6715 sampler by spawning an external (3rd party) instrument editor
6716 application for a given instrument. The 3rd party instrument
6717 editor applications have to place a respective plugin DLL file
6718 into the sampler's plugins directory. The sampler will
6719 automatically try to load all plugin DLLs in that directory on
6720 startup and only on startup!</t>
6721 <t>At the moment there is only one command for this feature set,
6722 but this will most probably change in future.</t>
6723
6724 <section title="Opening an appropriate instrument editor application" anchor="EDIT INSTRUMENT" lscp_cmd="true">
6725 <t>The front-end can request to open an appropriate instrument
6726 editor application by sending the following command:</t>
6727 <t>
6728 <list>
6729 <t>EDIT CHANNEL INSTRUMENT &lt;sampler-channel&gt;</t>
6730 </list>
6731 </t>
6732 <t>Where &lt;sampler-channel&gt; should be replaced by the
6733 number of the sampler channel as given by the
6734 <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
6735 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref>
6736 command.</t>
6737
6738 <t>The sampler will try to ask all registered instrument
6739 editors (or to be more specific: their sampler plugins)
6740 whether they are capable to handle the instrument on the
6741 given sampler channel. The sampler will simply use the first
6742 instrument editor application which replied with a positive
6743 answer and spawn that instrument editor application within
6744 the sampler's process and provide that application access
6745 to the instrument's data structures, so both applications
6746 can share and access the same instruments data at the same
6747 time, thus allowing to immediately hear changes with the
6748 sampler made by the instrument editor.</t>
6749
6750 <t>Note: consequently instrument editors are always spawned
6751 locally on the same machine where the sampler is running
6752 on!</t>
6753
6754 <t>Possible Answers:</t>
6755 <t>
6756 <list>
6757 <t>"OK" -
6758 <list>
6759 <t>when an appropriate instrument editor was
6760 launched</t>
6761 </list>
6762 </t>
6763 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6764 <list>
6765 <t>when an appropriate instrument editor was
6766 launched, but there are noteworthy issues</t>
6767 </list>
6768 </t>
6769 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6770 <list>
6771 <t>when an appropriate instrument editor
6772 could not be launched</t>
6773 </list>
6774 </t>
6775 </list>
6776 </t>
6777
6778 <t>Examples:</t>
6779 <t>
6780 <list>
6781 <t>C: "EDIT CHANNEL INSTRUMENT 0"</t>
6782 <t>S: "OK"</t>
6783 </list>
6784 </t>
6785 </section>
6786 </section>
6787
6788 <section title="Managing Files" anchor="file_management">
6789 <t>You can query detailed information about files located
6790 at the same system where the sampler instance is running on.
6791 Using this command set allows to retrieve file information
6792 even remotely from another machine.</t>
6793
6794 <section title="Retrieving amount of instruments of a file" anchor="GET FILE INSTRUMENTS" lscp_cmd="true">
6795 <t>The front-end can retrieve the amount of instruments
6796 within a given instrument file by sending the
6797 following command:</t>
6798 <t>
6799 <list>
6800 <t>GET FILE INSTRUMENTS &lt;filename&gt;</t>
6801 </list>
6802 </t>
6803 <t>Where &lt;filename&gt; is the name of the instrument
6804 file (encapsulated into apostrophes, supporting escape
6805 sequences as described in chapter
6806 "<xref target="character_set">Character Set and Escape
6807 Sequences</xref>").</t>
6808
6809 <t>The sampler will try to ask all sampler engines,
6810 whether they support the given file and ask the first
6811 engine with a positive answer for the amount of
6812 instruments.</t>
6813
6814 <t>Possible Answers:</t>
6815 <t>
6816 <list>
6817 <t>On success, the sampler will answer by
6818 returning the amount of instruments.
6819 </t>
6820 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6821 <list>
6822 <t>if the file could not be handled</t>
6823 </list>
6824 </t>
6825 </list>
6826 </t>
6827
6828 <t>Examples:</t>
6829 <t>
6830 <list>
6831 <t>C: "GET FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
6832 <t>S: "10"</t>
6833 </list>
6834 </t>
6835 </section>
6836
6837 <section title="Retrieving all instruments of a file" anchor="LIST FILE INSTRUMENTS" lscp_cmd="true">
6838 <t>The front-end can retrieve a list of all instruments
6839 within a given instrument file by sending the
6840 following command:</t>
6841 <t>
6842 <list>
6843 <t>LIST FILE INSTRUMENTS &lt;filename&gt;</t>
6844 </list>
6845 </t>
6846 <t>Where &lt;filename&gt; is the name of the instrument
6847 file (encapsulated into apostrophes, supporting escape
6848 sequences as described in chapter
6849 "<xref target="character_set">Character Set and Escape
6850 Sequences</xref>").</t>
6851
6852 <t>The sampler will try to ask all sampler engines,
6853 whether they support the given file and ask the first
6854 engine with a positive answer for a list of IDs for the
6855 instruments in the given file.</t>
6856
6857 <t>Possible Answers:</t>
6858 <t>
6859 <list>
6860 <t>On success, the sampler will answer by
6861 returning a comma separated list of
6862 instrument IDs.
6863 </t>
6864 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6865 <list>
6866 <t>if the file could not be handled</t>
6867 </list>
6868 </t>
6869 </list>
6870 </t>
6871
6872 <t>Examples:</t>
6873 <t>
6874 <list>
6875 <t>C: "LIST FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
6876 <t>S: "0,1,2,3,4,5,6,7,8,9"</t>
6877 </list>
6878 </t>
6879 </section>
6880
6881 <section title="Retrieving information about one instrument in a file" anchor="GET FILE INSTRUMENT INFO" lscp_cmd="true">
6882 <t>The front-end can retrieve detailed information
6883 about a specific instrument within a given instrument
6884 file by sending the following command:</t>
6885 <t>
6886 <list>
6887 <t>GET FILE INSTRUMENT INFO &lt;filename&gt;
6888 &lt;instr-id&gt;</t>
6889 </list>
6890 </t>
6891 <t>Where &lt;filename&gt; is the name of the instrument
6892 file (encapsulated into apostrophes, supporting escape
6893 sequences as described in chapter
6894 "<xref target="character_set">Character Set and Escape
6895 Sequences</xref>") and &lt;instr-id&gt; is the numeric
6896 instrument ID as returned by the
6897 <xref target="LIST FILE INSTRUMENTS">
6898 "LIST FILE INSTRUMENTS"</xref> command.</t>
6899
6900 <t>The sampler will try to ask all sampler engines,
6901 whether they support the given file and ask the first
6902 engine with a positive answer for information about the
6903 specific instrument in the given file.</t>
6904
6905 <t>Possible Answers:</t>
6906 <t>
6907 <list>
6908 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6909 Each answer line begins with the settings category name
6910 followed by a colon and then a space character &lt;SP&gt; and finally
6911 the info character string to that setting category. At the
6912 moment the following categories are defined:</t>
6913
6914 <t>
6915 <list>
6916 <t>NAME -
6917 <list>
6918 <t>name of the instrument as
6919 stored in the instrument file</t>
6920 </list>
6921 </t>
6922 <t>FORMAT_FAMILY -
6923 <list>
6924 <t>name of the sampler format
6925 of the given instrument</t>
6926 </list>
6927 </t>
6928 <t>FORMAT_VERSION -
6929 <list>
6930 <t>version of the sampler format
6931 the instrumen is stored as</t>
6932 </list>
6933 </t>
6934 <t>PRODUCT -
6935 <list>
6936 <t>official product name of the
6937 instrument as stored in the file
6938 </t>
6939 </list>
6940 </t>
6941 <t>ARTISTS -
6942 <list>
6943 <t>artists / sample library
6944 vendor of the instrument</t>
6945 </list>
6946 </t>
6947 <t>KEY_BINDINGS -
6948 <list>
6949 <t>comma separated list of integer values representing
6950 the instrument's key mapping in the range between 0 .. 127,
6951 reflecting the analog meaning of the MIDI specification.</t>
6952 </list>
6953 </t>
6954 <t>KEYSWITCH_BINDINGS -
6955 <list>
6956 <t>comma separated list of integer values representing
6957 the instrument's keyswitch mapping in the range between 0 .. 127,
6958 reflecting the analog meaning of the MIDI specification.</t>
6959 </list>
6960 </t>
6961 </list>
6962 </t>
6963 </list>
6964 </t>
6965 <t>The mentioned fields above don't have to be in particular order.</t>
6966
6967 <t>Example:</t>
6968 <t>
6969 <list>
6970 <t>C: "GET FILE INSTRUMENT INFO 'D:/Sounds/Foo.gig' 0"</t>
6971 <t>S: "NAME: Lunatic Loops"</t>
6972 <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
6973 <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 3"</t>
6974 <t>&nbsp;&nbsp;&nbsp;"PRODUCT: The Backbone Bongo Beats"</t>
6975 <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Jimmy the Fish"</t>
6976 <t>&nbsp;&nbsp;&nbsp;"."</t>
6977 </list>
6978 </t>
6979 </section>
6980 </section>
6981 <section title="Managing Effects" anchor="effects">
6982 <t>There are two possible approaches to apply audio effects
6983 (e.g. reverb, delay, compression).
6984 You can either a) load and apply internal effects or you can b) route
6985 effect sends directly to dedicated output channels of your
6986 audio device and apply effects externally (e.g. by routing
6987 those dedicated output channels to another application).</t>
6988 <t>This chapter describes how to load and manage internal effects.
6989 If your intention is rather to apply effects externally, then
6990 you can omit this chapter. For applying effects externally, you
6991 just need to <xref target="CREATE FX_SEND">create FX sends</xref>
6992 on the respective sampler channel(s)
6993 and <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">adjust their destination audio channels</xref>
6994 appropriately, because by default FX sends are automatically routed
6995 directly to the audio output device.</t>
6996 <t>The sampler usually provides a set of internal audio effects.
6997 The exact set of effects depends on the availability
6998 of third party effect plugins installed on the system where the
6999 sampler runs on (e.g. LADSPA plugins).</t>
7000 <t>At the moment only "send effects" are supported. Support for
7001 "insert effects" and "master effects" is planned to be added at
7002 a later point.</t>
7003 <t>The following commands allow to retrieve the set of internal
7004 effects available to the sampler, detailed information about
7005 those effects and to create and destroy instances of such
7006 effects. After an instance of an effect is created, the effect
7007 instance can be inserted into the audio signal path of the
7008 sampler, e.g. as send effect.</t>
7009 <t>The sampler allows to create an arbitrary amount of so called
7010 send effect chains. Each effect chain can host an arbitrary
7011 amount of effect instances. The output of the first effect
7012 instance in an effect chain is fed to the input of the second
7013 effect instance of the chain and so on. So effects in one chain
7014 are processed sequentially. Send effect chains however are
7015 processed in parallel to other send effect chains. Audio signals
7016 of sampler channels are fed to send effects by creating FX sends
7017 to the respective sampler channel and assigning a destination
7018 send effect to that FX by using the
7019 <xref target="SET FX_SEND EFFECT">"SET FX_SEND EFFECT"</xref>
7020 command. The latter allows to route the FX send to the beginning
7021 of a send effect chain, as well as directly to any other
7022 position of the send effect chain.</t>
7023
7024 <section title="Retrieve amount of available effects" anchor="GET AVAILABLE_EFFECTS" lscp_cmd="true">
7025 <t>The front-end can retrieve the amount of internal
7026 effects, available to the sampler by sending
7027 the following command:</t>
7028 <t>
7029 <list>
7030 <t>GET AVAILABLE_EFFECTS</t>
7031 </list>
7032 </t>
7033
7034 <t>Possible Answers:</t>
7035 <t>
7036 <list>
7037 <t>The sampler will answer by returning the current
7038 number of effects available to the sampler.</t>
7039 </list>
7040 </t>
7041
7042 <t>Examples:</t>
7043 <t>
7044 <list>
7045 <t>C: "GET AVAILABLE_EFFECTS"</t>
7046 <t>S: "129"</t>
7047 </list>
7048 </t>
7049 </section>
7050
7051 <section title="Get list of available effects" anchor="LIST AVAILABLE_EFFECTS" lscp_cmd="true">
7052 <t>The set of available internal effects can change at
7053 runtime. The front-end can retrieve the list of internal
7054 effects, available to the sampler by sending the following
7055 command:</t>
7056 <t>
7057 <list>
7058 <t>LIST AVAILABLE_EFFECTS</t>
7059 </list>
7060 </t>
7061
7062 <t>Possible Answers:</t>
7063 <t>
7064 <list>
7065 <t>The sampler will answer by returning a comma
7066 separated list with numerical IDs of effects. Note:
7067 the numercial ID of an effect is generated by the
7068 sampler for the current moment. The numerical ID of
7069 the same effect can change at runtime, e.g. when the
7070 user requests a rescan of available effect plugins.
7071 </t>
7072 </list>
7073 </t>
7074 <t>Example:</t>
7075 <t>
7076 <list>
7077 <t>C: "LIST AVAILABLE_EFFECTS"</t>
7078 <t>S: "5,6,7,120,121,122,123,124"</t>
7079 </list>
7080 </t>
7081 </section>
7082
7083 <section title="Retrieving general information about an effect" anchor="GET EFFECT INFO" lscp_cmd="true">
7084 <t>The front-end can ask for general information about an
7085 effect by sending the following command:</t>
7086 <t>
7087 <list>
7088 <t>GET EFFECT INFO &lt;effect-index&gt;</t>
7089 </list>
7090 </t>
7091 <t>Where &lt;effect-index&gt; is the numerical ID of an
7092 effect as returned by the
7093 <xref target="LIST AVAILABLE_EFFECTS">"LIST AVAILABLE_EFFECTS"</xref>
7094 command.</t>
7095 <t>Possible Answers:</t>
7096 <t>
7097 <list>
7098 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
7099 Each answer line begins with the effect information
7100 category name, followed by a colon and then a space
7101 character &lt;SP&gt; and finally the info character
7102 string to that effect information category. At the
7103 moment the following categories are defined:</t>
7104 <t>
7105 <list>
7106 <t>SYSTEM -
7107 <list>
7108 <t>name of the effect plugin system
7109 the effect is based on
7110 (e.g. "LADSPA")</t>
7111 </list>
7112 </t>
7113 <t>MODULE -
7114 <list>
7115 <t>module of the effect plugin
7116 system that contains this effect,
7117 the module is usually the
7118 dynamic-linked library (DLL)
7119 filename of the effect plugin,
7120 including full path (note that this
7121 filename may contain
7122 <xref target="character_set">escape sequences</xref>)</t>
7123 </list>
7124 </t>
7125 <t>NAME -
7126 <list>
7127 <t>character string defining the
7128 unique name of the effect within its
7129 module (note that the character
7130 string may contain
7131 <xref target="character_set">escape sequences</xref>)</t>
7132 </list>
7133 </t>
7134 <t>DESCRIPTION -
7135 <list>
7136 <t>human readable name of the
7137 effect, intended to be displayed in
7138 user interfaces (note that the
7139 character string may contain
7140 <xref target="character_set">escape sequences</xref>)</t>
7141 </list>
7142 </t>
7143 </list>
7144 </t>
7145 </list>
7146 </t>
7147 <t>The mentioned fields above don't have to be in particular order.</t>
7148
7149 <t>Example:</t>
7150 <t>
7151 <list>
7152 <t>C: "GET EFFECT INFO 121"</t>
7153 <t>S: "SYSTEM: LADSPA"</t>
7154 <t>&nbsp;&nbsp;&nbsp;"MODULE: /usr/lib/ladspa/lowpass_iir_1891.so"</t>
7155 <t>&nbsp;&nbsp;&nbsp;"NAME: lowpass_iir"</t>
7156 <t>&nbsp;&nbsp;&nbsp;"DESCRIPTION: Glame Lowpass Filter"</t>
7157 <t>&nbsp;&nbsp;&nbsp;"."</t>
7158 </list>
7159 </t>
7160 </section>
7161
7162 <section title="Creating an instance of an effect by its portable ID" anchor="CREATE EFFECT_INSTANCE" lscp_cmd="true">
7163 <t>The front-end can spawn an instance of the desired
7164 effect by sending the following command:</t>
7165 <t>
7166 <list>
7167 <t>CREATE EFFECT_INSTANCE &lt;effect-system&gt; &lt;module&gt; &lt;effect-name&gt;</t>
7168 </list>
7169 </t>
7170 <t>Where &lt;effect-system&gt; is the "SYSTEM" field,
7171 &lt;module&gt; the "MODULE" field and &lt;effect-name&gt;
7172 the "NAME" field as returned by the
7173 <xref target="GET EFFECT INFO">"GET EFFECT INFO"</xref>
7174 command. The filename of argument &lt;module&gt; and the
7175 character string of argument &lt;effect-name&gt; may contain
7176 <xref target="character_set">escape sequences</xref>.</t>
7177
7178 <t>The sampler will try to load the requested effect and to
7179 create an instance of it. To allow loading the same effect
7180 on a different machine, probably even running a completely
7181 different operating system (e.g. Linux vs. Windows), the
7182 sampler tries to match &lt;module&gt; "softly". That means
7183 it first tries to find an effect that exactly matches the
7184 given &lt;module&gt; argument. If there is no exact match,
7185 the sampler will try to lower the restrictions on matching
7186 the &lt;module&gt; argument more and more, e.g. by ignoring
7187 upper / lower case differences and by ignoring the path of
7188 the DLL filename and file extension. If there is still no
7189 match at the end, the sampler will try to ignore the
7190 &lt;module&gt; argument completely and as a last resort
7191 search for an effect that only matches the given
7192 &lt;effect-system&gt; and &lt;effect-name&gt; arguments.</t>
7193
7194 <t>Possible Answers:</t>
7195 <t>
7196 <list>
7197 <t>"OK[&lt;effect-instance&gt;]" -
7198 <list>
7199 <t>in case the effect instance was
7200 successfully created, where
7201 &lt;effect-instance&gt; is the numerical ID
7202 of the new effect instance</t>
7203 </list>
7204 </t>
7205 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
7206 <list>
7207 <t>in case the effect instance was spawned
7208 successfully, but there are noteworthy
7209 issue(s) related, providing an appropriate
7210 warning code and warning message</t>
7211 </list>
7212 </t>
7213 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7214 <list>
7215 <t>if the effect could not be instantiated</t>
7216 </list>
7217 </t>
7218 </list>
7219 </t>
7220
7221 <t>Examples:</t>
7222 <t>
7223 <list>
7224 <t>C: "CREATE EFFECT_INSTANCE LADSPA '/usr/lib/ladspa/mod_delay_1419.so' 'modDelay'"</t>
7225 <t>S: "OK[0]"</t>
7226 </list>
7227 </t>
7228 </section>
7229
7230 <section title="Creating an instance of an effect by its numerical ID" anchor="CREATE EFFECT_INSTANCE (non-portable)">
7231 <t>The front-end can spawn an instance of the desired
7232 effect by sending the following command:</t>
7233 <t>
7234 <list>
7235 <t>CREATE EFFECT_INSTANCE &lt;effect-index&gt;</t>
7236 </list>
7237 </t>
7238 <t>Where &lt;effect-index&gt; is the numerical ID of the
7239 effect as returned by the
7240 <xref target="LIST AVAILABLE_EFFECTS">"LIST AVAILABLE_EFFECTS"</xref>
7241 command.</t>
7242
7243 <t>The sampler will try to load the requested effect and to
7244 create an instance of it.</t>
7245
7246 <t>Note: Since the numerical ID of a certain effect can
7247 change at any time, you should not use this command in
7248 LSCP files to restore a certain effect at a later time! To
7249 store a sampler session including all its effects, use the
7250 <xref target="CREATE EFFECT_INSTANCE">portable text-based
7251 version of "CREATE EFFECT_INSTANCE"</xref> instead! This
7252 allows to restore a sampler session with all its effects
7253 also on other machines, possibly even running a completely
7254 different operating system (e.g. Linux vs. Windows), with
7255 different plugin directories or plugin DLL names.</t>
7256
7257 <t>Possible Answers:</t>
7258 <t>
7259 <list>
7260 <t>"OK[&lt;effect-instance&gt;]" -
7261 <list>
7262 <t>in case the effect instance was
7263 successfully created, where
7264 &lt;effect-instance&gt; is the numerical ID
7265 of the new effect instance</t>
7266 </list>
7267 </t>
7268 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
7269 <list>
7270 <t>in case the effect instance was spawned
7271 successfully, but there are noteworthy
7272 issue(s) related, providing an appropriate
7273 warning code and warning message</t>
7274 </list>
7275 </t>
7276 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7277 <list>
7278 <t>if the effect could not be instantiated</t>
7279 </list>
7280 </t>
7281 </list>
7282 </t>
7283
7284 <t>Examples:</t>
7285 <t>
7286 <list>
7287 <t>C: "CREATE EFFECT_INSTANCE 72"</t>
7288 <t>S: "OK[5]"</t>
7289 </list>
7290 </t>
7291 </section>
7292
7293 <section title="Destroy an effect instance" anchor="DESTROY EFFECT_INSTANCE" lscp_cmd="true">
7294 <t>The front-end can destroy an unusued effect instance and
7295 thus freeing it from memory by sending the following command:</t>
7296 <t>
7297 <list>
7298 <t>DESTROY EFFECT_INSTANCE &lt;effect-instance&gt;</t>
7299 </list>
7300 </t>
7301 <t>Where &lt;effect-instance&gt; is the numerical ID of the
7302 effect instance as returned by the
7303 <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref> or
7304 <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7305 command.</t>
7306
7307 <t>The effect instance can only be destroyed if it's not
7308 used in any part of the sampler's audio signal path anymore.
7309 If the effect instance is still in use somewhere, trying to
7310 destroy the effect instance will result in an error
7311 message.</t>
7312
7313 <t>Possible Answers:</t>
7314 <t>
7315 <list>
7316 <t>"OK" -
7317 <list>
7318 <t>in case the effect instance was successfully destroyed</t>
7319 </list>
7320 </t>
7321 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7322 <list>
7323 <t>in case it failed, providing an appropriate error code and
7324 error message</t>
7325 </list>
7326 </t>
7327 </list>
7328 </t>
7329
7330 <t>Examples:</t>
7331 <t>
7332 <list>
7333 <t>C: "DESTROY EFFECT_INSTANCE 5"</t>
7334 <t>S: "OK"</t>
7335 </list>
7336 </t>
7337 </section>
7338
7339 <section title="Retrieve amount of effect instances" anchor="GET EFFECT_INSTANCES" lscp_cmd="true">
7340 <t>The front-end can retrieve the current amount of effect
7341 instances by sending the following command:</t>
7342 <t>
7343 <list>
7344 <t>GET EFFECT_INSTANCES</t>
7345 </list>
7346 </t>
7347
7348 <t>Possible Answers:</t>
7349 <t>
7350 <list>
7351 <t>The sampler will answer by returning the current
7352 number of effect instances created and not yet
7353 destroyed in the current sampler session.</t>
7354 </list>
7355 </t>
7356
7357 <t>Examples:</t>
7358 <t>
7359 <list>
7360 <t>C: "GET EFFECT_INSTANCES"</t>
7361 <t>S: "14"</t>
7362 </list>
7363 </t>
7364 </section>
7365
7366 <section title="Get list of effect instances" anchor="LIST EFFECT_INSTANCES" lscp_cmd="true">
7367 <t>The front-end can retrieve the current list of effect
7368 instances by sending the following command:</t>
7369 <t>
7370 <list>
7371 <t>LIST EFFECT_INSTANCES</t>
7372 </list>
7373 </t>
7374
7375 <t>Possible Answers:</t>
7376 <t>
7377 <list>
7378 <t>The sampler will answer by returning a comma
7379 separated list with numerical IDs of effects
7380 instances.
7381 </t>
7382 </list>
7383 </t>
7384 <t>Example:</t>
7385 <t>
7386 <list>
7387 <t>C: "LIST EFFECT_INSTANCES"</t>
7388 <t>S: "9,11,14,15,16,17,25"</t>
7389 </list>
7390 </t>
7391 </section>
7392
7393 <section title="Retrieving current information about an effect instance" anchor="GET EFFECT_INSTANCE INFO" lscp_cmd="true">
7394 <t>The front-end can ask for the current information about
7395 a particular effect instance by sending the following command:</t>
7396 <t>
7397 <list>
7398 <t>GET EFFECT_INSTANCE INFO &lt;effect-instance&gt;</t>
7399 </list>
7400 </t>
7401 <t>Where &lt;effect-instance&gt; is the numerical ID of an
7402 effect instance as returned by the
7403 <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref>
7404 or
7405 <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7406 command.</t>
7407
7408 <t>Possible Answers:</t>
7409 <t>
7410 <list>
7411 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
7412 Each answer line begins with the information
7413 category name, followed by a colon and then a space
7414 character &lt;SP&gt; and finally the info character
7415 string to that information category. At the
7416 moment the following categories are defined:</t>
7417 <t>
7418 <list>
7419 <t>SYSTEM -
7420 <list>
7421 <t>name of the effect plugin system
7422 the effect is based on
7423 (e.g. "LADSPA")</t>
7424 </list>
7425 </t>
7426 <t>MODULE -
7427 <list>
7428 <t>module of the effect plugin
7429 system that contains this effect,
7430 the module is usually the
7431 dynamic-linked library (DLL)
7432 filename of the effect plugin,
7433 including full path (note that this
7434 filename may contain
7435 <xref target="character_set">escape sequences</xref>)</t>
7436 </list>
7437 </t>
7438 <t>NAME -
7439 <list>
7440 <t>character string defining the
7441 unique name of the effect within its
7442 module (note that the character
7443 string may contain
7444 <xref target="character_set">escape sequences</xref>)</t>
7445 </list>
7446 </t>
7447 <t>DESCRIPTION -
7448 <list>
7449 <t>human readable name of the
7450 effect, intended to be displayed in
7451 user interfaces (note that the
7452 character string may contain
7453 <xref target="character_set">escape sequences</xref>)</t>
7454 </list>
7455 </t>
7456 <t>INPUT_CONTROLS -
7457 <list>
7458 <t>amount of input controls the
7459 effect instance provides, to allow
7460 controlling the effect parameters in
7461 realtime</t>
7462 </list>
7463 </t>
7464 </list>
7465 </t>
7466 </list>
7467 </t>
7468 <t>The mentioned fields above don't have to be in particular order.</t>
7469
7470 <t>Example:</t>
7471 <t>
7472 <list>
7473 <t>C: "GET EFFECT_INSTANCE INFO 3"</t>
7474 <t>S: "SYSTEM: LADSPA"</t>
7475 <t>&nbsp;&nbsp;&nbsp;"MODULE: /usr/lib/ladspa/mod_delay_1419.so"</t>
7476 <t>&nbsp;&nbsp;&nbsp;"NAME: modDelay"</t>
7477 <t>&nbsp;&nbsp;&nbsp;"DESCRIPTION: Modulatable delay"</t>
7478 <t>&nbsp;&nbsp;&nbsp;"INPUT_CONTROLS: 1"</t>
7479 <t>&nbsp;&nbsp;&nbsp;"."</t>
7480 </list>
7481 </t>
7482 </section>
7483
7484 <section title="Retrieving information about an effect parameter" anchor="GET EFFECT_INSTANCE_INPUT_CONTROL INFO" lscp_cmd="true">
7485 <t>Effects typically provide a certain set of effect
7486 parameters which can be altered by the user in realtime
7487 (e.g. depth of a reverb effect, duration of a delay effect,
7488 dry / wet signal ratio). Those controllable effect parameters
7489 are called "input controls". The front-end can ask for the
7490 current information of an effect instance's input control
7491 by sending the following command:</t>
7492 <t>
7493 <list>
7494 <t>GET EFFECT_INSTANCE_INPUT_CONTROL INFO &lt;effect-instance&gt; &lt;input-control&gt;</t>
7495 </list>
7496 </t>
7497 <t>Where &lt;effect-instance&gt; is the numerical ID of an
7498 effect instance as returned by the
7499 <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref>
7500 or
7501 <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7502 command and &lt;input-control&gt; is the index of the input
7503 control within the numerical bounds as returned by the
7504 "INPUT_CONTROLS" field of the
7505 <xref target="GET EFFECT_INSTANCE INFO">"GET EFFECT_INSTANCE INFO"</xref>
7506 command.</t>
7507
7508 <t>Possible Answers:</t>
7509 <t>
7510 <list>
7511 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
7512 Each answer line begins with the information
7513 category name, followed by a colon and then a space
7514 character &lt;SP&gt; and finally the info character
7515 string to that information category. There are
7516 information categories which are always returned,
7517 independent of the respective effect parameter and
7518 there are optional information categories
7519 which are only shown for certain effect parameters.
7520 At the moment the following categories are defined:</t>
7521 <t>
7522 <list>
7523 <t>DESCRIPTION -
7524 <list>
7525 <t>(always returned)
7526 human readable name of the
7527 effect parameter, intended to be
7528 displayed in user interfaces (note
7529 that the character string may
7530 contain <xref target="character_set">escape sequences</xref>)</t>
7531 </list>
7532 </t>
7533 <t>VALUE -
7534 <list>
7535 <t>
7536 (always returned)
7537 current (optional dotted)
7538 floating point value of this effect
7539 parameter</t>
7540 </list>
7541 </t>
7542 <t>RANGE_MIN -
7543 <list>
7544 <t>
7545 (optionally returned)
7546 minimum allowed value for this
7547 effect parameter</t>
7548 </list>
7549 </t>
7550 <t>RANGE_MAX -
7551 <list>
7552 <t>
7553 (optionally returned)
7554 maximum allowed value for this
7555 effect parameter</t>
7556 </list>
7557 </t>
7558 <t>POSSIBILITIES -
7559 <list>
7560 <t>
7561 (optionally returned)
7562 comma separated list of
7563 (optional dotted) floating point
7564 numbers, reflecting the exact set of
7565 possible values for this effect
7566 parameter</t>
7567 </list>
7568 </t>
7569 <t>DEFAULT -
7570 <list>
7571 <t>
7572 (optionally returned)
7573 default value of this effect
7574 parameter</t>
7575 </list>
7576 </t>
7577 </list>
7578 </t>
7579 </list>
7580 </t>
7581 <t>The mentioned fields above don't have to be in particular order.</t>
7582
7583 <t>Example:</t>
7584 <t>
7585 <list>
7586 <t>C: "GET EFFECT_INSTANCE_INPUT_CONTROL INFO 1 0"</t>
7587 <t>S: "DESCRIPTION: Base delay (s)"</t>
7588 <t>&nbsp;&nbsp;&nbsp;"VALUE: 0.500"</t>
7589 <t>&nbsp;&nbsp;&nbsp;"RANGE_MIN: 0.000"</t>
7590 <t>&nbsp;&nbsp;&nbsp;"."</t>
7591 </list>
7592 </t>
7593 </section>
7594
7595 <section title="Altering an effect parameter" anchor="SET EFFECT_INSTANCE_INPUT_CONTROL VALUE" lscp_cmd="true">
7596 <t>The front-end can alter the current value of an effect
7597 parameter by sending the following command:</t>
7598 <t>
7599 <list>
7600 <t>SET EFFECT_INSTANCE_INPUT_CONTROL VALUE &lt;effect-instance&gt; &lt;input-control&gt; &lt;value&gt;</t>
7601 </list>
7602 </t>
7603 <t>Where &lt;effect-instance&gt; is the numerical ID of the
7604 effect instance as returned by the
7605 <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref> or
7606 <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7607 command, &lt;input-control&gt; is the index of the input
7608 control within the numerical bounds as returned by the
7609 "INPUT_CONTROLS" field of the
7610 <xref target="GET EFFECT_INSTANCE INFO">"GET EFFECT_INSTANCE INFO"</xref>
7611 command and &lt;value&gt; is the new (optional dotted)
7612 floating point value for this effect parameter.</t>
7613
7614 <t>Possible Answers:</t>
7615 <t>
7616 <list>
7617 <t>"OK" -
7618 <list>
7619 <t>in case the effect was altered successfully</t>
7620 </list>
7621 </t>
7622 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7623 <list>
7624 <t>in case it failed, providing an appropriate error code and
7625 error message</t>
7626 </list>
7627 </t>
7628 </list>
7629 </t>
7630
7631 <t>Examples:</t>
7632 <t>
7633 <list>
7634 <t>C: "SET EFFECT_INSTANCE_INPUT_CONTROL VALUE 0 1 0.5"</t>
7635 <t>S: "OK"</t>
7636 </list>
7637 </t>
7638 </section>
7639
7640 <section title="Retrieve amount of send effect chains" anchor="GET SEND_EFFECT_CHAINS" lscp_cmd="true">
7641 <t>The front-end can retrieve the current amount of send
7642 effect chains of an audio output device by sending the
7643 following command:</t>
7644 <t>
7645 <list>
7646 <t>GET SEND_EFFECT_CHAINS &lt;audio-device&gt;</t>
7647 </list>
7648 </t>
7649 <t>Where &lt;audio-device&gt; should be replaced by the
7650 numerical ID of the audio output device as given by the
7651 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7652 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7653 command.</t>
7654
7655 <t>Possible Answers:</t>
7656 <t>
7657 <list>
7658 <t>The sampler will answer by returning the current
7659 number of send effect chains of the supplied audio
7660 output device.</t>
7661 </list>
7662 </t>
7663
7664 <t>Examples:</t>
7665 <t>
7666 <list>
7667 <t>C: "GET SEND_EFFECT_CHAINS 0"</t>
7668 <t>S: "4"</t>
7669 </list>
7670 </t>
7671 </section>
7672
7673 <section title="Retrieve list of send effect chains" anchor="LIST SEND_EFFECT_CHAINS" lscp_cmd="true">
7674 <t>The front-end can retrieve the current list of send
7675 effect chains of an audio output device by sending the
7676 following command:</t>
7677 <t>
7678 <list>
7679 <t>LIST SEND_EFFECT_CHAINS &lt;audio-device&gt;</t>
7680 </list>
7681 </t>
7682 <t>Where &lt;audio-device&gt; should be replaced by the
7683 numerical ID of the audio output device as given by the
7684 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7685 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7686 command.</t>
7687
7688 <t>Possible Answers:</t>
7689 <t>
7690 <list>
7691 <t>The sampler will answer by returning a comma
7692 separated list with numerical IDs of send effect
7693 chains of the supplied audio output device.
7694 </t>
7695 </list>
7696 </t>
7697
7698 <t>Examples:</t>
7699 <t>
7700 <list>
7701 <t>C: "LIST SEND_EFFECT_CHAINS 0"</t>
7702 <t>S: "3,4,7"</t>
7703 </list>
7704 </t>
7705 </section>
7706
7707 <section title="Add send effect chain" anchor="ADD SEND_EFFECT_CHAIN" lscp_cmd="true">
7708 <t>The front-end can add a send effect chain by sending the
7709 following command:</t>
7710 <t>
7711 <list>
7712 <t>ADD SEND_EFFECT_CHAIN &lt;audio-device&gt;</t>
7713 </list>
7714 </t>
7715 <t>Where &lt;audio-device&gt; should be replaced by the
7716 numerical ID of the audio output device as given by the
7717 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7718 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7719 command.</t>
7720
7721 <t>Possible Answers:</t>
7722 <t>
7723 <list>
7724 <t>"OK[&lt;effect-chain&gt;]" -
7725 <list>
7726 <t>in case the send effect chain was
7727 added successfully, where
7728 &lt;effect-chain&gt; is the numerical ID
7729 of the new send effect chain</t>
7730 </list>
7731 </t>
7732 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7733 <list>
7734 <t>if the send effect chain could not be added</t>
7735 </list>
7736 </t>
7737 </list>
7738 </t>
7739
7740 <t>Examples:</t>
7741 <t>
7742 <list>
7743 <t>C: "ADD SEND_EFFECT_CHAIN 0"</t>
7744 <t>S: "OK[2]"</t>
7745 </list>
7746 </t>
7747 </section>
7748
7749 <section title="Remove send effect chain" anchor="REMOVE SEND_EFFECT_CHAIN" lscp_cmd="true">
7750 <t>The front-end can remove a send effect chain by sending
7751 the following command:</t>
7752 <t>
7753 <list>
7754 <t>REMOVE SEND_EFFECT_CHAIN &lt;audio-device&gt; &lt;effect-chain&gt;</t>
7755 </list>
7756 </t>
7757 <t>Where &lt;audio-device&gt; should be replaced by the
7758 numerical ID of the audio output device as given by the
7759 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7760 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7761 command and &lt;effect-chain&gt; by the numerical ID as
7762 returned by the
7763 <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
7764 or
7765 <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
7766 command.</t>
7767
7768 <t>Possible Answers:</t>
7769 <t>
7770 <list>
7771 <t>"OK" -
7772 <list>
7773 <t>in case the send effect chain was
7774 removed successfully</t>
7775 </list>
7776 </t>
7777 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7778 <list>
7779 <t>if the send effect chain could not be removed</t>
7780 </list>
7781 </t>
7782 </list>
7783 </t>
7784
7785 <t>Examples:</t>
7786 <t>
7787 <list>
7788 <t>C: "REMOVE SEND_EFFECT_CHAIN 0 2"</t>
7789 <t>S: "OK"</t>
7790 </list>
7791 </t>
7792 </section>
7793
7794 <section title="Retrieving information about a send effect chain" anchor="GET SEND_EFFECT_CHAIN INFO" lscp_cmd="true">
7795 <t>The front-end can ask for information of a send effect
7796 chain by sending the following command:</t>
7797 <t>
7798 <list>
7799 <t>GET SEND_EFFECT_CHAIN INFO &lt;audio-device&gt; &lt;effect-chain&gt;</t>
7800 </list>
7801 </t>
7802 <t>Where &lt;audio-device&gt; should be replaced by the
7803 numerical ID of the audio output device as given by the
7804 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7805 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7806 command and &lt;effect-chain&gt; by the numerical ID as
7807 returned by the
7808 <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
7809 or
7810 <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
7811 command.</t>
7812
7813 <t>Possible Answers:</t>
7814 <t>
7815 <list>
7816 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
7817 Each answer line begins with the information
7818 category name, followed by a colon and then a space
7819 character &lt;SP&gt; and finally the info character
7820 string to that information category.
7821 At the moment the following categories are defined:</t>
7822 <t>
7823 <list>
7824 <t>EFFECT_COUNT -
7825 <list>
7826 <t>amount of effects in this send
7827 effect chain</t>
7828 </list>
7829 </t>
7830 <t>EFFECT_SEQUENCE -
7831 <list>
7832 <t>comma separated list of the
7833 numerical IDs of the effect
7834 instances in this send effect chain,
7835 in the order as they are procssed in
7836 the effect chain</t>
7837 </list>
7838 </t>
7839 </list>
7840 </t>
7841 </list>
7842 </t>
7843 <t>The mentioned fields above don't have to be in particular order.</t>
7844
7845 <t>Example:</t>
7846 <t>
7847 <list>
7848 <t>C: "GET SEND_EFFECT_CHAIN INFO 0 2"</t>
7849 <t>S: "EFFECT_COUNT: 3"</t>
7850 <t>&nbsp;&nbsp;&nbsp;"EFFECT_SEQUENCE: 31,4,7"</t>
7851 <t>&nbsp;&nbsp;&nbsp;"."</t>
7852 </list>
7853 </t>
7854 </section>
7855
7856 <section title="Append effect instance to a send effect chain" anchor="APPEND SEND_EFFECT_CHAIN EFFECT" lscp_cmd="true">
7857 <t>The front-end can add an unused effect instance to the
7858 end of a send effect chain by sending the following command:</t>
7859 <t>
7860 <list>
7861 <t>APPEND SEND_EFFECT_CHAIN EFFECT &lt;audio-device&gt; &lt;effect-chain&gt; &lt;effect-instance&gt;</t>
7862 </list>
7863 </t>
7864 <t>Where &lt;audio-device&gt; should be replaced by the
7865 numerical ID of the audio output device as given by the
7866 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7867 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7868 command and &lt;effect-chain&gt; by the numerical ID as
7869 returned by the
7870 <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
7871 or
7872 <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
7873 command and &lt;effect-instance&gt; as returned by the
7874 <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref> or
7875 <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7876 command.</t>
7877 <t>Only unused effect instances can be added to the effect
7878 chain. Trying to add an effect instance which is already in
7879 use somewhere in the audio signal path of the sampler will
7880 result in an error.</t>
7881
7882 <t>Possible Answers:</t>
7883 <t>
7884 <list>
7885 <t>"OK" -
7886 <list>
7887 <t>in case the effect instance was
7888 added successfully to the chain</t>
7889 </list>
7890 </t>
7891 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7892 <list>
7893 <t>if the effect instance could not be added</t>
7894 </list>
7895 </t>
7896 </list>
7897 </t>
7898
7899 <t>Examples:</t>
7900 <t>
7901 <list>
7902 <t>C: "APPEND SEND_EFFECT_CHAIN EFFECT 0 2 38"</t>
7903 <t>S: "OK"</t>
7904 </list>
7905 </t>
7906 </section>
7907
7908 <section title="Insert effect instance to a send effect chain" anchor="INSERT SEND_EFFECT_CHAIN EFFECT" lscp_cmd="true">
7909 <t>The front-end can add an unused effect instance to a
7910 certain position of a send effect chain by sending the
7911 following command:</t>
7912 <t>
7913 <list>
7914 <t>INSERT SEND_EFFECT_CHAIN EFFECT &lt;audio-device&gt; &lt;effect-chain&gt; &lt;chain-pos&gt; &lt;effect-instance&gt;</t>
7915 </list>
7916 </t>
7917 <t>Where &lt;audio-device&gt; should be replaced by the
7918 numerical ID of the audio output device as given by the
7919 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7920 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7921 command, &lt;effect-chain&gt; by the numerical ID as
7922 returned by the
7923 <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
7924 or
7925 <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
7926 command, &lt;effect-instance&gt; as returned by the
7927 <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref> or
7928 <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7929 command and &lt;chain-pos&gt; the exact position of the
7930 effect chain where the supplied effect shall be inserted
7931 to.</t>
7932 <t>Only unused effect instances can be added to the effect
7933 chain. Trying to add an effect instance which is already in
7934 use somewhere in the audio signal path of the sampler will
7935 result in an error.</t>
7936
7937 <t>Possible Answers:</t>
7938 <t>
7939 <list>
7940 <t>"OK" -
7941 <list>
7942 <t>in case the effect instance was
7943 added successfully to the chain</t>
7944 </list>
7945 </t>
7946 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7947 <list>
7948 <t>if the effect instance could not be added</t>
7949 </list>
7950 </t>
7951 </list>
7952 </t>
7953
7954 <t>Examples:</t>
7955 <t>
7956 <list>
7957 <t>C: "INSERT SEND_EFFECT_CHAIN EFFECT 0 2 4 38"</t>
7958 <t>S: "OK"</t>
7959 </list>
7960 </t>
7961 </section>
7962
7963 <section title="Remove effect instance from send effect chain" anchor="REMOVE SEND_EFFECT_CHAIN EFFECT" lscp_cmd="true">
7964 <t>The front-end can remove an effect instance from a
7965 certain position of a send effect chain by sending the
7966 following command:</t>
7967 <t>
7968 <list>
7969 <t>REMOVE SEND_EFFECT_CHAIN EFFECT &lt;audio-device&gt; &lt;effect-chain&gt; &lt;chain-pos&gt;</t>
7970 </list>
7971 </t>
7972 <t>Where &lt;audio-device&gt; should be replaced by the
7973 numerical ID of the audio output device as given by the
7974 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7975 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7976 command, &lt;effect-chain&gt; by the numerical ID as
7977 returned by the
7978 <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
7979 or
7980 <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
7981 command and &lt;chain-pos&gt; the exact position of the
7982 effect instance to be removed from the effect chain.</t>
7983
7984 <t>Possible Answers:</t>
7985 <t>
7986 <list>
7987 <t>"OK" -
7988 <list>
7989 <t>in case the effect instance was
7990 removed successfully</t>
7991 </list>
7992 </t>
7993 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7994 <list>
7995 <t>if the effect instance could not be removed</t>
7996 </list>
7997 </t>
7998 </list>
7999 </t>
8000
8001 <t>Examples:</t>
8002 <t>
8003 <list>
8004 <t>C: "REMOVE SEND_EFFECT_CHAIN EFFECT 0 2 4"</t>
8005 <t>S: "OK"</t>
8006 </list>
8007 </t>
8008 </section>
8009
8010 </section>
8011 </section>
8012
8013 <section title="Command Syntax" anchor="command_syntax">
8014 <t>The grammar of the control protocol as descibed in <xref target="control_commands"/>
8015 is defined below using Backus-Naur Form (BNF as described in <xref target="RFC2234"/>)
8016 where applicable.
8017 </t>
8018 <!--
8019 This section is automatically generated by scripts/update_grammar.pl
8020 from src/network/lscp.y (yacc input file). Do not modify this section
8021 manually !
8022 -->
8023 <!-- GRAMMAR_BNF_BEGIN - do NOT delete or modify this line !!! -->
8024
8025 <t>input =
8026 <list>
8027 <t>line
8028 </t>
8029 <t>/ error
8030 </t>
8031 </list>
8032 </t>
8033 <t>line =
8034 <list>
8035 <t>statement LF
8036 </t>
8037 <t>/ statement CR LF
8038 </t>
8039 </list>
8040 </t>
8041 <t>statement =
8042 <list>
8043 <t>/* epsilon (empty statement/line ignored) */
8044 </t>
8045 <t>/ comment
8046 </t>
8047 <t>/ command
8048 </t>
8049 </list>
8050 </t>
8051 <t>comment =
8052 <list>
8053 <t>'#'
8054 </t>
8055 <t>/ comment '#'
8056 </t>
8057 <t>/ comment SP
8058 </t>
8059 <t>/ comment number
8060 </t>
8061 <t>/ comment string
8062 </t>
8063 </list>
8064 </t>
8065 <t>command =
8066 <list>
8067 <t>ADD SP add_instruction
8068 </t>
8069 <t>/ MAP SP map_instruction
8070 </t>
8071 <t>/ UNMAP SP unmap_instruction
8072 </t>
8073 <t>/ GET SP get_instruction
8074 </t>
8075 <t>/ CREATE SP create_instruction
8076 </t>
8077 <t>/ DESTROY SP destroy_instruction
8078 </t>
8079 <t>/ LIST SP list_instruction
8080 </t>
8081 <t>/ LOAD SP load_instruction
8082 </t>
8083 <t>/ REMOVE SP remove_instruction
8084 </t>
8085 <t>/ SET SP set_instruction
8086 </t>
8087 <t>/ SUBSCRIBE SP subscribe_event
8088 </t>
8089 <t>/ UNSUBSCRIBE SP unsubscribe_event
8090 </t>
8091 <t>/ RESET SP reset_instruction
8092 </t>
8093 <t>/ CLEAR SP clear_instruction
8094 </t>
8095 <t>/ FIND SP find_instruction
8096 </t>
8097 <t>/ MOVE SP move_instruction
8098 </t>
8099 <t>/ COPY SP copy_instruction
8100 </t>
8101 <t>/ EDIT SP edit_instruction
8102 </t>
8103 <t>/ FORMAT SP format_instruction
8104 </t>
8105 <t>/ SEND SP send_instruction
8106 </t>
8107 <t>/ APPEND SP append_instruction
8108 </t>
8109 <t>/ INSERT SP insert_instruction
8110 </t>
8111 <t>/ RESET
8112 </t>
8113 <t>/ QUIT
8114 </t>
8115 </list>
8116 </t>
8117 <t>add_instruction =
8118 <list>
8119 <t>CHANNEL
8120 </t>
8121 <t>/ CHANNEL SP MIDI_INPUT SP sampler_channel SP device_index
8122 </t>
8123 <t>/ CHANNEL SP MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index
8124 </t>
8125 <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
8126 </t>
8127 <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename
8128 </t>
8129 <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP FILE_AS_DIR SP db_path SP filename
8130 </t>
8131 <t>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename
8132 </t>
8133 <t>/ DB_INSTRUMENTS SP scan_mode SP FILE_AS_DIR SP db_path SP filename
8134 </t>
8135 <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
8136 </t>
8137 <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index
8138 </t>
8139 <t>/ DB_INSTRUMENTS SP db_path SP filename
8140 </t>
8141 <t>/ DB_INSTRUMENTS SP db_path SP filename SP instrument_index
8142 </t>
8143 <t>/ MIDI_INSTRUMENT_MAP
8144 </t>
8145 <t>/ MIDI_INSTRUMENT_MAP SP map_name
8146 </t>
8147 <t>/ SEND_EFFECT_CHAIN SP device_index
8148 </t>
8149 </list>
8150 </t>
8151 <t>subscribe_event =
8152 <list>
8153 <t>AUDIO_OUTPUT_DEVICE_COUNT
8154 </t>
8155 <t>/ AUDIO_OUTPUT_DEVICE_INFO
8156 </t>
8157 <t>/ MIDI_INPUT_DEVICE_COUNT
8158 </t>
8159 <t>/ MIDI_INPUT_DEVICE_INFO
8160 </t>
8161 <t>/ CHANNEL_COUNT
8162 </t>
8163 <t>/ CHANNEL_MIDI
8164 </t>
8165 <t>/ DEVICE_MIDI
8166 </t>
8167 <t>/ VOICE_COUNT
8168 </t>
8169 <t>/ STREAM_COUNT
8170 </t>
8171 <t>/ BUFFER_FILL
8172 </t>
8173 <t>/ CHANNEL_INFO
8174 </t>
8175 <t>/ FX_SEND_COUNT
8176 </t>
8177 <t>/ FX_SEND_INFO
8178 </t>
8179 <t>/ MIDI_INSTRUMENT_MAP_COUNT
8180 </t>
8181 <t>/ MIDI_INSTRUMENT_MAP_INFO
8182 </t>
8183 <t>/ MIDI_INSTRUMENT_COUNT
8184 </t>
8185 <t>/ MIDI_INSTRUMENT_INFO
8186 </t>
8187 <t>/ DB_INSTRUMENT_DIRECTORY_COUNT
8188 </t>
8189 <t>/ DB_INSTRUMENT_DIRECTORY_INFO
8190 </t>
8191 <t>/ DB_INSTRUMENT_COUNT
8192 </t>
8193 <t>/ DB_INSTRUMENT_INFO
8194 </t>
8195 <t>/ DB_INSTRUMENTS_JOB_INFO
8196 </t>
8197 <t>/ MISCELLANEOUS
8198 </t>
8199 <t>/ TOTAL_STREAM_COUNT
8200 </t>
8201 <t>/ TOTAL_VOICE_COUNT
8202 </t>
8203 <t>/ GLOBAL_INFO
8204 </t>
8205 <t>/ EFFECT_INSTANCE_COUNT
8206 </t>
8207 <t>/ EFFECT_INSTANCE_INFO
8208 </t>
8209 <t>/ SEND_EFFECT_CHAIN_COUNT
8210 </t>
8211 <t>/ SEND_EFFECT_CHAIN_INFO
8212 </t>
8213 </list>
8214 </t>
8215 <t>unsubscribe_event =
8216 <list>
8217 <t>AUDIO_OUTPUT_DEVICE_COUNT
8218 </t>
8219 <t>/ AUDIO_OUTPUT_DEVICE_INFO
8220 </t>
8221 <t>/ MIDI_INPUT_DEVICE_COUNT
8222 </t>
8223 <t>/ MIDI_INPUT_DEVICE_INFO
8224 </t>
8225 <t>/ CHANNEL_COUNT
8226 </t>
8227 <t>/ CHANNEL_MIDI
8228 </t>
8229 <t>/ DEVICE_MIDI
8230 </t>
8231 <t>/ VOICE_COUNT
8232 </t>
8233 <t>/ STREAM_COUNT
8234 </t>
8235 <t>/ BUFFER_FILL
8236 </t>
8237 <t>/ CHANNEL_INFO
8238 </t>
8239 <t>/ FX_SEND_COUNT
8240 </t>
8241 <t>/ FX_SEND_INFO
8242 </t>
8243 <t>/ MIDI_INSTRUMENT_MAP_COUNT
8244 </t>
8245 <t>/ MIDI_INSTRUMENT_MAP_INFO
8246 </t>
8247 <t>/ MIDI_INSTRUMENT_COUNT
8248 </t>
8249 <t>/ MIDI_INSTRUMENT_INFO
8250 </t>
8251 <t>/ DB_INSTRUMENT_DIRECTORY_COUNT
8252 </t>
8253 <t>/ DB_INSTRUMENT_DIRECTORY_INFO
8254 </t>
8255 <t>/ DB_INSTRUMENT_COUNT
8256 </t>
8257 <t>/ DB_INSTRUMENT_INFO
8258 </t>
8259 <t>/ DB_INSTRUMENTS_JOB_INFO
8260 </t>
8261 <t>/ MISCELLANEOUS
8262 </t>
8263 <t>/ TOTAL_STREAM_COUNT
8264 </t>
8265 <t>/ TOTAL_VOICE_COUNT
8266 </t>
8267 <t>/ GLOBAL_INFO
8268 </t>
8269 <t>/ EFFECT_INSTANCE_COUNT
8270 </t>
8271 <t>/ EFFECT_INSTANCE_INFO
8272 </t>
8273 <t>/ SEND_EFFECT_CHAIN_COUNT
8274 </t>
8275 <t>/ SEND_EFFECT_CHAIN_INFO
8276 </t>
8277 </list>
8278 </t>
8279 <t>map_instruction =
8280 <list>
8281 <t>MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value
8282 </t>
8283 <t>/ MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode
8284 </t>
8285 <t>/ MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP entry_name
8286 </t>
8287 <t>/ MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode SP entry_name
8288 </t>
8289 </list>
8290 </t>
8291 <t>unmap_instruction =
8292 <list>
8293 <t>MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog
8294 </t>
8295 </list>
8296 </t>
8297 <t>remove_instruction =
8298 <list>
8299 <t>CHANNEL SP sampler_channel
8300 </t>
8301 <t>/ CHANNEL SP MIDI_INPUT SP sampler_channel
8302 </t>
8303 <t>/ CHANNEL SP MIDI_INPUT SP sampler_channel SP device_index
8304 </t>
8305 <t>/ CHANNEL SP MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index
8306 </t>
8307 <t>/ MIDI_INSTRUMENT_MAP SP midi_map
8308 </t>
8309 <t>/ MIDI_INSTRUMENT_MAP SP ALL
8310 </t>
8311 <t>/ SEND_EFFECT_CHAIN SP device_index SP effect_chain
8312 </t>
8313 <t>/ SEND_EFFECT_CHAIN SP EFFECT SP device_index SP effect_chain SP chain_pos
8314 </t>
8315 <t>/ FX_SEND SP EFFECT SP sampler_channel SP fx_send_id
8316 </t>
8317 <t>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path
8318 </t>
8319 <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
8320 </t>
8321 <t>/ DB_INSTRUMENT SP db_path
8322 </t>
8323 </list>
8324 </t>
8325 <t>get_instruction =
8326 <list>
8327 <t>AVAILABLE_ENGINES
8328 </t>
8329 <t>/ AVAILABLE_EFFECTS
8330 </t>
8331 <t>/ EFFECT_INSTANCES
8332 </t>
8333 <t>/ EFFECT SP INFO SP effect_index
8334 </t>
8335 <t>/ EFFECT_INSTANCE SP INFO SP effect_instance
8336 </t>
8337 <t>/ EFFECT_INSTANCE_INPUT_CONTROL SP INFO SP effect_instance SP input_control
8338 </t>
8339 <t>/ SEND_EFFECT_CHAINS SP device_index
8340 </t>
8341 <t>/ SEND_EFFECT_CHAIN SP INFO SP device_index SP effect_chain
8342 </t>
8343 <t>/ AVAILABLE_MIDI_INPUT_DRIVERS
8344 </t>
8345 <t>/ MIDI_INPUT_DRIVER SP INFO SP string
8346 </t>
8347 <t>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
8348 </t>
8349 <t>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
8350 </t>
8351 <t>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
8352 </t>
8353 <t>/ AUDIO_OUTPUT_DRIVER SP INFO SP string
8354 </t>
8355 <t>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
8356 </t>
8357 <t>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
8358 </t>
8359 <t>/ AUDIO_OUTPUT_DEVICES
8360 </t>
8361 <t>/ MIDI_INPUT_DEVICES
8362 </t>
8363 <t>/ AUDIO_OUTPUT_DEVICE SP INFO SP number
8364 </t>
8365 <t>/ MIDI_INPUT_DEVICE SP INFO SP number
8366 </t>
8367 <t>/ MIDI_INPUT_PORT SP INFO SP number SP number
8368 </t>
8369 <t>/ MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
8370 </t>
8371 <t>/ AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
8372 </t>
8373 <t>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP string
8374 </t>
8375 <t>/ CHANNELS
8376 </t>
8377 <t>/ CHANNEL SP INFO SP sampler_channel
8378 </t>
8379 <t>/ CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
8380 </t>
8381 <t>/ CHANNEL SP STREAM_COUNT SP sampler_channel
8382 </t>
8383 <t>/ CHANNEL SP VOICE_COUNT SP sampler_channel
8384 </t>
8385 <t>/ ENGINE SP INFO SP engine_name
8386 </t>
8387 <t>/ SERVER SP INFO
8388 </t>
8389 <t>/ TOTAL_STREAM_COUNT
8390 </t>
8391 <t>/ TOTAL_VOICE_COUNT
8392 </t>
8393 <t>/ TOTAL_VOICE_COUNT_MAX
8394 </t>
8395 <t>/ MIDI_INSTRUMENTS SP midi_map
8396 </t>
8397 <t>/ MIDI_INSTRUMENTS SP ALL
8398 </t>
8399 <t>/ MIDI_INSTRUMENT SP INFO SP midi_map SP midi_bank SP midi_prog
8400 </t>
8401 <t>/ MIDI_INSTRUMENT_MAPS
8402 </t>
8403 <t>/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map
8404 </t>
8405 <t>/ FX_SENDS SP sampler_channel
8406 </t>
8407 <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
8408 </t>
8409 <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
8410 </t>
8411 <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
8412 </t>
8413 <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP db_path
8414 </t>
8415 <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
8416 </t>
8417 <t>/ DB_INSTRUMENTS SP db_path
8418 </t>
8419 <t>/ DB_INSTRUMENT SP INFO SP db_path
8420 </t>
8421 <t>/ DB_INSTRUMENTS_JOB SP INFO SP number
8422 </t>
8423 <t>/ VOLUME
8424 </t>
8425 <t>/ VOICES
8426 </t>
8427 <t>/ STREAMS
8428 </t>
8429 <t>/ FILE SP INSTRUMENTS SP filename
8430 </t>
8431 <t>/ FILE SP INSTRUMENT SP INFO SP filename SP instrument_index
8432 </t>
8433 </list>
8434 </t>
8435 <t>set_instruction =
8436 <list>
8437 <t>AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
8438 </t>
8439 <t>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '=' param_val_list
8440 </t>
8441 <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
8442 </t>
8443 <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE
8444 </t>
8445 <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list
8446 </t>
8447 <t>/ EFFECT_INSTANCE_INPUT_CONTROL SP VALUE SP effect_instance SP input_control SP control_value
8448 </t>
8449 <t>/ CHANNEL SP set_chan_instruction
8450 </t>
8451 <t>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
8452 </t>
8453 <t>/ FX_SEND SP NAME SP sampler_channel SP fx_send_id SP fx_send_name
8454 </t>
8455 <t>/ FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id SP audio_channel_index SP audio_channel_index
8456 </t>
8457 <t>/ FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP midi_ctrl
8458 </t>
8459 <t>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
8460 </t>
8461 <t>/ FX_SEND SP EFFECT SP sampler_channel SP fx_send_id SP effect_chain SP chain_pos
8462 </t>
8463 <t>/ DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped
8464 </t>
8465 <t>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped
8466 </t>
8467 <t>/ DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped
8468 </t>
8469 <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
8470 </t>
8471 <t>/ DB_INSTRUMENT SP FILE_PATH SP filename SP filename
8472 </t>
8473 <t>/ ECHO SP boolean
8474 </t>
8475 <t>/ SHELL SP INTERACT SP boolean
8476 </t>
8477 <t>/ SHELL SP AUTO_CORRECT SP boolean
8478 </t>
8479 <t>/ SHELL SP DOC SP boolean
8480 </t>
8481 <t>/ VOLUME SP volume_value
8482 </t>
8483 <t>/ VOICES SP number
8484 </t>
8485 <t>/ STREAMS SP number
8486 </t>
8487 </list>
8488 </t>
8489 <t>create_instruction =
8490 <list>
8491 <t>AUDIO_OUTPUT_DEVICE SP string SP key_val_list
8492 </t>
8493 <t>/ AUDIO_OUTPUT_DEVICE SP string
8494 </t>
8495 <t>/ MIDI_INPUT_DEVICE SP string SP key_val_list
8496 </t>
8497 <t>/ MIDI_INPUT_DEVICE SP string
8498 </t>
8499 <t>/ FX_SEND SP sampler_channel SP midi_ctrl
8500 </t>
8501 <t>/ FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name
8502 </t>
8503 <t>/ EFFECT_INSTANCE SP effect_index
8504 </t>
8505 <t>/ EFFECT_INSTANCE SP effect_system SP module SP effect_name
8506 </t>
8507 </list>
8508 </t>
8509 <t>reset_instruction =
8510 <list>
8511 <t>CHANNEL SP sampler_channel
8512 </t>
8513 </list>
8514 </t>
8515 <t>clear_instruction =
8516 <list>
8517 <t>MIDI_INSTRUMENTS SP midi_map
8518 </t>
8519 <t>/ MIDI_INSTRUMENTS SP ALL
8520 </t>
8521 </list>
8522 </t>
8523 <t>find_instruction =
8524 <list>
8525 <t>DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list
8526 </t>
8527 <t>/ DB_INSTRUMENTS SP db_path SP query_val_list
8528 </t>
8529 <t>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP query_val_list
8530 </t>
8531 <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
8532 </t>
8533 <t>/ LOST SP DB_INSTRUMENT_FILES
8534 </t>
8535 </list>
8536 </t>
8537 <t>move_instruction =
8538 <list>
8539 <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
8540 </t>
8541 <t>/ DB_INSTRUMENT SP db_path SP db_path
8542 </t>
8543 </list>
8544 </t>
8545 <t>copy_instruction =
8546 <list>
8547 <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
8548 </t>
8549 <t>/ DB_INSTRUMENT SP db_path SP db_path
8550 </t>
8551 </list>
8552 </t>
8553 <t>destroy_instruction =
8554 <list>
8555 <t>AUDIO_OUTPUT_DEVICE SP number
8556 </t>
8557 <t>/ MIDI_INPUT_DEVICE SP number
8558 </t>
8559 <t>/ FX_SEND SP sampler_channel SP fx_send_id
8560 </t>
8561 <t>/ EFFECT_INSTANCE SP number
8562 </t>
8563 </list>
8564 </t>
8565 <t>load_instruction =
8566 <list>
8567 <t>INSTRUMENT SP load_instr_args
8568 </t>
8569 <t>/ ENGINE SP load_engine_args
8570 </t>
8571 </list>
8572 </t>
8573 <t>append_instruction =
8574 <list>
8575 <t>SEND_EFFECT_CHAIN SP EFFECT SP device_index SP effect_chain SP effect_instance
8576 </t>
8577 </list>
8578 </t>
8579 <t>insert_instruction =
8580 <list>
8581 <t>SEND_EFFECT_CHAIN SP EFFECT SP device_index SP effect_chain SP chain_pos SP effect_instance
8582 </t>
8583 </list>
8584 </t>
8585 <t>set_chan_instruction =
8586 <list>
8587 <t>AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
8588 </t>
8589 <t>/ AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index SP audio_channel_index
8590 </t>
8591 <t>/ AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
8592 </t>
8593 <t>/ MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index SP midi_input_channel_index
8594 </t>
8595 <t>/ MIDI_INPUT_DEVICE SP sampler_channel SP device_index
8596 </t>
8597 <t>/ MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
8598 </t>
8599 <t>/ MIDI_INPUT_CHANNEL SP sampler_channel SP midi_input_channel_index
8600 </t>
8601 <t>/ MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
8602 </t>
8603 <t>/ VOLUME SP sampler_channel SP volume_value
8604 </t>
8605 <t>/ MUTE SP sampler_channel SP boolean
8606 </t>
8607 <t>/ SOLO SP sampler_channel SP boolean
8608 </t>
8609 <t>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP midi_map
8610 </t>
8611 <t>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP NONE
8612 </t>
8613 <t>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP DEFAULT
8614 </t>
8615 </list>
8616 </t>
8617 <t>edit_instruction =
8618 <list>
8619 <t>CHANNEL SP INSTRUMENT SP sampler_channel
8620 </t>
8621 </list>
8622 </t>
8623 <t>format_instruction =
8624 <list>
8625 <t>INSTRUMENTS_DB
8626 </t>
8627 </list>
8628 </t>
8629 <t>modal_arg =
8630 <list>
8631 <t>/* epsilon (empty argument) */
8632 </t>
8633 <t>/ NON_MODAL SP
8634 </t>
8635 </list>
8636 </t>
8637 <t>key_val_list =
8638 <list>
8639 <t>string '=' param_val_list
8640 </t>
8641 <t>/ key_val_list SP string '=' param_val_list
8642 </t>
8643 </list>
8644 </t>
8645 <t>buffer_size_type =
8646 <list>
8647 <t>BYTES
8648 </t>
8649 <t>/ PERCENTAGE
8650 </t>
8651 </list>
8652 </t>
8653 <t>list_instruction =
8654 <list>
8655 <t>AUDIO_OUTPUT_DEVICES
8656 </t>
8657 <t>/ MIDI_INPUT_DEVICES
8658 </t>
8659 <t>/ CHANNELS
8660 </t>
8661 <t>/ CHANNEL SP MIDI_INPUTS SP sampler_channel
8662 </t>
8663 <t>/ AVAILABLE_ENGINES
8664 </t>
8665 <t>/ AVAILABLE_EFFECTS
8666 </t>
8667 <t>/ EFFECT_INSTANCES
8668 </t>
8669 <t>/ SEND_EFFECT_CHAINS SP number
8670 </t>
8671 <t>/ AVAILABLE_MIDI_INPUT_DRIVERS
8672 </t>
8673 <t>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
8674 </t>
8675 <t>/ MIDI_INSTRUMENTS SP midi_map
8676 </t>
8677 <t>/ MIDI_INSTRUMENTS SP ALL
8678 </t>
8679 <t>/ MIDI_INSTRUMENT_MAPS
8680 </t>
8681 <t>/ FX_SENDS SP sampler_channel
8682 </t>
8683 <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
8684 </t>
8685 <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
8686 </t>
8687 <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
8688 </t>
8689 <t>/ DB_INSTRUMENTS SP db_path
8690 </t>
8691 <t>/ FILE SP INSTRUMENTS SP filename
8692 </t>
8693 </list>
8694 </t>
8695 <t>send_instruction =
8696 <list>
8697 <t>CHANNEL SP MIDI_DATA SP string SP sampler_channel SP number SP number
8698 </t>
8699 </list>
8700 </t>
8701 <t>load_instr_args =
8702 <list>
8703 <t>filename SP instrument_index SP sampler_channel
8704 </t>
8705 <t>/ NON_MODAL SP filename SP instrument_index SP sampler_channel
8706 </t>
8707 </list>
8708 </t>
8709 <t>load_engine_args =
8710 <list>
8711 <t>engine_name SP sampler_channel
8712 </t>
8713 </list>
8714 </t>
8715 <t>instr_load_mode =
8716 <list>
8717 <t>ON_DEMAND
8718 </t>
8719 <t>/ ON_DEMAND_HOLD
8720 </t>
8721 <t>/ PERSISTENT
8722 </t>
8723 </list>
8724 </t>
8725 <t>effect_instance =
8726 <list>
8727 <t>number
8728 </t>
8729 </list>
8730 </t>
8731 <t>device_index =
8732 <list>
8733 <t>number
8734 </t>
8735 </list>
8736 </t>
8737 <t>audio_channel_index =
8738 <list>
8739 <t>number
8740 </t>
8741 </list>
8742 </t>
8743 <t>audio_output_type_name =
8744 <list>
8745 <t>string
8746 </t>
8747 </list>
8748 </t>
8749 <t>midi_input_port_index =
8750 <list>
8751 <t>number
8752 </t>
8753 </list>
8754 </t>
8755 <t>midi_input_channel_index =
8756 <list>
8757 <t>number
8758 </t>
8759 <t>/ ALL
8760 </t>
8761 </list>
8762 </t>
8763 <t>midi_input_type_name =
8764 <list>
8765 <t>string
8766 </t>
8767 </list>
8768 </t>
8769 <t>midi_map =
8770 <list>
8771 <t>number
8772 </t>
8773 </list>
8774 </t>
8775 <t>midi_bank =
8776 <list>
8777 <t>number
8778 </t>
8779 </list>
8780 </t>
8781 <t>midi_prog =
8782 <list>
8783 <t>number
8784 </t>
8785 </list>
8786 </t>
8787 <t>midi_ctrl =
8788 <list>
8789 <t>number
8790 </t>
8791 </list>
8792 </t>
8793 <t>volume_value =
8794 <list>
8795 <t>dotnum
8796 </t>
8797 <t>/ number
8798 </t>
8799 </list>
8800 </t>
8801 <t>control_value =
8802 <list>
8803 <t>real
8804 </t>
8805 </list>
8806 </t>
8807 <t>sampler_channel =
8808 <list>
8809 <t>number
8810 </t>
8811 </list>
8812 </t>
8813 <t>instrument_index =
8814 <list>
8815 <t>number
8816 </t>
8817 </list>
8818 </t>
8819 <t>fx_send_id =
8820 <list>
8821 <t>number
8822 </t>
8823 </list>
8824 </t>
8825 <t>engine_name =
8826 <list>
8827 <t>string
8828 </t>
8829 </list>
8830 </t>
8831 <t>filename =
8832 <list>
8833 <t>path
8834 </t>
8835 </list>
8836 </t>
8837 <t>db_path =
8838 <list>
8839 <t>path
8840 </t>
8841 </list>
8842 </t>
8843 <t>map_name =
8844 <list>
8845 <t>stringval_escaped
8846 </t>
8847 </list>
8848 </t>
8849 <t>entry_name =
8850 <list>
8851 <t>stringval_escaped
8852 </t>
8853 </list>
8854 </t>
8855 <t>fx_send_name =
8856 <list>
8857 <t>stringval_escaped
8858 </t>
8859 </list>
8860 </t>
8861 <t>effect_name =
8862 <list>
8863 <t>stringval_escaped
8864 </t>
8865 </list>
8866 </t>
8867 <t>effect_index =
8868 <list>
8869 <t>number
8870 </t>
8871 </list>
8872 </t>
8873 <t>effect_chain =
8874 <list>
8875 <t>number
8876 </t>
8877 </list>
8878 </t>
8879 <t>chain_pos =
8880 <list>
8881 <t>number
8882 </t>
8883 </list>
8884 </t>
8885 <t>input_control =
8886 <list>
8887 <t>number
8888 </t>
8889 </list>
8890 </t>
8891 <t>param_val_list =
8892 <list>
8893 <t>param_val
8894 </t>
8895 <t>/ param_val_list','param_val
8896 </t>
8897 </list>
8898 </t>
8899
8900 <t>param_val =
8901 <list>
8902 <t>string
8903 </t>
8904 <t>/ stringval
8905 </t>
8906 <t>/ number
8907 </t>
8908 <t>/ dotnum
8909 </t>
8910 </list>
8911 </t>
8912 <t>query_val_list =
8913 <list>
8914 <t>string '=' query_val
8915 </t>
8916 <t>/ query_val_list SP string '=' query_val
8917 </t>
8918 </list>
8919 </t>
8920 <t>query_val =
8921 <list>
8922 <t>text_escaped
8923 </t>
8924 <t>/ stringval_escaped
8925 </t>
8926 </list>
8927 </t>
8928 <t>scan_mode =
8929 <list>
8930 <t>RECURSIVE
8931 </t>
8932 <t>/ NON_RECURSIVE
8933 </t>
8934 <t>/ FLAT
8935 </t>
8936 </list>
8937 </t>
8938 <t>effect_system =
8939 <list>
8940 <t>string
8941 </t>
8942 </list>
8943 </t>
8944 <t>module =
8945 <list>
8946 <t>filename
8947 </t>
8948 </list>
8949 </t>
8950
8951 <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->
8952
8953 <section title="Character Set and Escape Sequences" anchor="character_set">
8954 <t>Older versions of this protocol up to and including v1.1 only
8955 supported the standard ASCII character set (ASCII code 0 - 127)
8956 <xref target="RFC20"/>, all younger versions of this protocol
8957 however support the Extended ASCII character set (ASCII code
8958 0 - 255). The same group of younger protocols also support
8959 escape sequences, but only for certain, explicitly declared
8960 parts of the protocol. The supported escape sequences are
8961 defined as follows:</t>
8962 <texttable>
8963 <ttcol>ASCII Character Sequence</ttcol>
8964 <ttcol>Translated into (Name)</ttcol>
8965 <c>\n</c> <c>new line</c>
8966 <c>\r</c> <c>carriage return</c>
8967 <c>\f</c> <c>form feed</c>
8968 <c>\t</c> <c>horizontal tab</c>
8969 <c>\v</c> <c>vertical tab</c>
8970 <c>\'</c> <c>apostrophe</c>
8971 <c>\"</c> <c>quotation mark</c>
8972 <c>\\</c> <c>backslash</c>
8973 <c>\OOO</c> <c>three digit octal ASCII code of the character</c>
8974 <c>\xHH</c> <c>two digit hex ASCII code of the character</c>
8975 </texttable>
8976 <t>Notice: due to the transition of certain parts of the
8977 protocol which now support escape sequences, a slight backward
8978 incompatibility to protocols version v1.1 and younger has been
8979 introduced. The only difference is that in parts of the protocol
8980 where escape characters are now supported, a backslash characters
8981 MUST be escaped as well (that is as double backslash), whereas
8982 in the old versions a single backslash was sufficient.</t>
8983
8984 <t>The following LSCP commands support escape sequences as part
8985 of their filename / path based arguments and / or may contain
8986 a filename / path with escape sequences in their response:
8987 <list>
8988 <t><xref target="LOAD INSTRUMENT">"LOAD INSTRUMENT"</xref></t>
8989 <t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t>
8990 <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
8991 <t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t>
8992 <t><xref target="ADD DB_INSTRUMENT_DIRECTORY">"ADD DB_INSTRUMENT_DIRECTORY"</xref></t>
8993 <t><xref target="ADD DB_INSTRUMENTS">"ADD DB_INSTRUMENTS"</xref></t>
8994 <t><xref target="REMOVE DB_INSTRUMENT_DIRECTORY">"REMOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
8995 <t><xref target="REMOVE DB_INSTRUMENT">"REMOVE DB_INSTRUMENT"</xref></t>
8996 <t><xref target="GET DB_INSTRUMENT_DIRECTORIES">"GET DB_INSTRUMENT_DIRECTORIES"</xref></t>
8997 <t><xref target="LIST DB_INSTRUMENT_DIRECTORIES">"LIST DB_INSTRUMENT_DIRECTORIES"</xref></t>
8998 <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
8999 <t><xref target="GET DB_INSTRUMENTS">"GET DB_INSTRUMENTS"</xref></t>
9000 <t><xref target="LIST DB_INSTRUMENTS">"LIST DB_INSTRUMENTS"</xref></t>
9001 <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
9002 <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
9003 <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
9004 <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
9005 <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
9006 <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
9007 <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
9008 <t><xref target="MOVE DB_INSTRUMENT">"MOVE DB_INSTRUMENT"</xref></t>
9009 <t><xref target="MOVE DB_INSTRUMENT_DIRECTORY">"MOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
9010 <t><xref target="COPY DB_INSTRUMENT">"COPY DB_INSTRUMENT"</xref></t>
9011 <t><xref target="COPY DB_INSTRUMENT_DIRECTORY">"COPY DB_INSTRUMENT_DIRECTORY"</xref></t>
9012 <t><xref target="FIND LOST DB_INSTRUMENT_FILES">"FIND LOST DB_INSTRUMENT_FILES"</xref></t>
9013 <t><xref target="SET DB_INSTRUMENT FILE_PATH">"SET DB_INSTRUMENT FILE_PATH"</xref></t>
9014 <t><xref target="GET FILE INSTRUMENTS">"GET FILE INSTRUMENTS"</xref></t>
9015 <t><xref target="LIST FILE INSTRUMENTS">"LIST FILE INSTRUMENTS"</xref></t>
9016 <t><xref target="GET FILE INSTRUMENT INFO">"GET FILE INSTRUMENT INFO"</xref></t>
9017 <t><xref target="GET EFFECT INFO">"GET EFFECT INFO"</xref></t>
9018 <t><xref target="GET EFFECT_INSTANCE INFO">"GET EFFECT_INSTANCE INFO"</xref></t>
9019 <t><xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref></t>
9020 </list>
9021 Note that the forward slash character ('/') has a special meaning in
9022 filename / path based arguments: it acts as separator of the nodes in
9023 the path, thus if a directory- or filename includes a forward slash
9024 (not intended as path node separator), you MUST escape that slash
9025 either with the respective hex escape sequence ("\x2f") or with the
9026 respective octal escape sequence ("\057").
9027 </t>
9028
9029 <t>
9030 Note for Windows: file path arguments in LSCP are expected
9031 to use forward slashes as directory node separator similar
9032 to Unix based operating systems. In contrast to Unix however
9033 a Windows typical drive character is expected to be
9034 prefixed to the path. That is an original Windows file path
9035 like "D:\Sounds\My.gig" would become in LSCP:
9036 "D:/Sounds/My.gig".
9037 </t>
9038
9039 <t>
9040 The following LSCP commands even support escape sequences as
9041 part of at least one of their text-based arguments (i.e. entity name,
9042 description) and / or may contain escape sequences in at least one of
9043 their text-based fields in their response:
9044 <list>
9045 <t><xref target="GET SERVER INFO">"GET SERVER INFO"</xref></t>
9046 <t><xref target="GET ENGINE INFO">"GET ENGINE INFO"</xref></t>
9047 <t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t>
9048 <t><xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref></t>
9049 <t><xref target="GET FX_SEND INFO">"GET FX_SEND INFO"</xref></t>
9050 <t><xref target="SET FX_SEND NAME">"SET FX_SEND NAME"</xref></t>
9051 <t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t>
9052 <t><xref target="GET MIDI_INSTRUMENT_MAP INFO">"GET MIDI_INSTRUMENT_MAP INFO"</xref></t>
9053 <t><xref target="ADD MIDI_INSTRUMENT_MAP">"ADD MIDI_INSTRUMENT_MAP"</xref></t>
9054 <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
9055 <t><xref target="SET MIDI_INSTRUMENT_MAP NAME">"SET MIDI_INSTRUMENT_MAP NAME"</xref></t>
9056 <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
9057 <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
9058 <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
9059 <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
9060 <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
9061 <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
9062 <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
9063 <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
9064 <t><xref target="GET EFFECT INFO">"GET EFFECT INFO"</xref></t>
9065 <t><xref target="GET EFFECT_INSTANCE INFO">"GET EFFECT_INSTANCE INFO"</xref></t>
9066 <t><xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref></t>
9067 </list>
9068 Please note that these lists are manually maintained. If you
9069 find a command that also supports escape sequences we forgot to
9070 mention here, please report it!
9071 </t>
9072 </section>
9073 </section>
9074
9075 <section title="Events" anchor="events">
9076 <t>This chapter will describe all currently defined events supported by LinuxSampler.</t>
9077
9078 <section title="Number of audio output devices changed" anchor="SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT" lscp_cmd="true">
9079 <t>Client may want to be notified when the total number of audio output devices on the
9080 back-end changes by issuing the following command:</t>
9081 <t>
9082 <list>
9083 <t>SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT</t>
9084 </list>
9085 </t>
9086 <t>Server will start sending the following notification messages:</t>
9087 <t>
9088 <list>
9089 <t>"NOTIFY:AUDIO_OUTPUT_DEVICE_COUNT:&lt;devices&gt;"</t>
9090 </list>
9091 </t>
9092 <t>where &lt;devices&gt; will be replaced by the new number
9093 of audio output devices.</t>
9094 </section>
9095
9096 <section title="Audio output device's settings changed" anchor="SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO" lscp_cmd="true">
9097 <t>Client may want to be notified when changes were made to audio output devices on the
9098 back-end by issuing the following command:</t>
9099 <t>
9100 <list>
9101 <t>SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO</t>
9102 </list>
9103 </t>
9104 <t>Server will start sending the following notification messages:</t>
9105 <t>
9106 <list>
9107 <t>"NOTIFY:AUDIO_OUTPUT_DEVICE_INFO:&lt;device-id&gt;"</t>
9108 </list>
9109 </t>
9110 <t>where &lt;device-id&gt; will be replaced by the numerical ID of the audio output device,
9111 which settings has been changed. The front-end will have to send
9112 the respective command to actually get the audio output device info. Because these messages
9113 will be triggered by LSCP commands issued by other clients rather than real
9114 time events happening on the server, it is believed that an empty notification
9115 message is sufficient here.</t>
9116 </section>
9117
9118 <section title="Number of MIDI input devices changed" anchor="SUBSCRIBE MIDI_INPUT_DEVICE_COUNT" lscp_cmd="true">
9119 <t>Client may want to be notified when the total number of MIDI input devices on the
9120 back-end changes by issuing the following command:</t>
9121 <t>
9122 <list>
9123 <t>SUBSCRIBE MIDI_INPUT_DEVICE_COUNT</t>
9124 </list>
9125 </t>
9126 <t>Server will start sending the following notification messages:</t>
9127 <t>
9128 <list>
9129 <t>"NOTIFY:MIDI_INPUT_DEVICE_COUNT:&lt;devices&gt;"</t>
9130 </list>
9131 </t>
9132 <t>where &lt;devices&gt; will be replaced by the new number
9133 of MIDI input devices.</t>
9134 </section>
9135
9136 <section title="MIDI input device's settings changed" anchor="SUBSCRIBE MIDI_INPUT_DEVICE_INFO" lscp_cmd="true">
9137 <t>Client may want to be notified when changes were made to MIDI input devices on the
9138 back-end by issuing the following command:</t>
9139 <t>
9140 <list>
9141 <t>SUBSCRIBE MIDI_INPUT_DEVICE_INFO</t>
9142 </list>
9143 </t>
9144 <t>Server will start sending the following notification messages:</t>
9145 <t>
9146 <list>
9147 <t>"NOTIFY:MIDI_INPUT_DEVICE_INFO:&lt;device-id&gt;"</t>
9148 </list>
9149 </t>
9150 <t>where &lt;device-id&gt; will be replaced by the numerical ID of the MIDI input device,
9151 which settings has been changed. The front-end will have to send
9152 the respective command to actually get the MIDI input device info. Because these messages
9153 will be triggered by LSCP commands issued by other clients rather than real
9154 time events happening on the server, it is believed that an empty notification
9155 message is sufficient here.</t>
9156 </section>
9157
9158 <section title="Number of sampler channels changed" anchor="SUBSCRIBE CHANNEL_COUNT" lscp_cmd="true">
9159 <t>Client may want to be notified when the total number of channels on the
9160 back-end changes by issuing the following command:</t>
9161 <t>
9162 <list>
9163 <t>SUBSCRIBE CHANNEL_COUNT</t>
9164 </list>
9165 </t>
9166 <t>Server will start sending the following notification messages:</t>
9167 <t>
9168 <list>
9169 <t>"NOTIFY:CHANNEL_COUNT:&lt;channels&gt;"</t>
9170 </list>
9171 </t>
9172 <t>where &lt;channels&gt; will be replaced by the new number
9173 of sampler channels.</t>
9174 </section>
9175
9176 <section title="MIDI data on a sampler channel arrived" anchor="SUBSCRIBE CHANNEL_MIDI" lscp_cmd="true">
9177 <t>Client may want to be notified when MIDI data arrive on sampler channels on
9178 back-end side, by issuing the following command:</t>
9179 <t>
9180 <list>
9181 <t>SUBSCRIBE CHANNEL_MIDI</t>
9182 </list>
9183 </t>
9184 <t>Server will start sending one of the the following notification messages:</t>
9185 <t>
9186 <list>
9187 <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_ON &lt;note&gt; &lt;velocity&gt;"</t>
9188 <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
9189 </list>
9190 </t>
9191 <t>where &lt;channel-id&gt; will be replaced by the ID of the sampler channel where the MIDI
9192 data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
9193 0 .. 127, reflecting the analog meaning of the MIDI specification.
9194 </t>
9195 <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
9196 delivered by this mechanism! With other words: events could be lost at any time!
9197 This restriction was made to keep the RT-safeness of the backend's MIDI and audio
9198 thread unaffected by this feature.</t>
9199 </section>
9200
9201 <section title="MIDI data on a MIDI input device arrived" anchor="SUBSCRIBE DEVICE_MIDI" lscp_cmd="true">
9202 <t>Client may want to be notified when MIDI data arrive on MIDI input devices by issuing the following command:</t>
9203 <t>
9204 <list>
9205 <t>SUBSCRIBE DEVICE_MIDI</t>
9206 </list>
9207 </t>
9208 <t>Server will start sending one of the the following notification messages:</t>
9209 <t>
9210 <list>
9211 <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_ON &lt;note&gt; &lt;velocity&gt;"</t>
9212 <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
9213 </list>
9214 </t>
9215 <t>where &lt;device-id&gt; &lt;port-id&gt; will be replaced
9216 by the IDs of the respective MIDI input device and the device's MIDI port where the MIDI
9217 data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
9218 0 .. 127, reflecting the analog meaning of the MIDI specification.
9219 </t>
9220 <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
9221 delivered by this mechanism! With other words: events could be lost at any time!
9222 This restriction was made to keep the RT-safeness of the backend's MIDI and audio
9223 thread unaffected by this feature.</t>
9224 </section>
9225
9226 <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT" lscp_cmd="true">
9227 <t>Client may want to be notified when the number of voices on the
9228 back-end changes by issuing the following command:</t>
9229 <t>
9230 <list>
9231 <t>SUBSCRIBE VOICE_COUNT</t>
9232 </list>
9233 </t>
9234 <t>Server will start sending the following notification messages:</t>
9235 <t>
9236 <list>
9237 <t>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;"</t>
9238 </list>
9239 </t>
9240 <t>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
9241 voice count change occurred and &lt;voices&gt; by the new number of
9242 active voices on that channel.</t>
9243 </section>
9244
9245 <section title="Number of active disk streams changed" anchor="SUBSCRIBE STREAM_COUNT" lscp_cmd="true">
9246 <t>Client may want to be notified when the number of streams on the back-end
9247 changes by issuing the following command: SUBSCRIBE STREAM_COUNT</t>
9248 <t>
9249 <list>
9250 <t>SUBSCRIBE STREAM_COUNT</t>
9251 </list>
9252 </t>
9253 <t>Server will start sending the following notification messages:</t>
9254 <t>
9255 <list>
9256 <t>"NOTIFY:STREAM_COUNT:&lt;sampler-channel&gt; &lt;streams&gt;"</t>
9257 </list>
9258 </t>
9259 <t>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
9260 stream count change occurred and &lt;streams&gt; by the new number of
9261 active disk streams on that channel.</t>
9262 </section>
9263
9264 <section title="Disk stream buffer fill state changed" anchor="SUBSCRIBE BUFFER_FILL" lscp_cmd="true">
9265 <t>Client may want to be notified when the buffer fill state of a disk stream
9266 on the back-end changes by issuing the following command:</t>
9267 <t>
9268 <list>
9269 <t>SUBSCRIBE BUFFER_FILL</t>
9270 </list>
9271 </t>
9272 <t>Server will start sending the following notification messages:</t>
9273 <t>
9274 <list>
9275 <t>"NOTIFY:BUFFER_FILL:&lt;sampler-channel&gt; &lt;fill-data&gt;"</t>
9276 </list>
9277 </t>
9278 <t>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
9279 buffer fill state change occurred on and &lt;fill-data&gt; will be replaced by the
9280 buffer fill data for this channel as described in <xref target="GET CHANNEL BUFFER_FILL" />
9281 as if the <xref target="GET CHANNEL BUFFER_FILL">
9282 "GET CHANNEL BUFFER_FILL PERCENTAGE"</xref> command was issued on this channel.</t>
9283 </section>
9284
9285 <section title="Channel information changed" anchor="SUBSCRIBE CHANNEL_INFO" lscp_cmd="true">
9286 <t>Client may want to be notified when changes were made to sampler channels on the
9287 back-end by issuing the following command:</t>
9288 <t>
9289 <list>
9290 <t>SUBSCRIBE CHANNEL_INFO</t>
9291 </list>
9292 </t>
9293 <t>Server will start sending the following notification messages:</t>
9294 <t>
9295 <list>
9296 <t>"NOTIFY:CHANNEL_INFO:&lt;sampler-channel&gt;"</t>
9297 </list>
9298 </t>
9299 <t>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
9300 channel info change occurred. The front-end will have to send
9301 the respective command to actually get the channel info. Because these messages
9302 will be triggered by LSCP commands issued by other clients rather than real
9303 time events happening on the server, it is believed that an empty notification
9304 message is sufficient here.</t>
9305 </section>
9306
9307 <section title="Number of effect sends changed" anchor="SUBSCRIBE FX_SEND_COUNT" lscp_cmd="true">
9308 <t>Client may want to be notified when the number of effect sends on
9309 a particular sampler channel is changed by issuing the following command:</t>
9310 <t>
9311 <list>
9312 <t>SUBSCRIBE FX_SEND_COUNT</t>
9313 </list>
9314 </t>
9315 <t>Server will start sending the following notification messages:</t>
9316 <t>
9317 <list>
9318 <t>"NOTIFY:FX_SEND_COUNT:&lt;channel-id&gt; &lt;fx-sends&gt;"</t>
9319 </list>
9320 </t>
9321 <t>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
9322 channel, on which the effect sends number is changed and &lt;fx-sends&gt; will
9323 be replaced by the new number of effect sends on that channel.</t>
9324 </section>
9325
9326 <section title="Effect send information changed" anchor="SUBSCRIBE FX_SEND_INFO" lscp_cmd="true">
9327 <t>Client may want to be notified when changes were made to effect sends on a
9328 a particular sampler channel by issuing the following command:</t>
9329 <t>
9330 <list>
9331 <t>SUBSCRIBE FX_SEND_INFO</t>
9332 </list>
9333 </t>
9334 <t>Server will start sending the following notification messages:</t>
9335 <t>
9336 <list>
9337 <t>"NOTIFY:FX_SEND_INFO:&lt;channel-id&gt; &lt;fx-send-id&gt;"</t>
9338 </list>
9339 </t>
9340 <t>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
9341 channel, on which an effect send entity is changed and &lt;fx-send-id&gt; will
9342 be replaced by the numerical ID of the changed effect send.</t>
9343 </section>
9344
9345 <section title="Total number of active voices changed" anchor="SUBSCRIBE TOTAL_VOICE_COUNT" lscp_cmd="true">
9346 <t>Client may want to be notified when the total number of voices on the
9347 back-end changes by issuing the following command:</t>
9348 <t>
9349 <list>
9350 <t>SUBSCRIBE TOTAL_VOICE_COUNT</t>
9351 </list>
9352 </t>
9353 <t>Server will start sending the following notification messages:</t>
9354 <t>
9355 <list>
9356 <t>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;"</t>
9357 </list>
9358 </t>
9359 <t>where &lt;voices&gt; will be replaced by the new number of
9360 all currently active voices.</t>
9361 </section>
9362
9363 <section title="Total number of active disk streams changed" anchor="SUBSCRIBE TOTAL_STREAM_COUNT" lscp_cmd="true">
9364 <t>Client may want to be notified when the total number of disk streams on the
9365 back-end changes by issuing the following command:</t>
9366 <t>
9367 <list>
9368 <t>SUBSCRIBE TOTAL_STREAM_COUNT</t>
9369 </list>
9370 </t>
9371 <t>Server will start sending the following notification messages:</t>
9372 <t>
9373 <list>
9374 <t>"NOTIFY:TOTAL_STREAM_COUNT:&lt;streams&gt;"</t>
9375 </list>
9376 </t>
9377 <t>where &lt;streams&gt; will be replaced by the new number of
9378 all currently active disk streams.</t>
9379 </section>
9380
9381 <section title="Number of MIDI instrument maps changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT" lscp_cmd="true">
9382 <t>Client may want to be notified when the number of MIDI instrument maps on the
9383 back-end changes by issuing the following command:</t>
9384 <t>
9385 <list>
9386 <t>SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT</t>
9387 </list>
9388 </t>
9389 <t>Server will start sending the following notification messages:</t>
9390 <t>
9391 <list>
9392 <t>"NOTIFY:MIDI_INSTRUMENT_MAP_COUNT:&lt;maps&gt;"</t>
9393 </list>
9394 </t>
9395 <t>where &lt;maps&gt; will be replaced by the new number
9396 of MIDI instrument maps.</t>
9397 </section>
9398
9399 <section title="MIDI instrument map information changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO" lscp_cmd="true">
9400 <t>Client may want to be notified when changes were made to MIDI instrument maps on the
9401 back-end by issuing the following command:</t>
9402 <t>
9403 <list>
9404 <t>SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO</t>
9405 </list>
9406 </t>
9407 <t>Server will start sending the following notification messages:</t>
9408 <t>
9409 <list>
9410 <t>"NOTIFY:MIDI_INSTRUMENT_MAP_INFO:&lt;map-id&gt;"</t>
9411 </list>
9412 </t>
9413 <t>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
9414 for which information changes occurred. The front-end will have to send
9415 the respective command to actually get the MIDI instrument map info. Because these messages
9416 will be triggered by LSCP commands issued by other clients rather than real
9417 time events happening on the server, it is believed that an empty notification
9418 message is sufficient here.</t>
9419 </section>
9420
9421 <section title="Number of MIDI instruments changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_COUNT" lscp_cmd="true">
9422 <t>Client may want to be notified when the number of MIDI instrument maps on the
9423 back-end changes by issuing the following command:</t>
9424 <t>
9425 <list>
9426 <t>SUBSCRIBE MIDI_INSTRUMENT_COUNT</t>
9427 </list>
9428 </t>
9429 <t>Server will start sending the following notification messages:</t>
9430 <t>
9431 <list>
9432 <t>"NOTIFY:MIDI_INSTRUMENT_COUNT:&lt;map-id&gt; &lt;instruments&gt;"</t>
9433 </list>
9434 </t>
9435 <t>where &lt;map-id&gt; is the numerical ID of the MIDI instrument map, in which
9436 the nuber of instruments has changed and &lt;instruments&gt; will be replaced by
9437 the new number of MIDI instruments in the specified map.</t>
9438 </section>
9439
9440 <section title="MIDI instrument information changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_INFO" lscp_cmd="true">
9441 <t>Client may want to be notified when changes were made to MIDI instruments on the
9442 back-end by issuing the following command:</t>
9443 <t>
9444 <list>
9445 <t>SUBSCRIBE MIDI_INSTRUMENT_INFO</t>
9446 </list>
9447 </t>
9448 <t>Server will start sending the following notification messages:</t>
9449 <t>
9450 <list>
9451 <t>"NOTIFY:MIDI_INSTRUMENT_INFO:&lt;map-id&gt; &lt;bank&gt; &lt;program&gt;"</t>
9452 </list>
9453 </t>
9454 <t>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
9455 in which a MIDI instrument is changed. &lt;bank&gt; and &lt;program&gt; specifies
9456 the location of the changed MIDI instrument in the map. The front-end will have to send
9457 the respective command to actually get the MIDI instrument info. Because these messages
9458 will be triggered by LSCP commands issued by other clients rather than real
9459 time events happening on the server, it is believed that an empty notification
9460 message is sufficient here.</t>
9461 </section>
9462
9463 <section title="Global settings changed" anchor="SUBSCRIBE GLOBAL_INFO" lscp_cmd="true">
9464 <t>Client may want to be notified when changes to the global settings
9465 of the sampler were made by issuing the following command:</t>
9466 <t>
9467 <list>
9468 <t>SUBSCRIBE GLOBAL_INFO</t>
9469 </list>
9470 </t>
9471 <t>Server will start sending the following types of notification messages:</t>
9472 <t>
9473 <list>
9474 <t>"NOTIFY:GLOBAL_INFO:VOLUME &lt;volume&gt;" - Notifies that the
9475 golbal volume of the sampler is changed, where &lt;volume&gt; will be
9476 replaced by the optional dotted floating point value, reflecting the
9477 new global volume parameter.</t>
9478 </list>
9479 <list>
9480 <t>"NOTIFY:GLOBAL_INFO:VOICES &lt;max-voices&gt;" - Notifies that the
9481 golbal limit of the sampler for maximum voices is changed, where
9482 &lt;max-voices&gt; will be an integer value, reflecting the
9483 new global voice limit parameter.</t>
9484 </list>
9485 <list>
9486 <t>"NOTIFY:GLOBAL_INFO:STREAMS &lt;max-streams&gt;" - Notifies that the
9487 golbal limit of the sampler for maximum disk streams is changed, where
9488 &lt;max-streams&gt; will be an integer value, reflecting the
9489 new global disk streams limit parameter.</t>
9490 </list>
9491 </t>
9492 </section>
9493
9494 <section title="Number of database instrument directories changed" anchor="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT" lscp_cmd="true">
9495 <t>Client may want to be notified when the number of instrument
9496 directories in a particular directory in the instruments database
9497 is changed by issuing the following command:</t>
9498 <t>
9499 <list>
9500 <t>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT</t>
9501 </list>
9502 </t>
9503 <t>Server will start sending the following notification messages:</t>
9504 <t>
9505 <list>
9506 <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_COUNT:&lt;dir-path&gt;"</t>
9507 </list>
9508 </t>
9509 <t>where &lt;dir-path&gt; will be replaced by the absolute path
9510 name of the directory in the instruments database,
9511 in which the number of directories is changed.</t>
9512 <t>Note that when a non-empty directory is removed, this event
9513 is not sent for the subdirectories in that directory.</t>
9514 </section>
9515
9516 <section title="Database instrument directory information changed" anchor="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO" lscp_cmd="true">
9517 <t>Client may want to be notified when changes were made to directories
9518 in the instruments database by issuing the following command:</t>
9519 <t>
9520 <list>
9521 <t>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO</t>
9522 </list>
9523 </t>
9524 <t>Server will start sending the following notification messages:</t>
9525 <t>
9526 <list>
9527 <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:&lt;dir-path&gt;"</t>
9528 </list>
9529 </t>
9530 <t>where &lt;dir-path&gt; will be replaced by the absolute path name
9531 of the directory, for which information changes occurred. The front-end will have to send
9532 the respective command to actually get the updated directory info. Because these messages
9533 will be triggered by LSCP commands issued by other clients rather than real
9534 time events happening on the server, it is believed that an empty notification
9535 message is sufficient here.</t>
9536 <t>
9537 <list>
9538 <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:NAME &lt;old-dir-path&gt; &lt;new-name&gt;"</t>
9539 </list>
9540 </t>
9541 <t>where &lt;old-dir-path&gt; is the old absolute path name of the directory
9542 (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
9543 the new name of the directory, encapsulated into apostrophes.</t>
9544 </section>
9545
9546 <section title="Number of database instruments changed" anchor="SUBSCRIBE DB_INSTRUMENT_COUNT" lscp_cmd="true">
9547 <t>Client may want to be notified when the number of instruments
9548 in a particular directory in the instruments database
9549 is changed by issuing the following command:</t>
9550 <t>
9551 <list>
9552 <t>SUBSCRIBE DB_INSTRUMENT_COUNT</t>
9553 </list>
9554 </t>
9555 <t>Server will start sending the following notification messages:</t>
9556 <t>
9557 <list>
9558 <t>"NOTIFY:DB_INSTRUMENT_COUNT:&lt;dir-path&gt;"</t>
9559 </list>
9560 </t>
9561 <t>where &lt;dir-path&gt; will be replaced by the absolute path
9562 name of the directory in the instruments database,
9563 in which the number of instruments is changed.</t>
9564 <t>Note that when a non-empty directory is removed, this event
9565 is not sent for the instruments in that directory.</t>
9566 </section>
9567
9568 <section title="Database instrument information changed" anchor="SUBSCRIBE DB_INSTRUMENT_INFO" lscp_cmd="true">
9569 <t>Client may want to be notified when changes were made to instruments
9570 in the instruments database by issuing the following command:</t>
9571 <t>
9572 <list>
9573 <t>SUBSCRIBE DB_INSTRUMENT_INFO</t>
9574 </list>
9575 </t>
9576 <t>Server will start sending the following notification messages:</t>
9577 <t>
9578 <list>
9579 <t>"NOTIFY:DB_INSTRUMENT_INFO:&lt;instr-path&gt;"</t>
9580 </list>
9581 </t>
9582 <t>where &lt;instr-path&gt; will be replaced by the absolute path name
9583 of the instrument, which settings are changed. The front-end will have to send
9584 the respective command to actually get the updated directory info. Because these messages
9585 will be triggered by LSCP commands issued by other clients rather than real
9586 time events happening on the server, it is believed that an empty notification
9587 message is sufficient here.</t>
9588 <t>
9589 <list>
9590 <t>"NOTIFY:DB_INSTRUMENT_INFO:NAME &lt;old-instr-path&gt; &lt;new-name&gt;"</t>
9591 </list>
9592 </t>
9593 <t>where &lt;old-instr-path&gt; is the old absolute path name of the instrument
9594 (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
9595 the new name of the instrument, encapsulated into apostrophes.</t>
9596 </section>
9597
9598 <section title="Database job status information changed" anchor="SUBSCRIBE DB_INSTRUMENTS_JOB_INFO" lscp_cmd="true">
9599 <t>Client may want to be notified when the status of particular database
9600 instruments job is changed by issuing the following command:</t>
9601 <t>
9602 <list>
9603 <t>SUBSCRIBE DB_INSTRUMENTS_JOB_INFO</t>
9604 </list>
9605 </t>
9606 <t>Server will start sending the following notification messages:</t>
9607 <t>
9608 <list>
9609 <t>"NOTIFY:DB_INSTRUMENTS_JOB_INFO:&lt;job-id&gt;"</t>
9610 </list>
9611 </t>
9612 <t>where &lt;job-id&gt; will be replaced by the numerical ID of the job,
9613 which status is changed. The front-end will have to send the respective
9614 command to actually get the status info. Because these messages
9615 will be triggered by LSCP commands issued by other clients rather than real
9616 time events happening on the server, it is believed that an empty notification
9617 message is sufficient here.</t>
9618 </section>
9619
9620 <section title="Number of effect instances changed" anchor="SUBSCRIBE EFFECT_INSTANCE_COUNT" lscp_cmd="true">
9621 <t>Client may want to be notified when the number of effect instances
9622 is changed by issuing the following command:</t>
9623 <t>
9624 <list>
9625 <t>SUBSCRIBE EFFECT_INSTANCE_COUNT</t>
9626 </list>
9627 </t>
9628 <t>Server will start sending the following notification messages:</t>
9629 <t>
9630 <list>
9631 <t>"EFFECT_INSTANCE_COUNT:&lt;instances&gt;"</t>
9632 </list>
9633 </t>
9634 <t>where &lt;instances&gt; will be replaced by the new number
9635 of effect instances.</t>
9636 </section>
9637
9638 <section title="Effect instance information changed" anchor="SUBSCRIBE EFFECT_INSTANCE_INFO" lscp_cmd="true">
9639 <t>Client may want to be notified when changes were made to effect instances
9640 on the back-end by issuing the following command:</t>
9641 <t>
9642 <list>
9643 <t>SUBSCRIBE EFFECT_INSTANCE_INFO</t>
9644 </list>
9645 </t>
9646 <t>Server will start sending the following notification messages:</t>
9647 <t>
9648 <list>
9649 <t>"EFFECT_INSTANCE_INFO:&lt;instance-id&gt;"</t>
9650 </list>
9651 </t>
9652 <t>where &lt;instance-id&gt; will be replaced by the numerical ID
9653 of the effect instance.</t>
9654 </section>
9655
9656 <section title="Number of send effect chains changed" anchor="SUBSCRIBE SEND_EFFECT_CHAIN_COUNT" lscp_cmd="true">
9657 <t>Client may want to be notified when the number of send effect chains
9658 is changed by issuing the following command:</t>
9659 <t>
9660 <list>
9661 <t>SUBSCRIBE SEND_EFFECT_CHAIN_COUNT</t>
9662 </list>
9663 </t>
9664 <t>Server will start sending the following notification messages:</t>
9665 <t>
9666 <list>
9667 <t>"NOTIFY:SEND_EFFECT_CHAIN_COUNT:&lt;device-id&gt; &lt;chains&gt;"</t>
9668 </list>
9669 </t>
9670 <t>where &lt;device-id&gt; will be replaced by the numerical ID of the audio
9671 output device, in which the number of send effect chains is changed and
9672 &lt;chains&gt; will be replaced by the new number of send effect chains.</t>
9673 </section>
9674
9675 <section title="Send effect chain information changed" anchor="SUBSCRIBE SEND_EFFECT_CHAIN_INFO" lscp_cmd="true">
9676 <t>Client may want to be notified when changes were made to send effect chains
9677 on the back-end by issuing the following command:</t>
9678 <t>
9679 <list>
9680 <t>SUBSCRIBE SEND_EFFECT_CHAIN_INFO</t>
9681 </list>
9682 </t>
9683 <t>Server will start sending the following notification messages:</t>
9684 <t>
9685 <list>
9686 <t>"SEND_EFFECT_CHAIN_INFO:&lt;device-id&gt; &lt;chain-id&gt; &lt;instances&gt;" -
9687 Notifies that the number of effect instances in a particular send effect chain
9688 is changed, where &lt;device-id&gt; will be replaced by the numerical ID of the audio
9689 output device the send effect chain belongs to, &lt;chain-id&gt; will be replaced
9690 by the numerical ID of the send effect chain in which the number of effect instances
9691 has changed and &lt;instances&gt; will be replaced by the new number
9692 of effect instances in the specified send effect chain.</t>
9693 </list>
9694 </t>
9695 </section>
9696
9697 <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS" lscp_cmd="true">
9698 <t>Client may want to be notified of miscellaneous and debugging events occurring at
9699 the server by issuing the following command:</t>
9700 <t>
9701 <list>
9702 <t>SUBSCRIBE MISCELLANEOUS</t>
9703 </list>
9704 </t>
9705 <t>Server will start sending the following notification messages:</t>
9706 <t>
9707 <list>
9708 <t>"NOTIFY:MISCELLANEOUS:&lt;string&gt;"</t>
9709 </list>
9710 </t>
9711 <t>where &lt;string&gt; will be replaced by whatever data server
9712 wants to send to the client. Client MAY display this data to the
9713 user AS IS to facilitate debugging.</t>
9714 </section>
9715 </section>
9716
9717 <section title="Security Considerations">
9718 <t>As there is so far no method of authentication and authorization
9719 defined and so not required for a client applications to succeed to
9720 connect, running LinuxSampler might be a security risk for the host
9721 system the LinuxSampler instance is running on.</t>
9722 </section>
9723
9724 <section title="Acknowledgments">
9725 <t>This document has benefited greatly from the comments of the
9726 following people, discussed on the LinuxSampler developer's mailing
9727 list:</t>
9728 <t>
9729 <list>
9730 <t>Rui Nuno Capela</t>
9731 <t>Vladimir Senkov</t>
9732 <t>Mark Knecht</t>
9733 <t>Grigor Iliev</t>
9734 </list>
9735 </t>
9736 </section>
9737
9738 </middle>
9739
9740 <back>
9741 <references>
9742 <reference anchor="RFC2119">
9743 <front>
9744 <title>Key words for use in RFCs to Indicate Requirement Levels</title>
9745 <author initials="S." surname="Bradner" fullname="Scott Bradner">
9746 <organization>Harvard University</organization>
9747 </author>
9748 <date year="1997"></date>
9749 </front>
9750 <seriesInfo name="RFC" value="2119" />
9751 </reference>
9752 <reference anchor="RFC793">
9753 <front>
9754 <title>TRANSMISSION CONTROL PROTOCOL</title>
9755 <author>
9756 <organization>Defense Advanced Research Projects Agency</organization>
9757 </author>
9758 <date year="1981"></date>
9759 </front>
9760 <seriesInfo name="RFC" value="793" />
9761 </reference>
9762 <reference anchor="RFC2234">
9763 <front>
9764 <title>Augmented BNF for Syntax Specifications</title>
9765 <author initials="D.H." surname="Crocker" fullname="David H. Crocker">
9766 <organization>Internet Mail Consortium</organization>
9767 </author>
9768 <author initials="P." surname="Overell" fullname="Paul Overell">
9769 <organization>Demon Internet Ltd</organization>
9770 </author>
9771 <date year="1997"></date>
9772 </front>
9773 <seriesInfo name="RFC" value="2234" />
9774 </reference>
9775 <reference anchor="RFC20">
9776 <front>
9777 <title>ASCII format for Network Interchange</title>
9778 <author>
9779 <organization>UCLA</organization>
9780 </author>
9781 <date year="1969"></date>
9782 </front>
9783 <seriesInfo name="RFC" value="20" />
9784 </reference>
9785 </references>
9786 </back>
9787
9788 </rfc>

  ViewVC Help
Powered by ViewVC