/[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 1201 - (show annotations) (download)
Thu May 24 14:22:39 2007 UTC (15 years, 8 months ago) by iliev
File MIME type: text/plain
File size: 207930 byte(s)
* added commands for monitoring the instrument scan progress

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