/[svn]/web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.txt
ViewVC logotype

Annotation of /web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 709 - (hide annotations) (download)
Thu Jul 21 09:36:52 2005 UTC (18 years, 8 months ago) by schoenebeck
File MIME type: text/plain
File size: 118934 byte(s)
just updated date

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

  ViewVC Help
Powered by ViewVC