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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2500 - (show annotations) (download) (as text)
Fri Jan 10 12:20:05 2014 UTC (10 years, 2 months ago) by schoenebeck
File MIME type: text/xml
File size: 496852 byte(s)
* Added support for multiple MIDI input ports per sampler channel (added
  various new C++ API methods for this new feature/design, old C++ API
  methods are now marked as deprecated but should still provide full
  behavior backward compatibility).
* LSCP Network interface: Added the following new LSCP commands for the new
  feature mentioned above: "ADD CHANNEL MIDI_INPUT",
  "REMOVE CHANNEL MIDI_INPUT" and "LIST CHANNEL MIDI_INPUTS". As with the
  C++ API changes, the old LSCP commands for MIDI input management are now
  marked as deprecated, but are still there and should provide full behavior
  backward compatibility.
* New LSCP specification document (LSCP v1.6).
* AbstractEngine::GSCheckSum(): don't allocate memory on the stack (was
  unsafe and caused compilation error with old clang 2.x).
* Bumped version (1.0.0.svn25).

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

  ViewVC Help
Powered by ViewVC