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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1556 - (show annotations) (download)
Thu Dec 6 01:46:03 2007 UTC (12 years, 4 months ago) by schoenebeck
File MIME type: text/plain
File size: 229256 byte(s)
- commited LSCP 1.3 specs of the next upcoming LS release

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