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