/[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 558 - (hide annotations) (download)
Sat May 21 01:30:30 2005 UTC (16 years, 8 months ago) by schoenebeck
File MIME type: text/plain
File size: 102903 byte(s)
LSCP events renamed:
"CHANNELS" -> "CHANNEL_COUNT"
"INFO" -> "CHANNEL_INFO"

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

  ViewVC Help
Powered by ViewVC