/[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 1006 - (show annotations) (download)
Fri Dec 29 20:27:15 2006 UTC (17 years, 3 months ago) by schoenebeck
File MIME type: text/plain
File size: 162219 byte(s)
- added two new LSCP commands for altering global volume
  at runtime

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

  ViewVC Help
Powered by ViewVC