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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1390 - (show annotations) (download)
Sun Oct 7 14:07:48 2007 UTC (11 years, 2 months ago) by schoenebeck
File MIME type: text/plain
File size: 221140 byte(s)
* updated LSCP specs draft regarding escape sequences

1
2
3
4 LinuxSampler Developers C. Schoenebeck
5 Internet-Draft Interessengemeinschaft Software
6 Intended status: Standards Track Engineering e. V.
7 Expires: April 9, 2008 October 7, 2007
8
9
10 LinuxSampler Control Protocol (draft)
11 LSCP 1.2cvs
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 April 9, 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 April 9, 2008 [Page 1]
56
57 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 2]
112
113 Internet-Draft LinuxSampler Control Protocol (draft) October 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 . . . . . . 45
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 . . . . . . . . . 47
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 . . . . . . . . . . . . 55
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 . . . . . . . . . . . . . . 60
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 . . . 63
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 . . . . 64
153 6.4.29. Getting effect send information . . . . . . . . . . . 65
154 6.4.30. Changing effect send's name . . . . . . . . . . . . . 66
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 . . . . . . . . . . . . . . . . . 70
160 6.5.1. Register front-end for receiving event messages . . . 70
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 April 9, 2008 [Page 3]
168
169 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
170
171
172 6.5.4. Close client connection . . . . . . . . . . . . . . . 72
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. Reset sampler . . . . . . . . . . . . . . . . . . . . 73
177 6.6.4. General sampler informations . . . . . . . . . . . . 74
178 6.6.5. Getting global volume attenuation . . . . . . . . . . 74
179 6.6.6. Setting global volume attenuation . . . . . . . . . . 75
180 6.7. MIDI Instrument Mapping . . . . . . . . . . . . . . . . . 75
181 6.7.1. Create a new MIDI instrument map . . . . . . . . . . 76
182 6.7.2. Delete one particular or all MIDI instrument maps . . 77
183 6.7.3. Get amount of existing MIDI instrument maps . . . . . 78
184 6.7.4. Getting all created MIDI instrument maps . . . . . . 78
185 6.7.5. Getting MIDI instrument map information . . . . . . . 78
186 6.7.6. Renaming a MIDI instrument map . . . . . . . . . . . 79
187 6.7.7. Create or replace a MIDI instrument map entry . . . . 80
188 6.7.8. Getting ammount of MIDI instrument map entries . . . 83
189 6.7.9. Getting indeces of all entries of a MIDI
190 instrument map . . . . . . . . . . . . . . . . . . . 83
191 6.7.10. Remove an entry from the MIDI instrument map . . . . 84
192 6.7.11. Get current settings of MIDI instrument map entry . . 85
193 6.7.12. Clear MIDI instrument map . . . . . . . . . . . . . . 86
194 6.8. Managing Instruments Database . . . . . . . . . . . . . . 87
195 6.8.1. Creating a new instrument directory . . . . . . . . . 87
196 6.8.2. Deleting an instrument directory . . . . . . . . . . 88
197 6.8.3. Getting amount of instrument directories . . . . . . 89
198 6.8.4. Listing all directories in specific directory . . . . 89
199 6.8.5. Getting instrument directory information . . . . . . 90
200 6.8.6. Renaming an instrument directory . . . . . . . . . . 91
201 6.8.7. Moving an instrument directory . . . . . . . . . . . 91
202 6.8.8. Copying instrument directories . . . . . . . . . . . 92
203 6.8.9. Changing the description of directory . . . . . . . . 93
204 6.8.10. Finding directories . . . . . . . . . . . . . . . . . 93
205 6.8.11. Adding instruments to the instruments database . . . 95
206 6.8.12. Removing an instrument . . . . . . . . . . . . . . . 96
207 6.8.13. Getting amount of instruments . . . . . . . . . . . . 97
208 6.8.14. Listing all instruments in specific directory . . . . 97
209 6.8.15. Getting instrument information . . . . . . . . . . . 98
210 6.8.16. Renaming an instrument . . . . . . . . . . . . . . . 100
211 6.8.17. Moving an instrument . . . . . . . . . . . . . . . . 101
212 6.8.18. Copying instruments . . . . . . . . . . . . . . . . . 102
213 6.8.19. Changing the description of instrument . . . . . . . 102
214 6.8.20. Finding instruments . . . . . . . . . . . . . . . . . 103
215 6.8.21. Getting job status information . . . . . . . . . . . 105
216 6.8.22. Formatting the instruments database . . . . . . . . . 106
217 6.9. Editing Instruments . . . . . . . . . . . . . . . . . . . 107
218 6.9.1. Opening an appropriate instrument editor
219 application . . . . . . . . . . . . . . . . . . . . . 107
220
221
222
223 Schoenebeck Expires April 9, 2008 [Page 4]
224
225 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
226
227
228 7. Command Syntax . . . . . . . . . . . . . . . . . . . . . . . 109
229 7.1. Character Set and Escape Sequences . . . . . . . . . . . 122
230 8. Events . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
231 8.1. Number of audio output devices changed . . . . . . . . . 126
232 8.2. Audio output device's settings changed . . . . . . . . . 126
233 8.3. Number of MIDI input devices changed . . . . . . . . . . 126
234 8.4. MIDI input device's settings changed . . . . . . . . . . 127
235 8.5. Number of sampler channels changed . . . . . . . . . . . 127
236 8.6. Number of active voices changed . . . . . . . . . . . . . 127
237 8.7. Number of active disk streams changed . . . . . . . . . . 128
238 8.8. Disk stream buffer fill state changed . . . . . . . . . . 128
239 8.9. Channel information changed . . . . . . . . . . . . . . . 128
240 8.10. Number of effect sends changed . . . . . . . . . . . . . 129
241 8.11. Effect send information changed . . . . . . . . . . . . . 129
242 8.12. Total number of active voices changed . . . . . . . . . . 129
243 8.13. Number of MIDI instrument maps changed . . . . . . . . . 130
244 8.14. MIDI instrument map information changed . . . . . . . . . 130
245 8.15. Number of MIDI instruments changed . . . . . . . . . . . 130
246 8.16. MIDI instrument information changed . . . . . . . . . . . 131
247 8.17. Global settings changed . . . . . . . . . . . . . . . . . 131
248 8.18. Number of database instrument directories changed . . . . 132
249 8.19. Database instrument directory information changed . . . . 132
250 8.20. Number of database instruments changed . . . . . . . . . 133
251 8.21. Database instrument information changed . . . . . . . . . 133
252 8.22. Database job status information changed . . . . . . . . . 134
253 8.23. Miscellaneous and debugging events . . . . . . . . . . . 134
254 9. Security Considerations . . . . . . . . . . . . . . . . . . . 135
255 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 136
256 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 137
257 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 138
258 Intellectual Property and Copyright Statements . . . . . . . . . 139
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279 Schoenebeck Expires April 9, 2008 [Page 5]
280
281 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 6]
336
337 Internet-Draft LinuxSampler Control Protocol (draft) October 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.4) 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 April 9, 2008 [Page 7]
392
393 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 8]
448
449 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 9]
504
505 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 10]
560
561 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 11]
616
617 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 12]
672
673 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 13]
728
729 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 14]
784
785 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 15]
840
841 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 16]
896
897 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 17]
952
953 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 18]
1008
1009 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 19]
1064
1065 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 20]
1120
1121 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 21]
1176
1177 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 22]
1232
1233 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 23]
1288
1289 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 24]
1344
1345 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 25]
1400
1401 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 26]
1456
1457 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 27]
1512
1513 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 28]
1568
1569 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 29]
1624
1625 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 30]
1680
1681 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 31]
1736
1737 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 32]
1792
1793 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 33]
1848
1849 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 34]
1904
1905 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 35]
1960
1961 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 36]
2016
2017 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 37]
2072
2073 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 38]
2128
2129 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 39]
2184
2185 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 40]
2240
2241 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 41]
2296
2297 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 42]
2352
2353 Internet-Draft LinuxSampler Control Protocol (draft) October 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 April 9, 2008 [Page 43]
2408
2409 Internet-Draft LinuxSampler Control Protocol (draft) October 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:
2435
2436
2437
2438 6.4.2. Loading a sampler engine
2439
2440 A sampler engine type can be associated to a specific sampler channel
2441 by the following command:
2442
2443 LOAD ENGINE <engine-name> <sampler-channel>
2444
2445 Where <engine-name> is an engine name as obtained by the "LIST
2446 AVAILABLE_ENGINES" (Section 6.4.8) command and <sampler-channel> the
2447 sampler channel as returned by the "ADD CHANNEL" (Section 6.4.5) or
2448 "LIST CHANNELS" (Section 6.4.4) command where the engine type should
2449 be assigned to. This command should be issued after adding a new
2450 sampler channel and before any other control commands on the new
2451 sampler channel. It can also be used to change the engine type of a
2452 sampler channel. This command has (currently) no way to define or
2453 force if a new engine instance should be created and assigned to the
2454 given sampler channel or if an already existing instance of that
2455 engine type, shared with other sampler channels, should be used.
2456
2457 Possible Answers:
2458
2459
2460
2461
2462
2463 Schoenebeck Expires April 9, 2008 [Page 44]
2464
2465 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
2466
2467
2468 "OK" -
2469
2470 in case the engine was successfully deployed
2471
2472 "WRN:<warning-code>:<warning-message>" -
2473
2474 in case the engine was deployed successfully, but there are
2475 noteworthy issue(s) related, providing an appropriate warning
2476 code and warning message
2477
2478 "ERR:<error-code>:<error-message>" -
2479
2480 in case it failed, providing an appropriate error code and
2481 error message
2482
2483 Example:
2484
2485
2486
2487 6.4.3. Getting all created sampler channel count
2488
2489 The number of sampler channels can change on runtime. To get the
2490 current amount of sampler channels, the front-end can send the
2491 following command:
2492
2493 GET CHANNELS
2494
2495 Possible Answers:
2496
2497 LinuxSampler will answer by returning the current number of
2498 sampler channels.
2499
2500 Example:
2501
2502 C: "GET CHANNELS"
2503
2504 S: "12"
2505
2506 6.4.4. Getting all created sampler channel list
2507
2508 The number of sampler channels can change on runtime. To get the
2509 current list of sampler channels, the front-end can send the
2510 following command:
2511
2512 LIST CHANNELS
2513
2514 Possible Answers:
2515
2516
2517
2518
2519 Schoenebeck Expires April 9, 2008 [Page 45]
2520
2521 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
2522
2523
2524 LinuxSampler will answer by returning a comma separated list with
2525 all sampler channels numerical IDs.
2526
2527 Example:
2528
2529 C: "LIST CHANNELS"
2530
2531 S: "0,1,2,3,4,5,6,9,10,11,15,20"
2532
2533 6.4.5. Adding a new sampler channel
2534
2535 A new sampler channel can be added to the end of the sampler channel
2536 list by sending the following command:
2537
2538 ADD CHANNEL
2539
2540 This will increment the sampler channel count by one and the new
2541 sampler channel will be appended to the end of the sampler channel
2542 list. The front-end should send the respective, related commands
2543 right after to e.g. load an engine, load an instrument and setting
2544 input, output method and eventually other commands to initialize the
2545 new channel. The front-end should use the sampler channel returned
2546 by the answer of this command to perform the previously recommended
2547 commands, to avoid race conditions e.g. with other front-ends that
2548 might also have sent an "ADD CHANNEL" command.
2549
2550 Possible Answers:
2551
2552 "OK[<sampler-channel>]" -
2553
2554 in case a new sampler channel could be added, where <sampler-
2555 channel> reflects the channel number of the new created sampler
2556 channel which should be used to set up the sampler channel by
2557 sending subsequent initialization commands
2558
2559 "WRN:<warning-code>:<warning-message>" -
2560
2561 in case a new channel was added successfully, but there are
2562 noteworthy issue(s) related, providing an appropriate warning
2563 code and warning message
2564
2565 "ERR:<error-code>:<error-message>" -
2566
2567 in case it failed, providing an appropriate error code and
2568 error message
2569
2570 Example:
2571
2572
2573
2574
2575 Schoenebeck Expires April 9, 2008 [Page 46]
2576
2577 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
2578
2579
2580
2581
2582 6.4.6. Removing a sampler channel
2583
2584 A sampler channel can be removed by sending the following command:
2585
2586 REMOVE CHANNEL <sampler-channel>
2587
2588 Where <sampler-channel> should be replaced by the number of the
2589 sampler channel as given by the "ADD CHANNEL" (Section 6.4.5) or
2590 "LIST CHANNELS" (Section 6.4.4) command. The channel numbers of all
2591 subsequent sampler channels remain the same.
2592
2593 Possible Answers:
2594
2595 "OK" -
2596
2597 in case the given sampler channel could be removed
2598
2599 "WRN:<warning-code>:<warning-message>" -
2600
2601 in case the given channel was removed, but there are noteworthy
2602 issue(s) related, providing an appropriate warning code and
2603 warning message
2604
2605 "ERR:<error-code>:<error-message>" -
2606
2607 in case it failed, providing an appropriate error code and
2608 error message
2609
2610 Example:
2611
2612
2613
2614 6.4.7. Getting amount of available engines
2615
2616 The front-end can ask for the number of available engines by sending
2617 the following command:
2618
2619 GET AVAILABLE_ENGINES
2620
2621 Possible Answers:
2622
2623 LinuxSampler will answer by sending the number of available
2624 engines.
2625
2626 Example:
2627
2628
2629
2630
2631 Schoenebeck Expires April 9, 2008 [Page 47]
2632
2633 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
2634
2635
2636 C: "GET AVAILABLE_ENGINES"
2637
2638 S: "4"
2639
2640 6.4.8. Getting all available engines
2641
2642 The front-end can ask for a list of all available engines by sending
2643 the following command:
2644
2645 LIST AVAILABLE_ENGINES
2646
2647 Possible Answers:
2648
2649 LinuxSampler will answer by sending a comma separated list of the
2650 engines' names encapsulated into apostrophes ('). Engine names
2651 can consist of lower and upper cases, digits and underlines ("_"
2652 character).
2653
2654 Example:
2655
2656 C: "LIST AVAILABLE_ENGINES"
2657
2658 S: "'GigEngine','AkaiEngine','DLSEngine','JoesCustomEngine'"
2659
2660 6.4.9. Getting information about an engine
2661
2662 The front-end can ask for information about a specific engine by
2663 sending the following command:
2664
2665 GET ENGINE INFO <engine-name>
2666
2667 Where <engine-name> is an engine name as obtained by the "LIST
2668 AVAILABLE_ENGINES" (Section 6.4.8) command.
2669
2670 Possible Answers:
2671
2672 LinuxSampler will answer by sending a <CRLF> separated list. Each
2673 answer line begins with the information category name followed by
2674 a colon and then a space character <SP> and finally the info
2675 character string to that info category. At the moment the
2676 following categories are defined:
2677
2678
2679
2680 DESCRIPTION -
2681
2682 arbitrary description text about the engine
2683
2684
2685
2686
2687 Schoenebeck Expires April 9, 2008 [Page 48]
2688
2689 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
2690
2691
2692 VERSION -
2693
2694 arbitrary character string regarding the engine's version
2695
2696 The mentioned fields above don't have to be in particular order.
2697
2698 Example:
2699
2700 C: "GET ENGINE INFO JoesCustomEngine"
2701
2702 S: "DESCRIPTION: this is Joe's custom sampler engine"
2703
2704 "VERSION: testing-1.0"
2705
2706 "."
2707
2708 6.4.10. Getting sampler channel information
2709
2710 The front-end can ask for the current settings of a sampler channel
2711 by sending the following command:
2712
2713 GET CHANNEL INFO <sampler-channel>
2714
2715 Where <sampler-channel> is the sampler channel number the front-end
2716 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2717 "LIST CHANNELS" (Section 6.4.4) command.
2718
2719 Possible Answers:
2720
2721 LinuxSampler will answer by sending a <CRLF> separated list. Each
2722 answer line begins with the settings category name followed by a
2723 colon and then a space character <SP> and finally the info
2724 character string to that setting category. At the moment the
2725 following categories are defined:
2726
2727
2728
2729 ENGINE_NAME -
2730
2731 name of the engine that is associated with the sampler
2732 channel, "NONE" if there's no engine associated yet for this
2733 sampler channel
2734
2735 AUDIO_OUTPUT_DEVICE -
2736
2737 numerical ID of the audio output device which is currently
2738 connected to this sampler channel to output the audio
2739 signal, "NONE" if there's no device connected to this
2740
2741
2742
2743 Schoenebeck Expires April 9, 2008 [Page 49]
2744
2745 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
2746
2747
2748 sampler channel
2749
2750 AUDIO_OUTPUT_CHANNELS -
2751
2752 number of output channels the sampler channel offers
2753 (dependent to used sampler engine and loaded instrument)
2754
2755 AUDIO_OUTPUT_ROUTING -
2756
2757 comma separated list which reflects to which audio channel
2758 of the selected audio output device each sampler output
2759 channel is routed to, e.g. "0,3" would mean the engine's
2760 output channel 0 is routed to channel 0 of the audio output
2761 device and the engine's output channel 1 is routed to the
2762 channel 3 of the audio output device
2763
2764 INSTRUMENT_FILE -
2765
2766 the file name of the loaded instrument, "NONE" if there's no
2767 instrument yet loaded for this sampler channel
2768
2769 INSTRUMENT_NR -
2770
2771 the instrument index number of the loaded instrument
2772
2773 INSTRUMENT_NAME -
2774
2775 the instrument name of the loaded instrument
2776
2777 INSTRUMENT_STATUS -
2778
2779 integer values 0 to 100 indicating loading progress
2780 percentage for the instrument. Negative value indicates a
2781 loading exception. Value of 100 indicates that the
2782 instrument is fully loaded.
2783
2784 MIDI_INPUT_DEVICE -
2785
2786 numerical ID of the MIDI input device which is currently
2787 connected to this sampler channel to deliver MIDI input
2788 commands, "NONE" if there's no device connected to this
2789 sampler channel
2790
2791 MIDI_INPUT_PORT -
2792
2793 port number of the MIDI input device
2794
2795
2796
2797
2798
2799 Schoenebeck Expires April 9, 2008 [Page 50]
2800
2801 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
2802
2803
2804 MIDI_INPUT_CHANNEL -
2805
2806 the MIDI input channel number this sampler channel should
2807 listen to or "ALL" to listen on all MIDI channels
2808
2809 VOLUME -
2810
2811 optionally dotted number for the channel volume factor
2812 (where a value < 1.0 means attenuation and a value > 1.0
2813 means amplification)
2814
2815 MUTE -
2816
2817 Determines whether the channel is muted, "true" if the
2818 channel is muted, "false" if the channel is not muted, and
2819 "MUTED_BY_SOLO" if the channel is muted because of the
2820 presence of a solo channel and will be unmuted when there
2821 are no solo channels left
2822
2823 SOLO -
2824
2825 Determines whether this is a solo channel, "true" if the
2826 channel is a solo channel; "false" otherwise
2827
2828 MIDI_INSTRUMENT_MAP -
2829
2830 Determines to which MIDI instrument map this sampler channel
2831 is assigned to. Read chapter "SET CHANNEL
2832 MIDI_INSTRUMENT_MAP" (Section 6.4.24) for a list of possible
2833 values.
2834
2835 The mentioned fields above don't have to be in particular order.
2836
2837 Example:
2838
2839 C: "GET CHANNEL INFO 34"
2840
2841 S: "ENGINE_NAME: GigEngine"
2842
2843 "VOLUME: 1.0"
2844
2845 "AUDIO_OUTPUT_DEVICE: 0"
2846
2847 "AUDIO_OUTPUT_CHANNELS: 2"
2848
2849 "AUDIO_OUTPUT_ROUTING: 0,1"
2850
2851
2852
2853
2854
2855 Schoenebeck Expires April 9, 2008 [Page 51]
2856
2857 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
2858
2859
2860 "INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"
2861
2862 "INSTRUMENT_NR: 0"
2863
2864 "INSTRUMENT_NAME: Fazioli Piano"
2865
2866 "INSTRUMENT_STATUS: 100"
2867
2868 "MIDI_INPUT_DEVICE: 0"
2869
2870 "MIDI_INPUT_PORT: 0"
2871
2872 "MIDI_INPUT_CHANNEL: 5"
2873
2874 "VOLUME: 1.0"
2875
2876 "MUTE: false"
2877
2878 "SOLO: false"
2879
2880 "MIDI_INSTRUMENT_MAP: NONE"
2881
2882 "."
2883
2884 6.4.11. Current number of active voices
2885
2886 The front-end can ask for the current number of active voices on a
2887 sampler channel by sending the following command:
2888
2889 GET CHANNEL VOICE_COUNT <sampler-channel>
2890
2891 Where <sampler-channel> is the sampler channel number the front-end
2892 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2893 "LIST CHANNELS" (Section 6.4.4) command.
2894
2895 Possible Answers:
2896
2897 LinuxSampler will answer by returning the number of active voices
2898 on that channel.
2899
2900 Example:
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911 Schoenebeck Expires April 9, 2008 [Page 52]
2912
2913 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
2914
2915
2916 6.4.12. Current number of active disk streams
2917
2918 The front-end can ask for the current number of active disk streams
2919 on a sampler channel by sending the following command:
2920
2921 GET CHANNEL STREAM_COUNT <sampler-channel>
2922
2923 Where <sampler-channel> is the sampler channel number the front-end
2924 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2925 "LIST CHANNELS" (Section 6.4.4) command.
2926
2927 Possible Answers:
2928
2929 LinuxSampler will answer by returning the number of active disk
2930 streams on that channel in case the engine supports disk
2931 streaming, if the engine doesn't support disk streaming it will
2932 return "NA" for not available.
2933
2934 Example:
2935
2936
2937
2938 6.4.13. Current fill state of disk stream buffers
2939
2940 The front-end can ask for the current fill state of all disk streams
2941 on a sampler channel by sending the following command:
2942
2943 GET CHANNEL BUFFER_FILL BYTES <sampler-channel>
2944
2945 to get the fill state in bytes or
2946
2947 GET CHANNEL BUFFER_FILL PERCENTAGE <sampler-channel>
2948
2949 to get the fill state in percent, where <sampler-channel> is the
2950 sampler channel number the front-end is interested in as returned by
2951 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
2952 command.
2953
2954 Possible Answers:
2955
2956 LinuxSampler will either answer by returning a comma separated
2957 string with the fill state of all disk stream buffers on that
2958 channel or an empty line if there are no active disk streams or
2959 "NA" for *not available* in case the engine which is deployed
2960 doesn't support disk streaming. Each entry in the answer list
2961 will begin with the stream's ID in brackets followed by the
2962 numerical representation of the fill size (either in bytes or
2963 percentage). Note: due to efficiency reasons the fill states in
2964
2965
2966
2967 Schoenebeck Expires April 9, 2008 [Page 53]
2968
2969 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
2970
2971
2972 the response are not in particular order, thus the front-end has
2973 to sort them by itself if necessary.
2974
2975 Examples:
2976
2977 C: "GET CHANNEL BUFFER_FILL BYTES 4"
2978
2979 S: "[115]420500,[116]510300,[75]110000,[120]230700"
2980
2981 C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
2982
2983 S: "[115]90%,[116]98%,[75]40%,[120]62%"
2984
2985 C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
2986
2987 S: ""
2988
2989 6.4.14. Setting audio output device
2990
2991 The front-end can set the audio output device on a specific sampler
2992 channel by sending the following command:
2993
2994 SET CHANNEL AUDIO_OUTPUT_DEVICE <sampler-channel>
2995 <audio-device-id>
2996
2997 Where <sampler-channel> is the respective sampler channel number as
2998 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
2999 (Section 6.4.4) command and <audio-device-id> is the numerical ID of
3000 the audio output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
3001 (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
3002 command.
3003
3004 Possible Answers:
3005
3006 "OK" -
3007
3008 on success
3009
3010 "WRN:<warning-code>:<warning-message>" -
3011
3012 if audio output device was set, but there are noteworthy
3013 issue(s) related, providing an appropriate warning code and
3014 warning message
3015
3016 "ERR:<error-code>:<error-message>" -
3017
3018 in case it failed, providing an appropriate error code and
3019 error message
3020
3021
3022
3023 Schoenebeck Expires April 9, 2008 [Page 54]
3024
3025 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3026
3027
3028 Examples:
3029
3030
3031
3032 6.4.15. Setting audio output type
3033
3034 DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
3035
3036 The front-end can alter the audio output type on a specific sampler
3037 channel by sending the following command:
3038
3039 SET CHANNEL AUDIO_OUTPUT_TYPE <sampler-channel> <audio-output-
3040 type>
3041
3042 Where <audio-output-type> is currently either "ALSA" or "JACK" and
3043 <sampler-channel> is the respective sampler channel number.
3044
3045 Possible Answers:
3046
3047 "OK" -
3048
3049 on success
3050
3051 "WRN:<warning-code>:<warning-message>" -
3052
3053 if audio output type was set, but there are noteworthy issue(s)
3054 related, providing an appropriate warning code and warning
3055 message
3056
3057 "ERR:<error-code>:<error-message>" -
3058
3059 in case it failed, providing an appropriate error code and
3060 error message
3061
3062 Examples:
3063
3064
3065
3066 6.4.16. Setting audio output channel
3067
3068 The front-end can alter the audio output channel on a specific
3069 sampler channel by sending the following command:
3070
3071 SET CHANNEL AUDIO_OUTPUT_CHANNEL <sampler-chan> <audio-out>
3072 <audio-in>
3073
3074 Where <sampler-chan> is the sampler channel number as returned by the
3075 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3076
3077
3078
3079 Schoenebeck Expires April 9, 2008 [Page 55]
3080
3081 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3082
3083
3084 command, <audio-out> is the numerical ID of the sampler channel's
3085 audio output channel which should be rerouted and <audio-in> is the
3086 numerical ID of the audio channel of the selected audio output device
3087 where <audio-out> should be routed to.
3088
3089 Possible Answers:
3090
3091 "OK" -
3092
3093 on success
3094
3095 "WRN:<warning-code>:<warning-message>" -
3096
3097 if audio output channel was set, but there are noteworthy
3098 issue(s) related, providing an appropriate warning code and
3099 warning message
3100
3101 "ERR:<error-code>:<error-message>" -
3102
3103 in case it failed, providing an appropriate error code and
3104 error message
3105
3106 Examples:
3107
3108
3109
3110 6.4.17. Setting MIDI input device
3111
3112 The front-end can set the MIDI input device on a specific sampler
3113 channel by sending the following command:
3114
3115 SET CHANNEL MIDI_INPUT_DEVICE <sampler-channel> <midi-device-id>
3116
3117 Where <sampler-channel> is the sampler channel number as returned by
3118 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3119 command and <midi-device-id> is the numerical ID of the MIDI input
3120 device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5)
3121 or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command.
3122
3123 Possible Answers:
3124
3125 "OK" -
3126
3127 on success
3128
3129 "WRN:<warning-code>:<warning-message>" -
3130
3131
3132
3133
3134
3135 Schoenebeck Expires April 9, 2008 [Page 56]
3136
3137 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3138
3139
3140 if MIDI input device was set, but there are noteworthy issue(s)
3141 related, providing an appropriate warning code and warning
3142 message
3143
3144 "ERR:<error-code>:<error-message>" -
3145
3146 in case it failed, providing an appropriate error code and
3147 error message
3148
3149 Examples:
3150
3151
3152
3153 6.4.18. Setting MIDI input type
3154
3155 DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
3156
3157 The front-end can alter the MIDI input type on a specific sampler
3158 channel by sending the following command:
3159
3160 SET CHANNEL MIDI_INPUT_TYPE <sampler-channel> <midi-input-type>
3161
3162 Where <midi-input-type> is currently only "ALSA" and <sampler-
3163 channel> is the respective sampler channel number.
3164
3165 Possible Answers:
3166
3167 "OK" -
3168
3169 on success
3170
3171 "WRN:<warning-code>:<warning-message>" -
3172
3173 if MIDI input type was set, but there are noteworthy issue(s)
3174 related, providing an appropriate warning code and warning
3175 message
3176
3177 "ERR:<error-code>:<error-message>" -
3178
3179 in case it failed, providing an appropriate error code and
3180 error message
3181
3182 Examples:
3183
3184
3185
3186
3187
3188
3189
3190
3191 Schoenebeck Expires April 9, 2008 [Page 57]
3192
3193 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3194
3195
3196 6.4.19. Setting MIDI input port
3197
3198 The front-end can alter the MIDI input port on a specific sampler
3199 channel by sending the following command:
3200
3201 SET CHANNEL MIDI_INPUT_PORT <sampler-channel> <midi-input-port>
3202
3203 Where <midi-input-port> is a MIDI input port number of the MIDI input
3204 device connected to the sampler channel given by <sampler-channel>.
3205
3206 Possible Answers:
3207
3208 "OK" -
3209
3210 on success
3211
3212 "WRN:<warning-code>:<warning-message>" -
3213
3214 if MIDI input port was set, but there are noteworthy issue(s)
3215 related, providing an appropriate warning code and warning
3216 message
3217
3218 "ERR:<error-code>:<error-message>" -
3219
3220 in case it failed, providing an appropriate error code and
3221 error message
3222
3223 Examples:
3224
3225
3226
3227 6.4.20. Setting MIDI input channel
3228
3229 The front-end can alter the MIDI channel a sampler channel should
3230 listen to by sending the following command:
3231
3232 SET CHANNEL MIDI_INPUT_CHANNEL <sampler-channel> <midi-input-chan>
3233
3234 Where <midi-input-chan> is the number of the new MIDI input channel
3235 where <sampler-channel> should listen to or "ALL" to listen on all 16
3236 MIDI channels.
3237
3238 Possible Answers:
3239
3240 "OK" -
3241
3242 on success
3243
3244
3245
3246
3247 Schoenebeck Expires April 9, 2008 [Page 58]
3248
3249 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3250
3251
3252 "WRN:<warning-code>:<warning-message>" -
3253
3254 if MIDI input channel was set, but there are noteworthy
3255 issue(s) related, providing an appropriate warning code and
3256 warning message
3257
3258 "ERR:<error-code>:<error-message>" -
3259
3260 in case it failed, providing an appropriate error code and
3261 error message
3262
3263 Examples:
3264
3265
3266
3267 6.4.21. Setting channel volume
3268
3269 The front-end can alter the volume of a sampler channel by sending
3270 the following command:
3271
3272 SET CHANNEL VOLUME <sampler-channel> <volume>
3273
3274 Where <volume> is an optionally dotted positive number (a value
3275 smaller than 1.0 means attenuation, whereas a value greater than 1.0
3276 means amplification) and <sampler-channel> defines the sampler
3277 channel where this volume factor should be set.
3278
3279 Possible Answers:
3280
3281 "OK" -
3282
3283 on success
3284
3285 "WRN:<warning-code>:<warning-message>" -
3286
3287 if channel volume was set, but there are noteworthy issue(s)
3288 related, providing an appropriate warning code and warning
3289 message
3290
3291 "ERR:<error-code>:<error-message>" -
3292
3293 in case it failed, providing an appropriate error code and
3294 error message
3295
3296 Examples:
3297
3298
3299
3300
3301
3302
3303 Schoenebeck Expires April 9, 2008 [Page 59]
3304
3305 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3306
3307
3308
3309
3310 6.4.22. Muting a sampler channel
3311
3312 The front-end can mute/unmute a specific sampler channel by sending
3313 the following command:
3314
3315 SET CHANNEL MUTE <sampler-channel> <mute>
3316
3317 Where <sampler-channel> is the respective sampler channel number as
3318 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3319 (Section 6.4.4) command and <mute> should be replaced either by "1"
3320 to mute the channel or "0" to unmute the channel.
3321
3322 Possible Answers:
3323
3324 "OK" -
3325
3326 on success
3327
3328 "WRN:<warning-code>:<warning-message>" -
3329
3330 if the channel was muted/unmuted, but there are noteworthy
3331 issue(s) related, providing an appropriate warning code and
3332 warning message
3333
3334 "ERR:<error-code>:<error-message>" -
3335
3336 in case it failed, providing an appropriate error code and
3337 error message
3338
3339 Examples:
3340
3341
3342
3343 6.4.23. Soloing a sampler channel
3344
3345 The front-end can solo/unsolo a specific sampler channel by sending
3346 the following command:
3347
3348 SET CHANNEL SOLO <sampler-channel> <solo>
3349
3350 Where <sampler-channel> is the respective sampler channel number as
3351 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3352 (Section 6.4.4) command and <solo> should be replaced either by "1"
3353 to solo the channel or "0" to unsolo the channel.
3354
3355 Possible Answers:
3356
3357
3358
3359 Schoenebeck Expires April 9, 2008 [Page 60]
3360
3361 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3362
3363
3364 "OK" -
3365
3366 on success
3367
3368 "WRN:<warning-code>:<warning-message>" -
3369
3370 if the channel was soloed/unsoloed, but there are noteworthy
3371 issue(s) related, providing an appropriate warning code and
3372 warning message
3373
3374 "ERR:<error-code>:<error-message>" -
3375
3376 in case it failed, providing an appropriate error code and
3377 error message
3378
3379 Examples:
3380
3381
3382
3383 6.4.24. Assigning a MIDI instrument map to a sampler channel
3384
3385 The front-end can assign a MIDI instrument map to a specific sampler
3386 channel by sending the following command:
3387
3388 SET CHANNEL MIDI_INSTRUMENT_MAP <sampler-channel> <map>
3389
3390 Where <sampler-channel> is the respective sampler channel number as
3391 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3392 (Section 6.4.4) command and <map> can have the following
3393 possibilites:
3394
3395 "NONE" -
3396
3397 This is the default setting. In this case the sampler channel
3398 is not assigned any MIDI instrument map and thus will ignore
3399 all MIDI program change messages.
3400
3401 "DEFAULT" -
3402
3403 The sampler channel will always use the default MIDI instrument
3404 map to handle MIDI program change messages.
3405
3406 numeric ID -
3407
3408 You can assign a specific MIDI instrument map by replacing
3409 <map> with the respective numeric ID of the MIDI instrument map
3410 as returned by the "LIST MIDI_INSTRUMENT_MAPS" (Section 6.7.4)
3411 command. Once that map will be deleted, the sampler channel
3412
3413
3414
3415 Schoenebeck Expires April 9, 2008 [Page 61]
3416
3417 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3418
3419
3420 would fall back to "NONE".
3421
3422 Read chapter "MIDI Instrument Mapping" (Section 6.7) for details
3423 regarding MIDI instrument mapping.
3424
3425 Possible Answers:
3426
3427 "OK" -
3428
3429 on success
3430
3431 "ERR:<error-code>:<error-message>" -
3432
3433 in case it failed, providing an appropriate error code and
3434 error message
3435
3436 Examples:
3437
3438
3439
3440 6.4.25. Adding an effect send to a sampler channel
3441
3442 The front-end can create an additional effect send on a specific
3443 sampler channel by sending the following command:
3444
3445 CREATE FX_SEND <sampler-channel> <midi-ctrl> [<name>]
3446
3447 Where <sampler-channel> is the respective sampler channel number as
3448 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3449 (Section 6.4.4) command, that is the sampler channel on which the
3450 effect send should be created on, <midi-ctrl> is a number between
3451 0..127 defining the MIDI controller which can alter the effect send
3452 level and <name> is an optional argument defining a name for the
3453 effect send entity. The name does not have to be unique, but MUST be
3454 encapsulated into apostrophes and supports escape sequences as
3455 described in chapter "Character Set and Escape Sequences
3456 (Section 7.1)".
3457
3458 By default, that is as initial routing, the effect send's audio
3459 channels are automatically routed to the last audio channels of the
3460 sampler channel's audio output device, that way you can i.e. first
3461 increase the amount of audio channels on the audio output device for
3462 having dedicated effect send output channels and when "CREATE
3463 FX_SEND" is called, those channels will automatically be picked. You
3464 can alter the destination channels however with "SET FX_SEND
3465 AUDIO_OUTPUT_CHANNEL" (Section 6.4.31).
3466
3467 Note: Create effect sends on a sampler channel only when needed,
3468
3469
3470
3471 Schoenebeck Expires April 9, 2008 [Page 62]
3472
3473 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3474
3475
3476 because having effect sends on a sampler channel will decrease
3477 runtime performance, because for implementing channel effect sends,
3478 separate (sampler channel local) audio buffers are needed to render
3479 and mix the voices and route the audio signal afterwards to the
3480 master outputs and effect send outputs (along with their respective
3481 effect send levels). A sampler channel without effect sends however
3482 can mix its voices directly into the audio output devices's audio
3483 buffers and is thus faster.
3484
3485 Possible Answers:
3486
3487 "OK[<fx-send-id>]" -
3488
3489 in case a new effect send could be added to the sampler
3490 channel, where <fx-send-id> reflects the unique ID of the newly
3491 created effect send entity
3492
3493 "ERR:<error-code>:<error-message>" -
3494
3495 when a new effect send could not be added, i.e. due to invalid
3496 parameters
3497
3498 Examples:
3499
3500 C: "CREATE FX_SEND 0 91 'Reverb Send'"
3501
3502 S: "OK[0]"
3503
3504 C: "CREATE FX_SEND 0 93"
3505
3506 S: "OK[1]"
3507
3508 6.4.26. Removing an effect send from a sampler channel
3509
3510 The front-end can remove an existing effect send on a specific
3511 sampler channel by sending the following command:
3512
3513 DESTROY FX_SEND <sampler-channel> <fx-send-id>
3514
3515 Where <sampler-channel> is the respective sampler channel number as
3516 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3517 (Section 6.4.4) command, that is the sampler channel from which the
3518 effect send should be removed from and <fx-send-id> is the respective
3519 effect send number as returned by the "CREATE FX_SEND"
3520 (Section 6.4.25) or "LIST FX_SENDS" (Section 6.4.28) command.
3521
3522 Possible Answers:
3523
3524
3525
3526
3527 Schoenebeck Expires April 9, 2008 [Page 63]
3528
3529 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3530
3531
3532 "OK" -
3533
3534 on success
3535
3536 "ERR:<error-code>:<error-message>" -
3537
3538 in case it failed, providing an appropriate error code and
3539 error message
3540
3541 Example:
3542
3543 C: "DESTROY FX_SEND 0 0"
3544
3545 S: "OK"
3546
3547 6.4.27. Getting amount of effect sends on a sampler channel
3548
3549 The front-end can ask for the amount of effect sends on a specific
3550 sampler channel by sending the following command:
3551
3552 GET FX_SENDS <sampler-channel>
3553
3554 Where <sampler-channel> is the respective sampler channel number as
3555 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3556 (Section 6.4.4) command.
3557
3558 Possible Answers:
3559
3560 The sampler will answer by returning the number of effect sends on
3561 the given sampler channel.
3562
3563 Example:
3564
3565 C: "GET FX_SENDS 0"
3566
3567 S: "2"
3568
3569 6.4.28. Listing all effect sends on a sampler channel
3570
3571 The front-end can ask for a list of effect sends on a specific
3572 sampler channel by sending the following command:
3573
3574 LIST FX_SENDS <sampler-channel>
3575
3576 Where <sampler-channel> is the respective sampler channel number as
3577 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3578 (Section 6.4.4) command.
3579
3580
3581
3582
3583 Schoenebeck Expires April 9, 2008 [Page 64]
3584
3585 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3586
3587
3588 Possible Answers:
3589
3590 The sampler will answer by returning a comma separated list with
3591 all effect sends' numerical IDs on the given sampler channel.
3592
3593 Examples:
3594
3595 C: "LIST FX_SENDS 0"
3596
3597 S: "0,1"
3598
3599 C: "LIST FX_SENDS 1"
3600
3601 S: ""
3602
3603 6.4.29. Getting effect send information
3604
3605 The front-end can ask for the current settings of an effect send
3606 entity by sending the following command:
3607
3608 GET FX_SEND INFO <sampler-channel> <fx-send-id>
3609
3610 Where <sampler-channel> is the sampler channel number as returned by
3611 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3612 command and <fx-send-id> reflects the numerical ID of the effect send
3613 entity as returned by the "CREATE FX_SEND" (Section 6.4.25) or "LIST
3614 FX_SENDS" (Section 6.4.28) command.
3615
3616 Possible Answers:
3617
3618 The sampler will answer by sending a <CRLF> separated list. Each
3619 answer line begins with the settings category name followed by a
3620 colon and then a space character <SP> and finally the info
3621 character string to that setting category. At the moment the
3622 following categories are defined:
3623
3624
3625
3626 NAME -
3627
3628 name of the effect send entity
3629
3630 MIDI_CONTROLLER -
3631
3632 a value between 0 and 127 reflecting the MIDI controller
3633 which is able to modify the effect send's send level
3634
3635
3636
3637
3638
3639 Schoenebeck Expires April 9, 2008 [Page 65]
3640
3641 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3642
3643
3644 LEVEL -
3645
3646 optionally dotted number reflecting the effect send's
3647 current send level (where a value < 1.0 means attenuation
3648 and a value > 1.0 means amplification)
3649
3650 AUDIO_OUTPUT_ROUTING -
3651
3652 comma separated list which reflects to which audio channel
3653 of the selected audio output device each effect send output
3654 channel is routed to, e.g. "0,3" would mean the effect
3655 send's output channel 0 is routed to channel 0 of the audio
3656 output device and the effect send's output channel 1 is
3657 routed to the channel 3 of the audio output device (see "SET
3658 FX_SEND AUDIO_OUTPUT_CHANNEL" (Section 6.4.31) for details)
3659
3660 The mentioned fields above don't have to be in particular order.
3661
3662 Example:
3663
3664 C: "GET FX_SEND INFO 0 0"
3665
3666 S: "NAME: Reverb Send"
3667
3668 "MIDI_CONTROLLER: 91"
3669
3670 "LEVEL: 0.3"
3671
3672 "AUDIO_OUTPUT_ROUTING: 2,3"
3673
3674 "."
3675
3676 6.4.30. Changing effect send's name
3677
3678 The front-end can alter the current name of an effect send entity by
3679 sending the following command:
3680
3681 SET FX_SEND NAME <sampler-chan> <fx-send-id> <name>
3682
3683 Where <sampler-chan> is the sampler channel number as returned by the
3684 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3685 command, <fx-send-id> reflects the numerical ID of the effect send
3686 entity as returned by the "CREATE FX_SEND" (Section 6.4.25) or "LIST
3687 FX_SENDS" (Section 6.4.28) command and <name> is the new name of the
3688 effect send entity, which does not have to be unique (name MUST be
3689 encapsulated into apostrophes and supports escape sequences as
3690 described in chapter "Character Set and Escape Sequences
3691 (Section 7.1)").
3692
3693
3694
3695 Schoenebeck Expires April 9, 2008 [Page 66]
3696
3697 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3698
3699
3700 Possible Answers:
3701
3702 "OK" -
3703
3704 on success
3705
3706 "ERR:<error-code>:<error-message>" -
3707
3708 in case it failed, providing an appropriate error code and
3709 error message
3710
3711 Example:
3712
3713 C: "SET FX_SEND NAME 0 0 'Fx Send 1'"
3714
3715 S: "OK"
3716
3717 6.4.31. Altering effect send's audio routing
3718
3719 The front-end can alter the destination of an effect send's audio
3720 channel on a specific sampler channel by sending the following
3721 command:
3722
3723 SET FX_SEND AUDIO_OUTPUT_CHANNEL <sampler-chan> <fx-send-id>
3724 <audio-src> <audio-dst>
3725
3726 Where <sampler-chan> is the sampler channel number as returned by the
3727 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3728 command, <fx-send-id> reflects the numerical ID of the effect send
3729 entity as returned by the "CREATE FX_SEND" (Section 6.4.25) or "LIST
3730 FX_SENDS" (Section 6.4.28) command, <audio-src> is the numerical ID
3731 of the effect send's audio channel which should be rerouted and
3732 <audio-dst> is the numerical ID of the audio channel of the selected
3733 audio output device where <audio-src> should be routed to.
3734
3735 Note that effect sends can only route audio to the same audio output
3736 device as assigned to the effect send's sampler channel. Also note
3737 that an effect send entity does always have exactly as much audio
3738 channels as its sampler channel. So if the sampler channel is
3739 stereo, the effect send does have two audio channels as well. Also
3740 keep in mind that the amount of audio channels on a sampler channel
3741 might be dependant not only to the deployed sampler engine on the
3742 sampler channel, but also dependant to the instrument currently
3743 loaded. However you can (effectively) turn an i.e. stereo effect
3744 send into a mono one by simply altering its audio routing
3745 appropriately.
3746
3747 Possible Answers:
3748
3749
3750
3751 Schoenebeck Expires April 9, 2008 [Page 67]
3752
3753 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3754
3755
3756 "OK" -
3757
3758 on success
3759
3760 "WRN:<warning-code>:<warning-message>" -
3761
3762 if audio output channel was set, but there are noteworthy
3763 issue(s) related, providing an appropriate warning code and
3764 warning message
3765
3766 "ERR:<error-code>:<error-message>" -
3767
3768 in case it failed, providing an appropriate error code and
3769 error message
3770
3771 Example:
3772
3773 C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2"
3774
3775 S: "OK"
3776
3777 6.4.32. Altering effect send's MIDI controller
3778
3779 The front-end can alter the MIDI controller of an effect send entity
3780 by sending the following command:
3781
3782 SET FX_SEND MIDI_CONTROLLER <sampler-chan> <fx-send-id> <midi-
3783 ctrl>
3784
3785 Where <sampler-chan> is the sampler channel number as returned by the
3786 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3787 command, <fx-send-id> reflects the numerical ID of the effect send
3788 entity as returned by the "CREATE FX_SEND" (Section 6.4.25) or "LIST
3789 FX_SENDS" (Section 6.4.28) command and <midi-ctrl> reflects the MIDI
3790 controller which shall be able to modify the effect send's send
3791 level.
3792
3793 Possible Answers:
3794
3795 "OK" -
3796
3797 on success
3798
3799 "WRN:<warning-code>:<warning-message>" -
3800
3801 if MIDI controller was set, but there are noteworthy issue(s)
3802 related, providing an appropriate warning code and warning
3803 message
3804
3805
3806
3807 Schoenebeck Expires April 9, 2008 [Page 68]
3808
3809 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3810
3811
3812 "ERR:<error-code>:<error-message>" -
3813
3814 in case it failed, providing an appropriate error code and
3815 error message
3816
3817 Example:
3818
3819 C: "SET FX_SEND MIDI_CONTROLLER 0 0 91"
3820
3821 S: "OK"
3822
3823 6.4.33. Altering effect send's send level
3824
3825 The front-end can alter the current send level of an effect send
3826 entity by sending the following command:
3827
3828 SET FX_SEND LEVEL <sampler-chan> <fx-send-id> <volume>
3829
3830 Where <sampler-chan> is the sampler channel number as returned by the
3831 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3832 command, <fx-send-id> reflects the numerical ID of the effect send
3833 entity as returned by the "CREATE FX_SEND" (Section 6.4.25) or "LIST
3834 FX_SENDS" (Section 6.4.28) command and <volume> is an optionally
3835 dotted positive number (a value smaller than 1.0 means attenuation,
3836 whereas a value greater than 1.0 means amplification) reflecting the
3837 new send level.
3838
3839 Possible Answers:
3840
3841 "OK" -
3842
3843 on success
3844
3845 "WRN:<warning-code>:<warning-message>" -
3846
3847 if new send level was set, but there are noteworthy issue(s)
3848 related, providing an appropriate warning code and warning
3849 message
3850
3851 "ERR:<error-code>:<error-message>" -
3852
3853 in case it failed, providing an appropriate error code and
3854 error message
3855
3856 Example:
3857
3858
3859
3860
3861
3862
3863 Schoenebeck Expires April 9, 2008 [Page 69]
3864
3865 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3866
3867
3868 C: "SET FX_SEND LEVEL 0 0 0.15"
3869
3870 S: "OK"
3871
3872 6.4.34. Resetting a sampler channel
3873
3874 The front-end can reset a particular sampler channel by sending the
3875 following command:
3876
3877 RESET CHANNEL <sampler-channel>
3878
3879 Where <sampler-channel> defines the sampler channel to be reset.
3880 This will cause the engine on that sampler channel, its voices and
3881 eventually disk streams and all control and status variables to be
3882 reset.
3883
3884 Possible Answers:
3885
3886 "OK" -
3887
3888 on success
3889
3890 "WRN:<warning-code>:<warning-message>" -
3891
3892 if channel was reset, but there are noteworthy issue(s)
3893 related, providing an appropriate warning code and warning
3894 message
3895
3896 "ERR:<error-code>:<error-message>" -
3897
3898 in case it failed, providing an appropriate error code and
3899 error message
3900
3901 Examples:
3902
3903
3904
3905 6.5. Controlling connection
3906
3907 The following commands are used to control the connection to
3908 LinuxSampler.
3909
3910 6.5.1. Register front-end for receiving event messages
3911
3912 The front-end can register itself to the LinuxSampler application to
3913 be informed about noteworthy events by sending this command:
3914
3915
3916
3917
3918
3919 Schoenebeck Expires April 9, 2008 [Page 70]
3920
3921 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3922
3923
3924 SUBSCRIBE <event-id>
3925
3926 where <event-id> will be replaced by the respective event that client
3927 wants to subscribe to.
3928
3929 Possible Answers:
3930
3931 "OK" -
3932
3933 on success
3934
3935 "WRN:<warning-code>:<warning-message>" -
3936
3937 if registration succeeded, but there are noteworthy issue(s)
3938 related, providing an appropriate warning code and warning
3939 message
3940
3941 "ERR:<error-code>:<error-message>" -
3942
3943 in case it failed, providing an appropriate error code and
3944 error message
3945
3946 Examples:
3947
3948
3949
3950 6.5.2. Unregister front-end for not receiving event messages
3951
3952 The front-end can unregister itself if it doesn't want to receive
3953 event messages anymore by sending the following command:
3954
3955 UNSUBSCRIBE <event-id>
3956
3957 Where <event-id> will be replaced by the respective event that client
3958 doesn't want to receive anymore.
3959
3960 Possible Answers:
3961
3962 "OK" -
3963
3964 on success
3965
3966 "WRN:<warning-code>:<warning-message>" -
3967
3968 if unregistration succeeded, but there are noteworthy issue(s)
3969 related, providing an appropriate warning code and warning
3970 message
3971
3972
3973
3974
3975 Schoenebeck Expires April 9, 2008 [Page 71]
3976
3977 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3978
3979
3980 "ERR:<error-code>:<error-message>" -
3981
3982 in case it failed, providing an appropriate error code and
3983 error message
3984
3985 Examples:
3986
3987
3988
3989 6.5.3. Enable or disable echo of commands
3990
3991 To enable or disable back sending of commands to the client the
3992 following command can be used:
3993
3994 SET ECHO <value>
3995
3996 Where <value> should be replaced either by "1" to enable echo mode or
3997 "0" to disable echo mode. When echo mode is enabled, all commands
3998 send to LinuxSampler will be immediately send back and after this
3999 echo the actual response to the command will be returned. Echo mode
4000 will only be altered for the client connection that issued the "SET
4001 ECHO" command, not globally for all client connections.
4002
4003 Possible Answers:
4004
4005 "OK" -
4006
4007 usually
4008
4009 "ERR:<error-code>:<error-message>" -
4010
4011 on syntax error, e.g. non boolean value
4012
4013 Examples:
4014
4015
4016
4017 6.5.4. Close client connection
4018
4019 The client can close its network connection to LinuxSampler by
4020 sending the following command:
4021
4022 QUIT
4023
4024 This is probably more interesting for manual telnet connections to
4025 LinuxSampler than really useful for a front-end implementation.
4026
4027
4028
4029
4030
4031 Schoenebeck Expires April 9, 2008 [Page 72]
4032
4033 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
4034
4035
4036 6.6. Global commands
4037
4038 The following commands have global impact on the sampler.
4039
4040 6.6.1. Current number of active voices
4041
4042 The front-end can ask for the current number of active voices on the
4043 sampler by sending the following command:
4044
4045 GET TOTAL_VOICE_COUNT
4046
4047 Possible Answers:
4048
4049 LinuxSampler will answer by returning the number of all active
4050 voices on the sampler.
4051
4052 6.6.2. Maximum amount of active voices
4053
4054 The front-end can ask for the maximum number of active voices by
4055 sending the following command:
4056
4057 GET TOTAL_VOICE_COUNT_MAX
4058
4059 Possible Answers:
4060
4061 LinuxSampler will answer by returning the maximum number of active
4062 voices.
4063
4064 6.6.3. Reset sampler
4065
4066 The front-end can reset the whole sampler by sending the following
4067 command:
4068
4069 RESET
4070
4071 Possible Answers:
4072
4073 "OK" -
4074
4075 always
4076
4077 Examples:
4078
4079
4080
4081
4082
4083
4084
4085
4086
4087 Schoenebeck Expires April 9, 2008 [Page 73]
4088
4089 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
4090
4091
4092 6.6.4. General sampler informations
4093
4094 The client can ask for general informations about the LinuxSampler
4095 instance by sending the following command:
4096
4097 GET SERVER INFO
4098
4099 Possible Answers:
4100
4101 LinuxSampler will answer by sending a <CRLF> separated list. Each
4102 answer line begins with the information category name followed by
4103 a colon and then a space character <SP> and finally the info
4104 character string to that information category. At the moment the
4105 following categories are defined:
4106
4107
4108
4109 DESCRIPTION -
4110
4111 arbitrary textual description about the sampler (note that
4112 the character string may contain escape sequences
4113 (Section 7.1))
4114
4115 VERSION -
4116
4117 version of the sampler
4118
4119 PROTOCOL_VERSION -
4120
4121 version of the LSCP specification the sampler complies with
4122 (see Section 2 for details)
4123
4124 INSTRUMENTS_DB_SUPPORT -
4125
4126 either yes or no, specifies whether the sampler is build
4127 with instruments database support.
4128
4129 The mentioned fields above don't have to be in particular order.
4130 Other fields might be added in future.
4131
4132 6.6.5. Getting global volume attenuation
4133
4134 The client can ask for the current global sampler-wide volume
4135 attenuation by sending the following command:
4136
4137 GET VOLUME
4138
4139 Possible Answers:
4140
4141
4142
4143 Schoenebeck Expires April 9, 2008 [Page 74]
4144
4145 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
4146
4147
4148 The sampler will always answer by returning the optional dotted
4149 floating point coefficient, reflecting the current global volume
4150 attenuation.
4151
4152 Note: it is up to the respective sampler engine whether to obey that
4153 global volume parameter or not, but in general all engines SHOULD use
4154 this parameter.
4155
4156 6.6.6. Setting global volume attenuation
4157
4158 The client can alter the current global sampler-wide volume
4159 attenuation by sending the following command:
4160
4161 SET VOLUME <volume>
4162
4163 Where <volume> should be replaced by the optional dotted floating
4164 point value, reflecting the new global volume parameter. This value
4165 might usually be in the range between 0.0 and 1.0, that is for
4166 attenuating the overall volume.
4167
4168 Possible Answers:
4169
4170 "OK" -
4171
4172 on success
4173
4174 "WRN:<warning-code>:<warning-message>" -
4175
4176 if the global volume was set, but there are noteworthy issue(s)
4177 related, providing an appropriate warning code and warning
4178 message
4179
4180 "ERR:<error-code>:<error-message>" -
4181
4182 in case it failed, providing an appropriate error code and
4183 error message
4184
4185 6.7. MIDI Instrument Mapping
4186
4187 The MIDI protocol provides a way to switch between instruments by
4188 sending so called MIDI bank select and MIDI program change messages
4189 which are essentially just numbers. The following commands allow to
4190 actually map arbitrary MIDI bank select / program change numbers with
4191 real instruments.
4192
4193 The sampler allows to manage an arbitrary amount of MIDI instrument
4194 maps which define which instrument to load on which MIDI program
4195 change message.
4196
4197
4198
4199 Schoenebeck Expires April 9, 2008 [Page 75]
4200
4201 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
4202
4203
4204 By default, that is when the sampler is launched, there is no map,
4205 thus the sampler will simply ignore all program change messages. The
4206 front-end has to explicitly create at least one map, add entries to
4207 the map and tell the respective sampler channel(s) which MIDI
4208 instrument map to use, so the sampler knows how to react on a given
4209 program change message on the respective sampler channel, that is by
4210 switching to the respectively defined engine type and loading the
4211 respective instrument. See command "SET CHANNEL MIDI_INSTRUMENT_MAP"
4212 (Section 6.4.24) for how to assign a MIDI instrument map to a sampler
4213 channel.
4214
4215 Also note per MIDI specification a bank select message does not cause
4216 to switch to another instrument. Instead when receiving a bank
4217 select message the bank value will be stored and a subsequent program
4218 change message (which may occur at any time) will finally cause the
4219 sampler to switch to the respective instrument as reflected by the
4220 current MIDI instrument map.
4221
4222 6.7.1. Create a new MIDI instrument map
4223
4224 The front-end can add a new MIDI instrument map by sending the
4225 following command:
4226
4227 ADD MIDI_INSTRUMENT_MAP [<name>]
4228
4229 Where <name> is an optional argument allowing to assign a custom name
4230 to the new map. MIDI instrument Map names do not have to be unique,
4231 but MUST be encapsulated into apostrophes and support escape
4232 sequences as described in chapter "Character Set and Escape Sequences
4233 (Section 7.1)".
4234
4235 Possible Answers:
4236
4237 "OK[<map>]" -
4238
4239 in case a new MIDI instrument map could be added, where <map>
4240 reflects the unique ID of the newly created MIDI instrument map
4241
4242 "ERR:<error-code>:<error-message>" -
4243
4244 when a new map could not be created, which might never occur in
4245 practice
4246
4247 Examples:
4248
4249 C: "ADD MIDI_INSTRUMENT_MAP 'Standard Map'"
4250
4251
4252
4253
4254
4255 Schoenebeck Expires April 9, 2008 [Page 76]
4256
4257 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
4258
4259
4260 S: "OK[0]"
4261
4262 C: "ADD MIDI_INSTRUMENT_MAP 'Standard Drumkit'"
4263
4264 S: "OK[1]"
4265
4266 C: "ADD MIDI_INSTRUMENT_MAP"
4267
4268 S: "OK[5]"
4269
4270 6.7.2. Delete one particular or all MIDI instrument maps
4271
4272 The front-end can delete a particular MIDI instrument map by sending
4273 the following command:
4274
4275 REMOVE MIDI_INSTRUMENT_MAP <map>
4276
4277 Where <map> reflects the unique ID of the map to delete as returned
4278 by the "LIST MIDI_INSTRUMENT_MAPS" (Section 6.7.4) command.
4279
4280 The front-end can delete all MIDI instrument maps by sending the
4281 following command:
4282
4283 REMOVE MIDI_INSTRUMENT_MAP ALL
4284
4285 Possible Answers:
4286
4287 "OK" -
4288
4289 in case the map(s) could be deleted
4290
4291 "ERR:<error-code>:<error-message>" -
4292
4293 when the given map does not exist
4294
4295 Examples:
4296
4297 C: "REMOVE MIDI_INSTRUMENT_MAP 0"
4298
4299 S: "OK"
4300
4301 C: "REMOVE MIDI_INSTRUMENT_MAP ALL"
4302
4303 S: "OK"
4304
4305
4306
4307
4308
4309
4310
4311 Schoenebeck Expires April 9, 2008 [Page 77]
4312
4313 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
4314
4315
4316 6.7.3. Get amount of existing MIDI instrument maps
4317
4318 The front-end can retrieve the current amount of MIDI instrument maps
4319 by sending the following command:
4320
4321 GET MIDI_INSTRUMENT_MAPS
4322
4323 Possible Answers:
4324
4325 The sampler will answer by returning the current number of MIDI
4326 instrument maps.
4327
4328 Example:
4329
4330 C: "GET MIDI_INSTRUMENT_MAPS"
4331
4332 S: "2"
4333
4334 6.7.4. Getting all created MIDI instrument maps
4335
4336 The number of MIDI instrument maps can change on runtime. To get the
4337 current list of MIDI instrument maps, the front-end can send the
4338 following command:
4339
4340 LIST MIDI_INSTRUMENT_MAPS
4341
4342 Possible Answers:
4343
4344 The sampler will answer by returning a comma separated list with
4345 all MIDI instrument maps' numerical IDs.
4346
4347 Example:
4348
4349 C: "LIST MIDI_INSTRUMENT_MAPS"
4350
4351 S: "0,1,5,12"
4352
4353 6.7.5. Getting MIDI instrument map information
4354
4355 The front-end can ask for the current settings of a MIDI instrument
4356 map by sending the following command:
4357
4358 GET MIDI_INSTRUMENT_MAP INFO <map>
4359
4360 Where <map> is the numerical ID of the map the front-end is
4361 interested in as returned by the "LIST MIDI_INSTRUMENT_MAPS"
4362 (Section 6.7.4) command.
4363
4364
4365
4366
4367 Schoenebeck Expires April 9, 2008 [Page 78]
4368
4369 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
4370
4371
4372 Possible Answers:
4373
4374 LinuxSampler will answer by sending a <CRLF> separated list. Each
4375 answer line begins with the settings category name followed by a
4376 colon and then a space character <SP> and finally the info
4377 character string to that setting category. At the moment the
4378 following categories are defined:
4379
4380
4381
4382 NAME -
4383
4384 custom name of the given map, which does not have to be
4385 unique
4386
4387 DEFAULT -
4388
4389 either true or false, defines whether this map is the
4390 default map
4391
4392 The mentioned fields above don't have to be in particular order.
4393
4394 Example:
4395
4396 C: "GET MIDI_INSTRUMENT_MAP INFO 0"
4397
4398 S: "NAME: Standard Map"
4399
4400 "DEFAULT: true"
4401
4402 "."
4403
4404 6.7.6. Renaming a MIDI instrument map
4405
4406 The front-end can alter the custom name of a MIDI instrument map by
4407 sending the following command:
4408
4409 SET MIDI_INSTRUMENT_MAP NAME <map> <name>
4410
4411 Where <map> is the numerical ID of the map and <name> the new custom
4412 name of the map, which does not have to be unique (name MUST be
4413 encapsulated into apostrophes and supports escape sequences as
4414 described in chapter "Character Set and Escape Sequences
4415 (Section 7.1)").
4416
4417 Possible Answers:
4418
4419
4420
4421
4422
4423 Schoenebeck Expires April 9, 2008 [Page 79]
4424
4425 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
4426
4427
4428 "OK" -
4429
4430 on success
4431
4432 "ERR:<error-code>:<error-message>" -
4433
4434 in case the given map does not exist
4435
4436 Example:
4437
4438 C: "SET MIDI_INSTRUMENT_MAP NAME 0 'Foo instruments'"
4439
4440 S: "OK"
4441
4442 6.7.7. Create or replace a MIDI instrument map entry
4443
4444 The front-end can create a new or replace an existing entry in a
4445 sampler's MIDI instrument map by sending the following command:
4446
4447 MAP MIDI_INSTRUMENT [NON_MODAL] <map> <midi_bank> <midi_prog>
4448 <engine_name> <filename> <instrument_index> <volume_value>
4449 [<instr_load_mode>] [<name>]
4450
4451 Where <map> is the numeric ID of the map to alter, <midi_bank> is an
4452 integer value between 0..16383 reflecting the MIDI bank select index,
4453 <midi_prog> an integer value between 0..127 reflecting the MIDI
4454 program change index, <engine_name> a sampler engine name as returned
4455 by the "LIST AVAILABLE_ENGINES" (Section 6.4.8) command (not
4456 encapsulated into apostrophes), <filename> the name of the
4457 instrument's file to be deployed (encapsulated into apostrophes,
4458 supporting escape sequences as described in chapter "Character Set
4459 and Escape Sequences (Section 7.1)"), <instrument_index> the index
4460 (integer value) of the instrument within the given file,
4461 <volume_value> reflects the master volume of the instrument as
4462 optionally dotted number (where a value < 1.0 means attenuation and a
4463 value > 1.0 means amplification). This parameter easily allows to
4464 adjust the volume of all intruments within a custom instrument map
4465 without having to adjust their instrument files. The OPTIONAL
4466 <instr_load_mode> argument defines the life time of the instrument,
4467 that is when the instrument should be loaded, when freed and has
4468 exactly the following possibilities:
4469
4470 "ON_DEMAND" -
4471
4472 The instrument will be loaded when needed, that is when
4473 demanded by at least one sampler channel. It will immediately
4474 be freed from memory when not needed by any sampler channel
4475 anymore.
4476
4477
4478
4479 Schoenebeck Expires April 9, 2008 [Page 80]
4480
4481 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
4482
4483
4484 "ON_DEMAND_HOLD" -
4485
4486 The instrument will be loaded when needed, that is when
4487 demanded by at least one sampler channel. It will be kept in
4488 memory even when not needed by any sampler channel anymore.
4489 Instruments with this mode are only freed when the sampler is
4490 reset or all mapping entries with this mode (and respective
4491 instrument) are explicitly changed to "ON_DEMAND" and no
4492 sampler channel is using the instrument anymore.
4493
4494 "PERSISTENT" -
4495
4496 The instrument will immediately be loaded into memory when this
4497 mapping command is sent and the instrument is kept all the
4498 time. Instruments with this mode are only freed when the
4499 sampler is reset or all mapping entries with this mode (and
4500 respective instrument) are explicitly changed to "ON_DEMAND"
4501 and no sampler channel is using the instrument anymore.
4502
4503 not supplied -
4504
4505 In case there is no <instr_load_mode> argument given, it will
4506 be up to the InstrumentManager to decide which mode to use.
4507 Usually it will use "ON_DEMAND" if an entry for the given
4508 instrument does not exist in the InstrumentManager's list yet,
4509 otherwise if an entry already exists, it will simply stick with
4510 the mode currently reflected by the already existing entry,
4511 that is it will not change the mode.
4512
4513 The <instr_load_mode> argument thus allows to define an appropriate
4514 strategy (low memory consumption vs. fast instrument switching) for
4515 each instrument individually. Note, the following restrictions apply
4516 to this argument: "ON_DEMAND_HOLD" and "PERSISTENT" have to be
4517 supported by the respective sampler engine (which is technically the
4518 case when the engine provides an InstrumentManager for its format).
4519 If this is not the case the argument will automatically fall back to
4520 the default value "ON_DEMAND". Also the load mode of one instrument
4521 may automatically change the laod mode of other instrument(s), i.e.
4522 because the instruments are part of the same file and the engine does
4523 not allow a way to manage load modes for them individually. Due to
4524 this, in case the frontend shows the load modes of entries, the
4525 frontend should retrieve the actual mode by i.e. sending "GET
4526 MIDI_INSTRUMENT INFO" (Section 6.7.11) command(s). Finally the
4527 OPTIONAL <name> argument allows to set a custom name (encapsulated
4528 into apostrophes, supporting escape sequences as described in chapter
4529 "Character Set and Escape Sequences (Section 7.1)") for the mapping
4530 entry, useful for frontends for displaying an appropriate name for
4531 mapped instruments (using "GET MIDI_INSTRUMENT INFO"
4532
4533
4534
4535 Schoenebeck Expires April 9, 2008 [Page 81]
4536
4537 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
4538
4539
4540 (Section 6.7.11)).
4541
4542 By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is
4543 completely established in the sampler. The OPTIONAL "NON_MODAL"
4544 argument however causes the respective "MAP MIDI_INSTRUMENT" command
4545 to return immediately, that is to let the sampler establish the
4546 mapping in the background. So this argument might be especially
4547 useful for mappings with a "PERSISTENT" type, because these have to
4548 load the respective instruments immediately and might thus block for
4549 a very long time. It is recommended however to use the OPTIONAL
4550 "NON_MODAL" argument only if really necessary, because it has the
4551 following drawbacks: as "NON_MODAL" instructions return immediately,
4552 they may not necessarily return an error i.e. when the given
4553 instrument file turns out to be corrupt, beside that subsequent
4554 commands in a LSCP instruction sequence might fail, because mandatory
4555 mappings are not yet completed.
4556
4557 Possible Answers:
4558
4559 "OK" -
4560
4561 usually
4562
4563 "ERR:<error-code>:<error-message>" -
4564
4565 when the given map or engine does not exist or a value is out
4566 of range
4567
4568 Examples:
4569
4570 C: "MAP MIDI_INSTRUMENT 0 3 0 gig '/usr/share/Steinway D.gig' 0
4571 0.8 PERSISTENT"
4572
4573 S: "OK"
4574
4575 C: "MAP MIDI_INSTRUMENT 0 4 50 gig '/home/john/foostrings.gig' 7
4576 1.0"
4577
4578 S: "OK"
4579
4580 C: "MAP MIDI_INSTRUMENT 0 0 0 gig '/usr/share/piano.gig' 0 1.0
4581 'Normal Piano'"
4582
4583 S: "OK"
4584
4585 C: "MAP MIDI_INSTRUMENT 0 1 0 gig '/usr/share/piano.gig' 0 0.25
4586 'Silent Piano'"
4587
4588
4589
4590
4591 Schoenebeck Expires April 9, 2008 [Page 82]
4592
4593 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
4594
4595
4596 S: "OK"
4597
4598 C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/
4599 foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"
4600
4601 S: "OK"
4602
4603 6.7.8. Getting ammount of MIDI instrument map entries
4604
4605 The front-end can query the amount of currently existing entries in a
4606 MIDI instrument map by sending the following command:
4607
4608 GET MIDI_INSTRUMENTS <map>
4609
4610 The front-end can query the amount of currently existing entries in
4611 all MIDI instrument maps by sending the following command:
4612
4613 GET MIDI_INSTRUMENTS ALL
4614
4615 Possible Answers:
4616
4617 The sampler will answer by sending the current number of entries
4618 in the MIDI instrument map(s).
4619
4620 Example:
4621
4622 C: "GET MIDI_INSTRUMENTS 0"
4623
4624 S: "234"
4625
4626 C: "GET MIDI_INSTRUMENTS ALL"
4627
4628 S: "954"
4629
4630 6.7.9. Getting indeces of all entries of a MIDI instrument map
4631
4632 The front-end can query a list of all currently existing entries in a
4633 certain MIDI instrument map by sending the following command:
4634
4635 LIST MIDI_INSTRUMENTS <map>
4636
4637 Where <map> is the numeric ID of the MIDI instrument map.
4638
4639 The front-end can query a list of all currently existing entries of
4640 all MIDI instrument maps by sending the following command:
4641
4642
4643
4644
4645
4646
4647 Schoenebeck Expires April 9, 2008 [Page 83]
4648
4649 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
4650
4651
4652 LIST MIDI_INSTRUMENTS ALL
4653
4654 Possible Answers:
4655
4656 The sampler will answer by sending a comma separated list of map
4657 ID - MIDI bank - MIDI program triples, where each triple is
4658 encapsulated into curly braces. The list is returned in one
4659 single line. Each triple just reflects the key of the respective
4660 map entry, thus subsequent "GET MIDI_INSTRUMENT INFO"
4661 (Section 6.7.11) command(s) are necessary to retrieve detailed
4662 informations about each entry.
4663
4664 Example:
4665
4666 C: "LIST MIDI_INSTRUMENTS 0"
4667
4668 S: "{0,0,0},{0,0,1},{0,0,3},{0,1,4},{1,127,127}"
4669
4670 6.7.10. Remove an entry from the MIDI instrument map
4671
4672 The front-end can delete an entry from a MIDI instrument map by
4673 sending the following command:
4674
4675 UNMAP MIDI_INSTRUMENT <map> <midi_bank> <midi_prog>
4676
4677 Where <map> is the numeric ID of the MIDI instrument map, <midi_bank>
4678 is an integer value between 0..16383 reflecting the MIDI bank value
4679 and <midi_prog> an integer value between 0..127 reflecting the MIDI
4680 program value of the map's entrie's key index triple.
4681
4682 Possible Answers:
4683
4684 "OK" -
4685
4686 usually
4687
4688 "ERR:<error-code>:<error-message>" -
4689
4690 when index out of bounds
4691
4692 Example:
4693
4694 C: "UNMAP MIDI_INSTRUMENT 0 2 127"
4695
4696 S: "OK"
4697
4698
4699
4700
4701
4702
4703 Schoenebeck Expires April 9, 2008 [Page 84]
4704
4705 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
4706
4707
4708 6.7.11. Get current settings of MIDI instrument map entry
4709
4710 The front-end can retrieve the current settings of a certain
4711 instrument map entry by sending the following command:
4712
4713 GET MIDI_INSTRUMENT INFO <map> <midi_bank> <midi_prog>
4714
4715 Where <map> is the numeric ID of the MIDI instrument map, <midi_bank>
4716 is an integer value between 0..16383 reflecting the MIDI bank value,
4717 <midi_bank> and <midi_prog> an integer value between 0..127
4718 reflecting the MIDI program value of the map's entrie's key index
4719 triple.
4720
4721 Possible Answers:
4722
4723 LinuxSampler will answer by sending a <CRLF> separated list. Each
4724 answer line begins with the information category name followed by
4725 a colon and then a space character <SP> and finally the info
4726 character string to that info category. At the moment the
4727 following categories are defined:
4728
4729 "NAME" -
4730
4731 Name for this MIDI instrument map entry (if defined). This
4732 name shall be used by frontends for displaying a name for this
4733 mapped instrument. It can be set and changed with the "MAP
4734 MIDI_INSTRUMENT" (Section 6.7.7) command and does not have to
4735 be unique.
4736
4737 "ENGINE_NAME" -
4738
4739 Name of the engine to be deployed for this instrument.
4740
4741 "INSTRUMENT_FILE" -
4742
4743 File name of the instrument.
4744
4745 "INSTRUMENT_NR" -
4746
4747 Index of the instrument within the file.
4748
4749 "INSTRUMENT_NAME" -
4750
4751 Name of the loaded instrument as reflected by its file. In
4752 contrast to the "NAME" field, the "INSTRUMENT_NAME" field
4753 cannot be changed.
4754
4755
4756
4757
4758
4759 Schoenebeck Expires April 9, 2008 [Page 85]
4760
4761 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
4762
4763
4764 "LOAD_MODE" -
4765
4766 Life time of instrument (see "MAP MIDI_INSTRUMENT"
4767 (Section 6.7.7) for details about this setting).
4768
4769 "VOLUME" -
4770
4771 master volume of the instrument as optionally dotted number
4772 (where a value < 1.0 means attenuation and a value > 1.0 means
4773 amplification)
4774
4775 The mentioned fields above don't have to be in particular order.
4776
4777 Example:
4778
4779 C: "GET MIDI_INSTRUMENT INFO 1 45 120"
4780
4781 S: "NAME: Drums for Foo Song"
4782
4783 "ENGINE_NAME: GigEngine"
4784
4785 "INSTRUMENT_FILE: /usr/share/joesdrumkit.gig"
4786
4787 "INSTRUMENT_NR: 0"
4788
4789 "INSTRUMENT_NAME: Joe's Drumkit"
4790
4791 "LOAD_MODE: PERSISTENT"
4792
4793 "VOLUME: 1.0"
4794
4795 "."
4796
4797 6.7.12. Clear MIDI instrument map
4798
4799 The front-end can clear a whole MIDI instrument map, that is delete
4800 all its entries by sending the following command:
4801
4802 CLEAR MIDI_INSTRUMENTS <map>
4803
4804 Where <map> is the numeric ID of the map to clear.
4805
4806 The front-end can clear all MIDI instrument maps, that is delete all
4807 entries of all maps by sending the following command:
4808
4809 CLEAR MIDI_INSTRUMENTS ALL
4810
4811 The command "CLEAR MIDI_INSTRUMENTS ALL" does not delete the maps,
4812
4813
4814
4815 Schoenebeck Expires April 9, 2008 [Page 86]
4816
4817 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
4818
4819
4820 only their entries, thus the map's settings like custom name will be
4821 preservevd.
4822
4823 Possible Answers:
4824
4825 "OK" -
4826
4827 always
4828
4829 Examples:
4830
4831 C: "CLEAR MIDI_INSTRUMENTS 0"
4832
4833 S: "OK"
4834
4835 C: "CLEAR MIDI_INSTRUMENTS ALL"
4836
4837 S: "OK"
4838
4839 6.8. Managing Instruments Database
4840
4841 The following commands describe how to use and manage the instruments
4842 database.
4843
4844 Notice:
4845
4846 All command arguments representing a path or instrument/directory
4847 name support escape sequences as described in chapter "Character
4848 Set and Escape Sequences (Section 7.1)".
4849
4850 All occurrences of a forward slash in instrument and directory
4851 names are escaped with its hex (\x2f) or octal (\057) escape
4852 sequence.
4853
4854 6.8.1. Creating a new instrument directory
4855
4856 The front-end can add a new instrument directory to the instruments
4857 database by sending the following command:
4858
4859 ADD DB_INSTRUMENT_DIRECTORY <dir>
4860
4861 Where <dir> is the absolute path name of the directory to be created
4862 (encapsulated into apostrophes).
4863
4864 Possible Answers:
4865
4866
4867
4868
4869
4870
4871 Schoenebeck Expires April 9, 2008 [Page 87]
4872
4873 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
4874
4875
4876 "OK" -
4877
4878 on success
4879
4880 "ERR:<error-code>:<error-message>" -
4881
4882 when the directory could not be created, which can happen if
4883 the directory already exists or the name contains not allowed
4884 symbols
4885
4886 Examples:
4887
4888 C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'"
4889
4890 S: "OK"
4891
4892 6.8.2. Deleting an instrument directory
4893
4894 The front-end can delete a particular instrument directory from the
4895 instruments database by sending the following command:
4896
4897 REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] <dir>
4898
4899 Where <dir> is the absolute path name of the directory to delete.
4900 The optional FORCE argument can be used to force the deletion of a
4901 non-empty directory and all its content.
4902
4903 Possible Answers:
4904
4905 "OK" -
4906
4907 if the directory is deleted successfully
4908
4909 "ERR:<error-code>:<error-message>" -
4910
4911 if the given directory does not exist, or if trying to delete a
4912 non-empty directory, without using the FORCE argument.
4913
4914 Examples:
4915
4916 C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'"
4917
4918 S: "OK"
4919
4920
4921
4922
4923
4924
4925
4926
4927 Schoenebeck Expires April 9, 2008 [Page 88]
4928
4929 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
4930
4931
4932 6.8.3. Getting amount of instrument directories
4933
4934 The front-end can retrieve the current amount of directories in a
4935 specific directory by sending the following command:
4936
4937 GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] <dir>
4938
4939 Where <dir> should be replaced by the absolute path name of the
4940 directory. If RECURSIVE is specified, the number of all directories,
4941 including those located in subdirectories of the specified directory,
4942 will be returned.
4943
4944 Possible Answers:
4945
4946 The current number of instrument directories in the specified
4947 directory.
4948
4949 "ERR:<error-code>:<error-message>" -
4950
4951 if the given directory does not exist.
4952
4953 Example:
4954
4955 C: "GET DB_INSTRUMENT_DIRECTORIES '/'"
4956
4957 S: "2"
4958
4959 6.8.4. Listing all directories in specific directory
4960
4961 The front-end can retrieve the current list of directories in
4962 specific directory by sending the following command:
4963
4964 LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] <dir>
4965
4966 Where <dir> should be replaced by the absolute path name of the
4967 directory. If RECURSIVE is specified, the absolute path names of all
4968 directories, including those located in subdirectories of the
4969 specified directory, will be returned.
4970
4971 Possible Answers:
4972
4973 A comma separated list of all instrument directories (encapsulated
4974 into apostrophes) in the specified directory.
4975
4976 "ERR:<error-code>:<error-message>" -
4977
4978 if the given directory does not exist.
4979
4980
4981
4982
4983 Schoenebeck Expires April 9, 2008 [Page 89]
4984
4985 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
4986
4987
4988 Example:
4989
4990 C: "LIST DB_INSTRUMENT_DIRECTORIES '/'"
4991
4992 S: "'Piano Collection','Percussion Collection'"
4993
4994 C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'"
4995
4996 S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano
4997 Collection/Acoustic/New','/Percussion Collection'"
4998
4999 6.8.5. Getting instrument directory information
5000
5001 The front-end can ask for the current settings of an instrument
5002 directory by sending the following command:
5003
5004 GET DB_INSTRUMENT_DIRECTORY INFO <dir>
5005
5006 Where <dir> should be replaced by the absolute path name of the
5007 directory the front-end is interested in.
5008
5009 Possible Answers:
5010
5011 LinuxSampler will answer by sending a <CRLF> separated list. Each
5012 answer line begins with the settings category name followed by a
5013 colon and then a space character <SP> and finally the info
5014 character string to that setting category. At the moment the
5015 following categories are defined:
5016
5017
5018
5019 DESCRIPTION -
5020
5021 A brief description of the directory content. Note that the
5022 character string may contain escape sequences (Section 7.1).
5023
5024 CREATED -
5025
5026 The creation date and time of the directory, represented in
5027 "YYYY-MM-DD HH:MM:SS" format
5028
5029 MODIFIED -
5030
5031 The date and time of the last modification of the directory,
5032 represented in "YYYY-MM-DD HH:MM:SS" format
5033
5034 The mentioned fields above don't have to be in particular order.
5035
5036
5037
5038
5039 Schoenebeck Expires April 9, 2008 [Page 90]
5040
5041 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
5042
5043
5044 Example:
5045
5046 C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'"
5047
5048 S: "DESCRIPTION: Piano collection of instruments in GigaSampler
5049 format."
5050
5051 "CREATED: 2007-02-05 10:23:12"
5052
5053 "MODIFIED: 2007-04-07 12:50:21"
5054
5055 "."
5056
5057 6.8.6. Renaming an instrument directory
5058
5059 The front-end can alter the name of a specific instrument directory
5060 by sending the following command:
5061
5062 SET DB_INSTRUMENT_DIRECTORY NAME <dir> <name>
5063
5064 Where <dir> is the absolute path name of the directory and <name> is
5065 the new name for that directory.
5066
5067 Possible Answers:
5068
5069 "OK" -
5070
5071 on success
5072
5073 "ERR:<error-code>:<error-message>" -
5074
5075 in case the given directory does not exists, or if a directory
5076 with name equal to the new name already exists.
5077
5078 Example:
5079
5080 C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic'
5081 'Acoustic'"
5082
5083 S: "OK"
5084
5085 6.8.7. Moving an instrument directory
5086
5087 The front-end can move a specific instrument directory by sending the
5088 following command:
5089
5090
5091
5092
5093
5094
5095 Schoenebeck Expires April 9, 2008 [Page 91]
5096
5097 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
5098
5099
5100 MOVE DB_INSTRUMENT_DIRECTORY <dir> <dst>
5101
5102 Where <dir> is the absolute path name of the directory to move and
5103 <dst> is the location where the directory will be moved to.
5104
5105 Possible Answers:
5106
5107 "OK" -
5108
5109 on success
5110
5111 "ERR:<error-code>:<error-message>" -
5112
5113 in case a given directory does not exists, or if a directory
5114 with name equal to the name of the specified directory already
5115 exists in the destination directory. Error is also thrown when
5116 trying to move a directory to a subdirectory of itself.
5117
5118 Example:
5119
5120 C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/
5121 Acoustic'"
5122
5123 S: "OK"
5124
5125 6.8.8. Copying instrument directories
5126
5127 The front-end can copy a specific instrument directory by sending the
5128 following command:
5129
5130 COPY DB_INSTRUMENT_DIRECTORY <dir> <dst>
5131
5132 Where <dir> is the absolute path name of the directory to copy and
5133 <dst> is the location where the directory will be copied to.
5134
5135 Possible Answers:
5136
5137 "OK" -
5138
5139 on success
5140
5141 "ERR:<error-code>:<error-message>" -
5142
5143 in case a given directory does not exists, or if a directory
5144 with name equal to the name of the specified directory already
5145 exists in the destination directory. Error is also thrown when
5146 trying to copy a directory to a subdirectory of itself.
5147
5148
5149
5150
5151 Schoenebeck Expires April 9, 2008 [Page 92]
5152
5153 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
5154
5155
5156 Example:
5157
5158 C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic'
5159 '/Acoustic/Pianos'"
5160
5161 S: "OK"
5162
5163 6.8.9. Changing the description of directory
5164
5165 The front-end can alter the description of a specific instrument
5166 directory by sending the following command:
5167
5168 SET DB_INSTRUMENT_DIRECTORY DESCRIPTION <dir> <desc>
5169
5170 Where <dir> is the absolute path name of the directory and <desc> is
5171 the new description for the directory (encapsulated into apostrophes,
5172 supporting escape sequences as described in chapter "Character Set
5173 and Escape Sequences (Section 7.1)").
5174
5175 Possible Answers:
5176
5177 "OK" -
5178
5179 on success
5180
5181 "ERR:<error-code>:<error-message>" -
5182
5183 in case the given directory does not exists.
5184
5185 Example:
5186
5187 C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A
5188 collection of piano instruments in various format.'"
5189
5190 S: "OK"
5191
5192 6.8.10. Finding directories
5193
5194 The front-end can search for directories in specific directory by
5195 sending the following command:
5196
5197 FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] <dir> <criteria-
5198 list>
5199
5200 Where <dir> should be replaced by the absolute path name of the
5201 directory to search in. If NON_RECURSIVE is specified, the
5202 directories located in subdirectories of the specified directory will
5203 not be searched. <criteria-list> is a list of search criterias in
5204
5205
5206
5207 Schoenebeck Expires April 9, 2008 [Page 93]
5208
5209 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
5210
5211
5212 form of "key1=val1 key2=val2 ...". The following criterias are
5213 allowed:
5214
5215 NAME='<search-string>'
5216
5217 Restricts the search to directories, which names satisfy the
5218 supplied search string (encapsulated into apostrophes, supporting
5219 escape sequences as described in chapter "Character Set and Escape
5220 Sequences (Section 7.1)").
5221
5222 CREATED='[<date-after>]..[<date-before>]'
5223
5224 Restricts the search to directories, which creation date satisfies
5225 the specified period, where <date-after> and <date-before> are in
5226 "YYYY-MM-DD HH:MM:SS" format. If <date-after> is omitted the
5227 search is restricted to directories created before <date-before>.
5228 If <date-before> is omitted, the search is restricted to
5229 directories created after <date-after>.
5230
5231 MODIFIED='[<date-after>]..[<date-before>]'
5232
5233 Restricts the search to directories, which date of last
5234 modification satisfies the specified period, where <date-after>
5235 and <date-before> are in "YYYY-MM-DD HH:MM:SS" format. If <date-
5236 after> is omitted the search is restricted to directories, which
5237 are last modified before <date-before>. If <date-before> is
5238 omitted, the search is restricted to directories, which are last
5239 modified after <date-after>.
5240
5241 DESCRIPTION='<search-string>'
5242
5243 Restricts the search to directories with description that
5244 satisfies the supplied search string (encapsulated into
5245 apostrophes, supporting escape sequences as described in chapter
5246 "Character Set and Escape Sequences (Section 7.1)").
5247
5248 Where <search-string> is either a regular expression, or a word list
5249 separated with spaces for OR search and with '+' for AND search.
5250
5251 Possible Answers:
5252
5253 A comma separated list with the absolute path names (encapsulated
5254 into apostrophes) of all directories in the specified directory
5255 that satisfy the supplied search criterias.
5256
5257 "ERR:<error-code>:<error-message>" -
5258
5259
5260
5261
5262
5263 Schoenebeck Expires April 9, 2008 [Page 94]
5264
5265 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
5266
5267
5268 if the given directory does not exist.
5269
5270 Example:
5271
5272 C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'"
5273
5274 S: "'/Piano Collection'"
5275
5276 C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:
5277 30:13'"
5278
5279 S: "'/Piano Collection','/Percussions'"
5280
5281 6.8.11. Adding instruments to the instruments database
5282
5283 The front-end can add one or more instruments to the instruments
5284 database by sending the following command:
5285
5286 ADD DB_INSTRUMENTS [NON_MODAL] [<mode>] <db_dir> <file_path>
5287 [<instr_index>]
5288
5289 Where <db_dir> is the absolute path name of a directory (encapsulated
5290 into apostrophes) in the instruments database in which only the new
5291 instruments (that are not already in the database) will be added,
5292 <file_path> is the absolute path name of a file or directory in the
5293 file system (encapsulated into apostrophes). In case an instrument
5294 file is supplied, only the instruments in the specified file will be
5295 added to the instruments database. If the optional <instr_index>
5296 (the index of the instrument within the given file) is supplied too,
5297 then only the specified instrument will be added. In case a
5298 directory is supplied, the instruments in that directory will be
5299 added. The OPTIONAL <mode> argument is only applied when a directory
5300 is provided as <file_path> and specifies how the scanning will be
5301 done and has exactly the following possibilities:
5302
5303 "RECURSIVE" -
5304
5305 All instruments will be processed, including those in the
5306 subdirectories, and the respective subdirectory tree structure
5307 will be recreated in the instruments database
5308
5309 "NON_RECURSIVE" -
5310
5311 Only the instruments in the specified directory will be added,
5312 the instruments in the subdirectories will not be processed.
5313
5314
5315
5316
5317
5318
5319 Schoenebeck Expires April 9, 2008 [Page 95]
5320
5321 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
5322
5323
5324 "FLAT" -
5325
5326 All instruments will be processed, including those in the
5327 subdirectories, but the respective subdirectory structure will
5328 not be recreated in the instruments database. All instruments
5329 will be added directly in the specified database directory.
5330
5331 The difference between regular and NON_MODAL versions of the command
5332 is that the regular command returns when the scanning is finished
5333 while NON_MODAL version returns immediately and a background process
5334 is launched. The GET DB_INSTRUMENTS_JOB INFO (Section 6.8.21)
5335 command can be used to monitor the scanning progress.
5336
5337 Possible Answers:
5338
5339 "OK" -
5340
5341 on success when NON_MODAL is not supplied
5342
5343 "OK[<job-id>]" -
5344
5345 on success when NON_MODAL is supplied, where <job-id> is a
5346 numerical ID used to obtain status information about the job
5347 progress. See GET DB_INSTRUMENTS_JOB INFO (Section 6.8.21)
5348
5349 "ERR:<error-code>:<error-message>" -
5350
5351 if an invalid path is specified.
5352
5353 Examples:
5354
5355 C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI
5356 Bosendorfer 290.gig' 0"
5357
5358 S: "OK"
5359
5360 6.8.12. Removing an instrument
5361
5362 The front-end can remove a particular instrument from the instruments
5363 database by sending the following command:
5364
5365 REMOVE DB_INSTRUMENT <instr_path>
5366
5367 Where <instr_path> is the absolute path name (in the instruments
5368 database) of the instrument to remove.
5369
5370 Possible Answers:
5371
5372
5373
5374
5375 Schoenebeck Expires April 9, 2008 [Page 96]
5376
5377 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
5378
5379
5380 "OK" -
5381
5382 if the instrument is removed successfully
5383
5384 "ERR:<error-code>:<error-message>" -
5385
5386 if the given path does not exist or is a directory.
5387
5388 Examples:
5389
5390 C: "REMOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'"
5391
5392 S: "OK"
5393
5394 6.8.13. Getting amount of instruments
5395
5396 The front-end can retrieve the current amount of instruments in a
5397 specific directory by sending the following command:
5398
5399 GET DB_INSTRUMENTS [RECURSIVE] <dir>
5400
5401 Where <dir> should be replaced by the absolute path name of the
5402 directory. If RECURSIVE is specified, the number of all instruments,
5403 including those located in subdirectories of the specified directory,
5404 will be returned.
5405
5406 Possible Answers:
5407
5408 The current number of instruments in the specified directory.
5409
5410 "ERR:<error-code>:<error-message>" -
5411
5412 if the given directory does not exist.
5413
5414 Example:
5415
5416 C: "GET DB_INSTRUMENTS '/Piano Collection'"
5417
5418 S: "2"
5419
5420 6.8.14. Listing all instruments in specific directory
5421
5422 The front-end can retrieve the current list of instruments in
5423 specific directory by sending the following command:
5424
5425 LIST DB_INSTRUMENTS [RECURSIVE] <dir>
5426
5427 Where <dir> should be replaced by the absolute path name of the
5428
5429
5430
5431 Schoenebeck Expires April 9, 2008 [Page 97]
5432
5433 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
5434
5435
5436 directory. If RECURSIVE is specified, the absolute path names of all
5437 instruments, including those located in subdirectories of the
5438 specified directory, will be returned.
5439
5440 Possible Answers:
5441
5442 A comma separated list of all instruments (encapsulated into
5443 apostrophes) in the specified directory.
5444
5445 "ERR:<error-code>:<error-message>" -
5446
5447 if the given directory does not exist.
5448
5449 Example:
5450
5451 C: "LIST DB_INSTRUMENTS '/Piano Collection'"
5452
5453 S: "'Bosendorfer 290','Steinway D'"
5454
5455 C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'"
5456
5457 S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/
5458 Steinway D','/Piano Collection/Lite/Free Piano'"
5459
5460 6.8.15. Getting instrument information
5461
5462 The front-end can ask for the current settings of an instrument by
5463 sending the following command:
5464
5465 GET DB_INSTRUMENT INFO <instr_path>
5466
5467 Where <instr_path> should be replaced by the absolute path name of
5468 the instrument the front-end is interested in.
5469
5470 Possible Answers:
5471
5472 LinuxSampler will answer by sending a <CRLF> separated list. Each
5473 answer line begins with the settings category name followed by a
5474 colon and then a space character <SP> and finally the info
5475 character string to that setting category. At the moment the
5476 following categories are defined:
5477
5478
5479
5480 INSTRUMENT_FILE -
5481
5482 File name of the instrument. Note that the character string
5483 may contain escape sequences (Section 7.1).
5484
5485
5486
5487 Schoenebeck Expires April 9, 2008 [Page 98]
5488
5489 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
5490
5491
5492 INSTRUMENT_NR -
5493
5494 Index of the instrument within the file.
5495
5496 FORMAT_FAMILY -
5497
5498 The format family of the instrument.
5499
5500 FORMAT_VERSION -
5501
5502 The format version of the instrument.
5503
5504 SIZE -
5505
5506 The size of the instrument in bytes.
5507
5508 CREATED -
5509
5510 The date and time when the instrument is added in the
5511 instruments database, represented in "YYYY-MM-DD HH:MM:SS"
5512 format
5513
5514 MODIFIED -
5515
5516 The date and time of the last modification of the
5517 instrument's database settings, represented in "YYYY-MM-DD
5518 HH:MM:SS" format
5519
5520 DESCRIPTION -
5521
5522 A brief description of the instrument. Note that the
5523 character string may contain escape sequences (Section 7.1).
5524
5525 IS_DRUM -
5526
5527 either true or false, determines whether the instrument is a
5528 drumkit or a chromatic instrument
5529
5530 PRODUCT -
5531
5532 The product title of the instrument. Note that the
5533 character string may contain escape sequences (Section 7.1).
5534
5535 ARTISTS -
5536
5537 Lists the artist names. Note that the character string may
5538 contain escape sequences (Section 7.1).
5539
5540
5541
5542
5543 Schoenebeck Expires April 9, 2008 [Page 99]
5544
5545 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
5546
5547
5548 KEYWORDS -
5549
5550 Provides a list of keywords that refer to the instrument.
5551 Keywords are separated with semicolon and blank. Note that
5552 the character string may contain escape sequences
5553 (Section 7.1).
5554
5555 The mentioned fields above don't have to be in particular order.
5556
5557 Example:
5558
5559 C: "GET DB_INSTRUMENT INFO '/Piano Collection/Bosendorfer 290'"
5560
5561 S: "INSTRUMENT_FILE: /home/me/gigs/Bosendorfer 290.gig"
5562
5563 "INSTRUMENT_NR: 0"
5564
5565 "FORMAT_FAMILY: GIG"
5566
5567 "FORMAT_VERSION: 2"
5568
5569 "SIZE: 2050871870"
5570
5571 "CREATED: 2007-02-05 10:23:12"
5572
5573 "MODIFIED: 2007-04-07 12:50:21"
5574
5575 "DESCRIPTION: "
5576
5577 "IS_DRUM: false"
5578
5579 "PRODUCT: GRANDIOSO Bosendorfer 290"
5580
5581 "ARTISTS: Post Musical Instruments"
5582
5583 "KEYWORDS: Bosendorfer"
5584
5585 "."
5586
5587 6.8.16. Renaming an instrument
5588
5589 The front-end can alter the name of a specific instrument by sending
5590 the following command:
5591
5592 SET DB_INSTRUMENT NAME <instr> <name>
5593
5594 Where <instr> is the absolute path name of the instrument and <name>
5595 is the new name for that instrument.
5596
5597
5598
5599 Schoenebeck Expires April 9, 2008 [Page 100]
5600
5601 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
5602
5603
5604 Possible Answers:
5605
5606 "OK" -
5607
5608 on success
5609
5610 "ERR:<error-code>:<error-message>" -
5611
5612 in case the given instrument does not exists, or if an
5613 instrument with name equal to the new name already exists.
5614
5615 Example:
5616
5617 C: "SET DB_INSTRUMENT NAME '/Piano Collection/Bosendorfer'
5618 'Bosendorfer 290'"
5619
5620 S: "OK"
5621
5622 6.8.17. Moving an instrument
5623
5624 The front-end can move a specific instrument to another directory by
5625 sending the following command:
5626
5627 MOVE DB_INSTRUMENT <instr> <dst>
5628
5629 Where <instr> is the absolute path name of the instrument to move and
5630 <dst> is the directory where the instrument will be moved to.
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 name of the specified
5642 instrument already exists in the destination directory.
5643
5644 Example:
5645
5646 C: "MOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Piano
5647 Collection/Acoustic'"
5648
5649 S: "OK"
5650
5651
5652
5653
5654
5655 Schoenebeck Expires April 9, 2008 [Page 101]
5656
5657 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
5658
5659
5660 6.8.18. Copying instruments
5661
5662 The front-end can copy a specific instrument to another directory by
5663 sending the following command:
5664
5665 COPY DB_INSTRUMENT <instr> <dst>
5666
5667 Where <instr> is the absolute path name of the instrument to copy and
5668 <dst> is the directory where the instrument will be copied 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: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'
5685 '/Acoustic/Pianos/'"
5686
5687 S: "OK"
5688
5689 6.8.19. Changing the description of instrument
5690
5691 The front-end can alter the description of a specific instrument by
5692 sending the following command:
5693
5694 SET DB_INSTRUMENT DESCRIPTION <instr> <desc>
5695
5696 Where <instr> is the absolute path name of the instrument and <desc>
5697 is the new description for the instrument (encapsulated into
5698 apostrophes, supporting escape sequences as described in chapter
5699 "Character Set and Escape Sequences (Section 7.1)").
5700
5701 Possible Answers:
5702
5703 "OK" -
5704
5705 on success
5706
5707
5708
5709
5710
5711 Schoenebeck Expires April 9, 2008 [Page 102]
5712
5713 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
5714
5715
5716 "ERR:<error-code>:<error-message>" -
5717
5718 in case the given instrument does not exists.
5719
5720 Example:
5721
5722 C: "SET DB_INSTRUMENT DESCRIPTION '/Piano Collection/Acoustic/
5723 Bosendorfer 290' 'No comment :)'"
5724
5725 S: "OK"
5726
5727 6.8.20. Finding instruments
5728
5729 The front-end can search for instruments in specific directory by
5730 sending the following command:
5731
5732 FIND DB_INSTRUMENTS [NON_RECURSIVE] <dir> <criteria-list>
5733
5734 Where <dir> should be replaced by the absolute path name of the
5735 directory to search in. If NON_RECURSIVE is specified, the
5736 directories located in subdirectories of the specified directory will
5737 not be searched. <criteria-list> is a list of search criterias in
5738 form of "key1=val1 key2=val2 ...". The following criterias are
5739 allowed:
5740
5741 NAME='<search-string>'
5742
5743 Restricts the search to instruments, which names satisfy the
5744 supplied search string (encapsulated into apostrophes, supporting
5745 escape sequences as described in chapter "Character Set and Escape
5746 Sequences (Section 7.1)").
5747
5748 SIZE=[<min>]..[<max>]
5749
5750 Restricts the search to instruments, which size is in the
5751 specified range. If <min> is omitted, the search results are
5752 restricted to instruments with size less then or equal to <max>.
5753 If <max> is omitted, the search is restricted to instruments with
5754 size greater then or equal to <min>.
5755
5756 CREATED='[<date-after>]..[<date-before>]'
5757
5758 Restricts the search to instruments, which creation date satisfies
5759 the specified period, where <date-after> and <date-before> are in
5760 "YYYY-MM-DD HH:MM:SS" format. If <date-after> is omitted the
5761 search is restricted to instruments created before <date-before>.
5762 If <date-before> is omitted, the search is restricted to
5763 instruments created after <date-after>.
5764
5765
5766
5767 Schoenebeck Expires April 9, 2008 [Page 103]
5768
5769 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
5770
5771
5772 MODIFIED='[<date-after>]..[<date-before>]'
5773
5774 Restricts the search to instruments, which date of last
5775 modification satisfies the specified period, where <date-after>
5776 and <date-before> are in "YYYY-MM-DD HH:MM:SS" format. If <date-
5777 after> is omitted the search is restricted to instruments, which
5778 are last modified before <date-before>. If <date-before> is
5779 omitted, the search is restricted to instruments, which are last
5780 modified after <date-after>.
5781
5782 DESCRIPTION='<search-string>'
5783
5784 Restricts the search to instruments with description that
5785 satisfies the supplied search string (encapsulated into
5786 apostrophes, supporting escape sequences as described in chapter
5787 "Character Set and Escape Sequences (Section 7.1)").
5788
5789 PRODUCT='<search-string>'
5790
5791 Restricts the search to instruments with product info that
5792 satisfies the supplied search string (encapsulated into
5793 apostrophes, supporting escape sequences as described in chapter
5794 "Character Set and Escape Sequences (Section 7.1)").
5795
5796 ARTISTS='<search-string>'
5797
5798 Restricts the search to instruments with artists info that
5799 satisfies the supplied search string (encapsulated into
5800 apostrophes, supporting escape sequences as described in chapter
5801 "Character Set and Escape Sequences (Section 7.1)").
5802
5803 KEYWORDS='<search-string>'
5804
5805 Restricts the search to instruments with keyword list that
5806 satisfies the supplied search string (encapsulated into
5807 apostrophes, supporting escape sequences as described in chapter
5808 "Character Set and Escape Sequences (Section 7.1)").
5809
5810 IS_DRUM=true | false
5811
5812 Either true or false. Restricts the search to drum kits or
5813 chromatic instruments.
5814
5815 FORMAT_FAMILIES='<format-list>'
5816
5817 Restricts the search to instruments of the supplied format
5818 families, where <format-list> is a comma separated list of format
5819 families.
5820
5821
5822
5823 Schoenebeck Expires April 9, 2008 [Page 104]
5824
5825 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
5826
5827
5828 Where <search-string> is either a regular expression, or a word list
5829 separated with spaces for OR search and with '+' for AND search.
5830
5831 Possible Answers:
5832
5833 A comma separated list with the absolute path names (encapsulated
5834 into apostrophes) of all instruments in the specified directory
5835 that satisfy the supplied search criterias.
5836
5837 "ERR:<error-code>:<error-message>" -
5838
5839 if the given directory does not exist.
5840
5841 Example:
5842
5843 C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+
5844 290'"
5845
5846 S: "'/Piano Collection/Bosendorfer 290'"
5847
5848 C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01
5849 09:30:13..'"
5850
5851 S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/
5852 Steinway D'"
5853
5854 6.8.21. Getting job status information
5855
5856 The front-end can ask for the current status of a particular database
5857 instruments job by sending the following command:
5858
5859 GET DB_INSTRUMENTS_JOB INFO <job-id>
5860
5861 Where <job-id> should be replaced by the numerical ID of the job the
5862 front-end is interested in.
5863
5864 Possible Answers:
5865
5866 LinuxSampler will answer by sending a <CRLF> separated list. Each
5867 answer line begins with the settings category name followed by a
5868 colon and then a space character <SP> and finally the info
5869 character string to that setting category. At the moment the
5870 following categories are defined:
5871
5872
5873
5874 FILES_TOTAL -
5875
5876
5877
5878
5879 Schoenebeck Expires April 9, 2008 [Page 105]
5880
5881 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
5882
5883
5884 The total number of files scheduled for scanning
5885
5886 FILES_SCANNED -
5887
5888 The current number of scanned files
5889
5890 SCANNING -
5891
5892 The absolute path name of the file which is currently being
5893 scanned
5894
5895 STATUS -
5896
5897 An integer value between 0 and 100 indicating the scanning
5898 progress percentage of the file which is currently being
5899 scanned
5900
5901 The mentioned fields above don't have to be in particular order.
5902
5903 Example:
5904
5905 C: "GET DB_INSTRUMENTS_JOB INFO 2"
5906
5907 S: "FILES_TOTAL: 12"
5908
5909 "FILES_SCANNED: 7"
5910
5911 "SCANNING: /home/me/gigs/Bosendorfer 290.gig"
5912
5913 "STATUS: 42"
5914
5915 "."
5916
5917 6.8.22. Formatting the instruments database
5918
5919 The front-end can remove all instruments and directories and re-
5920 create the instruments database structure (e.g., in case of a
5921 database corruption) by sending the following command:
5922
5923 FORMAT INSTRUMENTS_DB
5924
5925 Possible Answers:
5926
5927 "OK" -
5928
5929 on success
5930
5931
5932
5933
5934
5935 Schoenebeck Expires April 9, 2008 [Page 106]
5936
5937 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
5938
5939
5940 "ERR:<error-code>:<error-message>" -
5941
5942 If the formatting of the instruments database failed.
5943
5944 6.9. Editing Instruments
5945
5946 The sampler allows to edit instruments while playing with the sampler
5947 by spawning an external (3rd party) instrument editor application for
5948 a given instrument. The 3rd party instrument editor applications
5949 have to place a respective plugin DLL file into the sampler's plugins
5950 directory. The sampler will automatically try to load all plugin
5951