/[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 945 - (show annotations) (download)
Sun Nov 26 16:39:49 2006 UTC (17 years, 4 months ago) by schoenebeck
File MIME type: text/plain
File size: 135374 byte(s)
- new LSCP draft (v1.2), added command set for
  MIDI instrument mapping

1
2
3
4 LinuxSampler Developers C. Schoenebeck
5 Internet-Draft Interessengemeinschaft Software
6 Expires: May 30, 2007 Engineering e. V.
7 November 26, 2006
8
9
10 LinuxSampler Control Protocol
11 LSCP 1.2
12
13 Status of this Memo
14
15 This document is an Internet-Draft and is in full conformance with
16 all provisions of Section 10 of RFC 2026.
17
18 Internet-Drafts are working documents of the Internet Engineering
19 Task Force (IETF), its areas, and its working groups. Note that
20 other groups may also distribute working documents as Internet-
21 Drafts.
22
23 Internet-Drafts are draft documents valid for a maximum of six months
24 and may be updated, replaced, or obsoleted by other documents at any
25 time. It is inappropriate to use Internet-Drafts as reference
26 material or to cite them other than as "work in progress."
27
28 The list of current Internet-Drafts can be accessed at
29 http://www.ietf.org/ietf/1id-abstracts.txt.
30
31 The list of Internet-Draft Shadow Directories can be accessed at
32 http://www.ietf.org/shadow.html.
33
34 This Internet-Draft will expire on May 30, 2007.
35
36 Copyright Notice
37
38 Copyright (C) The Internet Society (2006). All Rights Reserved.
39
40 Abstract
41
42 The LinuxSampler Control Protocol (LSCP) is an application-level
43 protocol primarily intended for local and remote controlling the
44 LinuxSampler backend application, which is a sophisticated server-
45 like console application essentially playing back audio samples and
46 manipulating the samples in real time to certain extent.
47
48
49
50
51
52
53
54
55 Schoenebeck Expires May 30, 2007 [Page 1]
56
57 Internet-Draft LinuxSampler Control Protocol November 2006
58
59
60 Table of Contents
61
62 1. Requirements notation . . . . . . . . . . . . . . . . . . . . 5
63 2. Versioning of this specification . . . . . . . . . . . . . . . 6
64 3. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 7
65 4. Focus of this protocol . . . . . . . . . . . . . . . . . . . . 8
66 5. Communication Overview . . . . . . . . . . . . . . . . . . . . 9
67 5.1. Request/response communication method . . . . . . . . . . 9
68 5.1.1. Result format . . . . . . . . . . . . . . . . . . . . 10
69 5.2. Subscribe/notify communication method . . . . . . . . . . 12
70 6. Description for control commands . . . . . . . . . . . . . . . 14
71 6.1. Ignored lines and comments . . . . . . . . . . . . . . . . 14
72 6.2. Configuring audio drivers . . . . . . . . . . . . . . . . 14
73 6.2.1. Getting amount of available audio output drivers . . . 14
74 6.2.2. Getting all available audio output drivers . . . . . . 15
75 6.2.3. Getting information about a specific audio output
76 driver . . . . . . . . . . . . . . . . . . . . . . . . 15
77 6.2.4. Getting information about specific audio output
78 driver parameter . . . . . . . . . . . . . . . . . . . 16
79 6.2.5. Creating an audio output device . . . . . . . . . . . 20
80 6.2.6. Destroying an audio output device . . . . . . . . . . 21
81 6.2.7. Getting all created audio output device count . . . . 22
82 6.2.8. Getting all created audio output device list . . . . . 22
83 6.2.9. Getting current settings of an audio output device . . 22
84 6.2.10. Changing settings of audio output devices . . . . . . 24
85 6.2.11. Getting information about an audio channel . . . . . . 24
86 6.2.12. Getting information about specific audio channel
87 parameter . . . . . . . . . . . . . . . . . . . . . . 26
88 6.2.13. Changing settings of audio output channels . . . . . . 28
89 6.3. Configuring MIDI input drivers . . . . . . . . . . . . . . 29
90 6.3.1. Getting amount of available MIDI input drivers . . . . 30
91 6.3.2. Getting all available MIDI input drivers . . . . . . . 30
92 6.3.3. Getting information about a specific MIDI input
93 driver . . . . . . . . . . . . . . . . . . . . . . . . 30
94 6.3.4. Getting information about specific MIDI input
95 driver parameter . . . . . . . . . . . . . . . . . . . 31
96 6.3.5. Creating a MIDI input device . . . . . . . . . . . . . 34
97 6.3.6. Destroying a MIDI input device . . . . . . . . . . . . 35
98 6.3.7. Getting all created MIDI input device count . . . . . 36
99 6.3.8. Getting all created MIDI input device list . . . . . . 36
100 6.3.9. Getting current settings of a MIDI input device . . . 36
101 6.3.10. Changing settings of MIDI input devices . . . . . . . 38
102 6.3.11. Getting information about a MIDI port . . . . . . . . 38
103 6.3.12. Getting information about specific MIDI port
104 parameter . . . . . . . . . . . . . . . . . . . . . . 39
105 6.3.13. Changing settings of MIDI input ports . . . . . . . . 41
106 6.4. Configuring sampler channels . . . . . . . . . . . . . . . 42
107 6.4.1. Loading an instrument . . . . . . . . . . . . . . . . 42
108
109
110
111 Schoenebeck Expires May 30, 2007 [Page 2]
112
113 Internet-Draft LinuxSampler Control Protocol November 2006
114
115
116 6.4.2. Loading a sampler engine . . . . . . . . . . . . . . . 43
117 6.4.3. Getting all created sampler channel count . . . . . . 44
118 6.4.4. Getting all created sampler channel list . . . . . . . 44
119 6.4.5. Adding a new sampler channel . . . . . . . . . . . . . 44
120 6.4.6. Removing a sampler channel . . . . . . . . . . . . . . 45
121 6.4.7. Getting amount of available engines . . . . . . . . . 46
122 6.4.8. Getting all available engines . . . . . . . . . . . . 46
123 6.4.9. Getting information about an engine . . . . . . . . . 47
124 6.4.10. Getting sampler channel information . . . . . . . . . 48
125 6.4.11. Current number of active voices . . . . . . . . . . . 51
126 6.4.12. Current number of active disk streams . . . . . . . . 51
127 6.4.13. Current fill state of disk stream buffers . . . . . . 51
128 6.4.14. Setting audio output device . . . . . . . . . . . . . 52
129 6.4.15. Setting audio output type . . . . . . . . . . . . . . 53
130 6.4.16. Setting audio output channel . . . . . . . . . . . . . 54
131 6.4.17. Setting MIDI input device . . . . . . . . . . . . . . 55
132 6.4.18. Setting MIDI input type . . . . . . . . . . . . . . . 55
133 6.4.19. Setting MIDI input port . . . . . . . . . . . . . . . 56
134 6.4.20. Setting MIDI input channel . . . . . . . . . . . . . . 57
135 6.4.21. Setting channel volume . . . . . . . . . . . . . . . . 57
136 6.4.22. Muting a sampler channel . . . . . . . . . . . . . . . 58
137 6.4.23. Soloing a sampler channel . . . . . . . . . . . . . . 59
138 6.4.24. Resetting a sampler channel . . . . . . . . . . . . . 59
139 6.5. Controlling connection . . . . . . . . . . . . . . . . . . 60
140 6.5.1. Register front-end for receiving event messages . . . 60
141 6.5.2. Unregister front-end for not receiving event
142 messages . . . . . . . . . . . . . . . . . . . . . . . 61
143 6.5.3. Enable or disable echo of commands . . . . . . . . . . 62
144 6.5.4. Close client connection . . . . . . . . . . . . . . . 62
145 6.6. Global commands . . . . . . . . . . . . . . . . . . . . . 62
146 6.6.1. Current number of active voices . . . . . . . . . . . 62
147 6.6.2. Maximum amount of active voices . . . . . . . . . . . 63
148 6.6.3. Reset sampler . . . . . . . . . . . . . . . . . . . . 63
149 6.6.4. General sampler informations . . . . . . . . . . . . . 63
150 6.7. MIDI Instrument Mapping . . . . . . . . . . . . . . . . . 64
151 6.7.1. Create or replace a MIDI instrument map entry . . . . 64
152 6.7.2. Getting ammount of MIDI instrument map entries . . . . 67
153 6.7.3. Getting indeces of all MIDI instrument map entries . . 67
154 6.7.4. Remove an entry from the MIDI instrument map . . . . . 68
155 6.7.5. Get current settings of MIDI instrument map entry . . 69
156 6.7.6. Clear MIDI instrument map . . . . . . . . . . . . . . 70
157 7. Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . 72
158 8. Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
159 8.1. Number of sampler channels changed . . . . . . . . . . . . 81
160 8.2. Number of active voices changed . . . . . . . . . . . . . 81
161 8.3. Number of active disk streams changed . . . . . . . . . . 81
162 8.4. Disk stream buffer fill state changed . . . . . . . . . . 82
163 8.5. Channel information changed . . . . . . . . . . . . . . . 82
164
165
166
167 Schoenebeck Expires May 30, 2007 [Page 3]
168
169 Internet-Draft LinuxSampler Control Protocol November 2006
170
171
172 8.6. Total number of active voices changed . . . . . . . . . . 82
173 8.7. Miscellaneous and debugging events . . . . . . . . . . . . 83
174 9. Security Considerations . . . . . . . . . . . . . . . . . . . 84
175 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 85
176 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 85
177 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 86
178 Intellectual Property and Copyright Statements . . . . . . . . . . 87
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223 Schoenebeck Expires May 30, 2007 [Page 4]
224
225 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 5]
280
281 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 6]
336
337 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 7]
392
393 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 8]
448
449 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 9]
504
505 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 10]
560
561 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 11]
616
617 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 12]
672
673 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 13]
728
729 Internet-Draft LinuxSampler Control Protocol November 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 6.2.1. Getting amount of available audio output drivers
778
779 Use the following command to get the number of audio output drivers
780
781
782
783 Schoenebeck Expires May 30, 2007 [Page 14]
784
785 Internet-Draft LinuxSampler Control Protocol November 2006
786
787
788 currently available for the LinuxSampler instance:
789
790 GET AVAILABLE_AUDIO_OUTPUT_DRIVERS
791
792 Possible Answers:
793
794 LinuxSampler will answer by sending the number of audio output
795 drivers.
796
797 Example:
798
799 C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
800
801 S: "2"
802
803 6.2.2. Getting all available audio output drivers
804
805 Use the following command to list all audio output drivers currently
806 available for the LinuxSampler instance:
807
808 LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS
809
810 Possible Answers:
811
812 LinuxSampler will answer by sending comma separated character
813 strings, each symbolizing an audio output driver.
814
815 Example:
816
817 C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"
818
819 S: "ALSA,JACK"
820
821 6.2.3. Getting information about a specific audio output driver
822
823 Use the following command to get detailed information about a
824 specific audio output driver:
825
826 GET AUDIO_OUTPUT_DRIVER INFO <audio-output-driver>
827
828 Where <audio-output-driver> is the name of the audio output driver,
829 returned by the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2)
830 command.
831
832 Possible Answers:
833
834
835
836
837
838
839 Schoenebeck Expires May 30, 2007 [Page 15]
840
841 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 16]
896
897 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 17]
952
953 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 18]
1008
1009 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 19]
1064
1065 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 20]
1120
1121 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 21]
1176
1177 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 22]
1232
1233 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 23]
1288
1289 Internet-Draft LinuxSampler Control Protocol November 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 6.2.11. Getting information about an audio channel
1337
1338 Use the following command to get information about an audio channel:
1339
1340
1341
1342
1343 Schoenebeck Expires May 30, 2007 [Page 24]
1344
1345 Internet-Draft LinuxSampler Control Protocol November 2006
1346
1347
1348 GET AUDIO_OUTPUT_CHANNEL INFO <device-id> <audio-chan>
1349
1350 Where <device-id> is the numerical ID of the audio output device as
1351 given by the "CREATE AUDIO_OUTPUT_DEVICE" (Section 6.2.5) or "LIST
1352 AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command and <audio-chan> the
1353 audio channel number.
1354
1355 Possible Answers:
1356
1357 LinuxSampler will answer by sending a <CRLF> separated list. Each
1358 answer line begins with the information category name followed by
1359 a colon and then a space character <SP> and finally the info
1360 character string to that info category. At the moment the
1361 following information categories are defined:
1362
1363
1364
1365 NAME -
1366
1367 arbitrary character string naming the channel, which doesn't
1368 have to be unique (always returned by all audio channels)
1369
1370 IS_MIX_CHANNEL -
1371
1372 either true or false, a mix-channel is not a real,
1373 independent audio channel, but a virtual channel which is
1374 mixed to another real channel, this mechanism is needed for
1375 sampler engines which need more audio channels than the used
1376 audio system might be able to offer (always returned by all
1377 audio channels)
1378
1379 MIX_CHANNEL_DESTINATION -
1380
1381 numerical ID (positive integer including 0) which reflects
1382 the real audio channel (of the same audio output device)
1383 this mix channel refers to, means where the audio signal
1384 actually will be routed / added to (only returned in case
1385 the audio channel is mix channel)
1386
1387 The mentioned fields above don't have to be in particular order. The
1388 fields above are only those fields which are generally returned for
1389 the described cases by all audio channels regardless of the audio
1390 driver. Every audio channel might have its own, additional driver
1391 and channel specific parameters.
1392
1393 Examples:
1394
1395
1396
1397
1398
1399 Schoenebeck Expires May 30, 2007 [Page 25]
1400
1401 Internet-Draft LinuxSampler Control Protocol November 2006
1402
1403
1404 C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 0"
1405
1406 S: "NAME: studio monitor left"
1407
1408 "IS_MIX_CHANNEL: false"
1409
1410 "."
1411
1412 C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 1"
1413
1414 S: "NAME: studio monitor right"
1415
1416 "IS_MIX_CHANNEL: false"
1417
1418 "."
1419
1420 C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"
1421
1422 S: "NAME: studio monitor left"
1423
1424 "IS_MIX_CHANNEL: true"
1425
1426 "MIX_CHANNEL_DESTINATION: 1"
1427
1428 "."
1429
1430 C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"
1431
1432 S: "NAME: 'ardour (left)'"
1433
1434 "IS_MIX_CHANNEL: false"
1435
1436 "JACK_BINDINGS: 'ardour:0'"
1437
1438 "."
1439
1440 6.2.12. Getting information about specific audio channel parameter
1441
1442 Use the following command to get detailed information about specific
1443 audio channel parameter:
1444
1445 GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO <dev-id> <chan> <param>
1446
1447 Where <dev-id> is the numerical ID of the audio output device as
1448 returned by the "CREATE AUDIO_OUTPUT_DEVICE" (Section 6.2.5) or "LIST
1449 AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command, <chan> the audio
1450 channel number and <param> a specific channel parameter name for
1451 which information should be obtained (as returned by the "GET
1452
1453
1454
1455 Schoenebeck Expires May 30, 2007 [Page 26]
1456
1457 Internet-Draft LinuxSampler Control Protocol November 2006
1458
1459
1460 AUDIO_OUTPUT_CHANNEL INFO" (Section 6.2.11) command).
1461
1462 Possible Answers:
1463
1464 LinuxSampler will answer by sending a <CRLF> separated list. Each
1465 answer line begins with the information category name followed by
1466 a colon and then a space character <SP> and finally the info
1467 character string to that info category. There are information
1468 which is always returned, independently of the given channel
1469 parameter and there is optional information which is only shown
1470 dependently to the given audio channel. At the moment the
1471 following information categories are defined:
1472
1473
1474
1475 TYPE -
1476
1477 either "BOOL" for boolean value(s) or "INT" for integer
1478 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1479 character string(s) (always returned)
1480
1481 DESCRIPTION -
1482
1483 arbitrary text describing the purpose of the parameter
1484 (always returned)
1485
1486 FIX -
1487
1488 either true or false, if true then this parameter is read
1489 only, thus cannot be altered (always returned)
1490
1491 MULTIPLICITY -
1492
1493 either true or false, defines if this parameter allows only
1494 one value or a list of values, where true means multiple
1495 values and false only a single value allowed (always
1496 returned)
1497
1498 RANGE_MIN -
1499
1500 defines lower limit of the allowed value range for this
1501 parameter, can be an integer value as well as a dotted
1502 number, usually used in conjunction with 'RANGE_MAX', but
1503 may also appear without (optionally returned, dependent to
1504 driver and channel parameter)
1505
1506
1507
1508
1509
1510
1511 Schoenebeck Expires May 30, 2007 [Page 27]
1512
1513 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 28]
1568
1569 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 29]
1624
1625 Internet-Draft LinuxSampler Control Protocol November 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 6.3.3. Getting information about a specific MIDI input driver
1673
1674 Use the following command to get detailed information about a
1675 specific MIDI input driver:
1676
1677
1678
1679 Schoenebeck Expires May 30, 2007 [Page 30]
1680
1681 Internet-Draft LinuxSampler Control Protocol November 2006
1682
1683
1684 GET MIDI_INPUT_DRIVER INFO <midi-input-driver>
1685
1686 Where <midi-input-driver> is the name of the MIDI input driver as
1687 returned by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2)
1688 command.
1689
1690 Possible Answers:
1691
1692 LinuxSampler will answer by sending a <CRLF> separated list. Each
1693 answer line begins with the information category name followed by
1694 a colon and then a space character <SP> and finally the info
1695 character string to that info category. At the moment the
1696 following information categories are defined:
1697
1698
1699
1700 DESCRIPTION -
1701
1702 arbitrary description text about the MIDI input driver
1703
1704 VERSION -
1705
1706 arbitrary character string regarding the driver's version
1707
1708 PARAMETERS -
1709
1710 comma separated list of all parameters available for the
1711 given MIDI input driver
1712
1713 The mentioned fields above don't have to be in particular order.
1714
1715 Example:
1716
1717 C: "GET MIDI_INPUT_DRIVER INFO ALSA"
1718
1719 S: "DESCRIPTION: Advanced Linux Sound Architecture"
1720
1721 "VERSION: 1.0"
1722
1723 "PARAMETERS: DRIVER,ACTIVE"
1724
1725 "."
1726
1727 6.3.4. Getting information about specific MIDI input driver parameter
1728
1729 Use the following command to get detailed information about a
1730 specific parameter of a specific MIDI input driver:
1731
1732
1733
1734
1735 Schoenebeck Expires May 30, 2007 [Page 31]
1736
1737 Internet-Draft LinuxSampler Control Protocol November 2006
1738
1739
1740 GET MIDI_INPUT_DRIVER_PARAMETER INFO <midit> <param> [<deplist>]
1741
1742 Where <midit> is the name of the MIDI input driver as returned by the
1743 "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2) command, <param>
1744 a specific parameter name for which information should be obtained
1745 (as returned by the "GET MIDI_INPUT_DRIVER INFO" (Section 6.3.3)
1746 command) and <deplist> is an optional list of parameters on which the
1747 sought parameter <param> depends on, <deplist> is a key-value pair
1748 list in form of "key1=val1 key2=val2 ...", where character string
1749 values are encapsulated into apostrophes ('). Arguments given with
1750 <deplist> which are not dependency parameters of <param> will be
1751 ignored, means the front-end application can simply put all
1752 parameters in <deplist> with the values selected by the user.
1753
1754 Possible Answers:
1755
1756 LinuxSampler will answer by sending a <CRLF> separated list. Each
1757 answer line begins with the information category name followed by a
1758 colon and then a space character <SP> and finally the info character
1759 string to that info category. There is information which is always
1760 returned, independent of the given driver parameter and there is
1761 optional information which is only shown dependent to given driver
1762 parameter. At the moment the following information categories are
1763 defined:
1764
1765 TYPE -
1766
1767 either "BOOL" for boolean value(s) or "INT" for integer
1768 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1769 character string(s) (always returned, no matter which driver
1770 parameter)
1771
1772 DESCRIPTION -
1773
1774 arbitrary text describing the purpose of the parameter (always
1775 returned, no matter which driver parameter)
1776
1777 MANDATORY -
1778
1779 either true or false, defines if this parameter must be given
1780 when the device is to be created with the 'CREATE
1781 MIDI_INPUT_DEVICE' (Section 6.3.5) command (always returned, no
1782 matter which driver parameter)
1783
1784 FIX -
1785
1786 either true or false, if false then this parameter can be
1787 changed at any time, once the device is created by the 'CREATE
1788
1789
1790
1791 Schoenebeck Expires May 30, 2007 [Page 32]
1792
1793 Internet-Draft LinuxSampler Control Protocol November 2006
1794
1795
1796 MIDI_INPUT_DEVICE' (Section 6.3.5) command (always returned, no
1797 matter which driver parameter)
1798
1799 MULTIPLICITY -
1800
1801 either true or false, defines if this parameter allows only one
1802 value or a list of values, where true means multiple values and
1803 false only a single value allowed (always returned, no matter
1804 which driver parameter)
1805
1806 DEPENDS -
1807
1808 comma separated list of parameters this parameter depends on,
1809 means the values for fields 'DEFAULT', 'RANGE_MIN', 'RANGE_MAX'
1810 and 'POSSIBILITIES' might depend on these listed parameters,
1811 for example assuming that an audio driver (like the ALSA
1812 driver) offers parameters 'card' and 'samplerate' then
1813 parameter 'samplerate' would depend on 'card' because the
1814 possible values for 'samplerate' depends on the sound card
1815 which can be chosen by the 'card' parameter (optionally
1816 returned, dependent to driver parameter)
1817
1818 DEFAULT -
1819
1820 reflects the default value for this parameter which is used
1821 when the device is created and not explicitly given with the
1822 'CREATE MIDI_INPUT_DEVICE' (Section 6.3.5) command, in case of
1823 MULTIPLCITY=true, this is a comma separated list, that's why
1824 character strings are encapsulated into apostrophes (')
1825 (optionally returned, dependent to driver parameter)
1826
1827 RANGE_MIN -
1828
1829 defines lower limit of the allowed value range for this
1830 parameter, can be an integer value as well as a dotted number,
1831 this parameter is often used in conjunction with RANGE_MAX, but
1832 may also appear without (optionally returned, dependent to
1833 driver parameter)
1834
1835 RANGE_MAX -
1836
1837 defines upper limit of the allowed value range for this
1838 parameter, can be an integer value as well as a dotted number,
1839 this parameter is often used in conjunction with RANGE_MIN, but
1840 may also appear without (optionally returned, dependent to
1841 driver parameter)
1842
1843
1844
1845
1846
1847 Schoenebeck Expires May 30, 2007 [Page 33]
1848
1849 Internet-Draft LinuxSampler Control Protocol November 2006
1850
1851
1852 POSSIBILITIES -
1853
1854 comma separated list of possible values for this parameter,
1855 character strings are encapsulated into apostrophes (optionally
1856 returned, dependent to driver parameter)
1857
1858 The mentioned fields above don't have to be in particular order.
1859
1860 Example:
1861
1862 C: "GET MIDI_INPUT_DRIVER_PARAMETER INFO ALSA ACTIVE"
1863
1864 S: "DESCRIPTION: Whether device is enabled"
1865
1866 "TYPE: BOOL"
1867
1868 "MANDATORY: false"
1869
1870 "FIX: false"
1871
1872 "MULTIPLICITY: false"
1873
1874 "DEFAULT: true"
1875
1876 "."
1877
1878 6.3.5. Creating a MIDI input device
1879
1880 Use the following command to create a new MIDI input device for the
1881 desired MIDI input system:
1882
1883 CREATE MIDI_INPUT_DEVICE <midi-input-driver> [<param-list>]
1884
1885 Where <midi-input-driver> should be replaced by the desired MIDI
1886 input system as returned by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
1887 (Section 6.3.2) command and <param-list> by an optional list of
1888 driver specific parameters in form of "key1=val1 key2=val2 ...",
1889 where character string values should be encapsulated into apostrophes
1890 ('). Note that there might be drivers which require parameter(s) to
1891 be given with this command. Use the previously described commands in
1892 this chapter to get that information.
1893
1894 Possible Answers:
1895
1896 "OK[<device-id>]" -
1897
1898 in case the device was successfully created, where <device-id>
1899 is the numerical ID of the new device
1900
1901
1902
1903 Schoenebeck Expires May 30, 2007 [Page 34]
1904
1905 Internet-Draft LinuxSampler Control Protocol November 2006
1906
1907
1908 "WRN[<device-id>]:<warning-code>:<warning-message>" -
1909
1910 in case the driver was loaded successfully, where <device-id>
1911 is the numerical ID of the new device, but there are noteworthy
1912 issue(s) related, providing an appropriate warning code and
1913 warning message
1914
1915 "ERR:<error-code>:<error-message>" -
1916
1917 in case it failed, providing an appropriate error code and
1918 error message
1919
1920 Example:
1921
1922 C: "CREATE MIDI_INPUT_DEVICE ALSA"
1923
1924 S: "OK[0]"
1925
1926 6.3.6. Destroying a MIDI input device
1927
1928 Use the following command to destroy a created MIDI input device:
1929
1930 DESTROY MIDI_INPUT_DEVICE <device-id>
1931
1932 Where <device-id> should be replaced by the device's numerical ID as
1933 returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
1934 MIDI_INPUT_DEVICES" (Section 6.3.8) command.
1935
1936 Possible Answers:
1937
1938 "OK" -
1939
1940 in case the device was successfully destroyed
1941
1942 "WRN:<warning-code>:<warning-message>" -
1943
1944 in case the device was destroyed, but there are noteworthy
1945 issue(s) related, providing an appropriate warning code and
1946 warning message
1947
1948 "ERR:<error-code>:<error-message>" -
1949
1950 in case it failed, providing an appropriate error code and
1951 error message
1952
1953 Example:
1954
1955
1956
1957
1958
1959 Schoenebeck Expires May 30, 2007 [Page 35]
1960
1961 Internet-Draft LinuxSampler Control Protocol November 2006
1962
1963
1964 C: "DESTROY MIDI_INPUT_DEVICE 0"
1965
1966 S: "OK"
1967
1968 6.3.7. Getting all created MIDI input device count
1969
1970 Use the following command to count all created MIDI input devices:
1971
1972 GET MIDI_INPUT_DEVICES
1973
1974 Possible Answers:
1975
1976 LinuxSampler will answer by sending the current number of all MIDI
1977 input devices.
1978
1979 Example:
1980
1981 C: "GET MIDI_INPUT_DEVICES"
1982
1983 S: "3"
1984
1985 6.3.8. Getting all created MIDI input device list
1986
1987 Use the following command to list all created MIDI input devices:
1988
1989 LIST MIDI_INPUT_DEVICES
1990
1991 Possible Answers:
1992
1993 LinuxSampler will answer by sending a comma separated list with
1994 the numerical Ids of all created MIDI input devices.
1995
1996 Examples:
1997
1998 C: "LIST MIDI_INPUT_DEVICES"
1999
2000 S: "0,1,2"
2001
2002 C: "LIST MIDI_INPUT_DEVICES"
2003
2004 S: "1,3"
2005
2006 6.3.9. Getting current settings of a MIDI input device
2007
2008 Use the following command to get current settings of a specific,
2009 created MIDI input device:
2010
2011
2012
2013
2014
2015 Schoenebeck Expires May 30, 2007 [Page 36]
2016
2017 Internet-Draft LinuxSampler Control Protocol November 2006
2018
2019
2020 GET MIDI_INPUT_DEVICE INFO <device-id>
2021
2022 Where <device-id> is the numerical ID of the MIDI input device as
2023 returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
2024 MIDI_INPUT_DEVICES" (Section 6.3.8) command.
2025
2026 Possible Answers:
2027
2028 LinuxSampler will answer by sending a <CRLF> separated list. Each
2029 answer line begins with the information category name followed by
2030 a colon and then a space character <SP> and finally the info
2031 character string to that info category. As some parameters might
2032 allow multiple values, character strings are encapsulated into
2033 apostrophes ('). At the moment the following information
2034 categories are defined (independent of driver):
2035
2036
2037
2038 DRIVER -
2039
2040 identifier of the used MIDI input driver, as e.g. returned
2041 by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2)
2042 command
2043
2044 ACTIVE -
2045
2046 either true or false, if false then the MIDI device is
2047 inactive and doesn't listen to any incoming MIDI events and
2048 thus doesn't forward them to connected sampler channels
2049
2050 The mentioned fields above don't have to be in particular order. The
2051 fields above are only those fields which are returned by all MIDI
2052 input devices. Every MIDI input driver might have its own,
2053 additional driver specific parameters (see "GET MIDI_INPUT_DRIVER
2054 INFO" (Section 6.3.3) command) which are also returned by this
2055 command.
2056
2057 Example:
2058
2059 C: "GET MIDI_INPUT_DEVICE INFO 0"
2060
2061 S: "DRIVER: ALSA"
2062
2063 "ACTIVE: true"
2064
2065 "."
2066
2067
2068
2069
2070
2071 Schoenebeck Expires May 30, 2007 [Page 37]
2072
2073 Internet-Draft LinuxSampler Control Protocol November 2006
2074
2075
2076 6.3.10. Changing settings of MIDI input devices
2077
2078 Use the following command to alter a specific setting of a created
2079 MIDI input device:
2080
2081 SET MIDI_INPUT_DEVICE_PARAMETER <device-id> <key>=<value>
2082
2083 Where <device-id> should be replaced by the numerical ID of the MIDI
2084 input device as returned by the "CREATE MIDI_INPUT_DEVICE"
2085 (Section 6.3.5) or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command,
2086 <key> by the name of the parameter to change and <value> by the new
2087 value for this parameter.
2088
2089 Possible Answers:
2090
2091 "OK" -
2092
2093 in case setting was successfully changed
2094
2095 "WRN:<warning-code>:<warning-message>" -
2096
2097 in case setting was changed successfully, but there are
2098 noteworthy issue(s) related, providing an appropriate warning
2099 code and warning message
2100
2101 "ERR:<error-code>:<error-message>" -
2102
2103 in case it failed, providing an appropriate error code and
2104 error message
2105
2106 Example:
2107
2108 C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"
2109
2110 S: "OK"
2111
2112 6.3.11. Getting information about a MIDI port
2113
2114 Use the following command to get information about a MIDI port:
2115
2116 GET MIDI_INPUT_PORT INFO <device-id> <midi-port>
2117
2118 Where <device-id> is the numerical ID of the MIDI input device as
2119 returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
2120 MIDI_INPUT_DEVICES" (Section 6.3.8) command and <midi-port> the MIDI
2121 input port number.
2122
2123 Possible Answers:
2124
2125
2126
2127 Schoenebeck Expires May 30, 2007 [Page 38]
2128
2129 Internet-Draft LinuxSampler Control Protocol November 2006
2130
2131
2132 LinuxSampler will answer by sending a <CRLF> separated list. Each
2133 answer line begins with the information category name followed by
2134 a colon and then a space character <SP> and finally the info
2135 character string to that info category. At the moment the
2136 following information categories are defined:
2137
2138 NAME -
2139
2140 arbitrary character string naming the port
2141
2142 The field above is only the one which is returned by all MIDI ports
2143 regardless of the MIDI driver and port. Every MIDI port might have
2144 its own, additional driver and port specific parameters.
2145
2146 Example:
2147
2148 C: "GET MIDI_INPUT_PORT INFO 0 0"
2149
2150 S: "NAME: 'Masterkeyboard'"
2151
2152 "ALSA_SEQ_BINDINGS: '64:0'"
2153
2154 "."
2155
2156 6.3.12. Getting information about specific MIDI port parameter
2157
2158 Use the following command to get detailed information about specific
2159 MIDI port parameter:
2160
2161 GET MIDI_INPUT_PORT_PARAMETER INFO <dev-id> <port> <param>
2162
2163 Where <dev-id> is the numerical ID of the MIDI input device as
2164 returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
2165 MIDI_INPUT_DEVICES" (Section 6.3.8) command, <port> the MIDI port
2166 number and <param> a specific port parameter name for which
2167 information should be obtained (as returned by the "GET
2168 MIDI_INPUT_PORT INFO" (Section 6.3.11) command).
2169
2170 Possible Answers:
2171
2172 LinuxSampler will answer by sending a <CRLF> separated list. Each
2173 answer line begins with the information category name followed by
2174 a colon and then a space character <SP> and finally the info
2175 character string to that info category. There is information
2176 which is always returned, independently of the given channel
2177 parameter and there is optional information which are only shown
2178 dependently to the given MIDI port. At the moment the following
2179 information categories are defined:
2180
2181
2182
2183 Schoenebeck Expires May 30, 2007 [Page 39]
2184
2185 Internet-Draft LinuxSampler Control Protocol November 2006
2186
2187
2188 TYPE -
2189
2190 either "BOOL" for boolean value(s) or "INT" for integer
2191 value(s) or "FLOAT" for dotted number(s) or "STRING" for
2192 character string(s) (always returned)
2193
2194 DESCRIPTION -
2195
2196 arbitrary text describing the purpose of the parameter (always
2197 returned)
2198
2199 FIX -
2200
2201 either true or false, if true then this parameter is read only,
2202 thus cannot be altered (always returned)
2203
2204 MULTIPLICITY -
2205
2206 either true or false, defines if this parameter allows only one
2207 value or a list of values, where true means multiple values and
2208 false only a single value allowed (always returned)
2209
2210 RANGE_MIN -
2211
2212 defines lower limit of the allowed value range for this
2213 parameter, can be an integer value as well as a dotted number,
2214 this parameter is usually used in conjunction with 'RANGE_MAX'
2215 but may also appear without (optionally returned, dependent to
2216 driver and port parameter)
2217
2218 RANGE_MAX -
2219
2220 defines upper limit of the allowed value range for this
2221 parameter, can be an integer value as well as a dotted number,
2222 this parameter is usually used in conjunction with 'RANGE_MIN'
2223 but may also appear without (optionally returned, dependent to
2224 driver and port parameter)
2225
2226 POSSIBILITIES -
2227
2228 comma separated list of possible values for this parameter,
2229 character strings are encapsulated into apostrophes (optionally
2230 returned, dependent to device and port parameter)
2231
2232 The mentioned fields above don't have to be in particular order.
2233
2234 Example:
2235
2236
2237
2238
2239 Schoenebeck Expires May 30, 2007 [Page 40]
2240
2241 Internet-Draft LinuxSampler Control Protocol November 2006
2242
2243
2244 C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"
2245
2246 S: "DESCRIPTION: bindings to other ALSA sequencer clients"
2247
2248 "TYPE: STRING"
2249
2250 "FIX: false"
2251
2252 "MULTIPLICITY: true"
2253
2254 "POSSIBILITIES: '64:0','68:0','68:1'"
2255
2256 "."
2257
2258 6.3.13. Changing settings of MIDI input ports
2259
2260 Use the following command to alter a specific setting of a MIDI input
2261 port:
2262
2263 SET MIDI_INPUT_PORT_PARAMETER <device-id> <port> <key>=<value>
2264
2265 Where <device-id> should be replaced by the numerical ID of the MIDI
2266 device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5)
2267 or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command, <port> by the
2268 MIDI port number, <key> by the name of the parameter to change and
2269 <value> by the new value for this parameter.
2270
2271 Possible Answers:
2272
2273 "OK" -
2274
2275 in case setting was successfully changed
2276
2277 "WRN:<warning-code>:<warning-message>" -
2278
2279 in case setting was changed successfully, but there are
2280 noteworthy issue(s) related, providing an appropriate warning
2281 code and warning message
2282
2283 "ERR:<error-code>:<error-message>" -
2284
2285 in case it failed, providing an appropriate error code and
2286 error message
2287
2288 Example:
2289
2290
2291
2292
2293
2294
2295 Schoenebeck Expires May 30, 2007 [Page 41]
2296
2297 Internet-Draft LinuxSampler Control Protocol November 2006
2298
2299
2300
2301
2302 6.4. Configuring sampler channels
2303
2304 The following commands describe how to add and remove sampler
2305 channels, associate a sampler channel with a sampler engine, load
2306 instruments and connect sampler channels to MIDI and audio devices.
2307
2308 6.4.1. Loading an instrument
2309
2310 An instrument file can be loaded and assigned to a sampler channel by
2311 one of the following commands:
2312
2313 LOAD INSTRUMENT [NON_MODAL] '<filename>' <instr-index> <sampler-
2314 channel>
2315
2316 Where <filename> is the name of the instrument file on the
2317 LinuxSampler instance's host system, <instr-index> the index of the
2318 instrument in the instrument file and <sampler-channel> is the number
2319 of the sampler channel the instrument should be assigned to. Each
2320 sampler channel can only have one instrument.
2321
2322 The difference between regular and NON_MODAL versions of the command
2323 is that the regular command returns OK only after the instrument has
2324 been fully loaded and the channel is ready to be used while NON_MODAL
2325 version returns immediately and a background process is launched to
2326 load the instrument on the channel. The GET CHANNEL INFO
2327 (Section 6.4.10) command can be used to obtain loading progress from
2328 INSTRUMENT_STATUS field. LOAD command will perform sanity checks
2329 such as making sure that the file could be read and it is of a proper
2330 format and SHOULD return ERR and SHOULD not launch the background
2331 process should any errors be detected at that point.
2332
2333 Possible Answers:
2334
2335 "OK" -
2336
2337 in case the instrument was successfully loaded
2338
2339 "WRN:<warning-code>:<warning-message>" -
2340
2341 in case the instrument was loaded successfully, but there are
2342 noteworthy issue(s) related (e.g. Engine doesn't support one
2343 or more patch parameters provided by the loaded instrument
2344 file), providing an appropriate warning code and warning
2345 message
2346
2347
2348
2349
2350
2351 Schoenebeck Expires May 30, 2007 [Page 42]
2352
2353 Internet-Draft LinuxSampler Control Protocol November 2006
2354
2355
2356 "ERR:<error-code>:<error-message>" -
2357
2358 in case it failed, providing an appropriate error code and
2359 error message
2360
2361 Example:
2362
2363
2364
2365 6.4.2. Loading a sampler engine
2366
2367 A sampler engine type can be associated to a specific sampler channel
2368 by the following command:
2369
2370 LOAD ENGINE <engine-name> <sampler-channel>
2371
2372 Where <engine-name> is an engine name as obtained by the "LIST
2373 AVAILABLE_ENGINES" (Section 6.4.8) command and <sampler-channel> the
2374 sampler channel as returned by the "ADD CHANNEL" (Section 6.4.5) or
2375 "LIST CHANNELS" (Section 6.4.4) command where the engine type should
2376 be assigned to. This command should be issued after adding a new
2377 sampler channel and before any other control commands on the new
2378 sampler channel. It can also be used to change the engine type of a
2379 sampler channel. This command has (currently) no way to define or
2380 force if a new engine instance should be created and assigned to the
2381 given sampler channel or if an already existing instance of that
2382 engine type, shared with other sampler channels, should be used.
2383
2384 Possible Answers:
2385
2386 "OK" -
2387
2388 in case the engine was successfully deployed
2389
2390 "WRN:<warning-code>:<warning-message>" -
2391
2392 in case the engine was deployed successfully, but there are
2393 noteworthy issue(s) related, providing an appropriate warning
2394 code and warning message
2395
2396 "ERR:<error-code>:<error-message>" -
2397
2398 in case it failed, providing an appropriate error code and
2399 error message
2400
2401 Example:
2402
2403
2404
2405
2406
2407 Schoenebeck Expires May 30, 2007 [Page 43]
2408
2409 Internet-Draft LinuxSampler Control Protocol November 2006
2410
2411
2412
2413
2414 6.4.3. Getting all created sampler channel count
2415
2416 The number of sampler channels can change on runtime. To get the
2417 current amount of sampler channels, the front-end can send the
2418 following command:
2419
2420 GET CHANNELS
2421
2422 Possible Answers:
2423
2424 LinuxSampler will answer by returning the current number of
2425 sampler channels.
2426
2427 Example:
2428
2429 C: "GET CHANNELS"
2430
2431 S: "12"
2432
2433 6.4.4. Getting all created sampler channel list
2434
2435 The number of sampler channels can change on runtime. To get the
2436 current list of sampler channels, the front-end can send the
2437 following command:
2438
2439 LIST CHANNELS
2440
2441 Possible Answers:
2442
2443 LinuxSampler will answer by returning a comma separated list with
2444 all sampler channels numerical IDs.
2445
2446 Example:
2447
2448 C: "LIST CHANNELS"
2449
2450 S: "0,1,2,3,4,5,6,9,10,11,15,20"
2451
2452 6.4.5. Adding a new sampler channel
2453
2454 A new sampler channel can be added to the end of the sampler channel
2455 list by sending the following command:
2456
2457 ADD CHANNEL
2458
2459 This will increment the sampler channel count by one and the new
2460
2461
2462
2463 Schoenebeck Expires May 30, 2007 [Page 44]
2464
2465 Internet-Draft LinuxSampler Control Protocol November 2006
2466
2467
2468 sampler channel will be appended to the end of the sampler channel
2469 list. The front-end should send the respective, related commands
2470 right after to e.g. load an engine, load an instrument and setting
2471 input, output method and eventually other commands to initialize the
2472 new channel. The front-end should use the sampler channel returned
2473 by the answer of this command to perform the previously recommended
2474 commands, to avoid race conditions e.g. with other front-ends that
2475 might also have sent an "ADD CHANNEL" command.
2476
2477 Possible Answers:
2478
2479 "OK[<sampler-channel>]" -
2480
2481 in case a new sampler channel could be added, where <sampler-
2482 channel> reflects the channel number of the new created sampler
2483 channel which should be used to set up the sampler channel by
2484 sending subsequent initialization commands
2485
2486 "WRN:<warning-code>:<warning-message>" -
2487
2488 in case a new channel was added successfully, but there are
2489 noteworthy issue(s) related, providing an appropriate warning
2490 code and warning message
2491
2492 "ERR:<error-code>:<error-message>" -
2493
2494 in case it failed, providing an appropriate error code and
2495 error message
2496
2497 Example:
2498
2499
2500
2501 6.4.6. Removing a sampler channel
2502
2503 A sampler channel can be removed by sending the following command:
2504
2505 REMOVE CHANNEL <sampler-channel>
2506
2507 Where <sampler-channel> should be replaced by the number of the
2508 sampler channel as given by the "ADD CHANNEL" (Section 6.4.5) or
2509 "LIST CHANNELS" (Section 6.4.4) command. The channel numbers of all
2510 subsequent sampler channels remain the same.
2511
2512 Possible Answers:
2513
2514
2515
2516
2517
2518
2519 Schoenebeck Expires May 30, 2007 [Page 45]
2520
2521 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 46]
2576
2577 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 47]
2632
2633 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 48]
2688
2689 Internet-Draft LinuxSampler Control Protocol November 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 May 30, 2007 [Page 49]
2744
2745 Internet-Draft LinuxSampler Control Protocol November 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 The mentioned fields above don't have to be in particular order.
2762
2763 Example:
2764
2765 C: "GET CHANNEL INFO 34"
2766
2767 S: "ENGINE_NAME: GigEngine"
2768
2769 "VOLUME: 1.0"
2770
2771 "AUDIO_OUTPUT_DEVICE: 0"
2772
2773 "AUDIO_OUTPUT_CHANNELS: 2"
2774
2775 "AUDIO_OUTPUT_ROUTING: 0,1"
2776
2777 "INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"
2778
2779 "INSTRUMENT_NR: 0"
2780
2781 "INSTRUMENT_NAME: Fazioli Piano"
2782
2783 "INSTRUMENT_STATUS: 100"
2784
2785 "MIDI_INPUT_DEVICE: 0"
2786
2787 "MIDI_INPUT_PORT: 0"
2788
2789 "MIDI_INPUT_CHANNEL: 5"
2790
2791 "."
2792
2793
2794
2795
2796
2797
2798
2799 Schoenebeck Expires May 30, 2007 [Page 50]
2800
2801 Internet-Draft LinuxSampler Control Protocol November 2006
2802
2803
2804 6.4.11. Current number of active voices
2805
2806 The front-end can ask for the current number of active voices on a
2807 sampler channel by sending the following command:
2808
2809 GET CHANNEL VOICE_COUNT <sampler-channel>
2810
2811 Where <sampler-channel> is the sampler channel number the front-end
2812 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2813 "LIST CHANNELS" (Section 6.4.4) command.
2814
2815 Possible Answers:
2816
2817 LinuxSampler will answer by returning the number of active voices
2818 on that channel.
2819
2820 Example:
2821
2822
2823
2824 6.4.12. Current number of active disk streams
2825
2826 The front-end can ask for the current number of active disk streams
2827 on a sampler channel by sending the following command:
2828
2829 GET CHANNEL STREAM_COUNT <sampler-channel>
2830
2831 Where <sampler-channel> is the sampler channel number the front-end
2832 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2833 "LIST CHANNELS" (Section 6.4.4) command.
2834
2835 Possible Answers:
2836
2837 LinuxSampler will answer by returning the number of active disk
2838 streams on that channel in case the engine supports disk
2839 streaming, if the engine doesn't support disk streaming it will
2840 return "NA" for not available.
2841
2842 Example:
2843
2844
2845
2846 6.4.13. Current fill state of disk stream buffers
2847
2848 The front-end can ask for the current fill state of all disk streams
2849 on a sampler channel by sending the following command:
2850
2851
2852
2853
2854
2855 Schoenebeck Expires May 30, 2007 [Page 51]
2856
2857 Internet-Draft LinuxSampler Control Protocol November 2006
2858
2859
2860 GET CHANNEL BUFFER_FILL BYTES <sampler-channel>
2861
2862 to get the fill state in bytes or
2863
2864 GET CHANNEL BUFFER_FILL PERCENTAGE <sampler-channel>
2865
2866 to get the fill state in percent, where <sampler-channel> is the
2867 sampler channel number the front-end is interested in as returned by
2868 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
2869 command.
2870
2871 Possible Answers:
2872
2873 LinuxSampler will either answer by returning a comma separated
2874 string with the fill state of all disk stream buffers on that
2875 channel or an empty line if there are no active disk streams or
2876 "NA" for *not available* in case the engine which is deployed
2877 doesn't support disk streaming. Each entry in the answer list
2878 will begin with the stream's ID in brackets followed by the
2879 numerical representation of the fill size (either in bytes or
2880 percentage). Note: due to efficiency reasons the fill states in
2881 the response are not in particular order, thus the front-end has
2882 to sort them by itself if necessary.
2883
2884 Examples:
2885
2886 C: "GET CHANNEL BUFFER_FILL BYTES 4"
2887
2888 S: "[115]420500,[116]510300,[75]110000,[120]230700"
2889
2890 C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
2891
2892 S: "[115]90%,[116]98%,[75]40%,[120]62%"
2893
2894 C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
2895
2896 S: ""
2897
2898 6.4.14. Setting audio output device
2899
2900 The front-end can set the audio output device on a specific sampler
2901 channel by sending the following command:
2902
2903 SET CHANNEL AUDIO_OUTPUT_DEVICE <sampler-channel>
2904 <audio-device-id>
2905
2906 Where <sampler-channel> is the respective sampler channel number as
2907 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
2908
2909
2910
2911 Schoenebeck Expires May 30, 2007 [Page 52]
2912
2913 Internet-Draft LinuxSampler Control Protocol November 2006
2914
2915
2916 (Section 6.4.4) command and <audio-device-id> is the numerical ID of
2917 the audio output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
2918 (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
2919 command.
2920
2921 Possible Answers:
2922
2923 "OK" -
2924
2925 on success
2926
2927 "WRN:<warning-code>:<warning-message>" -
2928
2929 if audio output device was set, but there are noteworthy
2930 issue(s) related, providing an appropriate warning code and
2931 warning message
2932
2933 "ERR:<error-code>:<error-message>" -
2934
2935 in case it failed, providing an appropriate error code and
2936 error message
2937
2938 Examples:
2939
2940
2941
2942 6.4.15. Setting audio output type
2943
2944 DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
2945
2946 The front-end can alter the audio output type on a specific sampler
2947 channel by sending the following command:
2948
2949 SET CHANNEL AUDIO_OUTPUT_TYPE <sampler-channel> <audio-output-
2950 type>
2951
2952 Where <audio-output-type> is currently either "ALSA" or "JACK" and
2953 <sampler-channel> is the respective sampler channel number.
2954
2955 Possible Answers:
2956
2957 "OK" -
2958
2959 on success
2960
2961 "WRN:<warning-code>:<warning-message>" -
2962
2963
2964
2965
2966
2967 Schoenebeck Expires May 30, 2007 [Page 53]
2968
2969 Internet-Draft LinuxSampler Control Protocol November 2006
2970
2971
2972 if audio output type was set, but there are noteworthy issue(s)
2973 related, providing an appropriate warning code and warning
2974 message
2975
2976 "ERR:<error-code>:<error-message>" -
2977
2978 in case it failed, providing an appropriate error code and
2979 error message
2980
2981 Examples:
2982
2983
2984
2985 6.4.16. Setting audio output channel
2986
2987 The front-end can alter the audio output channel on a specific
2988 sampler channel by sending the following command:
2989
2990 SET CHANNEL AUDIO_OUTPUT_CHANNEL <sampler-chan> <audio-out>
2991 <audio-in>
2992
2993 Where <sampler-chan> is the sampler channel number as returned by the
2994 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
2995 command, <audio-out> is the numerical ID of the sampler channel's
2996 audio output channel which should be rerouted and <audio-in> is the
2997 numerical ID of the audio channel of the selected audio output device
2998 where <audio-out> should be routed to.
2999
3000 Possible Answers:
3001
3002 "OK" -
3003
3004 on success
3005
3006 "WRN:<warning-code>:<warning-message>" -
3007
3008 if audio output channel was set, but there are noteworthy
3009 issue(s) related, providing an appropriate warning code and
3010 warning message
3011
3012 "ERR:<error-code>:<error-message>" -
3013
3014 in case it failed, providing an appropriate error code and
3015 error message
3016
3017 Examples:
3018
3019
3020
3021
3022
3023 Schoenebeck Expires May 30, 2007 [Page 54]
3024
3025 Internet-Draft LinuxSampler Control Protocol November 2006
3026
3027
3028
3029
3030 6.4.17. Setting MIDI input device
3031
3032 The front-end can set the MIDI input device on a specific sampler
3033 channel by sending the following command:
3034
3035 SET CHANNEL MIDI_INPUT_DEVICE <sampler-channel> <midi-device-id>
3036
3037 Where <sampler-channel> is the sampler channel number as returned by
3038 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3039 command and <midi-device-id> is the numerical ID of the MIDI input
3040 device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5)
3041 or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command.
3042
3043 Possible Answers:
3044
3045 "OK" -
3046
3047 on success
3048
3049 "WRN:<warning-code>:<warning-message>" -
3050
3051 if MIDI input device was set, but there are noteworthy issue(s)
3052 related, providing an appropriate warning code and warning
3053 message
3054
3055 "ERR:<error-code>:<error-message>" -
3056
3057 in case it failed, providing an appropriate error code and
3058 error message
3059
3060 Examples:
3061
3062
3063
3064 6.4.18. Setting MIDI input type
3065
3066 DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
3067
3068 The front-end can alter the MIDI input type on a specific sampler
3069 channel by sending the following command:
3070
3071 SET CHANNEL MIDI_INPUT_TYPE <sampler-channel> <midi-input-type>
3072
3073 Where <midi-input-type> is currently only "ALSA" and <sampler-
3074 channel> is the respective sampler channel number.
3075
3076
3077
3078
3079 Schoenebeck Expires May 30, 2007 [Page 55]
3080
3081 Internet-Draft LinuxSampler Control Protocol November 2006
3082
3083
3084 Possible Answers:
3085
3086 "OK" -
3087
3088 on success
3089
3090 "WRN:<warning-code>:<warning-message>" -
3091
3092 if MIDI input type was set, but there are noteworthy issue(s)
3093 related, providing an appropriate warning code and warning
3094 message
3095
3096 "ERR:<error-code>:<error-message>" -
3097
3098 in case it failed, providing an appropriate error code and
3099 error message
3100
3101 Examples:
3102
3103
3104
3105 6.4.19. Setting MIDI input port
3106
3107 The front-end can alter the MIDI input port on a specific sampler
3108 channel by sending the following command:
3109
3110 SET CHANNEL MIDI_INPUT_PORT <sampler-channel> <midi-input-port>
3111
3112 Where <midi-input-port> is a MIDI input port number of the MIDI input
3113 device connected to the sampler channel given by <sampler-channel>.
3114
3115 Possible Answers:
3116
3117 "OK" -
3118
3119 on success
3120
3121 "WRN:<warning-code>:<warning-message>" -
3122
3123 if MIDI input port was set, but there are noteworthy issue(s)
3124 related, providing an appropriate warning code and warning
3125 message
3126
3127 "ERR:<error-code>:<error-message>" -
3128
3129 in case it failed, providing an appropriate error code and
3130 error message
3131
3132
3133
3134
3135 Schoenebeck Expires May 30, 2007 [Page 56]
3136
3137 Internet-Draft LinuxSampler Control Protocol November 2006
3138
3139
3140 Examples:
3141
3142
3143
3144 6.4.20. Setting MIDI input channel
3145
3146 The front-end can alter the MIDI channel a sampler channel should
3147 listen to by sending the following command:
3148
3149 SET CHANNEL MIDI_INPUT_CHANNEL <sampler-channel> <midi-input-chan>
3150
3151 Where <midi-input-chan> is the number of the new MIDI input channel
3152 where <sampler-channel> should listen to or "ALL" to listen on all 16
3153 MIDI channels.
3154
3155 Possible Answers:
3156
3157 "OK" -
3158
3159 on success
3160
3161 "WRN:<warning-code>:<warning-message>" -
3162
3163 if MIDI input channel was set, but there are noteworthy
3164 issue(s) related, providing an appropriate warning code and
3165 warning message
3166
3167 "ERR:<error-code>:<error-message>" -
3168
3169 in case it failed, providing an appropriate error code and
3170 error message
3171
3172 Examples:
3173
3174
3175
3176 6.4.21. Setting channel volume
3177
3178 The front-end can alter the volume of a sampler channel by sending
3179 the following command:
3180
3181 SET CHANNEL VOLUME <sampler-channel> <volume>
3182
3183 Where <volume> is an optionally dotted positive number (a value
3184 smaller than 1.0 means attenuation, whereas a value greater than 1.0
3185 means amplification) and <sampler-channel> defines the sampler
3186 channel where this volume factor should be set.
3187
3188
3189
3190
3191 Schoenebeck Expires May 30, 2007 [Page 57]
3192
3193 Internet-Draft LinuxSampler Control Protocol November 2006
3194
3195
3196 Possible Answers:
3197
3198 "OK" -
3199
3200 on success
3201
3202 "WRN:<warning-code>:<warning-message>" -
3203
3204 if channel volume was set, but there are noteworthy issue(s)
3205 related, providing an appropriate warning code and warning
3206 message
3207
3208 "ERR:<error-code>:<error-message>" -
3209
3210 in case it failed, providing an appropriate error code and
3211 error message
3212
3213 Examples:
3214
3215
3216
3217 6.4.22. Muting a sampler channel
3218
3219 The front-end can mute/unmute a specific sampler channel by sending
3220 the following command:
3221
3222 SET CHANNEL MUTE <sampler-channel> <mute>
3223
3224 Where <sampler-channel> is the respective sampler channel number as
3225 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3226 (Section 6.4.4) command and <mute> should be replaced either by "1"
3227 to mute the channel or "0" to unmute the channel.
3228
3229 Possible Answers:
3230
3231 "OK" -
3232
3233 on success
3234
3235 "WRN:<warning-code>:<warning-message>" -
3236
3237 if the channel was muted/unmuted, but there are noteworthy
3238 issue(s) related, providing an appropriate warning code and
3239 warning message
3240
3241 "ERR:<error-code>:<error-message>" -
3242
3243
3244
3245
3246
3247 Schoenebeck Expires May 30, 2007 [Page 58]
3248
3249 Internet-Draft LinuxSampler Control Protocol November 2006
3250
3251
3252 in case it failed, providing an appropriate error code and
3253 error message
3254
3255 Examples:
3256
3257
3258
3259 6.4.23. Soloing a sampler channel
3260
3261 The front-end can solo/unsolo a specific sampler channel by sending
3262 the following command:
3263
3264 SET CHANNEL SOLO <sampler-channel> <solo>
3265
3266 Where <sampler-channel> is the respective sampler channel number as
3267 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3268 (Section 6.4.4) command and <solo> should be replaced either by "1"
3269 to solo the channel or "0" to unsolo the channel.
3270
3271 Possible Answers:
3272
3273 "OK" -
3274
3275 on success
3276
3277 "WRN:<warning-code>:<warning-message>" -
3278
3279 if the channel was soloed/unsoloed, but there are noteworthy
3280 issue(s) related, providing an appropriate warning code and
3281 warning message
3282
3283 "ERR:<error-code>:<error-message>" -
3284
3285 in case it failed, providing an appropriate error code and
3286 error message
3287
3288 Examples:
3289
3290
3291
3292 6.4.24. Resetting a sampler channel
3293
3294 The front-end can reset a particular sampler channel by sending the
3295 following command:
3296
3297 RESET CHANNEL <sampler-channel>
3298
3299 Where <sampler-channel> defines the sampler channel to be reset.
3300
3301
3302
3303 Schoenebeck Expires May 30, 2007 [Page 59]
3304
3305 Internet-Draft LinuxSampler Control Protocol November 2006
3306
3307
3308 This will cause the engine on that sampler channel, its voices and
3309 eventually disk streams and all control and status variables to be
3310 reset.
3311
3312 Possible Answers:
3313
3314 "OK" -
3315
3316 on success
3317
3318 "WRN:<warning-code>:<warning-message>" -
3319
3320 if channel was reset, but there are noteworthy issue(s)
3321 related, providing an appropriate warning code and warning
3322 message
3323
3324 "ERR:<error-code>:<error-message>" -
3325
3326 in case it failed, providing an appropriate error code and
3327 error message
3328
3329 Examples:
3330
3331
3332
3333 6.5. Controlling connection
3334
3335 The following commands are used to control the connection to
3336 LinuxSampler.
3337
3338 6.5.1. Register front-end for receiving event messages
3339
3340 The front-end can register itself to the LinuxSampler application to
3341 be informed about noteworthy events by sending this command:
3342
3343 SUBSCRIBE <event-id>
3344
3345 where <event-id> will be replaced by the respective event that client
3346 wants to subscribe to.
3347
3348 Possible Answers:
3349
3350 "OK" -
3351
3352 on success
3353
3354
3355
3356
3357
3358
3359 Schoenebeck Expires May 30, 2007 [Page 60]
3360
3361 Internet-Draft LinuxSampler Control Protocol November 2006
3362
3363
3364 "WRN:<warning-code>:<warning-message>" -
3365
3366 if registration succeeded, but there are noteworthy issue(s)
3367 related, providing an appropriate warning code and warning
3368 message
3369
3370 "ERR:<error-code>:<error-message>" -
3371
3372 in case it failed, providing an appropriate error code and
3373 error message
3374
3375 Examples:
3376
3377
3378
3379 6.5.2. Unregister front-end for not receiving event messages
3380
3381 The front-end can unregister itself if it doesn't want to receive
3382 event messages anymore by sending the following command:
3383
3384 UNSUBSCRIBE <event-id>
3385
3386 Where <event-id> will be replaced by the respective event that client
3387 doesn't want to receive anymore.
3388
3389 Possible Answers:
3390
3391 "OK" -
3392
3393 on success
3394
3395 "WRN:<warning-code>:<warning-message>" -
3396
3397 if unregistration succeeded, but there are noteworthy issue(s)
3398 related, providing an appropriate warning code and warning
3399 message
3400
3401 "ERR:<error-code>:<error-message>" -
3402
3403 in case it failed, providing an appropriate error code and
3404 error message
3405
3406 Examples:
3407
3408
3409
3410
3411
3412
3413
3414
3415 Schoenebeck Expires May 30, 2007 [Page 61]
3416
3417 Internet-Draft LinuxSampler Control Protocol November 2006
3418
3419
3420 6.5.3. Enable or disable echo of commands
3421
3422 To enable or disable back sending of commands to the client the
3423 following command can be used:
3424
3425 SET ECHO <value>
3426
3427 Where <value> should be replaced either by "1" to enable echo mode or
3428 "0" to disable echo mode. When echo mode is enabled, all commands
3429 send to LinuxSampler will be immediately send back and after this
3430 echo the actual response to the command will be returned. Echo mode
3431 will only be altered for the client connection that issued the "SET
3432 ECHO" command, not globally for all client connections.
3433
3434 Possible Answers:
3435
3436 "OK" -
3437
3438 usually
3439
3440 "ERR:<error-code>:<error-message>" -
3441
3442 on syntax error, e.g. non boolean value
3443
3444 Examples:
3445
3446
3447
3448 6.5.4. Close client connection
3449
3450 The client can close its network connection to LinuxSampler by
3451 sending the following command:
3452
3453 QUIT
3454
3455 This is probably more interesting for manual telnet connections to
3456 LinuxSampler than really useful for a front-end implementation.
3457
3458 6.6. Global commands
3459
3460 The following commands have global impact on the sampler.
3461
3462 6.6.1. Current number of active voices
3463
3464 The front-end can ask for the current number of active voices on the
3465 sampler by sending the following command:
3466
3467
3468
3469
3470
3471 Schoenebeck Expires May 30, 2007 [Page 62]
3472
3473 Internet-Draft LinuxSampler Control Protocol November 2006
3474
3475
3476 GET TOTAL_VOICE_COUNT
3477
3478 Possible Answers:
3479
3480 LinuxSampler will answer by returning the number of all active
3481 voices on the sampler.
3482
3483 6.6.2. Maximum amount of active voices
3484
3485 The front-end can ask for the maximum number of active voices by
3486 sending the following command:
3487
3488 GET TOTAL_VOICE_COUNT_MAX
3489
3490 Possible Answers:
3491
3492 LinuxSampler will answer by returning the maximum number of active
3493 voices.
3494
3495 6.6.3. Reset sampler
3496
3497 The front-end can reset the whole sampler by sending the following
3498 command:
3499
3500 RESET
3501
3502 Possible Answers:
3503
3504 "OK" -
3505
3506 always
3507
3508 Examples:
3509
3510
3511
3512 6.6.4. General sampler informations
3513
3514 The client can ask for general informations about the LinuxSampler
3515 instance by sending the following command:
3516
3517 GET SERVER INFO
3518
3519 Possible Answers:
3520
3521 LinuxSampler will answer by sending a <CRLF> separated list. Each
3522 answer line begins with the information category name followed by
3523 a colon and then a space character <SP> and finally the info
3524
3525
3526
3527 Schoenebeck Expires May 30, 2007 [Page 63]
3528
3529 Internet-Draft LinuxSampler Control Protocol November 2006
3530
3531
3532 character string to that information category. At the moment the
3533 following categories are defined:
3534
3535
3536
3537 DESCRIPTION -
3538
3539 arbitrary textual description about the sampler
3540
3541 VERSION -
3542
3543 version of the sampler
3544
3545 PROTOCOL_VERSION -
3546
3547 version of the LSCP specification the sampler complies with
3548 (see Section 2 for details)
3549
3550 The mentioned fields above don't have to be in particular order.
3551 Other fields might be added in future.
3552
3553 6.7. MIDI Instrument Mapping
3554
3555 The MIDI protocol provides a way to switch between instruments by
3556 sending so called MIDI bank select and MIDI program change messages
3557 which are essentially just numbers. The following commands allow to
3558 actually map arbitrary MIDI bank select / program change numbers with
3559 real instruments.
3560
3561 By default, that is when the sampler is launched, this map will be
3562 empty, thus the sampler will simply ignore all program change
3563 messages. The front-end has to explicitly add entries to the map so
3564 the sampler knows how to react on a given program change message,
3565 that is by switching to the respectively defined engine type and
3566 loading the respective instrument.
3567
3568 Also note per MIDI specification a bank select message does not cause
3569 to switch to another instrument. Instead when receiving a bank
3570 select message the bank value will be stored and a subsequent program
3571 change message (which may occur at any time) will finally cause the
3572 sampler to switch to the respective instrument as reflected by the
3573 current MIDI instrument map.
3574
3575 6.7.1. Create or replace a MIDI instrument map entry
3576
3577 The front-end can create a new or replace an existing entry in the
3578 sampler's MIDI instrument map by sending the following command:
3579
3580
3581
3582
3583 Schoenebeck Expires May 30, 2007 [Page 64]
3584
3585 Internet-Draft LinuxSampler Control Protocol November 2006
3586
3587
3588 MAP MIDI_INSTRUMENT <midi_bank_msb> <midi_bank_lsb> <midi_prog>
3589 <engine_name> <filename> <instrument_index> <volume_value>
3590 [<instr_load_mode>] [<name>]
3591
3592 Where <midi_bank_msb> is an integer value between 0..127 reflecting
3593 the MIDI bank select MSB (coarse) index, <midi_bank_lsb> an integer
3594 value between 0..127 reflecting the MIDI bank select LSB (fine)
3595 index, <midi_prog> an integer value between 0..127 reflecting the
3596 MIDI program change index, <engine_name> a sampler engine name as
3597 returned by the "LIST AVAILABLE_ENGINES" (Section 6.4.8) command (not
3598 encapsulated into apostrophes), <filename> the name of the
3599 instrument's file to be deployed (encapsulated into apostrophes),
3600 <instrument_index> the index (integer value) of the instrument within
3601 the given file, <volume_value> reflects the master volume of the
3602 instrument as optionally dotted number (where a value < 1.0 means
3603 attenuation and a value > 1.0 means amplification). This parameter
3604 easily allows to adjust the volume of all intruments within a custom
3605 instrument map without having to adjust their instrument files. The
3606 OPTIONAL <instr_load_mode> argument defines the life time of the
3607 instrument, that is when the instrument should be loaded, when freed
3608 and has exactly the following possibilities:
3609
3610 "ON_DEMAND" -
3611
3612 The instrument will be loaded when needed, that is when
3613 demanded by at least one sampler channel. It will immediately
3614 be freed from memory when not needed by any sampler channel
3615 anymore.
3616
3617 "ON_DEMAND_HOLD" -
3618
3619 The instrument will be loaded when needed, that is when
3620 demanded by at least one sampler channel. It will be kept in
3621 memory even when not needed by any sampler channel anymore.
3622 Instruments with this mode are only freed when the sampler is
3623 reset or all mapping entries with this mode (and respective
3624 instrument) are explicitly changed to "ON_DEMAND" and no
3625 sampler channel is using the instrument anymore.
3626
3627 "PERSISTENT" -
3628
3629 The instrument will immediately be loaded into memory in the
3630 background when this mapping command is sent and the instrument
3631 is kept all the time. Instruments with this mode are only
3632 freed when the sampler is reset or all mapping entries with
3633 this mode (and respective instrument) are explicitly changed to
3634 "ON_DEMAND" and no sampler channel is using the instrument
3635 anymore.
3636
3637
3638
3639 Schoenebeck Expires May 30, 2007 [Page 65]
3640
3641 Internet-Draft LinuxSampler Control Protocol November 2006
3642
3643
3644 not supplied -
3645
3646 In case there is no <instr_load_mode> argument given, it will
3647 be up to the InstrumentManager to decide which mode to use.
3648 Usually it will use "ON_DEMAND" if an entry for the given
3649 instrument does not exist in the InstrumentManager's list yet,
3650 otherwise if an entry already exists, it will simply stick with
3651 the mode currently reflected by the already existing entry,
3652 that is it will not change the mode.
3653
3654 The <instr_load_mode> argument thus allows to define an appropriate
3655 strategy (low memory consumption vs. fast instrument switching) for
3656 each instrument individually. Note, the following restrictions apply
3657 to this argument: "ON_DEMAND_HOLD" and "PERSISTENT" have to be
3658 supported by the respective sampler engine (which is technically the
3659 case when the engine provides an InstrumentManager for its format).
3660 If this is not the case the argument will automatically fall back to
3661 the default value "ON_DEMAND". Also the load mode of one instrument
3662 may automatically change the laod mode of other instrument(s), i.e.
3663 because the instruments are part of the same file and the engine does
3664 not allow a way to manage load modes for them individually. Due to
3665 this, in case the frontend shows the load modes of entries, the
3666 frontend should retrieve the actual mode by i.e. sending "GET
3667 MIDI_INSTRUMENT INFO" (Section 6.7.5) command(s). Finally the
3668 OPTIONAL <name> argument allows to set a custom name (encapsulated
3669 into apostrophes) for the mapping entry, useful for frontends for
3670 displaying an appropriate name for mapped instruments (using "GET
3671 MIDI_INSTRUMENT INFO" (Section 6.7.5)).
3672
3673 The "MAP MIDI_INSTRUMENT" command will immediately return, thus it
3674 will not block when an instrument is to be loaded due to a
3675 "PERSISTENT" type entry as instruments are loaded in the background.
3676 As a consequence this command may not necessarily return an error
3677 i.e. when the given instrument file does not exist or may turn out to
3678 be corrupt.
3679
3680 Possible Answers:
3681
3682 "OK" -
3683
3684 usually
3685
3686 "ERR:<error-code>:<error-message>" -
3687
3688 when the given engine does not exist or a value is out of range
3689
3690 Examples:
3691
3692
3693
3694
3695 Schoenebeck Expires May 30, 2007 [Page 66]
3696
3697 Internet-Draft LinuxSampler Control Protocol November 2006
3698
3699
3700 C: "MAP MIDI_INSTRUMENT 3 0 0 gig '/usr/share/Steinway D.gig' 0
3701 0.8 PERSISTENT"
3702
3703 S: "OK"
3704
3705 C: "MAP MIDI_INSTRUMENT 127 4 50 gig '/home/john/foostrings.gig' 7
3706 1.0"
3707
3708 S: "OK"
3709
3710 C: "MAP MIDI_INSTRUMENT 0 0 0 gig '/usr/share/piano.gig' 0 1.0
3711 'Normal Piano'"
3712
3713 S: "OK"
3714
3715 C: "MAP MIDI_INSTRUMENT 1 0 0 gig '/usr/share/piano.gig' 0 0.25
3716 'Silent Piano'"
3717
3718 S: "OK"
3719
3720 C: "MAP MIDI_INSTRUMENT 99 8 120 gig '/home/joe/foodrums.gig' 0
3721 1.0 PERSISTENT 'Foo Drumkit'"
3722
3723 S: "OK"
3724
3725 6.7.2. Getting ammount of MIDI instrument map entries
3726
3727 The front-end can query the amount of currently existing MIDI
3728 instrument map entries by sending the following command:
3729
3730 GET MIDI_INSTRUMENTS
3731
3732 Possible Answers:
3733
3734 LinuxSampler will answer by sending the current number of entries
3735 in the sampler's MIDI instrument map.
3736
3737 Example:
3738
3739 C: "GET MIDI_INSTRUMENTS"
3740
3741 S: "634"
3742
3743 6.7.3. Getting indeces of all MIDI instrument map entries
3744
3745 The front-end can query a list of all currently existing MIDI
3746 instrument map entries by sending the following command:
3747
3748
3749
3750
3751 Schoenebeck Expires May 30, 2007 [Page 67]
3752
3753 Internet-Draft LinuxSampler Control Protocol November 2006
3754
3755
3756 LIST MIDI_INSTRUMENTS
3757
3758 Possible Answers:
3759
3760 LinuxSampler will answer by sending a comma separated list of MIDI
3761 bank MSB (coarse) - MIDI bank LSB (fine) - MIDI program triples,
3762 where each triple is encapsulated into curly braces. The list is
3763 returned in one single line. Each triple just reflects the key of
3764 the respective map entry, thus subsequent "GET MIDI_INSTRUMENT
3765 INFO" (Section 6.7.5) command(s) are necessary to retrieve
3766 detailed informations about each entry.
3767
3768 Example:
3769
3770 C: "LIST MIDI_INSTRUMENTS"
3771
3772 S: "{0,0,0},{0,0,1},{120,0,3},{120,0,4},{23,127,127}"
3773
3774 6.7.4. Remove an entry from the MIDI instrument map
3775
3776 The front-end can delete an entry from the MIDI instrument map by
3777 sending the following command:
3778
3779 UNMAP MIDI_INSTRUMENT <midi_bank_msb> <midi_bank_lsb> <midi_prog>
3780
3781 Where <midi_bank_msb> is an integer value between 0..127 reflecting
3782 the MIDI bank MSB (coarse) value, <midi_bank_lsb> an integer value
3783 between 0..127 reflecting the MIDI bank LSB (fine) value and
3784 <midi_prog> an integer value between 0..127 reflecting the MIDI
3785 program value of the map entrie's key index triple.
3786
3787 Possible Answers:
3788
3789 "OK" -
3790
3791 usually
3792
3793 "ERR:<error-code>:<error-message>" -
3794
3795 when index out of bounds
3796
3797 Example:
3798
3799 C: "UNMAP MIDI_INSTRUMENT 2 40 127"
3800
3801 S: "OK"
3802
3803
3804
3805
3806
3807 Schoenebeck Expires May 30, 2007 [Page 68]
3808
3809 Internet-Draft LinuxSampler Control Protocol November 2006
3810
3811
3812 6.7.5. Get current settings of MIDI instrument map entry
3813
3814 The front-end can retrieve the current settings of a certain
3815 instrument map entry by sending the following command:
3816
3817 GET MIDI_INSTRUMENT INFO <midi_bank_msb> <midi_bank_lsb>
3818 <midi_prog>
3819
3820 Where <midi_bank_msb> is an integer value between 0..127 reflecting
3821 the MIDI bank MSB (coarse) value, <midi_bank_lsb> an integer value
3822 between 0..127 reflecting the MIDI bank LSB (fine) value and
3823 <midi_prog> an integer value between 0..127 reflecting the MIDI
3824 program value of the map entrie's key index triple.
3825
3826 Possible Answers:
3827
3828 LinuxSampler will answer by sending a <CRLF> separated list. Each
3829 answer line begins with the information category name followed by
3830 a colon and then a space character <SP> and finally the info
3831 character string to that info category. At the moment the
3832 following categories are defined:
3833
3834 "NAME" -
3835
3836 Name for this MIDI instrument map entry (if defined). This
3837 name shall be used by frontends for displaying a name for this
3838 mapped instrument. It can be set and changed with the "MAP
3839 MIDI_INSTRUMENT" (Section 6.7.1) command and does not have to
3840 be unique.
3841
3842 "ENGINE_NAME" -
3843
3844 Name of the engine to be deployed for this instrument.
3845
3846 "INSTRUMENT_FILE" -
3847
3848 File name of the instrument.
3849
3850 "INSTRUMENT_NR" -
3851
3852 Index of the instrument within the file.
3853
3854 "INSTRUMENT_NAME" -
3855
3856 Name of the loaded instrument as reflected by its file. In
3857 contrast to the "NAME" field, the "INSTRUMENT_NAME" field
3858 cannot be changed.
3859
3860
3861
3862
3863 Schoenebeck Expires May 30, 2007 [Page 69]
3864
3865 Internet-Draft LinuxSampler Control Protocol November 2006
3866
3867
3868 "LOAD_MODE" -
3869
3870 Life time of instrument (see "MAP MIDI_INSTRUMENT"
3871 (Section 6.7.1) for details about this setting).
3872
3873 "VOLUME" -
3874
3875 master volume of the instrument as optionally dotted number
3876 (where a value < 1.0 means attenuation and a value > 1.0 means
3877 amplification)
3878
3879 The mentioned fields above don't have to be in particular order.
3880
3881 Example:
3882
3883 C: "GET MIDI_INSTRUMENT INFO 3 45 120"
3884
3885 S: "NAME: Drums for Foo Song"
3886
3887 "ENGINE_NAME: GigEngine"
3888
3889 "INSTRUMENT_FILE: /usr/share/joesdrumkit.gig"
3890
3891 "INSTRUMENT_NR: 0"
3892
3893 "INSTRUMENT_NAME: Joe's Drumkit"
3894
3895 "LOAD_MODE: PERSISTENT"
3896
3897 "VOLUME: 1.0"
3898
3899 "."
3900
3901 6.7.6. Clear MIDI instrument map
3902
3903 The front-end can clear the whole MIDI instrument map, that is delete
3904 all entries by sending the following command:
3905
3906 CLEAR MIDI_INSTRUMENTS
3907
3908 Possible Answers:
3909
3910 "OK" -
3911
3912 always
3913
3914 Example:
3915
3916
3917
3918
3919 Schoenebeck Expires May 30, 2007 [Page 70]
3920
3921 Internet-Draft LinuxSampler Control Protocol November 2006
3922
3923
3924 C: "CLEAR MIDI_INSTRUMENTS"
3925
3926 S: "OK"
3927
3928
3929
3930
3931
3932
3933
3934
3935
3936
3937
3938
3939
3940
3941
3942
3943
3944
3945
3946
3947
3948
3949
3950
3951
3952
3953
3954
3955
3956
3957
3958
3959
3960
3961
3962
3963
3964
3965
3966
3967
3968
3969
3970
3971
3972
3973
3974
3975 Schoenebeck Expires May 30, 2007 [Page 71]
3976
3977 Internet-Draft LinuxSampler Control Protocol November 2006
3978
3979
3980 7. Command Syntax
3981
3982 The grammar of the control protocol as descibed in Section 6 is
3983 defined below using Backus-Naur Form (BNF as described in [RFC2234])
3984 where applicable.
3985
3986 input =
3987
3988 line LF
3989
3990 / line CR LF
3991
3992 line =
3993
3994 /* epsilon (empty line ignored) */
3995
3996 / comment
3997
3998 / command
3999
4000 / error
4001
4002 comment =
4003
4004 '#'
4005
4006 / comment '#'
4007
4008 / comment SP
4009
4010 / comment number
4011
4012 / comment string
4013
4014 command =
4015
4016 ADD SP CHANNEL
4017
4018 / MAP SP map_instruction
4019
4020 / UNMAP SP unmap_instruction
4021
4022 / GET SP get_instruction
4023
4024 / CREATE SP create_instruction
4025
4026 / DESTROY SP destroy_instruction
4027
4028
4029
4030
4031 Schoenebeck Expires May 30, 2007 [Page 72]
4032
4033 Internet-Draft LinuxSampler Control Protocol November 2006
4034
4035
4036 / LIST SP list_instruction
4037
4038 / LOAD SP load_instruction
4039
4040 / REMOVE SP remove_instruction
4041
4042 / SET SP set_instruction
4043
4044 / SUBSCRIBE SP subscribe_event
4045
4046 / UNSUBSCRIBE SP unsubscribe_event
4047
4048 / SELECT SP text
4049
4050 / RESET SP reset_instruction
4051
4052 / CLEAR SP clear_instruction
4053
4054 / RESET
4055
4056 / QUIT
4057
4058 subscribe_event =
4059
4060 CHANNEL_COUNT
4061
4062 / VOICE_COUNT
4063
4064 / STREAM_COUNT
4065
4066 / BUFFER_FILL
4067
4068 / CHANNEL_INFO
4069
4070 / MISCELLANEOUS
4071
4072 / TOTAL_VOICE_COUNT
4073
4074 unsubscribe_event =
4075
4076 CHANNEL_COUNT
4077
4078 / VOICE_COUNT
4079
4080 / STREAM_COUNT
4081
4082 / BUFFER_FILL
4083
4084
4085
4086
4087 Schoenebeck Expires May 30, 2007 [Page 73]
4088
4089 Internet-Draft LinuxSampler Control Protocol November 2006
4090
4091
4092 / CHANNEL_INFO
4093
4094 / MISCELLANEOUS
4095
4096 / TOTAL_VOICE_COUNT
4097
4098 map_instruction =
4099
4100 MIDI_INSTRUMENT SP midi_bank_msb SP midi_bank_lsb SP midi_prog SP
4101 engine_name SP filename SP instrument_index SP volume_value
4102
4103 / MIDI_INSTRUMENT SP midi_bank_msb SP midi_bank_lsb SP midi_prog
4104 SP engine_name SP filename SP instrument_index SP volume_value SP
4105 instr_load_mode
4106
4107 / MIDI_INSTRUMENT SP midi_bank_msb SP midi_bank_lsb SP midi_prog
4108 SP engine_name SP filename SP instrument_index SP volume_value SP
4109 entry_name
4110
4111 / MIDI_INSTRUMENT SP midi_bank_msb SP midi_bank_lsb SP midi_prog
4112 SP engine_name SP filename SP instrument_index SP volume_value SP
4113 instr_load_mode SP entry_name
4114
4115 unmap_instruction =
4116
4117 MIDI_INSTRUMENT SP midi_bank_msb SP midi_bank_lsb SP midi_prog
4118
4119 remove_instruction =
4120
4121 CHANNEL SP sampler_channel
4122
4123 get_instruction =
4124
4125 AVAILABLE_ENGINES
4126
4127 / AVAILABLE_MIDI_INPUT_DRIVERS
4128
4129 / MIDI_INPUT_DRIVER SP INFO SP string
4130
4131 / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
4132
4133 / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP
4134 key_val_list
4135
4136 / AVAILABLE_AUDIO_OUTPUT_DRIVERS
4137
4138 / AUDIO_OUTPUT_DRIVER SP INFO SP string
4139
4140
4141
4142
4143 Schoenebeck Expires May 30, 2007 [Page 74]
4144
4145 Internet-Draft LinuxSampler Control Protocol November 2006
4146
4147
4148 / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
4149
4150 / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP
4151 key_val_list
4152
4153 / AUDIO_OUTPUT_DEVICES
4154
4155 / MIDI_INPUT_DEVICES
4156
4157 / AUDIO_OUTPUT_DEVICE SP INFO SP number
4158
4159 / MIDI_INPUT_DEVICE SP INFO SP number
4160
4161 / MIDI_INPUT_PORT SP INFO SP number SP number
4162
4163 / MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
4164
4165 / AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
4166
4167 / AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP
4168 string
4169
4170 / CHANNELS
4171
4172 / CHANNEL SP INFO SP sampler_channel
4173
4174 / CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
4175
4176 / CHANNEL SP STREAM_COUNT SP sampler_channel
4177
4178 / CHANNEL SP VOICE_COUNT SP sampler_channel
4179
4180 / ENGINE SP INFO SP engine_name
4181
4182 / SERVER SP INFO
4183
4184 / TOTAL_VOICE_COUNT
4185
4186 / TOTAL_VOICE_COUNT_MAX
4187
4188 / MIDI_INSTRUMENTS
4189
4190 / MIDI_INSTRUMENT SP INFO SP midi_bank_msb SP midi_bank_lsb SP
4191 midi_prog
4192
4193 set_instruction =
4194
4195
4196
4197
4198
4199 Schoenebeck Expires May 30, 2007 [Page 75]
4200
4201 Internet-Draft LinuxSampler Control Protocol November 2006
4202
4203
4204 AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '='
4205 param_val_list
4206
4207 / AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '='
4208 param_val_list
4209
4210 / MIDI_INPUT_DEVICE_PARAMETER SP number SP string '='
4211 param_val_list
4212
4213 / MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '='
4214 param_val_list
4215
4216 / CHANNEL SP set_chan_instruction
4217
4218 / ECHO SP boolean
4219
4220 create_instruction =
4221
4222 AUDIO_OUTPUT_DEVICE SP string SP key_val_list
4223
4224 / AUDIO_OUTPUT_DEVICE SP string
4225
4226 / MIDI_INPUT_DEVICE SP string SP key_val_list
4227
4228 / MIDI_INPUT_DEVICE SP string
4229
4230 reset_instruction =
4231
4232 CHANNEL SP sampler_channel
4233
4234 clear_instruction =
4235
4236 MIDI_INSTRUMENTS
4237
4238 destroy_instruction =
4239
4240 AUDIO_OUTPUT_DEVICE SP number
4241
4242 / MIDI_INPUT_DEVICE SP number
4243
4244 load_instruction =
4245
4246 INSTRUMENT SP load_instr_args
4247
4248 / ENGINE SP load_engine_args
4249
4250 set_chan_instruction =
4251
4252
4253
4254
4255 Schoenebeck Expires May 30, 2007 [Page 76]
4256
4257 Internet-Draft LinuxSampler Control Protocol November 2006
4258
4259
4260 AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
4261
4262 / AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index
4263 SP audio_channel_index
4264
4265 / AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
4266
4267 / MIDI_INPUT SP sampler_channel SP device_index SP
4268 midi_input_port_index SP midi_input_channel_index
4269
4270 / MIDI_INPUT_DEVICE SP sampler_channel SP device_index
4271
4272 / MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
4273
4274 / MIDI_INPUT_CHANNEL SP sampler_channel SP
4275 midi_input_channel_index
4276
4277 / MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
4278
4279 / VOLUME SP sampler_channel SP volume_value
4280
4281 / MUTE SP sampler_channel SP boolean
4282
4283 / SOLO SP sampler_channel SP boolean
4284
4285 key_val_list =
4286
4287 string '=' param_val_list
4288
4289 / key_val_list SP string '=' param_val_list
4290
4291 buffer_size_type =
4292
4293 BYTES
4294
4295 / PERCENTAGE
4296
4297 list_instruction =
4298
4299 AUDIO_OUTPUT_DEVICES
4300
4301 / MIDI_INPUT_DEVICES
4302
4303 / CHANNELS
4304
4305 / AVAILABLE_ENGINES
4306
4307
4308
4309
4310
4311 Schoenebeck Expires May 30, 2007 [Page 77]
4312
4313 Internet-Draft LinuxSampler Control Protocol November 2006
4314
4315
4316 / AVAILABLE_MIDI_INPUT_DRIVERS
4317
4318 / AVAILABLE_AUDIO_OUTPUT_DRIVERS
4319
4320 / MIDI_INSTRUMENTS
4321
4322 load_instr_args =
4323
4324 filename SP instrument_index SP sampler_channel
4325
4326 / NON_MODAL SP filename SP instrument_index SP sampler_channel
4327
4328 load_engine_args =
4329
4330 engine_name SP sampler_channel
4331
4332 instr_load_mode =
4333
4334 ON_DEMAND
4335
4336 / ON_DEMAND_HOLD
4337
4338 / PERSISTENT
4339
4340 device_index =
4341
4342 number
4343
4344 audio_channel_index =
4345
4346 number
4347
4348 audio_output_type_name =
4349
4350 string
4351
4352 midi_input_port_index =
4353
4354 number
4355
4356 midi_input_channel_index =
4357
4358 number
4359
4360 / ALL
4361
4362 midi_input_type_name =
4363
4364
4365
4366
4367 Schoenebeck Expires May 30, 2007 [Page 78]
4368
4369 Internet-Draft LinuxSampler Control Protocol November 2006
4370
4371
4372 string
4373
4374 midi_bank_msb =
4375
4376 number
4377
4378 midi_bank_lsb =
4379
4380 number
4381
4382 midi_prog =
4383
4384 number
4385
4386 volume_value =
4387
4388 dotnum
4389
4390 / number
4391
4392 sampler_channel =
4393
4394 number
4395
4396 instrument_index =
4397
4398 number
4399
4400 engine_name =
4401
4402 string
4403
4404 filename =
4405
4406 stringval
4407
4408 entry_name =
4409
4410 stringval
4411
4412 param_val_list =
4413
4414 param_val
4415
4416 / param_val_list','param_val
4417
4418 param_val =
4419
4420
4421
4422
4423 Schoenebeck Expires May 30, 2007 [Page 79]
4424
4425 Internet-Draft LinuxSampler Control Protocol November 2006
4426
4427
4428 string
4429
4430 / stringval
4431
4432 / number
4433
4434 / dotnum
4435
4436
4437
4438
4439
4440
4441
4442
4443
4444
4445
4446
4447
4448
4449
4450
4451
4452
4453
4454
4455
4456
4457
4458
4459
4460
4461
4462
4463
4464
4465
4466
4467
4468
4469
4470
4471
4472
4473
4474
4475
4476
4477
4478
4479 Schoenebeck Expires May 30, 2007 [Page 80]
4480
4481 Internet-Draft LinuxSampler Control Protocol November 2006
4482
4483
4484 8. Events
4485
4486 This chapter will describe all currently defined events supported by
4487 LinuxSampler.
4488
4489 8.1. Number of sampler channels changed
4490
4491 Client may want to be notified when the total number of channels on
4492 the back-end changes by issuing the following command:
4493
4494 SUBSCRIBE CHANNEL_COUNT
4495
4496 Server will start sending the following notification messages:
4497
4498 "NOTIFY:CHANNEL_COUNT:<channels>"
4499
4500 where <channels> will be replaced by the new number of sampler
4501 channels.
4502
4503 8.2. Number of active voices changed
4504
4505 Client may want to be notified when the number of voices on the back-
4506 end changes by issuing the following command:
4507
4508 SUBSCRIBE VOICE_COUNT
4509
4510 Server will start sending the following notification messages:
4511
4512 "NOTIFY:VOICE_COUNT:<sampler-channel> <voices>
4513
4514 where <sampler-channel> will be replaced by the sampler channel the
4515 voice count change occurred and <voices> by the new number of active
4516 voices on that channel.
4517
4518 8.3. Number of active disk streams changed
4519
4520 Client may want to be notified when the number of streams on the
4521 back-end changes by issuing the following command: SUBSCRIBE
4522 STREAM_COUNT
4523
4524 SUBSCRIBE STREAM_COUNT
4525
4526 Server will start sending the following notification messages:
4527
4528 "NOTIFY:STREAM_COUNT:<sampler-channel> <streams>"
4529
4530 where <sampler-channel> will be replaced by the sampler channel the
4531 stream count change occurred and <streams> by the new number of
4532
4533
4534
4535 Schoenebeck Expires May 30, 2007 [Page 81]
4536
4537 Internet-Draft LinuxSampler Control Protocol November 2006
4538
4539
4540 active disk streams on that channel.
4541
4542 8.4. Disk stream buffer fill state changed
4543
4544 Client may want to be notified when the buffer fill state of a disk
4545 stream on the back-end changes by issuing the following command:
4546
4547 SUBSCRIBE BUFFER_FILL
4548
4549 Server will start sending the following notification messages:
4550
4551 "NOTIFY:BUFFER_FILL:<sampler-channel> <fill-data>"
4552
4553 where <sampler-channel> will be replaced by the sampler channel the
4554 buffer fill state change occurred on and <fill-data> will be replaced
4555 by the buffer fill data for this channel as described in
4556 Section 6.4.13 as if the "GET CHANNEL BUFFER_FILL PERCENTAGE"
4557 (Section 6.4.13) command was issued on this channel.
4558
4559 8.5. Channel information changed
4560
4561 Client may want to be notified when changes were made to sampler
4562 channels on the back-end by issuing the following command:
4563
4564 SUBSCRIBE CHANNEL_INFO
4565
4566 Server will start sending the following notification messages:
4567
4568 "NOTIFY:CHANNEL_INFO:<sampler-channel>"
4569
4570 where <sampler-channel> will be replaced by the sampler channel the
4571 channel info change occurred. The front-end will have to send the
4572 respective command to actually get the channel info. Because these
4573 messages will be triggered by LSCP commands issued by other clients
4574 rather than real time events happening on the server, it is believed
4575 that an empty notification message is sufficient here.
4576
4577 8.6. Total number of active voices changed
4578
4579 Client may want to be notified when the total number of voices on the
4580 back-end changes by issuing the following command:
4581
4582 SUBSCRIBE TOTAL_VOICE_COUNT
4583
4584 Server will start sending the following notification messages:
4585
4586
4587
4588
4589
4590
4591 Schoenebeck Expires May 30, 2007 [Page 82]
4592
4593 Internet-Draft LinuxSampler Control Protocol November 2006
4594
4595
4596 "NOTIFY:TOTAL_VOICE_COUNT:<voices>
4597
4598 where <voices> will be replaced by the new number of all currently
4599 active voices.
4600
4601 8.7. Miscellaneous and debugging events
4602
4603 Client may want to be notified of miscellaneous and debugging events
4604 occurring at the server by issuing the following command:
4605
4606 SUBSCRIBE MISCELLANEOUS
4607
4608 Server will start sending the following notification messages:
4609
4610 "NOTIFY:MISCELLANEOUS:<string>"
4611
4612 where <string> will be replaced by whatever data server wants to send
4613 to the client. Client MAY display this data to the user AS IS to
4614 facilitate debugging.
4615
4616
4617
4618
4619
4620
4621
4622
4623
4624
4625
4626
4627
4628
4629
4630
4631
4632
4633
4634
4635
4636
4637
4638
4639
4640
4641
4642
4643
4644
4645
4646
4647 Schoenebeck Expires May 30, 2007 [Page 83]
4648
4649 Internet-Draft LinuxSampler Control Protocol November 2006
4650
4651
4652 9. Security Considerations
4653
4654 As there is so far no method of authentication and authorization
4655 defined and so not required for a client applications to succeed to
4656 connect, running LinuxSampler might be a security risk for the host
4657 system the LinuxSampler instance is running on.
4658
4659
4660
4661
4662
4663
4664
4665
4666
4667
4668
4669
4670
4671
4672
4673
4674
4675
4676
4677
4678
4679
4680
4681
4682
4683
4684
4685
4686
4687
4688
4689
4690
4691
4692
4693
4694
4695
4696
4697
4698
4699
4700
4701
4702
4703 Schoenebeck Expires May 30, 2007 [Page 84]
4704
4705 Internet-Draft LinuxSampler Control Protocol November 2006
4706
4707
4708 10. Acknowledgments
4709
4710 This document has benefited greatly from the comments of the
4711 following people, discussed on the LinuxSampler developer's mailing
4712 list:
4713
4714 Rui Nuno Capela
4715
4716 Vladimir Senkov
4717
4718 Mark Knecht
4719
4720 Grigor Iliev
4721
4722
4723 11. References
4724
4725 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
4726 Requirement Levels", RFC 2119, 1997.
4727
4728 [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
4729 Specifications", RFC 2234, 1997.
4730
4731 [RFC793] Defense Advanced Research Projects Agency, "TRANSMISSION
4732 CONTROL PROTOCOL", RFC 793, 1981.
4733
4734
4735
4736
4737
4738
4739
4740
4741
4742
4743
4744
4745
4746
4747
4748
4749
4750
4751
4752
4753
4754
4755
4756
4757
4758
4759 Schoenebeck Expires May 30, 2007 [Page 85]
4760
4761 Internet-Draft LinuxSampler Control Protocol November 2006
4762
4763
4764 Author's Address
4765
4766 C. Schoenebeck
4767 Interessengemeinschaft Software Engineering e. V.
4768 Max-Planck-Str. 39
4769 74081 Heilbronn
4770 Germany
4771
4772 Email: schoenebeck at software minus engineering dot org
4773
4774
4775
4776
4777
4778
4779
4780
4781
4782
4783
4784
4785
4786
4787
4788
4789
4790
4791
4792
4793
4794
4795
4796
4797
4798
4799
4800
4801
4802
4803
4804
4805
4806
4807
4808
4809
4810
4811
4812
4813
4814
4815 Schoenebeck Expires May 30, 2007 [Page 86]
4816
4817 Internet-Draft LinuxSampler Control Protocol November 2006
4818
4819
4820 Intellectual Property Statement
4821
4822 The IETF takes no position regarding the validity or scope of any
4823 intellectual property or other rights that might be claimed to
4824 pertain to the implementation or use of the technology described in
4825 this document or the extent to which any license under such rights
4826 might or might not be available; neither does it represent that it
4827 has made any effort to identify any such rights. Information on the
4828 IETF's procedures with respect to rights in standards-track and
4829 standards-related documentation can be found in BCP 11. Copies of
4830 claims of rights made available for publication and any assurances of
4831 licenses to be made available, or the result of an attempt made to
4832 obtain a general license or permission for the use of such
4833 proprietary rights by implementors or users of this specification can
4834 be obtained from the IETF Secretariat.
4835
4836 The IETF invites any interested party to bring to its attention any
4837 copyrights, patents or patent applications, or other proprietary
4838 rights which may cover technology that may be required to practice
4839 this standard. Please address the information to the IETF Executive
4840 Director.
4841
4842
4843 Full Copyright Statement
4844
4845 Copyright (C) The Internet Society (2006). All Rights Reserved.
4846
4847 This document and translations of it may be copied and furnished to
4848 others, and derivative works that comment on or otherwise explain it
4849 or assist in its implementation may be prepared, copied, published
4850 and distributed, in whole or in part, without restriction of any
4851 kind, provided that the above copyright notice and this paragraph are
4852 included on all such copies and derivative works. However, this
4853 document itself may not be modified in any way, such as by removing
4854 the copyright notice or references to the Internet Society or other
4855 Internet organizations, except as needed for the purpose of
4856 developing Internet standards in which case the procedures for
4857 copyrights defined in the Internet Standards process must be
4858 followed, or as required to translate it into languages other than
4859 English.
4860
4861 The limited permissions granted above are perpetual and will not be
4862 revoked by the Internet Society or its successors or assignees.
4863
4864 This document and the information contained herein is provided on an
4865 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
4866 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
4867 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
4868
4869
4870
4871 Schoenebeck Expires May 30, 2007 [Page 87]
4872
4873 Internet-Draft LinuxSampler Control Protocol November 2006
4874
4875
4876 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
4877 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
4878
4879
4880 Acknowledgment
4881
4882 Funding for the RFC Editor function is currently provided by the
4883 Internet Society.
4884
4885
4886
4887
4888
4889
4890
4891
4892
4893
4894
4895
4896
4897
4898
4899
4900
4901
4902
4903
4904
4905
4906
4907
4908
4909
4910
4911
4912
4913
4914
4915
4916
4917
4918
4919
4920
4921
4922
4923
4924
4925
4926
4927 Schoenebeck Expires May 30, 2007 [Page 88]
4928

  ViewVC Help
Powered by ViewVC