/[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 1110 - (show annotations) (download)
Thu Mar 22 21:12:10 2007 UTC (13 years, 4 months ago) by iliev
File MIME type: text/plain
File size: 168415 byte(s)
- Added new notification events for tracking
effect send changes and global volume changes

1
2
3
4 LinuxSampler Developers C. Schoenebeck
5 Internet-Draft Interessengemeinschaft Software
6 Intended status: Standards Track Engineering e. V.
7 Expires: September 23, 2007 March 22, 2007
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 September 23, 2007.
37
38 Copyright Notice
39
40 Copyright (C) The IETF Trust (2007).
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55 Schoenebeck Expires September 23, 2007 [Page 1]
56
57 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 2]
112
113 Internet-Draft LinuxSampler Control Protocol March 2007
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. Adding an effect send to a sampler channel . . . . . 61
150 6.4.26. Removing an effect send from a sampler channel . . . 62
151 6.4.27. Getting amount of effect sends on a sampler channel . 63
152 6.4.28. Listing all effect sends on a sampler channel . . . . 63
153 6.4.29. Getting effect send information . . . . . . . . . . . 64
154 6.4.30. Altering effect send's audio routing . . . . . . . . 65
155 6.4.31. Altering effect send's MIDI controller . . . . . . . 66
156 6.4.32. Altering effect send's send level . . . . . . . . . . 67
157 6.4.33. Resetting a sampler channel . . . . . . . . . . . . . 68
158 6.5. Controlling connection . . . . . . . . . . . . . . . . . 68
159 6.5.1. Register front-end for receiving event messages . . . 68
160 6.5.2. Unregister front-end for not receiving event
161 messages . . . . . . . . . . . . . . . . . . . . . . 69
162 6.5.3. Enable or disable echo of commands . . . . . . . . . 70
163 6.5.4. Close client connection . . . . . . . . . . . . . . . 70
164
165
166
167 Schoenebeck Expires September 23, 2007 [Page 3]
168
169 Internet-Draft LinuxSampler Control Protocol March 2007
170
171
172 6.6. Global commands . . . . . . . . . . . . . . . . . . . . . 71
173 6.6.1. Current number of active voices . . . . . . . . . . . 71
174 6.6.2. Maximum amount of active voices . . . . . . . . . . . 71
175 6.6.3. Reset sampler . . . . . . . . . . . . . . . . . . . . 71
176 6.6.4. General sampler informations . . . . . . . . . . . . 72
177 6.6.5. Getting global volume attenuation . . . . . . . . . . 72
178 6.6.6. Setting global volume attenuation . . . . . . . . . . 73
179 6.7. MIDI Instrument Mapping . . . . . . . . . . . . . . . . . 73
180 6.7.1. Create a new MIDI instrument map . . . . . . . . . . 74
181 6.7.2. Delete one particular or all MIDI instrument maps . . 75
182 6.7.3. Get amount of existing MIDI instrument maps . . . . . 75
183 6.7.4. Getting all created MIDI instrument maps . . . . . . 76
184 6.7.5. Getting MIDI instrument map information . . . . . . . 76
185 6.7.6. Renaming a MIDI instrument map . . . . . . . . . . . 77
186 6.7.7. Create or replace a MIDI instrument map entry . . . . 77
187 6.7.8. Getting ammount of MIDI instrument map entries . . . 80
188 6.7.9. Getting indeces of all entries of a MIDI
189 instrument map . . . . . . . . . . . . . . . . . . . 81
190 6.7.10. Remove an entry from the MIDI instrument map . . . . 82
191 6.7.11. Get current settings of MIDI instrument map entry . . 82
192 6.7.12. Clear MIDI instrument map . . . . . . . . . . . . . . 84
193 7. Command Syntax . . . . . . . . . . . . . . . . . . . . . . . 85
194 8. Events . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
195 8.1. Number of audio output devices changed . . . . . . . . . 96
196 8.2. Audio output device's settings changed . . . . . . . . . 96
197 8.3. Number of MIDI input devices changed . . . . . . . . . . 96
198 8.4. MIDI input device's settings changed . . . . . . . . . . 97
199 8.5. Number of sampler channels changed . . . . . . . . . . . 97
200 8.6. Number of active voices changed . . . . . . . . . . . . . 97
201 8.7. Number of active disk streams changed . . . . . . . . . . 98
202 8.8. Disk stream buffer fill state changed . . . . . . . . . . 98
203 8.9. Channel information changed . . . . . . . . . . . . . . . 98
204 8.10. Number of effect sends changed . . . . . . . . . . . . . 99
205 8.11. Effect send information changed . . . . . . . . . . . . . 99
206 8.12. Total number of active voices changed . . . . . . . . . . 99
207 8.13. Number of MIDI instrument maps changed . . . . . . . . . 100
208 8.14. MIDI instrument map information changed . . . . . . . . . 100
209 8.15. Number of MIDI instruments changed . . . . . . . . . . . 100
210 8.16. MIDI instrument information changed . . . . . . . . . . . 101
211 8.17. Global settings changed . . . . . . . . . . . . . . . . . 101
212 8.18. Miscellaneous and debugging events . . . . . . . . . . . 102
213 9. Security Considerations . . . . . . . . . . . . . . . . . . . 103
214 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 104
215 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 105
216 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 106
217 Intellectual Property and Copyright Statements . . . . . . . . . 107
218
219
220
221
222
223 Schoenebeck Expires September 23, 2007 [Page 4]
224
225 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 5]
280
281 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 6]
336
337 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 7]
392
393 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 8]
448
449 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 9]
504
505 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 10]
560
561 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 11]
616
617 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 12]
672
673 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 13]
728
729 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 14]
784
785 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 15]
840
841 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 16]
896
897 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 17]
952
953 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 18]
1008
1009 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 19]
1064
1065 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 20]
1120
1121 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 21]
1176
1177 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 22]
1232
1233 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 23]
1288
1289 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 24]
1344
1345 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 25]
1400
1401 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 26]
1456
1457 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 27]
1512
1513 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 28]
1568
1569 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 29]
1624
1625 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 30]
1680
1681 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 31]
1736
1737 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 32]
1792
1793 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 33]
1848
1849 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 34]
1904
1905 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 35]
1960
1961 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 36]
2016
2017 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 37]
2072
2073 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 38]
2128
2129 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 39]
2184
2185 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 40]
2240
2241 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 41]
2296
2297 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 42]
2352
2353 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 43]
2408
2409 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 44]
2464
2465 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 45]
2520
2521 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 46]
2576
2577 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 47]
2632
2633 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 48]
2688
2689 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 49]
2744
2745 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 50]
2800
2801 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 51]
2856
2857 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 52]
2912
2913 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 53]
2968
2969 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 54]
3024
3025 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 55]
3080
3081 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 56]
3136
3137 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 57]
3192
3193 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 58]
3248
3249 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 59]
3304
3305 Internet-Draft LinuxSampler Control Protocol March 2007
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 September 23, 2007 [Page 60]
3360
3361 Internet-Draft LinuxSampler Control Protocol March 2007
3362
3363
3364 Examples:
3365
3366
3367
3368 6.4.25. Adding an effect send to a sampler channel
3369
3370 The front-end can create an additional effect send on a specific
3371 sampler channel by sending the following command:
3372
3373 CREATE FX_SEND <sampler-channel> <midi-ctrl> [<name>]
3374
3375 Where <sampler-channel> is the respective sampler channel number as
3376 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3377 (Section 6.4.4) command, that is the sampler channel on which the
3378 effect send should be created on, <midi-ctrl> is a number between
3379 0..127 defining the MIDI controller which can alter the effect send
3380 level and <name> is an optional argument defining a name for the
3381 effect send entity. The name does not have to be unique.
3382
3383 By default, that is as initial routing, the effect send's audio
3384 channels are automatically routed to the last audio channels of the
3385 sampler channel's audio output device, that way you can i.e. first
3386 increase the amount of audio channels on the audio output device for
3387 having dedicated effect send output channels and when "CREATE
3388 FX_SEND" is called, those channels will automatically be picked. You
3389 can alter the destination channels however with "SET FX_SEND
3390 AUDIO_OUTPUT_CHANNEL" (Section 6.4.30).
3391
3392 Note: Create effect sends on a sampler channel only when needed,
3393 because having effect sends on a sampler channel will decrease
3394 runtime performance, because for implementing channel effect sends,
3395 separate (sampler channel local) audio buffers are needed to render
3396 and mix the voices and route the audio signal afterwards to the
3397 master outputs and effect send outputs (along with their respective
3398 effect send levels). A sampler channel without effect sends however
3399 can mix its voices directly into the audio output devices's audio
3400 buffers and is thus faster.
3401
3402 Possible Answers:
3403
3404 "OK[<fx-send-id>]" -
3405
3406 in case a new effect send could be added to the sampler
3407 channel, where <fx-send-id> reflects the unique ID of the newly
3408 created effect send entity
3409
3410
3411
3412
3413
3414
3415 Schoenebeck Expires September 23, 2007 [Page 61]
3416
3417 Internet-Draft LinuxSampler Control Protocol March 2007
3418
3419
3420 "ERR:<error-code>:<error-message>" -
3421
3422 when a new effect send could not be added, i.e. due to invalid
3423 parameters
3424
3425 Examples:
3426
3427 C: "CREATE FX_SEND 0 91 'Reverb Send'"
3428
3429 S: "OK[0]"
3430
3431 C: "CREATE FX_SEND 0 93"
3432
3433 S: "OK[1]"
3434
3435 6.4.26. Removing an effect send from a sampler channel
3436
3437 The front-end can remove an existing effect send on a specific
3438 sampler channel by sending the following command:
3439
3440 DESTROY FX_SEND <sampler-channel> <fx-send-id>
3441
3442 Where <sampler-channel> is the respective sampler channel number as
3443 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3444 (Section 6.4.4) command, that is the sampler channel from which the
3445 effect send should be removed from and <fx-send-id> is the respective
3446 effect send number as returned by the "CREATE FX_SEND"
3447 (Section 6.4.25) or "LIST FX_SENDS" (Section 6.4.28) command.
3448
3449 Possible Answers:
3450
3451 "OK" -
3452
3453 on success
3454
3455 "ERR:<error-code>:<error-message>" -
3456
3457 in case it failed, providing an appropriate error code and
3458 error message
3459
3460 Example:
3461
3462 C: "DESTROY FX_SEND 0 0"
3463
3464 S: "OK"
3465
3466
3467
3468
3469
3470
3471 Schoenebeck Expires September 23, 2007 [Page 62]
3472
3473 Internet-Draft LinuxSampler Control Protocol March 2007
3474
3475
3476 6.4.27. Getting amount of effect sends on a sampler channel
3477
3478 The front-end can ask for the amount of effect sends on a specific
3479 sampler channel by sending the following command:
3480
3481 GET FX_SENDS <sampler-channel>
3482
3483 Where <sampler-channel> is the respective sampler channel number as
3484 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3485 (Section 6.4.4) command.
3486
3487 Possible Answers:
3488
3489 The sampler will answer by returning the number of effect sends on
3490 the given sampler channel.
3491
3492 Example:
3493
3494 C: "GET FX_SENDS 0"
3495
3496 S: "2"
3497
3498 6.4.28. Listing all effect sends on a sampler channel
3499
3500 The front-end can ask for a list of effect sends on a specific
3501 sampler channel by sending the following command:
3502
3503 LIST FX_SENDS <sampler-channel>
3504
3505 Where <sampler-channel> is the respective sampler channel number as
3506 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3507 (Section 6.4.4) command.
3508
3509 Possible Answers:
3510
3511 The sampler will answer by returning a comma separated list with
3512 all effect sends' numerical IDs on the given sampler channel.
3513
3514 Examples:
3515
3516 C: "LIST FX_SENDS 0"
3517
3518 S: "0,1"
3519
3520 C: "LIST FX_SENDS 1"
3521
3522 S: ""
3523
3524
3525
3526
3527 Schoenebeck Expires September 23, 2007 [Page 63]
3528
3529 Internet-Draft LinuxSampler Control Protocol March 2007
3530
3531
3532 6.4.29. Getting effect send information
3533
3534 The front-end can ask for the current settings of an effect send
3535 entity by sending the following command:
3536
3537 GET FX_SEND INFO <sampler-channel> <fx-send-id>
3538
3539 Where <sampler-channel> is the sampler channel number as returned by
3540 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3541 command and <fx-send-id> reflects the numerical ID of the effect send
3542 entity as returned by the "CREATE FX_SEND" (Section 6.4.25) or "LIST
3543 FX_SENDS" (Section 6.4.28) command.
3544
3545 Possible Answers:
3546
3547 The sampler will answer by sending a <CRLF> separated list. Each
3548 answer line begins with the settings category name followed by a
3549 colon and then a space character <SP> and finally the info
3550 character string to that setting category. At the moment the
3551 following categories are defined:
3552
3553
3554
3555 NAME -
3556
3557 name of the effect send entity
3558
3559 MIDI_CONTROLLER -
3560
3561 a value between 0 and 127 reflecting the MIDI controller
3562 which is able to modify the effect send's send level
3563
3564 LEVEL -
3565
3566 optionally dotted number reflecting the effect send's
3567 current send level (where a value < 1.0 means attenuation
3568 and a value > 1.0 means amplification)
3569
3570 AUDIO_OUTPUT_ROUTING -
3571
3572 comma separated list which reflects to which audio channel
3573 of the selected audio output device each effect send output
3574 channel is routed to, e.g. "0,3" would mean the effect
3575 send's output channel 0 is routed to channel 0 of the audio
3576 output device and the effect send's output channel 1 is
3577 routed to the channel 3 of the audio output device (see "SET
3578 FX_SEND AUDIO_OUTPUT_CHANNEL" (Section 6.4.30) for details)
3579
3580
3581
3582
3583 Schoenebeck Expires September 23, 2007 [Page 64]
3584
3585 Internet-Draft LinuxSampler Control Protocol March 2007
3586
3587
3588 The mentioned fields above don't have to be in particular order.
3589
3590 Example:
3591
3592 C: "GET FX_SEND INFO 0 0"
3593
3594 S: "NAME: Reverb Send"
3595
3596 "MIDI_CONTROLLER: 91"
3597
3598 "LEVEL: 0.3"
3599
3600 "AUDIO_OUTPUT_ROUTING: 2,3"
3601
3602 "."
3603
3604 6.4.30. Altering effect send's audio routing
3605
3606 The front-end can alter the destination of an effect send's audio
3607 channel on a specific sampler channel by sending the following
3608 command:
3609
3610 SET FX_SEND AUDIO_OUTPUT_CHANNEL <sampler-chan> <fx-send-id>
3611 <audio-src> <audio-dst>
3612
3613 Where <sampler-chan> is the sampler channel number as returned by the
3614 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3615 command, <fx-send-id> reflects the numerical ID of the effect send
3616 entity as returned by the "CREATE FX_SEND" (Section 6.4.25) or "LIST
3617 FX_SENDS" (Section 6.4.28) command, <audio-src> is the numerical ID
3618 of the effect send's audio channel which should be rerouted and
3619 <audio-dst> is the numerical ID of the audio channel of the selected
3620 audio output device where <audio-src> should be routed to.
3621
3622 Note that effect sends can only route audio to the same audio output
3623 device as assigned to the effect send's sampler channel. Also note
3624 that an effect send entity does always have exactly as much audio
3625 channels as its sampler channel. So if the sampler channel is
3626 stereo, the effect send does have two audio channels as well. Also
3627 keep in mind that the amount of audio channels on a sampler channel
3628 might be dependant not only to the deployed sampler engine on the
3629 sampler channel, but also dependant to the instrument currently
3630 loaded. However you can (effectively) turn an i.e. stereo effect
3631 send into a mono one by simply altering its audio routing
3632 appropriately.
3633
3634 Possible Answers:
3635
3636
3637
3638
3639 Schoenebeck Expires September 23, 2007 [Page 65]
3640
3641 Internet-Draft LinuxSampler Control Protocol March 2007
3642
3643
3644 "OK" -
3645
3646 on success
3647
3648 "WRN:<warning-code>:<warning-message>" -
3649
3650 if audio output channel was set, but there are noteworthy
3651 issue(s) related, providing an appropriate warning code and
3652 warning message
3653
3654 "ERR:<error-code>:<error-message>" -
3655
3656 in case it failed, providing an appropriate error code and
3657 error message
3658
3659 Example:
3660
3661 C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2"
3662
3663 S: "OK"
3664
3665 6.4.31. Altering effect send's MIDI controller
3666
3667 The front-end can alter the MIDI controller of an effect send entity
3668 by sending the following command:
3669
3670 SET FX_SEND MIDI_CONTROLLER <sampler-chan> <fx-send-id> <midi-
3671 ctrl>
3672
3673 Where <sampler-chan> is the sampler channel number as returned by the
3674 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3675 command, <fx-send-id> reflects the numerical ID of the effect send
3676 entity as returned by the "CREATE FX_SEND" (Section 6.4.25) or "LIST
3677 FX_SENDS" (Section 6.4.28) command and <midi-ctrl> reflects the MIDI
3678 controller which shall be able to modify the effect send's send
3679 level.
3680
3681 Possible Answers:
3682
3683 "OK" -
3684
3685 on success
3686
3687 "WRN:<warning-code>:<warning-message>" -
3688
3689 if MIDI controller was set, but there are noteworthy issue(s)
3690 related, providing an appropriate warning code and warning
3691 message
3692
3693
3694
3695 Schoenebeck Expires September 23, 2007 [Page 66]
3696
3697 Internet-Draft LinuxSampler Control Protocol March 2007
3698
3699
3700 "ERR:<error-code>:<error-message>" -
3701
3702 in case it failed, providing an appropriate error code and
3703 error message
3704
3705 Example:
3706
3707 C: "SET FX_SEND MIDI_CONTROLLER 0 0 91"
3708
3709 S: "OK"
3710
3711 6.4.32. Altering effect send's send level
3712
3713 The front-end can alter the current send level of an effect send
3714 entity by sending the following command:
3715
3716 SET FX_SEND LEVEL <sampler-chan> <fx-send-id> <volume>
3717
3718 Where <sampler-chan> is the sampler channel number as returned by the
3719 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3720 command, <fx-send-id> reflects the numerical ID of the effect send
3721 entity as returned by the "CREATE FX_SEND" (Section 6.4.25) or "LIST
3722 FX_SENDS" (Section 6.4.28) command and <volume> is an optionally
3723 dotted positive number (a value smaller than 1.0 means attenuation,
3724 whereas a value greater than 1.0 means amplification) reflecting the
3725 new send level.
3726
3727 Possible Answers:
3728
3729 "OK" -
3730
3731 on success
3732
3733 "WRN:<warning-code>:<warning-message>" -
3734
3735 if new send level was set, but there are noteworthy issue(s)
3736 related, providing an appropriate warning code and warning
3737 message
3738
3739 "ERR:<error-code>:<error-message>" -
3740
3741 in case it failed, providing an appropriate error code and
3742 error message
3743
3744 Example:
3745
3746
3747
3748
3749
3750
3751 Schoenebeck Expires September 23, 2007 [Page 67]
3752
3753 Internet-Draft LinuxSampler Control Protocol March 2007
3754
3755
3756 C: "SET FX_SEND LEVEL 0 0 0.15"
3757
3758 S: "OK"
3759
3760 6.4.33. Resetting a sampler channel
3761
3762 The front-end can reset a particular sampler channel by sending the
3763 following command:
3764
3765 RESET CHANNEL <sampler-channel>
3766
3767 Where <sampler-channel> defines the sampler channel to be reset.
3768 This will cause the engine on that sampler channel, its voices and
3769 eventually disk streams and all control and status variables to be
3770 reset.
3771
3772 Possible Answers:
3773
3774 "OK" -
3775
3776 on success
3777
3778 "WRN:<warning-code>:<warning-message>" -
3779
3780 if channel was reset, but there are noteworthy issue(s)
3781 related, providing an appropriate warning code and warning
3782 message
3783
3784 "ERR:<error-code>:<error-message>" -
3785
3786 in case it failed, providing an appropriate error code and
3787 error message
3788
3789 Examples:
3790
3791
3792
3793 6.5. Controlling connection
3794
3795 The following commands are used to control the connection to
3796 LinuxSampler.
3797
3798 6.5.1. Register front-end for receiving event messages
3799
3800 The front-end can register itself to the LinuxSampler application to
3801 be informed about noteworthy events by sending this command:
3802
3803
3804
3805
3806
3807 Schoenebeck Expires September 23, 2007 [Page 68]
3808
3809 Internet-Draft LinuxSampler Control Protocol March 2007
3810
3811
3812 SUBSCRIBE <event-id>
3813
3814 where <event-id> will be replaced by the respective event that client
3815 wants to subscribe to.
3816
3817 Possible Answers:
3818
3819 "OK" -
3820
3821 on success
3822
3823 "WRN:<warning-code>:<warning-message>" -
3824
3825 if registration succeeded, but there are noteworthy issue(s)
3826 related, providing an appropriate warning code and warning
3827 message
3828
3829 "ERR:<error-code>:<error-message>" -
3830
3831 in case it failed, providing an appropriate error code and
3832 error message
3833
3834 Examples:
3835
3836
3837
3838 6.5.2. Unregister front-end for not receiving event messages
3839
3840 The front-end can unregister itself if it doesn't want to receive
3841 event messages anymore by sending the following command:
3842
3843 UNSUBSCRIBE <event-id>
3844
3845 Where <event-id> will be replaced by the respective event that client
3846 doesn't want to receive anymore.
3847
3848 Possible Answers:
3849
3850 "OK" -
3851
3852 on success
3853
3854 "WRN:<warning-code>:<warning-message>" -
3855
3856 if unregistration succeeded, but there are noteworthy issue(s)
3857 related, providing an appropriate warning code and warning
3858 message
3859
3860
3861
3862
3863 Schoenebeck Expires September 23, 2007 [Page 69]
3864
3865 Internet-Draft LinuxSampler Control Protocol March 2007
3866
3867
3868 "ERR:<error-code>:<error-message>" -
3869
3870 in case it failed, providing an appropriate error code and
3871 error message
3872
3873 Examples:
3874
3875
3876
3877 6.5.3. Enable or disable echo of commands
3878
3879 To enable or disable back sending of commands to the client the
3880 following command can be used:
3881
3882 SET ECHO <value>
3883
3884 Where <value> should be replaced either by "1" to enable echo mode or
3885 "0" to disable echo mode. When echo mode is enabled, all commands
3886 send to LinuxSampler will be immediately send back and after this
3887 echo the actual response to the command will be returned. Echo mode
3888 will only be altered for the client connection that issued the "SET
3889 ECHO" command, not globally for all client connections.
3890
3891 Possible Answers:
3892
3893 "OK" -
3894
3895 usually
3896
3897 "ERR:<error-code>:<error-message>" -
3898
3899 on syntax error, e.g. non boolean value
3900
3901 Examples:
3902
3903
3904
3905 6.5.4. Close client connection
3906
3907 The client can close its network connection to LinuxSampler by
3908 sending the following command:
3909
3910 QUIT
3911
3912 This is probably more interesting for manual telnet connections to
3913 LinuxSampler than really useful for a front-end implementation.
3914
3915
3916
3917
3918
3919 Schoenebeck Expires September 23, 2007 [Page 70]
3920
3921 Internet-Draft LinuxSampler Control Protocol March 2007
3922
3923
3924 6.6. Global commands
3925
3926 The following commands have global impact on the sampler.
3927
3928 6.6.1. Current number of active voices
3929
3930 The front-end can ask for the current number of active voices on the
3931 sampler by sending the following command:
3932
3933 GET TOTAL_VOICE_COUNT
3934
3935 Possible Answers:
3936
3937 LinuxSampler will answer by returning the number of all active
3938 voices on the sampler.
3939
3940 6.6.2. Maximum amount of active voices
3941
3942 The front-end can ask for the maximum number of active voices by
3943 sending the following command:
3944
3945 GET TOTAL_VOICE_COUNT_MAX
3946
3947 Possible Answers:
3948
3949 LinuxSampler will answer by returning the maximum number of active
3950 voices.
3951
3952 6.6.3. Reset sampler
3953
3954 The front-end can reset the whole sampler by sending the following
3955 command:
3956
3957 RESET
3958
3959 Possible Answers:
3960
3961 "OK" -
3962
3963 always
3964
3965 Examples:
3966
3967
3968
3969
3970
3971
3972
3973
3974
3975 Schoenebeck Expires September 23, 2007 [Page 71]
3976
3977 Internet-Draft LinuxSampler Control Protocol March 2007
3978
3979
3980 6.6.4. General sampler informations
3981
3982 The client can ask for general informations about the LinuxSampler
3983 instance by sending the following command:
3984
3985 GET SERVER INFO
3986
3987 Possible Answers:
3988
3989 LinuxSampler will answer by sending a <CRLF> separated list. Each
3990 answer line begins with the information category name followed by
3991 a colon and then a space character <SP> and finally the info
3992 character string to that information category. At the moment the
3993 following categories are defined:
3994
3995
3996
3997 DESCRIPTION -
3998
3999 arbitrary textual description about the sampler
4000
4001 VERSION -
4002
4003 version of the sampler
4004
4005 PROTOCOL_VERSION -
4006
4007 version of the LSCP specification the sampler complies with
4008 (see Section 2 for details)
4009
4010 The mentioned fields above don't have to be in particular order.
4011 Other fields might be added in future.
4012
4013 6.6.5. Getting global volume attenuation
4014
4015 The client can ask for the current global sampler-wide volume
4016 attenuation by sending the following command:
4017
4018 GET VOLUME
4019
4020 Possible Answers:
4021
4022 The sampler will always answer by returning the optional dotted
4023 floating point coefficient, reflecting the current global volume
4024 attenuation.
4025
4026 Note: it is up to the respective sampler engine whether to obey that
4027 global volume parameter or not, but in general all engines SHOULD use
4028
4029
4030
4031 Schoenebeck Expires September 23, 2007 [Page 72]
4032
4033 Internet-Draft LinuxSampler Control Protocol March 2007
4034
4035
4036 this parameter.
4037
4038 6.6.6. Setting global volume attenuation
4039
4040 The client can alter the current global sampler-wide volume
4041 attenuation by sending the following command:
4042
4043 SET VOLUME <volume>
4044
4045 Where <volume> should be replaced by the optional dotted floating
4046 point value, reflecting the new global volume parameter. This value
4047 might usually be in the range between 0.0 and 1.0, that is for
4048 attenuating the overall volume.
4049
4050 Possible Answers:
4051
4052 "OK" -
4053
4054 on success
4055
4056 "WRN:<warning-code>:<warning-message>" -
4057
4058 if the global volume was set, but there are noteworthy issue(s)
4059 related, providing an appropriate warning code and warning
4060 message
4061
4062 "ERR:<error-code>:<error-message>" -
4063
4064 in case it failed, providing an appropriate error code and
4065 error message
4066
4067 6.7. MIDI Instrument Mapping
4068
4069 The MIDI protocol provides a way to switch between instruments by
4070 sending so called MIDI bank select and MIDI program change messages
4071 which are essentially just numbers. The following commands allow to
4072 actually map arbitrary MIDI bank select / program change numbers with
4073 real instruments.
4074
4075 The sampler allows to manage an arbitrary amount of MIDI instrument
4076 maps which define which instrument to load on which MIDI program
4077 change message.
4078
4079 By default, that is when the sampler is launched, there is no map,
4080 thus the sampler will simply ignore all program change messages. The
4081 front-end has to explicitly create at least one map, add entries to
4082 the map and tell the respective sampler channel(s) which MIDI
4083 instrument map to use, so the sampler knows how to react on a given
4084
4085
4086
4087 Schoenebeck Expires September 23, 2007 [Page 73]
4088
4089 Internet-Draft LinuxSampler Control Protocol March 2007
4090
4091
4092 program change message on the respective sampler channel, that is by
4093 switching to the respectively defined engine type and loading the
4094 respective instrument. See command "SET CHANNEL MIDI_INSTRUMENT_MAP"
4095 (Section 6.4.24) for how to assign a MIDI instrument map to a sampler
4096 channel.
4097
4098 Also note per MIDI specification a bank select message does not cause
4099 to switch to another instrument. Instead when receiving a bank
4100 select message the bank value will be stored and a subsequent program
4101 change message (which may occur at any time) will finally cause the
4102 sampler to switch to the respective instrument as reflected by the
4103 current MIDI instrument map.
4104
4105 6.7.1. Create a new MIDI instrument map
4106
4107 The front-end can add a new MIDI instrument map by sending the
4108 following command:
4109
4110 ADD MIDI_INSTRUMENT_MAP [<name>]
4111
4112 Where <name> is an optional argument allowing to assign a custom name
4113 to the new map. MIDI instrument Map names do not have to be unique.
4114
4115 Possible Answers:
4116
4117 "OK[<map>]" -
4118
4119 in case a new MIDI instrument map could be added, where <map>
4120 reflects the unique ID of the newly created MIDI instrument map
4121
4122 "ERR:<error-code>:<error-message>" -
4123
4124 when a new map could not be created, which might never occur in
4125 practice
4126
4127 Examples:
4128
4129 C: "ADD MIDI_INSTRUMENT_MAP 'Standard Map'"
4130
4131 S: "OK[0]"
4132
4133 C: "ADD MIDI_INSTRUMENT_MAP 'Standard Drumkit'"
4134
4135 S: "OK[1]"
4136
4137 C: "ADD MIDI_INSTRUMENT_MAP"
4138
4139
4140
4141
4142
4143 Schoenebeck Expires September 23, 2007 [Page 74]
4144
4145 Internet-Draft LinuxSampler Control Protocol March 2007
4146
4147
4148 S: "OK[5]"
4149
4150 6.7.2. Delete one particular or all MIDI instrument maps
4151
4152 The front-end can delete a particular MIDI instrument map by sending
4153 the following command:
4154
4155 REMOVE MIDI_INSTRUMENT_MAP <map>
4156
4157 Where <map> reflects the unique ID of the map to delete as returned
4158 by the "LIST MIDI_INSTRUMENT_MAPS" (Section 6.7.4) command.
4159
4160 The front-end can delete all MIDI instrument maps by sending the
4161 following command:
4162
4163 REMOVE MIDI_INSTRUMENT_MAP ALL
4164
4165 Possible Answers:
4166
4167 "OK" -
4168
4169 in case the map(s) could be deleted
4170
4171 "ERR:<error-code>:<error-message>" -
4172
4173 when the given map does not exist
4174
4175 Examples:
4176
4177 C: "REMOVE MIDI_INSTRUMENT_MAP 0"
4178
4179 S: "OK"
4180
4181 C: "REMOVE MIDI_INSTRUMENT_MAP ALL"
4182
4183 S: "OK"
4184
4185 6.7.3. Get amount of existing MIDI instrument maps
4186
4187 The front-end can retrieve the current amount of MIDI instrument maps
4188 by sending the following command:
4189
4190 GET MIDI_INSTRUMENT_MAPS
4191
4192 Possible Answers:
4193
4194
4195
4196
4197
4198
4199 Schoenebeck Expires September 23, 2007 [Page 75]
4200
4201 Internet-Draft LinuxSampler Control Protocol March 2007
4202
4203
4204 The sampler will answer by returning the current number of MIDI
4205 instrument maps.
4206
4207 Example:
4208
4209 C: "GET MIDI_INSTRUMENT_MAPS"
4210
4211 S: "2"
4212
4213 6.7.4. Getting all created MIDI instrument maps
4214
4215 The number of MIDI instrument maps can change on runtime. To get the
4216 current list of MIDI instrument maps, the front-end can send the
4217 following command:
4218
4219 LIST MIDI_INSTRUMENT_MAPS
4220
4221 Possible Answers:
4222
4223 The sampler will answer by returning a comma separated list with
4224 all MIDI instrument maps' numerical IDs.
4225
4226 Example:
4227
4228 C: "LIST MIDI_INSTRUMENT_MAPS"
4229
4230 S: "0,1,5,12"
4231
4232 6.7.5. Getting MIDI instrument map information
4233
4234 The front-end can ask for the current settings of a MIDI instrument
4235 map by sending the following command:
4236
4237 GET MIDI_INSTRUMENT_MAP INFO <map>
4238
4239 Where <map> is the numerical ID of the map the front-end is
4240 interested in as returned by the "LIST MIDI_INSTRUMENT_MAPS"
4241 (Section 6.7.4) command.
4242
4243 Possible Answers:
4244
4245 LinuxSampler will answer by sending a <CRLF> separated list. Each
4246 answer line begins with the settings category name followed by a
4247 colon and then a space character <SP> and finally the info
4248 character string to that setting category. At the moment the
4249 following categories are defined:
4250
4251
4252
4253
4254
4255 Schoenebeck Expires September 23, 2007 [Page 76]
4256
4257 Internet-Draft LinuxSampler Control Protocol March 2007
4258
4259
4260
4261
4262 NAME -
4263
4264 custom name of the given map, which does not have to be
4265 unique
4266
4267 The mentioned fields above don't have to be in particular order.
4268
4269 Example:
4270
4271 C: "GET MIDI_INSTRUMENT_MAP INFO 0"
4272
4273 S: "NAME: Standard Map"
4274
4275 "."
4276
4277 6.7.6. Renaming a MIDI instrument map
4278
4279 The front-end can alter the custom name of a MIDI instrument map by
4280 sending the following command:
4281
4282 SET MIDI_INSTRUMENT_MAP NAME <map> <name>
4283
4284 Where <map> is the numerical ID of the map and <name> the new custom
4285 name of the map, which does not have to be unique.
4286
4287 Possible Answers:
4288
4289 "OK" -
4290
4291 on success
4292
4293 "ERR:<error-code>:<error-message>" -
4294
4295 in case the given map does not exist
4296
4297 Example:
4298
4299 C: "SET MIDI_INSTRUMENT_MAP NAME 0 'Foo instruments'"
4300
4301 S: "OK"
4302
4303 6.7.7. Create or replace a MIDI instrument map entry
4304
4305 The front-end can create a new or replace an existing entry in a
4306 sampler's MIDI instrument map by sending the following command:
4307
4308
4309
4310
4311 Schoenebeck Expires September 23, 2007 [Page 77]
4312
4313 Internet-Draft LinuxSampler Control Protocol March 2007
4314
4315
4316 MAP MIDI_INSTRUMENT [NON_MODAL] <map> <midi_bank> <midi_prog>
4317 <engine_name> <filename> <instrument_index> <volume_value>
4318 [<instr_load_mode>] [<name>]
4319
4320 Where <map> is the numeric ID of the map to alter, <midi_bank> is an
4321 integer value between 0..16383 reflecting the MIDI bank select index,
4322 <midi_prog> an integer value between 0..127 reflecting the MIDI
4323 program change index, <engine_name> a sampler engine name as returned
4324 by the "LIST AVAILABLE_ENGINES" (Section 6.4.8) command (not
4325 encapsulated into apostrophes), <filename> the name of the
4326 instrument's file to be deployed (encapsulated into apostrophes),
4327 <instrument_index> the index (integer value) of the instrument within
4328 the given file, <volume_value> reflects the master volume of the
4329 instrument as optionally dotted number (where a value < 1.0 means
4330 attenuation and a value > 1.0 means amplification). This parameter
4331 easily allows to adjust the volume of all intruments within a custom
4332 instrument map without having to adjust their instrument files. The
4333 OPTIONAL <instr_load_mode> argument defines the life time of the
4334 instrument, that is when the instrument should be loaded, when freed
4335 and has exactly the following possibilities:
4336
4337 "ON_DEMAND" -
4338
4339 The instrument will be loaded when needed, that is when
4340 demanded by at least one sampler channel. It will immediately
4341 be freed from memory when not needed by any sampler channel
4342 anymore.
4343
4344 "ON_DEMAND_HOLD" -
4345
4346 The instrument will be loaded when needed, that is when
4347 demanded by at least one sampler channel. It will be kept in
4348 memory even when not needed by any sampler channel anymore.
4349 Instruments with this mode are only freed when the sampler is
4350 reset or all mapping entries with this mode (and respective
4351 instrument) are explicitly changed to "ON_DEMAND" and no
4352 sampler channel is using the instrument anymore.
4353
4354 "PERSISTENT" -
4355
4356 The instrument will immediately be loaded into memory when this
4357 mapping command is sent and the instrument is kept all the
4358 time. Instruments with this mode are only freed when the
4359 sampler is reset or all mapping entries with this mode (and
4360 respective instrument) are explicitly changed to "ON_DEMAND"
4361 and no sampler channel is using the instrument anymore.
4362
4363
4364
4365
4366
4367 Schoenebeck Expires September 23, 2007 [Page 78]
4368
4369 Internet-Draft LinuxSampler Control Protocol March 2007
4370
4371
4372 not supplied -
4373
4374 In case there is no <instr_load_mode> argument given, it will
4375 be up to the InstrumentManager to decide which mode to use.
4376 Usually it will use "ON_DEMAND" if an entry for the given
4377 instrument does not exist in the InstrumentManager's list yet,
4378 otherwise if an entry already exists, it will simply stick with
4379 the mode currently reflected by the already existing entry,
4380 that is it will not change the mode.
4381
4382 The <instr_load_mode> argument thus allows to define an appropriate
4383 strategy (low memory consumption vs. fast instrument switching) for
4384 each instrument individually. Note, the following restrictions apply
4385 to this argument: "ON_DEMAND_HOLD" and "PERSISTENT" have to be
4386 supported by the respective sampler engine (which is technically the
4387 case when the engine provides an InstrumentManager for its format).
4388 If this is not the case the argument will automatically fall back to
4389 the default value "ON_DEMAND". Also the load mode of one instrument
4390 may automatically change the laod mode of other instrument(s), i.e.
4391 because the instruments are part of the same file and the engine does
4392 not allow a way to manage load modes for them individually. Due to
4393 this, in case the frontend shows the load modes of entries, the
4394 frontend should retrieve the actual mode by i.e. sending "GET
4395 MIDI_INSTRUMENT INFO" (Section 6.7.11) command(s). Finally the
4396 OPTIONAL <name> argument allows to set a custom name (encapsulated
4397 into apostrophes) for the mapping entry, useful for frontends for
4398 displaying an appropriate name for mapped instruments (using "GET
4399 MIDI_INSTRUMENT INFO" (Section 6.7.11)).
4400
4401 By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is
4402 completely established in the sampler. The OPTIONAL "NON_MODAL"
4403 argument however causes the respective "MAP MIDI_INSTRUMENT" command
4404 to return immediately, that is to let the sampler establish the
4405 mapping in the background. So this argument might be especially
4406 useful for mappings with a "PERSISTENT" type, because these have to
4407 load the respective instruments immediately and might thus block for
4408 a very long time. It is recommended however to use the OPTIONAL
4409 "NON_MODAL" argument only if really necessary, because it has the
4410 following drawbacks: as "NON_MODAL" instructions return immediately,
4411 they may not necessarily return an error i.e. when the given
4412 instrument file turns out to be corrupt, beside that subsequent
4413 commands in a LSCP instruction sequence might fail, because mandatory
4414 mappings are not yet completed.
4415
4416 Possible Answers:
4417
4418
4419
4420
4421
4422
4423 Schoenebeck Expires September 23, 2007 [Page 79]
4424
4425 Internet-Draft LinuxSampler Control Protocol March 2007
4426
4427
4428 "OK" -
4429
4430 usually
4431
4432 "ERR:<error-code>:<error-message>" -
4433
4434 when the given map or engine does not exist or a value is out
4435 of range
4436
4437 Examples:
4438
4439 C: "MAP MIDI_INSTRUMENT 0 3 0 gig '/usr/share/Steinway D.gig' 0
4440 0.8 PERSISTENT"
4441
4442 S: "OK"
4443
4444 C: "MAP MIDI_INSTRUMENT 0 4 50 gig '/home/john/foostrings.gig' 7
4445 1.0"
4446
4447 S: "OK"
4448
4449 C: "MAP MIDI_INSTRUMENT 0 0 0 gig '/usr/share/piano.gig' 0 1.0
4450 'Normal Piano'"
4451
4452 S: "OK"
4453
4454 C: "MAP MIDI_INSTRUMENT 0 1 0 gig '/usr/share/piano.gig' 0 0.25
4455 'Silent Piano'"
4456
4457 S: "OK"
4458
4459 C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/
4460 foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"
4461
4462 S: "OK"
4463
4464 6.7.8. Getting ammount of MIDI instrument map entries
4465
4466 The front-end can query the amount of currently existing entries in a
4467 MIDI instrument map by sending the following command:
4468
4469 GET MIDI_INSTRUMENTS <map>
4470
4471 The front-end can query the amount of currently existing entries in
4472 all MIDI instrument maps by sending the following command:
4473
4474
4475
4476
4477
4478
4479 Schoenebeck Expires September 23, 2007 [Page 80]
4480
4481 Internet-Draft LinuxSampler Control Protocol March 2007
4482
4483
4484 GET MIDI_INSTRUMENTS ALL
4485
4486 Possible Answers:
4487
4488 The sampler will answer by sending the current number of entries
4489 in the MIDI instrument map(s).
4490
4491 Example:
4492
4493 C: "GET MIDI_INSTRUMENTS 0"
4494
4495 S: "234"
4496
4497 C: "GET MIDI_INSTRUMENTS ALL"
4498
4499 S: "954"
4500
4501 6.7.9. Getting indeces of all entries of a MIDI instrument map
4502
4503 The front-end can query a list of all currently existing entries in a
4504 certain MIDI instrument map by sending the following command:
4505
4506 LIST MIDI_INSTRUMENTS <map>
4507
4508 Where <map> is the numeric ID of the MIDI instrument map.
4509
4510 The front-end can query a list of all currently existing entries of
4511 all MIDI instrument maps by sending the following command:
4512
4513 LIST MIDI_INSTRUMENTS ALL
4514
4515 Possible Answers:
4516
4517 The sampler will answer by sending a comma separated list of map
4518 ID - MIDI bank - MIDI program triples, where each triple is
4519 encapsulated into curly braces. The list is returned in one
4520 single line. Each triple just reflects the key of the respective
4521 map entry, thus subsequent "GET MIDI_INSTRUMENT INFO"
4522 (Section 6.7.11) command(s) are necessary to retrieve detailed
4523 informations about each entry.
4524
4525 Example:
4526
4527 C: "LIST MIDI_INSTRUMENTS 0"
4528
4529 S: "{0,0,0},{0,0,1},{0,0,3},{0,1,4},{1,127,127}"
4530
4531
4532
4533
4534
4535 Schoenebeck Expires September 23, 2007 [Page 81]
4536
4537 Internet-Draft LinuxSampler Control Protocol March 2007
4538
4539
4540 6.7.10. Remove an entry from the MIDI instrument map
4541
4542 The front-end can delete an entry from a MIDI instrument map by
4543 sending the following command:
4544
4545 UNMAP MIDI_INSTRUMENT <map> <midi_bank> <midi_prog>
4546
4547 Where <map> is the numeric ID of the MIDI instrument map, <midi_bank>
4548 is an integer value between 0..16383 reflecting the MIDI bank value
4549 and <midi_prog> an integer value between 0..127 reflecting the MIDI
4550 program value of the map's entrie's key index triple.
4551
4552 Possible Answers:
4553
4554 "OK" -
4555
4556 usually
4557
4558 "ERR:<error-code>:<error-message>" -
4559
4560 when index out of bounds
4561
4562 Example:
4563
4564 C: "UNMAP MIDI_INSTRUMENT 0 2 127"
4565
4566 S: "OK"
4567
4568 6.7.11. Get current settings of MIDI instrument map entry
4569
4570 The front-end can retrieve the current settings of a certain
4571 instrument map entry by sending the following command:
4572
4573 GET MIDI_INSTRUMENT INFO <map> <midi_bank> <midi_prog>
4574
4575 Where <map> is the numeric ID of the MIDI instrument map, <midi_bank>
4576 is an integer value between 0..16383 reflecting the MIDI bank value,
4577 <midi_bank> and <midi_prog> an integer value between 0..127
4578 reflecting the MIDI program value of the map's entrie's key index
4579 triple.
4580
4581 Possible Answers:
4582
4583 LinuxSampler will answer by sending a <CRLF> separated list. Each
4584 answer line begins with the information category name followed by
4585 a colon and then a space character <SP> and finally the info
4586 character string to that info category. At the moment the
4587 following categories are defined:
4588
4589
4590
4591 Schoenebeck Expires September 23, 2007 [Page 82]
4592
4593 Internet-Draft LinuxSampler Control Protocol March 2007
4594
4595
4596 "NAME" -
4597
4598 Name for this MIDI instrument map entry (if defined). This
4599 name shall be used by frontends for displaying a name for this
4600 mapped instrument. It can be set and changed with the "MAP
4601 MIDI_INSTRUMENT" (Section 6.7.7) command and does not have to
4602 be unique.
4603
4604 "ENGINE_NAME" -
4605
4606 Name of the engine to be deployed for this instrument.
4607
4608 "INSTRUMENT_FILE" -
4609
4610 File name of the instrument.
4611
4612 "INSTRUMENT_NR" -
4613
4614 Index of the instrument within the file.
4615
4616 "INSTRUMENT_NAME" -
4617
4618 Name of the loaded instrument as reflected by its file. In
4619 contrast to the "NAME" field, the "INSTRUMENT_NAME" field
4620 cannot be changed.
4621
4622 "LOAD_MODE" -
4623
4624 Life time of instrument (see "MAP MIDI_INSTRUMENT"
4625 (Section 6.7.7) for details about this setting).
4626
4627 "VOLUME" -
4628
4629 master volume of the instrument as optionally dotted number
4630 (where a value < 1.0 means attenuation and a value > 1.0 means
4631 amplification)
4632
4633 The mentioned fields above don't have to be in particular order.
4634
4635 Example:
4636
4637 C: "GET MIDI_INSTRUMENT INFO 1 45 120"
4638
4639 S: "NAME: Drums for Foo Song"
4640
4641 "ENGINE_NAME: GigEngine"
4642
4643
4644
4645
4646
4647 Schoenebeck Expires September 23, 2007 [Page 83]
4648
4649 Internet-Draft LinuxSampler Control Protocol March 2007
4650
4651
4652 "INSTRUMENT_FILE: /usr/share/joesdrumkit.gig"
4653
4654 "INSTRUMENT_NR: 0"
4655
4656 "INSTRUMENT_NAME: Joe's Drumkit"
4657
4658 "LOAD_MODE: PERSISTENT"
4659
4660 "VOLUME: 1.0"
4661
4662 "."
4663
4664 6.7.12. Clear MIDI instrument map
4665
4666 The front-end can clear a whole MIDI instrument map, that is delete
4667 all its entries by sending the following command:
4668
4669 CLEAR MIDI_INSTRUMENTS <map>
4670
4671 Where <map> is the numeric ID of the map to clear.
4672
4673 The front-end can clear all MIDI instrument maps, that is delete all
4674 entries of all maps by sending the following command:
4675
4676 CLEAR MIDI_INSTRUMENTS ALL
4677
4678 The command "CLEAR MIDI_INSTRUMENTS ALL" does not delete the maps,
4679 only their entries, thus the map's settings like custom name will be
4680 preservevd.
4681
4682 Possible Answers:
4683
4684 "OK" -
4685
4686 always
4687
4688 Examples:
4689
4690 C: "CLEAR MIDI_INSTRUMENTS 0"
4691
4692 S: "OK"
4693
4694 C: "CLEAR MIDI_INSTRUMENTS ALL"
4695
4696 S: "OK"
4697
4698
4699
4700
4701
4702
4703 Schoenebeck Expires September 23, 2007 [Page 84]
4704
4705 Internet-Draft LinuxSampler Control Protocol March 2007
4706
4707
4708 7. Command Syntax
4709
4710 The grammar of the control protocol as descibed in Section 6 is
4711 defined below using Backus-Naur Form (BNF as described in [RFC2234])
4712 where applicable.
4713
4714 input =
4715
4716 line LF
4717
4718 / line CR LF
4719
4720 line =
4721
4722 /* epsilon (empty line ignored) */
4723
4724 / comment
4725
4726 / command
4727
4728 / error
4729
4730 comment =
4731
4732 '#'
4733
4734 / comment '#'
4735
4736 / comment SP
4737
4738 / comment number
4739
4740 / comment string
4741
4742 command =
4743
4744 ADD SP add_instruction
4745
4746 / MAP SP map_instruction
4747
4748 / UNMAP SP unmap_instruction
4749
4750 / GET SP get_instruction
4751
4752 / CREATE SP create_instruction
4753
4754 / DESTROY SP destroy_instruction
4755
4756
4757
4758
4759 Schoenebeck Expires September 23, 2007 [Page 85]
4760
4761 Internet-Draft LinuxSampler Control Protocol March 2007
4762
4763
4764 / LIST SP list_instruction
4765
4766 / LOAD SP load_instruction
4767
4768 / REMOVE SP remove_instruction
4769
4770 / SET SP set_instruction
4771
4772 / SUBSCRIBE SP subscribe_event
4773
4774 / UNSUBSCRIBE SP unsubscribe_event
4775
4776 / SELECT SP text
4777
4778 / RESET SP reset_instruction
4779
4780 / CLEAR SP clear_instruction
4781
4782 / RESET
4783
4784 / QUIT
4785
4786 add_instruction =
4787
4788 CHANNEL
4789
4790 / MIDI_INSTRUMENT_MAP
4791
4792 / MIDI_INSTRUMENT_MAP SP map_name
4793
4794 subscribe_event =
4795
4796 AUDIO_OUTPUT_DEVICE_COUNT
4797
4798 / AUDIO_OUTPUT_DEVICE_INFO
4799
4800 / MIDI_INPUT_DEVICE_COUNT
4801
4802 / MIDI_INPUT_DEVICE_INFO
4803
4804 / CHANNEL_COUNT
4805
4806 / VOICE_COUNT
4807
4808 / STREAM_COUNT
4809
4810 / BUFFER_FILL
4811
4812
4813
4814
4815 Schoenebeck Expires September 23, 2007 [Page 86]
4816
4817 Internet-Draft LinuxSampler Control Protocol March 2007
4818
4819
4820 / CHANNEL_INFO
4821
4822 / FX_SEND_COUNT
4823
4824 / FX_SEND_INFO
4825
4826 / MIDI_INSTRUMENT_MAP_COUNT
4827
4828 / MIDI_INSTRUMENT_MAP_INFO
4829
4830 / MIDI_INSTRUMENT_COUNT
4831
4832 / MIDI_INSTRUMENT_INFO
4833
4834 / MISCELLANEOUS
4835
4836 / TOTAL_VOICE_COUNT
4837
4838 / GLOBAL_INFO
4839
4840 unsubscribe_event =
4841
4842 AUDIO_OUTPUT_DEVICE_COUNT
4843
4844 / AUDIO_OUTPUT_DEVICE_INFO
4845
4846 / MIDI_INPUT_DEVICE_COUNT
4847
4848 / MIDI_INPUT_DEVICE_INFO
4849
4850 / CHANNEL_COUNT
4851
4852 / VOICE_COUNT
4853
4854 / STREAM_COUNT
4855
4856 / BUFFER_FILL
4857
4858 / CHANNEL_INFO
4859
4860 / FX_SEND_COUNT
4861
4862 / FX_SEND_INFO
4863
4864 / MIDI_INSTRUMENT_MAP_COUNT
4865
4866 / MIDI_INSTRUMENT_MAP_INFO
4867
4868
4869
4870
4871 Schoenebeck Expires September 23, 2007 [Page 87]
4872
4873 Internet-Draft LinuxSampler Control Protocol March 2007
4874
4875
4876 / MIDI_INSTRUMENT_COUNT
4877
4878 / MIDI_INSTRUMENT_INFO
4879
4880 / MISCELLANEOUS
4881
4882 / TOTAL_VOICE_COUNT
4883
4884 / GLOBAL_INFO
4885
4886 map_instruction =
4887
4888 MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP
4889 engine_name SP filename SP instrument_index SP volume_value
4890
4891 / MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog
4892 SP engine_name SP filename SP instrument_index SP volume_value SP
4893 instr_load_mode
4894
4895 / MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog
4896 SP engine_name SP filename SP instrument_index SP volume_value SP
4897 entry_name
4898
4899 / MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog
4900 SP engine_name SP filename SP instrument_index SP volume_value SP
4901 instr_load_mode SP entry_name
4902
4903 unmap_instruction =
4904
4905 MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog
4906
4907 remove_instruction =
4908
4909 CHANNEL SP sampler_channel
4910
4911 / MIDI_INSTRUMENT_MAP SP midi_map
4912
4913 / MIDI_INSTRUMENT_MAP SP ALL
4914
4915 get_instruction =
4916
4917 AVAILABLE_ENGINES
4918
4919 / AVAILABLE_MIDI_INPUT_DRIVERS
4920
4921 / MIDI_INPUT_DRIVER SP INFO SP string
4922
4923
4924
4925
4926
4927 Schoenebeck Expires September 23, 2007 [Page 88]
4928
4929 Internet-Draft LinuxSampler Control Protocol March 2007
4930
4931
4932 / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
4933
4934 / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP
4935 key_val_list
4936
4937 / AVAILABLE_AUDIO_OUTPUT_DRIVERS
4938
4939 / AUDIO_OUTPUT_DRIVER SP INFO SP string
4940
4941 / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
4942
4943 / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP
4944 key_val_list
4945
4946 / AUDIO_OUTPUT_DEVICES
4947
4948 / MIDI_INPUT_DEVICES
4949
4950 / AUDIO_OUTPUT_DEVICE SP INFO SP number
4951
4952 / MIDI_INPUT_DEVICE SP INFO SP number
4953
4954 / MIDI_INPUT_PORT SP INFO SP number SP number
4955
4956 / MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
4957
4958 / AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
4959
4960 / AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP
4961 string
4962
4963 / CHANNELS
4964
4965 / CHANNEL SP INFO SP sampler_channel
4966
4967 / CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
4968
4969 / CHANNEL SP STREAM_COUNT SP sampler_channel
4970
4971 / CHANNEL SP VOICE_COUNT SP sampler_channel
4972
4973 / ENGINE SP INFO SP engine_name
4974
4975 / SERVER SP INFO
4976
4977 / TOTAL_VOICE_COUNT
4978
4979
4980
4981
4982
4983 Schoenebeck Expires September 23, 2007 [Page 89]
4984
4985 Internet-Draft LinuxSampler Control Protocol March 2007
4986
4987
4988 / TOTAL_VOICE_COUNT_MAX
4989
4990 / MIDI_INSTRUMENTS SP midi_map
4991
4992 / MIDI_INSTRUMENTS SP ALL
4993
4994 / MIDI_INSTRUMENT SP INFO SP midi_map SP midi_bank SP midi_prog
4995
4996 / MIDI_INSTRUMENT_MAPS
4997
4998 / MIDI_INSTRUMENT_MAP SP INFO SP midi_map
4999
5000 / FX_SENDS SP sampler_channel
5001
5002 / FX_SEND SP INFO SP sampler_channel SP fx_send_id
5003
5004 / VOLUME
5005
5006 set_instruction =
5007
5008 AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '='
5009 param_val_list
5010
5011 / AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '='
5012 param_val_list
5013
5014 / MIDI_INPUT_DEVICE_PARAMETER SP number SP string '='
5015 param_val_list
5016
5017 / MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '='
5018 param_val_list
5019
5020 / CHANNEL SP set_chan_instruction
5021
5022 / MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
5023
5024 / FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id
5025 SP audio_channel_index SP audio_channel_index
5026
5027 / FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP
5028 midi_ctrl
5029
5030 / FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP
5031 volume_value
5032
5033 / ECHO SP boolean
5034
5035
5036
5037
5038
5039 Schoenebeck Expires September 23, 2007 [Page 90]
5040
5041 Internet-Draft LinuxSampler Control Protocol March 2007
5042
5043
5044 / VOLUME SP volume_value
5045
5046 create_instruction =
5047
5048 AUDIO_OUTPUT_DEVICE SP string SP key_val_list
5049
5050 / AUDIO_OUTPUT_DEVICE SP string
5051
5052 / MIDI_INPUT_DEVICE SP string SP key_val_list
5053
5054 / MIDI_INPUT_DEVICE SP string
5055
5056 / FX_SEND SP sampler_channel SP midi_ctrl
5057
5058 / FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name
5059
5060 reset_instruction =
5061
5062 CHANNEL SP sampler_channel
5063
5064 clear_instruction =
5065
5066 MIDI_INSTRUMENTS SP midi_map
5067
5068 / MIDI_INSTRUMENTS SP ALL
5069
5070 destroy_instruction =
5071
5072 AUDIO_OUTPUT_DEVICE SP number
5073
5074 / MIDI_INPUT_DEVICE SP number
5075
5076 / FX_SEND SP sampler_channel SP fx_send_id
5077
5078 load_instruction =
5079
5080 INSTRUMENT SP load_instr_args
5081
5082 / ENGINE SP load_engine_args
5083
5084 set_chan_instruction =
5085
5086 AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
5087
5088 / AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index
5089 SP audio_channel_index
5090
5091
5092
5093
5094
5095 Schoenebeck Expires September 23, 2007 [Page 91]
5096
5097 Internet-Draft LinuxSampler Control Protocol March 2007
5098
5099
5100 / AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
5101
5102 / MIDI_INPUT SP sampler_channel SP device_index SP
5103 midi_input_port_index SP midi_input_channel_index
5104
5105 / MIDI_INPUT_DEVICE SP sampler_channel SP device_index
5106
5107 / MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
5108
5109 / MIDI_INPUT_CHANNEL SP sampler_channel SP
5110 midi_input_channel_index
5111
5112 / MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
5113
5114 / VOLUME SP sampler_channel SP volume_value
5115
5116 / MUTE SP sampler_channel SP boolean
5117
5118 / SOLO SP sampler_channel SP boolean
5119
5120 / MIDI_INSTRUMENT_MAP SP sampler_channel SP midi_map
5121
5122 / MIDI_INSTRUMENT_MAP SP sampler_channel SP NONE
5123
5124 / MIDI_INSTRUMENT_MAP SP sampler_channel SP DEFAULT
5125
5126 modal_arg =
5127
5128 /* epsilon (empty argument) */
5129
5130 / NON_MODAL SP
5131
5132 key_val_list =
5133
5134 string '=' param_val_list
5135
5136 / key_val_list SP string '=' param_val_list
5137
5138 buffer_size_type =
5139
5140 BYTES
5141
5142 / PERCENTAGE
5143
5144 list_instruction =
5145
5146 AUDIO_OUTPUT_DEVICES
5147
5148
5149
5150
5151 Schoenebeck Expires September 23, 2007 [Page 92]
5152
5153 Internet-Draft LinuxSampler Control Protocol March 2007
5154
5155
5156 / MIDI_INPUT_DEVICES
5157
5158 / CHANNELS
5159
5160 / AVAILABLE_ENGINES
5161
5162 / AVAILABLE_MIDI_INPUT_DRIVERS
5163
5164 / AVAILABLE_AUDIO_OUTPUT_DRIVERS
5165
5166 / MIDI_INSTRUMENTS SP midi_map
5167
5168 / MIDI_INSTRUMENTS SP ALL
5169
5170 / MIDI_INSTRUMENT_MAPS
5171
5172 / FX_SENDS SP sampler_channel
5173
5174 load_instr_args =
5175
5176 filename SP instrument_index SP sampler_channel
5177
5178 / NON_MODAL SP filename SP instrument_index SP sampler_channel
5179
5180 load_engine_args =
5181
5182 engine_name SP sampler_channel
5183
5184 instr_load_mode =
5185
5186 ON_DEMAND
5187
5188 / ON_DEMAND_HOLD
5189
5190 / PERSISTENT
5191
5192 device_index =
5193
5194 number
5195
5196 audio_channel_index =
5197
5198 number
5199
5200 audio_output_type_name =
5201
5202 string
5203
5204
5205
5206
5207 Schoenebeck Expires September 23, 2007 [Page 93]
5208
5209 Internet-Draft LinuxSampler Control Protocol March 2007
5210
5211
5212 midi_input_port_index =
5213
5214 number
5215
5216 midi_input_channel_index =
5217
5218 number
5219
5220 / ALL
5221
5222 midi_input_type_name =
5223
5224 string
5225
5226 midi_map =
5227
5228 number
5229
5230 midi_bank =
5231
5232 number
5233
5234 midi_prog =
5235
5236 number
5237
5238 midi_ctrl =
5239
5240 number
5241
5242 volume_value =
5243
5244 dotnum
5245
5246 / number
5247
5248 sampler_channel =
5249
5250 number
5251
5252 instrument_index =
5253
5254 number
5255
5256 fx_send_id =
5257
5258 number
5259
5260
5261
5262
5263 Schoenebeck Expires September 23, 2007 [Page 94]
5264
5265 Internet-Draft LinuxSampler Control Protocol March 2007
5266
5267
5268 engine_name =
5269
5270 string
5271
5272 filename =
5273
5274 stringval
5275
5276 map_name =
5277
5278 stringval
5279
5280 entry_name =
5281
5282 stringval
5283
5284 fx_send_name =
5285
5286 stringval
5287
5288 param_val_list =
5289
5290 param_val
5291
5292 / param_val_list','param_val
5293
5294 param_val =
5295
5296 string
5297
5298 / stringval
5299
5300 / number
5301
5302 / dotnum
5303
5304
5305
5306
5307
5308
5309
5310
5311
5312
5313
5314
5315
5316
5317
5318
5319 Schoenebeck Expires September 23, 2007 [Page 95]
5320
5321 Internet-Draft LinuxSampler Control Protocol March 2007
5322
5323
5324 8. Events
5325
5326 This chapter will describe all currently defined events supported by
5327 LinuxSampler.
5328
5329 8.1. Number of audio output devices changed
5330
5331 Client may want to be notified when the total number of audio output
5332 devices on the back-end changes by issuing the following command:
5333
5334 SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT
5335
5336 Server will start sending the following notification messages:
5337
5338 "NOTIFY:AUDIO_OUTPUT_DEVICE_COUNT:<devices>"
5339
5340 where <devices> will be replaced by the new number of audio output
5341 devices.
5342
5343 8.2. Audio output device's settings changed
5344
5345 Client may want to be notified when changes were made to audio output
5346 devices on the back-end by issuing the following command:
5347
5348 SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO
5349
5350 Server will start sending the following notification messages:
5351
5352 "NOTIFY:AUDIO_OUTPUT_DEVICE_INFO:<device-id>"
5353
5354 where <device-id> will be replaced by the numerical ID of the audio
5355 output device, which settings has been changed. The front-end will
5356 have to send the respective command to actually get the audio output
5357 device info. Because these messages will be triggered by LSCP
5358 commands issued by other clients rather than real time events
5359 happening on the server, it is believed that an empty notification
5360 message is sufficient here.
5361
5362 8.3. Number of MIDI input devices changed
5363
5364 Client may want to be notified when the total number of MIDI input
5365 devices on the back-end changes by issuing the following command:
5366
5367 SUBSCRIBE MIDI_INPUT_DEVICE_COUNT
5368
5369 Server will start sending the following notification messages:
5370
5371
5372
5373
5374
5375 Schoenebeck Expires September 23, 2007 [Page 96]
5376
5377 Internet-Draft LinuxSampler Control Protocol March 2007
5378
5379
5380 "NOTIFY:MIDI_INPUT_DEVICE_COUNT:<devices>"
5381
5382 where <devices> will be replaced by the new number of MIDI input
5383 devices.
5384
5385 8.4. MIDI input device's settings changed
5386
5387 Client may want to be notified when changes were made to MIDI input
5388 devices on the back-end by issuing the following command:
5389
5390 SUBSCRIBE MIDI_INPUT_DEVICE_INFO
5391
5392 Server will start sending the following notification messages:
5393
5394 "NOTIFY:MIDI_INPUT_DEVICE_INFO:<device-id>"
5395
5396 where <device-id> will be replaced by the numerical ID of the MIDI
5397 input device, which settings has been changed. The front-end will
5398 have to send the respective command to actually get the MIDI input
5399 device info. Because these messages will be triggered by LSCP
5400 commands issued by other clients rather than real time events
5401 happening on the server, it is believed that an empty notification
5402 message is sufficient here.
5403
5404 8.5. Number of sampler channels changed
5405
5406 Client may want to be notified when the total number of channels on
5407 the back-end changes by issuing the following command:
5408
5409 SUBSCRIBE CHANNEL_COUNT
5410
5411 Server will start sending the following notification messages:
5412
5413 "NOTIFY:CHANNEL_COUNT:<channels>"
5414
5415 where <channels> will be replaced by the new number of sampler
5416 channels.
5417
5418 8.6. Number of active voices changed
5419
5420 Client may want to be notified when the number of voices on the back-
5421 end changes by issuing the following command:
5422
5423 SUBSCRIBE VOICE_COUNT
5424
5425 Server will start sending the following notification messages:
5426
5427
5428
5429
5430
5431 Schoenebeck Expires September 23, 2007 [Page 97]
5432
5433 Internet-Draft LinuxSampler Control Protocol March 2007
5434
5435
5436 "NOTIFY:VOICE_COUNT:<sampler-channel> <voices>"
5437
5438 where <sampler-channel> will be replaced by the sampler channel the
5439 voice count change occurred and <voices> by the new number of active
5440 voices on that channel.
5441
5442 8.7. Number of active disk streams changed
5443
5444 Client may want to be notified when the number of streams on the
5445 back-end changes by issuing the following command: SUBSCRIBE
5446 STREAM_COUNT
5447
5448 SUBSCRIBE STREAM_COUNT
5449
5450 Server will start sending the following notification messages:
5451
5452 "NOTIFY:STREAM_COUNT:<sampler-channel> <streams>"
5453
5454 where <sampler-channel> will be replaced by the sampler channel the
5455 stream count change occurred and <streams> by the new number of
5456 active disk streams on that channel.
5457
5458 8.8. Disk stream buffer fill state changed
5459
5460 Client may want to be notified when the buffer fill state of a disk
5461 stream on the back-end changes by issuing the following command:
5462
5463 SUBSCRIBE BUFFER_FILL
5464
5465 Server will start sending the following notification messages:
5466
5467 "NOTIFY:BUFFER_FILL:<sampler-channel> <fill-data>"
5468
5469 where <sampler-channel> will be replaced by the sampler channel the
5470 buffer fill state change occurred on and <fill-data> will be replaced
5471 by the buffer fill data for this channel as described in
5472 Section 6.4.13 as if the "GET CHANNEL BUFFER_FILL PERCENTAGE"
5473 (Section 6.4.13) command was issued on this channel.
5474
5475 8.9. Channel information changed
5476
5477 Client may want to be notified when changes were made to sampler
5478 channels on the back-end by issuing the following command:
5479
5480 SUBSCRIBE CHANNEL_INFO
5481
5482 Server will start sending the following notification messages:
5483
5484
5485
5486
5487 Schoenebeck Expires September 23, 2007 [Page 98]
5488
5489 Internet-Draft LinuxSampler Control Protocol March 2007
5490
5491
5492 "NOTIFY:CHANNEL_INFO:<sampler-channel>"
5493
5494 where <sampler-channel> will be replaced by the sampler channel the
5495 channel info change occurred. The front-end will have to send the
5496 respective command to actually get the channel info. Because these
5497 messages will be triggered by LSCP commands issued by other clients
5498 rather than real time events happening on the server, it is believed
5499 that an empty notification message is sufficient here.
5500
5501 8.10. Number of effect sends changed
5502
5503 Client may want to be notified when the number of effect sends on a
5504 particular sampler channel is changed by issuing the following
5505 command:
5506
5507 SUBSCRIBE FX_SEND_COUNT
5508
5509 Server will start sending the following notification messages:
5510
5511 "NOTIFY:FX_SEND_COUNT:<channel-id> <fx-sends>"
5512
5513 where <channel-id> will be replaced by the numerical ID of the
5514 sampler channel, on which the effect sends number is changed and <fx-
5515 sends> will be replaced by the new number of effect sends on that
5516 channel.
5517
5518 8.11. Effect send information changed
5519
5520 Client may want to be notified when changes were made to effect sends
5521 on a a particular sampler channel by issuing the following command:
5522
5523 SUBSCRIBE FX_SEND_INFO
5524
5525 Server will start sending the following notification messages:
5526
5527 "NOTIFY:FX_SEND_INFO:<channel-id> <fx-send-id>"
5528
5529 where <channel-id> will be replaced by the numerical ID of the
5530 sampler channel, on which an effect send entity is changed and <fx-
5531 send-id> will be replaced by the numerical ID of the changed effect
5532 send.
5533
5534 8.12. Total number of active voices changed
5535
5536 Client may want to be notified when the total number of voices on the
5537 back-end changes by issuing the following command:
5538
5539
5540
5541
5542
5543 Schoenebeck Expires September 23, 2007 [Page 99]
5544
5545 Internet-Draft LinuxSampler Control Protocol March 2007
5546
5547
5548 SUBSCRIBE TOTAL_VOICE_COUNT
5549
5550 Server will start sending the following notification messages:
5551
5552 "NOTIFY:TOTAL_VOICE_COUNT:<voices>"
5553
5554 where <voices> will be replaced by the new number of all currently
5555 active voices.
5556
5557 8.13. Number of MIDI instrument maps changed
5558
5559 Client may want to be notified when the number of MIDI instrument
5560 maps on the back-end changes by issuing the following command:
5561
5562 SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT
5563
5564 Server will start sending the following notification messages:
5565
5566 "NOTIFY:MIDI_INSTRUMENT_MAP_COUNT:<maps>"
5567
5568 where <maps> will be replaced by the new number of MIDI instrument
5569 maps.
5570
5571 8.14. MIDI instrument map information changed
5572
5573 Client may want to be notified when changes were made to MIDI
5574 instrument maps on the back-end by issuing the following command:
5575
5576 SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO
5577
5578 Server will start sending the following notification messages:
5579
5580 "NOTIFY:MIDI_INSTRUMENT_MAP_INFO:<map-id>"
5581
5582 where <map-id> will be replaced by the numerical ID of the MIDI
5583 instrument map, for which information changes occurred. The front-
5584 end will have to send the respective command to actually get the MIDI
5585 instrument map info. Because these messages will be triggered by
5586 LSCP commands issued by other clients rather than real time events
5587 happening on the server, it is believed that an empty notification
5588 message is sufficient here.
5589
5590 8.15. Number of MIDI instruments changed
5591
5592 Client may want to be notified when the number of MIDI instrument
5593 maps on the back-end changes by issuing the following command:
5594
5595
5596
5597
5598
5599 Schoenebeck Expires September 23, 2007 [Page 100]
5600
5601 Internet-Draft LinuxSampler Control Protocol March 2007
5602
5603
5604 SUBSCRIBE MIDI_INSTRUMENT_COUNT
5605
5606 Server will start sending the following notification messages:
5607
5608 "NOTIFY:MIDI_INSTRUMENT_COUNT:<map-id> <instruments>"
5609
5610 where <map-id> is the numerical ID of the MIDI instrument map, in
5611 which the nuber of instruments has changed and <instruments> will be
5612 replaced by the new number of MIDI instruments in the specified map.
5613
5614 8.16. MIDI instrument information changed
5615
5616 Client may want to be notified when changes were made to MIDI
5617 instruments on the back-end by issuing the following command:
5618
5619 SUBSCRIBE MIDI_INSTRUMENT_INFO
5620
5621 Server will start sending the following notification messages:
5622
5623 "NOTIFY:MIDI_INSTRUMENT_INFO:<map-id> <bank> <program>"
5624
5625 where <map-id> will be replaced by the numerical ID of the MIDI
5626 instrument map, in which a MIDI instrument is changed. <bank> and
5627 <program> specifies the location of the changed MIDI instrument in
5628 the map. The front-end will have to send the respective command to
5629 actually get the MIDI instrument info. Because these messages will
5630 be triggered by LSCP commands issued by other clients rather than
5631 real time events happening on the server, it is believed that an
5632 empty notification message is sufficient here.
5633
5634 8.17. Global settings changed
5635
5636 Client may want to be notified when changes to the global settings of
5637 the sampler were made by issuing the following command:
5638
5639 SUBSCRIBE GLOBAL_INFO
5640
5641 Server will start sending the following types of notification
5642 messages:
5643
5644 "NOTIFY:GLOBAL_INFO:VOLUME <volume>" - Notifies that the golbal
5645 volume of the sampler is changed, where <volume> will be replaced
5646 by the optional dotted floating point value, reflecting the new
5647 global volume parameter.
5648
5649
5650
5651
5652
5653
5654
5655 Schoenebeck Expires September 23, 2007 [Page 101]
5656
5657 Internet-Draft LinuxSampler Control Protocol March 2007
5658
5659
5660 8.18. Miscellaneous and debugging events
5661
5662 Client may want to be notified of miscellaneous and debugging events
5663 occurring at the server by issuing the following command:
5664
5665 SUBSCRIBE MISCELLANEOUS
5666
5667 Server will start sending the following notification messages:
5668
5669 "NOTIFY:MISCELLANEOUS:<string>"
5670
5671 where <string> will be replaced by whatever data server wants to send
5672 to the client. Client MAY display this data to the user AS IS to
5673 facilitate debugging.
5674
5675
5676
5677
5678
5679
5680
5681
5682
5683
5684
5685
5686
5687
5688
5689
5690
5691
5692
5693
5694
5695
5696
5697
5698
5699
5700
5701
5702
5703
5704
5705
5706
5707
5708
5709
5710
5711 Schoenebeck Expires September 23, 2007 [Page 102]
5712
5713 Internet-Draft LinuxSampler Control Protocol March 2007
5714
5715
5716 9. Security Considerations
5717
5718 As there is so far no method of authentication and authorization
5719 defined and so not required for a client applications to succeed to
5720 connect, running LinuxSampler might be a security risk for the host
5721 system the LinuxSampler instance is running on.
5722
5723
5724
5725
5726
5727
5728
5729
5730
5731
5732
5733
5734
5735
5736
5737
5738
5739
5740
5741
5742
5743
5744
5745
5746
5747
5748
5749
5750
5751
5752
5753
5754
5755
5756
5757
5758
5759
5760
5761
5762
5763
5764
5765
5766
5767 Schoenebeck Expires September 23, 2007 [Page 103]
5768
5769 Internet-Draft LinuxSampler Control Protocol March 2007
5770
5771
5772 10. Acknowledgments
5773
5774 This document has benefited greatly from the comments of the
5775 following people, discussed on the LinuxSampler developer's mailing
5776 list:
5777
5778 Rui Nuno Capela
5779
5780 Vladimir Senkov
5781
5782 Mark Knecht
5783
5784 Grigor Iliev
5785
5786
5787
5788
5789
5790
5791
5792
5793
5794
5795
5796
5797
5798
5799
5800
5801
5802
5803
5804
5805
5806
5807
5808
5809
5810
5811
5812
5813
5814
5815
5816
5817
5818
5819
5820
5821
5822
5823 Schoenebeck Expires September 23, 2007 [Page 104]
5824
5825 Internet-Draft LinuxSampler Control Protocol March 2007
5826
5827
5828 11. References
5829
5830 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
5831 Requirement Levels", RFC 2119, 1997.
5832
5833 [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
5834 Specifications", RFC 2234, 1997.
5835
5836 [RFC793] Defense Advanced Research Projects Agency, "TRANSMISSION
5837 CONTROL PROTOCOL", RFC 793, 1981.
5838
5839
5840
5841
5842
5843
5844
5845
5846
5847
5848
5849
5850
5851
5852
5853
5854
5855
5856
5857
5858
5859
5860
5861
5862
5863
5864
5865
5866
5867
5868
5869
5870
5871
5872
5873
5874
5875
5876
5877
5878
5879 Schoenebeck Expires September 23, 2007 [Page 105]
5880
5881 Internet-Draft LinuxSampler Control Protocol March 2007
5882
5883
5884 Author's Address
5885
5886 C. Schoenebeck
5887 Interessengemeinschaft Software Engineering e. V.
5888 Max-Planck-Str. 39
5889 74081 Heilbronn
5890 Germany
5891
5892 Email: schoenebeck at software minus engineering dot org
5893
5894
5895
5896
5897
5898
5899
5900
5901
5902
5903
5904
5905
5906
5907
5908
5909
5910
5911
5912
5913
5914
5915
5916
5917
5918
5919
5920
5921
5922
5923
5924
5925
5926
5927
5928
5929
5930
5931
5932
5933
5934
5935 Schoenebeck Expires September 23, 2007 [Page 106]
5936
5937 Internet-Draft LinuxSampler Control Protocol March 2007
5938
5939
5940 Full Copyright Statement
5941
5942 Copyright (C) The IETF Trust (2007).
5943
5944 This document is subject to the rights, licenses and restrictions
5945 contained in BCP 78, and except as set forth therein, the authors
5946 retain all their rights.
5947
5948 This document and the information contained herein are provided on an
5949 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
5950 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
5951 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
5952 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
5953 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
5954 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
5955
5956
5957 Intellectual Property
5958
5959 The IETF takes no position regarding the validity or scope of any
5960 Intellectual Property Rights or other rights that might be claimed to
5961 pertain to the implementation or use of the technology described in
5962 this document or the extent to which any license under such rights
5963 might or might not be available; nor does it represent that it has
5964 made any independent effort to identify any such rights. Information
5965 on the procedures with respect to rights in RFC documents can be
5966 found in BCP 78 and BCP 79.
5967
5968 Copies of IPR disclosures made to the IETF Secretariat and any
5969 assurances of licenses to be made available, or the result of an
5970 attempt made to obtain a general license or permission for the use of
5971 such proprietary rights by implementers or users of this
5972 specification can be obtained from the IETF on-line IPR repository at
5973 http://www.ietf.org/ipr.
5974
5975 The IETF invites any interested party to bring to its attention any
5976 copyrights, patents or patent applications, or other proprietary
5977 rights that may cover technology that may be required to implement
5978 this standard. Please address the information to the IETF at
5979 ietf-ipr@ietf.org.
5980
5981
5982 Acknowledgment
5983
5984 Funding for the RFC Editor function is provided by the IETF
5985 Administrative Support Activity (IASA).
5986
5987
5988
5989
5990
5991 Schoenebeck Expires September 23, 2007 [Page 107]
5992

  ViewVC Help
Powered by ViewVC