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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2189 - (show annotations) (download)
Fri Jun 24 19:57:07 2011 UTC (12 years, 8 months ago) by iliev
File MIME type: text/plain
File size: 278818 byte(s)
* updated LSCP specs

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

  ViewVC Help
Powered by ViewVC