/[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 1731 - (hide annotations) (download)
Fri May 2 13:03:00 2008 UTC (15 years, 10 months ago) by iliev
File MIME type: text/plain
File size: 233449 byte(s)
- updating the LSCP spec

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