/[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 1400 - (show annotations) (download)
Thu Oct 11 18:59:34 2007 UTC (16 years, 5 months ago) by schoenebeck
File MIME type: text/plain
File size: 222512 byte(s)
* listed LSCP commands which may return escape sequences
  in their response

1
2
3
4 LinuxSampler Developers C. Schoenebeck
5 Internet-Draft Interessengemeinschaft Software
6 Intended status: Standards Track Engineering e. V.
7 Expires: April 13, 2008 October 11, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 (note that the
2683 character string may contain escape sequences (Section 7.1))
2684
2685
2686
2687 Schoenebeck Expires April 13, 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 13, 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 (note: since
2768 LSCP 1.2 this path may contain escape sequences
2769 (Section 7.1))
2770
2771 INSTRUMENT_NR -
2772
2773 the instrument index number of the loaded instrument
2774
2775 INSTRUMENT_NAME -
2776
2777 the instrument name of the loaded instrument (note: since
2778 LSCP 1.2 this character string may contain escape sequences
2779 (Section 7.1))
2780
2781 INSTRUMENT_STATUS -
2782
2783 integer values 0 to 100 indicating loading progress
2784 percentage for the instrument. Negative value indicates a
2785 loading exception. Value of 100 indicates that the
2786 instrument is fully loaded.
2787
2788 MIDI_INPUT_DEVICE -
2789
2790 numerical ID of the MIDI input device which is currently
2791 connected to this sampler channel to deliver MIDI input
2792 commands, "NONE" if there's no device connected to this
2793 sampler channel
2794
2795
2796
2797
2798
2799 Schoenebeck Expires April 13, 2008 [Page 50]
2800
2801 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
2802
2803
2804 MIDI_INPUT_PORT -
2805
2806 port number of the MIDI input device
2807
2808 MIDI_INPUT_CHANNEL -
2809
2810 the MIDI input channel number this sampler channel should
2811 listen to or "ALL" to listen on all MIDI channels
2812
2813 VOLUME -
2814
2815 optionally dotted number for the channel volume factor
2816 (where a value < 1.0 means attenuation and a value > 1.0
2817 means amplification)
2818
2819 MUTE -
2820
2821 Determines whether the channel is muted, "true" if the
2822 channel is muted, "false" if the channel is not muted, and
2823 "MUTED_BY_SOLO" if the channel is muted because of the
2824 presence of a solo channel and will be unmuted when there
2825 are no solo channels left
2826
2827 SOLO -
2828
2829 Determines whether this is a solo channel, "true" if the
2830 channel is a solo channel; "false" otherwise
2831
2832 MIDI_INSTRUMENT_MAP -
2833
2834 Determines to which MIDI instrument map this sampler channel
2835 is assigned to. Read chapter "SET CHANNEL
2836 MIDI_INSTRUMENT_MAP" (Section 6.4.24) for a list of possible
2837 values.
2838
2839 The mentioned fields above don't have to be in particular order.
2840
2841 Example:
2842
2843 C: "GET CHANNEL INFO 34"
2844
2845 S: "ENGINE_NAME: GigEngine"
2846
2847 "VOLUME: 1.0"
2848
2849 "AUDIO_OUTPUT_DEVICE: 0"
2850
2851
2852
2853
2854
2855 Schoenebeck Expires April 13, 2008 [Page 51]
2856
2857 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
2858
2859
2860 "AUDIO_OUTPUT_CHANNELS: 2"
2861
2862 "AUDIO_OUTPUT_ROUTING: 0,1"
2863
2864 "INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"
2865
2866 "INSTRUMENT_NR: 0"
2867
2868 "INSTRUMENT_NAME: Fazioli Piano"
2869
2870 "INSTRUMENT_STATUS: 100"
2871
2872 "MIDI_INPUT_DEVICE: 0"
2873
2874 "MIDI_INPUT_PORT: 0"
2875
2876 "MIDI_INPUT_CHANNEL: 5"
2877
2878 "VOLUME: 1.0"
2879
2880 "MUTE: false"
2881
2882 "SOLO: false"
2883
2884 "MIDI_INSTRUMENT_MAP: NONE"
2885
2886 "."
2887
2888 6.4.11. Current number of active voices
2889
2890 The front-end can ask for the current number of active voices on a
2891 sampler channel by sending the following command:
2892
2893 GET CHANNEL VOICE_COUNT <sampler-channel>
2894
2895 Where <sampler-channel> is the sampler channel number the front-end
2896 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2897 "LIST CHANNELS" (Section 6.4.4) command.
2898
2899 Possible Answers:
2900
2901 LinuxSampler will answer by returning the number of active voices
2902 on that channel.
2903
2904 Example:
2905
2906
2907
2908
2909
2910
2911 Schoenebeck Expires April 13, 2008 [Page 52]
2912
2913 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
2914
2915
2916
2917
2918 6.4.12. Current number of active disk streams
2919
2920 The front-end can ask for the current number of active disk streams
2921 on a sampler channel by sending the following command:
2922
2923 GET CHANNEL STREAM_COUNT <sampler-channel>
2924
2925 Where <sampler-channel> is the sampler channel number the front-end
2926 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2927 "LIST CHANNELS" (Section 6.4.4) command.
2928
2929 Possible Answers:
2930
2931 LinuxSampler will answer by returning the number of active disk
2932 streams on that channel in case the engine supports disk
2933 streaming, if the engine doesn't support disk streaming it will
2934 return "NA" for not available.
2935
2936 Example:
2937
2938
2939
2940 6.4.13. Current fill state of disk stream buffers
2941
2942 The front-end can ask for the current fill state of all disk streams
2943 on a sampler channel by sending the following command:
2944
2945 GET CHANNEL BUFFER_FILL BYTES <sampler-channel>
2946
2947 to get the fill state in bytes or
2948
2949 GET CHANNEL BUFFER_FILL PERCENTAGE <sampler-channel>
2950
2951 to get the fill state in percent, where <sampler-channel> is the
2952 sampler channel number the front-end is interested in as returned by
2953 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
2954 command.
2955
2956 Possible Answers:
2957
2958 LinuxSampler will either answer by returning a comma separated
2959 string with the fill state of all disk stream buffers on that
2960 channel or an empty line if there are no active disk streams or
2961 "NA" for *not available* in case the engine which is deployed
2962 doesn't support disk streaming. Each entry in the answer list
2963 will begin with the stream's ID in brackets followed by the
2964
2965
2966
2967 Schoenebeck Expires April 13, 2008 [Page 53]
2968
2969 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
2970
2971
2972 numerical representation of the fill size (either in bytes or
2973 percentage). Note: due to efficiency reasons the fill states in
2974 the response are not in particular order, thus the front-end has
2975 to sort them by itself if necessary.
2976
2977 Examples:
2978
2979 C: "GET CHANNEL BUFFER_FILL BYTES 4"
2980
2981 S: "[115]420500,[116]510300,[75]110000,[120]230700"
2982
2983 C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
2984
2985 S: "[115]90%,[116]98%,[75]40%,[120]62%"
2986
2987 C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
2988
2989 S: ""
2990
2991 6.4.14. Setting audio output device
2992
2993 The front-end can set the audio output device on a specific sampler
2994 channel by sending the following command:
2995
2996 SET CHANNEL AUDIO_OUTPUT_DEVICE <sampler-channel>
2997 <audio-device-id>
2998
2999 Where <sampler-channel> is the respective sampler channel number as
3000 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3001 (Section 6.4.4) command and <audio-device-id> is the numerical ID of
3002 the audio output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
3003 (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
3004 command.
3005
3006 Possible Answers:
3007
3008 "OK" -
3009
3010 on success
3011
3012 "WRN:<warning-code>:<warning-message>" -
3013
3014 if audio output device was set, but there are noteworthy
3015 issue(s) related, providing an appropriate warning code and
3016 warning message
3017
3018
3019
3020
3021
3022
3023 Schoenebeck Expires April 13, 2008 [Page 54]
3024
3025 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3026
3027
3028 "ERR:<error-code>:<error-message>" -
3029
3030 in case it failed, providing an appropriate error code and
3031 error message
3032
3033 Examples:
3034
3035
3036
3037 6.4.15. Setting audio output type
3038
3039 DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
3040
3041 The front-end can alter the audio output type on a specific sampler
3042 channel by sending the following command:
3043
3044 SET CHANNEL AUDIO_OUTPUT_TYPE <sampler-channel> <audio-output-
3045 type>
3046
3047 Where <audio-output-type> is currently either "ALSA" or "JACK" and
3048 <sampler-channel> is the respective sampler channel number.
3049
3050 Possible Answers:
3051
3052 "OK" -
3053
3054 on success
3055
3056 "WRN:<warning-code>:<warning-message>" -
3057
3058 if audio output type was set, but there are noteworthy issue(s)
3059 related, providing an appropriate warning code and warning
3060 message
3061
3062 "ERR:<error-code>:<error-message>" -
3063
3064 in case it failed, providing an appropriate error code and
3065 error message
3066
3067 Examples:
3068
3069
3070
3071 6.4.16. Setting audio output channel
3072
3073 The front-end can alter the audio output channel on a specific
3074 sampler channel by sending the following command:
3075
3076
3077
3078
3079 Schoenebeck Expires April 13, 2008 [Page 55]
3080
3081 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3082
3083
3084 SET CHANNEL AUDIO_OUTPUT_CHANNEL <sampler-chan> <audio-out>
3085 <audio-in>
3086
3087 Where <sampler-chan> is the sampler channel number as returned by the
3088 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3089 command, <audio-out> is the numerical ID of the sampler channel's
3090 audio output channel which should be rerouted and <audio-in> is the
3091 numerical ID of the audio channel of the selected audio output device
3092 where <audio-out> should be routed to.
3093
3094 Possible Answers:
3095
3096 "OK" -
3097
3098 on success
3099
3100 "WRN:<warning-code>:<warning-message>" -
3101
3102 if audio output channel was set, but there are noteworthy
3103 issue(s) related, providing an appropriate warning code and
3104 warning message
3105
3106 "ERR:<error-code>:<error-message>" -
3107
3108 in case it failed, providing an appropriate error code and
3109 error message
3110
3111 Examples:
3112
3113
3114
3115 6.4.17. Setting MIDI input device
3116
3117 The front-end can set the MIDI input device on a specific sampler
3118 channel by sending the following command:
3119
3120 SET CHANNEL MIDI_INPUT_DEVICE <sampler-channel> <midi-device-id>
3121
3122 Where <sampler-channel> is the sampler channel number as returned by
3123 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3124 command and <midi-device-id> is the numerical ID of the MIDI input
3125 device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5)
3126 or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command.
3127
3128 Possible Answers:
3129
3130
3131
3132
3133
3134
3135 Schoenebeck Expires April 13, 2008 [Page 56]
3136
3137 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3138
3139
3140 "OK" -
3141
3142 on success
3143
3144 "WRN:<warning-code>:<warning-message>" -
3145
3146 if MIDI input device was set, but there are noteworthy issue(s)
3147 related, providing an appropriate warning code and warning
3148 message
3149
3150 "ERR:<error-code>:<error-message>" -
3151
3152 in case it failed, providing an appropriate error code and
3153 error message
3154
3155 Examples:
3156
3157
3158
3159 6.4.18. Setting MIDI input type
3160
3161 DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
3162
3163 The front-end can alter the MIDI input type on a specific sampler
3164 channel by sending the following command:
3165
3166 SET CHANNEL MIDI_INPUT_TYPE <sampler-channel> <midi-input-type>
3167
3168 Where <midi-input-type> is currently only "ALSA" and <sampler-
3169 channel> is the respective sampler channel number.
3170
3171 Possible Answers:
3172
3173 "OK" -
3174
3175 on success
3176
3177 "WRN:<warning-code>:<warning-message>" -
3178
3179 if MIDI input type was set, but there are noteworthy issue(s)
3180 related, providing an appropriate warning code and warning
3181 message
3182
3183 "ERR:<error-code>:<error-message>" -
3184
3185 in case it failed, providing an appropriate error code and
3186 error message
3187
3188
3189
3190
3191 Schoenebeck Expires April 13, 2008 [Page 57]
3192
3193 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3194
3195
3196 Examples:
3197
3198
3199
3200 6.4.19. Setting MIDI input port
3201
3202 The front-end can alter the MIDI input port on a specific sampler
3203 channel by sending the following command:
3204
3205 SET CHANNEL MIDI_INPUT_PORT <sampler-channel> <midi-input-port>
3206
3207 Where <midi-input-port> is a MIDI input port number of the MIDI input
3208 device connected to the sampler channel given by <sampler-channel>.
3209
3210 Possible Answers:
3211
3212 "OK" -
3213
3214 on success
3215
3216 "WRN:<warning-code>:<warning-message>" -
3217
3218 if MIDI input port was set, but there are noteworthy issue(s)
3219 related, providing an appropriate warning code and warning
3220 message
3221
3222 "ERR:<error-code>:<error-message>" -
3223
3224 in case it failed, providing an appropriate error code and
3225 error message
3226
3227 Examples:
3228
3229
3230
3231 6.4.20. Setting MIDI input channel
3232
3233 The front-end can alter the MIDI channel a sampler channel should
3234 listen to by sending the following command:
3235
3236 SET CHANNEL MIDI_INPUT_CHANNEL <sampler-channel> <midi-input-chan>
3237
3238 Where <midi-input-chan> is the number of the new MIDI input channel
3239 where <sampler-channel> should listen to or "ALL" to listen on all 16
3240 MIDI channels.
3241
3242 Possible Answers:
3243
3244
3245
3246
3247 Schoenebeck Expires April 13, 2008 [Page 58]
3248
3249 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3250
3251
3252 "OK" -
3253
3254 on success
3255
3256 "WRN:<warning-code>:<warning-message>" -
3257
3258 if MIDI input channel was set, but there are noteworthy
3259 issue(s) related, providing an appropriate warning code and
3260 warning message
3261
3262 "ERR:<error-code>:<error-message>" -
3263
3264 in case it failed, providing an appropriate error code and
3265 error message
3266
3267 Examples:
3268
3269
3270
3271 6.4.21. Setting channel volume
3272
3273 The front-end can alter the volume of a sampler channel by sending
3274 the following command:
3275
3276 SET CHANNEL VOLUME <sampler-channel> <volume>
3277
3278 Where <volume> is an optionally dotted positive number (a value
3279 smaller than 1.0 means attenuation, whereas a value greater than 1.0
3280 means amplification) and <sampler-channel> defines the sampler
3281 channel where this volume factor should be set.
3282
3283 Possible Answers:
3284
3285 "OK" -
3286
3287 on success
3288
3289 "WRN:<warning-code>:<warning-message>" -
3290
3291 if channel volume was set, but there are noteworthy issue(s)
3292 related, providing an appropriate warning code and warning
3293 message
3294
3295 "ERR:<error-code>:<error-message>" -
3296
3297 in case it failed, providing an appropriate error code and
3298 error message
3299
3300
3301
3302
3303 Schoenebeck Expires April 13, 2008 [Page 59]
3304
3305 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3306
3307
3308 Examples:
3309
3310
3311
3312 6.4.22. Muting a sampler channel
3313
3314 The front-end can mute/unmute a specific sampler channel by sending
3315 the following command:
3316
3317 SET CHANNEL MUTE <sampler-channel> <mute>
3318
3319 Where <sampler-channel> is the respective sampler channel number as
3320 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3321 (Section 6.4.4) command and <mute> should be replaced either by "1"
3322 to mute the channel or "0" to unmute the channel.
3323
3324 Possible Answers:
3325
3326 "OK" -
3327
3328 on success
3329
3330 "WRN:<warning-code>:<warning-message>" -
3331
3332 if the channel was muted/unmuted, but there are noteworthy
3333 issue(s) related, providing an appropriate warning code and
3334 warning message
3335
3336 "ERR:<error-code>:<error-message>" -
3337
3338 in case it failed, providing an appropriate error code and
3339 error message
3340
3341 Examples:
3342
3343
3344
3345 6.4.23. Soloing a sampler channel
3346
3347 The front-end can solo/unsolo a specific sampler channel by sending
3348 the following command:
3349
3350 SET CHANNEL SOLO <sampler-channel> <solo>
3351
3352 Where <sampler-channel> is the respective sampler channel number as
3353 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3354 (Section 6.4.4) command and <solo> should be replaced either by "1"
3355 to solo the channel or "0" to unsolo the channel.
3356
3357
3358
3359 Schoenebeck Expires April 13, 2008 [Page 60]
3360
3361 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3362
3363
3364 Possible Answers:
3365
3366 "OK" -
3367
3368 on success
3369
3370 "WRN:<warning-code>:<warning-message>" -
3371
3372 if the channel was soloed/unsoloed, but there are noteworthy
3373 issue(s) related, providing an appropriate warning code and
3374 warning message
3375
3376 "ERR:<error-code>:<error-message>" -
3377
3378 in case it failed, providing an appropriate error code and
3379 error message
3380
3381 Examples:
3382
3383
3384
3385 6.4.24. Assigning a MIDI instrument map to a sampler channel
3386
3387 The front-end can assign a MIDI instrument map to a specific sampler
3388 channel by sending the following command:
3389
3390 SET CHANNEL MIDI_INSTRUMENT_MAP <sampler-channel> <map>
3391
3392 Where <sampler-channel> is the respective sampler channel number as
3393 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3394 (Section 6.4.4) command and <map> can have the following
3395 possibilites:
3396
3397 "NONE" -
3398
3399 This is the default setting. In this case the sampler channel
3400 is not assigned any MIDI instrument map and thus will ignore
3401 all MIDI program change messages.
3402
3403 "DEFAULT" -
3404
3405 The sampler channel will always use the default MIDI instrument
3406 map to handle MIDI program change messages.
3407
3408 numeric ID -
3409
3410 You can assign a specific MIDI instrument map by replacing
3411 <map> with the respective numeric ID of the MIDI instrument map
3412
3413
3414
3415 Schoenebeck Expires April 13, 2008 [Page 61]
3416
3417 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3418
3419
3420 as returned by the "LIST MIDI_INSTRUMENT_MAPS" (Section 6.7.4)
3421 command. Once that map will be deleted, the sampler channel
3422 would fall back to "NONE".
3423
3424 Read chapter "MIDI Instrument Mapping" (Section 6.7) for details
3425 regarding MIDI instrument mapping.
3426
3427 Possible Answers:
3428
3429 "OK" -
3430
3431 on success
3432
3433 "ERR:<error-code>:<error-message>" -
3434
3435 in case it failed, providing an appropriate error code and
3436 error message
3437
3438 Examples:
3439
3440
3441
3442 6.4.25. Adding an effect send to a sampler channel
3443
3444 The front-end can create an additional effect send on a specific
3445 sampler channel by sending the following command:
3446
3447 CREATE FX_SEND <sampler-channel> <midi-ctrl> [<name>]
3448
3449 Where <sampler-channel> is the respective sampler channel number as
3450 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3451 (Section 6.4.4) command, that is the sampler channel on which the
3452 effect send should be created on, <midi-ctrl> is a number between
3453 0..127 defining the MIDI controller which can alter the effect send
3454 level and <name> is an optional argument defining a name for the
3455 effect send entity. The name does not have to be unique, but MUST be
3456 encapsulated into apostrophes and supports escape sequences as
3457 described in chapter "Character Set and Escape Sequences
3458 (Section 7.1)".
3459
3460 By default, that is as initial routing, the effect send's audio
3461 channels are automatically routed to the last audio channels of the
3462 sampler channel's audio output device, that way you can i.e. first
3463 increase the amount of audio channels on the audio output device for
3464 having dedicated effect send output channels and when "CREATE
3465 FX_SEND" is called, those channels will automatically be picked. You
3466 can alter the destination channels however with "SET FX_SEND
3467 AUDIO_OUTPUT_CHANNEL" (Section 6.4.31).
3468
3469
3470
3471 Schoenebeck Expires April 13, 2008 [Page 62]
3472
3473 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
3474
3475
3476 Note: Create effect sends on a sampler channel only when needed,
3477 because having effect sends on a sampler channel will decrease
3478 runtime performance, because for implementing channel effect sends,
3479 separate (sampler channel local) audio buffers are needed to render
3480 and mix the voices and route the audio signal afterwards to the
3481 master outputs and effect send outputs (along with their respective
3482 effect send levels). A sampler channel without effect sends however
3483 can mix its voices directly into the audio output devices's audio
3484 buffers and is thus faster.
3485
3486 Possible Answers:
3487
3488 "OK[<fx-send-id>]" -
3489
3490 in case a new effect send could be added to the sampler
3491 channel, where <fx-send-id> reflects the unique ID of the newly
3492 created effect send entity
3493
3494 "ERR:<error-code>:<error-message>" -
3495
3496 when a new effect send could not be added, i.e. due to invalid
3497 parameters
3498
3499 Examples:
3500
3501 C: "CREATE FX_SEND 0 91 'Reverb Send'"
3502
3503 S: "OK[0]"
3504
3505 C: "CREATE FX_SEND 0 93"
3506
3507 S: "OK[1]"
3508
3509 6.4.26. Removing an effect send from a sampler channel
3510
3511 The front-end can remove an existing effect send on a specific
3512 sampler channel by sending the following command:
3513
3514 DESTROY FX_SEND <sampler-channel> <fx-send-id>
3515
3516 Where <sampler-channel> is the respective sampler channel number as
3517 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3518 (Section 6.4.4) command, that is the sampler channel from which the
3519 effect send should be removed from and <fx-send-id> is the respective
3520 effect send number as returned by the "CREATE FX_SEND"
3521 (Section 6.4.25) or "LIST FX_SENDS" (Section 6.4.28) command.
3522
3523 Possible Answers:
3524
3525
3526
3527 Schoenebeck Expires April 13, 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 13, 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 (note that this character
3629 string may contain escape sequences (Section 7.1))
3630
3631 MIDI_CONTROLLER -
3632
3633 a value between 0 and 127 reflecting the MIDI controller
3634 which is able to modify the effect send's send level
3635
3636
3637
3638
3639 Schoenebeck Expires April 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 (note that this character string may contain escape
4386 sequences (Section 7.1))
4387
4388 DEFAULT -
4389
4390 either true or false, defines whether this map is the
4391 default map
4392
4393 The mentioned fields above don't have to be in particular order.
4394
4395 Example:
4396
4397 C: "GET MIDI_INSTRUMENT_MAP INFO 0"
4398
4399 S: "NAME: Standard Map"
4400
4401 "DEFAULT: true"
4402
4403 "."
4404
4405 6.7.6. Renaming a MIDI instrument map
4406
4407 The front-end can alter the custom name of a MIDI instrument map by
4408 sending the following command:
4409
4410 SET MIDI_INSTRUMENT_MAP NAME <map> <name>
4411
4412 Where <map> is the numerical ID of the map and <name> the new custom
4413 name of the map, which does not have to be unique (name MUST be
4414 encapsulated into apostrophes and supports escape sequences as
4415 described in chapter "Character Set and Escape Sequences
4416 (Section 7.1)").
4417
4418 Possible Answers:
4419
4420
4421
4422
4423 Schoenebeck Expires April 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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. (note that this character string may contain escape
4736 sequences (Section 7.1))
4737
4738 "ENGINE_NAME" -
4739
4740 Name of the engine to be deployed for this instrument.
4741
4742 "INSTRUMENT_FILE" -
4743
4744 File name of the instrument (note that this path may contain
4745 escape sequences (Section 7.1)).
4746
4747 "INSTRUMENT_NR" -
4748
4749 Index of the instrument within the file.
4750
4751 "INSTRUMENT_NAME" -
4752
4753 Name of the loaded instrument as reflected by its file. In
4754 contrast to the "NAME" field, the "INSTRUMENT_NAME" field
4755 cannot be changed (note that this character string may contain
4756
4757
4758
4759 Schoenebeck Expires April 13, 2008 [Page 85]
4760
4761 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
4762
4763
4764 escape sequences (Section 7.1)).
4765
4766 "LOAD_MODE" -
4767
4768 Life time of instrument (see "MAP MIDI_INSTRUMENT"
4769 (Section 6.7.7) for details about this setting).
4770
4771 "VOLUME" -
4772
4773 master volume of the instrument as optionally dotted number
4774 (where a value < 1.0 means attenuation and a value > 1.0 means
4775 amplification)
4776
4777 The mentioned fields above don't have to be in particular order.
4778
4779 Example:
4780
4781 C: "GET MIDI_INSTRUMENT INFO 1 45 120"
4782
4783 S: "NAME: Drums for Foo Song"
4784
4785 "ENGINE_NAME: GigEngine"
4786
4787 "INSTRUMENT_FILE: /usr/share/joesdrumkit.gig"
4788
4789 "INSTRUMENT_NR: 0"
4790
4791 "INSTRUMENT_NAME: Joe's Drumkit"
4792
4793 "LOAD_MODE: PERSISTENT"
4794
4795 "VOLUME: 1.0"
4796
4797 "."
4798
4799 6.7.12. Clear MIDI instrument map
4800
4801 The front-end can clear a whole MIDI instrument map, that is delete
4802 all its entries by sending the following command:
4803
4804 CLEAR MIDI_INSTRUMENTS <map>
4805
4806 Where <map> is the numeric ID of the map to clear.
4807
4808 The front-end can clear all MIDI instrument maps, that is delete all
4809 entries of all maps by sending the following command:
4810
4811
4812
4813
4814
4815 Schoenebeck Expires April 13, 2008 [Page 86]
4816
4817 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
4818
4819
4820 CLEAR MIDI_INSTRUMENTS ALL
4821
4822 The command "CLEAR MIDI_INSTRUMENTS ALL" does not delete the maps,
4823 only their entries, thus the map's settings like custom name will be
4824 preservevd.
4825
4826 Possible Answers:
4827
4828 "OK" -
4829
4830 always
4831
4832 Examples:
4833
4834 C: "CLEAR MIDI_INSTRUMENTS 0"
4835
4836 S: "OK"
4837
4838 C: "CLEAR MIDI_INSTRUMENTS ALL"
4839
4840 S: "OK"
4841
4842 6.8. Managing Instruments Database
4843
4844 The following commands describe how to use and manage the instruments
4845 database.
4846
4847 Notice:
4848
4849 All command arguments representing a path or instrument/directory
4850 name support escape sequences as described in chapter "Character
4851 Set and Escape Sequences (Section 7.1)".
4852
4853 All occurrences of a forward slash in instrument and directory
4854 names are escaped with its hex (\x2f) or octal (\057) escape
4855 sequence.
4856
4857 6.8.1. Creating a new instrument directory
4858
4859 The front-end can add a new instrument directory to the instruments
4860 database by sending the following command:
4861
4862 ADD DB_INSTRUMENT_DIRECTORY <dir>
4863
4864 Where <dir> is the absolute path name of the directory to be created
4865 (encapsulated into apostrophes).
4866
4867 Possible Answers:
4868
4869
4870
4871 Schoenebeck Expires April 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 13, 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 DLLs in that directory on startup and only on startup!
5952
5953 At the moment there is only one command for this feature set, but
5954 this will most probably change in future.
5955
5956 6.9.1. Opening an appropriate instrument editor application
5957
5958 The front-end can request to open an appropriate instrument editor
5959 application by sending the following command:
5960
5961 EDIT INSTRUMENT <sampler-channel>
5962
5963 Where <sampler-channel> should be replaced by the number of the
5964 sampler channel as given by the "ADD CHANNEL" (Section 6.4.5) or
5965 "LIST CHANNELS" (Section 6.4.4) command.
5966
5967 The sampler will try to ask all registered instrument editors (or to
5968 be more specific: their sampler plugins) whether they are capable to
5969 handle the instrument on the given sampler channel. The sampler will
5970 simply use the first instrument editor application which replied with
5971 a positive answer and spawn that instrument editor application within
5972 the sampler's process and provide that application access to the
5973 instrument's data structures, so both applications can share and
5974 access the same instruments data at the same time, thus allowing to
5975 immediately hear changes with the sampler made by the instrument
5976 editor.
5977
5978 Note: consequently instrument editors are always spawned locally on
5979 the same machine where the sampler is running on!
5980
5981 Possible Answers:
5982
5983 "OK" -
5984
5985 when an appropriate instrument editor was launched
5986
5987
5988
5989
5990
5991 Schoenebeck Expires April 13, 2008 [Page 107]
5992
5993 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
5994
5995
5996 "WRN:<warning-code>:<warning-message>" -
5997
5998 when an appropriate instrument editor was launched, but there
5999 are noteworthy issues
6000
6001 "ERR:<error-code>:<error-message>" -
6002
6003 when an appropriate instrument editor could not be launched
6004
6005 Examples:
6006
6007 C: "EDIT INSTRUMENT 0"
6008
6009 S: "OK"
6010
6011
6012
6013
6014
6015
6016
6017
6018
6019
6020
6021
6022
6023
6024
6025
6026
6027
6028
6029
6030
6031
6032
6033
6034
6035
6036
6037
6038
6039
6040
6041
6042
6043
6044
6045
6046
6047 Schoenebeck Expires April 13, 2008 [Page 108]
6048
6049 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
6050
6051
6052 7. Command Syntax
6053
6054 The grammar of the control protocol as descibed in Section 6 is
6055 defined below using Backus-Naur Form (BNF as described in [RFC2234])
6056 where applicable.
6057
6058 input =
6059
6060 line LF
6061
6062 / line CR LF
6063
6064 line =
6065
6066 /* epsilon (empty line ignored) */
6067
6068 / comment
6069
6070 / command
6071
6072 / error
6073
6074 comment =
6075
6076 '#'
6077
6078 / comment '#'
6079
6080 / comment SP
6081
6082 / comment number
6083
6084 / comment string
6085
6086 command =
6087
6088 ADD SP add_instruction
6089
6090 / MAP SP map_instruction
6091
6092 / UNMAP SP unmap_instruction
6093
6094 / GET SP get_instruction
6095
6096 / CREATE SP create_instruction
6097
6098 / DESTROY SP destroy_instruction
6099
6100
6101
6102
6103 Schoenebeck Expires April 13, 2008 [Page 109]
6104
6105 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
6106
6107
6108 / LIST SP list_instruction
6109
6110 / LOAD SP load_instruction
6111
6112 / REMOVE SP remove_instruction
6113
6114 / SET SP set_instruction
6115
6116 / SUBSCRIBE SP subscribe_event
6117
6118 / UNSUBSCRIBE SP unsubscribe_event
6119
6120 / RESET SP reset_instruction
6121
6122 / CLEAR SP clear_instruction
6123
6124 / FIND SP find_instruction
6125
6126 / MOVE SP move_instruction
6127
6128 / COPY SP copy_instruction
6129
6130 / EDIT SP edit_instruction
6131
6132 / FORMAT SP format_instruction
6133
6134 / RESET
6135
6136 / QUIT
6137
6138 add_instruction =
6139
6140 CHANNEL
6141
6142 / DB_INSTRUMENT_DIRECTORY SP db_path
6143
6144 / DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename
6145
6146 / DB_INSTRUMENTS SP scan_mode SP db_path SP filename
6147
6148 / DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
6149
6150 / DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP
6151 instrument_index
6152
6153 / DB_INSTRUMENTS SP db_path SP filename
6154
6155
6156
6157
6158
6159 Schoenebeck Expires April 13, 2008 [Page 110]
6160
6161 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
6162
6163
6164 / DB_INSTRUMENTS SP db_path SP filename SP instrument_index
6165
6166 / MIDI_INSTRUMENT_MAP
6167
6168 / MIDI_INSTRUMENT_MAP SP map_name
6169
6170 subscribe_event =
6171
6172 AUDIO_OUTPUT_DEVICE_COUNT
6173
6174 / AUDIO_OUTPUT_DEVICE_INFO
6175
6176 / MIDI_INPUT_DEVICE_COUNT
6177
6178 / MIDI_INPUT_DEVICE_INFO
6179
6180 / CHANNEL_COUNT
6181
6182 / VOICE_COUNT
6183
6184 / STREAM_COUNT
6185
6186 / BUFFER_FILL
6187
6188 / CHANNEL_INFO
6189
6190 / FX_SEND_COUNT
6191
6192 / FX_SEND_INFO
6193
6194 / MIDI_INSTRUMENT_MAP_COUNT
6195
6196 / MIDI_INSTRUMENT_MAP_INFO
6197
6198 / MIDI_INSTRUMENT_COUNT
6199
6200 / MIDI_INSTRUMENT_INFO
6201
6202 / DB_INSTRUMENT_DIRECTORY_COUNT
6203
6204 / DB_INSTRUMENT_DIRECTORY_INFO
6205
6206 / DB_INSTRUMENT_COUNT
6207
6208 / DB_INSTRUMENT_INFO
6209
6210 / DB_INSTRUMENTS_JOB_INFO
6211
6212
6213
6214
6215 Schoenebeck Expires April 13, 2008 [Page 111]
6216
6217 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
6218
6219
6220 / MISCELLANEOUS
6221
6222 / TOTAL_VOICE_COUNT
6223
6224 / GLOBAL_INFO
6225
6226 unsubscribe_event =
6227
6228 AUDIO_OUTPUT_DEVICE_COUNT
6229
6230 / AUDIO_OUTPUT_DEVICE_INFO
6231
6232 / MIDI_INPUT_DEVICE_COUNT
6233
6234 / MIDI_INPUT_DEVICE_INFO
6235
6236 / CHANNEL_COUNT
6237
6238 / VOICE_COUNT
6239
6240 / STREAM_COUNT
6241
6242 / BUFFER_FILL
6243
6244 / CHANNEL_INFO
6245
6246 / FX_SEND_COUNT
6247
6248 / FX_SEND_INFO
6249
6250 / MIDI_INSTRUMENT_MAP_COUNT
6251
6252 / MIDI_INSTRUMENT_MAP_INFO
6253
6254 / MIDI_INSTRUMENT_COUNT
6255
6256 / MIDI_INSTRUMENT_INFO
6257
6258 / DB_INSTRUMENT_DIRECTORY_COUNT
6259
6260 / DB_INSTRUMENT_DIRECTORY_INFO
6261
6262 / DB_INSTRUMENT_COUNT
6263
6264 / DB_INSTRUMENT_INFO
6265
6266 / DB_INSTRUMENTS_JOB_INFO
6267
6268
6269
6270
6271 Schoenebeck Expires April 13, 2008 [Page 112]
6272
6273 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
6274
6275
6276 / MISCELLANEOUS
6277
6278 / TOTAL_VOICE_COUNT
6279
6280 / GLOBAL_INFO
6281
6282 map_instruction =
6283
6284 MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP
6285 engine_name SP filename SP instrument_index SP volume_value
6286
6287 / MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog
6288 SP engine_name SP filename SP instrument_index SP volume_value SP
6289 instr_load_mode
6290
6291 / MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog
6292 SP engine_name SP filename SP instrument_index SP volume_value SP
6293 entry_name
6294
6295 / MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog
6296 SP engine_name SP filename SP instrument_index SP volume_value SP
6297 instr_load_mode SP entry_name
6298
6299 unmap_instruction =
6300
6301 MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog
6302
6303 remove_instruction =
6304
6305 CHANNEL SP sampler_channel
6306
6307 / MIDI_INSTRUMENT_MAP SP midi_map
6308
6309 / MIDI_INSTRUMENT_MAP SP ALL
6310
6311 / DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path
6312
6313 / DB_INSTRUMENT_DIRECTORY SP db_path
6314
6315 / DB_INSTRUMENT SP db_path
6316
6317 get_instruction =
6318
6319 AVAILABLE_ENGINES
6320
6321 / AVAILABLE_MIDI_INPUT_DRIVERS
6322
6323
6324
6325
6326
6327 Schoenebeck Expires April 13, 2008 [Page 113]
6328
6329 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
6330
6331
6332 / MIDI_INPUT_DRIVER SP INFO SP string
6333
6334 / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
6335
6336 / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP
6337 key_val_list
6338
6339 / AVAILABLE_AUDIO_OUTPUT_DRIVERS
6340
6341 / AUDIO_OUTPUT_DRIVER SP INFO SP string
6342
6343 / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
6344
6345 / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP
6346 key_val_list
6347
6348 / AUDIO_OUTPUT_DEVICES
6349
6350 / MIDI_INPUT_DEVICES
6351
6352 / AUDIO_OUTPUT_DEVICE SP INFO SP number
6353
6354 / MIDI_INPUT_DEVICE SP INFO SP number
6355
6356 / MIDI_INPUT_PORT SP INFO SP number SP number
6357
6358 / MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
6359
6360 / AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
6361
6362 / AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP
6363 string
6364
6365 / CHANNELS
6366
6367 / CHANNEL SP INFO SP sampler_channel
6368
6369 / CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
6370
6371 / CHANNEL SP STREAM_COUNT SP sampler_channel
6372
6373 / CHANNEL SP VOICE_COUNT SP sampler_channel
6374
6375 / ENGINE SP INFO SP engine_name
6376
6377 / SERVER SP INFO
6378
6379
6380
6381
6382
6383 Schoenebeck Expires April 13, 2008 [Page 114]
6384
6385 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
6386
6387
6388 / TOTAL_VOICE_COUNT
6389
6390 / TOTAL_VOICE_COUNT_MAX
6391
6392 / MIDI_INSTRUMENTS SP midi_map
6393
6394 / MIDI_INSTRUMENTS SP ALL
6395
6396 / MIDI_INSTRUMENT SP INFO SP midi_map SP midi_bank SP midi_prog
6397
6398 / MIDI_INSTRUMENT_MAPS
6399
6400 / MIDI_INSTRUMENT_MAP SP INFO SP midi_map
6401
6402 / FX_SENDS SP sampler_channel
6403
6404 / FX_SEND SP INFO SP sampler_channel SP fx_send_id
6405
6406 / DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
6407
6408 / DB_INSTRUMENT_DIRECTORIES SP db_path
6409
6410 / DB_INSTRUMENT_DIRECTORY SP INFO SP db_path
6411
6412 / DB_INSTRUMENTS SP RECURSIVE SP db_path
6413
6414 / DB_INSTRUMENTS SP db_path
6415
6416 / DB_INSTRUMENT SP INFO SP db_path
6417
6418 / DB_INSTRUMENTS_JOB SP INFO SP number
6419
6420 / VOLUME
6421
6422 set_instruction =
6423
6424 AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '='
6425 param_val_list
6426
6427 / AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '='
6428 param_val_list
6429
6430 / MIDI_INPUT_DEVICE_PARAMETER SP number SP string '='
6431 param_val_list
6432
6433 / MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE
6434
6435
6436
6437
6438
6439 Schoenebeck Expires April 13, 2008 [Page 115]
6440
6441 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
6442
6443
6444 / MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '='
6445 param_val_list
6446
6447 / CHANNEL SP set_chan_instruction
6448
6449 / MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
6450
6451 / FX_SEND SP NAME SP sampler_channel SP fx_send_id SP fx_send_name
6452
6453 / FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id
6454 SP audio_channel_index SP audio_channel_index
6455
6456 / FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP
6457 midi_ctrl
6458
6459 / FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP
6460 volume_value
6461
6462 / DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped
6463
6464 / DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP
6465 stringval_escaped
6466
6467 / DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped
6468
6469 / DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
6470
6471 / ECHO SP boolean
6472
6473 / VOLUME SP volume_value
6474
6475 create_instruction =
6476
6477 AUDIO_OUTPUT_DEVICE SP string SP key_val_list
6478
6479 / AUDIO_OUTPUT_DEVICE SP string
6480
6481 / MIDI_INPUT_DEVICE SP string SP key_val_list
6482
6483 / MIDI_INPUT_DEVICE SP string
6484
6485 / FX_SEND SP sampler_channel SP midi_ctrl
6486
6487 / FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name
6488
6489 reset_instruction =
6490
6491
6492
6493
6494
6495 Schoenebeck Expires April 13, 2008 [Page 116]
6496
6497 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
6498
6499
6500 CHANNEL SP sampler_channel
6501
6502 clear_instruction =
6503
6504 MIDI_INSTRUMENTS SP midi_map
6505
6506 / MIDI_INSTRUMENTS SP ALL
6507
6508 find_instruction =
6509
6510 DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list
6511
6512 / DB_INSTRUMENTS SP db_path SP query_val_list
6513
6514 / DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP
6515 query_val_list
6516
6517 / DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
6518
6519 move_instruction =
6520
6521 DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
6522
6523 / DB_INSTRUMENT SP db_path SP db_path
6524
6525 copy_instruction =
6526
6527 DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
6528
6529 / DB_INSTRUMENT SP db_path SP db_path
6530
6531 destroy_instruction =
6532
6533 AUDIO_OUTPUT_DEVICE SP number
6534
6535 / MIDI_INPUT_DEVICE SP number
6536
6537 / FX_SEND SP sampler_channel SP fx_send_id
6538
6539 load_instruction =
6540
6541 INSTRUMENT SP load_instr_args
6542
6543 / ENGINE SP load_engine_args
6544
6545 set_chan_instruction =
6546
6547
6548
6549
6550
6551 Schoenebeck Expires April 13, 2008 [Page 117]
6552
6553 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
6554
6555
6556 AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
6557
6558 / AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index
6559 SP audio_channel_index
6560
6561 / AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
6562
6563 / MIDI_INPUT SP sampler_channel SP device_index SP
6564 midi_input_port_index SP midi_input_channel_index
6565
6566 / MIDI_INPUT_DEVICE SP sampler_channel SP device_index
6567
6568 / MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
6569
6570 / MIDI_INPUT_CHANNEL SP sampler_channel SP
6571 midi_input_channel_index
6572
6573 / MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
6574
6575 / VOLUME SP sampler_channel SP volume_value
6576
6577 / MUTE SP sampler_channel SP boolean
6578
6579 / SOLO SP sampler_channel SP boolean
6580
6581 / MIDI_INSTRUMENT_MAP SP sampler_channel SP midi_map
6582
6583 / MIDI_INSTRUMENT_MAP SP sampler_channel SP NONE
6584
6585 / MIDI_INSTRUMENT_MAP SP sampler_channel SP DEFAULT
6586
6587 edit_instruction =
6588
6589 INSTRUMENT SP sampler_channel
6590
6591 format_instruction =
6592
6593 INSTRUMENTS_DB
6594
6595 modal_arg =
6596
6597 /* epsilon (empty argument) */
6598
6599 / NON_MODAL SP
6600
6601 key_val_list =
6602
6603
6604
6605
6606
6607 Schoenebeck Expires April 13, 2008 [Page 118]
6608
6609 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
6610
6611
6612 string '=' param_val_list
6613
6614 / key_val_list SP string '=' param_val_list
6615
6616 buffer_size_type =
6617
6618 BYTES
6619
6620 / PERCENTAGE
6621
6622 list_instruction =
6623
6624 AUDIO_OUTPUT_DEVICES
6625
6626 / MIDI_INPUT_DEVICES
6627
6628 / CHANNELS
6629
6630 / AVAILABLE_ENGINES
6631
6632 / AVAILABLE_MIDI_INPUT_DRIVERS
6633
6634 / AVAILABLE_AUDIO_OUTPUT_DRIVERS
6635
6636 / MIDI_INSTRUMENTS SP midi_map
6637
6638 / MIDI_INSTRUMENTS SP ALL
6639
6640 / MIDI_INSTRUMENT_MAPS
6641
6642 / FX_SENDS SP sampler_channel
6643
6644 / DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
6645
6646 / DB_INSTRUMENT_DIRECTORIES SP db_path
6647
6648 / DB_INSTRUMENTS SP RECURSIVE SP db_path
6649
6650 / DB_INSTRUMENTS SP db_path
6651
6652 load_instr_args =
6653
6654 filename SP instrument_index SP sampler_channel
6655
6656 / NON_MODAL SP filename SP instrument_index SP sampler_channel
6657
6658 load_engine_args =
6659
6660
6661
6662
6663 Schoenebeck Expires April 13, 2008 [Page 119]
6664
6665 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
6666
6667
6668 engine_name SP sampler_channel
6669
6670 instr_load_mode =
6671
6672 ON_DEMAND
6673
6674 / ON_DEMAND_HOLD
6675
6676 / PERSISTENT
6677
6678 device_index =
6679
6680 number
6681
6682 audio_channel_index =
6683
6684 number
6685
6686 audio_output_type_name =
6687
6688 string
6689
6690 midi_input_port_index =
6691
6692 number
6693
6694 midi_input_channel_index =
6695
6696 number
6697
6698 / ALL
6699
6700 midi_input_type_name =
6701
6702 string
6703
6704 midi_map =
6705
6706 number
6707
6708 midi_bank =
6709
6710 number
6711
6712 midi_prog =
6713
6714 number
6715
6716
6717
6718
6719 Schoenebeck Expires April 13, 2008 [Page 120]
6720
6721 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
6722
6723
6724 midi_ctrl =
6725
6726 number
6727
6728 volume_value =
6729
6730 dotnum
6731
6732 / number
6733
6734 sampler_channel =
6735
6736 number
6737
6738 instrument_index =
6739
6740 number
6741
6742 fx_send_id =
6743
6744 number
6745
6746 engine_name =
6747
6748 string
6749
6750 filename =
6751
6752 path
6753
6754 db_path =
6755
6756 path
6757
6758 map_name =
6759
6760 stringval_escaped
6761
6762 entry_name =
6763
6764 stringval_escaped
6765
6766 fx_send_name =
6767
6768 stringval_escaped
6769
6770 param_val_list =
6771
6772
6773
6774
6775 Schoenebeck Expires April 13, 2008 [Page 121]
6776
6777 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
6778
6779
6780 param_val
6781
6782 / param_val_list','param_val
6783
6784 param_val =
6785
6786 string
6787
6788 / stringval
6789
6790 / number
6791
6792 / dotnum
6793
6794 query_val_list =
6795
6796 string '=' query_val
6797
6798 / query_val_list SP string '=' query_val
6799
6800 query_val =
6801
6802 text_escaped
6803
6804 / stringval_escaped
6805
6806 scan_mode =
6807
6808 RECURSIVE
6809
6810 / NON_RECURSIVE
6811
6812 / FLAT
6813
6814 7.1. Character Set and Escape Sequences
6815
6816 Older versions of this protocol up to and including v1.1 only
6817 supported the standard ASCII character set (ASCII code 0 - 127)
6818 [RFC20], all younger versions of this protocol however support the
6819 Extended ASCII character set (ASCII code 0 - 255). The same group of
6820 younger protocols also support escape sequences, but only for
6821 certain, explicitly declared parts of the protocol. The supported
6822 escape sequences are defined as follows:
6823
6824
6825
6826
6827
6828
6829
6830
6831 Schoenebeck Expires April 13, 2008 [Page 122]
6832
6833 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
6834
6835
6836 +------------------------+------------------------------------------+
6837 | ASCII Character | Translated into (Name) |
6838 | Sequence | |
6839 +------------------------+------------------------------------------+
6840 | \n | new line |
6841 | | |
6842 | \r | carriage return |
6843 | | |
6844 | \f | form feed |
6845 | | |
6846 | \t | horizontal tab |
6847 | | |
6848 | \v | vertical tab |
6849 | | |
6850 | \' | apostrophe |
6851 | | |
6852 | \" | quotation mark |
6853 | | |
6854 | \\ | backslash |
6855 | | |
6856 | \OOO | three digit octal ASCII code of the |
6857 | | character |
6858 | | |
6859 | \xHH | two digit hex ASCII code of the |
6860 | | character |
6861 +------------------------+------------------------------------------+
6862
6863 Notice: due to the transition of certain parts of the protocol which
6864 now support escape sequences, a slight backward incompatibility to
6865 protocols version v1.1 and younger has been introduced. The only
6866 difference is that in parts of the protocol where escape characters
6867 are now supported, a backslash characters MUST be escaped as well
6868 (that is as double backslash), whereas in the old versions a single
6869 backslash was sufficient.
6870
6871 The following LSCP commands support escape sequences as part of their
6872 filename / path based arguments and / or may contain a filename /
6873 path with escape sequences in their response:
6874
6875 "LOAD INSTRUMENT" (Section 6.4.1)
6876
6877 "GET CHANNEL INFO" (Section 6.4.10)
6878
6879 "MAP MIDI_INSTRUMENT" (Section 6.7.7)
6880
6881 "GET MIDI_INSTRUMENT INFO" (Section 6.7.11)
6882
6883
6884
6885
6886
6887 Schoenebeck Expires April 13, 2008 [Page 123]
6888
6889 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
6890
6891
6892 "ADD DB_INSTRUMENT_DIRECTORY" (Section 6.8.1)
6893
6894 "ADD DB_INSTRUMENTS" (Section 6.8.11)
6895
6896 "REMOVE DB_INSTRUMENT_DIRECTORY" (Section 6.8.2)
6897
6898 "REMOVE DB_INSTRUMENT" (Section 6.8.12)
6899
6900 "GET DB_INSTRUMENT_DIRECTORIES" (Section 6.8.3)
6901
6902 "LIST DB_INSTRUMENT_DIRECTORIES" (Section 6.8.4)
6903
6904 "GET DB_INSTRUMENT_DIRECTORY INFO" (Section 6.8.5)
6905
6906 "GET DB_INSTRUMENTS" (Section 6.8.13)
6907
6908 "LIST DB_INSTRUMENTS" (Section 6.8.14)
6909
6910 "GET DB_INSTRUMENT INFO" (Section 6.8.15)
6911
6912 "SET DB_INSTRUMENT_DIRECTORY NAME" (Section 6.8.6)
6913
6914 "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION" (Section 6.8.9)
6915
6916 "SET DB_INSTRUMENT NAME" (Section 6.8.16)
6917
6918 "SET DB_INSTRUMENT DESCRIPTION" (Section 6.8.19)
6919
6920 "FIND DB_INSTRUMENTS" (Section 6.8.20)
6921
6922 "FIND DB_INSTRUMENT_DIRECTORIES" (Section 6.8.10)
6923
6924 "MOVE DB_INSTRUMENT" (Section 6.8.17)
6925
6926 "MOVE DB_INSTRUMENT_DIRECTORY" (Section 6.8.7)
6927
6928 "COPY DB_INSTRUMENT" (Section 6.8.18)
6929
6930 "COPY DB_INSTRUMENT_DIRECTORY" (Section 6.8.8)
6931
6932 Note that the forward slash character ('/') has a special meaning in
6933 filename / path based arguments: it acts as separator of the nodes in
6934 the path, thus if a directory- or filename includes a forward slash
6935 (not intended as path node separator), you MUST escape that slash
6936 either with the respective hex escape sequence ("\x2f") or with the
6937 respective octal escape sequence ("\057").
6938
6939 The following LSCP commands even support escape sequences as part of
6940
6941
6942
6943 Schoenebeck Expires April 13, 2008 [Page 124]
6944
6945 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
6946
6947
6948 at least one of their text-based arguments (i.e. entity name,
6949 description) and / or may contain escape sequences in at least one of
6950 their text-based fields in their response:
6951
6952 "GET SERVER INFO" (Section 6.6.4)
6953
6954 "GET ENGINE INFO" (Section 6.4.9)
6955
6956 "GET CHANNEL INFO" (Section 6.4.10)
6957
6958 "CREATE FX_SEND" (Section 6.4.25)
6959
6960 "GET FX_SEND INFO" (Section 6.4.29)
6961
6962 "SET FX_SEND NAME" (Section 6.4.30)
6963
6964 "GET MIDI_INSTRUMENT INFO" (Section 6.7.11)
6965
6966 "GET MIDI_INSTRUMENT_MAP INFO" (Section 6.7.5)
6967
6968 "ADD MIDI_INSTRUMENT_MAP" (Section 6.7.1)
6969
6970 "MAP MIDI_INSTRUMENT" (Section 6.7.7)
6971
6972 "SET MIDI_INSTRUMENT_MAP NAME" (Section 6.7.6)
6973
6974 "SET DB_INSTRUMENT_DIRECTORY NAME" (Section 6.8.6)
6975
6976 "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION" (Section 6.8.9)
6977
6978 "FIND DB_INSTRUMENT_DIRECTORIES" (Section 6.8.10)
6979
6980 "SET DB_INSTRUMENT NAME" (Section 6.8.16)
6981
6982 "SET DB_INSTRUMENT DESCRIPTION" (Section 6.8.19)
6983
6984 "FIND DB_INSTRUMENTS" (Section 6.8.20)
6985
6986 Please note that these lists are manually maintained. If you find a
6987 command that also supports escape sequences we forgot to mention
6988 here, please report it!
6989
6990
6991
6992
6993
6994
6995
6996
6997
6998
6999 Schoenebeck Expires April 13, 2008 [Page 125]
7000
7001 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
7002
7003
7004 8. Events
7005
7006 This chapter will describe all currently defined events supported by
7007 LinuxSampler.
7008
7009 8.1. Number of audio output devices changed
7010
7011 Client may want to be notified when the total number of audio output
7012 devices on the back-end changes by issuing the following command:
7013
7014 SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT
7015
7016 Server will start sending the following notification messages:
7017
7018 "NOTIFY:AUDIO_OUTPUT_DEVICE_COUNT:<devices>"
7019
7020 where <devices> will be replaced by the new number of audio output
7021 devices.
7022
7023 8.2. Audio output device's settings changed
7024
7025 Client may want to be notified when changes were made to audio output
7026 devices on the back-end by issuing the following command:
7027
7028 SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO
7029
7030 Server will start sending the following notification messages:
7031
7032 "NOTIFY:AUDIO_OUTPUT_DEVICE_INFO:<device-id>"
7033
7034 where <device-id> will be replaced by the numerical ID of the audio
7035 output device, which settings has been changed. The front-end will
7036 have to send the respective command to actually get the audio output
7037 device info. Because these messages will be triggered by LSCP
7038 commands issued by other clients rather than real time events
7039 happening on the server, it is believed that an empty notification
7040 message is sufficient here.
7041
7042 8.3. Number of MIDI input devices changed
7043
7044 Client may want to be notified when the total number of MIDI input
7045 devices on the back-end changes by issuing the following command:
7046
7047 SUBSCRIBE MIDI_INPUT_DEVICE_COUNT
7048
7049 Server will start sending the following notification messages:
7050
7051
7052
7053
7054
7055 Schoenebeck Expires April 13, 2008 [Page 126]
7056
7057 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
7058
7059
7060 "NOTIFY:MIDI_INPUT_DEVICE_COUNT:<devices>"
7061
7062 where <devices> will be replaced by the new number of MIDI input
7063 devices.
7064
7065 8.4. MIDI input device's settings changed
7066
7067 Client may want to be notified when changes were made to MIDI input
7068 devices on the back-end by issuing the following command:
7069
7070 SUBSCRIBE MIDI_INPUT_DEVICE_INFO
7071
7072 Server will start sending the following notification messages:
7073
7074 "NOTIFY:MIDI_INPUT_DEVICE_INFO:<device-id>"
7075
7076 where <device-id> will be replaced by the numerical ID of the MIDI
7077 input device, which settings has been changed. The front-end will
7078 have to send the respective command to actually get the MIDI input
7079 device info. Because these messages will be triggered by LSCP
7080 commands issued by other clients rather than real time events
7081 happening on the server, it is believed that an empty notification
7082 message is sufficient here.
7083
7084 8.5. Number of sampler channels changed
7085
7086 Client may want to be notified when the total number of channels on
7087 the back-end changes by issuing the following command:
7088
7089 SUBSCRIBE CHANNEL_COUNT
7090
7091 Server will start sending the following notification messages:
7092
7093 "NOTIFY:CHANNEL_COUNT:<channels>"
7094
7095 where <channels> will be replaced by the new number of sampler
7096 channels.
7097
7098 8.6. Number of active voices changed
7099
7100 Client may want to be notified when the number of voices on the back-
7101 end changes by issuing the following command:
7102
7103 SUBSCRIBE VOICE_COUNT
7104
7105 Server will start sending the following notification messages:
7106
7107
7108
7109
7110
7111 Schoenebeck Expires April 13, 2008 [Page 127]
7112
7113 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
7114
7115
7116 "NOTIFY:VOICE_COUNT:<sampler-channel> <voices>"
7117
7118 where <sampler-channel> will be replaced by the sampler channel the
7119 voice count change occurred and <voices> by the new number of active
7120 voices on that channel.
7121
7122 8.7. Number of active disk streams changed
7123
7124 Client may want to be notified when the number of streams on the
7125 back-end changes by issuing the following command: SUBSCRIBE
7126 STREAM_COUNT
7127
7128 SUBSCRIBE STREAM_COUNT
7129
7130 Server will start sending the following notification messages:
7131
7132 "NOTIFY:STREAM_COUNT:<sampler-channel> <streams>"
7133
7134 where <sampler-channel> will be replaced by the sampler channel the
7135 stream count change occurred and <streams> by the new number of
7136 active disk streams on that channel.
7137
7138 8.8. Disk stream buffer fill state changed
7139
7140 Client may want to be notified when the buffer fill state of a disk
7141 stream on the back-end changes by issuing the following command:
7142
7143 SUBSCRIBE BUFFER_FILL
7144
7145 Server will start sending the following notification messages:
7146
7147 "NOTIFY:BUFFER_FILL:<sampler-channel> <fill-data>"
7148
7149 where <sampler-channel> will be replaced by the sampler channel the
7150 buffer fill state change occurred on and <fill-data> will be replaced
7151 by the buffer fill data for this channel as described in
7152 Section 6.4.13 as if the "GET CHANNEL BUFFER_FILL PERCENTAGE"
7153 (Section 6.4.13) command was issued on this channel.
7154
7155 8.9. Channel information changed
7156
7157 Client may want to be notified when changes were made to sampler
7158 channels on the back-end by issuing the following command:
7159
7160 SUBSCRIBE CHANNEL_INFO
7161
7162 Server will start sending the following notification messages:
7163
7164
7165
7166
7167 Schoenebeck Expires April 13, 2008 [Page 128]
7168
7169 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
7170
7171
7172 "NOTIFY:CHANNEL_INFO:<sampler-channel>"
7173
7174 where <sampler-channel> will be replaced by the sampler channel the
7175 channel info change occurred. The front-end will have to send the
7176 respective command to actually get the channel info. Because these
7177 messages will be triggered by LSCP commands issued by other clients
7178 rather than real time events happening on the server, it is believed
7179 that an empty notification message is sufficient here.
7180
7181 8.10. Number of effect sends changed
7182
7183 Client may want to be notified when the number of effect sends on a
7184 particular sampler channel is changed by issuing the following
7185 command:
7186
7187 SUBSCRIBE FX_SEND_COUNT
7188
7189 Server will start sending the following notification messages:
7190
7191 "NOTIFY:FX_SEND_COUNT:<channel-id> <fx-sends>"
7192
7193 where <channel-id> will be replaced by the numerical ID of the
7194 sampler channel, on which the effect sends number is changed and <fx-
7195 sends> will be replaced by the new number of effect sends on that
7196 channel.
7197
7198 8.11. Effect send information changed
7199
7200 Client may want to be notified when changes were made to effect sends
7201 on a a particular sampler channel by issuing the following command:
7202
7203 SUBSCRIBE FX_SEND_INFO
7204
7205 Server will start sending the following notification messages:
7206
7207 "NOTIFY:FX_SEND_INFO:<channel-id> <fx-send-id>"
7208
7209 where <channel-id> will be replaced by the numerical ID of the
7210 sampler channel, on which an effect send entity is changed and <fx-
7211 send-id> will be replaced by the numerical ID of the changed effect
7212 send.
7213
7214 8.12. Total number of active voices changed
7215
7216 Client may want to be notified when the total number of voices on the
7217 back-end changes by issuing the following command:
7218
7219
7220
7221
7222
7223 Schoenebeck Expires April 13, 2008 [Page 129]
7224
7225 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
7226
7227
7228 SUBSCRIBE TOTAL_VOICE_COUNT
7229
7230 Server will start sending the following notification messages:
7231
7232 "NOTIFY:TOTAL_VOICE_COUNT:<voices>"
7233
7234 where <voices> will be replaced by the new number of all currently
7235 active voices.
7236
7237 8.13. Number of MIDI instrument maps changed
7238
7239 Client may want to be notified when the number of MIDI instrument
7240 maps on the back-end changes by issuing the following command:
7241
7242 SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT
7243
7244 Server will start sending the following notification messages:
7245
7246 "NOTIFY:MIDI_INSTRUMENT_MAP_COUNT:<maps>"
7247
7248 where <maps> will be replaced by the new number of MIDI instrument
7249 maps.
7250
7251 8.14. MIDI instrument map information changed
7252
7253 Client may want to be notified when changes were made to MIDI
7254 instrument maps on the back-end by issuing the following command:
7255
7256 SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO
7257
7258 Server will start sending the following notification messages:
7259
7260 "NOTIFY:MIDI_INSTRUMENT_MAP_INFO:<map-id>"
7261
7262 where <map-id> will be replaced by the numerical ID of the MIDI
7263 instrument map, for which information changes occurred. The front-
7264 end will have to send the respective command to actually get the MIDI
7265 instrument map info. Because these messages will be triggered by
7266 LSCP commands issued by other clients rather than real time events
7267 happening on the server, it is believed that an empty notification
7268 message is sufficient here.
7269
7270 8.15. Number of MIDI instruments changed
7271
7272 Client may want to be notified when the number of MIDI instrument
7273 maps on the back-end changes by issuing the following command:
7274
7275
7276
7277
7278
7279 Schoenebeck Expires April 13, 2008 [Page 130]
7280
7281 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
7282
7283
7284 SUBSCRIBE MIDI_INSTRUMENT_COUNT
7285
7286 Server will start sending the following notification messages:
7287
7288 "NOTIFY:MIDI_INSTRUMENT_COUNT:<map-id> <instruments>"
7289
7290 where <map-id> is the numerical ID of the MIDI instrument map, in
7291 which the nuber of instruments has changed and <instruments> will be
7292 replaced by the new number of MIDI instruments in the specified map.
7293
7294 8.16. MIDI instrument information changed
7295
7296 Client may want to be notified when changes were made to MIDI
7297 instruments on the back-end by issuing the following command:
7298
7299 SUBSCRIBE MIDI_INSTRUMENT_INFO
7300
7301 Server will start sending the following notification messages:
7302
7303 "NOTIFY:MIDI_INSTRUMENT_INFO:<map-id> <bank> <program>"
7304
7305 where <map-id> will be replaced by the numerical ID of the MIDI
7306 instrument map, in which a MIDI instrument is changed. <bank> and
7307 <program> specifies the location of the changed MIDI instrument in
7308 the map. The front-end will have to send the respective command to
7309 actually get the MIDI instrument info. Because these messages will
7310 be triggered by LSCP commands issued by other clients rather than
7311 real time events happening on the server, it is believed that an
7312 empty notification message is sufficient here.
7313
7314 8.17. Global settings changed
7315
7316 Client may want to be notified when changes to the global settings of
7317 the sampler were made by issuing the following command:
7318
7319 SUBSCRIBE GLOBAL_INFO
7320
7321 Server will start sending the following types of notification
7322 messages:
7323
7324 "NOTIFY:GLOBAL_INFO:VOLUME <volume>" - Notifies that the golbal
7325 volume of the sampler is changed, where <volume> will be replaced
7326 by the optional dotted floating point value, reflecting the new
7327 global volume parameter.
7328
7329
7330
7331
7332
7333
7334
7335 Schoenebeck Expires April 13, 2008 [Page 131]
7336
7337 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
7338
7339
7340 8.18. Number of database instrument directories changed
7341
7342 Client may want to be notified when the number of instrument
7343 directories in a particular directory in the instruments database is
7344 changed by issuing the following command:
7345
7346 SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT
7347
7348 Server will start sending the following notification messages:
7349
7350 "NOTIFY:DB_INSTRUMENT_DIRECTORY_COUNT:<dir-path>"
7351
7352 where <dir-path> will be replaced by the absolute path name of the
7353 directory in the instruments database, in which the number of
7354 directories is changed.
7355
7356 Note that when a non-empty directory is removed, this event is not
7357 sent for the subdirectories in that directory.
7358
7359 8.19. Database instrument directory information changed
7360
7361 Client may want to be notified when changes were made to directories
7362 in the instruments database by issuing the following command:
7363
7364 SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO
7365
7366 Server will start sending the following notification messages:
7367
7368 "NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:<dir-path>"
7369
7370 where <dir-path> will be replaced by the absolute path name of the
7371 directory, for which information changes occurred. The front-end
7372 will have to send the respective command to actually get the updated
7373 directory info. Because these messages will be triggered by LSCP
7374 commands issued by other clients rather than real time events
7375 happening on the server, it is believed that an empty notification
7376 message is sufficient here.
7377
7378 "NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:NAME <old-dir-path> <new-
7379 name>"
7380
7381 where <old-dir-path> is the old absolute path name of the directory
7382 (encapsulated into apostrophes), which name is changes and <new-name>
7383 is the new name of the directory, encapsulated into apostrophes.
7384
7385
7386
7387
7388
7389
7390
7391 Schoenebeck Expires April 13, 2008 [Page 132]
7392
7393 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
7394
7395
7396 8.20. Number of database instruments changed
7397
7398 Client may want to be notified when the number of instruments in a
7399 particular directory in the instruments database is changed by
7400 issuing the following command:
7401
7402 SUBSCRIBE DB_INSTRUMENT_COUNT
7403
7404 Server will start sending the following notification messages:
7405
7406 "NOTIFY:DB_INSTRUMENT_COUNT:<dir-path>"
7407
7408 where <dir-path> will be replaced by the absolute path name of the
7409 directory in the instruments database, in which the number of
7410 instruments is changed.
7411
7412 Note that when a non-empty directory is removed, this event is not
7413 sent for the instruments in that directory.
7414
7415 8.21. Database instrument information changed
7416
7417 Client may want to be notified when changes were made to instruments
7418 in the instruments database by issuing the following command:
7419
7420 SUBSCRIBE DB_INSTRUMENT_INFO
7421
7422 Server will start sending the following notification messages:
7423
7424 "NOTIFY:DB_INSTRUMENT_INFO:<instr-path>"
7425
7426 where <instr-path> will be replaced by the absolute path name of the
7427 instrument, which settings are changed. The front-end will have to
7428 send the respective command to actually get the updated directory
7429 info. Because these messages will be triggered by LSCP commands
7430 issued by other clients rather than real time events happening on the
7431 server, it is believed that an empty notification message is
7432 sufficient here.
7433
7434 "NOTIFY:DB_INSTRUMENT_INFO:NAME <old-instr-path> <new-name>"
7435
7436 where <old-instr-path> is the old absolute path name of the
7437 instrument (encapsulated into apostrophes), which name is changes and
7438 <new-name> is the new name of the instrument, encapsulated into
7439 apostrophes.
7440
7441
7442
7443
7444
7445
7446
7447 Schoenebeck Expires April 13, 2008 [Page 133]
7448
7449 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
7450
7451
7452 8.22. Database job status information changed
7453
7454 Client may want to be notified when the status of particular database
7455 instruments job is changed by issuing the following command:
7456
7457 SUBSCRIBE DB_INSTRUMENTS_JOB_INFO
7458
7459 Server will start sending the following notification messages:
7460
7461 "NOTIFY:DB_INSTRUMENTS_JOB_INFO:<job-id>"
7462
7463 where <job-id> will be replaced by the numerical ID of the job, which
7464 status is changed. The front-end will have to send the respective
7465 command to actually get the status info. Because these messages will
7466 be triggered by LSCP commands issued by other clients rather than
7467 real time events happening on the server, it is believed that an
7468 empty notification message is sufficient here.
7469
7470 8.23. Miscellaneous and debugging events
7471
7472 Client may want to be notified of miscellaneous and debugging events
7473 occurring at the server by issuing the following command:
7474
7475 SUBSCRIBE MISCELLANEOUS
7476
7477 Server will start sending the following notification messages:
7478
7479 "NOTIFY:MISCELLANEOUS:<string>"
7480
7481 where <string> will be replaced by whatever data server wants to send
7482 to the client. Client MAY display this data to the user AS IS to
7483 facilitate debugging.
7484
7485
7486
7487
7488
7489
7490
7491
7492
7493
7494
7495
7496
7497
7498
7499
7500
7501
7502
7503 Schoenebeck Expires April 13, 2008 [Page 134]
7504
7505 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
7506
7507
7508 9. Security Considerations
7509
7510 As there is so far no method of authentication and authorization
7511 defined and so not required for a client applications to succeed to
7512 connect, running LinuxSampler might be a security risk for the host
7513 system the LinuxSampler instance is running on.
7514
7515
7516
7517
7518
7519
7520
7521
7522
7523
7524
7525
7526
7527
7528
7529
7530
7531
7532
7533
7534
7535
7536
7537
7538
7539
7540
7541
7542
7543
7544
7545
7546
7547
7548
7549
7550
7551
7552
7553
7554
7555
7556
7557
7558
7559 Schoenebeck Expires April 13, 2008 [Page 135]
7560
7561 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
7562
7563
7564 10. Acknowledgments
7565
7566 This document has benefited greatly from the comments of the
7567 following people, discussed on the LinuxSampler developer's mailing
7568 list:
7569
7570 Rui Nuno Capela
7571
7572 Vladimir Senkov
7573
7574 Mark Knecht
7575
7576 Grigor Iliev
7577
7578
7579
7580
7581
7582
7583
7584
7585
7586
7587
7588
7589
7590
7591
7592
7593
7594
7595
7596
7597
7598
7599
7600
7601
7602
7603
7604
7605
7606
7607
7608
7609
7610
7611
7612
7613
7614
7615 Schoenebeck Expires April 13, 2008 [Page 136]
7616
7617 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
7618
7619
7620 11. References
7621
7622 [RFC20] UCLA, "ASCII format for Network Interchange", RFC 20,
7623 1969.
7624
7625 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
7626 Requirement Levels", RFC 2119, 1997.
7627
7628 [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
7629 Specifications", RFC 2234, 1997.
7630
7631 [RFC793] Defense Advanced Research Projects Agency, "TRANSMISSION
7632 CONTROL PROTOCOL", RFC 793, 1981.
7633
7634
7635
7636
7637
7638
7639
7640
7641
7642
7643
7644
7645
7646
7647
7648
7649
7650
7651
7652
7653
7654
7655
7656
7657
7658
7659
7660
7661
7662
7663
7664
7665
7666
7667
7668
7669
7670
7671 Schoenebeck Expires April 13, 2008 [Page 137]
7672
7673 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
7674
7675
7676 Author's Address
7677
7678 C. Schoenebeck
7679 Interessengemeinschaft Software Engineering e. V.
7680 Max-Planck-Str. 39
7681 74081 Heilbronn
7682 Germany
7683
7684 Email: schoenebeck at software minus engineering dot org
7685
7686
7687
7688
7689
7690
7691
7692
7693
7694
7695
7696
7697
7698
7699
7700
7701
7702
7703
7704
7705
7706
7707
7708
7709
7710
7711
7712
7713
7714
7715
7716
7717
7718
7719
7720
7721
7722
7723
7724
7725
7726
7727 Schoenebeck Expires April 13, 2008 [Page 138]
7728
7729 Internet-Draft LinuxSampler Control Protocol (draft) October 2007
7730
7731
7732 Full Copyright Statement
7733
7734 Copyright (C) The IETF Trust (2007).
7735
7736 This document is subject to the rights, licenses and restrictions
7737 contained in BCP 78, and except as set forth therein, the authors
7738 retain all their rights.
7739
7740 This document and the information contained herein are provided on an
7741 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
7742 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
7743 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
7744 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
7745 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
7746 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
7747
7748
7749 Intellectual Property
7750
7751 The IETF takes no position regarding the validity or scope of any
7752 Intellectual Property Rights or other rights that might be claimed to
7753 pertain to the implementation or use of the technology described in
7754 this document or the extent to which any license under such rights
7755 might or might not be available; nor does it represent that it has
7756 made any independent effort to identify any such rights. Information
7757 on the procedures with respect to rights in RFC documents can be
7758 found in BCP 78 and BCP 79.
7759
7760 Copies of IPR disclosures made to the IETF Secretariat and any
7761 assurances of licenses to be made available, or the result of an
7762 attempt made to obtain a general license or permission for the use of
7763 such proprietary rights by implementers or users of this
7764 specification can be obtained from the IETF on-line IPR repository at
7765 http://www.ietf.org/ipr.
7766
7767 The IETF invites any interested party to bring to its attention any
7768 copyrights, patents or patent applications, or other proprietary
7769 rights that may cover technology that may be required to implement
7770 this standard. Please address the information to the IETF at
7771 ietf-ipr@ietf.org.
7772
7773
7774 Acknowledgment
7775
7776 Funding for the RFC Editor function is provided by the IETF
7777 Administrative Support Activity (IASA).
7778
7779
7780
7781
7782
7783 Schoenebeck Expires April 13, 2008 [Page 139]
7784
7785

  ViewVC Help
Powered by ViewVC