/[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 940 - (hide annotations) (download)
Sat Nov 25 17:18:12 2006 UTC (17 years, 4 months ago) by schoenebeck
File MIME type: text/plain
File size: 120533 byte(s)
with the latest LS release (0.4.0) we also have a new
LSCP spec release (1.1) now

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

  ViewVC Help
Powered by ViewVC