/[svn]/web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.txt
ViewVC logotype

Contents of /web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 993 - (show annotations) (download)
Wed Dec 20 19:56:43 2006 UTC (17 years, 3 months ago) by iliev
File MIME type: text/plain
File size: 150503 byte(s)
- Added new notification events for tracking audio/MIDI device
  changes, MIDI instrument map changes and MIDI instrument changes

1
2
3
4 LinuxSampler Developers C. Schoenebeck
5 Internet-Draft Interessengemeinschaft Software
6 Intended status: Standards Track Engineering e. V.
7 Expires: June 23, 2007 December 20, 2006
8
9
10 LinuxSampler Control Protocol
11 LSCP 1.2
12
13 Status of this Memo
14
15 By submitting this Internet-Draft, each author represents that any
16 applicable patent or other IPR claims of which he or she is aware
17 have been or will be disclosed, and any of which he or she becomes
18 aware will be disclosed, in accordance with Section 6 of BCP 79.
19
20 Internet-Drafts are working documents of the Internet Engineering
21 Task Force (IETF), its areas, and its working groups. Note that
22 other groups may also distribute working documents as Internet-
23 Drafts.
24
25 Internet-Drafts are draft documents valid for a maximum of six months
26 and may be updated, replaced, or obsoleted by other documents at any
27 time. It is inappropriate to use Internet-Drafts as reference
28 material or to cite them other than as "work in progress."
29
30 The list of current Internet-Drafts can be accessed at
31 http://www.ietf.org/ietf/1id-abstracts.txt.
32
33 The list of Internet-Draft Shadow Directories can be accessed at
34 http://www.ietf.org/shadow.html.
35
36 This Internet-Draft will expire on June 23, 2007.
37
38 Copyright Notice
39
40 Copyright (C) The Internet Society (2006).
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55 Schoenebeck Expires June 23, 2007 [Page 1]
56
57 Internet-Draft LinuxSampler Control Protocol December 2006
58
59
60 Abstract
61
62 The LinuxSampler Control Protocol (LSCP) is an application-level
63 protocol primarily intended for local and remote controlling the
64 LinuxSampler backend application, which is a sophisticated server-
65 like console application essentially playing back audio samples and
66 manipulating the samples in real time to certain extent.
67
68
69 Table of Contents
70
71 1. Requirements notation . . . . . . . . . . . . . . . . . . . . 5
72 2. Versioning of this specification . . . . . . . . . . . . . . . 6
73 3. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 7
74 4. Focus of this protocol . . . . . . . . . . . . . . . . . . . . 8
75 5. Communication Overview . . . . . . . . . . . . . . . . . . . . 9
76 5.1. Request/response communication method . . . . . . . . . . 9
77 5.1.1. Result format . . . . . . . . . . . . . . . . . . . . 10
78 5.2. Subscribe/notify communication method . . . . . . . . . . 12
79 6. Description for control commands . . . . . . . . . . . . . . . 14
80 6.1. Ignored lines and comments . . . . . . . . . . . . . . . . 14
81 6.2. Configuring audio drivers . . . . . . . . . . . . . . . . 14
82 6.2.1. Getting amount of available audio output drivers . . . 15
83 6.2.2. Getting all available audio output drivers . . . . . . 15
84 6.2.3. Getting information about a specific audio output
85 driver . . . . . . . . . . . . . . . . . . . . . . . . 15
86 6.2.4. Getting information about specific audio output
87 driver parameter . . . . . . . . . . . . . . . . . . . 16
88 6.2.5. Creating an audio output device . . . . . . . . . . . 20
89 6.2.6. Destroying an audio output device . . . . . . . . . . 21
90 6.2.7. Getting all created audio output device count . . . . 22
91 6.2.8. Getting all created audio output device list . . . . . 22
92 6.2.9. Getting current settings of an audio output device . . 22
93 6.2.10. Changing settings of audio output devices . . . . . . 24
94 6.2.11. Getting information about an audio channel . . . . . . 25
95 6.2.12. Getting information about specific audio channel
96 parameter . . . . . . . . . . . . . . . . . . . . . . 26
97 6.2.13. Changing settings of audio output channels . . . . . . 28
98 6.3. Configuring MIDI input drivers . . . . . . . . . . . . . . 29
99 6.3.1. Getting amount of available MIDI input drivers . . . . 30
100 6.3.2. Getting all available MIDI input drivers . . . . . . . 30
101 6.3.3. Getting information about a specific MIDI input
102 driver . . . . . . . . . . . . . . . . . . . . . . . . 31
103 6.3.4. Getting information about specific MIDI input
104 driver parameter . . . . . . . . . . . . . . . . . . . 32
105 6.3.5. Creating a MIDI input device . . . . . . . . . . . . . 34
106 6.3.6. Destroying a MIDI input device . . . . . . . . . . . . 35
107 6.3.7. Getting all created MIDI input device count . . . . . 36
108
109
110
111 Schoenebeck Expires June 23, 2007 [Page 2]
112
113 Internet-Draft LinuxSampler Control Protocol December 2006
114
115
116 6.3.8. Getting all created MIDI input device list . . . . . . 36
117 6.3.9. Getting current settings of a MIDI input device . . . 37
118 6.3.10. Changing settings of MIDI input devices . . . . . . . 38
119 6.3.11. Getting information about a MIDI port . . . . . . . . 38
120 6.3.12. Getting information about specific MIDI port
121 parameter . . . . . . . . . . . . . . . . . . . . . . 39
122 6.3.13. Changing settings of MIDI input ports . . . . . . . . 41
123 6.4. Configuring sampler channels . . . . . . . . . . . . . . . 42
124 6.4.1. Loading an instrument . . . . . . . . . . . . . . . . 42
125 6.4.2. Loading a sampler engine . . . . . . . . . . . . . . . 43
126 6.4.3. Getting all created sampler channel count . . . . . . 44
127 6.4.4. Getting all created sampler channel list . . . . . . . 44
128 6.4.5. Adding a new sampler channel . . . . . . . . . . . . . 44
129 6.4.6. Removing a sampler channel . . . . . . . . . . . . . . 45
130 6.4.7. Getting amount of available engines . . . . . . . . . 46
131 6.4.8. Getting all available engines . . . . . . . . . . . . 46
132 6.4.9. Getting information about an engine . . . . . . . . . 47
133 6.4.10. Getting sampler channel information . . . . . . . . . 48
134 6.4.11. Current number of active voices . . . . . . . . . . . 51
135 6.4.12. Current number of active disk streams . . . . . . . . 51
136 6.4.13. Current fill state of disk stream buffers . . . . . . 52
137 6.4.14. Setting audio output device . . . . . . . . . . . . . 53
138 6.4.15. Setting audio output type . . . . . . . . . . . . . . 53
139 6.4.16. Setting audio output channel . . . . . . . . . . . . . 54
140 6.4.17. Setting MIDI input device . . . . . . . . . . . . . . 55
141 6.4.18. Setting MIDI input type . . . . . . . . . . . . . . . 56
142 6.4.19. Setting MIDI input port . . . . . . . . . . . . . . . 56
143 6.4.20. Setting MIDI input channel . . . . . . . . . . . . . . 57
144 6.4.21. Setting channel volume . . . . . . . . . . . . . . . . 58
145 6.4.22. Muting a sampler channel . . . . . . . . . . . . . . . 58
146 6.4.23. Soloing a sampler channel . . . . . . . . . . . . . . 59
147 6.4.24. Assigning a MIDI instrument map to a sampler
148 channel . . . . . . . . . . . . . . . . . . . . . . . 60
149 6.4.25. Resetting a sampler channel . . . . . . . . . . . . . 61
150 6.5. Controlling connection . . . . . . . . . . . . . . . . . . 61
151 6.5.1. Register front-end for receiving event messages . . . 61
152 6.5.2. Unregister front-end for not receiving event
153 messages . . . . . . . . . . . . . . . . . . . . . . . 62
154 6.5.3. Enable or disable echo of commands . . . . . . . . . . 63
155 6.5.4. Close client connection . . . . . . . . . . . . . . . 63
156 6.6. Global commands . . . . . . . . . . . . . . . . . . . . . 64
157 6.6.1. Current number of active voices . . . . . . . . . . . 64
158 6.6.2. Maximum amount of active voices . . . . . . . . . . . 64
159 6.6.3. Reset sampler . . . . . . . . . . . . . . . . . . . . 64
160 6.6.4. General sampler informations . . . . . . . . . . . . . 65
161 6.7. MIDI Instrument Mapping . . . . . . . . . . . . . . . . . 65
162 6.7.1. Create a new MIDI instrument map . . . . . . . . . . . 66
163 6.7.2. Delete one particular or all MIDI instrument maps . . 67
164
165
166
167 Schoenebeck Expires June 23, 2007 [Page 3]
168
169 Internet-Draft LinuxSampler Control Protocol December 2006
170
171
172 6.7.3. Get amount of existing MIDI instrument maps . . . . . 67
173 6.7.4. Getting all created MIDI instrument maps . . . . . . . 68
174 6.7.5. Getting MIDI instrument map information . . . . . . . 68
175 6.7.6. Renaming a MIDI instrument map . . . . . . . . . . . . 69
176 6.7.7. Create or replace a MIDI instrument map entry . . . . 69
177 6.7.8. Getting ammount of MIDI instrument map entries . . . . 72
178 6.7.9. Getting indeces of all entries of a MIDI
179 instrument map . . . . . . . . . . . . . . . . . . . . 73
180 6.7.10. Remove an entry from the MIDI instrument map . . . . . 73
181 6.7.11. Get current settings of MIDI instrument map entry . . 74
182 6.7.12. Clear MIDI instrument map . . . . . . . . . . . . . . 76
183 7. Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . 77
184 8. Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
185 8.1. Number of audio output devices changed . . . . . . . . . . 87
186 8.2. Audio output device's settings changed . . . . . . . . . . 87
187 8.3. Number of MIDI input devices changed . . . . . . . . . . . 87
188 8.4. MIDI input device's settings changed . . . . . . . . . . . 88
189 8.5. Number of sampler channels changed . . . . . . . . . . . . 88
190 8.6. Number of active voices changed . . . . . . . . . . . . . 88
191 8.7. Number of active disk streams changed . . . . . . . . . . 89
192 8.8. Disk stream buffer fill state changed . . . . . . . . . . 89
193 8.9. Channel information changed . . . . . . . . . . . . . . . 89
194 8.10. Total number of active voices changed . . . . . . . . . . 90
195 8.11. Number of MIDI instrument maps changed . . . . . . . . . . 90
196 8.12. MIDI instrument map information changed . . . . . . . . . 90
197 8.13. Number of MIDI instruments changed . . . . . . . . . . . . 91
198 8.14. MIDI instrument information changed . . . . . . . . . . . 91
199 8.15. Miscellaneous and debugging events . . . . . . . . . . . . 92
200 9. Security Considerations . . . . . . . . . . . . . . . . . . . 93
201 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 94
202 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 95
203 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 96
204 Intellectual Property and Copyright Statements . . . . . . . . . . 97
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223 Schoenebeck Expires June 23, 2007 [Page 4]
224
225 Internet-Draft LinuxSampler Control Protocol December 2006
226
227
228 1. Requirements notation
229
230 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
231 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
232 document are to be interpreted as described in [RFC2119].
233
234 This protocol is always case-sensitive if not explicitly claimed the
235 opposite.
236
237 In examples, "C:" and "S:" indicate lines sent by the client (front-
238 end) and server (LinuxSampler) respectively. Lines in examples must
239 be interpreted as every line being CRLF terminated (carriage return
240 character followed by line feed character as defined in the ASCII
241 standard), thus the following example:
242
243 C: "some line"
244
245 "another line"
246
247 must actually be interpreted as client sending the following message:
248
249 "some line<CR><LF>another line<CR><LF>"
250
251 where <CR> symbolizes the carriage return character and <LF> the line
252 feed character as defined in the ASCII standard.
253
254 Due to technical reasons, messages can arbitrary be fragmented, means
255 the following example:
256
257 S: "abcd"
258
259 could also happen to be sent in three messages like in the following
260 sequence scenario:
261
262 o server sending message "a"
263
264 o followed by a delay (pause) with arbitrary duration
265
266 o followed by server sending message "bcd<CR>"
267
268 o again followed by a delay (pause) with arbitrary duration
269
270 o followed by server sending the message "<LF>"
271
272 where again <CR> and <LF> symbolize the carriage return and line feed
273 characters respectively.
274
275
276
277
278
279 Schoenebeck Expires June 23, 2007 [Page 5]
280
281 Internet-Draft LinuxSampler Control Protocol December 2006
282
283
284 2. Versioning of this specification
285
286 LSCP will certainly be extended and enhanced by-and-by. Each
287 official release of the LSCP specification will be tagged with a
288 unique version tuple. The version tuple consists at least of a major
289 and minor version number like:
290
291 "1.2"
292
293 In this example the major version number would be "1" and the minor
294 version number would be "2". Note that the version tuple might also
295 have more than two elements. The major version number defines a
296 group of backward compatible versions. That means a frontend is
297 compatible to the connected sampler if and only if the LSCP versions
298 to which each of the two parties complies to, match both of the
299 following rules:
300
301 Compatibility:
302
303 1. The frontend's LSCP major version and the sampler's LSCP major
304 version are exactly equal.
305
306 2. The frontend's LSCP minor version is less or equal than the
307 sampler's LSCP minor version.
308
309 Compatibility can only be claimed if both rules are true. The
310 frontend can use the "GET SERVER INFO" (Section 6.6.4) command to get
311 the version of the LSCP specification the sampler complies with.
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335 Schoenebeck Expires June 23, 2007 [Page 6]
336
337 Internet-Draft LinuxSampler Control Protocol December 2006
338
339
340 3. Introduction
341
342 LinuxSampler is a so called software sampler application capable to
343 playback audio samples from a computer's Random Access Memory (RAM)
344 as well as directly streaming it from disk. LinuxSampler is designed
345 to be modular. It provides several so called "sampler engines" where
346 each engine is specialized for a certain purpose. LinuxSampler has
347 virtual channels which will be referred in this document as "sampler
348 channels". The channels are in such way virtual as they can be
349 connected to an arbitrary MIDI input method and arbitrary MIDI
350 channel (e.g. sampler channel 17 could be connected to an ALSA
351 sequencer device 64:0 and listening to MIDI channel 1 there). Each
352 sampler channel will be associated with an instance of one of the
353 available sampler engines (e.g. GigEngine, DLSEngine). The audio
354 output of each sampler channel can be routed to an arbitrary audio
355 output method (ALSA / JACK) and an arbitrary audio output channel
356 there.
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391 Schoenebeck Expires June 23, 2007 [Page 7]
392
393 Internet-Draft LinuxSampler Control Protocol December 2006
394
395
396 4. Focus of this protocol
397
398 Main focus of this protocol is to provide a way to configure a
399 running LinuxSampler instance and to retrieve information about it.
400 The focus of this protocol is not to provide a way to control
401 synthesis parameters or even to trigger or release notes. Or in
402 other words; the focus are those functionalities which are not
403 covered by MIDI or which may at most be handled via MIDI System
404 Exclusive Messages.
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447 Schoenebeck Expires June 23, 2007 [Page 8]
448
449 Internet-Draft LinuxSampler Control Protocol December 2006
450
451
452 5. Communication Overview
453
454 There are two distinct methods of communication between a running
455 instance of LinuxSampler and one or more control applications, so
456 called "front-ends": a simple request/response communication method
457 used by the clients to give commands to the server as well as to
458 inquire about server's status and a subscribe/notify communication
459 method used by the client to subscribe to and receive notifications
460 of certain events as they happen on the server. The latter needs
461 more effort to be implemented in the front-end application. The two
462 communication methods will be described next.
463
464 5.1. Request/response communication method
465
466 This simple communication method is based on TCP [RFC793]. The
467 front-end application establishes a TCP connection to the
468 LinuxSampler instance on a certain host system. Then the front-end
469 application will send certain ASCII based commands as defined in this
470 document (every command line must be CRLF terminated - see
471 "Conventions used in this document" at the beginning of this
472 document) and the LinuxSampler application will response after a
473 certain process time with an appropriate ASCII based answer, also as
474 defined in this document. So this TCP communication is simply based
475 on query and answer paradigm. That way LinuxSampler is only able to
476 answer on queries from front-ends, but not able to automatically send
477 messages to the client if it's not asked to. The fronted should not
478 reconnect to LinuxSampler for every single command, instead it should
479 keep the connection established and simply resend message(s) for
480 subsequent commands. To keep information in the front-end up-to-date
481 the front-end has to periodically send new requests to get the
482 current information from the LinuxSampler instance. This is often
483 referred to as "polling". While polling is simple to implement and
484 may be OK to use in some cases, there may be disadvantages to polling
485 such as network traffic overhead and information being out of date.
486 It is possible for a client or several clients to open more than one
487 connection to the server at the same time. It is also possible to
488 send more than one request to the server at the same time but if
489 those requests are sent over the same connection server MUST execute
490 them sequentially. Upon executing a request server will produce a
491 result set and send it to the client. Each and every request made by
492 the client MUST result in a result set being sent back to the client.
493 No other data other than a result set may be sent by a server to a
494 client. No result set may be sent to a client without the client
495 sending request to the server first. On any particular connection,
496 result sets MUST be sent in their entirety without being interrupted
497 by other result sets. If several requests got queued up at the
498 server they MUST be processed in the order they were received and
499 result sets MUST be sent back in the same order.
500
501
502
503 Schoenebeck Expires June 23, 2007 [Page 9]
504
505 Internet-Draft LinuxSampler Control Protocol December 2006
506
507
508 5.1.1. Result format
509
510 Result set could be one of the following types:
511
512 1. Normal
513
514 2. Warning
515
516 3. Error
517
518 Warning and Error result sets MUST be single line and have the
519 following format:
520
521 o "WRN:<warning-code>:<warning-message>"
522
523 o "ERR:<error-code>:<error-message>"
524
525 Where <warning-code> and <error-code> are numeric unique identifiers
526 of the warning or error and <warning-message> and <error-message> are
527 human readable descriptions of the warning or error respectively.
528
529 Examples:
530
531 C: "LOAD INSTRUMENT '/home/me/Boesendorfer24bit.gig" 0 0
532
533 S: "WRN:32:This is a 24 bit patch which is not supported natively
534 yet."
535
536 C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA EAR"
537
538 S: "ERR:3456:Audio output driver 'ALSA' does not have a parameter
539 'EAR'."
540
541 C: "GET AUDIO_OUTPUT_DEVICE INFO 123456"
542
543 S: "ERR:9:There is no audio output device with index 123456."
544
545 Normal result sets could be:
546
547 1. Empty
548
549 2. Single line
550
551 3. Multi-line
552
553 Empty result set is issued when the server only needed to acknowledge
554 the fact that the request was received and it was processed
555 successfully and no additional information is available. This result
556
557
558
559 Schoenebeck Expires June 23, 2007 [Page 10]
560
561 Internet-Draft LinuxSampler Control Protocol December 2006
562
563
564 set has the following format:
565
566 "OK"
567
568 Example:
569
570 C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 CHANNELS=4"
571
572 S: "OK"
573
574 Single line result sets are command specific. One example of a
575 single line result set is an empty line. Multi-line result sets are
576 command specific and may include one or more lines of information.
577 They MUST always end with the following line:
578
579 "."
580
581 Example:
582
583 C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
584
585 S: "DRIVER: ALSA"
586
587 "CHANNELS: 2"
588
589 "SAMPLERATE: 44100"
590
591 "ACTIVE: true"
592
593 "FRAGMENTS: 2"
594
595 "FRAGMENTSIZE: 128"
596
597 "CARD: '0,0'"
598
599 "."
600
601 In addition to above mentioned formats, warnings and empty result
602 sets MAY be indexed. In this case, they have the following formats
603 respectively:
604
605 o "WRN[<index>]:<warning-code>:<warning-message>"
606
607 o "OK[<index>]"
608
609 where <index> is command specific and is used to indicate channel
610 number that the result set was related to or other integer value.
611
612
613
614
615 Schoenebeck Expires June 23, 2007 [Page 11]
616
617 Internet-Draft LinuxSampler Control Protocol December 2006
618
619
620 Each line of the result set MUST end with <CRLF>.
621
622 Examples:
623
624 C: "ADD CHANNEL"
625
626 S: "OK[12]"
627
628 C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"
629
630 S: "WRN[0]:32:Sample rate not supported, using 44100 instead."
631
632 5.2. Subscribe/notify communication method
633
634 This more sophisticated communication method is actually only an
635 extension of the simple request/response communication method. The
636 front-end still uses a TCP connection and sends the same commands on
637 the TCP connection. Two extra commands are SUBSCRIBE and UNSUBSCRIBE
638 commands that allow a client to tell the server that it is interested
639 in receiving notifications about certain events as they happen on the
640 server. The SUBSCRIBE command has the following syntax:
641
642 SUBSCRIBE <event-id>
643
644 where <event-id> will be replaced by the respective event that client
645 wants to subscribe to. Upon receiving such request, server SHOULD
646 respond with OK and start sending EVENT notifications when a given
647 even has occurred to the front-end when an event has occurred. It
648 MAY be possible certain events may be sent before OK response during
649 real time nature of their generation. Event messages have the
650 following format:
651
652 NOTIFY:<event-id>:<custom-event-data>
653
654 where <event-id> uniquely identifies the event that has occurred and
655 <custom-event-data> is event specific.
656
657 Several rules must be followed by the server when generating events:
658
659 1. Events MUST NOT be sent to any client who has not issued an
660 appropriate SUBSCRIBE command.
661
662 2. Events MUST only be sent using the same connection that was used
663 to subscribe to them.
664
665 3. When response is being sent to the client, event MUST be inserted
666 in the stream before or after the response, but NOT in the
667 middle. Same is true about the response. It should never be
668
669
670
671 Schoenebeck Expires June 23, 2007 [Page 12]
672
673 Internet-Draft LinuxSampler Control Protocol December 2006
674
675
676 inserted in the middle of the event message as well as any other
677 response.
678
679 If the client is not interested in a particular event anymore it MAY
680 issue UNSUBSCRIBE command using the following syntax:
681
682 UNSUBSCRIBE <event-id>
683
684 where <event-id> will be replace by the respective event that client
685 is no longer interested in receiving. For a list of supported events
686 see Section 8.
687
688 Example: the fill states of disk stream buffers have changed on
689 sampler channel 4 and the LinuxSampler instance will react by sending
690 the following message to all clients who subscribed to this event:
691
692 NOTIFY:CHANNEL_BUFFER_FILL:4 [35]62%,[33]80%,[37]98%
693
694 Which means there are currently three active streams on sampler
695 channel 4, where the stream with ID "35" is filled by 62%, stream
696 with ID 33 is filled by 80% and stream with ID 37 is filled by 98%.
697
698 Clients may choose to open more than one connection to the server and
699 use some connections to receive notifications while using other
700 connections to issue commands to the back-end. This is entirely
701 legal and up to the implementation. This does not change the
702 protocol in any way and no special restrictions exist on the server
703 to allow or disallow this or to track what connections belong to what
704 front-ends. Server will listen on a single port, accept multiple
705 connections and support protocol described in this specification in
706 it's entirety on this single port on each connection that it
707 accepted.
708
709 Due to the fact that TCP is used for this communication, dead peers
710 will be detected automatically by the OS TCP stack. While it may
711 take a while to detect dead peers if no traffic is being sent from
712 server to client (TCP keep-alive timer is set to 2 hours on many
713 OSes) it will not be an issue here as when notifications are sent by
714 the server, dead client will be detected quickly.
715
716 When connection is closed for any reason server MUST forget all
717 subscriptions that were made on this connection. If client
718 reconnects it MUST resubscribe to all events that it wants to
719 receive.
720
721
722
723
724
725
726
727 Schoenebeck Expires June 23, 2007 [Page 13]
728
729 Internet-Draft LinuxSampler Control Protocol December 2006
730
731
732 6. Description for control commands
733
734 This chapter will describe the available control commands that can be
735 sent on the TCP connection in detail. Some certain commands (e.g.
736 "GET CHANNEL INFO" (Section 6.4.10) or "GET ENGINE INFO"
737 (Section 6.4.9)) lead to multiple-line responses. In this case
738 LinuxSampler signals the end of the response by a "." (single dot)
739 line.
740
741 6.1. Ignored lines and comments
742
743 White lines, that is lines which only contain space and tabulator
744 characters, and lines that start with a "#" character are ignored,
745 thus it's possible for example to group commands and to place
746 comments in a LSCP script file.
747
748 6.2. Configuring audio drivers
749
750 Instances of drivers in LinuxSampler are called devices. You can use
751 multiple audio devices simultaneously, e.g. to output the sound of
752 one sampler channel using the ALSA audio output driver, and on
753 another sampler channel you might want to use the JACK audio output
754 driver. For particular audio output systems it's also possible to
755 create several devices of the same audio output driver, e.g. two
756 separate ALSA audio output devices for using two different sound
757 cards at the same time. This chapter describes all commands to
758 configure LinuxSampler's audio output devices and their parameters.
759
760 Instead of defining commands and parameters for each driver
761 individually, all possible parameters, their meanings and possible
762 values have to be obtained at runtime. This makes the protocol a bit
763 abstract, but has the advantage, that front-ends can be written
764 independently of what drivers are currently implemented and what
765 parameters these drivers are actually offering. This means front-
766 ends can even handle drivers which are implemented somewhere in
767 future without modifying the front-end at all.
768
769 Note: examples in this chapter showing particular parameters of
770 drivers are not meant as specification of the drivers' parameters.
771 Driver implementations in LinuxSampler might have complete different
772 parameter names and meanings than shown in these examples or might
773 change in future, so these examples are only meant for showing how to
774 retrieve what parameters drivers are offering, how to retrieve their
775 possible values, etc.
776
777
778
779
780
781
782
783 Schoenebeck Expires June 23, 2007 [Page 14]
784
785 Internet-Draft LinuxSampler Control Protocol December 2006
786
787
788 6.2.1. Getting amount of available audio output drivers
789
790 Use the following command to get the number of audio output drivers
791 currently available for the LinuxSampler instance:
792
793 GET AVAILABLE_AUDIO_OUTPUT_DRIVERS
794
795 Possible Answers:
796
797 LinuxSampler will answer by sending the number of audio output
798 drivers.
799
800 Example:
801
802 C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
803
804 S: "2"
805
806 6.2.2. Getting all available audio output drivers
807
808 Use the following command to list all audio output drivers currently
809 available for the LinuxSampler instance:
810
811 LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS
812
813 Possible Answers:
814
815 LinuxSampler will answer by sending comma separated character
816 strings, each symbolizing an audio output driver.
817
818 Example:
819
820 C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"
821
822 S: "ALSA,JACK"
823
824 6.2.3. Getting information about a specific audio output driver
825
826 Use the following command to get detailed information about a
827 specific audio output driver:
828
829 GET AUDIO_OUTPUT_DRIVER INFO <audio-output-driver>
830
831 Where <audio-output-driver> is the name of the audio output driver,
832 returned by the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2)
833 command.
834
835 Possible Answers:
836
837
838
839 Schoenebeck Expires June 23, 2007 [Page 15]
840
841 Internet-Draft LinuxSampler Control Protocol December 2006
842
843
844 LinuxSampler will answer by sending a <CRLF> separated list. Each
845 answer line begins with the information category name followed by
846 a colon and then a space character <SP> and finally the info
847 character string to that info category. At the moment the
848 following information categories are defined:
849
850
851
852 DESCRIPTION -
853
854 character string describing the audio output driver
855
856 VERSION -
857
858 character string reflecting the driver's version
859
860 PARAMETERS -
861
862 comma separated list of all parameters available for the
863 given audio output driver, at least parameters 'channels',
864 'samplerate' and 'active' are offered by all audio output
865 drivers
866
867 The mentioned fields above don't have to be in particular order.
868
869 Example:
870
871 C: "GET AUDIO_OUTPUT_DRIVER INFO ALSA"
872
873 S: "DESCRIPTION: Advanced Linux Sound Architecture"
874
875 "VERSION: 1.0"
876
877 "PARAMETERS: DRIVER,CHANNELS,SAMPLERATE,ACTIVE,FRAGMENTS,
878 FRAGMENTSIZE,CARD"
879
880 "."
881
882 6.2.4. Getting information about specific audio output driver parameter
883
884 Use the following command to get detailed information about a
885 specific audio output driver parameter:
886
887 GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO <audio> <prm> [<deplist>]
888
889 Where <audio> is the name of the audio output driver as returned by
890 the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2) command,
891 <prm> a specific parameter name for which information should be
892
893
894
895 Schoenebeck Expires June 23, 2007 [Page 16]
896
897 Internet-Draft LinuxSampler Control Protocol December 2006
898
899
900 obtained (as returned by the "GET AUDIO_OUTPUT_DRIVER INFO"
901 (Section 6.2.3) command) and <deplist> is an optional list of
902 parameters on which the sought parameter <prm> depends on, <deplist>
903 is a list of key-value pairs in form of "key1=val1 key2=val2 ...",
904 where character string values are encapsulated into apostrophes (').
905 Arguments given with <deplist> which are not dependency parameters of
906 <prm> will be ignored, means the front-end application can simply put
907 all parameters into <deplist> with the values already selected by the
908 user.
909
910 Possible Answers:
911
912 LinuxSampler will answer by sending a <CRLF> separated list. Each
913 answer line begins with the information category name followed by
914 a colon and then a space character <SP> and finally the info
915 character string to that info category. There are information
916 which is always returned, independently of the given driver
917 parameter and there are optional information which is only shown
918 dependently to given driver parameter. At the moment the
919 following information categories are defined:
920
921 TYPE -
922
923 either "BOOL" for boolean value(s) or "INT" for integer
924 value(s) or "FLOAT" for dotted number(s) or "STRING" for
925 character string(s) (always returned, no matter which driver
926 parameter)
927
928 DESCRIPTION -
929
930 arbitrary text describing the purpose of the parameter (always
931 returned, no matter which driver parameter)
932
933 MANDATORY -
934
935 either true or false, defines if this parameter must be given
936 when the device is to be created with the 'CREATE
937 AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command (always returned,
938 no matter which driver parameter)
939
940 FIX -
941
942 either true or false, if false then this parameter can be
943 changed at any time, once the device is created by the 'CREATE
944 AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command (always returned,
945 no matter which driver parameter)
946
947
948
949
950
951 Schoenebeck Expires June 23, 2007 [Page 17]
952
953 Internet-Draft LinuxSampler Control Protocol December 2006
954
955
956 MULTIPLICITY -
957
958 either true or false, defines if this parameter allows only one
959 value or a list of values, where true means multiple values and
960 false only a single value allowed (always returned, no matter
961 which driver parameter)
962
963 DEPENDS -
964
965 comma separated list of parameters this parameter depends on,
966 means the values for fields 'DEFAULT', 'RANGE_MIN', 'RANGE_MAX'
967 and 'POSSIBILITIES' might depend on these listed parameters,
968 for example assuming that an audio driver (like the ALSA
969 driver) offers parameters 'card' and 'samplerate' then
970 parameter 'samplerate' would depend on 'card' because the
971 possible values for 'samplerate' depends on the sound card
972 which can be chosen by the 'card' parameter (optionally
973 returned, dependent to driver parameter)
974
975 DEFAULT -
976
977 reflects the default value for this parameter which is used
978 when the device is created and not explicitly given with the
979 'CREATE AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command, in case
980 of MULTIPLCITY=true, this is a comma separated list, that's why
981 character strings are encapsulated into apostrophes (')
982 (optionally returned, dependent to driver parameter)
983
984 RANGE_MIN -
985
986 defines lower limit of the allowed value range for this
987 parameter, can be an integer value as well as a dotted number,
988 this parameter is often used in conjunction with RANGE_MAX, but
989 may also appear without (optionally returned, dependent to
990 driver parameter)
991
992 RANGE_MAX -
993
994 defines upper limit of the allowed value range for this
995 parameter, can be an integer value as well as a dotted number,
996 this parameter is often used in conjunction with RANGE_MIN, but
997 may also appear without (optionally returned, dependent to
998 driver parameter)
999
1000 POSSIBILITIES -
1001
1002 comma separated list of possible values for this parameter,
1003 character strings are encapsulated into apostrophes (optionally
1004
1005
1006
1007 Schoenebeck Expires June 23, 2007 [Page 18]
1008
1009 Internet-Draft LinuxSampler Control Protocol December 2006
1010
1011
1012 returned, dependent to driver parameter)
1013
1014 The mentioned fields above don't have to be in particular order.
1015
1016 Examples:
1017
1018 C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA CARD"
1019
1020 S: "DESCRIPTION: sound card to be used"
1021
1022 "TYPE: STRING"
1023
1024 "MANDATORY: false"
1025
1026 "FIX: true"
1027
1028 "MULTIPLICITY: false"
1029
1030 "DEFAULT: '0,0'"
1031
1032 "POSSIBILITIES: '0,0','1,0','2,0'"
1033
1034 "."
1035
1036 C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE"
1037
1038 S: "DESCRIPTION: output sample rate in Hz"
1039
1040 "TYPE: INT"
1041
1042 "MANDATORY: false"
1043
1044 "FIX: false"
1045
1046 "MULTIPLICITY: false"
1047
1048 "DEPENDS: card"
1049
1050 "DEFAULT: 44100"
1051
1052 "."
1053
1054 C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE
1055 CARD='0,0'"
1056
1057 S: "DESCRIPTION: output sample rate in Hz"
1058
1059
1060
1061
1062
1063 Schoenebeck Expires June 23, 2007 [Page 19]
1064
1065 Internet-Draft LinuxSampler Control Protocol December 2006
1066
1067
1068 "TYPE: INT"
1069
1070 "MANDATORY: false"
1071
1072 "FIX: false"
1073
1074 "MULTIPLICITY: false"
1075
1076 "DEPENDS: card"
1077
1078 "DEFAULT: 44100"
1079
1080 "RANGE_MIN: 22050"
1081
1082 "RANGE_MAX: 96000"
1083
1084 "."
1085
1086 6.2.5. Creating an audio output device
1087
1088 Use the following command to create a new audio output device for the
1089 desired audio output system:
1090
1091 CREATE AUDIO_OUTPUT_DEVICE <audio-output-driver> [<param-list>]
1092
1093 Where <audio-output-driver> should be replaced by the desired audio
1094 output system as returned by the "LIST
1095 AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2) command and <param-
1096 list> by an optional list of driver specific parameters in form of
1097 "key1=val1 key2=val2 ...", where character string values should be
1098 encapsulated into apostrophes ('). Note that there might be drivers
1099 which require parameter(s) to be given with this command. Use the
1100 previously described commands in this chapter to get this
1101 information.
1102
1103 Possible Answers:
1104
1105 "OK[<device-id>]" -
1106
1107 in case the device was successfully created, where <device-id>
1108 is the numerical ID of the new device
1109
1110 "WRN[<device-id>]:<warning-code>:<warning-message>" -
1111
1112 in case the device was created successfully, where <device-id>
1113 is the numerical ID of the new device, but there are noteworthy
1114 issue(s) related (e.g. sound card doesn't support given
1115 hardware parameters and the driver is using fall-back values),
1116
1117
1118
1119 Schoenebeck Expires June 23, 2007 [Page 20]
1120
1121 Internet-Draft LinuxSampler Control Protocol December 2006
1122
1123
1124 providing an appropriate warning code and warning message
1125
1126 "ERR:<error-code>:<error-message>" -
1127
1128 in case it failed, providing an appropriate error code and
1129 error message
1130
1131 Examples:
1132
1133 C: "CREATE AUDIO_OUTPUT_DEVICE ALSA"
1134
1135 S: "OK[0]"
1136
1137 C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"
1138
1139 S: "OK[1]"
1140
1141 6.2.6. Destroying an audio output device
1142
1143 Use the following command to destroy a created output device:
1144
1145 DESTROY AUDIO_OUTPUT_DEVICE <device-id>
1146
1147 Where <device-id> should be replaced by the numerical ID of the audio
1148 output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
1149 (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
1150 command.
1151
1152 Possible Answers:
1153
1154 "OK" -
1155
1156 in case the device was successfully destroyed
1157
1158 "WRN:<warning-code>:<warning-message>" -
1159
1160 in case the device was destroyed successfully, but there are
1161 noteworthy issue(s) related (e.g. an audio over ethernet driver
1162 was unloaded but the other host might not be informed about
1163 this situation), providing an appropriate warning code and
1164 warning message
1165
1166 "ERR:<error-code>:<error-message>" -
1167
1168 in case it failed, providing an appropriate error code and
1169 error message
1170
1171 Example:
1172
1173
1174
1175 Schoenebeck Expires June 23, 2007 [Page 21]
1176
1177 Internet-Draft LinuxSampler Control Protocol December 2006
1178
1179
1180 C: "DESTROY AUDIO_OUTPUT_DEVICE 0"
1181
1182 S: "OK"
1183
1184 6.2.7. Getting all created audio output device count
1185
1186 Use the following command to count all created audio output devices:
1187
1188 GET AUDIO_OUTPUT_DEVICES
1189
1190 Possible Answers:
1191
1192 LinuxSampler will answer by sending the current number of all
1193 audio output devices.
1194
1195 Example:
1196
1197 C: "GET AUDIO_OUTPUT_DEVICES"
1198
1199 S: "4"
1200
1201 6.2.8. Getting all created audio output device list
1202
1203 Use the following command to list all created audio output devices:
1204
1205 LIST AUDIO_OUTPUT_DEVICES
1206
1207 Possible Answers:
1208
1209 LinuxSampler will answer by sending a comma separated list with
1210 the numerical IDs of all audio output devices.
1211
1212 Example:
1213
1214 C: "LIST AUDIO_OUTPUT_DEVICES"
1215
1216 S: "0,1,4,5"
1217
1218 6.2.9. Getting current settings of an audio output device
1219
1220 Use the following command to get current settings of a specific,
1221 created audio output device:
1222
1223 GET AUDIO_OUTPUT_DEVICE INFO <device-id>
1224
1225 Where <device-id> should be replaced by numerical ID of the audio
1226 output device as e.g. returned by the "LIST AUDIO_OUTPUT_DEVICES"
1227 (Section 6.2.8) command.
1228
1229
1230
1231 Schoenebeck Expires June 23, 2007 [Page 22]
1232
1233 Internet-Draft LinuxSampler Control Protocol December 2006
1234
1235
1236 Possible Answers:
1237
1238 LinuxSampler will answer by sending a <CRLF> separated list. Each
1239 answer line begins with the information category name followed by a
1240 colon and then a space character <SP> and finally the info character
1241 string to that info category. As some parameters might allow
1242 multiple values, character strings are encapsulated into apostrophes
1243 ('). At the moment the following information categories are defined
1244 (independently of device):
1245
1246 DRIVER -
1247
1248 identifier of the used audio output driver, as also returned by
1249 the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2)
1250 command
1251
1252 CHANNELS -
1253
1254 amount of audio output channels this device currently offers
1255
1256 SAMPLERATE -
1257
1258 playback sample rate the device uses
1259
1260 ACTIVE -
1261
1262 either true or false, if false then the audio device is
1263 inactive and doesn't output any sound, nor do the sampler
1264 channels connected to this audio device render any audio
1265
1266 The mentioned fields above don't have to be in particular order. The
1267 fields above are only those fields which are returned by all audio
1268 output devices. Every audio output driver might have its own,
1269 additional driver specific parameters (see Section 6.2.3) which are
1270 also returned by this command.
1271
1272 Example:
1273
1274 C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
1275
1276 S: "DRIVER: ALSA"
1277
1278 "CHANNELS: 2"
1279
1280 "SAMPLERATE: 44100"
1281
1282 "ACTIVE: true"
1283
1284
1285
1286
1287 Schoenebeck Expires June 23, 2007 [Page 23]
1288
1289 Internet-Draft LinuxSampler Control Protocol December 2006
1290
1291
1292 "FRAGMENTS: 2"
1293
1294 "FRAGMENTSIZE: 128"
1295
1296 "CARD: '0,0'"
1297
1298 "."
1299
1300 6.2.10. Changing settings of audio output devices
1301
1302 Use the following command to alter a specific setting of a created
1303 audio output device:
1304
1305 SET AUDIO_OUTPUT_DEVICE_PARAMETER <device-id> <key>=<value>
1306
1307 Where <device-id> should be replaced by the numerical ID of the audio
1308 output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
1309 (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
1310 command, <key> by the name of the parameter to change and <value> by
1311 the new value for this parameter.
1312
1313 Possible Answers:
1314
1315 "OK" -
1316
1317 in case setting was successfully changed
1318
1319 "WRN:<warning-code>:<warning-message>" -
1320
1321 in case setting was changed successfully, but there are
1322 noteworthy issue(s) related, providing an appropriate warning
1323 code and warning message
1324
1325 "ERR:<error-code>:<error-message>" -
1326
1327 in case it failed, providing an appropriate error code and
1328 error message
1329
1330 Example:
1331
1332 C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"
1333
1334 S: "OK"
1335
1336
1337
1338
1339
1340
1341
1342
1343 Schoenebeck Expires June 23, 2007 [Page 24]
1344
1345 Internet-Draft LinuxSampler Control Protocol December 2006
1346
1347
1348 6.2.11. Getting information about an audio channel
1349
1350 Use the following command to get information about an audio channel:
1351
1352 GET AUDIO_OUTPUT_CHANNEL INFO <device-id> <audio-chan>
1353
1354 Where <device-id> is the numerical ID of the audio output device as
1355 given by the "CREATE AUDIO_OUTPUT_DEVICE" (Section 6.2.5) or "LIST
1356 AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command and <audio-chan> the
1357 audio channel number.
1358
1359 Possible Answers:
1360
1361 LinuxSampler will answer by sending a <CRLF> separated list. Each
1362 answer line begins with the information category name followed by
1363 a colon and then a space character <SP> and finally the info
1364 character string to that info category. At the moment the
1365 following information categories are defined:
1366
1367
1368
1369 NAME -
1370
1371 arbitrary character string naming the channel, which doesn't
1372 have to be unique (always returned by all audio channels)
1373
1374 IS_MIX_CHANNEL -
1375
1376 either true or false, a mix-channel is not a real,
1377 independent audio channel, but a virtual channel which is
1378 mixed to another real channel, this mechanism is needed for
1379 sampler engines which need more audio channels than the used
1380 audio system might be able to offer (always returned by all
1381 audio channels)
1382
1383 MIX_CHANNEL_DESTINATION -
1384
1385 numerical ID (positive integer including 0) which reflects
1386 the real audio channel (of the same audio output device)
1387 this mix channel refers to, means where the audio signal
1388 actually will be routed / added to (only returned in case
1389 the audio channel is mix channel)
1390
1391 The mentioned fields above don't have to be in particular order. The
1392 fields above are only those fields which are generally returned for
1393 the described cases by all audio channels regardless of the audio
1394 driver. Every audio channel might have its own, additional driver
1395 and channel specific parameters.
1396
1397
1398
1399 Schoenebeck Expires June 23, 2007 [Page 25]
1400
1401 Internet-Draft LinuxSampler Control Protocol December 2006
1402
1403
1404 Examples:
1405
1406 C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 0"
1407
1408 S: "NAME: studio monitor left"
1409
1410 "IS_MIX_CHANNEL: false"
1411
1412 "."
1413
1414 C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 1"
1415
1416 S: "NAME: studio monitor right"
1417
1418 "IS_MIX_CHANNEL: false"
1419
1420 "."
1421
1422 C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"
1423
1424 S: "NAME: studio monitor left"
1425
1426 "IS_MIX_CHANNEL: true"
1427
1428 "MIX_CHANNEL_DESTINATION: 1"
1429
1430 "."
1431
1432 C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"
1433
1434 S: "NAME: 'ardour (left)'"
1435
1436 "IS_MIX_CHANNEL: false"
1437
1438 "JACK_BINDINGS: 'ardour:0'"
1439
1440 "."
1441
1442 6.2.12. Getting information about specific audio channel parameter
1443
1444 Use the following command to get detailed information about specific
1445 audio channel parameter:
1446
1447 GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO <dev-id> <chan> <param>
1448
1449 Where <dev-id> is the numerical ID of the audio output device as
1450 returned by the "CREATE AUDIO_OUTPUT_DEVICE" (Section 6.2.5) or "LIST
1451 AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command, <chan> the audio
1452
1453
1454
1455 Schoenebeck Expires June 23, 2007 [Page 26]
1456
1457 Internet-Draft LinuxSampler Control Protocol December 2006
1458
1459
1460 channel number and <param> a specific channel parameter name for
1461 which information should be obtained (as returned by the "GET
1462 AUDIO_OUTPUT_CHANNEL INFO" (Section 6.2.11) command).
1463
1464 Possible Answers:
1465
1466 LinuxSampler will answer by sending a <CRLF> separated list. Each
1467 answer line begins with the information category name followed by
1468 a colon and then a space character <SP> and finally the info
1469 character string to that info category. There are information
1470 which is always returned, independently of the given channel
1471 parameter and there is optional information which is only shown
1472 dependently to the given audio channel. At the moment the
1473 following information categories are defined:
1474
1475
1476
1477 TYPE -
1478
1479 either "BOOL" for boolean value(s) or "INT" for integer
1480 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1481 character string(s) (always returned)
1482
1483 DESCRIPTION -
1484
1485 arbitrary text describing the purpose of the parameter
1486 (always returned)
1487
1488 FIX -
1489
1490 either true or false, if true then this parameter is read
1491 only, thus cannot be altered (always returned)
1492
1493 MULTIPLICITY -
1494
1495 either true or false, defines if this parameter allows only
1496 one value or a list of values, where true means multiple
1497 values and false only a single value allowed (always
1498 returned)
1499
1500 RANGE_MIN -
1501
1502 defines lower limit of the allowed value range for this
1503 parameter, can be an integer value as well as a dotted
1504 number, usually used in conjunction with 'RANGE_MAX', but
1505 may also appear without (optionally returned, dependent to
1506 driver and channel parameter)
1507
1508
1509
1510
1511 Schoenebeck Expires June 23, 2007 [Page 27]
1512
1513 Internet-Draft LinuxSampler Control Protocol December 2006
1514
1515
1516 RANGE_MAX -
1517
1518 defines upper limit of the allowed value range for this
1519 parameter, can be an integer value as well as a dotted
1520 number, usually used in conjunction with 'RANGE_MIN', but
1521 may also appear without (optionally returned, dependent to
1522 driver and channel parameter)
1523
1524 POSSIBILITIES -
1525
1526 comma separated list of possible values for this parameter,
1527 character strings are encapsulated into apostrophes
1528 (optionally returned, dependent to driver and channel
1529 parameter)
1530
1531 The mentioned fields above don't have to be in particular order.
1532
1533 Example:
1534
1535 C: "GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO 1 0 JACK_BINDINGS"
1536
1537 S: "DESCRIPTION: bindings to other JACK clients"
1538
1539 "TYPE: STRING"
1540
1541 "FIX: false"
1542
1543 "MULTIPLICITY: true"
1544
1545 "POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"
1546
1547 "."
1548
1549 6.2.13. Changing settings of audio output channels
1550
1551 Use the following command to alter a specific setting of an audio
1552 output channel:
1553
1554 SET AUDIO_OUTPUT_CHANNEL_PARAMETER <dev-id> <chn> <key>=<value>
1555
1556 Where <dev-id> should be replaced by the numerical ID of the audio
1557 output device as returned by the "CREATE AUDIO_OUTPUT_DEVICE"
1558 (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
1559 command, <chn> by the audio channel number, <key> by the name of the
1560 parameter to change and <value> by the new value for this parameter.
1561
1562 Possible Answers:
1563
1564
1565
1566
1567 Schoenebeck Expires June 23, 2007 [Page 28]
1568
1569 Internet-Draft LinuxSampler Control Protocol December 2006
1570
1571
1572 "OK" -
1573
1574 in case setting was successfully changed
1575
1576 "WRN:<warning-code>:<warning-message>" -
1577
1578 in case setting was changed successfully, but there are
1579 noteworthy issue(s) related, providing an appropriate warning
1580 code and warning message
1581
1582 "ERR:<error-code>:<error-message>" -
1583
1584 in case it failed, providing an appropriate error code and
1585 error message
1586
1587 Example:
1588
1589 C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"
1590
1591 S: "OK"
1592
1593 C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"
1594
1595 S: "OK"
1596
1597 6.3. Configuring MIDI input drivers
1598
1599 Instances of drivers in LinuxSampler are called devices. You can use
1600 multiple MIDI devices simultaneously, e.g. to use MIDI over ethernet
1601 as MIDI input on one sampler channel and ALSA as MIDI input on
1602 another sampler channel. For particular MIDI input systems it's also
1603 possible to create several devices of the same MIDI input type. This
1604 chapter describes all commands to configure LinuxSampler's MIDI input
1605 devices and their parameters.
1606
1607 Instead of defining commands and parameters for each driver
1608 individually, all possible parameters, their meanings and possible
1609 values have to be obtained at runtime. This makes the protocol a bit
1610 abstract, but has the advantage, that front-ends can be written
1611 independently of what drivers are currently implemented and what
1612 parameters these drivers are actually offering. This means front-
1613 ends can even handle drivers which are implemented somewhere in
1614 future without modifying the front-end at all.
1615
1616 Commands for configuring MIDI input devices are pretty much the same
1617 as the commands for configuring audio output drivers, already
1618 described in the last chapter.
1619
1620
1621
1622
1623 Schoenebeck Expires June 23, 2007 [Page 29]
1624
1625 Internet-Draft LinuxSampler Control Protocol December 2006
1626
1627
1628 Note: examples in this chapter showing particular parameters of
1629 drivers are not meant as specification of the drivers' parameters.
1630 Driver implementations in LinuxSampler might have complete different
1631 parameter names and meanings than shown in these examples or might
1632 change in future, so these examples are only meant for showing how to
1633 retrieve what parameters drivers are offering, how to retrieve their
1634 possible values, etc.
1635
1636 6.3.1. Getting amount of available MIDI input drivers
1637
1638 Use the following command to get the number of MIDI input drivers
1639 currently available for the LinuxSampler instance:
1640
1641 GET AVAILABLE_MIDI_INPUT_DRIVERS
1642
1643 Possible Answers:
1644
1645 LinuxSampler will answer by sending the number of available MIDI
1646 input drivers.
1647
1648 Example:
1649
1650 C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"
1651
1652 S: "2"
1653
1654 6.3.2. Getting all available MIDI input drivers
1655
1656 Use the following command to list all MIDI input drivers currently
1657 available for the LinuxSampler instance:
1658
1659 LIST AVAILABLE_MIDI_INPUT_DRIVERS
1660
1661 Possible Answers:
1662
1663 LinuxSampler will answer by sending comma separated character
1664 strings, each symbolizing a MIDI input driver.
1665
1666 Example:
1667
1668 C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
1669
1670 S: "ALSA,JACK"
1671
1672
1673
1674
1675
1676
1677
1678
1679 Schoenebeck Expires June 23, 2007 [Page 30]
1680
1681 Internet-Draft LinuxSampler Control Protocol December 2006
1682
1683
1684 6.3.3. Getting information about a specific MIDI input driver
1685
1686 Use the following command to get detailed information about a
1687 specific MIDI input driver:
1688
1689 GET MIDI_INPUT_DRIVER INFO <midi-input-driver>
1690
1691 Where <midi-input-driver> is the name of the MIDI input driver as
1692 returned by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2)
1693 command.
1694
1695 Possible Answers:
1696
1697 LinuxSampler will answer by sending a <CRLF> separated list. Each
1698 answer line begins with the information category name followed by
1699 a colon and then a space character <SP> and finally the info
1700 character string to that info category. At the moment the
1701 following information categories are defined:
1702
1703
1704
1705 DESCRIPTION -
1706
1707 arbitrary description text about the MIDI input driver
1708
1709 VERSION -
1710
1711 arbitrary character string regarding the driver's version
1712
1713 PARAMETERS -
1714
1715 comma separated list of all parameters available for the
1716 given MIDI input driver
1717
1718 The mentioned fields above don't have to be in particular order.
1719
1720 Example:
1721
1722 C: "GET MIDI_INPUT_DRIVER INFO ALSA"
1723
1724 S: "DESCRIPTION: Advanced Linux Sound Architecture"
1725
1726 "VERSION: 1.0"
1727
1728 "PARAMETERS: DRIVER,ACTIVE"
1729
1730 "."
1731
1732
1733
1734
1735 Schoenebeck Expires June 23, 2007 [Page 31]
1736
1737 Internet-Draft LinuxSampler Control Protocol December 2006
1738
1739
1740 6.3.4. Getting information about specific MIDI input driver parameter
1741
1742 Use the following command to get detailed information about a
1743 specific parameter of a specific MIDI input driver:
1744
1745 GET MIDI_INPUT_DRIVER_PARAMETER INFO <midit> <param> [<deplist>]
1746
1747 Where <midit> is the name of the MIDI input driver as returned by the
1748 "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2) command, <param>
1749 a specific parameter name for which information should be obtained
1750 (as returned by the "GET MIDI_INPUT_DRIVER INFO" (Section 6.3.3)
1751 command) and <deplist> is an optional list of parameters on which the
1752 sought parameter <param> depends on, <deplist> is a key-value pair
1753 list in form of "key1=val1 key2=val2 ...", where character string
1754 values are encapsulated into apostrophes ('). Arguments given with
1755 <deplist> which are not dependency parameters of <param> will be
1756 ignored, means the front-end application can simply put all
1757 parameters in <deplist> with the values selected by the user.
1758
1759 Possible Answers:
1760
1761 LinuxSampler will answer by sending a <CRLF> separated list. Each
1762 answer line begins with the information category name followed by a
1763 colon and then a space character <SP> and finally the info character
1764 string to that info category. There is information which is always
1765 returned, independent of the given driver parameter and there is
1766 optional information which is only shown dependent to given driver
1767 parameter. At the moment the following information categories are
1768 defined:
1769
1770 TYPE -
1771
1772 either "BOOL" for boolean value(s) or "INT" for integer
1773 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1774 character string(s) (always returned, no matter which driver
1775 parameter)
1776
1777 DESCRIPTION -
1778
1779 arbitrary text describing the purpose of the parameter (always
1780 returned, no matter which driver parameter)
1781
1782 MANDATORY -
1783
1784 either true or false, defines if this parameter must be given
1785 when the device is to be created with the 'CREATE
1786 MIDI_INPUT_DEVICE' (Section 6.3.5) command (always returned, no
1787 matter which driver parameter)
1788
1789
1790
1791 Schoenebeck Expires June 23, 2007 [Page 32]
1792
1793 Internet-Draft LinuxSampler Control Protocol December 2006
1794
1795
1796 FIX -
1797
1798 either true or false, if false then this parameter can be
1799 changed at any time, once the device is created by the 'CREATE
1800 MIDI_INPUT_DEVICE' (Section 6.3.5) command (always returned, no
1801 matter which driver parameter)
1802
1803 MULTIPLICITY -
1804
1805 either true or false, defines if this parameter allows only one
1806 value or a list of values, where true means multiple values and
1807 false only a single value allowed (always returned, no matter
1808 which driver parameter)
1809
1810 DEPENDS -
1811
1812 comma separated list of parameters this parameter depends on,
1813 means the values for fields 'DEFAULT', 'RANGE_MIN', 'RANGE_MAX'
1814 and 'POSSIBILITIES' might depend on these listed parameters,
1815 for example assuming that an audio driver (like the ALSA
1816 driver) offers parameters 'card' and 'samplerate' then
1817 parameter 'samplerate' would depend on 'card' because the
1818 possible values for 'samplerate' depends on the sound card
1819 which can be chosen by the 'card' parameter (optionally
1820 returned, dependent to driver parameter)
1821
1822 DEFAULT -
1823
1824 reflects the default value for this parameter which is used
1825 when the device is created and not explicitly given with the
1826 'CREATE MIDI_INPUT_DEVICE' (Section 6.3.5) command, in case of
1827 MULTIPLCITY=true, this is a comma separated list, that's why
1828 character strings are encapsulated into apostrophes (')
1829 (optionally returned, dependent to driver parameter)
1830
1831 RANGE_MIN -
1832
1833 defines lower limit of the allowed value range for this
1834 parameter, can be an integer value as well as a dotted number,
1835 this parameter is often used in conjunction with RANGE_MAX, but
1836 may also appear without (optionally returned, dependent to
1837 driver parameter)
1838
1839 RANGE_MAX -
1840
1841 defines upper limit of the allowed value range for this
1842 parameter, can be an integer value as well as a dotted number,
1843 this parameter is often used in conjunction with RANGE_MIN, but
1844
1845
1846
1847 Schoenebeck Expires June 23, 2007 [Page 33]
1848
1849 Internet-Draft LinuxSampler Control Protocol December 2006
1850
1851
1852 may also appear without (optionally returned, dependent to
1853 driver parameter)
1854
1855 POSSIBILITIES -
1856
1857 comma separated list of possible values for this parameter,
1858 character strings are encapsulated into apostrophes (optionally
1859 returned, dependent to driver parameter)
1860
1861 The mentioned fields above don't have to be in particular order.
1862
1863 Example:
1864
1865 C: "GET MIDI_INPUT_DRIVER_PARAMETER INFO ALSA ACTIVE"
1866
1867 S: "DESCRIPTION: Whether device is enabled"
1868
1869 "TYPE: BOOL"
1870
1871 "MANDATORY: false"
1872
1873 "FIX: false"
1874
1875 "MULTIPLICITY: false"
1876
1877 "DEFAULT: true"
1878
1879 "."
1880
1881 6.3.5. Creating a MIDI input device
1882
1883 Use the following command to create a new MIDI input device for the
1884 desired MIDI input system:
1885
1886 CREATE MIDI_INPUT_DEVICE <midi-input-driver> [<param-list>]
1887
1888 Where <midi-input-driver> should be replaced by the desired MIDI
1889 input system as returned by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
1890 (Section 6.3.2) command and <param-list> by an optional list of
1891 driver specific parameters in form of "key1=val1 key2=val2 ...",
1892 where character string values should be encapsulated into apostrophes
1893 ('). Note that there might be drivers which require parameter(s) to
1894 be given with this command. Use the previously described commands in
1895 this chapter to get that information.
1896
1897 Possible Answers:
1898
1899
1900
1901
1902
1903 Schoenebeck Expires June 23, 2007 [Page 34]
1904
1905 Internet-Draft LinuxSampler Control Protocol December 2006
1906
1907
1908 "OK[<device-id>]" -
1909
1910 in case the device was successfully created, where <device-id>
1911 is the numerical ID of the new device
1912
1913 "WRN[<device-id>]:<warning-code>:<warning-message>" -
1914
1915 in case the driver was loaded successfully, where <device-id>
1916 is the numerical ID of the new device, but there are noteworthy
1917 issue(s) related, providing an appropriate warning code and
1918 warning message
1919
1920 "ERR:<error-code>:<error-message>" -
1921
1922 in case it failed, providing an appropriate error code and
1923 error message
1924
1925 Example:
1926
1927 C: "CREATE MIDI_INPUT_DEVICE ALSA"
1928
1929 S: "OK[0]"
1930
1931 6.3.6. Destroying a MIDI input device
1932
1933 Use the following command to destroy a created MIDI input device:
1934
1935 DESTROY MIDI_INPUT_DEVICE <device-id>
1936
1937 Where <device-id> should be replaced by the device's numerical ID as
1938 returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
1939 MIDI_INPUT_DEVICES" (Section 6.3.8) command.
1940
1941 Possible Answers:
1942
1943 "OK" -
1944
1945 in case the device was successfully destroyed
1946
1947 "WRN:<warning-code>:<warning-message>" -
1948
1949 in case the device was destroyed, but there are noteworthy
1950 issue(s) related, providing an appropriate warning code and
1951 warning message
1952
1953 "ERR:<error-code>:<error-message>" -
1954
1955
1956
1957
1958
1959 Schoenebeck Expires June 23, 2007 [Page 35]
1960
1961 Internet-Draft LinuxSampler Control Protocol December 2006
1962
1963
1964 in case it failed, providing an appropriate error code and
1965 error message
1966
1967 Example:
1968
1969 C: "DESTROY MIDI_INPUT_DEVICE 0"
1970
1971 S: "OK"
1972
1973 6.3.7. Getting all created MIDI input device count
1974
1975 Use the following command to count all created MIDI input devices:
1976
1977 GET MIDI_INPUT_DEVICES
1978
1979 Possible Answers:
1980
1981 LinuxSampler will answer by sending the current number of all MIDI
1982 input devices.
1983
1984 Example:
1985
1986 C: "GET MIDI_INPUT_DEVICES"
1987
1988 S: "3"
1989
1990 6.3.8. Getting all created MIDI input device list
1991
1992 Use the following command to list all created MIDI input devices:
1993
1994 LIST MIDI_INPUT_DEVICES
1995
1996 Possible Answers:
1997
1998 LinuxSampler will answer by sending a comma separated list with
1999 the numerical Ids of all created MIDI input devices.
2000
2001 Examples:
2002
2003 C: "LIST MIDI_INPUT_DEVICES"
2004
2005 S: "0,1,2"
2006
2007 C: "LIST MIDI_INPUT_DEVICES"
2008
2009 S: "1,3"
2010
2011
2012
2013
2014
2015 Schoenebeck Expires June 23, 2007 [Page 36]
2016
2017 Internet-Draft LinuxSampler Control Protocol December 2006
2018
2019
2020 6.3.9. Getting current settings of a MIDI input device
2021
2022 Use the following command to get current settings of a specific,
2023 created MIDI input device:
2024
2025 GET MIDI_INPUT_DEVICE INFO <device-id>
2026
2027 Where <device-id> is the numerical ID of the MIDI input device as
2028 returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
2029 MIDI_INPUT_DEVICES" (Section 6.3.8) command.
2030
2031 Possible Answers:
2032
2033 LinuxSampler will answer by sending a <CRLF> separated list. Each
2034 answer line begins with the information category name followed by
2035 a colon and then a space character <SP> and finally the info
2036 character string to that info category. As some parameters might
2037 allow multiple values, character strings are encapsulated into
2038 apostrophes ('). At the moment the following information
2039 categories are defined (independent of driver):
2040
2041
2042
2043 DRIVER -
2044
2045 identifier of the used MIDI input driver, as e.g. returned
2046 by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2)
2047 command
2048
2049 ACTIVE -
2050
2051 either true or false, if false then the MIDI device is
2052 inactive and doesn't listen to any incoming MIDI events and
2053 thus doesn't forward them to connected sampler channels
2054
2055 The mentioned fields above don't have to be in particular order. The
2056 fields above are only those fields which are returned by all MIDI
2057 input devices. Every MIDI input driver might have its own,
2058 additional driver specific parameters (see "GET MIDI_INPUT_DRIVER
2059 INFO" (Section 6.3.3) command) which are also returned by this
2060 command.
2061
2062 Example:
2063
2064 C: "GET MIDI_INPUT_DEVICE INFO 0"
2065
2066 S: "DRIVER: ALSA"
2067
2068
2069
2070
2071 Schoenebeck Expires June 23, 2007 [Page 37]
2072
2073 Internet-Draft LinuxSampler Control Protocol December 2006
2074
2075
2076 "ACTIVE: true"
2077
2078 "."
2079
2080 6.3.10. Changing settings of MIDI input devices
2081
2082 Use the following command to alter a specific setting of a created
2083 MIDI input device:
2084
2085 SET MIDI_INPUT_DEVICE_PARAMETER <device-id> <key>=<value>
2086
2087 Where <device-id> should be replaced by the numerical ID of the MIDI
2088 input device as returned by the "CREATE MIDI_INPUT_DEVICE"
2089 (Section 6.3.5) or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command,
2090 <key> by the name of the parameter to change and <value> by the new
2091 value for this parameter.
2092
2093 Possible Answers:
2094
2095 "OK" -
2096
2097 in case setting was successfully changed
2098
2099 "WRN:<warning-code>:<warning-message>" -
2100
2101 in case setting was changed successfully, but there are
2102 noteworthy issue(s) related, providing an appropriate warning
2103 code and warning message
2104
2105 "ERR:<error-code>:<error-message>" -
2106
2107 in case it failed, providing an appropriate error code and
2108 error message
2109
2110 Example:
2111
2112 C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"
2113
2114 S: "OK"
2115
2116 6.3.11. Getting information about a MIDI port
2117
2118 Use the following command to get information about a MIDI port:
2119
2120 GET MIDI_INPUT_PORT INFO <device-id> <midi-port>
2121
2122 Where <device-id> is the numerical ID of the MIDI input device as
2123 returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
2124
2125
2126
2127 Schoenebeck Expires June 23, 2007 [Page 38]
2128
2129 Internet-Draft LinuxSampler Control Protocol December 2006
2130
2131
2132 MIDI_INPUT_DEVICES" (Section 6.3.8) command and <midi-port> the MIDI
2133 input port number.
2134
2135 Possible Answers:
2136
2137 LinuxSampler will answer by sending a <CRLF> separated list. Each
2138 answer line begins with the information category name followed by
2139 a colon and then a space character <SP> and finally the info
2140 character string to that info category. At the moment the
2141 following information categories are defined:
2142
2143 NAME -
2144
2145 arbitrary character string naming the port
2146
2147 The field above is only the one which is returned by all MIDI ports
2148 regardless of the MIDI driver and port. Every MIDI port might have
2149 its own, additional driver and port specific parameters.
2150
2151 Example:
2152
2153 C: "GET MIDI_INPUT_PORT INFO 0 0"
2154
2155 S: "NAME: 'Masterkeyboard'"
2156
2157 "ALSA_SEQ_BINDINGS: '64:0'"
2158
2159 "."
2160
2161 6.3.12. Getting information about specific MIDI port parameter
2162
2163 Use the following command to get detailed information about specific
2164 MIDI port parameter:
2165
2166 GET MIDI_INPUT_PORT_PARAMETER INFO <dev-id> <port> <param>
2167
2168 Where <dev-id> is the numerical ID of the MIDI input device as
2169 returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
2170 MIDI_INPUT_DEVICES" (Section 6.3.8) command, <port> the MIDI port
2171 number and <param> a specific port parameter name for which
2172 information should be obtained (as returned by the "GET
2173 MIDI_INPUT_PORT INFO" (Section 6.3.11) command).
2174
2175 Possible Answers:
2176
2177 LinuxSampler will answer by sending a <CRLF> separated list. Each
2178 answer line begins with the information category name followed by
2179 a colon and then a space character <SP> and finally the info
2180
2181
2182
2183 Schoenebeck Expires June 23, 2007 [Page 39]
2184
2185 Internet-Draft LinuxSampler Control Protocol December 2006
2186
2187
2188 character string to that info category. There is information
2189 which is always returned, independently of the given channel
2190 parameter and there is optional information which are only shown
2191 dependently to the given MIDI port. At the moment the following
2192 information categories are defined:
2193
2194 TYPE -
2195
2196 either "BOOL" for boolean value(s) or "INT" for integer
2197 value(s) or "FLOAT" for dotted number(s) or "STRING" for
2198 character string(s) (always returned)
2199
2200 DESCRIPTION -
2201
2202 arbitrary text describing the purpose of the parameter (always
2203 returned)
2204
2205 FIX -
2206
2207 either true or false, if true then this parameter is read only,
2208 thus cannot be altered (always returned)
2209
2210 MULTIPLICITY -
2211
2212 either true or false, defines if this parameter allows only one
2213 value or a list of values, where true means multiple values and
2214 false only a single value allowed (always returned)
2215
2216 RANGE_MIN -
2217
2218 defines lower limit of the allowed value range for this
2219 parameter, can be an integer value as well as a dotted number,
2220 this parameter is usually used in conjunction with 'RANGE_MAX'
2221 but may also appear without (optionally returned, dependent to
2222 driver and port parameter)
2223
2224 RANGE_MAX -
2225
2226 defines upper limit of the allowed value range for this
2227 parameter, can be an integer value as well as a dotted number,
2228 this parameter is usually used in conjunction with 'RANGE_MIN'
2229 but may also appear without (optionally returned, dependent to
2230 driver and port parameter)
2231
2232 POSSIBILITIES -
2233
2234 comma separated list of possible values for this parameter,
2235 character strings are encapsulated into apostrophes (optionally
2236
2237
2238
2239 Schoenebeck Expires June 23, 2007 [Page 40]
2240
2241 Internet-Draft LinuxSampler Control Protocol December 2006
2242
2243
2244 returned, dependent to device and port parameter)
2245
2246 The mentioned fields above don't have to be in particular order.
2247
2248 Example:
2249
2250 C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"
2251
2252 S: "DESCRIPTION: bindings to other ALSA sequencer clients"
2253
2254 "TYPE: STRING"
2255
2256 "FIX: false"
2257
2258 "MULTIPLICITY: true"
2259
2260 "POSSIBILITIES: '64:0','68:0','68:1'"
2261
2262 "."
2263
2264 6.3.13. Changing settings of MIDI input ports
2265
2266 Use the following command to alter a specific setting of a MIDI input
2267 port:
2268
2269 SET MIDI_INPUT_PORT_PARAMETER <device-id> <port> <key>=<value>
2270
2271 Where <device-id> should be replaced by the numerical ID of the MIDI
2272 device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5)
2273 or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command, <port> by the
2274 MIDI port number, <key> by the name of the parameter to change and
2275 <value> by the new value for this parameter.
2276
2277 Possible Answers:
2278
2279 "OK" -
2280
2281 in case setting was successfully changed
2282
2283 "WRN:<warning-code>:<warning-message>" -
2284
2285 in case setting was changed successfully, but there are
2286 noteworthy issue(s) related, providing an appropriate warning
2287 code and warning message
2288
2289 "ERR:<error-code>:<error-message>" -
2290
2291
2292
2293
2294
2295 Schoenebeck Expires June 23, 2007 [Page 41]
2296
2297 Internet-Draft LinuxSampler Control Protocol December 2006
2298
2299
2300 in case it failed, providing an appropriate error code and
2301 error message
2302
2303 Example:
2304
2305
2306
2307 6.4. Configuring sampler channels
2308
2309 The following commands describe how to add and remove sampler
2310 channels, associate a sampler channel with a sampler engine, load
2311 instruments and connect sampler channels to MIDI and audio devices.
2312
2313 6.4.1. Loading an instrument
2314
2315 An instrument file can be loaded and assigned to a sampler channel by
2316 one of the following commands:
2317
2318 LOAD INSTRUMENT [NON_MODAL] '<filename>' <instr-index> <sampler-
2319 channel>
2320
2321 Where <filename> is the name of the instrument file on the
2322 LinuxSampler instance's host system, <instr-index> the index of the
2323 instrument in the instrument file and <sampler-channel> is the number
2324 of the sampler channel the instrument should be assigned to. Each
2325 sampler channel can only have one instrument.
2326
2327 The difference between regular and NON_MODAL versions of the command
2328 is that the regular command returns OK only after the instrument has
2329 been fully loaded and the channel is ready to be used while NON_MODAL
2330 version returns immediately and a background process is launched to
2331 load the instrument on the channel. The GET CHANNEL INFO
2332 (Section 6.4.10) command can be used to obtain loading progress from
2333 INSTRUMENT_STATUS field. LOAD command will perform sanity checks
2334 such as making sure that the file could be read and it is of a proper
2335 format and SHOULD return ERR and SHOULD not launch the background
2336 process should any errors be detected at that point.
2337
2338 Possible Answers:
2339
2340 "OK" -
2341
2342 in case the instrument was successfully loaded
2343
2344 "WRN:<warning-code>:<warning-message>" -
2345
2346 in case the instrument was loaded successfully, but there are
2347 noteworthy issue(s) related (e.g. Engine doesn't support one
2348
2349
2350
2351 Schoenebeck Expires June 23, 2007 [Page 42]
2352
2353 Internet-Draft LinuxSampler Control Protocol December 2006
2354
2355
2356 or more patch parameters provided by the loaded instrument
2357 file), providing an appropriate warning code and warning
2358 message
2359
2360 "ERR:<error-code>:<error-message>" -
2361
2362 in case it failed, providing an appropriate error code and
2363 error message
2364
2365 Example:
2366
2367
2368
2369 6.4.2. Loading a sampler engine
2370
2371 A sampler engine type can be associated to a specific sampler channel
2372 by the following command:
2373
2374 LOAD ENGINE <engine-name> <sampler-channel>
2375
2376 Where <engine-name> is an engine name as obtained by the "LIST
2377 AVAILABLE_ENGINES" (Section 6.4.8) command and <sampler-channel> the
2378 sampler channel as returned by the "ADD CHANNEL" (Section 6.4.5) or
2379 "LIST CHANNELS" (Section 6.4.4) command where the engine type should
2380 be assigned to. This command should be issued after adding a new
2381 sampler channel and before any other control commands on the new
2382 sampler channel. It can also be used to change the engine type of a
2383 sampler channel. This command has (currently) no way to define or
2384 force if a new engine instance should be created and assigned to the
2385 given sampler channel or if an already existing instance of that
2386 engine type, shared with other sampler channels, should be used.
2387
2388 Possible Answers:
2389
2390 "OK" -
2391
2392 in case the engine was successfully deployed
2393
2394 "WRN:<warning-code>:<warning-message>" -
2395
2396 in case the engine was deployed successfully, but there are
2397 noteworthy issue(s) related, providing an appropriate warning
2398 code and warning message
2399
2400 "ERR:<error-code>:<error-message>" -
2401
2402 in case it failed, providing an appropriate error code and
2403 error message
2404
2405
2406
2407 Schoenebeck Expires June 23, 2007 [Page 43]
2408
2409 Internet-Draft LinuxSampler Control Protocol December 2006
2410
2411
2412 Example:
2413
2414
2415
2416 6.4.3. Getting all created sampler channel count
2417
2418 The number of sampler channels can change on runtime. To get the
2419 current amount of sampler channels, the front-end can send the
2420 following command:
2421
2422 GET CHANNELS
2423
2424 Possible Answers:
2425
2426 LinuxSampler will answer by returning the current number of
2427 sampler channels.
2428
2429 Example:
2430
2431 C: "GET CHANNELS"
2432
2433 S: "12"
2434
2435 6.4.4. Getting all created sampler channel list
2436
2437 The number of sampler channels can change on runtime. To get the
2438 current list of sampler channels, the front-end can send the
2439 following command:
2440
2441 LIST CHANNELS
2442
2443 Possible Answers:
2444
2445 LinuxSampler will answer by returning a comma separated list with
2446 all sampler channels numerical IDs.
2447
2448 Example:
2449
2450 C: "LIST CHANNELS"
2451
2452 S: "0,1,2,3,4,5,6,9,10,11,15,20"
2453
2454 6.4.5. Adding a new sampler channel
2455
2456 A new sampler channel can be added to the end of the sampler channel
2457 list by sending the following command:
2458
2459
2460
2461
2462
2463 Schoenebeck Expires June 23, 2007 [Page 44]
2464
2465 Internet-Draft LinuxSampler Control Protocol December 2006
2466
2467
2468 ADD CHANNEL
2469
2470 This will increment the sampler channel count by one and the new
2471 sampler channel will be appended to the end of the sampler channel
2472 list. The front-end should send the respective, related commands
2473 right after to e.g. load an engine, load an instrument and setting
2474 input, output method and eventually other commands to initialize the
2475 new channel. The front-end should use the sampler channel returned
2476 by the answer of this command to perform the previously recommended
2477 commands, to avoid race conditions e.g. with other front-ends that
2478 might also have sent an "ADD CHANNEL" command.
2479
2480 Possible Answers:
2481
2482 "OK[<sampler-channel>]" -
2483
2484 in case a new sampler channel could be added, where <sampler-
2485 channel> reflects the channel number of the new created sampler
2486 channel which should be used to set up the sampler channel by
2487 sending subsequent initialization commands
2488
2489 "WRN:<warning-code>:<warning-message>" -
2490
2491 in case a new channel was added successfully, but there are
2492 noteworthy issue(s) related, providing an appropriate warning
2493 code and warning message
2494
2495 "ERR:<error-code>:<error-message>" -
2496
2497 in case it failed, providing an appropriate error code and
2498 error message
2499
2500 Example:
2501
2502
2503
2504 6.4.6. Removing a sampler channel
2505
2506 A sampler channel can be removed by sending the following command:
2507
2508 REMOVE CHANNEL <sampler-channel>
2509
2510 Where <sampler-channel> should be replaced by the number of the
2511 sampler channel as given by the "ADD CHANNEL" (Section 6.4.5) or
2512 "LIST CHANNELS" (Section 6.4.4) command. The channel numbers of all
2513 subsequent sampler channels remain the same.
2514
2515 Possible Answers:
2516
2517
2518
2519 Schoenebeck Expires June 23, 2007 [Page 45]
2520
2521 Internet-Draft LinuxSampler Control Protocol December 2006
2522
2523
2524 "OK" -
2525
2526 in case the given sampler channel could be removed
2527
2528 "WRN:<warning-code>:<warning-message>" -
2529
2530 in case the given channel was removed, but there are noteworthy
2531 issue(s) related, providing an appropriate warning code and
2532 warning message
2533
2534 "ERR:<error-code>:<error-message>" -
2535
2536 in case it failed, providing an appropriate error code and
2537 error message
2538
2539 Example:
2540
2541
2542
2543 6.4.7. Getting amount of available engines
2544
2545 The front-end can ask for the number of available engines by sending
2546 the following command:
2547
2548 GET AVAILABLE_ENGINES
2549
2550 Possible Answers:
2551
2552 LinuxSampler will answer by sending the number of available
2553 engines.
2554
2555 Example:
2556
2557 C: "GET AVAILABLE_ENGINES"
2558
2559 S: "4"
2560
2561 6.4.8. Getting all available engines
2562
2563 The front-end can ask for a list of all available engines by sending
2564 the following command:
2565
2566 LIST AVAILABLE_ENGINES
2567
2568 Possible Answers:
2569
2570
2571
2572
2573
2574
2575 Schoenebeck Expires June 23, 2007 [Page 46]
2576
2577 Internet-Draft LinuxSampler Control Protocol December 2006
2578
2579
2580 LinuxSampler will answer by sending a comma separated list of the
2581 engines' names encapsulated into apostrophes ('). Engine names
2582 can consist of lower and upper cases, digits and underlines ("_"
2583 character).
2584
2585 Example:
2586
2587 C: "LIST AVAILABLE_ENGINES"
2588
2589 S: "'GigEngine','AkaiEngine','DLSEngine','JoesCustomEngine'"
2590
2591 6.4.9. Getting information about an engine
2592
2593 The front-end can ask for information about a specific engine by
2594 sending the following command:
2595
2596 GET ENGINE INFO <engine-name>
2597
2598 Where <engine-name> is an engine name as obtained by the "LIST
2599 AVAILABLE_ENGINES" (Section 6.4.8) command.
2600
2601 Possible Answers:
2602
2603 LinuxSampler will answer by sending a <CRLF> separated list. Each
2604 answer line begins with the information category name followed by
2605 a colon and then a space character <SP> and finally the info
2606 character string to that info category. At the moment the
2607 following categories are defined:
2608
2609
2610
2611 DESCRIPTION -
2612
2613 arbitrary description text about the engine
2614
2615 VERSION -
2616
2617 arbitrary character string regarding the engine's version
2618
2619 The mentioned fields above don't have to be in particular order.
2620
2621 Example:
2622
2623 C: "GET ENGINE INFO JoesCustomEngine"
2624
2625 S: "DESCRIPTION: this is Joe's custom sampler engine"
2626
2627
2628
2629
2630
2631 Schoenebeck Expires June 23, 2007 [Page 47]
2632
2633 Internet-Draft LinuxSampler Control Protocol December 2006
2634
2635
2636 "VERSION: testing-1.0"
2637
2638 "."
2639
2640 6.4.10. Getting sampler channel information
2641
2642 The front-end can ask for the current settings of a sampler channel
2643 by sending the following command:
2644
2645 GET CHANNEL INFO <sampler-channel>
2646
2647 Where <sampler-channel> is the sampler channel number the front-end
2648 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2649 "LIST CHANNELS" (Section 6.4.4) command.
2650
2651 Possible Answers:
2652
2653 LinuxSampler will answer by sending a <CRLF> separated list. Each
2654 answer line begins with the settings category name followed by a
2655 colon and then a space character <SP> and finally the info
2656 character string to that setting category. At the moment the
2657 following categories are defined:
2658
2659
2660
2661 ENGINE_NAME -
2662
2663 name of the engine that is associated with the sampler
2664 channel, "NONE" if there's no engine associated yet for this
2665 sampler channel
2666
2667 AUDIO_OUTPUT_DEVICE -
2668
2669 numerical ID of the audio output device which is currently
2670 connected to this sampler channel to output the audio
2671 signal, "NONE" if there's no device connected to this
2672 sampler channel
2673
2674 AUDIO_OUTPUT_CHANNELS -
2675
2676 number of output channels the sampler channel offers
2677 (dependent to used sampler engine and loaded instrument)
2678
2679 AUDIO_OUTPUT_ROUTING -
2680
2681 comma separated list which reflects to which audio channel
2682 of the selected audio output device each sampler output
2683 channel is routed to, e.g. "0,3" would mean the engine's
2684
2685
2686
2687 Schoenebeck Expires June 23, 2007 [Page 48]
2688
2689 Internet-Draft LinuxSampler Control Protocol December 2006
2690
2691
2692 output channel 0 is routed to channel 0 of the audio output
2693 device and the engine's output channel 1 is routed to the
2694 channel 3 of the audio output device
2695
2696 INSTRUMENT_FILE -
2697
2698 the file name of the loaded instrument, "NONE" if there's no
2699 instrument yet loaded for this sampler channel
2700
2701 INSTRUMENT_NR -
2702
2703 the instrument index number of the loaded instrument
2704
2705 INSTRUMENT_NAME -
2706
2707 the instrument name of the loaded instrument
2708
2709 INSTRUMENT_STATUS -
2710
2711 integer values 0 to 100 indicating loading progress
2712 percentage for the instrument. Negative value indicates a
2713 loading exception. Value of 100 indicates that the
2714 instrument is fully loaded.
2715
2716 MIDI_INPUT_DEVICE -
2717
2718 numerical ID of the MIDI input device which is currently
2719 connected to this sampler channel to deliver MIDI input
2720 commands, "NONE" if there's no device connected to this
2721 sampler channel
2722
2723 MIDI_INPUT_PORT -
2724
2725 port number of the MIDI input device
2726
2727 MIDI_INPUT_CHANNEL -
2728
2729 the MIDI input channel number this sampler channel should
2730 listen to or "ALL" to listen on all MIDI channels
2731
2732 VOLUME -
2733
2734 optionally dotted number for the channel volume factor
2735 (where a value < 1.0 means attenuation and a value > 1.0
2736 means amplification)
2737
2738
2739
2740
2741
2742
2743 Schoenebeck Expires June 23, 2007 [Page 49]
2744
2745 Internet-Draft LinuxSampler Control Protocol December 2006
2746
2747
2748 MUTE -
2749
2750 Determines whether the channel is muted, "true" if the
2751 channel is muted, "false" if the channel is not muted, and
2752 "MUTED_BY_SOLO" if the channel is muted because of the
2753 presence of a solo channel and will be unmuted when there
2754 are no solo channels left
2755
2756 SOLO -
2757
2758 Determines whether this is a solo channel, "true" if the
2759 channel is a solo channel; "false" otherwise
2760
2761 MIDI_INSTRUMENT_MAP -
2762
2763 Determines to which MIDI instrument map this sampler channel
2764 is assigned to. Read chapter "SET CHANNEL
2765 MIDI_INSTRUMENT_MAP" (Section 6.4.24) for a list of possible
2766 values.
2767
2768 The mentioned fields above don't have to be in particular order.
2769
2770 Example:
2771
2772 C: "GET CHANNEL INFO 34"
2773
2774 S: "ENGINE_NAME: GigEngine"
2775
2776 "VOLUME: 1.0"
2777
2778 "AUDIO_OUTPUT_DEVICE: 0"
2779
2780 "AUDIO_OUTPUT_CHANNELS: 2"
2781
2782 "AUDIO_OUTPUT_ROUTING: 0,1"
2783
2784 "INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"
2785
2786 "INSTRUMENT_NR: 0"
2787
2788 "INSTRUMENT_NAME: Fazioli Piano"
2789
2790 "INSTRUMENT_STATUS: 100"
2791
2792 "MIDI_INPUT_DEVICE: 0"
2793
2794 "MIDI_INPUT_PORT: 0"
2795
2796
2797
2798
2799 Schoenebeck Expires June 23, 2007 [Page 50]
2800
2801 Internet-Draft LinuxSampler Control Protocol December 2006
2802
2803
2804 "MIDI_INPUT_CHANNEL: 5"
2805
2806 "VOLUME: 1.0"
2807
2808 "MUTE: false"
2809
2810 "SOLO: false"
2811
2812 "MIDI_INSTRUMENT_MAP: NONE"
2813
2814 "."
2815
2816 6.4.11. Current number of active voices
2817
2818 The front-end can ask for the current number of active voices on a
2819 sampler channel by sending the following command:
2820
2821 GET CHANNEL VOICE_COUNT <sampler-channel>
2822
2823 Where <sampler-channel> is the sampler channel number the front-end
2824 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2825 "LIST CHANNELS" (Section 6.4.4) command.
2826
2827 Possible Answers:
2828
2829 LinuxSampler will answer by returning the number of active voices
2830 on that channel.
2831
2832 Example:
2833
2834
2835
2836 6.4.12. Current number of active disk streams
2837
2838 The front-end can ask for the current number of active disk streams
2839 on a sampler channel by sending the following command:
2840
2841 GET CHANNEL STREAM_COUNT <sampler-channel>
2842
2843 Where <sampler-channel> is the sampler channel number the front-end
2844 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2845 "LIST CHANNELS" (Section 6.4.4) command.
2846
2847 Possible Answers:
2848
2849 LinuxSampler will answer by returning the number of active disk
2850 streams on that channel in case the engine supports disk
2851 streaming, if the engine doesn't support disk streaming it will
2852
2853
2854
2855 Schoenebeck Expires June 23, 2007 [Page 51]
2856
2857 Internet-Draft LinuxSampler Control Protocol December 2006
2858
2859
2860 return "NA" for not available.
2861
2862 Example:
2863
2864
2865
2866 6.4.13. Current fill state of disk stream buffers
2867
2868 The front-end can ask for the current fill state of all disk streams
2869 on a sampler channel by sending the following command:
2870
2871 GET CHANNEL BUFFER_FILL BYTES <sampler-channel>
2872
2873 to get the fill state in bytes or
2874
2875 GET CHANNEL BUFFER_FILL PERCENTAGE <sampler-channel>
2876
2877 to get the fill state in percent, where <sampler-channel> is the
2878 sampler channel number the front-end is interested in as returned by
2879 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
2880 command.
2881
2882 Possible Answers:
2883
2884 LinuxSampler will either answer by returning a comma separated
2885 string with the fill state of all disk stream buffers on that
2886 channel or an empty line if there are no active disk streams or
2887 "NA" for *not available* in case the engine which is deployed
2888 doesn't support disk streaming. Each entry in the answer list
2889 will begin with the stream's ID in brackets followed by the
2890 numerical representation of the fill size (either in bytes or
2891 percentage). Note: due to efficiency reasons the fill states in
2892 the response are not in particular order, thus the front-end has
2893 to sort them by itself if necessary.
2894
2895 Examples:
2896
2897 C: "GET CHANNEL BUFFER_FILL BYTES 4"
2898
2899 S: "[115]420500,[116]510300,[75]110000,[120]230700"
2900
2901 C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
2902
2903 S: "[115]90%,[116]98%,[75]40%,[120]62%"
2904
2905 C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
2906
2907
2908
2909
2910
2911 Schoenebeck Expires June 23, 2007 [Page 52]
2912
2913 Internet-Draft LinuxSampler Control Protocol December 2006
2914
2915
2916 S: ""
2917
2918 6.4.14. Setting audio output device
2919
2920 The front-end can set the audio output device on a specific sampler
2921 channel by sending the following command:
2922
2923 SET CHANNEL AUDIO_OUTPUT_DEVICE <sampler-channel>
2924 <audio-device-id>
2925
2926 Where <sampler-channel> is the respective sampler channel number as
2927 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
2928 (Section 6.4.4) command and <audio-device-id> is the numerical ID of
2929 the audio output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
2930 (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
2931 command.
2932
2933 Possible Answers:
2934
2935 "OK" -
2936
2937 on success
2938
2939 "WRN:<warning-code>:<warning-message>" -
2940
2941 if audio output device was set, but there are noteworthy
2942 issue(s) related, providing an appropriate warning code and
2943 warning message
2944
2945 "ERR:<error-code>:<error-message>" -
2946
2947 in case it failed, providing an appropriate error code and
2948 error message
2949
2950 Examples:
2951
2952
2953
2954 6.4.15. Setting audio output type
2955
2956 DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
2957
2958 The front-end can alter the audio output type on a specific sampler
2959 channel by sending the following command:
2960
2961 SET CHANNEL AUDIO_OUTPUT_TYPE <sampler-channel> <audio-output-
2962 type>
2963
2964
2965
2966
2967 Schoenebeck Expires June 23, 2007 [Page 53]
2968
2969 Internet-Draft LinuxSampler Control Protocol December 2006
2970
2971
2972 Where <audio-output-type> is currently either "ALSA" or "JACK" and
2973 <sampler-channel> is the respective sampler channel number.
2974
2975 Possible Answers:
2976
2977 "OK" -
2978
2979 on success
2980
2981 "WRN:<warning-code>:<warning-message>" -
2982
2983 if audio output type was set, but there are noteworthy issue(s)
2984 related, providing an appropriate warning code and warning
2985 message
2986
2987 "ERR:<error-code>:<error-message>" -
2988
2989 in case it failed, providing an appropriate error code and
2990 error message
2991
2992 Examples:
2993
2994
2995
2996 6.4.16. Setting audio output channel
2997
2998 The front-end can alter the audio output channel on a specific
2999 sampler channel by sending the following command:
3000
3001 SET CHANNEL AUDIO_OUTPUT_CHANNEL <sampler-chan> <audio-out>
3002 <audio-in>
3003
3004 Where <sampler-chan> is the sampler channel number as returned by the
3005 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3006 command, <audio-out> is the numerical ID of the sampler channel's
3007 audio output channel which should be rerouted and <audio-in> is the
3008 numerical ID of the audio channel of the selected audio output device
3009 where <audio-out> should be routed to.
3010
3011 Possible Answers:
3012
3013 "OK" -
3014
3015 on success
3016
3017 "WRN:<warning-code>:<warning-message>" -
3018
3019
3020
3021
3022
3023 Schoenebeck Expires June 23, 2007 [Page 54]
3024
3025 Internet-Draft LinuxSampler Control Protocol December 2006
3026
3027
3028 if audio output channel was set, but there are noteworthy
3029 issue(s) related, providing an appropriate warning code and
3030 warning message
3031
3032 "ERR:<error-code>:<error-message>" -
3033
3034 in case it failed, providing an appropriate error code and
3035 error message
3036
3037 Examples:
3038
3039
3040
3041 6.4.17. Setting MIDI input device
3042
3043 The front-end can set the MIDI input device on a specific sampler
3044 channel by sending the following command:
3045
3046 SET CHANNEL MIDI_INPUT_DEVICE <sampler-channel> <midi-device-id>
3047
3048 Where <sampler-channel> is the sampler channel number as returned by
3049 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3050 command and <midi-device-id> is the numerical ID of the MIDI input
3051 device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5)
3052 or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command.
3053
3054 Possible Answers:
3055
3056 "OK" -
3057
3058 on success
3059
3060 "WRN:<warning-code>:<warning-message>" -
3061
3062 if MIDI input device was set, but there are noteworthy issue(s)
3063 related, providing an appropriate warning code and warning
3064 message
3065
3066 "ERR:<error-code>:<error-message>" -
3067
3068 in case it failed, providing an appropriate error code and
3069 error message
3070
3071 Examples:
3072
3073
3074
3075
3076
3077
3078
3079 Schoenebeck Expires June 23, 2007 [Page 55]
3080
3081 Internet-Draft LinuxSampler Control Protocol December 2006
3082
3083
3084 6.4.18. Setting MIDI input type
3085
3086 DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
3087
3088 The front-end can alter the MIDI input type on a specific sampler
3089 channel by sending the following command:
3090
3091 SET CHANNEL MIDI_INPUT_TYPE <sampler-channel> <midi-input-type>
3092
3093 Where <midi-input-type> is currently only "ALSA" and <sampler-
3094 channel> is the respective sampler channel number.
3095
3096 Possible Answers:
3097
3098 "OK" -
3099
3100 on success
3101
3102 "WRN:<warning-code>:<warning-message>" -
3103
3104 if MIDI input type was set, but there are noteworthy issue(s)
3105 related, providing an appropriate warning code and warning
3106 message
3107
3108 "ERR:<error-code>:<error-message>" -
3109
3110 in case it failed, providing an appropriate error code and
3111 error message
3112
3113 Examples:
3114
3115
3116
3117 6.4.19. Setting MIDI input port
3118
3119 The front-end can alter the MIDI input port on a specific sampler
3120 channel by sending the following command:
3121
3122 SET CHANNEL MIDI_INPUT_PORT <sampler-channel> <midi-input-port>
3123
3124 Where <midi-input-port> is a MIDI input port number of the MIDI input
3125 device connected to the sampler channel given by <sampler-channel>.
3126
3127 Possible Answers:
3128
3129 "OK" -
3130
3131
3132
3133
3134
3135 Schoenebeck Expires June 23, 2007 [Page 56]
3136
3137 Internet-Draft LinuxSampler Control Protocol December 2006
3138
3139
3140 on success
3141
3142 "WRN:<warning-code>:<warning-message>" -
3143
3144 if MIDI input port was set, but there are noteworthy issue(s)
3145 related, providing an appropriate warning code and warning
3146 message
3147
3148 "ERR:<error-code>:<error-message>" -
3149
3150 in case it failed, providing an appropriate error code and
3151 error message
3152
3153 Examples:
3154
3155
3156
3157 6.4.20. Setting MIDI input channel
3158
3159 The front-end can alter the MIDI channel a sampler channel should
3160 listen to by sending the following command:
3161
3162 SET CHANNEL MIDI_INPUT_CHANNEL <sampler-channel> <midi-input-chan>
3163
3164 Where <midi-input-chan> is the number of the new MIDI input channel
3165 where <sampler-channel> should listen to or "ALL" to listen on all 16
3166 MIDI channels.
3167
3168 Possible Answers:
3169
3170 "OK" -
3171
3172 on success
3173
3174 "WRN:<warning-code>:<warning-message>" -
3175
3176 if MIDI input channel was set, but there are noteworthy
3177 issue(s) related, providing an appropriate warning code and
3178 warning message
3179
3180 "ERR:<error-code>:<error-message>" -
3181
3182 in case it failed, providing an appropriate error code and
3183 error message
3184
3185 Examples:
3186
3187
3188
3189
3190
3191 Schoenebeck Expires June 23, 2007 [Page 57]
3192
3193 Internet-Draft LinuxSampler Control Protocol December 2006
3194
3195
3196
3197
3198 6.4.21. Setting channel volume
3199
3200 The front-end can alter the volume of a sampler channel by sending
3201 the following command:
3202
3203 SET CHANNEL VOLUME <sampler-channel> <volume>
3204
3205 Where <volume> is an optionally dotted positive number (a value
3206 smaller than 1.0 means attenuation, whereas a value greater than 1.0
3207 means amplification) and <sampler-channel> defines the sampler
3208 channel where this volume factor should be set.
3209
3210 Possible Answers:
3211
3212 "OK" -
3213
3214 on success
3215
3216 "WRN:<warning-code>:<warning-message>" -
3217
3218 if channel volume was set, but there are noteworthy issue(s)
3219 related, providing an appropriate warning code and warning
3220 message
3221
3222 "ERR:<error-code>:<error-message>" -
3223
3224 in case it failed, providing an appropriate error code and
3225 error message
3226
3227 Examples:
3228
3229
3230
3231 6.4.22. Muting a sampler channel
3232
3233 The front-end can mute/unmute a specific sampler channel by sending
3234 the following command:
3235
3236 SET CHANNEL MUTE <sampler-channel> <mute>
3237
3238 Where <sampler-channel> is the respective sampler channel number as
3239 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3240 (Section 6.4.4) command and <mute> should be replaced either by "1"
3241 to mute the channel or "0" to unmute the channel.
3242
3243 Possible Answers:
3244
3245
3246
3247 Schoenebeck Expires June 23, 2007 [Page 58]
3248
3249 Internet-Draft LinuxSampler Control Protocol December 2006
3250
3251
3252 "OK" -
3253
3254 on success
3255
3256 "WRN:<warning-code>:<warning-message>" -
3257
3258 if the channel was muted/unmuted, but there are noteworthy
3259 issue(s) related, providing an appropriate warning code and
3260 warning message
3261
3262 "ERR:<error-code>:<error-message>" -
3263
3264 in case it failed, providing an appropriate error code and
3265 error message
3266
3267 Examples:
3268
3269
3270
3271 6.4.23. Soloing a sampler channel
3272
3273 The front-end can solo/unsolo a specific sampler channel by sending
3274 the following command:
3275
3276 SET CHANNEL SOLO <sampler-channel> <solo>
3277
3278 Where <sampler-channel> is the respective sampler channel number as
3279 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3280 (Section 6.4.4) command and <solo> should be replaced either by "1"
3281 to solo the channel or "0" to unsolo the channel.
3282
3283 Possible Answers:
3284
3285 "OK" -
3286
3287 on success
3288
3289 "WRN:<warning-code>:<warning-message>" -
3290
3291 if the channel was soloed/unsoloed, but there are noteworthy
3292 issue(s) related, providing an appropriate warning code and
3293 warning message
3294
3295 "ERR:<error-code>:<error-message>" -
3296
3297 in case it failed, providing an appropriate error code and
3298 error message
3299
3300
3301
3302
3303 Schoenebeck Expires June 23, 2007 [Page 59]
3304
3305 Internet-Draft LinuxSampler Control Protocol December 2006
3306
3307
3308 Examples:
3309
3310
3311
3312 6.4.24. Assigning a MIDI instrument map to a sampler channel
3313
3314 The front-end can assign a MIDI instrument map to a specific sampler
3315 channel by sending the following command:
3316
3317 SET CHANNEL MIDI_INSTRUMENT_MAP <sampler-channel> <map>
3318
3319 Where <sampler-channel> is the respective sampler channel number as
3320 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3321 (Section 6.4.4) command and <map> can have the following
3322 possibilites:
3323
3324 "NONE" -
3325
3326 This is the default setting. In this case the sampler channel
3327 is not assigned any MIDI instrument map and thus will ignore
3328 all MIDI program change messages.
3329
3330 "DEFAULT" -
3331
3332 The sampler channel will always use the default MIDI instrument
3333 map to handle MIDI program change messages.
3334
3335 numeric ID -
3336
3337 You can assign a specific MIDI instrument map by replacing
3338 <map> with the respective numeric ID of the MIDI instrument map
3339 as returned by the "LIST MIDI_INSTRUMENT_MAPS" (Section 6.7.4)
3340 command. Once that map will be deleted, the sampler channel
3341 would fall back to "NONE".
3342
3343 Read chapter "MIDI Instrument Mapping" (Section 6.7) for details
3344 regarding MIDI instrument mapping.
3345
3346 Possible Answers:
3347
3348 "OK" -
3349
3350 on success
3351
3352 "ERR:<error-code>:<error-message>" -
3353
3354 in case it failed, providing an appropriate error code and
3355 error message
3356
3357
3358
3359 Schoenebeck Expires June 23, 2007 [Page 60]
3360
3361 Internet-Draft LinuxSampler Control Protocol December 2006
3362
3363
3364 Examples:
3365
3366
3367
3368 6.4.25. Resetting a sampler channel
3369
3370 The front-end can reset a particular sampler channel by sending the
3371 following command:
3372
3373 RESET CHANNEL <sampler-channel>
3374
3375 Where <sampler-channel> defines the sampler channel to be reset.
3376 This will cause the engine on that sampler channel, its voices and
3377 eventually disk streams and all control and status variables to be
3378 reset.
3379
3380 Possible Answers:
3381
3382 "OK" -
3383
3384 on success
3385
3386 "WRN:<warning-code>:<warning-message>" -
3387
3388 if channel was reset, but there are noteworthy issue(s)
3389 related, providing an appropriate warning code and warning
3390 message
3391
3392 "ERR:<error-code>:<error-message>" -
3393
3394 in case it failed, providing an appropriate error code and
3395 error message
3396
3397 Examples:
3398
3399
3400
3401 6.5. Controlling connection
3402
3403 The following commands are used to control the connection to
3404 LinuxSampler.
3405
3406 6.5.1. Register front-end for receiving event messages
3407
3408 The front-end can register itself to the LinuxSampler application to
3409 be informed about noteworthy events by sending this command:
3410
3411
3412
3413
3414
3415 Schoenebeck Expires June 23, 2007 [Page 61]
3416
3417 Internet-Draft LinuxSampler Control Protocol December 2006
3418
3419
3420 SUBSCRIBE <event-id>
3421
3422 where <event-id> will be replaced by the respective event that client
3423 wants to subscribe to.
3424
3425 Possible Answers:
3426
3427 "OK" -
3428
3429 on success
3430
3431 "WRN:<warning-code>:<warning-message>" -
3432
3433 if registration succeeded, but there are noteworthy issue(s)
3434 related, providing an appropriate warning code and warning
3435 message
3436
3437 "ERR:<error-code>:<error-message>" -
3438
3439 in case it failed, providing an appropriate error code and
3440 error message
3441
3442 Examples:
3443
3444
3445
3446 6.5.2. Unregister front-end for not receiving event messages
3447
3448 The front-end can unregister itself if it doesn't want to receive
3449 event messages anymore by sending the following command:
3450
3451 UNSUBSCRIBE <event-id>
3452
3453 Where <event-id> will be replaced by the respective event that client
3454 doesn't want to receive anymore.
3455
3456 Possible Answers:
3457
3458 "OK" -
3459
3460 on success
3461
3462 "WRN:<warning-code>:<warning-message>" -
3463
3464 if unregistration succeeded, but there are noteworthy issue(s)
3465 related, providing an appropriate warning code and warning
3466 message
3467
3468
3469
3470
3471 Schoenebeck Expires June 23, 2007 [Page 62]
3472
3473 Internet-Draft LinuxSampler Control Protocol December 2006
3474
3475
3476 "ERR:<error-code>:<error-message>" -
3477
3478 in case it failed, providing an appropriate error code and
3479 error message
3480
3481 Examples:
3482
3483
3484
3485 6.5.3. Enable or disable echo of commands
3486
3487 To enable or disable back sending of commands to the client the
3488 following command can be used:
3489
3490 SET ECHO <value>
3491
3492 Where <value> should be replaced either by "1" to enable echo mode or
3493 "0" to disable echo mode. When echo mode is enabled, all commands
3494 send to LinuxSampler will be immediately send back and after this
3495 echo the actual response to the command will be returned. Echo mode
3496 will only be altered for the client connection that issued the "SET
3497 ECHO" command, not globally for all client connections.
3498
3499 Possible Answers:
3500
3501 "OK" -
3502
3503 usually
3504
3505 "ERR:<error-code>:<error-message>" -
3506
3507 on syntax error, e.g. non boolean value
3508
3509 Examples:
3510
3511
3512
3513 6.5.4. Close client connection
3514
3515 The client can close its network connection to LinuxSampler by
3516 sending the following command:
3517
3518 QUIT
3519
3520 This is probably more interesting for manual telnet connections to
3521 LinuxSampler than really useful for a front-end implementation.
3522
3523
3524
3525
3526
3527 Schoenebeck Expires June 23, 2007 [Page 63]
3528
3529 Internet-Draft LinuxSampler Control Protocol December 2006
3530
3531
3532 6.6. Global commands
3533
3534 The following commands have global impact on the sampler.
3535
3536 6.6.1. Current number of active voices
3537
3538 The front-end can ask for the current number of active voices on the
3539 sampler by sending the following command:
3540
3541 GET TOTAL_VOICE_COUNT
3542
3543 Possible Answers:
3544
3545 LinuxSampler will answer by returning the number of all active
3546 voices on the sampler.
3547
3548 6.6.2. Maximum amount of active voices
3549
3550 The front-end can ask for the maximum number of active voices by
3551 sending the following command:
3552
3553 GET TOTAL_VOICE_COUNT_MAX
3554
3555 Possible Answers:
3556
3557 LinuxSampler will answer by returning the maximum number of active
3558 voices.
3559
3560 6.6.3. Reset sampler
3561
3562 The front-end can reset the whole sampler by sending the following
3563 command:
3564
3565 RESET
3566
3567 Possible Answers:
3568
3569 "OK" -
3570
3571 always
3572
3573 Examples:
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583 Schoenebeck Expires June 23, 2007 [Page 64]
3584
3585 Internet-Draft LinuxSampler Control Protocol December 2006
3586
3587
3588 6.6.4. General sampler informations
3589
3590 The client can ask for general informations about the LinuxSampler
3591 instance by sending the following command:
3592
3593 GET SERVER INFO
3594
3595 Possible Answers:
3596
3597 LinuxSampler will answer by sending a <CRLF> separated list. Each
3598 answer line begins with the information category name followed by
3599 a colon and then a space character <SP> and finally the info
3600 character string to that information category. At the moment the
3601 following categories are defined:
3602
3603
3604
3605 DESCRIPTION -
3606
3607 arbitrary textual description about the sampler
3608
3609 VERSION -
3610
3611 version of the sampler
3612
3613 PROTOCOL_VERSION -
3614
3615 version of the LSCP specification the sampler complies with
3616 (see Section 2 for details)
3617
3618 The mentioned fields above don't have to be in particular order.
3619 Other fields might be added in future.
3620
3621 6.7. MIDI Instrument Mapping
3622
3623 The MIDI protocol provides a way to switch between instruments by
3624 sending so called MIDI bank select and MIDI program change messages
3625 which are essentially just numbers. The following commands allow to
3626 actually map arbitrary MIDI bank select / program change numbers with
3627 real instruments.
3628
3629 The sampler allows to manage an arbitrary amount of MIDI instrument
3630 maps which define which instrument to load on which MIDI program
3631 change message.
3632
3633 By default, that is when the sampler is launched, there is no map,
3634 thus the sampler will simply ignore all program change messages. The
3635 front-end has to explicitly create at least one map, add entries to
3636
3637
3638
3639 Schoenebeck Expires June 23, 2007 [Page 65]
3640
3641 Internet-Draft LinuxSampler Control Protocol December 2006
3642
3643
3644 the map and tell the respective sampler channel(s) which MIDI
3645 instrument map to use, so the sampler knows how to react on a given
3646 program change message on the respective sampler channel, that is by
3647 switching to the respectively defined engine type and loading the
3648 respective instrument. See command "SET CHANNEL MIDI_INSTRUMENT_MAP"
3649 (Section 6.4.24) for how to assign a MIDI instrument map to a sampler
3650 channel.
3651
3652 Also note per MIDI specification a bank select message does not cause
3653 to switch to another instrument. Instead when receiving a bank
3654 select message the bank value will be stored and a subsequent program
3655 change message (which may occur at any time) will finally cause the
3656 sampler to switch to the respective instrument as reflected by the
3657 current MIDI instrument map.
3658
3659 6.7.1. Create a new MIDI instrument map
3660
3661 The front-end can add a new MIDI instrument map by sending the
3662 following command:
3663
3664 ADD MIDI_INSTRUMENT_MAP [<name>]
3665
3666 Where <name> is an optional argument allowing to assign a custom name
3667 to the new map. MIDI instrument Map names do not have to be unique.
3668
3669 Possible Answers:
3670
3671 "OK[<map>]" -
3672
3673 in case a new MIDI instrument map could be added, where <map>
3674 reflects the unique ID of the newly created MIDI instrument map
3675
3676 "ERR:<error-code>:<error-message>" -
3677
3678 when a new map could not be created, which might never occur in
3679 practice
3680
3681 Examples:
3682
3683 C: "ADD MIDI_INSTRUMENT_MAP 'Standard Map'"
3684
3685 S: "OK[0]"
3686
3687 C: "ADD MIDI_INSTRUMENT_MAP 'Standard Drumkit'"
3688
3689 S: "OK[1]"
3690
3691
3692
3693
3694
3695 Schoenebeck Expires June 23, 2007 [Page 66]
3696
3697 Internet-Draft LinuxSampler Control Protocol December 2006
3698
3699
3700 C: "ADD MIDI_INSTRUMENT_MAP"
3701
3702 S: "OK[5]"
3703
3704 6.7.2. Delete one particular or all MIDI instrument maps
3705
3706 The front-end can delete a particular MIDI instrument map by sending
3707 the following command:
3708
3709 REMOVE MIDI_INSTRUMENT_MAP <map>
3710
3711 Where <map> reflects the unique ID of the map to delete as returned
3712 by the "LIST MIDI_INSTRUMENT_MAPS" (Section 6.7.4) command.
3713
3714 The front-end can delete all MIDI instrument maps by sending the
3715 following command:
3716
3717 REMOVE MIDI_INSTRUMENT_MAP ALL
3718
3719 Possible Answers:
3720
3721 "OK" -
3722
3723 in case the map(s) could be deleted
3724
3725 "ERR:<error-code>:<error-message>" -
3726
3727 when the given map does not exist
3728
3729 Examples:
3730
3731 C: "REMOVE MIDI_INSTRUMENT_MAP 0"
3732
3733 S: "OK"
3734
3735 C: "REMOVE MIDI_INSTRUMENT_MAP ALL"
3736
3737 S: "OK"
3738
3739 6.7.3. Get amount of existing MIDI instrument maps
3740
3741 The front-end can retrieve the current amount of MIDI instrument maps
3742 by sending the following command:
3743
3744 GET MIDI_INSTRUMENT_MAPS
3745
3746 Possible Answers:
3747
3748
3749
3750
3751 Schoenebeck Expires June 23, 2007 [Page 67]
3752
3753 Internet-Draft LinuxSampler Control Protocol December 2006
3754
3755
3756 The sampler will answer by returning the current number of MIDI
3757 instrument maps.
3758
3759 Example:
3760
3761 C: "GET MIDI_INSTRUMENT_MAPS"
3762
3763 S: "2"
3764
3765 6.7.4. Getting all created MIDI instrument maps
3766
3767 The number of MIDI instrument maps can change on runtime. To get the
3768 current list of MIDI instrument maps, the front-end can send the
3769 following command:
3770
3771 LIST MIDI_INSTRUMENT_MAPS
3772
3773 Possible Answers:
3774
3775 The sampler will answer by returning a comma separated list with
3776 all MIDI instrument maps' numerical IDs.
3777
3778 Example:
3779
3780 C: "LIST MIDI_INSTRUMENT_MAPS"
3781
3782 S: "0,1,5,12"
3783
3784 6.7.5. Getting MIDI instrument map information
3785
3786 The front-end can ask for the current settings of a MIDI instrument
3787 map by sending the following command:
3788
3789 GET MIDI_INSTRUMENT_MAP INFO <map>
3790
3791 Where <map> is the numerical ID of the map the front-end is
3792 interested in as returned by the "LIST MIDI_INSTRUMENT_MAPS"
3793 (Section 6.7.4) command.
3794
3795 Possible Answers:
3796
3797 LinuxSampler will answer by sending a <CRLF> separated list. Each
3798 answer line begins with the settings category name followed by a
3799 colon and then a space character <SP> and finally the info
3800 character string to that setting category. At the moment the
3801 following categories are defined:
3802
3803
3804
3805
3806
3807 Schoenebeck Expires June 23, 2007 [Page 68]
3808
3809 Internet-Draft LinuxSampler Control Protocol December 2006
3810
3811
3812
3813
3814 NAME -
3815
3816 custom name of the given map, which does not have to be
3817 unique
3818
3819 The mentioned fields above don't have to be in particular order.
3820
3821 Example:
3822
3823 C: "GET MIDI_INSTRUMENT_MAP INFO 0"
3824
3825 S: "NAME: Standard Map"
3826
3827 "."
3828
3829 6.7.6. Renaming a MIDI instrument map
3830
3831 The front-end can alter the custom name of a MIDI instrument map by
3832 sending the following command:
3833
3834 SET MIDI_INSTRUMENT_MAP NAME <map> <name>
3835
3836 Where <map> is the numerical ID of the map and <name> the new custom
3837 name of the map, which does not have to be unique.
3838
3839 Possible Answers:
3840
3841 "OK" -
3842
3843 on success
3844
3845 "ERR:<error-code>:<error-message>" -
3846
3847 in case the given map does not exist
3848
3849 Example:
3850
3851 C: "SET MIDI_INSTRUMENT_MAP NAME 0 'Foo instruments'"
3852
3853 S: "OK"
3854
3855 6.7.7. Create or replace a MIDI instrument map entry
3856
3857 The front-end can create a new or replace an existing entry in a
3858 sampler's MIDI instrument map by sending the following command:
3859
3860
3861
3862
3863 Schoenebeck Expires June 23, 2007 [Page 69]
3864
3865 Internet-Draft LinuxSampler Control Protocol December 2006
3866
3867
3868 MAP MIDI_INSTRUMENT <map> <midi_bank> <midi_prog> <engine_name>
3869 <filename> <instrument_index> <volume_value> [<instr_load_mode>]
3870 [<name>]
3871
3872 Where <map> is the numeric ID of the map to alter, <midi_bank> is an
3873 integer value between 0..16383 reflecting the MIDI bank select index,
3874 <midi_prog> an integer value between 0..127 reflecting the MIDI
3875 program change index, <engine_name> a sampler engine name as returned
3876 by the "LIST AVAILABLE_ENGINES" (Section 6.4.8) command (not
3877 encapsulated into apostrophes), <filename> the name of the
3878 instrument's file to be deployed (encapsulated into apostrophes),
3879 <instrument_index> the index (integer value) of the instrument within
3880 the given file, <volume_value> reflects the master volume of the
3881 instrument as optionally dotted number (where a value < 1.0 means
3882 attenuation and a value > 1.0 means amplification). This parameter
3883 easily allows to adjust the volume of all intruments within a custom
3884 instrument map without having to adjust their instrument files. The
3885 OPTIONAL <instr_load_mode> argument defines the life time of the
3886 instrument, that is when the instrument should be loaded, when freed
3887 and has exactly the following possibilities:
3888
3889 "ON_DEMAND" -
3890
3891 The instrument will be loaded when needed, that is when
3892 demanded by at least one sampler channel. It will immediately
3893 be freed from memory when not needed by any sampler channel
3894 anymore.
3895
3896 "ON_DEMAND_HOLD" -
3897
3898 The instrument will be loaded when needed, that is when
3899 demanded by at least one sampler channel. It will be kept in
3900 memory even when not needed by any sampler channel anymore.
3901 Instruments with this mode are only freed when the sampler is
3902 reset or all mapping entries with this mode (and respective
3903 instrument) are explicitly changed to "ON_DEMAND" and no
3904 sampler channel is using the instrument anymore.
3905
3906 "PERSISTENT" -
3907
3908 The instrument will immediately be loaded into memory in the
3909 background when this mapping command is sent and the instrument
3910 is kept all the time. Instruments with this mode are only
3911 freed when the sampler is reset or all mapping entries with
3912 this mode (and respective instrument) are explicitly changed to
3913 "ON_DEMAND" and no sampler channel is using the instrument
3914 anymore.
3915
3916
3917
3918
3919 Schoenebeck Expires June 23, 2007 [Page 70]
3920
3921 Internet-Draft LinuxSampler Control Protocol December 2006
3922
3923
3924 not supplied -
3925
3926 In case there is no <instr_load_mode> argument given, it will
3927 be up to the InstrumentManager to decide which mode to use.
3928 Usually it will use "ON_DEMAND" if an entry for the given
3929 instrument does not exist in the InstrumentManager's list yet,
3930 otherwise if an entry already exists, it will simply stick with
3931 the mode currently reflected by the already existing entry,
3932 that is it will not change the mode.
3933
3934 The <instr_load_mode> argument thus allows to define an appropriate
3935 strategy (low memory consumption vs. fast instrument switching) for
3936 each instrument individually. Note, the following restrictions apply
3937 to this argument: "ON_DEMAND_HOLD" and "PERSISTENT" have to be
3938 supported by the respective sampler engine (which is technically the
3939 case when the engine provides an InstrumentManager for its format).
3940 If this is not the case the argument will automatically fall back to
3941 the default value "ON_DEMAND". Also the load mode of one instrument
3942 may automatically change the laod mode of other instrument(s), i.e.
3943 because the instruments are part of the same file and the engine does
3944 not allow a way to manage load modes for them individually. Due to
3945 this, in case the frontend shows the load modes of entries, the
3946 frontend should retrieve the actual mode by i.e. sending "GET
3947 MIDI_INSTRUMENT INFO" (Section 6.7.11) command(s). Finally the
3948 OPTIONAL <name> argument allows to set a custom name (encapsulated
3949 into apostrophes) for the mapping entry, useful for frontends for
3950 displaying an appropriate name for mapped instruments (using "GET
3951 MIDI_INSTRUMENT INFO" (Section 6.7.11)).
3952
3953 The "MAP MIDI_INSTRUMENT" command will immediately return, thus it
3954 will not block when an instrument is to be loaded due to a
3955 "PERSISTENT" type entry as instruments are loaded in the background.
3956 As a consequence this command may not necessarily return an error
3957 i.e. when the given instrument file does not exist or may turn out to
3958 be corrupt.
3959
3960 Possible Answers:
3961
3962 "OK" -
3963
3964 usually
3965
3966 "ERR:<error-code>:<error-message>" -
3967
3968 when the given map or engine does not exist or a value is out
3969 of range
3970
3971 Examples:
3972
3973
3974
3975 Schoenebeck Expires June 23, 2007 [Page 71]
3976
3977 Internet-Draft LinuxSampler Control Protocol December 2006
3978
3979
3980 C: "MAP MIDI_INSTRUMENT 0 3 0 gig '/usr/share/Steinway D.gig' 0
3981 0.8 PERSISTENT"
3982
3983 S: "OK"
3984
3985 C: "MAP MIDI_INSTRUMENT 0 4 50 gig '/home/john/foostrings.gig' 7
3986 1.0"
3987
3988 S: "OK"
3989
3990 C: "MAP MIDI_INSTRUMENT 0 0 0 gig '/usr/share/piano.gig' 0 1.0
3991 'Normal Piano'"
3992
3993 S: "OK"
3994
3995 C: "MAP MIDI_INSTRUMENT 0 1 0 gig '/usr/share/piano.gig' 0 0.25
3996 'Silent Piano'"
3997
3998 S: "OK"
3999
4000 C: "MAP MIDI_INSTRUMENT 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0
4001 PERSISTENT 'Foo Drumkit'"
4002
4003 S: "OK"
4004
4005 6.7.8. Getting ammount of MIDI instrument map entries
4006
4007 The front-end can query the amount of currently existing entries in a
4008 MIDI instrument map by sending the following command:
4009
4010 GET MIDI_INSTRUMENTS <map>
4011
4012 The front-end can query the amount of currently existing entries in
4013 all MIDI instrument maps by sending the following command:
4014
4015 GET MIDI_INSTRUMENTS ALL
4016
4017 Possible Answers:
4018
4019 The sampler will answer by sending the current number of entries
4020 in the MIDI instrument map(s).
4021
4022 Example:
4023
4024 C: "GET MIDI_INSTRUMENTS 0"
4025
4026 S: "234"
4027
4028
4029
4030
4031 Schoenebeck Expires June 23, 2007 [Page 72]
4032
4033 Internet-Draft LinuxSampler Control Protocol December 2006
4034
4035
4036 C: "GET MIDI_INSTRUMENTS ALL"
4037
4038 S: "954"
4039
4040 6.7.9. Getting indeces of all entries of a MIDI instrument map
4041
4042 The front-end can query a list of all currently existing entries in a
4043 certain MIDI instrument map by sending the following command:
4044
4045 LIST MIDI_INSTRUMENTS <map>
4046
4047 Where <map> is the numeric ID of the MIDI instrument map.
4048
4049 The front-end can query a list of all currently existing entries of
4050 all MIDI instrument maps by sending the following command:
4051
4052 LIST MIDI_INSTRUMENTS ALL
4053
4054 Possible Answers:
4055
4056 The sampler will answer by sending a comma separated list of map
4057 ID - MIDI bank - MIDI program triples, where each triple is
4058 encapsulated into curly braces. The list is returned in one
4059 single line. Each triple just reflects the key of the respective
4060 map entry, thus subsequent "GET MIDI_INSTRUMENT INFO"
4061 (Section 6.7.11) command(s) are necessary to retrieve detailed
4062 informations about each entry.
4063
4064 Example:
4065
4066 C: "LIST MIDI_INSTRUMENTS 0"
4067
4068 S: "{0,0,0},{0,0,1},{0,0,3},{0,1,4},{1,127,127}"
4069
4070 6.7.10. Remove an entry from the MIDI instrument map
4071
4072 The front-end can delete an entry from a MIDI instrument map by
4073 sending the following command:
4074
4075 UNMAP MIDI_INSTRUMENT <map> <midi_bank> <midi_prog>
4076
4077 Where <map> is the numeric ID of the MIDI instrument map, <midi_bank>
4078 is an integer value between 0..16383 reflecting the MIDI bank value
4079 and <midi_prog> an integer value between 0..127 reflecting the MIDI
4080 program value of the map's entrie's key index triple.
4081
4082 Possible Answers:
4083
4084
4085
4086
4087 Schoenebeck Expires June 23, 2007 [Page 73]
4088
4089 Internet-Draft LinuxSampler Control Protocol December 2006
4090
4091
4092 "OK" -
4093
4094 usually
4095
4096 "ERR:<error-code>:<error-message>" -
4097
4098 when index out of bounds
4099
4100 Example:
4101
4102 C: "UNMAP MIDI_INSTRUMENT 0 2 127"
4103
4104 S: "OK"
4105
4106 6.7.11. Get current settings of MIDI instrument map entry
4107
4108 The front-end can retrieve the current settings of a certain
4109 instrument map entry by sending the following command:
4110
4111 GET MIDI_INSTRUMENT INFO <map> <midi_bank> <midi_prog>
4112
4113 Where <map> is the numeric ID of the MIDI instrument map, <midi_bank>
4114 is an integer value between 0..16383 reflecting the MIDI bank value,
4115 <midi_bank> and <midi_prog> an integer value between 0..127
4116 reflecting the MIDI program value of the map's entrie's key index
4117 triple.
4118
4119 Possible Answers:
4120
4121 LinuxSampler will answer by sending a <CRLF> separated list. Each
4122 answer line begins with the information category name followed by
4123 a colon and then a space character <SP> and finally the info
4124 character string to that info category. At the moment the
4125 following categories are defined:
4126
4127 "NAME" -
4128
4129 Name for this MIDI instrument map entry (if defined). This
4130 name shall be used by frontends for displaying a name for this
4131 mapped instrument. It can be set and changed with the "MAP
4132 MIDI_INSTRUMENT" (Section 6.7.7) command and does not have to
4133 be unique.
4134
4135 "ENGINE_NAME" -
4136
4137 Name of the engine to be deployed for this instrument.
4138
4139
4140
4141
4142
4143 Schoenebeck Expires June 23, 2007 [Page 74]
4144
4145 Internet-Draft LinuxSampler Control Protocol December 2006
4146
4147
4148 "INSTRUMENT_FILE" -
4149
4150 File name of the instrument.
4151
4152 "INSTRUMENT_NR" -
4153
4154 Index of the instrument within the file.
4155
4156 "INSTRUMENT_NAME" -
4157
4158 Name of the loaded instrument as reflected by its file. In
4159 contrast to the "NAME" field, the "INSTRUMENT_NAME" field
4160 cannot be changed.
4161
4162 "LOAD_MODE" -
4163
4164 Life time of instrument (see "MAP MIDI_INSTRUMENT"
4165 (Section 6.7.7) for details about this setting).
4166
4167 "VOLUME" -
4168
4169 master volume of the instrument as optionally dotted number
4170 (where a value < 1.0 means attenuation and a value > 1.0 means
4171 amplification)
4172
4173 The mentioned fields above don't have to be in particular order.
4174
4175 Example:
4176
4177 C: "GET MIDI_INSTRUMENT INFO 1 45 120"
4178
4179 S: "NAME: Drums for Foo Song"
4180
4181 "ENGINE_NAME: GigEngine"
4182
4183 "INSTRUMENT_FILE: /usr/share/joesdrumkit.gig"
4184
4185 "INSTRUMENT_NR: 0"
4186
4187 "INSTRUMENT_NAME: Joe's Drumkit"
4188
4189 "LOAD_MODE: PERSISTENT"
4190
4191 "VOLUME: 1.0"
4192
4193 "."
4194
4195
4196
4197
4198
4199 Schoenebeck Expires June 23, 2007 [Page 75]
4200
4201 Internet-Draft LinuxSampler Control Protocol December 2006
4202
4203
4204 6.7.12. Clear MIDI instrument map
4205
4206 The front-end can clear a whole MIDI instrument map, that is delete
4207 all its entries by sending the following command:
4208
4209 CLEAR MIDI_INSTRUMENTS <map>
4210
4211 Where <map> is the numeric ID of the map to clear.
4212
4213 The front-end can clear all MIDI instrument maps, that is delete all
4214 entries of all maps by sending the following command:
4215
4216 CLEAR MIDI_INSTRUMENTS ALL
4217
4218 The command "CLEAR MIDI_INSTRUMENTS ALL" does not delete the maps,
4219 only their entries, thus the map's settings like custom name will be
4220 preservevd.
4221
4222 Possible Answers:
4223
4224 "OK" -
4225
4226 always
4227
4228 Examples:
4229
4230 C: "CLEAR MIDI_INSTRUMENTS 0"
4231
4232 S: "OK"
4233
4234 C: "CLEAR MIDI_INSTRUMENTS ALL"
4235
4236 S: "OK"
4237
4238
4239
4240
4241
4242
4243
4244
4245
4246
4247
4248
4249
4250
4251
4252
4253
4254
4255 Schoenebeck Expires June 23, 2007 [Page 76]
4256
4257 Internet-Draft LinuxSampler Control Protocol December 2006
4258
4259
4260 7. Command Syntax
4261
4262 The grammar of the control protocol as descibed in Section 6 is
4263 defined below using Backus-Naur Form (BNF as described in [RFC2234])
4264 where applicable.
4265
4266 input =
4267
4268 line LF
4269
4270 / line CR LF
4271
4272 line =
4273
4274 /* epsilon (empty line ignored) */
4275
4276 / comment
4277
4278 / command
4279
4280 / error
4281
4282 comment =
4283
4284 '#'
4285
4286 / comment '#'
4287
4288 / comment SP
4289
4290 / comment number
4291
4292 / comment string
4293
4294 command =
4295
4296 ADD SP add_instruction
4297
4298 / MAP SP map_instruction
4299
4300 / UNMAP SP unmap_instruction
4301
4302 / GET SP get_instruction
4303
4304 / CREATE SP create_instruction
4305
4306 / DESTROY SP destroy_instruction
4307
4308
4309
4310
4311 Schoenebeck Expires June 23, 2007 [Page 77]
4312
4313 Internet-Draft LinuxSampler Control Protocol December 2006
4314
4315
4316 / LIST SP list_instruction
4317
4318 / LOAD SP load_instruction
4319
4320 / REMOVE SP remove_instruction
4321
4322 / SET SP set_instruction
4323
4324 / SUBSCRIBE SP subscribe_event
4325
4326 / UNSUBSCRIBE SP unsubscribe_event
4327
4328 / SELECT SP text
4329
4330 / RESET SP reset_instruction
4331
4332 / CLEAR SP clear_instruction
4333
4334 / RESET
4335
4336 / QUIT
4337
4338 add_instruction =
4339
4340 CHANNEL
4341
4342 / MIDI_INSTRUMENT_MAP
4343
4344 / MIDI_INSTRUMENT_MAP SP map_name
4345
4346 subscribe_event =
4347
4348 AUDIO_OUTPUT_DEVICE_COUNT
4349
4350 / AUDIO_OUTPUT_DEVICE_INFO
4351
4352 / MIDI_INPUT_DEVICE_COUNT
4353
4354 / MIDI_INPUT_DEVICE_INFO
4355
4356 / CHANNEL_COUNT
4357
4358 / VOICE_COUNT
4359
4360 / STREAM_COUNT
4361
4362 / BUFFER_FILL
4363
4364
4365
4366
4367 Schoenebeck Expires June 23, 2007 [Page 78]
4368
4369 Internet-Draft LinuxSampler Control Protocol December 2006
4370
4371
4372 / CHANNEL_INFO
4373
4374 / MIDI_INSTRUMENT_MAP_COUNT
4375
4376 / MIDI_INSTRUMENT_MAP_INFO
4377
4378 / MIDI_INSTRUMENT_COUNT
4379
4380 / MIDI_INSTRUMENT_INFO
4381
4382 / MISCELLANEOUS
4383
4384 / TOTAL_VOICE_COUNT
4385
4386 unsubscribe_event =
4387
4388 AUDIO_OUTPUT_DEVICE_COUNT
4389
4390 / AUDIO_OUTPUT_DEVICE_INFO
4391
4392 / MIDI_INPUT_DEVICE_COUNT
4393
4394 / MIDI_INPUT_DEVICE_INFO
4395
4396 / CHANNEL_COUNT
4397
4398 / VOICE_COUNT
4399
4400 / STREAM_COUNT
4401
4402 / BUFFER_FILL
4403
4404 / CHANNEL_INFO
4405
4406 / MIDI_INSTRUMENT_MAP_COUNT
4407
4408 / MIDI_INSTRUMENT_MAP_INFO
4409
4410 / MIDI_INSTRUMENT_COUNT
4411
4412 / MIDI_INSTRUMENT_INFO
4413
4414 / MISCELLANEOUS
4415
4416 / TOTAL_VOICE_COUNT
4417
4418 map_instruction =
4419
4420
4421
4422
4423 Schoenebeck Expires June 23, 2007 [Page 79]
4424
4425 Internet-Draft LinuxSampler Control Protocol December 2006
4426
4427
4428 MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP
4429 engine_name SP filename SP instrument_index SP volume_value
4430
4431 / MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP
4432 engine_name SP filename SP instrument_index SP volume_value SP
4433 instr_load_mode
4434
4435 / MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP
4436 engine_name SP filename SP instrument_index SP volume_value SP
4437 entry_name
4438
4439 / MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP
4440 engine_name SP filename SP instrument_index SP volume_value SP
4441 instr_load_mode SP entry_name
4442
4443 unmap_instruction =
4444
4445 MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog
4446
4447 remove_instruction =
4448
4449 CHANNEL SP sampler_channel
4450
4451 / MIDI_INSTRUMENT_MAP SP midi_map
4452
4453 / MIDI_INSTRUMENT_MAP SP ALL
4454
4455 get_instruction =
4456
4457 AVAILABLE_ENGINES
4458
4459 / AVAILABLE_MIDI_INPUT_DRIVERS
4460
4461 / MIDI_INPUT_DRIVER SP INFO SP string
4462
4463 / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
4464
4465 / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP
4466 key_val_list
4467
4468 / AVAILABLE_AUDIO_OUTPUT_DRIVERS
4469
4470 / AUDIO_OUTPUT_DRIVER SP INFO SP string
4471
4472 / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
4473
4474 / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP
4475 key_val_list
4476
4477
4478
4479 Schoenebeck Expires June 23, 2007 [Page 80]
4480
4481 Internet-Draft LinuxSampler Control Protocol December 2006
4482
4483
4484 / AUDIO_OUTPUT_DEVICES
4485
4486 / MIDI_INPUT_DEVICES
4487
4488 / AUDIO_OUTPUT_DEVICE SP INFO SP number
4489
4490 / MIDI_INPUT_DEVICE SP INFO SP number
4491
4492 / MIDI_INPUT_PORT SP INFO SP number SP number
4493
4494 / MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
4495
4496 / AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
4497
4498 / AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP
4499 string
4500
4501 / CHANNELS
4502
4503 / CHANNEL SP INFO SP sampler_channel
4504
4505 / CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
4506
4507 / CHANNEL SP STREAM_COUNT SP sampler_channel
4508
4509 / CHANNEL SP VOICE_COUNT SP sampler_channel
4510
4511 / ENGINE SP INFO SP engine_name
4512
4513 / SERVER SP INFO
4514
4515 / TOTAL_VOICE_COUNT
4516
4517 / TOTAL_VOICE_COUNT_MAX
4518
4519 / MIDI_INSTRUMENTS SP midi_map
4520
4521 / MIDI_INSTRUMENTS SP ALL
4522
4523 / MIDI_INSTRUMENT SP INFO SP midi_map SP midi_bank SP midi_prog
4524
4525 / MIDI_INSTRUMENT_MAPS
4526
4527 / MIDI_INSTRUMENT_MAP SP INFO SP midi_map
4528
4529 set_instruction =
4530
4531
4532
4533
4534
4535 Schoenebeck Expires June 23, 2007 [Page 81]
4536
4537 Internet-Draft LinuxSampler Control Protocol December 2006
4538
4539
4540 AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '='
4541 param_val_list
4542
4543 / AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '='
4544 param_val_list
4545
4546 / MIDI_INPUT_DEVICE_PARAMETER SP number SP string '='
4547 param_val_list
4548
4549 / MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '='
4550 param_val_list
4551
4552 / CHANNEL SP set_chan_instruction
4553
4554 / MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
4555
4556 / ECHO SP boolean
4557
4558 create_instruction =
4559
4560 AUDIO_OUTPUT_DEVICE SP string SP key_val_list
4561
4562 / AUDIO_OUTPUT_DEVICE SP string
4563
4564 / MIDI_INPUT_DEVICE SP string SP key_val_list
4565
4566 / MIDI_INPUT_DEVICE SP string
4567
4568 reset_instruction =
4569
4570 CHANNEL SP sampler_channel
4571
4572 clear_instruction =
4573
4574 MIDI_INSTRUMENTS SP midi_map
4575
4576 / MIDI_INSTRUMENTS SP ALL
4577
4578 destroy_instruction =
4579
4580 AUDIO_OUTPUT_DEVICE SP number
4581
4582 / MIDI_INPUT_DEVICE SP number
4583
4584 load_instruction =
4585
4586 INSTRUMENT SP load_instr_args
4587
4588
4589
4590
4591 Schoenebeck Expires June 23, 2007 [Page 82]
4592
4593 Internet-Draft LinuxSampler Control Protocol December 2006
4594
4595
4596 / ENGINE SP load_engine_args
4597
4598 set_chan_instruction =
4599
4600 AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
4601
4602 / AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index
4603 SP audio_channel_index
4604
4605 / AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
4606
4607 / MIDI_INPUT SP sampler_channel SP device_index SP
4608 midi_input_port_index SP midi_input_channel_index
4609
4610 / MIDI_INPUT_DEVICE SP sampler_channel SP device_index
4611
4612 / MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
4613
4614 / MIDI_INPUT_CHANNEL SP sampler_channel SP
4615 midi_input_channel_index
4616
4617 / MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
4618
4619 / VOLUME SP sampler_channel SP volume_value
4620
4621 / MUTE SP sampler_channel SP boolean
4622
4623 / SOLO SP sampler_channel SP boolean
4624
4625 / MIDI_INSTRUMENT_MAP SP sampler_channel SP midi_map
4626
4627 / MIDI_INSTRUMENT_MAP SP sampler_channel SP NONE
4628
4629 / MIDI_INSTRUMENT_MAP SP sampler_channel SP DEFAULT
4630
4631 key_val_list =
4632
4633 string '=' param_val_list
4634
4635 / key_val_list SP string '=' param_val_list
4636
4637 buffer_size_type =
4638
4639 BYTES
4640
4641 / PERCENTAGE
4642
4643 list_instruction =
4644
4645
4646
4647 Schoenebeck Expires June 23, 2007 [Page 83]
4648
4649 Internet-Draft LinuxSampler Control Protocol December 2006
4650
4651
4652 AUDIO_OUTPUT_DEVICES
4653
4654 / MIDI_INPUT_DEVICES
4655
4656 / CHANNELS
4657
4658 / AVAILABLE_ENGINES
4659
4660 / AVAILABLE_MIDI_INPUT_DRIVERS
4661
4662 / AVAILABLE_AUDIO_OUTPUT_DRIVERS
4663
4664 / MIDI_INSTRUMENTS SP midi_map
4665
4666 / MIDI_INSTRUMENTS SP ALL
4667
4668 / MIDI_INSTRUMENT_MAPS
4669
4670 load_instr_args =
4671
4672 filename SP instrument_index SP sampler_channel
4673
4674 / NON_MODAL SP filename SP instrument_index SP sampler_channel
4675
4676 load_engine_args =
4677
4678 engine_name SP sampler_channel
4679
4680 instr_load_mode =
4681
4682 ON_DEMAND
4683
4684 / ON_DEMAND_HOLD
4685
4686 / PERSISTENT
4687
4688 device_index =
4689
4690 number
4691
4692 audio_channel_index =
4693
4694 number
4695
4696 audio_output_type_name =
4697
4698 string
4699
4700
4701
4702
4703 Schoenebeck Expires June 23, 2007 [Page 84]
4704
4705 Internet-Draft LinuxSampler Control Protocol December 2006
4706
4707
4708 midi_input_port_index =
4709
4710 number
4711
4712 midi_input_channel_index =
4713
4714 number
4715
4716 / ALL
4717
4718 midi_input_type_name =
4719
4720 string
4721
4722 midi_map =
4723
4724 number
4725
4726 midi_bank =
4727
4728 number
4729
4730 midi_prog =
4731
4732 number
4733
4734 volume_value =
4735
4736 dotnum
4737
4738 / number
4739
4740 sampler_channel =
4741
4742 number
4743
4744 instrument_index =
4745
4746 number
4747
4748 engine_name =
4749
4750 string
4751
4752 filename =
4753
4754 stringval
4755
4756
4757
4758
4759 Schoenebeck Expires June 23, 2007 [Page 85]
4760
4761 Internet-Draft LinuxSampler Control Protocol December 2006
4762
4763
4764 map_name =
4765
4766 stringval
4767
4768 entry_name =
4769
4770 stringval
4771
4772 param_val_list =
4773
4774 param_val
4775
4776 / param_val_list','param_val
4777
4778 param_val =
4779
4780 string
4781
4782 / stringval
4783
4784 / number
4785
4786 / dotnum
4787
4788
4789
4790
4791
4792
4793
4794
4795
4796
4797
4798
4799
4800
4801
4802
4803
4804
4805
4806
4807
4808
4809
4810
4811
4812
4813
4814
4815 Schoenebeck Expires June 23, 2007 [Page 86]
4816
4817 Internet-Draft LinuxSampler Control Protocol December 2006
4818
4819
4820 8. Events
4821
4822 This chapter will describe all currently defined events supported by
4823 LinuxSampler.
4824
4825 8.1. Number of audio output devices changed
4826
4827 Client may want to be notified when the total number of audio output
4828 devices on the back-end changes by issuing the following command:
4829
4830 SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT
4831
4832 Server will start sending the following notification messages:
4833
4834 "NOTIFY:AUDIO_OUTPUT_DEVICE_COUNT:<devices>"
4835
4836 where <devices> will be replaced by the new number of audio output
4837 devices.
4838
4839 8.2. Audio output device's settings changed
4840
4841 Client may want to be notified when changes were made to audio output
4842 devices on the back-end by issuing the following command:
4843
4844 SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO
4845
4846 Server will start sending the following notification messages:
4847
4848 "NOTIFY:AUDIO_OUTPUT_DEVICE_INFO:<device-id>"
4849
4850 where <device-id> will be replaced by the numerical ID of the audio
4851 output device, which settings has been changed. The front-end will
4852 have to send the respective command to actually get the audio output
4853 device info. Because these messages will be triggered by LSCP
4854 commands issued by other clients rather than real time events
4855 happening on the server, it is believed that an empty notification
4856 message is sufficient here.
4857
4858 8.3. Number of MIDI input devices changed
4859
4860 Client may want to be notified when the total number of MIDI input
4861 devices on the back-end changes by issuing the following command:
4862
4863 SUBSCRIBE MIDI_INPUT_DEVICE_COUNT
4864
4865 Server will start sending the following notification messages:
4866
4867
4868
4869
4870
4871 Schoenebeck Expires June 23, 2007 [Page 87]
4872
4873 Internet-Draft LinuxSampler Control Protocol December 2006
4874
4875
4876 "NOTIFY:MIDI_INPUT_DEVICE_COUNT:<devices>"
4877
4878 where <devices> will be replaced by the new number of MIDI input
4879 devices.
4880
4881 8.4. MIDI input device's settings changed
4882
4883 Client may want to be notified when changes were made to MIDI input
4884 devices on the back-end by issuing the following command:
4885
4886 SUBSCRIBE MIDI_INPUT_DEVICE_INFO
4887
4888 Server will start sending the following notification messages:
4889
4890 "NOTIFY:MIDI_INPUT_DEVICE_INFO:<device-id>"
4891
4892 where <device-id> will be replaced by the numerical ID of the MIDI
4893 input device, which settings has been changed. The front-end will
4894 have to send the respective command to actually get the MIDI input
4895 device info. Because these messages will be triggered by LSCP
4896 commands issued by other clients rather than real time events
4897 happening on the server, it is believed that an empty notification
4898 message is sufficient here.
4899
4900 8.5. Number of sampler channels changed
4901
4902 Client may want to be notified when the total number of channels on
4903 the back-end changes by issuing the following command:
4904
4905 SUBSCRIBE CHANNEL_COUNT
4906
4907 Server will start sending the following notification messages:
4908
4909 "NOTIFY:CHANNEL_COUNT:<channels>"
4910
4911 where <channels> will be replaced by the new number of sampler
4912 channels.
4913
4914 8.6. Number of active voices changed
4915
4916 Client may want to be notified when the number of voices on the back-
4917 end changes by issuing the following command:
4918
4919 SUBSCRIBE VOICE_COUNT
4920
4921 Server will start sending the following notification messages:
4922
4923
4924
4925
4926
4927 Schoenebeck Expires June 23, 2007 [Page 88]
4928
4929 Internet-Draft LinuxSampler Control Protocol December 2006
4930
4931
4932 "NOTIFY:VOICE_COUNT:<sampler-channel> <voices>
4933
4934 where <sampler-channel> will be replaced by the sampler channel the
4935 voice count change occurred and <voices> by the new number of active
4936 voices on that channel.
4937
4938 8.7. Number of active disk streams changed
4939
4940 Client may want to be notified when the number of streams on the
4941 back-end changes by issuing the following command: SUBSCRIBE
4942 STREAM_COUNT
4943
4944 SUBSCRIBE STREAM_COUNT
4945
4946 Server will start sending the following notification messages:
4947
4948 "NOTIFY:STREAM_COUNT:<sampler-channel> <streams>"
4949
4950 where <sampler-channel> will be replaced by the sampler channel the
4951 stream count change occurred and <streams> by the new number of
4952 active disk streams on that channel.
4953
4954 8.8. Disk stream buffer fill state changed
4955
4956 Client may want to be notified when the buffer fill state of a disk
4957 stream on the back-end changes by issuing the following command:
4958
4959 SUBSCRIBE BUFFER_FILL
4960
4961 Server will start sending the following notification messages:
4962
4963 "NOTIFY:BUFFER_FILL:<sampler-channel> <fill-data>"
4964
4965 where <sampler-channel> will be replaced by the sampler channel the
4966 buffer fill state change occurred on and <fill-data> will be replaced
4967 by the buffer fill data for this channel as described in
4968 Section 6.4.13 as if the "GET CHANNEL BUFFER_FILL PERCENTAGE"
4969 (Section 6.4.13) command was issued on this channel.
4970
4971 8.9. Channel information changed
4972
4973 Client may want to be notified when changes were made to sampler
4974 channels on the back-end by issuing the following command:
4975
4976 SUBSCRIBE CHANNEL_INFO
4977
4978 Server will start sending the following notification messages:
4979
4980
4981
4982
4983 Schoenebeck Expires June 23, 2007 [Page 89]
4984
4985 Internet-Draft LinuxSampler Control Protocol December 2006
4986
4987
4988 "NOTIFY:CHANNEL_INFO:<sampler-channel>"
4989
4990 where <sampler-channel> will be replaced by the sampler channel the
4991 channel info change occurred. The front-end will have to send the
4992 respective command to actually get the channel info. Because these
4993 messages will be triggered by LSCP commands issued by other clients
4994 rather than real time events happening on the server, it is believed
4995 that an empty notification message is sufficient here.
4996
4997 8.10. Total number of active voices changed
4998
4999 Client may want to be notified when the total number of voices on the
5000 back-end changes by issuing the following command:
5001
5002 SUBSCRIBE TOTAL_VOICE_COUNT
5003
5004 Server will start sending the following notification messages:
5005
5006 "NOTIFY:TOTAL_VOICE_COUNT:<voices>
5007
5008 where <voices> will be replaced by the new number of all currently
5009 active voices.
5010
5011 8.11. Number of MIDI instrument maps changed
5012
5013 Client may want to be notified when the number of MIDI instrument
5014 maps on the back-end changes by issuing the following command:
5015
5016 SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT
5017
5018 Server will start sending the following notification messages:
5019
5020 "NOTIFY:MIDI_INSTRUMENT_MAP_COUNT:<maps>"
5021
5022 where <maps> will be replaced by the new number of MIDI instrument
5023 maps.
5024
5025 8.12. MIDI instrument map information changed
5026
5027 Client may want to be notified when changes were made to MIDI
5028 instrument maps on the back-end by issuing the following command:
5029
5030 SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO
5031
5032 Server will start sending the following notification messages:
5033
5034
5035
5036
5037
5038
5039 Schoenebeck Expires June 23, 2007 [Page 90]
5040
5041 Internet-Draft LinuxSampler Control Protocol December 2006
5042
5043
5044 "NOTIFY:MIDI_INSTRUMENT_MAP_INFO:<map-id>"
5045
5046 where <map-id> will be replaced by the numerical ID of the MIDI
5047 instrument map, for which information changes occurred. The front-
5048 end will have to send the respective command to actually get the MIDI
5049 instrument map info. Because these messages will be triggered by
5050 LSCP commands issued by other clients rather than real time events
5051 happening on the server, it is believed that an empty notification
5052 message is sufficient here.
5053
5054 8.13. Number of MIDI instruments changed
5055
5056 Client may want to be notified when the number of MIDI instrument
5057 maps on the back-end changes by issuing the following command:
5058
5059 SUBSCRIBE MIDI_INSTRUMENT_COUNT
5060
5061 Server will start sending the following notification messages:
5062
5063 "NOTIFY:MIDI_INSTRUMENT_COUNT:<map-id> <instruments>"
5064
5065 where <map-id> is the numerical ID of the MIDI instrument map, in
5066 which the nuber of instruments has changed and <instruments> will be
5067 replaced by the new number of MIDI instruments in the specified map.
5068
5069 8.14. MIDI instrument information changed
5070
5071 Client may want to be notified when changes were made to MIDI
5072 instruments on the back-end by issuing the following command:
5073
5074 SUBSCRIBE MIDI_INSTRUMENT_INFO
5075
5076 Server will start sending the following notification messages:
5077
5078 "NOTIFY:MIDI_INSTRUMENT_INFO:<map-id> <bank> <program>"
5079
5080 where <map-id> will be replaced by the numerical ID of the MIDI
5081 instrument map, in which a MIDI instrument is changed. <bank> and
5082 <program> specifies the location of the changed MIDI instrument in
5083 the map. The front-end will have to send the respective command to
5084 actually get the MIDI instrument info. Because these messages will
5085 be triggered by LSCP commands issued by other clients rather than
5086 real time events happening on the server, it is believed that an
5087 empty notification message is sufficient here.
5088
5089
5090
5091
5092
5093
5094
5095 Schoenebeck Expires June 23, 2007 [Page 91]
5096
5097 Internet-Draft LinuxSampler Control Protocol December 2006
5098
5099
5100 8.15. Miscellaneous and debugging events
5101
5102 Client may want to be notified of miscellaneous and debugging events
5103 occurring at the server by issuing the following command:
5104
5105 SUBSCRIBE MISCELLANEOUS
5106
5107 Server will start sending the following notification messages:
5108
5109 "NOTIFY:MISCELLANEOUS:<string>"
5110
5111 where <string> will be replaced by whatever data server wants to send
5112 to the client. Client MAY display this data to the user AS IS to
5113 facilitate debugging.
5114
5115
5116
5117
5118
5119
5120
5121
5122
5123
5124
5125
5126
5127
5128
5129
5130
5131
5132
5133
5134
5135
5136
5137
5138
5139
5140
5141
5142
5143
5144
5145
5146
5147
5148
5149
5150
5151 Schoenebeck Expires June 23, 2007 [Page 92]
5152
5153 Internet-Draft LinuxSampler Control Protocol December 2006
5154
5155
5156 9. Security Considerations
5157
5158 As there is so far no method of authentication and authorization
5159 defined and so not required for a client applications to succeed to
5160 connect, running LinuxSampler might be a security risk for the host
5161 system the LinuxSampler instance is running on.
5162
5163
5164
5165
5166
5167
5168
5169
5170
5171
5172
5173
5174
5175
5176
5177
5178
5179
5180
5181
5182
5183
5184
5185
5186
5187
5188
5189
5190
5191
5192
5193
5194
5195
5196
5197
5198
5199
5200
5201
5202
5203
5204
5205
5206
5207 Schoenebeck Expires June 23, 2007 [Page 93]
5208
5209 Internet-Draft LinuxSampler Control Protocol December 2006
5210
5211
5212 10. Acknowledgments
5213
5214 This document has benefited greatly from the comments of the
5215 following people, discussed on the LinuxSampler developer's mailing
5216 list:
5217
5218 Rui Nuno Capela
5219
5220 Vladimir Senkov
5221
5222 Mark Knecht
5223
5224 Grigor Iliev
5225
5226
5227
5228
5229
5230
5231
5232
5233
5234
5235
5236
5237
5238
5239
5240
5241
5242
5243
5244
5245
5246
5247
5248
5249
5250
5251
5252
5253
5254
5255
5256
5257
5258
5259
5260
5261
5262
5263 Schoenebeck Expires June 23, 2007 [Page 94]
5264
5265 Internet-Draft LinuxSampler Control Protocol December 2006
5266
5267
5268 11. References
5269
5270 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
5271 Requirement Levels", RFC 2119, 1997.
5272
5273 [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
5274 Specifications", RFC 2234, 1997.
5275
5276 [RFC793] Defense Advanced Research Projects Agency, "TRANSMISSION
5277 CONTROL PROTOCOL", RFC 793, 1981.
5278
5279
5280
5281
5282
5283
5284
5285
5286
5287
5288
5289
5290
5291
5292
5293
5294
5295
5296
5297
5298
5299
5300
5301
5302
5303
5304
5305
5306
5307
5308
5309
5310
5311
5312
5313
5314
5315
5316
5317
5318
5319 Schoenebeck Expires June 23, 2007 [Page 95]
5320
5321 Internet-Draft LinuxSampler Control Protocol December 2006
5322
5323
5324 Author's Address
5325
5326 C. Schoenebeck
5327 Interessengemeinschaft Software Engineering e. V.
5328 Max-Planck-Str. 39
5329 74081 Heilbronn
5330 Germany
5331
5332 Email: schoenebeck at software minus engineering dot org
5333
5334
5335
5336
5337
5338
5339
5340
5341
5342
5343
5344
5345
5346
5347
5348
5349
5350
5351
5352
5353
5354
5355
5356
5357
5358
5359
5360
5361
5362
5363
5364
5365
5366
5367
5368
5369
5370
5371
5372
5373
5374
5375 Schoenebeck Expires June 23, 2007 [Page 96]
5376
5377 Internet-Draft LinuxSampler Control Protocol December 2006
5378
5379
5380 Full Copyright Statement
5381
5382 Copyright (C) The Internet Society (2006).
5383
5384 This document is subject to the rights, licenses and restrictions
5385 contained in BCP 78, and except as set forth therein, the authors
5386 retain all their rights.
5387
5388 This document and the information contained herein are provided on an
5389 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
5390 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
5391 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
5392 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
5393 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
5394 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
5395
5396
5397 Intellectual Property
5398
5399 The IETF takes no position regarding the validity or scope of any
5400 Intellectual Property Rights or other rights that might be claimed to
5401 pertain to the implementation or use of the technology described in
5402 this document or the extent to which any license under such rights
5403 might or might not be available; nor does it represent that it has
5404 made any independent effort to identify any such rights. Information
5405 on the procedures with respect to rights in RFC documents can be
5406 found in BCP 78 and BCP 79.
5407
5408 Copies of IPR disclosures made to the IETF Secretariat and any
5409 assurances of licenses to be made available, or the result of an
5410 attempt made to obtain a general license or permission for the use of
5411 such proprietary rights by implementers or users of this
5412 specification can be obtained from the IETF on-line IPR repository at
5413 http://www.ietf.org/ipr.
5414
5415 The IETF invites any interested party to bring to its attention any
5416 copyrights, patents or patent applications, or other proprietary
5417 rights that may cover technology that may be required to implement
5418 this standard. Please address the information to the IETF at
5419 ietf-ipr@ietf.org.
5420
5421
5422 Acknowledgment
5423
5424 Funding for the RFC Editor function is provided by the IETF
5425 Administrative Support Activity (IASA).
5426
5427
5428
5429
5430
5431 Schoenebeck Expires June 23, 2007 [Page 97]
5432

  ViewVC Help
Powered by ViewVC