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

  ViewVC Help
Powered by ViewVC