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

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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 3501 - (show annotations) (download) (as text)
Mon Mar 11 15:07:49 2019 UTC (5 years, 1 month ago) by schoenebeck
File MIME type: text/xml
File size: 502173 byte(s) 
* FX Sends: Provide more useful error messages on routing problems
  (see bug #169).
* LSCP reference doc: Be more clear describing the two distinct
  approaches of using external vs. internal effects (see bug #169).
* Bumped version (2.1.0.svn8).
1 <?xml version="1.0" encoding="UTF-8"?>
2
3 <!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
4 <!ENTITY rfc2119 PUBLIC ''
5 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
6 ]>
7
8 <?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
9
10 <?rfc toc="yes" ?>
11 <?rfc symrefs="yes" ?>
12 <?rfc sortrefs="yes"?>
13 <?rfc iprnotified="no" ?>
14
15 <!-- FIXME: next attribute should actually be "yes", temporarily disbled due
16 to an annoying "missing Normative/Informative References" error message -->
17 <?rfc strict="no" ?>
18
19 <rfc category="std" ipr="full3978" docName="LSCP 1.7">
20 <front>
21 <title>LinuxSampler Control Protocol</title>
22 <author initials='C.S.' surname="Schoenebeck" fullname='C.
23 Schoenebeck'>
24 <organization>
25 LinuxSampler.org
26 </organization>
27 <address>
28 <postal>
29 <street>Crudebyte Engineering</street>
30 <street>Hofgartenstr. 3</street>
31 <!-- <code>74081</code> -->
32 <city>74189 Weinsberg</city>
33 <country>Germany</country>
34 </postal>
35 <phone>+49 7134 911614</phone>
36 <email>cuse@users.sf.net</email>
37 </address>
38 </author>
39 <date month="March" year="2019"/>
40 <workgroup>LinuxSampler Developers</workgroup>
41 <keyword>LSCP</keyword>
42 <abstract>
43 <t>The LinuxSampler Control Protocol (LSCP) is an
44 application-level protocol primarily intended for local and
45 remote controlling the LinuxSampler backend application, which is a
46 sophisticated server-like console application essentially playing
47 back audio samples and manipulating the samples in real time to
48 certain extent.</t>
49 </abstract>
50 </front>
51
52 <middle>
53 <section title="Requirements notation">
54 <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
55 "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
56 and "OPTIONAL" in this document are to be interpreted as
57 described in <xref target="RFC2119"/>.</t>
58
59 <t>This protocol is always case-sensitive if not explicitly
60 claimed the opposite.</t>
61
62 <t>In examples, "C:" and "S:" indicate lines sent by the client
63 (front-end) and server (LinuxSampler) respectively. Lines in
64 examples must be interpreted as every line being CRLF
65 terminated (carriage return character followed by line feed
66 character as defined in the ASCII standard <xref target="RFC20"/>),
67 thus the following example:</t>
68
69 <t>
70 <list>
71 <t>C: "some line"</t>
72 <t>&nbsp;&nbsp;&nbsp;"another line"</t>
73 </list>
74 </t>
75
76 <t>must actually be interpreted as client sending the following
77 message:</t>
78
79 <t>
80 <list>
81 <t>"some line&lt;CR&gt;&lt;LF&gt;another
82 line&lt;CR&gt;&lt;LF&gt;"</t>
83 </list>
84 </t>
85
86 <t>where &lt;CR&gt; symbolizes the carriage return character and
87 &lt;LF&gt; the line feed character as defined in the ASCII
88 standard.</t>
89
90 <t>Due to technical reasons, messages can arbitrary be
91 fragmented, means the following example:</t>
92
93 <t>
94 <list>
95 <t>S: "abcd"</t>
96 </list>
97 </t>
98
99 <t>could also happen to be sent in three messages like in the
100 following sequence scenario:</t>
101
102 <t>
103 <list style="symbols">
104 <t>server sending message "a"</t>
105 <t>followed by a delay (pause) with
106 arbitrary duration</t>
107 <t>followed by server sending message
108 "bcd&lt;CR&gt;"</t>
109 <t>again followed by a delay (pause) with arbitrary
110 duration</t>
111 <t>followed by server sending the message
112 "&lt;LF&gt;"</t>
113 </list>
114 </t>
115
116 <t>where again &lt;CR&gt; and &lt;LF&gt; symbolize the carriage
117 return and line feed characters respectively.</t>
118 </section>
119
120 <section title="Versioning of this specification" anchor="LSCP versioning">
121 <t>LSCP will certainly be extended and enhanced by-and-by. Each official
122 release of the LSCP specification will be tagged with a unique version
123 tuple. The version tuple consists at least of a major and minor version
124 number like:
125 </t>
126 <t>
127 <list>
128 <t>"1.2"</t>
129 </list>
130 </t>
131 <t>
132 In this example the major version number would be "1" and the minor
133 version number would be "2". Note that the version tuple might also
134 have more than two elements. The major version number defines a
135 group of backward compatible versions. That means a frontend is
136 compatible to the connected sampler if and only if the LSCP versions
137 to which each of the two parties complies to, match both of the
138 following rules:
139 </t>
140 <t>Compatibility:</t>
141 <t>
142 <list style="numbers">
143 <t>The frontend's LSCP major version and the sampler's LSCP
144 major version are exactly equal.</t>
145 <t>The frontend's LSCP minor version is less or equal than
146 the sampler's LSCP minor version.</t>
147 </list>
148 </t>
149 <t>
150 Compatibility can only be claimed if both rules are true.
151 The frontend can use the
152 <xref target="GET SERVER INFO">"GET SERVER INFO"</xref> command to
153 get the version of the LSCP specification the sampler complies with.
154 </t>
155 </section>
156
157 <section title="Introduction">
158 <t>LinuxSampler is a so called software sampler application
159 capable to playback audio samples from a computer's Random
160 Access Memory (RAM) as well as directly streaming it from disk.
161 LinuxSampler is designed to be modular. It provides several so
162 called "sampler engines" where each engine is specialized for a
163 certain purpose. LinuxSampler has virtual channels which will be
164 referred in this document as "sampler channels". The channels
165 are in such way virtual as they can be connected to an
166 arbitrary MIDI input method and arbitrary MIDI channel (e.g.
167 sampler channel 17 could be connected to an ALSA sequencer
168 device 64:0 and listening to MIDI channel 1 there). Each sampler
169 channel will be associated with an instance of one of the available
170 sampler engines (e.g. GigEngine, DLSEngine). The audio output of
171 each sampler channel can be routed to an arbitrary audio output
172 method (ALSA / JACK) and an arbitrary audio output channel
173 there.</t>
174 </section>
175
176 <section title="Focus of this protocol">
177 <t>Main focus of this protocol is to provide a way to configure
178 a running LinuxSampler instance and to retrieve information
179 about it. The focus of this protocol is not to provide a way to
180 control synthesis parameters or even to trigger or release
181 notes. Or in other words; the focus are those functionalities
182 which are not covered by MIDI or which may at most be handled
183 via MIDI System Exclusive Messages.</t>
184 </section>
185
186 <section title="Communication Overview">
187 <t>There are two distinct methods of communication between a
188 running instance of LinuxSampler and one or more control
189 applications, so called "front-ends": a simple request/response
190 communication method used by the clients to give commands to the
191 server as well as to inquire about server's status and a
192 subscribe/notify communication method used by the client to
193 subscribe to and receive notifications of certain events as they
194 happen on the server. The latter needs more effort to be
195 implemented in the front-end application. The two communication
196 methods will be described next.</t>
197
198 <section title="Request/response communication method">
199 <t>This simple communication method is based on
200 <xref target="RFC793">TCP</xref>. The
201 front-end application establishes a TCP connection to the
202 LinuxSampler instance on a certain host system. Then the
203 front-end application will send certain ASCII based commands
204 as defined in this document (every command line must be CRLF
205 terminated - see "Conventions used in this document" at the
206 beginning of this document) and the LinuxSampler application
207 will response after a certain process time with an
208 appropriate ASCII based answer, also as defined in this
209 document. So this TCP communication is simply based on query
210 and answer paradigm. That way LinuxSampler is only able to
211 answer on queries from front-ends, but not able to
212 automatically send messages to the client if it's not asked
213 to. The fronted should not reconnect to LinuxSampler for
214 every single command, instead it should keep the connection
215 established and simply resend message(s) for subsequent
216 commands. To keep information in the front-end up-to-date
217 the front-end has to periodically send new requests to get
218 the current information from the LinuxSampler instance. This
219 is often referred to as "polling". While polling is simple
220 to implement and may be OK to use in some cases, there may
221 be disadvantages to polling such as network traffic overhead
222 and information being out of date.
223 It is possible for a client or several clients to open more
224 than one connection to the server at the same time. It is
225 also possible to send more than one request to the server
226 at the same time but if those requests are sent over the
227 same connection server MUST execute them sequentially. Upon
228 executing a request server will produce a result set and
229 send it to the client. Each and every request made by the
230 client MUST result in a result set being sent back to the
231 client. No other data other than a result set may be sent by
232 a server to a client. No result set may be sent to a client
233 without the client sending request to the server first. On
234 any particular connection, result sets MUST be sent in their
235 entirety without being interrupted by other result sets. If
236 several requests got queued up at the server they MUST be
237 processed in the order they were received and result sets
238 MUST be sent back in the same order.</t>
239
240 <section title="Result format">
241 <t>Result set could be one of the following types:</t>
242 <t>
243 <list style="numbers">
244 <t>Normal</t>
245 <t>Warning</t>
246 <t>Error</t>
247 </list>
248 </t>
249 <t>Warning and Error result sets MUST be single line and
250 have the following format:</t>
251 <t>
252 <list style="symbols">
253 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;"</t>
254 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;"</t>
255 </list>
256 </t>
257 <t>Where &lt;warning-code&gt; and &lt;error-code&gt; are
258 numeric unique identifiers of the warning or error and
259 &lt;warning-message&gt; and &lt;error-message&gt; are
260 human readable descriptions of the warning or error
261 respectively.</t>
262 <t>Examples:</t>
263 <t>
264 <list>
265 <t>C: "LOAD INSTRUMENT '/home/me/Boesendorfer24bit.gig" 0 0</t>
266 <t>S: "WRN:32:This is a 24 bit patch which is not supported natively yet."</t>
267 </list>
268 </t>
269 <t>
270 <list>
271 <t>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA EAR"</t>
272 <t>S: "ERR:3456:Audio output driver 'ALSA' does not have a parameter 'EAR'."</t>
273 </list>
274 </t>
275 <t>
276 <list>
277 <t>C: "GET AUDIO_OUTPUT_DEVICE INFO 123456"</t>
278 <t>S: "ERR:9:There is no audio output device with index 123456."</t>
279 </list>
280 </t>
281 <t>Normal result sets could be:</t>
282 <t>
283 <list style="numbers">
284 <t>Empty</t>
285 <t>Single line</t>
286 <t>Multi-line</t>
287 </list>
288 </t>
289 <t> Empty result set is issued when the server only
290 needed to acknowledge the fact that the request was
291 received and it was processed successfully and no
292 additional information is available. This result set has
293 the following format:</t>
294 <t>
295 <list>
296 <t>"OK"</t>
297 </list>
298 </t>
299 <t>Example:</t>
300 <t>
301 <list>
302 <t>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 CHANNELS=4"</t>
303 <t>S: "OK"</t>
304 </list>
305 </t>
306 <t>Single line result sets are command specific. One
307 example of a single line result set is an empty line.
308 Multi-line result sets are command specific and may
309 include one or more lines of information. They MUST
310 always end with the following line:</t>
311 <t>
312 <list>
313 <t>"."</t>
314 </list>
315 </t>
316 <t>Example:</t>
317 <t>
318 <list>
319 <t>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"</t>
320 <t>S: "DRIVER: ALSA"</t>
321 <t>&nbsp;&nbsp;&nbsp;"CHANNELS: 2"</t>
322 <t>&nbsp;&nbsp;&nbsp;"SAMPLERATE: 44100"</t>
323 <t>&nbsp;&nbsp;&nbsp;"ACTIVE: true"</t>
324 <t>&nbsp;&nbsp;&nbsp;"FRAGMENTS: 2"</t>
325 <t>&nbsp;&nbsp;&nbsp;"FRAGMENTSIZE: 128"</t>
326 <t>&nbsp;&nbsp;&nbsp;"CARD: '0,0'"</t>
327 <t>&nbsp;&nbsp;&nbsp;"."</t>
328 </list>
329 </t>
330 <t>In addition to above mentioned formats, warnings and
331 empty result sets MAY be indexed. In this case, they
332 have the following formats respectively:</t>
333 <t>
334 <list style="symbols">
335 <t>"WRN[&lt;index&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;"</t>
336 <t>"OK[&lt;index&gt;]"</t>
337 </list>
338 </t>
339 <t>where &lt;index&gt; is command specific and is used
340 to indicate channel number that the result set was
341 related to or other integer value.</t>
342 <t>Each line of the result set MUST end with
343 &lt;CRLF&gt;.</t>
344 <t>Examples:</t>
345 <t>
346 <list>
347 <t>C: "ADD CHANNEL"</t>
348 <t>S: "OK[12]"</t>
349 </list>
350 </t>
351 <t>
352 <list>
353 <t>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"</t>
354 <t>S: "WRN[0]:32:Sample rate not supported, using 44100 instead."</t>
355 </list>
356 </t>
357 </section>
358 </section>
359 <section title="Subscribe/notify communication method">
360 <t>This more sophisticated communication method is actually
361 only an extension of the simple request/response
362 communication method. The front-end still uses a TCP
363 connection and sends the same commands on the TCP
364 connection. Two extra commands are SUBSCRIBE and UNSUBSCRIBE
365 commands that allow a client to tell the server that it is
366 interested in receiving notifications about certain events
367 as they happen on the server. The SUBSCRIBE command has the
368 following syntax:</t>
369
370 <t>
371 <list>
372 <t>SUBSCRIBE &lt;event-id&gt;</t>
373 </list>
374 </t>
375
376 <t>where &lt;event-id&gt; will be replaced by the respective
377 event that client wants to subscribe to. Upon receiving such
378 request, server SHOULD respond with OK and start sending
379 EVENT notifications when a given even has occurred to the
380 front-end when an event has occurred. It MAY be possible
381 certain events may be sent before OK response during real
382 time nature of their generation. Event messages have the
383 following format:</t>
384
385 <t>
386 <list>
387 <t>NOTIFY:&lt;event-id&gt;:&lt;custom-event-data&gt;</t>
388 </list>
389 </t>
390
391 <t>where &lt;event-id&gt; uniquely identifies the event that
392 has occurred and &lt;custom-event-data&gt; is event
393 specific.</t>
394
395 <t>Several rules must be followed by the server when
396 generating events:</t>
397
398 <t>
399 <list style="numbers">
400 <t>Events MUST NOT be sent to any client who has not
401 issued an appropriate SUBSCRIBE command.</t>
402 <t>Events MUST only be sent using the same
403 connection that was used to subscribe to them.</t>
404 <t>When response is being sent to the client, event
405 MUST be inserted in the stream before or after the
406 response, but NOT in the middle. Same is true about
407 the response. It should never be inserted in the
408 middle of the event message as well as any other
409 response.</t>
410 </list>
411 </t>
412
413 <t>If the client is not interested in a particular event
414 anymore it MAY issue UNSUBSCRIBE command using the following
415 syntax:</t>
416
417 <t>
418 <list>
419 <t>UNSUBSCRIBE &lt;event-id&gt;</t>
420 </list>
421 </t>
422
423 <t>where &lt;event-id&gt; will be replace by the respective
424 event that client is no longer interested in receiving. For
425 a list of supported events see <xref target="events" />.</t>
426
427 <t>Example: the fill states of disk stream buffers have
428 changed on sampler channel 4 and the LinuxSampler instance
429 will react by sending the following message to all clients
430 who subscribed to this event:</t>
431
432 <t>
433 <list>
434 <t>NOTIFY:CHANNEL_BUFFER_FILL:4 [35]62%,[33]80%,[37]98%</t>
435 </list>
436 </t>
437
438 <t>Which means there are currently three active streams on
439 sampler channel 4, where the stream with ID "35" is filled
440 by 62%, stream with ID 33 is filled by 80% and stream with
441 ID 37 is filled by 98%.</t>
442
443 <t>Clients may choose to open more than one connection to
444 the server and use some connections to receive notifications
445 while using other connections to issue commands to the
446 back-end. This is entirely legal and up to the
447 implementation. This does not change the protocol in any way
448 and no special restrictions exist on the server to allow or
449 disallow this or to track what connections belong to what
450 front-ends. Server will listen on a single port, accept
451 multiple connections and support protocol described in this
452 specification in it's entirety on this single port on each
453 connection that it accepted.</t>
454
455 <t>Due to the fact that TCP is used for this communication,
456 dead peers will be detected automatically by the OS TCP
457 stack. While it may take a while to detect dead peers if no
458 traffic is being sent from server to client (TCP keep-alive
459 timer is set to 2 hours on many OSes) it will not be an
460 issue here as when notifications are sent by the server,
461 dead client will be detected quickly.</t>
462
463 <t>When connection is closed for any reason server MUST
464 forget all subscriptions that were made on this connection.
465 If client reconnects it MUST resubscribe to all events that
466 it wants to receive.</t>
467
468 </section>
469 </section>
470
471 <section title="Description for control commands" anchor="control_commands">
472 <t>This chapter will describe the available control commands
473 that can be sent on the TCP connection in detail. Some certain
474 commands (e.g. <xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref>
475 or <xref target="GET ENGINE INFO">"GET ENGINE INFO"</xref>) lead to
476 multiple-line responses. In this case LinuxSampler signals the
477 end of the response by a "." (single dot) line.</t>
478
479 <section title="Ignored lines and comments">
480 <t>White lines, that is lines which only contain space and
481 tabulator characters, and lines that start with a "#"
482 character are ignored, thus it's possible for example to
483 group commands and to place comments in a LSCP script
484 file.</t>
485 </section>
486
487 <section title="Configuring audio drivers">
488 <t>Instances of drivers in LinuxSampler are called devices.
489 You can use multiple audio devices simultaneously, e.g. to
490 output the sound of one sampler channel using the ALSA audio
491 output driver, and on another sampler channel you might want
492 to use the JACK audio output driver. For particular audio
493 output systems it's also possible to create several devices
494 of the same audio output driver, e.g. two separate ALSA
495 audio output devices for using two different sound cards at
496 the same time. This chapter describes all commands to
497 configure LinuxSampler's audio output devices and their
498 parameters.</t>
499
500 <t>Instead of defining commands and parameters for each
501 driver individually, all possible parameters, their meanings
502 and possible values have to be obtained at runtime. This
503 makes the protocol a bit abstract, but has the advantage,
504 that front-ends can be written independently of what drivers
505 are currently implemented and what parameters these drivers
506 are actually offering. This means front-ends can even handle
507 drivers which are implemented somewhere in future without
508 modifying the front-end at all.</t>
509
510 <t>Note: examples in this chapter showing particular
511 parameters of drivers are not meant as specification of the
512 drivers' parameters. Driver implementations in LinuxSampler
513 might have complete different parameter names and meanings
514 than shown in these examples or might change in future, so
515 these examples are only meant for showing how to retrieve
516 what parameters drivers are offering, how to retrieve their
517 possible values, etc.</t>
518
519 <section title="Getting amount of available audio output drivers" anchor="GET AVAILABLE_AUDIO_OUTPUT_DRIVERS" lscp_cmd="true">
520 <t>Use the following command to get the number of
521 audio output drivers currently available for the
522 LinuxSampler instance:</t>
523 <t>
524 <list>
525 <t>GET AVAILABLE_AUDIO_OUTPUT_DRIVERS</t>
526 </list>
527 </t>
528 <t>Possible Answers:</t>
529 <t>
530 <list>
531 <t>LinuxSampler will answer by sending the
532 number of audio output drivers.</t>
533 </list>
534 </t>
535 <t>Example:</t>
536 <t>
537 <list>
538 <t>C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"</t>
539 <t>S: "2"</t>
540 </list>
541 </t>
542 </section>
543
544 <section title="Getting all available audio output drivers" anchor="LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" lscp_cmd="true">
545 <t>Use the following command to list all audio output
546 drivers currently available for the LinuxSampler
547 instance:</t>
548 <t>
549 <list>
550 <t>LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS</t>
551 </list>
552 </t>
553 <t>Possible Answers:</t>
554 <t>
555 <list>
556 <t>LinuxSampler will answer by sending comma
557 separated character strings, each symbolizing an
558 audio output driver.</t>
559 </list>
560 </t>
561 <t>Example:</t>
562 <t>
563 <list>
564 <t>C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"</t>
565 <t>S: "ALSA,JACK"</t>
566 </list>
567 </t>
568 </section>
569
570 <section title="Getting information about a specific audio
571 output driver" anchor="GET AUDIO_OUTPUT_DRIVER INFO" lscp_cmd="true">
572 <t>Use the following command to get detailed information
573 about a specific audio output driver:</t>
574 <t>
575 <list>
576 <t>GET AUDIO_OUTPUT_DRIVER INFO
577 &lt;audio-output-driver&gt;</t>
578 </list>
579 </t>
580 <t>Where &lt;audio-output-driver&gt; is the name of the
581 audio output driver, returned by the
582 <xref target="LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"</xref> command.</t>
583 <t>Possible Answers:</t>
584 <t>
585 <list>
586 <t>LinuxSampler will answer by sending a
587 &lt;CRLF&gt; separated list. Each answer line
588 begins with the information category name
589 followed by a colon and then a space character
590 &lt;SP&gt; and finally the info character string
591 to that info category. At the moment the
592 following information categories are
593 defined:</t>
594
595 <t>
596 <list>
597 <t>DESCRIPTION -
598 <list>
599 <t> character string describing the
600 audio output driver</t>
601 </list>
602 </t>
603
604 <t>VERSION -
605 <list>
606 <t>character string reflecting the
607 driver's version</t>
608 </list>
609 </t>
610
611 <t>PARAMETERS -
612 <list>
613 <t>comma separated list of all
614 parameters available for the given
615 audio output driver, at least
616 parameters 'channels', 'samplerate'
617 and 'active' are offered by all audio
618 output drivers</t>
619 </list>
620 </t>
621 </list>
622 </t>
623
624 <t>The mentioned fields above don't have to be
625 in particular order.</t>
626 </list>
627 </t>
628 <t>Example:</t>
629 <t>
630 <list>
631 <t>C: "GET AUDIO_OUTPUT_DRIVER INFO ALSA"</t>
632 <t>S: "DESCRIPTION: Advanced Linux Sound
633 Architecture"</t>
634 <t>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"</t>
635 <t>&nbsp;&nbsp;&nbsp;"PARAMETERS:
636 DRIVER,CHANNELS,SAMPLERATE,ACTIVE,FRAGMENTS,
637 FRAGMENTSIZE,CARD"</t>
638 <t>&nbsp;&nbsp;&nbsp;"."</t>
639 </list>
640 </t>
641 </section>
642
643 <section title="Getting information about specific audio
644 output driver parameter" anchor="GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO" lscp_cmd="true">
645 <t>Use the following command to get detailed information
646 about a specific audio output driver parameter:</t>
647 <t>
648 <list>
649 <t>GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO &lt;audio&gt; &lt;prm&gt; [&lt;deplist&gt;]</t>
650 </list>
651 </t>
652 <t>Where &lt;audio&gt; is the name of the audio output
653 driver as returned by the <xref target="LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">
654 "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"</xref> command,
655 &lt;prm&gt; a specific parameter name for which information should be
656 obtained (as returned by the
657 <xref target="GET AUDIO_OUTPUT_DRIVER INFO">"GET AUDIO_OUTPUT_DRIVER INFO"</xref> command) and
658 &lt;deplist&gt; is an optional list of parameters on which the sought
659 parameter &lt;prm&gt; depends on, &lt;deplist&gt; is a list of key-value
660 pairs in form of "key1=val1 key2=val2 ...", where character string values
661 are encapsulated into apostrophes ('). Arguments given with &lt;deplist&gt;
662 which are not dependency parameters of &lt;prm&gt; will be ignored, means
663 the front-end application can simply put all parameters into &lt;deplist&gt;
664 with the values already selected by the user.</t>
665 <t>Possible Answers:</t>
666 <t>
667 <list>
668 <t>LinuxSampler will answer by sending a
669 &lt;CRLF&gt; separated list.
670 Each answer line begins with the information category name
671 followed by a colon and then a space character &lt;SP&gt; and
672 finally
673 the info character string to that info category. There are
674 information which is always returned, independently of the
675 given driver parameter and there are optional information
676 which is only shown dependently to given driver parameter. At
677 the moment the following information categories are defined:</t>
678 </list>
679 </t>
680
681 <t>
682 <list>
683 <t>TYPE -
684 <list>
685 <t>either "BOOL" for boolean value(s) or
686 "INT" for integer
687 value(s) or "FLOAT" for dotted number(s) or "STRING" for
688 character string(s)
689 (always returned, no matter which driver parameter)</t>
690 </list>
691 </t>
692
693 <t>DESCRIPTION -
694 <list>
695 <t>arbitrary text describing the purpose of the parameter
696 (always returned, no matter which driver parameter)</t>
697 </list>
698 </t>
699
700 <t>MANDATORY -
701 <list>
702 <t>either true or false, defines if this parameter must be
703 given when the device is to be created with the
704 <xref target="CREATE AUDIO_OUTPUT_DEVICE">'CREATE AUDIO_OUTPUT_DEVICE'</xref>
705 command (always returned, no matter which driver parameter)</t>
706 </list>
707 </t>
708
709 <t>FIX -
710 <list>
711 <t>either true or false, if false then this parameter can
712 be changed at any time, once the device is created by
713 the <xref target="CREATE AUDIO_OUTPUT_DEVICE">'CREATE AUDIO_OUTPUT_DEVICE'</xref>
714 command (always returned, no matter which driver parameter)</t>
715 </list>
716 </t>
717
718 <t>MULTIPLICITY -
719 <list>
720 <t>either true or false, defines if this parameter allows
721 only one value or a list of values, where true means
722 multiple values and false only a single value allowed
723 (always returned, no matter which driver parameter)</t>
724 </list>
725 </t>
726
727 <t>DEPENDS -
728 <list>
729 <t>comma separated list of parameters this parameter depends
730 on, means the values for fields 'DEFAULT', 'RANGE_MIN',
731 'RANGE_MAX' and 'POSSIBILITIES' might depend on these
732 listed parameters, for example assuming that an audio
733 driver (like the ALSA driver) offers parameters 'card'
734 and 'samplerate' then parameter 'samplerate' would
735 depend on 'card' because the possible values for
736 'samplerate' depends on the sound card which can be
737 chosen by the 'card' parameter
738 (optionally returned, dependent to driver parameter)</t>
739 </list>
740 </t>
741
742 <t>DEFAULT -
743 <list>
744 <t>reflects the default value for this parameter which is
745 used when the device is created and not explicitly
746 given with the <xref target="CREATE AUDIO_OUTPUT_DEVICE">
747 'CREATE AUDIO_OUTPUT_DEVICE'</xref> command,
748 in case of MULTIPLCITY=true, this is a comma separated
749 list, that's why character strings are encapsulated into
750 apostrophes (')
751 (optionally returned, dependent to driver parameter)</t>
752 </list>
753 </t>
754
755 <t>RANGE_MIN -
756 <list>
757 <t>defines lower limit of the allowed value range for this
758 parameter, can be an integer value as well as a dotted
759 number, this parameter is often used in conjunction
760 with RANGE_MAX, but may also appear without
761 (optionally returned, dependent to driver parameter)</t>
762 </list>
763 </t>
764
765 <t>RANGE_MAX -
766 <list>
767 <t>defines upper limit of the allowed value range for this
768 parameter, can be an integer value as well as a dotted
769 number, this parameter is often used in conjunction with
770 RANGE_MIN, but may also appear without
771 (optionally returned, dependent to driver parameter)</t>
772 </list>
773 </t>
774
775 <t>POSSIBILITIES -
776 <list>
777 <t>comma separated list of possible values for this
778 parameter, character strings are encapsulated into
779 apostrophes
780 (optionally returned, dependent to driver parameter)</t>
781 </list>
782 </t>
783 </list>
784 </t>
785
786 <t>The mentioned fields above don't have to be in particular order.</t>
787
788 <t>Examples:</t>
789 <t>
790 <list>
791 <t>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA CARD"</t>
792 <t>S: "DESCRIPTION: sound card to be used"</t>
793 <t>&nbsp;&nbsp;&nbsp;"TYPE: STRING"</t>
794 <t>&nbsp;&nbsp;&nbsp;"MANDATORY: false"</t>
795 <t>&nbsp;&nbsp;&nbsp;"FIX: true"</t>
796 <t>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"</t>
797 <t>&nbsp;&nbsp;&nbsp;"DEFAULT: '0,0'"</t>
798 <t>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: '0,0','1,0','2,0'"</t>
799 <t>&nbsp;&nbsp;&nbsp;"."</t>
800 </list>
801 </t>
802 <t>
803 <list>
804 <t>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE"</t>
805 <t>S: "DESCRIPTION: output sample rate in Hz"</t>
806 <t>&nbsp;&nbsp;&nbsp;"TYPE: INT"</t>
807 <t>&nbsp;&nbsp;&nbsp;"MANDATORY: false"</t>
808 <t>&nbsp;&nbsp;&nbsp;"FIX: false"</t>
809 <t>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"</t>
810 <t>&nbsp;&nbsp;&nbsp;"DEPENDS: card"</t>
811 <t>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"</t>
812 <t>&nbsp;&nbsp;&nbsp;"."</t>
813 </list>
814 </t>
815 <t>
816 <list>
817 <t>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE CARD='0,0'"</t>
818 <t>S: "DESCRIPTION: output sample rate in Hz"</t>
819 <t>&nbsp;&nbsp;&nbsp;"TYPE: INT"</t>
820 <t>&nbsp;&nbsp;&nbsp;"MANDATORY: false"</t>
821 <t>&nbsp;&nbsp;&nbsp;"FIX: false"</t>
822 <t>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"</t>
823 <t>&nbsp;&nbsp;&nbsp;"DEPENDS: card"</t>
824 <t>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"</t>
825 <t>&nbsp;&nbsp;&nbsp;"RANGE_MIN: 22050"</t>
826 <t>&nbsp;&nbsp;&nbsp;"RANGE_MAX: 96000"</t>
827 <t>&nbsp;&nbsp;&nbsp;"."</t>
828 </list>
829 </t>
830 </section>
831
832 <section title="Creating an audio output device" anchor="CREATE AUDIO_OUTPUT_DEVICE" lscp_cmd="true">
833 <t>Use the following command to create a new audio output device for the desired audio output system:</t>
834
835 <t>
836 <list>
837 <t>CREATE AUDIO_OUTPUT_DEVICE &lt;audio-output-driver&gt; [&lt;param-list&gt;]</t>
838 </list>
839 </t>
840
841 <t>Where &lt;audio-output-driver&gt; should be replaced by the desired audio
842 output system as returned by the
843 <xref target="LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"</xref>
844 command and &lt;param-list&gt; by an optional list of driver
845 specific parameters in form of "key1=val1 key2=val2 ...", where
846 character string values should be encapsulated into apostrophes (').
847 Note that there might be drivers which require parameter(s) to be
848 given with this command. Use the previously described commands in
849 this chapter to get this information.</t>
850
851 <t>Possible Answers:</t>
852 <t>
853 <list>
854 <t>"OK[&lt;device-id&gt;]" -
855 <list>
856 <t>in case the device was successfully created, where
857 &lt;device-id&gt; is the numerical ID of the new device</t>
858 </list>
859 </t>
860 <t>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
861 <list>
862 <t>in case the device was created successfully, where
863 &lt;device-id&gt; is the numerical ID of the new device, but there
864 are noteworthy issue(s) related (e.g. sound card doesn't
865 support given hardware parameters and the driver is using
866 fall-back values), providing an appropriate warning code and
867 warning message</t>
868 </list>
869 </t>
870 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
871 <list>
872 <t>in case it failed, providing an appropriate error code and error message</t>
873 </list>
874 </t>
875 </list>
876 </t>
877 <t>Examples:</t>
878 <t>
879 <list>
880 <t>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA"</t>
881 <t>S: "OK[0]"</t>
882 </list>
883 </t>
884 <t>
885 <list>
886 <t>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"</t>
887 <t>S: "OK[1]"</t>
888 </list>
889 </t>
890 </section>
891
892 <section title="Destroying an audio output device" anchor="DESTROY AUDIO_OUTPUT_DEVICE" lscp_cmd="true">
893 <t>Use the following command to destroy a created output device:</t>
894 <t>
895 <list>
896 <t>DESTROY AUDIO_OUTPUT_DEVICE &lt;device-id&gt;</t>
897 </list>
898 </t>
899 <t>Where &lt;device-id&gt; should be replaced by the numerical ID of the
900 audio output device as given by the
901 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
902 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
903 command.</t>
904 <t>Possible Answers:</t>
905 <t>
906 <list>
907 <t>"OK" -
908 <list>
909 <t>in case the device was successfully destroyed</t>
910 </list>
911 </t>
912 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
913 <list>
914 <t>in case the device was destroyed successfully, but there are
915 noteworthy issue(s) related (e.g. an audio over ethernet
916 driver was unloaded but the other host might not be
917 informed about this situation), providing an appropriate
918 warning code and warning message</t>
919 </list>
920 </t>
921 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
922 <list>
923 <t>in case it failed, providing an appropriate error code and
924 error message</t>
925 </list>
926 </t>
927 </list>
928 </t>
929 <t>Example:</t>
930 <t>
931 <list>
932 <t>C: "DESTROY AUDIO_OUTPUT_DEVICE 0"</t>
933 <t>S: "OK"</t>
934 </list>
935 </t>
936 </section>
937
938 <section title="Getting all created audio output device count" anchor="GET AUDIO_OUTPUT_DEVICES">
939 <t>Use the following command to count all created audio output devices:</t>
940 <t>
941 <list>
942 <t>GET AUDIO_OUTPUT_DEVICES</t>
943 </list>
944 </t>
945 <t>Possible Answers:</t>
946 <t>
947 <list>
948 <t>LinuxSampler will answer by sending the current number of all
949 audio output devices.</t>
950 </list>
951 </t>
952 <t>Example:</t>
953 <t>
954 <list>
955 <t>C: "GET AUDIO_OUTPUT_DEVICES"</t>
956 <t>S: "4"</t>
957 </list>
958 </t>
959 </section>
960
961 <section title="Getting all created audio output device list" anchor="LIST AUDIO_OUTPUT_DEVICES" lscp_cmd="true">
962 <t>Use the following command to list all created audio output devices:</t>
963 <t>
964 <list>
965 <t>LIST AUDIO_OUTPUT_DEVICES</t>
966 </list>
967 </t>
968 <t>Possible Answers:</t>
969 <t>
970 <list>
971 <t>LinuxSampler will answer by sending a comma separated list with
972 the numerical IDs of all audio output devices.</t>
973 </list>
974 </t>
975 <t>Example:</t>
976 <t>
977 <list>
978 <t>C: "LIST AUDIO_OUTPUT_DEVICES"</t>
979 <t>S: "0,1,4,5"</t>
980 </list>
981 </t>
982 </section>
983
984 <section title="Getting current settings of an audio output device" anchor="GET AUDIO_OUTPUT_DEVICE INFO" lscp_cmd="true">
985 <t>Use the following command to get current settings of a specific, created audio output device:</t>
986 <t>
987 <list>
988 <t>GET AUDIO_OUTPUT_DEVICE INFO &lt;device-id&gt;</t>
989 </list>
990 </t>
991 <t>Where &lt;device-id&gt; should be replaced by numerical ID
992 of the audio output device as e.g. returned by the
993 <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref> command.</t>
994 <t>Possible Answers:</t>
995 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
996 Each answer line begins with the information category name
997 followed by a colon and then a space character &lt;SP&gt; and finally
998 the info character string to that info category. As some
999 parameters might allow multiple values, character strings are
1000 encapsulated into apostrophes ('). At the moment the following
1001 information categories are defined (independently of device):</t>
1002 <t>
1003 <list>
1004 <t>DRIVER -
1005 <list>
1006 <t>identifier of the used audio output driver, as also
1007 returned by the
1008 <xref target="LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">
1009 "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"</xref>
1010 command</t>
1011 </list>
1012 </t>
1013 <t>CHANNELS -
1014 <list>
1015 <t>amount of audio output channels this device currently
1016 offers</t>
1017 </list>
1018 </t>
1019 <t>SAMPLERATE -
1020 <list>
1021 <t>playback sample rate the device uses</t>
1022 </list>
1023 </t>
1024 <t>ACTIVE -
1025 <list>
1026 <t>either true or false, if false then the audio device is
1027 inactive and doesn't output any sound, nor do the
1028 sampler channels connected to this audio device render
1029 any audio</t>
1030 </list>
1031 </t>
1032 </list>
1033 </t>
1034 <t>The mentioned fields above don't have to be in particular
1035 order. The fields above are only those fields which are
1036 returned by all audio output devices. Every audio output driver
1037 might have its own, additional driver specific parameters (see
1038 <xref target="GET AUDIO_OUTPUT_DRIVER INFO" />)
1039 which are also returned by this command.</t>
1040 <t>Example:</t>
1041 <t>
1042 <list>
1043 <t>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"</t>
1044 <t>S: "DRIVER: ALSA"</t>
1045 <t>&nbsp;&nbsp;&nbsp;"CHANNELS: 2"</t>
1046 <t>&nbsp;&nbsp;&nbsp;"SAMPLERATE: 44100"</t>
1047 <t>&nbsp;&nbsp;&nbsp;"ACTIVE: true"</t>
1048 <t>&nbsp;&nbsp;&nbsp;"FRAGMENTS: 2"</t>
1049 <t>&nbsp;&nbsp;&nbsp;"FRAGMENTSIZE: 128"</t>
1050 <t>&nbsp;&nbsp;&nbsp;"CARD: '0,0'"</t>
1051 <t>&nbsp;&nbsp;&nbsp;"."</t>
1052 </list>
1053 </t>
1054 </section>
1055
1056
1057 <section title="Changing settings of audio output devices" anchor="SET AUDIO_OUTPUT_DEVICE_PARAMETER" lscp_cmd="true">
1058 <t>Use the following command to alter a specific setting of a created audio output device:</t>
1059 <t>
1060 <list>
1061 <t>SET AUDIO_OUTPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;</t>
1062 </list>
1063 </t>
1064 <t>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1065 audio output device as given by the
1066 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
1067 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
1068 command, &lt;key&gt; by the name of the parameter to change
1069 and &lt;value&gt; by the new value for this parameter.</t>
1070 <t>Possible Answers:</t>
1071 <t>
1072 <list>
1073 <t>"OK" -
1074 <list>
1075 <t>in case setting was successfully changed</t>
1076 </list>
1077 </t>
1078 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1079 <list>
1080 <t>in case setting was changed successfully, but there are
1081 noteworthy issue(s) related, providing an appropriate
1082 warning code and warning message</t>
1083 </list>
1084 </t>
1085 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1086 <list>
1087 <t>in case it failed, providing an appropriate error code and
1088 error message</t>
1089 </list>
1090 </t>
1091 </list>
1092 </t>
1093 <t>Example:</t>
1094 <t>
1095 <list>
1096 <t>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"</t>
1097 <t>S: "OK"</t>
1098 </list>
1099 </t>
1100 </section>
1101
1102 <section title="Getting information about an audio channel" anchor="GET AUDIO_OUTPUT_CHANNEL INFO" lscp_cmd="true">
1103 <t>Use the following command to get information about an audio channel:</t>
1104 <t>
1105 <list>
1106 <t>GET AUDIO_OUTPUT_CHANNEL INFO &lt;device-id&gt; &lt;audio-chan&gt;</t>
1107 </list>
1108 </t>
1109 <t>Where &lt;device-id&gt; is the numerical ID of the audio output device as given by the
1110 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
1111 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
1112 command and &lt;audio-chan&gt; the audio channel number.</t>
1113 <t>Possible Answers:</t>
1114 <t>
1115 <list>
1116 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1117 Each answer line begins with the information category name
1118 followed by a colon and then a space character &lt;SP&gt; and finally
1119 the info character string to that info category. At the moment
1120 the following information categories are defined:</t>
1121
1122 <t>
1123 <list>
1124 <t>NAME -
1125 <list>
1126 <t>arbitrary character string naming the channel, which
1127 doesn't have to be unique (always returned by all audio channels)</t>
1128 </list>
1129 </t>
1130 <t>IS_MIX_CHANNEL -
1131 <list>
1132 <t>either true or false, a mix-channel is not a real,
1133 independent audio channel, but a virtual channel which
1134 is mixed to another real channel, this mechanism is
1135 needed for sampler engines which need more audio
1136 channels than the used audio system might be able to offer
1137 (always returned by all audio channels)</t>
1138 </list>
1139 </t>
1140 <t>MIX_CHANNEL_DESTINATION -
1141 <list>
1142 <t>numerical ID (positive integer including 0)
1143 which reflects the real audio channel (of the same audio
1144 output device) this mix channel refers to, means where
1145 the audio signal actually will be routed / added to
1146 (only returned in case the audio channel is mix channel)</t>
1147 </list>
1148 </t>
1149 </list>
1150 </t>
1151 </list>
1152 </t>
1153
1154 <t>The mentioned fields above don't have to be in particular
1155 order. The fields above are only those fields which are
1156 generally returned for the described cases by all audio
1157 channels regardless of the audio driver. Every audio channel
1158 might have its own, additional driver and channel specific
1159 parameters.</t>
1160
1161 <t>Examples:</t>
1162
1163 <t>
1164 <list>
1165 <t>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 0"</t>
1166 <t>S: "NAME: studio monitor left"</t>
1167 <t>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"</t>
1168 <t>&nbsp;&nbsp;&nbsp;"."</t>
1169 </list>
1170 </t>
1171
1172 <t>
1173 <list>
1174 <t>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 1"</t>
1175 <t>S: "NAME: studio monitor right"</t>
1176 <t>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"</t>
1177 <t>&nbsp;&nbsp;&nbsp;"."</t>
1178 </list>
1179 </t>
1180
1181 <t>
1182 <list>
1183 <t>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"</t>
1184 <t>S: "NAME: studio monitor left"</t>
1185 <t>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: true"</t>
1186 <t>&nbsp;&nbsp;&nbsp;"MIX_CHANNEL_DESTINATION: 1"</t>
1187 <t>&nbsp;&nbsp;&nbsp;"."</t>
1188 </list>
1189 </t>
1190
1191 <t>
1192 <list>
1193 <t>C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"</t>
1194 <t>S: "NAME: 'ardour (left)'"</t>
1195 <t>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"</t>
1196 <t>&nbsp;&nbsp;&nbsp;"JACK_BINDINGS: 'ardour:0'"</t>
1197 <t>&nbsp;&nbsp;&nbsp;"."</t>
1198 </list>
1199 </t>
1200 </section>
1201
1202 <section title="Getting information about specific audio channel parameter" anchor="GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO" lscp_cmd="true">
1203 <t>Use the following command to get detailed information about specific audio channel parameter:</t>
1204
1205 <t>
1206 <list>
1207 <t>GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO &lt;dev-id&gt; &lt;chan&gt; &lt;param&gt;</t>
1208 </list>
1209 </t>
1210
1211 <t>Where &lt;dev-id&gt; is the numerical ID of the audio output device as returned by the
1212 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
1213 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
1214 command, &lt;chan&gt; the audio channel number
1215 and &lt;param&gt; a specific channel parameter name for which information should
1216 be obtained (as returned by the <xref target="GET AUDIO_OUTPUT_CHANNEL INFO">
1217 "GET AUDIO_OUTPUT_CHANNEL INFO"</xref> command).</t>
1218 <t>Possible Answers:</t>
1219
1220 <t>
1221 <list>
1222 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1223 Each answer line begins with the information category name
1224 followed by a colon and then a space character &lt;SP&gt; and finally
1225 the info character string to that info category. There are
1226 information which is always returned, independently of the
1227 given channel parameter and there is optional information
1228 which is only shown dependently to the given audio channel. At
1229 the moment the following information categories are defined:</t>
1230 <t>
1231 <list>
1232 <t>TYPE -
1233 <list>
1234 <t>either "BOOL" for boolean value(s) or "INT" for integer
1235 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1236 character string(s)
1237 (always returned)</t>
1238 </list>
1239 </t>
1240 <t>DESCRIPTION -
1241 <list>
1242 <t>arbitrary text describing the purpose of the parameter (always returned)</t>
1243 </list>
1244 </t>
1245 <t>FIX -
1246 <list>
1247 <t>either true or false, if true then this parameter is
1248 read only, thus cannot be altered
1249 (always returned)</t>
1250 </list>
1251 </t>
1252 <t>MULTIPLICITY -
1253 <list>
1254 <t>either true or false, defines if this parameter allows
1255 only one value or a list of values, where true means
1256 multiple values and false only a single value allowed
1257 (always returned)</t>
1258 </list>
1259 </t>
1260 <t>RANGE_MIN -
1261 <list>
1262 <t>defines lower limit of the allowed value range for this
1263 parameter, can be an integer value as well as a dotted
1264 number, usually used in conjunction with 'RANGE_MAX',
1265 but may also appear without
1266 (optionally returned, dependent to driver and channel
1267 parameter)</t>
1268 </list>
1269 </t>
1270 <t>RANGE_MAX -
1271 <list>
1272 <t>defines upper limit of the allowed value range for this
1273 parameter, can be an integer value as well as a dotted
1274 number, usually used in conjunction with 'RANGE_MIN',
1275 but may also appear without
1276 (optionally returned, dependent to driver and channel
1277 parameter)</t>
1278 </list>
1279 </t>
1280 <t>POSSIBILITIES -
1281 <list>
1282 <t>comma separated list of possible values for this
1283 parameter, character strings are encapsulated into
1284 apostrophes
1285 (optionally returned, dependent to driver and channel
1286 parameter)</t>
1287 </list>
1288 </t>
1289 </list>
1290 </t>
1291 <t>The mentioned fields above don't have to be in particular order.</t>
1292 </list>
1293 </t>
1294 <t>Example:</t>
1295 <t>
1296 <list>
1297 <t>C: "GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO 1 0 JACK_BINDINGS"</t>
1298 <t>S: "DESCRIPTION: bindings to other JACK clients"</t>
1299 <t>&nbsp;&nbsp;&nbsp;"TYPE: STRING"</t>
1300 <t>&nbsp;&nbsp;&nbsp;"FIX: false"</t>
1301 <t>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"</t>
1302 <t>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"</t>
1303 <t>&nbsp;&nbsp;&nbsp;"."</t>
1304 </list>
1305 </t>
1306 </section>
1307
1308 <section title="Changing settings of audio output channels" anchor="SET AUDIO_OUTPUT_CHANNEL_PARAMETER" lscp_cmd="true">
1309 <t>Use the following command to alter a specific setting of an audio output channel:</t>
1310 <t>
1311 <list>
1312 <t>SET AUDIO_OUTPUT_CHANNEL_PARAMETER &lt;dev-id&gt; &lt;chn&gt; &lt;key&gt;=&lt;value&gt;</t>
1313 </list>
1314 </t>
1315 <t>Where &lt;dev-id&gt; should be replaced by the numerical ID of the audio output device as returned by the
1316 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
1317 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
1318 command, &lt;chn&gt; by the audio channel number, &lt;key&gt; by the name of the
1319 parameter to change and &lt;value&gt; by the new value for this parameter.</t>
1320 <t>Possible Answers:</t>
1321 <t>
1322 <list>
1323 <t>"OK" -
1324 <list>
1325 <t>in case setting was successfully changed</t>
1326 </list>
1327 </t>
1328 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1329 <list>
1330 <t>in case setting was changed successfully, but there are
1331 noteworthy issue(s) related, providing an appropriate
1332 warning code and warning message</t>
1333 </list>
1334 </t>
1335 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1336 <list>
1337 <t>in case it failed, providing an appropriate error code and
1338 error message</t>
1339 </list>
1340 </t>
1341 </list>
1342 </t>
1343 <t>Example:</t>
1344 <t>
1345 <list>
1346 <t>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"</t>
1347 <t>S: "OK"</t>
1348 </list>
1349 </t>
1350 <t>
1351 <list>
1352 <t>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"</t>
1353 <t>S: "OK"</t>
1354 </list>
1355 </t>
1356 </section>
1357 </section>
1358
1359 <section title="Configuring MIDI input drivers">
1360 <t>Instances of drivers in LinuxSampler are called devices. You can use
1361 multiple MIDI devices simultaneously, e.g. to use MIDI over ethernet as
1362 MIDI input on one sampler channel and ALSA as MIDI input on another sampler
1363 channel. For particular MIDI input systems it's also possible to create
1364 several devices of the same MIDI input type. This chapter describes all
1365 commands to configure LinuxSampler's MIDI input devices and their parameters.</t>
1366
1367 <t>Instead of defining commands and parameters for each driver individually,
1368 all possible parameters, their meanings and possible values have to be obtained
1369 at runtime. This makes the protocol a bit abstract, but has the advantage, that
1370 front-ends can be written independently of what drivers are currently implemented
1371 and what parameters these drivers are actually offering. This means front-ends can
1372 even handle drivers which are implemented somewhere in future without modifying
1373 the front-end at all.</t>
1374
1375 <t>Commands for configuring MIDI input devices are pretty much the same as the
1376 commands for configuring audio output drivers, already described in the last
1377 chapter.</t>
1378
1379 <t>Note: examples in this chapter showing particular parameters of drivers are
1380 not meant as specification of the drivers' parameters. Driver implementations in
1381 LinuxSampler might have complete different parameter names and meanings than shown
1382 in these examples or might change in future, so these examples are only meant for
1383 showing how to retrieve what parameters drivers are offering, how to retrieve their
1384 possible values, etc.</t>
1385
1386 <section title="Getting amount of available MIDI input drivers" anchor="GET AVAILABLE_MIDI_INPUT_DRIVERS" lscp_cmd="true">
1387 <t>Use the following command to get the number of
1388 MIDI input drivers currently available for the
1389 LinuxSampler instance:</t>
1390 <t>
1391 <list>
1392 <t>GET AVAILABLE_MIDI_INPUT_DRIVERS</t>
1393 </list>
1394 </t>
1395 <t>Possible Answers:</t>
1396 <t>
1397 <list>
1398 <t>LinuxSampler will answer by sending the
1399 number of available MIDI input drivers.</t>
1400 </list>
1401 </t>
1402 <t>Example:</t>
1403 <t>
1404 <list>
1405 <t>C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"</t>
1406 <t>S: "2"</t>
1407 </list>
1408 </t>
1409 </section>
1410
1411 <section title="Getting all available MIDI input drivers" anchor="LIST AVAILABLE_MIDI_INPUT_DRIVERS" lscp_cmd="true">
1412 <t>Use the following command to list all MIDI input drivers currently available
1413 for the LinuxSampler instance:</t>
1414 <t>
1415 <list>
1416 <t>LIST AVAILABLE_MIDI_INPUT_DRIVERS</t>
1417 </list>
1418 </t>
1419 <t>Possible Answers:</t>
1420 <t>
1421 <list>
1422 <t>LinuxSampler will answer by sending comma separated character
1423 strings, each symbolizing a MIDI input driver.</t>
1424 </list>
1425 </t>
1426 <t>Example:</t>
1427 <t>
1428 <list>
1429 <t>C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"</t>
1430 <t>S: "ALSA,JACK"</t>
1431 </list>
1432 </t>
1433 </section>
1434
1435 <section title="Getting information about a specific MIDI input driver" anchor="GET MIDI_INPUT_DRIVER INFO" lscp_cmd="true">
1436 <t>Use the following command to get detailed information about a specific MIDI input driver:</t>
1437 <t>
1438 <list>
1439 <t>GET MIDI_INPUT_DRIVER INFO &lt;midi-input-driver&gt;</t>
1440 </list>
1441 </t>
1442 <t>Where &lt;midi-input-driver&gt; is the name of the MIDI input driver as returned
1443 by the <xref target="LIST AVAILABLE_MIDI_INPUT_DRIVERS">
1444 "LIST AVAILABLE_MIDI_INPUT_DRIVERS"</xref> command.</t>
1445 <t>Possible Answers:</t>
1446 <t>
1447 <list>
1448 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1449 Each answer line begins with the information category name
1450 followed by a colon and then a space character &lt;SP&gt; and finally
1451 the info character string to that info category. At the moment
1452 the following information categories are defined:</t>
1453
1454 <t>
1455 <list>
1456 <t>DESCRIPTION -
1457 <list>
1458 <t>arbitrary description text about the MIDI input driver</t>
1459 </list>
1460 </t>
1461 <t>VERSION -
1462 <list>
1463 <t>arbitrary character string regarding the driver's version</t>
1464 </list>
1465 </t>
1466 <t>PARAMETERS -
1467 <list>
1468 <t>comma separated list of all parameters available for the given MIDI input driver</t>
1469 </list>
1470 </t>
1471 </list>
1472 </t>
1473
1474 <t>The mentioned fields above don't have to be in particular order.</t>
1475 </list>
1476 </t>
1477
1478 <t>Example:</t>
1479
1480 <t>
1481 <list>
1482 <t>C: "GET MIDI_INPUT_DRIVER INFO ALSA"</t>
1483 <t>S: "DESCRIPTION: Advanced Linux Sound Architecture"</t>
1484 <t>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"</t>
1485 <t>&nbsp;&nbsp;&nbsp;"PARAMETERS: DRIVER,ACTIVE"</t>
1486 <t>&nbsp;&nbsp;&nbsp;"."</t>
1487 </list>
1488 </t>
1489 </section>
1490
1491 <section title="Getting information about specific MIDI input driver parameter" anchor="GET MIDI_INPUT_DRIVER_PARAMETER INFO" lscp_cmd="true">
1492 <t>Use the following command to get detailed information about a specific parameter of a specific MIDI input driver:</t>
1493 <t>
1494 <list>
1495 <t>GET MIDI_INPUT_DRIVER_PARAMETER INFO &lt;midit&gt; &lt;param&gt; [&lt;deplist&gt;]</t>
1496 </list>
1497 </t>
1498
1499 <t>Where &lt;midit&gt; is the name of the MIDI input driver as returned
1500 by the <xref target="LIST AVAILABLE_MIDI_INPUT_DRIVERS">
1501 "LIST AVAILABLE_MIDI_INPUT_DRIVERS"</xref> command, &lt;param&gt; a specific
1502 parameter name for which information should be obtained (as returned by the
1503 <xref target="GET MIDI_INPUT_DRIVER INFO">
1504 "GET MIDI_INPUT_DRIVER INFO"</xref> command) and &lt;deplist&gt; is an optional list
1505 of parameters on which the sought parameter &lt;param&gt; depends on,
1506 &lt;deplist&gt; is a key-value pair list in form of "key1=val1 key2=val2 ...",
1507 where character string values are encapsulated into apostrophes ('). Arguments
1508 given with &lt;deplist&gt; which are not dependency parameters of &lt;param&gt;
1509 will be ignored, means the front-end application can simply put all parameters
1510 in &lt;deplist&gt; with the values selected by the user.</t>
1511
1512 <t>Possible Answers:</t>
1513
1514 <t>LinuxSampler will answer by sending a &lt;CRLF> separated list.
1515 Each answer line begins with the information category name
1516 followed by a colon and then a space character &lt;SP> and finally
1517 the info character string to that info category. There is
1518 information which is always returned, independent of the
1519 given driver parameter and there is optional information
1520 which is only shown dependent to given driver parameter. At
1521 the moment the following information categories are defined:</t>
1522
1523 <t>
1524 <list>
1525 <t>TYPE -
1526 <list>
1527 <t>either "BOOL" for boolean value(s) or "INT" for integer
1528 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1529 character string(s)
1530 (always returned, no matter which driver parameter)</t>
1531 </list>
1532 </t>
1533
1534 <t>DESCRIPTION -
1535 <list>
1536 <t>arbitrary text describing the purpose of the parameter
1537 (always returned, no matter which driver parameter)</t>
1538 </list>
1539 </t>
1540
1541 <t>MANDATORY -
1542 <list>
1543 <t>either true or false, defines if this parameter must be
1544 given when the device is to be created with the
1545 <xref target="CREATE MIDI_INPUT_DEVICE">
1546 'CREATE MIDI_INPUT_DEVICE'</xref> command
1547 (always returned, no matter which driver parameter)</t>
1548 </list>
1549 </t>
1550
1551 <t>FIX -
1552 <list>
1553 <t>either true or false, if false then this parameter can
1554 be changed at any time, once the device is created by
1555 the <xref target="CREATE MIDI_INPUT_DEVICE">
1556 'CREATE MIDI_INPUT_DEVICE'</xref> command
1557 (always returned, no matter which driver parameter)</t>
1558 </list>
1559 </t>
1560
1561 <t>MULTIPLICITY -
1562 <list>
1563 <t>either true or false, defines if this parameter allows
1564 only one value or a list of values, where true means
1565 multiple values and false only a single value allowed
1566 (always returned, no matter which driver parameter)</t>
1567 </list>
1568 </t>
1569
1570 <t>DEPENDS -
1571 <list>
1572 <t>comma separated list of parameters this parameter depends
1573 on, means the values for fields 'DEFAULT', 'RANGE_MIN',
1574 'RANGE_MAX' and 'POSSIBILITIES' might depend on these
1575 listed parameters, for example assuming that an audio
1576 driver (like the ALSA driver) offers parameters 'card'
1577 and 'samplerate' then parameter 'samplerate' would
1578 depend on 'card' because the possible values for
1579 'samplerate' depends on the sound card which can be
1580 chosen by the 'card' parameter
1581 (optionally returned, dependent to driver parameter)</t>
1582 </list>
1583 </t>
1584
1585 <t>DEFAULT -
1586 <list>
1587 <t>reflects the default value for this parameter which is
1588 used when the device is created and not explicitly
1589 given with the <xref target="CREATE MIDI_INPUT_DEVICE">
1590 'CREATE MIDI_INPUT_DEVICE'</xref> command,
1591 in case of MULTIPLCITY=true, this is a comma separated
1592 list, that's why character strings are encapsulated into
1593 apostrophes (')
1594 (optionally returned, dependent to driver parameter)</t>
1595 </list>
1596 </t>
1597
1598 <t>RANGE_MIN -
1599 <list>
1600 <t>defines lower limit of the allowed value range for this
1601 parameter, can be an integer value as well as a dotted
1602 number, this parameter is often used in conjunction
1603 with RANGE_MAX, but may also appear without
1604 (optionally returned, dependent to driver parameter)</t>
1605 </list>
1606 </t>
1607
1608 <t>RANGE_MAX -
1609 <list>
1610 <t>defines upper limit of the allowed value range for this
1611 parameter, can be an integer value as well as a dotted
1612 number, this parameter is often used in conjunction with
1613 RANGE_MIN, but may also appear without
1614 (optionally returned, dependent to driver parameter)</t>
1615 </list>
1616 </t>
1617
1618 <t>POSSIBILITIES -
1619 <list>
1620 <t>comma separated list of possible values for this
1621 parameter, character strings are encapsulated into
1622 apostrophes
1623 (optionally returned, dependent to driver parameter)</t>
1624 </list>
1625 </t>
1626 </list>
1627 </t>
1628
1629 <t>The mentioned fields above don't have to be in particular order.</t>
1630
1631 <t>Example:</t>
1632 <t>
1633 <list>
1634 <t>C: "GET MIDI_INPUT_DRIVER_PARAMETER INFO ALSA ACTIVE"</t>
1635 <t>S: "DESCRIPTION: Whether device is enabled"</t>
1636 <t>&nbsp;&nbsp;&nbsp;"TYPE: BOOL"</t>
1637 <t>&nbsp;&nbsp;&nbsp;"MANDATORY: false"</t>
1638 <t>&nbsp;&nbsp;&nbsp;"FIX: false"</t>
1639 <t>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"</t>
1640 <t>&nbsp;&nbsp;&nbsp;"DEFAULT: true"</t>
1641 <t>&nbsp;&nbsp;&nbsp;"."</t>
1642 </list>
1643 </t>
1644 </section>
1645
1646 <section title="Creating a MIDI input device" anchor="CREATE MIDI_INPUT_DEVICE" lscp_cmd="true">
1647 <t>Use the following command to create a new MIDI input device for the desired MIDI input system:</t>
1648 <t>
1649 <list>
1650 <t>CREATE MIDI_INPUT_DEVICE &lt;midi-input-driver&gt; [&lt;param-list&gt;]</t>
1651 </list>
1652 </t>
1653
1654 <t>Where &lt;midi-input-driver&gt; should be replaced by the desired MIDI input system as returned
1655 by the <xref target="LIST AVAILABLE_MIDI_INPUT_DRIVERS">
1656 "LIST AVAILABLE_MIDI_INPUT_DRIVERS"</xref> command and &lt;param-list&gt; by an
1657 optional list of driver specific parameters in form of "key1=val1 key2=val2 ...", where
1658 character string values should be encapsulated into apostrophes (').
1659 Note that there might be drivers which require parameter(s) to be
1660 given with this command. Use the previously described commands in
1661 this chapter to get that information.</t>
1662
1663 <t>Possible Answers:</t>
1664 <t>
1665 <list>
1666 <t>"OK[&lt;device-id&gt;]" -
1667 <list>
1668 <t>in case the device was successfully created, where
1669 &lt;device-id&gt; is the numerical ID of the new device</t>
1670 </list>
1671 </t>
1672 <t>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1673 <list>
1674 <t>in case the driver was loaded successfully, where
1675 &lt;device-id&gt; is the numerical ID of the new device, but
1676 there are noteworthy issue(s) related, providing an
1677 appropriate warning code and warning message</t>
1678 </list>
1679 </t>
1680 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1681 <list>
1682 <t>in case it failed, providing an appropriate error code and error message</t>
1683 </list>
1684 </t>
1685 </list>
1686 </t>
1687 <t>Example:</t>
1688 <t>
1689 <list>
1690 <t>C: "CREATE MIDI_INPUT_DEVICE ALSA"</t>
1691 <t>S: "OK[0]"</t>
1692 </list>
1693 </t>
1694 </section>
1695
1696 <section title="Destroying a MIDI input device" anchor="DESTROY MIDI_INPUT_DEVICE" lscp_cmd="true">
1697 <t>Use the following command to destroy a created MIDI input device:</t>
1698 <t>
1699 <list>
1700 <t>DESTROY MIDI_INPUT_DEVICE &lt;device-id&gt;</t>
1701 </list>
1702 </t>
1703 <t>Where &lt;device-id&gt; should be replaced by the device's numerical ID as returned by the
1704 <xref target="CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</xref>
1705 or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
1706 command.</t>
1707 <t>Possible Answers:</t>
1708 <t>
1709 <list>
1710 <t>"OK" -
1711 <list>
1712 <t>in case the device was successfully destroyed</t>
1713 </list>
1714 </t>
1715 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1716 <list>
1717 <t>in case the device was destroyed, but there are noteworthy
1718 issue(s) related, providing an appropriate warning code and
1719 warning message</t>
1720 </list>
1721 </t>
1722 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1723 <list>
1724 <t>in case it failed, providing an appropriate error code and error message</t>
1725 </list>
1726 </t>
1727 </list>
1728 </t>
1729 <t>Example:</t>
1730 <t>
1731 <list>
1732 <t>C: "DESTROY MIDI_INPUT_DEVICE 0"</t>
1733 <t>S: "OK"</t>
1734 </list>
1735 </t>
1736 </section>
1737
1738 <section title="Getting all created MIDI input device count" anchor="GET MIDI_INPUT_DEVICES" lscp_cmd="true">
1739 <t>Use the following command to count all created MIDI input devices:</t>
1740 <t>
1741 <list>
1742 <t>GET MIDI_INPUT_DEVICES</t>
1743 </list>
1744 </t>
1745 <t>Possible Answers:</t>
1746 <t>
1747 <list>
1748 <t>LinuxSampler will answer by sending the current number of all
1749 MIDI input devices.</t>
1750 </list>
1751 </t>
1752 <t>Example:</t>
1753 <t>
1754 <list>
1755 <t>C: "GET MIDI_INPUT_DEVICES"</t>
1756 <t>S: "3"</t>
1757 </list>
1758 </t>
1759 </section>
1760
1761
1762 <section title="Getting all created MIDI input device list" anchor="LIST MIDI_INPUT_DEVICES" lscp_cmd="true">
1763 <t>Use the following command to list all created MIDI input devices:</t>
1764 <t>
1765 <list>
1766 <t>LIST MIDI_INPUT_DEVICES</t>
1767 </list>
1768 </t>
1769 <t>Possible Answers:</t>
1770 <t>
1771 <list>
1772 <t>LinuxSampler will answer by sending a comma separated list
1773 with the numerical Ids of all created MIDI input devices.</t>
1774 </list>
1775 </t>
1776 <t>Examples:</t>
1777 <t>
1778 <list>
1779 <t>C: "LIST MIDI_INPUT_DEVICES"</t>
1780 <t>S: "0,1,2"</t>
1781 </list>
1782 </t>
1783 <t>
1784 <list>
1785 <t>C: "LIST MIDI_INPUT_DEVICES"</t>
1786 <t>S: "1,3"</t>
1787 </list>
1788 </t>
1789 </section>
1790
1791 <section title="Getting current settings of a MIDI input device" anchor="GET MIDI_INPUT_DEVICE INFO" lscp_cmd="true">
1792 <t>Use the following command to get current settings of a specific, created MIDI input device:</t>
1793 <t>
1794 <list>
1795 <t>GET MIDI_INPUT_DEVICE INFO &lt;device-id&gt;</t>
1796 </list>
1797 </t>
1798 <t>Where &lt;device-id&gt; is the numerical ID of the MIDI input device as returned by the
1799 <xref target="CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</xref>
1800 or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
1801 command.</t>
1802 <t>Possible Answers:</t>
1803 <t>
1804 <list>
1805 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1806 Each answer line begins with the information category name
1807 followed by a colon and then a space character &lt;SP&gt; and finally
1808 the info character string to that info category. As some
1809 parameters might allow multiple values, character strings are
1810 encapsulated into apostrophes ('). At the moment the following
1811 information categories are defined (independent of driver):</t>
1812
1813 <t>
1814 <list>
1815 <t>DRIVER -
1816 <list>
1817 <t>identifier of the used MIDI input driver, as e.g.
1818 returned by the <xref target="LIST AVAILABLE_MIDI_INPUT_DRIVERS">
1819 "LIST AVAILABLE_MIDI_INPUT_DRIVERS"</xref>
1820 command</t>
1821 </list>
1822 </t>
1823 </list>
1824 <list>
1825 <t>ACTIVE -
1826 <list>
1827 <t>either true or false, if false then the MIDI device is
1828 inactive and doesn't listen to any incoming MIDI events
1829 and thus doesn't forward them to connected sampler
1830 channels</t>
1831 </list>
1832 </t>
1833 </list>
1834 </t>
1835 </list>
1836 </t>
1837
1838 <t>The mentioned fields above don't have to be in particular
1839 order. The fields above are only those fields which are
1840 returned by all MIDI input devices. Every MIDI input driver
1841 might have its own, additional driver specific parameters (see
1842 <xref target="GET MIDI_INPUT_DRIVER INFO">
1843 "GET MIDI_INPUT_DRIVER INFO"</xref> command) which are also returned
1844 by this command.</t>
1845
1846 <t>Example:</t>
1847 <t>
1848 <list>
1849 <t>C: "GET MIDI_INPUT_DEVICE INFO 0"</t>
1850 <t>S: "DRIVER: ALSA"</t>
1851 <t>&nbsp;&nbsp;&nbsp;"ACTIVE: true"</t>
1852 <t>&nbsp;&nbsp;&nbsp;"."</t>
1853 </list>
1854 </t>
1855 </section>
1856
1857 <section title="Changing settings of MIDI input devices" anchor="SET MIDI_INPUT_DEVICE_PARAMETER" lscp_cmd="true">
1858 <t>Use the following command to alter a specific setting of a created MIDI input device:</t>
1859 <t>
1860 <list>
1861 <t>SET MIDI_INPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;</t>
1862 </list>
1863 </t>
1864
1865 <t>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1866 MIDI input device as returned by the
1867 <xref target="CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</xref>
1868 or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
1869 command, &lt;key&gt; by the name of the parameter to change and
1870 &lt;value&gt; by the new value for this parameter.</t>
1871
1872 <t>Possible Answers:</t>
1873 <t>
1874 <list>
1875 <t>"OK" -
1876 <list>
1877 <t>in case setting was successfully changed</t>
1878 </list>
1879 </t>
1880 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1881 <list>
1882 <t>in case setting was changed successfully, but there are
1883 noteworthy issue(s) related, providing an appropriate
1884 warning code and warning message</t>
1885 </list>
1886 </t>
1887 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1888 <list>
1889 <t>in case it failed, providing an appropriate error code and error message</t>
1890 </list>
1891 </t>
1892 </list>
1893 </t>
1894 <t>Example:</t>
1895 <t>
1896 <list>
1897 <t>C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"</t>
1898 <t>S: "OK"</t>
1899 </list>
1900 </t>
1901 </section>
1902
1903 <section title="Getting information about a MIDI port" anchor="GET MIDI_INPUT_PORT INFO" lscp_cmd="true">
1904 <t>Use the following command to get information about a MIDI port:</t>
1905 <t>
1906 <list>
1907 <t>GET MIDI_INPUT_PORT INFO &lt;device-id&gt; &lt;midi-port&gt;</t>
1908 </list>
1909 </t>
1910 <t>Where &lt;device-id&gt; is the numerical ID of the MIDI input device as returned by the
1911 <xref target="CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</xref>
1912 or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
1913 command and &lt;midi-port&gt; the MIDI input port number.</t>
1914 <t>Possible Answers:</t>
1915 <t>
1916 <list>
1917 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1918 Each answer line begins with the information category name
1919 followed by a colon and then a space character &lt;SP&gt; and finally
1920 the info character string to that info category. At the moment
1921 the following information categories are defined:</t>
1922
1923 <t>NAME -
1924 <list>
1925 <t>arbitrary character string naming the port</t>
1926 </list>
1927 </t>
1928 </list>
1929 </t>
1930
1931 <t>The field above is only the one which is returned by all MIDI
1932 ports regardless of the MIDI driver and port. Every MIDI port
1933 might have its own, additional driver and port specific
1934 parameters.</t>
1935
1936 <t>Example:</t>
1937 <t>
1938 <list>
1939 <t>C: "GET MIDI_INPUT_PORT INFO 0 0"</t>
1940 <t>S: "NAME: 'Masterkeyboard'"</t>
1941 <t>&nbsp;&nbsp;&nbsp;"ALSA_SEQ_BINDINGS: '64:0'"</t>
1942 <t>&nbsp;&nbsp;&nbsp;"."</t>
1943 </list>
1944 </t>
1945 </section>
1946
1947 <section title="Getting information about specific MIDI port parameter" anchor="GET MIDI_INPUT_PORT_PARAMETER INFO" lscp_cmd="true">
1948 <t>Use the following command to get detailed information about specific MIDI port parameter:</t>
1949 <t>
1950 <list>
1951 <t>GET MIDI_INPUT_PORT_PARAMETER INFO &lt;dev-id&gt; &lt;port&gt; &lt;param&gt;</t>
1952 </list>
1953 </t>
1954
1955 <t>Where &lt;dev-id&gt; is the numerical ID of the MIDI input device as returned by the
1956 <xref target="CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</xref>
1957 or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
1958 command, &lt;port&gt; the MIDI port number and
1959 &lt;param&gt; a specific port parameter name for which information should be
1960 obtained (as returned by the <xref target="GET MIDI_INPUT_PORT INFO">
1961 "GET MIDI_INPUT_PORT INFO"</xref> command).</t>
1962
1963 <t>Possible Answers:</t>
1964 <t>
1965 <list>
1966 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1967 Each answer line begins with the information category name
1968 followed by a colon and then a space character &lt;SP&gt; and finally
1969 the info character string to that info category. There is
1970 information which is always returned, independently of the
1971 given channel parameter and there is optional information
1972 which are only shown dependently to the given MIDI port. At the
1973 moment the following information categories are defined:</t>
1974
1975 <t>TYPE -
1976 <list>
1977 <t>either "BOOL" for boolean value(s) or "INT" for integer
1978 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1979 character string(s)
1980 (always returned)</t>
1981 </list>
1982 </t>
1983 <t>DESCRIPTION -
1984 <list>
1985 <t>arbitrary text describing the purpose of the parameter
1986 (always returned)</t>
1987 </list>
1988 </t>
1989 <t>FIX -
1990 <list>
1991 <t>either true or false, if true then this parameter is
1992 read only, thus cannot be altered
1993 (always returned)</t>
1994 </list>
1995 </t>
1996 <t>MULTIPLICITY -
1997 <list>
1998 <t>either true or false, defines if this parameter allows
1999 only one value or a list of values, where true means
2000 multiple values and false only a single value allowed
2001 (always returned)</t>
2002 </list>
2003 </t>
2004 <t>RANGE_MIN -
2005 <list>
2006 <t>defines lower limit of the allowed value range for this
2007 parameter, can be an integer value as well as a dotted
2008 number, this parameter is usually used in conjunction
2009 with 'RANGE_MAX' but may also appear without
2010 (optionally returned, dependent to driver and port
2011 parameter)</t>
2012 </list>
2013 </t>
2014 <t>RANGE_MAX -
2015 <list>
2016 <t>defines upper limit of the allowed value range for this
2017 parameter, can be an integer value as well as a dotted
2018 number, this parameter is usually used in conjunction
2019 with 'RANGE_MIN' but may also appear without
2020 (optionally returned, dependent to driver and port
2021 parameter)</t>
2022 </list>
2023 </t>
2024 <t>POSSIBILITIES -
2025 <list>
2026 <t>comma separated list of possible values for this
2027 parameter, character strings are encapsulated into
2028 apostrophes
2029 (optionally returned, dependent to device and port
2030 parameter)</t>
2031 </list>
2032 </t>
2033 </list>
2034 </t>
2035
2036 <t>The mentioned fields above don't have to be in particular order.</t>
2037
2038 <t>Example:</t>
2039 <t>
2040 <list>
2041 <t>C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"</t>
2042 <t>S: "DESCRIPTION: bindings to other ALSA sequencer clients"</t>
2043 <t>&nbsp;&nbsp;&nbsp;"TYPE: STRING"</t>
2044 <t>&nbsp;&nbsp;&nbsp;"FIX: false"</t>
2045 <t>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"</t>
2046 <t>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: '64:0','68:0','68:1'"</t>
2047 <t>&nbsp;&nbsp;&nbsp;"."</t>
2048 </list>
2049 </t>
2050 </section>
2051
2052 <section title="Changing settings of MIDI input ports" anchor="SET MIDI_INPUT_PORT_PARAMETER" lscp_cmd="true">
2053 <t>Use the following command to alter a specific setting of a MIDI input port:</t>
2054 <t>
2055 <list>
2056 <t>SET MIDI_INPUT_PORT_PARAMETER &lt;device-id&gt; &lt;port&gt; &lt;key&gt;=&lt;value&gt;</t>
2057 </list>
2058 </t>
2059
2060 <t>Where &lt;device-id&gt; should be replaced by the numerical ID of the
2061 MIDI device as returned by the
2062 <xref target="CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</xref>
2063 or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
2064 command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of
2065 the parameter to change and &lt;value&gt; by the new value for this
2066 parameter (encapsulated into apostrophes) or NONE (not encapsulated into apostrophes)
2067 for specifying no value for parameters allowing a list of values.</t>
2068
2069 <t>Possible Answers:</t>
2070 <t>
2071 <list>
2072 <t>"OK" -
2073 <list>
2074 <t>in case setting was successfully changed</t>
2075 </list>
2076 </t>
2077 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2078 <list>
2079 <t>in case setting was changed successfully, but there are
2080 noteworthy issue(s) related, providing an appropriate
2081 warning code and warning message</t>
2082 </list>
2083 </t>
2084 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2085 <list>
2086 <t>in case it failed, providing an appropriate error code and error message</t>
2087 </list>
2088 </t>
2089 </list>
2090 </t>
2091 <t>Example:</t>
2092 <t>
2093 <list>
2094 <t>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='20:0'"</t>
2095 <t>S: "OK"</t>
2096 </list>
2097 </t>
2098 <t>
2099 <list>
2100 <t>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE"</t>
2101 <t>S: "OK"</t>
2102 </list>
2103 </t>
2104 </section>
2105 </section>
2106
2107 <section title="Configuring sampler channels">
2108 <t>The following commands describe how to add and remove sampler channels, associate a
2109 sampler channel with a sampler engine, load instruments and connect sampler channels to
2110 MIDI and audio devices.</t>
2111
2112 <section title="Loading an instrument" anchor="LOAD INSTRUMENT" lscp_cmd="true">
2113 <t>An instrument file can be loaded and assigned to a sampler channel by one of the following commands:</t>
2114 <t>
2115 <list>
2116 <t>LOAD INSTRUMENT [NON_MODAL] '&lt;filename&gt;' &lt;instr-index&gt; &lt;sampler-channel&gt;</t>
2117 </list>
2118 </t>
2119
2120 <t>Where &lt;filename&gt; is the name of the instrument file on the
2121 LinuxSampler instance's host system, &lt;instr-index&gt; the index of the
2122 instrument in the instrument file and &lt;sampler-channel> is the
2123 number of the sampler channel the instrument should be assigned to.
2124 Each sampler channel can only have one instrument.</t>
2125
2126 <t>Notice: since LSCP 1.2 the &lt;filename&gt; argument supports
2127 escape characters for special characters (see chapter
2128 "<xref target="character_set">Character Set and Escape Sequences</xref>"
2129 for details) and accordingly backslash characters in the filename
2130 MUST now be escaped as well!</t>
2131
2132 <t>The difference between regular and NON_MODAL versions of the command
2133 is that the regular command returns OK only after the instrument has been
2134 fully loaded and the channel is ready to be used while NON_MODAL version
2135 returns immediately and a background process is launched to load the instrument
2136 on the channel. The <xref target="GET CHANNEL INFO">GET CHANNEL INFO</xref>
2137 command can be used to obtain loading
2138 progress from INSTRUMENT_STATUS field. LOAD command will perform sanity checks
2139 such as making sure that the file could be read and it is of a proper format
2140 and SHOULD return ERR and SHOULD not launch the background process should any
2141 errors be detected at that point.</t>
2142
2143 <t>Possible Answers:</t>
2144 <t>
2145 <list>
2146 <t>"OK" -
2147 <list>
2148 <t>in case the instrument was successfully loaded</t>
2149 </list>
2150 </t>
2151 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2152 <list>
2153 <t>in case the instrument was loaded successfully, but there
2154 are noteworthy issue(s) related (e.g. Engine doesn't support
2155 one or more patch parameters provided by the loaded
2156 instrument file), providing an appropriate warning code and
2157 warning message</t>
2158 </list>
2159 </t>
2160 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2161 <list>
2162 <t>in case it failed, providing an appropriate error code and error message</t>
2163 </list>
2164 </t>
2165 </list>
2166 </t>
2167 <t>Example (Unix):</t>
2168 <t>
2169 <list>
2170 <t>C: LOAD INSTRUMENT '/home/joe/gigs/cello.gig' 0 0</t>
2171 <t>S: OK</t>
2172 </list>
2173 </t>
2174 <t>Example (Windows):</t>
2175 <t>
2176 <list>
2177 <t>C: LOAD INSTRUMENT 'D:/MySounds/cello.gig' 0 0</t>
2178 <t>S: OK</t>
2179 </list>
2180 </t>
2181 </section>
2182
2183 <section title="Loading a sampler engine" anchor="LOAD ENGINE">
2184 <t>A sampler engine type can be associated to a specific sampler
2185 channel by the following command:</t>
2186 <t>
2187 <list>
2188 <t>LOAD ENGINE &lt;engine-name&gt; &lt;sampler-channel&gt;</t>
2189 </list>
2190 </t>
2191
2192 <t>Where &lt;engine-name&gt; is an engine name as obtained by the
2193 <xref target="LIST AVAILABLE_ENGINES">
2194 "LIST AVAILABLE_ENGINES"</xref> command and &lt;sampler-channel&gt;
2195 the sampler channel as returned by the
2196 <xref target="ADD CHANNEL">"ADD CHANNEL"</xref> or
2197 <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command where
2198 the engine type should be assigned to. This command should be issued
2199 after adding a new sampler channel and before any other control
2200 commands on the new sampler channel. It can also be used to change
2201 the engine type of a sampler channel. This command has (currently) no
2202 way to define or force if a new engine instance should be created and
2203 assigned to the given sampler channel or if an already existing
2204 instance of that engine type, shared with other sampler channels,
2205 should be used.</t>
2206
2207 <t>Possible Answers:</t>
2208 <t>
2209 <list>
2210 <t>"OK" -
2211 <list>
2212 <t>in case the engine was successfully deployed</t>
2213 </list>
2214 </t>
2215 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2216 <list>
2217 <t>in case the engine was deployed successfully, but there
2218 are noteworthy issue(s) related, providing an appropriate
2219 warning code and warning message</t>
2220 </list>
2221 </t>
2222 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2223 <list>
2224 <t>in case it failed, providing an appropriate error code and
2225 error message</t>
2226 </list>
2227 </t>
2228 </list>
2229 </t>
2230 <t>Example:</t>
2231 <t>
2232 <list>
2233 <t></t>
2234 </list>
2235 </t>
2236 </section>
2237
2238 <section title="Getting all created sampler channel count" anchor="GET CHANNELS" lscp_cmd="true">
2239 <t>The number of sampler channels can change on runtime. To get the
2240 current amount of sampler channels, the front-end can send the
2241 following command:</t>
2242 <t>
2243 <list>
2244 <t>GET CHANNELS</t>
2245 </list>
2246 </t>
2247 <t>Possible Answers:</t>
2248 <t>
2249 <list>
2250 <t>LinuxSampler will answer by returning the current number of sampler channels.</t>
2251 </list>
2252 </t>
2253 <t>Example:</t>
2254 <t>
2255 <list>
2256 <t>C: "GET CHANNELS"</t>
2257 <t>S: "12"</t>
2258 </list>
2259 </t>
2260 </section>
2261
2262 <section title="Getting all created sampler channel list" anchor="LIST CHANNELS" lscp_cmd="true">
2263 <t>The number of sampler channels can change on runtime. To get the
2264 current list of sampler channels, the front-end can send the
2265 following command:</t>
2266 <t>
2267 <list>
2268 <t>LIST CHANNELS</t>
2269 </list>
2270 </t>
2271 <t>Possible Answers:</t>
2272 <t>
2273 <list>
2274 <t>LinuxSampler will answer by returning a comma separated list
2275 with all sampler channels numerical IDs.</t>
2276 </list>
2277 </t>
2278 <t>Example:</t>
2279 <t>
2280 <list>
2281 <t>C: "LIST CHANNELS"</t>
2282 <t>S: "0,1,2,3,4,5,6,9,10,11,15,20"</t>
2283 </list>
2284 </t>
2285 </section>
2286
2287 <section title="Adding a new sampler channel" anchor="ADD CHANNEL" lscp_cmd="true">
2288 <t>A new sampler channel can be added to the end of the sampler
2289 channel list by sending the following command:</t>
2290 <t>
2291 <list>
2292 <t>ADD CHANNEL</t>
2293 </list>
2294 </t>
2295 <t>This will increment the sampler channel count by one and the new
2296 sampler channel will be appended to the end of the sampler channel
2297 list. The front-end should send the respective, related commands
2298 right after to e.g. load an engine, load an instrument and setting
2299 input, output method and eventually other commands to initialize
2300 the new channel. The front-end should use the sampler channel
2301 returned by the answer of this command to perform the previously
2302 recommended commands, to avoid race conditions e.g. with other
2303 front-ends that might also have sent an "ADD CHANNEL" command.</t>
2304 <t>Possible Answers:</t>
2305 <t>
2306 <list>
2307 <t>"OK[&lt;sampler-channel&gt;]" -
2308 <list>
2309 <t>in case a new sampler channel could be added, where
2310 &lt;sampler-channel&gt; reflects the channel number of the new
2311 created sampler channel which should be used to set up
2312 the sampler channel by sending subsequent initialization
2313 commands</t>
2314 </list>
2315 </t>
2316 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2317 <list>
2318 <t>in case a new channel was added successfully, but there are
2319 noteworthy issue(s) related, providing an appropriate
2320 warning code and warning message</t>
2321 </list>
2322 </t>
2323 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2324 <list>
2325 <t>in case it failed, providing an appropriate error code and
2326 error message</t>
2327 </list>
2328 </t>
2329 </list>
2330 </t>
2331 <t>Example:</t>
2332 <t>
2333 <list>
2334 <t></t>
2335 </list>
2336 </t>
2337 </section>
2338
2339 <section title="Removing a sampler channel" anchor="REMOVE CHANNEL" lscp_cmd="true">
2340 <t>A sampler channel can be removed by sending the following command:</t>
2341 <t>
2342 <list>
2343 <t>REMOVE CHANNEL &lt;sampler-channel&gt;</t>
2344 </list>
2345 </t>
2346
2347 <t>Where &lt;sampler-channel&gt; should be replaced by the
2348 number of the sampler channel as given by the
2349 <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
2350 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref>
2351 command. The channel numbers of all subsequent sampler channels
2352 remain the same.</t>
2353
2354 <t>Possible Answers:</t>
2355 <t>
2356 <list>
2357 <t>"OK" -
2358 <list>
2359 <t>in case the given sampler channel could be removed</t>
2360 </list>
2361 </t>
2362 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2363 <list>
2364 <t>in case the given channel was removed, but there are
2365 noteworthy issue(s) related, providing an appropriate
2366 warning code and warning message</t>
2367 </list>
2368 </t>
2369 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2370 <list>
2371 <t>in case it failed, providing an appropriate error code and
2372 error message</t>
2373 </list>
2374 </t>
2375 </list>
2376 </t>
2377 <t>Example:</t>
2378 <t>
2379 <list>
2380 <t></t>
2381 </list>
2382 </t>
2383 </section>
2384
2385 <section title="Getting amount of available engines" anchor="GET AVAILABLE_ENGINES" lscp_cmd="true">
2386 <t>The front-end can ask for the number of available engines by sending the following command:</t>
2387 <t>
2388 <list>
2389 <t>GET AVAILABLE_ENGINES</t>
2390 </list>
2391 </t>
2392 <t>Possible Answers:</t>
2393 <t>
2394 <list>
2395 <t>LinuxSampler will answer by sending the number of available engines.</t>
2396 </list>
2397 </t>
2398 <t>Example:</t>
2399 <t>
2400 <list>
2401 <t>C: "GET AVAILABLE_ENGINES"</t>
2402 <t>S: "4"</t>
2403 </list>
2404 </t>
2405 </section>
2406
2407 <section title="Getting all available engines" anchor="LIST AVAILABLE_ENGINES" lscp_cmd="true">
2408 <t>The front-end can ask for a list of all available engines by sending the following command:</t>
2409 <t>
2410 <list>
2411 <t>LIST AVAILABLE_ENGINES</t>
2412 </list>
2413 </t>
2414 <t>Possible Answers:</t>
2415 <t>
2416 <list>
2417 <t>LinuxSampler will answer by sending a comma separated list
2418 of the engines' names encapsulated into apostrophes (').
2419 Engine names can consist of lower and upper cases,
2420 digits and underlines ("_" character).</t>
2421 </list>
2422 </t>
2423 <t>Example:</t>
2424 <t>
2425 <list>
2426 <t>C: "LIST AVAILABLE_ENGINES"</t>
2427 <t>S: "'gig','sfz','sf2'"</t>
2428 </list>
2429 </t>
2430 </section>
2431
2432 <section title="Getting information about an engine" anchor="GET ENGINE INFO" lscp_cmd="true">
2433 <t>The front-end can ask for information about a specific engine by
2434 sending the following command:</t>
2435 <t>
2436 <list>
2437 <t>GET ENGINE INFO &lt;engine-name&gt;</t>
2438 </list>
2439 </t>
2440 <t>Where &lt;engine-name&gt; is an engine name as obtained by the
2441 <xref target="LIST AVAILABLE_ENGINES">
2442 "LIST AVAILABLE_ENGINES"</xref> command.</t>
2443 <t>Possible Answers:</t>
2444 <t>
2445 <list>
2446 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2447 Each answer line begins with the information category name
2448 followed by a colon and then a space character &lt;SP&gt; and finally
2449 the info character string to that info category. At the moment
2450 the following categories are defined:</t>
2451
2452 <t>
2453 <list>
2454 <t>DESCRIPTION -
2455 <list>
2456 <t>arbitrary description text about the engine
2457 (note that the character string may contain
2458 <xref target="character_set">escape sequences</xref>)</t>
2459 </list>
2460 </t>
2461 <t>VERSION -
2462 <list>
2463 <t>arbitrary character string regarding the engine's version</t>
2464 </list>
2465 </t>
2466 </list>
2467 </t>
2468 </list>
2469 </t>
2470
2471 <t>The mentioned fields above don't have to be in particular order.</t>
2472
2473 <t>Examples:</t>
2474 <t>
2475 <list>
2476 <t>C: "GET ENGINE INFO gig"</t>
2477 <t>S: "DESCRIPTION: GigaSampler Format Engine"</t>
2478 <t>&nbsp;&nbsp;&nbsp;"VERSION: 1.110"</t>
2479 <t>&nbsp;&nbsp;&nbsp;"."</t>
2480 <t>C: "GET ENGINE INFO sf2"</t>
2481 <t>S: "DESCRIPTION: SoundFont Format Engine"</t>
2482 <t>&nbsp;&nbsp;&nbsp;"VERSION: 1.4"</t>
2483 <t>&nbsp;&nbsp;&nbsp;"."</t>
2484 <t>C: "GET ENGINE INFO sfz"</t>
2485 <t>S: "DESCRIPTION: SFZ Format Engine"</t>
2486 <t>&nbsp;&nbsp;&nbsp;"VERSION: 1.11"</t>
2487 <t>&nbsp;&nbsp;&nbsp;"."</t>
2488 </list>
2489 </t>
2490 </section>
2491
2492 <section title="Getting sampler channel information" anchor="GET CHANNEL INFO" lscp_cmd="true">
2493 <t>The front-end can ask for the current settings of a sampler channel
2494 by sending the following command:</t>
2495 <t>
2496 <list>
2497 <t>GET CHANNEL INFO &lt;sampler-channel&gt;</t>
2498 </list>
2499 </t>
2500 <t>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
2501 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
2502 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
2503 <t>Possible Answers:</t>
2504 <t>
2505 <list>
2506 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2507 Each answer line begins with the settings category name
2508 followed by a colon and then a space character &lt;SP&gt; and finally
2509 the info character string to that setting category. At the
2510 moment the following categories are defined:</t>
2511
2512 <t>
2513 <list>
2514 <t>ENGINE_NAME -
2515 <list>
2516 <t>name of the engine that is associated with the sampler
2517 channel, "NONE" if there's no engine associated yet for
2518 this sampler channel</t>
2519 </list>
2520 </t>
2521 <t>AUDIO_OUTPUT_DEVICE -
2522 <list>
2523 <t>numerical ID of the audio output device which is
2524 currently connected to this sampler channel to output
2525 the audio signal, "-1" if there's no device
2526 connected to this sampler channel</t>
2527 </list>
2528 </t>
2529 <t>AUDIO_OUTPUT_CHANNELS -
2530 <list>
2531 <t>number of output channels the sampler channel offers
2532 (dependent to used sampler engine and loaded instrument)</t>
2533 </list>
2534 </t>
2535 <t>AUDIO_OUTPUT_ROUTING -
2536 <list>
2537 <t>comma separated list which reflects to which audio
2538 channel of the selected audio output device each
2539 sampler output channel is routed to, e.g. "0,3" would
2540 mean the engine's output channel 0 is routed to channel
2541 0 of the audio output device and the engine's output
2542 channel 1 is routed to the channel 3 of the audio
2543 output device</t>
2544 </list>
2545 </t>
2546 <t>INSTRUMENT_FILE -
2547 <list>
2548 <t>the file name of the loaded instrument, "NONE" if
2549 there's no instrument yet loaded for this sampler
2550 channel (note: since LSCP 1.2 this path may contain
2551 <xref target="character_set">escape sequences</xref>)</t>
2552 </list>
2553 </t>
2554 <t>INSTRUMENT_NR -
2555 <list>
2556 <t>the instrument index number of the loaded instrument,
2557 "-1" if there's no instrument loaded for this sampler
2558 channel</t>
2559 </list>
2560 </t>
2561 <t>INSTRUMENT_NAME -
2562 <list>
2563 <t>the instrument name of the loaded instrument
2564 (note: since LSCP 1.2 this character string may contain
2565 <xref target="character_set">escape sequences</xref>)</t>
2566 </list>
2567 </t>
2568 <t>INSTRUMENT_STATUS -
2569 <list>
2570 <t>Integer values 0 to 100 indicating loading progress
2571 percentage for the instrument. Negative
2572 value indicates a loading exception (also returns "-1" in case no
2573 instrument was yet to be loaded on the sampler channel).
2574 Value of 100 indicates that the instrument is fully
2575 loaded.</t>
2576 </list>
2577 </t>
2578 <t>MIDI_INPUT_DEVICE -
2579 <list>
2580 <t>DEPRECATED: THIS FIELD WILL DISAPPEAR!</t>
2581 <t>numerical ID of the MIDI input device which is
2582 currently connected to this sampler channel to deliver
2583 MIDI input commands, "-1" if there's no device
2584 connected to this sampler channel</t>
2585 <t>Should not be used anymore as of LSCP v1.6 and younger.
2586 This field is currently only preserved for backward compatibility.
2587 </t>
2588 <t>This field a relict from times where only one MIDI input per
2589 sampler channel was allowed. Use <xref target="LIST CHANNEL MIDI_INPUTS">"GET CHANNEL MIDI_INPUTS"</xref>
2590 instead.</t>
2591 </list>
2592 </t>
2593 <t>MIDI_INPUT_PORT -
2594 <list>
2595 <t>DEPRECATED: THIS FIELD WILL DISAPPEAR!</t>
2596 <t>port number of the MIDI input device (in case a
2597 MIDI device was already assigned to the sampler
2598 channel)</t>
2599 <t>Should not be used anymore as of LSCP v1.6 and younger.
2600 This field is currently only preserved for backward compatibility.
2601 </t>
2602 <t>This field a relict from times where only one MIDI input per
2603 sampler channel was allowed. Use <xref target="LIST CHANNEL MIDI_INPUTS">"GET CHANNEL MIDI_INPUTS"</xref>
2604 instead.</t>
2605 </list>
2606 </t>
2607 <t>MIDI_INPUT_CHANNEL -
2608 <list>
2609 <t>the MIDI input channel number this sampler channel
2610 should listen to or "ALL" to listen on all MIDI channels</t>
2611 </list>
2612 </t>
2613 <t>VOLUME -
2614 <list>
2615 <t>optionally dotted number for the channel volume factor
2616 (where a value &lt; 1.0 means attenuation and a value >
2617 1.0 means amplification)</t>
2618 </list>
2619 </t>
2620 <t>MUTE -
2621 <list>
2622 <t>Determines whether the channel is muted, "true" if the
2623 channel is muted, "false" if the channel is not muted, and
2624 "MUTED_BY_SOLO" if the channel is muted because of the
2625 presence of a solo channel and will be unmuted when
2626 there are no solo channels left</t>
2627 </list>
2628 </t>
2629 <t>SOLO -
2630 <list>
2631 <t>Determines whether this is a solo channel, "true" if
2632 the channel is a solo channel; "false" otherwise</t>
2633 </list>
2634 </t>
2635 <t>MIDI_INSTRUMENT_MAP -
2636 <list>
2637 <t>Determines to which MIDI instrument map this sampler
2638 channel is assigned to. Read chapter
2639 <xref target="SET CHANNEL MIDI_INSTRUMENT_MAP">"SET CHANNEL MIDI_INSTRUMENT_MAP"</xref>
2640 for a list of possible values.</t>
2641 </list>
2642 </t>
2643 </list>
2644 </t>
2645 </list>
2646 </t>
2647 <t>The mentioned fields above don't have to be in particular order.</t>
2648
2649 <t>Example:</t>
2650 <t>
2651 <list>
2652 <t>C: "GET CHANNEL INFO 34"</t>
2653 <t>S: "ENGINE_NAME: gig"</t>
2654 <t>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"</t>
2655 <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_DEVICE: 0"</t>
2656 <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_CHANNELS: 2"</t>
2657 <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 0,1"</t>
2658 <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"</t>
2659 <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"</t>
2660 <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NAME: Fazioli Piano"</t>
2661 <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_STATUS: 100"</t>
2662 <t>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_DEVICE: 0"</t>
2663 <t>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_PORT: 0"</t>
2664 <t>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_CHANNEL: 5"</t>
2665 <t>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"</t>
2666 <t>&nbsp;&nbsp;&nbsp;"MUTE: false"</t>
2667 <t>&nbsp;&nbsp;&nbsp;"SOLO: false"</t>
2668 <t>&nbsp;&nbsp;&nbsp;"MIDI_INSTRUMENT_MAP: NONE"</t>
2669 <t>&nbsp;&nbsp;&nbsp;"."</t>
2670 </list>
2671 </t>
2672 </section>
2673
2674 <section title="Current number of active voices" anchor="GET CHANNEL VOICE_COUNT" lscp_cmd="true">
2675 <t>The front-end can ask for the current number of active voices on a
2676 sampler channel by sending the following command:</t>
2677 <t>
2678 <list>
2679 <t>GET CHANNEL VOICE_COUNT &lt;sampler-channel&gt;</t>
2680 </list>
2681 </t>
2682 <t>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
2683 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
2684 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
2685
2686 <t>Possible Answers:</t>
2687 <t>
2688 <list>
2689 <t>LinuxSampler will answer by returning the number of active
2690 voices on that channel.</t>
2691 </list>
2692 </t>
2693 <t>Example:</t>
2694 <t>
2695 <list>
2696 <t></t>
2697 </list>
2698 </t>
2699 </section>
2700
2701 <section title="Current number of active disk streams" anchor="GET CHANNEL STREAM_COUNT" lscp_cmd="true">
2702 <t>The front-end can ask for the current number of active disk streams
2703 on a sampler channel by sending the following command:</t>
2704 <t>
2705 <list>
2706 <t>GET CHANNEL STREAM_COUNT &lt;sampler-channel&gt;</t>
2707 </list>
2708 </t>
2709 <t>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
2710 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
2711 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
2712
2713 <t>Possible Answers:</t>
2714 <t>
2715 <list>
2716 <t>LinuxSampler will answer by returning the number of active
2717 disk streams on that channel in case the engine supports disk
2718 streaming, if the engine doesn't support disk streaming it will
2719 return "NA" for not available.</t>
2720 </list>
2721 </t>
2722 <t>Example:</t>
2723 <t>
2724 <list>
2725 <t></t>
2726 </list>
2727 </t>
2728 </section>
2729
2730 <section title="Current fill state of disk stream buffers" anchor="GET CHANNEL BUFFER_FILL" lscp_cmd="true">
2731 <t>The front-end can ask for the current fill state of all disk streams
2732 on a sampler channel by sending the following command:</t>
2733 <t>
2734 <list>
2735 <t>GET CHANNEL BUFFER_FILL BYTES &lt;sampler-channel&gt;</t>
2736 </list>
2737 </t>
2738 <t>to get the fill state in bytes or</t>
2739 <t>
2740 <list>
2741 <t>GET CHANNEL BUFFER_FILL PERCENTAGE &lt;sampler-channel&gt;</t>
2742 </list>
2743 </t>
2744 <t>to get the fill state in percent, where &lt;sampler-channel&gt; is the
2745 sampler channel number the front-end is interested in
2746 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
2747 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
2748
2749 <t>Possible Answers:</t>
2750 <t>
2751 <list>
2752 <t>LinuxSampler will either answer by returning a comma separated
2753 string with the fill state of all disk stream buffers on that
2754 channel or an empty line if there are no active disk streams or
2755 "NA" for *not available* in case the engine which is deployed
2756 doesn't support disk streaming. Each entry in the answer list
2757 will begin with the stream's ID in brackets followed by the
2758 numerical representation of the fill size (either in bytes or
2759 percentage). Note: due to efficiency reasons the fill states in
2760 the response are not in particular order, thus the front-end has
2761 to sort them by itself if necessary.</t>
2762 </list>
2763 </t>
2764 <t>Examples:</t>
2765 <t>
2766 <list>
2767 <t>C: "GET CHANNEL BUFFER_FILL BYTES 4"</t>
2768 <t>S: "[115]420500,[116]510300,[75]110000,[120]230700"</t>
2769 </list>
2770
2771 <list>
2772 <t>C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"</t>
2773 <t>S: "[115]90%,[116]98%,[75]40%,[120]62%"</t>
2774 </list>
2775
2776 <list>
2777 <t>C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"</t>
2778 <t>S: ""</t>
2779 </list>
2780 </t>
2781 </section>
2782
2783 <section title="Setting audio output device" anchor="SET CHANNEL AUDIO_OUTPUT_DEVICE" lscp_cmd="true">
2784 <t>The front-end can set the audio output device on a specific sampler
2785 channel by sending the following command:</t>
2786 <t>
2787 <list>
2788 <t>SET CHANNEL AUDIO_OUTPUT_DEVICE &lt;sampler-channel&gt; &lt;audio-device-id&gt;</t>
2789 </list>
2790 </t>
2791 <t>Where &lt;sampler-channel&gt; is the respective sampler channel
2792 number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
2793 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command and
2794 &lt;audio-device-id&gt; is the numerical ID of the audio output device as given by the
2795 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
2796 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
2797 command.</t>
2798
2799 <t>Possible Answers:</t>
2800 <t>
2801 <list>
2802 <t>"OK" -
2803 <list>
2804 <t>on success</t>
2805 </list>
2806 </t>
2807 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2808 <list>
2809 <t>if audio output device was set, but there are noteworthy
2810 issue(s) related, providing an appropriate warning code and
2811 warning message</t>
2812 </list>
2813 </t>
2814 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2815 <list>
2816 <t>in case it failed, providing an appropriate error code and error message</t>
2817 </list>
2818 </t>
2819 </list>
2820 </t>
2821 <t>Examples:</t>
2822 <t>
2823 <list>
2824 <t></t>
2825 </list>
2826 </t>
2827 </section>
2828
2829 <section title="Setting audio output type" anchor="SET CHANNEL AUDIO_OUTPUT_TYPE" lscp_cmd="true">
2830 <t>DEPRECATED: THIS COMMAND WILL DISAPPEAR!</t>
2831
2832 <t>The front-end can alter the audio output type on a specific sampler
2833 channel by sending the following command:</t>
2834 <t>
2835 <list>
2836 <t>SET CHANNEL AUDIO_OUTPUT_TYPE &lt;sampler-channel&gt; &lt;audio-output-type&gt;</t>
2837 </list>
2838 </t>
2839 <t>Where &lt;audio-output-type&gt; is currently either "ALSA" or "JACK" and
2840 &lt;sampler-channel&gt; is the respective sampler channel number.</t>
2841
2842 <t>Possible Answers:</t>
2843 <t>
2844 <list>
2845 <t>"OK" -
2846 <list>
2847 <t>on success</t>
2848 </list>
2849 </t>
2850 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2851 <list>
2852 <t>if audio output type was set, but there are noteworthy
2853 issue(s) related, providing an appropriate warning code and
2854 warning message</t>
2855 </list>
2856 </t>
2857 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2858 <list>
2859 <t>in case it failed, providing an appropriate error code and error message</t>
2860 </list>
2861 </t>
2862 </list>
2863 </t>
2864 <t>Examples:</t>
2865 <t>
2866 <list>
2867 <t></t>
2868 </list>
2869 </t>
2870 <t>Deprecated:</t>
2871 <t>
2872 <list>
2873 <t>Should not be used anymore. This command is currently only preserved for backward compatibility.</t>
2874 <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>
2875 </list>
2876 </t>
2877 </section>
2878
2879 <section title="Setting audio output channel" anchor="SET CHANNEL AUDIO_OUTPUT_CHANNEL" lscp_cmd="true">
2880 <t>The front-end can alter the audio output channel on a specific
2881 sampler channel by sending the following command:</t>
2882 <t>
2883 <list>
2884 <t>SET CHANNEL AUDIO_OUTPUT_CHANNEL &lt;sampler-chan&gt; &lt;audio-out&gt; &lt;audio-in&gt;</t>
2885 </list>
2886 </t>
2887 <t>Where &lt;sampler-chan&gt; is the sampler channel number
2888 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
2889 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command, &lt;audio-out&gt; is the
2890 numerical ID of the sampler channel's audio output channel which should be
2891 rerouted and &lt;audio-in&gt; is the numerical ID of the audio channel of the selected audio
2892 output device where &lt;audio-out&gt; should be routed to.</t>
2893
2894 <t>Possible Answers:</t>
2895 <t>
2896 <list>
2897 <t>"OK" -
2898 <list>
2899 <t>on success</t>
2900 </list>
2901 </t>
2902 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2903 <list>
2904 <t>if audio output channel was set, but there are noteworthy
2905 issue(s) related, providing an appropriate warning code and
2906 warning message</t>
2907 </list>
2908 </t>
2909 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2910 <list>
2911 <t>in case it failed, providing an appropriate error code and error message</t>
2912 </list>
2913 </t>
2914 </list>
2915 </t>
2916 <t>Examples:</t>
2917 <t>
2918 <list>
2919 <t></t>
2920 </list>
2921 </t>
2922 </section>
2923
2924 <section title="Add MIDI input to sampler channel" anchor="ADD CHANNEL MIDI_INPUT" lscp_cmd="true">
2925 <t>The front-end can add a MIDI input on a specific sampler
2926 channel by sending the following command:</t>
2927 <t>
2928 <list>
2929 <t>ADD CHANNEL MIDI_INPUT &lt;sampler-channel&gt; &lt;midi-device-id&gt; [&lt;midi-input-port&gt;]</t>
2930 </list>
2931 </t>
2932 <t>Where &lt;sampler-channel&gt; is the sampler channel number
2933 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
2934 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command
2935 and &lt;midi-device-id&gt; is the numerical ID of the MIDI input
2936 device as returned by the
2937 <xref target="CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</xref>
2938 or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref> command,
2939 and &lt;midi-input-port&gt; is an optional MIDI input port number of that
2940 MIDI input device. If &lt;midi-input-port&gt; is omitted,
2941 then the MIDI input device's first port (port number 0) is
2942 used.
2943 </t>
2944
2945 <t>Possible Answers:</t>
2946 <t>
2947 <list>
2948 <t>"OK" -
2949 <list>
2950 <t>on success</t>
2951 </list>
2952 </t>
2953 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2954 <list>
2955 <t>if MIDI input port was connected, but there are noteworthy
2956 issue(s) related, providing an appropriate warning code and
2957 warning message</t>
2958 </list>
2959 </t>
2960 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2961 <list>
2962 <t>in case it failed, providing an appropriate error code and error message</t>
2963 </list>
2964 </t>
2965 </list>
2966 </t>
2967 <t>Examples:</t>
2968 <t>
2969 <list>
2970 <t>C: "ADD CHANNEL MIDI_INPUT 0 0"</t>
2971 <t>S: "OK"</t>
2972 <t>C: "ADD CHANNEL MIDI_INPUT 1 0"</t>
2973 <t>S: "OK"</t>
2974 <t>C: "ADD CHANNEL MIDI_INPUT 1 1 1"</t>
2975 <t>S: "OK"</t>
2976 <t>C: "ADD CHANNEL MIDI_INPUT 1 2 0"</t>
2977 <t>S: "OK"</t>
2978 </list>
2979 </t>
2980 <t>Since:</t>
2981 <t>
2982 <list>
2983 <t>Introduced with LSCP v1.6</t>
2984 </list>
2985 </t>
2986 </section>
2987
2988 <section title="Remove MIDI input(s) from sampler channel" anchor="REMOVE CHANNEL MIDI_INPUT" lscp_cmd="true">
2989 <t>The front-end can remove one ore more MIDI input(s) on a
2990 specific sampler channel by sending the following command:</t>
2991 <t>
2992 <list>
2993 <t>REMOVE CHANNEL MIDI_INPUT &lt;sampler-channel&gt; [&lt;midi-device-id&gt; [&lt;midi-input-port&gt;]]</t>
2994 </list>
2995 </t>
2996 <t>Where &lt;sampler-channel&gt; is the sampler channel number
2997 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
2998 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command
2999 and &lt;midi-device-id&gt; and &lt;midi-input-port&gt; are
3000 optional numerical IDs defining the MIDI input device and
3001 one of its MIDI ports as returned by the
3002 <xref target="LIST CHANNEL MIDI_INPUTS">"LIST CHANNEL MIDI_INPUTS"</xref> command.
3003 </t>
3004
3005 <t>
3006 If &lt;midi-input-port&gt; is omitted, then all MIDI input
3007 ports of &lt;midi-device-id&gt; are disconnected from this
3008 sampler channel.
3009 </t>
3010
3011 <t>
3012 If both, &lt;midi-device-id&gt; and &lt;midi-input-port&gt;
3013 are omitted, then all MIDI input ports currently connected
3014 to this sampler channel are disconnected from this sampler
3015 channel.
3016 </t>
3017
3018 <t>Possible Answers:</t>
3019 <t>
3020 <list>
3021 <t>"OK" -
3022 <list>
3023 <t>on success</t>
3024 </list>
3025 </t>
3026 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3027 <list>
3028 <t>if MIDI input porst were disconnected, but there are noteworthy
3029 issue(s) related, providing an appropriate warning code and
3030 warning message</t>
3031 </list>
3032 </t>
3033 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3034 <list>
3035 <t>in case it failed, providing an appropriate error code and error message</t>
3036 </list>
3037 </t>
3038 </list>
3039 </t>
3040 <t>Examples:</t>
3041 <t>
3042 <list>
3043 <t>C: "REMOVE CHANNEL MIDI_INPUT 0"</t>
3044 <t>S: "OK"</t>
3045 <t>C: "REMOVE CHANNEL MIDI_INPUT 1"</t>
3046 <t>S: "OK"</t>
3047 <t>C: "REMOVE CHANNEL MIDI_INPUT 1 2 0"</t>
3048 <t>S: "OK"</t>
3049 </list>
3050 </t>
3051 <t>Since:</t>
3052 <t>
3053 <list>
3054 <t>Introduced with LSCP v1.6</t>
3055 </list>
3056 </t>
3057 </section>
3058
3059 <section title="Getting all MIDI inputs of a sampler channel" anchor="LIST CHANNEL MIDI_INPUTS" lscp_cmd="true">
3060 <t>The front-end can query a list of all currently connected
3061 MIDI inputs of a certain sampler channel by sending the following
3062 command:</t>
3063 <t>
3064 <list>
3065 <t>LIST CHANNEL MIDI_INPUTS &lt;sampler-channel&gt;</t>
3066 </list>
3067 </t>
3068 <t>Where &lt;sampler-channel&gt; is the sampler channel number
3069 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3070 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.
3071 </t>
3072
3073 <t>Possible Answers:</t>
3074 <t>
3075 <list>
3076 <t>The sampler will answer by sending a comma separated
3077 list of MIDI input device ID - MIDI input port number pairs, where
3078 each pair is encapsulated into curly braces. The
3079 list is returned in one single line. The MIDI input
3080 device ID corresponds to the number returned by
3081 <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
3082 and the port number is the index of the respective MIDI
3083 port of that MIDI input device.</t>
3084 </list>
3085 </t>
3086
3087 <t>Example:</t>
3088 <t>
3089 <list>
3090 <t>C: "LIST CHANNEL MIDI_INPUTS 0"</t>
3091 <t>S: "{0,0},{1,3},{2,0}"</t>
3092 </list>
3093 </t>
3094
3095 <t>Since:</t>
3096 <t>
3097 <list>
3098 <t>Introduced with LSCP v1.6</t>
3099 </list>
3100 </t>
3101 </section>
3102
3103 <section title="Setting MIDI input device" anchor="SET CHANNEL MIDI_INPUT_DEVICE" lscp_cmd="true">
3104 <t>DEPRECATED: THIS COMMAND WILL DISAPPEAR!</t>
3105
3106 <t>The front-end can set the MIDI input device on a specific sampler
3107 channel by sending the following command:</t>
3108 <t>
3109 <list>
3110 <t>SET CHANNEL MIDI_INPUT_DEVICE &lt;sampler-channel&gt; &lt;midi-device-id&gt;</t>
3111 </list>
3112 </t>
3113 <t>Where &lt;sampler-channel&gt; is the sampler channel number
3114 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3115 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command
3116 and &lt;midi-device-id&gt; is the numerical ID of the MIDI input device as returned by the
3117 <xref target="CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</xref>
3118 or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref> command.</t>
3119
3120 <t>
3121 If more than 1 MIDI inputs are currently connected to this
3122 sampler channel: Sending this command will disconnect ALL
3123 currently connected MIDI input ports connected to this
3124 sampler channel before establishing the new MIDI input
3125 connection. So this command does NOT add the connection,
3126 it replaces all existing ones instead. This behavior is due
3127 to preserving full behavior backward compatibility.
3128 </t>
3129
3130 <t>Possible Answers:</t>
3131 <t>
3132 <list>
3133 <t>"OK" -
3134 <list>
3135 <t>on success</t>
3136 </list>
3137 </t>
3138 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3139 <list>
3140 <t>if MIDI input device was set, but there are noteworthy
3141 issue(s) related, providing an appropriate warning code and
3142 warning message</t>
3143 </list>
3144 </t>
3145 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3146 <list>
3147 <t>in case it failed, providing an appropriate error code and error message</t>
3148 </list>
3149 </t>
3150 </list>
3151 </t>
3152 <t>Examples:</t>
3153 <t>
3154 <list>
3155 <t></t>
3156 </list>
3157 </t>
3158 <t>Deprecated:</t>
3159 <t>
3160 <list>
3161 <t>Should not be used anymore as of LSCP v1.6 and younger. This command is currently only preserved for backward compatibility.</t>
3162 <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>
3163 </list>
3164 </t>
3165 </section>
3166
3167 <section title="Setting MIDI input type" anchor="SET CHANNEL MIDI_INPUT_TYPE" lscp_cmd="true">
3168 <t>DEPRECATED: THIS COMMAND WILL DISAPPEAR!</t>
3169
3170 <t>The front-end can alter the MIDI input type on a specific sampler
3171 channel by sending the following command:</t>
3172 <t>
3173 <list>
3174 <t>SET CHANNEL MIDI_INPUT_TYPE &lt;sampler-channel&gt; &lt;midi-input-type&gt;</t>
3175 </list>
3176 </t>
3177 <t>Where &lt;midi-input-type&gt; is currently only "ALSA" and
3178 &lt;sampler-channel&gt; is the respective sampler channel number.</t>
3179
3180 <t>
3181 If more than 1 MIDI inputs are currently connected to this
3182 sampler channel: Sending this command will disconnect ALL
3183 currently connected MIDI input ports connected to this
3184 sampler channel before establishing the new MIDI input
3185 connection. So this command does NOT add the connection,
3186 it replaces all existing ones instead. This behavior is due
3187 to preserving full behavior backward compatibility.
3188 </t>
3189
3190 <t>Possible Answers:</t>
3191 <t>
3192 <list>
3193 <t>"OK" -
3194 <list>
3195 <t>on success</t>
3196 </list>
3197 </t>
3198 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3199 <list>
3200 <t>if MIDI input type was set, but there are noteworthy
3201 issue(s) related, providing an appropriate warning code and
3202 warning message</t>
3203 </list>
3204 </t>
3205 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3206 <list>
3207 <t>in case it failed, providing an appropriate error code and error message</t>
3208 </list>
3209 </t>
3210 </list>
3211 </t>
3212 <t>Examples:</t>
3213 <t>
3214 <list>
3215 <t></t>
3216 </list>
3217 </t>
3218 <t>Deprecated:</t>
3219 <t>
3220 <list>
3221 <t>Should not be used anymore. This command is currently only preserved for backward compatibility.</t>
3222 <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>
3223 </list>
3224 </t>
3225 </section>
3226
3227 <section title="Setting MIDI input port" anchor="SET CHANNEL MIDI_INPUT_PORT" lscp_cmd="true">
3228 <t>DEPRECATED: THIS COMMAND WILL DISAPPEAR!</t>
3229
3230 <t>The front-end can alter the MIDI input port on a specific sampler
3231 channel by sending the following command:</t>
3232 <t>
3233 <list>
3234 <t>SET CHANNEL MIDI_INPUT_PORT &lt;sampler-channel&gt; &lt;midi-input-port&gt;</t>
3235 </list>
3236 </t>
3237 <t>Where &lt;midi-input-port&gt; is a MIDI input port number of the
3238 MIDI input device connected to the sampler channel given by
3239 &lt;sampler-channel&gt;.</t>
3240
3241 <t>
3242 If more than 1 MIDI inputs are currently connected to this
3243 sampler channel: Sending this command will switch the
3244 connection of the first (and only the first) MIDI input port
3245 currently being connected to this sampler channel, to
3246 another port of the same MIDI input device. Or in other
3247 words: the first MIDI input port currently connected to
3248 this sampler channel will be disconnected, and the requested
3249 other port of its MIDI input device will be connected to
3250 this sampler channel instead. This behavior is due
3251 to preserving full behavior backward compatibility.
3252 </t>
3253
3254 <t>Possible Answers:</t>
3255 <t>
3256 <list>
3257 <t>"OK" -
3258 <list>
3259 <t>on success</t>
3260 </list>
3261 </t>
3262 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3263 <list>
3264 <t>if MIDI input port was set, but there are noteworthy
3265 issue(s) related, providing an appropriate warning code and
3266 warning message</t>
3267 </list>
3268 </t>
3269 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3270 <list>
3271 <t>in case it failed, providing an appropriate error code and error message</t>
3272 </list>
3273 </t>
3274 </list>
3275 </t>
3276 <t>Examples:</t>
3277 <t>
3278 <list>
3279 <t></t>
3280 </list>
3281 </t>
3282 <t>Deprecated:</t>
3283 <t>
3284 <list>
3285 <t>Should not be used anymore. This command is currently only preserved for backward compatibility.</t>
3286 <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>
3287 </list>
3288 </t>
3289 </section>
3290
3291 <section title="Setting MIDI input channel" anchor="SET CHANNEL MIDI_INPUT_CHANNEL" lscp_cmd="true">
3292 <t>The front-end can alter the MIDI channel a sampler channel should
3293 listen to by sending the following command:</t>
3294 <t>
3295 <list>
3296 <t>SET CHANNEL MIDI_INPUT_CHANNEL &lt;sampler-channel&gt; &lt;midi-input-chan&gt;</t>
3297 </list>
3298 </t>
3299 <t>Where &lt;midi-input-chan&gt; is the number
3300 of the new MIDI input channel (zero indexed!) where
3301 &lt;sampler-channel&gt; should listen to, or "ALL" to listen on all 16 MIDI
3302 channels.</t>
3303
3304 <t>Possible Answers:</t>
3305 <t>
3306 <list>
3307 <t>"OK" -
3308 <list>
3309 <t>on success</t>
3310 </list>
3311 </t>
3312 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3313 <list>
3314 <t>if MIDI input channel was set, but there are noteworthy
3315 issue(s) related, providing an appropriate warning code and
3316 warning message</t>
3317 </list>
3318 </t>
3319 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3320 <list>
3321 <t>in case it failed, providing an appropriate error code and error message</t>
3322 </list>
3323 </t>
3324 </list>
3325 </t>
3326 <t>Examples:</t>
3327 <t>
3328 <list>
3329 <t>C: "SET CHANNEL MIDI_INPUT_CHANNEL 0 0"</t>
3330 <t>S: "OK"</t>
3331 <t>C: "SET CHANNEL MIDI_INPUT_CHANNEL 1 ALL"</t>
3332 <t>S: "OK"</t>
3333 </list>
3334 </t>
3335 </section>
3336
3337 <section title="Setting channel volume" anchor="SET CHANNEL VOLUME" lscp_cmd="true">
3338 <t>The front-end can alter the volume of a sampler channel by sending
3339 the following command:</t>
3340 <t>
3341 <list>
3342 <t>SET CHANNEL VOLUME &lt;sampler-channel&gt; &lt;volume&gt;</t>
3343 </list>
3344 </t>
3345 <t>Where &lt;volume&gt; is an optionally dotted positive number (a value
3346 smaller than 1.0 means attenuation, whereas a value greater than
3347 1.0 means amplification) and &lt;sampler-channel&gt; defines the sampler
3348 channel where this volume factor should be set.</t>
3349
3350 <t>Possible Answers:</t>
3351 <t>
3352 <list>
3353 <t>"OK" -
3354 <list>
3355 <t>on success</t>
3356 </list>
3357 </t>
3358 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3359 <list>
3360 <t>if channel volume was set, but there are noteworthy
3361 issue(s) related, providing an appropriate warning code and
3362 warning message</t>
3363 </list>
3364 </t>
3365 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3366 <list>
3367 <t>in case it failed, providing an appropriate error code and error message</t>
3368 </list>
3369 </t>
3370 </list>
3371 </t>
3372 <t>Examples:</t>
3373 <t>
3374 <list>
3375 <t></t>
3376 </list>
3377 </t>
3378 </section>
3379
3380 <section title="Muting a sampler channel" anchor="SET CHANNEL MUTE" lscp_cmd="true">
3381 <t>The front-end can mute/unmute a specific sampler
3382 channel by sending the following command:</t>
3383 <t>
3384 <list>
3385 <t>SET CHANNEL MUTE &lt;sampler-channel&gt; &lt;mute&gt;</t>
3386 </list>
3387 </t>
3388 <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3389 number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3390 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command and
3391 &lt;mute&gt; should be replaced either by "1" to mute the channel or "0"
3392 to unmute the channel.</t>
3393
3394 <t>Possible Answers:</t>
3395 <t>
3396 <list>
3397 <t>"OK" -
3398 <list>
3399 <t>on success</t>
3400 </list>
3401 </t>
3402 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3403 <list>
3404 <t>if the channel was muted/unmuted, but there are noteworthy
3405 issue(s) related, providing an appropriate warning code and
3406 warning message</t>
3407 </list>
3408 </t>
3409 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3410 <list>
3411 <t>in case it failed, providing an appropriate error code and error message</t>
3412 </list>
3413 </t>
3414 </list>
3415 </t>
3416 <t>Examples:</t>
3417 <t>
3418 <list>
3419 <t></t>
3420 </list>
3421 </t>
3422 </section>
3423
3424 <section title="Soloing a sampler channel" anchor="SET CHANNEL SOLO" lscp_cmd="true">
3425 <t>The front-end can solo/unsolo a specific sampler channel
3426 by sending the following command:</t>
3427 <t>
3428 <list>
3429 <t>SET CHANNEL SOLO &lt;sampler-channel&gt; &lt;solo&gt;</t>
3430 </list>
3431 </t>
3432 <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3433 number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3434 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command and
3435 &lt;solo&gt; should be replaced either by "1" to solo the channel or "0"
3436 to unsolo the channel.</t>
3437
3438 <t>Possible Answers:</t>
3439 <t>
3440 <list>
3441 <t>"OK" -
3442 <list>
3443 <t>on success</t>
3444 </list>
3445 </t>
3446 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3447 <list>
3448 <t>if the channel was soloed/unsoloed, but there are noteworthy
3449 issue(s) related, providing an appropriate warning code and
3450 warning message</t>
3451 </list>
3452 </t>
3453 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3454 <list>
3455 <t>in case it failed, providing an appropriate error code and error message</t>
3456 </list>
3457 </t>
3458 </list>
3459 </t>
3460 <t>Examples:</t>
3461 <t>
3462 <list>
3463 <t></t>
3464 </list>
3465 </t>
3466 </section>
3467
3468 <section title="Assigning a MIDI instrument map to a sampler channel" anchor="SET CHANNEL MIDI_INSTRUMENT_MAP" lscp_cmd="true">
3469 <t>The front-end can assign a MIDI instrument map to a specific sampler channel
3470 by sending the following command:</t>
3471 <t>
3472 <list>
3473 <t>SET CHANNEL MIDI_INSTRUMENT_MAP &lt;sampler-channel&gt; &lt;map&gt;</t>
3474 </list>
3475 </t>
3476 <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3477 number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3478 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command and
3479 &lt;map&gt; can have the following possibilites:</t>
3480 <t>
3481 <list>
3482 <t>"NONE" -
3483 <list>
3484 <t>This is the default setting. In this case
3485 the sampler channel is not assigned any MIDI
3486 instrument map and thus will ignore all MIDI
3487 program change messages.</t>
3488 </list>
3489 </t>
3490 <t>"DEFAULT" -
3491 <list>
3492 <t>The sampler channel will always use the
3493 default MIDI instrument map to handle MIDI
3494 program change messages.</t>
3495 </list>
3496 </t>
3497 <t>numeric ID -
3498 <list>
3499 <t>You can assign a specific MIDI instrument map
3500 by replacing &lt;map&gt; with the respective numeric
3501 ID of the MIDI instrument map as returned by the
3502 <xref target="LIST MIDI_INSTRUMENT_MAPS">"LIST MIDI_INSTRUMENT_MAPS"</xref>
3503 command. Once that map will be deleted, the sampler
3504 channel would fall back to "NONE".</t>
3505 </list>
3506 </t>
3507 </list>
3508 </t>
3509 <t>Read chapter <xref target="MIDI Instrument Mapping">"MIDI Instrument Mapping"</xref>
3510 for details regarding MIDI instrument mapping.</t>
3511
3512 <t>Possible Answers:</t>
3513 <t>
3514 <list>
3515 <t>"OK" -
3516 <list>
3517 <t>on success</t>
3518 </list>
3519 </t>
3520 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3521 <list>
3522 <t>in case it failed, providing an appropriate error code and error message</t>
3523 </list>
3524 </t>
3525 </list>
3526 </t>
3527
3528 <t>Examples:</t>
3529 <t>
3530 <list>
3531 <t></t>
3532 </list>
3533 </t>
3534 </section>
3535
3536 <section title="Adding an effect send to a sampler channel" anchor="CREATE FX_SEND" lscp_cmd="true">
3537 <t>The front-end can create an additional effect send on a specific sampler channel
3538 by sending the following command:</t>
3539 <t>
3540 <list>
3541 <t>CREATE FX_SEND &lt;sampler-channel&gt; &lt;midi-ctrl&gt; [&lt;name&gt;]</t>
3542 </list>
3543 </t>
3544 <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3545 number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3546 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command, that is the
3547 sampler channel on which the effect send should be created on, &lt;midi-ctrl&gt;
3548 is a number between 0..127 defining the MIDI controller which can alter the
3549 effect send level and &lt;name&gt; is an optional argument defining a name
3550 for the effect send entity. The name does not have to be unique, but MUST be
3551 encapsulated into apostrophes and supports escape sequences as described in chapter
3552 "<xref target="character_set">Character Set and Escape Sequences</xref>".</t>
3553
3554 <t>Note: there are two possible approaches to apply audio effects with FX sends:
3555 you can either use a) internal effects or b) external effects.
3556 By default, that is as initial routing, effect sends are automatically routed
3557 directly to the sampler channel's audio output device and the effect send's
3558 audio channels are by default automatically routed to the last audio channels
3559 of that audio output device (for the purpose of applying effects externally that is,
3560 e.g. by using another application), that way you can i.e. first increase the
3561 amount of audio channels on the audio output device for having dedicated effect
3562 send output channels and when "CREATE FX_SEND" is called, those channels will
3563 automatically be picked. You can alter the destination channels however with
3564 <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">"SET FX_SEND AUDIO_OUTPUT_CHANNEL"</xref>.
3565 If your intention is rather to use internal effects instead of external effects,
3566 then you first need to <xref target="effects">load those internal effects</xref>
3567 and then assign the FX sends to the desired internal effect by sending
3568 <xref target="SET FX_SEND EFFECT">"SET FX_SEND EFFECT"</xref>.
3569 </t>
3570
3571 <t>Note: Create effect sends on a sampler channel only when needed, because having effect
3572 sends on a sampler channel will decrease runtime performance, because for implementing channel
3573 effect sends, separate (sampler channel local) audio buffers are needed to render and mix
3574 the voices and route the audio signal afterwards to the master outputs and effect send
3575 outputs (along with their respective effect send levels). A sampler channel without effect
3576 sends however can mix its voices directly into the audio output devices's audio buffers
3577 and is thus faster.
3578 </t>
3579
3580 <t>Possible Answers:</t>
3581 <t>
3582 <list>
3583 <t>"OK[&lt;fx-send-id&gt;]" -
3584 <list>
3585 <t>in case a new effect send could be added to the
3586 sampler channel, where &lt;fx-send-id&gt; reflects the
3587 unique ID of the newly created effect send entity</t>
3588 </list>
3589 </t>
3590 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3591 <list>
3592 <t>when a new effect send could not be added, i.e.
3593 due to invalid parameters</t>
3594 </list>
3595 </t>
3596 </list>
3597 </t>
3598
3599 <t>Examples:</t>
3600 <t>
3601 <list>
3602 <t>C: "CREATE FX_SEND 0 91 'Reverb Send'"</t>
3603 <t>S: "OK[0]"</t>
3604 </list>
3605 </t>
3606 <t>
3607 <list>
3608 <t>C: "CREATE FX_SEND 0 93"</t>
3609 <t>S: "OK[1]"</t>
3610 </list>
3611 </t>
3612 </section>
3613
3614 <section title="Removing an effect send from a sampler channel" anchor="DESTROY FX_SEND" lscp_cmd="true">
3615 <t>The front-end can remove an existing effect send on a specific sampler channel
3616 by sending the following command:</t>
3617 <t>
3618 <list>
3619 <t>DESTROY FX_SEND &lt;sampler-channel&gt; &lt;fx-send-id&gt;</t>
3620 </list>
3621 </t>
3622 <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3623 number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3624 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command, that is the
3625 sampler channel from which the effect send should be removed from and
3626 &lt;fx-send-id&gt; is the respective effect send number as returned by the
3627 <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3628 or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command.</t>
3629
3630 <t>Possible Answers:</t>
3631 <t>
3632 <list>
3633 <t>"OK" -
3634 <list>
3635 <t>on success</t>
3636 </list>
3637 </t>
3638 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3639 <list>
3640 <t>in case it failed, providing an appropriate error code and
3641 error message</t>
3642 </list>
3643 </t>
3644 </list>
3645 </t>
3646
3647 <t>Example:</t>
3648 <t>
3649 <list>
3650 <t>C: "DESTROY FX_SEND 0 0"</t>
3651 <t>S: "OK"</t>
3652 </list>
3653 </t>
3654 </section>
3655
3656 <section title="Getting amount of effect sends on a sampler channel" anchor="GET FX_SENDS" lscp_cmd="true">
3657 <t>The front-end can ask for the amount of effect sends on a specific sampler channel
3658 by sending the following command:</t>
3659 <t>
3660 <list>
3661 <t>GET FX_SENDS &lt;sampler-channel&gt;</t>
3662 </list>
3663 </t>
3664 <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3665 number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3666 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
3667
3668 <t>Possible Answers:</t>
3669 <t>
3670 <list>
3671 <t>The sampler will answer by returning the number of effect
3672 sends on the given sampler channel.</t>
3673 </list>
3674 </t>
3675
3676 <t>Example:</t>
3677 <t>
3678 <list>
3679 <t>C: "GET FX_SENDS 0"</t>
3680 <t>S: "2"</t>
3681 </list>
3682 </t>
3683 </section>
3684
3685 <section title="Listing all effect sends on a sampler channel" anchor="LIST FX_SENDS" lscp_cmd="true">
3686 <t>The front-end can ask for a list of effect sends on a specific sampler channel
3687 by sending the following command:</t>
3688 <t>
3689 <list>
3690 <t>LIST FX_SENDS &lt;sampler-channel&gt;</t>
3691 </list>
3692 </t>
3693 <t>Where &lt;sampler-channel&gt; is the respective sampler channel
3694 number as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3695 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command.</t>
3696
3697 <t>Possible Answers:</t>
3698 <t>
3699 <list>
3700 <t>The sampler will answer by returning a comma separated list
3701 with all effect sends' numerical IDs on the given sampler
3702 channel.</t>
3703 </list>
3704 </t>
3705
3706 <t>Examples:</t>
3707 <t>
3708 <list>
3709 <t>C: "LIST FX_SENDS 0"</t>
3710 <t>S: "0,1"</t>
3711 </list>
3712 </t>
3713 <t>
3714 <list>
3715 <t>C: "LIST FX_SENDS 1"</t>
3716 <t>S: ""</t>
3717 </list>
3718 </t>
3719 </section>
3720
3721 <section title="Getting effect send information" anchor="GET FX_SEND INFO" lscp_cmd="true">
3722 <t>The front-end can ask for the current settings of an effect send entity
3723 by sending the following command:</t>
3724 <t>
3725 <list>
3726 <t>GET FX_SEND INFO &lt;sampler-channel&gt; &lt;fx-send-id&gt;</t>
3727 </list>
3728 </t>
3729 <t>Where &lt;sampler-channel&gt; is the sampler channel number
3730 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3731 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command and
3732 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3733 as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3734 or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command.
3735 </t>
3736
3737 <t>Possible Answers:</t>
3738 <t>
3739 <list>
3740 <t>The sampler will answer by sending a &lt;CRLF&gt; separated list.
3741 Each answer line begins with the settings category name
3742 followed by a colon and then a space character &lt;SP&gt; and finally
3743 the info character string to that setting category. At the
3744 moment the following categories are defined:</t>
3745
3746 <t>
3747 <list>
3748 <t>NAME -
3749 <list>
3750 <t>name of the effect send entity
3751 (note that this character string may contain
3752 <xref target="character_set">escape sequences</xref>)</t>
3753 </list>
3754 </t>
3755 <t>MIDI_CONTROLLER -
3756 <list>
3757 <t>a value between 0 and 127 reflecting the MIDI controller
3758 which is able to modify the effect send's send level</t>
3759 </list>
3760 </t>
3761 <t>LEVEL -
3762 <list>
3763 <t>optionally dotted number reflecting the effect send's
3764 current send level (where a value &lt; 1.0 means attenuation
3765 and a value > 1.0 means amplification)</t>
3766 </list>
3767 </t>
3768 <t>AUDIO_OUTPUT_ROUTING -
3769 <list>
3770 <t>comma separated list which reflects to which audio
3771 channel of the selected audio output device each
3772 effect send output channel is routed to, e.g. "0,3" would
3773 mean the effect send's output channel 0 is routed to channel
3774 0 of the audio output device and the effect send's output
3775 channel 1 is routed to the channel 3 of the audio
3776 output device (see
3777 <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">"SET FX_SEND AUDIO_OUTPUT_CHANNEL"</xref>
3778 for details), if an internal send
3779 effect is assigned to the effect
3780 send, then this setting defines the
3781 audio channel routing to that
3782 effect instance respectively</t>
3783 </list>
3784 </t>
3785 <t>EFFECT -
3786 <list>
3787 <t>destination send effect chain ID
3788 and destination effect chain
3789 position, separated by comma in the
3790 form "&lt;effect-chain&gt;,&lt;chain-pos&gt;"
3791 or "NONE" if there is no send effect
3792 assigned to the effect send</t>
3793 </list>
3794 </t>
3795 </list>
3796 </t>
3797 </list>
3798 </t>
3799 <t>The mentioned fields above don't have to be in particular order.</t>
3800
3801 <t>Example:</t>
3802 <t>
3803 <list>
3804 <t>C: "GET FX_SEND INFO 0 0"</t>
3805 <t>S: "NAME: Reverb Send"</t>
3806 <t>&nbsp;&nbsp;&nbsp;"MIDI_CONTROLLER: 91"</t>
3807 <t>&nbsp;&nbsp;&nbsp;"LEVEL: 0.3"</t>
3808 <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 2,3"</t>
3809 <t>&nbsp;&nbsp;&nbsp;"EFFECT: NONE"</t>
3810 <t>&nbsp;&nbsp;&nbsp;"."</t>
3811 </list>
3812 </t>
3813 <t>
3814 <list>
3815 <t>C: "GET FX_SEND INFO 0 1"</t>
3816 <t>S: "NAME: Delay Send (Internal)"</t>
3817 <t>&nbsp;&nbsp;&nbsp;"MIDI_CONTROLLER: 93"</t>
3818 <t>&nbsp;&nbsp;&nbsp;"LEVEL: 0.51"</t>
3819 <t>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 1,2"</t>
3820 <t>&nbsp;&nbsp;&nbsp;"EFFECT: 2,0"</t>
3821 <t>&nbsp;&nbsp;&nbsp;"."</t>
3822 </list>
3823 </t>
3824 </section>
3825
3826 <section title="Changing effect send's name" anchor="SET FX_SEND NAME" lscp_cmd="true">
3827 <t>The front-end can alter the current name of an effect
3828 send entity by sending the following command:</t>
3829 <t>
3830 <list>
3831 <t>SET FX_SEND NAME &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;name&gt;</t>
3832 </list>
3833 </t>
3834 <t>Where &lt;sampler-chan&gt; is the sampler channel number
3835 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3836 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3837 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3838 as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3839 or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
3840 &lt;name&gt; is the new name of the effect send entity, which
3841 does not have to be unique (name MUST be encapsulated into apostrophes
3842 and supports escape sequences as described in chapter
3843 "<xref target="character_set">Character Set and Escape Sequences</xref>").
3844 </t>
3845
3846 <t>Possible Answers:</t>
3847 <t>
3848 <list>
3849 <t>"OK" -
3850 <list>
3851 <t>on success</t>
3852 </list>
3853 </t>
3854 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3855 <list>
3856 <t>in case it failed, providing an appropriate error code and error message</t>
3857 </list>
3858 </t>
3859 </list>
3860 </t>
3861 <t>Example:</t>
3862 <t>
3863 <list>
3864 <t>C: "SET FX_SEND NAME 0 0 'Fx Send 1'"</t>
3865 <t>S: "OK"</t>
3866 </list>
3867 </t>
3868 </section>
3869
3870 <section title="Altering effect send's audio routing" anchor="SET FX_SEND AUDIO_OUTPUT_CHANNEL" lscp_cmd="true">
3871 <t>The front-end can alter the destination of an effect send's audio channel on a specific
3872 sampler channel by sending the following command:</t>
3873 <t>
3874 <list>
3875 <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>
3876 </list>
3877 </t>
3878 <t>Where &lt;sampler-chan&gt; is the sampler channel number
3879 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3880 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3881 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3882 as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3883 or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command,
3884 &lt;audio-src&gt; is the numerical ID of the effect send's audio channel
3885 which should be rerouted and &lt;audio-dst&gt; is the numerical ID of
3886 either a) the audio output channel of the sampler channel's audio output
3887 device (i.e. if external effect shall be applied) or b) of the audio
3888 input channel of an internal effect assigned to the FX send where
3889 &lt;audio-src&gt; should be routed to.</t>
3890
3891 <t>Note that effect sends can only route audio to the same audio output
3892 device as assigned to the effect send's sampler channel. Also note that an
3893 effect send entity does always have exactly as much audio channels as its
3894 sampler channel. So if the sampler channel is stereo, the effect send does
3895 have two audio channels as well. Also keep in mind that the amount of audio
3896 channels on a sampler channel might be dependant not only to the deployed
3897 sampler engine on the sampler channel, but also dependant to the instrument
3898 currently loaded. However you can (effectively) turn an i.e. stereo effect
3899 send into a mono one by simply altering its audio routing appropriately.</t>
3900
3901 <t>Possible Answers:</t>
3902 <t>
3903 <list>
3904 <t>"OK" -
3905 <list>
3906 <t>on success</t>
3907 </list>
3908 </t>
3909 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3910 <list>
3911 <t>if audio output channel was set, but there are noteworthy
3912 issue(s) related, providing an appropriate warning code and
3913 warning message</t>
3914 </list>
3915 </t>
3916 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3917 <list>
3918 <t>in case it failed, providing an appropriate error code and error message</t>
3919 </list>
3920 </t>
3921 </list>
3922 </t>
3923 <t>Example:</t>
3924 <t>
3925 <list>
3926 <t>C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2"</t>
3927 <t>S: "OK"</t>
3928 </list>
3929 </t>
3930 </section>
3931
3932 <section title="Assigning destination effect to an effect send" anchor="SET FX_SEND EFFECT" lscp_cmd="true">
3933 <t>The front-end can (re-)assign an internal destination effect to an
3934 effect send by sending the following command:</t>
3935 <t>
3936 <list>
3937 <t>SET FX_SEND EFFECT &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;effect-chain&gt; &lt;chain-pos&gt;</t>
3938 </list>
3939 </t>
3940 <t>Where &lt;sampler-chan&gt; is the sampler channel number
3941 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3942 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
3943 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
3944 as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
3945 or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command,
3946 &lt;effect-chain&gt; by the numerical ID of the destination
3947 effect chain as returned by the
3948 <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
3949 or
3950 <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
3951 command and &lt;chain-pos&gt; reflects the exact effect
3952 chain position in the effect chain which hosts the actual
3953 destination effect.</t>
3954
3955 <t>Note: This command MUST NOT be used if you want to apply
3956 audio effects externally! By default FX sends are routed directly
3957 to the audio output device for that purpose.
3958 You can also revert this command later on by sending
3959 <xref target="REMOVE FX_SEND EFFECT">"REMOVE FX_SEND EFFECT"</xref>,
3960 which will cause the FX send to be routed directly to the sampler channel's
3961 audio output device instead (i.e. for using external effects instead of
3962 internal effects).
3963 </t>
3964
3965 <t>Possible Answers:</t>
3966 <t>
3967 <list>
3968 <t>"OK" -
3969 <list>
3970 <t>on success</t>
3971 </list>
3972 </t>
3973 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3974 <list>
3975 <t>in case it failed, providing an appropriate error code and error message</t>
3976 </list>
3977 </t>
3978 </list>
3979 </t>
3980 <t>Example:</t>
3981 <t>
3982 <list>
3983 <t>C: "SET FX_SEND EFFECT 0 0 2 5"</t>
3984 <t>S: "OK"</t>
3985 </list>
3986 </t>
3987 </section>
3988
3989 <section title="Removing destination effect from an effect send" anchor="REMOVE FX_SEND EFFECT" lscp_cmd="true">
3990 <t>The front-end can (re-)assign a destination effect to an
3991 effect send by sending the following command:</t>
3992 <t>
3993 <list>
3994 <t>REMOVE FX_SEND EFFECT &lt;sampler-chan&gt; &lt;fx-send-id&gt;</t>
3995 </list>
3996 </t>
3997 <t>Where &lt;sampler-chan&gt; is the sampler channel number
3998 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
3999 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
4000 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
4001 as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
4002 or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command.</t>
4003
4004 <t>After the destination effect has been removed from the
4005 effect send, the audio signal of the effect send will be
4006 routed directly to the audio output device, according to the
4007 audio channel routing setting of the effect send.
4008 </t>
4009
4010 <t>Possible Answers:</t>
4011 <t>
4012 <list>
4013 <t>"OK" -
4014 <list>
4015 <t>on success</t>
4016 </list>
4017 </t>
4018 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4019 <list>
4020 <t>in case it failed, providing an appropriate error code and error message</t>
4021 </list>
4022 </t>
4023 </list>
4024 </t>
4025 <t>Example:</t>
4026 <t>
4027 <list>
4028 <t>C: "REMOVE FX_SEND EFFECT 0 0"</t>
4029 <t>S: "OK"</t>
4030 </list>
4031 </t>
4032 </section>
4033
4034 <section title="Altering effect send's MIDI controller" anchor="SET FX_SEND MIDI_CONTROLLER" lscp_cmd="true">
4035 <t>The front-end can alter the MIDI controller of an effect
4036 send entity by sending the following command:</t>
4037 <t>
4038 <list>
4039 <t>SET FX_SEND MIDI_CONTROLLER &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;midi-ctrl&gt;</t>
4040 </list>
4041 </t>
4042 <t>Where &lt;sampler-chan&gt; is the sampler channel number
4043 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
4044 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
4045 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
4046 as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
4047 or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
4048 &lt;midi-ctrl&gt; reflects the MIDI controller which shall be
4049 able to modify the effect send's send level.</t>
4050
4051 <t>Possible Answers:</t>
4052 <t>
4053 <list>
4054 <t>"OK" -
4055 <list>
4056 <t>on success</t>
4057 </list>
4058 </t>
4059 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4060 <list>
4061 <t>if MIDI controller was set, but there are noteworthy
4062 issue(s) related, providing an appropriate warning code and
4063 warning message</t>
4064 </list>
4065 </t>
4066 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4067 <list>
4068 <t>in case it failed, providing an appropriate error code and error message</t>
4069 </list>
4070 </t>
4071 </list>
4072 </t>
4073 <t>Example:</t>
4074 <t>
4075 <list>
4076 <t>C: "SET FX_SEND MIDI_CONTROLLER 0 0 91"</t>
4077 <t>S: "OK"</t>
4078 </list>
4079 </t>
4080 </section>
4081
4082 <section title="Altering effect send's send level" anchor="SET FX_SEND LEVEL" lscp_cmd="true">
4083 <t>The front-end can alter the current send level of an effect
4084 send entity by sending the following command:</t>
4085 <t>
4086 <list>
4087 <t>SET FX_SEND LEVEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;volume&gt;</t>
4088 </list>
4089 </t>
4090 <t>Where &lt;sampler-chan&gt; is the sampler channel number
4091 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
4092 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
4093 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
4094 as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref>
4095 or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and
4096 &lt;volume&gt; is an optionally dotted positive number (a value
4097 smaller than 1.0 means attenuation, whereas a value greater than
4098 1.0 means amplification) reflecting the new send level.</t>
4099
4100 <t>Possible Answers:</t>
4101 <t>
4102 <list>
4103 <t>"OK" -
4104 <list>
4105 <t>on success</t>
4106 </list>
4107 </t>
4108 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4109 <list>
4110 <t>if new send level was set, but there are noteworthy
4111 issue(s) related, providing an appropriate warning code and
4112 warning message</t>
4113 </list>
4114 </t>
4115 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4116 <list>
4117 <t>in case it failed, providing an appropriate error code and error message</t>
4118 </list>
4119 </t>
4120 </list>
4121 </t>
4122 <t>Example:</t>
4123 <t>
4124 <list>
4125 <t>C: "SET FX_SEND LEVEL 0 0 0.15"</t>
4126 <t>S: "OK"</t>
4127 </list>
4128 </t>
4129 </section>
4130
4131 <section title="Sending MIDI messages to sampler channel" anchor="SEND CHANNEL MIDI_DATA" lscp_cmd="true">
4132 <t>The front-end can send MIDI events to a specific sampler channel
4133 by sending the following command:</t>
4134 <t>
4135 <list>
4136 <t>SEND CHANNEL MIDI_DATA &lt;midi-msg&gt; &lt;sampler-chan&gt; &lt;arg1&gt; &lt;arg2&gt;</t>
4137 </list>
4138 </t>
4139 <t>Where &lt;sampler-chan&gt; is the sampler channel number
4140 as returned by the <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
4141 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref> command,
4142 &lt;arg1&gt; and &lt;arg2&gt; arguments depend on the &lt;midi-msg&gt; argument, which
4143 specifies the MIDI message type. Currently, the following MIDI messages are supported:</t>
4144 <t>
4145 <list>
4146 <t>"NOTE_ON" -
4147 <list>
4148 <t>For turning on MIDI notes, where &lt;arg1&gt;
4149 specifies the key number and &lt;arg2&gt; the velocity
4150 as described in the MIDI specification.</t>
4151 </list>
4152 </t>
4153 <t>"NOTE_OFF" -
4154 <list>
4155 <t>For turning a currently playing MIDI note off, where &lt;arg1&gt;
4156 specifies the key number and &lt;arg2&gt; the velocity
4157 as described in the MIDI specification.</t>
4158 </list>
4159 </t>
4160 <t>"CC" -
4161 <list>
4162 <t>For changing a MIDI controller, where &lt;arg1&gt;
4163 specifies the controller number and &lt;arg2&gt; the
4164 new value of the controller as described in the Control
4165 Change section of the MIDI specification.</t>
4166 </list>
4167 </t>
4168 </list>
4169 </t>
4170 <t>CAUTION: This command is provided for implementations of virtual MIDI keyboards
4171 and no realtime guarantee whatsoever will be made!</t>
4172 <t>Possible Answers:</t>
4173 <t>
4174 <list>
4175 <t>"OK" -
4176 <list>
4177 <t>on success</t>
4178 </list>
4179 </t>
4180 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4181 <list>
4182 <t>in case it failed, providing an appropriate error code and error message</t>
4183 </list>
4184 </t>
4185 </list>
4186 </t>
4187 <t>Example:</t>
4188 <t>
4189 <list>
4190 <t>C: "SEND CHANNEL MIDI_DATA NOTE_ON 0 56 112"</t>
4191 <t>S: "OK"</t>
4192 </list>
4193 </t>
4194 </section>
4195
4196 <section title="Resetting a sampler channel" anchor="RESET CHANNEL" lscp_cmd="true">
4197 <t>The front-end can reset a particular sampler channel by sending the following command:</t>
4198 <t>
4199 <list>
4200 <t>RESET CHANNEL &lt;sampler-channel&gt;</t>
4201 </list>
4202 </t>
4203 <t>
4204 Where &lt;sampler-channel&gt; defines the sampler channel to be reset.
4205 This will cause the engine on that sampler channel, its voices and
4206 eventually disk streams and all control and status variables to be
4207 reset.</t>
4208
4209 <t>Possible Answers:</t>
4210 <t>
4211 <list>
4212 <t>"OK" -
4213 <list>
4214 <t>on success</t>
4215 </list>
4216 </t>
4217 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4218 <list>
4219 <t>if channel was reset, but there are noteworthy issue(s)
4220 related, providing an appropriate warning code and warning
4221 message</t>
4222 </list>
4223 </t>
4224 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4225 <list>
4226 <t>in case it failed, providing an appropriate error code and
4227 error message</t>
4228 </list>
4229 </t>
4230 </list>
4231 </t>
4232 <t>Examples:</t>
4233 <t>
4234 <list>
4235 <t></t>
4236 </list>
4237 </t>
4238 </section>
4239 </section>
4240
4241 <section title="Controlling connection">
4242 <t>The following commands are used to control the connection to LinuxSampler.</t>
4243
4244 <section title="Register front-end for receiving event messages" anchor="SUBSCRIBE" lscp_cmd="true">
4245 <t>The front-end can register itself to the LinuxSampler application to
4246 be informed about noteworthy events by sending this command:</t>
4247 <t>
4248 <list>
4249 <t>SUBSCRIBE &lt;event-id&gt;</t>
4250 </list>
4251 </t>
4252 <t>where &lt;event-id&gt; will be replaced by the respective event that
4253 client wants to subscribe to.</t>
4254
4255 <t>Possible Answers:</t>
4256 <t>
4257 <list>
4258 <t>"OK" -
4259 <list>
4260 <t>on success</t>
4261 </list>
4262 </t>
4263 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4264 <list>
4265 <t>if registration succeeded, but there are noteworthy
4266 issue(s) related, providing an appropriate warning code and
4267 warning message</t>
4268 </list>
4269 </t>
4270 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4271 <list>
4272 <t>in case it failed, providing an appropriate error code and
4273 error message</t>
4274 </list>
4275 </t>
4276 </list>
4277 </t>
4278 <t>Examples:</t>
4279 <t>
4280 <list>
4281 <t></t>
4282 </list>
4283 </t>
4284 </section>
4285
4286 <section title="Unregister front-end for not receiving event messages" anchor="UNSUBSCRIBE" lscp_cmd="true">
4287 <t>The front-end can unregister itself if it doesn't want to receive event
4288 messages anymore by sending the following command:</t>
4289 <t>
4290 <list>
4291 <t>UNSUBSCRIBE &lt;event-id&gt;</t>
4292 </list>
4293 </t>
4294 <t>Where &lt;event-id&gt; will be replaced by the respective event that
4295 client doesn't want to receive anymore.</t>
4296
4297 <t>Possible Answers:</t>
4298 <t>
4299 <list>
4300 <t>"OK" -
4301 <list>
4302 <t>on success</t>
4303 </list>
4304 </t>
4305 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4306 <list>
4307 <t>if unregistration succeeded, but there are noteworthy
4308 issue(s) related, providing an appropriate warning code and
4309 warning message</t>
4310 </list>
4311 </t>
4312 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4313 <list>
4314 <t>in case it failed, providing an appropriate error code and
4315 error message</t>
4316 </list>
4317 </t>
4318 </list>
4319 </t>
4320 <t>Examples:</t>
4321 <t>
4322 <list>
4323 <t></t>
4324 </list>
4325 </t>
4326 </section>
4327
4328 <section title="Enable or disable echo of commands" anchor="SET ECHO" lscp_cmd="true">
4329 <t>To enable or disable back sending of commands to the client the following command can be used:</t>
4330 <t>
4331 <list>
4332 <t>SET ECHO &lt;value&gt;</t>
4333 </list>
4334 </t>
4335 <t>Where &lt;value&gt; should be replaced either by "1" to enable echo mode
4336 or "0" to disable echo mode. When echo mode is enabled, all
4337 commands send to LinuxSampler will be immediately send back and
4338 after this echo the actual response to the command will be
4339 returned. Echo mode will only be altered for the client connection
4340 that issued the "SET ECHO" command, not globally for all client
4341 connections.</t>
4342
4343 <t>Possible Answers:</t>
4344 <t>
4345 <list>
4346 <t>"OK" -
4347 <list>
4348 <t>usually</t>
4349 </list>
4350 </t>
4351 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4352 <list>
4353 <t>on syntax error, e.g. non boolean value</t>
4354 </list>
4355 </t>
4356 </list>
4357 </t>
4358 <t>Examples:</t>
4359 <t>
4360 <list>
4361 <t></t>
4362 </list>
4363 </t>
4364 </section>
4365
4366 <section title="Close client connection" anchor="QUIT" lscp_cmd="true">
4367 <t>The client can close its network connection to LinuxSampler by sending the following command:</t>
4368 <t>
4369 <list>
4370 <t>QUIT</t>
4371 </list>
4372 </t>
4373 <t>This is probably more interesting for manual telnet connections to
4374 LinuxSampler than really useful for a front-end implementation.</t>
4375 </section>
4376 </section>
4377
4378 <section title="Global commands">
4379 <t>The following commands have global impact on the sampler.</t>
4380
4381 <section title="Current number of active voices" anchor="GET TOTAL_VOICE_COUNT" lscp_cmd="true">
4382 <t>The front-end can ask for the current number of active voices on
4383 the sampler by sending the following command:</t>
4384 <t>
4385 <list>
4386 <t>GET TOTAL_VOICE_COUNT</t>
4387 </list>
4388 </t>
4389
4390 <t>Possible Answers:</t>
4391 <t>
4392 <list>
4393 <t>LinuxSampler will answer by returning the number of all active
4394 voices on the sampler.</t>
4395 </list>
4396 </t>
4397 </section>
4398
4399 <section title="Maximum amount of active voices" anchor="GET TOTAL_VOICE_COUNT_MAX" lscp_cmd="true">
4400 <t>The front-end can ask for the maximum number of active voices
4401 by sending the following command:</t>
4402 <t>
4403 <list>
4404 <t>GET TOTAL_VOICE_COUNT_MAX</t>
4405 </list>
4406 </t>
4407
4408 <t>Possible Answers:</t>
4409 <t>
4410 <list>
4411 <t>LinuxSampler will answer by returning the maximum number
4412 of active voices.</t>
4413 </list>
4414 </t>
4415 </section>
4416
4417 <section title="Current number of active disk streams" anchor="GET TOTAL_STREAM_COUNT" lscp_cmd="true">
4418 <t>The front-end can ask for the current number of active disk streams on
4419 the sampler by sending the following command:</t>
4420 <t>
4421 <list>
4422 <t>GET TOTAL_STREAM_COUNT</t>
4423 </list>
4424 </t>
4425
4426 <t>Possible Answers:</t>
4427 <t>
4428 <list>
4429 <t>LinuxSampler will answer by returning the number of all active
4430 disk streams on the sampler.</t>
4431 </list>
4432 </t>
4433 </section>
4434
4435 <section title="Reset sampler" anchor="RESET">
4436 <t>The front-end can reset the whole sampler by sending the following command:</t>
4437 <t>
4438 <list>
4439 <t>RESET</t>
4440 </list>
4441 </t>
4442
4443 <t>Possible Answers:</t>
4444 <t>
4445 <list>
4446 <t>"OK" -
4447 <list>
4448 <t>always</t>
4449 </list>
4450 </t>
4451 </list>
4452 </t>
4453 <t>Examples:</t>
4454 <t>
4455 <list>
4456 <t></t>
4457 </list>
4458 </t>
4459 </section>
4460
4461 <section title="General sampler information" anchor="GET SERVER INFO" lscp_cmd="true">
4462 <t>The client can ask for general information about the LinuxSampler
4463 instance by sending the following command:</t>
4464 <t>
4465 <list>
4466 <t>GET SERVER INFO</t>
4467 </list>
4468 </t>
4469 <t>Possible Answers:</t>
4470 <t>
4471 <list>
4472 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
4473 Each answer line begins with the information category name
4474 followed by a colon and then a space character &lt;SP&gt; and finally
4475 the info character string to that information category. At the
4476 moment the following categories are defined:
4477 </t>
4478 <t>
4479 <list>
4480 <t>DESCRIPTION -
4481 <list>
4482 <t>arbitrary textual description about the sampler
4483 (note that the character string may contain
4484 <xref target="character_set">escape sequences</xref>)</t>
4485 </list>
4486 </t>
4487 <t>VERSION -
4488 <list>
4489 <t>version of the sampler</t>
4490 </list>
4491 </t>
4492 <t>PROTOCOL_VERSION -
4493 <list>
4494 <t>version of the LSCP specification the sampler
4495 complies with (see <xref target="LSCP versioning" /> for details)</t>
4496 </list>
4497 </t>
4498 <t>INSTRUMENTS_DB_SUPPORT -
4499 <list>
4500 <t>either yes or no, specifies whether the
4501 sampler is build with instruments database support.</t>
4502 </list>
4503 </t>
4504 </list>
4505 </t>
4506 </list>
4507 </t>
4508 <t>The mentioned fields above don't have to be in particular order.
4509 Other fields might be added in future.</t>
4510
4511 <t>Example:</t>
4512 <t>
4513 <list>
4514 <t>C: "GET SERVER INFO"</t>
4515 <t>S: "DESCRIPTION: LinuxSampler - modular, streaming capable sampler"</t>
4516 <t>&nbsp;&nbsp;&nbsp;"VERSION: 1.0.0.svn23"</t>
4517 <t>&nbsp;&nbsp;&nbsp;"PROTOCOL_VERSION: 1.5"</t>
4518 <t>&nbsp;&nbsp;&nbsp;"INSTRUMENTS_DB_SUPPORT: no"</t>
4519 <t>&nbsp;&nbsp;&nbsp;"."</t>
4520 </list>
4521 </t>
4522 </section>
4523
4524 <section title="Getting global volume attenuation" anchor="GET VOLUME" lscp_cmd="true">
4525 <t>The client can ask for the current global sampler-wide volume
4526 attenuation by sending the following command:</t>
4527 <t>
4528 <list>
4529 <t>GET VOLUME</t>
4530 </list>
4531 </t>
4532 <t>Possible Answers:</t>
4533 <t>
4534 <list>
4535 <t>The sampler will always answer by returning the optional
4536 dotted floating point coefficient, reflecting the current
4537 global volume attenuation.
4538 </t>
4539 </list>
4540 </t>
4541 <t>Note: it is up to the respective sampler engine whether to obey
4542 that global volume parameter or not, but in general all engines SHOULD
4543 use this parameter.</t>
4544 </section>
4545
4546 <section title="Setting global volume attenuation" anchor="SET VOLUME" lscp_cmd="true">
4547 <t>The client can alter the current global sampler-wide volume
4548 attenuation by sending the following command:</t>
4549 <t>
4550 <list>
4551 <t>SET VOLUME &lt;volume&gt;</t>
4552 </list>
4553 </t>
4554 <t>Where &lt;volume&gt; should be replaced by the optional dotted
4555 floating point value, reflecting the new global volume parameter.
4556 This value might usually be in the range between 0.0 and 1.0, that
4557 is for attenuating the overall volume.</t>
4558
4559 <t>Possible Answers:</t>
4560 <t>
4561 <list>
4562 <t>"OK" -
4563 <list>
4564 <t>on success</t>
4565 </list>
4566 </t>
4567 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4568 <list>
4569 <t>if the global volume was set, but there are noteworthy
4570 issue(s) related, providing an appropriate warning code and
4571 warning message</t>
4572 </list>
4573 </t>
4574 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4575 <list>
4576 <t>in case it failed, providing an appropriate error code and error message</t>
4577 </list>
4578 </t>
4579 </list>
4580 </t>
4581 </section>
4582
4583 <section title="Getting global voice limit" anchor="GET VOICES" lscp_cmd="true">
4584 <t>The client can ask for the current global sampler-wide limit
4585 for maximum voices by sending the following command:</t>
4586 <t>
4587 <list>
4588 <t>GET VOICES</t>
4589 </list>
4590 </t>
4591 <t>Possible Answers:</t>
4592 <t>
4593 <list>
4594 <t>LinuxSampler will answer by returning the number for
4595 the current limit of maximum voices.</t>
4596 </list>
4597 </t>
4598
4599 <t>The voice limit setting defines how many voices should maximum
4600 be processed by the sampler at the same time. If the user
4601 triggers new notes which would exceed that voice limit, the
4602 sampler engine will react by stealing old voices for those
4603 newly triggered notes. Note that the amount of voices triggered
4604 by a new note can be larger than one and is dependent to the
4605 respective instrument and probably further criterias.</t>
4606 </section>
4607
4608 <section title="Setting global voice limit" anchor="SET VOICES" lscp_cmd="true">
4609 <t>The client can alter the current global sampler-wide limit
4610 for maximum voices by sending the following command:</t>
4611 <t>
4612 <list>
4613 <t>SET VOICES &lt;max-voices&gt;</t>
4614 </list>
4615 </t>
4616 <t>Where &lt;max-voices&gt; should be replaced by the integer
4617 value, reflecting the new global amount limit of maximum voices.
4618 This value has to be larger than 0.</t>
4619
4620 <t>Possible Answers:</t>
4621 <t>
4622 <list>
4623 <t>"OK" -
4624 <list>
4625 <t>on success</t>
4626 </list>
4627 </t>
4628 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4629 <list>
4630 <t>if the voice limit was set, but there are noteworthy
4631 issue(s) related, providing an appropriate warning code and
4632 warning message</t>
4633 </list>
4634 </t>
4635 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4636 <list>
4637 <t>in case it failed, providing an appropriate error code and error message</t>
4638 </list>
4639 </t>
4640 </list>
4641 </t>
4642
4643 <t>Note: the given value will be passed to all sampler engine instances.
4644 The total amount of maximum voices on the running system might thus
4645 be as big as the given value multiplied by the current amount of engine
4646 instances.</t>
4647
4648 <t>Caution: when adjusting the voice limit, you SHOULD also
4649 adjust the disk stream limit respectively and vice versa.</t>
4650 </section>
4651
4652 <section title="Getting global disk stream limit" anchor="GET STREAMS" lscp_cmd="true">
4653 <t>The client can ask for the current global sampler-wide limit
4654 for maximum disk streams by sending the following command:</t>
4655 <t>
4656 <list>
4657 <t>GET STREAMS</t>
4658 </list>
4659 </t>
4660 <t>Possible Answers:</t>
4661 <t>
4662 <list>
4663 <t>LinuxSampler will answer by returning the number for
4664 the current limit of maximum disk streams.</t>
4665 </list>
4666 </t>
4667
4668 <t>The disk stream limit setting defines how many disk streams should
4669 maximum be processed by a sampler engine at the same time. The
4670 higher this value, the more memory (RAM) will be occupied, since
4671 every disk streams allocates a certain buffer size for being able
4672 to perform its streaming operations.</t>
4673 </section>
4674
4675 <section title="Setting global disk stream limit" anchor="SET STREAMS" lscp_cmd="true">
4676 <t>The client can alter the current global sampler-wide limit
4677 for maximum disk streams by sending the following command:</t>
4678 <t>
4679 <list>
4680 <t>SET STREAMS &lt;max-streams&gt;</t>
4681 </list>
4682 </t>
4683 <t>Where &lt;max-streams&gt; should be replaced by the integer
4684 value, reflecting the new global amount limit of maximum disk streams.
4685 This value has to be positive.</t>
4686
4687 <t>Possible Answers:</t>
4688 <t>
4689 <list>
4690 <t>"OK" -
4691 <list>
4692 <t>on success</t>
4693 </list>
4694 </t>
4695 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4696 <list>
4697 <t>if the disk stream limit was set, but there are noteworthy
4698 issue(s) related, providing an appropriate warning code and
4699 warning message</t>
4700 </list>
4701 </t>
4702 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4703 <list>
4704 <t>in case it failed, providing an appropriate error code and error message</t>
4705 </list>
4706 </t>
4707 </list>
4708 </t>
4709
4710 <t>Note: the given value will be passed to all sampler engine instances.
4711 The total amount of maximum disk streams on the running system might
4712 thus be as big as the given value multiplied by the current amount of
4713 engine instances.</t>
4714
4715 <t>Caution: when adjusting the disk stream limit, you SHOULD also
4716 adjust the voice limit respectively and vice versa.</t>
4717 </section>
4718
4719 </section>
4720
4721
4722 <section title="MIDI Instrument Mapping" anchor="MIDI Instrument Mapping">
4723 <t>The MIDI protocol provides a way to switch between instruments
4724 by sending so called MIDI bank select and MIDI program change
4725 messages which are essentially just numbers. The following commands
4726 allow to actually map arbitrary MIDI bank select / program change
4727 numbers with real instruments.</t>
4728 <t>The sampler allows to manage an arbitrary amount of MIDI
4729 instrument maps which define which instrument to load on
4730 which MIDI program change message.</t>
4731 <t>By default, that is when the sampler is launched, there is no
4732 map, thus the sampler will simply ignore all program change
4733 messages. The front-end has to explicitly create at least one
4734 map, add entries to the map and tell the respective sampler
4735 channel(s) which MIDI instrument map to use, so the sampler
4736 knows how to react on a given program change message on the
4737 respective sampler channel, that is by switching to the
4738 respectively defined engine type and loading the respective
4739 instrument. See command
4740 <xref target="SET CHANNEL MIDI_INSTRUMENT_MAP">"SET CHANNEL MIDI_INSTRUMENT_MAP"</xref>
4741 for how to assign a MIDI instrument map to a sampler channel.</t>
4742 <t>Also note per MIDI specification a bank select message does not
4743 cause to switch to another instrument. Instead when receiving a
4744 bank select message the bank value will be stored and a subsequent
4745 program change message (which may occur at any time) will finally
4746 cause the sampler to switch to the respective instrument as
4747 reflected by the current MIDI instrument map.</t>
4748
4749 <section title="Create a new MIDI instrument map" anchor="ADD MIDI_INSTRUMENT_MAP" lscp_cmd="true">
4750 <t>The front-end can add a new MIDI instrument map by sending
4751 the following command:</t>
4752 <t>
4753 <list>
4754 <t>ADD MIDI_INSTRUMENT_MAP [&lt;name&gt;]</t>
4755 </list>
4756 </t>
4757 <t>Where &lt;name&gt; is an optional argument allowing to
4758 assign a custom name to the new map. MIDI instrument Map
4759 names do not have to be unique, but MUST be encapsulated
4760 into apostrophes and support escape sequences as described
4761 in chapter "<xref target="character_set">Character Set and Escape Sequences</xref>".
4762 </t>
4763
4764 <t>Possible Answers:</t>
4765 <t>
4766 <list>
4767 <t>"OK[&lt;map&gt;]" -
4768 <list>
4769 <t>in case a new MIDI instrument map could
4770 be added, where &lt;map&gt; reflects the
4771 unique ID of the newly created MIDI
4772 instrument map</t>
4773 </list>
4774 </t>
4775 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4776 <list>
4777 <t>when a new map could not be created, which
4778 might never occur in practice</t>
4779 </list>
4780 </t>
4781 </list>
4782 </t>
4783
4784 <t>Examples:</t>
4785 <t>
4786 <list>
4787 <t>C: "ADD MIDI_INSTRUMENT_MAP 'Standard Map'"</t>
4788 <t>S: "OK[0]"</t>
4789 </list>
4790 </t>
4791 <t>
4792 <list>
4793 <t>C: "ADD MIDI_INSTRUMENT_MAP 'Standard Drumkit'"</t>
4794 <t>S: "OK[1]"</t>
4795 </list>
4796 </t>
4797 <t>
4798 <list>
4799 <t>C: "ADD MIDI_INSTRUMENT_MAP"</t>
4800 <t>S: "OK[5]"</t>
4801 </list>
4802 </t>
4803 </section>
4804
4805 <section title="Delete one particular or all MIDI instrument maps" anchor="REMOVE MIDI_INSTRUMENT_MAP" lscp_cmd="true">
4806 <t>The front-end can delete a particular MIDI instrument map
4807 by sending the following command:</t>
4808 <t>
4809 <list>
4810 <t>REMOVE MIDI_INSTRUMENT_MAP &lt;map&gt;</t>
4811 </list>
4812 </t>
4813 <t>Where &lt;map&gt; reflects the unique ID of the map to delete
4814 as returned by the <xref target="LIST MIDI_INSTRUMENT_MAPS">"LIST MIDI_INSTRUMENT_MAPS"</xref>
4815 command.</t>
4816 <t>The front-end can delete all MIDI instrument maps by
4817 sending the following command:</t>
4818 <t>
4819 <list>
4820 <t>REMOVE MIDI_INSTRUMENT_MAP ALL</t>
4821 </list>
4822 </t>
4823
4824 <t>Possible Answers:</t>
4825 <t>
4826 <list>
4827 <t>"OK" -
4828 <list>
4829 <t>in case the map(s) could be deleted</t>
4830 </list>
4831 </t>
4832 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4833 <list>
4834 <t>when the given map does not exist</t>
4835 </list>
4836 </t>
4837 </list>
4838 </t>
4839
4840 <t>Examples:</t>
4841 <t>
4842 <list>
4843 <t>C: "REMOVE MIDI_INSTRUMENT_MAP 0"</t>
4844 <t>S: "OK"</t>
4845 </list>
4846 </t>
4847 <t>
4848 <list>
4849 <t>C: "REMOVE MIDI_INSTRUMENT_MAP ALL"</t>
4850 <t>S: "OK"</t>
4851 </list>
4852 </t>
4853 </section>
4854
4855 <section title="Get amount of existing MIDI instrument maps" anchor="GET MIDI_INSTRUMENT_MAPS" lscp_cmd="true">
4856 <t>The front-end can retrieve the current amount of MIDI
4857 instrument maps by sending the following command:</t>
4858 <t>
4859 <list>
4860 <t>GET MIDI_INSTRUMENT_MAPS</t>
4861 </list>
4862 </t>
4863
4864 <t>Possible Answers:</t>
4865 <t>
4866 <list>
4867 <t>The sampler will answer by returning the current
4868 number of MIDI instrument maps.</t>
4869 </list>
4870 </t>
4871
4872 <t>Example:</t>
4873 <t>
4874 <list>
4875 <t>C: "GET MIDI_INSTRUMENT_MAPS"</t>
4876 <t>S: "2"</t>
4877 </list>
4878 </t>
4879 </section>
4880
4881 <section title="Getting all created MIDI instrument maps" anchor="LIST MIDI_INSTRUMENT_MAPS" lscp_cmd="true">
4882 <t>The number of MIDI instrument maps can change on runtime. To get the
4883 current list of MIDI instrument maps, the front-end can send the
4884 following command:</t>
4885 <t>
4886 <list>
4887 <t>LIST MIDI_INSTRUMENT_MAPS</t>
4888 </list>
4889 </t>
4890 <t>Possible Answers:</t>
4891 <t>
4892 <list>
4893 <t>The sampler will answer by returning a comma separated list
4894 with all MIDI instrument maps' numerical IDs.</t>
4895 </list>
4896 </t>
4897 <t>Example:</t>
4898 <t>
4899 <list>
4900 <t>C: "LIST MIDI_INSTRUMENT_MAPS"</t>
4901 <t>S: "0,1,5,12"</t>
4902 </list>
4903 </t>
4904 </section>
4905
4906 <section title="Getting MIDI instrument map information" anchor="GET MIDI_INSTRUMENT_MAP INFO" lscp_cmd="true">
4907 <t>The front-end can ask for the current settings of a MIDI
4908 instrument map by sending the following command:</t>
4909 <t>
4910 <list>
4911 <t>GET MIDI_INSTRUMENT_MAP INFO &lt;map&gt;</t>
4912 </list>
4913 </t>
4914 <t>Where &lt;map&gt; is the numerical ID of the map the
4915 front-end is interested in as returned by the
4916 <xref target="LIST MIDI_INSTRUMENT_MAPS">"LIST MIDI_INSTRUMENT_MAPS"</xref>
4917 command.</t>
4918
4919 <t>Possible Answers:</t>
4920 <t>
4921 <list>
4922 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
4923 Each answer line begins with the settings category name
4924 followed by a colon and then a space character &lt;SP&gt; and finally
4925 the info character string to that setting category. At the
4926 moment the following categories are defined:</t>
4927
4928 <t>
4929 <list>
4930 <t>NAME -
4931 <list>
4932 <t>custom name of the given map,
4933 which does not have to be unique
4934 (note that this character string may contain
4935 <xref target="character_set">escape sequences</xref>)</t>
4936 </list>
4937 </t>
4938 <t>DEFAULT -
4939 <list>
4940 <t>either true or false,
4941 defines whether this map is the default map</t>
4942 </list>
4943 </t>
4944 </list>
4945 </t>
4946 </list>
4947 </t>
4948 <t>The mentioned fields above don't have to be in particular order.</t>
4949
4950 <t>Example:</t>
4951 <t>
4952 <list>
4953 <t>C: "GET MIDI_INSTRUMENT_MAP INFO 0"</t>
4954 <t>S: "NAME: Standard Map"</t>
4955 <t>&nbsp;&nbsp;&nbsp;"DEFAULT: true"</t>
4956 <t>&nbsp;&nbsp;&nbsp;"."</t>
4957 </list>
4958 </t>
4959 </section>
4960
4961 <section title="Renaming a MIDI instrument map" anchor="SET MIDI_INSTRUMENT_MAP NAME" lscp_cmd="true">
4962 <t>The front-end can alter the custom name of a MIDI
4963 instrument map by sending the following command:</t>
4964 <t>
4965 <list>
4966 <t>SET MIDI_INSTRUMENT_MAP NAME &lt;map&gt; &lt;name&gt;</t>
4967 </list>
4968 </t>
4969 <t>Where &lt;map&gt; is the numerical ID of the map and
4970 &lt;name&gt; the new custom name of the map, which does not
4971 have to be unique (name MUST be encapsulated into apostrophes
4972 and supports escape sequences as described in chapter
4973 "<xref target="character_set">Character Set and Escape Sequences</xref>").
4974 </t>
4975
4976 <t>Possible Answers:</t>
4977 <t>
4978 <list>
4979 <t>"OK" -
4980 <list>
4981 <t>on success</t>
4982 </list>
4983 </t>
4984 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4985 <list>
4986 <t>in case the given map does not exist</t>
4987 </list>
4988 </t>
4989 </list>
4990 </t>
4991
4992 <t>Example:</t>
4993 <t>
4994 <list>
4995 <t>C: "SET MIDI_INSTRUMENT_MAP NAME 0 'Foo instruments'"</t>
4996 <t>S: "OK"</t>
4997 </list>
4998 </t>
4999 </section>
5000
5001 <section title="Create or replace a MIDI instrument map entry" anchor="MAP MIDI_INSTRUMENT" lscp_cmd="true">
5002 <t>The front-end can create a new or replace an existing entry
5003 in a sampler's MIDI instrument map by sending the following
5004 command:</t>
5005 <t>
5006 <list>
5007 <t>MAP MIDI_INSTRUMENT [NON_MODAL] &lt;map&gt;
5008 &lt;midi_bank&gt; &lt;midi_prog&gt; &lt;engine_name&gt;
5009 &lt;filename&gt; &lt;instrument_index&gt; &lt;volume_value&gt;
5010 [&lt;instr_load_mode&gt;] [&lt;name&gt;]</t>
5011 </list>
5012 </t>
5013 <t>Where &lt;map&gt; is the numeric ID of the map to alter,
5014 &lt;midi_bank&gt; is an integer value between
5015 0..16383 reflecting the MIDI bank select index,
5016 &lt;midi_prog&gt; an
5017 integer value between 0..127 reflecting the MIDI program change
5018 index, &lt;engine_name&gt; a sampler engine name as returned by
5019 the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>
5020 command (not encapsulated into apostrophes), &lt;filename&gt; the name
5021 of the instrument's file to be deployed (encapsulated into apostrophes,
5022 supporting escape sequences as described in chapter
5023 "<xref target="character_set">Character Set and Escape Sequences</xref>"),
5024 &lt;instrument_index&gt; the index (integer value) of the instrument
5025 within the given file, &lt;volume_value&gt; reflects the master
5026 volume of the instrument as optionally dotted number (where a
5027 value &lt; 1.0 means attenuation and a value > 1.0 means
5028 amplification). This parameter easily allows to adjust the
5029 volume of all intruments within a custom instrument map
5030 without having to adjust their instrument files. The
5031 OPTIONAL &lt;instr_load_mode&gt; argument defines the life
5032 time of the instrument, that is when the instrument should
5033 be loaded, when freed and has exactly the following
5034 possibilities:</t>
5035 <t>
5036 <list>
5037 <t>"ON_DEMAND" -
5038 <list>
5039 <t>The instrument will be loaded when needed,
5040 that is when demanded by at least one sampler
5041 channel. It will immediately be freed from memory
5042 when not needed by any sampler channel anymore.</t>
5043 </list>
5044 </t>
5045 <t>"ON_DEMAND_HOLD" -
5046 <list>
5047 <t>The instrument will be loaded when needed,
5048 that is when demanded by at least one sampler
5049 channel. It will be kept in memory even when
5050 not needed by any sampler channel anymore.
5051 Instruments with this mode are only freed
5052 when the sampler is reset or all mapping
5053 entries with this mode (and respective
5054 instrument) are explicitly changed to
5055 "ON_DEMAND" and no sampler channel is using
5056 the instrument anymore.</t>
5057 </list>
5058 </t>
5059 <t>"PERSISTENT" -
5060 <list>
5061 <t>The instrument will immediately be loaded
5062 into memory when this mapping
5063 command is sent and the instrument is kept all
5064 the time. Instruments with this mode are
5065 only freed when the sampler is reset or all
5066 mapping entries with this mode (and
5067 respective instrument) are explicitly
5068 changed to "ON_DEMAND" and no sampler
5069 channel is using the instrument anymore.</t>
5070 </list>
5071 </t>
5072 <t>not supplied -
5073 <list>
5074 <t>In case there is no &lt;instr_load_mode&gt;
5075 argument given, it will be up to the
5076 InstrumentManager to decide which mode to use.
5077 Usually it will use "ON_DEMAND" if an entry
5078 for the given instrument does not exist in
5079 the InstrumentManager's list yet, otherwise
5080 if an entry already exists, it will simply
5081 stick with the mode currently reflected by
5082 the already existing entry, that is it will
5083 not change the mode.</t>
5084 </list>
5085 </t>
5086 </list>
5087 </t>
5088 <t>
5089 The &lt;instr_load_mode&gt; argument thus allows to define an
5090 appropriate strategy (low memory consumption vs. fast
5091 instrument switching) for each instrument individually. Note, the
5092 following restrictions apply to this argument: "ON_DEMAND_HOLD" and
5093 "PERSISTENT" have to be supported by the respective sampler engine
5094 (which is technically the case when the engine provides an
5095 InstrumentManager for its format). If this is not the case the
5096 argument will automatically fall back to the default value
5097 "ON_DEMAND". Also the load mode of one instrument may
5098 automatically change the laod mode of other instrument(s), i.e.
5099 because the instruments are part of the same file and the
5100 engine does not allow a way to manage load modes for them
5101 individually. Due to this, in case the frontend shows the
5102 load modes of entries, the frontend should retrieve the actual
5103 mode by i.e. sending
5104 <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>
5105 command(s). Finally the OPTIONAL &lt;name&gt; argument allows to set a custom name
5106 (encapsulated into apostrophes, supporting escape sequences as described in chapter
5107 "<xref target="character_set">Character Set and Escape Sequences</xref>") for the
5108 mapping entry, useful for frontends for displaying an appropriate name for
5109 mapped instruments (using
5110 <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>).
5111 </t>
5112 <t>
5113 By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is
5114 completely established in the sampler. The OPTIONAL "NON_MODAL" argument
5115 however causes the respective "MAP MIDI_INSTRUMENT" command to return
5116 immediately, that is to let the sampler establish the mapping in the
5117 background. So this argument might be especially useful for mappings with
5118 a "PERSISTENT" type, because these have to load the respective instruments
5119 immediately and might thus block for a very long time. It is recommended
5120 however to use the OPTIONAL "NON_MODAL" argument only if really necessary,
5121 because it has the following drawbacks: as "NON_MODAL" instructions return
5122 immediately, they may not necessarily return an error i.e. when the given
5123 instrument file turns out to be corrupt, beside that subsequent commands
5124 in a LSCP instruction sequence might fail, because mandatory mappings are
5125 not yet completed.
5126 </t>
5127
5128 <t>Possible Answers:</t>
5129 <t>
5130 <list>
5131 <t>"OK" -
5132 <list>
5133 <t>usually</t>
5134 </list>
5135 </t>
5136 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5137 <list>
5138 <t>when the given map or engine does not exist or a value
5139 is out of range</t>
5140 </list>
5141 </t>
5142 </list>
5143 </t>
5144
5145 <t>Examples:</t>
5146 <t>
5147 <list>
5148 <t>C: "MAP MIDI_INSTRUMENT 0 3 0 gig '/usr/share/Steinway D.gig' 0 0.8 PERSISTENT"</t>
5149 <t>S: "OK"</t>
5150 </list>
5151 </t>
5152 <t>
5153 <list>
5154 <t>C: "MAP MIDI_INSTRUMENT 0 4 50 gig '/home/john/foostrings.gig' 7 1.0"</t>
5155 <t>S: "OK"</t>
5156 </list>
5157 </t>
5158 <t>
5159 <list>
5160 <t>C: "MAP MIDI_INSTRUMENT 0 0 0 gig '/usr/share/piano.gig' 0 1.0 'Normal Piano'"</t>
5161 <t>S: "OK"</t>
5162 <t>C: "MAP MIDI_INSTRUMENT 0 1 0 gig '/usr/share/piano.gig' 0 0.25 'Silent Piano'"</t>
5163 <t>S: "OK"</t>
5164 </list>
5165 </t>
5166 <t>
5167 <list>
5168 <t>C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"</t>
5169 <t>S: "OK"</t>
5170 </list>
5171 </t>
5172 </section>
5173
5174 <section title="Getting amount of MIDI instrument map entries" anchor="GET MIDI_INSTRUMENTS" lscp_cmd="true">
5175 <t>The front-end can query the amount of currently existing
5176 entries in a MIDI instrument map by sending the following
5177 command:</t>
5178 <t>
5179 <list>
5180 <t>GET MIDI_INSTRUMENTS &lt;map&gt;</t>
5181 </list>
5182 </t>
5183 <t>The front-end can query the amount of currently existing
5184 entries in all MIDI instrument maps by sending the following
5185 command:</t>
5186 <t>
5187 <list>
5188 <t>GET MIDI_INSTRUMENTS ALL</t>
5189 </list>
5190 </t>
5191 <t>Possible Answers:</t>
5192 <t>
5193 <list>
5194 <t>The sampler will answer by sending the current number of
5195 entries in the MIDI instrument map(s).</t>
5196 </list>
5197 </t>
5198
5199 <t>Example:</t>
5200 <t>
5201 <list>
5202 <t>C: "GET MIDI_INSTRUMENTS 0"</t>
5203 <t>S: "234"</t>
5204 </list>
5205 </t>
5206 <t>
5207 <list>
5208 <t>C: "GET MIDI_INSTRUMENTS ALL"</t>
5209 <t>S: "954"</t>
5210 </list>
5211 </t>
5212 </section>
5213
5214 <section title="Getting indeces of all entries of a MIDI instrument map" anchor="LIST MIDI_INSTRUMENTS" lscp_cmd="true">
5215 <t>The front-end can query a list of all currently existing
5216 entries in a certain MIDI instrument map by sending the following
5217 command:</t>
5218 <t>
5219 <list>
5220 <t>LIST MIDI_INSTRUMENTS &lt;map&gt;</t>
5221 </list>
5222 </t>
5223 <t>Where &lt;map&gt; is the numeric ID of the MIDI instrument map.</t>
5224 <t>The front-end can query a list of all currently existing
5225 entries of all MIDI instrument maps by sending the following
5226 command:</t>
5227 <t>
5228 <list>
5229 <t>LIST MIDI_INSTRUMENTS ALL</t>
5230 </list>
5231 </t>
5232
5233 <t>Possible Answers:</t>
5234 <t>
5235 <list>
5236 <t>The sampler will answer by sending a comma separated
5237 list of map ID - MIDI bank - MIDI program triples, where
5238 each triple is encapsulated into curly braces. The
5239 list is returned in one single line. Each triple
5240 just reflects the key of the respective map entry,
5241 thus subsequent
5242 <xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>
5243 command(s) are necessary to retrieve detailed information
5244 about each entry.</t>
5245 </list>
5246 </t>
5247
5248 <t>Example:</t>
5249 <t>
5250 <list>
5251 <t>C: "LIST MIDI_INSTRUMENTS 0"</t>
5252 <t>S: "{0,0,0},{0,0,1},{0,0,3},{0,1,4},{1,127,127}"</t>
5253 </list>
5254 </t>
5255 </section>
5256
5257 <section title="Remove an entry from the MIDI instrument map" anchor="UNMAP MIDI_INSTRUMENT" lscp_cmd="true">
5258 <t>The front-end can delete an entry from a MIDI instrument
5259 map by sending the following command:</t>
5260 <t>
5261 <list>
5262 <t>UNMAP MIDI_INSTRUMENT &lt;map&gt; &lt;midi_bank&gt; &lt;midi_prog&gt;</t>
5263 </list>
5264 </t>
5265 <t>
5266 Where &lt;map&gt; is the numeric ID of the MIDI instrument map,
5267 &lt;midi_bank&gt; is an integer value between 0..16383
5268 reflecting the MIDI bank value and
5269 &lt;midi_prog&gt; an integer value between
5270 0..127 reflecting the MIDI program value of the map's entrie's key
5271 index triple.
5272 </t>
5273
5274 <t>Possible Answers:</t>
5275 <t>
5276 <list>
5277 <t>"OK" -
5278 <list>
5279 <t>usually</t>
5280 </list>
5281 </t>
5282 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5283 <list>
5284 <t>when index out of bounds</t>
5285 </list>
5286 </t>
5287 </list>
5288 </t>
5289
5290 <t>Example:</t>
5291 <t>
5292 <list>
5293 <t>C: "UNMAP MIDI_INSTRUMENT 0 2 127"</t>
5294 <t>S: "OK"</t>
5295 </list>
5296 </t>
5297 </section>
5298
5299 <section title="Get current settings of MIDI instrument map entry" anchor="GET MIDI_INSTRUMENT INFO" lscp_cmd="true">
5300 <t>The front-end can retrieve the current settings of a certain
5301 instrument map entry by sending the following command:</t>
5302 <t>
5303 <list>
5304 <t>GET MIDI_INSTRUMENT INFO &lt;map&gt; &lt;midi_bank&gt; &lt;midi_prog&gt;</t>
5305 </list>
5306 </t>
5307 <t>
5308 Where &lt;map&gt; is the numeric ID of the MIDI instrument map,
5309 &lt;midi_bank&gt; is an integer value between 0..16383
5310 reflecting the MIDI bank value, &lt;midi_bank&gt;
5311 and &lt;midi_prog&gt; an integer value between
5312 0..127 reflecting the MIDI program value of the map's entrie's key
5313 index triple.
5314 </t>
5315
5316 <t>Possible Answers:</t>
5317 <t>
5318 <list>
5319 <t>LinuxSampler will answer by sending a &lt;CRLF&gt;
5320 separated list. Each answer line begins with the
5321 information category name followed by a colon and then
5322 a space character &lt;SP&gt; and finally the info
5323 character string to that info category. At the moment
5324 the following categories are defined:</t>
5325 <t>"NAME" -
5326 <list>
5327 <t>Name for this MIDI instrument map entry (if defined).
5328 This name shall be used by frontends for displaying a
5329 name for this mapped instrument. It can be set and
5330 changed with the
5331 <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref>
5332 command and does not have to be unique.
5333 (note that this character string may contain
5334 <xref target="character_set">escape sequences</xref>)</t>
5335 </list>
5336 </t>
5337 <t>"ENGINE_NAME" -
5338 <list>
5339 <t>Name of the engine to be deployed for this
5340 instrument.</t>
5341 </list>
5342 </t>
5343 <t>"INSTRUMENT_FILE" -
5344 <list>
5345 <t>File name of the instrument
5346 (note that this path may contain
5347 <xref target="character_set">escape sequences</xref>).</t>
5348 </list>
5349 </t>
5350 <t>"INSTRUMENT_NR" -
5351 <list>
5352 <t>Index of the instrument within the file.</t>
5353 </list>
5354 </t>
5355 <t>"INSTRUMENT_NAME" -
5356 <list>
5357 <t>Name of the loaded instrument as reflected by its file.
5358 In contrast to the "NAME" field, the "INSTRUMENT_NAME" field
5359 cannot be changed (note that this character string may contain
5360 <xref target="character_set">escape sequences</xref>).</t>
5361 </list>
5362 </t>
5363 <t>"LOAD_MODE" -
5364 <list>
5365 <t>Life time of instrument
5366 (see <xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref> for details about this setting).</t>
5367 </list>
5368 </t>
5369 <t>"VOLUME" -
5370 <list>
5371 <t>master volume of the instrument as optionally
5372 dotted number (where a value &lt; 1.0 means attenuation
5373 and a value > 1.0 means amplification)</t>
5374 </list>
5375 </t>
5376 <t>The mentioned fields above don't have to be in particular order.</t>
5377 </list>
5378 </t>
5379
5380 <t>Example:</t>
5381 <t>
5382 <list>
5383 <t>C: "GET MIDI_INSTRUMENT INFO 1 45 120"</t>
5384 <t>S: "NAME: Drums for Foo Song"</t>
5385 <t>&nbsp;&nbsp;&nbsp;"ENGINE_NAME: GigEngine"</t>
5386 <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_FILE: /usr/share/joesdrumkit.gig"</t>
5387 <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"</t>
5388 <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NAME: Joe's Drumkit"</t>
5389 <t>&nbsp;&nbsp;&nbsp;"LOAD_MODE: PERSISTENT"</t>
5390 <t>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"</t>
5391 <t>&nbsp;&nbsp;&nbsp;"."</t>
5392 </list>
5393 </t>
5394 </section>
5395
5396 <section title="Clear MIDI instrument map" anchor="CLEAR MIDI_INSTRUMENTS" lscp_cmd="true">
5397 <t>The front-end can clear a whole MIDI instrument map, that
5398 is delete all its entries by sending the following command:</t>
5399 <t>
5400 <list>
5401 <t>CLEAR MIDI_INSTRUMENTS &lt;map&gt;</t>
5402 </list>
5403 </t>
5404 <t>Where &lt;map&gt; is the numeric ID of the map to clear.</t>
5405 <t>The front-end can clear all MIDI instrument maps, that
5406 is delete all entries of all maps by sending the following
5407 command:</t>
5408 <t>
5409 <list>
5410 <t>CLEAR MIDI_INSTRUMENTS ALL</t>
5411 </list>
5412 </t>
5413 <t>The command "CLEAR MIDI_INSTRUMENTS ALL" does not delete the
5414 maps, only their entries, thus the map's settings like
5415 custom name will be preservevd.</t>
5416
5417 <t>Possible Answers:</t>
5418 <t>
5419 <list>
5420 <t>"OK" -
5421 <list>
5422 <t>always</t>
5423 </list>
5424 </t>
5425 </list>
5426 </t>
5427
5428 <t>Examples:</t>
5429 <t>
5430 <list>
5431 <t>C: "CLEAR MIDI_INSTRUMENTS 0"</t>
5432 <t>S: "OK"</t>
5433 </list>
5434 </t>
5435 <t>
5436 <list>
5437 <t>C: "CLEAR MIDI_INSTRUMENTS ALL"</t>
5438 <t>S: "OK"</t>
5439 </list>
5440 </t>
5441 </section>
5442 </section>
5443
5444
5445 <section title="Managing Instruments Database" anchor="Managing Instruments Database">
5446 <t>The following commands describe how to use and manage
5447 the instruments database.</t>
5448 <t>Notice:</t>
5449 <t>
5450 <list>
5451 <t>All command arguments representing a path or
5452 instrument/directory name support escape sequences as described in chapter
5453 "<xref target="character_set">Character Set and Escape Sequences</xref>".
5454 </t>
5455 <t>All occurrences of a forward slash in instrument and directory
5456 names are escaped with its hex (\x2f) or octal (\057) escape sequence.
5457 </t>
5458 </list>
5459 </t>
5460
5461 <section title="Creating a new instrument directory" anchor="ADD DB_INSTRUMENT_DIRECTORY" lscp_cmd="true">
5462 <t>The front-end can add a new instrument directory to the
5463 instruments database by sending the following command:</t>
5464 <t>
5465 <list>
5466 <t>ADD DB_INSTRUMENT_DIRECTORY &lt;dir&gt;</t>
5467 </list>
5468 </t>
5469 <t>Where &lt;dir&gt; is the absolute path name of the directory
5470 to be created (encapsulated into apostrophes).</t>
5471
5472 <t>Possible Answers:</t>
5473 <t>
5474 <list>
5475 <t>"OK" -
5476 <list>
5477 <t>on success</t>
5478 </list>
5479 </t>
5480 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5481 <list>
5482 <t>when the directory could not be created, which
5483 can happen if the directory already exists or the
5484 name contains not allowed symbols</t>
5485 </list>
5486 </t>
5487 </list>
5488 </t>
5489
5490 <t>Examples:</t>
5491 <t>
5492 <list>
5493 <t>C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'"</t>
5494 <t>S: "OK"</t>
5495 </list>
5496 </t>
5497 </section>
5498
5499 <section title="Deleting an instrument directory" anchor="REMOVE DB_INSTRUMENT_DIRECTORY" lscp_cmd="true">
5500 <t>The front-end can delete a particular instrument directory
5501 from the instruments database by sending the following command:</t>
5502 <t>
5503 <list>
5504 <t>REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] &lt;dir&gt;</t>
5505 </list>
5506 </t>
5507 <t>Where &lt;dir&gt; is the absolute path name of the directory
5508 to delete. The optional FORCE argument can be used to
5509 force the deletion of a non-empty directory and all its content.</t>
5510
5511 <t>Possible Answers:</t>
5512 <t>
5513 <list>
5514 <t>"OK" -
5515 <list>
5516 <t>if the directory is deleted successfully</t>
5517 </list>
5518 </t>
5519 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5520 <list>
5521 <t>if the given directory does not exist, or
5522 if trying to delete a non-empty directory,
5523 without using the FORCE argument.</t>
5524 </list>
5525 </t>
5526 </list>
5527 </t>
5528
5529 <t>Examples:</t>
5530 <t>
5531 <list>
5532 <t>C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'"</t>
5533 <t>S: "OK"</t>
5534 </list>
5535 </t>
5536 </section>
5537
5538 <section title="Getting amount of instrument directories" anchor="GET DB_INSTRUMENT_DIRECTORIES" lscp_cmd="true">
5539 <t>The front-end can retrieve the current amount of
5540 directories in a specific directory by sending the following command:</t>
5541 <t>
5542 <list>
5543 <t>GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
5544 </list>
5545 </t>
5546 <t>Where &lt;dir&gt; should be replaced by the absolute path
5547 name of the directory. If RECURSIVE is specified, the number of
5548 all directories, including those located in subdirectories of the
5549 specified directory, will be returned.</t>
5550
5551 <t>Possible Answers:</t>
5552 <t>
5553 <list>
5554 <t>The current number of instrument directories
5555 in the specified directory.</t>
5556 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5557 <list>
5558 <t>if the given directory does not exist.</t>
5559 </list>
5560 </t>
5561 </list>
5562 </t>
5563
5564 <t>Example:</t>
5565 <t>
5566 <list>
5567 <t>C: "GET DB_INSTRUMENT_DIRECTORIES '/'"</t>
5568 <t>S: "2"</t>
5569 </list>
5570 </t>
5571 </section>
5572
5573 <section title="Listing all directories in specific directory" anchor="LIST DB_INSTRUMENT_DIRECTORIES" lscp_cmd="true">
5574 <t>The front-end can retrieve the current list of directories
5575 in specific directory by sending the following command:</t>
5576 <t>
5577 <list>
5578 <t>LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;</t>
5579 </list>
5580 </t>
5581 <t>Where &lt;dir&gt; should be replaced by the absolute path
5582 name of the directory. If RECURSIVE is specified, the absolute path names
5583 of all directories, including those located in subdirectories of the
5584 specified directory, will be returned.</t>
5585
5586 <t>Possible Answers:</t>
5587 <t>
5588 <list>
5589 <t>A comma separated list of all instrument directories
5590 (encapsulated into apostrophes) in the specified directory.</t>
5591 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5592 <list>
5593 <t>if the given directory does not exist.</t>
5594 </list>
5595 </t>
5596 </list>
5597 </t>
5598 <t>Example:</t>
5599 <t>
5600 <list>
5601 <t>C: "LIST DB_INSTRUMENT_DIRECTORIES '/'"</t>
5602 <t>S: "'Piano Collection','Percussion Collection'"</t>
5603 </list>
5604 </t>
5605 <t>
5606 <list>
5607 <t>C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'"</t>
5608 <t>S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano Collection/Acoustic/New','/Percussion Collection'"</t>
5609 </list>
5610 </t>
5611 </section>
5612
5613 <section title="Getting instrument directory information" anchor="GET DB_INSTRUMENT_DIRECTORY INFO" lscp_cmd="true">
5614 <t>The front-end can ask for the current settings of an
5615 instrument directory by sending the following command:</t>
5616 <t>
5617 <list>
5618 <t>GET DB_INSTRUMENT_DIRECTORY INFO &lt;dir&gt;</t>
5619 </list>
5620 </t>
5621 <t>Where &lt;dir&gt; should be replaced by the absolute path
5622 name of the directory the front-end is interested in.</t>
5623
5624 <t>Possible Answers:</t>
5625 <t>
5626 <list>
5627 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
5628 Each answer line begins with the settings category name
5629 followed by a colon and then a space character &lt;SP&gt; and finally
5630 the info character string to that setting category. At the
5631 moment the following categories are defined:</t>
5632
5633 <t>
5634 <list>
5635 <t>DESCRIPTION -
5636 <list>
5637 <t>A brief description of the directory content.
5638 Note that the character string may contain
5639 <xref target="character_set">escape sequences</xref>.</t>
5640 </list>
5641 </t>
5642 <t>CREATED -
5643 <list>
5644 <t>The creation date and time of the directory,
5645 represented in "YYYY-MM-DD HH:MM:SS" format</t>
5646 </list>
5647 </t>
5648 <t>MODIFIED -
5649 <list>
5650 <t>The date and time of the last modification of the
5651 directory, represented in "YYYY-MM-DD HH:MM:SS" format</t>
5652 </list>
5653 </t>
5654 </list>
5655 </t>
5656 </list>
5657 </t>
5658 <t>The mentioned fields above don't have to be in particular order.</t>
5659
5660 <t>Example:</t>
5661 <t>
5662 <list>
5663 <t>C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'"</t>
5664 <t>S: "DESCRIPTION: Piano collection of instruments in GigaSampler format."</t>
5665 <t>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"</t>
5666 <t>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"</t>
5667 <t>&nbsp;&nbsp;&nbsp;"."</t>
5668 </list>
5669 </t>
5670 </section>
5671
5672 <section title="Renaming an instrument directory" anchor="SET DB_INSTRUMENT_DIRECTORY NAME" lscp_cmd="true">
5673 <t>The front-end can alter the name of a specific
5674 instrument directory by sending the following command:</t>
5675 <t>
5676 <list>
5677 <t>SET DB_INSTRUMENT_DIRECTORY NAME &lt;dir&gt; &lt;name&gt;</t>
5678 </list>
5679 </t>
5680 <t>Where &lt;dir&gt; is the absolute path name of the directory and
5681 &lt;name&gt; is the new name for that directory.</t>
5682
5683 <t>Possible Answers:</t>
5684 <t>
5685 <list>
5686 <t>"OK" -
5687 <list>
5688 <t>on success</t>
5689 </list>
5690 </t>
5691 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5692 <list>
5693 <t>in case the given directory does not exists,
5694 or if a directory with name equal to the new
5695 name already exists.</t>
5696 </list>
5697 </t>
5698 </list>
5699 </t>
5700
5701 <t>Example:</t>
5702 <t>
5703 <list>
5704 <t>C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic' 'Acoustic'"</t>
5705 <t>S: "OK"</t>
5706 </list>
5707 </t>
5708 </section>
5709
5710 <section title="Moving an instrument directory" anchor="MOVE DB_INSTRUMENT_DIRECTORY" lscp_cmd="true">
5711 <t>The front-end can move a specific
5712 instrument directory by sending the following command:</t>
5713 <t>
5714 <list>
5715 <t>MOVE DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
5716 </list>
5717 </t>
5718 <t>Where &lt;dir&gt; is the absolute path name of the directory
5719 to move and &lt;dst&gt; is the location where the directory will
5720 be moved to.</t>
5721
5722 <t>Possible Answers:</t>
5723 <t>
5724 <list>
5725 <t>"OK" -
5726 <list>
5727 <t>on success</t>
5728 </list>
5729 </t>
5730 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5731 <list>
5732 <t>in case a given directory does not exists,
5733 or if a directory with name equal to the name
5734 of the specified directory already exists in
5735 the destination directory. Error is also thrown
5736 when trying to move a directory to a subdirectory
5737 of itself.</t>
5738 </list>
5739 </t>
5740 </list>
5741 </t>
5742
5743 <t>Example:</t>
5744 <t>
5745 <list>
5746 <t>C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/Acoustic'"</t>
5747 <t>S: "OK"</t>
5748 </list>
5749 </t>
5750 </section>
5751
5752 <section title="Copying instrument directories" anchor="COPY DB_INSTRUMENT_DIRECTORY" lscp_cmd="true">
5753 <t>The front-end can copy a specific
5754 instrument directory by sending the following command:</t>
5755 <t>
5756 <list>
5757 <t>COPY DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;</t>
5758 </list>
5759 </t>
5760 <t>Where &lt;dir&gt; is the absolute path name of the directory
5761 to copy and &lt;dst&gt; is the location where the directory will
5762 be copied to.</t>
5763
5764 <t>Possible Answers:</t>
5765 <t>
5766 <list>
5767 <t>"OK" -
5768 <list>
5769 <t>on success</t>
5770 </list>
5771 </t>
5772 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5773 <list>
5774 <t>in case a given directory does not exists,
5775 or if a directory with name equal to the name
5776 of the specified directory already exists in
5777 the destination directory. Error is also thrown
5778 when trying to copy a directory to a subdirectory
5779 of itself.</t>
5780 </list>
5781 </t>
5782 </list>
5783 </t>
5784
5785 <t>Example:</t>
5786 <t>
5787 <list>
5788 <t>C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic' '/Acoustic/Pianos'"</t>
5789 <t>S: "OK"</t>
5790 </list>
5791 </t>
5792 </section>
5793
5794 <section title="Changing the description of directory" anchor="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION" lscp_cmd="true">
5795 <t>The front-end can alter the description of a specific
5796 instrument directory by sending the following command:</t>
5797 <t>
5798 <list>
5799 <t>SET DB_INSTRUMENT_DIRECTORY DESCRIPTION &lt;dir&gt; &lt;desc&gt;</t>
5800 </list>
5801 </t>
5802 <t>Where &lt;dir&gt; is the absolute path name of the directory and
5803 &lt;desc&gt; is the new description for the directory
5804 (encapsulated into apostrophes, supporting escape sequences as described in chapter
5805 "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5806
5807 <t>Possible Answers:</t>
5808 <t>
5809 <list>
5810 <t>"OK" -
5811 <list>
5812 <t>on success</t>
5813 </list>
5814 </t>
5815 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5816 <list>
5817 <t>in case the given directory does not exists.</t>
5818 </list>
5819 </t>
5820 </list>
5821 </t>
5822
5823 <t>Example:</t>
5824 <t>
5825 <list>
5826 <t>C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A collection of piano instruments in various format.'"</t>
5827 <t>S: "OK"</t>
5828 </list>
5829 </t>
5830 </section>
5831
5832 <section title="Finding directories" anchor="FIND DB_INSTRUMENT_DIRECTORIES" lscp_cmd="true">
5833 <t>The front-end can search for directories
5834 in specific directory by sending the following command:</t>
5835 <t>
5836 <list>
5837 <t>FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
5838 </list>
5839 </t>
5840 <t>Where &lt;dir&gt; should be replaced by the absolute path
5841 name of the directory to search in. If NON_RECURSIVE is specified, the
5842 directories located in subdirectories of the specified directory will not
5843 be searched. &lt;criteria-list&gt; is a list of search criterias
5844 in form of "key1=val1 key2=val2 ...". The following criterias are
5845 allowed:</t>
5846 <t>
5847 <t>NAME='&lt;search-string&gt;'
5848 <list>
5849 <t>Restricts the search to directories, which names
5850 satisfy the supplied search string (encapsulated into apostrophes,
5851 supporting escape sequences as described in chapter
5852 "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5853 </list>
5854 </t>
5855
5856 <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5857 <list>
5858 <t>Restricts the search to directories, which creation
5859 date satisfies the specified period, where &lt;date-after&gt;
5860 and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
5861 If &lt;date-after&gt; is omitted the search is restricted to
5862 directories created before &lt;date-before&gt;. If
5863 &lt;date-before&gt; is omitted, the search is restricted
5864 to directories created after &lt;date-after&gt;.</t>
5865 </list>
5866 </t>
5867
5868 <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
5869 <list>
5870 <t>Restricts the search to directories, which
5871 date of last modification satisfies the specified period, where
5872 &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
5873 format. If &lt;date-after&gt; is omitted the search is restricted to
5874 directories, which are last modified before &lt;date-before&gt;. If
5875 &lt;date-before&gt; is omitted, the search is restricted to directories,
5876 which are last modified after &lt;date-after&gt;.</t>
5877 </list>
5878 </t>
5879
5880 <t>DESCRIPTION='&lt;search-string&gt;'
5881 <list>
5882 <t>Restricts the search to directories with description
5883 that satisfies the supplied search string
5884 (encapsulated into apostrophes, supporting escape
5885 sequences as described in chapter
5886 "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5887 </list>
5888 </t>
5889 </t>
5890
5891 <t>Where &lt;search-string&gt; is either a regular expression, or a
5892 word list separated with spaces for OR search and with '+' for AND search.</t>
5893
5894 <t>Possible Answers:</t>
5895 <t>
5896 <list>
5897 <t>A comma separated list with the absolute path names (encapsulated into
5898 apostrophes) of all directories in the specified directory that satisfy
5899 the supplied search criterias.</t>
5900 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5901 <list>
5902 <t>if the given directory does not exist.</t>
5903 </list>
5904 </t>
5905 </list>
5906 </t>
5907 <t>Example:</t>
5908 <t>
5909 <list>
5910 <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'"</t>
5911 <t>S: "'/Piano Collection'"</t>
5912 </list>
5913 </t>
5914 <t>
5915 <list>
5916 <t>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:30:13'"</t>
5917 <t>S: "'/Piano Collection','/Percussions'"</t>
5918 </list>
5919 </t>
5920 </section>
5921
5922 <section title="Adding instruments to the instruments database" anchor="ADD DB_INSTRUMENTS" lscp_cmd="true">
5923 <t>The front-end can add one or more instruments
5924 to the instruments database by sending the following command:</t>
5925 <t>
5926 <list>
5927 <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>
5928 </list>
5929 </t>
5930 <t>Where &lt;db_dir&gt; is the absolute path name of a directory
5931 (encapsulated into apostrophes) in the instruments database in which
5932 only the new instruments (that are not already in the database) will
5933 be added, &lt;file_path&gt; is the absolute path name of a file or
5934 directory in the file system (encapsulated into apostrophes). In case
5935 an instrument file is supplied, only the instruments in the specified
5936 file will be added to the instruments database. If the optional
5937 &lt;instr_index&gt; (the index of the instrument within the given file)
5938 is supplied too, then only the specified instrument will be added.
5939 In case a directory is supplied, the instruments in that directory
5940 will be added. The OPTIONAL &lt;mode&gt; argument is only applied
5941 when a directory is provided as &lt;file_path&gt; and specifies how the
5942 scanning will be done and has exactly the following possibilities:</t>
5943 <t>
5944 <list>
5945 <t>"RECURSIVE" -
5946 <list>
5947 <t>All instruments will be processed, including those
5948 in the subdirectories, and the respective subdirectory
5949 tree structure will be recreated in the instruments
5950 database</t>
5951 </list>
5952 </t>
5953 <t>"NON_RECURSIVE" -
5954 <list>
5955 <t>Only the instruments in the specified directory
5956 will be added, the instruments in the subdirectories
5957 will not be processed.</t>
5958 </list>
5959 </t>
5960 <t>"FLAT" -
5961 <list>
5962 <t>All instruments will be processed, including those
5963 in the subdirectories, but the respective subdirectory
5964 structure will not be recreated in the instruments
5965 database. All instruments will be added directly in
5966 the specified database directory.</t>
5967 </list>
5968 </t>
5969 </list>
5970 </t>
5971
5972 <t> If FILE_AS_DIR argument is supplied, all instruments in an instrument
5973 file will be added to a separate directory in the instruments database, which
5974 name will be the name of the instrument file with the file extension stripped off.
5975 </t>
5976 <t>The difference between regular and NON_MODAL versions of the command
5977 is that the regular command returns when the scanning is finished
5978 while NON_MODAL version returns immediately and a background process is launched.
5979 The <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5980 command can be used to monitor the scanning progress.</t>
5981
5982 <t>Possible Answers:</t>
5983 <t>
5984 <list>
5985 <t>"OK" -
5986 <list>
5987 <t>on success when NON_MODAL is not supplied</t>
5988 </list>
5989 </t>
5990 <t>"OK[&lt;job-id&gt;]" -
5991 <list>
5992 <t>on success when NON_MODAL is supplied, where &lt;job-id&gt;
5993 is a numerical ID used to obtain status information about the job progress.
5994 See <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5995 </t>
5996 </list>
5997 </t>
5998 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5999 <list>
6000 <t>if an invalid path is specified.</t>
6001 </list>
6002 </t>
6003 </list>
6004 </t>
6005
6006 <t>Examples:</t>
6007 <t>
6008 <list>
6009 <t>C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI Bosendorfer 290.gig' 0"</t>
6010 <t>S: "OK"</t>
6011 </list>
6012 </t>
6013 </section>
6014
6015 <section title="Removing an instrument" anchor="REMOVE DB_INSTRUMENT" lscp_cmd="true">
6016 <t>The front-end can remove a particular instrument
6017 from the instruments database by sending the following command:</t>
6018 <t>
6019 <list>
6020 <t>REMOVE DB_INSTRUMENT &lt;instr_path&gt;</t>
6021 </list>
6022 </t>
6023 <t>Where &lt;instr_path&gt; is the absolute path name
6024 (in the instruments database) of the instrument to remove.</t>
6025
6026 <t>Possible Answers:</t>
6027 <t>
6028 <list>
6029 <t>"OK" -
6030 <list>
6031 <t>if the instrument is removed successfully</t>
6032 </list>
6033 </t>
6034 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6035 <list>
6036 <t>if the given path does not exist or
6037 is a directory.</t>
6038 </list>
6039 </t>
6040 </list>
6041 </t>
6042
6043 <t>Examples:</t>
6044 <t>
6045 <list>
6046 <t>C: "REMOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'"</t>
6047 <t>S: "OK"</t>
6048 </list>
6049 </t>
6050 </section>
6051
6052 <section title="Getting amount of instruments" anchor="GET DB_INSTRUMENTS" lscp_cmd="true">
6053 <t>The front-end can retrieve the current amount of
6054 instruments in a specific directory by sending the following command:</t>
6055 <t>
6056 <list>
6057 <t>GET DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
6058 </list>
6059 </t>
6060 <t>Where &lt;dir&gt; should be replaced by the absolute path name
6061 of the directory. If RECURSIVE is specified, the number of all
6062 instruments, including those located in subdirectories of the
6063 specified directory, will be returned.</t>
6064
6065 <t>Possible Answers:</t>
6066 <t>
6067 <list>
6068 <t>The current number of instruments
6069 in the specified directory.</t>
6070 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6071 <list>
6072 <t>if the given directory does not exist.</t>
6073 </list>
6074 </t>
6075 </list>
6076 </t>
6077
6078 <t>Example:</t>
6079 <t>
6080 <list>
6081 <t>C: "GET DB_INSTRUMENTS '/Piano Collection'"</t>
6082 <t>S: "2"</t>
6083 </list>
6084 </t>
6085 </section>
6086
6087 <section title="Listing all instruments in specific directory" anchor="LIST DB_INSTRUMENTS" lscp_cmd="true">
6088 <t>The front-end can retrieve the current list of instruments
6089 in specific directory by sending the following command:</t>
6090 <t>
6091 <list>
6092 <t>LIST DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;</t>
6093 </list>
6094 </t>
6095 <t>Where &lt;dir&gt; should be replaced by the absolute path
6096 name of the directory. If RECURSIVE is specified, the absolute path
6097 names of all instruments, including those located in subdirectories
6098 of the specified directory, will be returned.</t>
6099
6100 <t>Possible Answers:</t>
6101 <t>
6102 <list>
6103 <t>A comma separated list of all instruments
6104 (encapsulated into apostrophes) in the specified directory.</t>
6105 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6106 <list>
6107 <t>if the given directory does not exist.</t>
6108 </list>
6109 </t>
6110 </list>
6111 </t>
6112 <t>Example:</t>
6113 <t>
6114 <list>
6115 <t>C: "LIST DB_INSTRUMENTS '/Piano Collection'"</t>
6116 <t>S: "'Bosendorfer 290','Steinway D'"</t>
6117 </list>
6118 </t>
6119 <t>
6120 <list>
6121 <t>C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'"</t>
6122 <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D','/Piano Collection/Lite/Free Piano'"</t>
6123 </list>
6124 </t>
6125 </section>
6126
6127 <section title="Getting instrument information" anchor="GET DB_INSTRUMENT INFO" lscp_cmd="true">
6128 <t>The front-end can ask for the current settings of an
6129 instrument by sending the following command:</t>
6130 <t>
6131 <list>
6132 <t>GET DB_INSTRUMENT INFO &lt;instr_path&gt;</t>
6133 </list>
6134 </t>
6135 <t>Where &lt;instr_path&gt; should be replaced by the absolute path
6136 name of the instrument the front-end is interested in.</t>
6137
6138 <t>Possible Answers:</t>
6139 <t>
6140 <list>
6141 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6142 Each answer line begins with the settings category name
6143 followed by a colon and then a space character &lt;SP&gt; and finally
6144 the info character string to that setting category. At the
6145 moment the following categories are defined:</t>
6146
6147 <t>
6148 <list>
6149 <t>INSTRUMENT_FILE -
6150 <list>
6151 <t>File name of the instrument.
6152 Note that the character string may contain
6153 <xref target="character_set">escape sequences</xref>.</t>
6154 </list>
6155 </t>
6156 <t>INSTRUMENT_NR -
6157 <list>
6158 <t>Index of the instrument within the file.</t>
6159 </list>
6160 </t>
6161 <t>FORMAT_FAMILY -
6162 <list>
6163 <t>The format family of the instrument.</t>
6164 </list>
6165 </t>
6166 <t>FORMAT_VERSION -
6167 <list>
6168 <t>The format version of the instrument.</t>
6169 </list>
6170 </t>
6171 <t>SIZE -
6172 <list>
6173 <t>The size of the instrument in bytes.</t>
6174 </list>
6175 </t>
6176 <t>CREATED -
6177 <list>
6178 <t>The date and time when the instrument is added
6179 in the instruments database, represented in
6180 "YYYY-MM-DD HH:MM:SS" format</t>
6181 </list>
6182 </t>
6183 <t>MODIFIED -
6184 <list>
6185 <t>The date and time of the last modification of the
6186 instrument's database settings, represented in
6187 "YYYY-MM-DD HH:MM:SS" format</t>
6188 </list>
6189 </t>
6190 <t>DESCRIPTION -
6191 <list>
6192 <t>A brief description of the instrument.
6193 Note that the character string may contain
6194 <xref target="character_set">escape sequences</xref>.</t>
6195 </list>
6196 </t>
6197 <t>IS_DRUM -
6198 <list>
6199 <t>either true or false, determines whether the
6200 instrument is a drumkit or a chromatic instrument</t>
6201 </list>
6202 </t>
6203 <t>PRODUCT -
6204 <list>
6205 <t>The product title of the instrument.
6206 Note that the character string may contain
6207 <xref target="character_set">escape sequences</xref>.</t>
6208 </list>
6209 </t>
6210 <t>ARTISTS -
6211 <list>
6212 <t>Lists the artist names.
6213 Note that the character string may contain
6214 <xref target="character_set">escape sequences</xref>.</t>
6215 </list>
6216 </t>
6217 <t>KEYWORDS -
6218 <list>
6219 <t>Provides a list of keywords that refer to the instrument.
6220 Keywords are separated with semicolon and blank.
6221 Note that the character string may contain
6222 <xref target="character_set">escape sequences</xref>.</t>
6223 </list>
6224 </t>
6225 </list>
6226 </t>
6227 </list>
6228 </t>
6229 <t>The mentioned fields above don't have to be in particular order.</t>
6230
6231 <t>Example:</t>
6232 <t>
6233 <list>
6234 <t>C: "GET DB_INSTRUMENT INFO '/Piano Collection/Bosendorfer 290'"</t>
6235 <t>S: "INSTRUMENT_FILE: /home/me/gigs/Bosendorfer 290.gig"</t>
6236 <t>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"</t>
6237 <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
6238 <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 2"</t>
6239 <t>&nbsp;&nbsp;&nbsp;"SIZE: 2050871870"</t>
6240 <t>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"</t>
6241 <t>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"</t>
6242 <t>&nbsp;&nbsp;&nbsp;"DESCRIPTION: "</t>
6243 <t>&nbsp;&nbsp;&nbsp;"IS_DRUM: false"</t>
6244 <t>&nbsp;&nbsp;&nbsp;"PRODUCT: GRANDIOSO Bosendorfer 290"</t>
6245 <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Post Musical Instruments"</t>
6246 <t>&nbsp;&nbsp;&nbsp;"KEYWORDS: Bosendorfer"</t>
6247 <t>&nbsp;&nbsp;&nbsp;"."</t>
6248 </list>
6249 </t>
6250 </section>
6251
6252 <section title="Renaming an instrument" anchor="SET DB_INSTRUMENT NAME" lscp_cmd="true">
6253 <t>The front-end can alter the name of a specific
6254 instrument by sending the following command:</t>
6255 <t>
6256 <list>
6257 <t>SET DB_INSTRUMENT NAME &lt;instr&gt; &lt;name&gt;</t>
6258 </list>
6259 </t>
6260 <t>Where &lt;instr&gt; is the absolute path name of the instrument and
6261 &lt;name&gt; is the new name for that instrument.</t>
6262
6263 <t>Possible Answers:</t>
6264 <t>
6265 <list>
6266 <t>"OK" -
6267 <list>
6268 <t>on success</t>
6269 </list>
6270 </t>
6271 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6272 <list>
6273 <t>in case the given instrument does not exists,
6274 or if an instrument with name equal to the new
6275 name already exists.</t>
6276 </list>
6277 </t>
6278 </list>
6279 </t>
6280
6281 <t>Example:</t>
6282 <t>
6283 <list>
6284 <t>C: "SET DB_INSTRUMENT NAME '/Piano Collection/Bosendorfer' 'Bosendorfer 290'"</t>
6285 <t>S: "OK"</t>
6286 </list>
6287 </t>
6288 </section>
6289
6290 <section title="Moving an instrument" anchor="MOVE DB_INSTRUMENT" lscp_cmd="true">
6291 <t>The front-end can move a specific instrument to another directory by
6292 sending the following command:</t>
6293 <t>
6294 <list>
6295 <t>MOVE DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
6296 </list>
6297 </t>
6298 <t>Where &lt;instr&gt; is the absolute path name of the instrument
6299 to move and &lt;dst&gt; is the directory where the instrument will
6300 be moved to.</t>
6301
6302 <t>Possible Answers:</t>
6303 <t>
6304 <list>
6305 <t>"OK" -
6306 <list>
6307 <t>on success</t>
6308 </list>
6309 </t>
6310 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6311 <list>
6312 <t>in case the given instrument does not exists,
6313 or if an instrument with name equal to the name of the
6314 specified instrument already exists in the destination
6315 directory.</t>
6316 </list>
6317 </t>
6318 </list>
6319 </t>
6320
6321 <t>Example:</t>
6322 <t>
6323 <list>
6324 <t>C: "MOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Piano Collection/Acoustic'"</t>
6325 <t>S: "OK"</t>
6326 </list>
6327 </t>
6328 </section>
6329
6330 <section title="Copying instruments" anchor="COPY DB_INSTRUMENT" lscp_cmd="true">
6331 <t>The front-end can copy a specific instrument to another directory by
6332 sending the following command:</t>
6333 <t>
6334 <list>
6335 <t>COPY DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;</t>
6336 </list>
6337 </t>
6338 <t>Where &lt;instr&gt; is the absolute path name of the instrument
6339 to copy and &lt;dst&gt; is the directory where the instrument will
6340 be copied to.</t>
6341
6342 <t>Possible Answers:</t>
6343 <t>
6344 <list>
6345 <t>"OK" -
6346 <list>
6347 <t>on success</t>
6348 </list>
6349 </t>
6350 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6351 <list>
6352 <t>in case the given instrument does not exists,
6353 or if an instrument with name equal to the name of the
6354 specified instrument already exists in the destination
6355 directory.</t>
6356 </list>
6357 </t>
6358 </list>
6359 </t>
6360
6361 <t>Example:</t>
6362 <t>
6363 <list>
6364 <t>C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Acoustic/Pianos/'"</t>
6365 <t>S: "OK"</t>
6366 </list>
6367 </t>
6368 </section>
6369
6370 <section title="Changing the description of instrument" anchor="SET DB_INSTRUMENT DESCRIPTION" lscp_cmd="true">
6371 <t>The front-end can alter the description of a specific
6372 instrument by sending the following command:</t>
6373 <t>
6374 <list>
6375 <t>SET DB_INSTRUMENT DESCRIPTION &lt;instr&gt; &lt;desc&gt;</t>
6376 </list>
6377 </t>
6378 <t>Where &lt;instr&gt; is the absolute path name of the instrument and
6379 &lt;desc&gt; is the new description for the instrument
6380 (encapsulated into apostrophes, supporting escape sequences as described in chapter
6381 "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6382
6383 <t>Possible Answers:</t>
6384 <t>
6385 <list>
6386 <t>"OK" -
6387 <list>
6388 <t>on success</t>
6389 </list>
6390 </t>
6391 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6392 <list>
6393 <t>in case the given instrument does not exists.</t>
6394 </list>
6395 </t>
6396 </list>
6397 </t>
6398
6399 <t>Example:</t>
6400 <t>
6401 <list>
6402 <t>C: "SET DB_INSTRUMENT DESCRIPTION '/Piano Collection/Acoustic/Bosendorfer 290' 'No comment :)'"</t>
6403 <t>S: "OK"</t>
6404 </list>
6405 </t>
6406 </section>
6407
6408 <section title="Finding instruments" anchor="FIND DB_INSTRUMENTS" lscp_cmd="true">
6409 <t>The front-end can search for instruments
6410 in specific directory by sending the following command:</t>
6411 <t>
6412 <list>
6413 <t>FIND DB_INSTRUMENTS [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;</t>
6414 </list>
6415 </t>
6416 <t>Where &lt;dir&gt; should be replaced by the absolute path
6417 name of the directory to search in. If NON_RECURSIVE is specified, the
6418 directories located in subdirectories of the specified directory will not
6419 be searched. &lt;criteria-list&gt; is a list of search criterias
6420 in form of "key1=val1 key2=val2 ...". The following criterias are
6421 allowed:</t>
6422 <t>
6423 <t>NAME='&lt;search-string&gt;'
6424 <list>
6425 <t>Restricts the search to instruments, which names
6426 satisfy the supplied search string (encapsulated into apostrophes,
6427 supporting escape sequences as described in chapter
6428 "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6429 </list>
6430 </t>
6431
6432 <t>SIZE=[&lt;min&gt;]..[&lt;max&gt;]
6433 <list>
6434 <t>Restricts the search to instruments, which
6435 size is in the specified range. If &lt;min&gt; is omitted,
6436 the search results are restricted to instruments with size less then
6437 or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the
6438 search is restricted to instruments with size greater then
6439 or equal to &lt;min&gt;.</t>
6440 </list>
6441 </t>
6442
6443 <t>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
6444 <list>
6445 <t>Restricts the search to instruments, which creation
6446 date satisfies the specified period, where &lt;date-after&gt;
6447 and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
6448 If &lt;date-after&gt; is omitted the search is restricted to
6449 instruments created before &lt;date-before&gt;. If
6450 &lt;date-before&gt; is omitted, the search is restricted
6451 to instruments created after &lt;date-after&gt;.</t>
6452 </list>
6453 </t>
6454
6455 <t>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
6456 <list>
6457 <t>Restricts the search to instruments, which
6458 date of last modification satisfies the specified period, where
6459 &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
6460 format. If &lt;date-after&gt; is omitted the search is restricted to
6461 instruments, which are last modified before &lt;date-before&gt;. If
6462 &lt;date-before&gt; is omitted, the search is restricted to instruments,
6463 which are last modified after &lt;date-after&gt;.</t>
6464 </list>
6465 </t>
6466
6467 <t>DESCRIPTION='&lt;search-string&gt;'
6468 <list>
6469 <t>Restricts the search to instruments with description
6470 that satisfies the supplied search string (encapsulated into apostrophes,
6471 supporting escape sequences as described in chapter
6472 "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6473 </list>
6474 </t>
6475
6476 <t>PRODUCT='&lt;search-string&gt;'
6477 <list>
6478 <t>Restricts the search to instruments with product info
6479 that satisfies the supplied search string (encapsulated into apostrophes,
6480 supporting escape sequences as described in chapter
6481 "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6482 </list>
6483 </t>
6484
6485 <t>ARTISTS='&lt;search-string&gt;'
6486 <list>
6487 <t>Restricts the search to instruments with artists info
6488 that satisfies the supplied search string (encapsulated into apostrophes,
6489 supporting escape sequences as described in chapter
6490 "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6491 </list>
6492 </t>
6493
6494 <t>KEYWORDS='&lt;search-string&gt;'
6495 <list>
6496 <t>Restricts the search to instruments with keyword list
6497 that satisfies the supplied search string (encapsulated into apostrophes,
6498 supporting escape sequences as described in chapter
6499 "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
6500 </list>
6501 </t>
6502
6503 <t>IS_DRUM=true | false
6504 <list>
6505 <t>Either true or false. Restricts the search to
6506 drum kits or chromatic instruments.</t>
6507 </list>
6508 </t>
6509
6510 <t>FORMAT_FAMILIES='&lt;format-list&gt;'
6511 <list>
6512 <t>Restricts the search to instruments of the supplied format families,
6513 where &lt;format-list&gt; is a comma separated list of format families.</t>
6514 </list>
6515 </t>
6516 </t>
6517
6518 <t>Where &lt;search-string&gt; is either a regular expression, or a
6519 word list separated with spaces for OR search and with '+' for AND search.</t>
6520
6521 <t>Possible Answers:</t>
6522 <t>
6523 <list>
6524 <t>A comma separated list with the absolute path names (encapsulated into
6525 apostrophes) of all instruments in the specified directory that satisfy
6526 the supplied search criterias.</t>
6527 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6528 <list>
6529 <t>if the given directory does not exist.</t>
6530 </list>
6531 </t>
6532 </list>
6533 </t>
6534 <t>Example:</t>
6535 <t>
6536 <list>
6537 <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+290'"</t>
6538 <t>S: "'/Piano Collection/Bosendorfer 290'"</t>
6539 </list>
6540 </t>
6541 <t>
6542 <list>
6543 <t>C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01 09:30:13..'"</t>
6544 <t>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D'"</t>
6545 </list>
6546 </t>
6547 </section>
6548
6549 <section title="Getting job status information" anchor="GET DB_INSTRUMENTS_JOB INFO" lscp_cmd="true">
6550 <t>The front-end can ask for the current status of a
6551 particular database instruments job by sending the following command:</t>
6552 <t>
6553 <list>
6554 <t>GET DB_INSTRUMENTS_JOB INFO &lt;job-id&gt;</t>
6555 </list>
6556 </t>
6557 <t>Where &lt;job-id&gt; should be replaced by the numerical ID
6558 of the job the front-end is interested in.</t>
6559
6560 <t>Possible Answers:</t>
6561 <t>
6562 <list>
6563 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6564 Each answer line begins with the settings category name
6565 followed by a colon and then a space character &lt;SP&gt; and finally
6566 the info character string to that setting category. At the
6567 moment the following categories are defined:</t>
6568
6569 <t>
6570 <list>
6571 <t>FILES_TOTAL -
6572 <list>
6573 <t>The total number of files scheduled for scanning</t>
6574 </list>
6575 </t>
6576 <t>FILES_SCANNED -
6577 <list>
6578 <t>The current number of scanned files</t>
6579 </list>
6580 </t>
6581 <t>SCANNING -
6582 <list>
6583 <t>The absolute path name of the file which is currently
6584 being scanned</t>
6585 </list>
6586 </t>
6587 <t>STATUS -
6588 <list>
6589 <t>An integer value between 0 and 100 indicating the
6590 scanning progress percentage of the file which is
6591 currently being scanned</t>
6592 </list>
6593 </t>
6594 </list>
6595 </t>
6596 </list>
6597 </t>
6598 <t>The mentioned fields above don't have to be in particular order.</t>
6599
6600 <t>Example:</t>
6601 <t>
6602 <list>
6603 <t>C: "GET DB_INSTRUMENTS_JOB INFO 2"</t>
6604 <t>S: "FILES_TOTAL: 12"</t>
6605 <t>&nbsp;&nbsp;&nbsp;"FILES_SCANNED: 7"</t>
6606 <t>&nbsp;&nbsp;&nbsp;"SCANNING: /home/me/gigs/Bosendorfer 290.gig"</t>
6607 <t>&nbsp;&nbsp;&nbsp;"STATUS: 42"</t>
6608 <t>&nbsp;&nbsp;&nbsp;"."</t>
6609 </list>
6610 </t>
6611 </section>
6612
6613 <section title="Formatting the instruments database" anchor="FORMAT INSTRUMENTS_DB" lscp_cmd="true">
6614 <t>The front-end can remove all instruments and directories and re-create
6615 the instruments database structure (e.g., in case of a database corruption)
6616 by sending the following command:</t>
6617 <t>
6618 <list>
6619 <t>FORMAT INSTRUMENTS_DB</t>
6620 </list>
6621 </t>
6622
6623 <t>Possible Answers:</t>
6624 <t>
6625 <list>
6626 <t>"OK" -
6627 <list>
6628 <t>on success</t>
6629 </list>
6630 </t>
6631 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6632 <list>
6633 <t>If the formatting of the instruments database
6634 failed.</t>
6635 </list>
6636 </t>
6637 </list>
6638 </t>
6639 </section>
6640
6641 <section title="Checking for lost instrument files" anchor="FIND LOST DB_INSTRUMENT_FILES" lscp_cmd="true">
6642 <t>The front-end can retrieve the list of all instrument files in the instruments database
6643 that don't exist in the filesystem by sending the following command:</t>
6644 <t>
6645 <list>
6646 <t>FIND LOST DB_INSTRUMENT_FILES</t>
6647 </list>
6648 </t>
6649
6650 <t>Possible Answers:</t>
6651 <t>
6652 <list>
6653 <t>A comma separated list with the absolute path names
6654 (encapsulated into apostrophes) of all lost instrument files.</t>
6655 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6656 <list>
6657 <t>in case it failed, providing an appropriate error code and error message.</t>
6658 </list>
6659 </t>
6660 </list>
6661 </t>
6662 <t>Example:</t>
6663 <t>
6664 <list>
6665 <t>C: "FIND LOST DB_INSTRUMENT_FILES"</t>
6666 <t>S: "'/gigs/Bosendorfer 290.gig','/gigs/Steinway D.gig','/gigs/Free Piano.gig'"</t>
6667 </list>
6668 </t>
6669 </section>
6670
6671 <section title="Replacing an instrument file" anchor="SET DB_INSTRUMENT FILE_PATH" lscp_cmd="true">
6672 <t>The front-end can substitute all occurrences of an instrument file
6673 in the instruments database with a new one by sending the following command:</t>
6674 <t>
6675 <list>
6676 <t>SET DB_INSTRUMENT FILE_PATH &lt;old_path&gt; &lt;new_path&gt;</t>
6677 </list>
6678 </t>
6679 <t>Where &lt;old_path&gt; is the absolute path name of the instrument file
6680 to substitute with &lt;new_path&gt;.</t>
6681
6682 <t>Possible Answers:</t>
6683 <t>
6684 <list>
6685 <t>"OK" -
6686 <list>
6687 <t>on success</t>
6688 </list>
6689 </t>
6690 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6691 <list>
6692 <t>in case it failed, providing an appropriate error code and error message.</t>
6693 </list>
6694 </t>
6695 </list>
6696 </t>
6697
6698 <t>Example:</t>
6699 <t>
6700 <list>
6701 <t>C: "SET DB_INSTRUMENT FILE_PATH '/gigs/Bosendorfer 290.gig' '/gigs/pianos/Bosendorfer 290.gig'"</t>
6702 <t>S: "OK"</t>
6703 </list>
6704 </t>
6705 </section>
6706
6707 </section>
6708
6709
6710
6711 <section title="Editing Instruments" anchor="editing_instruments">
6712 <t>The sampler allows to edit instruments while playing with the
6713 sampler by spawning an external (3rd party) instrument editor
6714 application for a given instrument. The 3rd party instrument
6715 editor applications have to place a respective plugin DLL file
6716 into the sampler's plugins directory. The sampler will
6717 automatically try to load all plugin DLLs in that directory on
6718 startup and only on startup!</t>
6719 <t>At the moment there is only one command for this feature set,
6720 but this will most probably change in future.</t>
6721
6722 <section title="Opening an appropriate instrument editor application" anchor="EDIT INSTRUMENT" lscp_cmd="true">
6723 <t>The front-end can request to open an appropriate instrument
6724 editor application by sending the following command:</t>
6725 <t>
6726 <list>
6727 <t>EDIT CHANNEL INSTRUMENT &lt;sampler-channel&gt;</t>
6728 </list>
6729 </t>
6730 <t>Where &lt;sampler-channel&gt; should be replaced by the
6731 number of the sampler channel as given by the
6732 <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
6733 or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref>
6734 command.</t>
6735
6736 <t>The sampler will try to ask all registered instrument
6737 editors (or to be more specific: their sampler plugins)
6738 whether they are capable to handle the instrument on the
6739 given sampler channel. The sampler will simply use the first
6740 instrument editor application which replied with a positive
6741 answer and spawn that instrument editor application within
6742 the sampler's process and provide that application access
6743 to the instrument's data structures, so both applications
6744 can share and access the same instruments data at the same
6745 time, thus allowing to immediately hear changes with the
6746 sampler made by the instrument editor.</t>
6747
6748 <t>Note: consequently instrument editors are always spawned
6749 locally on the same machine where the sampler is running
6750 on!</t>
6751
6752 <t>Possible Answers:</t>
6753 <t>
6754 <list>
6755 <t>"OK" -
6756 <list>
6757 <t>when an appropriate instrument editor was
6758 launched</t>
6759 </list>
6760 </t>
6761 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6762 <list>
6763 <t>when an appropriate instrument editor was
6764 launched, but there are noteworthy issues</t>
6765 </list>
6766 </t>
6767 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6768 <list>
6769 <t>when an appropriate instrument editor
6770 could not be launched</t>
6771 </list>
6772 </t>
6773 </list>
6774 </t>
6775
6776 <t>Examples:</t>
6777 <t>
6778 <list>
6779 <t>C: "EDIT CHANNEL INSTRUMENT 0"</t>
6780 <t>S: "OK"</t>
6781 </list>
6782 </t>
6783 </section>
6784 </section>
6785
6786 <section title="Managing Files" anchor="file_management">
6787 <t>You can query detailed information about files located
6788 at the same system where the sampler instance is running on.
6789 Using this command set allows to retrieve file information
6790 even remotely from another machine.</t>
6791
6792 <section title="Retrieving amount of instruments of a file" anchor="GET FILE INSTRUMENTS" lscp_cmd="true">
6793 <t>The front-end can retrieve the amount of instruments
6794 within a given instrument file by sending the
6795 following command:</t>
6796 <t>
6797 <list>
6798 <t>GET FILE INSTRUMENTS &lt;filename&gt;</t>
6799 </list>
6800 </t>
6801 <t>Where &lt;filename&gt; is the name of the instrument
6802 file (encapsulated into apostrophes, supporting escape
6803 sequences as described in chapter
6804 "<xref target="character_set">Character Set and Escape
6805 Sequences</xref>").</t>
6806
6807 <t>The sampler will try to ask all sampler engines,
6808 whether they support the given file and ask the first
6809 engine with a positive answer for the amount of
6810 instruments.</t>
6811
6812 <t>Possible Answers:</t>
6813 <t>
6814 <list>
6815 <t>On success, the sampler will answer by
6816 returning the amount of instruments.
6817 </t>
6818 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6819 <list>
6820 <t>if the file could not be handled</t>
6821 </list>
6822 </t>
6823 </list>
6824 </t>
6825
6826 <t>Examples:</t>
6827 <t>
6828 <list>
6829 <t>C: "GET FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
6830 <t>S: "10"</t>
6831 </list>
6832 </t>
6833 </section>
6834
6835 <section title="Retrieving all instruments of a file" anchor="LIST FILE INSTRUMENTS" lscp_cmd="true">
6836 <t>The front-end can retrieve a list of all instruments
6837 within a given instrument file by sending the
6838 following command:</t>
6839 <t>
6840 <list>
6841 <t>LIST FILE INSTRUMENTS &lt;filename&gt;</t>
6842 </list>
6843 </t>
6844 <t>Where &lt;filename&gt; is the name of the instrument
6845 file (encapsulated into apostrophes, supporting escape
6846 sequences as described in chapter
6847 "<xref target="character_set">Character Set and Escape
6848 Sequences</xref>").</t>
6849
6850 <t>The sampler will try to ask all sampler engines,
6851 whether they support the given file and ask the first
6852 engine with a positive answer for a list of IDs for the
6853 instruments in the given file.</t>
6854
6855 <t>Possible Answers:</t>
6856 <t>
6857 <list>
6858 <t>On success, the sampler will answer by
6859 returning a comma separated list of
6860 instrument IDs.
6861 </t>
6862 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6863 <list>
6864 <t>if the file could not be handled</t>
6865 </list>
6866 </t>
6867 </list>
6868 </t>
6869
6870 <t>Examples:</t>
6871 <t>
6872 <list>
6873 <t>C: "LIST FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"</t>
6874 <t>S: "0,1,2,3,4,5,6,7,8,9"</t>
6875 </list>
6876 </t>
6877 </section>
6878
6879 <section title="Retrieving information about one instrument in a file" anchor="GET FILE INSTRUMENT INFO" lscp_cmd="true">
6880 <t>The front-end can retrieve detailed information
6881 about a specific instrument within a given instrument
6882 file by sending the following command:</t>
6883 <t>
6884 <list>
6885 <t>GET FILE INSTRUMENT INFO &lt;filename&gt;
6886 &lt;instr-id&gt;</t>
6887 </list>
6888 </t>
6889 <t>Where &lt;filename&gt; is the name of the instrument
6890 file (encapsulated into apostrophes, supporting escape
6891 sequences as described in chapter
6892 "<xref target="character_set">Character Set and Escape
6893 Sequences</xref>") and &lt;instr-id&gt; is the numeric
6894 instrument ID as returned by the
6895 <xref target="LIST FILE INSTRUMENTS">
6896 "LIST FILE INSTRUMENTS"</xref> command.</t>
6897
6898 <t>The sampler will try to ask all sampler engines,
6899 whether they support the given file and ask the first
6900 engine with a positive answer for information about the
6901 specific instrument in the given file.</t>
6902
6903 <t>Possible Answers:</t>
6904 <t>
6905 <list>
6906 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6907 Each answer line begins with the settings category name
6908 followed by a colon and then a space character &lt;SP&gt; and finally
6909 the info character string to that setting category. At the
6910 moment the following categories are defined:</t>
6911
6912 <t>
6913 <list>
6914 <t>NAME -
6915 <list>
6916 <t>name of the instrument as
6917 stored in the instrument file</t>
6918 </list>
6919 </t>
6920 <t>FORMAT_FAMILY -
6921 <list>
6922 <t>name of the sampler format
6923 of the given instrument</t>
6924 </list>
6925 </t>
6926 <t>FORMAT_VERSION -
6927 <list>
6928 <t>version of the sampler format
6929 the instrumen is stored as</t>
6930 </list>
6931 </t>
6932 <t>PRODUCT -
6933 <list>
6934 <t>official product name of the
6935 instrument as stored in the file
6936 </t>
6937 </list>
6938 </t>
6939 <t>ARTISTS -
6940 <list>
6941 <t>artists / sample library
6942 vendor of the instrument</t>
6943 </list>
6944 </t>
6945 <t>KEY_BINDINGS -
6946 <list>
6947 <t>comma separated list of integer values representing
6948 the instrument's key mapping in the range between 0 .. 127,
6949 reflecting the analog meaning of the MIDI specification.</t>
6950 </list>
6951 </t>
6952 <t>KEYSWITCH_BINDINGS -
6953 <list>
6954 <t>comma separated list of integer values representing
6955 the instrument's keyswitch mapping in the range between 0 .. 127,
6956 reflecting the analog meaning of the MIDI specification.</t>
6957 </list>
6958 </t>
6959 </list>
6960 </t>
6961 </list>
6962 </t>
6963 <t>The mentioned fields above don't have to be in particular order.</t>
6964
6965 <t>Example:</t>
6966 <t>
6967 <list>
6968 <t>C: "GET FILE INSTRUMENT INFO 'D:/Sounds/Foo.gig' 0"</t>
6969 <t>S: "NAME: Lunatic Loops"</t>
6970 <t>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"</t>
6971 <t>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 3"</t>
6972 <t>&nbsp;&nbsp;&nbsp;"PRODUCT: The Backbone Bongo Beats"</t>
6973 <t>&nbsp;&nbsp;&nbsp;"ARTISTS: Jimmy the Fish"</t>
6974 <t>&nbsp;&nbsp;&nbsp;"."</t>
6975 </list>
6976 </t>
6977 </section>
6978 </section>
6979 <section title="Managing Effects" anchor="effects">
6980 <t>There are two possible approaches to apply audio effects
6981 (e.g. reverb, delay, compression).
6982 You can either a) load and apply internal effects or you can b) route
6983 effect sends directly to dedicated output channels of your
6984 audio device and apply effects externally (e.g. by routing
6985 those dedicated output channels to another application).</t>
6986 <t>This chapter describes how to load and manage internal effects.
6987 If your intention is rather to apply effects externally, then
6988 you can omit this chapter. For applying effects externally, you
6989 just need to <xref target="CREATE FX_SEND">create FX sends</xref>
6990 on the respective sampler channel(s)
6991 and <xref target="SET FX_SEND AUDIO_OUTPUT_CHANNEL">adjust their destination audio channels</xref>
6992 appropriately, because by default FX sends are automatically routed
6993 directly to the audio output device.</t>
6994 <t>The sampler usually provides a set of internal audio effects.
6995 The exact set of effects depends on the availability
6996 of third party effect plugins installed on the system where the
6997 sampler runs on (e.g. LADSPA plugins).</t>
6998 <t>At the moment only "send effects" are supported. Support for
6999 "insert effects" and "master effects" is planned to be added at
7000 a later point.</t>
7001 <t>The following commands allow to retrieve the set of internal
7002 effects available to the sampler, detailed information about
7003 those effects and to create and destroy instances of such
7004 effects. After an instance of an effect is created, the effect
7005 instance can be inserted into the audio signal path of the
7006 sampler, e.g. as send effect.</t>
7007 <t>The sampler allows to create an arbitrary amount of so called
7008 send effect chains. Each effect chain can host an arbitrary
7009 amount of effect instances. The output of the first effect
7010 instance in an effect chain is fed to the input of the second
7011 effect instance of the chain and so on. So effects in one chain
7012 are processed sequentially. Send effect chains however are
7013 processed in parallel to other send effect chains. Audio signals
7014 of sampler channels are fed to send effects by creating FX sends
7015 to the respective sampler channel and assigning a destination
7016 send effect to that FX by using the
7017 <xref target="SET FX_SEND EFFECT">"SET FX_SEND EFFECT"</xref>
7018 command. The latter allows to route the FX send to the beginning
7019 of a send effect chain, as well as directly to any other
7020 position of the send effect chain.</t>
7021
7022 <section title="Retrieve amount of available effects" anchor="GET AVAILABLE_EFFECTS" lscp_cmd="true">
7023 <t>The front-end can retrieve the amount of internal
7024 effects, available to the sampler by sending
7025 the following command:</t>
7026 <t>
7027 <list>
7028 <t>GET AVAILABLE_EFFECTS</t>
7029 </list>
7030 </t>
7031
7032 <t>Possible Answers:</t>
7033 <t>
7034 <list>
7035 <t>The sampler will answer by returning the current
7036 number of effects available to the sampler.</t>
7037 </list>
7038 </t>
7039
7040 <t>Examples:</t>
7041 <t>
7042 <list>
7043 <t>C: "GET AVAILABLE_EFFECTS"</t>
7044 <t>S: "129"</t>
7045 </list>
7046 </t>
7047 </section>
7048
7049 <section title="Get list of available effects" anchor="LIST AVAILABLE_EFFECTS" lscp_cmd="true">
7050 <t>The set of available internal effects can change at
7051 runtime. The front-end can retrieve the list of internal
7052 effects, available to the sampler by sending the following
7053 command:</t>
7054 <t>
7055 <list>
7056 <t>LIST AVAILABLE_EFFECTS</t>
7057 </list>
7058 </t>
7059
7060 <t>Possible Answers:</t>
7061 <t>
7062 <list>
7063 <t>The sampler will answer by returning a comma
7064 separated list with numerical IDs of effects. Note:
7065 the numercial ID of an effect is generated by the
7066 sampler for the current moment. The numerical ID of
7067 the same effect can change at runtime, e.g. when the
7068 user requests a rescan of available effect plugins.
7069 </t>
7070 </list>
7071 </t>
7072 <t>Example:</t>
7073 <t>
7074 <list>
7075 <t>C: "LIST AVAILABLE_EFFECTS"</t>
7076 <t>S: "5,6,7,120,121,122,123,124"</t>
7077 </list>
7078 </t>
7079 </section>
7080
7081 <section title="Retrieving general information about an effect" anchor="GET EFFECT INFO" lscp_cmd="true">
7082 <t>The front-end can ask for general information about an
7083 effect by sending the following command:</t>
7084 <t>
7085 <list>
7086 <t>GET EFFECT INFO &lt;effect-index&gt;</t>
7087 </list>
7088 </t>
7089 <t>Where &lt;effect-index&gt; is the numerical ID of an
7090 effect as returned by the
7091 <xref target="LIST AVAILABLE_EFFECTS">"LIST AVAILABLE_EFFECTS"</xref>
7092 command.</t>
7093 <t>Possible Answers:</t>
7094 <t>
7095 <list>
7096 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
7097 Each answer line begins with the effect information
7098 category name, followed by a colon and then a space
7099 character &lt;SP&gt; and finally the info character
7100 string to that effect information category. At the
7101 moment the following categories are defined:</t>
7102 <t>
7103 <list>
7104 <t>SYSTEM -
7105 <list>
7106 <t>name of the effect plugin system
7107 the effect is based on
7108 (e.g. "LADSPA")</t>
7109 </list>
7110 </t>
7111 <t>MODULE -
7112 <list>
7113 <t>module of the effect plugin
7114 system that contains this effect,
7115 the module is usually the
7116 dynamic-linked library (DLL)
7117 filename of the effect plugin,
7118 including full path (note that this
7119 filename may contain
7120 <xref target="character_set">escape sequences</xref>)</t>
7121 </list>
7122 </t>
7123 <t>NAME -
7124 <list>
7125 <t>character string defining the
7126 unique name of the effect within its
7127 module (note that the character
7128 string may contain
7129 <xref target="character_set">escape sequences</xref>)</t>
7130 </list>
7131 </t>
7132 <t>DESCRIPTION -
7133 <list>
7134 <t>human readable name of the
7135 effect, intended to be displayed in
7136 user interfaces (note that the
7137 character string may contain
7138 <xref target="character_set">escape sequences</xref>)</t>
7139 </list>
7140 </t>
7141 </list>
7142 </t>
7143 </list>
7144 </t>
7145 <t>The mentioned fields above don't have to be in particular order.</t>
7146
7147 <t>Example:</t>
7148 <t>
7149 <list>
7150 <t>C: "GET EFFECT INFO 121"</t>
7151 <t>S: "SYSTEM: LADSPA"</t>
7152 <t>&nbsp;&nbsp;&nbsp;"MODULE: /usr/lib/ladspa/lowpass_iir_1891.so"</t>
7153 <t>&nbsp;&nbsp;&nbsp;"NAME: lowpass_iir"</t>
7154 <t>&nbsp;&nbsp;&nbsp;"DESCRIPTION: Glame Lowpass Filter"</t>
7155 <t>&nbsp;&nbsp;&nbsp;"."</t>
7156 </list>
7157 </t>
7158 </section>
7159
7160 <section title="Creating an instance of an effect by its portable ID" anchor="CREATE EFFECT_INSTANCE" lscp_cmd="true">
7161 <t>The front-end can spawn an instance of the desired
7162 effect by sending the following command:</t>
7163 <t>
7164 <list>
7165 <t>CREATE EFFECT_INSTANCE &lt;effect-system&gt; &lt;module&gt; &lt;effect-name&gt;</t>
7166 </list>
7167 </t>
7168 <t>Where &lt;effect-system&gt; is the "SYSTEM" field,
7169 &lt;module&gt; the "MODULE" field and &lt;effect-name&gt;
7170 the "NAME" field as returned by the
7171 <xref target="GET EFFECT INFO">"GET EFFECT INFO"</xref>
7172 command. The filename of argument &lt;module&gt; and the
7173 character string of argument &lt;effect-name&gt; may contain
7174 <xref target="character_set">escape sequences</xref>.</t>
7175
7176 <t>The sampler will try to load the requested effect and to
7177 create an instance of it. To allow loading the same effect
7178 on a different machine, probably even running a completely
7179 different operating system (e.g. Linux vs. Windows), the
7180 sampler tries to match &lt;module&gt; "softly". That means
7181 it first tries to find an effect that exactly matches the
7182 given &lt;module&gt; argument. If there is no exact match,
7183 the sampler will try to lower the restrictions on matching
7184 the &lt;module&gt; argument more and more, e.g. by ignoring
7185 upper / lower case differences and by ignoring the path of
7186 the DLL filename and file extension. If there is still no
7187 match at the end, the sampler will try to ignore the
7188 &lt;module&gt; argument completely and as a last resort
7189 search for an effect that only matches the given
7190 &lt;effect-system&gt; and &lt;effect-name&gt; arguments.</t>
7191
7192 <t>Possible Answers:</t>
7193 <t>
7194 <list>
7195 <t>"OK[&lt;effect-instance&gt;]" -
7196 <list>
7197 <t>in case the effect instance was
7198 successfully created, where
7199 &lt;effect-instance&gt; is the numerical ID
7200 of the new effect instance</t>
7201 </list>
7202 </t>
7203 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
7204 <list>
7205 <t>in case the effect instance was spawned
7206 successfully, but there are noteworthy
7207 issue(s) related, providing an appropriate
7208 warning code and warning message</t>
7209 </list>
7210 </t>
7211 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7212 <list>
7213 <t>if the effect could not be instantiated</t>
7214 </list>
7215 </t>
7216 </list>
7217 </t>
7218
7219 <t>Examples:</t>
7220 <t>
7221 <list>
7222 <t>C: "CREATE EFFECT_INSTANCE LADSPA '/usr/lib/ladspa/mod_delay_1419.so' 'modDelay'"</t>
7223 <t>S: "OK[0]"</t>
7224 </list>
7225 </t>
7226 </section>
7227
7228 <section title="Creating an instance of an effect by its numerical ID" anchor="CREATE EFFECT_INSTANCE (non-portable)">
7229 <t>The front-end can spawn an instance of the desired
7230 effect by sending the following command:</t>
7231 <t>
7232 <list>
7233 <t>CREATE EFFECT_INSTANCE &lt;effect-index&gt;</t>
7234 </list>
7235 </t>
7236 <t>Where &lt;effect-index&gt; is the numerical ID of the
7237 effect as returned by the
7238 <xref target="LIST AVAILABLE_EFFECTS">"LIST AVAILABLE_EFFECTS"</xref>
7239 command.</t>
7240
7241 <t>The sampler will try to load the requested effect and to
7242 create an instance of it.</t>
7243
7244 <t>Note: Since the numerical ID of a certain effect can
7245 change at any time, you should not use this command in
7246 LSCP files to restore a certain effect at a later time! To
7247 store a sampler session including all its effects, use the
7248 <xref target="CREATE EFFECT_INSTANCE">portable text-based
7249 version of "CREATE EFFECT_INSTANCE"</xref> instead! This
7250 allows to restore a sampler session with all its effects
7251 also on other machines, possibly even running a completely
7252 different operating system (e.g. Linux vs. Windows), with
7253 different plugin directories or plugin DLL names.</t>
7254
7255 <t>Possible Answers:</t>
7256 <t>
7257 <list>
7258 <t>"OK[&lt;effect-instance&gt;]" -
7259 <list>
7260 <t>in case the effect instance was
7261 successfully created, where
7262 &lt;effect-instance&gt; is the numerical ID
7263 of the new effect instance</t>
7264 </list>
7265 </t>
7266 <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
7267 <list>
7268 <t>in case the effect instance was spawned
7269 successfully, but there are noteworthy
7270 issue(s) related, providing an appropriate
7271 warning code and warning message</t>
7272 </list>
7273 </t>
7274 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7275 <list>
7276 <t>if the effect could not be instantiated</t>
7277 </list>
7278 </t>
7279 </list>
7280 </t>
7281
7282 <t>Examples:</t>
7283 <t>
7284 <list>
7285 <t>C: "CREATE EFFECT_INSTANCE 72"</t>
7286 <t>S: "OK[5]"</t>
7287 </list>
7288 </t>
7289 </section>
7290
7291 <section title="Destroy an effect instance" anchor="DESTROY EFFECT_INSTANCE" lscp_cmd="true">
7292 <t>The front-end can destroy an unusued effect instance and
7293 thus freeing it from memory by sending the following command:</t>
7294 <t>
7295 <list>
7296 <t>DESTROY EFFECT_INSTANCE &lt;effect-instance&gt;</t>
7297 </list>
7298 </t>
7299 <t>Where &lt;effect-instance&gt; is the numerical ID of the
7300 effect instance as returned by the
7301 <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref> or
7302 <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7303 command.</t>
7304
7305 <t>The effect instance can only be destroyed if it's not
7306 used in any part of the sampler's audio signal path anymore.
7307 If the effect instance is still in use somewhere, trying to
7308 destroy the effect instance will result in an error
7309 message.</t>
7310
7311 <t>Possible Answers:</t>
7312 <t>
7313 <list>
7314 <t>"OK" -
7315 <list>
7316 <t>in case the effect instance was successfully destroyed</t>
7317 </list>
7318 </t>
7319 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7320 <list>
7321 <t>in case it failed, providing an appropriate error code and
7322 error message</t>
7323 </list>
7324 </t>
7325 </list>
7326 </t>
7327
7328 <t>Examples:</t>
7329 <t>
7330 <list>
7331 <t>C: "DESTROY EFFECT_INSTANCE 5"</t>
7332 <t>S: "OK"</t>
7333 </list>
7334 </t>
7335 </section>
7336
7337 <section title="Retrieve amount of effect instances" anchor="GET EFFECT_INSTANCES" lscp_cmd="true">
7338 <t>The front-end can retrieve the current amount of effect
7339 instances by sending the following command:</t>
7340 <t>
7341 <list>
7342 <t>GET EFFECT_INSTANCES</t>
7343 </list>
7344 </t>
7345
7346 <t>Possible Answers:</t>
7347 <t>
7348 <list>
7349 <t>The sampler will answer by returning the current
7350 number of effect instances created and not yet
7351 destroyed in the current sampler session.</t>
7352 </list>
7353 </t>
7354
7355 <t>Examples:</t>
7356 <t>
7357 <list>
7358 <t>C: "GET EFFECT_INSTANCES"</t>
7359 <t>S: "14"</t>
7360 </list>
7361 </t>
7362 </section>
7363
7364 <section title="Get list of effect instances" anchor="LIST EFFECT_INSTANCES" lscp_cmd="true">
7365 <t>The front-end can retrieve the current list of effect
7366 instances by sending the following command:</t>
7367 <t>
7368 <list>
7369 <t>LIST EFFECT_INSTANCES</t>
7370 </list>
7371 </t>
7372
7373 <t>Possible Answers:</t>
7374 <t>
7375 <list>
7376 <t>The sampler will answer by returning a comma
7377 separated list with numerical IDs of effects
7378 instances.
7379 </t>
7380 </list>
7381 </t>
7382 <t>Example:</t>
7383 <t>
7384 <list>
7385 <t>C: "LIST EFFECT_INSTANCES"</t>
7386 <t>S: "9,11,14,15,16,17,25"</t>
7387 </list>
7388 </t>
7389 </section>
7390
7391 <section title="Retrieving current information about an effect instance" anchor="GET EFFECT_INSTANCE INFO" lscp_cmd="true">
7392 <t>The front-end can ask for the current information about
7393 a particular effect instance by sending the following command:</t>
7394 <t>
7395 <list>
7396 <t>GET EFFECT_INSTANCE INFO &lt;effect-instance&gt;</t>
7397 </list>
7398 </t>
7399 <t>Where &lt;effect-instance&gt; is the numerical ID of an
7400 effect instance as returned by the
7401 <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref>
7402 or
7403 <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7404 command.</t>
7405
7406 <t>Possible Answers:</t>
7407 <t>
7408 <list>
7409 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
7410 Each answer line begins with the information
7411 category name, followed by a colon and then a space
7412 character &lt;SP&gt; and finally the info character
7413 string to that information category. At the
7414 moment the following categories are defined:</t>
7415 <t>
7416 <list>
7417 <t>SYSTEM -
7418 <list>
7419 <t>name of the effect plugin system
7420 the effect is based on
7421 (e.g. "LADSPA")</t>
7422 </list>
7423 </t>
7424 <t>MODULE -
7425 <list>
7426 <t>module of the effect plugin
7427 system that contains this effect,
7428 the module is usually the
7429 dynamic-linked library (DLL)
7430 filename of the effect plugin,
7431 including full path (note that this
7432 filename may contain
7433 <xref target="character_set">escape sequences</xref>)</t>
7434 </list>
7435 </t>
7436 <t>NAME -
7437 <list>
7438 <t>character string defining the
7439 unique name of the effect within its
7440 module (note that the character
7441 string may contain
7442 <xref target="character_set">escape sequences</xref>)</t>
7443 </list>
7444 </t>
7445 <t>DESCRIPTION -
7446 <list>
7447 <t>human readable name of the
7448 effect, intended to be displayed in
7449 user interfaces (note that the
7450 character string may contain
7451 <xref target="character_set">escape sequences</xref>)</t>
7452 </list>
7453 </t>
7454 <t>INPUT_CONTROLS -
7455 <list>
7456 <t>amount of input controls the
7457 effect instance provides, to allow
7458 controlling the effect parameters in
7459 realtime</t>
7460 </list>
7461 </t>
7462 </list>
7463 </t>
7464 </list>
7465 </t>
7466 <t>The mentioned fields above don't have to be in particular order.</t>
7467
7468 <t>Example:</t>
7469 <t>
7470 <list>
7471 <t>C: "GET EFFECT_INSTANCE INFO 3"</t>
7472 <t>S: "SYSTEM: LADSPA"</t>
7473 <t>&nbsp;&nbsp;&nbsp;"MODULE: /usr/lib/ladspa/mod_delay_1419.so"</t>
7474 <t>&nbsp;&nbsp;&nbsp;"NAME: modDelay"</t>
7475 <t>&nbsp;&nbsp;&nbsp;"DESCRIPTION: Modulatable delay"</t>
7476 <t>&nbsp;&nbsp;&nbsp;"INPUT_CONTROLS: 1"</t>
7477 <t>&nbsp;&nbsp;&nbsp;"."</t>
7478 </list>
7479 </t>
7480 </section>
7481
7482 <section title="Retrieving information about an effect parameter" anchor="GET EFFECT_INSTANCE_INPUT_CONTROL INFO" lscp_cmd="true">
7483 <t>Effects typically provide a certain set of effect
7484 parameters which can be altered by the user in realtime
7485 (e.g. depth of a reverb effect, duration of a delay effect,
7486 dry / wet signal ratio). Those controllable effect parameters
7487 are called "input controls". The front-end can ask for the
7488 current information of an effect instance's input control
7489 by sending the following command:</t>
7490 <t>
7491 <list>
7492 <t>GET EFFECT_INSTANCE_INPUT_CONTROL INFO &lt;effect-instance&gt; &lt;input-control&gt;</t>
7493 </list>
7494 </t>
7495 <t>Where &lt;effect-instance&gt; is the numerical ID of an
7496 effect instance as returned by the
7497 <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref>
7498 or
7499 <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7500 command and &lt;input-control&gt; is the index of the input
7501 control within the numerical bounds as returned by the
7502 "INPUT_CONTROLS" field of the
7503 <xref target="GET EFFECT_INSTANCE INFO">"GET EFFECT_INSTANCE INFO"</xref>
7504 command.</t>
7505
7506 <t>Possible Answers:</t>
7507 <t>
7508 <list>
7509 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
7510 Each answer line begins with the information
7511 category name, followed by a colon and then a space
7512 character &lt;SP&gt; and finally the info character
7513 string to that information category. There are
7514 information categories which are always returned,
7515 independent of the respective effect parameter and
7516 there are optional information categories
7517 which are only shown for certain effect parameters.
7518 At the moment the following categories are defined:</t>
7519 <t>
7520 <list>
7521 <t>DESCRIPTION -
7522 <list>
7523 <t>(always returned)
7524 human readable name of the
7525 effect parameter, intended to be
7526 displayed in user interfaces (note
7527 that the character string may
7528 contain <xref target="character_set">escape sequences</xref>)</t>
7529 </list>
7530 </t>
7531 <t>VALUE -
7532 <list>
7533 <t>
7534 (always returned)
7535 current (optional dotted)
7536 floating point value of this effect
7537 parameter</t>
7538 </list>
7539 </t>
7540 <t>RANGE_MIN -
7541 <list>
7542 <t>
7543 (optionally returned)
7544 minimum allowed value for this
7545 effect parameter</t>
7546 </list>
7547 </t>
7548 <t>RANGE_MAX -
7549 <list>
7550 <t>
7551 (optionally returned)
7552 maximum allowed value for this
7553 effect parameter</t>
7554 </list>
7555 </t>
7556 <t>POSSIBILITIES -
7557 <list>
7558 <t>
7559 (optionally returned)
7560 comma separated list of
7561 (optional dotted) floating point
7562 numbers, reflecting the exact set of
7563 possible values for this effect
7564 parameter</t>
7565 </list>
7566 </t>
7567 <t>DEFAULT -
7568 <list>
7569 <t>
7570 (optionally returned)
7571 default value of this effect
7572 parameter</t>
7573 </list>
7574 </t>
7575 </list>
7576 </t>
7577 </list>
7578 </t>
7579 <t>The mentioned fields above don't have to be in particular order.</t>
7580
7581 <t>Example:</t>
7582 <t>
7583 <list>
7584 <t>C: "GET EFFECT_INSTANCE_INPUT_CONTROL INFO 1 0"</t>
7585 <t>S: "DESCRIPTION: Base delay (s)"</t>
7586 <t>&nbsp;&nbsp;&nbsp;"VALUE: 0.500"</t>
7587 <t>&nbsp;&nbsp;&nbsp;"RANGE_MIN: 0.000"</t>
7588 <t>&nbsp;&nbsp;&nbsp;"."</t>
7589 </list>
7590 </t>
7591 </section>
7592
7593 <section title="Altering an effect parameter" anchor="SET EFFECT_INSTANCE_INPUT_CONTROL VALUE" lscp_cmd="true">
7594 <t>The front-end can alter the current value of an effect
7595 parameter by sending the following command:</t>
7596 <t>
7597 <list>
7598 <t>SET EFFECT_INSTANCE_INPUT_CONTROL VALUE &lt;effect-instance&gt; &lt;input-control&gt; &lt;value&gt;</t>
7599 </list>
7600 </t>
7601 <t>Where &lt;effect-instance&gt; is the numerical ID of the
7602 effect instance as returned by the
7603 <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref> or
7604 <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7605 command, &lt;input-control&gt; is the index of the input
7606 control within the numerical bounds as returned by the
7607 "INPUT_CONTROLS" field of the
7608 <xref target="GET EFFECT_INSTANCE INFO">"GET EFFECT_INSTANCE INFO"</xref>
7609 command and &lt;value&gt; is the new (optional dotted)
7610 floating point value for this effect parameter.</t>
7611
7612 <t>Possible Answers:</t>
7613 <t>
7614 <list>
7615 <t>"OK" -
7616 <list>
7617 <t>in case the effect was altered successfully</t>
7618 </list>
7619 </t>
7620 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7621 <list>
7622 <t>in case it failed, providing an appropriate error code and
7623 error message</t>
7624 </list>
7625 </t>
7626 </list>
7627 </t>
7628
7629 <t>Examples:</t>
7630 <t>
7631 <list>
7632 <t>C: "SET EFFECT_INSTANCE_INPUT_CONTROL VALUE 0 1 0.5"</t>
7633 <t>S: "OK"</t>
7634 </list>
7635 </t>
7636 </section>
7637
7638 <section title="Retrieve amount of send effect chains" anchor="GET SEND_EFFECT_CHAINS" lscp_cmd="true">
7639 <t>The front-end can retrieve the current amount of send
7640 effect chains of an audio output device by sending the
7641 following command:</t>
7642 <t>
7643 <list>
7644 <t>GET SEND_EFFECT_CHAINS &lt;audio-device&gt;</t>
7645 </list>
7646 </t>
7647 <t>Where &lt;audio-device&gt; should be replaced by the
7648 numerical ID of the audio output device as given by the
7649 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7650 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7651 command.</t>
7652
7653 <t>Possible Answers:</t>
7654 <t>
7655 <list>
7656 <t>The sampler will answer by returning the current
7657 number of send effect chains of the supplied audio
7658 output device.</t>
7659 </list>
7660 </t>
7661
7662 <t>Examples:</t>
7663 <t>
7664 <list>
7665 <t>C: "GET SEND_EFFECT_CHAINS 0"</t>
7666 <t>S: "4"</t>
7667 </list>
7668 </t>
7669 </section>
7670
7671 <section title="Retrieve list of send effect chains" anchor="LIST SEND_EFFECT_CHAINS" lscp_cmd="true">
7672 <t>The front-end can retrieve the current list of send
7673 effect chains of an audio output device by sending the
7674 following command:</t>
7675 <t>
7676 <list>
7677 <t>LIST SEND_EFFECT_CHAINS &lt;audio-device&gt;</t>
7678 </list>
7679 </t>
7680 <t>Where &lt;audio-device&gt; should be replaced by the
7681 numerical ID of the audio output device as given by the
7682 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7683 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7684 command.</t>
7685
7686 <t>Possible Answers:</t>
7687 <t>
7688 <list>
7689 <t>The sampler will answer by returning a comma
7690 separated list with numerical IDs of send effect
7691 chains of the supplied audio output device.
7692 </t>
7693 </list>
7694 </t>
7695
7696 <t>Examples:</t>
7697 <t>
7698 <list>
7699 <t>C: "LIST SEND_EFFECT_CHAINS 0"</t>
7700 <t>S: "3,4,7"</t>
7701 </list>
7702 </t>
7703 </section>
7704
7705 <section title="Add send effect chain" anchor="ADD SEND_EFFECT_CHAIN" lscp_cmd="true">
7706 <t>The front-end can add a send effect chain by sending the
7707 following command:</t>
7708 <t>
7709 <list>
7710 <t>ADD SEND_EFFECT_CHAIN &lt;audio-device&gt;</t>
7711 </list>
7712 </t>
7713 <t>Where &lt;audio-device&gt; should be replaced by the
7714 numerical ID of the audio output device as given by the
7715 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7716 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7717 command.</t>
7718
7719 <t>Possible Answers:</t>
7720 <t>
7721 <list>
7722 <t>"OK[&lt;effect-chain&gt;]" -
7723 <list>
7724 <t>in case the send effect chain was
7725 added successfully, where
7726 &lt;effect-chain&gt; is the numerical ID
7727 of the new send effect chain</t>
7728 </list>
7729 </t>
7730 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7731 <list>
7732 <t>if the send effect chain could not be added</t>
7733 </list>
7734 </t>
7735 </list>
7736 </t>
7737
7738 <t>Examples:</t>
7739 <t>
7740 <list>
7741 <t>C: "ADD SEND_EFFECT_CHAIN 0"</t>
7742 <t>S: "OK[2]"</t>
7743 </list>
7744 </t>
7745 </section>
7746
7747 <section title="Remove send effect chain" anchor="REMOVE SEND_EFFECT_CHAIN" lscp_cmd="true">
7748 <t>The front-end can remove a send effect chain by sending
7749 the following command:</t>
7750 <t>
7751 <list>
7752 <t>REMOVE SEND_EFFECT_CHAIN &lt;audio-device&gt; &lt;effect-chain&gt;</t>
7753 </list>
7754 </t>
7755 <t>Where &lt;audio-device&gt; should be replaced by the
7756 numerical ID of the audio output device as given by the
7757 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7758 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7759 command and &lt;effect-chain&gt; by the numerical ID as
7760 returned by the
7761 <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
7762 or
7763 <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
7764 command.</t>
7765
7766 <t>Possible Answers:</t>
7767 <t>
7768 <list>
7769 <t>"OK" -
7770 <list>
7771 <t>in case the send effect chain was
7772 removed successfully</t>
7773 </list>
7774 </t>
7775 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7776 <list>
7777 <t>if the send effect chain could not be removed</t>
7778 </list>
7779 </t>
7780 </list>
7781 </t>
7782
7783 <t>Examples:</t>
7784 <t>
7785 <list>
7786 <t>C: "REMOVE SEND_EFFECT_CHAIN 0 2"</t>
7787 <t>S: "OK"</t>
7788 </list>
7789 </t>
7790 </section>
7791
7792 <section title="Retrieving information about a send effect chain" anchor="GET SEND_EFFECT_CHAIN INFO" lscp_cmd="true">
7793 <t>The front-end can ask for information of a send effect
7794 chain by sending the following command:</t>
7795 <t>
7796 <list>
7797 <t>GET SEND_EFFECT_CHAIN INFO &lt;audio-device&gt; &lt;effect-chain&gt;</t>
7798 </list>
7799 </t>
7800 <t>Where &lt;audio-device&gt; should be replaced by the
7801 numerical ID of the audio output device as given by the
7802 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7803 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7804 command and &lt;effect-chain&gt; by the numerical ID as
7805 returned by the
7806 <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
7807 or
7808 <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
7809 command.</t>
7810
7811 <t>Possible Answers:</t>
7812 <t>
7813 <list>
7814 <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
7815 Each answer line begins with the information
7816 category name, followed by a colon and then a space
7817 character &lt;SP&gt; and finally the info character
7818 string to that information category.
7819 At the moment the following categories are defined:</t>
7820 <t>
7821 <list>
7822 <t>EFFECT_COUNT -
7823 <list>
7824 <t>amount of effects in this send
7825 effect chain</t>
7826 </list>
7827 </t>
7828 <t>EFFECT_SEQUENCE -
7829 <list>
7830 <t>comma separated list of the
7831 numerical IDs of the effect
7832 instances in this send effect chain,
7833 in the order as they are procssed in
7834 the effect chain</t>
7835 </list>
7836 </t>
7837 </list>
7838 </t>
7839 </list>
7840 </t>
7841 <t>The mentioned fields above don't have to be in particular order.</t>
7842
7843 <t>Example:</t>
7844 <t>
7845 <list>
7846 <t>C: "GET SEND_EFFECT_CHAIN INFO 0 2"</t>
7847 <t>S: "EFFECT_COUNT: 3"</t>
7848 <t>&nbsp;&nbsp;&nbsp;"EFFECT_SEQUENCE: 31,4,7"</t>
7849 <t>&nbsp;&nbsp;&nbsp;"."</t>
7850 </list>
7851 </t>
7852 </section>
7853
7854 <section title="Append effect instance to a send effect chain" anchor="APPEND SEND_EFFECT_CHAIN EFFECT" lscp_cmd="true">
7855 <t>The front-end can add an unused effect instance to the
7856 end of a send effect chain by sending the following command:</t>
7857 <t>
7858 <list>
7859 <t>APPEND SEND_EFFECT_CHAIN EFFECT &lt;audio-device&gt; &lt;effect-chain&gt; &lt;effect-instance&gt;</t>
7860 </list>
7861 </t>
7862 <t>Where &lt;audio-device&gt; should be replaced by the
7863 numerical ID of the audio output device as given by the
7864 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7865 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7866 command and &lt;effect-chain&gt; by the numerical ID as
7867 returned by the
7868 <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
7869 or
7870 <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
7871 command and &lt;effect-instance&gt; as returned by the
7872 <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref> or
7873 <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7874 command.</t>
7875 <t>Only unused effect instances can be added to the effect
7876 chain. Trying to add an effect instance which is already in
7877 use somewhere in the audio signal path of the sampler will
7878 result in an error.</t>
7879
7880 <t>Possible Answers:</t>
7881 <t>
7882 <list>
7883 <t>"OK" -
7884 <list>
7885 <t>in case the effect instance was
7886 added successfully to the chain</t>
7887 </list>
7888 </t>
7889 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7890 <list>
7891 <t>if the effect instance could not be added</t>
7892 </list>
7893 </t>
7894 </list>
7895 </t>
7896
7897 <t>Examples:</t>
7898 <t>
7899 <list>
7900 <t>C: "APPEND SEND_EFFECT_CHAIN EFFECT 0 2 38"</t>
7901 <t>S: "OK"</t>
7902 </list>
7903 </t>
7904 </section>
7905
7906 <section title="Insert effect instance to a send effect chain" anchor="INSERT SEND_EFFECT_CHAIN EFFECT" lscp_cmd="true">
7907 <t>The front-end can add an unused effect instance to a
7908 certain position of a send effect chain by sending the
7909 following command:</t>
7910 <t>
7911 <list>
7912 <t>INSERT SEND_EFFECT_CHAIN EFFECT &lt;audio-device&gt; &lt;effect-chain&gt; &lt;chain-pos&gt; &lt;effect-instance&gt;</t>
7913 </list>
7914 </t>
7915 <t>Where &lt;audio-device&gt; should be replaced by the
7916 numerical ID of the audio output device as given by the
7917 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7918 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7919 command, &lt;effect-chain&gt; by the numerical ID as
7920 returned by the
7921 <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
7922 or
7923 <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
7924 command, &lt;effect-instance&gt; as returned by the
7925 <xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref> or
7926 <xref target="LIST EFFECT_INSTANCES">"LIST EFFECT_INSTANCES"</xref>
7927 command and &lt;chain-pos&gt; the exact position of the
7928 effect chain where the supplied effect shall be inserted
7929 to.</t>
7930 <t>Only unused effect instances can be added to the effect
7931 chain. Trying to add an effect instance which is already in
7932 use somewhere in the audio signal path of the sampler will
7933 result in an error.</t>
7934
7935 <t>Possible Answers:</t>
7936 <t>
7937 <list>
7938 <t>"OK" -
7939 <list>
7940 <t>in case the effect instance was
7941 added successfully to the chain</t>
7942 </list>
7943 </t>
7944 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7945 <list>
7946 <t>if the effect instance could not be added</t>
7947 </list>
7948 </t>
7949 </list>
7950 </t>
7951
7952 <t>Examples:</t>
7953 <t>
7954 <list>
7955 <t>C: "INSERT SEND_EFFECT_CHAIN EFFECT 0 2 4 38"</t>
7956 <t>S: "OK"</t>
7957 </list>
7958 </t>
7959 </section>
7960
7961 <section title="Remove effect instance from send effect chain" anchor="REMOVE SEND_EFFECT_CHAIN EFFECT" lscp_cmd="true">
7962 <t>The front-end can remove an effect instance from a
7963 certain position of a send effect chain by sending the
7964 following command:</t>
7965 <t>
7966 <list>
7967 <t>REMOVE SEND_EFFECT_CHAIN EFFECT &lt;audio-device&gt; &lt;effect-chain&gt; &lt;chain-pos&gt;</t>
7968 </list>
7969 </t>
7970 <t>Where &lt;audio-device&gt; should be replaced by the
7971 numerical ID of the audio output device as given by the
7972 <xref target="CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</xref>
7973 or <xref target="LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</xref>
7974 command, &lt;effect-chain&gt; by the numerical ID as
7975 returned by the
7976 <xref target="ADD SEND_EFFECT_CHAIN">"ADD SEND_EFFECT_CHAIN"</xref>
7977 or
7978 <xref target="LIST SEND_EFFECT_CHAINS">"LIST SEND_EFFECT_CHAINS"</xref>
7979 command and &lt;chain-pos&gt; the exact position of the
7980 effect instance to be removed from the effect chain.</t>
7981
7982 <t>Possible Answers:</t>
7983 <t>
7984 <list>
7985 <t>"OK" -
7986 <list>
7987 <t>in case the effect instance was
7988 removed successfully</t>
7989 </list>
7990 </t>
7991 <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7992 <list>
7993 <t>if the effect instance could not be removed</t>
7994 </list>
7995 </t>
7996 </list>
7997 </t>
7998
7999 <t>Examples:</t>
8000 <t>
8001 <list>
8002 <t>C: "REMOVE SEND_EFFECT_CHAIN EFFECT 0 2 4"</t>
8003 <t>S: "OK"</t>
8004 </list>
8005 </t>
8006 </section>
8007
8008 </section>
8009 </section>
8010
8011 <section title="Command Syntax" anchor="command_syntax">
8012 <t>The grammar of the control protocol as descibed in <xref target="control_commands"/>
8013 is defined below using Backus-Naur Form (BNF as described in <xref target="RFC2234"/>)
8014 where applicable.
8015 </t>
8016 <!--
8017 This section is automatically generated by scripts/update_grammar.pl
8018 from src/network/lscp.y (yacc input file). Do not modify this section
8019 manually !
8020 -->
8021 <!-- GRAMMAR_BNF_BEGIN - do NOT delete or modify this line !!! -->
8022
8023 <t>input =
8024 <list>
8025 <t>line
8026 </t>
8027 <t>/ error
8028 </t>
8029 </list>
8030 </t>
8031 <t>line =
8032 <list>
8033 <t>statement LF
8034 </t>
8035 <t>/ statement CR LF
8036 </t>
8037 </list>
8038 </t>
8039 <t>statement =
8040 <list>
8041 <t>/* epsilon (empty statement/line ignored) */
8042 </t>
8043 <t>/ comment
8044 </t>
8045 <t>/ command
8046 </t>
8047 </list>
8048 </t>
8049 <t>comment =
8050 <list>
8051 <t>'#'
8052 </t>
8053 <t>/ comment '#'
8054 </t>
8055 <t>/ comment SP
8056 </t>
8057 <t>/ comment number
8058 </t>
8059 <t>/ comment string
8060 </t>
8061 </list>
8062 </t>
8063 <t>command =
8064 <list>
8065 <t>ADD SP add_instruction
8066 </t>
8067 <t>/ MAP SP map_instruction
8068 </t>
8069 <t>/ UNMAP SP unmap_instruction
8070 </t>
8071 <t>/ GET SP get_instruction
8072 </t>
8073 <t>/ CREATE SP create_instruction
8074 </t>
8075 <t>/ DESTROY SP destroy_instruction
8076 </t>
8077 <t>/ LIST SP list_instruction
8078 </t>
8079 <t>/ LOAD SP load_instruction
8080 </t>
8081 <t>/ REMOVE SP remove_instruction
8082 </t>
8083 <t>/ SET SP set_instruction
8084 </t>
8085 <t>/ SUBSCRIBE SP subscribe_event
8086 </t>
8087 <t>/ UNSUBSCRIBE SP unsubscribe_event
8088 </t>
8089 <t>/ RESET SP reset_instruction
8090 </t>
8091 <t>/ CLEAR SP clear_instruction
8092 </t>
8093 <t>/ FIND SP find_instruction
8094 </t>
8095 <t>/ MOVE SP move_instruction
8096 </t>
8097 <t>/ COPY SP copy_instruction
8098 </t>
8099 <t>/ EDIT SP edit_instruction
8100 </t>
8101 <t>/ FORMAT SP format_instruction
8102 </t>
8103 <t>/ SEND SP send_instruction
8104 </t>
8105 <t>/ APPEND SP append_instruction
8106 </t>
8107 <t>/ INSERT SP insert_instruction
8108 </t>
8109 <t>/ RESET
8110 </t>
8111 <t>/ QUIT
8112 </t>
8113 </list>
8114 </t>
8115 <t>add_instruction =
8116 <list>
8117 <t>CHANNEL
8118 </t>
8119 <t>/ CHANNEL SP MIDI_INPUT SP sampler_channel SP device_index
8120 </t>
8121 <t>/ CHANNEL SP MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index
8122 </t>
8123 <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
8124 </t>
8125 <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename
8126 </t>
8127 <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP FILE_AS_DIR SP db_path SP filename
8128 </t>
8129 <t>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename
8130 </t>
8131 <t>/ DB_INSTRUMENTS SP scan_mode SP FILE_AS_DIR SP db_path SP filename
8132 </t>
8133 <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
8134 </t>
8135 <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index
8136 </t>
8137 <t>/ DB_INSTRUMENTS SP db_path SP filename
8138 </t>
8139 <t>/ DB_INSTRUMENTS SP db_path SP filename SP instrument_index
8140 </t>
8141 <t>/ MIDI_INSTRUMENT_MAP
8142 </t>
8143 <t>/ MIDI_INSTRUMENT_MAP SP map_name
8144 </t>
8145 <t>/ SEND_EFFECT_CHAIN SP device_index
8146 </t>
8147 </list>
8148 </t>
8149 <t>subscribe_event =
8150 <list>
8151 <t>AUDIO_OUTPUT_DEVICE_COUNT
8152 </t>
8153 <t>/ AUDIO_OUTPUT_DEVICE_INFO
8154 </t>
8155 <t>/ MIDI_INPUT_DEVICE_COUNT
8156 </t>
8157 <t>/ MIDI_INPUT_DEVICE_INFO
8158 </t>
8159 <t>/ CHANNEL_COUNT
8160 </t>
8161 <t>/ CHANNEL_MIDI
8162 </t>
8163 <t>/ DEVICE_MIDI
8164 </t>
8165 <t>/ VOICE_COUNT
8166 </t>
8167 <t>/ STREAM_COUNT
8168 </t>
8169 <t>/ BUFFER_FILL
8170 </t>
8171 <t>/ CHANNEL_INFO
8172 </t>
8173 <t>/ FX_SEND_COUNT
8174 </t>
8175 <t>/ FX_SEND_INFO
8176 </t>
8177 <t>/ MIDI_INSTRUMENT_MAP_COUNT
8178 </t>
8179 <t>/ MIDI_INSTRUMENT_MAP_INFO
8180 </t>
8181 <t>/ MIDI_INSTRUMENT_COUNT
8182 </t>
8183 <t>/ MIDI_INSTRUMENT_INFO
8184 </t>
8185 <t>/ DB_INSTRUMENT_DIRECTORY_COUNT
8186 </t>
8187 <t>/ DB_INSTRUMENT_DIRECTORY_INFO
8188 </t>
8189 <t>/ DB_INSTRUMENT_COUNT
8190 </t>
8191 <t>/ DB_INSTRUMENT_INFO
8192 </t>
8193 <t>/ DB_INSTRUMENTS_JOB_INFO
8194 </t>
8195 <t>/ MISCELLANEOUS
8196 </t>
8197 <t>/ TOTAL_STREAM_COUNT
8198 </t>
8199 <t>/ TOTAL_VOICE_COUNT
8200 </t>
8201 <t>/ GLOBAL_INFO
8202 </t>
8203 <t>/ EFFECT_INSTANCE_COUNT
8204 </t>
8205 <t>/ EFFECT_INSTANCE_INFO
8206 </t>
8207 <t>/ SEND_EFFECT_CHAIN_COUNT
8208 </t>
8209 <t>/ SEND_EFFECT_CHAIN_INFO
8210 </t>
8211 </list>
8212 </t>
8213 <t>unsubscribe_event =
8214 <list>
8215 <t>AUDIO_OUTPUT_DEVICE_COUNT
8216 </t>
8217 <t>/ AUDIO_OUTPUT_DEVICE_INFO
8218 </t>
8219 <t>/ MIDI_INPUT_DEVICE_COUNT
8220 </t>
8221 <t>/ MIDI_INPUT_DEVICE_INFO
8222 </t>
8223 <t>/ CHANNEL_COUNT
8224 </t>
8225 <t>/ CHANNEL_MIDI
8226 </t>
8227 <t>/ DEVICE_MIDI
8228 </t>
8229 <t>/ VOICE_COUNT
8230 </t>
8231 <t>/ STREAM_COUNT
8232 </t>
8233 <t>/ BUFFER_FILL
8234 </t>
8235 <t>/ CHANNEL_INFO
8236 </t>
8237 <t>/ FX_SEND_COUNT
8238 </t>
8239 <t>/ FX_SEND_INFO
8240 </t>
8241 <t>/ MIDI_INSTRUMENT_MAP_COUNT
8242 </t>
8243 <t>/ MIDI_INSTRUMENT_MAP_INFO
8244 </t>
8245 <t>/ MIDI_INSTRUMENT_COUNT
8246 </t>
8247 <t>/ MIDI_INSTRUMENT_INFO
8248 </t>
8249 <t>/ DB_INSTRUMENT_DIRECTORY_COUNT
8250 </t>
8251 <t>/ DB_INSTRUMENT_DIRECTORY_INFO
8252 </t>
8253 <t>/ DB_INSTRUMENT_COUNT
8254 </t>
8255 <t>/ DB_INSTRUMENT_INFO
8256 </t>
8257 <t>/ DB_INSTRUMENTS_JOB_INFO
8258 </t>
8259 <t>/ MISCELLANEOUS
8260 </t>
8261 <t>/ TOTAL_STREAM_COUNT
8262 </t>
8263 <t>/ TOTAL_VOICE_COUNT
8264 </t>
8265 <t>/ GLOBAL_INFO
8266 </t>
8267 <t>/ EFFECT_INSTANCE_COUNT
8268 </t>
8269 <t>/ EFFECT_INSTANCE_INFO
8270 </t>
8271 <t>/ SEND_EFFECT_CHAIN_COUNT
8272 </t>
8273 <t>/ SEND_EFFECT_CHAIN_INFO
8274 </t>
8275 </list>
8276 </t>
8277 <t>map_instruction =
8278 <list>
8279 <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
8280 </t>
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 SP instr_load_mode
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 entry_name
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 instr_load_mode SP entry_name
8286 </t>
8287 </list>
8288 </t>
8289 <t>unmap_instruction =
8290 <list>
8291 <t>MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog
8292 </t>
8293 </list>
8294 </t>
8295 <t>remove_instruction =
8296 <list>
8297 <t>CHANNEL SP sampler_channel
8298 </t>
8299 <t>/ CHANNEL SP MIDI_INPUT SP sampler_channel
8300 </t>
8301 <t>/ CHANNEL SP MIDI_INPUT SP sampler_channel SP device_index
8302 </t>
8303 <t>/ CHANNEL SP MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index
8304 </t>
8305 <t>/ MIDI_INSTRUMENT_MAP SP midi_map
8306 </t>
8307 <t>/ MIDI_INSTRUMENT_MAP SP ALL
8308 </t>
8309 <t>/ SEND_EFFECT_CHAIN SP device_index SP effect_chain
8310 </t>
8311 <t>/ SEND_EFFECT_CHAIN SP EFFECT SP device_index SP effect_chain SP chain_pos
8312 </t>
8313 <t>/ FX_SEND SP EFFECT SP sampler_channel SP fx_send_id
8314 </t>
8315 <t>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path
8316 </t>
8317 <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
8318 </t>
8319 <t>/ DB_INSTRUMENT SP db_path
8320 </t>
8321 </list>
8322 </t>
8323 <t>get_instruction =
8324 <list>
8325 <t>AVAILABLE_ENGINES
8326 </t>
8327 <t>/ AVAILABLE_EFFECTS
8328 </t>
8329 <t>/ EFFECT_INSTANCES
8330 </t>
8331 <t>/ EFFECT SP INFO SP effect_index
8332 </t>
8333 <t>/ EFFECT_INSTANCE SP INFO SP effect_instance
8334 </t>
8335 <t>/ EFFECT_INSTANCE_INPUT_CONTROL SP INFO SP effect_instance SP input_control
8336 </t>
8337 <t>/ SEND_EFFECT_CHAINS SP device_index
8338 </t>
8339 <t>/ SEND_EFFECT_CHAIN SP INFO SP device_index SP effect_chain
8340 </t>
8341 <t>/ AVAILABLE_MIDI_INPUT_DRIVERS
8342 </t>
8343 <t>/ MIDI_INPUT_DRIVER SP INFO SP string
8344 </t>
8345 <t>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
8346 </t>
8347 <t>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
8348 </t>
8349 <t>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
8350 </t>
8351 <t>/ AUDIO_OUTPUT_DRIVER SP INFO SP string
8352 </t>
8353 <t>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
8354 </t>
8355 <t>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
8356 </t>
8357 <t>/ AUDIO_OUTPUT_DEVICES
8358 </t>
8359 <t>/ MIDI_INPUT_DEVICES
8360 </t>
8361 <t>/ AUDIO_OUTPUT_DEVICE SP INFO SP number
8362 </t>
8363 <t>/ MIDI_INPUT_DEVICE SP INFO SP number
8364 </t>
8365 <t>/ MIDI_INPUT_PORT SP INFO SP number SP number
8366 </t>
8367 <t>/ MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
8368 </t>
8369 <t>/ AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
8370 </t>
8371 <t>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP string
8372 </t>
8373 <t>/ CHANNELS
8374 </t>
8375 <t>/ CHANNEL SP INFO SP sampler_channel
8376 </t>
8377 <t>/ CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
8378 </t>
8379 <t>/ CHANNEL SP STREAM_COUNT SP sampler_channel
8380 </t>
8381 <t>/ CHANNEL SP VOICE_COUNT SP sampler_channel
8382 </t>
8383 <t>/ ENGINE SP INFO SP engine_name
8384 </t>
8385 <t>/ SERVER SP INFO
8386 </t>
8387 <t>/ TOTAL_STREAM_COUNT
8388 </t>
8389 <t>/ TOTAL_VOICE_COUNT
8390 </t>
8391 <t>/ TOTAL_VOICE_COUNT_MAX
8392 </t>
8393 <t>/ MIDI_INSTRUMENTS SP midi_map
8394 </t>
8395 <t>/ MIDI_INSTRUMENTS SP ALL
8396 </t>
8397 <t>/ MIDI_INSTRUMENT SP INFO SP midi_map SP midi_bank SP midi_prog
8398 </t>
8399 <t>/ MIDI_INSTRUMENT_MAPS
8400 </t>
8401 <t>/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map
8402 </t>
8403 <t>/ FX_SENDS SP sampler_channel
8404 </t>
8405 <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
8406 </t>
8407 <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
8408 </t>
8409 <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
8410 </t>
8411 <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP db_path
8412 </t>
8413 <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
8414 </t>
8415 <t>/ DB_INSTRUMENTS SP db_path
8416 </t>
8417 <t>/ DB_INSTRUMENT SP INFO SP db_path
8418 </t>
8419 <t>/ DB_INSTRUMENTS_JOB SP INFO SP number
8420 </t>
8421 <t>/ VOLUME
8422 </t>
8423 <t>/ VOICES
8424 </t>
8425 <t>/ STREAMS
8426 </t>
8427 <t>/ FILE SP INSTRUMENTS SP filename
8428 </t>
8429 <t>/ FILE SP INSTRUMENT SP INFO SP filename SP instrument_index
8430 </t>
8431 </list>
8432 </t>
8433 <t>set_instruction =
8434 <list>
8435 <t>AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
8436 </t>
8437 <t>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '=' param_val_list
8438 </t>
8439 <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
8440 </t>
8441 <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE
8442 </t>
8443 <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list
8444 </t>
8445 <t>/ EFFECT_INSTANCE_INPUT_CONTROL SP VALUE SP effect_instance SP input_control SP control_value
8446 </t>
8447 <t>/ CHANNEL SP set_chan_instruction
8448 </t>
8449 <t>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
8450 </t>
8451 <t>/ FX_SEND SP NAME SP sampler_channel SP fx_send_id SP fx_send_name
8452 </t>
8453 <t>/ FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id SP audio_channel_index SP audio_channel_index
8454 </t>
8455 <t>/ FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP midi_ctrl
8456 </t>
8457 <t>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
8458 </t>
8459 <t>/ FX_SEND SP EFFECT SP sampler_channel SP fx_send_id SP effect_chain SP chain_pos
8460 </t>
8461 <t>/ DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped
8462 </t>
8463 <t>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped
8464 </t>
8465 <t>/ DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped
8466 </t>
8467 <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
8468 </t>
8469 <t>/ DB_INSTRUMENT SP FILE_PATH SP filename SP filename
8470 </t>
8471 <t>/ ECHO SP boolean
8472 </t>
8473 <t>/ SHELL SP INTERACT SP boolean
8474 </t>
8475 <t>/ SHELL SP AUTO_CORRECT SP boolean
8476 </t>
8477 <t>/ SHELL SP DOC SP boolean
8478 </t>
8479 <t>/ VOLUME SP volume_value
8480 </t>
8481 <t>/ VOICES SP number
8482 </t>
8483 <t>/ STREAMS SP number
8484 </t>
8485 </list>
8486 </t>
8487 <t>create_instruction =
8488 <list>
8489 <t>AUDIO_OUTPUT_DEVICE SP string SP key_val_list
8490 </t>
8491 <t>/ AUDIO_OUTPUT_DEVICE SP string
8492 </t>
8493 <t>/ MIDI_INPUT_DEVICE SP string SP key_val_list
8494 </t>
8495 <t>/ MIDI_INPUT_DEVICE SP string
8496 </t>
8497 <t>/ FX_SEND SP sampler_channel SP midi_ctrl
8498 </t>
8499 <t>/ FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name
8500 </t>
8501 <t>/ EFFECT_INSTANCE SP effect_index
8502 </t>
8503 <t>/ EFFECT_INSTANCE SP effect_system SP module SP effect_name
8504 </t>
8505 </list>
8506 </t>
8507 <t>reset_instruction =
8508 <list>
8509 <t>CHANNEL SP sampler_channel
8510 </t>
8511 </list>
8512 </t>
8513 <t>clear_instruction =
8514 <list>
8515 <t>MIDI_INSTRUMENTS SP midi_map
8516 </t>
8517 <t>/ MIDI_INSTRUMENTS SP ALL
8518 </t>
8519 </list>
8520 </t>
8521 <t>find_instruction =
8522 <list>
8523 <t>DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list
8524 </t>
8525 <t>/ DB_INSTRUMENTS SP db_path SP query_val_list
8526 </t>
8527 <t>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP query_val_list
8528 </t>
8529 <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
8530 </t>
8531 <t>/ LOST SP DB_INSTRUMENT_FILES
8532 </t>
8533 </list>
8534 </t>
8535 <t>move_instruction =
8536 <list>
8537 <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
8538 </t>
8539 <t>/ DB_INSTRUMENT SP db_path SP db_path
8540 </t>
8541 </list>
8542 </t>
8543 <t>copy_instruction =
8544 <list>
8545 <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
8546 </t>
8547 <t>/ DB_INSTRUMENT SP db_path SP db_path
8548 </t>
8549 </list>
8550 </t>
8551 <t>destroy_instruction =
8552 <list>
8553 <t>AUDIO_OUTPUT_DEVICE SP number
8554 </t>
8555 <t>/ MIDI_INPUT_DEVICE SP number
8556 </t>
8557 <t>/ FX_SEND SP sampler_channel SP fx_send_id
8558 </t>
8559 <t>/ EFFECT_INSTANCE SP number
8560 </t>
8561 </list>
8562 </t>
8563 <t>load_instruction =
8564 <list>
8565 <t>INSTRUMENT SP load_instr_args
8566 </t>
8567 <t>/ ENGINE SP load_engine_args
8568 </t>
8569 </list>
8570 </t>
8571 <t>append_instruction =
8572 <list>
8573 <t>SEND_EFFECT_CHAIN SP EFFECT SP device_index SP effect_chain SP effect_instance
8574 </t>
8575 </list>
8576 </t>
8577 <t>insert_instruction =
8578 <list>
8579 <t>SEND_EFFECT_CHAIN SP EFFECT SP device_index SP effect_chain SP chain_pos SP effect_instance
8580 </t>
8581 </list>
8582 </t>
8583 <t>set_chan_instruction =
8584 <list>
8585 <t>AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
8586 </t>
8587 <t>/ AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index SP audio_channel_index
8588 </t>
8589 <t>/ AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
8590 </t>
8591 <t>/ MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index SP midi_input_channel_index
8592 </t>
8593 <t>/ MIDI_INPUT_DEVICE SP sampler_channel SP device_index
8594 </t>
8595 <t>/ MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
8596 </t>
8597 <t>/ MIDI_INPUT_CHANNEL SP sampler_channel SP midi_input_channel_index
8598 </t>
8599 <t>/ MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
8600 </t>
8601 <t>/ VOLUME SP sampler_channel SP volume_value
8602 </t>
8603 <t>/ MUTE SP sampler_channel SP boolean
8604 </t>
8605 <t>/ SOLO SP sampler_channel SP boolean
8606 </t>
8607 <t>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP midi_map
8608 </t>
8609 <t>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP NONE
8610 </t>
8611 <t>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP DEFAULT
8612 </t>
8613 </list>
8614 </t>
8615 <t>edit_instruction =
8616 <list>
8617 <t>CHANNEL SP INSTRUMENT SP sampler_channel
8618 </t>
8619 </list>
8620 </t>
8621 <t>format_instruction =
8622 <list>
8623 <t>INSTRUMENTS_DB
8624 </t>
8625 </list>
8626 </t>
8627 <t>modal_arg =
8628 <list>
8629 <t>/* epsilon (empty argument) */
8630 </t>
8631 <t>/ NON_MODAL SP
8632 </t>
8633 </list>
8634 </t>
8635 <t>key_val_list =
8636 <list>
8637 <t>string '=' param_val_list
8638 </t>
8639 <t>/ key_val_list SP string '=' param_val_list
8640 </t>
8641 </list>
8642 </t>
8643 <t>buffer_size_type =
8644 <list>
8645 <t>BYTES
8646 </t>
8647 <t>/ PERCENTAGE
8648 </t>
8649 </list>
8650 </t>
8651 <t>list_instruction =
8652 <list>
8653 <t>AUDIO_OUTPUT_DEVICES
8654 </t>
8655 <t>/ MIDI_INPUT_DEVICES
8656 </t>
8657 <t>/ CHANNELS
8658 </t>
8659 <t>/ CHANNEL SP MIDI_INPUTS SP sampler_channel
8660 </t>
8661 <t>/ AVAILABLE_ENGINES
8662 </t>
8663 <t>/ AVAILABLE_EFFECTS
8664 </t>
8665 <t>/ EFFECT_INSTANCES
8666 </t>
8667 <t>/ SEND_EFFECT_CHAINS SP number
8668 </t>
8669 <t>/ AVAILABLE_MIDI_INPUT_DRIVERS
8670 </t>
8671 <t>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
8672 </t>
8673 <t>/ MIDI_INSTRUMENTS SP midi_map
8674 </t>
8675 <t>/ MIDI_INSTRUMENTS SP ALL
8676 </t>
8677 <t>/ MIDI_INSTRUMENT_MAPS
8678 </t>
8679 <t>/ FX_SENDS SP sampler_channel
8680 </t>
8681 <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
8682 </t>
8683 <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
8684 </t>
8685 <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
8686 </t>
8687 <t>/ DB_INSTRUMENTS SP db_path
8688 </t>
8689 <t>/ FILE SP INSTRUMENTS SP filename
8690 </t>
8691 </list>
8692 </t>
8693 <t>send_instruction =
8694 <list>
8695 <t>CHANNEL SP MIDI_DATA SP string SP sampler_channel SP number SP number
8696 </t>
8697 </list>
8698 </t>
8699 <t>load_instr_args =
8700 <list>
8701 <t>filename SP instrument_index SP sampler_channel
8702 </t>
8703 <t>/ NON_MODAL SP filename SP instrument_index SP sampler_channel
8704 </t>
8705 </list>
8706 </t>
8707 <t>load_engine_args =
8708 <list>
8709 <t>engine_name SP sampler_channel
8710 </t>
8711 </list>
8712 </t>
8713 <t>instr_load_mode =
8714 <list>
8715 <t>ON_DEMAND
8716 </t>
8717 <t>/ ON_DEMAND_HOLD
8718 </t>
8719 <t>/ PERSISTENT
8720 </t>
8721 </list>
8722 </t>
8723 <t>effect_instance =
8724 <list>
8725 <t>number
8726 </t>
8727 </list>
8728 </t>
8729 <t>device_index =
8730 <list>
8731 <t>number
8732 </t>
8733 </list>
8734 </t>
8735 <t>audio_channel_index =
8736 <list>
8737 <t>number
8738 </t>
8739 </list>
8740 </t>
8741 <t>audio_output_type_name =
8742 <list>
8743 <t>string
8744 </t>
8745 </list>
8746 </t>
8747 <t>midi_input_port_index =
8748 <list>
8749 <t>number
8750 </t>
8751 </list>
8752 </t>
8753 <t>midi_input_channel_index =
8754 <list>
8755 <t>number
8756 </t>
8757 <t>/ ALL
8758 </t>
8759 </list>
8760 </t>
8761 <t>midi_input_type_name =
8762 <list>
8763 <t>string
8764 </t>
8765 </list>
8766 </t>
8767 <t>midi_map =
8768 <list>
8769 <t>number
8770 </t>
8771 </list>
8772 </t>
8773 <t>midi_bank =
8774 <list>
8775 <t>number
8776 </t>
8777 </list>
8778 </t>
8779 <t>midi_prog =
8780 <list>
8781 <t>number
8782 </t>
8783 </list>
8784 </t>
8785 <t>midi_ctrl =
8786 <list>
8787 <t>number
8788 </t>
8789 </list>
8790 </t>
8791 <t>volume_value =
8792 <list>
8793 <t>dotnum
8794 </t>
8795 <t>/ number
8796 </t>
8797 </list>
8798 </t>
8799 <t>control_value =
8800 <list>
8801 <t>real
8802 </t>
8803 </list>
8804 </t>
8805 <t>sampler_channel =
8806 <list>
8807 <t>number
8808 </t>
8809 </list>
8810 </t>
8811 <t>instrument_index =
8812 <list>
8813 <t>number
8814 </t>
8815 </list>
8816 </t>
8817 <t>fx_send_id =
8818 <list>
8819 <t>number
8820 </t>
8821 </list>
8822 </t>
8823 <t>engine_name =
8824 <list>
8825 <t>string
8826 </t>
8827 </list>
8828 </t>
8829 <t>filename =
8830 <list>
8831 <t>path
8832 </t>
8833 </list>
8834 </t>
8835 <t>db_path =
8836 <list>
8837 <t>path
8838 </t>
8839 </list>
8840 </t>
8841 <t>map_name =
8842 <list>
8843 <t>stringval_escaped
8844 </t>
8845 </list>
8846 </t>
8847 <t>entry_name =
8848 <list>
8849 <t>stringval_escaped
8850 </t>
8851 </list>
8852 </t>
8853 <t>fx_send_name =
8854 <list>
8855 <t>stringval_escaped
8856 </t>
8857 </list>
8858 </t>
8859 <t>effect_name =
8860 <list>
8861 <t>stringval_escaped
8862 </t>
8863 </list>
8864 </t>
8865 <t>effect_index =
8866 <list>
8867 <t>number
8868 </t>
8869 </list>
8870 </t>
8871 <t>effect_chain =
8872 <list>
8873 <t>number
8874 </t>
8875 </list>
8876 </t>
8877 <t>chain_pos =
8878 <list>
8879 <t>number
8880 </t>
8881 </list>
8882 </t>
8883 <t>input_control =
8884 <list>
8885 <t>number
8886 </t>
8887 </list>
8888 </t>
8889 <t>param_val_list =
8890 <list>
8891 <t>param_val
8892 </t>
8893 <t>/ param_val_list','param_val
8894 </t>
8895 </list>
8896 </t>
8897
8898 <t>param_val =
8899 <list>
8900 <t>string
8901 </t>
8902 <t>/ stringval
8903 </t>
8904 <t>/ number
8905 </t>
8906 <t>/ dotnum
8907 </t>
8908 </list>
8909 </t>
8910 <t>query_val_list =
8911 <list>
8912 <t>string '=' query_val
8913 </t>
8914 <t>/ query_val_list SP string '=' query_val
8915 </t>
8916 </list>
8917 </t>
8918 <t>query_val =
8919 <list>
8920 <t>text_escaped
8921 </t>
8922 <t>/ stringval_escaped
8923 </t>
8924 </list>
8925 </t>
8926 <t>scan_mode =
8927 <list>
8928 <t>RECURSIVE
8929 </t>
8930 <t>/ NON_RECURSIVE
8931 </t>
8932 <t>/ FLAT
8933 </t>
8934 </list>
8935 </t>
8936 <t>effect_system =
8937 <list>
8938 <t>string
8939 </t>
8940 </list>
8941 </t>
8942 <t>module =
8943 <list>
8944 <t>filename
8945 </t>
8946 </list>
8947 </t>
8948
8949 <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->
8950
8951 <section title="Character Set and Escape Sequences" anchor="character_set">
8952 <t>Older versions of this protocol up to and including v1.1 only
8953 supported the standard ASCII character set (ASCII code 0 - 127)
8954 <xref target="RFC20"/>, all younger versions of this protocol
8955 however support the Extended ASCII character set (ASCII code
8956 0 - 255). The same group of younger protocols also support
8957 escape sequences, but only for certain, explicitly declared
8958 parts of the protocol. The supported escape sequences are
8959 defined as follows:</t>
8960 <texttable>
8961 <ttcol>ASCII Character Sequence</ttcol>
8962 <ttcol>Translated into (Name)</ttcol>
8963 <c>\n</c> <c>new line</c>
8964 <c>\r</c> <c>carriage return</c>
8965 <c>\f</c> <c>form feed</c>
8966 <c>\t</c> <c>horizontal tab</c>
8967 <c>\v</c> <c>vertical tab</c>
8968 <c>\'</c> <c>apostrophe</c>
8969 <c>\"</c> <c>quotation mark</c>
8970 <c>\\</c> <c>backslash</c>
8971 <c>\OOO</c> <c>three digit octal ASCII code of the character</c>
8972 <c>\xHH</c> <c>two digit hex ASCII code of the character</c>
8973 </texttable>
8974 <t>Notice: due to the transition of certain parts of the
8975 protocol which now support escape sequences, a slight backward
8976 incompatibility to protocols version v1.1 and younger has been
8977 introduced. The only difference is that in parts of the protocol
8978 where escape characters are now supported, a backslash characters
8979 MUST be escaped as well (that is as double backslash), whereas
8980 in the old versions a single backslash was sufficient.</t>
8981
8982 <t>The following LSCP commands support escape sequences as part
8983 of their filename / path based arguments and / or may contain
8984 a filename / path with escape sequences in their response:
8985 <list>
8986 <t><xref target="LOAD INSTRUMENT">"LOAD INSTRUMENT"</xref></t>
8987 <t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t>
8988 <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
8989 <t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t>
8990 <t><xref target="ADD DB_INSTRUMENT_DIRECTORY">"ADD DB_INSTRUMENT_DIRECTORY"</xref></t>
8991 <t><xref target="ADD DB_INSTRUMENTS">"ADD DB_INSTRUMENTS"</xref></t>
8992 <t><xref target="REMOVE DB_INSTRUMENT_DIRECTORY">"REMOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
8993 <t><xref target="REMOVE DB_INSTRUMENT">"REMOVE DB_INSTRUMENT"</xref></t>
8994 <t><xref target="GET DB_INSTRUMENT_DIRECTORIES">"GET DB_INSTRUMENT_DIRECTORIES"</xref></t>
8995 <t><xref target="LIST DB_INSTRUMENT_DIRECTORIES">"LIST DB_INSTRUMENT_DIRECTORIES"</xref></t>
8996 <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
8997 <t><xref target="GET DB_INSTRUMENTS">"GET DB_INSTRUMENTS"</xref></t>
8998 <t><xref target="LIST DB_INSTRUMENTS">"LIST DB_INSTRUMENTS"</xref></t>
8999 <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
9000 <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
9001 <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
9002 <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
9003 <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
9004 <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
9005 <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
9006 <t><xref target="MOVE DB_INSTRUMENT">"MOVE DB_INSTRUMENT"</xref></t>
9007 <t><xref target="MOVE DB_INSTRUMENT_DIRECTORY">"MOVE DB_INSTRUMENT_DIRECTORY"</xref></t>
9008 <t><xref target="COPY DB_INSTRUMENT">"COPY DB_INSTRUMENT"</xref></t>
9009 <t><xref target="COPY DB_INSTRUMENT_DIRECTORY">"COPY DB_INSTRUMENT_DIRECTORY"</xref></t>
9010 <t><xref target="FIND LOST DB_INSTRUMENT_FILES">"FIND LOST DB_INSTRUMENT_FILES"</xref></t>
9011 <t><xref target="SET DB_INSTRUMENT FILE_PATH">"SET DB_INSTRUMENT FILE_PATH"</xref></t>
9012 <t><xref target="GET FILE INSTRUMENTS">"GET FILE INSTRUMENTS"</xref></t>
9013 <t><xref target="LIST FILE INSTRUMENTS">"LIST FILE INSTRUMENTS"</xref></t>
9014 <t><xref target="GET FILE INSTRUMENT INFO">"GET FILE INSTRUMENT INFO"</xref></t>
9015 <t><xref target="GET EFFECT INFO">"GET EFFECT INFO"</xref></t>
9016 <t><xref target="GET EFFECT_INSTANCE INFO">"GET EFFECT_INSTANCE INFO"</xref></t>
9017 <t><xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref></t>
9018 </list>
9019 Note that the forward slash character ('/') has a special meaning in
9020 filename / path based arguments: it acts as separator of the nodes in
9021 the path, thus if a directory- or filename includes a forward slash
9022 (not intended as path node separator), you MUST escape that slash
9023 either with the respective hex escape sequence ("\x2f") or with the
9024 respective octal escape sequence ("\057").
9025 </t>
9026
9027 <t>
9028 Note for Windows: file path arguments in LSCP are expected
9029 to use forward slashes as directory node separator similar
9030 to Unix based operating systems. In contrast to Unix however
9031 a Windows typical drive character is expected to be
9032 prefixed to the path. That is an original Windows file path
9033 like "D:\Sounds\My.gig" would become in LSCP:
9034 "D:/Sounds/My.gig".
9035 </t>
9036
9037 <t>
9038 The following LSCP commands even support escape sequences as
9039 part of at least one of their text-based arguments (i.e. entity name,
9040 description) and / or may contain escape sequences in at least one of
9041 their text-based fields in their response:
9042 <list>
9043 <t><xref target="GET SERVER INFO">"GET SERVER INFO"</xref></t>
9044 <t><xref target="GET ENGINE INFO">"GET ENGINE INFO"</xref></t>
9045 <t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t>
9046 <t><xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref></t>
9047 <t><xref target="GET FX_SEND INFO">"GET FX_SEND INFO"</xref></t>
9048 <t><xref target="SET FX_SEND NAME">"SET FX_SEND NAME"</xref></t>
9049 <t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t>
9050 <t><xref target="GET MIDI_INSTRUMENT_MAP INFO">"GET MIDI_INSTRUMENT_MAP INFO"</xref></t>
9051 <t><xref target="ADD MIDI_INSTRUMENT_MAP">"ADD MIDI_INSTRUMENT_MAP"</xref></t>
9052 <t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t>
9053 <t><xref target="SET MIDI_INSTRUMENT_MAP NAME">"SET MIDI_INSTRUMENT_MAP NAME"</xref></t>
9054 <t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t>
9055 <t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t>
9056 <t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t>
9057 <t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t>
9058 <t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t>
9059 <t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t>
9060 <t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t>
9061 <t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t>
9062 <t><xref target="GET EFFECT INFO">"GET EFFECT INFO"</xref></t>
9063 <t><xref target="GET EFFECT_INSTANCE INFO">"GET EFFECT_INSTANCE INFO"</xref></t>
9064 <t><xref target="CREATE EFFECT_INSTANCE">"CREATE EFFECT_INSTANCE"</xref></t>
9065 </list>
9066 Please note that these lists are manually maintained. If you
9067 find a command that also supports escape sequences we forgot to
9068 mention here, please report it!
9069 </t>
9070 </section>
9071 </section>
9072
9073 <section title="Events" anchor="events">
9074 <t>This chapter will describe all currently defined events supported by LinuxSampler.</t>
9075
9076 <section title="Number of audio output devices changed" anchor="SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT" lscp_cmd="true">
9077 <t>Client may want to be notified when the total number of audio output devices on the
9078 back-end changes by issuing the following command:</t>
9079 <t>
9080 <list>
9081 <t>SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT</t>
9082 </list>
9083 </t>
9084 <t>Server will start sending the following notification messages:</t>
9085 <t>
9086 <list>
9087 <t>"NOTIFY:AUDIO_OUTPUT_DEVICE_COUNT:&lt;devices&gt;"</t>
9088 </list>
9089 </t>
9090 <t>where &lt;devices&gt; will be replaced by the new number
9091 of audio output devices.</t>
9092 </section>
9093
9094 <section title="Audio output device's settings changed" anchor="SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO" lscp_cmd="true">
9095 <t>Client may want to be notified when changes were made to audio output devices on the
9096 back-end by issuing the following command:</t>
9097 <t>
9098 <list>
9099 <t>SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO</t>
9100 </list>
9101 </t>
9102 <t>Server will start sending the following notification messages:</t>
9103 <t>
9104 <list>
9105 <t>"NOTIFY:AUDIO_OUTPUT_DEVICE_INFO:&lt;device-id&gt;"</t>
9106 </list>
9107 </t>
9108 <t>where &lt;device-id&gt; will be replaced by the numerical ID of the audio output device,
9109 which settings has been changed. The front-end will have to send
9110 the respective command to actually get the audio output device info. Because these messages
9111 will be triggered by LSCP commands issued by other clients rather than real
9112 time events happening on the server, it is believed that an empty notification
9113 message is sufficient here.</t>
9114 </section>
9115
9116 <section title="Number of MIDI input devices changed" anchor="SUBSCRIBE MIDI_INPUT_DEVICE_COUNT" lscp_cmd="true">
9117 <t>Client may want to be notified when the total number of MIDI input devices on the
9118 back-end changes by issuing the following command:</t>
9119 <t>
9120 <list>
9121 <t>SUBSCRIBE MIDI_INPUT_DEVICE_COUNT</t>
9122 </list>
9123 </t>
9124 <t>Server will start sending the following notification messages:</t>
9125 <t>
9126 <list>
9127 <t>"NOTIFY:MIDI_INPUT_DEVICE_COUNT:&lt;devices&gt;"</t>
9128 </list>
9129 </t>
9130 <t>where &lt;devices&gt; will be replaced by the new number
9131 of MIDI input devices.</t>
9132 </section>
9133
9134 <section title="MIDI input device's settings changed" anchor="SUBSCRIBE MIDI_INPUT_DEVICE_INFO" lscp_cmd="true">
9135 <t>Client may want to be notified when changes were made to MIDI input devices on the
9136 back-end by issuing the following command:</t>
9137 <t>
9138 <list>
9139 <t>SUBSCRIBE MIDI_INPUT_DEVICE_INFO</t>
9140 </list>
9141 </t>
9142 <t>Server will start sending the following notification messages:</t>
9143 <t>
9144 <list>
9145 <t>"NOTIFY:MIDI_INPUT_DEVICE_INFO:&lt;device-id&gt;"</t>
9146 </list>
9147 </t>
9148 <t>where &lt;device-id&gt; will be replaced by the numerical ID of the MIDI input device,
9149 which settings has been changed. The front-end will have to send
9150 the respective command to actually get the MIDI input device info. Because these messages
9151 will be triggered by LSCP commands issued by other clients rather than real
9152 time events happening on the server, it is believed that an empty notification
9153 message is sufficient here.</t>
9154 </section>
9155
9156 <section title="Number of sampler channels changed" anchor="SUBSCRIBE CHANNEL_COUNT" lscp_cmd="true">
9157 <t>Client may want to be notified when the total number of channels on the
9158 back-end changes by issuing the following command:</t>
9159 <t>
9160 <list>
9161 <t>SUBSCRIBE CHANNEL_COUNT</t>
9162 </list>
9163 </t>
9164 <t>Server will start sending the following notification messages:</t>
9165 <t>
9166 <list>
9167 <t>"NOTIFY:CHANNEL_COUNT:&lt;channels&gt;"</t>
9168 </list>
9169 </t>
9170 <t>where &lt;channels&gt; will be replaced by the new number
9171 of sampler channels.</t>
9172 </section>
9173
9174 <section title="MIDI data on a sampler channel arrived" anchor="SUBSCRIBE CHANNEL_MIDI" lscp_cmd="true">
9175 <t>Client may want to be notified when MIDI data arrive on sampler channels on
9176 back-end side, by issuing the following command:</t>
9177 <t>
9178 <list>
9179 <t>SUBSCRIBE CHANNEL_MIDI</t>
9180 </list>
9181 </t>
9182 <t>Server will start sending one of the the following notification messages:</t>
9183 <t>
9184 <list>
9185 <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_ON &lt;note&gt; &lt;velocity&gt;"</t>
9186 <t>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
9187 </list>
9188 </t>
9189 <t>where &lt;channel-id&gt; will be replaced by the ID of the sampler channel where the MIDI
9190 data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
9191 0 .. 127, reflecting the analog meaning of the MIDI specification.
9192 </t>
9193 <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
9194 delivered by this mechanism! With other words: events could be lost at any time!
9195 This restriction was made to keep the RT-safeness of the backend's MIDI and audio
9196 thread unaffected by this feature.</t>
9197 </section>
9198
9199 <section title="MIDI data on a MIDI input device arrived" anchor="SUBSCRIBE DEVICE_MIDI" lscp_cmd="true">
9200 <t>Client may want to be notified when MIDI data arrive on MIDI input devices by issuing the following command:</t>
9201 <t>
9202 <list>
9203 <t>SUBSCRIBE DEVICE_MIDI</t>
9204 </list>
9205 </t>
9206 <t>Server will start sending one of the the following notification messages:</t>
9207 <t>
9208 <list>
9209 <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_ON &lt;note&gt; &lt;velocity&gt;"</t>
9210 <t>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"</t>
9211 </list>
9212 </t>
9213 <t>where &lt;device-id&gt; &lt;port-id&gt; will be replaced
9214 by the IDs of the respective MIDI input device and the device's MIDI port where the MIDI
9215 data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
9216 0 .. 127, reflecting the analog meaning of the MIDI specification.
9217 </t>
9218 <t>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
9219 delivered by this mechanism! With other words: events could be lost at any time!
9220 This restriction was made to keep the RT-safeness of the backend's MIDI and audio
9221 thread unaffected by this feature.</t>
9222 </section>
9223
9224 <section title="Number of active voices changed" anchor="SUBSCRIBE VOICE_COUNT" lscp_cmd="true">
9225 <t>Client may want to be notified when the number of voices on the
9226 back-end changes by issuing the following command:</t>
9227 <t>
9228 <list>
9229 <t>SUBSCRIBE VOICE_COUNT</t>
9230 </list>
9231 </t>
9232 <t>Server will start sending the following notification messages:</t>
9233 <t>
9234 <list>
9235 <t>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;"</t>
9236 </list>
9237 </t>
9238 <t>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
9239 voice count change occurred and &lt;voices&gt; by the new number of
9240 active voices on that channel.</t>
9241 </section>
9242
9243 <section title="Number of active disk streams changed" anchor="SUBSCRIBE STREAM_COUNT" lscp_cmd="true">
9244 <t>Client may want to be notified when the number of streams on the back-end
9245 changes by issuing the following command: SUBSCRIBE STREAM_COUNT</t>
9246 <t>
9247 <list>
9248 <t>SUBSCRIBE STREAM_COUNT</t>
9249 </list>
9250 </t>
9251 <t>Server will start sending the following notification messages:</t>
9252 <t>
9253 <list>
9254 <t>"NOTIFY:STREAM_COUNT:&lt;sampler-channel&gt; &lt;streams&gt;"</t>
9255 </list>
9256 </t>
9257 <t>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
9258 stream count change occurred and &lt;streams&gt; by the new number of
9259 active disk streams on that channel.</t>
9260 </section>
9261
9262 <section title="Disk stream buffer fill state changed" anchor="SUBSCRIBE BUFFER_FILL" lscp_cmd="true">
9263 <t>Client may want to be notified when the buffer fill state of a disk stream
9264 on the back-end changes by issuing the following command:</t>
9265 <t>
9266 <list>
9267 <t>SUBSCRIBE BUFFER_FILL</t>
9268 </list>
9269 </t>
9270 <t>Server will start sending the following notification messages:</t>
9271 <t>
9272 <list>
9273 <t>"NOTIFY:BUFFER_FILL:&lt;sampler-channel&gt; &lt;fill-data&gt;"</t>
9274 </list>
9275 </t>
9276 <t>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
9277 buffer fill state change occurred on and &lt;fill-data&gt; will be replaced by the
9278 buffer fill data for this channel as described in <xref target="GET CHANNEL BUFFER_FILL" />
9279 as if the <xref target="GET CHANNEL BUFFER_FILL">
9280 "GET CHANNEL BUFFER_FILL PERCENTAGE"</xref> command was issued on this channel.</t>
9281 </section>
9282
9283 <section title="Channel information changed" anchor="SUBSCRIBE CHANNEL_INFO" lscp_cmd="true">
9284 <t>Client may want to be notified when changes were made to sampler channels on the
9285 back-end by issuing the following command:</t>
9286 <t>
9287 <list>
9288 <t>SUBSCRIBE CHANNEL_INFO</t>
9289 </list>
9290 </t>
9291 <t>Server will start sending the following notification messages:</t>
9292 <t>
9293 <list>
9294 <t>"NOTIFY:CHANNEL_INFO:&lt;sampler-channel&gt;"</t>
9295 </list>
9296 </t>
9297 <t>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
9298 channel info change occurred. The front-end will have to send
9299 the respective command to actually get the channel info. Because these messages
9300 will be triggered by LSCP commands issued by other clients rather than real
9301 time events happening on the server, it is believed that an empty notification
9302 message is sufficient here.</t>
9303 </section>
9304
9305 <section title="Number of effect sends changed" anchor="SUBSCRIBE FX_SEND_COUNT" lscp_cmd="true">
9306 <t>Client may want to be notified when the number of effect sends on
9307 a particular sampler channel is changed by issuing the following command:</t>
9308 <t>
9309 <list>
9310 <t>SUBSCRIBE FX_SEND_COUNT</t>
9311 </list>
9312 </t>
9313 <t>Server will start sending the following notification messages:</t>
9314 <t>
9315 <list>
9316 <t>"NOTIFY:FX_SEND_COUNT:&lt;channel-id&gt; &lt;fx-sends&gt;"</t>
9317 </list>
9318 </t>
9319 <t>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
9320 channel, on which the effect sends number is changed and &lt;fx-sends&gt; will
9321 be replaced by the new number of effect sends on that channel.</t>
9322 </section>
9323
9324 <section title="Effect send information changed" anchor="SUBSCRIBE FX_SEND_INFO" lscp_cmd="true">
9325 <t>Client may want to be notified when changes were made to effect sends on a
9326 a particular sampler channel by issuing the following command:</t>
9327 <t>
9328 <list>
9329 <t>SUBSCRIBE FX_SEND_INFO</t>
9330 </list>
9331 </t>
9332 <t>Server will start sending the following notification messages:</t>
9333 <t>
9334 <list>
9335 <t>"NOTIFY:FX_SEND_INFO:&lt;channel-id&gt; &lt;fx-send-id&gt;"</t>
9336 </list>
9337 </t>
9338 <t>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
9339 channel, on which an effect send entity is changed and &lt;fx-send-id&gt; will
9340 be replaced by the numerical ID of the changed effect send.</t>
9341 </section>
9342
9343 <section title="Total number of active voices changed" anchor="SUBSCRIBE TOTAL_VOICE_COUNT" lscp_cmd="true">
9344 <t>Client may want to be notified when the total number of voices on the
9345 back-end changes by issuing the following command:</t>
9346 <t>
9347 <list>
9348 <t>SUBSCRIBE TOTAL_VOICE_COUNT</t>
9349 </list>
9350 </t>
9351 <t>Server will start sending the following notification messages:</t>
9352 <t>
9353 <list>
9354 <t>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;"</t>
9355 </list>
9356 </t>
9357 <t>where &lt;voices&gt; will be replaced by the new number of
9358 all currently active voices.</t>
9359 </section>
9360
9361 <section title="Total number of active disk streams changed" anchor="SUBSCRIBE TOTAL_STREAM_COUNT" lscp_cmd="true">
9362 <t>Client may want to be notified when the total number of disk streams on the
9363 back-end changes by issuing the following command:</t>
9364 <t>
9365 <list>
9366 <t>SUBSCRIBE TOTAL_STREAM_COUNT</t>
9367 </list>
9368 </t>
9369 <t>Server will start sending the following notification messages:</t>
9370 <t>
9371 <list>
9372 <t>"NOTIFY:TOTAL_STREAM_COUNT:&lt;streams&gt;"</t>
9373 </list>
9374 </t>
9375 <t>where &lt;streams&gt; will be replaced by the new number of
9376 all currently active disk streams.</t>
9377 </section>
9378
9379 <section title="Number of MIDI instrument maps changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT" lscp_cmd="true">
9380 <t>Client may want to be notified when the number of MIDI instrument maps on the
9381 back-end changes by issuing the following command:</t>
9382 <t>
9383 <list>
9384 <t>SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT</t>
9385 </list>
9386 </t>
9387 <t>Server will start sending the following notification messages:</t>
9388 <t>
9389 <list>
9390 <t>"NOTIFY:MIDI_INSTRUMENT_MAP_COUNT:&lt;maps&gt;"</t>
9391 </list>
9392 </t>
9393 <t>where &lt;maps&gt; will be replaced by the new number
9394 of MIDI instrument maps.</t>
9395 </section>
9396
9397 <section title="MIDI instrument map information changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO" lscp_cmd="true">
9398 <t>Client may want to be notified when changes were made to MIDI instrument maps on the
9399 back-end by issuing the following command:</t>
9400 <t>
9401 <list>
9402 <t>SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO</t>
9403 </list>
9404 </t>
9405 <t>Server will start sending the following notification messages:</t>
9406 <t>
9407 <list>
9408 <t>"NOTIFY:MIDI_INSTRUMENT_MAP_INFO:&lt;map-id&gt;"</t>
9409 </list>
9410 </t>
9411 <t>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
9412 for which information changes occurred. The front-end will have to send
9413 the respective command to actually get the MIDI instrument map info. Because these messages
9414 will be triggered by LSCP commands issued by other clients rather than real
9415 time events happening on the server, it is believed that an empty notification
9416 message is sufficient here.</t>
9417 </section>
9418
9419 <section title="Number of MIDI instruments changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_COUNT" lscp_cmd="true">
9420 <t>Client may want to be notified when the number of MIDI instrument maps on the
9421 back-end changes by issuing the following command:</t>
9422 <t>
9423 <list>
9424 <t>SUBSCRIBE MIDI_INSTRUMENT_COUNT</t>
9425 </list>
9426 </t>
9427 <t>Server will start sending the following notification messages:</t>
9428 <t>
9429 <list>
9430 <t>"NOTIFY:MIDI_INSTRUMENT_COUNT:&lt;map-id&gt; &lt;instruments&gt;"</t>
9431 </list>
9432 </t>
9433 <t>where &lt;map-id&gt; is the numerical ID of the MIDI instrument map, in which
9434 the nuber of instruments has changed and &lt;instruments&gt; will be replaced by
9435 the new number of MIDI instruments in the specified map.</t>
9436 </section>
9437
9438 <section title="MIDI instrument information changed" anchor="SUBSCRIBE MIDI_INSTRUMENT_INFO" lscp_cmd="true">
9439 <t>Client may want to be notified when changes were made to MIDI instruments on the
9440 back-end by issuing the following command:</t>
9441 <t>
9442 <list>
9443 <t>SUBSCRIBE MIDI_INSTRUMENT_INFO</t>
9444 </list>
9445 </t>
9446 <t>Server will start sending the following notification messages:</t>
9447 <t>
9448 <list>
9449 <t>"NOTIFY:MIDI_INSTRUMENT_INFO:&lt;map-id&gt; &lt;bank&gt; &lt;program&gt;"</t>
9450 </list>
9451 </t>
9452 <t>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
9453 in which a MIDI instrument is changed. &lt;bank&gt; and &lt;program&gt; specifies
9454 the location of the changed MIDI instrument in the map. The front-end will have to send
9455 the respective command to actually get the MIDI instrument info. Because these messages
9456 will be triggered by LSCP commands issued by other clients rather than real
9457 time events happening on the server, it is believed that an empty notification
9458 message is sufficient here.</t>
9459 </section>
9460
9461 <section title="Global settings changed" anchor="SUBSCRIBE GLOBAL_INFO" lscp_cmd="true">
9462 <t>Client may want to be notified when changes to the global settings
9463 of the sampler were made by issuing the following command:</t>
9464 <t>
9465 <list>
9466 <t>SUBSCRIBE GLOBAL_INFO</t>
9467 </list>
9468 </t>
9469 <t>Server will start sending the following types of notification messages:</t>
9470 <t>
9471 <list>
9472 <t>"NOTIFY:GLOBAL_INFO:VOLUME &lt;volume&gt;" - Notifies that the
9473 golbal volume of the sampler is changed, where &lt;volume&gt; will be
9474 replaced by the optional dotted floating point value, reflecting the
9475 new global volume parameter.</t>
9476 </list>
9477 <list>
9478 <t>"NOTIFY:GLOBAL_INFO:VOICES &lt;max-voices&gt;" - Notifies that the
9479 golbal limit of the sampler for maximum voices is changed, where
9480 &lt;max-voices&gt; will be an integer value, reflecting the
9481 new global voice limit parameter.</t>
9482 </list>
9483 <list>
9484 <t>"NOTIFY:GLOBAL_INFO:STREAMS &lt;max-streams&gt;" - Notifies that the
9485 golbal limit of the sampler for maximum disk streams is changed, where
9486 &lt;max-streams&gt; will be an integer value, reflecting the
9487 new global disk streams limit parameter.</t>
9488 </list>
9489 </t>
9490 </section>
9491
9492 <section title="Number of database instrument directories changed" anchor="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT" lscp_cmd="true">
9493 <t>Client may want to be notified when the number of instrument
9494 directories in a particular directory in the instruments database
9495 is changed by issuing the following command:</t>
9496 <t>
9497 <list>
9498 <t>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT</t>
9499 </list>
9500 </t>
9501 <t>Server will start sending the following notification messages:</t>
9502 <t>
9503 <list>
9504 <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_COUNT:&lt;dir-path&gt;"</t>
9505 </list>
9506 </t>
9507 <t>where &lt;dir-path&gt; will be replaced by the absolute path
9508 name of the directory in the instruments database,
9509 in which the number of directories is changed.</t>
9510 <t>Note that when a non-empty directory is removed, this event
9511 is not sent for the subdirectories in that directory.</t>
9512 </section>
9513
9514 <section title="Database instrument directory information changed" anchor="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO" lscp_cmd="true">
9515 <t>Client may want to be notified when changes were made to directories
9516 in the instruments database by issuing the following command:</t>
9517 <t>
9518 <list>
9519 <t>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO</t>
9520 </list>
9521 </t>
9522 <t>Server will start sending the following notification messages:</t>
9523 <t>
9524 <list>
9525 <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:&lt;dir-path&gt;"</t>
9526 </list>
9527 </t>
9528 <t>where &lt;dir-path&gt; will be replaced by the absolute path name
9529 of the directory, for which information changes occurred. The front-end will have to send
9530 the respective command to actually get the updated directory info. Because these messages
9531 will be triggered by LSCP commands issued by other clients rather than real
9532 time events happening on the server, it is believed that an empty notification
9533 message is sufficient here.</t>
9534 <t>
9535 <list>
9536 <t>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:NAME &lt;old-dir-path&gt; &lt;new-name&gt;"</t>
9537 </list>
9538 </t>
9539 <t>where &lt;old-dir-path&gt; is the old absolute path name of the directory
9540 (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
9541 the new name of the directory, encapsulated into apostrophes.</t>
9542 </section>
9543
9544 <section title="Number of database instruments changed" anchor="SUBSCRIBE DB_INSTRUMENT_COUNT" lscp_cmd="true">
9545 <t>Client may want to be notified when the number of instruments
9546 in a particular directory in the instruments database
9547 is changed by issuing the following command:</t>
9548 <t>
9549 <list>
9550 <t>SUBSCRIBE DB_INSTRUMENT_COUNT</t>
9551 </list>
9552 </t>
9553 <t>Server will start sending the following notification messages:</t>
9554 <t>
9555 <list>
9556 <t>"NOTIFY:DB_INSTRUMENT_COUNT:&lt;dir-path&gt;"</t>
9557 </list>
9558 </t>
9559 <t>where &lt;dir-path&gt; will be replaced by the absolute path
9560 name of the directory in the instruments database,
9561 in which the number of instruments is changed.</t>
9562 <t>Note that when a non-empty directory is removed, this event
9563 is not sent for the instruments in that directory.</t>
9564 </section>
9565
9566 <section title="Database instrument information changed" anchor="SUBSCRIBE DB_INSTRUMENT_INFO" lscp_cmd="true">
9567 <t>Client may want to be notified when changes were made to instruments
9568 in the instruments database by issuing the following command:</t>
9569 <t>
9570 <list>
9571 <t>SUBSCRIBE DB_INSTRUMENT_INFO</t>
9572 </list>
9573 </t>
9574 <t>Server will start sending the following notification messages:</t>
9575 <t>
9576 <list>
9577 <t>"NOTIFY:DB_INSTRUMENT_INFO:&lt;instr-path&gt;"</t>
9578 </list>
9579 </t>
9580 <t>where &lt;instr-path&gt; will be replaced by the absolute path name
9581 of the instrument, which settings are changed. The front-end will have to send
9582 the respective command to actually get the updated directory info. Because these messages
9583 will be triggered by LSCP commands issued by other clients rather than real
9584 time events happening on the server, it is believed that an empty notification
9585 message is sufficient here.</t>
9586 <t>
9587 <list>
9588 <t>"NOTIFY:DB_INSTRUMENT_INFO:NAME &lt;old-instr-path&gt; &lt;new-name&gt;"</t>
9589 </list>
9590 </t>
9591 <t>where &lt;old-instr-path&gt; is the old absolute path name of the instrument
9592 (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
9593 the new name of the instrument, encapsulated into apostrophes.</t>
9594 </section>
9595
9596 <section title="Database job status information changed" anchor="SUBSCRIBE DB_INSTRUMENTS_JOB_INFO" lscp_cmd="true">
9597 <t>Client may want to be notified when the status of particular database
9598 instruments job is changed by issuing the following command:</t>
9599 <t>
9600 <list>
9601 <t>SUBSCRIBE DB_INSTRUMENTS_JOB_INFO</t>
9602 </list>
9603 </t>
9604 <t>Server will start sending the following notification messages:</t>
9605 <t>
9606 <list>
9607 <t>"NOTIFY:DB_INSTRUMENTS_JOB_INFO:&lt;job-id&gt;"</t>
9608 </list>
9609 </t>
9610 <t>where &lt;job-id&gt; will be replaced by the numerical ID of the job,
9611 which status is changed. The front-end will have to send the respective
9612 command to actually get the status info. Because these messages
9613 will be triggered by LSCP commands issued by other clients rather than real
9614 time events happening on the server, it is believed that an empty notification
9615 message is sufficient here.</t>
9616 </section>
9617
9618 <section title="Number of effect instances changed" anchor="SUBSCRIBE EFFECT_INSTANCE_COUNT" lscp_cmd="true">
9619 <t>Client may want to be notified when the number of effect instances
9620 is changed by issuing the following command:</t>
9621 <t>
9622 <list>
9623 <t>SUBSCRIBE EFFECT_INSTANCE_COUNT</t>
9624 </list>
9625 </t>
9626 <t>Server will start sending the following notification messages:</t>
9627 <t>
9628 <list>
9629 <t>"EFFECT_INSTANCE_COUNT:&lt;instances&gt;"</t>
9630 </list>
9631 </t>
9632 <t>where &lt;instances&gt; will be replaced by the new number
9633 of effect instances.</t>
9634 </section>
9635
9636 <section title="Effect instance information changed" anchor="SUBSCRIBE EFFECT_INSTANCE_INFO" lscp_cmd="true">
9637 <t>Client may want to be notified when changes were made to effect instances
9638 on the back-end by issuing the following command:</t>
9639 <t>
9640 <list>
9641 <t>SUBSCRIBE EFFECT_INSTANCE_INFO</t>
9642 </list>
9643 </t>
9644 <t>Server will start sending the following notification messages:</t>
9645 <t>
9646 <list>
9647 <t>"EFFECT_INSTANCE_INFO:&lt;instance-id&gt;"</t>
9648 </list>
9649 </t>
9650 <t>where &lt;instance-id&gt; will be replaced by the numerical ID
9651 of the effect instance.</t>
9652 </section>
9653
9654 <section title="Number of send effect chains changed" anchor="SUBSCRIBE SEND_EFFECT_CHAIN_COUNT" lscp_cmd="true">
9655 <t>Client may want to be notified when the number of send effect chains
9656 is changed by issuing the following command:</t>
9657 <t>
9658 <list>
9659 <t>SUBSCRIBE SEND_EFFECT_CHAIN_COUNT</t>
9660 </list>
9661 </t>
9662 <t>Server will start sending the following notification messages:</t>
9663 <t>
9664 <list>
9665 <t>"NOTIFY:SEND_EFFECT_CHAIN_COUNT:&lt;device-id&gt; &lt;chains&gt;"</t>
9666 </list>
9667 </t>
9668 <t>where &lt;device-id&gt; will be replaced by the numerical ID of the audio
9669 output device, in which the number of send effect chains is changed and
9670 &lt;chains&gt; will be replaced by the new number of send effect chains.</t>
9671 </section>
9672
9673 <section title="Send effect chain information changed" anchor="SUBSCRIBE SEND_EFFECT_CHAIN_INFO" lscp_cmd="true">
9674 <t>Client may want to be notified when changes were made to send effect chains
9675 on the back-end by issuing the following command:</t>
9676 <t>
9677 <list>
9678 <t>SUBSCRIBE SEND_EFFECT_CHAIN_INFO</t>
9679 </list>
9680 </t>
9681 <t>Server will start sending the following notification messages:</t>
9682 <t>
9683 <list>
9684 <t>"SEND_EFFECT_CHAIN_INFO:&lt;device-id&gt; &lt;chain-id&gt; &lt;instances&gt;" -
9685 Notifies that the number of effect instances in a particular send effect chain
9686 is changed, where &lt;device-id&gt; will be replaced by the numerical ID of the audio
9687 output device the send effect chain belongs to, &lt;chain-id&gt; will be replaced
9688 by the numerical ID of the send effect chain in which the number of effect instances
9689 has changed and &lt;instances&gt; will be replaced by the new number
9690 of effect instances in the specified send effect chain.</t>
9691 </list>
9692 </t>
9693 </section>
9694
9695 <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS" lscp_cmd="true">
9696 <t>Client may want to be notified of miscellaneous and debugging events occurring at
9697 the server by issuing the following command:</t>
9698 <t>
9699 <list>
9700 <t>SUBSCRIBE MISCELLANEOUS</t>
9701 </list>
9702 </t>
9703 <t>Server will start sending the following notification messages:</t>
9704 <t>
9705 <list>
9706 <t>"NOTIFY:MISCELLANEOUS:&lt;string&gt;"</t>
9707 </list>
9708 </t>
9709 <t>where &lt;string&gt; will be replaced by whatever data server
9710 wants to send to the client. Client MAY display this data to the
9711 user AS IS to facilitate debugging.</t>
9712 </section>
9713 </section>
9714
9715 <section title="Security Considerations">
9716 <t>As there is so far no method of authentication and authorization
9717 defined and so not required for a client applications to succeed to
9718 connect, running LinuxSampler might be a security risk for the host
9719 system the LinuxSampler instance is running on.</t>
9720 </section>
9721
9722 <section title="Acknowledgments">
9723 <t>This document has benefited greatly from the comments of the
9724 following people, discussed on the LinuxSampler developer's mailing
9725 list:</t>
9726 <t>
9727 <list>
9728 <t>Rui Nuno Capela</t>
9729 <t>Vladimir Senkov</t>
9730 <t>Mark Knecht</t>
9731 <t>Grigor Iliev</t>
9732 </list>
9733 </t>
9734 </section>
9735
9736 </middle>
9737
9738 <back>
9739 <references>
9740 <reference anchor="RFC2119">
9741 <front>
9742 <title>Key words for use in RFCs to Indicate Requirement Levels</title>
9743 <author initials="S." surname="Bradner" fullname="Scott Bradner">
9744 <organization>Harvard University</organization>
9745 </author>
9746 <date year="1997"></date>
9747 </front>
9748 <seriesInfo name="RFC" value="2119" />
9749 </reference>
9750 <reference anchor="RFC793">
9751 <front>
9752 <title>TRANSMISSION CONTROL PROTOCOL</title>
9753 <author>
9754 <organization>Defense Advanced Research Projects Agency</organization>
9755 </author>
9756 <date year="1981"></date>
9757 </front>
9758 <seriesInfo name="RFC" value="793" />
9759 </reference>
9760 <reference anchor="RFC2234">
9761 <front>
9762 <title>Augmented BNF for Syntax Specifications</title>
9763 <author initials="D.H." surname="Crocker" fullname="David H. Crocker">
9764 <organization>Internet Mail Consortium</organization>
9765 </author>
9766 <author initials="P." surname="Overell" fullname="Paul Overell">
9767 <organization>Demon Internet Ltd</organization>
9768 </author>
9769 <date year="1997"></date>
9770 </front>
9771 <seriesInfo name="RFC" value="2234" />
9772 </reference>
9773 <reference anchor="RFC20">
9774 <front>
9775 <title>ASCII format for Network Interchange</title>
9776 <author>
9777 <organization>UCLA</organization>
9778 </author>
9779 <date year="1969"></date>
9780 </front>
9781 <seriesInfo name="RFC" value="20" />
9782 </reference>
9783 </references>
9784 </back>
9785
9786 </rfc>
  ViewVC Help
Powered by ViewVC