/[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 1251 - (show annotations) (download)
Fri Jun 22 14:24:57 2007 UTC (13 years, 8 months ago) by schoenebeck
File MIME type: text/plain
File size: 211573 byte(s)
- updated LSCP spec draft regarding extended ASCII character
  set and support for escape sequences

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