/[svn]/web/trunk/www.linuxsampler.org/api/lscp-1.7.txt
ViewVC logotype

Contents of /web/trunk/www.linuxsampler.org/api/lscp-1.7.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2791 - (show annotations) (download)
Wed Jul 15 21:41:19 2015 UTC (8 years, 8 months ago) by schoenebeck
File MIME type: text/plain
File size: 288834 byte(s)
* Updated LSCP spec document (v1.7 for LinuxSampler release 2.0.0).

1
2
3
4 LinuxSampler Developers C. Schoenebeck
5 Internet-Draft LinuxSampler.org
6 Intended status: Standards Track July 15, 2015
7 Expires: January 16, 2016
8
9
10 LinuxSampler Control Protocol
11 LSCP 1.7
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 January 16, 2016.
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55 Schoenebeck Expires January 16, 2016 [Page 1]
56
57 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 2]
112
113 Internet-Draft LinuxSampler Control Protocol July 2015
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 . . . . . . . 55
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 . . . . . . . . . . . . . 57
130 6.4.16. Setting audio output channel . . . . . . . . . . . . 58
131 6.4.17. Add MIDI input to sampler channel . . . . . . . . . 59
132 6.4.18. Remove MIDI input(s) from sampler channel . . . . . 60
133 6.4.19. Getting all MIDI inputs of a sampler channel . . . . 61
134 6.4.20. Setting MIDI input device . . . . . . . . . . . . . 62
135 6.4.21. Setting MIDI input type . . . . . . . . . . . . . . 63
136 6.4.22. Setting MIDI input port . . . . . . . . . . . . . . 64
137 6.4.23. Setting MIDI input channel . . . . . . . . . . . . . 65
138 6.4.24. Setting channel volume . . . . . . . . . . . . . . . 66
139 6.4.25. Muting a sampler channel . . . . . . . . . . . . . . 66
140 6.4.26. Soloing a sampler channel . . . . . . . . . . . . . 67
141 6.4.27. Assigning a MIDI instrument map to a sampler
142 channel . . . . . . . . . . . . . . . . . . . . . . 68
143 6.4.28. Adding an effect send to a sampler channel . . . . . 69
144 6.4.29. Removing an effect send from a sampler channel . . . 70
145 6.4.30. Getting amount of effect sends on a sampler
146 channel . . . . . . . . . . . . . . . . . . . . . . 71
147 6.4.31. Listing all effect sends on a sampler channel . . . 71
148 6.4.32. Getting effect send information . . . . . . . . . . 72
149 6.4.33. Changing effect send's name . . . . . . . . . . . . 74
150 6.4.34. Altering effect send's audio routing . . . . . . . . 75
151 6.4.35. Assigning destination effect to an effect send . . . 76
152 6.4.36. Removing destination effect from an effect send . . 77
153 6.4.37. Altering effect send's MIDI controller . . . . . . . 77
154 6.4.38. Altering effect send's send level . . . . . . . . . 78
155 6.4.39. Sending MIDI messages to sampler channel . . . . . . 79
156 6.4.40. Resetting a sampler channel . . . . . . . . . . . . 80
157 6.5. Controlling connection . . . . . . . . . . . . . . . . . 81
158 6.5.1. Register front-end for receiving event messages . . 81
159 6.5.2. Unregister front-end for not receiving event
160 messages . . . . . . . . . . . . . . . . . . . . . . 81
161 6.5.3. Enable or disable echo of commands . . . . . . . . . 82
162 6.5.4. Close client connection . . . . . . . . . . . . . . 83
163 6.6. Global commands . . . . . . . . . . . . . . . . . . . . . 83
164
165
166
167 Schoenebeck Expires January 16, 2016 [Page 3]
168
169 Internet-Draft LinuxSampler Control Protocol July 2015
170
171
172 6.6.1. Current number of active voices . . . . . . . . . . 83
173 6.6.2. Maximum amount of active voices . . . . . . . . . . 83
174 6.6.3. Current number of active disk streams . . . . . . . 83
175 6.6.4. Reset sampler . . . . . . . . . . . . . . . . . . . 84
176 6.6.5. General sampler informations . . . . . . . . . . . . 84
177 6.6.6. Getting global volume attenuation . . . . . . . . . 85
178 6.6.7. Setting global volume attenuation . . . . . . . . . 86
179 6.6.8. Getting global voice limit . . . . . . . . . . . . . 86
180 6.6.9. Setting global voice limit . . . . . . . . . . . . . 87
181 6.6.10. Getting global disk stream limit . . . . . . . . . . 87
182 6.6.11. Setting global disk stream limit . . . . . . . . . . 88
183 6.7. MIDI Instrument Mapping . . . . . . . . . . . . . . . . . 88
184 6.7.1. Create a new MIDI instrument map . . . . . . . . . . 89
185 6.7.2. Delete one particular or all MIDI instrument maps . 90
186 6.7.3. Get amount of existing MIDI instrument maps . . . . 91
187 6.7.4. Getting all created MIDI instrument maps . . . . . . 91
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 . . . 93
191 6.7.8. Getting amount of MIDI instrument map entries . . . 96
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 . . . . 97
195 6.7.11. Get current settings of MIDI instrument map entry . 98
196 6.7.12. Clear MIDI instrument map . . . . . . . . . . . . . 99
197 6.8. Managing Instruments Database . . . . . . . . . . . . . . 100
198 6.8.1. Creating a new instrument directory . . . . . . . . 100
199 6.8.2. Deleting an instrument directory . . . . . . . . . . 101
200 6.8.3. Getting amount of instrument directories . . . . . . 102
201 6.8.4. Listing all directories in specific directory . . . 102
202 6.8.5. Getting instrument directory information . . . . . . 103
203 6.8.6. Renaming an instrument directory . . . . . . . . . . 104
204 6.8.7. Moving an instrument directory . . . . . . . . . . . 104
205 6.8.8. Copying instrument directories . . . . . . . . . . . 105
206 6.8.9. Changing the description of directory . . . . . . . 106
207 6.8.10. Finding directories . . . . . . . . . . . . . . . . 106
208 6.8.11. Adding instruments to the instruments database . . . 108
209 6.8.12. Removing an instrument . . . . . . . . . . . . . . . 109
210 6.8.13. Getting amount of instruments . . . . . . . . . . . 110
211 6.8.14. Listing all instruments in specific directory . . . 111
212 6.8.15. Getting instrument information . . . . . . . . . . . 111
213 6.8.16. Renaming an instrument . . . . . . . . . . . . . . . 114
214 6.8.17. Moving an instrument . . . . . . . . . . . . . . . . 114
215 6.8.18. Copying instruments . . . . . . . . . . . . . . . . 115
216 6.8.19. Changing the description of instrument . . . . . . . 115
217 6.8.20. Finding instruments . . . . . . . . . . . . . . . . 116
218 6.8.21. Getting job status information . . . . . . . . . . . 118
219 6.8.22. Formatting the instruments database . . . . . . . . 120
220
221
222
223 Schoenebeck Expires January 16, 2016 [Page 4]
224
225 Internet-Draft LinuxSampler Control Protocol July 2015
226
227
228 6.8.23. Checking for lost instrument files . . . . . . . . . 120
229 6.8.24. Replacing an instrument file . . . . . . . . . . . . 121
230 6.9. Editing Instruments . . . . . . . . . . . . . . . . . . . 121
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 . . . . . 123
235 6.10.2. Retrieving all instruments of a file . . . . . . . . 123
236 6.10.3. Retrieving informations about one instrument in a
237 file . . . . . . . . . . . . . . . . . . . . . . . . 124
238 6.11. Managing Effects . . . . . . . . . . . . . . . . . . . . 126
239 6.11.1. Retrieve amount of available effects . . . . . . . . 126
240 6.11.2. Get list of available effects . . . . . . . . . . . 127
241 6.11.3. Retrieving general information about an effect . . . 127
242 6.11.4. Creating an instance of an effect by its portable
243 ID . . . . . . . . . . . . . . . . . . . . . . . . . 128
244 6.11.5. Creating an instance of an effect by its
245 numerical ID . . . . . . . . . . . . . . . . . . . . 129
246 6.11.6. Destroy an effect instance . . . . . . . . . . . . . 130
247 6.11.7. Retrieve amount of effect instances . . . . . . . . 131
248 6.11.8. Get list of effect instances . . . . . . . . . . . . 131
249 6.11.9. Retrieving current information about an effect
250 instance . . . . . . . . . . . . . . . . . . . . . . 132
251 6.11.10. Retrieving information about an effect parameter . . 133
252 6.11.11. Altering an effect parameter . . . . . . . . . . . . 135
253 6.11.12. Retrieve amount of send effect chains . . . . . . . 135
254 6.11.13. Retrieve list of send effect chains . . . . . . . . 136
255 6.11.14. Add send effect chain . . . . . . . . . . . . . . . 136
256 6.11.15. Remove send effect chain . . . . . . . . . . . . . . 137
257 6.11.16. Retrieving information about a send effect chain . . 138
258 6.11.17. Append effect instance to a send effect chain . . . 139
259 6.11.18. Insert effect instance to a send effect chain . . . 139
260 6.11.19. Remove effect instance from send effect chain . . . 140
261 7. Command Syntax . . . . . . . . . . . . . . . . . . . . . . . 142
262 7.1. Character Set and Escape Sequences . . . . . . . . . . . 159
263 8. Events . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
264 8.1. Number of audio output devices changed . . . . . . . . . 164
265 8.2. Audio output device's settings changed . . . . . . . . . 164
266 8.3. Number of MIDI input devices changed . . . . . . . . . . 164
267 8.4. MIDI input device's settings changed . . . . . . . . . . 165
268 8.5. Number of sampler channels changed . . . . . . . . . . . 165
269 8.6. MIDI data on a sampler channel arrived . . . . . . . . . 165
270 8.7. MIDI data on a MIDI input device arrived . . . . . . . . 166
271 8.8. Number of active voices changed . . . . . . . . . . . . . 166
272 8.9. Number of active disk streams changed . . . . . . . . . . 167
273 8.10. Disk stream buffer fill state changed . . . . . . . . . . 167
274 8.11. Channel information changed . . . . . . . . . . . . . . . 167
275 8.12. Number of effect sends changed . . . . . . . . . . . . . 168
276
277
278
279 Schoenebeck Expires January 16, 2016 [Page 5]
280
281 Internet-Draft LinuxSampler Control Protocol July 2015
282
283
284 8.13. Effect send information changed . . . . . . . . . . . . . 168
285 8.14. Total number of active voices changed . . . . . . . . . . 169
286 8.15. Total number of active disk streams changed . . . . . . . 169
287 8.16. Number of MIDI instrument maps changed . . . . . . . . . 169
288 8.17. MIDI instrument map information changed . . . . . . . . . 169
289 8.18. Number of MIDI instruments changed . . . . . . . . . . . 170
290 8.19. MIDI instrument information changed . . . . . . . . . . . 170
291 8.20. Global settings changed . . . . . . . . . . . . . . . . . 171
292 8.21. Number of database instrument directories changed . . . . 171
293 8.22. Database instrument directory information changed . . . . 171
294 8.23. Number of database instruments changed . . . . . . . . . 172
295 8.24. Database instrument information changed . . . . . . . . . 172
296 8.25. Database job status information changed . . . . . . . . . 173
297 8.26. Number of effect instances changed . . . . . . . . . . . 173
298 8.27. Effect instance information changed . . . . . . . . . . . 174
299 8.28. Number of send effect chains changed . . . . . . . . . . 174
300 8.29. Send effect chain information changed . . . . . . . . . . 174
301 8.30. Miscellaneous and debugging events . . . . . . . . . . . 175
302 9. Security Considerations . . . . . . . . . . . . . . . . . . . 176
303 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 177
304 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 178
305 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 179
306 Intellectual Property and Copyright Statements . . . . . . . . . 180
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 January 16, 2016 [Page 6]
336
337 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 7]
392
393 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 8]
448
449 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 9]
504
505 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 10]
560
561 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 11]
616
617 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 12]
672
673 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 13]
728
729 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 14]
784
785 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 15]
840
841 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 16]
896
897 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 17]
952
953 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 18]
1008
1009 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 19]
1064
1065 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 20]
1120
1121 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 21]
1176
1177 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 22]
1232
1233 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 23]
1288
1289 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 24]
1344
1345 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 25]
1400
1401 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 26]
1456
1457 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 27]
1512
1513 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 28]
1568
1569 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 29]
1624
1625 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 30]
1680
1681 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 31]
1736
1737 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 32]
1792
1793 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 33]
1848
1849 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 34]
1904
1905 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 35]
1960
1961 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 36]
2016
2017 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 37]
2072
2073 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 38]
2128
2129 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 39]
2184
2185 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 40]
2240
2241 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 41]
2296
2297 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 42]
2352
2353 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 43]
2408
2409 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 44]
2464
2465 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 45]
2520
2521 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 46]
2576
2577 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 47]
2632
2633 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 48]
2688
2689 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 49]
2744
2745 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 50]
2800
2801 Internet-Draft LinuxSampler Control Protocol July 2015
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 January 16, 2016 [Page 51]
2856
2857 Internet-Draft LinuxSampler Control Protocol July 2015
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 DEPRECATED: THIS FIELD WILL DISAPPEAR!
2889
2890 numerical ID of the MIDI input device which is currently
2891 connected to this sampler channel to deliver MIDI input
2892 commands, "-1" if there's no device connected to this
2893 sampler channel
2894
2895 Should not be used anymore as of LSCP v1.6 and younger.
2896 This field is currently only preserved for backward
2897 compatibility.
2898
2899 This field a relict from times where only one MIDI input per
2900 sampler channel was allowed. Use "GET CHANNEL MIDI_INPUTS"
2901 (Section 6.4.19) instead.
2902
2903 MIDI_INPUT_PORT -
2904
2905 DEPRECATED: THIS FIELD WILL DISAPPEAR!
2906
2907
2908
2909
2910
2911 Schoenebeck Expires January 16, 2016 [Page 52]
2912
2913 Internet-Draft LinuxSampler Control Protocol July 2015
2914
2915
2916 port number of the MIDI input device (in case a MIDI device
2917 was already assigned to the sampler channel)
2918
2919 Should not be used anymore as of LSCP v1.6 and younger.
2920 This field is currently only preserved for backward
2921 compatibility.
2922
2923 This field a relict from times where only one MIDI input per
2924 sampler channel was allowed. Use "GET CHANNEL MIDI_INPUTS"
2925 (Section 6.4.19) instead.
2926
2927 MIDI_INPUT_CHANNEL -
2928
2929 the MIDI input channel number this sampler channel should
2930 listen to or "ALL" to listen on all MIDI channels
2931
2932 VOLUME -
2933
2934 optionally dotted number for the channel volume factor
2935 (where a value < 1.0 means attenuation and a value > 1.0
2936 means amplification)
2937
2938 MUTE -
2939
2940 Determines whether the channel is muted, "true" if the
2941 channel is muted, "false" if the channel is not muted, and
2942 "MUTED_BY_SOLO" if the channel is muted because of the
2943 presence of a solo channel and will be unmuted when there
2944 are no solo channels left
2945
2946 SOLO -
2947
2948 Determines whether this is a solo channel, "true" if the
2949 channel is a solo channel; "false" otherwise
2950
2951 MIDI_INSTRUMENT_MAP -
2952
2953 Determines to which MIDI instrument map this sampler channel
2954 is assigned to. Read chapter "SET CHANNEL
2955 MIDI_INSTRUMENT_MAP" (Section 6.4.27) for a list of possible
2956 values.
2957
2958 The mentioned fields above don't have to be in particular order.
2959
2960 Example:
2961
2962
2963
2964
2965
2966
2967 Schoenebeck Expires January 16, 2016 [Page 53]
2968
2969 Internet-Draft LinuxSampler Control Protocol July 2015
2970
2971
2972 C: "GET CHANNEL INFO 34"
2973
2974 S: "ENGINE_NAME: gig"
2975
2976 "VOLUME: 1.0"
2977
2978 "AUDIO_OUTPUT_DEVICE: 0"
2979
2980 "AUDIO_OUTPUT_CHANNELS: 2"
2981
2982 "AUDIO_OUTPUT_ROUTING: 0,1"
2983
2984 "INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"
2985
2986 "INSTRUMENT_NR: 0"
2987
2988 "INSTRUMENT_NAME: Fazioli Piano"
2989
2990 "INSTRUMENT_STATUS: 100"
2991
2992 "MIDI_INPUT_DEVICE: 0"
2993
2994 "MIDI_INPUT_PORT: 0"
2995
2996 "MIDI_INPUT_CHANNEL: 5"
2997
2998 "VOLUME: 1.0"
2999
3000 "MUTE: false"
3001
3002 "SOLO: false"
3003
3004 "MIDI_INSTRUMENT_MAP: NONE"
3005
3006 "."
3007
3008 6.4.11. Current number of active voices
3009
3010 The front-end can ask for the current number of active voices on a
3011 sampler channel by sending the following command:
3012
3013 GET CHANNEL VOICE_COUNT <sampler-channel>
3014
3015 Where <sampler-channel> is the sampler channel number the front-end
3016 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
3017 "LIST CHANNELS" (Section 6.4.4) command.
3018
3019 Possible Answers:
3020
3021
3022
3023 Schoenebeck Expires January 16, 2016 [Page 54]
3024
3025 Internet-Draft LinuxSampler Control Protocol July 2015
3026
3027
3028 LinuxSampler will answer by returning the number of active voices
3029 on that channel.
3030
3031 Example:
3032
3033
3034
3035 6.4.12. Current number of active disk streams
3036
3037 The front-end can ask for the current number of active disk streams
3038 on a sampler channel by sending the following command:
3039
3040 GET CHANNEL STREAM_COUNT <sampler-channel>
3041
3042 Where <sampler-channel> is the sampler channel number the front-end
3043 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
3044 "LIST CHANNELS" (Section 6.4.4) command.
3045
3046 Possible Answers:
3047
3048 LinuxSampler will answer by returning the number of active disk
3049 streams on that channel in case the engine supports disk
3050 streaming, if the engine doesn't support disk streaming it will
3051 return "NA" for not available.
3052
3053 Example:
3054
3055
3056
3057 6.4.13. Current fill state of disk stream buffers
3058
3059 The front-end can ask for the current fill state of all disk streams
3060 on a sampler channel by sending the following command:
3061
3062 GET CHANNEL BUFFER_FILL BYTES <sampler-channel>
3063
3064 to get the fill state in bytes or
3065
3066 GET CHANNEL BUFFER_FILL PERCENTAGE <sampler-channel>
3067
3068 to get the fill state in percent, where <sampler-channel> is the
3069 sampler channel number the front-end is interested in as returned by
3070 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3071 command.
3072
3073 Possible Answers:
3074
3075
3076
3077
3078
3079 Schoenebeck Expires January 16, 2016 [Page 55]
3080
3081 Internet-Draft LinuxSampler Control Protocol July 2015
3082
3083
3084 LinuxSampler will either answer by returning a comma separated
3085 string with the fill state of all disk stream buffers on that
3086 channel or an empty line if there are no active disk streams or
3087 "NA" for *not available* in case the engine which is deployed
3088 doesn't support disk streaming. Each entry in the answer list
3089 will begin with the stream's ID in brackets followed by the
3090 numerical representation of the fill size (either in bytes or
3091 percentage). Note: due to efficiency reasons the fill states in
3092 the response are not in particular order, thus the front-end has
3093 to sort them by itself if necessary.
3094
3095 Examples:
3096
3097 C: "GET CHANNEL BUFFER_FILL BYTES 4"
3098
3099 S: "[115]420500,[116]510300,[75]110000,[120]230700"
3100
3101 C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
3102
3103 S: "[115]90%,[116]98%,[75]40%,[120]62%"
3104
3105 C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
3106
3107 S: ""
3108
3109 6.4.14. Setting audio output device
3110
3111 The front-end can set the audio output device on a specific sampler
3112 channel by sending the following command:
3113
3114 SET CHANNEL AUDIO_OUTPUT_DEVICE <sampler-channel>
3115 <audio-device-id>
3116
3117 Where <sampler-channel> is the respective sampler channel number as
3118 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3119 (Section 6.4.4) command and <audio-device-id> is the numerical ID of
3120 the audio output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
3121 (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
3122 command.
3123
3124 Possible Answers:
3125
3126 "OK" -
3127
3128 on success
3129
3130
3131
3132
3133
3134
3135 Schoenebeck Expires January 16, 2016 [Page 56]
3136
3137 Internet-Draft LinuxSampler Control Protocol July 2015
3138
3139
3140 "WRN:<warning-code>:<warning-message>" -
3141
3142 if audio output device was set, but there are noteworthy
3143 issue(s) related, providing an appropriate warning code and
3144 warning message
3145
3146 "ERR:<error-code>:<error-message>" -
3147
3148 in case it failed, providing an appropriate error code and
3149 error message
3150
3151 Examples:
3152
3153
3154
3155 6.4.15. Setting audio output type
3156
3157 DEPRECATED: THIS COMMAND WILL DISAPPEAR!
3158
3159 The front-end can alter the audio output type on a specific sampler
3160 channel by sending the following command:
3161
3162 SET CHANNEL AUDIO_OUTPUT_TYPE <sampler-channel> <audio-output-
3163 type>
3164
3165 Where <audio-output-type> is currently either "ALSA" or "JACK" and
3166 <sampler-channel> is the respective sampler channel number.
3167
3168 Possible Answers:
3169
3170 "OK" -
3171
3172 on success
3173
3174 "WRN:<warning-code>:<warning-message>" -
3175
3176 if audio output type was set, but there are noteworthy issue(s)
3177 related, providing an appropriate warning code and warning
3178 message
3179
3180 "ERR:<error-code>:<error-message>" -
3181
3182 in case it failed, providing an appropriate error code and
3183 error message
3184
3185 Examples:
3186
3187
3188
3189
3190
3191 Schoenebeck Expires January 16, 2016 [Page 57]
3192
3193 Internet-Draft LinuxSampler Control Protocol July 2015
3194
3195
3196
3197
3198 Deprecated:
3199
3200 Should not be used anymore. This command is currently only
3201 preserved for backward compatibility.
3202
3203 This command is a relict from times where there was no
3204 sophisticated driver management yet. Use "CREATE
3205 AUDIO_OUTPUT_DEVICE" (Section 6.2.5) and "SET CHANNEL
3206 AUDIO_OUTPUT_DEVICE" (Section 6.4.14) instead.
3207
3208 6.4.16. Setting audio output channel
3209
3210 The front-end can alter the audio output channel on a specific
3211 sampler channel by sending the following command:
3212
3213 SET CHANNEL AUDIO_OUTPUT_CHANNEL <sampler-chan> <audio-out>
3214 <audio-in>
3215
3216 Where <sampler-chan> is the sampler channel number as returned by the
3217 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3218 command, <audio-out> is the numerical ID of the sampler channel's
3219 audio output channel which should be rerouted and <audio-in> is the
3220 numerical ID of the audio channel of the selected audio output device
3221 where <audio-out> should be routed to.
3222
3223 Possible Answers:
3224
3225 "OK" -
3226
3227 on success
3228
3229 "WRN:<warning-code>:<warning-message>" -
3230
3231 if audio output channel was set, but there are noteworthy
3232 issue(s) related, providing an appropriate warning code and
3233 warning message
3234
3235 "ERR:<error-code>:<error-message>" -
3236
3237 in case it failed, providing an appropriate error code and
3238 error message
3239
3240 Examples:
3241
3242
3243
3244
3245
3246
3247 Schoenebeck Expires January 16, 2016 [Page 58]
3248
3249 Internet-Draft LinuxSampler Control Protocol July 2015
3250
3251
3252
3253
3254 6.4.17. Add MIDI input to sampler channel
3255
3256 The front-end can add a MIDI input on a specific sampler channel by
3257 sending the following command:
3258
3259 ADD CHANNEL MIDI_INPUT <sampler-channel> <midi-device-id> [<midi-
3260 input-port>]
3261
3262 Where <sampler-channel> is the sampler channel number as returned by
3263 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3264 command and <midi-device-id> is the numerical ID of the MIDI input
3265 device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5)
3266 or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command, and <midi-
3267 input-port> is an optional MIDI input port number of that MIDI input
3268 device. If <midi-input-port> is omitted, then the MIDI input
3269 device's first port (port number 0) is used.
3270
3271 Possible Answers:
3272
3273 "OK" -
3274
3275 on success
3276
3277 "WRN:<warning-code>:<warning-message>" -
3278
3279 if MIDI input port was connected, but there are noteworthy
3280 issue(s) related, providing an appropriate warning code and
3281 warning message
3282
3283 "ERR:<error-code>:<error-message>" -
3284
3285 in case it failed, providing an appropriate error code and
3286 error message
3287
3288 Examples:
3289
3290 C: "ADD CHANNEL MIDI_INPUT 0 0"
3291
3292 S: "OK"
3293
3294 C: "ADD CHANNEL MIDI_INPUT 1 0"
3295
3296 S: "OK"
3297
3298 C: "ADD CHANNEL MIDI_INPUT 1 1 1"
3299
3300
3301
3302
3303 Schoenebeck Expires January 16, 2016 [Page 59]
3304
3305 Internet-Draft LinuxSampler Control Protocol July 2015
3306
3307
3308 S: "OK"
3309
3310 C: "ADD CHANNEL MIDI_INPUT 1 2 0"
3311
3312 S: "OK"
3313
3314 Since:
3315
3316 Introduced with LSCP v1.6
3317
3318 6.4.18. Remove MIDI input(s) from sampler channel
3319
3320 The front-end can remove one ore more MIDI input(s) on a specific
3321 sampler channel by sending the following command:
3322
3323 REMOVE CHANNEL MIDI_INPUT <sampler-channel> [<midi-device-id>
3324 [<midi-input-port>]]
3325
3326 Where <sampler-channel> is the sampler channel number as returned by
3327 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3328 command and <midi-device-id> and <midi-input-port> are optional
3329 numerical IDs defining the MIDI input device and one of its MIDI
3330 ports as returned by the "LIST CHANNEL MIDI_INPUTS" (Section 6.4.19)
3331 command.
3332
3333 If <midi-input-port> is omitted, then all MIDI input ports of <midi-
3334 device-id> are disconnected from this sampler channel.
3335
3336 If both, <midi-device-id> and <midi-input-port> are omitted, then all
3337 MIDI input ports currently connected to this sampler channel are
3338 disconnected from this sampler channel.
3339
3340 Possible Answers:
3341
3342 "OK" -
3343
3344 on success
3345
3346 "WRN:<warning-code>:<warning-message>" -
3347
3348 if MIDI input porst were disconnected, but there are noteworthy
3349 issue(s) related, providing an appropriate warning code and
3350 warning message
3351
3352 "ERR:<error-code>:<error-message>" -
3353
3354 in case it failed, providing an appropriate error code and
3355 error message
3356
3357
3358
3359 Schoenebeck Expires January 16, 2016 [Page 60]
3360
3361 Internet-Draft LinuxSampler Control Protocol July 2015
3362
3363
3364 Examples:
3365
3366 C: "REMOVE CHANNEL MIDI_INPUT 0"
3367
3368 S: "OK"
3369
3370 C: "REMOVE CHANNEL MIDI_INPUT 1"
3371
3372 S: "OK"
3373
3374 C: "REMOVE CHANNEL MIDI_INPUT 1 2 0"
3375
3376 S: "OK"
3377
3378 Since:
3379
3380 Introduced with LSCP v1.6
3381
3382 6.4.19. Getting all MIDI inputs of a sampler channel
3383
3384 The front-end can query a list of all currently connected MIDI inputs
3385 of a certain sampler channel by sending the following command:
3386
3387 LIST CHANNEL MIDI_INPUTS <sampler-channel>
3388
3389 Where <sampler-channel> is the sampler channel number as returned by
3390 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3391 command.
3392
3393 Possible Answers:
3394
3395 The sampler will answer by sending a comma separated list of MIDI
3396 input device ID - MIDI input port number pairs, where each pair is
3397 encapsulated into curly braces. The list is returned in one
3398 single line. The MIDI input device ID corresponds to the number
3399 returned by "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) and the port
3400 number is the index of the respective MIDI port of that MIDI input
3401 device.
3402
3403 Example:
3404
3405 C: "LIST CHANNEL MIDI_INPUTS 0"
3406
3407 S: "{0,0},{1,3},{2,0}"
3408
3409 Since:
3410
3411
3412
3413
3414
3415 Schoenebeck Expires January 16, 2016 [Page 61]
3416
3417 Internet-Draft LinuxSampler Control Protocol July 2015
3418
3419
3420 Introduced with LSCP v1.6
3421
3422 6.4.20. Setting MIDI input device
3423
3424 DEPRECATED: THIS COMMAND WILL DISAPPEAR!
3425
3426 The front-end can set the MIDI input device on a specific sampler
3427 channel by sending the following command:
3428
3429 SET CHANNEL MIDI_INPUT_DEVICE <sampler-channel> <midi-device-id>
3430
3431 Where <sampler-channel> is the sampler channel number as returned by
3432 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3433 command and <midi-device-id> is the numerical ID of the MIDI input
3434 device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5)
3435 or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command.
3436
3437 If more than 1 MIDI inputs are currently connected to this sampler
3438 channel: Sending this command will disconnect ALL currently connected
3439 MIDI input ports connected to this sampler channel before
3440 establishing the new MIDI input connection. So this command does NOT
3441 add the connection, it replaces all existing ones instead. This
3442 behavior is due to preserving full behavior backward compatibility.
3443
3444 Possible Answers:
3445
3446 "OK" -
3447
3448 on success
3449
3450 "WRN:<warning-code>:<warning-message>" -
3451
3452 if MIDI input device was set, but there are noteworthy issue(s)
3453 related, providing an appropriate warning code and warning
3454 message
3455
3456 "ERR:<error-code>:<error-message>" -
3457
3458 in case it failed, providing an appropriate error code and
3459 error message
3460
3461 Examples:
3462
3463
3464
3465 Deprecated:
3466
3467
3468
3469
3470
3471 Schoenebeck Expires January 16, 2016 [Page 62]
3472
3473 Internet-Draft LinuxSampler Control Protocol July 2015
3474
3475
3476 Should not be used anymore as of LSCP v1.6 and younger. This
3477 command is currently only preserved for backward compatibility.
3478
3479 This command is a relict from times where only one MIDI input per
3480 sampler channel was allowed. Use "ADD CHANNEL MIDI_INPUT"
3481 (Section 6.4.17) and "REMOVE CHANNEL MIDI_INPUT" (Section 6.4.18)
3482 instead.
3483
3484 6.4.21. Setting MIDI input type
3485
3486 DEPRECATED: THIS COMMAND WILL DISAPPEAR!
3487
3488 The front-end can alter the MIDI input type on a specific sampler
3489 channel by sending the following command:
3490
3491 SET CHANNEL MIDI_INPUT_TYPE <sampler-channel> <midi-input-type>
3492
3493 Where <midi-input-type> is currently only "ALSA" and <sampler-
3494 channel> is the respective sampler channel number.
3495
3496 If more than 1 MIDI inputs are currently connected to this sampler
3497 channel: Sending this command will disconnect ALL currently connected
3498 MIDI input ports connected to this sampler channel before
3499 establishing the new MIDI input connection. So this command does NOT
3500 add the connection, it replaces all existing ones instead. This
3501 behavior is due to preserving full behavior backward compatibility.
3502
3503 Possible Answers:
3504
3505 "OK" -
3506
3507 on success
3508
3509 "WRN:<warning-code>:<warning-message>" -
3510
3511 if MIDI input type was set, but there are noteworthy issue(s)
3512 related, providing an appropriate warning code and warning
3513 message
3514
3515 "ERR:<error-code>:<error-message>" -
3516
3517 in case it failed, providing an appropriate error code and
3518 error message
3519
3520 Examples:
3521
3522
3523
3524
3525
3526
3527 Schoenebeck Expires January 16, 2016 [Page 63]
3528
3529 Internet-Draft LinuxSampler Control Protocol July 2015
3530
3531
3532
3533
3534 Deprecated:
3535
3536 Should not be used anymore. This command is currently only
3537 preserved for backward compatibility.
3538
3539 This command is a relict from times where only 1 MIDI input per
3540 sampler channels was allowed and where no sophisticated driver
3541 management existed yet. Use "ADD CHANNEL MIDI_INPUT"
3542 (Section 6.4.17) and "REMOVE CHANNEL MIDI_INPUT" (Section 6.4.18)
3543 instead.
3544
3545 6.4.22. Setting MIDI input port
3546
3547 DEPRECATED: THIS COMMAND WILL DISAPPEAR!
3548
3549 The front-end can alter the MIDI input port on a specific sampler
3550 channel by sending the following command:
3551
3552 SET CHANNEL MIDI_INPUT_PORT <sampler-channel> <midi-input-port>
3553
3554 Where <midi-input-port> is a MIDI input port number of the MIDI input
3555 device connected to the sampler channel given by <sampler-channel>.
3556
3557 If more than 1 MIDI inputs are currently connected to this sampler
3558 channel: Sending this command will switch the connection of the first
3559 (and only the first) MIDI input port currently being connected to
3560 this sampler channel, to another port of the same MIDI input device.
3561 Or in other words: the first MIDI input port currently connected to
3562 this sampler channel will be disconnected, and the requested other
3563 port of its MIDI input device will be connected to this sampler
3564 channel instead. This behavior is due to preserving full behavior
3565 backward compatibility.
3566
3567 Possible Answers:
3568
3569 "OK" -
3570
3571 on success
3572
3573 "WRN:<warning-code>:<warning-message>" -
3574
3575 if MIDI input port was set, but there are noteworthy issue(s)
3576 related, providing an appropriate warning code and warning
3577 message
3578
3579
3580
3581
3582
3583 Schoenebeck Expires January 16, 2016 [Page 64]
3584
3585 Internet-Draft LinuxSampler Control Protocol July 2015
3586
3587
3588 "ERR:<error-code>:<error-message>" -
3589
3590 in case it failed, providing an appropriate error code and
3591 error message
3592
3593 Examples:
3594
3595
3596
3597 Deprecated:
3598
3599 Should not be used anymore. This command is currently only
3600 preserved for backward compatibility.
3601
3602 This command is a relict from times where only one MIDI input per
3603 sampler channel was allowed. Use "ADD CHANNEL MIDI_INPUT"
3604 (Section 6.4.17) and "REMOVE CHANNEL MIDI_INPUT" (Section 6.4.18)
3605 instead.
3606
3607 6.4.23. Setting MIDI input channel
3608
3609 The front-end can alter the MIDI channel a sampler channel should
3610 listen to by sending the following command:
3611
3612 SET CHANNEL MIDI_INPUT_CHANNEL <sampler-channel> <midi-input-chan>
3613
3614 Where <midi-input-chan> is the number of the new MIDI input channel
3615 (zero indexed!) where <sampler-channel> should listen to, or "ALL" to
3616 listen on all 16 MIDI channels.
3617
3618 Possible Answers:
3619
3620 "OK" -
3621
3622 on success
3623
3624 "WRN:<warning-code>:<warning-message>" -
3625
3626 if MIDI input channel was set, but there are noteworthy
3627 issue(s) related, providing an appropriate warning code and
3628 warning message
3629
3630 "ERR:<error-code>:<error-message>" -
3631
3632 in case it failed, providing an appropriate error code and
3633 error message
3634
3635 Examples:
3636
3637
3638
3639 Schoenebeck Expires January 16, 2016 [Page 65]
3640
3641 Internet-Draft LinuxSampler Control Protocol July 2015
3642
3643
3644 C: "SET CHANNEL MIDI_INPUT_CHANNEL 0 0"
3645
3646 S: "OK"
3647
3648 C: "SET CHANNEL MIDI_INPUT_CHANNEL 1 ALL"
3649
3650 S: "OK"
3651
3652 6.4.24. Setting channel volume
3653
3654 The front-end can alter the volume of a sampler channel by sending
3655 the following command:
3656
3657 SET CHANNEL VOLUME <sampler-channel> <volume>
3658
3659 Where <volume> is an optionally dotted positive number (a value
3660 smaller than 1.0 means attenuation, whereas a value greater than 1.0
3661 means amplification) and <sampler-channel> defines the sampler
3662 channel where this volume factor should be set.
3663
3664 Possible Answers:
3665
3666 "OK" -
3667
3668 on success
3669
3670 "WRN:<warning-code>:<warning-message>" -
3671
3672 if channel volume was set, but there are noteworthy issue(s)
3673 related, providing an appropriate warning code and warning
3674 message
3675
3676 "ERR:<error-code>:<error-message>" -
3677
3678 in case it failed, providing an appropriate error code and
3679 error message
3680
3681 Examples:
3682
3683
3684
3685 6.4.25. Muting a sampler channel
3686
3687 The front-end can mute/unmute a specific sampler channel by sending
3688 the following command:
3689
3690
3691
3692
3693
3694
3695 Schoenebeck Expires January 16, 2016 [Page 66]
3696
3697 Internet-Draft LinuxSampler Control Protocol July 2015
3698
3699
3700 SET CHANNEL MUTE <sampler-channel> <mute>
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 <mute> should be replaced either by "1"
3705 to mute the channel or "0" to unmute 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 muted/unmuted, 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.26. Soloing a sampler channel
3729
3730 The front-end can solo/unsolo a specific sampler channel by sending
3731 the following command:
3732
3733 SET CHANNEL SOLO <sampler-channel> <solo>
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 <solo> should be replaced either by "1"
3738 to solo the channel or "0" to unsolo the channel.
3739
3740 Possible Answers:
3741
3742 "OK" -
3743
3744 on success
3745
3746
3747
3748
3749
3750
3751 Schoenebeck Expires January 16, 2016 [Page 67]
3752
3753 Internet-Draft LinuxSampler Control Protocol July 2015
3754
3755
3756 "WRN:<warning-code>:<warning-message>" -
3757
3758 if the channel was soloed/unsoloed, but there are noteworthy
3759 issue(s) related, providing an appropriate warning code and
3760 warning message
3761
3762 "ERR:<error-code>:<error-message>" -
3763
3764 in case it failed, providing an appropriate error code and
3765 error message
3766
3767 Examples:
3768
3769
3770
3771 6.4.27. Assigning a MIDI instrument map to a sampler channel
3772
3773 The front-end can assign a MIDI instrument map to a specific sampler
3774 channel by sending the following command:
3775
3776 SET CHANNEL MIDI_INSTRUMENT_MAP <sampler-channel> <map>
3777
3778 Where <sampler-channel> is the respective sampler channel number as
3779 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3780 (Section 6.4.4) command and <map> can have the following
3781 possibilites:
3782
3783 "NONE" -
3784
3785 This is the default setting. In this case the sampler channel
3786 is not assigned any MIDI instrument map and thus will ignore
3787 all MIDI program change messages.
3788
3789 "DEFAULT" -
3790
3791 The sampler channel will always use the default MIDI instrument
3792 map to handle MIDI program change messages.
3793
3794 numeric ID -
3795
3796 You can assign a specific MIDI instrument map by replacing
3797 <map> with the respective numeric ID of the MIDI instrument map
3798 as returned by the "LIST MIDI_INSTRUMENT_MAPS" (Section 6.7.4)
3799 command. Once that map will be deleted, the sampler channel
3800 would fall back to "NONE".
3801
3802 Read chapter "MIDI Instrument Mapping" (Section 6.7) for details
3803 regarding MIDI instrument mapping.
3804
3805
3806
3807 Schoenebeck Expires January 16, 2016 [Page 68]
3808
3809 Internet-Draft LinuxSampler Control Protocol July 2015
3810
3811
3812 Possible Answers:
3813
3814 "OK" -
3815
3816 on success
3817
3818 "ERR:<error-code>:<error-message>" -
3819
3820 in case it failed, providing an appropriate error code and
3821 error message
3822
3823 Examples:
3824
3825
3826
3827 6.4.28. Adding an effect send to a sampler channel
3828
3829 The front-end can create an additional effect send on a specific
3830 sampler channel by sending the following command:
3831
3832 CREATE FX_SEND <sampler-channel> <midi-ctrl> [<name>]
3833
3834 Where <sampler-channel> is the respective sampler channel number as
3835 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3836 (Section 6.4.4) command, that is the sampler channel on which the
3837 effect send should be created on, <midi-ctrl> is a number between
3838 0..127 defining the MIDI controller which can alter the effect send
3839 level and <name> is an optional argument defining a name for the
3840 effect send entity. The name does not have to be unique, but MUST be
3841 encapsulated into apostrophes and supports escape sequences as
3842 described in chapter "Character Set and Escape Sequences
3843 (Section 7.1)".
3844
3845 By default, that is as initial routing, the effect send's audio
3846 channels are automatically routed to the last audio channels of the
3847 sampler channel's audio output device, that way you can i.e. first
3848 increase the amount of audio channels on the audio output device for
3849 having dedicated effect send output channels and when "CREATE
3850 FX_SEND" is called, those channels will automatically be picked. You
3851 can alter the destination channels however with "SET FX_SEND
3852 AUDIO_OUTPUT_CHANNEL" (Section 6.4.34).
3853
3854 Note: Create effect sends on a sampler channel only when needed,
3855 because having effect sends on a sampler channel will decrease
3856 runtime performance, because for implementing channel effect sends,
3857 separate (sampler channel local) audio buffers are needed to render
3858 and mix the voices and route the audio signal afterwards to the
3859 master outputs and effect send outputs (along with their respective
3860
3861
3862
3863 Schoenebeck Expires January 16, 2016 [Page 69]
3864
3865 Internet-Draft LinuxSampler Control Protocol July 2015
3866
3867
3868 effect send levels). A sampler channel without effect sends however
3869 can mix its voices directly into the audio output devices's audio
3870 buffers and is thus faster.
3871
3872 Possible Answers:
3873
3874 "OK[<fx-send-id>]" -
3875
3876 in case a new effect send could be added to the sampler
3877 channel, where <fx-send-id> reflects the unique ID of the newly
3878 created effect send entity
3879
3880 "ERR:<error-code>:<error-message>" -
3881
3882 when a new effect send could not be added, i.e. due to invalid
3883 parameters
3884
3885 Examples:
3886
3887 C: "CREATE FX_SEND 0 91 'Reverb Send'"
3888
3889 S: "OK[0]"
3890
3891 C: "CREATE FX_SEND 0 93"
3892
3893 S: "OK[1]"
3894
3895 6.4.29. Removing an effect send from a sampler channel
3896
3897 The front-end can remove an existing effect send on a specific
3898 sampler channel by sending the following command:
3899
3900 DESTROY FX_SEND <sampler-channel> <fx-send-id>
3901
3902 Where <sampler-channel> is the respective sampler channel number as
3903 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3904 (Section 6.4.4) command, that is the sampler channel from which the
3905 effect send should be removed from and <fx-send-id> is the respective
3906 effect send number as returned by the "CREATE FX_SEND"
3907 (Section 6.4.28) or "LIST FX_SENDS" (Section 6.4.31) command.
3908
3909 Possible Answers:
3910
3911 "OK" -
3912
3913 on success
3914
3915
3916
3917
3918
3919 Schoenebeck Expires January 16, 2016 [Page 70]
3920
3921 Internet-Draft LinuxSampler Control Protocol July 2015
3922
3923
3924 "ERR:<error-code>:<error-message>" -
3925
3926 in case it failed, providing an appropriate error code and
3927 error message
3928
3929 Example:
3930
3931 C: "DESTROY FX_SEND 0 0"
3932
3933 S: "OK"
3934
3935 6.4.30. Getting amount of effect sends on a sampler channel
3936
3937 The front-end can ask for the amount of effect sends on a specific
3938 sampler channel by sending the following command:
3939
3940 GET FX_SENDS <sampler-channel>
3941
3942 Where <sampler-channel> is the respective sampler channel number as
3943 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3944 (Section 6.4.4) command.
3945
3946 Possible Answers:
3947
3948 The sampler will answer by returning the number of effect sends on
3949 the given sampler channel.
3950
3951 Example:
3952
3953 C: "GET FX_SENDS 0"
3954
3955 S: "2"
3956
3957 6.4.31. Listing all effect sends on a sampler channel
3958
3959 The front-end can ask for a list of effect sends on a specific
3960 sampler channel by sending the following command:
3961
3962 LIST FX_SENDS <sampler-channel>
3963
3964 Where <sampler-channel> is the respective sampler channel number as
3965 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3966 (Section 6.4.4) command.
3967
3968 Possible Answers:
3969
3970
3971
3972
3973
3974
3975 Schoenebeck Expires January 16, 2016 [Page 71]
3976
3977 Internet-Draft LinuxSampler Control Protocol July 2015
3978
3979
3980 The sampler will answer by returning a comma separated list with
3981 all effect sends' numerical IDs on the given sampler channel.
3982
3983 Examples:
3984
3985 C: "LIST FX_SENDS 0"
3986
3987 S: "0,1"
3988
3989 C: "LIST FX_SENDS 1"
3990
3991 S: ""
3992
3993 6.4.32. Getting effect send information
3994
3995 The front-end can ask for the current settings of an effect send
3996 entity by sending the following command:
3997
3998 GET FX_SEND INFO <sampler-channel> <fx-send-id>
3999
4000 Where <sampler-channel> is the sampler channel number as returned by
4001 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
4002 command and <fx-send-id> reflects the numerical ID of the effect send
4003 entity as returned by the "CREATE FX_SEND" (Section 6.4.28) or "LIST
4004 FX_SENDS" (Section 6.4.31) command.
4005
4006 Possible Answers:
4007
4008 The sampler will answer by sending a <CRLF> separated list. Each
4009 answer line begins with the settings category name followed by a
4010 colon and then a space character <SP> and finally the info
4011 character string to that setting category. At the moment the
4012 following categories are defined:
4013
4014
4015
4016 NAME -
4017
4018 name of the effect send entity (note that this character
4019 string may contain escape sequences (Section 7.1))
4020
4021 MIDI_CONTROLLER -
4022
4023 a value between 0 and 127 reflecting the MIDI controller
4024 which is able to modify the effect send's send level
4025
4026
4027
4028
4029
4030
4031 Schoenebeck Expires January 16, 2016 [Page 72]
4032
4033 Internet-Draft LinuxSampler Control Protocol July 2015
4034
4035
4036 LEVEL -
4037
4038 optionally dotted number reflecting the effect send's
4039 current send level (where a value < 1.0 means attenuation
4040 and a value > 1.0 means amplification)
4041
4042 AUDIO_OUTPUT_ROUTING -
4043
4044 comma separated list which reflects to which audio channel
4045 of the selected audio output device each effect send output
4046 channel is routed to, e.g. "0,3" would mean the effect
4047 send's output channel 0 is routed to channel 0 of the audio
4048 output device and the effect send's output channel 1 is
4049 routed to the channel 3 of the audio output device (see "SET
4050 FX_SEND AUDIO_OUTPUT_CHANNEL" (Section 6.4.34) for details),
4051 if an internal send effect is assigned to the effect send,
4052 then this setting defines the audio channel routing to that
4053 effect instance respectively
4054
4055 EFFECT -
4056
4057 destination send effect chain ID and destination effect
4058 chain position, separated by comma in the form "<effect-
4059 chain>,<chain-pos>" or "NONE" if there is no send effect
4060 assigned to the effect send
4061
4062 The mentioned fields above don't have to be in particular order.
4063
4064 Example:
4065
4066 C: "GET FX_SEND INFO 0 0"
4067
4068 S: "NAME: Reverb Send"
4069
4070 "MIDI_CONTROLLER: 91"
4071
4072 "LEVEL: 0.3"
4073
4074 "AUDIO_OUTPUT_ROUTING: 2,3"
4075
4076 "EFFECT: NONE"
4077
4078 "."
4079
4080 C: "GET FX_SEND INFO 0 1"
4081
4082 S: "NAME: Delay Send (Internal)"
4083
4084
4085
4086
4087 Schoenebeck Expires January 16, 2016 [Page 73]
4088
4089 Internet-Draft LinuxSampler Control Protocol July 2015
4090
4091
4092 "MIDI_CONTROLLER: 93"
4093
4094 "LEVEL: 0.51"
4095
4096 "AUDIO_OUTPUT_ROUTING: 1,2"
4097
4098 "EFFECT: 2,0"
4099
4100 "."
4101
4102 6.4.33. Changing effect send's name
4103
4104 The front-end can alter the current name of an effect send entity by
4105 sending the following command:
4106
4107 SET FX_SEND NAME <sampler-chan> <fx-send-id> <name>
4108
4109 Where <sampler-chan> is the sampler channel number as returned by the
4110 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
4111 command, <fx-send-id> reflects the numerical ID of the effect send
4112 entity as returned by the "CREATE FX_SEND" (Section 6.4.28) or "LIST
4113 FX_SENDS" (Section 6.4.31) command and <name> is the new name of the
4114 effect send entity, which does not have to be unique (name MUST be
4115 encapsulated into apostrophes and supports escape sequences as
4116 described in chapter "Character Set and Escape Sequences
4117 (Section 7.1)").
4118
4119 Possible Answers:
4120
4121 "OK" -
4122
4123 on success
4124
4125 "ERR:<error-code>:<error-message>" -
4126
4127 in case it failed, providing an appropriate error code and
4128 error message
4129
4130 Example:
4131
4132 C: "SET FX_SEND NAME 0 0 'Fx Send 1'"
4133
4134 S: "OK"
4135
4136
4137
4138
4139
4140
4141
4142
4143 Schoenebeck Expires January 16, 2016 [Page 74]
4144
4145 Internet-Draft LinuxSampler Control Protocol July 2015
4146
4147
4148 6.4.34. Altering effect send's audio routing
4149
4150 The front-end can alter the destination of an effect send's audio
4151 channel on a specific sampler channel by sending the following
4152 command:
4153
4154 SET FX_SEND AUDIO_OUTPUT_CHANNEL <sampler-chan> <fx-send-id>
4155 <audio-src> <audio-dst>
4156
4157 Where <sampler-chan> is the sampler channel number as returned by the
4158 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
4159 command, <fx-send-id> reflects the numerical ID of the effect send
4160 entity as returned by the "CREATE FX_SEND" (Section 6.4.28) or "LIST
4161 FX_SENDS" (Section 6.4.31) command, <audio-src> is the numerical ID
4162 of the effect send's audio channel which should be rerouted and
4163 <audio-dst> is the numerical ID of the audio channel of the selected
4164 audio output device where <audio-src> should be routed to. If an
4165 internal send effect is assigned to the effect send, then this
4166 setting defines the audio channel routing to that effect instance
4167 respectively.
4168
4169 Note that effect sends can only route audio to the same audio output
4170 device as assigned to the effect send's sampler channel. Also note
4171 that an effect send entity does always have exactly as much audio
4172 channels as its sampler channel. So if the sampler channel is
4173 stereo, the effect send does have two audio channels as well. Also
4174 keep in mind that the amount of audio channels on a sampler channel
4175 might be dependant not only to the deployed sampler engine on the
4176 sampler channel, but also dependant to the instrument currently
4177 loaded. However you can (effectively) turn an i.e. stereo effect
4178 send into a mono one by simply altering its audio routing
4179 appropriately.
4180
4181 Possible Answers:
4182
4183 "OK" -
4184
4185 on success
4186
4187 "WRN:<warning-code>:<warning-message>" -
4188
4189 if audio output channel was set, but there are noteworthy
4190 issue(s) related, providing an appropriate warning code and
4191 warning message
4192
4193 "ERR:<error-code>:<error-message>" -
4194
4195
4196
4197
4198
4199 Schoenebeck Expires January 16, 2016 [Page 75]
4200
4201 Internet-Draft LinuxSampler Control Protocol July 2015
4202
4203
4204 in case it failed, providing an appropriate error code and
4205 error message
4206
4207 Example:
4208
4209 C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2"
4210
4211 S: "OK"
4212
4213 6.4.35. Assigning destination effect to an effect send
4214
4215 The front-end can (re-)assign a destination effect to an effect send
4216 by sending the following command:
4217
4218 SET FX_SEND EFFECT <sampler-chan> <fx-send-id> <effect-chain>
4219 <chain-pos>
4220
4221 Where <sampler-chan> is the sampler channel number as returned by the
4222 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
4223 command, <fx-send-id> reflects the numerical ID of the effect send
4224 entity as returned by the "CREATE FX_SEND" (Section 6.4.28) or "LIST
4225 FX_SENDS" (Section 6.4.31) command, <effect-chain> by the numerical
4226 ID of the destination effect chain as returned by the "ADD
4227 SEND_EFFECT_CHAIN" (Section 6.11.14) or "LIST SEND_EFFECT_CHAINS"
4228 (Section 6.11.13) command and <chain-pos> reflects the exact effect
4229 chain position in the effect chain which hosts the actual destination
4230 effect.
4231
4232 Possible Answers:
4233
4234 "OK" -
4235
4236 on success
4237
4238 "ERR:<error-code>:<error-message>" -
4239
4240 in case it failed, providing an appropriate error code and
4241 error message
4242
4243 Example:
4244
4245 C: "SET FX_SEND EFFECT 0 0 2 5"
4246
4247 S: "OK"
4248
4249
4250
4251
4252
4253
4254
4255 Schoenebeck Expires January 16, 2016 [Page 76]
4256
4257 Internet-Draft LinuxSampler Control Protocol July 2015
4258
4259
4260 6.4.36. Removing destination effect from an effect send
4261
4262 The front-end can (re-)assign a destination effect to an effect send
4263 by sending the following command:
4264
4265 REMOVE FX_SEND EFFECT <sampler-chan> <fx-send-id>
4266
4267 Where <sampler-chan> is the sampler channel number as returned by the
4268 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
4269 command, <fx-send-id> reflects the numerical ID of the effect send
4270 entity as returned by the "CREATE FX_SEND" (Section 6.4.28) or "LIST
4271 FX_SENDS" (Section 6.4.31) command.
4272
4273 After the destination effect has been removed from the effect send,
4274 the audio signal of the effect send will be routed directly to the
4275 audio output device, according to the audio channel routing setting
4276 of the effect send.
4277
4278 Possible Answers:
4279
4280 "OK" -
4281
4282 on success
4283
4284 "ERR:<error-code>:<error-message>" -
4285
4286 in case it failed, providing an appropriate error code and
4287 error message
4288
4289 Example:
4290
4291 C: "REMOVE FX_SEND EFFECT 0 0"
4292
4293 S: "OK"
4294
4295 6.4.37. Altering effect send's MIDI controller
4296
4297 The front-end can alter the MIDI controller of an effect send entity
4298 by sending the following command:
4299
4300 SET FX_SEND MIDI_CONTROLLER <sampler-chan> <fx-send-id> <midi-
4301 ctrl>
4302
4303 Where <sampler-chan> is the sampler channel number as returned by the
4304 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
4305 command, <fx-send-id> reflects the numerical ID of the effect send
4306 entity as returned by the "CREATE FX_SEND" (Section 6.4.28) or "LIST
4307 FX_SENDS" (Section 6.4.31) command and <midi-ctrl> reflects the MIDI
4308
4309
4310
4311 Schoenebeck Expires January 16, 2016 [Page 77]
4312
4313 Internet-Draft LinuxSampler Control Protocol July 2015
4314
4315
4316 controller which shall be able to modify the effect send's send
4317 level.
4318
4319 Possible Answers:
4320
4321 "OK" -
4322
4323 on success
4324
4325 "WRN:<warning-code>:<warning-message>" -
4326
4327 if MIDI controller was set, but there are noteworthy issue(s)
4328 related, providing an appropriate warning code and warning
4329 message
4330
4331 "ERR:<error-code>:<error-message>" -
4332
4333 in case it failed, providing an appropriate error code and
4334 error message
4335
4336 Example:
4337
4338 C: "SET FX_SEND MIDI_CONTROLLER 0 0 91"
4339
4340 S: "OK"
4341
4342 6.4.38. Altering effect send's send level
4343
4344 The front-end can alter the current send level of an effect send
4345 entity by sending the following command:
4346
4347 SET FX_SEND LEVEL <sampler-chan> <fx-send-id> <volume>
4348
4349 Where <sampler-chan> is the sampler channel number as returned by the
4350 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
4351 command, <fx-send-id> reflects the numerical ID of the effect send
4352 entity as returned by the "CREATE FX_SEND" (Section 6.4.28) or "LIST
4353 FX_SENDS" (Section 6.4.31) command and <volume> is an optionally
4354 dotted positive number (a value smaller than 1.0 means attenuation,
4355 whereas a value greater than 1.0 means amplification) reflecting the
4356 new send level.
4357
4358 Possible Answers:
4359
4360 "OK" -
4361
4362 on success
4363
4364
4365
4366
4367 Schoenebeck Expires January 16, 2016 [Page 78]
4368
4369 Internet-Draft LinuxSampler Control Protocol July 2015
4370
4371
4372 "WRN:<warning-code>:<warning-message>" -
4373
4374 if new send level was set, but there are noteworthy issue(s)
4375 related, providing an appropriate warning code and warning
4376 message
4377
4378 "ERR:<error-code>:<error-message>" -
4379
4380 in case it failed, providing an appropriate error code and
4381 error message
4382
4383 Example:
4384
4385 C: "SET FX_SEND LEVEL 0 0 0.15"
4386
4387 S: "OK"
4388
4389 6.4.39. Sending MIDI messages to sampler channel
4390
4391 The front-end can send MIDI events to a specific sampler channel by
4392 sending the following command:
4393
4394 SEND CHANNEL MIDI_DATA <midi-msg> <sampler-chan> <arg1> <arg2>
4395
4396 Where <sampler-chan> is the sampler channel number as returned by the
4397 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
4398 command, <arg1> and <arg2> arguments depend on the <midi-msg>
4399 argument, which specifies the MIDI message type. Currently, the
4400 following MIDI messages are supported:
4401
4402 "NOTE_ON" -
4403
4404 For turning on MIDI notes, where <arg1> specifies the key
4405 number and <arg2> the velocity as described in the MIDI
4406 specification.
4407
4408 "NOTE_OFF" -
4409
4410 For turning a currently playing MIDI note off, where <arg1>
4411 specifies the key number and <arg2> the velocity as described
4412 in the MIDI specification.
4413
4414 "CC" -
4415
4416 For changing a MIDI controller, where <arg1> specifies the
4417 controller number and <arg2> the new value of the controller as
4418 described in the Control Change section of the MIDI
4419 specification.
4420
4421
4422
4423 Schoenebeck Expires January 16, 2016 [Page 79]
4424
4425 Internet-Draft LinuxSampler Control Protocol July 2015
4426
4427
4428 CAUTION: This command is provided for implementations of virtual MIDI
4429 keyboards and no realtime guarantee whatsoever will be made!
4430
4431 Possible Answers:
4432
4433 "OK" -
4434
4435 on success
4436
4437 "ERR:<error-code>:<error-message>" -
4438
4439 in case it failed, providing an appropriate error code and
4440 error message
4441
4442 Example:
4443
4444 C: "SEND CHANNEL MIDI_DATA NOTE_ON 0 56 112"
4445
4446 S: "OK"
4447
4448 6.4.40. Resetting a sampler channel
4449
4450 The front-end can reset a particular sampler channel by sending the
4451 following command:
4452
4453 RESET CHANNEL <sampler-channel>
4454
4455 Where <sampler-channel> defines the sampler channel to be reset.
4456 This will cause the engine on that sampler channel, its voices and
4457 eventually disk streams and all control and status variables to be
4458 reset.
4459
4460 Possible Answers:
4461
4462 "OK" -
4463
4464 on success
4465
4466 "WRN:<warning-code>:<warning-message>" -
4467
4468 if channel was reset, but there are noteworthy issue(s)
4469 related, providing an appropriate warning code and warning
4470 message
4471
4472 "ERR:<error-code>:<error-message>" -
4473
4474 in case it failed, providing an appropriate error code and
4475 error message
4476
4477
4478
4479 Schoenebeck Expires January 16, 2016 [Page 80]
4480
4481 Internet-Draft LinuxSampler Control Protocol July 2015
4482
4483
4484 Examples:
4485
4486
4487
4488 6.5. Controlling connection
4489
4490 The following commands are used to control the connection to
4491 LinuxSampler.
4492
4493 6.5.1. Register front-end for receiving event messages
4494
4495 The front-end can register itself to the LinuxSampler application to
4496 be informed about noteworthy events by sending this command:
4497
4498 SUBSCRIBE <event-id>
4499
4500 where <event-id> will be replaced by the respective event that client
4501 wants to subscribe to.
4502
4503 Possible Answers:
4504
4505 "OK" -
4506
4507 on success
4508
4509 "WRN:<warning-code>:<warning-message>" -
4510
4511 if registration succeeded, but there are noteworthy issue(s)
4512 related, providing an appropriate warning code and warning
4513 message
4514
4515 "ERR:<error-code>:<error-message>" -
4516
4517 in case it failed, providing an appropriate error code and
4518 error message
4519
4520 Examples:
4521
4522
4523
4524 6.5.2. Unregister front-end for not receiving event messages
4525
4526 The front-end can unregister itself if it doesn't want to receive
4527 event messages anymore by sending the following command:
4528
4529 UNSUBSCRIBE <event-id>
4530
4531 Where <event-id> will be replaced by the respective event that client
4532
4533
4534
4535 Schoenebeck Expires January 16, 2016 [Page 81]
4536
4537 Internet-Draft LinuxSampler Control Protocol July 2015
4538
4539
4540 doesn't want to receive anymore.
4541
4542 Possible Answers:
4543
4544 "OK" -
4545
4546 on success
4547
4548 "WRN:<warning-code>:<warning-message>" -
4549
4550 if unregistration succeeded, but there are noteworthy issue(s)
4551 related, providing an appropriate warning code and warning
4552 message
4553
4554 "ERR:<error-code>:<error-message>" -
4555
4556 in case it failed, providing an appropriate error code and
4557 error message
4558
4559 Examples:
4560
4561
4562
4563 6.5.3. Enable or disable echo of commands
4564
4565 To enable or disable back sending of commands to the client the
4566 following command can be used:
4567
4568 SET ECHO <value>
4569
4570 Where <value> should be replaced either by "1" to enable echo mode or
4571 "0" to disable echo mode. When echo mode is enabled, all commands
4572 send to LinuxSampler will be immediately send back and after this
4573 echo the actual response to the command will be returned. Echo mode
4574 will only be altered for the client connection that issued the "SET
4575 ECHO" command, not globally for all client connections.
4576
4577 Possible Answers:
4578
4579 "OK" -
4580
4581 usually
4582
4583 "ERR:<error-code>:<error-message>" -
4584
4585 on syntax error, e.g. non boolean value
4586
4587 Examples:
4588
4589
4590
4591 Schoenebeck Expires January 16, 2016 [Page 82]
4592
4593 Internet-Draft LinuxSampler Control Protocol July 2015
4594
4595
4596
4597
4598 6.5.4. Close client connection
4599
4600 The client can close its network connection to LinuxSampler by
4601 sending the following command:
4602
4603 QUIT
4604
4605 This is probably more interesting for manual telnet connections to
4606 LinuxSampler than really useful for a front-end implementation.
4607
4608 6.6. Global commands
4609
4610 The following commands have global impact on the sampler.
4611
4612 6.6.1. Current number of active voices
4613
4614 The front-end can ask for the current number of active voices on the
4615 sampler by sending the following command:
4616
4617 GET TOTAL_VOICE_COUNT
4618
4619 Possible Answers:
4620
4621 LinuxSampler will answer by returning the number of all active
4622 voices on the sampler.
4623
4624 6.6.2. Maximum amount of active voices
4625
4626 The front-end can ask for the maximum number of active voices by
4627 sending the following command:
4628
4629 GET TOTAL_VOICE_COUNT_MAX
4630
4631 Possible Answers:
4632
4633 LinuxSampler will answer by returning the maximum number of active
4634 voices.
4635
4636 6.6.3. Current number of active disk streams
4637
4638 The front-end can ask for the current number of active disk streams
4639 on the sampler by sending the following command:
4640
4641 GET TOTAL_STREAM_COUNT
4642
4643 Possible Answers:
4644
4645
4646
4647 Schoenebeck Expires January 16, 2016 [Page 83]
4648
4649 Internet-Draft LinuxSampler Control Protocol July 2015
4650
4651
4652 LinuxSampler will answer by returning the number of all active
4653 disk streams on the sampler.
4654
4655 6.6.4. Reset sampler
4656
4657 The front-end can reset the whole sampler by sending the following
4658 command:
4659
4660 RESET
4661
4662 Possible Answers:
4663
4664 "OK" -
4665
4666 always
4667
4668 Examples:
4669
4670
4671
4672 6.6.5. General sampler informations
4673
4674 The client can ask for general informations about the LinuxSampler
4675 instance by sending the following command:
4676
4677 GET SERVER INFO
4678
4679 Possible Answers:
4680
4681 LinuxSampler will answer by sending a <CRLF> separated list. Each
4682 answer line begins with the information category name followed by
4683 a colon and then a space character <SP> and finally the info
4684 character string to that information category. At the moment the
4685 following categories are defined:
4686
4687
4688
4689 DESCRIPTION -
4690
4691 arbitrary textual description about the sampler (note that
4692 the character string may contain escape sequences
4693 (Section 7.1))
4694
4695 VERSION -
4696
4697 version of the sampler
4698
4699
4700
4701
4702
4703 Schoenebeck Expires January 16, 2016 [Page 84]
4704
4705 Internet-Draft LinuxSampler Control Protocol July 2015
4706
4707
4708 PROTOCOL_VERSION -
4709
4710 version of the LSCP specification the sampler complies with
4711 (see Section 2 for details)
4712
4713 INSTRUMENTS_DB_SUPPORT -
4714
4715 either yes or no, specifies whether the sampler is build
4716 with instruments database support.
4717
4718 The mentioned fields above don't have to be in particular order.
4719 Other fields might be added in future.
4720
4721 Example:
4722
4723 C: "GET SERVER INFO"
4724
4725 S: "DESCRIPTION: LinuxSampler - modular, streaming capable
4726 sampler"
4727
4728 "VERSION: 1.0.0.svn23"
4729
4730 "PROTOCOL_VERSION: 1.5"
4731
4732 "INSTRUMENTS_DB_SUPPORT: no"
4733
4734 "."
4735
4736 6.6.6. Getting global volume attenuation
4737
4738 The client can ask for the current global sampler-wide volume
4739 attenuation by sending the following command:
4740
4741 GET VOLUME
4742
4743 Possible Answers:
4744
4745 The sampler will always answer by returning the optional dotted
4746 floating point coefficient, reflecting the current global volume
4747 attenuation.
4748
4749 Note: it is up to the respective sampler engine whether to obey that
4750 global volume parameter or not, but in general all engines SHOULD use
4751 this parameter.
4752
4753
4754
4755
4756
4757
4758
4759 Schoenebeck Expires January 16, 2016 [Page 85]
4760
4761 Internet-Draft LinuxSampler Control Protocol July 2015
4762
4763
4764 6.6.7. Setting global volume attenuation
4765
4766 The client can alter the current global sampler-wide volume
4767 attenuation by sending the following command:
4768
4769 SET VOLUME <volume>
4770
4771 Where <volume> should be replaced by the optional dotted floating
4772 point value, reflecting the new global volume parameter. This value
4773 might usually be in the range between 0.0 and 1.0, that is for
4774 attenuating the overall volume.
4775
4776 Possible Answers:
4777
4778 "OK" -
4779
4780 on success
4781
4782 "WRN:<warning-code>:<warning-message>" -
4783
4784 if the global volume was set, but there are noteworthy issue(s)
4785 related, providing an appropriate warning code and warning
4786 message
4787
4788 "ERR:<error-code>:<error-message>" -
4789
4790 in case it failed, providing an appropriate error code and
4791 error message
4792
4793 6.6.8. Getting global voice limit
4794
4795 The client can ask for the current global sampler-wide limit for
4796 maximum voices by sending the following command:
4797
4798 GET VOICES
4799
4800 Possible Answers:
4801
4802 LinuxSampler will answer by returning the number for the current
4803 limit of maximum voices.
4804
4805 The voice limit setting defines how many voices should maximum be
4806 processed by the sampler at the same time. If the user triggers new
4807 notes which would exceed that voice limit, the sampler engine will
4808 react by stealing old voices for those newly triggered notes. Note
4809 that the amount of voices triggered by a new note can be larger than
4810 one and is dependent to the respective instrument and probably
4811 further criterias.
4812
4813
4814
4815 Schoenebeck Expires January 16, 2016 [Page 86]
4816
4817 Internet-Draft LinuxSampler Control Protocol July 2015
4818
4819
4820 6.6.9. Setting global voice limit
4821
4822 The client can alter the current global sampler-wide limit for
4823 maximum voices by sending the following command:
4824
4825 SET VOICES <max-voices>
4826
4827 Where <max-voices> should be replaced by the integer value,
4828 reflecting the new global amount limit of maximum voices. This value
4829 has to be larger than 0.
4830
4831 Possible Answers:
4832
4833 "OK" -
4834
4835 on success
4836
4837 "WRN:<warning-code>:<warning-message>" -
4838
4839 if the voice limit was set, but there are noteworthy issue(s)
4840 related, providing an appropriate warning code and warning
4841 message
4842
4843 "ERR:<error-code>:<error-message>" -
4844
4845 in case it failed, providing an appropriate error code and
4846 error message
4847
4848 Note: the given value will be passed to all sampler engine instances.
4849 The total amount of maximum voices on the running system might thus
4850 be as big as the given value multiplied by the current amount of
4851 engine instances.
4852
4853 Caution: when adjusting the voice limit, you SHOULD also adjust the
4854 disk stream limit respectively and vice versa.
4855
4856 6.6.10. Getting global disk stream limit
4857
4858 The client can ask for the current global sampler-wide limit for
4859 maximum disk streams by sending the following command:
4860
4861 GET STREAMS
4862
4863 Possible Answers:
4864
4865 LinuxSampler will answer by returning the number for the current
4866 limit of maximum disk streams.
4867
4868
4869
4870
4871 Schoenebeck Expires January 16, 2016 [Page 87]
4872
4873 Internet-Draft LinuxSampler Control Protocol July 2015
4874
4875
4876 The disk stream limit setting defines how many disk streams should
4877 maximum be processed by a sampler engine at the same time. The
4878 higher this value, the more memory (RAM) will be occupied, since
4879 every disk streams allocates a certain buffer size for being able to
4880 perform its streaming operations.
4881
4882 6.6.11. Setting global disk stream limit
4883
4884 The client can alter the current global sampler-wide limit for
4885 maximum disk streams by sending the following command:
4886
4887 SET STREAMS <max-streams>
4888
4889 Where <max-streams> should be replaced by the integer value,
4890 reflecting the new global amount limit of maximum disk streams. This
4891 value has to be positive.
4892
4893 Possible Answers:
4894
4895 "OK" -
4896
4897 on success
4898
4899 "WRN:<warning-code>:<warning-message>" -
4900
4901 if the disk stream limit was set, but there are noteworthy
4902 issue(s) related, providing an appropriate warning code and
4903 warning message
4904
4905 "ERR:<error-code>:<error-message>" -
4906
4907 in case it failed, providing an appropriate error code and
4908 error message
4909
4910 Note: the given value will be passed to all sampler engine instances.
4911 The total amount of maximum disk streams on the running system might
4912 thus be as big as the given value multiplied by the current amount of
4913 engine instances.
4914
4915 Caution: when adjusting the disk stream limit, you SHOULD also adjust
4916 the voice limit respectively and vice versa.
4917
4918 6.7. MIDI Instrument Mapping
4919
4920 The MIDI protocol provides a way to switch between instruments by
4921 sending so called MIDI bank select and MIDI program change messages
4922 which are essentially just numbers. The following commands allow to
4923 actually map arbitrary MIDI bank select / program change numbers with
4924
4925
4926
4927 Schoenebeck Expires January 16, 2016 [Page 88]
4928
4929 Internet-Draft LinuxSampler Control Protocol July 2015
4930
4931
4932 real instruments.
4933
4934 The sampler allows to manage an arbitrary amount of MIDI instrument
4935 maps which define which instrument to load on which MIDI program
4936 change message.
4937
4938 By default, that is when the sampler is launched, there is no map,
4939 thus the sampler will simply ignore all program change messages. The
4940 front-end has to explicitly create at least one map, add entries to
4941 the map and tell the respective sampler channel(s) which MIDI
4942 instrument map to use, so the sampler knows how to react on a given
4943 program change message on the respective sampler channel, that is by
4944 switching to the respectively defined engine type and loading the
4945 respective instrument. See command "SET CHANNEL MIDI_INSTRUMENT_MAP"
4946 (Section 6.4.27) for how to assign a MIDI instrument map to a sampler
4947 channel.
4948
4949 Also note per MIDI specification a bank select message does not cause
4950 to switch to another instrument. Instead when receiving a bank
4951 select message the bank value will be stored and a subsequent program
4952 change message (which may occur at any time) will finally cause the
4953 sampler to switch to the respective instrument as reflected by the
4954 current MIDI instrument map.
4955
4956 6.7.1. Create a new MIDI instrument map
4957
4958 The front-end can add a new MIDI instrument map by sending the
4959 following command:
4960
4961 ADD MIDI_INSTRUMENT_MAP [<name>]
4962
4963 Where <name> is an optional argument allowing to assign a custom name
4964 to the new map. MIDI instrument Map names do not have to be unique,
4965 but MUST be encapsulated into apostrophes and support escape
4966 sequences as described in chapter "Character Set and Escape Sequences
4967 (Section 7.1)".
4968
4969 Possible Answers:
4970
4971 "OK[<map>]" -
4972
4973 in case a new MIDI instrument map could be added, where <map>
4974 reflects the unique ID of the newly created MIDI instrument map
4975
4976 "ERR:<error-code>:<error-message>" -
4977
4978 when a new map could not be created, which might never occur in
4979 practice
4980
4981
4982
4983 Schoenebeck Expires January 16, 2016 [Page 89]
4984
4985 Internet-Draft LinuxSampler Control Protocol July 2015
4986
4987
4988 Examples:
4989
4990 C: "ADD MIDI_INSTRUMENT_MAP 'Standard Map'"
4991
4992 S: "OK[0]"
4993
4994 C: "ADD MIDI_INSTRUMENT_MAP 'Standard Drumkit'"
4995
4996 S: "OK[1]"
4997
4998 C: "ADD MIDI_INSTRUMENT_MAP"
4999
5000 S: "OK[5]"
5001
5002 6.7.2. Delete one particular or all MIDI instrument maps
5003
5004 The front-end can delete a particular MIDI instrument map by sending
5005 the following command:
5006
5007 REMOVE MIDI_INSTRUMENT_MAP <map>
5008
5009 Where <map> reflects the unique ID of the map to delete as returned
5010 by the "LIST MIDI_INSTRUMENT_MAPS" (Section 6.7.4) command.
5011
5012 The front-end can delete all MIDI instrument maps by sending the
5013 following command:
5014
5015 REMOVE MIDI_INSTRUMENT_MAP ALL
5016
5017 Possible Answers:
5018
5019 "OK" -
5020
5021 in case the map(s) could be deleted
5022
5023 "ERR:<error-code>:<error-message>" -
5024
5025 when the given map does not exist
5026
5027 Examples:
5028
5029 C: "REMOVE MIDI_INSTRUMENT_MAP 0"
5030
5031 S: "OK"
5032
5033 C: "REMOVE MIDI_INSTRUMENT_MAP ALL"
5034
5035
5036
5037
5038
5039 Schoenebeck Expires January 16, 2016 [Page 90]
5040
5041 Internet-Draft LinuxSampler Control Protocol July 2015
5042
5043
5044 S: "OK"
5045
5046 6.7.3. Get amount of existing MIDI instrument maps
5047
5048 The front-end can retrieve the current amount of MIDI instrument maps
5049 by sending the following command:
5050
5051 GET MIDI_INSTRUMENT_MAPS
5052
5053 Possible Answers:
5054
5055 The sampler will answer by returning the current number of MIDI
5056 instrument maps.
5057
5058 Example:
5059
5060 C: "GET MIDI_INSTRUMENT_MAPS"
5061
5062 S: "2"
5063
5064 6.7.4. Getting all created MIDI instrument maps
5065
5066 The number of MIDI instrument maps can change on runtime. To get the
5067 current list of MIDI instrument maps, the front-end can send the
5068 following command:
5069
5070 LIST MIDI_INSTRUMENT_MAPS
5071
5072 Possible Answers:
5073
5074 The sampler will answer by returning a comma separated list with
5075 all MIDI instrument maps' numerical IDs.
5076
5077 Example:
5078
5079 C: "LIST MIDI_INSTRUMENT_MAPS"
5080
5081 S: "0,1,5,12"
5082
5083 6.7.5. Getting MIDI instrument map information
5084
5085 The front-end can ask for the current settings of a MIDI instrument
5086 map by sending the following command:
5087
5088 GET MIDI_INSTRUMENT_MAP INFO <map>
5089
5090 Where <map> is the numerical ID of the map the front-end is
5091 interested in as returned by the "LIST MIDI_INSTRUMENT_MAPS"
5092
5093
5094
5095 Schoenebeck Expires January 16, 2016 [Page 91]
5096
5097 Internet-Draft LinuxSampler Control Protocol July 2015
5098
5099
5100 (Section 6.7.4) command.
5101
5102 Possible Answers:
5103
5104 LinuxSampler will answer by sending a <CRLF> separated list. Each
5105 answer line begins with the settings category name followed by a
5106 colon and then a space character <SP> and finally the info
5107 character string to that setting category. At the moment the
5108 following categories are defined:
5109
5110
5111
5112 NAME -
5113
5114 custom name of the given map, which does not have to be
5115 unique (note that this character string may contain escape
5116 sequences (Section 7.1))
5117
5118 DEFAULT -
5119
5120 either true or false, defines whether this map is the
5121 default map
5122
5123 The mentioned fields above don't have to be in particular order.
5124
5125 Example:
5126
5127 C: "GET MIDI_INSTRUMENT_MAP INFO 0"
5128
5129 S: "NAME: Standard Map"
5130
5131 "DEFAULT: true"
5132
5133 "."
5134
5135 6.7.6. Renaming a MIDI instrument map
5136
5137 The front-end can alter the custom name of a MIDI instrument map by
5138 sending the following command:
5139
5140 SET MIDI_INSTRUMENT_MAP NAME <map> <name>
5141
5142 Where <map> is the numerical ID of the map and <name> the new custom
5143 name of the map, which does not have to be unique (name MUST be
5144 encapsulated into apostrophes and supports escape sequences as
5145 described in chapter "Character Set and Escape Sequences
5146 (Section 7.1)").
5147
5148
5149
5150
5151 Schoenebeck Expires January 16, 2016 [Page 92]
5152
5153 Internet-Draft LinuxSampler Control Protocol July 2015
5154
5155
5156 Possible Answers:
5157
5158 "OK" -
5159
5160 on success
5161
5162 "ERR:<error-code>:<error-message>" -
5163
5164 in case the given map does not exist
5165
5166 Example:
5167
5168 C: "SET MIDI_INSTRUMENT_MAP NAME 0 'Foo instruments'"
5169
5170 S: "OK"
5171
5172 6.7.7. Create or replace a MIDI instrument map entry
5173
5174 The front-end can create a new or replace an existing entry in a
5175 sampler's MIDI instrument map by sending the following command:
5176
5177 MAP MIDI_INSTRUMENT [NON_MODAL] <map> <midi_bank> <midi_prog>
5178 <engine_name> <filename> <instrument_index> <volume_value>
5179 [<instr_load_mode>] [<name>]
5180
5181 Where <map> is the numeric ID of the map to alter, <midi_bank> is an
5182 integer value between 0..16383 reflecting the MIDI bank select index,
5183 <midi_prog> an integer value between 0..127 reflecting the MIDI
5184 program change index, <engine_name> a sampler engine name as returned
5185 by the "LIST AVAILABLE_ENGINES" (Section 6.4.8) command (not
5186 encapsulated into apostrophes), <filename> the name of the
5187 instrument's file to be deployed (encapsulated into apostrophes,
5188 supporting escape sequences as described in chapter "Character Set
5189 and Escape Sequences (Section 7.1)"), <instrument_index> the index
5190 (integer value) of the instrument within the given file,
5191 <volume_value> reflects the master volume of the instrument as
5192 optionally dotted number (where a value < 1.0 means attenuation and a
5193 value > 1.0 means amplification). This parameter easily allows to
5194 adjust the volume of all intruments within a custom instrument map
5195 without having to adjust their instrument files. The OPTIONAL
5196 <instr_load_mode> argument defines the life time of the instrument,
5197 that is when the instrument should be loaded, when freed and has
5198 exactly the following possibilities:
5199
5200 "ON_DEMAND" -
5201
5202 The instrument will be loaded when needed, that is when
5203 demanded by at least one sampler channel. It will immediately
5204
5205
5206
5207 Schoenebeck Expires January 16, 2016 [Page 93]
5208
5209 Internet-Draft LinuxSampler Control Protocol July 2015
5210
5211
5212 be freed from memory when not needed by any sampler channel
5213 anymore.
5214
5215 "ON_DEMAND_HOLD" -
5216
5217 The instrument will be loaded when needed, that is when
5218 demanded by at least one sampler channel. It will be kept in
5219 memory even when not needed by any sampler channel anymore.
5220 Instruments with this mode are only freed when the sampler is
5221 reset or all mapping entries with this mode (and respective
5222 instrument) are explicitly changed to "ON_DEMAND" and no
5223 sampler channel is using the instrument anymore.
5224
5225 "PERSISTENT" -
5226
5227 The instrument will immediately be loaded into memory when this
5228 mapping command is sent and the instrument is kept all the
5229 time. Instruments with this mode are only freed when the
5230 sampler is reset or all mapping entries with this mode (and
5231 respective instrument) are explicitly changed to "ON_DEMAND"
5232 and no sampler channel is using the instrument anymore.
5233
5234 not supplied -
5235
5236 In case there is no <instr_load_mode> argument given, it will
5237 be up to the InstrumentManager to decide which mode to use.
5238 Usually it will use "ON_DEMAND" if an entry for the given
5239 instrument does not exist in the InstrumentManager's list yet,
5240 otherwise if an entry already exists, it will simply stick with
5241 the mode currently reflected by the already existing entry,
5242 that is it will not change the mode.
5243
5244 The <instr_load_mode> argument thus allows to define an appropriate
5245 strategy (low memory consumption vs. fast instrument switching) for
5246 each instrument individually. Note, the following restrictions apply
5247 to this argument: "ON_DEMAND_HOLD" and "PERSISTENT" have to be
5248 supported by the respective sampler engine (which is technically the
5249 case when the engine provides an InstrumentManager for its format).
5250 If this is not the case the argument will automatically fall back to
5251 the default value "ON_DEMAND". Also the load mode of one instrument
5252 may automatically change the laod mode of other instrument(s), i.e.
5253 because the instruments are part of the same file and the engine does
5254 not allow a way to manage load modes for them individually. Due to
5255 this, in case the frontend shows the load modes of entries, the
5256 frontend should retrieve the actual mode by i.e. sending "GET
5257 MIDI_INSTRUMENT INFO" (Section 6.7.11) command(s). Finally the
5258 OPTIONAL <name> argument allows to set a custom name (encapsulated
5259 into apostrophes, supporting escape sequences as described in chapter
5260
5261
5262
5263 Schoenebeck Expires January 16, 2016 [Page 94]
5264
5265 Internet-Draft LinuxSampler Control Protocol July 2015
5266
5267
5268 "Character Set and Escape Sequences (Section 7.1)") for the mapping
5269 entry, useful for frontends for displaying an appropriate name for
5270 mapped instruments (using "GET MIDI_INSTRUMENT INFO"
5271 (Section 6.7.11)).
5272
5273 By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is
5274 completely established in the sampler. The OPTIONAL "NON_MODAL"
5275 argument however causes the respective "MAP MIDI_INSTRUMENT" command
5276 to return immediately, that is to let the sampler establish the
5277 mapping in the background. So this argument might be especially
5278 useful for mappings with a "PERSISTENT" type, because these have to
5279 load the respective instruments immediately and might thus block for
5280 a very long time. It is recommended however to use the OPTIONAL
5281 "NON_MODAL" argument only if really necessary, because it has the
5282 following drawbacks: as "NON_MODAL" instructions return immediately,
5283 they may not necessarily return an error i.e. when the given
5284 instrument file turns out to be corrupt, beside that subsequent
5285 commands in a LSCP instruction sequence might fail, because mandatory
5286 mappings are not yet completed.
5287
5288 Possible Answers:
5289
5290 "OK" -
5291
5292 usually
5293
5294 "ERR:<error-code>:<error-message>" -
5295
5296 when the given map or engine does not exist or a value is out
5297 of range
5298
5299 Examples:
5300
5301 C: "MAP MIDI_INSTRUMENT 0 3 0 gig '/usr/share/Steinway D.gig' 0
5302 0.8 PERSISTENT"
5303
5304 S: "OK"
5305
5306 C: "MAP MIDI_INSTRUMENT 0 4 50 gig '/home/john/foostrings.gig' 7
5307 1.0"
5308
5309 S: "OK"
5310
5311 C: "MAP MIDI_INSTRUMENT 0 0 0 gig '/usr/share/piano.gig' 0 1.0
5312 'Normal Piano'"
5313
5314 S: "OK"
5315
5316
5317
5318
5319 Schoenebeck Expires January 16, 2016 [Page 95]
5320
5321 Internet-Draft LinuxSampler Control Protocol July 2015
5322
5323
5324 C: "MAP MIDI_INSTRUMENT 0 1 0 gig '/usr/share/piano.gig' 0 0.25
5325 'Silent Piano'"
5326
5327 S: "OK"
5328
5329 C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/
5330 foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"
5331
5332 S: "OK"
5333
5334 6.7.8. Getting amount of MIDI instrument map entries
5335
5336 The front-end can query the amount of currently existing entries in a
5337 MIDI instrument map by sending the following command:
5338
5339 GET MIDI_INSTRUMENTS <map>
5340
5341 The front-end can query the amount of currently existing entries in
5342 all MIDI instrument maps by sending the following command:
5343
5344 GET MIDI_INSTRUMENTS ALL
5345
5346 Possible Answers:
5347
5348 The sampler will answer by sending the current number of entries
5349 in the MIDI instrument map(s).
5350
5351 Example:
5352
5353 C: "GET MIDI_INSTRUMENTS 0"
5354
5355 S: "234"
5356
5357 C: "GET MIDI_INSTRUMENTS ALL"
5358
5359 S: "954"
5360
5361 6.7.9. Getting indeces of all entries of a MIDI instrument map
5362
5363 The front-end can query a list of all currently existing entries in a
5364 certain MIDI instrument map by sending the following command:
5365
5366 LIST MIDI_INSTRUMENTS <map>
5367
5368 Where <map> is the numeric ID of the MIDI instrument map.
5369
5370 The front-end can query a list of all currently existing entries of
5371 all MIDI instrument maps by sending the following command:
5372
5373
5374
5375 Schoenebeck Expires January 16, 2016 [Page 96]
5376
5377 Internet-Draft LinuxSampler Control Protocol July 2015
5378
5379
5380 LIST MIDI_INSTRUMENTS ALL
5381
5382 Possible Answers:
5383
5384 The sampler will answer by sending a comma separated list of map
5385 ID - MIDI bank - MIDI program triples, where each triple is
5386 encapsulated into curly braces. The list is returned in one
5387 single line. Each triple just reflects the key of the respective
5388 map entry, thus subsequent "GET MIDI_INSTRUMENT INFO"
5389 (Section 6.7.11) command(s) are necessary to retrieve detailed
5390 informations about each entry.
5391
5392 Example:
5393
5394 C: "LIST MIDI_INSTRUMENTS 0"
5395
5396 S: "{0,0,0},{0,0,1},{0,0,3},{0,1,4},{1,127,127}"
5397
5398 6.7.10. Remove an entry from the MIDI instrument map
5399
5400 The front-end can delete an entry from a MIDI instrument map by
5401 sending the following command:
5402
5403 UNMAP MIDI_INSTRUMENT <map> <midi_bank> <midi_prog>
5404
5405 Where <map> is the numeric ID of the MIDI instrument map, <midi_bank>
5406 is an integer value between 0..16383 reflecting the MIDI bank value
5407 and <midi_prog> an integer value between 0..127 reflecting the MIDI
5408 program value of the map's entrie's key index triple.
5409
5410 Possible Answers:
5411
5412 "OK" -
5413
5414 usually
5415
5416 "ERR:<error-code>:<error-message>" -
5417
5418 when index out of bounds
5419
5420 Example:
5421
5422 C: "UNMAP MIDI_INSTRUMENT 0 2 127"
5423
5424 S: "OK"
5425
5426
5427
5428
5429
5430
5431 Schoenebeck Expires January 16, 2016 [Page 97]
5432
5433 Internet-Draft LinuxSampler Control Protocol July 2015
5434
5435
5436 6.7.11. Get current settings of MIDI instrument map entry
5437
5438 The front-end can retrieve the current settings of a certain
5439 instrument map entry by sending the following command:
5440
5441 GET MIDI_INSTRUMENT INFO <map> <midi_bank> <midi_prog>
5442
5443 Where <map> is the numeric ID of the MIDI instrument map, <midi_bank>
5444 is an integer value between 0..16383 reflecting the MIDI bank value,
5445 <midi_bank> and <midi_prog> an integer value between 0..127
5446 reflecting the MIDI program value of the map's entrie's key index
5447 triple.
5448
5449 Possible Answers:
5450
5451 LinuxSampler will answer by sending a <CRLF> separated list. Each
5452 answer line begins with the information category name followed by
5453 a colon and then a space character <SP> and finally the info
5454 character string to that info category. At the moment the
5455 following categories are defined:
5456
5457 "NAME" -
5458
5459 Name for this MIDI instrument map entry (if defined). This
5460 name shall be used by frontends for displaying a name for this
5461 mapped instrument. It can be set and changed with the "MAP
5462 MIDI_INSTRUMENT" (Section 6.7.7) command and does not have to
5463 be unique. (note that this character string may contain escape
5464 sequences (Section 7.1))
5465
5466 "ENGINE_NAME" -
5467
5468 Name of the engine to be deployed for this instrument.
5469
5470 "INSTRUMENT_FILE" -
5471
5472 File name of the instrument (note that this path may contain
5473 escape sequences (Section 7.1)).
5474
5475 "INSTRUMENT_NR" -
5476
5477 Index of the instrument within the file.
5478
5479 "INSTRUMENT_NAME" -
5480
5481 Name of the loaded instrument as reflected by its file. In
5482 contrast to the "NAME" field, the "INSTRUMENT_NAME" field
5483 cannot be changed (note that this character string may contain
5484
5485
5486
5487 Schoenebeck Expires January 16, 2016 [Page 98]
5488
5489 Internet-Draft LinuxSampler Control Protocol July 2015
5490
5491
5492 escape sequences (Section 7.1)).
5493
5494 "LOAD_MODE" -
5495
5496 Life time of instrument (see "MAP MIDI_INSTRUMENT"
5497 (Section 6.7.7) for details about this setting).
5498
5499 "VOLUME" -
5500
5501 master volume of the instrument as optionally dotted number
5502 (where a value < 1.0 means attenuation and a value > 1.0 means
5503 amplification)
5504
5505 The mentioned fields above don't have to be in particular order.
5506
5507 Example:
5508
5509 C: "GET MIDI_INSTRUMENT INFO 1 45 120"
5510
5511 S: "NAME: Drums for Foo Song"
5512
5513 "ENGINE_NAME: GigEngine"
5514
5515 "INSTRUMENT_FILE: /usr/share/joesdrumkit.gig"
5516
5517 "INSTRUMENT_NR: 0"
5518
5519 "INSTRUMENT_NAME: Joe's Drumkit"
5520
5521 "LOAD_MODE: PERSISTENT"
5522
5523 "VOLUME: 1.0"
5524
5525 "."
5526
5527 6.7.12. Clear MIDI instrument map
5528
5529 The front-end can clear a whole MIDI instrument map, that is delete
5530 all its entries by sending the following command:
5531
5532 CLEAR MIDI_INSTRUMENTS <map>
5533
5534 Where <map> is the numeric ID of the map to clear.
5535
5536 The front-end can clear all MIDI instrument maps, that is delete all
5537 entries of all maps by sending the following command:
5538
5539
5540
5541
5542
5543 Schoenebeck Expires January 16, 2016 [Page 99]
5544
5545 Internet-Draft LinuxSampler Control Protocol July 2015
5546
5547
5548 CLEAR MIDI_INSTRUMENTS ALL
5549
5550 The command "CLEAR MIDI_INSTRUMENTS ALL" does not delete the maps,
5551 only their entries, thus the map's settings like custom name will be
5552 preservevd.
5553
5554 Possible Answers:
5555
5556 "OK" -
5557
5558 always
5559
5560 Examples:
5561
5562 C: "CLEAR MIDI_INSTRUMENTS 0"
5563
5564 S: "OK"
5565
5566 C: "CLEAR MIDI_INSTRUMENTS ALL"
5567
5568 S: "OK"
5569
5570 6.8. Managing Instruments Database
5571
5572 The following commands describe how to use and manage the instruments
5573 database.
5574
5575 Notice:
5576
5577 All command arguments representing a path or instrument/directory
5578 name support escape sequences as described in chapter "Character
5579 Set and Escape Sequences (Section 7.1)".
5580
5581 All occurrences of a forward slash in instrument and directory
5582 names are escaped with its hex (\x2f) or octal (\057) escape
5583 sequence.
5584
5585 6.8.1. Creating a new instrument directory
5586
5587 The front-end can add a new instrument directory to the instruments
5588 database by sending the following command:
5589
5590 ADD DB_INSTRUMENT_DIRECTORY <dir>
5591
5592 Where <dir> is the absolute path name of the directory to be created
5593 (encapsulated into apostrophes).
5594
5595 Possible Answers:
5596
5597
5598
5599 Schoenebeck Expires January 16, 2016 [Page 100]
5600
5601 Internet-Draft LinuxSampler Control Protocol July 2015
5602
5603
5604 "OK" -
5605
5606 on success
5607
5608 "ERR:<error-code>:<error-message>" -
5609
5610 when the directory could not be created, which can happen if
5611 the directory already exists or the name contains not allowed
5612 symbols
5613
5614 Examples:
5615
5616 C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'"
5617
5618 S: "OK"
5619
5620 6.8.2. Deleting an instrument directory
5621
5622 The front-end can delete a particular instrument directory from the
5623 instruments database by sending the following command:
5624
5625 REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] <dir>
5626
5627 Where <dir> is the absolute path name of the directory to delete.
5628 The optional FORCE argument can be used to force the deletion of a
5629 non-empty directory and all its content.
5630
5631 Possible Answers:
5632
5633 "OK" -
5634
5635 if the directory is deleted successfully
5636
5637 "ERR:<error-code>:<error-message>" -
5638
5639 if the given directory does not exist, or if trying to delete a
5640 non-empty directory, without using the FORCE argument.
5641
5642 Examples:
5643
5644 C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'"
5645
5646 S: "OK"
5647
5648
5649
5650
5651
5652
5653
5654
5655 Schoenebeck Expires January 16, 2016 [Page 101]
5656
5657 Internet-Draft LinuxSampler Control Protocol July 2015
5658
5659
5660 6.8.3. Getting amount of instrument directories
5661
5662 The front-end can retrieve the current amount of directories in a
5663 specific directory by sending the following command:
5664
5665 GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] <dir>
5666
5667 Where <dir> should be replaced by the absolute path name of the
5668 directory. If RECURSIVE is specified, the number of all directories,
5669 including those located in subdirectories of the specified directory,
5670 will be returned.
5671
5672 Possible Answers:
5673
5674 The current number of instrument directories in the specified
5675 directory.
5676
5677 "ERR:<error-code>:<error-message>" -
5678
5679 if the given directory does not exist.
5680
5681 Example:
5682
5683 C: "GET DB_INSTRUMENT_DIRECTORIES '/'"
5684
5685 S: "2"
5686
5687 6.8.4. Listing all directories in specific directory
5688
5689 The front-end can retrieve the current list of directories in
5690 specific directory by sending the following command:
5691
5692 LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] <dir>
5693
5694 Where <dir> should be replaced by the absolute path name of the
5695 directory. If RECURSIVE is specified, the absolute path names of all
5696 directories, including those located in subdirectories of the
5697 specified directory, will be returned.
5698
5699 Possible Answers:
5700
5701 A comma separated list of all instrument directories (encapsulated
5702 into apostrophes) in the specified directory.
5703
5704 "ERR:<error-code>:<error-message>" -
5705
5706 if the given directory does not exist.
5707
5708
5709
5710
5711 Schoenebeck Expires January 16, 2016 [Page 102]
5712
5713 Internet-Draft LinuxSampler Control Protocol July 2015
5714
5715
5716 Example:
5717
5718 C: "LIST DB_INSTRUMENT_DIRECTORIES '/'"
5719
5720 S: "'Piano Collection','Percussion Collection'"
5721
5722 C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'"
5723
5724 S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano
5725 Collection/Acoustic/New','/Percussion Collection'"
5726
5727 6.8.5. Getting instrument directory information
5728
5729 The front-end can ask for the current settings of an instrument
5730 directory by sending the following command:
5731
5732 GET DB_INSTRUMENT_DIRECTORY INFO <dir>
5733
5734 Where <dir> should be replaced by the absolute path name of the
5735 directory the front-end is interested in.
5736
5737 Possible Answers:
5738
5739 LinuxSampler will answer by sending a <CRLF> separated list. Each
5740 answer line begins with the settings category name followed by a
5741 colon and then a space character <SP> and finally the info
5742 character string to that setting category. At the moment the
5743 following categories are defined:
5744
5745
5746
5747 DESCRIPTION -
5748
5749 A brief description of the directory content. Note that the
5750 character string may contain escape sequences (Section 7.1).
5751
5752 CREATED -
5753
5754 The creation date and time of the directory, represented in
5755 "YYYY-MM-DD HH:MM:SS" format
5756
5757 MODIFIED -
5758
5759 The date and time of the last modification of the directory,
5760 represented in "YYYY-MM-DD HH:MM:SS" format
5761
5762 The mentioned fields above don't have to be in particular order.
5763
5764
5765
5766
5767 Schoenebeck Expires January 16, 2016 [Page 103]
5768
5769 Internet-Draft LinuxSampler Control Protocol July 2015
5770
5771
5772 Example:
5773
5774 C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'"
5775
5776 S: "DESCRIPTION: Piano collection of instruments in GigaSampler
5777 format."
5778
5779 "CREATED: 2007-02-05 10:23:12"
5780
5781 "MODIFIED: 2007-04-07 12:50:21"
5782
5783 "."
5784
5785 6.8.6. Renaming an instrument directory
5786
5787 The front-end can alter the name of a specific instrument directory
5788 by sending the following command:
5789
5790 SET DB_INSTRUMENT_DIRECTORY NAME <dir> <name>
5791
5792 Where <dir> is the absolute path name of the directory and <name> is
5793 the new name for that directory.
5794
5795 Possible Answers:
5796
5797 "OK" -
5798
5799 on success
5800
5801 "ERR:<error-code>:<error-message>" -
5802
5803 in case the given directory does not exists, or if a directory
5804 with name equal to the new name already exists.
5805
5806 Example:
5807
5808 C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic'
5809 'Acoustic'"
5810
5811 S: "OK"
5812
5813 6.8.7. Moving an instrument directory
5814
5815 The front-end can move a specific instrument directory by sending the
5816 following command:
5817
5818
5819
5820
5821
5822
5823 Schoenebeck Expires January 16, 2016 [Page 104]
5824
5825 Internet-Draft LinuxSampler Control Protocol July 2015
5826
5827
5828 MOVE DB_INSTRUMENT_DIRECTORY <dir> <dst>
5829
5830 Where <dir> is the absolute path name of the directory to move and
5831 <dst> is the location where the directory will be moved to.
5832
5833 Possible Answers:
5834
5835 "OK" -
5836
5837 on success
5838
5839 "ERR:<error-code>:<error-message>" -
5840
5841 in case a given directory does not exists, or if a directory
5842 with name equal to the name of the specified directory already
5843 exists in the destination directory. Error is also thrown when
5844 trying to move a directory to a subdirectory of itself.
5845
5846 Example:
5847
5848 C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/
5849 Acoustic'"
5850
5851 S: "OK"
5852
5853 6.8.8. Copying instrument directories
5854
5855 The front-end can copy a specific instrument directory by sending the
5856 following command:
5857
5858 COPY DB_INSTRUMENT_DIRECTORY <dir> <dst>
5859
5860 Where <dir> is the absolute path name of the directory to copy and
5861 <dst> is the location where the directory will be copied to.
5862
5863 Possible Answers:
5864
5865 "OK" -
5866
5867 on success
5868
5869 "ERR:<error-code>:<error-message>" -
5870
5871 in case a given directory does not exists, or if a directory
5872 with name equal to the name of the specified directory already
5873 exists in the destination directory. Error is also thrown when
5874 trying to copy a directory to a subdirectory of itself.
5875
5876
5877
5878
5879 Schoenebeck Expires January 16, 2016 [Page 105]
5880
5881 Internet-Draft LinuxSampler Control Protocol July 2015
5882
5883
5884 Example:
5885
5886 C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic'
5887 '/Acoustic/Pianos'"
5888
5889 S: "OK"
5890
5891 6.8.9. Changing the description of directory
5892
5893 The front-end can alter the description of a specific instrument
5894 directory by sending the following command:
5895
5896 SET DB_INSTRUMENT_DIRECTORY DESCRIPTION <dir> <desc>
5897
5898 Where <dir> is the absolute path name of the directory and <desc> is
5899 the new description for the directory (encapsulated into apostrophes,
5900 supporting escape sequences as described in chapter "Character Set
5901 and Escape Sequences (Section 7.1)").
5902
5903 Possible Answers:
5904
5905 "OK" -
5906
5907 on success
5908
5909 "ERR:<error-code>:<error-message>" -
5910
5911 in case the given directory does not exists.
5912
5913 Example:
5914
5915 C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A
5916 collection of piano instruments in various format.'"
5917
5918 S: "OK"
5919
5920 6.8.10. Finding directories
5921
5922 The front-end can search for directories in specific directory by
5923 sending the following command:
5924
5925 FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] <dir> <criteria-
5926 list>
5927
5928 Where <dir> should be replaced by the absolute path name of the
5929 directory to search in. If NON_RECURSIVE is specified, the
5930 directories located in subdirectories of the specified directory will
5931 not be searched. <criteria-list> is a list of search criterias in
5932
5933
5934
5935 Schoenebeck Expires January 16, 2016 [Page 106]
5936
5937 Internet-Draft LinuxSampler Control Protocol July 2015
5938
5939
5940 form of "key1=val1 key2=val2 ...". The following criterias are
5941 allowed:
5942
5943 NAME='<search-string>'
5944
5945 Restricts the search to directories, which names satisfy the
5946 supplied search string (encapsulated into apostrophes, supporting
5947 escape sequences as described in chapter "Character Set and Escape
5948 Sequences (Section 7.1)").
5949
5950 CREATED='[<date-after>]..[<date-before>]'
5951
5952 Restricts the search to directories, which creation date satisfies
5953 the specified period, where <date-after> and <date-before> are in
5954 "YYYY-MM-DD HH:MM:SS" format. If <date-after> is omitted the
5955 search is restricted to directories created before <date-before>.
5956 If <date-before> is omitted, the search is restricted to
5957 directories created after <date-after>.
5958
5959 MODIFIED='[<date-after>]..[<date-before>]'
5960
5961 Restricts the search to directories, which date of last
5962 modification satisfies the specified period, where <date-after>
5963 and <date-before> are in "YYYY-MM-DD HH:MM:SS" format. If <date-
5964 after> is omitted the search is restricted to directories, which
5965 are last modified before <date-before>. If <date-before> is
5966 omitted, the search is restricted to directories, which are last
5967 modified after <date-after>.
5968
5969 DESCRIPTION='<search-string>'
5970
5971 Restricts the search to directories with description that
5972 satisfies the supplied search string (encapsulated into
5973 apostrophes, supporting escape sequences as described in chapter
5974 "Character Set and Escape Sequences (Section 7.1)").
5975
5976 Where <search-string> is either a regular expression, or a word list
5977 separated with spaces for OR search and with '+' for AND search.
5978
5979 Possible Answers:
5980
5981 A comma separated list with the absolute path names (encapsulated
5982 into apostrophes) of all directories in the specified directory
5983 that satisfy the supplied search criterias.
5984
5985 "ERR:<error-code>:<error-message>" -
5986
5987
5988
5989
5990
5991 Schoenebeck Expires January 16, 2016 [Page 107]
5992
5993 Internet-Draft LinuxSampler Control Protocol July 2015
5994
5995
5996 if the given directory does not exist.
5997
5998 Example:
5999
6000 C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'"
6001
6002 S: "'/Piano Collection'"
6003
6004 C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:
6005 30:13'"
6006
6007 S: "'/Piano Collection','/Percussions'"
6008
6009 6.8.11. Adding instruments to the instruments database
6010
6011 The front-end can add one or more instruments to the instruments
6012 database by sending the following command:
6013
6014 ADD DB_INSTRUMENTS [NON_MODAL] [<mode>[ FILE_AS_DIR]] <db_dir>
6015 <file_path> [<instr_index>]
6016
6017 Where <db_dir> is the absolute path name of a directory (encapsulated
6018 into apostrophes) in the instruments database in which only the new
6019 instruments (that are not already in the database) will be added,
6020 <file_path> is the absolute path name of a file or directory in the
6021 file system (encapsulated into apostrophes). In case an instrument
6022 file is supplied, only the instruments in the specified file will be
6023 added to the instruments database. If the optional <instr_index>
6024 (the index of the instrument within the given file) is supplied too,
6025 then only the specified instrument will be added. In case a
6026 directory is supplied, the instruments in that directory will be
6027 added. The OPTIONAL <mode> argument is only applied when a directory
6028 is provided as <file_path> and specifies how the scanning will be
6029 done and has exactly the following possibilities:
6030
6031 "RECURSIVE" -
6032
6033 All instruments will be processed, including those in the
6034 subdirectories, and the respective subdirectory tree structure
6035 will be recreated in the instruments database
6036
6037 "NON_RECURSIVE" -
6038
6039 Only the instruments in the specified directory will be added,
6040 the instruments in the subdirectories will not be processed.
6041
6042
6043
6044
6045
6046
6047 Schoenebeck Expires January 16, 2016 [Page 108]
6048
6049 Internet-Draft LinuxSampler Control Protocol July 2015
6050
6051
6052 "FLAT" -
6053
6054 All instruments will be processed, including those in the
6055 subdirectories, but the respective subdirectory structure will
6056 not be recreated in the instruments database. All instruments
6057 will be added directly in the specified database directory.
6058
6059 If FILE_AS_DIR argument is supplied, all instruments in an instrument
6060 file will be added to a separate directory in the instruments
6061 database, which name will be the name of the instrument file with the
6062 file extension stripped off.
6063
6064 The difference between regular and NON_MODAL versions of the command
6065 is that the regular command returns when the scanning is finished
6066 while NON_MODAL version returns immediately and a background process
6067 is launched. The GET DB_INSTRUMENTS_JOB INFO (Section 6.8.21)
6068 command can be used to monitor the scanning progress.
6069
6070 Possible Answers:
6071
6072 "OK" -
6073
6074 on success when NON_MODAL is not supplied
6075
6076 "OK[<job-id>]" -
6077
6078 on success when NON_MODAL is supplied, where <job-id> is a
6079 numerical ID used to obtain status information about the job
6080 progress. See GET DB_INSTRUMENTS_JOB INFO (Section 6.8.21)
6081
6082 "ERR:<error-code>:<error-message>" -
6083
6084 if an invalid path is specified.
6085
6086 Examples:
6087
6088 C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI
6089 Bosendorfer 290.gig' 0"
6090
6091 S: "OK"
6092
6093 6.8.12. Removing an instrument
6094
6095 The front-end can remove a particular instrument from the instruments
6096 database by sending the following command:
6097
6098
6099
6100
6101
6102
6103 Schoenebeck Expires January 16, 2016 [Page 109]
6104
6105 Internet-Draft LinuxSampler Control Protocol July 2015
6106
6107
6108 REMOVE DB_INSTRUMENT <instr_path>
6109
6110 Where <instr_path> is the absolute path name (in the instruments
6111 database) of the instrument to remove.
6112
6113 Possible Answers:
6114
6115 "OK" -
6116
6117 if the instrument is removed successfully
6118
6119 "ERR:<error-code>:<error-message>" -
6120
6121 if the given path does not exist or is a directory.
6122
6123 Examples:
6124
6125 C: "REMOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'"
6126
6127 S: "OK"
6128
6129 6.8.13. Getting amount of instruments
6130
6131 The front-end can retrieve the current amount of instruments in a
6132 specific directory by sending the following command:
6133
6134 GET DB_INSTRUMENTS [RECURSIVE] <dir>
6135
6136 Where <dir> should be replaced by the absolute path name of the
6137 directory. If RECURSIVE is specified, the number of all instruments,
6138 including those located in subdirectories of the specified directory,
6139 will be returned.
6140
6141 Possible Answers:
6142
6143 The current number of instruments in the specified directory.
6144
6145 "ERR:<error-code>:<error-message>" -
6146
6147 if the given directory does not exist.
6148
6149 Example:
6150
6151 C: "GET DB_INSTRUMENTS '/Piano Collection'"
6152
6153 S: "2"
6154
6155
6156
6157
6158
6159 Schoenebeck Expires January 16, 2016 [Page 110]
6160
6161 Internet-Draft LinuxSampler Control Protocol July 2015
6162
6163
6164 6.8.14. Listing all instruments in specific directory
6165
6166 The front-end can retrieve the current list of instruments in
6167 specific directory by sending the following command:
6168
6169 LIST DB_INSTRUMENTS [RECURSIVE] <dir>
6170
6171 Where <dir> should be replaced by the absolute path name of the
6172 directory. If RECURSIVE is specified, the absolute path names of all
6173 instruments, including those located in subdirectories of the
6174 specified directory, will be returned.
6175
6176 Possible Answers:
6177
6178 A comma separated list of all instruments (encapsulated into
6179 apostrophes) in the specified directory.
6180
6181 "ERR:<error-code>:<error-message>" -
6182
6183 if the given directory does not exist.
6184
6185 Example:
6186
6187 C: "LIST DB_INSTRUMENTS '/Piano Collection'"
6188
6189 S: "'Bosendorfer 290','Steinway D'"
6190
6191 C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'"
6192
6193 S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/
6194 Steinway D','/Piano Collection/Lite/Free Piano'"
6195
6196 6.8.15. Getting instrument information
6197
6198 The front-end can ask for the current settings of an instrument by
6199 sending the following command:
6200
6201 GET DB_INSTRUMENT INFO <instr_path>
6202
6203 Where <instr_path> should be replaced by the absolute path name of
6204 the instrument the front-end is interested in.
6205
6206 Possible Answers:
6207
6208 LinuxSampler will answer by sending a <CRLF> separated list. Each
6209 answer line begins with the settings category name followed by a
6210 colon and then a space character <SP> and finally the info
6211 character string to that setting category. At the moment the
6212
6213
6214
6215 Schoenebeck Expires January 16, 2016 [Page 111]
6216
6217 Internet-Draft LinuxSampler Control Protocol July 2015
6218
6219
6220 following categories are defined:
6221
6222
6223
6224 INSTRUMENT_FILE -
6225
6226 File name of the instrument. Note that the character string
6227 may contain escape sequences (Section 7.1).
6228
6229 INSTRUMENT_NR -
6230
6231 Index of the instrument within the file.
6232
6233 FORMAT_FAMILY -
6234
6235 The format family of the instrument.
6236
6237 FORMAT_VERSION -
6238
6239 The format version of the instrument.
6240
6241 SIZE -
6242
6243 The size of the instrument in bytes.
6244
6245 CREATED -
6246
6247 The date and time when the instrument is added in the
6248 instruments database, represented in "YYYY-MM-DD HH:MM:SS"
6249 format
6250
6251 MODIFIED -
6252
6253 The date and time of the last modification of the
6254 instrument's database settings, represented in "YYYY-MM-DD
6255 HH:MM:SS" format
6256
6257 DESCRIPTION -
6258
6259 A brief description of the instrument. Note that the
6260 character string may contain escape sequences (Section 7.1).
6261
6262 IS_DRUM -
6263
6264 either true or false, determines whether the instrument is a
6265 drumkit or a chromatic instrument
6266
6267
6268
6269
6270
6271 Schoenebeck Expires January 16, 2016 [Page 112]
6272
6273 Internet-Draft LinuxSampler Control Protocol July 2015
6274
6275
6276 PRODUCT -
6277
6278 The product title of the instrument. Note that the
6279 character string may contain escape sequences (Section 7.1).
6280
6281 ARTISTS -
6282
6283 Lists the artist names. Note that the character string may
6284 contain escape sequences (Section 7.1).
6285
6286 KEYWORDS -
6287
6288 Provides a list of keywords that refer to the instrument.
6289 Keywords are separated with semicolon and blank. Note that
6290 the character string may contain escape sequences
6291 (Section 7.1).
6292
6293 The mentioned fields above don't have to be in particular order.
6294
6295 Example:
6296
6297 C: "GET DB_INSTRUMENT INFO '/Piano Collection/Bosendorfer 290'"
6298
6299 S: "INSTRUMENT_FILE: /home/me/gigs/Bosendorfer 290.gig"
6300
6301 "INSTRUMENT_NR: 0"
6302
6303 "FORMAT_FAMILY: GIG"
6304
6305 "FORMAT_VERSION: 2"
6306
6307 "SIZE: 2050871870"
6308
6309 "CREATED: 2007-02-05 10:23:12"
6310
6311 "MODIFIED: 2007-04-07 12:50:21"
6312
6313 "DESCRIPTION: "
6314
6315 "IS_DRUM: false"
6316
6317 "PRODUCT: GRANDIOSO Bosendorfer 290"
6318
6319 "ARTISTS: Post Musical Instruments"
6320
6321 "KEYWORDS: Bosendorfer"
6322
6323
6324
6325
6326
6327 Schoenebeck Expires January 16, 2016 [Page 113]
6328
6329 Internet-Draft LinuxSampler Control Protocol July 2015
6330
6331
6332 "."
6333
6334 6.8.16. Renaming an instrument
6335
6336 The front-end can alter the name of a specific instrument by sending
6337 the following command:
6338
6339 SET DB_INSTRUMENT NAME <instr> <name>
6340
6341 Where <instr> is the absolute path name of the instrument and <name>
6342 is the new name for that instrument.
6343
6344 Possible Answers:
6345
6346 "OK" -
6347
6348 on success
6349
6350 "ERR:<error-code>:<error-message>" -
6351
6352 in case the given instrument does not exists, or if an
6353 instrument with name equal to the new name already exists.
6354
6355 Example:
6356
6357 C: "SET DB_INSTRUMENT NAME '/Piano Collection/Bosendorfer'
6358 'Bosendorfer 290'"
6359
6360 S: "OK"
6361
6362 6.8.17. Moving an instrument
6363
6364 The front-end can move a specific instrument to another directory by
6365 sending the following command:
6366
6367 MOVE DB_INSTRUMENT <instr> <dst>
6368
6369 Where <instr> is the absolute path name of the instrument to move and
6370 <dst> is the directory where the instrument will be moved to.
6371
6372 Possible Answers:
6373
6374 "OK" -
6375
6376 on success
6377
6378
6379
6380
6381
6382
6383 Schoenebeck Expires January 16, 2016 [Page 114]
6384
6385 Internet-Draft LinuxSampler Control Protocol July 2015
6386
6387
6388 "ERR:<error-code>:<error-message>" -
6389
6390 in case the given instrument does not exists, or if an
6391 instrument with name equal to the name of the specified
6392 instrument already exists in the destination directory.
6393
6394 Example:
6395
6396 C: "MOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Piano
6397 Collection/Acoustic'"
6398
6399 S: "OK"
6400
6401 6.8.18. Copying instruments
6402
6403 The front-end can copy a specific instrument to another directory by
6404 sending the following command:
6405
6406 COPY DB_INSTRUMENT <instr> <dst>
6407
6408 Where <instr> is the absolute path name of the instrument to copy and
6409 <dst> is the directory where the instrument will be copied to.
6410
6411 Possible Answers:
6412
6413 "OK" -
6414
6415 on success
6416
6417 "ERR:<error-code>:<error-message>" -
6418
6419 in case the given instrument does not exists, or if an
6420 instrument with name equal to the name of the specified
6421 instrument already exists in the destination directory.
6422
6423 Example:
6424
6425 C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'
6426 '/Acoustic/Pianos/'"
6427
6428 S: "OK"
6429
6430 6.8.19. Changing the description of instrument
6431
6432 The front-end can alter the description of a specific instrument by
6433 sending the following command:
6434
6435
6436
6437
6438
6439 Schoenebeck Expires January 16, 2016 [Page 115]
6440
6441 Internet-Draft LinuxSampler Control Protocol July 2015
6442
6443
6444 SET DB_INSTRUMENT DESCRIPTION <instr> <desc>
6445
6446 Where <instr> is the absolute path name of the instrument and <desc>
6447 is the new description for the instrument (encapsulated into
6448 apostrophes, supporting escape sequences as described in chapter
6449 "Character Set and Escape Sequences (Section 7.1)").
6450
6451 Possible Answers:
6452
6453 "OK" -
6454
6455 on success
6456
6457 "ERR:<error-code>:<error-message>" -
6458
6459 in case the given instrument does not exists.
6460
6461 Example:
6462
6463 C: "SET DB_INSTRUMENT DESCRIPTION '/Piano Collection/Acoustic/
6464 Bosendorfer 290' 'No comment :)'"
6465
6466 S: "OK"
6467
6468 6.8.20. Finding instruments
6469
6470 The front-end can search for instruments in specific directory by
6471 sending the following command:
6472
6473 FIND DB_INSTRUMENTS [NON_RECURSIVE] <dir> <criteria-list>
6474
6475 Where <dir> should be replaced by the absolute path name of the
6476 directory to search in. If NON_RECURSIVE is specified, the
6477 directories located in subdirectories of the specified directory will
6478 not be searched. <criteria-list> is a list of search criterias in
6479 form of "key1=val1 key2=val2 ...". The following criterias are
6480 allowed:
6481
6482 NAME='<search-string>'
6483
6484 Restricts the search to instruments, which names satisfy the
6485 supplied search string (encapsulated into apostrophes, supporting
6486 escape sequences as described in chapter "Character Set and Escape
6487 Sequences (Section 7.1)").
6488
6489 SIZE=[<min>]..[<max>]
6490
6491
6492
6493
6494
6495 Schoenebeck Expires January 16, 2016 [Page 116]
6496
6497 Internet-Draft LinuxSampler Control Protocol July 2015
6498
6499
6500 Restricts the search to instruments, which size is in the
6501 specified range. If <min> is omitted, the search results are
6502 restricted to instruments with size less then or equal to <max>.
6503 If <max> is omitted, the search is restricted to instruments with
6504 size greater then or equal to <min>.
6505
6506 CREATED='[<date-after>]..[<date-before>]'
6507
6508 Restricts the search to instruments, which creation date satisfies
6509 the specified period, where <date-after> and <date-before> are in
6510 "YYYY-MM-DD HH:MM:SS" format. If <date-after> is omitted the
6511 search is restricted to instruments created before <date-before>.
6512 If <date-before> is omitted, the search is restricted to
6513 instruments created after <date-after>.
6514
6515 MODIFIED='[<date-after>]..[<date-before>]'
6516
6517 Restricts the search to instruments, which date of last
6518 modification satisfies the specified period, where <date-after>
6519 and <date-before> are in "YYYY-MM-DD HH:MM:SS" format. If <date-
6520 after> is omitted the search is restricted to instruments, which
6521 are last modified before <date-before>. If <date-before> is
6522 omitted, the search is restricted to instruments, which are last
6523 modified after <date-after>.
6524
6525 DESCRIPTION='<search-string>'
6526
6527 Restricts the search to instruments with description that
6528 satisfies the supplied search string (encapsulated into
6529 apostrophes, supporting escape sequences as described in chapter
6530 "Character Set and Escape Sequences (Section 7.1)").
6531
6532 PRODUCT='<search-string>'
6533
6534 Restricts the search to instruments with product info that
6535 satisfies the supplied search string (encapsulated into
6536 apostrophes, supporting escape sequences as described in chapter
6537 "Character Set and Escape Sequences (Section 7.1)").
6538
6539 ARTISTS='<search-string>'
6540
6541 Restricts the search to instruments with artists info that
6542 satisfies the supplied search string (encapsulated into
6543 apostrophes, supporting escape sequences as described in chapter
6544 "Character Set and Escape Sequences (Section 7.1)").
6545
6546 KEYWORDS='<search-string>'
6547
6548
6549
6550
6551 Schoenebeck Expires January 16, 2016 [Page 117]
6552
6553 Internet-Draft LinuxSampler Control Protocol July 2015
6554
6555
6556 Restricts the search to instruments with keyword list that
6557 satisfies the supplied search string (encapsulated into
6558 apostrophes, supporting escape sequences as described in chapter
6559 "Character Set and Escape Sequences (Section 7.1)").
6560
6561 IS_DRUM=true | false
6562
6563 Either true or false. Restricts the search to drum kits or
6564 chromatic instruments.
6565
6566 FORMAT_FAMILIES='<format-list>'
6567
6568 Restricts the search to instruments of the supplied format
6569 families, where <format-list> is a comma separated list of format
6570 families.
6571
6572 Where <search-string> is either a regular expression, or a word list
6573 separated with spaces for OR search and with '+' for AND search.
6574
6575 Possible Answers:
6576
6577 A comma separated list with the absolute path names (encapsulated
6578 into apostrophes) of all instruments in the specified directory
6579 that satisfy the supplied search criterias.
6580
6581 "ERR:<error-code>:<error-message>" -
6582
6583 if the given directory does not exist.
6584
6585 Example:
6586
6587 C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+
6588 290'"
6589
6590 S: "'/Piano Collection/Bosendorfer 290'"
6591
6592 C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01
6593 09:30:13..'"
6594
6595 S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/
6596 Steinway D'"
6597
6598 6.8.21. Getting job status information
6599
6600 The front-end can ask for the current status of a particular database
6601 instruments job by sending the following command:
6602
6603
6604
6605
6606
6607 Schoenebeck Expires January 16, 2016 [Page 118]
6608
6609 Internet-Draft LinuxSampler Control Protocol July 2015
6610
6611
6612 GET DB_INSTRUMENTS_JOB INFO <job-id>
6613
6614 Where <job-id> should be replaced by the numerical ID of the job the
6615 front-end is interested in.
6616
6617 Possible Answers:
6618
6619 LinuxSampler will answer by sending a <CRLF> separated list. Each
6620 answer line begins with the settings category name followed by a
6621 colon and then a space character <SP> and finally the info
6622 character string to that setting category. At the moment the
6623 following categories are defined:
6624
6625
6626
6627 FILES_TOTAL -
6628
6629 The total number of files scheduled for scanning
6630
6631 FILES_SCANNED -
6632
6633 The current number of scanned files
6634
6635 SCANNING -
6636
6637 The absolute path name of the file which is currently being
6638 scanned
6639
6640 STATUS -
6641
6642 An integer value between 0 and 100 indicating the scanning
6643 progress percentage of the file which is currently being
6644 scanned
6645
6646 The mentioned fields above don't have to be in particular order.
6647
6648 Example:
6649
6650 C: "GET DB_INSTRUMENTS_JOB INFO 2"
6651
6652 S: "FILES_TOTAL: 12"
6653
6654 "FILES_SCANNED: 7"
6655
6656 "SCANNING: /home/me/gigs/Bosendorfer 290.gig"
6657
6658 "STATUS: 42"
6659
6660
6661
6662
6663 Schoenebeck Expires January 16, 2016 [Page 119]
6664
6665 Internet-Draft LinuxSampler Control Protocol July 2015
6666
6667
6668 "."
6669
6670 6.8.22. Formatting the instruments database
6671
6672 The front-end can remove all instruments and directories and re-
6673 create the instruments database structure (e.g., in case of a
6674 database corruption) by sending the following command:
6675
6676 FORMAT INSTRUMENTS_DB
6677
6678 Possible Answers:
6679
6680 "OK" -
6681
6682 on success
6683
6684 "ERR:<error-code>:<error-message>" -
6685
6686 If the formatting of the instruments database failed.
6687
6688 6.8.23. Checking for lost instrument files
6689
6690 The front-end can retrieve the list of all instrument files in the
6691 instruments database that don't exist in the filesystem by sending
6692 the following command:
6693
6694 FIND LOST DB_INSTRUMENT_FILES
6695
6696 Possible Answers:
6697
6698 A comma separated list with the absolute path names (encapsulated
6699 into apostrophes) of all lost instrument files.
6700
6701 "ERR:<error-code>:<error-message>" -
6702
6703 in case it failed, providing an appropriate error code and
6704 error message.
6705
6706 Example:
6707
6708 C: "FIND LOST DB_INSTRUMENT_FILES"
6709
6710 S: "'/gigs/Bosendorfer 290.gig','/gigs/Steinway D.gig','/gigs/Free
6711 Piano.gig'"
6712
6713
6714
6715
6716
6717
6718
6719 Schoenebeck Expires January 16, 2016 [Page 120]
6720
6721 Internet-Draft LinuxSampler Control Protocol July 2015
6722
6723
6724 6.8.24. Replacing an instrument file
6725
6726 The front-end can substitute all occurrences of an instrument file in
6727 the instruments database with a new one by sending the following
6728 command:
6729
6730 SET DB_INSTRUMENT FILE_PATH <old_path> <new_path>
6731
6732 Where <old_path> is the absolute path name of the instrument file to
6733 substitute with <new_path>.
6734
6735 Possible Answers:
6736
6737 "OK" -
6738
6739 on success
6740
6741 "ERR:<error-code>:<error-message>" -
6742
6743 in case it failed, providing an appropriate error code and
6744 error message.
6745
6746 Example:
6747
6748 C: "SET DB_INSTRUMENT FILE_PATH '/gigs/Bosendorfer 290.gig'
6749 '/gigs/pianos/Bosendorfer 290.gig'"
6750
6751 S: "OK"
6752
6753 6.9. Editing Instruments
6754
6755 The sampler allows to edit instruments while playing with the sampler
6756 by spawning an external (3rd party) instrument editor application for
6757 a given instrument. The 3rd party instrument editor applications
6758 have to place a respective plugin DLL file into the sampler's plugins
6759 directory. The sampler will automatically try to load all plugin
6760 DLLs in that directory on startup and only on startup!
6761
6762 At the moment there is only one command for this feature set, but
6763 this will most probably change in future.
6764
6765 6.9.1. Opening an appropriate instrument editor application
6766
6767 The front-end can request to open an appropriate instrument editor
6768 application by sending the following command:
6769
6770
6771
6772
6773
6774
6775 Schoenebeck Expires January 16, 2016 [Page 121]
6776
6777 Internet-Draft LinuxSampler Control Protocol July 2015
6778
6779
6780 EDIT CHANNEL INSTRUMENT <sampler-channel>
6781
6782 Where <sampler-channel> should be replaced by the number of the
6783 sampler channel as given by the "ADD CHANNEL" (Section 6.4.5) or
6784 "LIST CHANNELS" (Section 6.4.4) command.
6785
6786 The sampler will try to ask all registered instrument editors (or to
6787 be more specific: their sampler plugins) whether they are capable to
6788 handle the instrument on the given sampler channel. The sampler will
6789 simply use the first instrument editor application which replied with
6790 a positive answer and spawn that instrument editor application within
6791 the sampler's process and provide that application access to the
6792 instrument's data structures, so both applications can share and
6793 access the same instruments data at the same time, thus allowing to
6794 immediately hear changes with the sampler made by the instrument
6795 editor.
6796
6797 Note: consequently instrument editors are always spawned locally on
6798 the same machine where the sampler is running on!
6799
6800 Possible Answers:
6801
6802 "OK" -
6803
6804 when an appropriate instrument editor was launched
6805
6806 "WRN:<warning-code>:<warning-message>" -
6807
6808 when an appropriate instrument editor was launched, but there
6809 are noteworthy issues
6810
6811 "ERR:<error-code>:<error-message>" -
6812
6813 when an appropriate instrument editor could not be launched
6814
6815 Examples:
6816
6817 C: "EDIT CHANNEL INSTRUMENT 0"
6818
6819 S: "OK"
6820
6821 6.10. Managing Files
6822
6823 You can query detailed informations about files located at the same
6824 system where the sampler instance is running on. Using this command
6825 set allows to retrieve file informations even remotely from another
6826 machine.
6827
6828
6829
6830
6831 Schoenebeck Expires January 16, 2016 [Page 122]
6832
6833 Internet-Draft LinuxSampler Control Protocol July 2015
6834
6835
6836 6.10.1. Retrieving amount of instruments of a file
6837
6838 The front-end can retrieve the amount of instruments within a given
6839 instrument file by sending the following command:
6840
6841 GET FILE INSTRUMENTS <filename>
6842
6843 Where <filename> is the name of the instrument file (encapsulated
6844 into apostrophes, supporting escape sequences as described in chapter
6845 "Character Set and Escape Sequences (Section 7.1)").
6846
6847 The sampler will try to ask all sampler engines, whether they support
6848 the given file and ask the first engine with a positive answer for
6849 the amount of instruments.
6850
6851 Possible Answers:
6852
6853 On success, the sampler will answer by returning the amount of
6854 instruments.
6855
6856 "ERR:<error-code>:<error-message>" -
6857
6858 if the file could not be handled
6859
6860 Examples:
6861
6862 C: "GET FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"
6863
6864 S: "10"
6865
6866 6.10.2. Retrieving all instruments of a file
6867
6868 The front-end can retrieve a list of all instruments within a given
6869 instrument file by sending the following command:
6870
6871 LIST FILE INSTRUMENTS <filename>
6872
6873 Where <filename> is the name of the instrument file (encapsulated
6874 into apostrophes, supporting escape sequences as described in chapter
6875 "Character Set and Escape Sequences (Section 7.1)").
6876
6877 The sampler will try to ask all sampler engines, whether they support
6878 the given file and ask the first engine with a positive answer for a
6879 list of IDs for the instruments in the given file.
6880
6881 Possible Answers:
6882
6883
6884
6885
6886
6887 Schoenebeck Expires January 16, 2016 [Page 123]
6888
6889 Internet-Draft LinuxSampler Control Protocol July 2015
6890
6891
6892 On success, the sampler will answer by returning a comma separated
6893 list of instrument IDs.
6894
6895 "ERR:<error-code>:<error-message>" -
6896
6897 if the file could not be handled
6898
6899 Examples:
6900
6901 C: "LIST FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"
6902
6903 S: "0,1,2,3,4,5,6,7,8,9"
6904
6905 6.10.3. Retrieving informations about one instrument in a file
6906
6907 The front-end can retrieve detailed informations about a specific
6908 instrument within a given instrument file by sending the following
6909 command:
6910
6911 GET FILE INSTRUMENT INFO <filename> <instr-id>
6912
6913 Where <filename> is the name of the instrument file (encapsulated
6914 into apostrophes, supporting escape sequences as described in chapter
6915 "Character Set and Escape Sequences (Section 7.1)") and <instr-id> is
6916 the numeric instrument ID as returned by the "LIST FILE INSTRUMENTS"
6917 (Section 6.10.2) command.
6918
6919 The sampler will try to ask all sampler engines, whether they support
6920 the given file and ask the first engine with a positive answer for
6921 informations about the specific instrument in the given file.
6922
6923 Possible Answers:
6924
6925 LinuxSampler will answer by sending a <CRLF> separated list. Each
6926 answer line begins with the settings category name followed by a
6927 colon and then a space character <SP> and finally the info
6928 character string to that setting category. At the moment the
6929 following categories are defined:
6930
6931
6932
6933 NAME -
6934
6935 name of the instrument as stored in the instrument file
6936
6937 FORMAT_FAMILY -
6938
6939
6940
6941
6942
6943 Schoenebeck Expires January 16, 2016 [Page 124]
6944
6945 Internet-Draft LinuxSampler Control Protocol July 2015
6946
6947
6948 name of the sampler format of the given instrument
6949
6950 FORMAT_VERSION -
6951
6952 version of the sampler format the instrumen is stored as
6953
6954 PRODUCT -
6955
6956 official product name of the instrument as stored in the
6957 file
6958
6959 ARTISTS -
6960
6961 artists / sample library vendor of the instrument
6962
6963 KEY_BINDINGS -
6964
6965 comma separated list of integer values representing the
6966 instrument's key mapping in the range between 0 .. 127,
6967 reflecting the analog meaning of the MIDI specification.
6968
6969 KEYSWITCH_BINDINGS -
6970
6971 comma separated list of integer values representing the
6972 instrument's keyswitch mapping in the range between 0 ..
6973 127, reflecting the analog meaning of the MIDI
6974 specification.
6975
6976 The mentioned fields above don't have to be in particular order.
6977
6978 Example:
6979
6980 C: "GET FILE INSTRUMENT INFO 'D:/Sounds/Foo.gig' 0"
6981
6982 S: "NAME: Lunatic Loops"
6983
6984 "FORMAT_FAMILY: GIG"
6985
6986 "FORMAT_VERSION: 3"
6987
6988 "PRODUCT: The Backbone Bongo Beats"
6989
6990 "ARTISTS: Jimmy the Fish"
6991
6992 "."
6993
6994
6995
6996
6997
6998
6999 Schoenebeck Expires January 16, 2016 [Page 125]
7000
7001 Internet-Draft LinuxSampler Control Protocol July 2015
7002
7003
7004 6.11. Managing Effects
7005
7006 Audio effects (e.g. reverb, delay, compression) can be applied to the
7007 audio signals generated by the sampler. The sampler usually provides
7008 a set of internal audio effects for this task. The exact set of
7009 effects depends on the availability of third party effect plugins
7010 installed on the system where the sampler runs on.
7011
7012 At the moment only "send effects" are supported. Support for "insert
7013 effects" and "master effects" is planned to be added at a later
7014 point.
7015
7016 The following commands allow to retrieve the set of internal effects
7017 available to the sampler, detailed informations about those effects
7018 and to create and destroy instances of such effects. After an
7019 instance of an effect is created, the effect instance can be inserted
7020 into the audio signal path of the sampler, e.g. as send effect.
7021
7022 The sampler allows to create an arbitrary amount of so called send
7023 effect chains. Each effect chain can host an arbitrary amount of
7024 effect instances. The output of the first effect instance in an
7025 effect chain is fed to the input of the second effect instance of the
7026 chain and so on. So effects in one chain are processed sequentially.
7027 Send effect chains however are processed in parallel to other send
7028 effect chains. Audio signals of sampler channels are fed to send
7029 effects by creating FX sends to the respective sampler channel and
7030 assigning a destination send effect to that FX by using the "SET
7031 FX_SEND EFFECT" (Section 6.4.35) command. The latter allows to route
7032 the FX send to the beginning of a send effect chain, as well as
7033 directly to any other position of the send effect chain.
7034
7035 6.11.1. Retrieve amount of available effects
7036
7037 The front-end can retrieve the amount of internal effects, available
7038 to the sampler by sending the following command:
7039
7040 GET AVAILABLE_EFFECTS
7041
7042 Possible Answers:
7043
7044 The sampler will answer by returning the current number of effects
7045 available to the sampler.
7046
7047 Examples:
7048
7049 C: "GET AVAILABLE_EFFECTS"
7050
7051
7052
7053
7054
7055 Schoenebeck Expires January 16, 2016 [Page 126]
7056
7057 Internet-Draft LinuxSampler Control Protocol July 2015
7058
7059
7060 S: "129"
7061
7062 6.11.2. Get list of available effects
7063
7064 The set of available internal effects can change at runtime. The
7065 front-end can retrieve the list of internal effects, available to the
7066 sampler by sending the following command:
7067
7068 LIST AVAILABLE_EFFECTS
7069
7070 Possible Answers:
7071
7072 The sampler will answer by returning a comma separated list with
7073 numerical IDs of effects. Note: the numercial ID of an effect is
7074 generated by the sampler for the current moment. The numerical ID
7075 of the same effect can change at runtime, e.g. when the user
7076 requests a rescan of available effect plugins.
7077
7078 Example:
7079
7080 C: "LIST AVAILABLE_EFFECTS"
7081
7082 S: "5,6,7,120,121,122,123,124"
7083
7084 6.11.3. Retrieving general information about an effect
7085
7086 The front-end can ask for general informations about an effect by
7087 sending the following command:
7088
7089 GET EFFECT INFO <effect-index>
7090
7091 Where <effect-index> is the numerical ID of an effect as returned by
7092 the "LIST AVAILABLE_EFFECTS" (Section 6.11.2) command.
7093
7094 Possible Answers:
7095
7096 LinuxSampler will answer by sending a <CRLF> separated list. Each
7097 answer line begins with the effect information category name,
7098 followed by a colon and then a space character <SP> and finally
7099 the info character string to that effect information category. At
7100 the moment the following categories are defined:
7101
7102
7103
7104 SYSTEM -
7105
7106 name of the effect plugin system the effect is based on
7107 (e.g. "LADSPA")
7108
7109
7110
7111 Schoenebeck Expires January 16, 2016 [Page 127]
7112
7113 Internet-Draft LinuxSampler Control Protocol July 2015
7114
7115
7116 MODULE -
7117
7118 module of the effect plugin system that contains this
7119 effect, the module is usually the dynamic-linked library
7120 (DLL) filename of the effect plugin, including full path
7121 (note that this filename may contain escape sequences
7122 (Section 7.1))
7123
7124 NAME -
7125
7126 character string defining the unique name of the effect
7127 within its module (note that the character string may
7128 contain escape sequences (Section 7.1))
7129
7130 DESCRIPTION -
7131
7132 human readable name of the effect, intended to be displayed
7133 in user interfaces (note that the character string may
7134 contain escape sequences (Section 7.1))
7135
7136 The mentioned fields above don't have to be in particular order.
7137
7138 Example:
7139
7140 C: "GET EFFECT INFO 121"
7141
7142 S: "SYSTEM: LADSPA"
7143
7144 "MODULE: /usr/lib/ladspa/lowpass_iir_1891.so"
7145
7146 "NAME: lowpass_iir"
7147
7148 "DESCRIPTION: Glame Lowpass Filter"
7149
7150 "."
7151
7152 6.11.4. Creating an instance of an effect by its portable ID
7153
7154 The front-end can spawn an instance of the desired effect by sending
7155 the following command:
7156
7157 CREATE EFFECT_INSTANCE <effect-system> <module> <effect-name>
7158
7159 Where <effect-system> is the "SYSTEM" field, <module> the "MODULE"
7160 field and <effect-name> the "NAME" field as returned by the "GET
7161 EFFECT INFO" (Section 6.11.3) command. The filename of argument
7162 <module> and the character string of argument <effect-name> may
7163 contain escape sequences (Section 7.1).
7164
7165
7166
7167 Schoenebeck Expires January 16, 2016 [Page 128]
7168
7169 Internet-Draft LinuxSampler Control Protocol July 2015
7170
7171
7172 The sampler will try to load the requested effect and to create an
7173 instance of it. To allow loading the same effect on a different
7174 machine, probably even running a completely different operating
7175 system (e.g. Linux vs. Windows), the sampler tries to match <module>
7176 "softly". That means it first tries to find an effect that exactly
7177 matches the given <module> argument. If there is no exact match, the
7178 sampler will try to lower the restrictions on matching the <module>
7179 argument more and more, e.g. by ignoring upper / lower case
7180 differences and by ignoring the path of the DLL filename and file
7181 extension. If there is still no match at the end, the sampler will
7182 try to ignore the <module> argument completely and as a last resort
7183 search for an effect that only matches the given <effect-system> and
7184 <effect-name> arguments.
7185
7186 Possible Answers:
7187
7188 "OK[<effect-instance>]" -
7189
7190 in case the effect instance was successfully created, where
7191 <effect-instance> is the numerical ID of the new effect
7192 instance
7193
7194 "WRN:<warning-code>:<warning-message>" -
7195
7196 in case the effect instance was spawned successfully, but there
7197 are noteworthy issue(s) related, providing an appropriate
7198 warning code and warning message
7199
7200 "ERR:<error-code>:<error-message>" -
7201
7202 if the effect could not be instantiated
7203
7204 Examples:
7205
7206 C: "CREATE EFFECT_INSTANCE LADSPA '/usr/lib/ladspa/
7207 mod_delay_1419.so' 'modDelay'"
7208
7209 S: "OK[0]"
7210
7211 6.11.5. Creating an instance of an effect by its numerical ID
7212
7213 The front-end can spawn an instance of the desired effect by sending
7214 the following command:
7215
7216 CREATE EFFECT_INSTANCE <effect-index>
7217
7218 Where <effect-index> is the numerical ID of the effect as returned by
7219 the "LIST AVAILABLE_EFFECTS" (Section 6.11.2) command.
7220
7221
7222
7223 Schoenebeck Expires January 16, 2016 [Page 129]
7224
7225 Internet-Draft LinuxSampler Control Protocol July 2015
7226
7227
7228 The sampler will try to load the requested effect and to create an
7229 instance of it.
7230
7231 Note: Since the numerical ID of a certain effect can change at any
7232 time, you should not use this command in LSCP files to restore a
7233 certain effect at a later time! To store a sampler session including
7234 all its effects, use the portable text-based version of "CREATE
7235 EFFECT_INSTANCE" (Section 6.11.4) instead! This allows to restore a
7236 sampler session with all its effects also on other machines, possibly
7237 even running a completely different operating system (e.g. Linux vs.
7238 Windows), with different plugin directories or plugin DLL names.
7239
7240 Possible Answers:
7241
7242 "OK[<effect-instance>]" -
7243
7244 in case the effect instance was successfully created, where
7245 <effect-instance> is the numerical ID of the new effect
7246 instance
7247
7248 "WRN:<warning-code>:<warning-message>" -
7249
7250 in case the effect instance was spawned successfully, but there
7251 are noteworthy issue(s) related, providing an appropriate
7252 warning code and warning message
7253
7254 "ERR:<error-code>:<error-message>" -
7255
7256 if the effect could not be instantiated
7257
7258 Examples:
7259
7260 C: "CREATE EFFECT_INSTANCE 72"
7261
7262 S: "OK[5]"
7263
7264 6.11.6. Destroy an effect instance
7265
7266 The front-end can destroy an unusued effect instance and thus freeing
7267 it from memory by sending the following command:
7268
7269 DESTROY EFFECT_INSTANCE <effect-instance>
7270
7271 Where <effect-instance> is the numerical ID of the effect instance as
7272 returned by the "CREATE EFFECT_INSTANCE" (Section 6.11.4) or "LIST
7273 EFFECT_INSTANCES" (Section 6.11.8) command.
7274
7275 The effect instance can only be destroyed if it's not used in any
7276
7277
7278
7279 Schoenebeck Expires January 16, 2016 [Page 130]
7280
7281 Internet-Draft LinuxSampler Control Protocol July 2015
7282
7283
7284 part of the sampler's audio signal path anymore. If the effect
7285 instance is still in use somewhere, trying to destroy the effect
7286 instance will result in an error message.
7287
7288 Possible Answers:
7289
7290 "OK" -
7291
7292 in case the effect instance was successfully destroyed
7293
7294 "ERR:<error-code>:<error-message>" -
7295
7296 in case it failed, providing an appropriate error code and
7297 error message
7298
7299 Examples:
7300
7301 C: "DESTROY EFFECT_INSTANCE 5"
7302
7303 S: "OK"
7304
7305 6.11.7. Retrieve amount of effect instances
7306
7307 The front-end can retrieve the current amount of effect instances by
7308 sending the following command:
7309
7310 GET EFFECT_INSTANCES
7311
7312 Possible Answers:
7313
7314 The sampler will answer by returning the current number of effect
7315 instances created and not yet destroyed in the current sampler
7316 session.
7317
7318 Examples:
7319
7320 C: "GET EFFECT_INSTANCES"
7321
7322 S: "14"
7323
7324 6.11.8. Get list of effect instances
7325
7326 The front-end can retrieve the current list of effect instances by
7327 sending the following command:
7328
7329 LIST EFFECT_INSTANCES
7330
7331 Possible Answers:
7332
7333
7334
7335 Schoenebeck Expires January 16, 2016 [Page 131]
7336
7337 Internet-Draft LinuxSampler Control Protocol July 2015
7338
7339
7340 The sampler will answer by returning a comma separated list with
7341 numerical IDs of effects instances.
7342
7343 Example:
7344
7345 C: "LIST EFFECT_INSTANCES"
7346
7347 S: "9,11,14,15,16,17,25"
7348
7349 6.11.9. Retrieving current information about an effect instance
7350
7351 The front-end can ask for the current informations about a particular
7352 effect instance by sending the following command:
7353
7354 GET EFFECT_INSTANCE INFO <effect-instance>
7355
7356 Where <effect-instance> is the numerical ID of an effect instance as
7357 returned by the "CREATE EFFECT_INSTANCE" (Section 6.11.4) or "LIST
7358 EFFECT_INSTANCES" (Section 6.11.8) command.
7359
7360 Possible Answers:
7361
7362 LinuxSampler will answer by sending a <CRLF> separated list. Each
7363 answer line begins with the information category name, followed by
7364 a colon and then a space character <SP> and finally the info
7365 character string to that information category. At the moment the
7366 following categories are defined:
7367
7368
7369
7370 SYSTEM -
7371
7372 name of the effect plugin system the effect is based on
7373 (e.g. "LADSPA")
7374
7375 MODULE -
7376
7377 module of the effect plugin system that contains this
7378 effect, the module is usually the dynamic-linked library
7379 (DLL) filename of the effect plugin, including full path
7380 (note that this filename may contain escape sequences
7381 (Section 7.1))
7382
7383 NAME -
7384
7385 character string defining the unique name of the effect
7386 within its module (note that the character string may
7387 contain escape sequences (Section 7.1))
7388
7389
7390
7391 Schoenebeck Expires January 16, 2016 [Page 132]
7392
7393 Internet-Draft LinuxSampler Control Protocol July 2015
7394
7395
7396 DESCRIPTION -
7397
7398 human readable name of the effect, intended to be displayed
7399 in user interfaces (note that the character string may
7400 contain escape sequences (Section 7.1))
7401
7402 INPUT_CONTROLS -
7403
7404 amount of input controls the effect instance provides, to
7405 allow controlling the effect parameters in realtime
7406
7407 The mentioned fields above don't have to be in particular order.
7408
7409 Example:
7410
7411 C: "GET EFFECT_INSTANCE INFO 3"
7412
7413 S: "SYSTEM: LADSPA"
7414
7415 "MODULE: /usr/lib/ladspa/mod_delay_1419.so"
7416
7417 "NAME: modDelay"
7418
7419 "DESCRIPTION: Modulatable delay"
7420
7421 "INPUT_CONTROLS: 1"
7422
7423 "."
7424
7425 6.11.10. Retrieving information about an effect parameter
7426
7427 Effects typically provide a certain set of effect parameters which
7428 can be altered by the user in realtime (e.g. depth of a reverb
7429 effect, duration of a delay effect, dry / wet signal ratio). Those
7430 controllable effect parameters are called "input controls". The
7431 front-end can ask for the current informations of an effect
7432 instance's input control by sending the following command:
7433
7434 GET EFFECT_INSTANCE_INPUT_CONTROL INFO <effect-instance> <input-
7435 control>
7436
7437 Where <effect-instance> is the numerical ID of an effect instance as
7438 returned by the "CREATE EFFECT_INSTANCE" (Section 6.11.4) or "LIST
7439 EFFECT_INSTANCES" (Section 6.11.8) command and <input-control> is the
7440 index of the input control within the numerical bounds as returned by
7441 the "INPUT_CONTROLS" field of the "GET EFFECT_INSTANCE INFO"
7442 (Section 6.11.9) command.
7443
7444
7445
7446
7447 Schoenebeck Expires January 16, 2016 [Page 133]
7448
7449 Internet-Draft LinuxSampler Control Protocol July 2015
7450
7451
7452 Possible Answers:
7453
7454 LinuxSampler will answer by sending a <CRLF> separated list. Each
7455 answer line begins with the information category name, followed by
7456 a colon and then a space character <SP> and finally the info
7457 character string to that information category. There are
7458 information categories which are always returned, independent of
7459 the respective effect parameter and there are optional information
7460 categories which are only shown for certain effect parameters. At
7461 the moment the following categories are defined:
7462
7463
7464
7465 DESCRIPTION -
7466
7467 (always returned) human readable name of the effect
7468 parameter, intended to be displayed in user interfaces (note
7469 that the character string may contain escape sequences
7470 (Section 7.1))
7471
7472 VALUE -
7473
7474 (always returned) current (optional dotted) floating point
7475 value of this effect parameter
7476
7477 RANGE_MIN -
7478
7479 (optionally returned) minimum allowed value for this effect
7480 parameter
7481
7482 RANGE_MAX -
7483
7484 (optionally returned) maximum allowed value for this effect
7485 parameter
7486
7487 POSSIBILITIES -
7488
7489 (optionally returned) comma separated list of (optional
7490 dotted) floating point numbers, reflecting the exact set of
7491 possible values for this effect parameter
7492
7493 DEFAULT -
7494
7495 (optionally returned) default value of this effect parameter
7496
7497 The mentioned fields above don't have to be in particular order.
7498
7499 Example:
7500
7501
7502
7503 Schoenebeck Expires January 16, 2016 [Page 134]
7504
7505 Internet-Draft LinuxSampler Control Protocol July 2015
7506
7507
7508 C: "GET EFFECT_INSTANCE_INPUT_CONTROL INFO 1 0"
7509
7510 S: "DESCRIPTION: Base delay (s)"
7511
7512 "VALUE: 0.500"
7513
7514 "RANGE_MIN: 0.000"
7515
7516 "."
7517
7518 6.11.11. Altering an effect parameter
7519
7520 The front-end can alter the current value of an effect parameter by
7521 sending the following command:
7522
7523 SET EFFECT_INSTANCE_INPUT_CONTROL VALUE <effect-instance> <input-
7524 control> <value>
7525
7526 Where <effect-instance> is the numerical ID of the effect instance as
7527 returned by the "CREATE EFFECT_INSTANCE" (Section 6.11.4) or "LIST
7528 EFFECT_INSTANCES" (Section 6.11.8) command, <input-control> is the
7529 index of the input control within the numerical bounds as returned by
7530 the "INPUT_CONTROLS" field of the "GET EFFECT_INSTANCE INFO"
7531 (Section 6.11.9) command and <value> is the new (optional dotted)
7532 floating point value for this effect parameter.
7533
7534 Possible Answers:
7535
7536 "OK" -
7537
7538 in case the effect was altered successfully
7539
7540 "ERR:<error-code>:<error-message>" -
7541
7542 in case it failed, providing an appropriate error code and
7543 error message
7544
7545 Examples:
7546
7547 C: "SET EFFECT_INSTANCE_INPUT_CONTROL VALUE 0 1 0.5"
7548
7549 S: "OK"
7550
7551 6.11.12. Retrieve amount of send effect chains
7552
7553 The front-end can retrieve the current amount of send effect chains
7554 of an audio output device by sending the following command:
7555
7556
7557
7558
7559 Schoenebeck Expires January 16, 2016 [Page 135]
7560
7561 Internet-Draft LinuxSampler Control Protocol July 2015
7562
7563
7564 GET SEND_EFFECT_CHAINS <audio-device>
7565
7566 Where <audio-device> should be replaced by the numerical ID of the
7567 audio output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
7568 (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
7569 command.
7570
7571 Possible Answers:
7572
7573 The sampler will answer by returning the current number of send
7574 effect chains of the supplied audio output device.
7575
7576 Examples:
7577
7578 C: "GET SEND_EFFECT_CHAINS 0"
7579
7580 S: "4"
7581
7582 6.11.13. Retrieve list of send effect chains
7583
7584 The front-end can retrieve the current list of send effect chains of
7585 an audio output device by sending the following command:
7586
7587 LIST SEND_EFFECT_CHAINS <audio-device>
7588
7589 Where <audio-device> should be replaced by the numerical ID of the
7590 audio output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
7591 (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
7592 command.
7593
7594 Possible Answers:
7595
7596 The sampler will answer by returning a comma separated list with
7597 numerical IDs of send effect chains of the supplied audio output
7598 device.
7599
7600 Examples:
7601
7602 C: "LIST SEND_EFFECT_CHAINS 0"
7603
7604 S: "3,4,7"
7605
7606 6.11.14. Add send effect chain
7607
7608 The front-end can add a send effect chain by sending the following
7609 command:
7610
7611
7612
7613
7614
7615 Schoenebeck Expires January 16, 2016 [Page 136]
7616
7617 Internet-Draft LinuxSampler Control Protocol July 2015
7618
7619
7620 ADD SEND_EFFECT_CHAIN <audio-device>
7621
7622 Where <audio-device> should be replaced by the numerical ID of the
7623 audio output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
7624 (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
7625 command.
7626
7627 Possible Answers:
7628
7629 "OK[<effect-chain>]" -
7630
7631 in case the send effect chain was added successfully, where
7632 <effect-chain> is the numerical ID of the new send effect chain
7633
7634 "ERR:<error-code>:<error-message>" -
7635
7636 if the send effect chain could not be added
7637
7638 Examples:
7639
7640 C: "ADD SEND_EFFECT_CHAIN 0"
7641
7642 S: "OK[2]"
7643
7644 6.11.15. Remove send effect chain
7645
7646 The front-end can remove a send effect chain by sending the following
7647 command:
7648
7649 REMOVE SEND_EFFECT_CHAIN <audio-device> <effect-chain>
7650
7651 Where <audio-device> should be replaced by the numerical ID of the
7652 audio output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
7653 (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
7654 command and <effect-chain> by the numerical ID as returned by the
7655 "ADD SEND_EFFECT_CHAIN" (Section 6.11.14) or "LIST
7656 SEND_EFFECT_CHAINS" (Section 6.11.13) command.
7657
7658 Possible Answers:
7659
7660 "OK" -
7661
7662 in case the send effect chain was removed successfully
7663
7664 "ERR:<error-code>:<error-message>" -
7665
7666 if the send effect chain could not be removed
7667
7668
7669
7670
7671 Schoenebeck Expires January 16, 2016 [Page 137]
7672
7673 Internet-Draft LinuxSampler Control Protocol July 2015
7674
7675
7676 Examples:
7677
7678 C: "REMOVE SEND_EFFECT_CHAIN 0 2"
7679
7680 S: "OK"
7681
7682 6.11.16. Retrieving information about a send effect chain
7683
7684 The front-end can ask for informations of a send effect chain by
7685 sending the following command:
7686
7687 GET SEND_EFFECT_CHAIN INFO <audio-device> <effect-chain>
7688
7689 Where <audio-device> should be replaced by the numerical ID of the
7690 audio output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
7691 (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
7692 command and <effect-chain> by the numerical ID as returned by the
7693 "ADD SEND_EFFECT_CHAIN" (Section 6.11.14) or "LIST
7694 SEND_EFFECT_CHAINS" (Section 6.11.13) command.
7695
7696 Possible Answers:
7697
7698 LinuxSampler will answer by sending a <CRLF> separated list. Each
7699 answer line begins with the information category name, followed by
7700 a colon and then a space character <SP> and finally the info
7701 character string to that information category. At the moment the
7702 following categories are defined:
7703
7704
7705
7706 EFFECT_COUNT -
7707
7708 amount of effects in this send effect chain
7709
7710 EFFECT_SEQUENCE -
7711
7712 comma separated list of the numerical IDs of the effect
7713 instances in this send effect chain, in the order as they
7714 are procssed in the effect chain
7715
7716 The mentioned fields above don't have to be in particular order.
7717
7718 Example:
7719
7720 C: "GET SEND_EFFECT_CHAIN INFO 0 2"
7721
7722 S: "EFFECT_COUNT: 3"
7723
7724
7725
7726
7727 Schoenebeck Expires January 16, 2016 [Page 138]
7728
7729 Internet-Draft LinuxSampler Control Protocol July 2015
7730
7731
7732 "EFFECT_SEQUENCE: 31,4,7"
7733
7734 "."
7735
7736 6.11.17. Append effect instance to a send effect chain
7737
7738 The front-end can add an unused effect instance to the end of a send
7739 effect chain by sending the following command:
7740
7741 APPEND SEND_EFFECT_CHAIN EFFECT <audio-device> <effect-chain>
7742 <effect-instance>
7743
7744 Where <audio-device> should be replaced by the numerical ID of the
7745 audio output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
7746 (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
7747 command and <effect-chain> by the numerical ID as returned by the
7748 "ADD SEND_EFFECT_CHAIN" (Section 6.11.14) or "LIST
7749 SEND_EFFECT_CHAINS" (Section 6.11.13) command and <effect-instance>
7750 as returned by the "CREATE EFFECT_INSTANCE" (Section 6.11.4) or "LIST
7751 EFFECT_INSTANCES" (Section 6.11.8) command.
7752
7753 Only unused effect instances can be added to the effect chain.
7754 Trying to add an effect instance which is already in use somewhere in
7755 the audio signal path of the sampler will result in an error.
7756
7757 Possible Answers:
7758
7759 "OK" -
7760
7761 in case the effect instance was added successfully to the chain
7762
7763 "ERR:<error-code>:<error-message>" -
7764
7765 if the effect instance could not be added
7766
7767 Examples:
7768
7769 C: "APPEND SEND_EFFECT_CHAIN EFFECT 0 2 38"
7770
7771 S: "OK"
7772
7773 6.11.18. Insert effect instance to a send effect chain
7774
7775 The front-end can add an unused effect instance to a certain position
7776 of a send effect chain by sending the following command:
7777
7778
7779
7780
7781
7782
7783 Schoenebeck Expires January 16, 2016 [Page 139]
7784
7785 Internet-Draft LinuxSampler Control Protocol July 2015
7786
7787
7788 INSERT SEND_EFFECT_CHAIN EFFECT <audio-device> <effect-chain>
7789 <chain-pos> <effect-instance>
7790
7791 Where <audio-device> should be replaced by the numerical ID of the
7792 audio output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
7793 (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
7794 command, <effect-chain> by the numerical ID as returned by the "ADD
7795 SEND_EFFECT_CHAIN" (Section 6.11.14) or "LIST SEND_EFFECT_CHAINS"
7796 (Section 6.11.13) command, <effect-instance> as returned by the
7797 "CREATE EFFECT_INSTANCE" (Section 6.11.4) or "LIST EFFECT_INSTANCES"
7798 (Section 6.11.8) command and <chain-pos> the exact position of the
7799 effect chain where the supplied effect shall be inserted to.
7800
7801 Only unused effect instances can be added to the effect chain.
7802 Trying to add an effect instance which is already in use somewhere in
7803 the audio signal path of the sampler will result in an error.
7804
7805 Possible Answers:
7806
7807 "OK" -
7808
7809 in case the effect instance was added successfully to the chain
7810
7811 "ERR:<error-code>:<error-message>" -
7812
7813 if the effect instance could not be added
7814
7815 Examples:
7816
7817 C: "INSERT SEND_EFFECT_CHAIN EFFECT 0 2 4 38"
7818
7819 S: "OK"
7820
7821 6.11.19. Remove effect instance from send effect chain
7822
7823 The front-end can remove an effect instance from a certain position
7824 of a send effect chain by sending the following command:
7825
7826 REMOVE SEND_EFFECT_CHAIN EFFECT <audio-device> <effect-chain>
7827 <chain-pos>
7828
7829 Where <audio-device> should be replaced by the numerical ID of the
7830 audio output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
7831 (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
7832 command, <effect-chain> by the numerical ID as returned by the "ADD
7833 SEND_EFFECT_CHAIN" (Section 6.11.14) or "LIST SEND_EFFECT_CHAINS"
7834 (Section 6.11.13) command and <chain-pos> the exact position of the
7835 effect instance to be removed from the effect chain.
7836
7837
7838
7839 Schoenebeck Expires January 16, 2016 [Page 140]
7840
7841 Internet-Draft LinuxSampler Control Protocol July 2015
7842
7843
7844 Possible Answers:
7845
7846 "OK" -
7847
7848 in case the effect instance was removed successfully
7849
7850 "ERR:<error-code>:<error-message>" -
7851
7852 if the effect instance could not be removed
7853
7854 Examples:
7855
7856 C: "REMOVE SEND_EFFECT_CHAIN EFFECT 0 2 4"
7857
7858 S: "OK"
7859
7860
7861
7862
7863
7864
7865
7866
7867
7868
7869
7870
7871
7872
7873
7874
7875
7876
7877
7878
7879
7880
7881
7882
7883
7884
7885
7886
7887
7888
7889
7890
7891
7892
7893
7894
7895 Schoenebeck Expires January 16, 2016 [Page 141]
7896
7897 Internet-Draft LinuxSampler Control Protocol July 2015
7898
7899
7900 7. Command Syntax
7901
7902 The grammar of the control protocol as descibed in Section 6 is
7903 defined below using Backus-Naur Form (BNF as described in [RFC2234])
7904 where applicable.
7905
7906 input =
7907
7908 line
7909
7910 / error
7911
7912 line =
7913
7914 statement LF
7915
7916 / statement CR LF
7917
7918 statement =
7919
7920 /* epsilon (empty statement/line ignored) */
7921
7922 / comment
7923
7924 / command
7925
7926 comment =
7927
7928 '#'
7929
7930 / comment '#'
7931
7932 / comment SP
7933
7934 / comment number
7935
7936 / comment string
7937
7938 command =
7939
7940 ADD SP add_instruction
7941
7942 / MAP SP map_instruction
7943
7944 / UNMAP SP unmap_instruction
7945
7946 / GET SP get_instruction
7947
7948
7949
7950
7951 Schoenebeck Expires January 16, 2016 [Page 142]
7952
7953 Internet-Draft LinuxSampler Control Protocol July 2015
7954
7955
7956 / CREATE SP create_instruction
7957
7958 / DESTROY SP destroy_instruction
7959
7960 / LIST SP list_instruction
7961
7962 / LOAD SP load_instruction
7963
7964 / REMOVE SP remove_instruction
7965
7966 / SET SP set_instruction
7967
7968 / SUBSCRIBE SP subscribe_event
7969
7970 / UNSUBSCRIBE SP unsubscribe_event
7971
7972 / RESET SP reset_instruction
7973
7974 / CLEAR SP clear_instruction
7975
7976 / FIND SP find_instruction
7977
7978 / MOVE SP move_instruction
7979
7980 / COPY SP copy_instruction
7981
7982 / EDIT SP edit_instruction
7983
7984 / FORMAT SP format_instruction
7985
7986 / SEND SP send_instruction
7987
7988 / APPEND SP append_instruction
7989
7990 / INSERT SP insert_instruction
7991
7992 / RESET
7993
7994 / QUIT
7995
7996 add_instruction =
7997
7998 CHANNEL
7999
8000 / CHANNEL SP MIDI_INPUT SP sampler_channel SP device_index
8001
8002 / CHANNEL SP MIDI_INPUT SP sampler_channel SP device_index SP
8003 midi_input_port_index
8004
8005
8006
8007 Schoenebeck Expires January 16, 2016 [Page 143]
8008
8009 Internet-Draft LinuxSampler Control Protocol July 2015
8010
8011
8012 / DB_INSTRUMENT_DIRECTORY SP db_path
8013
8014 / DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename
8015
8016 / DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP FILE_AS_DIR SP
8017 db_path SP filename
8018
8019 / DB_INSTRUMENTS SP scan_mode SP db_path SP filename
8020
8021 / DB_INSTRUMENTS SP scan_mode SP FILE_AS_DIR SP db_path SP
8022 filename
8023
8024 / DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
8025
8026 / DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP
8027 instrument_index
8028
8029 / DB_INSTRUMENTS SP db_path SP filename
8030
8031 / DB_INSTRUMENTS SP db_path SP filename SP instrument_index
8032
8033 / MIDI_INSTRUMENT_MAP
8034
8035 / MIDI_INSTRUMENT_MAP SP map_name
8036
8037 / SEND_EFFECT_CHAIN SP device_index
8038
8039 subscribe_event =
8040
8041 AUDIO_OUTPUT_DEVICE_COUNT
8042
8043 / AUDIO_OUTPUT_DEVICE_INFO
8044
8045 / MIDI_INPUT_DEVICE_COUNT
8046
8047 / MIDI_INPUT_DEVICE_INFO
8048
8049 / CHANNEL_COUNT
8050
8051 / CHANNEL_MIDI
8052
8053 / DEVICE_MIDI
8054
8055 / VOICE_COUNT
8056
8057 / STREAM_COUNT
8058
8059
8060
8061
8062
8063 Schoenebeck Expires January 16, 2016 [Page 144]
8064
8065 Internet-Draft LinuxSampler Control Protocol July 2015
8066
8067
8068 / BUFFER_FILL
8069
8070 / CHANNEL_INFO
8071
8072 / FX_SEND_COUNT
8073
8074 / FX_SEND_INFO
8075
8076 / MIDI_INSTRUMENT_MAP_COUNT
8077
8078 / MIDI_INSTRUMENT_MAP_INFO
8079
8080 / MIDI_INSTRUMENT_COUNT
8081
8082 / MIDI_INSTRUMENT_INFO
8083
8084 / DB_INSTRUMENT_DIRECTORY_COUNT
8085
8086 / DB_INSTRUMENT_DIRECTORY_INFO
8087
8088 / DB_INSTRUMENT_COUNT
8089
8090 / DB_INSTRUMENT_INFO
8091
8092 / DB_INSTRUMENTS_JOB_INFO
8093
8094 / MISCELLANEOUS
8095
8096 / TOTAL_STREAM_COUNT
8097
8098 / TOTAL_VOICE_COUNT
8099
8100 / GLOBAL_INFO
8101
8102 / EFFECT_INSTANCE_COUNT
8103
8104 / EFFECT_INSTANCE_INFO
8105
8106 / SEND_EFFECT_CHAIN_COUNT
8107
8108 / SEND_EFFECT_CHAIN_INFO
8109
8110 unsubscribe_event =
8111
8112 AUDIO_OUTPUT_DEVICE_COUNT
8113
8114 / AUDIO_OUTPUT_DEVICE_INFO
8115
8116
8117
8118
8119 Schoenebeck Expires January 16, 2016 [Page 145]
8120
8121 Internet-Draft LinuxSampler Control Protocol July 2015
8122
8123
8124 / MIDI_INPUT_DEVICE_COUNT
8125
8126 / MIDI_INPUT_DEVICE_INFO
8127
8128 / CHANNEL_COUNT
8129
8130 / CHANNEL_MIDI
8131
8132 / DEVICE_MIDI
8133
8134 / VOICE_COUNT
8135
8136 / STREAM_COUNT
8137
8138 / BUFFER_FILL
8139
8140 / CHANNEL_INFO
8141
8142 / FX_SEND_COUNT
8143
8144 / FX_SEND_INFO
8145
8146 / MIDI_INSTRUMENT_MAP_COUNT
8147
8148 / MIDI_INSTRUMENT_MAP_INFO
8149
8150 / MIDI_INSTRUMENT_COUNT
8151
8152 / MIDI_INSTRUMENT_INFO
8153
8154 / DB_INSTRUMENT_DIRECTORY_COUNT
8155
8156 / DB_INSTRUMENT_DIRECTORY_INFO
8157
8158 / DB_INSTRUMENT_COUNT
8159
8160 / DB_INSTRUMENT_INFO
8161
8162 / DB_INSTRUMENTS_JOB_INFO
8163
8164 / MISCELLANEOUS
8165
8166 / TOTAL_STREAM_COUNT
8167
8168 / TOTAL_VOICE_COUNT
8169
8170 / GLOBAL_INFO
8171
8172
8173
8174
8175 Schoenebeck Expires January 16, 2016 [Page 146]
8176
8177 Internet-Draft LinuxSampler Control Protocol July 2015
8178
8179
8180 / EFFECT_INSTANCE_COUNT
8181
8182 / EFFECT_INSTANCE_INFO
8183
8184 / SEND_EFFECT_CHAIN_COUNT
8185
8186 / SEND_EFFECT_CHAIN_INFO
8187
8188 map_instruction =
8189
8190 MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP
8191 engine_name SP filename SP instrument_index SP volume_value
8192
8193 / MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog
8194 SP engine_name SP filename SP instrument_index SP volume_value SP
8195 instr_load_mode
8196
8197 / MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog
8198 SP engine_name SP filename SP instrument_index SP volume_value SP
8199 entry_name
8200
8201 / MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog
8202 SP engine_name SP filename SP instrument_index SP volume_value SP
8203 instr_load_mode SP entry_name
8204
8205 unmap_instruction =
8206
8207 MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog
8208
8209 remove_instruction =
8210
8211 CHANNEL SP sampler_channel
8212
8213 / CHANNEL SP MIDI_INPUT SP sampler_channel
8214
8215 / CHANNEL SP MIDI_INPUT SP sampler_channel SP device_index
8216
8217 / CHANNEL SP MIDI_INPUT SP sampler_channel SP device_index SP
8218 midi_input_port_index
8219
8220 / MIDI_INSTRUMENT_MAP SP midi_map
8221
8222 / MIDI_INSTRUMENT_MAP SP ALL
8223
8224 / SEND_EFFECT_CHAIN SP device_index SP effect_chain
8225
8226 / SEND_EFFECT_CHAIN SP EFFECT SP device_index SP effect_chain SP
8227 chain_pos
8228
8229
8230
8231 Schoenebeck Expires January 16, 2016 [Page 147]
8232
8233 Internet-Draft LinuxSampler Control Protocol July 2015
8234
8235
8236 / FX_SEND SP EFFECT SP sampler_channel SP fx_send_id
8237
8238 / DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path
8239
8240 / DB_INSTRUMENT_DIRECTORY SP db_path
8241
8242 / DB_INSTRUMENT SP db_path
8243
8244 get_instruction =
8245
8246 AVAILABLE_ENGINES
8247
8248 / AVAILABLE_EFFECTS
8249
8250 / EFFECT_INSTANCES
8251
8252 / EFFECT SP INFO SP effect_index
8253
8254 / EFFECT_INSTANCE SP INFO SP effect_instance
8255
8256 / EFFECT_INSTANCE_INPUT_CONTROL SP INFO SP effect_instance SP
8257 input_control
8258
8259 / SEND_EFFECT_CHAINS SP device_index
8260
8261 / SEND_EFFECT_CHAIN SP INFO SP device_index SP effect_chain
8262
8263 / AVAILABLE_MIDI_INPUT_DRIVERS
8264
8265 / MIDI_INPUT_DRIVER SP INFO SP string
8266
8267 / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
8268
8269 / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP
8270 key_val_list
8271
8272 / AVAILABLE_AUDIO_OUTPUT_DRIVERS
8273
8274 / AUDIO_OUTPUT_DRIVER SP INFO SP string
8275
8276 / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
8277
8278 / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP
8279 key_val_list
8280
8281 / AUDIO_OUTPUT_DEVICES
8282
8283
8284
8285
8286
8287 Schoenebeck Expires January 16, 2016 [Page 148]
8288
8289 Internet-Draft LinuxSampler Control Protocol July 2015
8290
8291
8292 / MIDI_INPUT_DEVICES
8293
8294 / AUDIO_OUTPUT_DEVICE SP INFO SP number
8295
8296 / MIDI_INPUT_DEVICE SP INFO SP number
8297
8298 / MIDI_INPUT_PORT SP INFO SP number SP number
8299
8300 / MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
8301
8302 / AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
8303
8304 / AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP
8305 string
8306
8307 / CHANNELS
8308
8309 / CHANNEL SP INFO SP sampler_channel
8310
8311 / CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
8312
8313 / CHANNEL SP STREAM_COUNT SP sampler_channel
8314
8315 / CHANNEL SP VOICE_COUNT SP sampler_channel
8316
8317 / ENGINE SP INFO SP engine_name
8318
8319 / SERVER SP INFO
8320
8321 / TOTAL_STREAM_COUNT
8322
8323 / TOTAL_VOICE_COUNT
8324
8325 / TOTAL_VOICE_COUNT_MAX
8326
8327 / MIDI_INSTRUMENTS SP midi_map
8328
8329 / MIDI_INSTRUMENTS SP ALL
8330
8331 / MIDI_INSTRUMENT SP INFO SP midi_map SP midi_bank SP midi_prog
8332
8333 / MIDI_INSTRUMENT_MAPS
8334
8335 / MIDI_INSTRUMENT_MAP SP INFO SP midi_map
8336
8337 / FX_SENDS SP sampler_channel
8338
8339
8340
8341
8342
8343 Schoenebeck Expires January 16, 2016 [Page 149]
8344
8345 Internet-Draft LinuxSampler Control Protocol July 2015
8346
8347
8348 / FX_SEND SP INFO SP sampler_channel SP fx_send_id
8349
8350 / DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
8351
8352 / DB_INSTRUMENT_DIRECTORIES SP db_path
8353
8354 / DB_INSTRUMENT_DIRECTORY SP INFO SP db_path
8355
8356 / DB_INSTRUMENTS SP RECURSIVE SP db_path
8357
8358 / DB_INSTRUMENTS SP db_path
8359
8360 / DB_INSTRUMENT SP INFO SP db_path
8361
8362 / DB_INSTRUMENTS_JOB SP INFO SP number
8363
8364 / VOLUME
8365
8366 / VOICES
8367
8368 / STREAMS
8369
8370 / FILE SP INSTRUMENTS SP filename
8371
8372 / FILE SP INSTRUMENT SP INFO SP filename SP instrument_index
8373
8374 set_instruction =
8375
8376 AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '='
8377 param_val_list
8378
8379 / AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '='
8380 param_val_list
8381
8382 / MIDI_INPUT_DEVICE_PARAMETER SP number SP string '='
8383 param_val_list
8384
8385 / MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE
8386
8387 / MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '='
8388 param_val_list
8389
8390 / EFFECT_INSTANCE_INPUT_CONTROL SP VALUE SP effect_instance SP
8391 input_control SP control_value
8392
8393 / CHANNEL SP set_chan_instruction
8394
8395
8396
8397
8398
8399 Schoenebeck Expires January 16, 2016 [Page 150]
8400
8401 Internet-Draft LinuxSampler Control Protocol July 2015
8402
8403
8404 / MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
8405
8406 / FX_SEND SP NAME SP sampler_channel SP fx_send_id SP fx_send_name
8407
8408 / FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id
8409 SP audio_channel_index SP audio_channel_index
8410
8411 / FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP
8412 midi_ctrl
8413
8414 / FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP
8415 volume_value
8416
8417 / FX_SEND SP EFFECT SP sampler_channel SP fx_send_id SP
8418 effect_chain SP chain_pos
8419
8420 / DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped
8421
8422 / DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP
8423 stringval_escaped
8424
8425 / DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped
8426
8427 / DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
8428
8429 / DB_INSTRUMENT SP FILE_PATH SP filename SP filename
8430
8431 / ECHO SP boolean
8432
8433 / SHELL SP INTERACT SP boolean
8434
8435 / SHELL SP AUTO_CORRECT SP boolean
8436
8437 / SHELL SP DOC SP boolean
8438
8439 / VOLUME SP volume_value
8440
8441 / VOICES SP number
8442
8443 / STREAMS SP number
8444
8445 create_instruction =
8446
8447 AUDIO_OUTPUT_DEVICE SP string SP key_val_list
8448
8449 / AUDIO_OUTPUT_DEVICE SP string
8450
8451
8452
8453
8454
8455 Schoenebeck Expires January 16, 2016 [Page 151]
8456
8457 Internet-Draft LinuxSampler Control Protocol July 2015
8458
8459
8460 / MIDI_INPUT_DEVICE SP string SP key_val_list
8461
8462 / MIDI_INPUT_DEVICE SP string
8463
8464 / FX_SEND SP sampler_channel SP midi_ctrl
8465
8466 / FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name
8467
8468 / EFFECT_INSTANCE SP effect_index
8469
8470 / EFFECT_INSTANCE SP effect_system SP module SP effect_name
8471
8472 reset_instruction =
8473
8474 CHANNEL SP sampler_channel
8475
8476 clear_instruction =
8477
8478 MIDI_INSTRUMENTS SP midi_map
8479
8480 / MIDI_INSTRUMENTS SP ALL
8481
8482 find_instruction =
8483
8484 DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list
8485
8486 / DB_INSTRUMENTS SP db_path SP query_val_list
8487
8488 / DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP
8489 query_val_list
8490
8491 / DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
8492
8493 / LOST SP DB_INSTRUMENT_FILES
8494
8495 move_instruction =
8496
8497 DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
8498
8499 / DB_INSTRUMENT SP db_path SP db_path
8500
8501 copy_instruction =
8502
8503 DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
8504
8505 / DB_INSTRUMENT SP db_path SP db_path
8506
8507 destroy_instruction =
8508
8509
8510
8511 Schoenebeck Expires January 16, 2016 [Page 152]
8512
8513 Internet-Draft LinuxSampler Control Protocol July 2015
8514
8515
8516 AUDIO_OUTPUT_DEVICE SP number
8517
8518 / MIDI_INPUT_DEVICE SP number
8519
8520 / FX_SEND SP sampler_channel SP fx_send_id
8521
8522 / EFFECT_INSTANCE SP number
8523
8524 load_instruction =
8525
8526 INSTRUMENT SP load_instr_args
8527
8528 / ENGINE SP load_engine_args
8529
8530 append_instruction =
8531
8532 SEND_EFFECT_CHAIN SP EFFECT SP device_index SP effect_chain SP
8533 effect_instance
8534
8535 insert_instruction =
8536
8537 SEND_EFFECT_CHAIN SP EFFECT SP device_index SP effect_chain SP
8538 chain_pos SP effect_instance
8539
8540 set_chan_instruction =
8541
8542 AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
8543
8544 / AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index
8545 SP audio_channel_index
8546
8547 / AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
8548
8549 / MIDI_INPUT SP sampler_channel SP device_index SP
8550 midi_input_port_index SP midi_input_channel_index
8551
8552 / MIDI_INPUT_DEVICE SP sampler_channel SP device_index
8553
8554 / MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
8555
8556 / MIDI_INPUT_CHANNEL SP sampler_channel SP
8557 midi_input_channel_index
8558
8559 / MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
8560
8561 / VOLUME SP sampler_channel SP volume_value
8562
8563
8564
8565
8566
8567 Schoenebeck Expires January 16, 2016 [Page 153]
8568
8569 Internet-Draft LinuxSampler Control Protocol July 2015
8570
8571
8572 / MUTE SP sampler_channel SP boolean
8573
8574 / SOLO SP sampler_channel SP boolean
8575
8576 / MIDI_INSTRUMENT_MAP SP sampler_channel SP midi_map
8577
8578 / MIDI_INSTRUMENT_MAP SP sampler_channel SP NONE
8579
8580 / MIDI_INSTRUMENT_MAP SP sampler_channel SP DEFAULT
8581
8582 edit_instruction =
8583
8584 CHANNEL SP INSTRUMENT SP sampler_channel
8585
8586 format_instruction =
8587
8588 INSTRUMENTS_DB
8589
8590 modal_arg =
8591
8592 /* epsilon (empty argument) */
8593
8594 / NON_MODAL SP
8595
8596 key_val_list =
8597
8598 string '=' param_val_list
8599
8600 / key_val_list SP string '=' param_val_list
8601
8602 buffer_size_type =
8603
8604 BYTES
8605
8606 / PERCENTAGE
8607
8608 list_instruction =
8609
8610 AUDIO_OUTPUT_DEVICES
8611
8612 / MIDI_INPUT_DEVICES
8613
8614 / CHANNELS
8615
8616 / CHANNEL SP MIDI_INPUTS SP sampler_channel
8617
8618 / AVAILABLE_ENGINES
8619
8620
8621
8622
8623 Schoenebeck Expires January 16, 2016 [Page 154]
8624
8625 Internet-Draft LinuxSampler Control Protocol July 2015
8626
8627
8628 / AVAILABLE_EFFECTS
8629
8630 / EFFECT_INSTANCES
8631
8632 / SEND_EFFECT_CHAINS SP number
8633
8634 / AVAILABLE_MIDI_INPUT_DRIVERS
8635
8636 / AVAILABLE_AUDIO_OUTPUT_DRIVERS
8637
8638 / MIDI_INSTRUMENTS SP midi_map
8639
8640 / MIDI_INSTRUMENTS SP ALL
8641
8642 / MIDI_INSTRUMENT_MAPS
8643
8644 / FX_SENDS SP sampler_channel
8645
8646 / DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
8647
8648 / DB_INSTRUMENT_DIRECTORIES SP db_path
8649
8650 / DB_INSTRUMENTS SP RECURSIVE SP db_path
8651
8652 / DB_INSTRUMENTS SP db_path
8653
8654 / FILE SP INSTRUMENTS SP filename
8655
8656 send_instruction =
8657
8658 CHANNEL SP MIDI_DATA SP string SP sampler_channel SP number SP
8659 number
8660
8661 load_instr_args =
8662
8663 filename SP instrument_index SP sampler_channel
8664
8665 / NON_MODAL SP filename SP instrument_index SP sampler_channel
8666
8667 load_engine_args =
8668
8669 engine_name SP sampler_channel
8670
8671 instr_load_mode =
8672
8673 ON_DEMAND
8674
8675
8676
8677
8678
8679 Schoenebeck Expires January 16, 2016 [Page 155]
8680
8681 Internet-Draft LinuxSampler Control Protocol July 2015
8682
8683
8684 / ON_DEMAND_HOLD
8685
8686 / PERSISTENT
8687
8688 effect_instance =
8689
8690 number
8691
8692 device_index =
8693
8694 number
8695
8696 audio_channel_index =
8697
8698 number
8699
8700 audio_output_type_name =
8701
8702 string
8703
8704 midi_input_port_index =
8705
8706 number
8707
8708 midi_input_channel_index =
8709
8710 number
8711
8712 / ALL
8713
8714 midi_input_type_name =
8715
8716 string
8717
8718 midi_map =
8719
8720 number
8721
8722 midi_bank =
8723
8724 number
8725
8726 midi_prog =
8727
8728 number
8729
8730 midi_ctrl =
8731
8732
8733
8734
8735 Schoenebeck Expires January 16, 2016 [Page 156]
8736
8737 Internet-Draft LinuxSampler Control Protocol July 2015
8738
8739
8740 number
8741
8742 volume_value =
8743
8744 dotnum
8745
8746 / number
8747
8748 control_value =
8749
8750 real
8751
8752 sampler_channel =
8753
8754 number
8755
8756 instrument_index =
8757
8758 number
8759
8760 fx_send_id =
8761
8762 number
8763
8764 engine_name =
8765
8766 string
8767
8768 filename =
8769
8770 path
8771
8772 db_path =
8773
8774 path
8775
8776 map_name =
8777
8778 stringval_escaped
8779
8780 entry_name =
8781
8782 stringval_escaped
8783
8784 fx_send_name =
8785
8786 stringval_escaped
8787
8788
8789
8790
8791 Schoenebeck Expires January 16, 2016 [Page 157]
8792
8793 Internet-Draft LinuxSampler Control Protocol July 2015
8794
8795
8796 effect_name =
8797
8798 stringval_escaped
8799
8800 effect_index =
8801
8802 number
8803
8804 effect_chain =
8805
8806 number
8807
8808 chain_pos =
8809
8810 number
8811
8812 input_control =
8813
8814 number
8815
8816 param_val_list =
8817
8818 param_val
8819
8820 / param_val_list','param_val
8821
8822 param_val =
8823
8824 string
8825
8826 / stringval
8827
8828 / number
8829
8830 / dotnum
8831
8832 query_val_list =
8833
8834 string '=' query_val
8835
8836 / query_val_list SP string '=' query_val
8837
8838 query_val =
8839
8840 text_escaped
8841
8842 / stringval_escaped
8843
8844
8845
8846
8847 Schoenebeck Expires January 16, 2016 [Page 158]
8848
8849 Internet-Draft LinuxSampler Control Protocol July 2015
8850
8851
8852 scan_mode =
8853
8854 RECURSIVE
8855
8856 / NON_RECURSIVE
8857
8858 / FLAT
8859
8860 effect_system =
8861
8862 string
8863
8864 module =
8865
8866 filename
8867
8868 7.1. Character Set and Escape Sequences
8869
8870 Older versions of this protocol up to and including v1.1 only
8871 supported the standard ASCII character set (ASCII code 0 - 127)
8872 [RFC20], all younger versions of this protocol however support the
8873 Extended ASCII character set (ASCII code 0 - 255). The same group of
8874 younger protocols also support escape sequences, but only for
8875 certain, explicitly declared parts of the protocol. The supported
8876 escape sequences are defined as follows:
8877
8878 +------------------------+------------------------------------------+
8879 | ASCII Character | Translated into (Name) |
8880 | Sequence | |
8881 +------------------------+------------------------------------------+
8882 | \n | new line |
8883 | | |
8884 | \r | carriage return |
8885 | | |
8886 | \f | form feed |
8887 | | |
8888 | \t | horizontal tab |
8889 | | |
8890 | \v | vertical tab |
8891 | | |
8892 | \' | apostrophe |
8893 | | |
8894 | \" | quotation mark |
8895 | | |
8896 | \\ | backslash |
8897 | | |
8898 | \OOO | three digit octal ASCII code of the |
8899 | | character |
8900
8901
8902
8903 Schoenebeck Expires January 16, 2016 [Page 159]
8904
8905 Internet-Draft LinuxSampler Control Protocol July 2015
8906
8907
8908 | \xHH | two digit hex ASCII code of the |
8909 | | character |
8910 +------------------------+------------------------------------------+
8911
8912 Notice: due to the transition of certain parts of the protocol which
8913 now support escape sequences, a slight backward incompatibility to
8914 protocols version v1.1 and younger has been introduced. The only
8915 difference is that in parts of the protocol where escape characters
8916 are now supported, a backslash characters MUST be escaped as well
8917 (that is as double backslash), whereas in the old versions a single
8918 backslash was sufficient.
8919
8920 The following LSCP commands support escape sequences as part of their
8921 filename / path based arguments and / or may contain a filename /
8922 path with escape sequences in their response:
8923
8924 "LOAD INSTRUMENT" (Section 6.4.1)
8925
8926 "GET CHANNEL INFO" (Section 6.4.10)
8927
8928 "MAP MIDI_INSTRUMENT" (Section 6.7.7)
8929
8930 "GET MIDI_INSTRUMENT INFO" (Section 6.7.11)
8931
8932 "ADD DB_INSTRUMENT_DIRECTORY" (Section 6.8.1)
8933
8934 "ADD DB_INSTRUMENTS" (Section 6.8.11)
8935
8936 "REMOVE DB_INSTRUMENT_DIRECTORY" (Section 6.8.2)
8937
8938 "REMOVE DB_INSTRUMENT" (Section 6.8.12)
8939
8940 "GET DB_INSTRUMENT_DIRECTORIES" (Section 6.8.3)
8941
8942 "LIST DB_INSTRUMENT_DIRECTORIES" (Section 6.8.4)
8943
8944 "GET DB_INSTRUMENT_DIRECTORY INFO" (Section 6.8.5)
8945
8946 "GET DB_INSTRUMENTS" (Section 6.8.13)
8947
8948 "LIST DB_INSTRUMENTS" (Section 6.8.14)
8949
8950 "GET DB_INSTRUMENT INFO" (Section 6.8.15)
8951
8952 "SET DB_INSTRUMENT_DIRECTORY NAME" (Section 6.8.6)
8953
8954 "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION" (Section 6.8.9)
8955
8956
8957
8958
8959 Schoenebeck Expires January 16, 2016 [Page 160]
8960
8961 Internet-Draft LinuxSampler Control Protocol July 2015
8962
8963
8964 "SET DB_INSTRUMENT NAME" (Section 6.8.16)
8965
8966 "SET DB_INSTRUMENT DESCRIPTION" (Section 6.8.19)
8967
8968 "FIND DB_INSTRUMENTS" (Section 6.8.20)
8969
8970 "FIND DB_INSTRUMENT_DIRECTORIES" (Section 6.8.10)
8971
8972 "MOVE DB_INSTRUMENT" (Section 6.8.17)
8973
8974 "MOVE DB_INSTRUMENT_DIRECTORY" (Section 6.8.7)
8975
8976 "COPY DB_INSTRUMENT" (Section 6.8.18)
8977
8978 "COPY DB_INSTRUMENT_DIRECTORY" (Section 6.8.8)
8979
8980 "FIND LOST DB_INSTRUMENT_FILES" (Section 6.8.23)
8981
8982 "SET DB_INSTRUMENT FILE_PATH" (Section 6.8.24)
8983
8984 "GET FILE INSTRUMENTS" (Section 6.10.1)
8985
8986 "LIST FILE INSTRUMENTS" (Section 6.10.2)
8987
8988 "GET FILE INSTRUMENT INFO" (Section 6.10.3)
8989
8990 "GET EFFECT INFO" (Section 6.11.3)
8991
8992 "GET EFFECT_INSTANCE INFO" (Section 6.11.9)
8993
8994 "CREATE EFFECT_INSTANCE" (Section 6.11.4)
8995
8996 Note that the forward slash character ('/') has a special meaning in
8997 filename / path based arguments: it acts as separator of the nodes in
8998 the path, thus if a directory- or filename includes a forward slash
8999 (not intended as path node separator), you MUST escape that slash
9000 either with the respective hex escape sequence ("\x2f") or with the
9001 respective octal escape sequence ("\057").
9002
9003 Note for Windows: file path arguments in LSCP are expected to use
9004 forward slashes as directory node separator similar to Unix based
9005 operating systems. In contrast to Unix however a Windows typical
9006 drive character is expected to be prefixed to the path. That is an
9007 original Windows file path like "D:\Sounds\My.gig" would become in
9008 LSCP: "D:/Sounds/My.gig".
9009
9010 The following LSCP commands even support escape sequences as part of
9011 at least one of their text-based arguments (i.e. entity name,
9012
9013
9014
9015 Schoenebeck Expires January 16, 2016 [Page 161]
9016
9017 Internet-Draft LinuxSampler Control Protocol July 2015
9018
9019
9020 description) and / or may contain escape sequences in at least one of
9021 their text-based fields in their response:
9022
9023 "GET SERVER INFO" (Section 6.6.5)
9024
9025 "GET ENGINE INFO" (Section 6.4.9)
9026
9027 "GET CHANNEL INFO" (Section 6.4.10)
9028
9029 "CREATE FX_SEND" (Section 6.4.28)
9030
9031 "GET FX_SEND INFO" (Section 6.4.32)
9032
9033 "SET FX_SEND NAME" (Section 6.4.33)
9034
9035 "GET MIDI_INSTRUMENT INFO" (Section 6.7.11)
9036
9037 "GET MIDI_INSTRUMENT_MAP INFO" (Section 6.7.5)
9038
9039 "ADD MIDI_INSTRUMENT_MAP" (Section 6.7.1)
9040
9041 "MAP MIDI_INSTRUMENT" (Section 6.7.7)
9042
9043 "SET MIDI_INSTRUMENT_MAP NAME" (Section 6.7.6)
9044
9045 "GET DB_INSTRUMENT_DIRECTORY INFO" (Section 6.8.5)
9046
9047 "SET DB_INSTRUMENT_DIRECTORY NAME" (Section 6.8.6)
9048
9049 "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION" (Section 6.8.9)
9050
9051 "FIND DB_INSTRUMENT_DIRECTORIES" (Section 6.8.10)
9052
9053 "GET DB_INSTRUMENT INFO" (Section 6.8.15)
9054
9055 "SET DB_INSTRUMENT NAME" (Section 6.8.16)
9056
9057 "SET DB_INSTRUMENT DESCRIPTION" (Section 6.8.19)
9058
9059 "FIND DB_INSTRUMENTS" (Section 6.8.20)
9060
9061 "GET EFFECT INFO" (Section 6.11.3)
9062
9063 "GET EFFECT_INSTANCE INFO" (Section 6.11.9)
9064
9065 "CREATE EFFECT_INSTANCE" (Section 6.11.4)
9066
9067 Please note that these lists are manually maintained. If you find a
9068
9069
9070
9071 Schoenebeck Expires January 16, 2016 [Page 162]
9072
9073 Internet-Draft LinuxSampler Control Protocol July 2015
9074
9075
9076 command that also supports escape sequences we forgot to mention
9077 here, please report it!
9078
9079
9080
9081
9082
9083
9084
9085
9086
9087
9088
9089
9090
9091
9092
9093
9094
9095
9096
9097
9098
9099
9100
9101
9102
9103
9104
9105
9106
9107
9108
9109
9110
9111
9112
9113
9114
9115
9116
9117
9118
9119
9120
9121
9122
9123
9124
9125
9126
9127 Schoenebeck Expires January 16, 2016 [Page 163]
9128
9129 Internet-Draft LinuxSampler Control Protocol July 2015
9130
9131
9132 8. Events
9133
9134 This chapter will describe all currently defined events supported by
9135 LinuxSampler.
9136
9137 8.1. Number of audio output devices changed
9138
9139 Client may want to be notified when the total number of audio output
9140 devices on the back-end changes by issuing the following command:
9141
9142 SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT
9143
9144 Server will start sending the following notification messages:
9145
9146 "NOTIFY:AUDIO_OUTPUT_DEVICE_COUNT:<devices>"
9147
9148 where <devices> will be replaced by the new number of audio output
9149 devices.
9150
9151 8.2. Audio output device's settings changed
9152
9153 Client may want to be notified when changes were made to audio output
9154 devices on the back-end by issuing the following command:
9155
9156 SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO
9157
9158 Server will start sending the following notification messages:
9159
9160 "NOTIFY:AUDIO_OUTPUT_DEVICE_INFO:<device-id>"
9161
9162 where <device-id> will be replaced by the numerical ID of the audio
9163 output device, which settings has been changed. The front-end will
9164 have to send the respective command to actually get the audio output
9165 device info. Because these messages will be triggered by LSCP
9166 commands issued by other clients rather than real time events
9167 happening on the server, it is believed that an empty notification
9168 message is sufficient here.
9169
9170 8.3. Number of MIDI input devices changed
9171
9172 Client may want to be notified when the total number of MIDI input
9173 devices on the back-end changes by issuing the following command:
9174
9175 SUBSCRIBE MIDI_INPUT_DEVICE_COUNT
9176
9177 Server will start sending the following notification messages:
9178
9179
9180
9181
9182
9183 Schoenebeck Expires January 16, 2016 [Page 164]
9184
9185 Internet-Draft LinuxSampler Control Protocol July 2015
9186
9187
9188 "NOTIFY:MIDI_INPUT_DEVICE_COUNT:<devices>"
9189
9190 where <devices> will be replaced by the new number of MIDI input
9191 devices.
9192
9193 8.4. MIDI input device's settings changed
9194
9195 Client may want to be notified when changes were made to MIDI input
9196 devices on the back-end by issuing the following command:
9197
9198 SUBSCRIBE MIDI_INPUT_DEVICE_INFO
9199
9200 Server will start sending the following notification messages:
9201
9202 "NOTIFY:MIDI_INPUT_DEVICE_INFO:<device-id>"
9203
9204 where <device-id> will be replaced by the numerical ID of the MIDI
9205 input device, which settings has been changed. The front-end will
9206 have to send the respective command to actually get the MIDI input
9207 device info. Because these messages will be triggered by LSCP
9208 commands issued by other clients rather than real time events
9209 happening on the server, it is believed that an empty notification
9210 message is sufficient here.
9211
9212 8.5. Number of sampler channels changed
9213
9214 Client may want to be notified when the total number of channels on
9215 the back-end changes by issuing the following command:
9216
9217 SUBSCRIBE CHANNEL_COUNT
9218
9219 Server will start sending the following notification messages:
9220
9221 "NOTIFY:CHANNEL_COUNT:<channels>"
9222
9223 where <channels> will be replaced by the new number of sampler
9224 channels.
9225
9226 8.6. MIDI data on a sampler channel arrived
9227
9228 Client may want to be notified when MIDI data arrive on sampler
9229 channels on back-end side, by issuing the following command:
9230
9231 SUBSCRIBE CHANNEL_MIDI
9232
9233 Server will start sending one of the the following notification
9234 messages:
9235
9236
9237
9238
9239 Schoenebeck Expires January 16, 2016 [Page 165]
9240
9241 Internet-Draft LinuxSampler Control Protocol July 2015
9242
9243
9244 "NOTIFY:CHANNEL_MIDI:<channel-id> NOTE_ON <note> <velocity>"
9245
9246 "NOTIFY:CHANNEL_MIDI:<channel-id> NOTE_OFF <note> <velocity>"
9247
9248 where <channel-id> will be replaced by the ID of the sampler channel
9249 where the MIDI data arrived. <note> and <velocity> are integer values
9250 in the range between 0 .. 127, reflecting the analog meaning of the
9251 MIDI specification.
9252
9253 CAUTION: no guarantee whatsoever will be made that MIDI events are
9254 actually all delivered by this mechanism! With other words: events
9255 could be lost at any time! This restriction was made to keep the RT-
9256 safeness of the backend's MIDI and audio thread unaffected by this
9257 feature.
9258
9259 8.7. MIDI data on a MIDI input device arrived
9260
9261 Client may want to be notified when MIDI data arrive on MIDI input
9262 devices by issuing the following command:
9263
9264 SUBSCRIBE DEVICE_MIDI
9265
9266 Server will start sending one of the the following notification
9267 messages:
9268
9269 "NOTIFY:DEVICE_MIDI:<device-id> <port-id> NOTE_ON <note>
9270 <velocity>"
9271
9272 "NOTIFY:DEVICE_MIDI:<device-id> <port-id> NOTE_OFF <note>
9273 <velocity>"
9274
9275 where <device-id> <port-id> will be replaced by the IDs of the
9276 respective MIDI input device and the device's MIDI port where the
9277 MIDI data arrived. <note> and <velocity> are integer values in the
9278 range between 0 .. 127, reflecting the analog meaning of the MIDI
9279 specification.
9280
9281 CAUTION: no guarantee whatsoever will be made that MIDI events are
9282 actually all delivered by this mechanism! With other words: events
9283 could be lost at any time! This restriction was made to keep the RT-
9284 safeness of the backend's MIDI and audio thread unaffected by this
9285 feature.
9286
9287 8.8. Number of active voices changed
9288
9289 Client may want to be notified when the number of voices on the back-
9290 end changes by issuing the following command:
9291
9292
9293
9294
9295 Schoenebeck Expires January 16, 2016 [Page 166]
9296
9297 Internet-Draft LinuxSampler Control Protocol July 2015
9298
9299
9300 SUBSCRIBE VOICE_COUNT
9301
9302 Server will start sending the following notification messages:
9303
9304 "NOTIFY:VOICE_COUNT:<sampler-channel> <voices>"
9305
9306 where <sampler-channel> will be replaced by the sampler channel the
9307 voice count change occurred and <voices> by the new number of active
9308 voices on that channel.
9309
9310 8.9. Number of active disk streams changed
9311
9312 Client may want to be notified when the number of streams on the
9313 back-end changes by issuing the following command: SUBSCRIBE
9314 STREAM_COUNT
9315
9316 SUBSCRIBE STREAM_COUNT
9317
9318 Server will start sending the following notification messages:
9319
9320 "NOTIFY:STREAM_COUNT:<sampler-channel> <streams>"
9321
9322 where <sampler-channel> will be replaced by the sampler channel the
9323 stream count change occurred and <streams> by the new number of
9324 active disk streams on that channel.
9325
9326 8.10. Disk stream buffer fill state changed
9327
9328 Client may want to be notified when the buffer fill state of a disk
9329 stream on the back-end changes by issuing the following command:
9330
9331 SUBSCRIBE BUFFER_FILL
9332
9333 Server will start sending the following notification messages:
9334
9335 "NOTIFY:BUFFER_FILL:<sampler-channel> <fill-data>"
9336
9337 where <sampler-channel> will be replaced by the sampler channel the
9338 buffer fill state change occurred on and <fill-data> will be replaced
9339 by the buffer fill data for this channel as described in
9340 Section 6.4.13 as if the "GET CHANNEL BUFFER_FILL PERCENTAGE"
9341 (Section 6.4.13) command was issued on this channel.
9342
9343 8.11. Channel information changed
9344
9345 Client may want to be notified when changes were made to sampler
9346 channels on the back-end by issuing the following command:
9347
9348
9349
9350
9351 Schoenebeck Expires January 16, 2016 [Page 167]
9352
9353 Internet-Draft LinuxSampler Control Protocol July 2015
9354
9355
9356 SUBSCRIBE CHANNEL_INFO
9357
9358 Server will start sending the following notification messages:
9359
9360 "NOTIFY:CHANNEL_INFO:<sampler-channel>"
9361
9362 where <sampler-channel> will be replaced by the sampler channel the
9363 channel info change occurred. The front-end will have to send the
9364 respective command to actually get the channel info. Because these
9365 messages will be triggered by LSCP commands issued by other clients
9366 rather than real time events happening on the server, it is believed
9367 that an empty notification message is sufficient here.
9368
9369 8.12. Number of effect sends changed
9370
9371 Client may want to be notified when the number of effect sends on a
9372 particular sampler channel is changed by issuing the following
9373 command:
9374
9375 SUBSCRIBE FX_SEND_COUNT
9376
9377 Server will start sending the following notification messages:
9378
9379 "NOTIFY:FX_SEND_COUNT:<channel-id> <fx-sends>"
9380
9381 where <channel-id> will be replaced by the numerical ID of the
9382 sampler channel, on which the effect sends number is changed and <fx-
9383 sends> will be replaced by the new number of effect sends on that
9384 channel.
9385
9386 8.13. Effect send information changed
9387
9388 Client may want to be notified when changes were made to effect sends
9389 on a a particular sampler channel by issuing the following command:
9390
9391 SUBSCRIBE FX_SEND_INFO
9392
9393 Server will start sending the following notification messages:
9394
9395 "NOTIFY:FX_SEND_INFO:<channel-id> <fx-send-id>"
9396
9397 where <channel-id> will be replaced by the numerical ID of the
9398 sampler channel, on which an effect send entity is changed and <fx-
9399 send-id> will be replaced by the numerical ID of the changed effect
9400 send.
9401
9402
9403
9404
9405
9406
9407 Schoenebeck Expires January 16, 2016 [Page 168]
9408
9409 Internet-Draft LinuxSampler Control Protocol July 2015
9410
9411
9412 8.14. Total number of active voices changed
9413
9414 Client may want to be notified when the total number of voices on the
9415 back-end changes by issuing the following command:
9416
9417 SUBSCRIBE TOTAL_VOICE_COUNT
9418
9419 Server will start sending the following notification messages:
9420
9421 "NOTIFY:TOTAL_VOICE_COUNT:<voices>"
9422
9423 where <voices> will be replaced by the new number of all currently
9424 active voices.
9425
9426 8.15. Total number of active disk streams changed
9427
9428 Client may want to be notified when the total number of disk streams
9429 on the back-end changes by issuing the following command:
9430
9431 SUBSCRIBE TOTAL_STREAM_COUNT
9432
9433 Server will start sending the following notification messages:
9434
9435 "NOTIFY:TOTAL_STREAM_COUNT:<streams>"
9436
9437 where <streams> will be replaced by the new number of all currently
9438 active disk streams.
9439
9440 8.16. Number of MIDI instrument maps changed
9441
9442 Client may want to be notified when the number of MIDI instrument
9443 maps on the back-end changes by issuing the following command:
9444
9445 SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT
9446
9447 Server will start sending the following notification messages:
9448
9449 "NOTIFY:MIDI_INSTRUMENT_MAP_COUNT:<maps>"
9450
9451 where <maps> will be replaced by the new number of MIDI instrument
9452 maps.
9453
9454 8.17. MIDI instrument map information changed
9455
9456 Client may want to be notified when changes were made to MIDI
9457 instrument maps on the back-end by issuing the following command:
9458
9459
9460
9461
9462
9463 Schoenebeck Expires January 16, 2016 [Page 169]
9464
9465 Internet-Draft LinuxSampler Control Protocol July 2015
9466
9467
9468 SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO
9469
9470 Server will start sending the following notification messages:
9471
9472 "NOTIFY:MIDI_INSTRUMENT_MAP_INFO:<map-id>"
9473
9474 where <map-id> will be replaced by the numerical ID of the MIDI
9475 instrument map, for which information changes occurred. The front-
9476 end will have to send the respective command to actually get the MIDI
9477 instrument map info. Because these messages will be triggered by
9478 LSCP commands issued by other clients rather than real time events
9479 happening on the server, it is believed that an empty notification
9480 message is sufficient here.
9481
9482 8.18. Number of MIDI instruments changed
9483
9484 Client may want to be notified when the number of MIDI instrument
9485 maps on the back-end changes by issuing the following command:
9486
9487 SUBSCRIBE MIDI_INSTRUMENT_COUNT
9488
9489 Server will start sending the following notification messages:
9490
9491 "NOTIFY:MIDI_INSTRUMENT_COUNT:<map-id> <instruments>"
9492
9493 where <map-id> is the numerical ID of the MIDI instrument map, in
9494 which the nuber of instruments has changed and <instruments> will be
9495 replaced by the new number of MIDI instruments in the specified map.
9496
9497 8.19. MIDI instrument information changed
9498
9499 Client may want to be notified when changes were made to MIDI
9500 instruments on the back-end by issuing the following command:
9501
9502 SUBSCRIBE MIDI_INSTRUMENT_INFO
9503
9504 Server will start sending the following notification messages:
9505
9506 "NOTIFY:MIDI_INSTRUMENT_INFO:<map-id> <bank> <program>"
9507
9508 where <map-id> will be replaced by the numerical ID of the MIDI
9509 instrument map, in which a MIDI instrument is changed. <bank> and
9510 <program> specifies the location of the changed MIDI instrument in
9511 the map. The front-end will have to send the respective command to
9512 actually get the MIDI instrument info. Because these messages will
9513 be triggered by LSCP commands issued by other clients rather than
9514 real time events happening on the server, it is believed that an
9515 empty notification message is sufficient here.
9516
9517
9518
9519 Schoenebeck Expires January 16, 2016 [Page 170]
9520
9521 Internet-Draft LinuxSampler Control Protocol July 2015
9522
9523
9524 8.20. Global settings changed
9525
9526 Client may want to be notified when changes to the global settings of
9527 the sampler were made by issuing the following command:
9528
9529 SUBSCRIBE GLOBAL_INFO
9530
9531 Server will start sending the following types of notification
9532 messages:
9533
9534 "NOTIFY:GLOBAL_INFO:VOLUME <volume>" - Notifies that the golbal
9535 volume of the sampler is changed, where <volume> will be replaced
9536 by the optional dotted floating point value, reflecting the new
9537 global volume parameter.
9538
9539 "NOTIFY:GLOBAL_INFO:VOICES <max-voices>" - Notifies that the
9540 golbal limit of the sampler for maximum voices is changed, where
9541 <max-voices> will be an integer value, reflecting the new global
9542 voice limit parameter.
9543
9544 "NOTIFY:GLOBAL_INFO:STREAMS <max-streams>" - Notifies that the
9545 golbal limit of the sampler for maximum disk streams is changed,
9546 where <max-streams> will be an integer value, reflecting the new
9547 global disk streams limit parameter.
9548
9549 8.21. Number of database instrument directories changed
9550
9551 Client may want to be notified when the number of instrument
9552 directories in a particular directory in the instruments database is
9553 changed by issuing the following command:
9554
9555 SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT
9556
9557 Server will start sending the following notification messages:
9558
9559 "NOTIFY:DB_INSTRUMENT_DIRECTORY_COUNT:<dir-path>"
9560
9561 where <dir-path> will be replaced by the absolute path name of the
9562 directory in the instruments database, in which the number of
9563 directories is changed.
9564
9565 Note that when a non-empty directory is removed, this event is not
9566 sent for the subdirectories in that directory.
9567
9568 8.22. Database instrument directory information changed
9569
9570 Client may want to be notified when changes were made to directories
9571 in the instruments database by issuing the following command:
9572
9573
9574
9575 Schoenebeck Expires January 16, 2016 [Page 171]
9576
9577 Internet-Draft LinuxSampler Control Protocol July 2015
9578
9579
9580 SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO
9581
9582 Server will start sending the following notification messages:
9583
9584 "NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:<dir-path>"
9585
9586 where <dir-path> will be replaced by the absolute path name of the
9587 directory, for which information changes occurred. The front-end
9588 will have to send the respective command to actually get the updated
9589 directory info. Because these messages will be triggered by LSCP
9590 commands issued by other clients rather than real time events
9591 happening on the server, it is believed that an empty notification
9592 message is sufficient here.
9593
9594 "NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:NAME <old-dir-path> <new-
9595 name>"
9596
9597 where <old-dir-path> is the old absolute path name of the directory
9598 (encapsulated into apostrophes), which name is changes and <new-name>
9599 is the new name of the directory, encapsulated into apostrophes.
9600
9601 8.23. Number of database instruments changed
9602
9603 Client may want to be notified when the number of instruments in a
9604 particular directory in the instruments database is changed by
9605 issuing the following command:
9606
9607 SUBSCRIBE DB_INSTRUMENT_COUNT
9608
9609 Server will start sending the following notification messages:
9610
9611 "NOTIFY:DB_INSTRUMENT_COUNT:<dir-path>"
9612
9613 where <dir-path> will be replaced by the absolute path name of the
9614 directory in the instruments database, in which the number of
9615 instruments is changed.
9616
9617 Note that when a non-empty directory is removed, this event is not
9618 sent for the instruments in that directory.
9619
9620 8.24. Database instrument information changed
9621
9622 Client may want to be notified when changes were made to instruments
9623 in the instruments database by issuing the following command:
9624
9625 SUBSCRIBE DB_INSTRUMENT_INFO
9626
9627 Server will start sending the following notification messages:
9628
9629
9630
9631 Schoenebeck Expires January 16, 2016 [Page 172]
9632
9633 Internet-Draft LinuxSampler Control Protocol July 2015
9634
9635
9636 "NOTIFY:DB_INSTRUMENT_INFO:<instr-path>"
9637
9638 where <instr-path> will be replaced by the absolute path name of the
9639 instrument, which settings are changed. The front-end will have to
9640 send the respective command to actually get the updated directory
9641 info. Because these messages will be triggered by LSCP commands
9642 issued by other clients rather than real time events happening on the
9643 server, it is believed that an empty notification message is
9644 sufficient here.
9645
9646 "NOTIFY:DB_INSTRUMENT_INFO:NAME <old-instr-path> <new-name>"
9647
9648 where <old-instr-path> is the old absolute path name of the
9649 instrument (encapsulated into apostrophes), which name is changes and
9650 <new-name> is the new name of the instrument, encapsulated into
9651 apostrophes.
9652
9653 8.25. Database job status information changed
9654
9655 Client may want to be notified when the status of particular database
9656 instruments job is changed by issuing the following command:
9657
9658 SUBSCRIBE DB_INSTRUMENTS_JOB_INFO
9659
9660 Server will start sending the following notification messages:
9661
9662 "NOTIFY:DB_INSTRUMENTS_JOB_INFO:<job-id>"
9663
9664 where <job-id> will be replaced by the numerical ID of the job, which
9665 status is changed. The front-end will have to send the respective
9666 command to actually get the status info. Because these messages will
9667 be triggered by LSCP commands issued by other clients rather than
9668 real time events happening on the server, it is believed that an
9669 empty notification message is sufficient here.
9670
9671 8.26. Number of effect instances changed
9672
9673 Client may want to be notified when the number of effect instances is
9674 changed by issuing the following command:
9675
9676 SUBSCRIBE EFFECT_INSTANCE_COUNT
9677
9678 Server will start sending the following notification messages:
9679
9680 "EFFECT_INSTANCE_COUNT:<instances>"
9681
9682 where <instances> will be replaced by the new number of effect
9683 instances.
9684
9685
9686
9687 Schoenebeck Expires January 16, 2016 [Page 173]
9688
9689 Internet-Draft LinuxSampler Control Protocol July 2015
9690
9691
9692 8.27. Effect instance information changed
9693
9694 Client may want to be notified when changes were made to effect
9695 instances on the back-end by issuing the following command:
9696
9697 SUBSCRIBE EFFECT_INSTANCE_INFO
9698
9699 Server will start sending the following notification messages:
9700
9701 "EFFECT_INSTANCE_INFO:<instance-id>"
9702
9703 where <instance-id> will be replaced by the numerical ID of the
9704 effect instance.
9705
9706 8.28. Number of send effect chains changed
9707
9708 Client may want to be notified when the number of send effect chains
9709 is changed by issuing the following command:
9710
9711 SUBSCRIBE SEND_EFFECT_CHAIN_COUNT
9712
9713 Server will start sending the following notification messages:
9714
9715 "NOTIFY:SEND_EFFECT_CHAIN_COUNT:<device-id> <chains>"
9716
9717 where <device-id> will be replaced by the numerical ID of the audio
9718 output device, in which the number of send effect chains is changed
9719 and <chains> will be replaced by the new number of send effect
9720 chains.
9721
9722 8.29. Send effect chain information changed
9723
9724 Client may want to be notified when changes were made to send effect
9725 chains on the back-end by issuing the following command:
9726
9727 SUBSCRIBE SEND_EFFECT_CHAIN_INFO
9728
9729 Server will start sending the following notification messages:
9730
9731 "SEND_EFFECT_CHAIN_INFO:<device-id> <chain-id> <instances>" -
9732 Notifies that the number of effect instances in a particular send
9733 effect chain is changed, where <device-id> will be replaced by the
9734 numerical ID of the audio output device the send effect chain
9735 belongs to, <chain-id> will be replaced by the numerical ID of the
9736 send effect chain in which the number of effect instances has
9737 changed and <instances> will be replaced by the new number of
9738 effect instances in the specified send effect chain.
9739
9740
9741
9742
9743 Schoenebeck Expires January 16, 2016 [Page 174]
9744
9745 Internet-Draft LinuxSampler Control Protocol July 2015
9746
9747
9748 8.30. Miscellaneous and debugging events
9749
9750 Client may want to be notified of miscellaneous and debugging events
9751 occurring at the server by issuing the following command:
9752
9753 SUBSCRIBE MISCELLANEOUS
9754
9755 Server will start sending the following notification messages:
9756
9757 "NOTIFY:MISCELLANEOUS:<string>"
9758
9759 where <string> will be replaced by whatever data server wants to send
9760 to the client. Client MAY display this data to the user AS IS to
9761 facilitate debugging.
9762
9763
9764
9765
9766
9767
9768
9769
9770
9771
9772
9773
9774
9775
9776
9777
9778
9779
9780
9781
9782
9783
9784
9785
9786
9787
9788
9789
9790
9791
9792
9793
9794
9795
9796
9797
9798
9799 Schoenebeck Expires January 16, 2016 [Page 175]
9800
9801 Internet-Draft LinuxSampler Control Protocol July 2015
9802
9803
9804 9. Security Considerations
9805
9806 As there is so far no method of authentication and authorization
9807 defined and so not required for a client applications to succeed to
9808 connect, running LinuxSampler might be a security risk for the host
9809 system the LinuxSampler instance is running on.
9810
9811
9812
9813
9814
9815
9816
9817
9818
9819
9820
9821
9822
9823
9824
9825
9826
9827
9828
9829
9830
9831
9832
9833
9834
9835
9836
9837
9838
9839
9840
9841
9842
9843
9844
9845
9846
9847
9848
9849
9850
9851
9852
9853
9854
9855 Schoenebeck Expires January 16, 2016 [Page 176]
9856
9857 Internet-Draft LinuxSampler Control Protocol July 2015
9858
9859
9860 10. Acknowledgments
9861
9862 This document has benefited greatly from the comments of the
9863 following people, discussed on the LinuxSampler developer's mailing
9864 list:
9865
9866 Rui Nuno Capela
9867
9868 Vladimir Senkov
9869
9870 Mark Knecht
9871
9872 Grigor Iliev
9873
9874
9875
9876
9877
9878
9879
9880
9881
9882
9883
9884
9885
9886
9887
9888
9889
9890
9891
9892
9893
9894
9895
9896
9897
9898
9899
9900
9901
9902
9903
9904
9905
9906
9907
9908
9909
9910
9911 Schoenebeck Expires January 16, 2016 [Page 177]
9912
9913 Internet-Draft LinuxSampler Control Protocol July 2015
9914
9915
9916 11. References
9917
9918 [RFC20] UCLA, "ASCII format for Network Interchange", RFC 20,
9919 1969.
9920
9921 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
9922 Requirement Levels", RFC 2119, 1997.
9923
9924 [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
9925 Specifications", RFC 2234, 1997.
9926
9927 [RFC793] Defense Advanced Research Projects Agency, "TRANSMISSION
9928 CONTROL PROTOCOL", RFC 793, 1981.
9929
9930
9931
9932
9933
9934
9935
9936
9937
9938
9939
9940
9941
9942
9943
9944
9945
9946
9947
9948
9949
9950
9951
9952
9953
9954
9955
9956
9957
9958
9959
9960
9961
9962
9963
9964
9965
9966
9967 Schoenebeck Expires January 16, 2016 [Page 178]
9968
9969 Internet-Draft LinuxSampler Control Protocol July 2015
9970
9971
9972 Author's Address
9973
9974 C. Schoenebeck
9975 LinuxSampler.org
9976 Crudebyte Engineering
9977 Hofgartenstr. 3
9978 74189 Weinsberg
9979 Germany
9980
9981 Phone: +49 7134 911614
9982 Email: cuse@users.sf.net
9983
9984
9985
9986
9987
9988
9989
9990
9991
9992
9993
9994
9995
9996
9997
9998
9999
10000
10001
10002
10003
10004
10005
10006
10007
10008
10009
10010
10011
10012
10013
10014
10015
10016
10017
10018
10019
10020
10021
10022
10023 Schoenebeck Expires January 16, 2016 [Page 179]
10024
10025 Internet-Draft LinuxSampler Control Protocol July 2015
10026
10027
10028 Full Copyright Statement
10029
10030 Copyright (C) The IETF Trust (2015).
10031
10032 This document is subject to the rights, licenses and restrictions
10033 contained in BCP 78, and except as set forth therein, the authors
10034 retain all their rights.
10035
10036 This document and the information contained herein are provided on an
10037 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
10038 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
10039 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
10040 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
10041 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
10042 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
10043
10044
10045 Intellectual Property
10046
10047 The IETF takes no position regarding the validity or scope of any
10048 Intellectual Property Rights or other rights that might be claimed to
10049 pertain to the implementation or use of the technology described in
10050 this document or the extent to which any license under such rights
10051 might or might not be available; nor does it represent that it has
10052 made any independent effort to identify any such rights. Information
10053 on the procedures with respect to rights in RFC documents can be
10054 found in BCP 78 and BCP 79.
10055
10056 Copies of IPR disclosures made to the IETF Secretariat and any
10057 assurances of licenses to be made available, or the result of an
10058 attempt made to obtain a general license or permission for the use of
10059 such proprietary rights by implementers or users of this
10060 specification can be obtained from the IETF on-line IPR repository at
10061 http://www.ietf.org/ipr.
10062
10063 The IETF invites any interested party to bring to its attention any
10064 copyrights, patents or patent applications, or other proprietary
10065 rights that may cover technology that may be required to implement
10066 this standard. Please address the information to the IETF at
10067 ietf-ipr@ietf.org.
10068
10069
10070
10071
10072
10073
10074
10075
10076
10077
10078
10079 Schoenebeck Expires January 16, 2016 [Page 180]
10080

Properties

Name Value
svn:executable *

  ViewVC Help
Powered by ViewVC