/[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 1048 - (hide annotations) (download)
Mon Feb 19 19:46:20 2007 UTC (17 years, 1 month ago) by schoenebeck
File MIME type: text/plain
File size: 166283 byte(s)
- an optional argument "NON_MODAL" has been added to the
  "MAP MIDI_INSTRUMENT" LSCP command, because all
  mapping commands block now by default

1 senoner 542
2    
3 schoenebeck 708
4 senoner 542 LinuxSampler Developers C. Schoenebeck
5     Internet-Draft Interessengemeinschaft Software
6 schoenebeck 974 Intended status: Standards Track Engineering e. V.
7 schoenebeck 1048 Expires: August 23, 2007 February 19, 2007
8 senoner 542
9    
10     LinuxSampler Control Protocol
11 schoenebeck 945 LSCP 1.2
12 senoner 542
13     Status of this Memo
14    
15 schoenebeck 974 By submitting this Internet-Draft, each author represents that any
16     applicable patent or other IPR claims of which he or she is aware
17     have been or will be disclosed, and any of which he or she becomes
18     aware will be disclosed, in accordance with Section 6 of BCP 79.
19 senoner 542
20     Internet-Drafts are working documents of the Internet Engineering
21     Task Force (IETF), its areas, and its working groups. Note that
22 schoenebeck 708 other groups may also distribute working documents as Internet-
23     Drafts.
24 senoner 542
25     Internet-Drafts are draft documents valid for a maximum of six months
26     and may be updated, replaced, or obsoleted by other documents at any
27     time. It is inappropriate to use Internet-Drafts as reference
28     material or to cite them other than as "work in progress."
29    
30     The list of current Internet-Drafts can be accessed at
31     http://www.ietf.org/ietf/1id-abstracts.txt.
32    
33     The list of Internet-Draft Shadow Directories can be accessed at
34     http://www.ietf.org/shadow.html.
35    
36 schoenebeck 1048 This Internet-Draft will expire on August 23, 2007.
37 senoner 542
38     Copyright Notice
39    
40 schoenebeck 1028 Copyright (C) The Internet Society (2007).
41 senoner 542
42    
43    
44    
45    
46    
47    
48    
49    
50    
51 schoenebeck 974
52    
53    
54    
55 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 1]
56 schoenebeck 940
57 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
58 senoner 542
59    
60 schoenebeck 974 Abstract
61    
62     The LinuxSampler Control Protocol (LSCP) is an application-level
63     protocol primarily intended for local and remote controlling the
64     LinuxSampler backend application, which is a sophisticated server-
65     like console application essentially playing back audio samples and
66     manipulating the samples in real time to certain extent.
67    
68    
69 senoner 542 Table of Contents
70    
71 schoenebeck 1002 1. Requirements notation . . . . . . . . . . . . . . . . . . . . 5
72     2. Versioning of this specification . . . . . . . . . . . . . . 6
73     3. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7
74     4. Focus of this protocol . . . . . . . . . . . . . . . . . . . 8
75     5. Communication Overview . . . . . . . . . . . . . . . . . . . 9
76     5.1. Request/response communication method . . . . . . . . . . 9
77     5.1.1. Result format . . . . . . . . . . . . . . . . . . . . 10
78     5.2. Subscribe/notify communication method . . . . . . . . . . 12
79     6. Description for control commands . . . . . . . . . . . . . . 14
80     6.1. Ignored lines and comments . . . . . . . . . . . . . . . 14
81     6.2. Configuring audio drivers . . . . . . . . . . . . . . . . 14
82     6.2.1. Getting amount of available audio output drivers . . 15
83     6.2.2. Getting all available audio output drivers . . . . . 15
84 schoenebeck 940 6.2.3. Getting information about a specific audio output
85 schoenebeck 1002 driver . . . . . . . . . . . . . . . . . . . . . . . 15
86 schoenebeck 940 6.2.4. Getting information about specific audio output
87 schoenebeck 1002 driver parameter . . . . . . . . . . . . . . . . . . 16
88     6.2.5. Creating an audio output device . . . . . . . . . . . 20
89     6.2.6. Destroying an audio output device . . . . . . . . . . 21
90     6.2.7. Getting all created audio output device count . . . . 22
91     6.2.8. Getting all created audio output device list . . . . 22
92     6.2.9. Getting current settings of an audio output device . 22
93     6.2.10. Changing settings of audio output devices . . . . . . 24
94     6.2.11. Getting information about an audio channel . . . . . 25
95 schoenebeck 940 6.2.12. Getting information about specific audio channel
96 schoenebeck 1002 parameter . . . . . . . . . . . . . . . . . . . . . . 26
97     6.2.13. Changing settings of audio output channels . . . . . 28
98     6.3. Configuring MIDI input drivers . . . . . . . . . . . . . 29
99     6.3.1. Getting amount of available MIDI input drivers . . . 30
100     6.3.2. Getting all available MIDI input drivers . . . . . . 30
101 schoenebeck 940 6.3.3. Getting information about a specific MIDI input
102 schoenebeck 1002 driver . . . . . . . . . . . . . . . . . . . . . . . 31
103 schoenebeck 940 6.3.4. Getting information about specific MIDI input
104 schoenebeck 1002 driver parameter . . . . . . . . . . . . . . . . . . 32
105     6.3.5. Creating a MIDI input device . . . . . . . . . . . . 34
106     6.3.6. Destroying a MIDI input device . . . . . . . . . . . 35
107     6.3.7. Getting all created MIDI input device count . . . . . 36
108 schoenebeck 974
109    
110    
111 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 2]
112 schoenebeck 974
113 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
114 schoenebeck 974
115    
116 schoenebeck 1002 6.3.8. Getting all created MIDI input device list . . . . . 36
117     6.3.9. Getting current settings of a MIDI input device . . . 37
118     6.3.10. Changing settings of MIDI input devices . . . . . . . 38
119     6.3.11. Getting information about a MIDI port . . . . . . . . 38
120 schoenebeck 940 6.3.12. Getting information about specific MIDI port
121 schoenebeck 1002 parameter . . . . . . . . . . . . . . . . . . . . . . 39
122     6.3.13. Changing settings of MIDI input ports . . . . . . . . 41
123     6.4. Configuring sampler channels . . . . . . . . . . . . . . 42
124     6.4.1. Loading an instrument . . . . . . . . . . . . . . . . 42
125     6.4.2. Loading a sampler engine . . . . . . . . . . . . . . 43
126     6.4.3. Getting all created sampler channel count . . . . . . 44
127     6.4.4. Getting all created sampler channel list . . . . . . 44
128     6.4.5. Adding a new sampler channel . . . . . . . . . . . . 44
129     6.4.6. Removing a sampler channel . . . . . . . . . . . . . 45
130     6.4.7. Getting amount of available engines . . . . . . . . . 46
131     6.4.8. Getting all available engines . . . . . . . . . . . . 46
132     6.4.9. Getting information about an engine . . . . . . . . . 47
133     6.4.10. Getting sampler channel information . . . . . . . . . 48
134     6.4.11. Current number of active voices . . . . . . . . . . . 51
135     6.4.12. Current number of active disk streams . . . . . . . . 51
136     6.4.13. Current fill state of disk stream buffers . . . . . . 52
137     6.4.14. Setting audio output device . . . . . . . . . . . . . 53
138     6.4.15. Setting audio output type . . . . . . . . . . . . . . 53
139     6.4.16. Setting audio output channel . . . . . . . . . . . . 54
140     6.4.17. Setting MIDI input device . . . . . . . . . . . . . . 55
141     6.4.18. Setting MIDI input type . . . . . . . . . . . . . . . 56
142     6.4.19. Setting MIDI input port . . . . . . . . . . . . . . . 56
143     6.4.20. Setting MIDI input channel . . . . . . . . . . . . . 57
144     6.4.21. Setting channel volume . . . . . . . . . . . . . . . 58
145     6.4.22. Muting a sampler channel . . . . . . . . . . . . . . 58
146     6.4.23. Soloing a sampler channel . . . . . . . . . . . . . . 59
147 schoenebeck 974 6.4.24. Assigning a MIDI instrument map to a sampler
148 schoenebeck 1002 channel . . . . . . . . . . . . . . . . . . . . . . . 60
149     6.4.25. Adding an effect send to a sampler channel . . . . . 61
150     6.4.26. Removing an effect send from a sampler channel . . . 62
151     6.4.27. Getting amount of effect sends on a sampler channel . 63
152     6.4.28. Listing all effect sends on a sampler channel . . . . 63
153     6.4.29. Getting effect send information . . . . . . . . . . . 64
154     6.4.30. Altering effect send's audio routing . . . . . . . . 65
155 schoenebeck 1028 6.4.31. Altering effect send's MIDI controller . . . . . . . 66
156     6.4.32. Altering effect send's send level . . . . . . . . . . 67
157     6.4.33. Resetting a sampler channel . . . . . . . . . . . . . 68
158     6.5. Controlling connection . . . . . . . . . . . . . . . . . 68
159     6.5.1. Register front-end for receiving event messages . . . 68
160 schoenebeck 940 6.5.2. Unregister front-end for not receiving event
161 schoenebeck 1028 messages . . . . . . . . . . . . . . . . . . . . . . 69
162     6.5.3. Enable or disable echo of commands . . . . . . . . . 70
163     6.5.4. Close client connection . . . . . . . . . . . . . . . 70
164 schoenebeck 708
165 senoner 542
166    
167 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 3]
168 schoenebeck 940
169 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
170 senoner 542
171    
172 schoenebeck 1028 6.6. Global commands . . . . . . . . . . . . . . . . . . . . . 71
173     6.6.1. Current number of active voices . . . . . . . . . . . 71
174     6.6.2. Maximum amount of active voices . . . . . . . . . . . 71
175     6.6.3. Reset sampler . . . . . . . . . . . . . . . . . . . . 71
176     6.6.4. General sampler informations . . . . . . . . . . . . 72
177     6.6.5. Getting global volume attenuation . . . . . . . . . . 72
178     6.6.6. Setting global volume attenuation . . . . . . . . . . 73
179     6.7. MIDI Instrument Mapping . . . . . . . . . . . . . . . . . 73
180     6.7.1. Create a new MIDI instrument map . . . . . . . . . . 74
181     6.7.2. Delete one particular or all MIDI instrument maps . . 75
182     6.7.3. Get amount of existing MIDI instrument maps . . . . . 75
183     6.7.4. Getting all created MIDI instrument maps . . . . . . 76
184     6.7.5. Getting MIDI instrument map information . . . . . . . 76
185     6.7.6. Renaming a MIDI instrument map . . . . . . . . . . . 77
186     6.7.7. Create or replace a MIDI instrument map entry . . . . 77
187     6.7.8. Getting ammount of MIDI instrument map entries . . . 80
188 schoenebeck 974 6.7.9. Getting indeces of all entries of a MIDI
189 schoenebeck 1028 instrument map . . . . . . . . . . . . . . . . . . . 81
190 schoenebeck 1048 6.7.10. Remove an entry from the MIDI instrument map . . . . 82
191 schoenebeck 1028 6.7.11. Get current settings of MIDI instrument map entry . . 82
192     6.7.12. Clear MIDI instrument map . . . . . . . . . . . . . . 84
193     7. Command Syntax . . . . . . . . . . . . . . . . . . . . . . . 85
194     8. Events . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
195     8.1. Number of audio output devices changed . . . . . . . . . 96
196     8.2. Audio output device's settings changed . . . . . . . . . 96
197     8.3. Number of MIDI input devices changed . . . . . . . . . . 96
198     8.4. MIDI input device's settings changed . . . . . . . . . . 97
199     8.5. Number of sampler channels changed . . . . . . . . . . . 97
200     8.6. Number of active voices changed . . . . . . . . . . . . . 97
201     8.7. Number of active disk streams changed . . . . . . . . . . 98
202     8.8. Disk stream buffer fill state changed . . . . . . . . . . 98
203     8.9. Channel information changed . . . . . . . . . . . . . . . 98
204     8.10. Total number of active voices changed . . . . . . . . . . 99
205     8.11. Number of MIDI instrument maps changed . . . . . . . . . 99
206     8.12. MIDI instrument map information changed . . . . . . . . . 99
207     8.13. Number of MIDI instruments changed . . . . . . . . . . . 100
208     8.14. MIDI instrument information changed . . . . . . . . . . . 100
209     8.15. Miscellaneous and debugging events . . . . . . . . . . . 101
210     9. Security Considerations . . . . . . . . . . . . . . . . . . . 102
211     10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 103
212     11. References . . . . . . . . . . . . . . . . . . . . . . . . . 104
213     Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 105
214     Intellectual Property and Copyright Statements . . . . . . . . . 106
215 schoenebeck 945
216    
217    
218    
219    
220    
221    
222    
223 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 4]
224 schoenebeck 945
225 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
226 schoenebeck 945
227    
228 senoner 542 1. Requirements notation
229    
230     The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
231     "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
232     document are to be interpreted as described in [RFC2119].
233    
234     This protocol is always case-sensitive if not explicitly claimed the
235     opposite.
236    
237 schoenebeck 708 In examples, "C:" and "S:" indicate lines sent by the client (front-
238     end) and server (LinuxSampler) respectively. Lines in examples must
239     be interpreted as every line being CRLF terminated (carriage return
240     character followed by line feed character as defined in the ASCII
241     standard), thus the following example:
242 senoner 542
243     C: "some line"
244 schoenebeck 708
245 senoner 542 "another line"
246    
247     must actually be interpreted as client sending the following message:
248    
249     "some line<CR><LF>another line<CR><LF>"
250    
251     where <CR> symbolizes the carriage return character and <LF> the line
252     feed character as defined in the ASCII standard.
253    
254     Due to technical reasons, messages can arbitrary be fragmented, means
255     the following example:
256    
257     S: "abcd"
258    
259     could also happen to be sent in three messages like in the following
260     sequence scenario:
261    
262     o server sending message "a"
263 schoenebeck 708
264 senoner 542 o followed by a delay (pause) with arbitrary duration
265 schoenebeck 708
266 senoner 542 o followed by server sending message "bcd<CR>"
267 schoenebeck 708
268 senoner 542 o again followed by a delay (pause) with arbitrary duration
269 schoenebeck 708
270 senoner 542 o followed by server sending the message "<LF>"
271    
272     where again <CR> and <LF> symbolize the carriage return and line feed
273     characters respectively.
274    
275    
276    
277    
278    
279 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 5]
280 schoenebeck 940
281 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
282 senoner 542
283    
284 schoenebeck 575 2. Versioning of this specification
285 senoner 542
286 schoenebeck 575 LSCP will certainly be extended and enhanced by-and-by. Each
287     official release of the LSCP specification will be tagged with a
288     unique version tuple. The version tuple consists at least of a major
289     and minor version number like:
290    
291     "1.2"
292    
293     In this example the major version number would be "1" and the minor
294     version number would be "2". Note that the version tuple might also
295     have more than two elements. The major version number defines a
296     group of backward compatible versions. That means a frontend is
297     compatible to the connected sampler if and only if the LSCP versions
298     to which each of the two parties complies to, match both of the
299     following rules:
300    
301     Compatibility:
302    
303     1. The frontend's LSCP major version and the sampler's LSCP major
304     version are exactly equal.
305 schoenebeck 708
306 schoenebeck 575 2. The frontend's LSCP minor version is less or equal than the
307     sampler's LSCP minor version.
308    
309     Compatibility can only be claimed if both rules are true. The
310 schoenebeck 940 frontend can use the "GET SERVER INFO" (Section 6.6.4) command to get
311 schoenebeck 575 the version of the LSCP specification the sampler complies with.
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 1048 Schoenebeck Expires August 23, 2007 [Page 6]
336 schoenebeck 940
337 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
338 schoenebeck 575
339    
340     3. Introduction
341    
342 senoner 542 LinuxSampler is a so called software sampler application capable to
343     playback audio samples from a computer's Random Access Memory (RAM)
344     as well as directly streaming it from disk. LinuxSampler is designed
345     to be modular. It provides several so called "sampler engines" where
346     each engine is specialized for a certain purpose. LinuxSampler has
347     virtual channels which will be referred in this document as "sampler
348     channels". The channels are in such way virtual as they can be
349     connected to an arbitrary MIDI input method and arbitrary MIDI
350 schoenebeck 708 channel (e.g. sampler channel 17 could be connected to an ALSA
351 senoner 542 sequencer device 64:0 and listening to MIDI channel 1 there). Each
352 schoenebeck 575 sampler channel will be associated with an instance of one of the
353 senoner 542 available sampler engines (e.g. GigEngine, DLSEngine). The audio
354     output of each sampler channel can be routed to an arbitrary audio
355     output method (ALSA / JACK) and an arbitrary audio output channel
356     there.
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 1048 Schoenebeck Expires August 23, 2007 [Page 7]
392 schoenebeck 940
393 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
394 senoner 542
395    
396 schoenebeck 575 4. Focus of this protocol
397 senoner 542
398     Main focus of this protocol is to provide a way to configure a
399     running LinuxSampler instance and to retrieve information about it.
400     The focus of this protocol is not to provide a way to control
401     synthesis parameters or even to trigger or release notes. Or in
402     other words; the focus are those functionalities which are not
403     covered by MIDI or which may at most be handled via MIDI System
404     Exclusive Messages.
405    
406    
407    
408    
409    
410    
411    
412    
413    
414    
415    
416    
417    
418    
419    
420    
421    
422    
423    
424    
425    
426    
427    
428    
429    
430    
431    
432    
433    
434    
435    
436    
437    
438    
439    
440    
441    
442    
443    
444    
445    
446    
447 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 8]
448 schoenebeck 940
449 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
450 senoner 542
451    
452 schoenebeck 575 5. Communication Overview
453 senoner 542
454     There are two distinct methods of communication between a running
455     instance of LinuxSampler and one or more control applications, so
456     called "front-ends": a simple request/response communication method
457     used by the clients to give commands to the server as well as to
458     inquire about server's status and a subscribe/notify communication
459     method used by the client to subscribe to and receive notifications
460     of certain events as they happen on the server. The latter needs
461     more effort to be implemented in the front-end application. The two
462     communication methods will be described next.
463    
464 schoenebeck 940 5.1. Request/response communication method
465 senoner 542
466 schoenebeck 575 This simple communication method is based on TCP [RFC793]. The
467     front-end application establishes a TCP connection to the
468     LinuxSampler instance on a certain host system. Then the front-end
469     application will send certain ASCII based commands as defined in this
470     document (every command line must be CRLF terminated - see
471     "Conventions used in this document" at the beginning of this
472     document) and the LinuxSampler application will response after a
473     certain process time with an appropriate ASCII based answer, also as
474     defined in this document. So this TCP communication is simply based
475     on query and answer paradigm. That way LinuxSampler is only able to
476     answer on queries from front-ends, but not able to automatically send
477     messages to the client if it's not asked to. The fronted should not
478     reconnect to LinuxSampler for every single command, instead it should
479     keep the connection established and simply resend message(s) for
480     subsequent commands. To keep information in the front-end up-to-date
481     the front-end has to periodically send new requests to get the
482     current information from the LinuxSampler instance. This is often
483     referred to as "polling". While polling is simple to implement and
484     may be OK to use in some cases, there may be disadvantages to polling
485     such as network traffic overhead and information being out of date.
486     It is possible for a client or several clients to open more than one
487 senoner 542 connection to the server at the same time. It is also possible to
488     send more than one request to the server at the same time but if
489     those requests are sent over the same connection server MUST execute
490     them sequentially. Upon executing a request server will produce a
491     result set and send it to the client. Each and every request made by
492     the client MUST result in a result set being sent back to the client.
493     No other data other than a result set may be sent by a server to a
494     client. No result set may be sent to a client without the client
495     sending request to the server first. On any particular connection,
496     result sets MUST be sent in their entirety without being interrupted
497     by other result sets. If several requests got queued up at the
498     server they MUST be processed in the order they were received and
499     result sets MUST be sent back in the same order.
500    
501    
502    
503 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 9]
504 schoenebeck 940
505 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
506 senoner 542
507    
508 schoenebeck 940 5.1.1. Result format
509 schoenebeck 708
510 senoner 542 Result set could be one of the following types:
511    
512     1. Normal
513 schoenebeck 708
514 senoner 542 2. Warning
515 schoenebeck 708
516 senoner 542 3. Error
517    
518     Warning and Error result sets MUST be single line and have the
519     following format:
520    
521     o "WRN:<warning-code>:<warning-message>"
522 schoenebeck 708
523 senoner 542 o "ERR:<error-code>:<error-message>"
524    
525     Where <warning-code> and <error-code> are numeric unique identifiers
526     of the warning or error and <warning-message> and <error-message> are
527     human readable descriptions of the warning or error respectively.
528    
529     Examples:
530    
531     C: "LOAD INSTRUMENT '/home/me/Boesendorfer24bit.gig" 0 0
532 schoenebeck 708
533 senoner 542 S: "WRN:32:This is a 24 bit patch which is not supported natively
534     yet."
535    
536     C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA EAR"
537 schoenebeck 708
538 senoner 542 S: "ERR:3456:Audio output driver 'ALSA' does not have a parameter
539     'EAR'."
540    
541     C: "GET AUDIO_OUTPUT_DEVICE INFO 123456"
542 schoenebeck 708
543 senoner 542 S: "ERR:9:There is no audio output device with index 123456."
544    
545     Normal result sets could be:
546    
547     1. Empty
548 schoenebeck 708
549 senoner 542 2. Single line
550 schoenebeck 708
551 senoner 542 3. Multi-line
552    
553     Empty result set is issued when the server only needed to acknowledge
554     the fact that the request was received and it was processed
555     successfully and no additional information is available. This result
556    
557    
558    
559 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 10]
560 schoenebeck 940
561 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
562 senoner 542
563    
564 schoenebeck 708 set has the following format:
565 senoner 542
566 schoenebeck 708 "OK"
567 senoner 542
568 schoenebeck 708 Example:
569 senoner 542
570 schoenebeck 708 C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 CHANNELS=4"
571    
572 senoner 542 S: "OK"
573    
574     Single line result sets are command specific. One example of a
575     single line result set is an empty line. Multi-line result sets are
576     command specific and may include one or more lines of information.
577     They MUST always end with the following line:
578    
579     "."
580    
581     Example:
582    
583     C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
584 schoenebeck 708
585 senoner 542 S: "DRIVER: ALSA"
586 schoenebeck 708
587 senoner 542 "CHANNELS: 2"
588 schoenebeck 708
589 senoner 542 "SAMPLERATE: 44100"
590 schoenebeck 708
591 senoner 542 "ACTIVE: true"
592 schoenebeck 708
593 senoner 542 "FRAGMENTS: 2"
594 schoenebeck 708
595 senoner 542 "FRAGMENTSIZE: 128"
596 schoenebeck 708
597 senoner 542 "CARD: '0,0'"
598 schoenebeck 708
599 senoner 542 "."
600    
601     In addition to above mentioned formats, warnings and empty result
602     sets MAY be indexed. In this case, they have the following formats
603     respectively:
604    
605     o "WRN[<index>]:<warning-code>:<warning-message>"
606 schoenebeck 708
607 senoner 542 o "OK[<index>]"
608    
609     where <index> is command specific and is used to indicate channel
610     number that the result set was related to or other integer value.
611    
612 schoenebeck 708
613    
614    
615 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 11]
616 schoenebeck 940
617 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
618 schoenebeck 708
619    
620 senoner 542 Each line of the result set MUST end with <CRLF>.
621    
622     Examples:
623    
624     C: "ADD CHANNEL"
625 schoenebeck 708
626 senoner 542 S: "OK[12]"
627    
628     C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"
629 schoenebeck 708
630 senoner 542 S: "WRN[0]:32:Sample rate not supported, using 44100 instead."
631    
632 schoenebeck 940 5.2. Subscribe/notify communication method
633 schoenebeck 708
634 senoner 542 This more sophisticated communication method is actually only an
635     extension of the simple request/response communication method. The
636     front-end still uses a TCP connection and sends the same commands on
637     the TCP connection. Two extra commands are SUBSCRIBE and UNSUBSCRIBE
638     commands that allow a client to tell the server that it is interested
639     in receiving notifications about certain events as they happen on the
640     server. The SUBSCRIBE command has the following syntax:
641    
642     SUBSCRIBE <event-id>
643    
644     where <event-id> will be replaced by the respective event that client
645     wants to subscribe to. Upon receiving such request, server SHOULD
646     respond with OK and start sending EVENT notifications when a given
647     even has occurred to the front-end when an event has occurred. It
648     MAY be possible certain events may be sent before OK response during
649     real time nature of their generation. Event messages have the
650     following format:
651    
652     NOTIFY:<event-id>:<custom-event-data>
653    
654     where <event-id> uniquely identifies the event that has occurred and
655     <custom-event-data> is event specific.
656    
657     Several rules must be followed by the server when generating events:
658    
659     1. Events MUST NOT be sent to any client who has not issued an
660     appropriate SUBSCRIBE command.
661 schoenebeck 708
662 senoner 542 2. Events MUST only be sent using the same connection that was used
663     to subscribe to them.
664 schoenebeck 708
665 senoner 542 3. When response is being sent to the client, event MUST be inserted
666     in the stream before or after the response, but NOT in the
667 schoenebeck 940 middle. Same is true about the response. It should never be
668 schoenebeck 708
669    
670    
671 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 12]
672 schoenebeck 940
673 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
674 schoenebeck 708
675    
676 senoner 542 inserted in the middle of the event message as well as any other
677     response.
678    
679     If the client is not interested in a particular event anymore it MAY
680     issue UNSUBSCRIBE command using the following syntax:
681    
682     UNSUBSCRIBE <event-id>
683    
684     where <event-id> will be replace by the respective event that client
685     is no longer interested in receiving. For a list of supported events
686 schoenebeck 575 see Section 8.
687 senoner 542
688     Example: the fill states of disk stream buffers have changed on
689     sampler channel 4 and the LinuxSampler instance will react by sending
690     the following message to all clients who subscribed to this event:
691    
692     NOTIFY:CHANNEL_BUFFER_FILL:4 [35]62%,[33]80%,[37]98%
693    
694     Which means there are currently three active streams on sampler
695     channel 4, where the stream with ID "35" is filled by 62%, stream
696     with ID 33 is filled by 80% and stream with ID 37 is filled by 98%.
697    
698     Clients may choose to open more than one connection to the server and
699     use some connections to receive notifications while using other
700     connections to issue commands to the back-end. This is entirely
701     legal and up to the implementation. This does not change the
702     protocol in any way and no special restrictions exist on the server
703     to allow or disallow this or to track what connections belong to what
704     front-ends. Server will listen on a single port, accept multiple
705     connections and support protocol described in this specification in
706     it's entirety on this single port on each connection that it
707     accepted.
708    
709     Due to the fact that TCP is used for this communication, dead peers
710     will be detected automatically by the OS TCP stack. While it may
711     take a while to detect dead peers if no traffic is being sent from
712     server to client (TCP keep-alive timer is set to 2 hours on many
713     OSes) it will not be an issue here as when notifications are sent by
714     the server, dead client will be detected quickly.
715    
716     When connection is closed for any reason server MUST forget all
717     subscriptions that were made on this connection. If client
718     reconnects it MUST resubscribe to all events that it wants to
719     receive.
720    
721    
722    
723    
724    
725    
726    
727 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 13]
728 schoenebeck 940
729 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
730 senoner 542
731    
732 schoenebeck 575 6. Description for control commands
733 senoner 542
734     This chapter will describe the available control commands that can be
735     sent on the TCP connection in detail. Some certain commands (e.g.
736 schoenebeck 708 "GET CHANNEL INFO" (Section 6.4.10) or "GET ENGINE INFO"
737     (Section 6.4.9)) lead to multiple-line responses. In this case
738     LinuxSampler signals the end of the response by a "." (single dot)
739     line.
740 senoner 542
741 schoenebeck 940 6.1. Ignored lines and comments
742 senoner 542
743     White lines, that is lines which only contain space and tabulator
744     characters, and lines that start with a "#" character are ignored,
745     thus it's possible for example to group commands and to place
746     comments in a LSCP script file.
747    
748 schoenebeck 940 6.2. Configuring audio drivers
749 senoner 542
750     Instances of drivers in LinuxSampler are called devices. You can use
751 schoenebeck 708 multiple audio devices simultaneously, e.g. to output the sound of
752 senoner 542 one sampler channel using the ALSA audio output driver, and on
753     another sampler channel you might want to use the JACK audio output
754     driver. For particular audio output systems it's also possible to
755 schoenebeck 708 create several devices of the same audio output driver, e.g. two
756 senoner 542 separate ALSA audio output devices for using two different sound
757     cards at the same time. This chapter describes all commands to
758     configure LinuxSampler's audio output devices and their parameters.
759    
760     Instead of defining commands and parameters for each driver
761     individually, all possible parameters, their meanings and possible
762     values have to be obtained at runtime. This makes the protocol a bit
763     abstract, but has the advantage, that front-ends can be written
764     independently of what drivers are currently implemented and what
765 schoenebeck 708 parameters these drivers are actually offering. This means front-
766     ends can even handle drivers which are implemented somewhere in
767 senoner 542 future without modifying the front-end at all.
768    
769     Note: examples in this chapter showing particular parameters of
770     drivers are not meant as specification of the drivers' parameters.
771     Driver implementations in LinuxSampler might have complete different
772     parameter names and meanings than shown in these examples or might
773     change in future, so these examples are only meant for showing how to
774     retrieve what parameters drivers are offering, how to retrieve their
775     possible values, etc.
776    
777    
778    
779    
780    
781 schoenebeck 974
782    
783 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 14]
784 schoenebeck 940
785 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
786 senoner 542
787    
788 schoenebeck 974 6.2.1. Getting amount of available audio output drivers
789    
790     Use the following command to get the number of audio output drivers
791 schoenebeck 708 currently available for the LinuxSampler instance:
792    
793 senoner 542 GET AVAILABLE_AUDIO_OUTPUT_DRIVERS
794    
795     Possible Answers:
796    
797     LinuxSampler will answer by sending the number of audio output
798     drivers.
799    
800     Example:
801    
802     C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
803 schoenebeck 708
804 senoner 542 S: "2"
805    
806 schoenebeck 940 6.2.2. Getting all available audio output drivers
807 schoenebeck 708
808 senoner 542 Use the following command to list all audio output drivers currently
809     available for the LinuxSampler instance:
810    
811     LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS
812    
813     Possible Answers:
814    
815     LinuxSampler will answer by sending comma separated character
816     strings, each symbolizing an audio output driver.
817    
818     Example:
819    
820     C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"
821 schoenebeck 708
822 senoner 542 S: "ALSA,JACK"
823    
824 schoenebeck 940 6.2.3. Getting information about a specific audio output driver
825 schoenebeck 708
826 senoner 542 Use the following command to get detailed information about a
827     specific audio output driver:
828    
829     GET AUDIO_OUTPUT_DRIVER INFO <audio-output-driver>
830    
831     Where <audio-output-driver> is the name of the audio output driver,
832 schoenebeck 575 returned by the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2)
833 senoner 542 command.
834    
835     Possible Answers:
836    
837 schoenebeck 708
838    
839 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 15]
840 schoenebeck 940
841 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
842 schoenebeck 708
843 schoenebeck 940
844 senoner 542 LinuxSampler will answer by sending a <CRLF> separated list. Each
845     answer line begins with the information category name followed by
846     a colon and then a space character <SP> and finally the info
847     character string to that info category. At the moment the
848     following information categories are defined:
849    
850    
851    
852 schoenebeck 708 DESCRIPTION -
853 senoner 542
854 schoenebeck 708 character string describing the audio output driver
855 senoner 542
856 schoenebeck 708 VERSION -
857 senoner 542
858 schoenebeck 708 character string reflecting the driver's version
859 senoner 542
860     PARAMETERS -
861 schoenebeck 708
862 senoner 542 comma separated list of all parameters available for the
863     given audio output driver, at least parameters 'channels',
864     'samplerate' and 'active' are offered by all audio output
865     drivers
866 schoenebeck 708
867 senoner 542 The mentioned fields above don't have to be in particular order.
868    
869     Example:
870    
871     C: "GET AUDIO_OUTPUT_DRIVER INFO ALSA"
872 schoenebeck 708
873 senoner 542 S: "DESCRIPTION: Advanced Linux Sound Architecture"
874 schoenebeck 708
875 senoner 542 "VERSION: 1.0"
876 schoenebeck 708
877 senoner 542 "PARAMETERS: DRIVER,CHANNELS,SAMPLERATE,ACTIVE,FRAGMENTS,
878     FRAGMENTSIZE,CARD"
879 schoenebeck 708
880 senoner 542 "."
881    
882 schoenebeck 940 6.2.4. Getting information about specific audio output driver parameter
883 schoenebeck 708
884 senoner 542 Use the following command to get detailed information about a
885     specific audio output driver parameter:
886    
887     GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO <audio> <prm> [<deplist>]
888    
889     Where <audio> is the name of the audio output driver as returned by
890 schoenebeck 575 the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2) command,
891 schoenebeck 940 <prm> a specific parameter name for which information should be
892 schoenebeck 708
893    
894    
895 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 16]
896 schoenebeck 940
897 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
898 schoenebeck 708
899    
900     obtained (as returned by the "GET AUDIO_OUTPUT_DRIVER INFO"
901     (Section 6.2.3) command) and <deplist> is an optional list of
902     parameters on which the sought parameter <prm> depends on, <deplist>
903     is a list of key-value pairs in form of "key1=val1 key2=val2 ...",
904     where character string values are encapsulated into apostrophes (').
905     Arguments given with <deplist> which are not dependency parameters of
906     <prm> will be ignored, means the front-end application can simply put
907     all parameters into <deplist> with the values already selected by the
908 senoner 542 user.
909    
910     Possible Answers:
911    
912     LinuxSampler will answer by sending a <CRLF> separated list. Each
913     answer line begins with the information category name followed by
914     a colon and then a space character <SP> and finally the info
915     character string to that info category. There are information
916     which is always returned, independently of the given driver
917     parameter and there are optional information which is only shown
918     dependently to given driver parameter. At the moment the
919     following information categories are defined:
920    
921     TYPE -
922 schoenebeck 708
923 senoner 542 either "BOOL" for boolean value(s) or "INT" for integer
924     value(s) or "FLOAT" for dotted number(s) or "STRING" for
925     character string(s) (always returned, no matter which driver
926     parameter)
927 schoenebeck 708
928 senoner 542 DESCRIPTION -
929 schoenebeck 708
930 senoner 542 arbitrary text describing the purpose of the parameter (always
931     returned, no matter which driver parameter)
932 schoenebeck 708
933 senoner 542 MANDATORY -
934 schoenebeck 708
935 senoner 542 either true or false, defines if this parameter must be given
936     when the device is to be created with the 'CREATE
937 schoenebeck 575 AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command (always returned,
938 senoner 542 no matter which driver parameter)
939 schoenebeck 708
940 senoner 542 FIX -
941 schoenebeck 708
942 senoner 542 either true or false, if false then this parameter can be
943     changed at any time, once the device is created by the 'CREATE
944 schoenebeck 575 AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command (always returned,
945 senoner 542 no matter which driver parameter)
946 schoenebeck 708
947    
948    
949    
950    
951 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 17]
952 schoenebeck 940
953 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
954 schoenebeck 708
955    
956 senoner 542 MULTIPLICITY -
957 schoenebeck 708
958 senoner 542 either true or false, defines if this parameter allows only one
959     value or a list of values, where true means multiple values and
960     false only a single value allowed (always returned, no matter
961     which driver parameter)
962 schoenebeck 708
963 senoner 542 DEPENDS -
964 schoenebeck 708
965 schoenebeck 561 comma separated list of parameters this parameter depends on,
966 senoner 542 means the values for fields 'DEFAULT', 'RANGE_MIN', 'RANGE_MAX'
967     and 'POSSIBILITIES' might depend on these listed parameters,
968     for example assuming that an audio driver (like the ALSA
969     driver) offers parameters 'card' and 'samplerate' then
970     parameter 'samplerate' would depend on 'card' because the
971     possible values for 'samplerate' depends on the sound card
972     which can be chosen by the 'card' parameter (optionally
973     returned, dependent to driver parameter)
974 schoenebeck 708
975 senoner 542 DEFAULT -
976 schoenebeck 708
977 senoner 542 reflects the default value for this parameter which is used
978     when the device is created and not explicitly given with the
979 schoenebeck 575 'CREATE AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command, in case
980 senoner 542 of MULTIPLCITY=true, this is a comma separated list, that's why
981     character strings are encapsulated into apostrophes (')
982     (optionally returned, dependent to driver parameter)
983 schoenebeck 708
984 senoner 542 RANGE_MIN -
985 schoenebeck 708
986 senoner 542 defines lower limit of the allowed value range for this
987     parameter, can be an integer value as well as a dotted number,
988     this parameter is often used in conjunction with RANGE_MAX, but
989     may also appear without (optionally returned, dependent to
990     driver parameter)
991 schoenebeck 708
992 senoner 542 RANGE_MAX -
993 schoenebeck 708
994 senoner 542 defines upper limit of the allowed value range for this
995     parameter, can be an integer value as well as a dotted number,
996     this parameter is often used in conjunction with RANGE_MIN, but
997     may also appear without (optionally returned, dependent to
998     driver parameter)
999 schoenebeck 708
1000 senoner 542 POSSIBILITIES -
1001 schoenebeck 708
1002 senoner 542 comma separated list of possible values for this parameter,
1003     character strings are encapsulated into apostrophes (optionally
1004 schoenebeck 708
1005    
1006    
1007 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 18]
1008 schoenebeck 940
1009 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
1010 schoenebeck 708
1011    
1012 senoner 542 returned, dependent to driver parameter)
1013    
1014     The mentioned fields above don't have to be in particular order.
1015    
1016     Examples:
1017    
1018     C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA CARD"
1019 schoenebeck 708
1020 senoner 542 S: "DESCRIPTION: sound card to be used"
1021 schoenebeck 708
1022 senoner 542 "TYPE: STRING"
1023 schoenebeck 708
1024 senoner 542 "MANDATORY: false"
1025 schoenebeck 708
1026 senoner 542 "FIX: true"
1027 schoenebeck 708
1028 senoner 542 "MULTIPLICITY: false"
1029 schoenebeck 708
1030 senoner 542 "DEFAULT: '0,0'"
1031 schoenebeck 708
1032 senoner 542 "POSSIBILITIES: '0,0','1,0','2,0'"
1033 schoenebeck 708
1034 senoner 542 "."
1035    
1036     C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE"
1037 schoenebeck 708
1038 senoner 542 S: "DESCRIPTION: output sample rate in Hz"
1039 schoenebeck 708
1040 senoner 542 "TYPE: INT"
1041 schoenebeck 708
1042 senoner 542 "MANDATORY: false"
1043 schoenebeck 708
1044 senoner 542 "FIX: false"
1045 schoenebeck 708
1046 senoner 542 "MULTIPLICITY: false"
1047 schoenebeck 708
1048 senoner 542 "DEPENDS: card"
1049 schoenebeck 708
1050 senoner 542 "DEFAULT: 44100"
1051 schoenebeck 708
1052 senoner 542 "."
1053    
1054     C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE
1055     CARD='0,0'"
1056 schoenebeck 708
1057 senoner 542 S: "DESCRIPTION: output sample rate in Hz"
1058 schoenebeck 708
1059    
1060    
1061    
1062    
1063 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 19]
1064 schoenebeck 940
1065 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
1066 schoenebeck 708
1067    
1068 senoner 542 "TYPE: INT"
1069 schoenebeck 708
1070 senoner 542 "MANDATORY: false"
1071 schoenebeck 708
1072 senoner 542 "FIX: false"
1073 schoenebeck 708
1074 senoner 542 "MULTIPLICITY: false"
1075 schoenebeck 708
1076 senoner 542 "DEPENDS: card"
1077 schoenebeck 708
1078 senoner 542 "DEFAULT: 44100"
1079 schoenebeck 708
1080 senoner 542 "RANGE_MIN: 22050"
1081    
1082 schoenebeck 708 "RANGE_MAX: 96000"
1083 senoner 542
1084 schoenebeck 708 "."
1085 senoner 542
1086 schoenebeck 940 6.2.5. Creating an audio output device
1087 senoner 542
1088 schoenebeck 940 Use the following command to create a new audio output device for the
1089     desired audio output system:
1090 senoner 542
1091     CREATE AUDIO_OUTPUT_DEVICE <audio-output-driver> [<param-list>]
1092    
1093     Where <audio-output-driver> should be replaced by the desired audio
1094 schoenebeck 575 output system as returned by the "LIST
1095 schoenebeck 708 AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2) command and <param-
1096     list> by an optional list of driver specific parameters in form of
1097     "key1=val1 key2=val2 ...", where character string values should be
1098     encapsulated into apostrophes ('). Note that there might be drivers
1099     which require parameter(s) to be given with this command. Use the
1100     previously described commands in this chapter to get this
1101 schoenebeck 575 information.
1102 senoner 542
1103     Possible Answers:
1104    
1105     "OK[<device-id>]" -
1106 schoenebeck 708
1107 senoner 542 in case the device was successfully created, where <device-id>
1108     is the numerical ID of the new device
1109 schoenebeck 708
1110 senoner 542 "WRN[<device-id>]:<warning-code>:<warning-message>" -
1111 schoenebeck 708
1112 senoner 542 in case the device was created successfully, where <device-id>
1113     is the numerical ID of the new device, but there are noteworthy
1114 schoenebeck 708 issue(s) related (e.g. sound card doesn't support given
1115 schoenebeck 940 hardware parameters and the driver is using fall-back values),
1116 schoenebeck 708
1117    
1118    
1119 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 20]
1120 schoenebeck 940
1121 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
1122 schoenebeck 708
1123    
1124 senoner 542 providing an appropriate warning code and warning message
1125 schoenebeck 708
1126 senoner 542 "ERR:<error-code>:<error-message>" -
1127 schoenebeck 708
1128 senoner 542 in case it failed, providing an appropriate error code and
1129     error message
1130    
1131     Examples:
1132    
1133     C: "CREATE AUDIO_OUTPUT_DEVICE ALSA"
1134 schoenebeck 708
1135 senoner 542 S: "OK[0]"
1136    
1137     C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"
1138 schoenebeck 708
1139 senoner 542 S: "OK[1]"
1140    
1141 schoenebeck 940 6.2.6. Destroying an audio output device
1142 schoenebeck 708
1143 senoner 542 Use the following command to destroy a created output device:
1144    
1145 schoenebeck 575 DESTROY AUDIO_OUTPUT_DEVICE <device-id>
1146    
1147     Where <device-id> should be replaced by the numerical ID of the audio
1148 schoenebeck 708 output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
1149     (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
1150     command.
1151 senoner 542
1152     Possible Answers:
1153    
1154     "OK" -
1155 schoenebeck 708
1156 senoner 542 in case the device was successfully destroyed
1157 schoenebeck 708
1158 senoner 542 "WRN:<warning-code>:<warning-message>" -
1159 schoenebeck 708
1160 senoner 542 in case the device was destroyed successfully, but there are
1161 schoenebeck 708 noteworthy issue(s) related (e.g. an audio over ethernet driver
1162     was unloaded but the other host might not be informed about
1163     this situation), providing an appropriate warning code and
1164     warning message
1165    
1166 senoner 542 "ERR:<error-code>:<error-message>" -
1167 schoenebeck 708
1168 senoner 542 in case it failed, providing an appropriate error code and
1169     error message
1170    
1171 schoenebeck 940 Example:
1172 schoenebeck 708
1173    
1174    
1175 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 21]
1176 schoenebeck 940
1177 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
1178 schoenebeck 708
1179    
1180 senoner 542 C: "DESTROY AUDIO_OUTPUT_DEVICE 0"
1181 schoenebeck 708
1182 senoner 542 S: "OK"
1183    
1184 schoenebeck 940 6.2.7. Getting all created audio output device count
1185 schoenebeck 708
1186 senoner 542 Use the following command to count all created audio output devices:
1187    
1188     GET AUDIO_OUTPUT_DEVICES
1189    
1190     Possible Answers:
1191    
1192     LinuxSampler will answer by sending the current number of all
1193     audio output devices.
1194    
1195     Example:
1196    
1197     C: "GET AUDIO_OUTPUT_DEVICES"
1198 schoenebeck 708
1199 senoner 542 S: "4"
1200    
1201 schoenebeck 940 6.2.8. Getting all created audio output device list
1202 schoenebeck 708
1203 senoner 542 Use the following command to list all created audio output devices:
1204    
1205     LIST AUDIO_OUTPUT_DEVICES
1206    
1207     Possible Answers:
1208    
1209 schoenebeck 575 LinuxSampler will answer by sending a comma separated list with
1210     the numerical IDs of all audio output devices.
1211    
1212 senoner 542 Example:
1213    
1214     C: "LIST AUDIO_OUTPUT_DEVICES"
1215 schoenebeck 708
1216 senoner 542 S: "0,1,4,5"
1217    
1218 schoenebeck 940 6.2.9. Getting current settings of an audio output device
1219 schoenebeck 708
1220 senoner 542 Use the following command to get current settings of a specific,
1221     created audio output device:
1222    
1223 schoenebeck 940 GET AUDIO_OUTPUT_DEVICE INFO <device-id>
1224 schoenebeck 708
1225 schoenebeck 940 Where <device-id> should be replaced by numerical ID of the audio
1226     output device as e.g. returned by the "LIST AUDIO_OUTPUT_DEVICES"
1227     (Section 6.2.8) command.
1228 schoenebeck 708
1229    
1230    
1231 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 22]
1232 schoenebeck 940
1233 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
1234 schoenebeck 708
1235    
1236 senoner 542 Possible Answers:
1237    
1238     LinuxSampler will answer by sending a <CRLF> separated list. Each
1239     answer line begins with the information category name followed by a
1240     colon and then a space character <SP> and finally the info character
1241     string to that info category. As some parameters might allow
1242     multiple values, character strings are encapsulated into apostrophes
1243     ('). At the moment the following information categories are defined
1244     (independently of device):
1245    
1246     DRIVER -
1247 schoenebeck 708
1248 senoner 542 identifier of the used audio output driver, as also returned by
1249 schoenebeck 575 the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2)
1250 senoner 542 command
1251 schoenebeck 708
1252 senoner 542 CHANNELS -
1253 schoenebeck 708
1254 senoner 542 amount of audio output channels this device currently offers
1255 schoenebeck 708
1256 senoner 542 SAMPLERATE -
1257 schoenebeck 708
1258 senoner 542 playback sample rate the device uses
1259 schoenebeck 708
1260 senoner 542 ACTIVE -
1261 schoenebeck 708
1262 senoner 542 either true or false, if false then the audio device is
1263     inactive and doesn't output any sound, nor do the sampler
1264     channels connected to this audio device render any audio
1265    
1266     The mentioned fields above don't have to be in particular order. The
1267     fields above are only those fields which are returned by all audio
1268     output devices. Every audio output driver might have its own,
1269 schoenebeck 575 additional driver specific parameters (see Section 6.2.3) which are
1270 senoner 542 also returned by this command.
1271    
1272 schoenebeck 708 Example:
1273 senoner 542
1274 schoenebeck 708 C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
1275 senoner 542
1276 schoenebeck 708 S: "DRIVER: ALSA"
1277 senoner 542
1278 schoenebeck 940 "CHANNELS: 2"
1279 senoner 542
1280 schoenebeck 940 "SAMPLERATE: 44100"
1281 senoner 542
1282 schoenebeck 940 "ACTIVE: true"
1283 schoenebeck 575
1284 schoenebeck 708
1285    
1286    
1287 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 23]
1288 schoenebeck 940
1289 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
1290 schoenebeck 708
1291    
1292 senoner 542 "FRAGMENTS: 2"
1293 schoenebeck 708
1294 senoner 542 "FRAGMENTSIZE: 128"
1295 schoenebeck 708
1296 senoner 542 "CARD: '0,0'"
1297 schoenebeck 708
1298 senoner 542 "."
1299    
1300 schoenebeck 940 6.2.10. Changing settings of audio output devices
1301 schoenebeck 708
1302 senoner 542 Use the following command to alter a specific setting of a created
1303     audio output device:
1304    
1305     SET AUDIO_OUTPUT_DEVICE_PARAMETER <device-id> <key>=<value>
1306    
1307     Where <device-id> should be replaced by the numerical ID of the audio
1308 schoenebeck 708 output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
1309     (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
1310     command, <key> by the name of the parameter to change and <value> by
1311     the new value for this parameter.
1312 senoner 542
1313     Possible Answers:
1314    
1315     "OK" -
1316 schoenebeck 708
1317 senoner 542 in case setting was successfully changed
1318 schoenebeck 708
1319 senoner 542 "WRN:<warning-code>:<warning-message>" -
1320 schoenebeck 708
1321 senoner 542 in case setting was changed successfully, but there are
1322     noteworthy issue(s) related, providing an appropriate warning
1323     code and warning message
1324 schoenebeck 708
1325 senoner 542 "ERR:<error-code>:<error-message>" -
1326 schoenebeck 708
1327 senoner 542 in case it failed, providing an appropriate error code and
1328     error message
1329    
1330     Example:
1331    
1332 schoenebeck 940 C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"
1333 schoenebeck 708
1334 schoenebeck 940 S: "OK"
1335 schoenebeck 708
1336    
1337    
1338    
1339    
1340    
1341 schoenebeck 974
1342    
1343 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 24]
1344 schoenebeck 940
1345 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
1346 schoenebeck 708
1347 senoner 542
1348 schoenebeck 974 6.2.11. Getting information about an audio channel
1349    
1350     Use the following command to get information about an audio channel:
1351    
1352 senoner 542 GET AUDIO_OUTPUT_CHANNEL INFO <device-id> <audio-chan>
1353    
1354 schoenebeck 575 Where <device-id> is the numerical ID of the audio output device as
1355     given by the "CREATE AUDIO_OUTPUT_DEVICE" (Section 6.2.5) or "LIST
1356     AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command and <audio-chan> the
1357     audio channel number.
1358    
1359     Possible Answers:
1360    
1361 senoner 542 LinuxSampler will answer by sending a <CRLF> separated list. Each
1362     answer line begins with the information category name followed by
1363     a colon and then a space character <SP> and finally the info
1364     character string to that info category. At the moment the
1365     following information categories are defined:
1366    
1367 schoenebeck 708
1368    
1369 senoner 542 NAME -
1370 schoenebeck 708
1371 senoner 542 arbitrary character string naming the channel, which doesn't
1372     have to be unique (always returned by all audio channels)
1373 schoenebeck 708
1374 senoner 542 IS_MIX_CHANNEL -
1375 schoenebeck 708
1376 senoner 542 either true or false, a mix-channel is not a real,
1377     independent audio channel, but a virtual channel which is
1378     mixed to another real channel, this mechanism is needed for
1379     sampler engines which need more audio channels than the used
1380     audio system might be able to offer (always returned by all
1381     audio channels)
1382 schoenebeck 708
1383 senoner 542 MIX_CHANNEL_DESTINATION -
1384 schoenebeck 708
1385 senoner 542 numerical ID (positive integer including 0) which reflects
1386     the real audio channel (of the same audio output device)
1387     this mix channel refers to, means where the audio signal
1388     actually will be routed / added to (only returned in case
1389     the audio channel is mix channel)
1390    
1391     The mentioned fields above don't have to be in particular order. The
1392     fields above are only those fields which are generally returned for
1393     the described cases by all audio channels regardless of the audio
1394     driver. Every audio channel might have its own, additional driver
1395     and channel specific parameters.
1396    
1397    
1398 schoenebeck 940
1399 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 25]
1400 schoenebeck 974
1401 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
1402 schoenebeck 940
1403    
1404 schoenebeck 974 Examples:
1405 schoenebeck 940
1406 senoner 542 C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 0"
1407 schoenebeck 708
1408 senoner 542 S: "NAME: studio monitor left"
1409 schoenebeck 708
1410 senoner 542 "IS_MIX_CHANNEL: false"
1411 schoenebeck 708
1412 senoner 542 "."
1413    
1414     C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 1"
1415 schoenebeck 708
1416 senoner 542 S: "NAME: studio monitor right"
1417 schoenebeck 708
1418 senoner 542 "IS_MIX_CHANNEL: false"
1419 schoenebeck 708
1420 senoner 542 "."
1421    
1422 schoenebeck 708 C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"
1423 senoner 542
1424 schoenebeck 708 S: "NAME: studio monitor left"
1425 senoner 542
1426 schoenebeck 708 "IS_MIX_CHANNEL: true"
1427 senoner 542
1428 schoenebeck 708 "MIX_CHANNEL_DESTINATION: 1"
1429 senoner 542
1430 schoenebeck 575 "."
1431    
1432 senoner 542 C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"
1433 schoenebeck 708
1434 senoner 542 S: "NAME: 'ardour (left)'"
1435 schoenebeck 708
1436 senoner 542 "IS_MIX_CHANNEL: false"
1437 schoenebeck 708
1438 senoner 542 "JACK_BINDINGS: 'ardour:0'"
1439 schoenebeck 708
1440 senoner 542 "."
1441    
1442 schoenebeck 940 6.2.12. Getting information about specific audio channel parameter
1443 schoenebeck 708
1444 senoner 542 Use the following command to get detailed information about specific
1445     audio channel parameter:
1446    
1447     GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO <dev-id> <chan> <param>
1448    
1449     Where <dev-id> is the numerical ID of the audio output device as
1450 schoenebeck 575 returned by the "CREATE AUDIO_OUTPUT_DEVICE" (Section 6.2.5) or "LIST
1451     AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command, <chan> the audio
1452 schoenebeck 940
1453    
1454    
1455 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 26]
1456 schoenebeck 940
1457 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
1458 schoenebeck 940
1459    
1460 schoenebeck 974 channel number and <param> a specific channel parameter name for
1461     which information should be obtained (as returned by the "GET
1462 schoenebeck 575 AUDIO_OUTPUT_CHANNEL INFO" (Section 6.2.11) command).
1463 senoner 542
1464     Possible Answers:
1465    
1466     LinuxSampler will answer by sending a <CRLF> separated list. Each
1467     answer line begins with the information category name followed by
1468     a colon and then a space character <SP> and finally the info
1469     character string to that info category. There are information
1470     which is always returned, independently of the given channel
1471     parameter and there is optional information which is only shown
1472     dependently to the given audio channel. At the moment the
1473     following information categories are defined:
1474    
1475 schoenebeck 708
1476    
1477 senoner 542 TYPE -
1478 schoenebeck 708
1479 senoner 542 either "BOOL" for boolean value(s) or "INT" for integer
1480     value(s) or "FLOAT" for dotted number(s) or "STRING" for
1481     character string(s) (always returned)
1482 schoenebeck 708
1483 senoner 542 DESCRIPTION -
1484 schoenebeck 708
1485 senoner 542 arbitrary text describing the purpose of the parameter
1486     (always returned)
1487 schoenebeck 708
1488 senoner 542 FIX -
1489 schoenebeck 708
1490 senoner 542 either true or false, if true then this parameter is read
1491     only, thus cannot be altered (always returned)
1492 schoenebeck 575
1493 schoenebeck 708 MULTIPLICITY -
1494 schoenebeck 575
1495 schoenebeck 708 either true or false, defines if this parameter allows only
1496     one value or a list of values, where true means multiple
1497     values and false only a single value allowed (always
1498     returned)
1499 schoenebeck 575
1500 schoenebeck 940 RANGE_MIN -
1501 schoenebeck 575
1502 schoenebeck 940 defines lower limit of the allowed value range for this
1503     parameter, can be an integer value as well as a dotted
1504     number, usually used in conjunction with 'RANGE_MAX', but
1505     may also appear without (optionally returned, dependent to
1506     driver and channel parameter)
1507 schoenebeck 575
1508    
1509 schoenebeck 708
1510    
1511 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 27]
1512 schoenebeck 940
1513 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
1514 schoenebeck 708
1515    
1516 senoner 542 RANGE_MAX -
1517 schoenebeck 708
1518 senoner 542 defines upper limit of the allowed value range for this
1519     parameter, can be an integer value as well as a dotted
1520     number, usually used in conjunction with 'RANGE_MIN', but
1521     may also appear without (optionally returned, dependent to
1522     driver and channel parameter)
1523 schoenebeck 708
1524 senoner 542 POSSIBILITIES -
1525 schoenebeck 708
1526 senoner 542 comma separated list of possible values for this parameter,
1527     character strings are encapsulated into apostrophes
1528     (optionally returned, dependent to driver and channel
1529     parameter)
1530 schoenebeck 708
1531 senoner 542 The mentioned fields above don't have to be in particular order.
1532    
1533     Example:
1534    
1535     C: "GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO 1 0 JACK_BINDINGS"
1536 schoenebeck 708
1537 senoner 542 S: "DESCRIPTION: bindings to other JACK clients"
1538 schoenebeck 708
1539 senoner 542 "TYPE: STRING"
1540 schoenebeck 708
1541 senoner 542 "FIX: false"
1542 schoenebeck 708
1543 senoner 542 "MULTIPLICITY: true"
1544 schoenebeck 708
1545 senoner 542 "POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"
1546 schoenebeck 708
1547 senoner 542 "."
1548    
1549 schoenebeck 940 6.2.13. Changing settings of audio output channels
1550 schoenebeck 708
1551 senoner 542 Use the following command to alter a specific setting of an audio
1552     output channel:
1553    
1554     SET AUDIO_OUTPUT_CHANNEL_PARAMETER <dev-id> <chn> <key>=<value>
1555    
1556     Where <dev-id> should be replaced by the numerical ID of the audio
1557 schoenebeck 575 output device as returned by the "CREATE AUDIO_OUTPUT_DEVICE"
1558     (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
1559     command, <chn> by the audio channel number, <key> by the name of the
1560 senoner 542 parameter to change and <value> by the new value for this parameter.
1561    
1562     Possible Answers:
1563    
1564 schoenebeck 940
1565    
1566    
1567 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 28]
1568 schoenebeck 940
1569 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
1570 schoenebeck 940
1571    
1572 schoenebeck 708 "OK" -
1573 schoenebeck 575
1574 schoenebeck 708 in case setting was successfully changed
1575 schoenebeck 575
1576 schoenebeck 708 "WRN:<warning-code>:<warning-message>" -
1577 schoenebeck 575
1578 senoner 542 in case setting was changed successfully, but there are
1579     noteworthy issue(s) related, providing an appropriate warning
1580     code and warning message
1581 schoenebeck 708
1582 senoner 542 "ERR:<error-code>:<error-message>" -
1583 schoenebeck 708
1584 senoner 542 in case it failed, providing an appropriate error code and
1585     error message
1586    
1587     Example:
1588    
1589     C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"
1590 schoenebeck 708
1591 senoner 542 S: "OK"
1592    
1593     C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"
1594 schoenebeck 708
1595 senoner 542 S: "OK"
1596    
1597 schoenebeck 940 6.3. Configuring MIDI input drivers
1598 schoenebeck 708
1599 senoner 542 Instances of drivers in LinuxSampler are called devices. You can use
1600 schoenebeck 708 multiple MIDI devices simultaneously, e.g. to use MIDI over ethernet
1601 senoner 542 as MIDI input on one sampler channel and ALSA as MIDI input on
1602     another sampler channel. For particular MIDI input systems it's also
1603     possible to create several devices of the same MIDI input type. This
1604     chapter describes all commands to configure LinuxSampler's MIDI input
1605     devices and their parameters.
1606    
1607     Instead of defining commands and parameters for each driver
1608     individually, all possible parameters, their meanings and possible
1609     values have to be obtained at runtime. This makes the protocol a bit
1610     abstract, but has the advantage, that front-ends can be written
1611     independently of what drivers are currently implemented and what
1612 schoenebeck 708 parameters these drivers are actually offering. This means front-
1613     ends can even handle drivers which are implemented somewhere in
1614 senoner 542 future without modifying the front-end at all.
1615    
1616     Commands for configuring MIDI input devices are pretty much the same
1617     as the commands for configuring audio output drivers, already
1618     described in the last chapter.
1619    
1620 schoenebeck 940
1621    
1622    
1623 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 29]
1624 schoenebeck 940
1625 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
1626 schoenebeck 940
1627    
1628 senoner 542 Note: examples in this chapter showing particular parameters of
1629     drivers are not meant as specification of the drivers' parameters.
1630     Driver implementations in LinuxSampler might have complete different
1631     parameter names and meanings than shown in these examples or might
1632     change in future, so these examples are only meant for showing how to
1633     retrieve what parameters drivers are offering, how to retrieve their
1634     possible values, etc.
1635    
1636 schoenebeck 940 6.3.1. Getting amount of available MIDI input drivers
1637 schoenebeck 575
1638 senoner 542 Use the following command to get the number of MIDI input drivers
1639     currently available for the LinuxSampler instance:
1640    
1641     GET AVAILABLE_MIDI_INPUT_DRIVERS
1642    
1643     Possible Answers:
1644    
1645     LinuxSampler will answer by sending the number of available MIDI
1646     input drivers.
1647    
1648     Example:
1649    
1650     C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"
1651 schoenebeck 708
1652 senoner 542 S: "2"
1653    
1654 schoenebeck 940 6.3.2. Getting all available MIDI input drivers
1655 schoenebeck 708
1656 senoner 542 Use the following command to list all MIDI input drivers currently
1657     available for the LinuxSampler instance:
1658    
1659     LIST AVAILABLE_MIDI_INPUT_DRIVERS
1660    
1661     Possible Answers:
1662    
1663     LinuxSampler will answer by sending comma separated character
1664     strings, each symbolizing a MIDI input driver.
1665    
1666     Example:
1667    
1668     C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
1669 schoenebeck 708
1670 senoner 542 S: "ALSA,JACK"
1671    
1672 schoenebeck 708
1673 senoner 542
1674 schoenebeck 940
1675    
1676 schoenebeck 974
1677    
1678    
1679 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 30]
1680 schoenebeck 940
1681 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
1682 schoenebeck 940
1683    
1684 schoenebeck 974 6.3.3. Getting information about a specific MIDI input driver
1685    
1686     Use the following command to get detailed information about a
1687     specific MIDI input driver:
1688    
1689 senoner 542 GET MIDI_INPUT_DRIVER INFO <midi-input-driver>
1690    
1691 schoenebeck 575 Where <midi-input-driver> is the name of the MIDI input driver as
1692     returned by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2)
1693     command.
1694 senoner 542
1695     Possible Answers:
1696    
1697     LinuxSampler will answer by sending a <CRLF> separated list. Each
1698     answer line begins with the information category name followed by
1699     a colon and then a space character <SP> and finally the info
1700     character string to that info category. At the moment the
1701     following information categories are defined:
1702    
1703 schoenebeck 708
1704    
1705 senoner 542 DESCRIPTION -
1706 schoenebeck 708
1707 senoner 542 arbitrary description text about the MIDI input driver
1708 schoenebeck 708
1709 senoner 542 VERSION -
1710 schoenebeck 708
1711 senoner 542 arbitrary character string regarding the driver's version
1712 schoenebeck 708
1713 senoner 542 PARAMETERS -
1714 schoenebeck 708
1715 senoner 542 comma separated list of all parameters available for the
1716     given MIDI input driver
1717 schoenebeck 708
1718 senoner 542 The mentioned fields above don't have to be in particular order.
1719    
1720     Example:
1721    
1722     C: "GET MIDI_INPUT_DRIVER INFO ALSA"
1723 schoenebeck 708
1724 senoner 542 S: "DESCRIPTION: Advanced Linux Sound Architecture"
1725 schoenebeck 708
1726 senoner 542 "VERSION: 1.0"
1727 schoenebeck 708
1728 senoner 542 "PARAMETERS: DRIVER,ACTIVE"
1729 schoenebeck 708
1730 senoner 542 "."
1731    
1732 schoenebeck 708
1733 senoner 542
1734 schoenebeck 940
1735 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 31]
1736 schoenebeck 974
1737 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
1738 schoenebeck 940
1739    
1740 schoenebeck 974 6.3.4. Getting information about specific MIDI input driver parameter
1741 schoenebeck 940
1742 schoenebeck 974 Use the following command to get detailed information about a
1743     specific parameter of a specific MIDI input driver:
1744 schoenebeck 940
1745 senoner 542 GET MIDI_INPUT_DRIVER_PARAMETER INFO <midit> <param> [<deplist>]
1746    
1747 schoenebeck 561 Where <midit> is the name of the MIDI input driver as returned by the
1748 schoenebeck 575 "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2) command, <param>
1749 schoenebeck 561 a specific parameter name for which information should be obtained
1750 schoenebeck 575 (as returned by the "GET MIDI_INPUT_DRIVER INFO" (Section 6.3.3)
1751 schoenebeck 561 command) and <deplist> is an optional list of parameters on which the
1752     sought parameter <param> depends on, <deplist> is a key-value pair
1753     list in form of "key1=val1 key2=val2 ...", where character string
1754     values are encapsulated into apostrophes ('). Arguments given with
1755     <deplist> which are not dependency parameters of <param> will be
1756     ignored, means the front-end application can simply put all
1757     parameters in <deplist> with the values selected by the user.
1758 senoner 542
1759     Possible Answers:
1760    
1761     LinuxSampler will answer by sending a <CRLF> separated list. Each
1762     answer line begins with the information category name followed by a
1763     colon and then a space character <SP> and finally the info character
1764     string to that info category. There is information which is always
1765     returned, independent of the given driver parameter and there is
1766     optional information which is only shown dependent to given driver
1767     parameter. At the moment the following information categories are
1768     defined:
1769    
1770     TYPE -
1771 schoenebeck 708
1772 senoner 542 either "BOOL" for boolean value(s) or "INT" for integer
1773     value(s) or "FLOAT" for dotted number(s) or "STRING" for
1774     character string(s) (always returned, no matter which driver
1775     parameter)
1776 schoenebeck 708
1777 senoner 542 DESCRIPTION -
1778 schoenebeck 708
1779 senoner 542 arbitrary text describing the purpose of the parameter (always
1780     returned, no matter which driver parameter)
1781 schoenebeck 708
1782 senoner 542 MANDATORY -
1783 schoenebeck 708
1784 senoner 542 either true or false, defines if this parameter must be given
1785     when the device is to be created with the 'CREATE
1786 schoenebeck 575 MIDI_INPUT_DEVICE' (Section 6.3.5) command (always returned, no
1787 senoner 542 matter which driver parameter)
1788 schoenebeck 708
1789    
1790 schoenebeck 940
1791 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 32]
1792 schoenebeck 974
1793 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
1794 schoenebeck 940
1795    
1796 schoenebeck 974 FIX -
1797 schoenebeck 940
1798 schoenebeck 974 either true or false, if false then this parameter can be
1799     changed at any time, once the device is created by the 'CREATE
1800 schoenebeck 575 MIDI_INPUT_DEVICE' (Section 6.3.5) command (always returned, no
1801 senoner 542 matter which driver parameter)
1802 schoenebeck 708
1803 senoner 542 MULTIPLICITY -
1804 schoenebeck 708
1805 senoner 542 either true or false, defines if this parameter allows only one
1806     value or a list of values, where true means multiple values and
1807     false only a single value allowed (always returned, no matter
1808     which driver parameter)
1809 schoenebeck 708
1810 senoner 542 DEPENDS -
1811 schoenebeck 708
1812 schoenebeck 561 comma separated list of parameters this parameter depends on,
1813 senoner 542 means the values for fields 'DEFAULT', 'RANGE_MIN', 'RANGE_MAX'
1814     and 'POSSIBILITIES' might depend on these listed parameters,
1815     for example assuming that an audio driver (like the ALSA
1816     driver) offers parameters 'card' and 'samplerate' then
1817     parameter 'samplerate' would depend on 'card' because the
1818     possible values for 'samplerate' depends on the sound card
1819     which can be chosen by the 'card' parameter (optionally
1820     returned, dependent to driver parameter)
1821 schoenebeck 708
1822 senoner 542 DEFAULT -
1823 schoenebeck 708
1824 senoner 542 reflects the default value for this parameter which is used
1825     when the device is created and not explicitly given with the
1826 schoenebeck 575 'CREATE MIDI_INPUT_DEVICE' (Section 6.3.5) command, in case of
1827 senoner 542 MULTIPLCITY=true, this is a comma separated list, that's why
1828     character strings are encapsulated into apostrophes (')
1829     (optionally returned, dependent to driver parameter)
1830 schoenebeck 575
1831 schoenebeck 708 RANGE_MIN -
1832    
1833     defines lower limit of the allowed value range for this
1834     parameter, can be an integer value as well as a dotted number,
1835 senoner 542 this parameter is often used in conjunction with RANGE_MAX, but
1836     may also appear without (optionally returned, dependent to
1837     driver parameter)
1838 schoenebeck 708
1839 senoner 542 RANGE_MAX -
1840 schoenebeck 708
1841 senoner 542 defines upper limit of the allowed value range for this
1842     parameter, can be an integer value as well as a dotted number,
1843     this parameter is often used in conjunction with RANGE_MIN, but
1844 schoenebeck 708
1845 schoenebeck 940
1846    
1847 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 33]
1848 schoenebeck 974
1849 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
1850 schoenebeck 940
1851    
1852 schoenebeck 974 may also appear without (optionally returned, dependent to
1853     driver parameter)
1854 schoenebeck 940
1855 senoner 542 POSSIBILITIES -
1856 schoenebeck 708
1857 senoner 542 comma separated list of possible values for this parameter,
1858     character strings are encapsulated into apostrophes (optionally
1859     returned, dependent to driver parameter)
1860    
1861     The mentioned fields above don't have to be in particular order.
1862    
1863     Example:
1864    
1865     C: "GET MIDI_INPUT_DRIVER_PARAMETER INFO ALSA ACTIVE"
1866 schoenebeck 708
1867 senoner 542 S: "DESCRIPTION: Whether device is enabled"
1868 schoenebeck 708
1869 senoner 542 "TYPE: BOOL"
1870 schoenebeck 708
1871 senoner 542 "MANDATORY: false"
1872 schoenebeck 708
1873 senoner 542 "FIX: false"
1874 schoenebeck 708
1875 senoner 542 "MULTIPLICITY: false"
1876 schoenebeck 708
1877 senoner 542 "DEFAULT: true"
1878 schoenebeck 708
1879 senoner 542 "."
1880    
1881 schoenebeck 940 6.3.5. Creating a MIDI input device
1882 schoenebeck 708
1883 schoenebeck 940 Use the following command to create a new MIDI input device for the
1884 senoner 542 desired MIDI input system:
1885    
1886     CREATE MIDI_INPUT_DEVICE <midi-input-driver> [<param-list>]
1887    
1888     Where <midi-input-driver> should be replaced by the desired MIDI
1889 schoenebeck 575 input system as returned by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
1890     (Section 6.3.2) command and <param-list> by an optional list of
1891     driver specific parameters in form of "key1=val1 key2=val2 ...",
1892     where character string values should be encapsulated into apostrophes
1893     ('). Note that there might be drivers which require parameter(s) to
1894     be given with this command. Use the previously described commands in
1895     this chapter to get that information.
1896 senoner 542
1897     Possible Answers:
1898    
1899 schoenebeck 708
1900 schoenebeck 575
1901 schoenebeck 940
1902    
1903 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 34]
1904 schoenebeck 940
1905 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
1906 schoenebeck 940
1907    
1908 schoenebeck 974 "OK[<device-id>]" -
1909    
1910     in case the device was successfully created, where <device-id>
1911     is the numerical ID of the new device
1912    
1913 schoenebeck 708 "WRN[<device-id>]:<warning-code>:<warning-message>" -
1914 schoenebeck 575
1915 senoner 542 in case the driver was loaded successfully, where <device-id>
1916     is the numerical ID of the new device, but there are noteworthy
1917     issue(s) related, providing an appropriate warning code and
1918     warning message
1919 schoenebeck 708
1920 senoner 542 "ERR:<error-code>:<error-message>" -
1921 schoenebeck 708
1922 senoner 542 in case it failed, providing an appropriate error code and
1923     error message
1924    
1925     Example:
1926    
1927     C: "CREATE MIDI_INPUT_DEVICE ALSA"
1928 schoenebeck 708
1929 senoner 542 S: "OK[0]"
1930    
1931 schoenebeck 940 6.3.6. Destroying a MIDI input device
1932 schoenebeck 708
1933 senoner 542 Use the following command to destroy a created MIDI input device:
1934    
1935     DESTROY MIDI_INPUT_DEVICE <device-id>
1936    
1937 schoenebeck 575 Where <device-id> should be replaced by the device's numerical ID as
1938     returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
1939     MIDI_INPUT_DEVICES" (Section 6.3.8) command.
1940 senoner 542
1941     Possible Answers:
1942    
1943     "OK" -
1944 schoenebeck 708
1945 senoner 542 in case the device was successfully destroyed
1946 schoenebeck 708
1947 senoner 542 "WRN:<warning-code>:<warning-message>" -
1948 schoenebeck 708
1949 senoner 542 in case the device was destroyed, but there are noteworthy
1950     issue(s) related, providing an appropriate warning code and
1951     warning message
1952 schoenebeck 708
1953 senoner 542 "ERR:<error-code>:<error-message>" -
1954 schoenebeck 708
1955 senoner 542
1956    
1957 schoenebeck 940
1958    
1959 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 35]
1960 schoenebeck 974
1961 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
1962 schoenebeck 940
1963    
1964 schoenebeck 974 in case it failed, providing an appropriate error code and
1965     error message
1966 schoenebeck 940
1967 schoenebeck 974 Example:
1968 schoenebeck 940
1969 senoner 542 C: "DESTROY MIDI_INPUT_DEVICE 0"
1970 schoenebeck 708
1971 senoner 542 S: "OK"
1972    
1973 schoenebeck 940 6.3.7. Getting all created MIDI input device count
1974 schoenebeck 708
1975 senoner 542 Use the following command to count all created MIDI input devices:
1976    
1977     GET MIDI_INPUT_DEVICES
1978    
1979     Possible Answers:
1980    
1981     LinuxSampler will answer by sending the current number of all MIDI
1982     input devices.
1983    
1984     Example:
1985    
1986     C: "GET MIDI_INPUT_DEVICES"
1987 schoenebeck 708
1988 senoner 542 S: "3"
1989    
1990 schoenebeck 940 6.3.8. Getting all created MIDI input device list
1991 schoenebeck 708
1992 senoner 542 Use the following command to list all created MIDI input devices:
1993    
1994     LIST MIDI_INPUT_DEVICES
1995    
1996     Possible Answers:
1997    
1998     LinuxSampler will answer by sending a comma separated list with
1999     the numerical Ids of all created MIDI input devices.
2000    
2001     Examples:
2002    
2003     C: "LIST MIDI_INPUT_DEVICES"
2004 schoenebeck 708
2005 senoner 542 S: "0,1,2"
2006    
2007     C: "LIST MIDI_INPUT_DEVICES"
2008 schoenebeck 708
2009 senoner 542 S: "1,3"
2010    
2011 schoenebeck 708
2012 senoner 542
2013 schoenebeck 940
2014    
2015 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 36]
2016 schoenebeck 974
2017 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
2018 schoenebeck 940
2019    
2020 schoenebeck 974 6.3.9. Getting current settings of a MIDI input device
2021 schoenebeck 940
2022 schoenebeck 974 Use the following command to get current settings of a specific,
2023     created MIDI input device:
2024 schoenebeck 940
2025 senoner 542 GET MIDI_INPUT_DEVICE INFO <device-id>
2026    
2027 schoenebeck 575 Where <device-id> is the numerical ID of the MIDI input device as
2028     returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
2029     MIDI_INPUT_DEVICES" (Section 6.3.8) command.
2030 senoner 542
2031     Possible Answers:
2032    
2033     LinuxSampler will answer by sending a <CRLF> separated list. Each
2034     answer line begins with the information category name followed by
2035     a colon and then a space character <SP> and finally the info
2036     character string to that info category. As some parameters might
2037     allow multiple values, character strings are encapsulated into
2038     apostrophes ('). At the moment the following information
2039     categories are defined (independent of driver):
2040    
2041 schoenebeck 575
2042    
2043 schoenebeck 708 DRIVER -
2044 schoenebeck 575
2045 schoenebeck 708 identifier of the used MIDI input driver, as e.g. returned
2046 schoenebeck 575 by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2)
2047 senoner 542 command
2048 schoenebeck 708
2049 senoner 542 ACTIVE -
2050 schoenebeck 708
2051 senoner 542 either true or false, if false then the MIDI device is
2052     inactive and doesn't listen to any incoming MIDI events and
2053     thus doesn't forward them to connected sampler channels
2054    
2055     The mentioned fields above don't have to be in particular order. The
2056     fields above are only those fields which are returned by all MIDI
2057     input devices. Every MIDI input driver might have its own,
2058     additional driver specific parameters (see "GET MIDI_INPUT_DRIVER
2059 schoenebeck 575 INFO" (Section 6.3.3) command) which are also returned by this
2060 senoner 542 command.
2061    
2062     Example:
2063    
2064     C: "GET MIDI_INPUT_DEVICE INFO 0"
2065 schoenebeck 708
2066 senoner 542 S: "DRIVER: ALSA"
2067 schoenebeck 708
2068    
2069 senoner 542
2070 schoenebeck 708
2071 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 37]
2072 schoenebeck 974
2073 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
2074 senoner 542
2075 schoenebeck 940
2076 schoenebeck 974 "ACTIVE: true"
2077 schoenebeck 940
2078 schoenebeck 974 "."
2079 schoenebeck 940
2080     6.3.10. Changing settings of MIDI input devices
2081    
2082 senoner 542 Use the following command to alter a specific setting of a created
2083     MIDI input device:
2084    
2085     SET MIDI_INPUT_DEVICE_PARAMETER <device-id> <key>=<value>
2086    
2087     Where <device-id> should be replaced by the numerical ID of the MIDI
2088 schoenebeck 708 input device as returned by the "CREATE MIDI_INPUT_DEVICE"
2089     (Section 6.3.5) or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command,
2090     <key> by the name of the parameter to change and <value> by the new
2091     value for this parameter.
2092 senoner 542
2093     Possible Answers:
2094    
2095     "OK" -
2096 schoenebeck 708
2097 senoner 542 in case setting was successfully changed
2098 schoenebeck 708
2099 senoner 542 "WRN:<warning-code>:<warning-message>" -
2100 schoenebeck 708
2101 senoner 542 in case setting was changed successfully, but there are
2102     noteworthy issue(s) related, providing an appropriate warning
2103     code and warning message
2104 schoenebeck 708
2105 senoner 542 "ERR:<error-code>:<error-message>" -
2106 schoenebeck 708
2107 senoner 542 in case it failed, providing an appropriate error code and
2108     error message
2109    
2110     Example:
2111    
2112     C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"
2113 schoenebeck 708
2114 senoner 542 S: "OK"
2115    
2116 schoenebeck 940 6.3.11. Getting information about a MIDI port
2117 schoenebeck 708
2118 senoner 542 Use the following command to get information about a MIDI port:
2119    
2120     GET MIDI_INPUT_PORT INFO <device-id> <midi-port>
2121    
2122 schoenebeck 575 Where <device-id> is the numerical ID of the MIDI input device as
2123     returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
2124 senoner 542
2125    
2126 schoenebeck 940
2127 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 38]
2128 schoenebeck 940
2129 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
2130 schoenebeck 940
2131    
2132 schoenebeck 974 MIDI_INPUT_DEVICES" (Section 6.3.8) command and <midi-port> the MIDI
2133     input port number.
2134    
2135     Possible Answers:
2136    
2137 senoner 542 LinuxSampler will answer by sending a <CRLF> separated list. Each
2138     answer line begins with the information category name followed by
2139     a colon and then a space character <SP> and finally the info
2140     character string to that info category. At the moment the
2141     following information categories are defined:
2142 schoenebeck 708
2143 senoner 542 NAME -
2144 schoenebeck 708
2145 senoner 542 arbitrary character string naming the port
2146    
2147     The field above is only the one which is returned by all MIDI ports
2148     regardless of the MIDI driver and port. Every MIDI port might have
2149     its own, additional driver and port specific parameters.
2150    
2151     Example:
2152    
2153     C: "GET MIDI_INPUT_PORT INFO 0 0"
2154 schoenebeck 708
2155 senoner 542 S: "NAME: 'Masterkeyboard'"
2156 schoenebeck 708
2157 senoner 542 "ALSA_SEQ_BINDINGS: '64:0'"
2158 schoenebeck 708
2159 senoner 542 "."
2160    
2161 schoenebeck 940 6.3.12. Getting information about specific MIDI port parameter
2162 schoenebeck 708
2163 senoner 542 Use the following command to get detailed information about specific
2164     MIDI port parameter:
2165    
2166     GET MIDI_INPUT_PORT_PARAMETER INFO <dev-id> <port> <param>
2167    
2168     Where <dev-id> is the numerical ID of the MIDI input device as
2169 schoenebeck 575 returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
2170     MIDI_INPUT_DEVICES" (Section 6.3.8) command, <port> the MIDI port
2171     number and <param> a specific port parameter name for which
2172     information should be obtained (as returned by the "GET
2173     MIDI_INPUT_PORT INFO" (Section 6.3.11) command).
2174    
2175 senoner 542 Possible Answers:
2176    
2177     LinuxSampler will answer by sending a <CRLF> separated list. Each
2178     answer line begins with the information category name followed by
2179     a colon and then a space character <SP> and finally the info
2180 schoenebeck 974
2181    
2182    
2183 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 39]
2184 schoenebeck 974
2185 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
2186 schoenebeck 974
2187    
2188 senoner 542 character string to that info category. There is information
2189     which is always returned, independently of the given channel
2190     parameter and there is optional information which are only shown
2191     dependently to the given MIDI port. At the moment the following
2192     information categories are defined:
2193 schoenebeck 708
2194 senoner 542 TYPE -
2195 schoenebeck 708
2196 senoner 542 either "BOOL" for boolean value(s) or "INT" for integer
2197     value(s) or "FLOAT" for dotted number(s) or "STRING" for
2198     character string(s) (always returned)
2199 schoenebeck 708
2200 senoner 542 DESCRIPTION -
2201 schoenebeck 708
2202 senoner 542 arbitrary text describing the purpose of the parameter (always
2203     returned)
2204 schoenebeck 708
2205 senoner 542 FIX -
2206 schoenebeck 708
2207 senoner 542 either true or false, if true then this parameter is read only,
2208     thus cannot be altered (always returned)
2209 schoenebeck 708
2210 senoner 542 MULTIPLICITY -
2211 schoenebeck 708
2212 senoner 542 either true or false, defines if this parameter allows only one
2213     value or a list of values, where true means multiple values and
2214     false only a single value allowed (always returned)
2215 schoenebeck 708
2216 senoner 542 RANGE_MIN -
2217 schoenebeck 708
2218 senoner 542 defines lower limit of the allowed value range for this
2219     parameter, can be an integer value as well as a dotted number,
2220     this parameter is usually used in conjunction with 'RANGE_MAX'
2221     but may also appear without (optionally returned, dependent to
2222     driver and port parameter)
2223 schoenebeck 708
2224 senoner 542 RANGE_MAX -
2225 schoenebeck 708
2226 senoner 542 defines upper limit of the allowed value range for this
2227     parameter, can be an integer value as well as a dotted number,
2228     this parameter is usually used in conjunction with 'RANGE_MIN'
2229     but may also appear without (optionally returned, dependent to
2230     driver and port parameter)
2231 schoenebeck 708
2232 senoner 542 POSSIBILITIES -
2233 schoenebeck 708
2234 senoner 542 comma separated list of possible values for this parameter,
2235     character strings are encapsulated into apostrophes (optionally
2236    
2237    
2238    
2239 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 40]
2240 schoenebeck 974
2241 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
2242 schoenebeck 940
2243    
2244 schoenebeck 974 returned, dependent to device and port parameter)
2245 schoenebeck 940
2246 schoenebeck 974 The mentioned fields above don't have to be in particular order.
2247 schoenebeck 940
2248 schoenebeck 974 Example:
2249 schoenebeck 940
2250 schoenebeck 708 C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"
2251 schoenebeck 575
2252 schoenebeck 708 S: "DESCRIPTION: bindings to other ALSA sequencer clients"
2253 schoenebeck 575
2254 schoenebeck 708 "TYPE: STRING"
2255 schoenebeck 575
2256 schoenebeck 708 "FIX: false"
2257 schoenebeck 575
2258 schoenebeck 708 "MULTIPLICITY: true"
2259 schoenebeck 575
2260 senoner 542 "POSSIBILITIES: '64:0','68:0','68:1'"
2261 schoenebeck 708
2262 senoner 542 "."
2263    
2264 schoenebeck 940 6.3.13. Changing settings of MIDI input ports
2265 schoenebeck 708
2266 senoner 542 Use the following command to alter a specific setting of a MIDI input
2267     port:
2268    
2269     SET MIDI_INPUT_PORT_PARAMETER <device-id> <port> <key>=<value>
2270    
2271     Where <device-id> should be replaced by the numerical ID of the MIDI
2272 schoenebeck 575 device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5)
2273     or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command, <port> by the
2274     MIDI port number, <key> by the name of the parameter to change and
2275     <value> by the new value for this parameter.
2276 senoner 542
2277     Possible Answers:
2278    
2279     "OK" -
2280 schoenebeck 708
2281 senoner 542 in case setting was successfully changed
2282 schoenebeck 708
2283 senoner 542 "WRN:<warning-code>:<warning-message>" -
2284 schoenebeck 708
2285 senoner 542 in case setting was changed successfully, but there are
2286     noteworthy issue(s) related, providing an appropriate warning
2287     code and warning message
2288 schoenebeck 708
2289 senoner 542 "ERR:<error-code>:<error-message>" -
2290 schoenebeck 708
2291 senoner 542
2292    
2293    
2294    
2295 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 41]
2296 schoenebeck 974
2297 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
2298 schoenebeck 708
2299 senoner 542
2300 schoenebeck 974 in case it failed, providing an appropriate error code and
2301     error message
2302 schoenebeck 940
2303 schoenebeck 974 Example:
2304 schoenebeck 940
2305    
2306    
2307     6.4. Configuring sampler channels
2308    
2309 senoner 542 The following commands describe how to add and remove sampler
2310 schoenebeck 575 channels, associate a sampler channel with a sampler engine, load
2311     instruments and connect sampler channels to MIDI and audio devices.
2312 senoner 542
2313 schoenebeck 940 6.4.1. Loading an instrument
2314 senoner 542
2315     An instrument file can be loaded and assigned to a sampler channel by
2316     one of the following commands:
2317    
2318 schoenebeck 708 LOAD INSTRUMENT [NON_MODAL] '<filename>' <instr-index> <sampler-
2319     channel>
2320 schoenebeck 575
2321 senoner 542 Where <filename> is the name of the instrument file on the
2322     LinuxSampler instance's host system, <instr-index> the index of the
2323     instrument in the instrument file and <sampler-channel> is the number
2324     of the sampler channel the instrument should be assigned to. Each
2325     sampler channel can only have one instrument.
2326    
2327     The difference between regular and NON_MODAL versions of the command
2328     is that the regular command returns OK only after the instrument has
2329     been fully loaded and the channel is ready to be used while NON_MODAL
2330     version returns immediately and a background process is launched to
2331 schoenebeck 708 load the instrument on the channel. The GET CHANNEL INFO
2332     (Section 6.4.10) command can be used to obtain loading progress from
2333 senoner 542 INSTRUMENT_STATUS field. LOAD command will perform sanity checks
2334     such as making sure that the file could be read and it is of a proper
2335     format and SHOULD return ERR and SHOULD not launch the background
2336     process should any errors be detected at that point.
2337    
2338     Possible Answers:
2339    
2340     "OK" -
2341 schoenebeck 708
2342 senoner 542 in case the instrument was successfully loaded
2343 schoenebeck 708
2344 senoner 542 "WRN:<warning-code>:<warning-message>" -
2345 schoenebeck 708
2346 senoner 542 in case the instrument was loaded successfully, but there are
2347     noteworthy issue(s) related (e.g. Engine doesn't support one
2348 schoenebeck 708
2349 schoenebeck 940
2350    
2351 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 42]
2352 schoenebeck 974
2353 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
2354 schoenebeck 940
2355    
2356 schoenebeck 974 or more patch parameters provided by the loaded instrument
2357     file), providing an appropriate warning code and warning
2358     message
2359 schoenebeck 940
2360 senoner 542 "ERR:<error-code>:<error-message>" -
2361 schoenebeck 708
2362 senoner 542 in case it failed, providing an appropriate error code and
2363     error message
2364    
2365     Example:
2366    
2367    
2368    
2369 schoenebeck 940 6.4.2. Loading a sampler engine
2370 schoenebeck 708
2371 schoenebeck 575 A sampler engine type can be associated to a specific sampler channel
2372     by the following command:
2373 senoner 542
2374     LOAD ENGINE <engine-name> <sampler-channel>
2375    
2376     Where <engine-name> is an engine name as obtained by the "LIST
2377 schoenebeck 575 AVAILABLE_ENGINES" (Section 6.4.8) command and <sampler-channel> the
2378     sampler channel as returned by the "ADD CHANNEL" (Section 6.4.5) or
2379     "LIST CHANNELS" (Section 6.4.4) command where the engine type should
2380     be assigned to. This command should be issued after adding a new
2381     sampler channel and before any other control commands on the new
2382     sampler channel. It can also be used to change the engine type of a
2383     sampler channel. This command has (currently) no way to define or
2384     force if a new engine instance should be created and assigned to the
2385     given sampler channel or if an already existing instance of that
2386     engine type, shared with other sampler channels, should be used.
2387    
2388 senoner 542 Possible Answers:
2389    
2390     "OK" -
2391 schoenebeck 708
2392 senoner 542 in case the engine was successfully deployed
2393 schoenebeck 708
2394 senoner 542 "WRN:<warning-code>:<warning-message>" -
2395 schoenebeck 708
2396 senoner 542 in case the engine was deployed successfully, but there are
2397     noteworthy issue(s) related, providing an appropriate warning
2398     code and warning message
2399 schoenebeck 708
2400 senoner 542 "ERR:<error-code>:<error-message>" -
2401 schoenebeck 708
2402 senoner 542 in case it failed, providing an appropriate error code and
2403     error message
2404    
2405    
2406    
2407 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 43]
2408 schoenebeck 974
2409 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
2410 senoner 542
2411 schoenebeck 708
2412 schoenebeck 974 Example:
2413 senoner 542
2414 schoenebeck 940
2415    
2416     6.4.3. Getting all created sampler channel count
2417    
2418 senoner 542 The number of sampler channels can change on runtime. To get the
2419     current amount of sampler channels, the front-end can send the
2420     following command:
2421    
2422     GET CHANNELS
2423    
2424     Possible Answers:
2425    
2426     LinuxSampler will answer by returning the current number of
2427     sampler channels.
2428    
2429     Example:
2430    
2431     C: "GET CHANNELS"
2432 schoenebeck 708
2433 senoner 542 S: "12"
2434    
2435 schoenebeck 940 6.4.4. Getting all created sampler channel list
2436 schoenebeck 708
2437 senoner 542 The number of sampler channels can change on runtime. To get the
2438     current list of sampler channels, the front-end can send the
2439 schoenebeck 708 following command:
2440    
2441 senoner 542 LIST CHANNELS
2442    
2443     Possible Answers:
2444    
2445     LinuxSampler will answer by returning a comma separated list with
2446     all sampler channels numerical IDs.
2447    
2448     Example:
2449    
2450     C: "LIST CHANNELS"
2451 schoenebeck 708
2452 senoner 542 S: "0,1,2,3,4,5,6,9,10,11,15,20"
2453    
2454 schoenebeck 940 6.4.5. Adding a new sampler channel
2455 schoenebeck 708
2456 senoner 542 A new sampler channel can be added to the end of the sampler channel
2457     list by sending the following command:
2458    
2459    
2460 schoenebeck 940
2461    
2462    
2463 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 44]
2464 schoenebeck 940
2465 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
2466 schoenebeck 940
2467    
2468 schoenebeck 974 ADD CHANNEL
2469    
2470     This will increment the sampler channel count by one and the new
2471 senoner 542 sampler channel will be appended to the end of the sampler channel
2472     list. The front-end should send the respective, related commands
2473 schoenebeck 708 right after to e.g. load an engine, load an instrument and setting
2474 senoner 542 input, output method and eventually other commands to initialize the
2475     new channel. The front-end should use the sampler channel returned
2476     by the answer of this command to perform the previously recommended
2477 schoenebeck 708 commands, to avoid race conditions e.g. with other front-ends that
2478 senoner 542 might also have sent an "ADD CHANNEL" command.
2479    
2480     Possible Answers:
2481    
2482     "OK[<sampler-channel>]" -
2483 schoenebeck 708
2484     in case a new sampler channel could be added, where <sampler-
2485     channel> reflects the channel number of the new created sampler
2486     channel which should be used to set up the sampler channel by
2487     sending subsequent initialization commands
2488    
2489 senoner 542 "WRN:<warning-code>:<warning-message>" -
2490 schoenebeck 708
2491 senoner 542 in case a new channel was added successfully, but there are
2492     noteworthy issue(s) related, providing an appropriate warning
2493     code and warning message
2494 schoenebeck 708
2495 senoner 542 "ERR:<error-code>:<error-message>" -
2496 schoenebeck 708
2497 senoner 542 in case it failed, providing an appropriate error code and
2498     error message
2499    
2500     Example:
2501    
2502    
2503    
2504 schoenebeck 940 6.4.6. Removing a sampler channel
2505 senoner 542
2506     A sampler channel can be removed by sending the following command:
2507    
2508     REMOVE CHANNEL <sampler-channel>
2509    
2510 schoenebeck 561 Where <sampler-channel> should be replaced by the number of the
2511 schoenebeck 575 sampler channel as given by the "ADD CHANNEL" (Section 6.4.5) or
2512     "LIST CHANNELS" (Section 6.4.4) command. The channel numbers of all
2513 schoenebeck 561 subsequent sampler channels remain the same.
2514 senoner 542
2515     Possible Answers:
2516    
2517 schoenebeck 940
2518    
2519 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 45]
2520 schoenebeck 940
2521 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
2522 schoenebeck 940
2523    
2524 senoner 542 "OK" -
2525 schoenebeck 708
2526 senoner 542 in case the given sampler channel could be removed
2527 schoenebeck 708
2528 senoner 542 "WRN:<warning-code>:<warning-message>" -
2529 schoenebeck 708
2530 senoner 542 in case the given channel was removed, but there are noteworthy
2531     issue(s) related, providing an appropriate warning code and
2532     warning message
2533 schoenebeck 708
2534 senoner 542 "ERR:<error-code>:<error-message>" -
2535 schoenebeck 708
2536 senoner 542 in case it failed, providing an appropriate error code and
2537     error message
2538    
2539     Example:
2540    
2541    
2542    
2543 schoenebeck 940 6.4.7. Getting amount of available engines
2544 schoenebeck 708
2545 senoner 542 The front-end can ask for the number of available engines by sending
2546     the following command:
2547    
2548     GET AVAILABLE_ENGINES
2549    
2550     Possible Answers:
2551    
2552     LinuxSampler will answer by sending the number of available
2553     engines.
2554    
2555     Example:
2556    
2557     C: "GET AVAILABLE_ENGINES"
2558 schoenebeck 708
2559 senoner 542 S: "4"
2560    
2561 schoenebeck 940 6.4.8. Getting all available engines
2562 schoenebeck 708
2563 senoner 542 The front-end can ask for a list of all available engines by sending
2564     the following command:
2565    
2566     LIST AVAILABLE_ENGINES
2567    
2568     Possible Answers:
2569    
2570 schoenebeck 940
2571    
2572    
2573    
2574    
2575 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 46]
2576 schoenebeck 940
2577 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
2578 schoenebeck 940
2579    
2580 schoenebeck 561 LinuxSampler will answer by sending a comma separated list of the
2581     engines' names encapsulated into apostrophes ('). Engine names
2582     can consist of lower and upper cases, digits and underlines ("_"
2583     character).
2584 senoner 542
2585     Example:
2586    
2587     C: "LIST AVAILABLE_ENGINES"
2588 schoenebeck 708
2589 schoenebeck 561 S: "'GigEngine','AkaiEngine','DLSEngine','JoesCustomEngine'"
2590 senoner 542
2591 schoenebeck 940 6.4.9. Getting information about an engine
2592 schoenebeck 708
2593 senoner 542 The front-end can ask for information about a specific engine by
2594     sending the following command:
2595    
2596     GET ENGINE INFO <engine-name>
2597    
2598     Where <engine-name> is an engine name as obtained by the "LIST
2599 schoenebeck 575 AVAILABLE_ENGINES" (Section 6.4.8) command.
2600 senoner 542
2601 schoenebeck 561 Possible Answers:
2602    
2603 senoner 542 LinuxSampler will answer by sending a <CRLF> separated list. Each
2604     answer line begins with the information category name followed by
2605     a colon and then a space character <SP> and finally the info
2606     character string to that info category. At the moment the
2607     following categories are defined:
2608    
2609 schoenebeck 708
2610    
2611 senoner 542 DESCRIPTION -
2612 schoenebeck 708
2613 senoner 542 arbitrary description text about the engine
2614 schoenebeck 708
2615 senoner 542 VERSION -
2616 schoenebeck 708
2617 senoner 542 arbitrary character string regarding the engine's version
2618    
2619     The mentioned fields above don't have to be in particular order.
2620    
2621     Example:
2622    
2623     C: "GET ENGINE INFO JoesCustomEngine"
2624 schoenebeck 708
2625 senoner 542 S: "DESCRIPTION: this is Joe's custom sampler engine"
2626 schoenebeck 708
2627 schoenebeck 940
2628    
2629    
2630    
2631 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 47]
2632 schoenebeck 940
2633 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
2634 schoenebeck 940
2635    
2636 senoner 542 "VERSION: testing-1.0"
2637 schoenebeck 708
2638 senoner 542 "."
2639    
2640 schoenebeck 940 6.4.10. Getting sampler channel information
2641 senoner 542
2642     The front-end can ask for the current settings of a sampler channel
2643     by sending the following command:
2644    
2645     GET CHANNEL INFO <sampler-channel>
2646    
2647     Where <sampler-channel> is the sampler channel number the front-end
2648 schoenebeck 575 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2649     "LIST CHANNELS" (Section 6.4.4) command.
2650 senoner 542
2651     Possible Answers:
2652    
2653     LinuxSampler will answer by sending a <CRLF> separated list. Each
2654     answer line begins with the settings category name followed by a
2655     colon and then a space character <SP> and finally the info
2656     character string to that setting category. At the moment the
2657     following categories are defined:
2658    
2659 schoenebeck 708
2660    
2661 senoner 542 ENGINE_NAME -
2662 schoenebeck 708
2663 schoenebeck 575 name of the engine that is associated with the sampler
2664     channel, "NONE" if there's no engine associated yet for this
2665     sampler channel
2666 schoenebeck 708
2667 senoner 542 AUDIO_OUTPUT_DEVICE -
2668 schoenebeck 708
2669 senoner 542 numerical ID of the audio output device which is currently
2670     connected to this sampler channel to output the audio
2671     signal, "NONE" if there's no device connected to this
2672 schoenebeck 561 sampler channel
2673 schoenebeck 708
2674 senoner 542 AUDIO_OUTPUT_CHANNELS -
2675 schoenebeck 708
2676 senoner 542 number of output channels the sampler channel offers
2677     (dependent to used sampler engine and loaded instrument)
2678 schoenebeck 708
2679 senoner 542 AUDIO_OUTPUT_ROUTING -
2680 schoenebeck 708
2681 senoner 542 comma separated list which reflects to which audio channel
2682     of the selected audio output device each sampler output
2683 schoenebeck 708 channel is routed to, e.g. "0,3" would mean the engine's
2684 schoenebeck 940
2685    
2686    
2687 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 48]
2688 schoenebeck 940
2689 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
2690 schoenebeck 940
2691    
2692 senoner 542 output channel 0 is routed to channel 0 of the audio output
2693     device and the engine's output channel 1 is routed to the
2694     channel 3 of the audio output device
2695 schoenebeck 708
2696 senoner 542 INSTRUMENT_FILE -
2697 schoenebeck 708
2698 senoner 542 the file name of the loaded instrument, "NONE" if there's no
2699     instrument yet loaded for this sampler channel
2700 schoenebeck 708
2701 senoner 542 INSTRUMENT_NR -
2702 schoenebeck 708
2703 senoner 542 the instrument index number of the loaded instrument
2704 schoenebeck 708
2705 senoner 542 INSTRUMENT_NAME -
2706 schoenebeck 708
2707 senoner 542 the instrument name of the loaded instrument
2708 schoenebeck 708
2709 senoner 542 INSTRUMENT_STATUS -
2710 schoenebeck 708
2711 senoner 542 integer values 0 to 100 indicating loading progress
2712     percentage for the instrument. Negative value indicates a
2713 schoenebeck 708 loading exception. Value of 100 indicates that the
2714     instrument is fully loaded.
2715 schoenebeck 575
2716 senoner 542 MIDI_INPUT_DEVICE -
2717 schoenebeck 708
2718 senoner 542 numerical ID of the MIDI input device which is currently
2719     connected to this sampler channel to deliver MIDI input
2720     commands, "NONE" if there's no device connected to this
2721     sampler channel
2722 schoenebeck 708
2723 senoner 542 MIDI_INPUT_PORT -
2724 schoenebeck 708
2725 senoner 542 port number of the MIDI input device
2726 schoenebeck 708
2727 senoner 542 MIDI_INPUT_CHANNEL -
2728 schoenebeck 708
2729 senoner 542 the MIDI input channel number this sampler channel should
2730     listen to or "ALL" to listen on all MIDI channels
2731 schoenebeck 708
2732 senoner 542 VOLUME -
2733 schoenebeck 708
2734 senoner 542 optionally dotted number for the channel volume factor
2735     (where a value < 1.0 means attenuation and a value > 1.0
2736     means amplification)
2737    
2738 schoenebeck 940
2739    
2740    
2741    
2742    
2743 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 49]
2744 schoenebeck 940
2745 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
2746 schoenebeck 940
2747    
2748 schoenebeck 708 MUTE -
2749    
2750     Determines whether the channel is muted, "true" if the
2751     channel is muted, "false" if the channel is not muted, and
2752     "MUTED_BY_SOLO" if the channel is muted because of the
2753     presence of a solo channel and will be unmuted when there
2754     are no solo channels left
2755    
2756     SOLO -
2757    
2758     Determines whether this is a solo channel, "true" if the
2759     channel is a solo channel; "false" otherwise
2760    
2761 schoenebeck 974 MIDI_INSTRUMENT_MAP -
2762    
2763     Determines to which MIDI instrument map this sampler channel
2764     is assigned to. Read chapter "SET CHANNEL
2765     MIDI_INSTRUMENT_MAP" (Section 6.4.24) for a list of possible
2766     values.
2767    
2768 senoner 542 The mentioned fields above don't have to be in particular order.
2769    
2770     Example:
2771    
2772     C: "GET CHANNEL INFO 34"
2773 schoenebeck 708
2774 senoner 542 S: "ENGINE_NAME: GigEngine"
2775 schoenebeck 708
2776 senoner 542 "VOLUME: 1.0"
2777 schoenebeck 708
2778 senoner 542 "AUDIO_OUTPUT_DEVICE: 0"
2779 schoenebeck 708
2780 senoner 542 "AUDIO_OUTPUT_CHANNELS: 2"
2781 schoenebeck 708
2782 schoenebeck 561 "AUDIO_OUTPUT_ROUTING: 0,1"
2783 schoenebeck 708
2784 senoner 542 "INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"
2785 schoenebeck 708
2786 senoner 542 "INSTRUMENT_NR: 0"
2787 schoenebeck 708
2788 senoner 542 "INSTRUMENT_NAME: Fazioli Piano"
2789 schoenebeck 708
2790 senoner 542 "INSTRUMENT_STATUS: 100"
2791 schoenebeck 708
2792 senoner 542 "MIDI_INPUT_DEVICE: 0"
2793 schoenebeck 708
2794 senoner 542 "MIDI_INPUT_PORT: 0"
2795 schoenebeck 708
2796    
2797 senoner 542
2798 schoenebeck 708
2799 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 50]
2800 schoenebeck 974
2801 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
2802 senoner 542
2803 schoenebeck 940
2804 schoenebeck 974 "MIDI_INPUT_CHANNEL: 5"
2805 schoenebeck 940
2806 schoenebeck 974 "VOLUME: 1.0"
2807 schoenebeck 940
2808 schoenebeck 974 "MUTE: false"
2809 schoenebeck 940
2810 schoenebeck 974 "SOLO: false"
2811 schoenebeck 940
2812 schoenebeck 974 "MIDI_INSTRUMENT_MAP: NONE"
2813 schoenebeck 940
2814 schoenebeck 974 "."
2815    
2816 schoenebeck 940 6.4.11. Current number of active voices
2817    
2818 senoner 542 The front-end can ask for the current number of active voices on a
2819     sampler channel by sending the following command:
2820    
2821     GET CHANNEL VOICE_COUNT <sampler-channel>
2822    
2823     Where <sampler-channel> is the sampler channel number the front-end
2824 schoenebeck 575 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2825     "LIST CHANNELS" (Section 6.4.4) command.
2826 senoner 542
2827     Possible Answers:
2828    
2829     LinuxSampler will answer by returning the number of active voices
2830     on that channel.
2831    
2832     Example:
2833    
2834    
2835    
2836 schoenebeck 940 6.4.12. Current number of active disk streams
2837 schoenebeck 708
2838 senoner 542 The front-end can ask for the current number of active disk streams
2839     on a sampler channel by sending the following command:
2840    
2841     GET CHANNEL STREAM_COUNT <sampler-channel>
2842    
2843     Where <sampler-channel> is the sampler channel number the front-end
2844 schoenebeck 575 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2845     "LIST CHANNELS" (Section 6.4.4) command.
2846 senoner 542
2847     Possible Answers:
2848    
2849     LinuxSampler will answer by returning the number of active disk
2850     streams on that channel in case the engine supports disk
2851     streaming, if the engine doesn't support disk streaming it will
2852 schoenebeck 974
2853    
2854    
2855 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 51]
2856 schoenebeck 974
2857 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
2858 schoenebeck 974
2859    
2860 senoner 542 return "NA" for not available.
2861    
2862     Example:
2863    
2864    
2865    
2866 schoenebeck 940 6.4.13. Current fill state of disk stream buffers
2867 schoenebeck 708
2868 senoner 542 The front-end can ask for the current fill state of all disk streams
2869     on a sampler channel by sending the following command:
2870    
2871     GET CHANNEL BUFFER_FILL BYTES <sampler-channel>
2872    
2873     to get the fill state in bytes or
2874    
2875     GET CHANNEL BUFFER_FILL PERCENTAGE <sampler-channel>
2876    
2877     to get the fill state in percent, where <sampler-channel> is the
2878 schoenebeck 575 sampler channel number the front-end is interested in as returned by
2879     the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
2880     command.
2881 senoner 542
2882     Possible Answers:
2883    
2884     LinuxSampler will either answer by returning a comma separated
2885     string with the fill state of all disk stream buffers on that
2886     channel or an empty line if there are no active disk streams or
2887     "NA" for *not available* in case the engine which is deployed
2888     doesn't support disk streaming. Each entry in the answer list
2889     will begin with the stream's ID in brackets followed by the
2890     numerical representation of the fill size (either in bytes or
2891     percentage). Note: due to efficiency reasons the fill states in
2892     the response are not in particular order, thus the front-end has
2893     to sort them by itself if necessary.
2894    
2895     Examples:
2896    
2897     C: "GET CHANNEL BUFFER_FILL BYTES 4"
2898 schoenebeck 708
2899 senoner 542 S: "[115]420500,[116]510300,[75]110000,[120]230700"
2900 schoenebeck 708
2901 senoner 542 C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
2902 schoenebeck 708
2903 senoner 542 S: "[115]90%,[116]98%,[75]40%,[120]62%"
2904 schoenebeck 708
2905 senoner 542 C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
2906 schoenebeck 708
2907 schoenebeck 974
2908    
2909    
2910    
2911 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 52]
2912 schoenebeck 974
2913 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
2914 schoenebeck 974
2915    
2916 senoner 542 S: ""
2917    
2918 schoenebeck 940 6.4.14. Setting audio output device
2919 schoenebeck 708
2920 senoner 542 The front-end can set the audio output device on a specific sampler
2921     channel by sending the following command:
2922    
2923     SET CHANNEL AUDIO_OUTPUT_DEVICE <sampler-channel>
2924     <audio-device-id>
2925    
2926 schoenebeck 575 Where <sampler-channel> is the respective sampler channel number as
2927     returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
2928     (Section 6.4.4) command and <audio-device-id> is the numerical ID of
2929     the audio output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
2930     (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
2931     command.
2932 senoner 542
2933     Possible Answers:
2934    
2935     "OK" -
2936 schoenebeck 708
2937 senoner 542 on success
2938 schoenebeck 708
2939 senoner 542 "WRN:<warning-code>:<warning-message>" -
2940 schoenebeck 708
2941 senoner 542 if audio output device was set, but there are noteworthy
2942     issue(s) related, providing an appropriate warning code and
2943     warning message
2944 schoenebeck 708
2945 senoner 542 "ERR:<error-code>:<error-message>" -
2946 schoenebeck 708
2947 senoner 542 in case it failed, providing an appropriate error code and
2948     error message
2949    
2950     Examples:
2951    
2952    
2953    
2954 schoenebeck 940 6.4.15. Setting audio output type
2955 senoner 542
2956     DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
2957    
2958     The front-end can alter the audio output type on a specific sampler
2959     channel by sending the following command:
2960    
2961 schoenebeck 708 SET CHANNEL AUDIO_OUTPUT_TYPE <sampler-channel> <audio-output-
2962     type>
2963 senoner 542
2964 schoenebeck 974
2965    
2966    
2967 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 53]
2968 schoenebeck 974
2969 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
2970 schoenebeck 974
2971    
2972 senoner 542 Where <audio-output-type> is currently either "ALSA" or "JACK" and
2973     <sampler-channel> is the respective sampler channel number.
2974    
2975     Possible Answers:
2976    
2977     "OK" -
2978 schoenebeck 708
2979 senoner 542 on success
2980 schoenebeck 708
2981 senoner 542 "WRN:<warning-code>:<warning-message>" -
2982 schoenebeck 708
2983 senoner 542 if audio output type was set, but there are noteworthy issue(s)
2984     related, providing an appropriate warning code and warning
2985     message
2986 schoenebeck 708
2987 senoner 542 "ERR:<error-code>:<error-message>" -
2988 schoenebeck 708
2989 senoner 542 in case it failed, providing an appropriate error code and
2990     error message
2991    
2992     Examples:
2993    
2994    
2995    
2996 schoenebeck 940 6.4.16. Setting audio output channel
2997 schoenebeck 708
2998 schoenebeck 575 The front-end can alter the audio output channel on a specific
2999     sampler channel by sending the following command:
3000 senoner 542
3001 schoenebeck 575 SET CHANNEL AUDIO_OUTPUT_CHANNEL <sampler-chan> <audio-out>
3002     <audio-in>
3003 senoner 542
3004 schoenebeck 575 Where <sampler-chan> is the sampler channel number as returned by the
3005     "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3006     command, <audio-out> is the numerical ID of the sampler channel's
3007     audio output channel which should be rerouted and <audio-in> is the
3008     numerical ID of the audio channel of the selected audio output device
3009     where <audio-out> should be routed to.
3010 senoner 542
3011 schoenebeck 575 Possible Answers:
3012 senoner 542
3013 schoenebeck 708 "OK" -
3014 senoner 542
3015 schoenebeck 708 on success
3016 senoner 542
3017 schoenebeck 708 "WRN:<warning-code>:<warning-message>" -
3018 senoner 542
3019 schoenebeck 974
3020    
3021    
3022    
3023 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 54]
3024 schoenebeck 974
3025 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
3026 schoenebeck 974
3027    
3028 senoner 542 if audio output channel was set, but there are noteworthy
3029     issue(s) related, providing an appropriate warning code and
3030     warning message
3031 schoenebeck 708
3032 senoner 542 "ERR:<error-code>:<error-message>" -
3033 schoenebeck 708
3034 senoner 542 in case it failed, providing an appropriate error code and
3035     error message
3036    
3037     Examples:
3038    
3039    
3040    
3041 schoenebeck 940 6.4.17. Setting MIDI input device
3042    
3043 senoner 542 The front-end can set the MIDI input device on a specific sampler
3044     channel by sending the following command:
3045    
3046     SET CHANNEL MIDI_INPUT_DEVICE <sampler-channel> <midi-device-id>
3047    
3048 schoenebeck 575 Where <sampler-channel> is the sampler channel number as returned by
3049     the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3050 schoenebeck 940 command and <midi-device-id> is the numerical ID of the MIDI input
3051 schoenebeck 575 device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5)
3052     or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command.
3053 senoner 542
3054     Possible Answers:
3055    
3056     "OK" -
3057 schoenebeck 708
3058 senoner 542 on success
3059 schoenebeck 708
3060 senoner 542 "WRN:<warning-code>:<warning-message>" -
3061 schoenebeck 708
3062 senoner 542 if MIDI input device was set, but there are noteworthy issue(s)
3063     related, providing an appropriate warning code and warning
3064     message
3065 schoenebeck 708
3066 senoner 542 "ERR:<error-code>:<error-message>" -
3067 schoenebeck 708
3068 senoner 542 in case it failed, providing an appropriate error code and
3069     error message
3070    
3071     Examples:
3072    
3073    
3074    
3075 schoenebeck 974
3076    
3077    
3078    
3079 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 55]
3080 schoenebeck 974
3081 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
3082 schoenebeck 974
3083    
3084 schoenebeck 940 6.4.18. Setting MIDI input type
3085 schoenebeck 708
3086 senoner 542 DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
3087    
3088     The front-end can alter the MIDI input type on a specific sampler
3089     channel by sending the following command:
3090    
3091     SET CHANNEL MIDI_INPUT_TYPE <sampler-channel> <midi-input-type>
3092    
3093 schoenebeck 708 Where <midi-input-type> is currently only "ALSA" and <sampler-
3094     channel> is the respective sampler channel number.
3095 senoner 542
3096     Possible Answers:
3097    
3098     "OK" -
3099 schoenebeck 708
3100 senoner 542 on success
3101 schoenebeck 708
3102 senoner 542 "WRN:<warning-code>:<warning-message>" -
3103 schoenebeck 708
3104 senoner 542 if MIDI input type was set, but there are noteworthy issue(s)
3105     related, providing an appropriate warning code and warning
3106     message
3107 schoenebeck 708
3108 senoner 542 "ERR:<error-code>:<error-message>" -
3109 schoenebeck 708
3110 senoner 542 in case it failed, providing an appropriate error code and
3111     error message
3112    
3113     Examples:
3114    
3115    
3116    
3117 schoenebeck 940 6.4.19. Setting MIDI input port
3118 schoenebeck 708
3119 senoner 542 The front-end can alter the MIDI input port on a specific sampler
3120     channel by sending the following command:
3121    
3122     SET CHANNEL MIDI_INPUT_PORT <sampler-channel> <midi-input-port>
3123    
3124     Where <midi-input-port> is a MIDI input port number of the MIDI input
3125     device connected to the sampler channel given by <sampler-channel>.
3126    
3127     Possible Answers:
3128    
3129     "OK" -
3130 schoenebeck 708
3131 schoenebeck 974
3132    
3133    
3134    
3135 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 56]
3136 schoenebeck 974
3137 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
3138 schoenebeck 974
3139    
3140 senoner 542 on success
3141 schoenebeck 708
3142 senoner 542 "WRN:<warning-code>:<warning-message>" -
3143 schoenebeck 708
3144 senoner 542 if MIDI input port was set, but there are noteworthy issue(s)
3145     related, providing an appropriate warning code and warning
3146     message
3147 schoenebeck 708
3148 senoner 542 "ERR:<error-code>:<error-message>" -
3149 schoenebeck 708
3150 senoner 542 in case it failed, providing an appropriate error code and
3151 schoenebeck 561 error message
3152 senoner 542
3153     Examples:
3154    
3155    
3156    
3157 schoenebeck 940 6.4.20. Setting MIDI input channel
3158 senoner 542
3159     The front-end can alter the MIDI channel a sampler channel should
3160     listen to by sending the following command:
3161    
3162     SET CHANNEL MIDI_INPUT_CHANNEL <sampler-channel> <midi-input-chan>
3163    
3164     Where <midi-input-chan> is the number of the new MIDI input channel
3165     where <sampler-channel> should listen to or "ALL" to listen on all 16
3166     MIDI channels.
3167    
3168     Possible Answers:
3169    
3170     "OK" -
3171 schoenebeck 708
3172 senoner 542 on success
3173 schoenebeck 708
3174 senoner 542 "WRN:<warning-code>:<warning-message>" -
3175 schoenebeck 708
3176 senoner 542 if MIDI input channel was set, but there are noteworthy
3177     issue(s) related, providing an appropriate warning code and
3178     warning message
3179 schoenebeck 708
3180 senoner 542 "ERR:<error-code>:<error-message>" -
3181 schoenebeck 708
3182 senoner 542 in case it failed, providing an appropriate error code and
3183     error message
3184    
3185     Examples:
3186    
3187    
3188    
3189 schoenebeck 974
3190    
3191 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 57]
3192 schoenebeck 974
3193 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
3194 schoenebeck 974
3195    
3196    
3197    
3198 schoenebeck 940 6.4.21. Setting channel volume
3199 schoenebeck 708
3200 senoner 542 The front-end can alter the volume of a sampler channel by sending
3201     the following command:
3202    
3203     SET CHANNEL VOLUME <sampler-channel> <volume>
3204    
3205     Where <volume> is an optionally dotted positive number (a value
3206     smaller than 1.0 means attenuation, whereas a value greater than 1.0
3207     means amplification) and <sampler-channel> defines the sampler
3208     channel where this volume factor should be set.
3209    
3210     Possible Answers:
3211    
3212     "OK" -
3213 schoenebeck 708
3214 senoner 542 on success
3215 schoenebeck 708
3216 senoner 542 "WRN:<warning-code>:<warning-message>" -
3217 schoenebeck 708
3218 senoner 542 if channel volume was set, but there are noteworthy issue(s)
3219     related, providing an appropriate warning code and warning
3220 schoenebeck 708 message
3221 schoenebeck 575
3222 schoenebeck 708 "ERR:<error-code>:<error-message>" -
3223 schoenebeck 575
3224 schoenebeck 708 in case it failed, providing an appropriate error code and
3225     error message
3226 schoenebeck 575
3227 schoenebeck 708 Examples:
3228    
3229    
3230    
3231 schoenebeck 940 6.4.22. Muting a sampler channel
3232 schoenebeck 708
3233     The front-end can mute/unmute a specific sampler channel by sending
3234     the following command:
3235    
3236     SET CHANNEL MUTE <sampler-channel> <mute>
3237    
3238     Where <sampler-channel> is the respective sampler channel number as
3239     returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3240     (Section 6.4.4) command and <mute> should be replaced either by "1"
3241     to mute the channel or "0" to unmute the channel.
3242    
3243     Possible Answers:
3244    
3245 schoenebeck 974
3246    
3247 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 58]
3248 schoenebeck 974
3249 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
3250 schoenebeck 974
3251    
3252 schoenebeck 708 "OK" -
3253    
3254     on success
3255    
3256     "WRN:<warning-code>:<warning-message>" -
3257    
3258     if the channel was muted/unmuted, but there are noteworthy
3259     issue(s) related, providing an appropriate warning code and
3260     warning message
3261    
3262 senoner 542 "ERR:<error-code>:<error-message>" -
3263 schoenebeck 708
3264 senoner 542 in case it failed, providing an appropriate error code and
3265     error message
3266    
3267     Examples:
3268    
3269    
3270    
3271 schoenebeck 940 6.4.23. Soloing a sampler channel
3272 senoner 542
3273 schoenebeck 708 The front-end can solo/unsolo a specific sampler channel by sending
3274     the following command:
3275    
3276     SET CHANNEL SOLO <sampler-channel> <solo>
3277    
3278     Where <sampler-channel> is the respective sampler channel number as
3279     returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3280     (Section 6.4.4) command and <solo> should be replaced either by "1"
3281     to solo the channel or "0" to unsolo the channel.
3282    
3283     Possible Answers:
3284    
3285     "OK" -
3286    
3287     on success
3288    
3289     "WRN:<warning-code>:<warning-message>" -
3290    
3291     if the channel was soloed/unsoloed, but there are noteworthy
3292     issue(s) related, providing an appropriate warning code and
3293     warning message
3294    
3295     "ERR:<error-code>:<error-message>" -
3296    
3297     in case it failed, providing an appropriate error code and
3298     error message
3299    
3300 schoenebeck 974
3301    
3302    
3303 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 59]
3304 schoenebeck 974
3305 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
3306 schoenebeck 974
3307    
3308 schoenebeck 708 Examples:
3309    
3310    
3311    
3312 schoenebeck 974 6.4.24. Assigning a MIDI instrument map to a sampler channel
3313 schoenebeck 708
3314 schoenebeck 974 The front-end can assign a MIDI instrument map to a specific sampler
3315     channel by sending the following command:
3316 senoner 542
3317 schoenebeck 974 SET CHANNEL MIDI_INSTRUMENT_MAP <sampler-channel> <map>
3318 senoner 542
3319 schoenebeck 974 Where <sampler-channel> is the respective sampler channel number as
3320     returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3321     (Section 6.4.4) command and <map> can have the following
3322     possibilites:
3323 schoenebeck 940
3324 schoenebeck 974 "NONE" -
3325 schoenebeck 940
3326 schoenebeck 974 This is the default setting. In this case the sampler channel
3327     is not assigned any MIDI instrument map and thus will ignore
3328     all MIDI program change messages.
3329 schoenebeck 940
3330 schoenebeck 974 "DEFAULT" -
3331    
3332     The sampler channel will always use the default MIDI instrument
3333     map to handle MIDI program change messages.
3334    
3335     numeric ID -
3336    
3337     You can assign a specific MIDI instrument map by replacing
3338     <map> with the respective numeric ID of the MIDI instrument map
3339     as returned by the "LIST MIDI_INSTRUMENT_MAPS" (Section 6.7.4)
3340     command. Once that map will be deleted, the sampler channel
3341     would fall back to "NONE".
3342    
3343     Read chapter "MIDI Instrument Mapping" (Section 6.7) for details
3344     regarding MIDI instrument mapping.
3345    
3346     Possible Answers:
3347    
3348     "OK" -
3349    
3350     on success
3351    
3352     "ERR:<error-code>:<error-message>" -
3353    
3354     in case it failed, providing an appropriate error code and
3355     error message
3356    
3357    
3358    
3359 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 60]
3360 schoenebeck 940
3361 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
3362 schoenebeck 940
3363    
3364 schoenebeck 974 Examples:
3365    
3366    
3367    
3368 schoenebeck 1002 6.4.25. Adding an effect send to a sampler channel
3369 schoenebeck 974
3370 schoenebeck 1002 The front-end can create an additional effect send on a specific
3371     sampler channel by sending the following command:
3372    
3373     CREATE FX_SEND <sampler-channel> <midi-ctrl> [<name>]
3374    
3375     Where <sampler-channel> is the respective sampler channel number as
3376     returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3377     (Section 6.4.4) command, that is the sampler channel on which the
3378     effect send should be created on, <midi-ctrl> is a number between
3379     0..127 defining the MIDI controller which can alter the effect send
3380     level and <name> is an optional argument defining a name for the
3381     effect send entity. The name does not have to be unique.
3382    
3383     By default, that is as initial routing, the effect send's audio
3384     channels are automatically routed to the last audio channels of the
3385     sampler channel's audio output device, that way you can i.e. first
3386     increase the amount of audio channels on the audio output device for
3387     having dedicated effect send output channels and when "CREATE
3388     FX_SEND" is called, those channels will automatically be picked. You
3389     can alter the destination channels however with "SET FX_SEND
3390     AUDIO_OUTPUT_CHANNEL" (Section 6.4.30).
3391    
3392     Note: Create effect sends on a sampler channel only when needed,
3393     because having effect sends on a sampler channel will decrease
3394     runtime performance, because for implementing channel effect sends,
3395     separate (sampler channel local) audio buffers are needed to render
3396     and mix the voices and route the audio signal afterwards to the
3397     master outputs and effect send outputs (along with their respective
3398     effect send levels). A sampler channel without effect sends however
3399     can mix its voices directly into the audio output devices's audio
3400     buffers and is thus faster.
3401    
3402     Possible Answers:
3403    
3404     "OK[<fx-send-id>]" -
3405    
3406     in case a new effect send could be added to the sampler
3407     channel, where <fx-send-id> reflects the unique ID of the newly
3408     created effect send entity
3409    
3410    
3411    
3412    
3413    
3414    
3415 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 61]
3416 schoenebeck 1002
3417 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
3418 schoenebeck 1002
3419    
3420     "ERR:<error-code>:<error-message>" -
3421    
3422     when a new effect send could not be added, i.e. due to invalid
3423     parameters
3424    
3425     Examples:
3426    
3427     C: "CREATE FX_SEND 0 91 'Reverb Send'"
3428    
3429     S: "OK[0]"
3430    
3431     C: "CREATE FX_SEND 0 93"
3432    
3433     S: "OK[1]"
3434    
3435     6.4.26. Removing an effect send from a sampler channel
3436    
3437     The front-end can remove an existing effect send on a specific
3438     sampler channel by sending the following command:
3439    
3440     DESTROY FX_SEND <sampler-channel> <fx-send-id>
3441    
3442     Where <sampler-channel> is the respective sampler channel number as
3443     returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3444     (Section 6.4.4) command, that is the sampler channel from which the
3445     effect send should be removed from and <fx-send-id> is the respective
3446     effect send number as returned by the "CREATE FX_SEND"
3447     (Section 6.4.25) or "LIST FX_SENDS" (Section 6.4.28) command.
3448    
3449     Possible Answers:
3450    
3451     "OK" -
3452    
3453     on success
3454    
3455     "ERR:<error-code>:<error-message>" -
3456    
3457     in case it failed, providing an appropriate error code and
3458     error message
3459    
3460     Example:
3461    
3462     C: "DESTROY FX_SEND 0 0"
3463    
3464     S: "OK"
3465    
3466    
3467    
3468    
3469    
3470    
3471 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 62]
3472 schoenebeck 1002
3473 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
3474 schoenebeck 1002
3475    
3476     6.4.27. Getting amount of effect sends on a sampler channel
3477    
3478     The front-end can ask for the amount of effect sends on a specific
3479     sampler channel by sending the following command:
3480    
3481     GET FX_SENDS <sampler-channel>
3482    
3483     Where <sampler-channel> is the respective sampler channel number as
3484     returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3485     (Section 6.4.4) command.
3486    
3487     Possible Answers:
3488    
3489     The sampler will answer by returning the number of effect sends on
3490     the given sampler channel.
3491    
3492     Example:
3493    
3494     C: "GET FX_SENDS 0"
3495    
3496     S: "2"
3497    
3498     6.4.28. Listing all effect sends on a sampler channel
3499    
3500     The front-end can ask for a list of effect sends on a specific
3501     sampler channel by sending the following command:
3502    
3503     LIST FX_SENDS <sampler-channel>
3504    
3505     Where <sampler-channel> is the respective sampler channel number as
3506     returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3507     (Section 6.4.4) command.
3508    
3509     Possible Answers:
3510    
3511     The sampler will answer by returning a comma separated list with
3512     all effect sends' numerical IDs on the given sampler channel.
3513    
3514     Examples:
3515    
3516     C: "LIST FX_SENDS 0"
3517    
3518     S: "0,1"
3519    
3520     C: "LIST FX_SENDS 1"
3521    
3522     S: ""
3523    
3524    
3525    
3526    
3527 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 63]
3528 schoenebeck 1002
3529 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
3530 schoenebeck 1002
3531    
3532     6.4.29. Getting effect send information
3533    
3534     The front-end can ask for the current settings of an effect send
3535     entity by sending the following command:
3536    
3537     GET FX_SEND INFO <sampler-channel> <fx-send-id>
3538    
3539     Where <sampler-channel> is the sampler channel number as returned by
3540     the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3541     command and <fx-send-id> reflects the numerical ID of the effect send
3542     entity as returned by the "CREATE FX_SEND" (Section 6.4.25) or "LIST
3543     FX_SENDS" (Section 6.4.28) command.
3544    
3545     Possible Answers:
3546    
3547     The sampler will answer by sending a <CRLF> separated list. Each
3548     answer line begins with the settings category name followed by a
3549     colon and then a space character <SP> and finally the info
3550     character string to that setting category. At the moment the
3551     following categories are defined:
3552    
3553    
3554    
3555     NAME -
3556    
3557     name of the effect send entity
3558    
3559 schoenebeck 1028 MIDI_CONTROLLER -
3560    
3561     a value between 0 and 127 reflecting the MIDI controller
3562     which is able to modify the effect send's send level
3563    
3564     LEVEL -
3565    
3566     optionally dotted number reflecting the effect send's
3567     current send level (where a value < 1.0 means attenuation
3568     and a value > 1.0 means amplification)
3569    
3570 schoenebeck 1002 AUDIO_OUTPUT_ROUTING -
3571    
3572     comma separated list which reflects to which audio channel
3573     of the selected audio output device each effect send output
3574     channel is routed to, e.g. "0,3" would mean the effect
3575     send's output channel 0 is routed to channel 0 of the audio
3576     output device and the effect send's output channel 1 is
3577     routed to the channel 3 of the audio output device (see "SET
3578     FX_SEND AUDIO_OUTPUT_CHANNEL" (Section 6.4.30) for details)
3579    
3580 schoenebeck 1028
3581    
3582    
3583 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 64]
3584 schoenebeck 1028
3585 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
3586 schoenebeck 1028
3587    
3588 schoenebeck 1002 The mentioned fields above don't have to be in particular order.
3589    
3590     Example:
3591    
3592     C: "GET FX_SEND INFO 0 0"
3593    
3594     S: "NAME: Reverb Send"
3595    
3596 schoenebeck 1028 "MIDI_CONTROLLER: 91"
3597 schoenebeck 1002
3598 schoenebeck 1028 "LEVEL: 0.3"
3599 schoenebeck 1002
3600 schoenebeck 1028 "AUDIO_OUTPUT_ROUTING: 2,3"
3601 schoenebeck 1002
3602     "."
3603    
3604     6.4.30. Altering effect send's audio routing
3605    
3606     The front-end can alter the destination of an effect send's audio
3607     channel on a specific sampler channel by sending the following
3608     command:
3609    
3610     SET FX_SEND AUDIO_OUTPUT_CHANNEL <sampler-chan> <fx-send-id>
3611     <audio-src> <audio-dst>
3612    
3613     Where <sampler-chan> is the sampler channel number as returned by the
3614     "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3615     command, <fx-send-id> reflects the numerical ID of the effect send
3616     entity as returned by the "CREATE FX_SEND" (Section 6.4.25) or "LIST
3617     FX_SENDS" (Section 6.4.28) command, <audio-src> is the numerical ID
3618     of the effect send's audio channel which should be rerouted and
3619     <audio-dst> is the numerical ID of the audio channel of the selected
3620     audio output device where <audio-src> should be routed to.
3621    
3622     Note that effect sends can only route audio to the same audio output
3623     device as assigned to the effect send's sampler channel. Also note
3624     that an effect send entity does always have exactly as much audio
3625     channels as its sampler channel. So if the sampler channel is
3626     stereo, the effect send does have two audio channels as well. Also
3627     keep in mind that the amount of audio channels on a sampler channel
3628     might be dependant not only to the deployed sampler engine on the
3629     sampler channel, but also dependant to the instrument currently
3630     loaded. However you can (effectively) turn an i.e. stereo effect
3631     send into a mono one by simply altering its audio routing
3632     appropriately.
3633    
3634     Possible Answers:
3635    
3636 schoenebeck 1028
3637    
3638    
3639 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 65]
3640 schoenebeck 1028
3641 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
3642 schoenebeck 1028
3643    
3644 schoenebeck 1002 "OK" -
3645    
3646     on success
3647    
3648     "WRN:<warning-code>:<warning-message>" -
3649    
3650     if audio output channel was set, but there are noteworthy
3651     issue(s) related, providing an appropriate warning code and
3652     warning message
3653    
3654     "ERR:<error-code>:<error-message>" -
3655    
3656     in case it failed, providing an appropriate error code and
3657     error message
3658    
3659 schoenebeck 1028 Example:
3660 schoenebeck 1002
3661 schoenebeck 1028 C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2"
3662 schoenebeck 1002
3663 schoenebeck 1028 S: "OK"
3664    
3665     6.4.31. Altering effect send's MIDI controller
3666    
3667     The front-end can alter the MIDI controller of an effect send entity
3668     by sending the following command:
3669    
3670     SET FX_SEND MIDI_CONTROLLER <sampler-chan> <fx-send-id> <midi-
3671     ctrl>
3672    
3673     Where <sampler-chan> is the sampler channel number as returned by the
3674     "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3675     command, <fx-send-id> reflects the numerical ID of the effect send
3676     entity as returned by the "CREATE FX_SEND" (Section 6.4.25) or "LIST
3677     FX_SENDS" (Section 6.4.28) command and <midi-ctrl> reflects the MIDI
3678     controller which shall be able to modify the effect send's send
3679     level.
3680    
3681     Possible Answers:
3682    
3683     "OK" -
3684    
3685     on success
3686    
3687     "WRN:<warning-code>:<warning-message>" -
3688    
3689     if MIDI controller was set, but there are noteworthy issue(s)
3690     related, providing an appropriate warning code and warning
3691     message
3692    
3693    
3694    
3695 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 66]
3696 schoenebeck 1002
3697 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
3698 schoenebeck 1002
3699    
3700 schoenebeck 1028 "ERR:<error-code>:<error-message>" -
3701    
3702     in case it failed, providing an appropriate error code and
3703     error message
3704    
3705 schoenebeck 1002 Example:
3706    
3707 schoenebeck 1028 C: "SET FX_SEND MIDI_CONTROLLER 0 0 91"
3708 schoenebeck 1002
3709     S: "OK"
3710    
3711 schoenebeck 1028 6.4.32. Altering effect send's send level
3712 schoenebeck 1002
3713 schoenebeck 1028 The front-end can alter the current send level of an effect send
3714     entity by sending the following command:
3715    
3716     SET FX_SEND LEVEL <sampler-chan> <fx-send-id> <volume>
3717    
3718     Where <sampler-chan> is the sampler channel number as returned by the
3719     "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3720     command, <fx-send-id> reflects the numerical ID of the effect send
3721     entity as returned by the "CREATE FX_SEND" (Section 6.4.25) or "LIST
3722     FX_SENDS" (Section 6.4.28) command and <volume> is an optionally
3723     dotted positive number (a value smaller than 1.0 means attenuation,
3724     whereas a value greater than 1.0 means amplification) reflecting the
3725     new send level.
3726    
3727     Possible Answers:
3728    
3729     "OK" -
3730    
3731     on success
3732    
3733     "WRN:<warning-code>:<warning-message>" -
3734    
3735     if new send level was set, but there are noteworthy issue(s)
3736     related, providing an appropriate warning code and warning
3737     message
3738    
3739     "ERR:<error-code>:<error-message>" -
3740    
3741     in case it failed, providing an appropriate error code and
3742     error message
3743    
3744     Example:
3745    
3746    
3747    
3748    
3749    
3750    
3751 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 67]
3752 schoenebeck 1028
3753 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
3754 schoenebeck 1028
3755    
3756     C: "SET FX_SEND LEVEL 0 0 0.15"
3757    
3758     S: "OK"
3759    
3760     6.4.33. Resetting a sampler channel
3761    
3762 schoenebeck 974 The front-end can reset a particular sampler channel by sending the
3763     following command:
3764    
3765     RESET CHANNEL <sampler-channel>
3766    
3767     Where <sampler-channel> defines the sampler channel to be reset.
3768 senoner 542 This will cause the engine on that sampler channel, its voices and
3769     eventually disk streams and all control and status variables to be
3770     reset.
3771    
3772     Possible Answers:
3773    
3774     "OK" -
3775 schoenebeck 708
3776 senoner 542 on success
3777 schoenebeck 708
3778 senoner 542 "WRN:<warning-code>:<warning-message>" -
3779 schoenebeck 708
3780 senoner 542 if channel was reset, but there are noteworthy issue(s)
3781     related, providing an appropriate warning code and warning
3782     message
3783 schoenebeck 708
3784 senoner 542 "ERR:<error-code>:<error-message>" -
3785 schoenebeck 708
3786 senoner 542 in case it failed, providing an appropriate error code and
3787     error message
3788    
3789     Examples:
3790    
3791    
3792    
3793 schoenebeck 940 6.5. Controlling connection
3794 schoenebeck 708
3795 schoenebeck 575 The following commands are used to control the connection to
3796     LinuxSampler.
3797 senoner 542
3798 schoenebeck 940 6.5.1. Register front-end for receiving event messages
3799 senoner 542
3800 schoenebeck 575 The front-end can register itself to the LinuxSampler application to
3801     be informed about noteworthy events by sending this command:
3802 senoner 542
3803 schoenebeck 974
3804    
3805 schoenebeck 1028
3806    
3807 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 68]
3808 schoenebeck 974
3809 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
3810 schoenebeck 974
3811    
3812 senoner 542 SUBSCRIBE <event-id>
3813    
3814     where <event-id> will be replaced by the respective event that client
3815     wants to subscribe to.
3816    
3817     Possible Answers:
3818    
3819     "OK" -
3820 schoenebeck 708
3821 senoner 542 on success
3822 schoenebeck 708
3823 senoner 542 "WRN:<warning-code>:<warning-message>" -
3824 schoenebeck 708
3825 senoner 542 if registration succeeded, but there are noteworthy issue(s)
3826     related, providing an appropriate warning code and warning
3827     message
3828 schoenebeck 708
3829 senoner 542 "ERR:<error-code>:<error-message>" -
3830 schoenebeck 708
3831 senoner 542 in case it failed, providing an appropriate error code and
3832     error message
3833    
3834     Examples:
3835    
3836    
3837    
3838 schoenebeck 940 6.5.2. Unregister front-end for not receiving event messages
3839 schoenebeck 708
3840 senoner 542 The front-end can unregister itself if it doesn't want to receive
3841     event messages anymore by sending the following command:
3842    
3843     UNSUBSCRIBE <event-id>
3844    
3845     Where <event-id> will be replaced by the respective event that client
3846     doesn't want to receive anymore.
3847    
3848     Possible Answers:
3849    
3850     "OK" -
3851 schoenebeck 708
3852 senoner 542 on success
3853 schoenebeck 708
3854 senoner 542 "WRN:<warning-code>:<warning-message>" -
3855 schoenebeck 708
3856 senoner 542 if unregistration succeeded, but there are noteworthy issue(s)
3857     related, providing an appropriate warning code and warning
3858     message
3859 schoenebeck 708
3860    
3861 senoner 542
3862    
3863 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 69]
3864 schoenebeck 974
3865 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
3866 senoner 542
3867    
3868 schoenebeck 974 "ERR:<error-code>:<error-message>" -
3869 senoner 542
3870 schoenebeck 974 in case it failed, providing an appropriate error code and
3871     error message
3872 schoenebeck 575
3873 schoenebeck 974 Examples:
3874 schoenebeck 940
3875    
3876    
3877     6.5.3. Enable or disable echo of commands
3878    
3879 senoner 542 To enable or disable back sending of commands to the client the
3880     following command can be used:
3881    
3882     SET ECHO <value>
3883    
3884     Where <value> should be replaced either by "1" to enable echo mode or
3885     "0" to disable echo mode. When echo mode is enabled, all commands
3886     send to LinuxSampler will be immediately send back and after this
3887     echo the actual response to the command will be returned. Echo mode
3888     will only be altered for the client connection that issued the "SET
3889     ECHO" command, not globally for all client connections.
3890    
3891     Possible Answers:
3892    
3893     "OK" -
3894 schoenebeck 708
3895 senoner 542 usually
3896 schoenebeck 708
3897 senoner 542 "ERR:<error-code>:<error-message>" -
3898    
3899 schoenebeck 708 on syntax error, e.g. non boolean value
3900    
3901 senoner 542 Examples:
3902    
3903    
3904    
3905 schoenebeck 940 6.5.4. Close client connection
3906 schoenebeck 708
3907 senoner 542 The client can close its network connection to LinuxSampler by
3908     sending the following command:
3909    
3910     QUIT
3911    
3912     This is probably more interesting for manual telnet connections to
3913     LinuxSampler than really useful for a front-end implementation.
3914    
3915    
3916    
3917    
3918 schoenebeck 940
3919 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 70]
3920 schoenebeck 974
3921 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
3922 schoenebeck 940
3923    
3924 schoenebeck 974 6.6. Global commands
3925 schoenebeck 940
3926 schoenebeck 974 The following commands have global impact on the sampler.
3927 schoenebeck 940
3928 schoenebeck 974 6.6.1. Current number of active voices
3929 schoenebeck 940
3930 schoenebeck 974 The front-end can ask for the current number of active voices on the
3931     sampler by sending the following command:
3932 schoenebeck 940
3933     GET TOTAL_VOICE_COUNT
3934    
3935     Possible Answers:
3936    
3937     LinuxSampler will answer by returning the number of all active
3938     voices on the sampler.
3939    
3940     6.6.2. Maximum amount of active voices
3941    
3942     The front-end can ask for the maximum number of active voices by
3943     sending the following command:
3944    
3945     GET TOTAL_VOICE_COUNT_MAX
3946    
3947     Possible Answers:
3948    
3949     LinuxSampler will answer by returning the maximum number of active
3950     voices.
3951    
3952     6.6.3. Reset sampler
3953    
3954 schoenebeck 575 The front-end can reset the whole sampler by sending the following
3955     command:
3956 senoner 542
3957 schoenebeck 575 RESET
3958    
3959     Possible Answers:
3960    
3961 schoenebeck 708 "OK" -
3962 schoenebeck 575
3963 schoenebeck 708 always
3964 schoenebeck 575
3965 schoenebeck 708 Examples:
3966 schoenebeck 575
3967 senoner 542
3968    
3969 schoenebeck 974
3970    
3971    
3972    
3973    
3974    
3975 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 71]
3976 schoenebeck 974
3977 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
3978 schoenebeck 974
3979    
3980 schoenebeck 940 6.6.4. General sampler informations
3981 senoner 542
3982 schoenebeck 708 The client can ask for general informations about the LinuxSampler
3983 schoenebeck 575 instance by sending the following command:
3984    
3985     GET SERVER INFO
3986    
3987 senoner 542 Possible Answers:
3988    
3989 schoenebeck 575 LinuxSampler will answer by sending a <CRLF> separated list. Each
3990     answer line begins with the information category name followed by
3991     a colon and then a space character <SP> and finally the info
3992     character string to that information category. At the moment the
3993     following categories are defined:
3994 senoner 542
3995 schoenebeck 708
3996    
3997 schoenebeck 575 DESCRIPTION -
3998 schoenebeck 708
3999 schoenebeck 575 arbitrary textual description about the sampler
4000 schoenebeck 708
4001 schoenebeck 575 VERSION -
4002 schoenebeck 708
4003 schoenebeck 575 version of the sampler
4004 schoenebeck 708
4005 schoenebeck 575 PROTOCOL_VERSION -
4006 schoenebeck 708
4007 schoenebeck 575 version of the LSCP specification the sampler complies with
4008     (see Section 2 for details)
4009 senoner 542
4010 schoenebeck 575 The mentioned fields above don't have to be in particular order.
4011     Other fields might be added in future.
4012 senoner 542
4013 schoenebeck 1006 6.6.5. Getting global volume attenuation
4014    
4015     The client can ask for the current global sampler-wide volume
4016     attenuation by sending the following command:
4017    
4018     GET VOLUME
4019    
4020     Possible Answers:
4021    
4022     The sampler will always answer by returning the optional dotted
4023     floating point coefficient, reflecting the current global volume
4024     attenuation.
4025    
4026     Note: it is up to the respective sampler engine whether to obey that
4027     global volume parameter or not, but in general all engines SHOULD use
4028    
4029    
4030    
4031 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 72]
4032 schoenebeck 1006
4033 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
4034 schoenebeck 1006
4035    
4036     this parameter.
4037    
4038     6.6.6. Setting global volume attenuation
4039    
4040     The client can alter the current global sampler-wide volume
4041     attenuation by sending the following command:
4042    
4043     SET VOLUME <volume>
4044    
4045     Where <volume> should be replaced by the optional dotted floating
4046     point value, reflecting the new global volume parameter. This value
4047     might usually be in the range between 0.0 and 1.0, that is for
4048     attenuating the overall volume.
4049    
4050     Possible Answers:
4051    
4052     "OK" -
4053    
4054     on success
4055    
4056     "WRN:<warning-code>:<warning-message>" -
4057    
4058     if the global volume was set, but there are noteworthy issue(s)
4059     related, providing an appropriate warning code and warning
4060     message
4061    
4062     "ERR:<error-code>:<error-message>" -
4063    
4064     in case it failed, providing an appropriate error code and
4065     error message
4066    
4067 schoenebeck 945 6.7. MIDI Instrument Mapping
4068 senoner 542
4069 schoenebeck 945 The MIDI protocol provides a way to switch between instruments by
4070     sending so called MIDI bank select and MIDI program change messages
4071     which are essentially just numbers. The following commands allow to
4072     actually map arbitrary MIDI bank select / program change numbers with
4073     real instruments.
4074 senoner 542
4075 schoenebeck 974 The sampler allows to manage an arbitrary amount of MIDI instrument
4076     maps which define which instrument to load on which MIDI program
4077     change message.
4078 senoner 542
4079 schoenebeck 974 By default, that is when the sampler is launched, there is no map,
4080     thus the sampler will simply ignore all program change messages. The
4081     front-end has to explicitly create at least one map, add entries to
4082 schoenebeck 1006 the map and tell the respective sampler channel(s) which MIDI
4083     instrument map to use, so the sampler knows how to react on a given
4084 schoenebeck 974
4085    
4086    
4087 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 73]
4088 schoenebeck 974
4089 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
4090 schoenebeck 974
4091    
4092     program change message on the respective sampler channel, that is by
4093     switching to the respectively defined engine type and loading the
4094     respective instrument. See command "SET CHANNEL MIDI_INSTRUMENT_MAP"
4095     (Section 6.4.24) for how to assign a MIDI instrument map to a sampler
4096     channel.
4097    
4098 schoenebeck 945 Also note per MIDI specification a bank select message does not cause
4099     to switch to another instrument. Instead when receiving a bank
4100     select message the bank value will be stored and a subsequent program
4101     change message (which may occur at any time) will finally cause the
4102     sampler to switch to the respective instrument as reflected by the
4103     current MIDI instrument map.
4104 senoner 542
4105 schoenebeck 974 6.7.1. Create a new MIDI instrument map
4106 senoner 542
4107 schoenebeck 974 The front-end can add a new MIDI instrument map by sending the
4108     following command:
4109    
4110     ADD MIDI_INSTRUMENT_MAP [<name>]
4111    
4112     Where <name> is an optional argument allowing to assign a custom name
4113     to the new map. MIDI instrument Map names do not have to be unique.
4114    
4115     Possible Answers:
4116    
4117     "OK[<map>]" -
4118    
4119     in case a new MIDI instrument map could be added, where <map>
4120     reflects the unique ID of the newly created MIDI instrument map
4121    
4122     "ERR:<error-code>:<error-message>" -
4123    
4124     when a new map could not be created, which might never occur in
4125     practice
4126    
4127     Examples:
4128    
4129     C: "ADD MIDI_INSTRUMENT_MAP 'Standard Map'"
4130    
4131     S: "OK[0]"
4132    
4133     C: "ADD MIDI_INSTRUMENT_MAP 'Standard Drumkit'"
4134    
4135     S: "OK[1]"
4136    
4137 schoenebeck 1006 C: "ADD MIDI_INSTRUMENT_MAP"
4138 schoenebeck 974
4139    
4140    
4141    
4142 schoenebeck 1006
4143 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 74]
4144 schoenebeck 974
4145 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
4146 schoenebeck 974
4147    
4148     S: "OK[5]"
4149    
4150     6.7.2. Delete one particular or all MIDI instrument maps
4151    
4152     The front-end can delete a particular MIDI instrument map by sending
4153     the following command:
4154    
4155     REMOVE MIDI_INSTRUMENT_MAP <map>
4156    
4157     Where <map> reflects the unique ID of the map to delete as returned
4158     by the "LIST MIDI_INSTRUMENT_MAPS" (Section 6.7.4) command.
4159    
4160     The front-end can delete all MIDI instrument maps by sending the
4161     following command:
4162    
4163     REMOVE MIDI_INSTRUMENT_MAP ALL
4164    
4165     Possible Answers:
4166    
4167     "OK" -
4168    
4169     in case the map(s) could be deleted
4170    
4171     "ERR:<error-code>:<error-message>" -
4172    
4173     when the given map does not exist
4174    
4175     Examples:
4176    
4177     C: "REMOVE MIDI_INSTRUMENT_MAP 0"
4178    
4179     S: "OK"
4180    
4181     C: "REMOVE MIDI_INSTRUMENT_MAP ALL"
4182    
4183     S: "OK"
4184    
4185     6.7.3. Get amount of existing MIDI instrument maps
4186    
4187     The front-end can retrieve the current amount of MIDI instrument maps
4188     by sending the following command:
4189    
4190     GET MIDI_INSTRUMENT_MAPS
4191    
4192     Possible Answers:
4193    
4194    
4195    
4196    
4197 schoenebeck 1006
4198    
4199 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 75]
4200 schoenebeck 974
4201 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
4202 schoenebeck 974
4203    
4204     The sampler will answer by returning the current number of MIDI
4205     instrument maps.
4206    
4207     Example:
4208    
4209     C: "GET MIDI_INSTRUMENT_MAPS"
4210    
4211     S: "2"
4212    
4213     6.7.4. Getting all created MIDI instrument maps
4214    
4215     The number of MIDI instrument maps can change on runtime. To get the
4216     current list of MIDI instrument maps, the front-end can send the
4217     following command:
4218    
4219     LIST MIDI_INSTRUMENT_MAPS
4220    
4221     Possible Answers:
4222    
4223     The sampler will answer by returning a comma separated list with
4224     all MIDI instrument maps' numerical IDs.
4225    
4226     Example:
4227    
4228     C: "LIST MIDI_INSTRUMENT_MAPS"
4229    
4230     S: "0,1,5,12"
4231    
4232     6.7.5. Getting MIDI instrument map information
4233    
4234     The front-end can ask for the current settings of a MIDI instrument
4235     map by sending the following command:
4236    
4237     GET MIDI_INSTRUMENT_MAP INFO <map>
4238    
4239     Where <map> is the numerical ID of the map the front-end is
4240     interested in as returned by the "LIST MIDI_INSTRUMENT_MAPS"
4241     (Section 6.7.4) command.
4242    
4243     Possible Answers:
4244    
4245     LinuxSampler will answer by sending a <CRLF> separated list. Each
4246     answer line begins with the settings category name followed by a
4247     colon and then a space character <SP> and finally the info
4248     character string to that setting category. At the moment the
4249     following categories are defined:
4250    
4251    
4252    
4253    
4254    
4255 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 76]
4256 schoenebeck 974
4257 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
4258 schoenebeck 974
4259    
4260    
4261    
4262     NAME -
4263    
4264     custom name of the given map, which does not have to be
4265     unique
4266    
4267     The mentioned fields above don't have to be in particular order.
4268    
4269     Example:
4270    
4271     C: "GET MIDI_INSTRUMENT_MAP INFO 0"
4272    
4273     S: "NAME: Standard Map"
4274    
4275     "."
4276    
4277     6.7.6. Renaming a MIDI instrument map
4278    
4279     The front-end can alter the custom name of a MIDI instrument map by
4280     sending the following command:
4281    
4282     SET MIDI_INSTRUMENT_MAP NAME <map> <name>
4283    
4284     Where <map> is the numerical ID of the map and <name> the new custom
4285     name of the map, which does not have to be unique.
4286    
4287     Possible Answers:
4288    
4289     "OK" -
4290    
4291     on success
4292    
4293     "ERR:<error-code>:<error-message>" -
4294    
4295     in case the given map does not exist
4296    
4297     Example:
4298    
4299     C: "SET MIDI_INSTRUMENT_MAP NAME 0 'Foo instruments'"
4300    
4301     S: "OK"
4302    
4303     6.7.7. Create or replace a MIDI instrument map entry
4304    
4305     The front-end can create a new or replace an existing entry in a
4306 schoenebeck 945 sampler's MIDI instrument map by sending the following command:
4307 senoner 542
4308    
4309    
4310    
4311 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 77]
4312 schoenebeck 945
4313 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
4314 senoner 542
4315    
4316 schoenebeck 1048 MAP MIDI_INSTRUMENT [NON_MODAL] <map> <midi_bank> <midi_prog>
4317     <engine_name> <filename> <instrument_index> <volume_value>
4318     [<instr_load_mode>] [<name>]
4319 senoner 542
4320 schoenebeck 974 Where <map> is the numeric ID of the map to alter, <midi_bank> is an
4321     integer value between 0..16383 reflecting the MIDI bank select index,
4322     <midi_prog> an integer value between 0..127 reflecting the MIDI
4323     program change index, <engine_name> a sampler engine name as returned
4324     by the "LIST AVAILABLE_ENGINES" (Section 6.4.8) command (not
4325 schoenebeck 945 encapsulated into apostrophes), <filename> the name of the
4326     instrument's file to be deployed (encapsulated into apostrophes),
4327     <instrument_index> the index (integer value) of the instrument within
4328     the given file, <volume_value> reflects the master volume of the
4329     instrument as optionally dotted number (where a value < 1.0 means
4330     attenuation and a value > 1.0 means amplification). This parameter
4331     easily allows to adjust the volume of all intruments within a custom
4332     instrument map without having to adjust their instrument files. The
4333     OPTIONAL <instr_load_mode> argument defines the life time of the
4334     instrument, that is when the instrument should be loaded, when freed
4335     and has exactly the following possibilities:
4336 senoner 542
4337 schoenebeck 945 "ON_DEMAND" -
4338 senoner 542
4339 schoenebeck 945 The instrument will be loaded when needed, that is when
4340     demanded by at least one sampler channel. It will immediately
4341     be freed from memory when not needed by any sampler channel
4342     anymore.
4343 senoner 542
4344 schoenebeck 945 "ON_DEMAND_HOLD" -
4345 senoner 542
4346 schoenebeck 945 The instrument will be loaded when needed, that is when
4347     demanded by at least one sampler channel. It will be kept in
4348     memory even when not needed by any sampler channel anymore.
4349     Instruments with this mode are only freed when the sampler is
4350     reset or all mapping entries with this mode (and respective
4351     instrument) are explicitly changed to "ON_DEMAND" and no
4352     sampler channel is using the instrument anymore.
4353 senoner 542
4354 schoenebeck 945 "PERSISTENT" -
4355 senoner 542
4356 schoenebeck 1048 The instrument will immediately be loaded into memory when this
4357     mapping command is sent and the instrument is kept all the
4358     time. Instruments with this mode are only freed when the
4359     sampler is reset or all mapping entries with this mode (and
4360     respective instrument) are explicitly changed to "ON_DEMAND"
4361     and no sampler channel is using the instrument anymore.
4362 senoner 542
4363    
4364 schoenebeck 708
4365 schoenebeck 974
4366 schoenebeck 1048
4367     Schoenebeck Expires August 23, 2007 [Page 78]
4368 schoenebeck 945
4369 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
4370 schoenebeck 708
4371    
4372 schoenebeck 945 not supplied -
4373 schoenebeck 708
4374 schoenebeck 945 In case there is no <instr_load_mode> argument given, it will
4375     be up to the InstrumentManager to decide which mode to use.
4376     Usually it will use "ON_DEMAND" if an entry for the given
4377     instrument does not exist in the InstrumentManager's list yet,
4378     otherwise if an entry already exists, it will simply stick with
4379     the mode currently reflected by the already existing entry,
4380     that is it will not change the mode.
4381 schoenebeck 940
4382 schoenebeck 945 The <instr_load_mode> argument thus allows to define an appropriate
4383     strategy (low memory consumption vs. fast instrument switching) for
4384     each instrument individually. Note, the following restrictions apply
4385     to this argument: "ON_DEMAND_HOLD" and "PERSISTENT" have to be
4386     supported by the respective sampler engine (which is technically the
4387     case when the engine provides an InstrumentManager for its format).
4388     If this is not the case the argument will automatically fall back to
4389     the default value "ON_DEMAND". Also the load mode of one instrument
4390     may automatically change the laod mode of other instrument(s), i.e.
4391     because the instruments are part of the same file and the engine does
4392     not allow a way to manage load modes for them individually. Due to
4393     this, in case the frontend shows the load modes of entries, the
4394     frontend should retrieve the actual mode by i.e. sending "GET
4395 schoenebeck 974 MIDI_INSTRUMENT INFO" (Section 6.7.11) command(s). Finally the
4396 schoenebeck 945 OPTIONAL <name> argument allows to set a custom name (encapsulated
4397     into apostrophes) for the mapping entry, useful for frontends for
4398     displaying an appropriate name for mapped instruments (using "GET
4399 schoenebeck 974 MIDI_INSTRUMENT INFO" (Section 6.7.11)).
4400 schoenebeck 940
4401 schoenebeck 1048 By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is
4402     completely established in the sampler. The OPTIONAL "NON_MODAL"
4403     argument however causes the respective "MAP MIDI_INSTRUMENT" command
4404     to return immediately, that is to let the sampler establish the
4405     mapping in the background. So this argument might be especially
4406     useful for mappings with a "PERSISTENT" type, because these have to
4407     load the respective instruments immediately and might thus block for
4408     a very long time. It is recommended however to use the OPTIONAL
4409     "NON_MODAL" argument only if really necessary, because it has the
4410     following drawbacks: as "NON_MODAL" instructions return immediately,
4411     they may not necessarily return an error i.e. when the given
4412     instrument file turns out to be corrupt, beside that subsequent
4413     commands in a LSCP instruction sequence might fail, because mandatory
4414     mappings are not yet completed.
4415 schoenebeck 940
4416 schoenebeck 945 Possible Answers:
4417 schoenebeck 940
4418 schoenebeck 1048
4419    
4420    
4421    
4422    
4423     Schoenebeck Expires August 23, 2007 [Page 79]
4424    
4425     Internet-Draft LinuxSampler Control Protocol February 2007
4426    
4427    
4428 schoenebeck 945 "OK" -
4429 schoenebeck 940
4430 schoenebeck 945 usually
4431 schoenebeck 940
4432 schoenebeck 945 "ERR:<error-code>:<error-message>" -
4433    
4434 schoenebeck 974 when the given map or engine does not exist or a value is out
4435     of range
4436 schoenebeck 945
4437     Examples:
4438    
4439 schoenebeck 974 C: "MAP MIDI_INSTRUMENT 0 3 0 gig '/usr/share/Steinway D.gig' 0
4440 schoenebeck 945 0.8 PERSISTENT"
4441    
4442     S: "OK"
4443    
4444 schoenebeck 974 C: "MAP MIDI_INSTRUMENT 0 4 50 gig '/home/john/foostrings.gig' 7
4445 schoenebeck 945 1.0"
4446    
4447     S: "OK"
4448    
4449     C: "MAP MIDI_INSTRUMENT 0 0 0 gig '/usr/share/piano.gig' 0 1.0
4450     'Normal Piano'"
4451    
4452     S: "OK"
4453    
4454 schoenebeck 974 C: "MAP MIDI_INSTRUMENT 0 1 0 gig '/usr/share/piano.gig' 0 0.25
4455 schoenebeck 945 'Silent Piano'"
4456    
4457     S: "OK"
4458    
4459 schoenebeck 1048 C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/
4460     foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"
4461 schoenebeck 945
4462     S: "OK"
4463    
4464 schoenebeck 974 6.7.8. Getting ammount of MIDI instrument map entries
4465 schoenebeck 945
4466 schoenebeck 974 The front-end can query the amount of currently existing entries in a
4467     MIDI instrument map by sending the following command:
4468 schoenebeck 945
4469 schoenebeck 974 GET MIDI_INSTRUMENTS <map>
4470 schoenebeck 945
4471 schoenebeck 974 The front-end can query the amount of currently existing entries in
4472     all MIDI instrument maps by sending the following command:
4473    
4474 schoenebeck 1048
4475    
4476    
4477    
4478    
4479     Schoenebeck Expires August 23, 2007 [Page 80]
4480    
4481     Internet-Draft LinuxSampler Control Protocol February 2007
4482    
4483    
4484 schoenebeck 974 GET MIDI_INSTRUMENTS ALL
4485    
4486 schoenebeck 945 Possible Answers:
4487    
4488 schoenebeck 974 The sampler will answer by sending the current number of entries
4489     in the MIDI instrument map(s).
4490 schoenebeck 945
4491     Example:
4492    
4493 schoenebeck 974 C: "GET MIDI_INSTRUMENTS 0"
4494 schoenebeck 945
4495 schoenebeck 974 S: "234"
4496 schoenebeck 945
4497 schoenebeck 974 C: "GET MIDI_INSTRUMENTS ALL"
4498 schoenebeck 945
4499 schoenebeck 974 S: "954"
4500 schoenebeck 945
4501 schoenebeck 974 6.7.9. Getting indeces of all entries of a MIDI instrument map
4502 schoenebeck 945
4503 schoenebeck 974 The front-end can query a list of all currently existing entries in a
4504     certain MIDI instrument map by sending the following command:
4505    
4506     LIST MIDI_INSTRUMENTS <map>
4507    
4508     Where <map> is the numeric ID of the MIDI instrument map.
4509    
4510     The front-end can query a list of all currently existing entries of
4511     all MIDI instrument maps by sending the following command:
4512    
4513     LIST MIDI_INSTRUMENTS ALL
4514    
4515 schoenebeck 945 Possible Answers:
4516    
4517 schoenebeck 974 The sampler will answer by sending a comma separated list of map
4518     ID - MIDI bank - MIDI program triples, where each triple is
4519     encapsulated into curly braces. The list is returned in one
4520     single line. Each triple just reflects the key of the respective
4521     map entry, thus subsequent "GET MIDI_INSTRUMENT INFO"
4522     (Section 6.7.11) command(s) are necessary to retrieve detailed
4523     informations about each entry.
4524 schoenebeck 945
4525     Example:
4526    
4527 schoenebeck 974 C: "LIST MIDI_INSTRUMENTS 0"
4528 schoenebeck 945
4529 schoenebeck 974 S: "{0,0,0},{0,0,1},{0,0,3},{0,1,4},{1,127,127}"
4530 schoenebeck 945
4531 schoenebeck 1048
4532    
4533    
4534    
4535     Schoenebeck Expires August 23, 2007 [Page 81]
4536    
4537     Internet-Draft LinuxSampler Control Protocol February 2007
4538    
4539    
4540 schoenebeck 974 6.7.10. Remove an entry from the MIDI instrument map
4541 schoenebeck 945
4542 schoenebeck 974 The front-end can delete an entry from a MIDI instrument map by
4543 schoenebeck 945 sending the following command:
4544    
4545 schoenebeck 974 UNMAP MIDI_INSTRUMENT <map> <midi_bank> <midi_prog>
4546 schoenebeck 945
4547 schoenebeck 974 Where <map> is the numeric ID of the MIDI instrument map, <midi_bank>
4548     is an integer value between 0..16383 reflecting the MIDI bank value
4549     and <midi_prog> an integer value between 0..127 reflecting the MIDI
4550     program value of the map's entrie's key index triple.
4551 schoenebeck 945
4552     Possible Answers:
4553    
4554     "OK" -
4555    
4556     usually
4557    
4558     "ERR:<error-code>:<error-message>" -
4559    
4560     when index out of bounds
4561    
4562     Example:
4563    
4564 schoenebeck 974 C: "UNMAP MIDI_INSTRUMENT 0 2 127"
4565 schoenebeck 945
4566     S: "OK"
4567    
4568 schoenebeck 974 6.7.11. Get current settings of MIDI instrument map entry
4569 schoenebeck 945
4570     The front-end can retrieve the current settings of a certain
4571     instrument map entry by sending the following command:
4572    
4573 schoenebeck 974 GET MIDI_INSTRUMENT INFO <map> <midi_bank> <midi_prog>
4574 schoenebeck 945
4575 schoenebeck 974 Where <map> is the numeric ID of the MIDI instrument map, <midi_bank>
4576     is an integer value between 0..16383 reflecting the MIDI bank value,
4577     <midi_bank> and <midi_prog> an integer value between 0..127
4578     reflecting the MIDI program value of the map's entrie's key index
4579     triple.
4580 schoenebeck 945
4581     Possible Answers:
4582    
4583     LinuxSampler will answer by sending a <CRLF> separated list. Each
4584     answer line begins with the information category name followed by
4585     a colon and then a space character <SP> and finally the info
4586     character string to that info category. At the moment the
4587     following categories are defined:
4588    
4589 schoenebeck 1048
4590    
4591     Schoenebeck Expires August 23, 2007 [Page 82]
4592    
4593     Internet-Draft LinuxSampler Control Protocol February 2007
4594    
4595    
4596 schoenebeck 945 "NAME" -
4597    
4598     Name for this MIDI instrument map entry (if defined). This
4599     name shall be used by frontends for displaying a name for this
4600     mapped instrument. It can be set and changed with the "MAP
4601 schoenebeck 974 MIDI_INSTRUMENT" (Section 6.7.7) command and does not have to
4602 schoenebeck 945 be unique.
4603    
4604     "ENGINE_NAME" -
4605    
4606     Name of the engine to be deployed for this instrument.
4607    
4608     "INSTRUMENT_FILE" -
4609    
4610     File name of the instrument.
4611    
4612     "INSTRUMENT_NR" -
4613    
4614     Index of the instrument within the file.
4615    
4616     "INSTRUMENT_NAME" -
4617    
4618     Name of the loaded instrument as reflected by its file. In
4619     contrast to the "NAME" field, the "INSTRUMENT_NAME" field
4620     cannot be changed.
4621    
4622     "LOAD_MODE" -
4623    
4624     Life time of instrument (see "MAP MIDI_INSTRUMENT"
4625 schoenebeck 974 (Section 6.7.7) for details about this setting).
4626 schoenebeck 945
4627     "VOLUME" -
4628    
4629     master volume of the instrument as optionally dotted number
4630     (where a value < 1.0 means attenuation and a value > 1.0 means
4631     amplification)
4632    
4633     The mentioned fields above don't have to be in particular order.
4634    
4635     Example:
4636    
4637 schoenebeck 974 C: "GET MIDI_INSTRUMENT INFO 1 45 120"
4638 schoenebeck 945
4639     S: "NAME: Drums for Foo Song"
4640    
4641     "ENGINE_NAME: GigEngine"
4642    
4643 schoenebeck 1048
4644    
4645    
4646    
4647     Schoenebeck Expires August 23, 2007 [Page 83]
4648    
4649     Internet-Draft LinuxSampler Control Protocol February 2007
4650    
4651    
4652 schoenebeck 945 "INSTRUMENT_FILE: /usr/share/joesdrumkit.gig"
4653    
4654     "INSTRUMENT_NR: 0"
4655    
4656     "INSTRUMENT_NAME: Joe's Drumkit"
4657    
4658     "LOAD_MODE: PERSISTENT"
4659    
4660     "VOLUME: 1.0"
4661    
4662     "."
4663    
4664 schoenebeck 974 6.7.12. Clear MIDI instrument map
4665 schoenebeck 945
4666 schoenebeck 974 The front-end can clear a whole MIDI instrument map, that is delete
4667     all its entries by sending the following command:
4668 schoenebeck 945
4669 schoenebeck 974 CLEAR MIDI_INSTRUMENTS <map>
4670 schoenebeck 945
4671 schoenebeck 974 Where <map> is the numeric ID of the map to clear.
4672 schoenebeck 945
4673 schoenebeck 974 The front-end can clear all MIDI instrument maps, that is delete all
4674     entries of all maps by sending the following command:
4675 schoenebeck 945
4676 schoenebeck 974 CLEAR MIDI_INSTRUMENTS ALL
4677 schoenebeck 945
4678 schoenebeck 974 The command "CLEAR MIDI_INSTRUMENTS ALL" does not delete the maps,
4679     only their entries, thus the map's settings like custom name will be
4680     preservevd.
4681 schoenebeck 945
4682 schoenebeck 974 Possible Answers:
4683 schoenebeck 945
4684 schoenebeck 974 "OK" -
4685 schoenebeck 945
4686 schoenebeck 974 always
4687 schoenebeck 945
4688 schoenebeck 974 Examples:
4689 schoenebeck 945
4690 schoenebeck 974 C: "CLEAR MIDI_INSTRUMENTS 0"
4691 schoenebeck 945
4692 schoenebeck 974 S: "OK"
4693 schoenebeck 945
4694 schoenebeck 974 C: "CLEAR MIDI_INSTRUMENTS ALL"
4695 schoenebeck 945
4696 schoenebeck 974 S: "OK"
4697 schoenebeck 945
4698    
4699    
4700    
4701    
4702    
4703 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 84]
4704 schoenebeck 945
4705 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
4706 schoenebeck 945
4707    
4708 schoenebeck 575 7. Command Syntax
4709 senoner 542
4710 schoenebeck 575 The grammar of the control protocol as descibed in Section 6 is
4711     defined below using Backus-Naur Form (BNF as described in [RFC2234])
4712     where applicable.
4713 senoner 542
4714 schoenebeck 575 input =
4715 schoenebeck 708
4716 schoenebeck 575 line LF
4717 schoenebeck 708
4718 schoenebeck 575 / line CR LF
4719 senoner 542
4720 schoenebeck 575 line =
4721 schoenebeck 708
4722 schoenebeck 575 /* epsilon (empty line ignored) */
4723 schoenebeck 708
4724 schoenebeck 575 / comment
4725 schoenebeck 708
4726 schoenebeck 575 / command
4727 schoenebeck 708
4728 schoenebeck 575 / error
4729 senoner 542
4730 schoenebeck 575 comment =
4731 schoenebeck 708
4732 schoenebeck 575 '#'
4733 schoenebeck 708
4734 schoenebeck 575 / comment '#'
4735 schoenebeck 708
4736 schoenebeck 575 / comment SP
4737 schoenebeck 708
4738 schoenebeck 575 / comment number
4739 schoenebeck 708
4740 schoenebeck 575 / comment string
4741 senoner 542
4742 schoenebeck 575 command =
4743 schoenebeck 708
4744 schoenebeck 974 ADD SP add_instruction
4745 schoenebeck 708
4746 schoenebeck 945 / MAP SP map_instruction
4747    
4748     / UNMAP SP unmap_instruction
4749    
4750 schoenebeck 575 / GET SP get_instruction
4751 schoenebeck 708
4752 schoenebeck 575 / CREATE SP create_instruction
4753 schoenebeck 708
4754 schoenebeck 575 / DESTROY SP destroy_instruction
4755 schoenebeck 708
4756    
4757    
4758    
4759 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 85]
4760 schoenebeck 940
4761 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
4762 schoenebeck 708
4763    
4764 schoenebeck 945 / LIST SP list_instruction
4765 schoenebeck 708
4766 schoenebeck 945 / LOAD SP load_instruction
4767    
4768     / REMOVE SP remove_instruction
4769    
4770 schoenebeck 575 / SET SP set_instruction
4771 schoenebeck 708
4772 schoenebeck 575 / SUBSCRIBE SP subscribe_event
4773 schoenebeck 708
4774 schoenebeck 575 / UNSUBSCRIBE SP unsubscribe_event
4775 schoenebeck 708
4776 schoenebeck 575 / SELECT SP text
4777 schoenebeck 708
4778 schoenebeck 945 / RESET SP reset_instruction
4779 schoenebeck 708
4780 schoenebeck 945 / CLEAR SP clear_instruction
4781    
4782 schoenebeck 575 / RESET
4783 schoenebeck 708
4784 schoenebeck 575 / QUIT
4785 senoner 542
4786 schoenebeck 974 add_instruction =
4787    
4788     CHANNEL
4789    
4790     / MIDI_INSTRUMENT_MAP
4791    
4792     / MIDI_INSTRUMENT_MAP SP map_name
4793    
4794 schoenebeck 575 subscribe_event =
4795 schoenebeck 708
4796 iliev 993 AUDIO_OUTPUT_DEVICE_COUNT
4797 schoenebeck 708
4798 iliev 993 / AUDIO_OUTPUT_DEVICE_INFO
4799    
4800     / MIDI_INPUT_DEVICE_COUNT
4801    
4802     / MIDI_INPUT_DEVICE_INFO
4803    
4804     / CHANNEL_COUNT
4805    
4806 schoenebeck 575 / VOICE_COUNT
4807 schoenebeck 708
4808 schoenebeck 575 / STREAM_COUNT
4809 schoenebeck 708
4810 schoenebeck 575 / BUFFER_FILL
4811 schoenebeck 708
4812 iliev 993
4813    
4814    
4815 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 86]
4816 iliev 993
4817 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
4818 iliev 993
4819    
4820 schoenebeck 575 / CHANNEL_INFO
4821 schoenebeck 708
4822 iliev 993 / MIDI_INSTRUMENT_MAP_COUNT
4823    
4824     / MIDI_INSTRUMENT_MAP_INFO
4825    
4826     / MIDI_INSTRUMENT_COUNT
4827    
4828     / MIDI_INSTRUMENT_INFO
4829    
4830 schoenebeck 575 / MISCELLANEOUS
4831 senoner 542
4832 schoenebeck 940 / TOTAL_VOICE_COUNT
4833    
4834 schoenebeck 575 unsubscribe_event =
4835 senoner 542
4836 iliev 993 AUDIO_OUTPUT_DEVICE_COUNT
4837 senoner 542
4838 iliev 993 / AUDIO_OUTPUT_DEVICE_INFO
4839 senoner 542
4840 iliev 993 / MIDI_INPUT_DEVICE_COUNT
4841 senoner 542
4842 iliev 993 / MIDI_INPUT_DEVICE_INFO
4843 senoner 542
4844 iliev 993 / CHANNEL_COUNT
4845 schoenebeck 945
4846 schoenebeck 974 / VOICE_COUNT
4847 schoenebeck 945
4848 schoenebeck 974 / STREAM_COUNT
4849 schoenebeck 945
4850 schoenebeck 974 / BUFFER_FILL
4851 schoenebeck 945
4852 schoenebeck 575 / CHANNEL_INFO
4853 schoenebeck 708
4854 iliev 993 / MIDI_INSTRUMENT_MAP_COUNT
4855    
4856     / MIDI_INSTRUMENT_MAP_INFO
4857    
4858     / MIDI_INSTRUMENT_COUNT
4859    
4860     / MIDI_INSTRUMENT_INFO
4861    
4862 schoenebeck 575 / MISCELLANEOUS
4863    
4864 schoenebeck 940 / TOTAL_VOICE_COUNT
4865 schoenebeck 708
4866 schoenebeck 945 map_instruction =
4867 schoenebeck 708
4868 iliev 993
4869    
4870    
4871 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 87]
4872 iliev 993
4873 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
4874 iliev 993
4875    
4876 schoenebeck 1048 MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP
4877 schoenebeck 945 engine_name SP filename SP instrument_index SP volume_value
4878 schoenebeck 708
4879 schoenebeck 1048 / MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog
4880     SP engine_name SP filename SP instrument_index SP volume_value SP
4881 schoenebeck 945 instr_load_mode
4882 schoenebeck 708
4883 schoenebeck 1048 / MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog
4884     SP engine_name SP filename SP instrument_index SP volume_value SP
4885 schoenebeck 945 entry_name
4886 schoenebeck 708
4887 schoenebeck 1048 / MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog
4888     SP engine_name SP filename SP instrument_index SP volume_value SP
4889 schoenebeck 945 instr_load_mode SP entry_name
4890 schoenebeck 708
4891 schoenebeck 945 unmap_instruction =
4892    
4893 schoenebeck 974 MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog
4894 schoenebeck 945
4895     remove_instruction =
4896    
4897     CHANNEL SP sampler_channel
4898    
4899 schoenebeck 974 / MIDI_INSTRUMENT_MAP SP midi_map
4900    
4901     / MIDI_INSTRUMENT_MAP SP ALL
4902    
4903 schoenebeck 940 get_instruction =
4904 schoenebeck 708
4905 schoenebeck 940 AVAILABLE_ENGINES
4906 schoenebeck 708
4907 schoenebeck 575 / AVAILABLE_MIDI_INPUT_DRIVERS
4908 schoenebeck 708
4909 schoenebeck 575 / MIDI_INPUT_DRIVER SP INFO SP string
4910 schoenebeck 708
4911 schoenebeck 575 / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
4912 schoenebeck 708
4913 schoenebeck 575 / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP
4914     key_val_list
4915 schoenebeck 708
4916 schoenebeck 575 / AVAILABLE_AUDIO_OUTPUT_DRIVERS
4917 schoenebeck 708
4918 schoenebeck 575 / AUDIO_OUTPUT_DRIVER SP INFO SP string
4919 schoenebeck 708
4920 schoenebeck 575 / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
4921 schoenebeck 708
4922 schoenebeck 575 / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP
4923     key_val_list
4924 schoenebeck 708
4925 iliev 993
4926    
4927 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 88]
4928 iliev 993
4929 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
4930 iliev 993
4931    
4932 schoenebeck 575 / AUDIO_OUTPUT_DEVICES
4933 schoenebeck 708
4934 schoenebeck 575 / MIDI_INPUT_DEVICES
4935 schoenebeck 708
4936 schoenebeck 575 / AUDIO_OUTPUT_DEVICE SP INFO SP number
4937 schoenebeck 708
4938 schoenebeck 575 / MIDI_INPUT_DEVICE SP INFO SP number
4939 schoenebeck 708
4940 schoenebeck 575 / MIDI_INPUT_PORT SP INFO SP number SP number
4941 schoenebeck 708
4942 schoenebeck 575 / MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
4943 schoenebeck 708
4944 schoenebeck 575 / AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
4945 schoenebeck 708
4946 schoenebeck 575 / AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP
4947     string
4948 schoenebeck 708
4949 schoenebeck 575 / CHANNELS
4950 schoenebeck 708
4951 schoenebeck 575 / CHANNEL SP INFO SP sampler_channel
4952 schoenebeck 708
4953 schoenebeck 575 / CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
4954 schoenebeck 708
4955 schoenebeck 575 / CHANNEL SP STREAM_COUNT SP sampler_channel
4956 schoenebeck 708
4957 schoenebeck 940 / CHANNEL SP VOICE_COUNT SP sampler_channel
4958 schoenebeck 708
4959 schoenebeck 940 / ENGINE SP INFO SP engine_name
4960 schoenebeck 708
4961 schoenebeck 575 / SERVER SP INFO
4962    
4963 schoenebeck 940 / TOTAL_VOICE_COUNT
4964    
4965     / TOTAL_VOICE_COUNT_MAX
4966    
4967 schoenebeck 974 / MIDI_INSTRUMENTS SP midi_map
4968 schoenebeck 945
4969 schoenebeck 974 / MIDI_INSTRUMENTS SP ALL
4970 schoenebeck 945
4971 schoenebeck 974 / MIDI_INSTRUMENT SP INFO SP midi_map SP midi_bank SP midi_prog
4972 schoenebeck 708
4973 schoenebeck 974 / MIDI_INSTRUMENT_MAPS
4974 schoenebeck 945
4975 schoenebeck 974 / MIDI_INSTRUMENT_MAP SP INFO SP midi_map
4976 schoenebeck 945
4977 schoenebeck 1002 / FX_SENDS SP sampler_channel
4978 schoenebeck 945
4979 iliev 993
4980    
4981    
4982    
4983 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 89]
4984 iliev 993
4985 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
4986 iliev 993
4987    
4988 schoenebeck 1002 / FX_SEND SP INFO SP sampler_channel SP fx_send_id
4989    
4990 schoenebeck 1006 / VOLUME
4991    
4992 schoenebeck 1002 set_instruction =
4993    
4994 schoenebeck 575 AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '='
4995     param_val_list
4996 schoenebeck 708
4997 schoenebeck 575 / AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '='
4998     param_val_list
4999 schoenebeck 708
5000 schoenebeck 575 / MIDI_INPUT_DEVICE_PARAMETER SP number SP string '='
5001     param_val_list
5002 schoenebeck 708
5003 schoenebeck 575 / MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '='
5004     param_val_list
5005 schoenebeck 708
5006 schoenebeck 575 / CHANNEL SP set_chan_instruction
5007 schoenebeck 708
5008 schoenebeck 974 / MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
5009    
5010 schoenebeck 1002 / FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id
5011     SP audio_channel_index SP audio_channel_index
5012    
5013 schoenebeck 1028 / FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP
5014     midi_ctrl
5015    
5016     / FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP
5017     volume_value
5018    
5019 schoenebeck 575 / ECHO SP boolean
5020    
5021 schoenebeck 1006 / VOLUME SP volume_value
5022    
5023 schoenebeck 708 create_instruction =
5024 schoenebeck 575
5025 schoenebeck 708 AUDIO_OUTPUT_DEVICE SP string SP key_val_list
5026 schoenebeck 575
5027 schoenebeck 708 / AUDIO_OUTPUT_DEVICE SP string
5028 schoenebeck 575
5029 schoenebeck 708 / MIDI_INPUT_DEVICE SP string SP key_val_list
5030 senoner 542
5031 schoenebeck 575 / MIDI_INPUT_DEVICE SP string
5032 senoner 542
5033 schoenebeck 1002 / FX_SEND SP sampler_channel SP midi_ctrl
5034    
5035 schoenebeck 1028
5036    
5037    
5038    
5039 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 90]
5040 schoenebeck 1028
5041 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
5042 schoenebeck 1028
5043    
5044 schoenebeck 1002 / FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name
5045    
5046 schoenebeck 945 reset_instruction =
5047    
5048     CHANNEL SP sampler_channel
5049    
5050     clear_instruction =
5051    
5052 schoenebeck 1006 MIDI_INSTRUMENTS SP midi_map
5053    
5054 schoenebeck 974 / MIDI_INSTRUMENTS SP ALL
5055    
5056 schoenebeck 575 destroy_instruction =
5057 schoenebeck 708
5058 schoenebeck 575 AUDIO_OUTPUT_DEVICE SP number
5059 schoenebeck 708
5060 schoenebeck 575 / MIDI_INPUT_DEVICE SP number
5061 senoner 542
5062 schoenebeck 1002 / FX_SEND SP sampler_channel SP fx_send_id
5063    
5064 schoenebeck 575 load_instruction =
5065 schoenebeck 708
5066 schoenebeck 575 INSTRUMENT SP load_instr_args
5067 schoenebeck 708
5068 schoenebeck 945 / ENGINE SP load_engine_args
5069 schoenebeck 940
5070 schoenebeck 945 set_chan_instruction =
5071 schoenebeck 940
5072 schoenebeck 575 AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
5073 schoenebeck 708
5074 schoenebeck 575 / AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index
5075     SP audio_channel_index
5076 schoenebeck 708
5077 schoenebeck 575 / AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
5078 schoenebeck 708
5079 schoenebeck 575 / MIDI_INPUT SP sampler_channel SP device_index SP
5080     midi_input_port_index SP midi_input_channel_index
5081 schoenebeck 708
5082 schoenebeck 575 / MIDI_INPUT_DEVICE SP sampler_channel SP device_index
5083 schoenebeck 708
5084 schoenebeck 575 / MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
5085 schoenebeck 708
5086 schoenebeck 575 / MIDI_INPUT_CHANNEL SP sampler_channel SP
5087     midi_input_channel_index
5088 schoenebeck 708
5089 schoenebeck 575 / MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
5090 schoenebeck 708
5091 senoner 542
5092 schoenebeck 708
5093    
5094 schoenebeck 974
5095 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 91]
5096 schoenebeck 1028
5097 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
5098 schoenebeck 974
5099 schoenebeck 1002
5100 schoenebeck 1028 / VOLUME SP sampler_channel SP volume_value
5101 schoenebeck 1002
5102 schoenebeck 1028 / MUTE SP sampler_channel SP boolean
5103 schoenebeck 1002
5104 schoenebeck 1028 / SOLO SP sampler_channel SP boolean
5105 schoenebeck 1002
5106 schoenebeck 1028 / MIDI_INSTRUMENT_MAP SP sampler_channel SP midi_map
5107 schoenebeck 1002
5108 schoenebeck 1006 / MIDI_INSTRUMENT_MAP SP sampler_channel SP NONE
5109    
5110 schoenebeck 974 / MIDI_INSTRUMENT_MAP SP sampler_channel SP DEFAULT
5111    
5112 schoenebeck 1048 modal_arg =
5113    
5114     /* epsilon (empty argument) */
5115    
5116     / NON_MODAL SP
5117    
5118 schoenebeck 575 key_val_list =
5119 schoenebeck 708
5120 schoenebeck 575 string '=' param_val_list
5121 schoenebeck 708
5122 schoenebeck 575 / key_val_list SP string '=' param_val_list
5123 senoner 542
5124 schoenebeck 575 buffer_size_type =
5125 schoenebeck 708
5126 schoenebeck 575 BYTES
5127 schoenebeck 708
5128 schoenebeck 575 / PERCENTAGE
5129 senoner 542
5130 schoenebeck 575 list_instruction =
5131 schoenebeck 708
5132 schoenebeck 575 AUDIO_OUTPUT_DEVICES
5133 schoenebeck 708
5134 schoenebeck 575 / MIDI_INPUT_DEVICES
5135 schoenebeck 708
5136 schoenebeck 945 / CHANNELS
5137 schoenebeck 708
5138 schoenebeck 945 / AVAILABLE_ENGINES
5139 schoenebeck 708
5140 schoenebeck 974 / AVAILABLE_MIDI_INPUT_DRIVERS
5141 schoenebeck 708
5142 schoenebeck 974 / AVAILABLE_AUDIO_OUTPUT_DRIVERS
5143 senoner 542
5144 schoenebeck 974 / MIDI_INSTRUMENTS SP midi_map
5145 schoenebeck 945
5146 schoenebeck 974 / MIDI_INSTRUMENTS SP ALL
5147 schoenebeck 945
5148 senoner 542
5149 schoenebeck 1002
5150 schoenebeck 708
5151 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 92]
5152    
5153     Internet-Draft LinuxSampler Control Protocol February 2007
5154 schoenebeck 708
5155    
5156 schoenebeck 1048 / MIDI_INSTRUMENT_MAPS
5157 schoenebeck 708
5158 schoenebeck 1048 / FX_SENDS SP sampler_channel
5159 senoner 542
5160 schoenebeck 1048 load_instr_args =
5161 schoenebeck 945
5162 schoenebeck 1028 filename SP instrument_index SP sampler_channel
5163 schoenebeck 1002
5164 schoenebeck 1028 / NON_MODAL SP filename SP instrument_index SP sampler_channel
5165 schoenebeck 1002
5166 schoenebeck 1028 load_engine_args =
5167 schoenebeck 1002
5168 schoenebeck 1028 engine_name SP sampler_channel
5169 schoenebeck 1002
5170 schoenebeck 1006 instr_load_mode =
5171    
5172 schoenebeck 945 ON_DEMAND
5173    
5174     / ON_DEMAND_HOLD
5175    
5176     / PERSISTENT
5177    
5178 schoenebeck 575 device_index =
5179 schoenebeck 708
5180 schoenebeck 575 number
5181 senoner 542
5182 schoenebeck 575 audio_channel_index =
5183 schoenebeck 708
5184 schoenebeck 575 number
5185 senoner 542
5186 schoenebeck 575 audio_output_type_name =
5187 schoenebeck 708
5188 schoenebeck 575 string
5189 senoner 542
5190 schoenebeck 575 midi_input_port_index =
5191 schoenebeck 708
5192 schoenebeck 575 number
5193 senoner 542
5194 schoenebeck 575 midi_input_channel_index =
5195 schoenebeck 708
5196 schoenebeck 575 number
5197 schoenebeck 708
5198 schoenebeck 575 / ALL
5199 senoner 542
5200 schoenebeck 575 midi_input_type_name =
5201 schoenebeck 708
5202 schoenebeck 575 string
5203 senoner 542
5204 schoenebeck 708
5205    
5206 schoenebeck 940
5207 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 93]
5208    
5209     Internet-Draft LinuxSampler Control Protocol February 2007
5210 schoenebeck 940
5211    
5212 schoenebeck 1048 midi_map =
5213 schoenebeck 940
5214 schoenebeck 1048 number
5215 schoenebeck 1002
5216 schoenebeck 1048 midi_bank =
5217 schoenebeck 1002
5218 schoenebeck 1028 number
5219 schoenebeck 1002
5220 schoenebeck 1028 midi_prog =
5221 schoenebeck 1002
5222 schoenebeck 1028 number
5223 schoenebeck 1002
5224 schoenebeck 1028 midi_ctrl =
5225 schoenebeck 1002
5226 schoenebeck 1006 number
5227    
5228 schoenebeck 945 volume_value =
5229 schoenebeck 940
5230 schoenebeck 945 dotnum
5231    
5232 schoenebeck 575 / number
5233 senoner 542
5234 schoenebeck 575 sampler_channel =
5235 schoenebeck 708
5236 schoenebeck 575 number
5237 senoner 542
5238 schoenebeck 575 instrument_index =
5239 schoenebeck 708
5240 schoenebeck 575 number
5241 senoner 542
5242 schoenebeck 1002 fx_send_id =
5243    
5244     number
5245    
5246 schoenebeck 708 engine_name =
5247 senoner 542
5248 schoenebeck 708 string
5249 senoner 542
5250 schoenebeck 708 filename =
5251 senoner 542
5252 schoenebeck 708 stringval
5253 senoner 542
5254 schoenebeck 974 map_name =
5255    
5256     stringval
5257    
5258 schoenebeck 945 entry_name =
5259    
5260    
5261 schoenebeck 1002
5262    
5263 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 94]
5264    
5265     Internet-Draft LinuxSampler Control Protocol February 2007
5266 senoner 542
5267    
5268 schoenebeck 1048 stringval
5269 senoner 542
5270 schoenebeck 1048 fx_send_name =
5271 senoner 542
5272 schoenebeck 1048 stringval
5273 senoner 542
5274 schoenebeck 1028 param_val_list =
5275 schoenebeck 1002
5276 schoenebeck 1028 param_val
5277 schoenebeck 1002
5278 schoenebeck 1028 / param_val_list','param_val
5279 schoenebeck 1002
5280 schoenebeck 1028 param_val =
5281 schoenebeck 1002
5282 schoenebeck 1006 string
5283    
5284 schoenebeck 940 / stringval
5285 senoner 542
5286 schoenebeck 708 / number
5287 senoner 542
5288 schoenebeck 708 / dotnum
5289 senoner 542
5290    
5291    
5292    
5293    
5294    
5295 schoenebeck 575
5296    
5297 iliev 993
5298    
5299    
5300    
5301    
5302    
5303    
5304    
5305    
5306    
5307    
5308    
5309    
5310    
5311    
5312    
5313    
5314    
5315    
5316    
5317 schoenebeck 1002
5318    
5319 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 95]
5320 schoenebeck 940
5321 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
5322 schoenebeck 575
5323    
5324     8. Events
5325 senoner 542
5326     This chapter will describe all currently defined events supported by
5327     LinuxSampler.
5328    
5329 iliev 993 8.1. Number of audio output devices changed
5330 senoner 542
5331 iliev 993 Client may want to be notified when the total number of audio output
5332     devices on the back-end changes by issuing the following command:
5333    
5334     SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT
5335    
5336     Server will start sending the following notification messages:
5337    
5338     "NOTIFY:AUDIO_OUTPUT_DEVICE_COUNT:<devices>"
5339    
5340     where <devices> will be replaced by the new number of audio output
5341     devices.
5342    
5343     8.2. Audio output device's settings changed
5344    
5345     Client may want to be notified when changes were made to audio output
5346     devices on the back-end by issuing the following command:
5347    
5348     SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO
5349    
5350     Server will start sending the following notification messages:
5351    
5352     "NOTIFY:AUDIO_OUTPUT_DEVICE_INFO:<device-id>"
5353    
5354     where <device-id> will be replaced by the numerical ID of the audio
5355     output device, which settings has been changed. The front-end will
5356     have to send the respective command to actually get the audio output
5357     device info. Because these messages will be triggered by LSCP
5358     commands issued by other clients rather than real time events
5359     happening on the server, it is believed that an empty notification
5360     message is sufficient here.
5361    
5362     8.3. Number of MIDI input devices changed
5363    
5364     Client may want to be notified when the total number of MIDI input
5365     devices on the back-end changes by issuing the following command:
5366    
5367     SUBSCRIBE MIDI_INPUT_DEVICE_COUNT
5368    
5369     Server will start sending the following notification messages:
5370    
5371    
5372    
5373    
5374    
5375 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 96]
5376 iliev 993
5377 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
5378 iliev 993
5379    
5380     "NOTIFY:MIDI_INPUT_DEVICE_COUNT:<devices>"
5381    
5382     where <devices> will be replaced by the new number of MIDI input
5383     devices.
5384    
5385     8.4. MIDI input device's settings changed
5386    
5387     Client may want to be notified when changes were made to MIDI input
5388     devices on the back-end by issuing the following command:
5389    
5390     SUBSCRIBE MIDI_INPUT_DEVICE_INFO
5391    
5392     Server will start sending the following notification messages:
5393    
5394     "NOTIFY:MIDI_INPUT_DEVICE_INFO:<device-id>"
5395    
5396     where <device-id> will be replaced by the numerical ID of the MIDI
5397     input device, which settings has been changed. The front-end will
5398     have to send the respective command to actually get the MIDI input
5399     device info. Because these messages will be triggered by LSCP
5400     commands issued by other clients rather than real time events
5401     happening on the server, it is believed that an empty notification
5402     message is sufficient here.
5403    
5404     8.5. Number of sampler channels changed
5405    
5406 senoner 542 Client may want to be notified when the total number of channels on
5407     the back-end changes by issuing the following command:
5408    
5409 schoenebeck 558 SUBSCRIBE CHANNEL_COUNT
5410 senoner 542
5411     Server will start sending the following notification messages:
5412    
5413 schoenebeck 558 "NOTIFY:CHANNEL_COUNT:<channels>"
5414 senoner 542
5415     where <channels> will be replaced by the new number of sampler
5416     channels.
5417    
5418 iliev 993 8.6. Number of active voices changed
5419 senoner 542
5420 schoenebeck 708 Client may want to be notified when the number of voices on the back-
5421     end changes by issuing the following command:
5422 senoner 542
5423     SUBSCRIBE VOICE_COUNT
5424    
5425     Server will start sending the following notification messages:
5426    
5427 iliev 993
5428    
5429    
5430    
5431 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 97]
5432 iliev 993
5433 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
5434 iliev 993
5435    
5436 senoner 542 "NOTIFY:VOICE_COUNT:<sampler-channel> <voices>
5437    
5438     where <sampler-channel> will be replaced by the sampler channel the
5439     voice count change occurred and <voices> by the new number of active
5440     voices on that channel.
5441    
5442 iliev 993 8.7. Number of active disk streams changed
5443 senoner 542
5444     Client may want to be notified when the number of streams on the
5445     back-end changes by issuing the following command: SUBSCRIBE
5446     STREAM_COUNT
5447    
5448     SUBSCRIBE STREAM_COUNT
5449    
5450     Server will start sending the following notification messages:
5451    
5452     "NOTIFY:STREAM_COUNT:<sampler-channel> <streams>"
5453    
5454     where <sampler-channel> will be replaced by the sampler channel the
5455     stream count change occurred and <streams> by the new number of
5456     active disk streams on that channel.
5457    
5458 iliev 993 8.8. Disk stream buffer fill state changed
5459 senoner 542
5460     Client may want to be notified when the buffer fill state of a disk
5461     stream on the back-end changes by issuing the following command:
5462    
5463     SUBSCRIBE BUFFER_FILL
5464    
5465     Server will start sending the following notification messages:
5466    
5467     "NOTIFY:BUFFER_FILL:<sampler-channel> <fill-data>"
5468    
5469     where <sampler-channel> will be replaced by the sampler channel the
5470     buffer fill state change occurred on and <fill-data> will be replaced
5471 schoenebeck 708 by the buffer fill data for this channel as described in
5472     Section 6.4.13 as if the "GET CHANNEL BUFFER_FILL PERCENTAGE"
5473     (Section 6.4.13) command was issued on this channel.
5474 senoner 542
5475 iliev 993 8.9. Channel information changed
5476 senoner 542
5477     Client may want to be notified when changes were made to sampler
5478 schoenebeck 561 channels on the back-end by issuing the following command:
5479 senoner 542
5480 schoenebeck 558 SUBSCRIBE CHANNEL_INFO
5481 senoner 542
5482     Server will start sending the following notification messages:
5483    
5484 iliev 993
5485    
5486    
5487 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 98]
5488 iliev 993
5489 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
5490 iliev 993
5491    
5492 schoenebeck 558 "NOTIFY:CHANNEL_INFO:<sampler-channel>"
5493 senoner 542
5494     where <sampler-channel> will be replaced by the sampler channel the
5495     channel info change occurred. The front-end will have to send the
5496     respective command to actually get the channel info. Because these
5497     messages will be triggered by LSCP commands issued by other clients
5498     rather than real time events happening on the server, it is believed
5499     that an empty notification message is sufficient here.
5500    
5501 iliev 993 8.10. Total number of active voices changed
5502 senoner 542
5503 schoenebeck 940 Client may want to be notified when the total number of voices on the
5504     back-end changes by issuing the following command:
5505 senoner 542
5506 schoenebeck 940 SUBSCRIBE TOTAL_VOICE_COUNT
5507 senoner 542
5508     Server will start sending the following notification messages:
5509    
5510 iliev 993 "NOTIFY:TOTAL_VOICE_COUNT:<voices>
5511 senoner 542
5512 iliev 993 where <voices> will be replaced by the new number of all currently
5513     active voices.
5514 senoner 542
5515 iliev 993 8.11. Number of MIDI instrument maps changed
5516 senoner 542
5517 iliev 993 Client may want to be notified when the number of MIDI instrument
5518     maps on the back-end changes by issuing the following command:
5519 senoner 542
5520 iliev 993 SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT
5521 senoner 542
5522 iliev 993 Server will start sending the following notification messages:
5523    
5524     "NOTIFY:MIDI_INSTRUMENT_MAP_COUNT:<maps>"
5525    
5526     where <maps> will be replaced by the new number of MIDI instrument
5527     maps.
5528    
5529     8.12. MIDI instrument map information changed
5530    
5531     Client may want to be notified when changes were made to MIDI
5532     instrument maps on the back-end by issuing the following command:
5533    
5534     SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO
5535    
5536     Server will start sending the following notification messages:
5537    
5538    
5539    
5540    
5541    
5542    
5543 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 99]
5544 schoenebeck 940
5545 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
5546 senoner 542
5547 schoenebeck 708
5548 iliev 993 "NOTIFY:MIDI_INSTRUMENT_MAP_INFO:<map-id>"
5549 schoenebeck 708
5550 iliev 993 where <map-id> will be replaced by the numerical ID of the MIDI
5551     instrument map, for which information changes occurred. The front-
5552     end will have to send the respective command to actually get the MIDI
5553     instrument map info. Because these messages will be triggered by
5554     LSCP commands issued by other clients rather than real time events
5555     happening on the server, it is believed that an empty notification
5556     message is sufficient here.
5557 schoenebeck 708
5558 iliev 993 8.13. Number of MIDI instruments changed
5559 senoner 542
5560 iliev 993 Client may want to be notified when the number of MIDI instrument
5561     maps on the back-end changes by issuing the following command:
5562    
5563     SUBSCRIBE MIDI_INSTRUMENT_COUNT
5564    
5565     Server will start sending the following notification messages:
5566    
5567     "NOTIFY:MIDI_INSTRUMENT_COUNT:<map-id> <instruments>"
5568    
5569     where <map-id> is the numerical ID of the MIDI instrument map, in
5570     which the nuber of instruments has changed and <instruments> will be
5571     replaced by the new number of MIDI instruments in the specified map.
5572    
5573     8.14. MIDI instrument information changed
5574    
5575     Client may want to be notified when changes were made to MIDI
5576     instruments on the back-end by issuing the following command:
5577    
5578     SUBSCRIBE MIDI_INSTRUMENT_INFO
5579    
5580     Server will start sending the following notification messages:
5581    
5582     "NOTIFY:MIDI_INSTRUMENT_INFO:<map-id> <bank> <program>"
5583    
5584     where <map-id> will be replaced by the numerical ID of the MIDI
5585     instrument map, in which a MIDI instrument is changed. <bank> and
5586     <program> specifies the location of the changed MIDI instrument in
5587     the map. The front-end will have to send the respective command to
5588     actually get the MIDI instrument info. Because these messages will
5589     be triggered by LSCP commands issued by other clients rather than
5590     real time events happening on the server, it is believed that an
5591     empty notification message is sufficient here.
5592    
5593    
5594    
5595    
5596    
5597    
5598    
5599 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 100]
5600 iliev 993
5601 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
5602 iliev 993
5603    
5604     8.15. Miscellaneous and debugging events
5605    
5606 schoenebeck 940 Client may want to be notified of miscellaneous and debugging events
5607     occurring at the server by issuing the following command:
5608 senoner 542
5609 schoenebeck 940 SUBSCRIBE MISCELLANEOUS
5610 senoner 542
5611 schoenebeck 940 Server will start sending the following notification messages:
5612 senoner 542
5613 schoenebeck 940 "NOTIFY:MISCELLANEOUS:<string>"
5614 senoner 542
5615 schoenebeck 940 where <string> will be replaced by whatever data server wants to send
5616     to the client. Client MAY display this data to the user AS IS to
5617     facilitate debugging.
5618 senoner 542
5619    
5620    
5621    
5622    
5623    
5624    
5625    
5626    
5627    
5628    
5629    
5630    
5631    
5632    
5633    
5634    
5635    
5636    
5637    
5638    
5639    
5640    
5641    
5642    
5643    
5644    
5645    
5646    
5647    
5648    
5649    
5650 iliev 993
5651    
5652    
5653    
5654    
5655 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 101]
5656 schoenebeck 940
5657 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
5658 senoner 542
5659    
5660 schoenebeck 575 9. Security Considerations
5661 senoner 542
5662     As there is so far no method of authentication and authorization
5663     defined and so not required for a client applications to succeed to
5664     connect, running LinuxSampler might be a security risk for the host
5665     system the LinuxSampler instance is running on.
5666    
5667    
5668    
5669    
5670    
5671    
5672    
5673    
5674    
5675    
5676    
5677    
5678    
5679    
5680    
5681    
5682    
5683    
5684    
5685    
5686    
5687    
5688    
5689    
5690    
5691    
5692    
5693    
5694    
5695    
5696    
5697    
5698    
5699    
5700    
5701    
5702    
5703    
5704    
5705    
5706    
5707    
5708    
5709    
5710    
5711 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 102]
5712 schoenebeck 940
5713 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
5714 senoner 542
5715    
5716 schoenebeck 575 10. Acknowledgments
5717 senoner 542
5718     This document has benefited greatly from the comments of the
5719     following people, discussed on the LinuxSampler developer's mailing
5720     list:
5721    
5722     Rui Nuno Capela
5723 schoenebeck 708
5724 senoner 542 Vladimir Senkov
5725 schoenebeck 708
5726 senoner 542 Mark Knecht
5727 schoenebeck 708
5728 schoenebeck 561 Grigor Iliev
5729 senoner 542
5730    
5731 schoenebeck 708
5732 senoner 542
5733    
5734 schoenebeck 575
5735    
5736 schoenebeck 940
5737    
5738    
5739    
5740    
5741    
5742    
5743    
5744    
5745    
5746    
5747    
5748    
5749    
5750    
5751    
5752    
5753    
5754    
5755    
5756    
5757    
5758    
5759    
5760 schoenebeck 974
5761    
5762    
5763    
5764    
5765    
5766    
5767 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 103]
5768 schoenebeck 940
5769 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
5770 schoenebeck 940
5771    
5772 schoenebeck 974 11. References
5773 senoner 542
5774 schoenebeck 974 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
5775     Requirement Levels", RFC 2119, 1997.
5776 senoner 542
5777 schoenebeck 974 [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
5778     Specifications", RFC 2234, 1997.
5779 senoner 542
5780 schoenebeck 974 [RFC793] Defense Advanced Research Projects Agency, "TRANSMISSION
5781     CONTROL PROTOCOL", RFC 793, 1981.
5782 senoner 542
5783    
5784    
5785    
5786    
5787    
5788    
5789    
5790    
5791    
5792    
5793    
5794    
5795    
5796    
5797    
5798    
5799 schoenebeck 940
5800    
5801    
5802    
5803    
5804    
5805    
5806    
5807    
5808    
5809    
5810    
5811    
5812    
5813    
5814    
5815    
5816    
5817    
5818    
5819    
5820    
5821    
5822    
5823 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 104]
5824 schoenebeck 940
5825 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
5826 schoenebeck 940
5827    
5828 schoenebeck 974 Author's Address
5829 senoner 542
5830 schoenebeck 974 C. Schoenebeck
5831     Interessengemeinschaft Software Engineering e. V.
5832     Max-Planck-Str. 39
5833     74081 Heilbronn
5834     Germany
5835 senoner 542
5836 schoenebeck 974 Email: schoenebeck at software minus engineering dot org
5837 senoner 542
5838    
5839    
5840    
5841    
5842    
5843    
5844    
5845    
5846    
5847    
5848    
5849    
5850    
5851    
5852    
5853    
5854    
5855    
5856    
5857    
5858    
5859    
5860    
5861    
5862    
5863    
5864    
5865    
5866    
5867    
5868    
5869    
5870    
5871    
5872    
5873    
5874    
5875    
5876    
5877    
5878    
5879 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 105]
5880 schoenebeck 974
5881 schoenebeck 1048 Internet-Draft LinuxSampler Control Protocol February 2007
5882 senoner 542
5883    
5884 schoenebeck 974 Full Copyright Statement
5885 senoner 542
5886 schoenebeck 1028 Copyright (C) The Internet Society (2007).
5887 senoner 542
5888 schoenebeck 974 This document is subject to the rights, licenses and restrictions
5889     contained in BCP 78, and except as set forth therein, the authors
5890     retain all their rights.
5891 senoner 542
5892 schoenebeck 974 This document and the information contained herein are provided on an
5893     "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
5894     OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
5895     ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
5896     INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
5897     INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
5898     WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
5899 senoner 542
5900    
5901 schoenebeck 974 Intellectual Property
5902 senoner 542
5903 schoenebeck 974 The IETF takes no position regarding the validity or scope of any
5904     Intellectual Property Rights or other rights that might be claimed to
5905     pertain to the implementation or use of the technology described in
5906     this document or the extent to which any license under such rights
5907     might or might not be available; nor does it represent that it has
5908     made any independent effort to identify any such rights. Information
5909     on the procedures with respect to rights in RFC documents can be
5910     found in BCP 78 and BCP 79.
5911 senoner 542
5912 schoenebeck 974 Copies of IPR disclosures made to the IETF Secretariat and any
5913     assurances of licenses to be made available, or the result of an
5914     attempt made to obtain a general license or permission for the use of
5915     such proprietary rights by implementers or users of this
5916     specification can be obtained from the IETF on-line IPR repository at
5917     http://www.ietf.org/ipr.
5918 senoner 542
5919 schoenebeck 974 The IETF invites any interested party to bring to its attention any
5920     copyrights, patents or patent applications, or other proprietary
5921     rights that may cover technology that may be required to implement
5922     this standard. Please address the information to the IETF at
5923     ietf-ipr@ietf.org.
5924 senoner 542
5925    
5926 schoenebeck 974 Acknowledgment
5927 senoner 542
5928 schoenebeck 974 Funding for the RFC Editor function is provided by the IETF
5929     Administrative Support Activity (IASA).
5930 senoner 542
5931    
5932 schoenebeck 974
5933    
5934    
5935 schoenebeck 1048 Schoenebeck Expires August 23, 2007 [Page 106]
5936 schoenebeck 940

  ViewVC Help
Powered by ViewVC