/[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 575 - (show annotations) (download)
Tue May 24 03:26:22 2005 UTC (18 years, 10 months ago) by schoenebeck
File MIME type: text/plain
File size: 114037 byte(s)
- LSCP syntax (BNF) is now auto generated
- tagged LSCP specification as version 1.0
- minor cleanup

1
2
3 LinuxSampler Developers C. Schoenebeck
4 Internet-Draft Interessengemeinschaft Software
5 Expires: November 22, 2005 Engineering e. V.
6 May 24, 2005
7
8
9 LinuxSampler Control Protocol
10 LSCP 1.0
11
12 Status of this Memo
13
14 This document is an Internet-Draft and is in full conformance with
15 all provisions of Section 10 of RFC2026.
16
17 Internet-Drafts are working documents of the Internet Engineering
18 Task Force (IETF), its areas, and its working groups. Note that
19 other groups may also distribute working documents as
20 Internet-Drafts.
21
22 Internet-Drafts are draft documents valid for a maximum of six months
23 and may be updated, replaced, or obsoleted by other documents at any
24 time. It is inappropriate to use Internet-Drafts as reference
25 material or to cite them other than as "work in progress."
26
27 The list of current Internet-Drafts can be accessed at
28 http://www.ietf.org/ietf/1id-abstracts.txt.
29
30 The list of Internet-Draft Shadow Directories can be accessed at
31 http://www.ietf.org/shadow.html.
32
33 This Internet-Draft will expire on November 22, 2005.
34
35 Copyright Notice
36
37 Copyright (C) The Internet Society (2005). All Rights Reserved.
38
39 Abstract
40
41 The LinuxSampler Control Protocol (LSCP) is an application-level
42 protocol primarily intended for local and remote controlling the
43 LinuxSampler backend application, which is a sophisticated
44 server-like console application essentially playing back audio
45 samples and manipulating the samples in real time to certain extent.
46
47
48
49
50
51
52
53
54
55 Schoenebeck Expires November 22, 2005 [Page 1]
56
57 Internet-Draft LinuxSampler Control Protocol May 2005
58
59
60 Table of Contents
61
62 1. Requirements notation . . . . . . . . . . . . . . . . . . . 4
63 2. Versioning of this specification . . . . . . . . . . . . . . 5
64 3. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6
65 4. Focus of this protocol . . . . . . . . . . . . . . . . . . . 7
66 5. Communication Overview . . . . . . . . . . . . . . . . . . . 8
67 5.1 Request/response communication method . . . . . . . . . . 8
68 5.1.1 Result format . . . . . . . . . . . . . . . . . . . . 9
69 5.2 Subscribe/notify communication method . . . . . . . . . . 10
70 6. Description for control commands . . . . . . . . . . . . . . 13
71 6.1 Ignored lines and comments . . . . . . . . . . . . . . . . 13
72 6.2 Configuring audio drivers . . . . . . . . . . . . . . . . 13
73 6.2.1 Getting amount of available audio output drivers . . . 13
74 6.2.2 Getting all available audio output drivers . . . . . . 14
75 6.2.3 Getting information about a specific audio output
76 driver . . . . . . . . . . . . . . . . . . . . . . . . 14
77 6.2.4 Getting information about specific audio output
78 driver parameter . . . . . . . . . . . . . . . . . . . 15
79 6.2.5 Creating an audio output device . . . . . . . . . . . 18
80 6.2.6 Destroying an audio output device . . . . . . . . . . 18
81 6.2.7 Getting all created audio output device count . . . . 19
82 6.2.8 Getting all created audio output device list . . . . . 19
83 6.2.9 Getting current settings of an audio output device . . 20
84 6.2.10 Changing settings of audio output devices . . . . . 21
85 6.2.11 Getting information about an audio channel . . . . . 21
86 6.2.12 Getting information about specific audio channel
87 parameter . . . . . . . . . . . . . . . . . . . . . 23
88 6.2.13 Changing settings of audio output channels . . . . . 24
89 6.3 Configuring MIDI input drivers . . . . . . . . . . . . . . 25
90 6.3.1 Getting amount of available MIDI input drivers . . . . 26
91 6.3.2 Getting all available MIDI input drivers . . . . . . . 26
92 6.3.3 Getting information about a specific MIDI input
93 driver . . . . . . . . . . . . . . . . . . . . . . . . 26
94 6.3.4 Getting information about specific MIDI input
95 driver parameter . . . . . . . . . . . . . . . . . . . 27
96 6.3.5 Creating a MIDI input device . . . . . . . . . . . . . 29
97 6.3.6 Destroying a MIDI input device . . . . . . . . . . . . 30
98 6.3.7 Getting all created MIDI input device count . . . . . 30
99 6.3.8 Getting all created MIDI input device list . . . . . . 31
100 6.3.9 Getting current settings of a MIDI input device . . . 31
101 6.3.10 Changing settings of MIDI input devices . . . . . . 32
102 6.3.11 Getting information about a MIDI port . . . . . . . 33
103 6.3.12 Getting information about specific MIDI port
104 parameter . . . . . . . . . . . . . . . . . . . . . 33
105 6.3.13 Changing settings of MIDI input ports . . . . . . . 35
106 6.4 Configuring sampler channels . . . . . . . . . . . . . . . 35
107 6.4.1 Loading an instrument . . . . . . . . . . . . . . . . 35
108
109
110
111 Schoenebeck Expires November 22, 2005 [Page 2]
112
113 Internet-Draft LinuxSampler Control Protocol May 2005
114
115
116 6.4.2 Loading a sampler engine . . . . . . . . . . . . . . . 36
117 6.4.3 Getting all created sampler channel count . . . . . . 37
118 6.4.4 Getting all created sampler channel list . . . . . . . 37
119 6.4.5 Adding a new sampler channel . . . . . . . . . . . . . 38
120 6.4.6 Removing a sampler channel . . . . . . . . . . . . . . 39
121 6.4.7 Getting amount of available engines . . . . . . . . . 39
122 6.4.8 Getting all available engines . . . . . . . . . . . . 39
123 6.4.9 Getting information about an engine . . . . . . . . . 40
124 6.4.10 Getting sampler channel information . . . . . . . . 41
125 6.4.11 Current number of active voices . . . . . . . . . . 42
126 6.4.12 Current number of active disk streams . . . . . . . 43
127 6.4.13 Current fill state of disk stream buffers . . . . . 43
128 6.4.14 Setting audio output device . . . . . . . . . . . . 44
129 6.4.15 Setting audio output type . . . . . . . . . . . . . 45
130 6.4.16 Setting audio output channel . . . . . . . . . . . . 45
131 6.4.17 Setting MIDI input device . . . . . . . . . . . . . 46
132 6.4.18 Setting MIDI input type . . . . . . . . . . . . . . 46
133 6.4.19 Setting MIDI input port . . . . . . . . . . . . . . 47
134 6.4.20 Setting MIDI input channel . . . . . . . . . . . . . 48
135 6.4.21 Setting channel volume . . . . . . . . . . . . . . . 48
136 6.4.22 Resetting a sampler channel . . . . . . . . . . . . 49
137 6.5 Controlling connection . . . . . . . . . . . . . . . . . . 49
138 6.5.1 Register front-end for receiving event messages . . . 49
139 6.5.2 Unregister front-end for not receiving event
140 messages . . . . . . . . . . . . . . . . . . . . . . . 50
141 6.5.3 Enable or disable echo of commands . . . . . . . . . . 51
142 6.5.4 Close client connection . . . . . . . . . . . . . . . 51
143 6.6 Global commands . . . . . . . . . . . . . . . . . . . . . 51
144 6.6.1 Reset sampler . . . . . . . . . . . . . . . . . . . . 51
145 6.6.2 General sampler informations . . . . . . . . . . . . . 52
146 7. Command Syntax . . . . . . . . . . . . . . . . . . . . . . . 53
147 8. Events . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
148 8.1 Number of sampler channels changed . . . . . . . . . . . . 58
149 8.2 Number of active voices changed . . . . . . . . . . . . . 58
150 8.3 Number of active disk streams changed . . . . . . . . . . 58
151 8.4 Disk stream buffer fill state changed . . . . . . . . . . 59
152 8.5 Channel information changed . . . . . . . . . . . . . . . 59
153 8.6 Miscellaneous and debugging events . . . . . . . . . . . . 59
154 9. Security Considerations . . . . . . . . . . . . . . . . . . 61
155 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 62
156 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 62
157 Author's Address . . . . . . . . . . . . . . . . . . . . . . 62
158 Intellectual Property and Copyright Statements . . . . . . . 63
159
160
161
162
163
164
165
166
167 Schoenebeck Expires November 22, 2005 [Page 3]
168
169 Internet-Draft LinuxSampler Control Protocol May 2005
170
171
172 1. Requirements notation
173
174 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
175 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
176 document are to be interpreted as described in [RFC2119].
177
178 This protocol is always case-sensitive if not explicitly claimed the
179 opposite.
180
181 In examples, "C:" and "S:" indicate lines sent by the client
182 (front-end) and server (LinuxSampler) respectively. Lines in
183 examples must be interpreted as every line being CRLF terminated
184 (carriage return character followed by line feed character as defined
185 in the ASCII standard), thus the following example:
186
187 C: "some line"
188 "another line"
189
190 must actually be interpreted as client sending the following message:
191
192 "some line<CR><LF>another line<CR><LF>"
193
194 where <CR> symbolizes the carriage return character and <LF> the line
195 feed character as defined in the ASCII standard.
196
197 Due to technical reasons, messages can arbitrary be fragmented, means
198 the following example:
199
200 S: "abcd"
201
202 could also happen to be sent in three messages like in the following
203 sequence scenario:
204
205 o server sending message "a"
206 o followed by a delay (pause) with arbitrary duration
207 o followed by server sending message "bcd<CR>"
208 o again followed by a delay (pause) with arbitrary duration
209 o followed by server sending the message "<LF>"
210
211 where again <CR> and <LF> symbolize the carriage return and line feed
212 characters respectively.
213
214
215
216
217
218
219
220
221
222
223 Schoenebeck Expires November 22, 2005 [Page 4]
224
225 Internet-Draft LinuxSampler Control Protocol May 2005
226
227
228 2. Versioning of this specification
229
230 LSCP will certainly be extended and enhanced by-and-by. Each
231 official release of the LSCP specification will be tagged with a
232 unique version tuple. The version tuple consists at least of a major
233 and minor version number like:
234
235 "1.2"
236
237 In this example the major version number would be "1" and the minor
238 version number would be "2". Note that the version tuple might also
239 have more than two elements. The major version number defines a
240 group of backward compatible versions. That means a frontend is
241 compatible to the connected sampler if and only if the LSCP versions
242 to which each of the two parties complies to, match both of the
243 following rules:
244
245 Compatibility:
246
247 1. The frontend's LSCP major version and the sampler's LSCP major
248 version are exactly equal.
249 2. The frontend's LSCP minor version is less or equal than the
250 sampler's LSCP minor version.
251
252 Compatibility can only be claimed if both rules are true. The
253 frontend can use the "GET SERVER INFO" (Section 6.6.2) command to get
254 the version of the LSCP specification the sampler complies with.
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279 Schoenebeck Expires November 22, 2005 [Page 5]
280
281 Internet-Draft LinuxSampler Control Protocol May 2005
282
283
284 3. Introduction
285
286 LinuxSampler is a so called software sampler application capable to
287 playback audio samples from a computer's Random Access Memory (RAM)
288 as well as directly streaming it from disk. LinuxSampler is designed
289 to be modular. It provides several so called "sampler engines" where
290 each engine is specialized for a certain purpose. LinuxSampler has
291 virtual channels which will be referred in this document as "sampler
292 channels". The channels are in such way virtual as they can be
293 connected to an arbitrary MIDI input method and arbitrary MIDI
294 channel (e.g. sampler channel 17 could be connected to an ALSA
295 sequencer device 64:0 and listening to MIDI channel 1 there). Each
296 sampler channel will be associated with an instance of one of the
297 available sampler engines (e.g. GigEngine, DLSEngine). The audio
298 output of each sampler channel can be routed to an arbitrary audio
299 output method (ALSA / JACK) and an arbitrary audio output channel
300 there.
301
302
303
304
305
306
307
308
309
310
311
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 November 22, 2005 [Page 6]
336
337 Internet-Draft LinuxSampler Control Protocol May 2005
338
339
340 4. Focus of this protocol
341
342 Main focus of this protocol is to provide a way to configure a
343 running LinuxSampler instance and to retrieve information about it.
344 The focus of this protocol is not to provide a way to control
345 synthesis parameters or even to trigger or release notes. Or in
346 other words; the focus are those functionalities which are not
347 covered by MIDI or which may at most be handled via MIDI System
348 Exclusive Messages.
349
350
351
352
353
354
355
356
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 November 22, 2005 [Page 7]
392
393 Internet-Draft LinuxSampler Control Protocol May 2005
394
395
396 5. Communication Overview
397
398 There are two distinct methods of communication between a running
399 instance of LinuxSampler and one or more control applications, so
400 called "front-ends": a simple request/response communication method
401 used by the clients to give commands to the server as well as to
402 inquire about server's status and a subscribe/notify communication
403 method used by the client to subscribe to and receive notifications
404 of certain events as they happen on the server. The latter needs
405 more effort to be implemented in the front-end application. The two
406 communication methods will be described next.
407
408 5.1 Request/response communication method
409
410 This simple communication method is based on TCP [RFC793]. The
411 front-end application establishes a TCP connection to the
412 LinuxSampler instance on a certain host system. Then the front-end
413 application will send certain ASCII based commands as defined in this
414 document (every command line must be CRLF terminated - see
415 "Conventions used in this document" at the beginning of this
416 document) and the LinuxSampler application will response after a
417 certain process time with an appropriate ASCII based answer, also as
418 defined in this document. So this TCP communication is simply based
419 on query and answer paradigm. That way LinuxSampler is only able to
420 answer on queries from front-ends, but not able to automatically send
421 messages to the client if it's not asked to. The fronted should not
422 reconnect to LinuxSampler for every single command, instead it should
423 keep the connection established and simply resend message(s) for
424 subsequent commands. To keep information in the front-end up-to-date
425 the front-end has to periodically send new requests to get the
426 current information from the LinuxSampler instance. This is often
427 referred to as "polling". While polling is simple to implement and
428 may be OK to use in some cases, there may be disadvantages to polling
429 such as network traffic overhead and information being out of date.
430 It is possible for a client or several clients to open more than one
431 connection to the server at the same time. It is also possible to
432 send more than one request to the server at the same time but if
433 those requests are sent over the same connection server MUST execute
434 them sequentially. Upon executing a request server will produce a
435 result set and send it to the client. Each and every request made by
436 the client MUST result in a result set being sent back to the client.
437 No other data other than a result set may be sent by a server to a
438 client. No result set may be sent to a client without the client
439 sending request to the server first. On any particular connection,
440 result sets MUST be sent in their entirety without being interrupted
441 by other result sets. If several requests got queued up at the
442 server they MUST be processed in the order they were received and
443 result sets MUST be sent back in the same order.
444
445
446
447 Schoenebeck Expires November 22, 2005 [Page 8]
448
449 Internet-Draft LinuxSampler Control Protocol May 2005
450
451
452 5.1.1 Result format
453
454 Result set could be one of the following types:
455
456 1. Normal
457 2. Warning
458 3. Error
459
460 Warning and Error result sets MUST be single line and have the
461 following format:
462
463 o "WRN:<warning-code>:<warning-message>"
464 o "ERR:<error-code>:<error-message>"
465
466 Where <warning-code> and <error-code> are numeric unique identifiers
467 of the warning or error and <warning-message> and <error-message> are
468 human readable descriptions of the warning or error respectively.
469
470 Examples:
471
472 C: "LOAD INSTRUMENT '/home/me/Boesendorfer24bit.gig" 0 0
473 S: "WRN:32:This is a 24 bit patch which is not supported natively
474 yet."
475
476 C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA EAR"
477 S: "ERR:3456:Audio output driver 'ALSA' does not have a parameter
478 'EAR'."
479
480 C: "GET AUDIO_OUTPUT_DEVICE INFO 123456"
481 S: "ERR:9:There is no audio output device with index 123456."
482
483 Normal result sets could be:
484
485 1. Empty
486 2. Single line
487 3. Multi-line
488
489 Empty result set is issued when the server only needed to acknowledge
490 the fact that the request was received and it was processed
491 successfully and no additional information is available. This result
492 set has the following format:
493
494 "OK"
495
496 Example:
497
498 C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 CHANNELS=4"
499
500
501
502
503 Schoenebeck Expires November 22, 2005 [Page 9]
504
505 Internet-Draft LinuxSampler Control Protocol May 2005
506
507
508 S: "OK"
509
510 Single line result sets are command specific. One example of a
511 single line result set is an empty line. Multi-line result sets are
512 command specific and may include one or more lines of information.
513 They MUST always end with the following line:
514
515 "."
516
517 Example:
518
519 C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
520 S: "DRIVER: ALSA"
521 "CHANNELS: 2"
522 "SAMPLERATE: 44100"
523 "ACTIVE: true"
524 "FRAGMENTS: 2"
525 "FRAGMENTSIZE: 128"
526 "CARD: '0,0'"
527 "."
528
529 In addition to above mentioned formats, warnings and empty result
530 sets MAY be indexed. In this case, they have the following formats
531 respectively:
532
533 o "WRN[<index>]:<warning-code>:<warning-message>"
534 o "OK[<index>]"
535
536 where <index> is command specific and is used to indicate channel
537 number that the result set was related to or other integer value.
538
539 Each line of the result set MUST end with <CRLF>.
540
541 Examples:
542
543 C: "ADD CHANNEL"
544 S: "OK[12]"
545
546 C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"
547 S: "WRN[0]:32:Sample rate not supported, using 44100 instead."
548
549 5.2 Subscribe/notify communication method
550
551 This more sophisticated communication method is actually only an
552 extension of the simple request/response communication method. The
553 front-end still uses a TCP connection and sends the same commands on
554 the TCP connection. Two extra commands are SUBSCRIBE and UNSUBSCRIBE
555 commands that allow a client to tell the server that it is interested
556
557
558
559 Schoenebeck Expires November 22, 2005 [Page 10]
560
561 Internet-Draft LinuxSampler Control Protocol May 2005
562
563
564 in receiving notifications about certain events as they happen on the
565 server. The SUBSCRIBE command has the following syntax:
566
567 SUBSCRIBE <event-id>
568
569 where <event-id> will be replaced by the respective event that client
570 wants to subscribe to. Upon receiving such request, server SHOULD
571 respond with OK and start sending EVENT notifications when a given
572 even has occurred to the front-end when an event has occurred. It
573 MAY be possible certain events may be sent before OK response during
574 real time nature of their generation. Event messages have the
575 following format:
576
577 NOTIFY:<event-id>:<custom-event-data>
578
579 where <event-id> uniquely identifies the event that has occurred and
580 <custom-event-data> is event specific.
581
582 Several rules must be followed by the server when generating events:
583
584 1. Events MUST NOT be sent to any client who has not issued an
585 appropriate SUBSCRIBE command.
586 2. Events MUST only be sent using the same connection that was used
587 to subscribe to them.
588 3. When response is being sent to the client, event MUST be inserted
589 in the stream before or after the response, but NOT in the
590 middle. Same is true about the response. It should never be
591 inserted in the middle of the event message as well as any other
592 response.
593
594 If the client is not interested in a particular event anymore it MAY
595 issue UNSUBSCRIBE command using the following syntax:
596
597 UNSUBSCRIBE <event-id>
598
599 where <event-id> will be replace by the respective event that client
600 is no longer interested in receiving. For a list of supported events
601 see Section 8.
602
603 Example: the fill states of disk stream buffers have changed on
604 sampler channel 4 and the LinuxSampler instance will react by sending
605 the following message to all clients who subscribed to this event:
606
607 NOTIFY:CHANNEL_BUFFER_FILL:4 [35]62%,[33]80%,[37]98%
608
609 Which means there are currently three active streams on sampler
610 channel 4, where the stream with ID "35" is filled by 62%, stream
611 with ID 33 is filled by 80% and stream with ID 37 is filled by 98%.
612
613
614
615 Schoenebeck Expires November 22, 2005 [Page 11]
616
617 Internet-Draft LinuxSampler Control Protocol May 2005
618
619
620 Clients may choose to open more than one connection to the server and
621 use some connections to receive notifications while using other
622 connections to issue commands to the back-end. This is entirely
623 legal and up to the implementation. This does not change the
624 protocol in any way and no special restrictions exist on the server
625 to allow or disallow this or to track what connections belong to what
626 front-ends. Server will listen on a single port, accept multiple
627 connections and support protocol described in this specification in
628 it's entirety on this single port on each connection that it
629 accepted.
630
631 Due to the fact that TCP is used for this communication, dead peers
632 will be detected automatically by the OS TCP stack. While it may
633 take a while to detect dead peers if no traffic is being sent from
634 server to client (TCP keep-alive timer is set to 2 hours on many
635 OSes) it will not be an issue here as when notifications are sent by
636 the server, dead client will be detected quickly.
637
638 When connection is closed for any reason server MUST forget all
639 subscriptions that were made on this connection. If client
640 reconnects it MUST resubscribe to all events that it wants to
641 receive.
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671 Schoenebeck Expires November 22, 2005 [Page 12]
672
673 Internet-Draft LinuxSampler Control Protocol May 2005
674
675
676 6. Description for control commands
677
678 This chapter will describe the available control commands that can be
679 sent on the TCP connection in detail. Some certain commands (e.g.
680 "GET CHANNEL INFO" (Section 6.4.10) or "GET ENGINE INFO" (Section
681 6.4.9)) lead to multiple-line responses. In this case LinuxSampler
682 signals the end of the response by a "." (single dot) line.
683
684 6.1 Ignored lines and comments
685
686 White lines, that is lines which only contain space and tabulator
687 characters, and lines that start with a "#" character are ignored,
688 thus it's possible for example to group commands and to place
689 comments in a LSCP script file.
690
691 6.2 Configuring audio drivers
692
693 Instances of drivers in LinuxSampler are called devices. You can use
694 multiple audio devices simultaneously, e.g. to output the sound of
695 one sampler channel using the ALSA audio output driver, and on
696 another sampler channel you might want to use the JACK audio output
697 driver. For particular audio output systems it's also possible to
698 create several devices of the same audio output driver, e.g. two
699 separate ALSA audio output devices for using two different sound
700 cards at the same time. This chapter describes all commands to
701 configure LinuxSampler's audio output devices and their parameters.
702
703 Instead of defining commands and parameters for each driver
704 individually, all possible parameters, their meanings and possible
705 values have to be obtained at runtime. This makes the protocol a bit
706 abstract, but has the advantage, that front-ends can be written
707 independently of what drivers are currently implemented and what
708 parameters these drivers are actually offering. This means
709 front-ends can even handle drivers which are implemented somewhere in
710 future without modifying the front-end at all.
711
712 Note: examples in this chapter showing particular parameters of
713 drivers are not meant as specification of the drivers' parameters.
714 Driver implementations in LinuxSampler might have complete different
715 parameter names and meanings than shown in these examples or might
716 change in future, so these examples are only meant for showing how to
717 retrieve what parameters drivers are offering, how to retrieve their
718 possible values, etc.
719
720 6.2.1 Getting amount of available audio output drivers
721
722 Use the following command to get the number of audio output drivers
723 currently available for the LinuxSampler instance:
724
725
726
727 Schoenebeck Expires November 22, 2005 [Page 13]
728
729 Internet-Draft LinuxSampler Control Protocol May 2005
730
731
732 GET AVAILABLE_AUDIO_OUTPUT_DRIVERS
733
734 Possible Answers:
735
736 LinuxSampler will answer by sending the number of audio output
737 drivers.
738
739 Example:
740
741 C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
742 S: "2"
743
744 6.2.2 Getting all available audio output drivers
745
746 Use the following command to list all audio output drivers currently
747 available for the LinuxSampler instance:
748
749 LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS
750
751 Possible Answers:
752
753 LinuxSampler will answer by sending comma separated character
754 strings, each symbolizing an audio output driver.
755
756 Example:
757
758 C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"
759 S: "ALSA,JACK"
760
761 6.2.3 Getting information about a specific audio output driver
762
763 Use the following command to get detailed information about a
764 specific audio output driver:
765
766 GET AUDIO_OUTPUT_DRIVER INFO <audio-output-driver>
767
768 Where <audio-output-driver> is the name of the audio output driver,
769 returned by the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2)
770 command.
771
772 Possible Answers:
773
774 LinuxSampler will answer by sending a <CRLF> separated list. Each
775 answer line begins with the information category name followed by
776 a colon and then a space character <SP> and finally the info
777 character string to that info category. At the moment the
778 following information categories are defined:
779
780
781
782
783 Schoenebeck Expires November 22, 2005 [Page 14]
784
785 Internet-Draft LinuxSampler Control Protocol May 2005
786
787
788
789 DESCRIPTION -
790 character string describing the audio output driver
791 VERSION -
792 character string reflecting the driver's version
793 PARAMETERS -
794 comma separated list of all parameters available for the
795 given audio output driver, at least parameters 'channels',
796 'samplerate' and 'active' are offered by all audio output
797 drivers
798 The mentioned fields above don't have to be in particular order.
799
800 Example:
801
802 C: "GET AUDIO_OUTPUT_DRIVER INFO ALSA"
803 S: "DESCRIPTION: Advanced Linux Sound Architecture"
804 "VERSION: 1.0"
805 "PARAMETERS: DRIVER,CHANNELS,SAMPLERATE,ACTIVE,FRAGMENTS,
806 FRAGMENTSIZE,CARD"
807 "."
808
809 6.2.4 Getting information about specific audio output driver parameter
810
811 Use the following command to get detailed information about a
812 specific audio output driver parameter:
813
814 GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO <audio> <prm> [<deplist>]
815
816 Where <audio> is the name of the audio output driver as returned by
817 the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2) command,
818 <prm> a specific parameter name for which information should be
819 obtained (as returned by the "GET AUDIO_OUTPUT_DRIVER INFO" (Section
820 6.2.3) command) and <deplist> is an optional list of parameters on
821 which the sought parameter <prm> depends on, <deplist> is a list of
822 key-value pairs in form of "key1=val1 key2=val2 ...", where character
823 string values are encapsulated into apostrophes ('). Arguments given
824 with <deplist> which are not dependency parameters of <prm> will be
825 ignored, means the front-end application can simply put all
826 parameters into <deplist> with the values already selected by the
827 user.
828
829 Possible Answers:
830
831 LinuxSampler will answer by sending a <CRLF> separated list. Each
832 answer line begins with the information category name followed by
833 a colon and then a space character <SP> and finally the info
834 character string to that info category. There are information
835 which is always returned, independently of the given driver
836
837
838
839 Schoenebeck Expires November 22, 2005 [Page 15]
840
841 Internet-Draft LinuxSampler Control Protocol May 2005
842
843
844 parameter and there are optional information which is only shown
845 dependently to given driver parameter. At the moment the
846 following information categories are defined:
847
848 TYPE -
849 either "BOOL" for boolean value(s) or "INT" for integer
850 value(s) or "FLOAT" for dotted number(s) or "STRING" for
851 character string(s) (always returned, no matter which driver
852 parameter)
853 DESCRIPTION -
854 arbitrary text describing the purpose of the parameter (always
855 returned, no matter which driver parameter)
856 MANDATORY -
857 either true or false, defines if this parameter must be given
858 when the device is to be created with the 'CREATE
859 AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command (always returned,
860 no matter which driver parameter)
861 FIX -
862 either true or false, if false then this parameter can be
863 changed at any time, once the device is created by the 'CREATE
864 AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command (always returned,
865 no matter which driver parameter)
866 MULTIPLICITY -
867 either true or false, defines if this parameter allows only one
868 value or a list of values, where true means multiple values and
869 false only a single value allowed (always returned, no matter
870 which driver parameter)
871 DEPENDS -
872 comma separated list of parameters this parameter depends on,
873 means the values for fields 'DEFAULT', 'RANGE_MIN', 'RANGE_MAX'
874 and 'POSSIBILITIES' might depend on these listed parameters,
875 for example assuming that an audio driver (like the ALSA
876 driver) offers parameters 'card' and 'samplerate' then
877 parameter 'samplerate' would depend on 'card' because the
878 possible values for 'samplerate' depends on the sound card
879 which can be chosen by the 'card' parameter (optionally
880 returned, dependent to driver parameter)
881 DEFAULT -
882 reflects the default value for this parameter which is used
883 when the device is created and not explicitly given with the
884 'CREATE AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command, in case
885 of MULTIPLCITY=true, this is a comma separated list, that's why
886 character strings are encapsulated into apostrophes (')
887 (optionally returned, dependent to driver parameter)
888 RANGE_MIN -
889 defines lower limit of the allowed value range for this
890 parameter, can be an integer value as well as a dotted number,
891 this parameter is often used in conjunction with RANGE_MAX, but
892
893
894
895 Schoenebeck Expires November 22, 2005 [Page 16]
896
897 Internet-Draft LinuxSampler Control Protocol May 2005
898
899
900 may also appear without (optionally returned, dependent to
901 driver parameter)
902 RANGE_MAX -
903 defines upper limit of the allowed value range for this
904 parameter, can be an integer value as well as a dotted number,
905 this parameter is often used in conjunction with RANGE_MIN, but
906 may also appear without (optionally returned, dependent to
907 driver parameter)
908 POSSIBILITIES -
909 comma separated list of possible values for this parameter,
910 character strings are encapsulated into apostrophes (optionally
911 returned, dependent to driver parameter)
912
913 The mentioned fields above don't have to be in particular order.
914
915 Examples:
916
917 C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA CARD"
918 S: "DESCRIPTION: sound card to be used"
919 "TYPE: STRING"
920 "MANDATORY: false"
921 "FIX: true"
922 "MULTIPLICITY: false"
923 "DEFAULT: '0,0'"
924 "POSSIBILITIES: '0,0','1,0','2,0'"
925 "."
926
927 C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE"
928 S: "DESCRIPTION: output sample rate in Hz"
929 "TYPE: INT"
930 "MANDATORY: false"
931 "FIX: false"
932 "MULTIPLICITY: false"
933 "DEPENDS: card"
934 "DEFAULT: 44100"
935 "."
936
937 C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE
938 CARD='0,0'"
939 S: "DESCRIPTION: output sample rate in Hz"
940 "TYPE: INT"
941 "MANDATORY: false"
942 "FIX: false"
943 "MULTIPLICITY: false"
944 "DEPENDS: card"
945 "DEFAULT: 44100"
946 "RANGE_MIN: 22050"
947
948
949
950
951 Schoenebeck Expires November 22, 2005 [Page 17]
952
953 Internet-Draft LinuxSampler Control Protocol May 2005
954
955
956 "RANGE_MAX: 96000"
957 "."
958
959 6.2.5 Creating an audio output device
960
961 Use the following command to create a new audio output device for
962 the desired audio output system:
963
964 CREATE AUDIO_OUTPUT_DEVICE <audio-output-driver> [<param-list>]
965
966 Where <audio-output-driver> should be replaced by the desired audio
967 output system as returned by the "LIST
968 AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2) command and
969 <param-list> by an optional list of driver specific parameters in
970 form of "key1=val1 key2=val2 ...", where character string values
971 should be encapsulated into apostrophes ('). Note that there might
972 be drivers which require parameter(s) to be given with this command.
973 Use the previously described commands in this chapter to get this
974 information.
975
976 Possible Answers:
977
978 "OK[<device-id>]" -
979 in case the device was successfully created, where <device-id>
980 is the numerical ID of the new device
981 "WRN[<device-id>]:<warning-code>:<warning-message>" -
982 in case the device was created successfully, where <device-id>
983 is the numerical ID of the new device, but there are noteworthy
984 issue(s) related (e.g. sound card doesn't support given
985 hardware parameters and the driver is using fall-back values),
986 providing an appropriate warning code and warning message
987 "ERR:<error-code>:<error-message>" -
988 in case it failed, providing an appropriate error code and
989 error message
990
991 Examples:
992
993 C: "CREATE AUDIO_OUTPUT_DEVICE ALSA"
994 S: "OK[0]"
995
996 C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"
997 S: "OK[1]"
998
999 6.2.6 Destroying an audio output device
1000
1001 Use the following command to destroy a created output device:
1002
1003
1004
1005
1006
1007 Schoenebeck Expires November 22, 2005 [Page 18]
1008
1009 Internet-Draft LinuxSampler Control Protocol May 2005
1010
1011
1012 DESTROY AUDIO_OUTPUT_DEVICE <device-id>
1013
1014 Where <device-id> should be replaced by the numerical ID of the audio
1015 output device as given by the "CREATE AUDIO_OUTPUT_DEVICE" (Section
1016 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command.
1017
1018 Possible Answers:
1019
1020 "OK" -
1021 in case the device was successfully destroyed
1022 "WRN:<warning-code>:<warning-message>" -
1023 in case the device was destroyed successfully, but there are
1024 noteworthy issue(s) related (e.g. an audio over ethernet
1025 driver was unloaded but the other host might not be informed
1026 about this situation), providing an appropriate warning code
1027 and warning message
1028 "ERR:<error-code>:<error-message>" -
1029 in case it failed, providing an appropriate error code and
1030 error message
1031
1032 Example:
1033
1034 C: "DESTROY AUDIO_OUTPUT_DEVICE 0"
1035 S: "OK"
1036
1037 6.2.7 Getting all created audio output device count
1038
1039 Use the following command to count all created audio output devices:
1040
1041 GET AUDIO_OUTPUT_DEVICES
1042
1043 Possible Answers:
1044
1045 LinuxSampler will answer by sending the current number of all
1046 audio output devices.
1047
1048 Example:
1049
1050 C: "GET AUDIO_OUTPUT_DEVICES"
1051 S: "4"
1052
1053 6.2.8 Getting all created audio output device list
1054
1055 Use the following command to list all created audio output devices:
1056
1057 LIST AUDIO_OUTPUT_DEVICES
1058
1059 Possible Answers:
1060
1061
1062
1063 Schoenebeck Expires November 22, 2005 [Page 19]
1064
1065 Internet-Draft LinuxSampler Control Protocol May 2005
1066
1067
1068 LinuxSampler will answer by sending a comma separated list with
1069 the numerical IDs of all audio output devices.
1070
1071 Example:
1072
1073 C: "LIST AUDIO_OUTPUT_DEVICES"
1074 S: "0,1,4,5"
1075
1076 6.2.9 Getting current settings of an audio output device
1077
1078 Use the following command to get current settings of a specific,
1079 created audio output device:
1080
1081 GET AUDIO_OUTPUT_DEVICE INFO <device-id>
1082
1083 Where <device-id> should be replaced by numerical ID of the audio
1084 output device as e.g. returned by the "LIST AUDIO_OUTPUT_DEVICES"
1085 (Section 6.2.8) command.
1086
1087 Possible Answers:
1088
1089 LinuxSampler will answer by sending a <CRLF> separated list. Each
1090 answer line begins with the information category name followed by a
1091 colon and then a space character <SP> and finally the info character
1092 string to that info category. As some parameters might allow
1093 multiple values, character strings are encapsulated into apostrophes
1094 ('). At the moment the following information categories are defined
1095 (independently of device):
1096
1097 DRIVER -
1098 identifier of the used audio output driver, as also returned by
1099 the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2)
1100 command
1101 CHANNELS -
1102 amount of audio output channels this device currently offers
1103 SAMPLERATE -
1104 playback sample rate the device uses
1105 ACTIVE -
1106 either true or false, if false then the audio device is
1107 inactive and doesn't output any sound, nor do the sampler
1108 channels connected to this audio device render any audio
1109
1110 The mentioned fields above don't have to be in particular order. The
1111 fields above are only those fields which are returned by all audio
1112 output devices. Every audio output driver might have its own,
1113 additional driver specific parameters (see Section 6.2.3) which are
1114 also returned by this command.
1115
1116
1117
1118
1119 Schoenebeck Expires November 22, 2005 [Page 20]
1120
1121 Internet-Draft LinuxSampler Control Protocol May 2005
1122
1123
1124 Example:
1125
1126 C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
1127 S: "DRIVER: ALSA"
1128 "CHANNELS: 2"
1129 "SAMPLERATE: 44100"
1130 "ACTIVE: true"
1131 "FRAGMENTS: 2"
1132 "FRAGMENTSIZE: 128"
1133 "CARD: '0,0'"
1134 "."
1135
1136 6.2.10 Changing settings of audio output devices
1137
1138 Use the following command to alter a specific setting of a created
1139 audio output device:
1140
1141 SET AUDIO_OUTPUT_DEVICE_PARAMETER <device-id> <key>=<value>
1142
1143 Where <device-id> should be replaced by the numerical ID of the audio
1144 output device as given by the "CREATE AUDIO_OUTPUT_DEVICE" (Section
1145 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command, <key>
1146 by the name of the parameter to change and <value> by the new value
1147 for this parameter.
1148
1149 Possible Answers:
1150
1151 "OK" -
1152 in case setting was successfully changed
1153 "WRN:<warning-code>:<warning-message>" -
1154 in case setting was changed successfully, but there are
1155 noteworthy issue(s) related, providing an appropriate warning
1156 code and warning message
1157 "ERR:<error-code>:<error-message>" -
1158 in case it failed, providing an appropriate error code and
1159 error message
1160
1161 Example:
1162
1163 C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"
1164 S: "OK"
1165
1166 6.2.11 Getting information about an audio channel
1167
1168 Use the following command to get information about an audio channel:
1169
1170 GET AUDIO_OUTPUT_CHANNEL INFO <device-id> <audio-chan>
1171
1172
1173
1174
1175 Schoenebeck Expires November 22, 2005 [Page 21]
1176
1177 Internet-Draft LinuxSampler Control Protocol May 2005
1178
1179
1180 Where <device-id> is the numerical ID of the audio output device as
1181 given by the "CREATE AUDIO_OUTPUT_DEVICE" (Section 6.2.5) or "LIST
1182 AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command and <audio-chan> the
1183 audio channel number.
1184
1185 Possible Answers:
1186
1187 LinuxSampler will answer by sending a <CRLF> separated list. Each
1188 answer line begins with the information category name followed by
1189 a colon and then a space character <SP> and finally the info
1190 character string to that info category. At the moment the
1191 following information categories are defined:
1192
1193 NAME -
1194 arbitrary character string naming the channel, which doesn't
1195 have to be unique (always returned by all audio channels)
1196 IS_MIX_CHANNEL -
1197 either true or false, a mix-channel is not a real,
1198 independent audio channel, but a virtual channel which is
1199 mixed to another real channel, this mechanism is needed for
1200 sampler engines which need more audio channels than the used
1201 audio system might be able to offer (always returned by all
1202 audio channels)
1203 MIX_CHANNEL_DESTINATION -
1204 numerical ID (positive integer including 0) which reflects
1205 the real audio channel (of the same audio output device)
1206 this mix channel refers to, means where the audio signal
1207 actually will be routed / added to (only returned in case
1208 the audio channel is mix channel)
1209
1210 The mentioned fields above don't have to be in particular order. The
1211 fields above are only those fields which are generally returned for
1212 the described cases by all audio channels regardless of the audio
1213 driver. Every audio channel might have its own, additional driver
1214 and channel specific parameters.
1215
1216 Examples:
1217
1218 C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 0"
1219 S: "NAME: studio monitor left"
1220 "IS_MIX_CHANNEL: false"
1221 "."
1222
1223 C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 1"
1224 S: "NAME: studio monitor right"
1225 "IS_MIX_CHANNEL: false"
1226 "."
1227
1228
1229
1230
1231 Schoenebeck Expires November 22, 2005 [Page 22]
1232
1233 Internet-Draft LinuxSampler Control Protocol May 2005
1234
1235
1236 C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"
1237 S: "NAME: studio monitor left"
1238 "IS_MIX_CHANNEL: true"
1239 "MIX_CHANNEL_DESTINATION: 1"
1240 "."
1241
1242 C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"
1243 S: "NAME: 'ardour (left)'"
1244 "IS_MIX_CHANNEL: false"
1245 "JACK_BINDINGS: 'ardour:0'"
1246 "."
1247
1248 6.2.12 Getting information about specific audio channel parameter
1249
1250 Use the following command to get detailed information about specific
1251 audio channel parameter:
1252
1253 GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO <dev-id> <chan> <param>
1254
1255 Where <dev-id> is the numerical ID of the audio output device as
1256 returned by the "CREATE AUDIO_OUTPUT_DEVICE" (Section 6.2.5) or "LIST
1257 AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command, <chan> the audio
1258 channel number and <param> a specific channel parameter name for
1259 which information should be obtained (as returned by the "GET
1260 AUDIO_OUTPUT_CHANNEL INFO" (Section 6.2.11) command).
1261
1262 Possible Answers:
1263
1264 LinuxSampler will answer by sending a <CRLF> separated list. Each
1265 answer line begins with the information category name followed by
1266 a colon and then a space character <SP> and finally the info
1267 character string to that info category. There are information
1268 which is always returned, independently of the given channel
1269 parameter and there is optional information which is only shown
1270 dependently to the given audio channel. At the moment the
1271 following information categories are defined:
1272
1273 TYPE -
1274 either "BOOL" for boolean value(s) or "INT" for integer
1275 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1276 character string(s) (always returned)
1277 DESCRIPTION -
1278 arbitrary text describing the purpose of the parameter
1279 (always returned)
1280 FIX -
1281 either true or false, if true then this parameter is read
1282 only, thus cannot be altered (always returned)
1283
1284
1285
1286
1287 Schoenebeck Expires November 22, 2005 [Page 23]
1288
1289 Internet-Draft LinuxSampler Control Protocol May 2005
1290
1291
1292 MULTIPLICITY -
1293 either true or false, defines if this parameter allows only
1294 one value or a list of values, where true means multiple
1295 values and false only a single value allowed (always
1296 returned)
1297 RANGE_MIN -
1298 defines lower limit of the allowed value range for this
1299 parameter, can be an integer value as well as a dotted
1300 number, usually used in conjunction with 'RANGE_MAX', but
1301 may also appear without (optionally returned, dependent to
1302 driver and channel parameter)
1303 RANGE_MAX -
1304 defines upper limit of the allowed value range for this
1305 parameter, can be an integer value as well as a dotted
1306 number, usually used in conjunction with 'RANGE_MIN', but
1307 may also appear without (optionally returned, dependent to
1308 driver and channel parameter)
1309 POSSIBILITIES -
1310 comma separated list of possible values for this parameter,
1311 character strings are encapsulated into apostrophes
1312 (optionally returned, dependent to driver and channel
1313 parameter)
1314 The mentioned fields above don't have to be in particular order.
1315
1316 Example:
1317
1318 C: "GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO 1 0 JACK_BINDINGS"
1319 S: "DESCRIPTION: bindings to other JACK clients"
1320 "TYPE: STRING"
1321 "FIX: false"
1322 "MULTIPLICITY: true"
1323 "POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"
1324 "."
1325
1326 6.2.13 Changing settings of audio output channels
1327
1328 Use the following command to alter a specific setting of an audio
1329 output channel:
1330
1331 SET AUDIO_OUTPUT_CHANNEL_PARAMETER <dev-id> <chn> <key>=<value>
1332
1333 Where <dev-id> should be replaced by the numerical ID of the audio
1334 output device as returned by the "CREATE AUDIO_OUTPUT_DEVICE"
1335 (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
1336 command, <chn> by the audio channel number, <key> by the name of the
1337 parameter to change and <value> by the new value for this parameter.
1338
1339 Possible Answers:
1340
1341
1342
1343 Schoenebeck Expires November 22, 2005 [Page 24]
1344
1345 Internet-Draft LinuxSampler Control Protocol May 2005
1346
1347
1348 "OK" -
1349 in case setting was successfully changed
1350 "WRN:<warning-code>:<warning-message>" -
1351 in case setting was changed successfully, but there are
1352 noteworthy issue(s) related, providing an appropriate warning
1353 code and warning message
1354 "ERR:<error-code>:<error-message>" -
1355 in case it failed, providing an appropriate error code and
1356 error message
1357
1358 Example:
1359
1360 C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"
1361 S: "OK"
1362
1363 C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"
1364 S: "OK"
1365
1366 6.3 Configuring MIDI input drivers
1367
1368 Instances of drivers in LinuxSampler are called devices. You can use
1369 multiple MIDI devices simultaneously, e.g. to use MIDI over ethernet
1370 as MIDI input on one sampler channel and ALSA as MIDI input on
1371 another sampler channel. For particular MIDI input systems it's also
1372 possible to create several devices of the same MIDI input type. This
1373 chapter describes all commands to configure LinuxSampler's MIDI input
1374 devices and their parameters.
1375
1376 Instead of defining commands and parameters for each driver
1377 individually, all possible parameters, their meanings and possible
1378 values have to be obtained at runtime. This makes the protocol a bit
1379 abstract, but has the advantage, that front-ends can be written
1380 independently of what drivers are currently implemented and what
1381 parameters these drivers are actually offering. This means
1382 front-ends can even handle drivers which are implemented somewhere in
1383 future without modifying the front-end at all.
1384
1385 Commands for configuring MIDI input devices are pretty much the same
1386 as the commands for configuring audio output drivers, already
1387 described in the last chapter.
1388
1389 Note: examples in this chapter showing particular parameters of
1390 drivers are not meant as specification of the drivers' parameters.
1391 Driver implementations in LinuxSampler might have complete different
1392 parameter names and meanings than shown in these examples or might
1393 change in future, so these examples are only meant for showing how to
1394 retrieve what parameters drivers are offering, how to retrieve their
1395 possible values, etc.
1396
1397
1398
1399 Schoenebeck Expires November 22, 2005 [Page 25]
1400
1401 Internet-Draft LinuxSampler Control Protocol May 2005
1402
1403
1404 6.3.1 Getting amount of available MIDI input drivers
1405
1406 Use the following command to get the number of MIDI input drivers
1407 currently available for the LinuxSampler instance:
1408
1409 GET AVAILABLE_MIDI_INPUT_DRIVERS
1410
1411 Possible Answers:
1412
1413 LinuxSampler will answer by sending the number of available MIDI
1414 input drivers.
1415
1416 Example:
1417
1418 C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"
1419 S: "2"
1420
1421 6.3.2 Getting all available MIDI input drivers
1422
1423 Use the following command to list all MIDI input drivers currently
1424 available for the LinuxSampler instance:
1425
1426 LIST AVAILABLE_MIDI_INPUT_DRIVERS
1427
1428 Possible Answers:
1429
1430 LinuxSampler will answer by sending comma separated character
1431 strings, each symbolizing a MIDI input driver.
1432
1433 Example:
1434
1435 C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
1436 S: "ALSA,JACK"
1437
1438 6.3.3 Getting information about a specific MIDI input driver
1439
1440 Use the following command to get detailed information about a
1441 specific MIDI input driver:
1442
1443 GET MIDI_INPUT_DRIVER INFO <midi-input-driver>
1444
1445 Where <midi-input-driver> is the name of the MIDI input driver as
1446 returned by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2)
1447 command.
1448
1449 Possible Answers:
1450
1451
1452
1453
1454
1455 Schoenebeck Expires November 22, 2005 [Page 26]
1456
1457 Internet-Draft LinuxSampler Control Protocol May 2005
1458
1459
1460 LinuxSampler will answer by sending a <CRLF> separated list. Each
1461 answer line begins with the information category name followed by
1462 a colon and then a space character <SP> and finally the info
1463 character string to that info category. At the moment the
1464 following information categories are defined:
1465
1466 DESCRIPTION -
1467 arbitrary description text about the MIDI input driver
1468 VERSION -
1469 arbitrary character string regarding the driver's version
1470 PARAMETERS -
1471 comma separated list of all parameters available for the
1472 given MIDI input driver
1473 The mentioned fields above don't have to be in particular order.
1474
1475 Example:
1476
1477 C: "GET MIDI_INPUT_DRIVER INFO ALSA"
1478 S: "DESCRIPTION: Advanced Linux Sound Architecture"
1479 "VERSION: 1.0"
1480 "PARAMETERS: DRIVER,ACTIVE"
1481 "."
1482
1483 6.3.4 Getting information about specific MIDI input driver parameter
1484
1485 Use the following command to get detailed information about a
1486 specific parameter of a specific MIDI input driver:
1487
1488 GET MIDI_INPUT_DRIVER_PARAMETER INFO <midit> <param> [<deplist>]
1489
1490 Where <midit> is the name of the MIDI input driver as returned by the
1491 "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2) command, <param>
1492 a specific parameter name for which information should be obtained
1493 (as returned by the "GET MIDI_INPUT_DRIVER INFO" (Section 6.3.3)
1494 command) and <deplist> is an optional list of parameters on which the
1495 sought parameter <param> depends on, <deplist> is a key-value pair
1496 list in form of "key1=val1 key2=val2 ...", where character string
1497 values are encapsulated into apostrophes ('). Arguments given with
1498 <deplist> which are not dependency parameters of <param> will be
1499 ignored, means the front-end application can simply put all
1500 parameters in <deplist> with the values selected by the user.
1501
1502 Possible Answers:
1503
1504 LinuxSampler will answer by sending a <CRLF> separated list. Each
1505 answer line begins with the information category name followed by a
1506 colon and then a space character <SP> and finally the info character
1507 string to that info category. There is information which is always
1508
1509
1510
1511 Schoenebeck Expires November 22, 2005 [Page 27]
1512
1513 Internet-Draft LinuxSampler Control Protocol May 2005
1514
1515
1516 returned, independent of the given driver parameter and there is
1517 optional information which is only shown dependent to given driver
1518 parameter. At the moment the following information categories are
1519 defined:
1520
1521 TYPE -
1522 either "BOOL" for boolean value(s) or "INT" for integer
1523 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1524 character string(s) (always returned, no matter which driver
1525 parameter)
1526 DESCRIPTION -
1527 arbitrary text describing the purpose of the parameter (always
1528 returned, no matter which driver parameter)
1529 MANDATORY -
1530 either true or false, defines if this parameter must be given
1531 when the device is to be created with the 'CREATE
1532 MIDI_INPUT_DEVICE' (Section 6.3.5) command (always returned, no
1533 matter which driver parameter)
1534 FIX -
1535 either true or false, if false then this parameter can be
1536 changed at any time, once the device is created by the 'CREATE
1537 MIDI_INPUT_DEVICE' (Section 6.3.5) command (always returned, no
1538 matter which driver parameter)
1539 MULTIPLICITY -
1540 either true or false, defines if this parameter allows only one
1541 value or a list of values, where true means multiple values and
1542 false only a single value allowed (always returned, no matter
1543 which driver parameter)
1544 DEPENDS -
1545 comma separated list of parameters this parameter depends on,
1546 means the values for fields 'DEFAULT', 'RANGE_MIN', 'RANGE_MAX'
1547 and 'POSSIBILITIES' might depend on these listed parameters,
1548 for example assuming that an audio driver (like the ALSA
1549 driver) offers parameters 'card' and 'samplerate' then
1550 parameter 'samplerate' would depend on 'card' because the
1551 possible values for 'samplerate' depends on the sound card
1552 which can be chosen by the 'card' parameter (optionally
1553 returned, dependent to driver parameter)
1554 DEFAULT -
1555 reflects the default value for this parameter which is used
1556 when the device is created and not explicitly given with the
1557 'CREATE MIDI_INPUT_DEVICE' (Section 6.3.5) command, in case of
1558 MULTIPLCITY=true, this is a comma separated list, that's why
1559 character strings are encapsulated into apostrophes (')
1560 (optionally returned, dependent to driver parameter)
1561 RANGE_MIN -
1562 defines lower limit of the allowed value range for this
1563 parameter, can be an integer value as well as a dotted number,
1564
1565
1566
1567 Schoenebeck Expires November 22, 2005 [Page 28]
1568
1569 Internet-Draft LinuxSampler Control Protocol May 2005
1570
1571
1572 this parameter is often used in conjunction with RANGE_MAX, but
1573 may also appear without (optionally returned, dependent to
1574 driver parameter)
1575 RANGE_MAX -
1576 defines upper limit of the allowed value range for this
1577 parameter, can be an integer value as well as a dotted number,
1578 this parameter is often used in conjunction with RANGE_MIN, but
1579 may also appear without (optionally returned, dependent to
1580 driver parameter)
1581 POSSIBILITIES -
1582 comma separated list of possible values for this parameter,
1583 character strings are encapsulated into apostrophes (optionally
1584 returned, dependent to driver parameter)
1585
1586 The mentioned fields above don't have to be in particular order.
1587
1588 Example:
1589
1590 C: "GET MIDI_INPUT_DRIVER_PARAMETER INFO ALSA ACTIVE"
1591 S: "DESCRIPTION: Whether device is enabled"
1592 "TYPE: BOOL"
1593 "MANDATORY: false"
1594 "FIX: false"
1595 "MULTIPLICITY: false"
1596 "DEFAULT: true"
1597 "."
1598
1599 6.3.5 Creating a MIDI input device
1600
1601 Use the following command to create a new MIDI input device for the
1602 desired MIDI input system:
1603
1604 CREATE MIDI_INPUT_DEVICE <midi-input-driver> [<param-list>]
1605
1606 Where <midi-input-driver> should be replaced by the desired MIDI
1607 input system as returned by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
1608 (Section 6.3.2) command and <param-list> by an optional list of
1609 driver specific parameters in form of "key1=val1 key2=val2 ...",
1610 where character string values should be encapsulated into apostrophes
1611 ('). Note that there might be drivers which require parameter(s) to
1612 be given with this command. Use the previously described commands in
1613 this chapter to get that information.
1614
1615 Possible Answers:
1616
1617 "OK[<device-id>]" -
1618 in case the device was successfully created, where <device-id>
1619 is the numerical ID of the new device
1620
1621
1622
1623 Schoenebeck Expires November 22, 2005 [Page 29]
1624
1625 Internet-Draft LinuxSampler Control Protocol May 2005
1626
1627
1628 "WRN[<device-id>]:<warning-code>:<warning-message>" -
1629 in case the driver was loaded successfully, where <device-id>
1630 is the numerical ID of the new device, but there are noteworthy
1631 issue(s) related, providing an appropriate warning code and
1632 warning message
1633 "ERR:<error-code>:<error-message>" -
1634 in case it failed, providing an appropriate error code and
1635 error message
1636
1637 Example:
1638
1639 C: "CREATE MIDI_INPUT_DEVICE ALSA"
1640 S: "OK[0]"
1641
1642 6.3.6 Destroying a MIDI input device
1643
1644 Use the following command to destroy a created MIDI input device:
1645
1646 DESTROY MIDI_INPUT_DEVICE <device-id>
1647
1648 Where <device-id> should be replaced by the device's numerical ID as
1649 returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
1650 MIDI_INPUT_DEVICES" (Section 6.3.8) command.
1651
1652 Possible Answers:
1653
1654 "OK" -
1655 in case the device was successfully destroyed
1656 "WRN:<warning-code>:<warning-message>" -
1657 in case the device was destroyed, but there are noteworthy
1658 issue(s) related, providing an appropriate warning code and
1659 warning message
1660 "ERR:<error-code>:<error-message>" -
1661 in case it failed, providing an appropriate error code and
1662 error message
1663
1664 Example:
1665
1666 C: "DESTROY MIDI_INPUT_DEVICE 0"
1667 S: "OK"
1668
1669 6.3.7 Getting all created MIDI input device count
1670
1671 Use the following command to count all created MIDI input devices:
1672
1673 GET MIDI_INPUT_DEVICES
1674
1675 Possible Answers:
1676
1677
1678
1679 Schoenebeck Expires November 22, 2005 [Page 30]
1680
1681 Internet-Draft LinuxSampler Control Protocol May 2005
1682
1683
1684 LinuxSampler will answer by sending the current number of all MIDI
1685 input devices.
1686
1687 Example:
1688
1689 C: "GET MIDI_INPUT_DEVICES"
1690 S: "3"
1691
1692 6.3.8 Getting all created MIDI input device list
1693
1694 Use the following command to list all created MIDI input devices:
1695
1696 LIST MIDI_INPUT_DEVICES
1697
1698 Possible Answers:
1699
1700 LinuxSampler will answer by sending a comma separated list with
1701 the numerical Ids of all created MIDI input devices.
1702
1703 Examples:
1704
1705 C: "LIST MIDI_INPUT_DEVICES"
1706 S: "0,1,2"
1707
1708 C: "LIST MIDI_INPUT_DEVICES"
1709 S: "1,3"
1710
1711 6.3.9 Getting current settings of a MIDI input device
1712
1713 Use the following command to get current settings of a specific,
1714 created MIDI input device:
1715
1716 GET MIDI_INPUT_DEVICE INFO <device-id>
1717
1718 Where <device-id> is the numerical ID of the MIDI input device as
1719 returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
1720 MIDI_INPUT_DEVICES" (Section 6.3.8) command.
1721
1722 Possible Answers:
1723
1724 LinuxSampler will answer by sending a <CRLF> separated list. Each
1725 answer line begins with the information category name followed by
1726 a colon and then a space character <SP> and finally the info
1727 character string to that info category. As some parameters might
1728 allow multiple values, character strings are encapsulated into
1729 apostrophes ('). At the moment the following information
1730 categories are defined (independent of driver):
1731
1732
1733
1734
1735 Schoenebeck Expires November 22, 2005 [Page 31]
1736
1737 Internet-Draft LinuxSampler Control Protocol May 2005
1738
1739
1740
1741 DRIVER -
1742 identifier of the used MIDI input driver, as e.g. returned
1743 by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2)
1744 command
1745 ACTIVE -
1746 either true or false, if false then the MIDI device is
1747 inactive and doesn't listen to any incoming MIDI events and
1748 thus doesn't forward them to connected sampler channels
1749
1750 The mentioned fields above don't have to be in particular order. The
1751 fields above are only those fields which are returned by all MIDI
1752 input devices. Every MIDI input driver might have its own,
1753 additional driver specific parameters (see "GET MIDI_INPUT_DRIVER
1754 INFO" (Section 6.3.3) command) which are also returned by this
1755 command.
1756
1757 Example:
1758
1759 C: "GET MIDI_INPUT_DEVICE INFO 0"
1760 S: "DRIVER: ALSA"
1761 "ACTIVE: true"
1762 "."
1763
1764 6.3.10 Changing settings of MIDI input devices
1765
1766 Use the following command to alter a specific setting of a created
1767 MIDI input device:
1768
1769 SET MIDI_INPUT_DEVICE_PARAMETER <device-id> <key>=<value>
1770
1771 Where <device-id> should be replaced by the numerical ID of the MIDI
1772 input device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section
1773 6.3.5) or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command, <key> by
1774 the name of the parameter to change and <value> by the new value for
1775 this parameter.
1776
1777 Possible Answers:
1778
1779 "OK" -
1780 in case setting was successfully changed
1781 "WRN:<warning-code>:<warning-message>" -
1782 in case setting was changed successfully, but there are
1783 noteworthy issue(s) related, providing an appropriate warning
1784 code and warning message
1785 "ERR:<error-code>:<error-message>" -
1786 in case it failed, providing an appropriate error code and
1787 error message
1788
1789
1790
1791 Schoenebeck Expires November 22, 2005 [Page 32]
1792
1793 Internet-Draft LinuxSampler Control Protocol May 2005
1794
1795
1796 Example:
1797
1798 C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"
1799 S: "OK"
1800
1801 6.3.11 Getting information about a MIDI port
1802
1803 Use the following command to get information about a MIDI port:
1804
1805 GET MIDI_INPUT_PORT INFO <device-id> <midi-port>
1806
1807 Where <device-id> is the numerical ID of the MIDI input device as
1808 returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
1809 MIDI_INPUT_DEVICES" (Section 6.3.8) command and <midi-port> the MIDI
1810 input port number.
1811
1812 Possible Answers:
1813
1814 LinuxSampler will answer by sending a <CRLF> separated list. Each
1815 answer line begins with the information category name followed by
1816 a colon and then a space character <SP> and finally the info
1817 character string to that info category. At the moment the
1818 following information categories are defined:
1819 NAME -
1820 arbitrary character string naming the port
1821
1822 The field above is only the one which is returned by all MIDI ports
1823 regardless of the MIDI driver and port. Every MIDI port might have
1824 its own, additional driver and port specific parameters.
1825
1826 Example:
1827
1828 C: "GET MIDI_INPUT_PORT INFO 0 0"
1829 S: "NAME: 'Masterkeyboard'"
1830 "ALSA_SEQ_BINDINGS: '64:0'"
1831 "."
1832
1833 6.3.12 Getting information about specific MIDI port parameter
1834
1835 Use the following command to get detailed information about specific
1836 MIDI port parameter:
1837
1838 GET MIDI_INPUT_PORT_PARAMETER INFO <dev-id> <port> <param>
1839
1840 Where <dev-id> is the numerical ID of the MIDI input device as
1841 returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
1842 MIDI_INPUT_DEVICES" (Section 6.3.8) command, <port> the MIDI port
1843 number and <param> a specific port parameter name for which
1844
1845
1846
1847 Schoenebeck Expires November 22, 2005 [Page 33]
1848
1849 Internet-Draft LinuxSampler Control Protocol May 2005
1850
1851
1852 information should be obtained (as returned by the "GET
1853 MIDI_INPUT_PORT INFO" (Section 6.3.11) command).
1854
1855 Possible Answers:
1856
1857 LinuxSampler will answer by sending a <CRLF> separated list. Each
1858 answer line begins with the information category name followed by
1859 a colon and then a space character <SP> and finally the info
1860 character string to that info category. There is information
1861 which is always returned, independently of the given channel
1862 parameter and there is optional information which are only shown
1863 dependently to the given MIDI port. At the moment the following
1864 information categories are defined:
1865 TYPE -
1866 either "BOOL" for boolean value(s) or "INT" for integer
1867 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1868 character string(s) (always returned)
1869 DESCRIPTION -
1870 arbitrary text describing the purpose of the parameter (always
1871 returned)
1872 FIX -
1873 either true or false, if true then this parameter is read only,
1874 thus cannot be altered (always returned)
1875 MULTIPLICITY -
1876 either true or false, defines if this parameter allows only one
1877 value or a list of values, where true means multiple values and
1878 false only a single value allowed (always returned)
1879 RANGE_MIN -
1880 defines lower limit of the allowed value range for this
1881 parameter, can be an integer value as well as a dotted number,
1882 this parameter is usually used in conjunction with 'RANGE_MAX'
1883 but may also appear without (optionally returned, dependent to
1884 driver and port parameter)
1885 RANGE_MAX -
1886 defines upper limit of the allowed value range for this
1887 parameter, can be an integer value as well as a dotted number,
1888 this parameter is usually used in conjunction with 'RANGE_MIN'
1889 but may also appear without (optionally returned, dependent to
1890 driver and port parameter)
1891 POSSIBILITIES -
1892 comma separated list of possible values for this parameter,
1893 character strings are encapsulated into apostrophes (optionally
1894 returned, dependent to device and port parameter)
1895
1896 The mentioned fields above don't have to be in particular order.
1897
1898 Example:
1899
1900
1901
1902
1903 Schoenebeck Expires November 22, 2005 [Page 34]
1904
1905 Internet-Draft LinuxSampler Control Protocol May 2005
1906
1907
1908 C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"
1909 S: "DESCRIPTION: bindings to other ALSA sequencer clients"
1910 "TYPE: STRING"
1911 "FIX: false"
1912 "MULTIPLICITY: true"
1913 "POSSIBILITIES: '64:0','68:0','68:1'"
1914 "."
1915
1916 6.3.13 Changing settings of MIDI input ports
1917
1918 Use the following command to alter a specific setting of a MIDI input
1919 port:
1920
1921 SET MIDI_INPUT_PORT_PARAMETER <device-id> <port> <key>=<value>
1922
1923 Where <device-id> should be replaced by the numerical ID of the MIDI
1924 device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5)
1925 or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command, <port> by the
1926 MIDI port number, <key> by the name of the parameter to change and
1927 <value> by the new value for this parameter.
1928
1929 Possible Answers:
1930
1931 "OK" -
1932 in case setting was successfully changed
1933 "WRN:<warning-code>:<warning-message>" -
1934 in case setting was changed successfully, but there are
1935 noteworthy issue(s) related, providing an appropriate warning
1936 code and warning message
1937 "ERR:<error-code>:<error-message>" -
1938 in case it failed, providing an appropriate error code and
1939 error message
1940
1941 Example:
1942
1943
1944
1945 6.4 Configuring sampler channels
1946
1947 The following commands describe how to add and remove sampler
1948 channels, associate a sampler channel with a sampler engine, load
1949 instruments and connect sampler channels to MIDI and audio devices.
1950
1951 6.4.1 Loading an instrument
1952
1953 An instrument file can be loaded and assigned to a sampler channel by
1954 one of the following commands:
1955
1956
1957
1958
1959 Schoenebeck Expires November 22, 2005 [Page 35]
1960
1961 Internet-Draft LinuxSampler Control Protocol May 2005
1962
1963
1964 LOAD INSTRUMENT [NON_MODAL] '<filename>' <instr-index>
1965 <sampler-channel>
1966
1967 Where <filename> is the name of the instrument file on the
1968 LinuxSampler instance's host system, <instr-index> the index of the
1969 instrument in the instrument file and <sampler-channel> is the number
1970 of the sampler channel the instrument should be assigned to. Each
1971 sampler channel can only have one instrument.
1972
1973 The difference between regular and NON_MODAL versions of the command
1974 is that the regular command returns OK only after the instrument has
1975 been fully loaded and the channel is ready to be used while NON_MODAL
1976 version returns immediately and a background process is launched to
1977 load the instrument on the channel. The GET CHANNEL INFO (Section
1978 6.4.10) command can be used to obtain loading progress from
1979 INSTRUMENT_STATUS field. LOAD command will perform sanity checks
1980 such as making sure that the file could be read and it is of a proper
1981 format and SHOULD return ERR and SHOULD not launch the background
1982 process should any errors be detected at that point.
1983
1984 Possible Answers:
1985
1986 "OK" -
1987 in case the instrument was successfully loaded
1988 "WRN:<warning-code>:<warning-message>" -
1989 in case the instrument was loaded successfully, but there are
1990 noteworthy issue(s) related (e.g. Engine doesn't support one
1991 or more patch parameters provided by the loaded instrument
1992 file), providing an appropriate warning code and warning
1993 message
1994 "ERR:<error-code>:<error-message>" -
1995 in case it failed, providing an appropriate error code and
1996 error message
1997
1998 Example:
1999
2000
2001
2002 6.4.2 Loading a sampler engine
2003
2004 A sampler engine type can be associated to a specific sampler channel
2005 by the following command:
2006
2007 LOAD ENGINE <engine-name> <sampler-channel>
2008
2009 Where <engine-name> is an engine name as obtained by the "LIST
2010 AVAILABLE_ENGINES" (Section 6.4.8) command and <sampler-channel> the
2011 sampler channel as returned by the "ADD CHANNEL" (Section 6.4.5) or
2012
2013
2014
2015 Schoenebeck Expires November 22, 2005 [Page 36]
2016
2017 Internet-Draft LinuxSampler Control Protocol May 2005
2018
2019
2020 "LIST CHANNELS" (Section 6.4.4) command where the engine type should
2021 be assigned to. This command should be issued after adding a new
2022 sampler channel and before any other control commands on the new
2023 sampler channel. It can also be used to change the engine type of a
2024 sampler channel. This command has (currently) no way to define or
2025 force if a new engine instance should be created and assigned to the
2026 given sampler channel or if an already existing instance of that
2027 engine type, shared with other sampler channels, should be used.
2028
2029 Possible Answers:
2030
2031 "OK" -
2032 in case the engine was successfully deployed
2033 "WRN:<warning-code>:<warning-message>" -
2034 in case the engine was deployed successfully, but there are
2035 noteworthy issue(s) related, providing an appropriate warning
2036 code and warning message
2037 "ERR:<error-code>:<error-message>" -
2038 in case it failed, providing an appropriate error code and
2039 error message
2040
2041 Example:
2042
2043
2044
2045 6.4.3 Getting all created sampler channel count
2046
2047 The number of sampler channels can change on runtime. To get the
2048 current amount of sampler channels, the front-end can send the
2049 following command:
2050
2051 GET CHANNELS
2052
2053 Possible Answers:
2054
2055 LinuxSampler will answer by returning the current number of
2056 sampler channels.
2057
2058 Example:
2059
2060 C: "GET CHANNELS"
2061 S: "12"
2062
2063 6.4.4 Getting all created sampler channel list
2064
2065 The number of sampler channels can change on runtime. To get the
2066 current list of sampler channels, the front-end can send the
2067 following command:
2068
2069
2070
2071 Schoenebeck Expires November 22, 2005 [Page 37]
2072
2073 Internet-Draft LinuxSampler Control Protocol May 2005
2074
2075
2076 LIST CHANNELS
2077
2078 Possible Answers:
2079
2080 LinuxSampler will answer by returning a comma separated list with
2081 all sampler channels numerical IDs.
2082
2083 Example:
2084
2085 C: "LIST CHANNELS"
2086 S: "0,1,2,3,4,5,6,9,10,11,15,20"
2087
2088 6.4.5 Adding a new sampler channel
2089
2090 A new sampler channel can be added to the end of the sampler channel
2091 list by sending the following command:
2092
2093 ADD CHANNEL
2094
2095 This will increment the sampler channel count by one and the new
2096 sampler channel will be appended to the end of the sampler channel
2097 list. The front-end should send the respective, related commands
2098 right after to e.g. load an engine, load an instrument and setting
2099 input, output method and eventually other commands to initialize the
2100 new channel. The front-end should use the sampler channel returned
2101 by the answer of this command to perform the previously recommended
2102 commands, to avoid race conditions e.g. with other front-ends that
2103 might also have sent an "ADD CHANNEL" command.
2104
2105 Possible Answers:
2106
2107 "OK[<sampler-channel>]" -
2108 in case a new sampler channel could be added, where
2109 <sampler-channel> reflects the channel number of the new
2110 created sampler channel which should be used to set up the
2111 sampler channel by sending subsequent initialization commands
2112 "WRN:<warning-code>:<warning-message>" -
2113 in case a new channel was added successfully, but there are
2114 noteworthy issue(s) related, providing an appropriate warning
2115 code and warning message
2116 "ERR:<error-code>:<error-message>" -
2117 in case it failed, providing an appropriate error code and
2118 error message
2119
2120 Example:
2121
2122
2123
2124
2125
2126
2127 Schoenebeck Expires November 22, 2005 [Page 38]
2128
2129 Internet-Draft LinuxSampler Control Protocol May 2005
2130
2131
2132 6.4.6 Removing a sampler channel
2133
2134 A sampler channel can be removed by sending the following command:
2135
2136 REMOVE CHANNEL <sampler-channel>
2137
2138 Where <sampler-channel> should be replaced by the number of the
2139 sampler channel as given by the "ADD CHANNEL" (Section 6.4.5) or
2140 "LIST CHANNELS" (Section 6.4.4) command. The channel numbers of all
2141 subsequent sampler channels remain the same.
2142
2143 Possible Answers:
2144
2145 "OK" -
2146 in case the given sampler channel could be removed
2147 "WRN:<warning-code>:<warning-message>" -
2148 in case the given channel was removed, but there are noteworthy
2149 issue(s) related, providing an appropriate warning code and
2150 warning message
2151 "ERR:<error-code>:<error-message>" -
2152 in case it failed, providing an appropriate error code and
2153 error message
2154
2155 Example:
2156
2157
2158
2159 6.4.7 Getting amount of available engines
2160
2161 The front-end can ask for the number of available engines by sending
2162 the following command:
2163
2164 GET AVAILABLE_ENGINES
2165
2166 Possible Answers:
2167
2168 LinuxSampler will answer by sending the number of available
2169 engines.
2170
2171 Example:
2172
2173 C: "GET AVAILABLE_ENGINES"
2174 S: "4"
2175
2176 6.4.8 Getting all available engines
2177
2178 The front-end can ask for a list of all available engines by sending
2179 the following command:
2180
2181
2182
2183 Schoenebeck Expires November 22, 2005 [Page 39]
2184
2185 Internet-Draft LinuxSampler Control Protocol May 2005
2186
2187
2188 LIST AVAILABLE_ENGINES
2189
2190 Possible Answers:
2191
2192 LinuxSampler will answer by sending a comma separated list of the
2193 engines' names encapsulated into apostrophes ('). Engine names
2194 can consist of lower and upper cases, digits and underlines ("_"
2195 character).
2196
2197 Example:
2198
2199 C: "LIST AVAILABLE_ENGINES"
2200 S: "'GigEngine','AkaiEngine','DLSEngine','JoesCustomEngine'"
2201
2202 6.4.9 Getting information about an engine
2203
2204 The front-end can ask for information about a specific engine by
2205 sending the following command:
2206
2207 GET ENGINE INFO <engine-name>
2208
2209 Where <engine-name> is an engine name as obtained by the "LIST
2210 AVAILABLE_ENGINES" (Section 6.4.8) command.
2211
2212 Possible Answers:
2213
2214 LinuxSampler will answer by sending a <CRLF> separated list. Each
2215 answer line begins with the information category name followed by
2216 a colon and then a space character <SP> and finally the info
2217 character string to that info category. At the moment the
2218 following categories are defined:
2219
2220 DESCRIPTION -
2221 arbitrary description text about the engine
2222 VERSION -
2223 arbitrary character string regarding the engine's version
2224
2225 The mentioned fields above don't have to be in particular order.
2226
2227 Example:
2228
2229 C: "GET ENGINE INFO JoesCustomEngine"
2230 S: "DESCRIPTION: this is Joe's custom sampler engine"
2231 "VERSION: testing-1.0"
2232 "."
2233
2234
2235
2236
2237
2238
2239 Schoenebeck Expires November 22, 2005 [Page 40]
2240
2241 Internet-Draft LinuxSampler Control Protocol May 2005
2242
2243
2244 6.4.10 Getting sampler channel information
2245
2246 The front-end can ask for the current settings of a sampler channel
2247 by sending the following command:
2248
2249 GET CHANNEL INFO <sampler-channel>
2250
2251 Where <sampler-channel> is the sampler channel number the front-end
2252 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2253 "LIST CHANNELS" (Section 6.4.4) command.
2254
2255 Possible Answers:
2256
2257 LinuxSampler will answer by sending a <CRLF> separated list. Each
2258 answer line begins with the settings category name followed by a
2259 colon and then a space character <SP> and finally the info
2260 character string to that setting category. At the moment the
2261 following categories are defined:
2262
2263 ENGINE_NAME -
2264 name of the engine that is associated with the sampler
2265 channel, "NONE" if there's no engine associated yet for this
2266 sampler channel
2267 AUDIO_OUTPUT_DEVICE -
2268 numerical ID of the audio output device which is currently
2269 connected to this sampler channel to output the audio
2270 signal, "NONE" if there's no device connected to this
2271 sampler channel
2272 AUDIO_OUTPUT_CHANNELS -
2273 number of output channels the sampler channel offers
2274 (dependent to used sampler engine and loaded instrument)
2275 AUDIO_OUTPUT_ROUTING -
2276 comma separated list which reflects to which audio channel
2277 of the selected audio output device each sampler output
2278 channel is routed to, e.g. "0,3" would mean the engine's
2279 output channel 0 is routed to channel 0 of the audio output
2280 device and the engine's output channel 1 is routed to the
2281 channel 3 of the audio output device
2282 INSTRUMENT_FILE -
2283 the file name of the loaded instrument, "NONE" if there's no
2284 instrument yet loaded for this sampler channel
2285 INSTRUMENT_NR -
2286 the instrument index number of the loaded instrument
2287 INSTRUMENT_NAME -
2288 the instrument name of the loaded instrument
2289 INSTRUMENT_STATUS -
2290 integer values 0 to 100 indicating loading progress
2291 percentage for the instrument. Negative value indicates a
2292
2293
2294
2295 Schoenebeck Expires November 22, 2005 [Page 41]
2296
2297 Internet-Draft LinuxSampler Control Protocol May 2005
2298
2299
2300 loading exception. Value of 100 indicates that the
2301 instrument is fully loaded.
2302 MIDI_INPUT_DEVICE -
2303 numerical ID of the MIDI input device which is currently
2304 connected to this sampler channel to deliver MIDI input
2305 commands, "NONE" if there's no device connected to this
2306 sampler channel
2307 MIDI_INPUT_PORT -
2308 port number of the MIDI input device
2309 MIDI_INPUT_CHANNEL -
2310 the MIDI input channel number this sampler channel should
2311 listen to or "ALL" to listen on all MIDI channels
2312 VOLUME -
2313 optionally dotted number for the channel volume factor
2314 (where a value < 1.0 means attenuation and a value > 1.0
2315 means amplification)
2316
2317 The mentioned fields above don't have to be in particular order.
2318
2319 Example:
2320
2321 C: "GET CHANNEL INFO 34"
2322 S: "ENGINE_NAME: GigEngine"
2323 "VOLUME: 1.0"
2324 "AUDIO_OUTPUT_DEVICE: 0"
2325 "AUDIO_OUTPUT_CHANNELS: 2"
2326 "AUDIO_OUTPUT_ROUTING: 0,1"
2327 "INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"
2328 "INSTRUMENT_NR: 0"
2329 "INSTRUMENT_NAME: Fazioli Piano"
2330 "INSTRUMENT_STATUS: 100"
2331 "MIDI_INPUT_DEVICE: 0"
2332 "MIDI_INPUT_PORT: 0"
2333 "MIDI_INPUT_CHANNEL: 5"
2334 "."
2335
2336 6.4.11 Current number of active voices
2337
2338 The front-end can ask for the current number of active voices on a
2339 sampler channel by sending the following command:
2340
2341 GET CHANNEL VOICE_COUNT <sampler-channel>
2342
2343 Where <sampler-channel> is the sampler channel number the front-end
2344 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2345 "LIST CHANNELS" (Section 6.4.4) command.
2346
2347 Possible Answers:
2348
2349
2350
2351 Schoenebeck Expires November 22, 2005 [Page 42]
2352
2353 Internet-Draft LinuxSampler Control Protocol May 2005
2354
2355
2356 LinuxSampler will answer by returning the number of active voices
2357 on that channel.
2358
2359 Example:
2360
2361
2362
2363 6.4.12 Current number of active disk streams
2364
2365 The front-end can ask for the current number of active disk streams
2366 on a sampler channel by sending the following command:
2367
2368 GET CHANNEL STREAM_COUNT <sampler-channel>
2369
2370 Where <sampler-channel> is the sampler channel number the front-end
2371 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2372 "LIST CHANNELS" (Section 6.4.4) command.
2373
2374 Possible Answers:
2375
2376 LinuxSampler will answer by returning the number of active disk
2377 streams on that channel in case the engine supports disk
2378 streaming, if the engine doesn't support disk streaming it will
2379 return "NA" for not available.
2380
2381 Example:
2382
2383
2384
2385 6.4.13 Current fill state of disk stream buffers
2386
2387 The front-end can ask for the current fill state of all disk streams
2388 on a sampler channel by sending the following command:
2389
2390 GET CHANNEL BUFFER_FILL BYTES <sampler-channel>
2391
2392 to get the fill state in bytes or
2393
2394 GET CHANNEL BUFFER_FILL PERCENTAGE <sampler-channel>
2395
2396 to get the fill state in percent, where <sampler-channel> is the
2397 sampler channel number the front-end is interested in as returned by
2398 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
2399 command.
2400
2401 Possible Answers:
2402
2403
2404
2405
2406
2407 Schoenebeck Expires November 22, 2005 [Page 43]
2408
2409 Internet-Draft LinuxSampler Control Protocol May 2005
2410
2411
2412 LinuxSampler will either answer by returning a comma separated
2413 string with the fill state of all disk stream buffers on that
2414 channel or an empty line if there are no active disk streams or
2415 "NA" for *not available* in case the engine which is deployed
2416 doesn't support disk streaming. Each entry in the answer list
2417 will begin with the stream's ID in brackets followed by the
2418 numerical representation of the fill size (either in bytes or
2419 percentage). Note: due to efficiency reasons the fill states in
2420 the response are not in particular order, thus the front-end has
2421 to sort them by itself if necessary.
2422
2423 Examples:
2424
2425 C: "GET CHANNEL BUFFER_FILL BYTES 4"
2426 S: "[115]420500,[116]510300,[75]110000,[120]230700"
2427 C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
2428 S: "[115]90%,[116]98%,[75]40%,[120]62%"
2429 C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
2430 S: ""
2431
2432 6.4.14 Setting audio output device
2433
2434 The front-end can set the audio output device on a specific sampler
2435 channel by sending the following command:
2436
2437 SET CHANNEL AUDIO_OUTPUT_DEVICE <sampler-channel>
2438 <audio-device-id>
2439
2440 Where <sampler-channel> is the respective sampler channel number as
2441 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
2442 (Section 6.4.4) command and <audio-device-id> is the numerical ID of
2443 the audio output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
2444 (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
2445 command.
2446
2447 Possible Answers:
2448
2449 "OK" -
2450 on success
2451 "WRN:<warning-code>:<warning-message>" -
2452 if audio output device was set, but there are noteworthy
2453 issue(s) related, providing an appropriate warning code and
2454 warning message
2455 "ERR:<error-code>:<error-message>" -
2456 in case it failed, providing an appropriate error code and
2457 error message
2458
2459 Examples:
2460
2461
2462
2463 Schoenebeck Expires November 22, 2005 [Page 44]
2464
2465 Internet-Draft LinuxSampler Control Protocol May 2005
2466
2467
2468
2469
2470 6.4.15 Setting audio output type
2471
2472 DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
2473
2474 The front-end can alter the audio output type on a specific sampler
2475 channel by sending the following command:
2476
2477 SET CHANNEL AUDIO_OUTPUT_TYPE <sampler-channel>
2478 <audio-output-type>
2479
2480 Where <audio-output-type> is currently either "ALSA" or "JACK" and
2481 <sampler-channel> is the respective sampler channel number.
2482
2483 Possible Answers:
2484
2485 "OK" -
2486 on success
2487 "WRN:<warning-code>:<warning-message>" -
2488 if audio output type was set, but there are noteworthy issue(s)
2489 related, providing an appropriate warning code and warning
2490 message
2491 "ERR:<error-code>:<error-message>" -
2492 in case it failed, providing an appropriate error code and
2493 error message
2494
2495 Examples:
2496
2497
2498
2499 6.4.16 Setting audio output channel
2500
2501 The front-end can alter the audio output channel on a specific
2502 sampler channel by sending the following command:
2503
2504 SET CHANNEL AUDIO_OUTPUT_CHANNEL <sampler-chan> <audio-out>
2505 <audio-in>
2506
2507 Where <sampler-chan> is the sampler channel number as returned by the
2508 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
2509 command, <audio-out> is the numerical ID of the sampler channel's
2510 audio output channel which should be rerouted and <audio-in> is the
2511 numerical ID of the audio channel of the selected audio output device
2512 where <audio-out> should be routed to.
2513
2514 Possible Answers:
2515
2516
2517
2518
2519 Schoenebeck Expires November 22, 2005 [Page 45]
2520
2521 Internet-Draft LinuxSampler Control Protocol May 2005
2522
2523
2524 "OK" -
2525 on success
2526 "WRN:<warning-code>:<warning-message>" -
2527 if audio output channel was set, but there are noteworthy
2528 issue(s) related, providing an appropriate warning code and
2529 warning message
2530 "ERR:<error-code>:<error-message>" -
2531 in case it failed, providing an appropriate error code and
2532 error message
2533
2534 Examples:
2535
2536
2537
2538 6.4.17 Setting MIDI input device
2539
2540 The front-end can set the MIDI input device on a specific sampler
2541 channel by sending the following command:
2542
2543 SET CHANNEL MIDI_INPUT_DEVICE <sampler-channel> <midi-device-id>
2544
2545 Where <sampler-channel> is the sampler channel number as returned by
2546 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
2547 command and <midi-device-id> is the numerical ID of the MIDI input
2548 device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5)
2549 or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command.
2550
2551 Possible Answers:
2552
2553 "OK" -
2554 on success
2555 "WRN:<warning-code>:<warning-message>" -
2556 if MIDI input device was set, but there are noteworthy issue(s)
2557 related, providing an appropriate warning code and warning
2558 message
2559 "ERR:<error-code>:<error-message>" -
2560 in case it failed, providing an appropriate error code and
2561 error message
2562
2563 Examples:
2564
2565
2566
2567 6.4.18 Setting MIDI input type
2568
2569 DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
2570
2571 The front-end can alter the MIDI input type on a specific sampler
2572
2573
2574
2575 Schoenebeck Expires November 22, 2005 [Page 46]
2576
2577 Internet-Draft LinuxSampler Control Protocol May 2005
2578
2579
2580 channel by sending the following command:
2581
2582 SET CHANNEL MIDI_INPUT_TYPE <sampler-channel> <midi-input-type>
2583
2584 Where <midi-input-type> is currently only "ALSA" and
2585 <sampler-channel> is the respective sampler channel number.
2586
2587 Possible Answers:
2588
2589 "OK" -
2590 on success
2591 "WRN:<warning-code>:<warning-message>" -
2592 if MIDI input type was set, but there are noteworthy issue(s)
2593 related, providing an appropriate warning code and warning
2594 message
2595 "ERR:<error-code>:<error-message>" -
2596 in case it failed, providing an appropriate error code and
2597 error message
2598
2599 Examples:
2600
2601
2602
2603 6.4.19 Setting MIDI input port
2604
2605 The front-end can alter the MIDI input port on a specific sampler
2606 channel by sending the following command:
2607
2608 SET CHANNEL MIDI_INPUT_PORT <sampler-channel> <midi-input-port>
2609
2610 Where <midi-input-port> is a MIDI input port number of the MIDI input
2611 device connected to the sampler channel given by <sampler-channel>.
2612
2613 Possible Answers:
2614
2615 "OK" -
2616 on success
2617 "WRN:<warning-code>:<warning-message>" -
2618 if MIDI input port was set, but there are noteworthy issue(s)
2619 related, providing an appropriate warning code and warning
2620 message
2621 "ERR:<error-code>:<error-message>" -
2622 in case it failed, providing an appropriate error code and
2623 error message
2624
2625 Examples:
2626
2627
2628
2629
2630
2631 Schoenebeck Expires November 22, 2005 [Page 47]
2632
2633 Internet-Draft LinuxSampler Control Protocol May 2005
2634
2635
2636
2637
2638 6.4.20 Setting MIDI input channel
2639
2640 The front-end can alter the MIDI channel a sampler channel should
2641 listen to by sending the following command:
2642
2643 SET CHANNEL MIDI_INPUT_CHANNEL <sampler-channel> <midi-input-chan>
2644
2645 Where <midi-input-chan> is the number of the new MIDI input channel
2646 where <sampler-channel> should listen to or "ALL" to listen on all 16
2647 MIDI channels.
2648
2649 Possible Answers:
2650
2651 "OK" -
2652 on success
2653 "WRN:<warning-code>:<warning-message>" -
2654 if MIDI input channel was set, but there are noteworthy
2655 issue(s) related, providing an appropriate warning code and
2656 warning message
2657 "ERR:<error-code>:<error-message>" -
2658 in case it failed, providing an appropriate error code and
2659 error message
2660
2661 Examples:
2662
2663
2664
2665 6.4.21 Setting channel volume
2666
2667 The front-end can alter the volume of a sampler channel by sending
2668 the following command:
2669
2670 SET CHANNEL VOLUME <sampler-channel> <volume>
2671
2672 Where <volume> is an optionally dotted positive number (a value
2673 smaller than 1.0 means attenuation, whereas a value greater than 1.0
2674 means amplification) and <sampler-channel> defines the sampler
2675 channel where this volume factor should be set.
2676
2677 Possible Answers:
2678
2679 "OK" -
2680 on success
2681 "WRN:<warning-code>:<warning-message>" -
2682 if channel volume was set, but there are noteworthy issue(s)
2683 related, providing an appropriate warning code and warning
2684
2685
2686
2687 Schoenebeck Expires November 22, 2005 [Page 48]
2688
2689 Internet-Draft LinuxSampler Control Protocol May 2005
2690
2691
2692 message
2693 "ERR:<error-code>:<error-message>" -
2694 in case it failed, providing an appropriate error code and
2695 error message
2696
2697 Examples:
2698
2699
2700
2701 6.4.22 Resetting a sampler channel
2702
2703 The front-end can reset a particular sampler channel by sending the
2704 following command:
2705
2706 RESET CHANNEL <sampler-channel>
2707
2708 Where <sampler-channel> defines the sampler channel to be reset.
2709 This will cause the engine on that sampler channel, its voices and
2710 eventually disk streams and all control and status variables to be
2711 reset.
2712
2713 Possible Answers:
2714
2715 "OK" -
2716 on success
2717 "WRN:<warning-code>:<warning-message>" -
2718 if channel was reset, but there are noteworthy issue(s)
2719 related, providing an appropriate warning code and warning
2720 message
2721 "ERR:<error-code>:<error-message>" -
2722 in case it failed, providing an appropriate error code and
2723 error message
2724
2725 Examples:
2726
2727
2728
2729 6.5 Controlling connection
2730
2731 The following commands are used to control the connection to
2732 LinuxSampler.
2733
2734 6.5.1 Register front-end for receiving event messages
2735
2736 The front-end can register itself to the LinuxSampler application to
2737 be informed about noteworthy events by sending this command:
2738
2739
2740
2741
2742
2743 Schoenebeck Expires November 22, 2005 [Page 49]
2744
2745 Internet-Draft LinuxSampler Control Protocol May 2005
2746
2747
2748 SUBSCRIBE <event-id>
2749
2750 where <event-id> will be replaced by the respective event that client
2751 wants to subscribe to.
2752
2753 Possible Answers:
2754
2755 "OK" -
2756 on success
2757 "WRN:<warning-code>:<warning-message>" -
2758 if registration succeeded, but there are noteworthy issue(s)
2759 related, providing an appropriate warning code and warning
2760 message
2761 "ERR:<error-code>:<error-message>" -
2762 in case it failed, providing an appropriate error code and
2763 error message
2764
2765 Examples:
2766
2767
2768
2769 6.5.2 Unregister front-end for not receiving event messages
2770
2771 The front-end can unregister itself if it doesn't want to receive
2772 event messages anymore by sending the following command:
2773
2774 UNSUBSCRIBE <event-id>
2775
2776 Where <event-id> will be replaced by the respective event that client
2777 doesn't want to receive anymore.
2778
2779 Possible Answers:
2780
2781 "OK" -
2782 on success
2783 "WRN:<warning-code>:<warning-message>" -
2784 if unregistration succeeded, but there are noteworthy issue(s)
2785 related, providing an appropriate warning code and warning
2786 message
2787 "ERR:<error-code>:<error-message>" -
2788 in case it failed, providing an appropriate error code and
2789 error message
2790
2791 Examples:
2792
2793
2794
2795
2796
2797
2798
2799 Schoenebeck Expires November 22, 2005 [Page 50]
2800
2801 Internet-Draft LinuxSampler Control Protocol May 2005
2802
2803
2804 6.5.3 Enable or disable echo of commands
2805
2806 To enable or disable back sending of commands to the client the
2807 following command can be used:
2808
2809 SET ECHO <value>
2810
2811 Where <value> should be replaced either by "1" to enable echo mode or
2812 "0" to disable echo mode. When echo mode is enabled, all commands
2813 send to LinuxSampler will be immediately send back and after this
2814 echo the actual response to the command will be returned. Echo mode
2815 will only be altered for the client connection that issued the "SET
2816 ECHO" command, not globally for all client connections.
2817
2818 Possible Answers:
2819
2820 "OK" -
2821 usually
2822 "ERR:<error-code>:<error-message>" -
2823 on syntax error, e.g. non boolean value
2824
2825 Examples:
2826
2827
2828
2829 6.5.4 Close client connection
2830
2831 The client can close its network connection to LinuxSampler by
2832 sending the following command:
2833
2834 QUIT
2835
2836 This is probably more interesting for manual telnet connections to
2837 LinuxSampler than really useful for a front-end implementation.
2838
2839 6.6 Global commands
2840
2841 The following commands have global impact on the sampler.
2842
2843 6.6.1 Reset sampler
2844
2845 The front-end can reset the whole sampler by sending the following
2846 command:
2847
2848 RESET
2849
2850 Possible Answers:
2851
2852
2853
2854
2855 Schoenebeck Expires November 22, 2005 [Page 51]
2856
2857 Internet-Draft LinuxSampler Control Protocol May 2005
2858
2859
2860 "OK" -
2861 always
2862
2863 Examples:
2864
2865
2866
2867 6.6.2 General sampler informations
2868
2869 The client can ask for general informations about the LinuxSampler
2870 instance by sending the following command:
2871
2872 GET SERVER INFO
2873
2874 Possible Answers:
2875
2876 LinuxSampler will answer by sending a <CRLF> separated list. Each
2877 answer line begins with the information category name followed by
2878 a colon and then a space character <SP> and finally the info
2879 character string to that information category. At the moment the
2880 following categories are defined:
2881
2882 DESCRIPTION -
2883 arbitrary textual description about the sampler
2884 VERSION -
2885 version of the sampler
2886 PROTOCOL_VERSION -
2887 version of the LSCP specification the sampler complies with
2888 (see Section 2 for details)
2889
2890 The mentioned fields above don't have to be in particular order.
2891 Other fields might be added in future.
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911 Schoenebeck Expires November 22, 2005 [Page 52]
2912
2913 Internet-Draft LinuxSampler Control Protocol May 2005
2914
2915
2916 7. Command Syntax
2917
2918 The grammar of the control protocol as descibed in Section 6 is
2919 defined below using Backus-Naur Form (BNF as described in [RFC2234])
2920 where applicable.
2921
2922 input =
2923 line LF
2924 / line CR LF
2925
2926 line =
2927 /* epsilon (empty line ignored) */
2928 / comment
2929 / command
2930 / error
2931
2932 comment =
2933 '#'
2934 / comment '#'
2935 / comment SP
2936 / comment number
2937 / comment string
2938
2939 command =
2940 ADD SP CHANNEL
2941 / GET SP get_instruction
2942 / CREATE SP create_instruction
2943 / DESTROY SP destroy_instruction
2944 / LIST SP list_instruction
2945 / LOAD SP load_instruction
2946 / REMOVE SP CHANNEL SP sampler_channel
2947 / SET SP set_instruction
2948 / SUBSCRIBE SP subscribe_event
2949 / UNSUBSCRIBE SP unsubscribe_event
2950 / SELECT SP text
2951 / RESET SP CHANNEL SP sampler_channel
2952 / RESET
2953 / QUIT
2954
2955 subscribe_event =
2956 CHANNEL_COUNT
2957 / VOICE_COUNT
2958 / STREAM_COUNT
2959 / BUFFER_FILL
2960 / CHANNEL_INFO
2961 / MISCELLANEOUS
2962
2963 unsubscribe_event =
2964
2965
2966
2967 Schoenebeck Expires November 22, 2005 [Page 53]
2968
2969 Internet-Draft LinuxSampler Control Protocol May 2005
2970
2971
2972 CHANNEL_COUNT
2973 / VOICE_COUNT
2974 / STREAM_COUNT
2975 / BUFFER_FILL
2976 / CHANNEL_INFO
2977 / MISCELLANEOUS
2978
2979 get_instruction =
2980 AVAILABLE_ENGINES
2981 / AVAILABLE_MIDI_INPUT_DRIVERS
2982 / MIDI_INPUT_DRIVER SP INFO SP string
2983 / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
2984 / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP
2985 key_val_list
2986 / AVAILABLE_AUDIO_OUTPUT_DRIVERS
2987 / AUDIO_OUTPUT_DRIVER SP INFO SP string
2988 / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
2989 / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP
2990 key_val_list
2991 / AUDIO_OUTPUT_DEVICES
2992 / MIDI_INPUT_DEVICES
2993 / AUDIO_OUTPUT_DEVICE SP INFO SP number
2994 / MIDI_INPUT_DEVICE SP INFO SP number
2995 / MIDI_INPUT_PORT SP INFO SP number SP number
2996 / MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
2997 / AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
2998 / AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP
2999 string
3000 / CHANNELS
3001 / CHANNEL SP INFO SP sampler_channel
3002 / CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
3003 / CHANNEL SP STREAM_COUNT SP sampler_channel
3004 / CHANNEL SP VOICE_COUNT SP sampler_channel
3005 / ENGINE SP INFO SP engine_name
3006 / SERVER SP INFO
3007
3008 set_instruction =
3009 AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '='
3010 param_val_list
3011 / AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '='
3012 param_val_list
3013 / MIDI_INPUT_DEVICE_PARAMETER SP number SP string '='
3014 param_val_list
3015 / MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '='
3016 param_val_list
3017 / CHANNEL SP set_chan_instruction
3018 / ECHO SP boolean
3019
3020
3021
3022
3023 Schoenebeck Expires November 22, 2005 [Page 54]
3024
3025 Internet-Draft LinuxSampler Control Protocol May 2005
3026
3027
3028 create_instruction =
3029 AUDIO_OUTPUT_DEVICE SP string SP key_val_list
3030 / AUDIO_OUTPUT_DEVICE SP string
3031 / MIDI_INPUT_DEVICE SP string SP key_val_list
3032 / MIDI_INPUT_DEVICE SP string
3033
3034 destroy_instruction =
3035 AUDIO_OUTPUT_DEVICE SP number
3036 / MIDI_INPUT_DEVICE SP number
3037
3038 load_instruction =
3039 INSTRUMENT SP load_instr_args
3040 / ENGINE SP load_engine_args
3041
3042 set_chan_instruction =
3043 AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
3044 / AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index
3045 SP audio_channel_index
3046 / AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
3047 / MIDI_INPUT SP sampler_channel SP device_index SP
3048 midi_input_port_index SP midi_input_channel_index
3049 / MIDI_INPUT_DEVICE SP sampler_channel SP device_index
3050 / MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
3051 / MIDI_INPUT_CHANNEL SP sampler_channel SP
3052 midi_input_channel_index
3053 / MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
3054 / VOLUME SP sampler_channel SP volume_value
3055
3056 key_val_list =
3057 string '=' param_val_list
3058 / key_val_list SP string '=' param_val_list
3059
3060 buffer_size_type =
3061 BYTES
3062 / PERCENTAGE
3063
3064 list_instruction =
3065 AUDIO_OUTPUT_DEVICES
3066 / MIDI_INPUT_DEVICES
3067 / CHANNELS
3068 / AVAILABLE_ENGINES
3069 / AVAILABLE_MIDI_INPUT_DRIVERS
3070 / AVAILABLE_AUDIO_OUTPUT_DRIVERS
3071
3072 load_instr_args =
3073 filename SP instrument_index SP sampler_channel
3074 / NON_MODAL SP filename SP instrument_index SP sampler_channel
3075
3076
3077
3078
3079 Schoenebeck Expires November 22, 2005 [Page 55]
3080
3081 Internet-Draft LinuxSampler Control Protocol May 2005
3082
3083
3084 load_engine_args =
3085 engine_name SP sampler_channel
3086
3087 device_index =
3088 number
3089
3090 audio_channel_index =
3091 number
3092
3093 audio_output_type_name =
3094 string
3095
3096 midi_input_port_index =
3097 number
3098
3099 midi_input_channel_index =
3100 number
3101 / ALL
3102
3103 midi_input_type_name =
3104 string
3105
3106 volume_value =
3107 dotnum
3108 / number
3109
3110 sampler_channel =
3111 number
3112
3113 instrument_index =
3114 number
3115
3116 engine_name =
3117 string
3118
3119 filename =
3120 stringval
3121
3122 param_val_list =
3123 param_val
3124 / param_val_list','param_val
3125
3126 param_val =
3127 string
3128 / '\'' string '\''
3129 / '\"' string '\"'
3130 / number
3131
3132
3133
3134
3135 Schoenebeck Expires November 22, 2005 [Page 56]
3136
3137 Internet-Draft LinuxSampler Control Protocol May 2005
3138
3139
3140 / dotnum
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191 Schoenebeck Expires November 22, 2005 [Page 57]
3192
3193 Internet-Draft LinuxSampler Control Protocol May 2005
3194
3195
3196 8. Events
3197
3198 This chapter will describe all currently defined events supported by
3199 LinuxSampler.
3200
3201 8.1 Number of sampler channels changed
3202
3203 Client may want to be notified when the total number of channels on
3204 the back-end changes by issuing the following command:
3205
3206 SUBSCRIBE CHANNEL_COUNT
3207
3208 Server will start sending the following notification messages:
3209
3210 "NOTIFY:CHANNEL_COUNT:<channels>"
3211
3212 where <channels> will be replaced by the new number of sampler
3213 channels.
3214
3215 8.2 Number of active voices changed
3216
3217 Client may want to be notified when the number of voices on the
3218 back-end changes by issuing the following command:
3219
3220 SUBSCRIBE VOICE_COUNT
3221
3222 Server will start sending the following notification messages:
3223
3224 "NOTIFY:VOICE_COUNT:<sampler-channel> <voices>
3225
3226 where <sampler-channel> will be replaced by the sampler channel the
3227 voice count change occurred and <voices> by the new number of active
3228 voices on that channel.
3229
3230 8.3 Number of active disk streams changed
3231
3232 Client may want to be notified when the number of streams on the
3233 back-end changes by issuing the following command: SUBSCRIBE
3234 STREAM_COUNT
3235
3236 SUBSCRIBE STREAM_COUNT
3237
3238 Server will start sending the following notification messages:
3239
3240 "NOTIFY:STREAM_COUNT:<sampler-channel> <streams>"
3241
3242 where <sampler-channel> will be replaced by the sampler channel the
3243 stream count change occurred and <streams> by the new number of
3244
3245
3246
3247 Schoenebeck Expires November 22, 2005 [Page 58]
3248
3249 Internet-Draft LinuxSampler Control Protocol May 2005
3250
3251
3252 active disk streams on that channel.
3253
3254 8.4 Disk stream buffer fill state changed
3255
3256 Client may want to be notified when the buffer fill state of a disk
3257 stream on the back-end changes by issuing the following command:
3258
3259 SUBSCRIBE BUFFER_FILL
3260
3261 Server will start sending the following notification messages:
3262
3263 "NOTIFY:BUFFER_FILL:<sampler-channel> <fill-data>"
3264
3265 where <sampler-channel> will be replaced by the sampler channel the
3266 buffer fill state change occurred on and <fill-data> will be replaced
3267 by the buffer fill data for this channel as described in Section
3268 6.4.13 as if the "GET CHANNEL BUFFER_FILL PERCENTAGE" (Section
3269 6.4.13) command was issued on this channel.
3270
3271 8.5 Channel information changed
3272
3273 Client may want to be notified when changes were made to sampler
3274 channels on the back-end by issuing the following command:
3275
3276 SUBSCRIBE CHANNEL_INFO
3277
3278 Server will start sending the following notification messages:
3279
3280 "NOTIFY:CHANNEL_INFO:<sampler-channel>"
3281
3282 where <sampler-channel> will be replaced by the sampler channel the
3283 channel info change occurred. The front-end will have to send the
3284 respective command to actually get the channel info. Because these
3285 messages will be triggered by LSCP commands issued by other clients
3286 rather than real time events happening on the server, it is believed
3287 that an empty notification message is sufficient here.
3288
3289 8.6 Miscellaneous and debugging events
3290
3291 Client may want to be notified of miscellaneous and debugging events
3292 occurring at the server by issuing the following command:
3293
3294 SUBSCRIBE MISCELLANEOUS
3295
3296 Server will start sending the following notification messages:
3297
3298 "NOTIFY:MISCELLANEOUS:<string>"
3299
3300
3301
3302
3303 Schoenebeck Expires November 22, 2005 [Page 59]
3304
3305 Internet-Draft LinuxSampler Control Protocol May 2005
3306
3307
3308 where <string> will be replaced by whatever data server wants to send
3309 to the client. Client MAY display this data to the user AS IS to
3310 facilitate debugging.
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359 Schoenebeck Expires November 22, 2005 [Page 60]
3360
3361 Internet-Draft LinuxSampler Control Protocol May 2005
3362
3363
3364 9. Security Considerations
3365
3366 As there is so far no method of authentication and authorization
3367 defined and so not required for a client applications to succeed to
3368 connect, running LinuxSampler might be a security risk for the host
3369 system the LinuxSampler instance is running on.
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415 Schoenebeck Expires November 22, 2005 [Page 61]
3416
3417 Internet-Draft LinuxSampler Control Protocol May 2005
3418
3419
3420 10. Acknowledgments
3421
3422 This document has benefited greatly from the comments of the
3423 following people, discussed on the LinuxSampler developer's mailing
3424 list:
3425
3426 Rui Nuno Capela
3427 Vladimir Senkov
3428 Mark Knecht
3429 Grigor Iliev
3430
3431 11 References
3432
3433 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
3434 Requirement Levels", RFC 2119, 1997.
3435
3436 [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
3437 Specifications", RFC 2234, 1997.
3438
3439 [RFC793] Defense Advanced Research Projects Agency, "TRANSMISSION
3440 CONTROL PROTOCOL", RFC 793, 1981.
3441
3442
3443 Author's Address
3444
3445 C. Schoenebeck
3446 Interessengemeinschaft Software Engineering e. V.
3447 Max-Planck-Str. 39
3448 74081 Heilbronn
3449 Germany
3450
3451 EMail: schoenebeck at software minus engineering dot org
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471 Schoenebeck Expires November 22, 2005 [Page 62]
3472
3473 Internet-Draft LinuxSampler Control Protocol May 2005
3474
3475
3476 Intellectual Property Statement
3477
3478 The IETF takes no position regarding the validity or scope of any
3479 intellectual property or other rights that might be claimed to
3480 pertain to the implementation or use of the technology described in
3481 this document or the extent to which any license under such rights
3482 might or might not be available; neither does it represent that it
3483 has made any effort to identify any such rights. Information on the
3484 IETF's procedures with respect to rights in standards-track and
3485 standards-related documentation can be found in BCP-11. Copies of
3486 claims of rights made available for publication and any assurances of
3487 licenses to be made available, or the result of an attempt made to
3488 obtain a general license or permission for the use of such
3489 proprietary rights by implementors or users of this specification can
3490 be obtained from the IETF Secretariat.
3491
3492 The IETF invites any interested party to bring to its attention any
3493 copyrights, patents or patent applications, or other proprietary
3494 rights which may cover technology that may be required to practice
3495 this standard. Please address the information to the IETF Executive
3496 Director.
3497
3498
3499 Full Copyright Statement
3500
3501 Copyright (C) The Internet Society (2005). All Rights Reserved.
3502
3503 This document and translations of it may be copied and furnished to
3504 others, and derivative works that comment on or otherwise explain it
3505 or assist in its implementation may be prepared, copied, published
3506 and distributed, in whole or in part, without restriction of any
3507 kind, provided that the above copyright notice and this paragraph are
3508 included on all such copies and derivative works. However, this
3509 document itself may not be modified in any way, such as by removing
3510 the copyright notice or references to the Internet Society or other
3511 Internet organizations, except as needed for the purpose of
3512 developing Internet standards in which case the procedures for
3513 copyrights defined in the Internet Standards process must be
3514 followed, or as required to translate it into languages other than
3515 English.
3516
3517 The limited permissions granted above are perpetual and will not be
3518 revoked by the Internet Society or its successors or assignees.
3519
3520 This document and the information contained herein is provided on an
3521 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
3522 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
3523 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
3524
3525
3526
3527 Schoenebeck Expires November 22, 2005 [Page 63]
3528
3529 Internet-Draft LinuxSampler Control Protocol May 2005
3530
3531
3532 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
3533 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
3534
3535
3536 Acknowledgment
3537
3538 Funding for the RFC Editor function is currently provided by the
3539 Internet Society.
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583 Schoenebeck Expires November 22, 2005 [Page 64]
3584

  ViewVC Help
Powered by ViewVC