/[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 1002 - (show annotations) (download)
Wed Dec 27 16:23:46 2006 UTC (17 years, 3 months ago) by schoenebeck
File MIME type: text/plain
File size: 160527 byte(s)
- added new LSCP commands for managing FX sends

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

  ViewVC Help
Powered by ViewVC