/[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 2143 - (show annotations) (download)
Tue Oct 5 18:23:41 2010 UTC (8 years, 2 months ago) by schoenebeck
File MIME type: text/plain
File size: 275804 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: April 8, 2011 October 5, 2010
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). Note that other groups may also distribute
30 working documents as Internet-Drafts. The list of current Internet-
31 Drafts is at http://datatracker.ietf.org/drafts/current/.
32
33 Internet-Drafts are draft documents valid for a maximum of six months
34 and may be updated, replaced, or obsoleted by other documents at any
35 time. It is inappropriate to use Internet-Drafts as reference
36 material or to cite them other than as "work in progress."
37
38 This Internet-Draft will expire on April 8, 2011.
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55 Schoenebeck Expires April 8, 2011 [Page 1]
56
57 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 2]
112
113 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 3]
168
169 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 4]
224
225 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 5]
280
281 Internet-Draft LinuxSampler Control Protocol October 2010
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. Miscellaneous and debugging events . . . . . . . . . . . 166
295 9. Security Considerations . . . . . . . . . . . . . . . . . . . 168
296 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 169
297 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 170
298 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 171
299 Intellectual Property and Copyright Statements . . . . . . . . . 172
300
301
302
303
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 April 8, 2011 [Page 6]
336
337 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 7]
392
393 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 8]
448
449 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 9]
504
505 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 10]
560
561 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 11]
616
617 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 12]
672
673 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 13]
728
729 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 14]
784
785 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 15]
840
841 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 16]
896
897 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 17]
952
953 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 18]
1008
1009 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 19]
1064
1065 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 20]
1120
1121 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 21]
1176
1177 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 22]
1232
1233 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 23]
1288
1289 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 24]
1344
1345 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 25]
1400
1401 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 26]
1456
1457 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 27]
1512
1513 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 28]
1568
1569 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 29]
1624
1625 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 30]
1680
1681 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 31]
1736
1737 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 32]
1792
1793 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 33]
1848
1849 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 34]
1904
1905 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 35]
1960
1961 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 36]
2016
2017 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 37]
2072
2073 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 38]
2128
2129 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 39]
2184
2185 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 40]
2240
2241 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 41]
2296
2297 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 42]
2352
2353 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 43]
2408
2409 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 44]
2464
2465 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 45]
2520
2521 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 46]
2576
2577 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 47]
2632
2633 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 48]
2688
2689 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 49]
2744
2745 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 50]
2800
2801 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 51]
2856
2857 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 52]
2912
2913 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 53]
2968
2969 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 54]
3024
3025 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 55]
3080
3081 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 56]
3136
3137 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 57]
3192
3193 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 58]
3248
3249 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 59]
3304
3305 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 60]
3360
3361 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 61]
3416
3417 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 62]
3472
3473 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 63]
3528
3529 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 64]
3584
3585 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 65]
3640
3641 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 66]
3696
3697 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 67]
3752
3753 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 68]
3808
3809 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 69]
3864
3865 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 70]
3920
3921 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 71]
3976
3977 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 72]
4032
4033 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 73]
4088
4089 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 74]
4144
4145 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 75]
4200
4201 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 76]
4256
4257 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 77]
4312
4313 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 78]
4368
4369 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 79]
4424
4425 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 80]
4480
4481 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 81]
4536
4537 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 82]
4592
4593 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 83]
4648
4649 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 84]
4704
4705 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 85]
4760
4761 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 86]
4816
4817 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 87]
4872
4873 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 88]
4928
4929 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 89]
4984
4985 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 90]
5040
5041 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 91]
5096
5097 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 92]
5152
5153 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 93]
5208
5209 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 94]
5264
5265 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 95]
5320
5321 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 96]
5376
5377 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 97]
5432
5433 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 98]
5488
5489 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 99]
5544
5545 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 100]
5600
5601 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 101]
5656
5657 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 102]
5712
5713 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 103]
5768
5769 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 104]
5824
5825 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 105]
5880
5881 Internet-Draft LinuxSampler Control Protocol October 2010
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 April 8, 2011 [Page 106]
5936
5937 Internet-Draft LinuxSampler Control Protocol October 2010
5938
5939
5940 DESCRIPTION -
5941