/[svn]/web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.txt
ViewVC logotype

Contents of /web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2498 - (show annotations) (download)
Thu Jan 9 22:05:21 2014 UTC (6 years, 1 month ago) by schoenebeck
File MIME type: text/plain
File size: 287575 byte(s)
* New LSCP specs (LSCP 1.6).

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