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

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

  ViewVC Help
Powered by ViewVC