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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 945 - (hide annotations) (download)
Sun Nov 26 16:39:49 2006 UTC (17 years, 4 months ago) by schoenebeck
File MIME type: text/plain
File size: 135374 byte(s)
- new LSCP draft (v1.2), added command set for
  MIDI instrument mapping

1 senoner 542
2    
3 schoenebeck 708
4 senoner 542 LinuxSampler Developers C. Schoenebeck
5     Internet-Draft Interessengemeinschaft Software
6 schoenebeck 945 Expires: May 30, 2007 Engineering e. V.
7     November 26, 2006
8 senoner 542
9    
10     LinuxSampler Control Protocol
11 schoenebeck 945 LSCP 1.2
12 senoner 542
13     Status of this Memo
14    
15     This document is an Internet-Draft and is in full conformance with
16 schoenebeck 708 all provisions of Section 10 of RFC 2026.
17 senoner 542
18     Internet-Drafts are working documents of the Internet Engineering
19     Task Force (IETF), its areas, and its working groups. Note that
20 schoenebeck 708 other groups may also distribute working documents as Internet-
21     Drafts.
22 senoner 542
23     Internet-Drafts are draft documents valid for a maximum of six months
24     and may be updated, replaced, or obsoleted by other documents at any
25     time. It is inappropriate to use Internet-Drafts as reference
26     material or to cite them other than as "work in progress."
27    
28     The list of current Internet-Drafts can be accessed at
29     http://www.ietf.org/ietf/1id-abstracts.txt.
30    
31     The list of Internet-Draft Shadow Directories can be accessed at
32     http://www.ietf.org/shadow.html.
33    
34 schoenebeck 945 This Internet-Draft will expire on May 30, 2007.
35 senoner 542
36     Copyright Notice
37    
38 schoenebeck 940 Copyright (C) The Internet Society (2006). All Rights Reserved.
39 senoner 542
40     Abstract
41    
42     The LinuxSampler Control Protocol (LSCP) is an application-level
43     protocol primarily intended for local and remote controlling the
44 schoenebeck 708 LinuxSampler backend application, which is a sophisticated server-
45     like console application essentially playing back audio samples and
46     manipulating the samples in real time to certain extent.
47 senoner 542
48    
49    
50    
51    
52    
53    
54    
55 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 1]
56 schoenebeck 940
57     Internet-Draft LinuxSampler Control Protocol November 2006
58 senoner 542
59    
60     Table of Contents
61    
62 schoenebeck 945 1. Requirements notation . . . . . . . . . . . . . . . . . . . . 5
63     2. Versioning of this specification . . . . . . . . . . . . . . . 6
64     3. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 7
65     4. Focus of this protocol . . . . . . . . . . . . . . . . . . . . 8
66     5. Communication Overview . . . . . . . . . . . . . . . . . . . . 9
67     5.1. Request/response communication method . . . . . . . . . . 9
68     5.1.1. Result format . . . . . . . . . . . . . . . . . . . . 10
69     5.2. Subscribe/notify communication method . . . . . . . . . . 12
70     6. Description for control commands . . . . . . . . . . . . . . . 14
71     6.1. Ignored lines and comments . . . . . . . . . . . . . . . . 14
72     6.2. Configuring audio drivers . . . . . . . . . . . . . . . . 14
73     6.2.1. Getting amount of available audio output drivers . . . 14
74     6.2.2. Getting all available audio output drivers . . . . . . 15
75 schoenebeck 940 6.2.3. Getting information about a specific audio output
76 schoenebeck 945 driver . . . . . . . . . . . . . . . . . . . . . . . . 15
77 schoenebeck 940 6.2.4. Getting information about specific audio output
78 schoenebeck 945 driver parameter . . . . . . . . . . . . . . . . . . . 16
79     6.2.5. Creating an audio output device . . . . . . . . . . . 20
80     6.2.6. Destroying an audio output device . . . . . . . . . . 21
81     6.2.7. Getting all created audio output device count . . . . 22
82     6.2.8. Getting all created audio output device list . . . . . 22
83     6.2.9. Getting current settings of an audio output device . . 22
84     6.2.10. Changing settings of audio output devices . . . . . . 24
85     6.2.11. Getting information about an audio channel . . . . . . 24
86 schoenebeck 940 6.2.12. Getting information about specific audio channel
87 schoenebeck 945 parameter . . . . . . . . . . . . . . . . . . . . . . 26
88     6.2.13. Changing settings of audio output channels . . . . . . 28
89     6.3. Configuring MIDI input drivers . . . . . . . . . . . . . . 29
90     6.3.1. Getting amount of available MIDI input drivers . . . . 30
91     6.3.2. Getting all available MIDI input drivers . . . . . . . 30
92 schoenebeck 940 6.3.3. Getting information about a specific MIDI input
93 schoenebeck 945 driver . . . . . . . . . . . . . . . . . . . . . . . . 30
94 schoenebeck 940 6.3.4. Getting information about specific MIDI input
95 schoenebeck 945 driver parameter . . . . . . . . . . . . . . . . . . . 31
96     6.3.5. Creating a MIDI input device . . . . . . . . . . . . . 34
97     6.3.6. Destroying a MIDI input device . . . . . . . . . . . . 35
98     6.3.7. Getting all created MIDI input device count . . . . . 36
99     6.3.8. Getting all created MIDI input device list . . . . . . 36
100     6.3.9. Getting current settings of a MIDI input device . . . 36
101     6.3.10. Changing settings of MIDI input devices . . . . . . . 38
102     6.3.11. Getting information about a MIDI port . . . . . . . . 38
103 schoenebeck 940 6.3.12. Getting information about specific MIDI port
104 schoenebeck 945 parameter . . . . . . . . . . . . . . . . . . . . . . 39
105     6.3.13. Changing settings of MIDI input ports . . . . . . . . 41
106     6.4. Configuring sampler channels . . . . . . . . . . . . . . . 42
107     6.4.1. Loading an instrument . . . . . . . . . . . . . . . . 42
108 senoner 542
109    
110    
111 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 2]
112 schoenebeck 940
113     Internet-Draft LinuxSampler Control Protocol November 2006
114 senoner 542
115    
116 schoenebeck 945 6.4.2. Loading a sampler engine . . . . . . . . . . . . . . . 43
117     6.4.3. Getting all created sampler channel count . . . . . . 44
118     6.4.4. Getting all created sampler channel list . . . . . . . 44
119     6.4.5. Adding a new sampler channel . . . . . . . . . . . . . 44
120     6.4.6. Removing a sampler channel . . . . . . . . . . . . . . 45
121     6.4.7. Getting amount of available engines . . . . . . . . . 46
122     6.4.8. Getting all available engines . . . . . . . . . . . . 46
123     6.4.9. Getting information about an engine . . . . . . . . . 47
124     6.4.10. Getting sampler channel information . . . . . . . . . 48
125     6.4.11. Current number of active voices . . . . . . . . . . . 51
126     6.4.12. Current number of active disk streams . . . . . . . . 51
127     6.4.13. Current fill state of disk stream buffers . . . . . . 51
128     6.4.14. Setting audio output device . . . . . . . . . . . . . 52
129     6.4.15. Setting audio output type . . . . . . . . . . . . . . 53
130     6.4.16. Setting audio output channel . . . . . . . . . . . . . 54
131     6.4.17. Setting MIDI input device . . . . . . . . . . . . . . 55
132     6.4.18. Setting MIDI input type . . . . . . . . . . . . . . . 55
133     6.4.19. Setting MIDI input port . . . . . . . . . . . . . . . 56
134     6.4.20. Setting MIDI input channel . . . . . . . . . . . . . . 57
135     6.4.21. Setting channel volume . . . . . . . . . . . . . . . . 57
136     6.4.22. Muting a sampler channel . . . . . . . . . . . . . . . 58
137     6.4.23. Soloing a sampler channel . . . . . . . . . . . . . . 59
138     6.4.24. Resetting a sampler channel . . . . . . . . . . . . . 59
139     6.5. Controlling connection . . . . . . . . . . . . . . . . . . 60
140     6.5.1. Register front-end for receiving event messages . . . 60
141 schoenebeck 940 6.5.2. Unregister front-end for not receiving event
142 schoenebeck 945 messages . . . . . . . . . . . . . . . . . . . . . . . 61
143     6.5.3. Enable or disable echo of commands . . . . . . . . . . 62
144     6.5.4. Close client connection . . . . . . . . . . . . . . . 62
145     6.6. Global commands . . . . . . . . . . . . . . . . . . . . . 62
146     6.6.1. Current number of active voices . . . . . . . . . . . 62
147     6.6.2. Maximum amount of active voices . . . . . . . . . . . 63
148     6.6.3. Reset sampler . . . . . . . . . . . . . . . . . . . . 63
149     6.6.4. General sampler informations . . . . . . . . . . . . . 63
150     6.7. MIDI Instrument Mapping . . . . . . . . . . . . . . . . . 64
151     6.7.1. Create or replace a MIDI instrument map entry . . . . 64
152     6.7.2. Getting ammount of MIDI instrument map entries . . . . 67
153     6.7.3. Getting indeces of all MIDI instrument map entries . . 67
154     6.7.4. Remove an entry from the MIDI instrument map . . . . . 68
155     6.7.5. Get current settings of MIDI instrument map entry . . 69
156     6.7.6. Clear MIDI instrument map . . . . . . . . . . . . . . 70
157     7. Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . 72
158     8. Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
159     8.1. Number of sampler channels changed . . . . . . . . . . . . 81
160     8.2. Number of active voices changed . . . . . . . . . . . . . 81
161     8.3. Number of active disk streams changed . . . . . . . . . . 81
162     8.4. Disk stream buffer fill state changed . . . . . . . . . . 82
163     8.5. Channel information changed . . . . . . . . . . . . . . . 82
164 schoenebeck 708
165 senoner 542
166    
167 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 3]
168 schoenebeck 940
169     Internet-Draft LinuxSampler Control Protocol November 2006
170 senoner 542
171    
172 schoenebeck 945 8.6. Total number of active voices changed . . . . . . . . . . 82
173     8.7. Miscellaneous and debugging events . . . . . . . . . . . . 83
174     9. Security Considerations . . . . . . . . . . . . . . . . . . . 84
175     10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 85
176     11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 85
177     Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 86
178     Intellectual Property and Copyright Statements . . . . . . . . . . 87
179    
180    
181    
182    
183    
184    
185    
186    
187    
188    
189    
190    
191    
192    
193    
194    
195    
196    
197    
198    
199    
200    
201    
202    
203    
204    
205    
206    
207    
208    
209    
210    
211    
212    
213    
214    
215    
216    
217    
218    
219    
220    
221    
222    
223     Schoenebeck Expires May 30, 2007 [Page 4]
224    
225     Internet-Draft LinuxSampler Control Protocol November 2006
226    
227    
228 senoner 542 1. Requirements notation
229    
230     The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
231     "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
232     document are to be interpreted as described in [RFC2119].
233    
234     This protocol is always case-sensitive if not explicitly claimed the
235     opposite.
236    
237 schoenebeck 708 In examples, "C:" and "S:" indicate lines sent by the client (front-
238     end) and server (LinuxSampler) respectively. Lines in examples must
239     be interpreted as every line being CRLF terminated (carriage return
240     character followed by line feed character as defined in the ASCII
241     standard), thus the following example:
242 senoner 542
243     C: "some line"
244 schoenebeck 708
245 senoner 542 "another line"
246    
247     must actually be interpreted as client sending the following message:
248    
249     "some line<CR><LF>another line<CR><LF>"
250    
251     where <CR> symbolizes the carriage return character and <LF> the line
252     feed character as defined in the ASCII standard.
253    
254     Due to technical reasons, messages can arbitrary be fragmented, means
255     the following example:
256    
257     S: "abcd"
258    
259     could also happen to be sent in three messages like in the following
260     sequence scenario:
261    
262     o server sending message "a"
263 schoenebeck 708
264 senoner 542 o followed by a delay (pause) with arbitrary duration
265 schoenebeck 708
266 senoner 542 o followed by server sending message "bcd<CR>"
267 schoenebeck 708
268 senoner 542 o again followed by a delay (pause) with arbitrary duration
269 schoenebeck 708
270 senoner 542 o followed by server sending the message "<LF>"
271    
272     where again <CR> and <LF> symbolize the carriage return and line feed
273     characters respectively.
274    
275    
276    
277    
278    
279 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 5]
280 schoenebeck 940
281     Internet-Draft LinuxSampler Control Protocol November 2006
282 senoner 542
283    
284 schoenebeck 575 2. Versioning of this specification
285 senoner 542
286 schoenebeck 575 LSCP will certainly be extended and enhanced by-and-by. Each
287     official release of the LSCP specification will be tagged with a
288     unique version tuple. The version tuple consists at least of a major
289     and minor version number like:
290    
291     "1.2"
292    
293     In this example the major version number would be "1" and the minor
294     version number would be "2". Note that the version tuple might also
295     have more than two elements. The major version number defines a
296     group of backward compatible versions. That means a frontend is
297     compatible to the connected sampler if and only if the LSCP versions
298     to which each of the two parties complies to, match both of the
299     following rules:
300    
301     Compatibility:
302    
303     1. The frontend's LSCP major version and the sampler's LSCP major
304     version are exactly equal.
305 schoenebeck 708
306 schoenebeck 575 2. The frontend's LSCP minor version is less or equal than the
307     sampler's LSCP minor version.
308    
309     Compatibility can only be claimed if both rules are true. The
310 schoenebeck 940 frontend can use the "GET SERVER INFO" (Section 6.6.4) command to get
311 schoenebeck 575 the version of the LSCP specification the sampler complies with.
312    
313    
314    
315    
316    
317    
318    
319    
320    
321    
322    
323    
324    
325    
326    
327    
328    
329    
330    
331    
332    
333    
334    
335 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 6]
336 schoenebeck 940
337     Internet-Draft LinuxSampler Control Protocol November 2006
338 schoenebeck 575
339    
340     3. Introduction
341    
342 senoner 542 LinuxSampler is a so called software sampler application capable to
343     playback audio samples from a computer's Random Access Memory (RAM)
344     as well as directly streaming it from disk. LinuxSampler is designed
345     to be modular. It provides several so called "sampler engines" where
346     each engine is specialized for a certain purpose. LinuxSampler has
347     virtual channels which will be referred in this document as "sampler
348     channels". The channels are in such way virtual as they can be
349     connected to an arbitrary MIDI input method and arbitrary MIDI
350 schoenebeck 708 channel (e.g. sampler channel 17 could be connected to an ALSA
351 senoner 542 sequencer device 64:0 and listening to MIDI channel 1 there). Each
352 schoenebeck 575 sampler channel will be associated with an instance of one of the
353 senoner 542 available sampler engines (e.g. GigEngine, DLSEngine). The audio
354     output of each sampler channel can be routed to an arbitrary audio
355     output method (ALSA / JACK) and an arbitrary audio output channel
356     there.
357    
358    
359    
360    
361    
362    
363    
364    
365    
366    
367    
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 945 Schoenebeck Expires May 30, 2007 [Page 7]
392 schoenebeck 940
393     Internet-Draft LinuxSampler Control Protocol November 2006
394 senoner 542
395    
396 schoenebeck 575 4. Focus of this protocol
397 senoner 542
398     Main focus of this protocol is to provide a way to configure a
399     running LinuxSampler instance and to retrieve information about it.
400     The focus of this protocol is not to provide a way to control
401     synthesis parameters or even to trigger or release notes. Or in
402     other words; the focus are those functionalities which are not
403     covered by MIDI or which may at most be handled via MIDI System
404     Exclusive Messages.
405    
406    
407    
408    
409    
410    
411    
412    
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 945 Schoenebeck Expires May 30, 2007 [Page 8]
448 schoenebeck 940
449     Internet-Draft LinuxSampler Control Protocol November 2006
450 senoner 542
451    
452 schoenebeck 575 5. Communication Overview
453 senoner 542
454     There are two distinct methods of communication between a running
455     instance of LinuxSampler and one or more control applications, so
456     called "front-ends": a simple request/response communication method
457     used by the clients to give commands to the server as well as to
458     inquire about server's status and a subscribe/notify communication
459     method used by the client to subscribe to and receive notifications
460     of certain events as they happen on the server. The latter needs
461     more effort to be implemented in the front-end application. The two
462     communication methods will be described next.
463    
464 schoenebeck 940 5.1. Request/response communication method
465 senoner 542
466 schoenebeck 575 This simple communication method is based on TCP [RFC793]. The
467     front-end application establishes a TCP connection to the
468     LinuxSampler instance on a certain host system. Then the front-end
469     application will send certain ASCII based commands as defined in this
470     document (every command line must be CRLF terminated - see
471     "Conventions used in this document" at the beginning of this
472     document) and the LinuxSampler application will response after a
473     certain process time with an appropriate ASCII based answer, also as
474     defined in this document. So this TCP communication is simply based
475     on query and answer paradigm. That way LinuxSampler is only able to
476     answer on queries from front-ends, but not able to automatically send
477     messages to the client if it's not asked to. The fronted should not
478     reconnect to LinuxSampler for every single command, instead it should
479     keep the connection established and simply resend message(s) for
480     subsequent commands. To keep information in the front-end up-to-date
481     the front-end has to periodically send new requests to get the
482     current information from the LinuxSampler instance. This is often
483     referred to as "polling". While polling is simple to implement and
484     may be OK to use in some cases, there may be disadvantages to polling
485     such as network traffic overhead and information being out of date.
486     It is possible for a client or several clients to open more than one
487 senoner 542 connection to the server at the same time. It is also possible to
488     send more than one request to the server at the same time but if
489     those requests are sent over the same connection server MUST execute
490     them sequentially. Upon executing a request server will produce a
491     result set and send it to the client. Each and every request made by
492     the client MUST result in a result set being sent back to the client.
493     No other data other than a result set may be sent by a server to a
494     client. No result set may be sent to a client without the client
495     sending request to the server first. On any particular connection,
496     result sets MUST be sent in their entirety without being interrupted
497     by other result sets. If several requests got queued up at the
498     server they MUST be processed in the order they were received and
499     result sets MUST be sent back in the same order.
500    
501    
502    
503 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 9]
504 schoenebeck 940
505     Internet-Draft LinuxSampler Control Protocol November 2006
506 senoner 542
507    
508 schoenebeck 940 5.1.1. Result format
509 schoenebeck 708
510 senoner 542 Result set could be one of the following types:
511    
512     1. Normal
513 schoenebeck 708
514 senoner 542 2. Warning
515 schoenebeck 708
516 senoner 542 3. Error
517    
518     Warning and Error result sets MUST be single line and have the
519     following format:
520    
521     o "WRN:<warning-code>:<warning-message>"
522 schoenebeck 708
523 senoner 542 o "ERR:<error-code>:<error-message>"
524    
525     Where <warning-code> and <error-code> are numeric unique identifiers
526     of the warning or error and <warning-message> and <error-message> are
527     human readable descriptions of the warning or error respectively.
528    
529     Examples:
530    
531     C: "LOAD INSTRUMENT '/home/me/Boesendorfer24bit.gig" 0 0
532 schoenebeck 708
533 senoner 542 S: "WRN:32:This is a 24 bit patch which is not supported natively
534     yet."
535    
536     C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA EAR"
537 schoenebeck 708
538 senoner 542 S: "ERR:3456:Audio output driver 'ALSA' does not have a parameter
539     'EAR'."
540    
541     C: "GET AUDIO_OUTPUT_DEVICE INFO 123456"
542 schoenebeck 708
543 senoner 542 S: "ERR:9:There is no audio output device with index 123456."
544    
545     Normal result sets could be:
546    
547     1. Empty
548 schoenebeck 708
549 senoner 542 2. Single line
550 schoenebeck 708
551 senoner 542 3. Multi-line
552    
553     Empty result set is issued when the server only needed to acknowledge
554     the fact that the request was received and it was processed
555     successfully and no additional information is available. This result
556    
557    
558    
559 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 10]
560 schoenebeck 940
561     Internet-Draft LinuxSampler Control Protocol November 2006
562 senoner 542
563    
564 schoenebeck 708 set has the following format:
565 senoner 542
566 schoenebeck 708 "OK"
567 senoner 542
568 schoenebeck 708 Example:
569 senoner 542
570 schoenebeck 708 C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 CHANNELS=4"
571    
572 senoner 542 S: "OK"
573    
574     Single line result sets are command specific. One example of a
575     single line result set is an empty line. Multi-line result sets are
576     command specific and may include one or more lines of information.
577     They MUST always end with the following line:
578    
579     "."
580    
581     Example:
582    
583     C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
584 schoenebeck 708
585 senoner 542 S: "DRIVER: ALSA"
586 schoenebeck 708
587 senoner 542 "CHANNELS: 2"
588 schoenebeck 708
589 senoner 542 "SAMPLERATE: 44100"
590 schoenebeck 708
591 senoner 542 "ACTIVE: true"
592 schoenebeck 708
593 senoner 542 "FRAGMENTS: 2"
594 schoenebeck 708
595 senoner 542 "FRAGMENTSIZE: 128"
596 schoenebeck 708
597 senoner 542 "CARD: '0,0'"
598 schoenebeck 708
599 senoner 542 "."
600    
601     In addition to above mentioned formats, warnings and empty result
602     sets MAY be indexed. In this case, they have the following formats
603     respectively:
604    
605     o "WRN[<index>]:<warning-code>:<warning-message>"
606 schoenebeck 708
607 senoner 542 o "OK[<index>]"
608    
609     where <index> is command specific and is used to indicate channel
610     number that the result set was related to or other integer value.
611    
612 schoenebeck 708
613    
614    
615 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 11]
616 schoenebeck 940
617     Internet-Draft LinuxSampler Control Protocol November 2006
618 schoenebeck 708
619    
620 senoner 542 Each line of the result set MUST end with <CRLF>.
621    
622     Examples:
623    
624     C: "ADD CHANNEL"
625 schoenebeck 708
626 senoner 542 S: "OK[12]"
627    
628     C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"
629 schoenebeck 708
630 senoner 542 S: "WRN[0]:32:Sample rate not supported, using 44100 instead."
631    
632 schoenebeck 940 5.2. Subscribe/notify communication method
633 schoenebeck 708
634 senoner 542 This more sophisticated communication method is actually only an
635     extension of the simple request/response communication method. The
636     front-end still uses a TCP connection and sends the same commands on
637     the TCP connection. Two extra commands are SUBSCRIBE and UNSUBSCRIBE
638     commands that allow a client to tell the server that it is interested
639     in receiving notifications about certain events as they happen on the
640     server. The SUBSCRIBE command has the following syntax:
641    
642     SUBSCRIBE <event-id>
643    
644     where <event-id> will be replaced by the respective event that client
645     wants to subscribe to. Upon receiving such request, server SHOULD
646     respond with OK and start sending EVENT notifications when a given
647     even has occurred to the front-end when an event has occurred. It
648     MAY be possible certain events may be sent before OK response during
649     real time nature of their generation. Event messages have the
650     following format:
651    
652     NOTIFY:<event-id>:<custom-event-data>
653    
654     where <event-id> uniquely identifies the event that has occurred and
655     <custom-event-data> is event specific.
656    
657     Several rules must be followed by the server when generating events:
658    
659     1. Events MUST NOT be sent to any client who has not issued an
660     appropriate SUBSCRIBE command.
661 schoenebeck 708
662 senoner 542 2. Events MUST only be sent using the same connection that was used
663     to subscribe to them.
664 schoenebeck 708
665 senoner 542 3. When response is being sent to the client, event MUST be inserted
666     in the stream before or after the response, but NOT in the
667 schoenebeck 940 middle. Same is true about the response. It should never be
668 schoenebeck 708
669    
670    
671 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 12]
672 schoenebeck 940
673     Internet-Draft LinuxSampler Control Protocol November 2006
674 schoenebeck 708
675    
676 senoner 542 inserted in the middle of the event message as well as any other
677     response.
678    
679     If the client is not interested in a particular event anymore it MAY
680     issue UNSUBSCRIBE command using the following syntax:
681    
682     UNSUBSCRIBE <event-id>
683    
684     where <event-id> will be replace by the respective event that client
685     is no longer interested in receiving. For a list of supported events
686 schoenebeck 575 see Section 8.
687 senoner 542
688     Example: the fill states of disk stream buffers have changed on
689     sampler channel 4 and the LinuxSampler instance will react by sending
690     the following message to all clients who subscribed to this event:
691    
692     NOTIFY:CHANNEL_BUFFER_FILL:4 [35]62%,[33]80%,[37]98%
693    
694     Which means there are currently three active streams on sampler
695     channel 4, where the stream with ID "35" is filled by 62%, stream
696     with ID 33 is filled by 80% and stream with ID 37 is filled by 98%.
697    
698     Clients may choose to open more than one connection to the server and
699     use some connections to receive notifications while using other
700     connections to issue commands to the back-end. This is entirely
701     legal and up to the implementation. This does not change the
702     protocol in any way and no special restrictions exist on the server
703     to allow or disallow this or to track what connections belong to what
704     front-ends. Server will listen on a single port, accept multiple
705     connections and support protocol described in this specification in
706     it's entirety on this single port on each connection that it
707     accepted.
708    
709     Due to the fact that TCP is used for this communication, dead peers
710     will be detected automatically by the OS TCP stack. While it may
711     take a while to detect dead peers if no traffic is being sent from
712     server to client (TCP keep-alive timer is set to 2 hours on many
713     OSes) it will not be an issue here as when notifications are sent by
714     the server, dead client will be detected quickly.
715    
716     When connection is closed for any reason server MUST forget all
717     subscriptions that were made on this connection. If client
718     reconnects it MUST resubscribe to all events that it wants to
719     receive.
720    
721    
722    
723    
724    
725    
726    
727 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 13]
728 schoenebeck 940
729     Internet-Draft LinuxSampler Control Protocol November 2006
730 senoner 542
731    
732 schoenebeck 575 6. Description for control commands
733 senoner 542
734     This chapter will describe the available control commands that can be
735     sent on the TCP connection in detail. Some certain commands (e.g.
736 schoenebeck 708 "GET CHANNEL INFO" (Section 6.4.10) or "GET ENGINE INFO"
737     (Section 6.4.9)) lead to multiple-line responses. In this case
738     LinuxSampler signals the end of the response by a "." (single dot)
739     line.
740 senoner 542
741 schoenebeck 940 6.1. Ignored lines and comments
742 senoner 542
743     White lines, that is lines which only contain space and tabulator
744     characters, and lines that start with a "#" character are ignored,
745     thus it's possible for example to group commands and to place
746     comments in a LSCP script file.
747    
748 schoenebeck 940 6.2. Configuring audio drivers
749 senoner 542
750     Instances of drivers in LinuxSampler are called devices. You can use
751 schoenebeck 708 multiple audio devices simultaneously, e.g. to output the sound of
752 senoner 542 one sampler channel using the ALSA audio output driver, and on
753     another sampler channel you might want to use the JACK audio output
754     driver. For particular audio output systems it's also possible to
755 schoenebeck 708 create several devices of the same audio output driver, e.g. two
756 senoner 542 separate ALSA audio output devices for using two different sound
757     cards at the same time. This chapter describes all commands to
758     configure LinuxSampler's audio output devices and their parameters.
759    
760     Instead of defining commands and parameters for each driver
761     individually, all possible parameters, their meanings and possible
762     values have to be obtained at runtime. This makes the protocol a bit
763     abstract, but has the advantage, that front-ends can be written
764     independently of what drivers are currently implemented and what
765 schoenebeck 708 parameters these drivers are actually offering. This means front-
766     ends can even handle drivers which are implemented somewhere in
767 senoner 542 future without modifying the front-end at all.
768    
769     Note: examples in this chapter showing particular parameters of
770     drivers are not meant as specification of the drivers' parameters.
771     Driver implementations in LinuxSampler might have complete different
772     parameter names and meanings than shown in these examples or might
773     change in future, so these examples are only meant for showing how to
774     retrieve what parameters drivers are offering, how to retrieve their
775     possible values, etc.
776    
777 schoenebeck 940 6.2.1. Getting amount of available audio output drivers
778 senoner 542
779     Use the following command to get the number of audio output drivers
780    
781    
782    
783 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 14]
784 schoenebeck 940
785     Internet-Draft LinuxSampler Control Protocol November 2006
786 senoner 542
787    
788 schoenebeck 708 currently available for the LinuxSampler instance:
789    
790 senoner 542 GET AVAILABLE_AUDIO_OUTPUT_DRIVERS
791    
792     Possible Answers:
793    
794     LinuxSampler will answer by sending the number of audio output
795     drivers.
796    
797     Example:
798    
799     C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
800 schoenebeck 708
801 senoner 542 S: "2"
802    
803 schoenebeck 940 6.2.2. Getting all available audio output drivers
804 schoenebeck 708
805 senoner 542 Use the following command to list all audio output drivers currently
806     available for the LinuxSampler instance:
807    
808     LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS
809    
810     Possible Answers:
811    
812     LinuxSampler will answer by sending comma separated character
813     strings, each symbolizing an audio output driver.
814    
815     Example:
816    
817     C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"
818 schoenebeck 708
819 senoner 542 S: "ALSA,JACK"
820    
821 schoenebeck 940 6.2.3. Getting information about a specific audio output driver
822 schoenebeck 708
823 senoner 542 Use the following command to get detailed information about a
824     specific audio output driver:
825    
826     GET AUDIO_OUTPUT_DRIVER INFO <audio-output-driver>
827    
828     Where <audio-output-driver> is the name of the audio output driver,
829 schoenebeck 575 returned by the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2)
830 senoner 542 command.
831    
832     Possible Answers:
833    
834 schoenebeck 708
835    
836    
837    
838    
839 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 15]
840 schoenebeck 940
841     Internet-Draft LinuxSampler Control Protocol November 2006
842 schoenebeck 708
843 schoenebeck 940
844 senoner 542 LinuxSampler will answer by sending a <CRLF> separated list. Each
845     answer line begins with the information category name followed by
846     a colon and then a space character <SP> and finally the info
847     character string to that info category. At the moment the
848     following information categories are defined:
849    
850    
851    
852 schoenebeck 708 DESCRIPTION -
853 senoner 542
854 schoenebeck 708 character string describing the audio output driver
855 senoner 542
856 schoenebeck 708 VERSION -
857 senoner 542
858 schoenebeck 708 character string reflecting the driver's version
859 senoner 542
860     PARAMETERS -
861 schoenebeck 708
862 senoner 542 comma separated list of all parameters available for the
863     given audio output driver, at least parameters 'channels',
864     'samplerate' and 'active' are offered by all audio output
865     drivers
866 schoenebeck 708
867 senoner 542 The mentioned fields above don't have to be in particular order.
868    
869     Example:
870    
871     C: "GET AUDIO_OUTPUT_DRIVER INFO ALSA"
872 schoenebeck 708
873 senoner 542 S: "DESCRIPTION: Advanced Linux Sound Architecture"
874 schoenebeck 708
875 senoner 542 "VERSION: 1.0"
876 schoenebeck 708
877 senoner 542 "PARAMETERS: DRIVER,CHANNELS,SAMPLERATE,ACTIVE,FRAGMENTS,
878     FRAGMENTSIZE,CARD"
879 schoenebeck 708
880 senoner 542 "."
881    
882 schoenebeck 940 6.2.4. Getting information about specific audio output driver parameter
883 schoenebeck 708
884 senoner 542 Use the following command to get detailed information about a
885     specific audio output driver parameter:
886    
887     GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO <audio> <prm> [<deplist>]
888    
889     Where <audio> is the name of the audio output driver as returned by
890 schoenebeck 575 the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2) command,
891 schoenebeck 940 <prm> a specific parameter name for which information should be
892 schoenebeck 708
893    
894    
895 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 16]
896 schoenebeck 940
897     Internet-Draft LinuxSampler Control Protocol November 2006
898 schoenebeck 708
899    
900     obtained (as returned by the "GET AUDIO_OUTPUT_DRIVER INFO"
901     (Section 6.2.3) command) and <deplist> is an optional list of
902     parameters on which the sought parameter <prm> depends on, <deplist>
903     is a list of key-value pairs in form of "key1=val1 key2=val2 ...",
904     where character string values are encapsulated into apostrophes (').
905     Arguments given with <deplist> which are not dependency parameters of
906     <prm> will be ignored, means the front-end application can simply put
907     all parameters into <deplist> with the values already selected by the
908 senoner 542 user.
909    
910     Possible Answers:
911    
912     LinuxSampler will answer by sending a <CRLF> separated list. Each
913     answer line begins with the information category name followed by
914     a colon and then a space character <SP> and finally the info
915     character string to that info category. There are information
916     which is always returned, independently of the given driver
917     parameter and there are optional information which is only shown
918     dependently to given driver parameter. At the moment the
919     following information categories are defined:
920    
921     TYPE -
922 schoenebeck 708
923 senoner 542 either "BOOL" for boolean value(s) or "INT" for integer
924     value(s) or "FLOAT" for dotted number(s) or "STRING" for
925     character string(s) (always returned, no matter which driver
926     parameter)
927 schoenebeck 708
928 senoner 542 DESCRIPTION -
929 schoenebeck 708
930 senoner 542 arbitrary text describing the purpose of the parameter (always
931     returned, no matter which driver parameter)
932 schoenebeck 708
933 senoner 542 MANDATORY -
934 schoenebeck 708
935 senoner 542 either true or false, defines if this parameter must be given
936     when the device is to be created with the 'CREATE
937 schoenebeck 575 AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command (always returned,
938 senoner 542 no matter which driver parameter)
939 schoenebeck 708
940 senoner 542 FIX -
941 schoenebeck 708
942 senoner 542 either true or false, if false then this parameter can be
943     changed at any time, once the device is created by the 'CREATE
944 schoenebeck 575 AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command (always returned,
945 senoner 542 no matter which driver parameter)
946 schoenebeck 708
947    
948    
949    
950    
951 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 17]
952 schoenebeck 940
953     Internet-Draft LinuxSampler Control Protocol November 2006
954 schoenebeck 708
955    
956 senoner 542 MULTIPLICITY -
957 schoenebeck 708
958 senoner 542 either true or false, defines if this parameter allows only one
959     value or a list of values, where true means multiple values and
960     false only a single value allowed (always returned, no matter
961     which driver parameter)
962 schoenebeck 708
963 senoner 542 DEPENDS -
964 schoenebeck 708
965 schoenebeck 561 comma separated list of parameters this parameter depends on,
966 senoner 542 means the values for fields 'DEFAULT', 'RANGE_MIN', 'RANGE_MAX'
967     and 'POSSIBILITIES' might depend on these listed parameters,
968     for example assuming that an audio driver (like the ALSA
969     driver) offers parameters 'card' and 'samplerate' then
970     parameter 'samplerate' would depend on 'card' because the
971     possible values for 'samplerate' depends on the sound card
972     which can be chosen by the 'card' parameter (optionally
973     returned, dependent to driver parameter)
974 schoenebeck 708
975 senoner 542 DEFAULT -
976 schoenebeck 708
977 senoner 542 reflects the default value for this parameter which is used
978     when the device is created and not explicitly given with the
979 schoenebeck 575 'CREATE AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command, in case
980 senoner 542 of MULTIPLCITY=true, this is a comma separated list, that's why
981     character strings are encapsulated into apostrophes (')
982     (optionally returned, dependent to driver parameter)
983 schoenebeck 708
984 senoner 542 RANGE_MIN -
985 schoenebeck 708
986 senoner 542 defines lower limit of the allowed value range for this
987     parameter, can be an integer value as well as a dotted number,
988     this parameter is often used in conjunction with RANGE_MAX, but
989     may also appear without (optionally returned, dependent to
990     driver parameter)
991 schoenebeck 708
992 senoner 542 RANGE_MAX -
993 schoenebeck 708
994 senoner 542 defines upper limit of the allowed value range for this
995     parameter, can be an integer value as well as a dotted number,
996     this parameter is often used in conjunction with RANGE_MIN, but
997     may also appear without (optionally returned, dependent to
998     driver parameter)
999 schoenebeck 708
1000 senoner 542 POSSIBILITIES -
1001 schoenebeck 708
1002 senoner 542 comma separated list of possible values for this parameter,
1003     character strings are encapsulated into apostrophes (optionally
1004 schoenebeck 708
1005    
1006    
1007 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 18]
1008 schoenebeck 940
1009     Internet-Draft LinuxSampler Control Protocol November 2006
1010 schoenebeck 708
1011    
1012 senoner 542 returned, dependent to driver parameter)
1013    
1014     The mentioned fields above don't have to be in particular order.
1015    
1016     Examples:
1017    
1018     C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA CARD"
1019 schoenebeck 708
1020 senoner 542 S: "DESCRIPTION: sound card to be used"
1021 schoenebeck 708
1022 senoner 542 "TYPE: STRING"
1023 schoenebeck 708
1024 senoner 542 "MANDATORY: false"
1025 schoenebeck 708
1026 senoner 542 "FIX: true"
1027 schoenebeck 708
1028 senoner 542 "MULTIPLICITY: false"
1029 schoenebeck 708
1030 senoner 542 "DEFAULT: '0,0'"
1031 schoenebeck 708
1032 senoner 542 "POSSIBILITIES: '0,0','1,0','2,0'"
1033 schoenebeck 708
1034 senoner 542 "."
1035    
1036     C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE"
1037 schoenebeck 708
1038 senoner 542 S: "DESCRIPTION: output sample rate in Hz"
1039 schoenebeck 708
1040 senoner 542 "TYPE: INT"
1041 schoenebeck 708
1042 senoner 542 "MANDATORY: false"
1043 schoenebeck 708
1044 senoner 542 "FIX: false"
1045 schoenebeck 708
1046 senoner 542 "MULTIPLICITY: false"
1047 schoenebeck 708
1048 senoner 542 "DEPENDS: card"
1049 schoenebeck 708
1050 senoner 542 "DEFAULT: 44100"
1051 schoenebeck 708
1052 senoner 542 "."
1053    
1054     C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE
1055     CARD='0,0'"
1056 schoenebeck 708
1057 senoner 542 S: "DESCRIPTION: output sample rate in Hz"
1058 schoenebeck 708
1059    
1060    
1061    
1062    
1063 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 19]
1064 schoenebeck 940
1065     Internet-Draft LinuxSampler Control Protocol November 2006
1066 schoenebeck 708
1067    
1068 senoner 542 "TYPE: INT"
1069 schoenebeck 708
1070 senoner 542 "MANDATORY: false"
1071 schoenebeck 708
1072 senoner 542 "FIX: false"
1073 schoenebeck 708
1074 senoner 542 "MULTIPLICITY: false"
1075 schoenebeck 708
1076 senoner 542 "DEPENDS: card"
1077 schoenebeck 708
1078 senoner 542 "DEFAULT: 44100"
1079 schoenebeck 708
1080 senoner 542 "RANGE_MIN: 22050"
1081    
1082 schoenebeck 708 "RANGE_MAX: 96000"
1083 senoner 542
1084 schoenebeck 708 "."
1085 senoner 542
1086 schoenebeck 940 6.2.5. Creating an audio output device
1087 senoner 542
1088 schoenebeck 940 Use the following command to create a new audio output device for the
1089     desired audio output system:
1090 senoner 542
1091     CREATE AUDIO_OUTPUT_DEVICE <audio-output-driver> [<param-list>]
1092    
1093     Where <audio-output-driver> should be replaced by the desired audio
1094 schoenebeck 575 output system as returned by the "LIST
1095 schoenebeck 708 AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2) command and <param-
1096     list> by an optional list of driver specific parameters in form of
1097     "key1=val1 key2=val2 ...", where character string values should be
1098     encapsulated into apostrophes ('). Note that there might be drivers
1099     which require parameter(s) to be given with this command. Use the
1100     previously described commands in this chapter to get this
1101 schoenebeck 575 information.
1102 senoner 542
1103     Possible Answers:
1104    
1105     "OK[<device-id>]" -
1106 schoenebeck 708
1107 senoner 542 in case the device was successfully created, where <device-id>
1108     is the numerical ID of the new device
1109 schoenebeck 708
1110 senoner 542 "WRN[<device-id>]:<warning-code>:<warning-message>" -
1111 schoenebeck 708
1112 senoner 542 in case the device was created successfully, where <device-id>
1113     is the numerical ID of the new device, but there are noteworthy
1114 schoenebeck 708 issue(s) related (e.g. sound card doesn't support given
1115 schoenebeck 940 hardware parameters and the driver is using fall-back values),
1116 schoenebeck 708
1117    
1118    
1119 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 20]
1120 schoenebeck 940
1121     Internet-Draft LinuxSampler Control Protocol November 2006
1122 schoenebeck 708
1123    
1124 senoner 542 providing an appropriate warning code and warning message
1125 schoenebeck 708
1126 senoner 542 "ERR:<error-code>:<error-message>" -
1127 schoenebeck 708
1128 senoner 542 in case it failed, providing an appropriate error code and
1129     error message
1130    
1131     Examples:
1132    
1133     C: "CREATE AUDIO_OUTPUT_DEVICE ALSA"
1134 schoenebeck 708
1135 senoner 542 S: "OK[0]"
1136    
1137     C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"
1138 schoenebeck 708
1139 senoner 542 S: "OK[1]"
1140    
1141 schoenebeck 940 6.2.6. Destroying an audio output device
1142 schoenebeck 708
1143 senoner 542 Use the following command to destroy a created output device:
1144    
1145 schoenebeck 575 DESTROY AUDIO_OUTPUT_DEVICE <device-id>
1146    
1147     Where <device-id> should be replaced by the numerical ID of the audio
1148 schoenebeck 708 output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
1149     (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
1150     command.
1151 senoner 542
1152     Possible Answers:
1153    
1154     "OK" -
1155 schoenebeck 708
1156 senoner 542 in case the device was successfully destroyed
1157 schoenebeck 708
1158 senoner 542 "WRN:<warning-code>:<warning-message>" -
1159 schoenebeck 708
1160 senoner 542 in case the device was destroyed successfully, but there are
1161 schoenebeck 708 noteworthy issue(s) related (e.g. an audio over ethernet driver
1162     was unloaded but the other host might not be informed about
1163     this situation), providing an appropriate warning code and
1164     warning message
1165    
1166 senoner 542 "ERR:<error-code>:<error-message>" -
1167 schoenebeck 708
1168 senoner 542 in case it failed, providing an appropriate error code and
1169     error message
1170    
1171 schoenebeck 940 Example:
1172 schoenebeck 708
1173    
1174    
1175 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 21]
1176 schoenebeck 940
1177     Internet-Draft LinuxSampler Control Protocol November 2006
1178 schoenebeck 708
1179    
1180 senoner 542 C: "DESTROY AUDIO_OUTPUT_DEVICE 0"
1181 schoenebeck 708
1182 senoner 542 S: "OK"
1183    
1184 schoenebeck 940 6.2.7. Getting all created audio output device count
1185 schoenebeck 708
1186 senoner 542 Use the following command to count all created audio output devices:
1187    
1188     GET AUDIO_OUTPUT_DEVICES
1189    
1190     Possible Answers:
1191    
1192     LinuxSampler will answer by sending the current number of all
1193     audio output devices.
1194    
1195     Example:
1196    
1197     C: "GET AUDIO_OUTPUT_DEVICES"
1198 schoenebeck 708
1199 senoner 542 S: "4"
1200    
1201 schoenebeck 940 6.2.8. Getting all created audio output device list
1202 schoenebeck 708
1203 senoner 542 Use the following command to list all created audio output devices:
1204    
1205     LIST AUDIO_OUTPUT_DEVICES
1206    
1207     Possible Answers:
1208    
1209 schoenebeck 575 LinuxSampler will answer by sending a comma separated list with
1210     the numerical IDs of all audio output devices.
1211    
1212 senoner 542 Example:
1213    
1214     C: "LIST AUDIO_OUTPUT_DEVICES"
1215 schoenebeck 708
1216 senoner 542 S: "0,1,4,5"
1217    
1218 schoenebeck 940 6.2.9. Getting current settings of an audio output device
1219 schoenebeck 708
1220 senoner 542 Use the following command to get current settings of a specific,
1221     created audio output device:
1222    
1223 schoenebeck 940 GET AUDIO_OUTPUT_DEVICE INFO <device-id>
1224 schoenebeck 708
1225 schoenebeck 940 Where <device-id> should be replaced by numerical ID of the audio
1226     output device as e.g. returned by the "LIST AUDIO_OUTPUT_DEVICES"
1227     (Section 6.2.8) command.
1228 schoenebeck 708
1229    
1230    
1231 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 22]
1232 schoenebeck 940
1233     Internet-Draft LinuxSampler Control Protocol November 2006
1234 schoenebeck 708
1235    
1236 senoner 542 Possible Answers:
1237    
1238     LinuxSampler will answer by sending a <CRLF> separated list. Each
1239     answer line begins with the information category name followed by a
1240     colon and then a space character <SP> and finally the info character
1241     string to that info category. As some parameters might allow
1242     multiple values, character strings are encapsulated into apostrophes
1243     ('). At the moment the following information categories are defined
1244     (independently of device):
1245    
1246     DRIVER -
1247 schoenebeck 708
1248 senoner 542 identifier of the used audio output driver, as also returned by
1249 schoenebeck 575 the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2)
1250 senoner 542 command
1251 schoenebeck 708
1252 senoner 542 CHANNELS -
1253 schoenebeck 708
1254 senoner 542 amount of audio output channels this device currently offers
1255 schoenebeck 708
1256 senoner 542 SAMPLERATE -
1257 schoenebeck 708
1258 senoner 542 playback sample rate the device uses
1259 schoenebeck 708
1260 senoner 542 ACTIVE -
1261 schoenebeck 708
1262 senoner 542 either true or false, if false then the audio device is
1263     inactive and doesn't output any sound, nor do the sampler
1264     channels connected to this audio device render any audio
1265    
1266     The mentioned fields above don't have to be in particular order. The
1267     fields above are only those fields which are returned by all audio
1268     output devices. Every audio output driver might have its own,
1269 schoenebeck 575 additional driver specific parameters (see Section 6.2.3) which are
1270 senoner 542 also returned by this command.
1271    
1272 schoenebeck 708 Example:
1273 senoner 542
1274 schoenebeck 708 C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
1275 senoner 542
1276 schoenebeck 708 S: "DRIVER: ALSA"
1277 senoner 542
1278 schoenebeck 940 "CHANNELS: 2"
1279 senoner 542
1280 schoenebeck 940 "SAMPLERATE: 44100"
1281 senoner 542
1282 schoenebeck 940 "ACTIVE: true"
1283 schoenebeck 575
1284 schoenebeck 708
1285    
1286    
1287 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 23]
1288 schoenebeck 940
1289     Internet-Draft LinuxSampler Control Protocol November 2006
1290 schoenebeck 708
1291    
1292 senoner 542 "FRAGMENTS: 2"
1293 schoenebeck 708
1294 senoner 542 "FRAGMENTSIZE: 128"
1295 schoenebeck 708
1296 senoner 542 "CARD: '0,0'"
1297 schoenebeck 708
1298 senoner 542 "."
1299    
1300 schoenebeck 940 6.2.10. Changing settings of audio output devices
1301 schoenebeck 708
1302 senoner 542 Use the following command to alter a specific setting of a created
1303     audio output device:
1304    
1305     SET AUDIO_OUTPUT_DEVICE_PARAMETER <device-id> <key>=<value>
1306    
1307     Where <device-id> should be replaced by the numerical ID of the audio
1308 schoenebeck 708 output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
1309     (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
1310     command, <key> by the name of the parameter to change and <value> by
1311     the new value for this parameter.
1312 senoner 542
1313     Possible Answers:
1314    
1315     "OK" -
1316 schoenebeck 708
1317 senoner 542 in case setting was successfully changed
1318 schoenebeck 708
1319 senoner 542 "WRN:<warning-code>:<warning-message>" -
1320 schoenebeck 708
1321 senoner 542 in case setting was changed successfully, but there are
1322     noteworthy issue(s) related, providing an appropriate warning
1323     code and warning message
1324 schoenebeck 708
1325 senoner 542 "ERR:<error-code>:<error-message>" -
1326 schoenebeck 708
1327 senoner 542 in case it failed, providing an appropriate error code and
1328     error message
1329    
1330     Example:
1331    
1332 schoenebeck 940 C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"
1333 schoenebeck 708
1334 schoenebeck 940 S: "OK"
1335 schoenebeck 708
1336 schoenebeck 940 6.2.11. Getting information about an audio channel
1337 schoenebeck 708
1338 schoenebeck 940 Use the following command to get information about an audio channel:
1339 schoenebeck 708
1340    
1341    
1342    
1343 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 24]
1344 schoenebeck 940
1345     Internet-Draft LinuxSampler Control Protocol November 2006
1346 schoenebeck 708
1347 senoner 542
1348     GET AUDIO_OUTPUT_CHANNEL INFO <device-id> <audio-chan>
1349    
1350 schoenebeck 575 Where <device-id> is the numerical ID of the audio output device as
1351     given by the "CREATE AUDIO_OUTPUT_DEVICE" (Section 6.2.5) or "LIST
1352     AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command and <audio-chan> the
1353     audio channel number.
1354    
1355     Possible Answers:
1356    
1357 senoner 542 LinuxSampler will answer by sending a <CRLF> separated list. Each
1358     answer line begins with the information category name followed by
1359     a colon and then a space character <SP> and finally the info
1360     character string to that info category. At the moment the
1361     following information categories are defined:
1362    
1363 schoenebeck 708
1364    
1365 senoner 542 NAME -
1366 schoenebeck 708
1367 senoner 542 arbitrary character string naming the channel, which doesn't
1368     have to be unique (always returned by all audio channels)
1369 schoenebeck 708
1370 senoner 542 IS_MIX_CHANNEL -
1371 schoenebeck 708
1372 senoner 542 either true or false, a mix-channel is not a real,
1373     independent audio channel, but a virtual channel which is
1374     mixed to another real channel, this mechanism is needed for
1375     sampler engines which need more audio channels than the used
1376     audio system might be able to offer (always returned by all
1377     audio channels)
1378 schoenebeck 708
1379 senoner 542 MIX_CHANNEL_DESTINATION -
1380 schoenebeck 708
1381 senoner 542 numerical ID (positive integer including 0) which reflects
1382     the real audio channel (of the same audio output device)
1383     this mix channel refers to, means where the audio signal
1384     actually will be routed / added to (only returned in case
1385     the audio channel is mix channel)
1386    
1387     The mentioned fields above don't have to be in particular order. The
1388     fields above are only those fields which are generally returned for
1389     the described cases by all audio channels regardless of the audio
1390     driver. Every audio channel might have its own, additional driver
1391     and channel specific parameters.
1392    
1393     Examples:
1394    
1395 schoenebeck 940
1396    
1397    
1398    
1399 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 25]
1400 schoenebeck 940
1401     Internet-Draft LinuxSampler Control Protocol November 2006
1402    
1403    
1404 senoner 542 C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 0"
1405 schoenebeck 708
1406 senoner 542 S: "NAME: studio monitor left"
1407 schoenebeck 708
1408 senoner 542 "IS_MIX_CHANNEL: false"
1409 schoenebeck 708
1410 senoner 542 "."
1411    
1412     C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 1"
1413 schoenebeck 708
1414 senoner 542 S: "NAME: studio monitor right"
1415 schoenebeck 708
1416 senoner 542 "IS_MIX_CHANNEL: false"
1417 schoenebeck 708
1418 senoner 542 "."
1419    
1420 schoenebeck 708 C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"
1421 senoner 542
1422 schoenebeck 708 S: "NAME: studio monitor left"
1423 senoner 542
1424 schoenebeck 708 "IS_MIX_CHANNEL: true"
1425 senoner 542
1426 schoenebeck 708 "MIX_CHANNEL_DESTINATION: 1"
1427 senoner 542
1428 schoenebeck 575 "."
1429    
1430 senoner 542 C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"
1431 schoenebeck 708
1432 senoner 542 S: "NAME: 'ardour (left)'"
1433 schoenebeck 708
1434 senoner 542 "IS_MIX_CHANNEL: false"
1435 schoenebeck 708
1436 senoner 542 "JACK_BINDINGS: 'ardour:0'"
1437 schoenebeck 708
1438 senoner 542 "."
1439    
1440 schoenebeck 940 6.2.12. Getting information about specific audio channel parameter
1441 schoenebeck 708
1442 senoner 542 Use the following command to get detailed information about specific
1443     audio channel parameter:
1444    
1445     GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO <dev-id> <chan> <param>
1446    
1447     Where <dev-id> is the numerical ID of the audio output device as
1448 schoenebeck 575 returned by the "CREATE AUDIO_OUTPUT_DEVICE" (Section 6.2.5) or "LIST
1449     AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command, <chan> the audio
1450     channel number and <param> a specific channel parameter name for
1451     which information should be obtained (as returned by the "GET
1452 schoenebeck 940
1453    
1454    
1455 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 26]
1456 schoenebeck 940
1457     Internet-Draft LinuxSampler Control Protocol November 2006
1458    
1459    
1460 schoenebeck 575 AUDIO_OUTPUT_CHANNEL INFO" (Section 6.2.11) command).
1461 senoner 542
1462     Possible Answers:
1463    
1464     LinuxSampler will answer by sending a <CRLF> separated list. Each
1465     answer line begins with the information category name followed by
1466     a colon and then a space character <SP> and finally the info
1467     character string to that info category. There are information
1468     which is always returned, independently of the given channel
1469     parameter and there is optional information which is only shown
1470     dependently to the given audio channel. At the moment the
1471     following information categories are defined:
1472    
1473 schoenebeck 708
1474    
1475 senoner 542 TYPE -
1476 schoenebeck 708
1477 senoner 542 either "BOOL" for boolean value(s) or "INT" for integer
1478     value(s) or "FLOAT" for dotted number(s) or "STRING" for
1479     character string(s) (always returned)
1480 schoenebeck 708
1481 senoner 542 DESCRIPTION -
1482 schoenebeck 708
1483 senoner 542 arbitrary text describing the purpose of the parameter
1484     (always returned)
1485 schoenebeck 708
1486 senoner 542 FIX -
1487 schoenebeck 708
1488 senoner 542 either true or false, if true then this parameter is read
1489     only, thus cannot be altered (always returned)
1490 schoenebeck 575
1491 schoenebeck 708 MULTIPLICITY -
1492 schoenebeck 575
1493 schoenebeck 708 either true or false, defines if this parameter allows only
1494     one value or a list of values, where true means multiple
1495     values and false only a single value allowed (always
1496     returned)
1497 schoenebeck 575
1498 schoenebeck 940 RANGE_MIN -
1499 schoenebeck 575
1500 schoenebeck 940 defines lower limit of the allowed value range for this
1501     parameter, can be an integer value as well as a dotted
1502     number, usually used in conjunction with 'RANGE_MAX', but
1503     may also appear without (optionally returned, dependent to
1504     driver and channel parameter)
1505 schoenebeck 575
1506    
1507 schoenebeck 708
1508    
1509    
1510    
1511 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 27]
1512 schoenebeck 940
1513     Internet-Draft LinuxSampler Control Protocol November 2006
1514 schoenebeck 708
1515    
1516 senoner 542 RANGE_MAX -
1517 schoenebeck 708
1518 senoner 542 defines upper limit of the allowed value range for this
1519     parameter, can be an integer value as well as a dotted
1520     number, usually used in conjunction with 'RANGE_MIN', but
1521     may also appear without (optionally returned, dependent to
1522     driver and channel parameter)
1523 schoenebeck 708
1524 senoner 542 POSSIBILITIES -
1525 schoenebeck 708
1526 senoner 542 comma separated list of possible values for this parameter,
1527     character strings are encapsulated into apostrophes
1528     (optionally returned, dependent to driver and channel
1529     parameter)
1530 schoenebeck 708
1531 senoner 542 The mentioned fields above don't have to be in particular order.
1532    
1533     Example:
1534    
1535     C: "GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO 1 0 JACK_BINDINGS"
1536 schoenebeck 708
1537 senoner 542 S: "DESCRIPTION: bindings to other JACK clients"
1538 schoenebeck 708
1539 senoner 542 "TYPE: STRING"
1540 schoenebeck 708
1541 senoner 542 "FIX: false"
1542 schoenebeck 708
1543 senoner 542 "MULTIPLICITY: true"
1544 schoenebeck 708
1545 senoner 542 "POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"
1546 schoenebeck 708
1547 senoner 542 "."
1548    
1549 schoenebeck 940 6.2.13. Changing settings of audio output channels
1550 schoenebeck 708
1551 senoner 542 Use the following command to alter a specific setting of an audio
1552     output channel:
1553    
1554     SET AUDIO_OUTPUT_CHANNEL_PARAMETER <dev-id> <chn> <key>=<value>
1555    
1556     Where <dev-id> should be replaced by the numerical ID of the audio
1557 schoenebeck 575 output device as returned by the "CREATE AUDIO_OUTPUT_DEVICE"
1558     (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
1559     command, <chn> by the audio channel number, <key> by the name of the
1560 senoner 542 parameter to change and <value> by the new value for this parameter.
1561    
1562     Possible Answers:
1563    
1564 schoenebeck 940
1565    
1566    
1567 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 28]
1568 schoenebeck 940
1569     Internet-Draft LinuxSampler Control Protocol November 2006
1570    
1571    
1572 schoenebeck 708 "OK" -
1573 schoenebeck 575
1574 schoenebeck 708 in case setting was successfully changed
1575 schoenebeck 575
1576 schoenebeck 708 "WRN:<warning-code>:<warning-message>" -
1577 schoenebeck 575
1578 senoner 542 in case setting was changed successfully, but there are
1579     noteworthy issue(s) related, providing an appropriate warning
1580     code and warning message
1581 schoenebeck 708
1582 senoner 542 "ERR:<error-code>:<error-message>" -
1583 schoenebeck 708
1584 senoner 542 in case it failed, providing an appropriate error code and
1585     error message
1586    
1587     Example:
1588    
1589     C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"
1590 schoenebeck 708
1591 senoner 542 S: "OK"
1592    
1593     C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"
1594 schoenebeck 708
1595 senoner 542 S: "OK"
1596    
1597 schoenebeck 940 6.3. Configuring MIDI input drivers
1598 schoenebeck 708
1599 senoner 542 Instances of drivers in LinuxSampler are called devices. You can use
1600 schoenebeck 708 multiple MIDI devices simultaneously, e.g. to use MIDI over ethernet
1601 senoner 542 as MIDI input on one sampler channel and ALSA as MIDI input on
1602     another sampler channel. For particular MIDI input systems it's also
1603     possible to create several devices of the same MIDI input type. This
1604     chapter describes all commands to configure LinuxSampler's MIDI input
1605     devices and their parameters.
1606    
1607     Instead of defining commands and parameters for each driver
1608     individually, all possible parameters, their meanings and possible
1609     values have to be obtained at runtime. This makes the protocol a bit
1610     abstract, but has the advantage, that front-ends can be written
1611     independently of what drivers are currently implemented and what
1612 schoenebeck 708 parameters these drivers are actually offering. This means front-
1613     ends can even handle drivers which are implemented somewhere in
1614 senoner 542 future without modifying the front-end at all.
1615    
1616     Commands for configuring MIDI input devices are pretty much the same
1617     as the commands for configuring audio output drivers, already
1618     described in the last chapter.
1619    
1620 schoenebeck 940
1621    
1622    
1623 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 29]
1624 schoenebeck 940
1625     Internet-Draft LinuxSampler Control Protocol November 2006
1626    
1627    
1628 senoner 542 Note: examples in this chapter showing particular parameters of
1629     drivers are not meant as specification of the drivers' parameters.
1630     Driver implementations in LinuxSampler might have complete different
1631     parameter names and meanings than shown in these examples or might
1632     change in future, so these examples are only meant for showing how to
1633     retrieve what parameters drivers are offering, how to retrieve their
1634     possible values, etc.
1635    
1636 schoenebeck 940 6.3.1. Getting amount of available MIDI input drivers
1637 schoenebeck 575
1638 senoner 542 Use the following command to get the number of MIDI input drivers
1639     currently available for the LinuxSampler instance:
1640    
1641     GET AVAILABLE_MIDI_INPUT_DRIVERS
1642    
1643     Possible Answers:
1644    
1645     LinuxSampler will answer by sending the number of available MIDI
1646     input drivers.
1647    
1648     Example:
1649    
1650     C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"
1651 schoenebeck 708
1652 senoner 542 S: "2"
1653    
1654 schoenebeck 940 6.3.2. Getting all available MIDI input drivers
1655 schoenebeck 708
1656 senoner 542 Use the following command to list all MIDI input drivers currently
1657     available for the LinuxSampler instance:
1658    
1659     LIST AVAILABLE_MIDI_INPUT_DRIVERS
1660    
1661     Possible Answers:
1662    
1663     LinuxSampler will answer by sending comma separated character
1664     strings, each symbolizing a MIDI input driver.
1665    
1666     Example:
1667    
1668     C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
1669 schoenebeck 708
1670 senoner 542 S: "ALSA,JACK"
1671    
1672 schoenebeck 940 6.3.3. Getting information about a specific MIDI input driver
1673 schoenebeck 708
1674 senoner 542 Use the following command to get detailed information about a
1675     specific MIDI input driver:
1676    
1677 schoenebeck 940
1678    
1679 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 30]
1680 schoenebeck 940
1681     Internet-Draft LinuxSampler Control Protocol November 2006
1682    
1683    
1684 senoner 542 GET MIDI_INPUT_DRIVER INFO <midi-input-driver>
1685    
1686 schoenebeck 575 Where <midi-input-driver> is the name of the MIDI input driver as
1687     returned by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2)
1688     command.
1689 senoner 542
1690     Possible Answers:
1691    
1692     LinuxSampler will answer by sending a <CRLF> separated list. Each
1693     answer line begins with the information category name followed by
1694     a colon and then a space character <SP> and finally the info
1695     character string to that info category. At the moment the
1696     following information categories are defined:
1697    
1698 schoenebeck 708
1699    
1700 senoner 542 DESCRIPTION -
1701 schoenebeck 708
1702 senoner 542 arbitrary description text about the MIDI input driver
1703 schoenebeck 708
1704 senoner 542 VERSION -
1705 schoenebeck 708
1706 senoner 542 arbitrary character string regarding the driver's version
1707 schoenebeck 708
1708 senoner 542 PARAMETERS -
1709 schoenebeck 708
1710 senoner 542 comma separated list of all parameters available for the
1711     given MIDI input driver
1712 schoenebeck 708
1713 senoner 542 The mentioned fields above don't have to be in particular order.
1714    
1715     Example:
1716    
1717     C: "GET MIDI_INPUT_DRIVER INFO ALSA"
1718 schoenebeck 708
1719 senoner 542 S: "DESCRIPTION: Advanced Linux Sound Architecture"
1720 schoenebeck 708
1721 senoner 542 "VERSION: 1.0"
1722 schoenebeck 708
1723 senoner 542 "PARAMETERS: DRIVER,ACTIVE"
1724 schoenebeck 708
1725 senoner 542 "."
1726    
1727 schoenebeck 940 6.3.4. Getting information about specific MIDI input driver parameter
1728 schoenebeck 708
1729 senoner 542 Use the following command to get detailed information about a
1730     specific parameter of a specific MIDI input driver:
1731    
1732 schoenebeck 940
1733    
1734    
1735 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 31]
1736 schoenebeck 940
1737     Internet-Draft LinuxSampler Control Protocol November 2006
1738    
1739    
1740 senoner 542 GET MIDI_INPUT_DRIVER_PARAMETER INFO <midit> <param> [<deplist>]
1741    
1742 schoenebeck 561 Where <midit> is the name of the MIDI input driver as returned by the
1743 schoenebeck 575 "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2) command, <param>
1744 schoenebeck 561 a specific parameter name for which information should be obtained
1745 schoenebeck 575 (as returned by the "GET MIDI_INPUT_DRIVER INFO" (Section 6.3.3)
1746 schoenebeck 561 command) and <deplist> is an optional list of parameters on which the
1747     sought parameter <param> depends on, <deplist> is a key-value pair
1748     list in form of "key1=val1 key2=val2 ...", where character string
1749     values are encapsulated into apostrophes ('). Arguments given with
1750     <deplist> which are not dependency parameters of <param> will be
1751     ignored, means the front-end application can simply put all
1752     parameters in <deplist> with the values selected by the user.
1753 senoner 542
1754     Possible Answers:
1755    
1756     LinuxSampler will answer by sending a <CRLF> separated list. Each
1757     answer line begins with the information category name followed by a
1758     colon and then a space character <SP> and finally the info character
1759     string to that info category. There is information which is always
1760     returned, independent of the given driver parameter and there is
1761     optional information which is only shown dependent to given driver
1762     parameter. At the moment the following information categories are
1763     defined:
1764    
1765     TYPE -
1766 schoenebeck 708
1767 senoner 542 either "BOOL" for boolean value(s) or "INT" for integer
1768     value(s) or "FLOAT" for dotted number(s) or "STRING" for
1769     character string(s) (always returned, no matter which driver
1770     parameter)
1771 schoenebeck 708
1772 senoner 542 DESCRIPTION -
1773 schoenebeck 708
1774 senoner 542 arbitrary text describing the purpose of the parameter (always
1775     returned, no matter which driver parameter)
1776 schoenebeck 708
1777 senoner 542 MANDATORY -
1778 schoenebeck 708
1779 senoner 542 either true or false, defines if this parameter must be given
1780     when the device is to be created with the 'CREATE
1781 schoenebeck 575 MIDI_INPUT_DEVICE' (Section 6.3.5) command (always returned, no
1782 senoner 542 matter which driver parameter)
1783 schoenebeck 708
1784 senoner 542 FIX -
1785 schoenebeck 708
1786 senoner 542 either true or false, if false then this parameter can be
1787     changed at any time, once the device is created by the 'CREATE
1788 schoenebeck 940
1789    
1790    
1791 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 32]
1792 schoenebeck 940
1793     Internet-Draft LinuxSampler Control Protocol November 2006
1794    
1795    
1796 schoenebeck 575 MIDI_INPUT_DEVICE' (Section 6.3.5) command (always returned, no
1797 senoner 542 matter which driver parameter)
1798 schoenebeck 708
1799 senoner 542 MULTIPLICITY -
1800 schoenebeck 708
1801 senoner 542 either true or false, defines if this parameter allows only one
1802     value or a list of values, where true means multiple values and
1803     false only a single value allowed (always returned, no matter
1804     which driver parameter)
1805 schoenebeck 708
1806 senoner 542 DEPENDS -
1807 schoenebeck 708
1808 schoenebeck 561 comma separated list of parameters this parameter depends on,
1809 senoner 542 means the values for fields 'DEFAULT', 'RANGE_MIN', 'RANGE_MAX'
1810     and 'POSSIBILITIES' might depend on these listed parameters,
1811     for example assuming that an audio driver (like the ALSA
1812     driver) offers parameters 'card' and 'samplerate' then
1813     parameter 'samplerate' would depend on 'card' because the
1814     possible values for 'samplerate' depends on the sound card
1815     which can be chosen by the 'card' parameter (optionally
1816     returned, dependent to driver parameter)
1817 schoenebeck 708
1818 senoner 542 DEFAULT -
1819 schoenebeck 708
1820 senoner 542 reflects the default value for this parameter which is used
1821     when the device is created and not explicitly given with the
1822 schoenebeck 575 'CREATE MIDI_INPUT_DEVICE' (Section 6.3.5) command, in case of
1823 senoner 542 MULTIPLCITY=true, this is a comma separated list, that's why
1824     character strings are encapsulated into apostrophes (')
1825     (optionally returned, dependent to driver parameter)
1826 schoenebeck 575
1827 schoenebeck 708 RANGE_MIN -
1828    
1829     defines lower limit of the allowed value range for this
1830     parameter, can be an integer value as well as a dotted number,
1831 senoner 542 this parameter is often used in conjunction with RANGE_MAX, but
1832     may also appear without (optionally returned, dependent to
1833     driver parameter)
1834 schoenebeck 708
1835 senoner 542 RANGE_MAX -
1836 schoenebeck 708
1837 senoner 542 defines upper limit of the allowed value range for this
1838     parameter, can be an integer value as well as a dotted number,
1839     this parameter is often used in conjunction with RANGE_MIN, but
1840     may also appear without (optionally returned, dependent to
1841     driver parameter)
1842 schoenebeck 708
1843 schoenebeck 940
1844    
1845    
1846    
1847 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 33]
1848 schoenebeck 940
1849     Internet-Draft LinuxSampler Control Protocol November 2006
1850    
1851    
1852 senoner 542 POSSIBILITIES -
1853 schoenebeck 708
1854 senoner 542 comma separated list of possible values for this parameter,
1855     character strings are encapsulated into apostrophes (optionally
1856     returned, dependent to driver parameter)
1857    
1858     The mentioned fields above don't have to be in particular order.
1859    
1860     Example:
1861    
1862     C: "GET MIDI_INPUT_DRIVER_PARAMETER INFO ALSA ACTIVE"
1863 schoenebeck 708
1864 senoner 542 S: "DESCRIPTION: Whether device is enabled"
1865 schoenebeck 708
1866 senoner 542 "TYPE: BOOL"
1867 schoenebeck 708
1868 senoner 542 "MANDATORY: false"
1869 schoenebeck 708
1870 senoner 542 "FIX: false"
1871 schoenebeck 708
1872 senoner 542 "MULTIPLICITY: false"
1873 schoenebeck 708
1874 senoner 542 "DEFAULT: true"
1875 schoenebeck 708
1876 senoner 542 "."
1877    
1878 schoenebeck 940 6.3.5. Creating a MIDI input device
1879 schoenebeck 708
1880 schoenebeck 940 Use the following command to create a new MIDI input device for the
1881 senoner 542 desired MIDI input system:
1882    
1883     CREATE MIDI_INPUT_DEVICE <midi-input-driver> [<param-list>]
1884    
1885     Where <midi-input-driver> should be replaced by the desired MIDI
1886 schoenebeck 575 input system as returned by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
1887     (Section 6.3.2) command and <param-list> by an optional list of
1888     driver specific parameters in form of "key1=val1 key2=val2 ...",
1889     where character string values should be encapsulated into apostrophes
1890     ('). Note that there might be drivers which require parameter(s) to
1891     be given with this command. Use the previously described commands in
1892     this chapter to get that information.
1893 senoner 542
1894     Possible Answers:
1895    
1896     "OK[<device-id>]" -
1897 schoenebeck 708
1898 senoner 542 in case the device was successfully created, where <device-id>
1899     is the numerical ID of the new device
1900 schoenebeck 575
1901 schoenebeck 940
1902    
1903 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 34]
1904 schoenebeck 940
1905     Internet-Draft LinuxSampler Control Protocol November 2006
1906    
1907    
1908 schoenebeck 708 "WRN[<device-id>]:<warning-code>:<warning-message>" -
1909 schoenebeck 575
1910 senoner 542 in case the driver was loaded successfully, where <device-id>
1911     is the numerical ID of the new device, but there are noteworthy
1912     issue(s) related, providing an appropriate warning code and
1913     warning message
1914 schoenebeck 708
1915 senoner 542 "ERR:<error-code>:<error-message>" -
1916 schoenebeck 708
1917 senoner 542 in case it failed, providing an appropriate error code and
1918     error message
1919    
1920     Example:
1921    
1922     C: "CREATE MIDI_INPUT_DEVICE ALSA"
1923 schoenebeck 708
1924 senoner 542 S: "OK[0]"
1925    
1926 schoenebeck 940 6.3.6. Destroying a MIDI input device
1927 schoenebeck 708
1928 senoner 542 Use the following command to destroy a created MIDI input device:
1929    
1930     DESTROY MIDI_INPUT_DEVICE <device-id>
1931    
1932 schoenebeck 575 Where <device-id> should be replaced by the device's numerical ID as
1933     returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
1934     MIDI_INPUT_DEVICES" (Section 6.3.8) command.
1935 senoner 542
1936     Possible Answers:
1937    
1938     "OK" -
1939 schoenebeck 708
1940 senoner 542 in case the device was successfully destroyed
1941 schoenebeck 708
1942 senoner 542 "WRN:<warning-code>:<warning-message>" -
1943 schoenebeck 708
1944 senoner 542 in case the device was destroyed, but there are noteworthy
1945     issue(s) related, providing an appropriate warning code and
1946     warning message
1947 schoenebeck 708
1948 senoner 542 "ERR:<error-code>:<error-message>" -
1949 schoenebeck 708
1950 senoner 542 in case it failed, providing an appropriate error code and
1951     error message
1952    
1953     Example:
1954    
1955 schoenebeck 940
1956    
1957    
1958    
1959 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 35]
1960 schoenebeck 940
1961     Internet-Draft LinuxSampler Control Protocol November 2006
1962    
1963    
1964 senoner 542 C: "DESTROY MIDI_INPUT_DEVICE 0"
1965 schoenebeck 708
1966 senoner 542 S: "OK"
1967    
1968 schoenebeck 940 6.3.7. Getting all created MIDI input device count
1969 schoenebeck 708
1970 senoner 542 Use the following command to count all created MIDI input devices:
1971    
1972     GET MIDI_INPUT_DEVICES
1973    
1974     Possible Answers:
1975    
1976     LinuxSampler will answer by sending the current number of all MIDI
1977     input devices.
1978    
1979     Example:
1980    
1981     C: "GET MIDI_INPUT_DEVICES"
1982 schoenebeck 708
1983 senoner 542 S: "3"
1984    
1985 schoenebeck 940 6.3.8. Getting all created MIDI input device list
1986 schoenebeck 708
1987 senoner 542 Use the following command to list all created MIDI input devices:
1988    
1989     LIST MIDI_INPUT_DEVICES
1990    
1991     Possible Answers:
1992    
1993     LinuxSampler will answer by sending a comma separated list with
1994     the numerical Ids of all created MIDI input devices.
1995    
1996     Examples:
1997    
1998     C: "LIST MIDI_INPUT_DEVICES"
1999 schoenebeck 708
2000 senoner 542 S: "0,1,2"
2001    
2002     C: "LIST MIDI_INPUT_DEVICES"
2003 schoenebeck 708
2004 senoner 542 S: "1,3"
2005    
2006 schoenebeck 940 6.3.9. Getting current settings of a MIDI input device
2007 schoenebeck 708
2008 senoner 542 Use the following command to get current settings of a specific,
2009     created MIDI input device:
2010    
2011 schoenebeck 940
2012    
2013    
2014    
2015 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 36]
2016 schoenebeck 940
2017     Internet-Draft LinuxSampler Control Protocol November 2006
2018    
2019    
2020 senoner 542 GET MIDI_INPUT_DEVICE INFO <device-id>
2021    
2022 schoenebeck 575 Where <device-id> is the numerical ID of the MIDI input device as
2023     returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
2024     MIDI_INPUT_DEVICES" (Section 6.3.8) command.
2025 senoner 542
2026     Possible Answers:
2027    
2028     LinuxSampler will answer by sending a <CRLF> separated list. Each
2029     answer line begins with the information category name followed by
2030     a colon and then a space character <SP> and finally the info
2031     character string to that info category. As some parameters might
2032     allow multiple values, character strings are encapsulated into
2033     apostrophes ('). At the moment the following information
2034     categories are defined (independent of driver):
2035    
2036 schoenebeck 575
2037    
2038 schoenebeck 708 DRIVER -
2039 schoenebeck 575
2040 schoenebeck 708 identifier of the used MIDI input driver, as e.g. returned
2041 schoenebeck 575 by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2)
2042 senoner 542 command
2043 schoenebeck 708
2044 senoner 542 ACTIVE -
2045 schoenebeck 708
2046 senoner 542 either true or false, if false then the MIDI device is
2047     inactive and doesn't listen to any incoming MIDI events and
2048     thus doesn't forward them to connected sampler channels
2049    
2050     The mentioned fields above don't have to be in particular order. The
2051     fields above are only those fields which are returned by all MIDI
2052     input devices. Every MIDI input driver might have its own,
2053     additional driver specific parameters (see "GET MIDI_INPUT_DRIVER
2054 schoenebeck 575 INFO" (Section 6.3.3) command) which are also returned by this
2055 senoner 542 command.
2056    
2057     Example:
2058    
2059     C: "GET MIDI_INPUT_DEVICE INFO 0"
2060 schoenebeck 708
2061 senoner 542 S: "DRIVER: ALSA"
2062 schoenebeck 708
2063 senoner 542 "ACTIVE: true"
2064 schoenebeck 708
2065 senoner 542 "."
2066    
2067 schoenebeck 708
2068 senoner 542
2069 schoenebeck 940
2070    
2071 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 37]
2072 schoenebeck 940
2073     Internet-Draft LinuxSampler Control Protocol November 2006
2074    
2075    
2076     6.3.10. Changing settings of MIDI input devices
2077    
2078 senoner 542 Use the following command to alter a specific setting of a created
2079     MIDI input device:
2080    
2081     SET MIDI_INPUT_DEVICE_PARAMETER <device-id> <key>=<value>
2082    
2083     Where <device-id> should be replaced by the numerical ID of the MIDI
2084 schoenebeck 708 input device as returned by the "CREATE MIDI_INPUT_DEVICE"
2085     (Section 6.3.5) or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command,
2086     <key> by the name of the parameter to change and <value> by the new
2087     value for this parameter.
2088 senoner 542
2089     Possible Answers:
2090    
2091     "OK" -
2092 schoenebeck 708
2093 senoner 542 in case setting was successfully changed
2094 schoenebeck 708
2095 senoner 542 "WRN:<warning-code>:<warning-message>" -
2096 schoenebeck 708
2097 senoner 542 in case setting was changed successfully, but there are
2098     noteworthy issue(s) related, providing an appropriate warning
2099     code and warning message
2100 schoenebeck 708
2101 senoner 542 "ERR:<error-code>:<error-message>" -
2102 schoenebeck 708
2103 senoner 542 in case it failed, providing an appropriate error code and
2104     error message
2105    
2106     Example:
2107    
2108     C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"
2109 schoenebeck 708
2110 senoner 542 S: "OK"
2111    
2112 schoenebeck 940 6.3.11. Getting information about a MIDI port
2113 schoenebeck 708
2114 senoner 542 Use the following command to get information about a MIDI port:
2115    
2116     GET MIDI_INPUT_PORT INFO <device-id> <midi-port>
2117    
2118 schoenebeck 575 Where <device-id> is the numerical ID of the MIDI input device as
2119     returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
2120     MIDI_INPUT_DEVICES" (Section 6.3.8) command and <midi-port> the MIDI
2121     input port number.
2122 senoner 542
2123     Possible Answers:
2124    
2125 schoenebeck 940
2126    
2127 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 38]
2128 schoenebeck 940
2129     Internet-Draft LinuxSampler Control Protocol November 2006
2130    
2131    
2132 senoner 542 LinuxSampler will answer by sending a <CRLF> separated list. Each
2133     answer line begins with the information category name followed by
2134     a colon and then a space character <SP> and finally the info
2135     character string to that info category. At the moment the
2136     following information categories are defined:
2137 schoenebeck 708
2138 senoner 542 NAME -
2139 schoenebeck 708
2140 senoner 542 arbitrary character string naming the port
2141    
2142     The field above is only the one which is returned by all MIDI ports
2143     regardless of the MIDI driver and port. Every MIDI port might have
2144     its own, additional driver and port specific parameters.
2145    
2146     Example:
2147    
2148     C: "GET MIDI_INPUT_PORT INFO 0 0"
2149 schoenebeck 708
2150 senoner 542 S: "NAME: 'Masterkeyboard'"
2151 schoenebeck 708
2152 senoner 542 "ALSA_SEQ_BINDINGS: '64:0'"
2153 schoenebeck 708
2154 senoner 542 "."
2155    
2156 schoenebeck 940 6.3.12. Getting information about specific MIDI port parameter
2157 schoenebeck 708
2158 senoner 542 Use the following command to get detailed information about specific
2159     MIDI port parameter:
2160    
2161     GET MIDI_INPUT_PORT_PARAMETER INFO <dev-id> <port> <param>
2162    
2163     Where <dev-id> is the numerical ID of the MIDI input device as
2164 schoenebeck 575 returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
2165     MIDI_INPUT_DEVICES" (Section 6.3.8) command, <port> the MIDI port
2166     number and <param> a specific port parameter name for which
2167     information should be obtained (as returned by the "GET
2168     MIDI_INPUT_PORT INFO" (Section 6.3.11) command).
2169    
2170 senoner 542 Possible Answers:
2171    
2172     LinuxSampler will answer by sending a <CRLF> separated list. Each
2173     answer line begins with the information category name followed by
2174     a colon and then a space character <SP> and finally the info
2175     character string to that info category. There is information
2176     which is always returned, independently of the given channel
2177     parameter and there is optional information which are only shown
2178     dependently to the given MIDI port. At the moment the following
2179     information categories are defined:
2180 schoenebeck 708
2181 schoenebeck 940
2182    
2183 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 39]
2184 schoenebeck 940
2185     Internet-Draft LinuxSampler Control Protocol November 2006
2186    
2187    
2188 senoner 542 TYPE -
2189 schoenebeck 708
2190 senoner 542 either "BOOL" for boolean value(s) or "INT" for integer
2191     value(s) or "FLOAT" for dotted number(s) or "STRING" for
2192     character string(s) (always returned)
2193 schoenebeck 708
2194 senoner 542 DESCRIPTION -
2195 schoenebeck 708
2196 senoner 542 arbitrary text describing the purpose of the parameter (always
2197     returned)
2198 schoenebeck 708
2199 senoner 542 FIX -
2200 schoenebeck 708
2201 senoner 542 either true or false, if true then this parameter is read only,
2202     thus cannot be altered (always returned)
2203 schoenebeck 708
2204 senoner 542 MULTIPLICITY -
2205 schoenebeck 708
2206 senoner 542 either true or false, defines if this parameter allows only one
2207     value or a list of values, where true means multiple values and
2208     false only a single value allowed (always returned)
2209 schoenebeck 708
2210 senoner 542 RANGE_MIN -
2211 schoenebeck 708
2212 senoner 542 defines lower limit of the allowed value range for this
2213     parameter, can be an integer value as well as a dotted number,
2214     this parameter is usually used in conjunction with 'RANGE_MAX'
2215     but may also appear without (optionally returned, dependent to
2216     driver and port parameter)
2217 schoenebeck 708
2218 senoner 542 RANGE_MAX -
2219 schoenebeck 708
2220 senoner 542 defines upper limit of the allowed value range for this
2221     parameter, can be an integer value as well as a dotted number,
2222     this parameter is usually used in conjunction with 'RANGE_MIN'
2223     but may also appear without (optionally returned, dependent to
2224     driver and port parameter)
2225 schoenebeck 708
2226 senoner 542 POSSIBILITIES -
2227 schoenebeck 708
2228 senoner 542 comma separated list of possible values for this parameter,
2229     character strings are encapsulated into apostrophes (optionally
2230     returned, dependent to device and port parameter)
2231    
2232     The mentioned fields above don't have to be in particular order.
2233    
2234     Example:
2235    
2236 schoenebeck 940
2237    
2238    
2239 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 40]
2240 schoenebeck 940
2241     Internet-Draft LinuxSampler Control Protocol November 2006
2242    
2243    
2244 schoenebeck 708 C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"
2245 schoenebeck 575
2246 schoenebeck 708 S: "DESCRIPTION: bindings to other ALSA sequencer clients"
2247 schoenebeck 575
2248 schoenebeck 708 "TYPE: STRING"
2249 schoenebeck 575
2250 schoenebeck 708 "FIX: false"
2251 schoenebeck 575
2252 schoenebeck 708 "MULTIPLICITY: true"
2253 schoenebeck 575
2254 senoner 542 "POSSIBILITIES: '64:0','68:0','68:1'"
2255 schoenebeck 708
2256 senoner 542 "."
2257    
2258 schoenebeck 940 6.3.13. Changing settings of MIDI input ports
2259 schoenebeck 708
2260 senoner 542 Use the following command to alter a specific setting of a MIDI input
2261     port:
2262    
2263     SET MIDI_INPUT_PORT_PARAMETER <device-id> <port> <key>=<value>
2264    
2265     Where <device-id> should be replaced by the numerical ID of the MIDI
2266 schoenebeck 575 device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5)
2267     or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command, <port> by the
2268     MIDI port number, <key> by the name of the parameter to change and
2269     <value> by the new value for this parameter.
2270 senoner 542
2271     Possible Answers:
2272    
2273     "OK" -
2274 schoenebeck 708
2275 senoner 542 in case setting was successfully changed
2276 schoenebeck 708
2277 senoner 542 "WRN:<warning-code>:<warning-message>" -
2278 schoenebeck 708
2279 senoner 542 in case setting was changed successfully, but there are
2280     noteworthy issue(s) related, providing an appropriate warning
2281     code and warning message
2282 schoenebeck 708
2283 senoner 542 "ERR:<error-code>:<error-message>" -
2284 schoenebeck 708
2285 senoner 542 in case it failed, providing an appropriate error code and
2286     error message
2287    
2288     Example:
2289    
2290    
2291    
2292 schoenebeck 708
2293 senoner 542
2294 schoenebeck 940
2295 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 41]
2296 schoenebeck 940
2297     Internet-Draft LinuxSampler Control Protocol November 2006
2298    
2299    
2300    
2301    
2302     6.4. Configuring sampler channels
2303    
2304 senoner 542 The following commands describe how to add and remove sampler
2305 schoenebeck 575 channels, associate a sampler channel with a sampler engine, load
2306     instruments and connect sampler channels to MIDI and audio devices.
2307 senoner 542
2308 schoenebeck 940 6.4.1. Loading an instrument
2309 senoner 542
2310     An instrument file can be loaded and assigned to a sampler channel by
2311     one of the following commands:
2312    
2313 schoenebeck 708 LOAD INSTRUMENT [NON_MODAL] '<filename>' <instr-index> <sampler-
2314     channel>
2315 schoenebeck 575
2316 senoner 542 Where <filename> is the name of the instrument file on the
2317     LinuxSampler instance's host system, <instr-index> the index of the
2318     instrument in the instrument file and <sampler-channel> is the number
2319     of the sampler channel the instrument should be assigned to. Each
2320     sampler channel can only have one instrument.
2321    
2322     The difference between regular and NON_MODAL versions of the command
2323     is that the regular command returns OK only after the instrument has
2324     been fully loaded and the channel is ready to be used while NON_MODAL
2325     version returns immediately and a background process is launched to
2326 schoenebeck 708 load the instrument on the channel. The GET CHANNEL INFO
2327     (Section 6.4.10) command can be used to obtain loading progress from
2328 senoner 542 INSTRUMENT_STATUS field. LOAD command will perform sanity checks
2329     such as making sure that the file could be read and it is of a proper
2330     format and SHOULD return ERR and SHOULD not launch the background
2331     process should any errors be detected at that point.
2332    
2333     Possible Answers:
2334    
2335     "OK" -
2336 schoenebeck 708
2337 senoner 542 in case the instrument was successfully loaded
2338 schoenebeck 708
2339 senoner 542 "WRN:<warning-code>:<warning-message>" -
2340 schoenebeck 708
2341 senoner 542 in case the instrument was loaded successfully, but there are
2342     noteworthy issue(s) related (e.g. Engine doesn't support one
2343     or more patch parameters provided by the loaded instrument
2344     file), providing an appropriate warning code and warning
2345     message
2346 schoenebeck 708
2347 schoenebeck 940
2348    
2349    
2350    
2351 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 42]
2352 schoenebeck 940
2353     Internet-Draft LinuxSampler Control Protocol November 2006
2354    
2355    
2356 senoner 542 "ERR:<error-code>:<error-message>" -
2357 schoenebeck 708
2358 senoner 542 in case it failed, providing an appropriate error code and
2359     error message
2360    
2361     Example:
2362    
2363    
2364    
2365 schoenebeck 940 6.4.2. Loading a sampler engine
2366 schoenebeck 708
2367 schoenebeck 575 A sampler engine type can be associated to a specific sampler channel
2368     by the following command:
2369 senoner 542
2370     LOAD ENGINE <engine-name> <sampler-channel>
2371    
2372     Where <engine-name> is an engine name as obtained by the "LIST
2373 schoenebeck 575 AVAILABLE_ENGINES" (Section 6.4.8) command and <sampler-channel> the
2374     sampler channel as returned by the "ADD CHANNEL" (Section 6.4.5) or
2375     "LIST CHANNELS" (Section 6.4.4) command where the engine type should
2376     be assigned to. This command should be issued after adding a new
2377     sampler channel and before any other control commands on the new
2378     sampler channel. It can also be used to change the engine type of a
2379     sampler channel. This command has (currently) no way to define or
2380     force if a new engine instance should be created and assigned to the
2381     given sampler channel or if an already existing instance of that
2382     engine type, shared with other sampler channels, should be used.
2383    
2384 senoner 542 Possible Answers:
2385    
2386     "OK" -
2387 schoenebeck 708
2388 senoner 542 in case the engine was successfully deployed
2389 schoenebeck 708
2390 senoner 542 "WRN:<warning-code>:<warning-message>" -
2391 schoenebeck 708
2392 senoner 542 in case the engine was deployed successfully, but there are
2393     noteworthy issue(s) related, providing an appropriate warning
2394     code and warning message
2395 schoenebeck 708
2396 senoner 542 "ERR:<error-code>:<error-message>" -
2397 schoenebeck 708
2398 senoner 542 in case it failed, providing an appropriate error code and
2399     error message
2400    
2401     Example:
2402    
2403    
2404    
2405 schoenebeck 708
2406 senoner 542
2407 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 43]
2408 schoenebeck 940
2409     Internet-Draft LinuxSampler Control Protocol November 2006
2410    
2411    
2412    
2413    
2414     6.4.3. Getting all created sampler channel count
2415    
2416 senoner 542 The number of sampler channels can change on runtime. To get the
2417     current amount of sampler channels, the front-end can send the
2418     following command:
2419    
2420     GET CHANNELS
2421    
2422     Possible Answers:
2423    
2424     LinuxSampler will answer by returning the current number of
2425     sampler channels.
2426    
2427     Example:
2428    
2429     C: "GET CHANNELS"
2430 schoenebeck 708
2431 senoner 542 S: "12"
2432    
2433 schoenebeck 940 6.4.4. Getting all created sampler channel list
2434 schoenebeck 708
2435 senoner 542 The number of sampler channels can change on runtime. To get the
2436     current list of sampler channels, the front-end can send the
2437 schoenebeck 708 following command:
2438    
2439 senoner 542 LIST CHANNELS
2440    
2441     Possible Answers:
2442    
2443     LinuxSampler will answer by returning a comma separated list with
2444     all sampler channels numerical IDs.
2445    
2446     Example:
2447    
2448     C: "LIST CHANNELS"
2449 schoenebeck 708
2450 senoner 542 S: "0,1,2,3,4,5,6,9,10,11,15,20"
2451    
2452 schoenebeck 940 6.4.5. Adding a new sampler channel
2453 schoenebeck 708
2454 senoner 542 A new sampler channel can be added to the end of the sampler channel
2455     list by sending the following command:
2456    
2457     ADD CHANNEL
2458    
2459     This will increment the sampler channel count by one and the new
2460 schoenebeck 940
2461    
2462    
2463 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 44]
2464 schoenebeck 940
2465     Internet-Draft LinuxSampler Control Protocol November 2006
2466    
2467    
2468 senoner 542 sampler channel will be appended to the end of the sampler channel
2469     list. The front-end should send the respective, related commands
2470 schoenebeck 708 right after to e.g. load an engine, load an instrument and setting
2471 senoner 542 input, output method and eventually other commands to initialize the
2472     new channel. The front-end should use the sampler channel returned
2473     by the answer of this command to perform the previously recommended
2474 schoenebeck 708 commands, to avoid race conditions e.g. with other front-ends that
2475 senoner 542 might also have sent an "ADD CHANNEL" command.
2476    
2477     Possible Answers:
2478    
2479     "OK[<sampler-channel>]" -
2480 schoenebeck 708
2481     in case a new sampler channel could be added, where <sampler-
2482     channel> reflects the channel number of the new created sampler
2483     channel which should be used to set up the sampler channel by
2484     sending subsequent initialization commands
2485    
2486 senoner 542 "WRN:<warning-code>:<warning-message>" -
2487 schoenebeck 708
2488 senoner 542 in case a new channel was added successfully, but there are
2489     noteworthy issue(s) related, providing an appropriate warning
2490     code and warning message
2491 schoenebeck 708
2492 senoner 542 "ERR:<error-code>:<error-message>" -
2493 schoenebeck 708
2494 senoner 542 in case it failed, providing an appropriate error code and
2495     error message
2496    
2497     Example:
2498    
2499    
2500    
2501 schoenebeck 940 6.4.6. Removing a sampler channel
2502 senoner 542
2503     A sampler channel can be removed by sending the following command:
2504    
2505     REMOVE CHANNEL <sampler-channel>
2506    
2507 schoenebeck 561 Where <sampler-channel> should be replaced by the number of the
2508 schoenebeck 575 sampler channel as given by the "ADD CHANNEL" (Section 6.4.5) or
2509     "LIST CHANNELS" (Section 6.4.4) command. The channel numbers of all
2510 schoenebeck 561 subsequent sampler channels remain the same.
2511 senoner 542
2512     Possible Answers:
2513    
2514 schoenebeck 940
2515    
2516    
2517    
2518    
2519 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 45]
2520 schoenebeck 940
2521     Internet-Draft LinuxSampler Control Protocol November 2006
2522    
2523    
2524 senoner 542 "OK" -
2525 schoenebeck 708
2526 senoner 542 in case the given sampler channel could be removed
2527 schoenebeck 708
2528 senoner 542 "WRN:<warning-code>:<warning-message>" -
2529 schoenebeck 708
2530 senoner 542 in case the given channel was removed, but there are noteworthy
2531     issue(s) related, providing an appropriate warning code and
2532     warning message
2533 schoenebeck 708
2534 senoner 542 "ERR:<error-code>:<error-message>" -
2535 schoenebeck 708
2536 senoner 542 in case it failed, providing an appropriate error code and
2537     error message
2538    
2539     Example:
2540    
2541    
2542    
2543 schoenebeck 940 6.4.7. Getting amount of available engines
2544 schoenebeck 708
2545 senoner 542 The front-end can ask for the number of available engines by sending
2546     the following command:
2547    
2548     GET AVAILABLE_ENGINES
2549    
2550     Possible Answers:
2551    
2552     LinuxSampler will answer by sending the number of available
2553     engines.
2554    
2555     Example:
2556    
2557     C: "GET AVAILABLE_ENGINES"
2558 schoenebeck 708
2559 senoner 542 S: "4"
2560    
2561 schoenebeck 940 6.4.8. Getting all available engines
2562 schoenebeck 708
2563 senoner 542 The front-end can ask for a list of all available engines by sending
2564     the following command:
2565    
2566     LIST AVAILABLE_ENGINES
2567    
2568     Possible Answers:
2569    
2570 schoenebeck 940
2571    
2572    
2573    
2574    
2575 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 46]
2576 schoenebeck 940
2577     Internet-Draft LinuxSampler Control Protocol November 2006
2578    
2579    
2580 schoenebeck 561 LinuxSampler will answer by sending a comma separated list of the
2581     engines' names encapsulated into apostrophes ('). Engine names
2582     can consist of lower and upper cases, digits and underlines ("_"
2583     character).
2584 senoner 542
2585     Example:
2586    
2587     C: "LIST AVAILABLE_ENGINES"
2588 schoenebeck 708
2589 schoenebeck 561 S: "'GigEngine','AkaiEngine','DLSEngine','JoesCustomEngine'"
2590 senoner 542
2591 schoenebeck 940 6.4.9. Getting information about an engine
2592 schoenebeck 708
2593 senoner 542 The front-end can ask for information about a specific engine by
2594     sending the following command:
2595    
2596     GET ENGINE INFO <engine-name>
2597    
2598     Where <engine-name> is an engine name as obtained by the "LIST
2599 schoenebeck 575 AVAILABLE_ENGINES" (Section 6.4.8) command.
2600 senoner 542
2601 schoenebeck 561 Possible Answers:
2602    
2603 senoner 542 LinuxSampler will answer by sending a <CRLF> separated list. Each
2604     answer line begins with the information category name followed by
2605     a colon and then a space character <SP> and finally the info
2606     character string to that info category. At the moment the
2607     following categories are defined:
2608    
2609 schoenebeck 708
2610    
2611 senoner 542 DESCRIPTION -
2612 schoenebeck 708
2613 senoner 542 arbitrary description text about the engine
2614 schoenebeck 708
2615 senoner 542 VERSION -
2616 schoenebeck 708
2617 senoner 542 arbitrary character string regarding the engine's version
2618    
2619     The mentioned fields above don't have to be in particular order.
2620    
2621     Example:
2622    
2623     C: "GET ENGINE INFO JoesCustomEngine"
2624 schoenebeck 708
2625 senoner 542 S: "DESCRIPTION: this is Joe's custom sampler engine"
2626 schoenebeck 708
2627 schoenebeck 940
2628    
2629    
2630    
2631 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 47]
2632 schoenebeck 940
2633     Internet-Draft LinuxSampler Control Protocol November 2006
2634    
2635    
2636 senoner 542 "VERSION: testing-1.0"
2637 schoenebeck 708
2638 senoner 542 "."
2639    
2640 schoenebeck 940 6.4.10. Getting sampler channel information
2641 senoner 542
2642     The front-end can ask for the current settings of a sampler channel
2643     by sending the following command:
2644    
2645     GET CHANNEL INFO <sampler-channel>
2646    
2647     Where <sampler-channel> is the sampler channel number the front-end
2648 schoenebeck 575 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2649     "LIST CHANNELS" (Section 6.4.4) command.
2650 senoner 542
2651     Possible Answers:
2652    
2653     LinuxSampler will answer by sending a <CRLF> separated list. Each
2654     answer line begins with the settings category name followed by a
2655     colon and then a space character <SP> and finally the info
2656     character string to that setting category. At the moment the
2657     following categories are defined:
2658    
2659 schoenebeck 708
2660    
2661 senoner 542 ENGINE_NAME -
2662 schoenebeck 708
2663 schoenebeck 575 name of the engine that is associated with the sampler
2664     channel, "NONE" if there's no engine associated yet for this
2665     sampler channel
2666 schoenebeck 708
2667 senoner 542 AUDIO_OUTPUT_DEVICE -
2668 schoenebeck 708
2669 senoner 542 numerical ID of the audio output device which is currently
2670     connected to this sampler channel to output the audio
2671     signal, "NONE" if there's no device connected to this
2672 schoenebeck 561 sampler channel
2673 schoenebeck 708
2674 senoner 542 AUDIO_OUTPUT_CHANNELS -
2675 schoenebeck 708
2676 senoner 542 number of output channels the sampler channel offers
2677     (dependent to used sampler engine and loaded instrument)
2678 schoenebeck 708
2679 senoner 542 AUDIO_OUTPUT_ROUTING -
2680 schoenebeck 708
2681 senoner 542 comma separated list which reflects to which audio channel
2682     of the selected audio output device each sampler output
2683 schoenebeck 708 channel is routed to, e.g. "0,3" would mean the engine's
2684 schoenebeck 940
2685    
2686    
2687 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 48]
2688 schoenebeck 940
2689     Internet-Draft LinuxSampler Control Protocol November 2006
2690    
2691    
2692 senoner 542 output channel 0 is routed to channel 0 of the audio output
2693     device and the engine's output channel 1 is routed to the
2694     channel 3 of the audio output device
2695 schoenebeck 708
2696 senoner 542 INSTRUMENT_FILE -
2697 schoenebeck 708
2698 senoner 542 the file name of the loaded instrument, "NONE" if there's no
2699     instrument yet loaded for this sampler channel
2700 schoenebeck 708
2701 senoner 542 INSTRUMENT_NR -
2702 schoenebeck 708
2703 senoner 542 the instrument index number of the loaded instrument
2704 schoenebeck 708
2705 senoner 542 INSTRUMENT_NAME -
2706 schoenebeck 708
2707 senoner 542 the instrument name of the loaded instrument
2708 schoenebeck 708
2709 senoner 542 INSTRUMENT_STATUS -
2710 schoenebeck 708
2711 senoner 542 integer values 0 to 100 indicating loading progress
2712     percentage for the instrument. Negative value indicates a
2713 schoenebeck 708 loading exception. Value of 100 indicates that the
2714     instrument is fully loaded.
2715 schoenebeck 575
2716 senoner 542 MIDI_INPUT_DEVICE -
2717 schoenebeck 708
2718 senoner 542 numerical ID of the MIDI input device which is currently
2719     connected to this sampler channel to deliver MIDI input
2720     commands, "NONE" if there's no device connected to this
2721     sampler channel
2722 schoenebeck 708
2723 senoner 542 MIDI_INPUT_PORT -
2724 schoenebeck 708
2725 senoner 542 port number of the MIDI input device
2726 schoenebeck 708
2727 senoner 542 MIDI_INPUT_CHANNEL -
2728 schoenebeck 708
2729 senoner 542 the MIDI input channel number this sampler channel should
2730     listen to or "ALL" to listen on all MIDI channels
2731 schoenebeck 708
2732 senoner 542 VOLUME -
2733 schoenebeck 708
2734 senoner 542 optionally dotted number for the channel volume factor
2735     (where a value < 1.0 means attenuation and a value > 1.0
2736     means amplification)
2737    
2738 schoenebeck 940
2739    
2740    
2741    
2742    
2743 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 49]
2744 schoenebeck 940
2745     Internet-Draft LinuxSampler Control Protocol November 2006
2746    
2747    
2748 schoenebeck 708 MUTE -
2749    
2750     Determines whether the channel is muted, "true" if the
2751     channel is muted, "false" if the channel is not muted, and
2752     "MUTED_BY_SOLO" if the channel is muted because of the
2753     presence of a solo channel and will be unmuted when there
2754     are no solo channels left
2755    
2756     SOLO -
2757    
2758     Determines whether this is a solo channel, "true" if the
2759     channel is a solo channel; "false" otherwise
2760    
2761 senoner 542 The mentioned fields above don't have to be in particular order.
2762    
2763     Example:
2764    
2765     C: "GET CHANNEL INFO 34"
2766 schoenebeck 708
2767 senoner 542 S: "ENGINE_NAME: GigEngine"
2768 schoenebeck 708
2769 senoner 542 "VOLUME: 1.0"
2770 schoenebeck 708
2771 senoner 542 "AUDIO_OUTPUT_DEVICE: 0"
2772 schoenebeck 708
2773 senoner 542 "AUDIO_OUTPUT_CHANNELS: 2"
2774 schoenebeck 708
2775 schoenebeck 561 "AUDIO_OUTPUT_ROUTING: 0,1"
2776 schoenebeck 708
2777 senoner 542 "INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"
2778 schoenebeck 708
2779 senoner 542 "INSTRUMENT_NR: 0"
2780 schoenebeck 708
2781 senoner 542 "INSTRUMENT_NAME: Fazioli Piano"
2782 schoenebeck 708
2783 senoner 542 "INSTRUMENT_STATUS: 100"
2784 schoenebeck 708
2785 senoner 542 "MIDI_INPUT_DEVICE: 0"
2786 schoenebeck 708
2787 senoner 542 "MIDI_INPUT_PORT: 0"
2788 schoenebeck 708
2789 senoner 542 "MIDI_INPUT_CHANNEL: 5"
2790 schoenebeck 708
2791 senoner 542 "."
2792    
2793 schoenebeck 708
2794 senoner 542
2795 schoenebeck 940
2796    
2797    
2798    
2799 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 50]
2800 schoenebeck 940
2801     Internet-Draft LinuxSampler Control Protocol November 2006
2802    
2803    
2804     6.4.11. Current number of active voices
2805    
2806 senoner 542 The front-end can ask for the current number of active voices on a
2807     sampler channel by sending the following command:
2808    
2809     GET CHANNEL VOICE_COUNT <sampler-channel>
2810    
2811     Where <sampler-channel> is the sampler channel number the front-end
2812 schoenebeck 575 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2813     "LIST CHANNELS" (Section 6.4.4) command.
2814 senoner 542
2815     Possible Answers:
2816    
2817     LinuxSampler will answer by returning the number of active voices
2818     on that channel.
2819    
2820     Example:
2821    
2822    
2823    
2824 schoenebeck 940 6.4.12. Current number of active disk streams
2825 schoenebeck 708
2826 senoner 542 The front-end can ask for the current number of active disk streams
2827     on a sampler channel by sending the following command:
2828    
2829     GET CHANNEL STREAM_COUNT <sampler-channel>
2830    
2831     Where <sampler-channel> is the sampler channel number the front-end
2832 schoenebeck 575 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2833     "LIST CHANNELS" (Section 6.4.4) command.
2834 senoner 542
2835     Possible Answers:
2836    
2837     LinuxSampler will answer by returning the number of active disk
2838     streams on that channel in case the engine supports disk
2839     streaming, if the engine doesn't support disk streaming it will
2840     return "NA" for not available.
2841    
2842     Example:
2843    
2844    
2845    
2846 schoenebeck 940 6.4.13. Current fill state of disk stream buffers
2847 schoenebeck 708
2848 senoner 542 The front-end can ask for the current fill state of all disk streams
2849     on a sampler channel by sending the following command:
2850    
2851 schoenebeck 940
2852    
2853    
2854    
2855 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 51]
2856 schoenebeck 940
2857     Internet-Draft LinuxSampler Control Protocol November 2006
2858    
2859    
2860 senoner 542 GET CHANNEL BUFFER_FILL BYTES <sampler-channel>
2861    
2862     to get the fill state in bytes or
2863    
2864     GET CHANNEL BUFFER_FILL PERCENTAGE <sampler-channel>
2865    
2866     to get the fill state in percent, where <sampler-channel> is the
2867 schoenebeck 575 sampler channel number the front-end is interested in as returned by
2868     the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
2869     command.
2870 senoner 542
2871     Possible Answers:
2872    
2873     LinuxSampler will either answer by returning a comma separated
2874     string with the fill state of all disk stream buffers on that
2875     channel or an empty line if there are no active disk streams or
2876     "NA" for *not available* in case the engine which is deployed
2877     doesn't support disk streaming. Each entry in the answer list
2878     will begin with the stream's ID in brackets followed by the
2879     numerical representation of the fill size (either in bytes or
2880     percentage). Note: due to efficiency reasons the fill states in
2881     the response are not in particular order, thus the front-end has
2882     to sort them by itself if necessary.
2883    
2884     Examples:
2885    
2886     C: "GET CHANNEL BUFFER_FILL BYTES 4"
2887 schoenebeck 708
2888 senoner 542 S: "[115]420500,[116]510300,[75]110000,[120]230700"
2889 schoenebeck 708
2890 senoner 542 C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
2891 schoenebeck 708
2892 senoner 542 S: "[115]90%,[116]98%,[75]40%,[120]62%"
2893 schoenebeck 708
2894 senoner 542 C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
2895 schoenebeck 708
2896 senoner 542 S: ""
2897    
2898 schoenebeck 940 6.4.14. Setting audio output device
2899 schoenebeck 708
2900 senoner 542 The front-end can set the audio output device on a specific sampler
2901     channel by sending the following command:
2902    
2903     SET CHANNEL AUDIO_OUTPUT_DEVICE <sampler-channel>
2904     <audio-device-id>
2905    
2906 schoenebeck 575 Where <sampler-channel> is the respective sampler channel number as
2907     returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
2908 schoenebeck 940
2909    
2910    
2911 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 52]
2912 schoenebeck 940
2913     Internet-Draft LinuxSampler Control Protocol November 2006
2914    
2915    
2916 schoenebeck 575 (Section 6.4.4) command and <audio-device-id> is the numerical ID of
2917     the audio output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
2918     (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
2919     command.
2920 senoner 542
2921     Possible Answers:
2922    
2923     "OK" -
2924 schoenebeck 708
2925 senoner 542 on success
2926 schoenebeck 708
2927 senoner 542 "WRN:<warning-code>:<warning-message>" -
2928 schoenebeck 708
2929 senoner 542 if audio output device was set, but there are noteworthy
2930     issue(s) related, providing an appropriate warning code and
2931     warning message
2932 schoenebeck 708
2933 senoner 542 "ERR:<error-code>:<error-message>" -
2934 schoenebeck 708
2935 senoner 542 in case it failed, providing an appropriate error code and
2936     error message
2937    
2938     Examples:
2939    
2940    
2941    
2942 schoenebeck 940 6.4.15. Setting audio output type
2943 senoner 542
2944     DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
2945    
2946     The front-end can alter the audio output type on a specific sampler
2947     channel by sending the following command:
2948    
2949 schoenebeck 708 SET CHANNEL AUDIO_OUTPUT_TYPE <sampler-channel> <audio-output-
2950     type>
2951 senoner 542
2952     Where <audio-output-type> is currently either "ALSA" or "JACK" and
2953     <sampler-channel> is the respective sampler channel number.
2954    
2955     Possible Answers:
2956    
2957     "OK" -
2958 schoenebeck 708
2959 senoner 542 on success
2960 schoenebeck 708
2961 senoner 542 "WRN:<warning-code>:<warning-message>" -
2962 schoenebeck 708
2963 schoenebeck 940
2964    
2965    
2966    
2967 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 53]
2968 schoenebeck 940
2969     Internet-Draft LinuxSampler Control Protocol November 2006
2970    
2971    
2972 senoner 542 if audio output type was set, but there are noteworthy issue(s)
2973     related, providing an appropriate warning code and warning
2974     message
2975 schoenebeck 708
2976 senoner 542 "ERR:<error-code>:<error-message>" -
2977 schoenebeck 708
2978 senoner 542 in case it failed, providing an appropriate error code and
2979     error message
2980    
2981     Examples:
2982    
2983    
2984    
2985 schoenebeck 940 6.4.16. Setting audio output channel
2986 schoenebeck 708
2987 schoenebeck 575 The front-end can alter the audio output channel on a specific
2988     sampler channel by sending the following command:
2989 senoner 542
2990 schoenebeck 575 SET CHANNEL AUDIO_OUTPUT_CHANNEL <sampler-chan> <audio-out>
2991     <audio-in>
2992 senoner 542
2993 schoenebeck 575 Where <sampler-chan> is the sampler channel number as returned by the
2994     "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
2995     command, <audio-out> is the numerical ID of the sampler channel's
2996     audio output channel which should be rerouted and <audio-in> is the
2997     numerical ID of the audio channel of the selected audio output device
2998     where <audio-out> should be routed to.
2999 senoner 542
3000 schoenebeck 575 Possible Answers:
3001 senoner 542
3002 schoenebeck 708 "OK" -
3003 senoner 542
3004 schoenebeck 708 on success
3005 senoner 542
3006 schoenebeck 708 "WRN:<warning-code>:<warning-message>" -
3007 senoner 542
3008     if audio output channel was set, but there are noteworthy
3009     issue(s) related, providing an appropriate warning code and
3010     warning message
3011 schoenebeck 708
3012 senoner 542 "ERR:<error-code>:<error-message>" -
3013 schoenebeck 708
3014 senoner 542 in case it failed, providing an appropriate error code and
3015     error message
3016    
3017     Examples:
3018    
3019    
3020    
3021 schoenebeck 708
3022 senoner 542
3023 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 54]
3024 schoenebeck 940
3025     Internet-Draft LinuxSampler Control Protocol November 2006
3026    
3027    
3028    
3029    
3030     6.4.17. Setting MIDI input device
3031    
3032 senoner 542 The front-end can set the MIDI input device on a specific sampler
3033     channel by sending the following command:
3034    
3035     SET CHANNEL MIDI_INPUT_DEVICE <sampler-channel> <midi-device-id>
3036    
3037 schoenebeck 575 Where <sampler-channel> is the sampler channel number as returned by
3038     the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3039 schoenebeck 940 command and <midi-device-id> is the numerical ID of the MIDI input
3040 schoenebeck 575 device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5)
3041     or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command.
3042 senoner 542
3043     Possible Answers:
3044    
3045     "OK" -
3046 schoenebeck 708
3047 senoner 542 on success
3048 schoenebeck 708
3049 senoner 542 "WRN:<warning-code>:<warning-message>" -
3050 schoenebeck 708
3051 senoner 542 if MIDI input device was set, but there are noteworthy issue(s)
3052     related, providing an appropriate warning code and warning
3053     message
3054 schoenebeck 708
3055 senoner 542 "ERR:<error-code>:<error-message>" -
3056 schoenebeck 708
3057 senoner 542 in case it failed, providing an appropriate error code and
3058     error message
3059    
3060     Examples:
3061    
3062    
3063    
3064 schoenebeck 940 6.4.18. Setting MIDI input type
3065 schoenebeck 708
3066 senoner 542 DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
3067    
3068     The front-end can alter the MIDI input type on a specific sampler
3069     channel by sending the following command:
3070    
3071     SET CHANNEL MIDI_INPUT_TYPE <sampler-channel> <midi-input-type>
3072    
3073 schoenebeck 708 Where <midi-input-type> is currently only "ALSA" and <sampler-
3074     channel> is the respective sampler channel number.
3075 senoner 542
3076 schoenebeck 940
3077    
3078    
3079 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 55]
3080 schoenebeck 940
3081     Internet-Draft LinuxSampler Control Protocol November 2006
3082    
3083    
3084 senoner 542 Possible Answers:
3085    
3086     "OK" -
3087 schoenebeck 708
3088 senoner 542 on success
3089 schoenebeck 708
3090 senoner 542 "WRN:<warning-code>:<warning-message>" -
3091 schoenebeck 708
3092 senoner 542 if MIDI input type was set, but there are noteworthy issue(s)
3093     related, providing an appropriate warning code and warning
3094     message
3095 schoenebeck 708
3096 senoner 542 "ERR:<error-code>:<error-message>" -
3097 schoenebeck 708
3098 senoner 542 in case it failed, providing an appropriate error code and
3099     error message
3100    
3101     Examples:
3102    
3103    
3104    
3105 schoenebeck 940 6.4.19. Setting MIDI input port
3106 schoenebeck 708
3107 senoner 542 The front-end can alter the MIDI input port on a specific sampler
3108     channel by sending the following command:
3109    
3110     SET CHANNEL MIDI_INPUT_PORT <sampler-channel> <midi-input-port>
3111    
3112     Where <midi-input-port> is a MIDI input port number of the MIDI input
3113     device connected to the sampler channel given by <sampler-channel>.
3114    
3115     Possible Answers:
3116    
3117     "OK" -
3118 schoenebeck 708
3119 senoner 542 on success
3120 schoenebeck 708
3121 senoner 542 "WRN:<warning-code>:<warning-message>" -
3122 schoenebeck 708
3123 senoner 542 if MIDI input port was set, but there are noteworthy issue(s)
3124     related, providing an appropriate warning code and warning
3125     message
3126 schoenebeck 708
3127 senoner 542 "ERR:<error-code>:<error-message>" -
3128 schoenebeck 708
3129 senoner 542 in case it failed, providing an appropriate error code and
3130 schoenebeck 561 error message
3131 senoner 542
3132 schoenebeck 940
3133    
3134    
3135 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 56]
3136 schoenebeck 940
3137     Internet-Draft LinuxSampler Control Protocol November 2006
3138    
3139    
3140 senoner 542 Examples:
3141    
3142    
3143    
3144 schoenebeck 940 6.4.20. Setting MIDI input channel
3145 senoner 542
3146     The front-end can alter the MIDI channel a sampler channel should
3147     listen to by sending the following command:
3148    
3149     SET CHANNEL MIDI_INPUT_CHANNEL <sampler-channel> <midi-input-chan>
3150    
3151     Where <midi-input-chan> is the number of the new MIDI input channel
3152     where <sampler-channel> should listen to or "ALL" to listen on all 16
3153     MIDI channels.
3154    
3155     Possible Answers:
3156    
3157     "OK" -
3158 schoenebeck 708
3159 senoner 542 on success
3160 schoenebeck 708
3161 senoner 542 "WRN:<warning-code>:<warning-message>" -
3162 schoenebeck 708
3163 senoner 542 if MIDI input channel was set, but there are noteworthy
3164     issue(s) related, providing an appropriate warning code and
3165     warning message
3166 schoenebeck 708
3167 senoner 542 "ERR:<error-code>:<error-message>" -
3168 schoenebeck 708
3169 senoner 542 in case it failed, providing an appropriate error code and
3170     error message
3171    
3172     Examples:
3173    
3174    
3175    
3176 schoenebeck 940 6.4.21. Setting channel volume
3177 schoenebeck 708
3178 senoner 542 The front-end can alter the volume of a sampler channel by sending
3179     the following command:
3180    
3181     SET CHANNEL VOLUME <sampler-channel> <volume>
3182    
3183     Where <volume> is an optionally dotted positive number (a value
3184     smaller than 1.0 means attenuation, whereas a value greater than 1.0
3185     means amplification) and <sampler-channel> defines the sampler
3186     channel where this volume factor should be set.
3187    
3188 schoenebeck 940
3189    
3190    
3191 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 57]
3192 schoenebeck 940
3193     Internet-Draft LinuxSampler Control Protocol November 2006
3194    
3195    
3196 senoner 542 Possible Answers:
3197    
3198     "OK" -
3199 schoenebeck 708
3200 senoner 542 on success
3201 schoenebeck 708
3202 senoner 542 "WRN:<warning-code>:<warning-message>" -
3203 schoenebeck 708
3204 senoner 542 if channel volume was set, but there are noteworthy issue(s)
3205     related, providing an appropriate warning code and warning
3206 schoenebeck 708 message
3207 schoenebeck 575
3208 schoenebeck 708 "ERR:<error-code>:<error-message>" -
3209 schoenebeck 575
3210 schoenebeck 708 in case it failed, providing an appropriate error code and
3211     error message
3212 schoenebeck 575
3213 schoenebeck 708 Examples:
3214    
3215    
3216    
3217 schoenebeck 940 6.4.22. Muting a sampler channel
3218 schoenebeck 708
3219     The front-end can mute/unmute a specific sampler channel by sending
3220     the following command:
3221    
3222     SET CHANNEL MUTE <sampler-channel> <mute>
3223    
3224     Where <sampler-channel> is the respective sampler channel number as
3225     returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3226     (Section 6.4.4) command and <mute> should be replaced either by "1"
3227     to mute the channel or "0" to unmute the channel.
3228    
3229     Possible Answers:
3230    
3231     "OK" -
3232    
3233     on success
3234    
3235     "WRN:<warning-code>:<warning-message>" -
3236    
3237     if the channel was muted/unmuted, but there are noteworthy
3238     issue(s) related, providing an appropriate warning code and
3239     warning message
3240    
3241 senoner 542 "ERR:<error-code>:<error-message>" -
3242 schoenebeck 708
3243 schoenebeck 940
3244    
3245    
3246    
3247 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 58]
3248 schoenebeck 940
3249     Internet-Draft LinuxSampler Control Protocol November 2006
3250    
3251    
3252 senoner 542 in case it failed, providing an appropriate error code and
3253     error message
3254    
3255     Examples:
3256    
3257    
3258    
3259 schoenebeck 940 6.4.23. Soloing a sampler channel
3260 senoner 542
3261 schoenebeck 708 The front-end can solo/unsolo a specific sampler channel by sending
3262     the following command:
3263    
3264     SET CHANNEL SOLO <sampler-channel> <solo>
3265    
3266     Where <sampler-channel> is the respective sampler channel number as
3267     returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3268     (Section 6.4.4) command and <solo> should be replaced either by "1"
3269     to solo the channel or "0" to unsolo the channel.
3270    
3271     Possible Answers:
3272    
3273     "OK" -
3274    
3275     on success
3276    
3277     "WRN:<warning-code>:<warning-message>" -
3278    
3279     if the channel was soloed/unsoloed, but there are noteworthy
3280     issue(s) related, providing an appropriate warning code and
3281     warning message
3282    
3283     "ERR:<error-code>:<error-message>" -
3284    
3285     in case it failed, providing an appropriate error code and
3286     error message
3287    
3288     Examples:
3289    
3290    
3291    
3292 schoenebeck 940 6.4.24. Resetting a sampler channel
3293 schoenebeck 708
3294 senoner 542 The front-end can reset a particular sampler channel by sending the
3295     following command:
3296    
3297     RESET CHANNEL <sampler-channel>
3298    
3299     Where <sampler-channel> defines the sampler channel to be reset.
3300 schoenebeck 940
3301    
3302    
3303 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 59]
3304 schoenebeck 940
3305     Internet-Draft LinuxSampler Control Protocol November 2006
3306    
3307    
3308 senoner 542 This will cause the engine on that sampler channel, its voices and
3309     eventually disk streams and all control and status variables to be
3310     reset.
3311    
3312     Possible Answers:
3313    
3314     "OK" -
3315 schoenebeck 708
3316 senoner 542 on success
3317 schoenebeck 708
3318 senoner 542 "WRN:<warning-code>:<warning-message>" -
3319 schoenebeck 708
3320 senoner 542 if channel was reset, but there are noteworthy issue(s)
3321     related, providing an appropriate warning code and warning
3322     message
3323 schoenebeck 708
3324 senoner 542 "ERR:<error-code>:<error-message>" -
3325 schoenebeck 708
3326 senoner 542 in case it failed, providing an appropriate error code and
3327     error message
3328    
3329     Examples:
3330    
3331    
3332    
3333 schoenebeck 940 6.5. Controlling connection
3334 schoenebeck 708
3335 schoenebeck 575 The following commands are used to control the connection to
3336     LinuxSampler.
3337 senoner 542
3338 schoenebeck 940 6.5.1. Register front-end for receiving event messages
3339 senoner 542
3340 schoenebeck 575 The front-end can register itself to the LinuxSampler application to
3341     be informed about noteworthy events by sending this command:
3342 senoner 542
3343     SUBSCRIBE <event-id>
3344    
3345     where <event-id> will be replaced by the respective event that client
3346     wants to subscribe to.
3347    
3348     Possible Answers:
3349    
3350     "OK" -
3351 schoenebeck 708
3352 senoner 542 on success
3353 schoenebeck 708
3354 schoenebeck 940
3355    
3356    
3357    
3358    
3359 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 60]
3360 schoenebeck 940
3361     Internet-Draft LinuxSampler Control Protocol November 2006
3362    
3363    
3364 senoner 542 "WRN:<warning-code>:<warning-message>" -
3365 schoenebeck 708
3366 senoner 542 if registration succeeded, but there are noteworthy issue(s)
3367     related, providing an appropriate warning code and warning
3368     message
3369 schoenebeck 708
3370 senoner 542 "ERR:<error-code>:<error-message>" -
3371 schoenebeck 708
3372 senoner 542 in case it failed, providing an appropriate error code and
3373     error message
3374    
3375     Examples:
3376    
3377    
3378    
3379 schoenebeck 940 6.5.2. Unregister front-end for not receiving event messages
3380 schoenebeck 708
3381 senoner 542 The front-end can unregister itself if it doesn't want to receive
3382     event messages anymore by sending the following command:
3383    
3384     UNSUBSCRIBE <event-id>
3385    
3386     Where <event-id> will be replaced by the respective event that client
3387     doesn't want to receive anymore.
3388    
3389     Possible Answers:
3390    
3391     "OK" -
3392 schoenebeck 708
3393 senoner 542 on success
3394 schoenebeck 708
3395 senoner 542 "WRN:<warning-code>:<warning-message>" -
3396 schoenebeck 708
3397 senoner 542 if unregistration succeeded, but there are noteworthy issue(s)
3398     related, providing an appropriate warning code and warning
3399     message
3400 schoenebeck 708
3401 senoner 542 "ERR:<error-code>:<error-message>" -
3402 schoenebeck 708
3403 senoner 542 in case it failed, providing an appropriate error code and
3404     error message
3405    
3406     Examples:
3407    
3408    
3409    
3410    
3411 schoenebeck 575
3412 schoenebeck 940
3413    
3414    
3415 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 61]
3416 schoenebeck 940
3417     Internet-Draft LinuxSampler Control Protocol November 2006
3418    
3419    
3420     6.5.3. Enable or disable echo of commands
3421    
3422 senoner 542 To enable or disable back sending of commands to the client the
3423     following command can be used:
3424    
3425     SET ECHO <value>
3426    
3427     Where <value> should be replaced either by "1" to enable echo mode or
3428     "0" to disable echo mode. When echo mode is enabled, all commands
3429     send to LinuxSampler will be immediately send back and after this
3430     echo the actual response to the command will be returned. Echo mode
3431     will only be altered for the client connection that issued the "SET
3432     ECHO" command, not globally for all client connections.
3433    
3434     Possible Answers:
3435    
3436     "OK" -
3437 schoenebeck 708
3438 senoner 542 usually
3439 schoenebeck 708
3440 senoner 542 "ERR:<error-code>:<error-message>" -
3441    
3442 schoenebeck 708 on syntax error, e.g. non boolean value
3443    
3444 senoner 542 Examples:
3445    
3446    
3447    
3448 schoenebeck 940 6.5.4. Close client connection
3449 schoenebeck 708
3450 senoner 542 The client can close its network connection to LinuxSampler by
3451     sending the following command:
3452    
3453     QUIT
3454    
3455     This is probably more interesting for manual telnet connections to
3456     LinuxSampler than really useful for a front-end implementation.
3457    
3458 schoenebeck 940 6.6. Global commands
3459 senoner 542
3460 schoenebeck 575 The following commands have global impact on the sampler.
3461 senoner 542
3462 schoenebeck 940 6.6.1. Current number of active voices
3463 senoner 542
3464 schoenebeck 940 The front-end can ask for the current number of active voices on the
3465     sampler by sending the following command:
3466    
3467    
3468    
3469    
3470    
3471 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 62]
3472 schoenebeck 940
3473     Internet-Draft LinuxSampler Control Protocol November 2006
3474    
3475    
3476     GET TOTAL_VOICE_COUNT
3477    
3478     Possible Answers:
3479    
3480     LinuxSampler will answer by returning the number of all active
3481     voices on the sampler.
3482    
3483     6.6.2. Maximum amount of active voices
3484    
3485     The front-end can ask for the maximum number of active voices by
3486     sending the following command:
3487    
3488     GET TOTAL_VOICE_COUNT_MAX
3489    
3490     Possible Answers:
3491    
3492     LinuxSampler will answer by returning the maximum number of active
3493     voices.
3494    
3495     6.6.3. Reset sampler
3496    
3497 schoenebeck 575 The front-end can reset the whole sampler by sending the following
3498     command:
3499 senoner 542
3500 schoenebeck 575 RESET
3501    
3502     Possible Answers:
3503    
3504 schoenebeck 708 "OK" -
3505 schoenebeck 575
3506 schoenebeck 708 always
3507 schoenebeck 575
3508 schoenebeck 708 Examples:
3509 schoenebeck 575
3510 senoner 542
3511    
3512 schoenebeck 940 6.6.4. General sampler informations
3513 senoner 542
3514 schoenebeck 708 The client can ask for general informations about the LinuxSampler
3515 schoenebeck 575 instance by sending the following command:
3516    
3517     GET SERVER INFO
3518    
3519 senoner 542 Possible Answers:
3520    
3521 schoenebeck 575 LinuxSampler will answer by sending a <CRLF> separated list. Each
3522     answer line begins with the information category name followed by
3523     a colon and then a space character <SP> and finally the info
3524 schoenebeck 940
3525    
3526    
3527 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 63]
3528 schoenebeck 940
3529     Internet-Draft LinuxSampler Control Protocol November 2006
3530    
3531    
3532 schoenebeck 575 character string to that information category. At the moment the
3533     following categories are defined:
3534 senoner 542
3535 schoenebeck 708
3536    
3537 schoenebeck 575 DESCRIPTION -
3538 schoenebeck 708
3539 schoenebeck 575 arbitrary textual description about the sampler
3540 schoenebeck 708
3541 schoenebeck 575 VERSION -
3542 schoenebeck 708
3543 schoenebeck 575 version of the sampler
3544 schoenebeck 708
3545 schoenebeck 575 PROTOCOL_VERSION -
3546 schoenebeck 708
3547 schoenebeck 575 version of the LSCP specification the sampler complies with
3548     (see Section 2 for details)
3549 senoner 542
3550 schoenebeck 575 The mentioned fields above don't have to be in particular order.
3551     Other fields might be added in future.
3552 senoner 542
3553 schoenebeck 945 6.7. MIDI Instrument Mapping
3554 senoner 542
3555 schoenebeck 945 The MIDI protocol provides a way to switch between instruments by
3556     sending so called MIDI bank select and MIDI program change messages
3557     which are essentially just numbers. The following commands allow to
3558     actually map arbitrary MIDI bank select / program change numbers with
3559     real instruments.
3560 senoner 542
3561 schoenebeck 945 By default, that is when the sampler is launched, this map will be
3562     empty, thus the sampler will simply ignore all program change
3563     messages. The front-end has to explicitly add entries to the map so
3564     the sampler knows how to react on a given program change message,
3565     that is by switching to the respectively defined engine type and
3566     loading the respective instrument.
3567 senoner 542
3568 schoenebeck 945 Also note per MIDI specification a bank select message does not cause
3569     to switch to another instrument. Instead when receiving a bank
3570     select message the bank value will be stored and a subsequent program
3571     change message (which may occur at any time) will finally cause the
3572     sampler to switch to the respective instrument as reflected by the
3573     current MIDI instrument map.
3574 senoner 542
3575 schoenebeck 945 6.7.1. Create or replace a MIDI instrument map entry
3576 senoner 542
3577 schoenebeck 945 The front-end can create a new or replace an existing entry in the
3578     sampler's MIDI instrument map by sending the following command:
3579 senoner 542
3580    
3581    
3582    
3583 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 64]
3584    
3585     Internet-Draft LinuxSampler Control Protocol November 2006
3586 senoner 542
3587    
3588 schoenebeck 945 MAP MIDI_INSTRUMENT <midi_bank_msb> <midi_bank_lsb> <midi_prog>
3589     <engine_name> <filename> <instrument_index> <volume_value>
3590     [<instr_load_mode>] [<name>]
3591 senoner 542
3592 schoenebeck 945 Where <midi_bank_msb> is an integer value between 0..127 reflecting
3593     the MIDI bank select MSB (coarse) index, <midi_bank_lsb> an integer
3594     value between 0..127 reflecting the MIDI bank select LSB (fine)
3595     index, <midi_prog> an integer value between 0..127 reflecting the
3596     MIDI program change index, <engine_name> a sampler engine name as
3597     returned by the "LIST AVAILABLE_ENGINES" (Section 6.4.8) command (not
3598     encapsulated into apostrophes), <filename> the name of the
3599     instrument's file to be deployed (encapsulated into apostrophes),
3600     <instrument_index> the index (integer value) of the instrument within
3601     the given file, <volume_value> reflects the master volume of the
3602     instrument as optionally dotted number (where a value < 1.0 means
3603     attenuation and a value > 1.0 means amplification). This parameter
3604     easily allows to adjust the volume of all intruments within a custom
3605     instrument map without having to adjust their instrument files. The
3606     OPTIONAL <instr_load_mode> argument defines the life time of the
3607     instrument, that is when the instrument should be loaded, when freed
3608     and has exactly the following possibilities:
3609 senoner 542
3610 schoenebeck 945 "ON_DEMAND" -
3611 senoner 542
3612 schoenebeck 945 The instrument will be loaded when needed, that is when
3613     demanded by at least one sampler channel. It will immediately
3614     be freed from memory when not needed by any sampler channel
3615     anymore.
3616 senoner 542
3617 schoenebeck 945 "ON_DEMAND_HOLD" -
3618 senoner 542
3619 schoenebeck 945 The instrument will be loaded when needed, that is when
3620     demanded by at least one sampler channel. It will be kept in
3621     memory even when not needed by any sampler channel anymore.
3622     Instruments with this mode are only freed when the sampler is
3623     reset or all mapping entries with this mode (and respective
3624     instrument) are explicitly changed to "ON_DEMAND" and no
3625     sampler channel is using the instrument anymore.
3626 senoner 542
3627 schoenebeck 945 "PERSISTENT" -
3628 senoner 542
3629 schoenebeck 945 The instrument will immediately be loaded into memory in the
3630     background when this mapping command is sent and the instrument
3631     is kept all the time. Instruments with this mode are only
3632     freed when the sampler is reset or all mapping entries with
3633     this mode (and respective instrument) are explicitly changed to
3634     "ON_DEMAND" and no sampler channel is using the instrument
3635     anymore.
3636 senoner 542
3637    
3638 schoenebeck 708
3639 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 65]
3640    
3641     Internet-Draft LinuxSampler Control Protocol November 2006
3642 schoenebeck 708
3643    
3644 schoenebeck 945 not supplied -
3645 schoenebeck 708
3646 schoenebeck 945 In case there is no <instr_load_mode> argument given, it will
3647     be up to the InstrumentManager to decide which mode to use.
3648     Usually it will use "ON_DEMAND" if an entry for the given
3649     instrument does not exist in the InstrumentManager's list yet,
3650     otherwise if an entry already exists, it will simply stick with
3651     the mode currently reflected by the already existing entry,
3652     that is it will not change the mode.
3653 schoenebeck 940
3654 schoenebeck 945 The <instr_load_mode> argument thus allows to define an appropriate
3655     strategy (low memory consumption vs. fast instrument switching) for
3656     each instrument individually. Note, the following restrictions apply
3657     to this argument: "ON_DEMAND_HOLD" and "PERSISTENT" have to be
3658     supported by the respective sampler engine (which is technically the
3659     case when the engine provides an InstrumentManager for its format).
3660     If this is not the case the argument will automatically fall back to
3661     the default value "ON_DEMAND". Also the load mode of one instrument
3662     may automatically change the laod mode of other instrument(s), i.e.
3663     because the instruments are part of the same file and the engine does
3664     not allow a way to manage load modes for them individually. Due to
3665     this, in case the frontend shows the load modes of entries, the
3666     frontend should retrieve the actual mode by i.e. sending "GET
3667     MIDI_INSTRUMENT INFO" (Section 6.7.5) command(s). Finally the
3668     OPTIONAL <name> argument allows to set a custom name (encapsulated
3669     into apostrophes) for the mapping entry, useful for frontends for
3670     displaying an appropriate name for mapped instruments (using "GET
3671     MIDI_INSTRUMENT INFO" (Section 6.7.5)).
3672 schoenebeck 940
3673 schoenebeck 945 The "MAP MIDI_INSTRUMENT" command will immediately return, thus it
3674     will not block when an instrument is to be loaded due to a
3675     "PERSISTENT" type entry as instruments are loaded in the background.
3676     As a consequence this command may not necessarily return an error
3677     i.e. when the given instrument file does not exist or may turn out to
3678     be corrupt.
3679 schoenebeck 940
3680 schoenebeck 945 Possible Answers:
3681 schoenebeck 940
3682 schoenebeck 945 "OK" -
3683 schoenebeck 940
3684 schoenebeck 945 usually
3685 schoenebeck 940
3686 schoenebeck 945 "ERR:<error-code>:<error-message>" -
3687    
3688     when the given engine does not exist or a value is out of range
3689    
3690     Examples:
3691    
3692    
3693    
3694    
3695     Schoenebeck Expires May 30, 2007 [Page 66]
3696 schoenebeck 940
3697     Internet-Draft LinuxSampler Control Protocol November 2006
3698    
3699    
3700 schoenebeck 945 C: "MAP MIDI_INSTRUMENT 3 0 0 gig '/usr/share/Steinway D.gig' 0
3701     0.8 PERSISTENT"
3702    
3703     S: "OK"
3704    
3705     C: "MAP MIDI_INSTRUMENT 127 4 50 gig '/home/john/foostrings.gig' 7
3706     1.0"
3707    
3708     S: "OK"
3709    
3710     C: "MAP MIDI_INSTRUMENT 0 0 0 gig '/usr/share/piano.gig' 0 1.0
3711     'Normal Piano'"
3712    
3713     S: "OK"
3714    
3715     C: "MAP MIDI_INSTRUMENT 1 0 0 gig '/usr/share/piano.gig' 0 0.25
3716     'Silent Piano'"
3717    
3718     S: "OK"
3719    
3720     C: "MAP MIDI_INSTRUMENT 99 8 120 gig '/home/joe/foodrums.gig' 0
3721     1.0 PERSISTENT 'Foo Drumkit'"
3722    
3723     S: "OK"
3724    
3725     6.7.2. Getting ammount of MIDI instrument map entries
3726    
3727     The front-end can query the amount of currently existing MIDI
3728     instrument map entries by sending the following command:
3729    
3730     GET MIDI_INSTRUMENTS
3731    
3732     Possible Answers:
3733    
3734     LinuxSampler will answer by sending the current number of entries
3735     in the sampler's MIDI instrument map.
3736    
3737     Example:
3738    
3739     C: "GET MIDI_INSTRUMENTS"
3740    
3741     S: "634"
3742    
3743     6.7.3. Getting indeces of all MIDI instrument map entries
3744    
3745     The front-end can query a list of all currently existing MIDI
3746     instrument map entries by sending the following command:
3747    
3748    
3749    
3750    
3751     Schoenebeck Expires May 30, 2007 [Page 67]
3752    
3753     Internet-Draft LinuxSampler Control Protocol November 2006
3754    
3755    
3756     LIST MIDI_INSTRUMENTS
3757    
3758     Possible Answers:
3759    
3760     LinuxSampler will answer by sending a comma separated list of MIDI
3761     bank MSB (coarse) - MIDI bank LSB (fine) - MIDI program triples,
3762     where each triple is encapsulated into curly braces. The list is
3763     returned in one single line. Each triple just reflects the key of
3764     the respective map entry, thus subsequent "GET MIDI_INSTRUMENT
3765     INFO" (Section 6.7.5) command(s) are necessary to retrieve
3766     detailed informations about each entry.
3767    
3768     Example:
3769    
3770     C: "LIST MIDI_INSTRUMENTS"
3771    
3772     S: "{0,0,0},{0,0,1},{120,0,3},{120,0,4},{23,127,127}"
3773    
3774     6.7.4. Remove an entry from the MIDI instrument map
3775    
3776     The front-end can delete an entry from the MIDI instrument map by
3777     sending the following command:
3778    
3779     UNMAP MIDI_INSTRUMENT <midi_bank_msb> <midi_bank_lsb> <midi_prog>
3780    
3781     Where <midi_bank_msb> is an integer value between 0..127 reflecting
3782     the MIDI bank MSB (coarse) value, <midi_bank_lsb> an integer value
3783     between 0..127 reflecting the MIDI bank LSB (fine) value and
3784     <midi_prog> an integer value between 0..127 reflecting the MIDI
3785     program value of the map entrie's key index triple.
3786    
3787     Possible Answers:
3788    
3789     "OK" -
3790    
3791     usually
3792    
3793     "ERR:<error-code>:<error-message>" -
3794    
3795     when index out of bounds
3796    
3797     Example:
3798    
3799     C: "UNMAP MIDI_INSTRUMENT 2 40 127"
3800    
3801     S: "OK"
3802    
3803    
3804    
3805    
3806    
3807     Schoenebeck Expires May 30, 2007 [Page 68]
3808    
3809     Internet-Draft LinuxSampler Control Protocol November 2006
3810    
3811    
3812     6.7.5. Get current settings of MIDI instrument map entry
3813    
3814     The front-end can retrieve the current settings of a certain
3815     instrument map entry by sending the following command:
3816    
3817     GET MIDI_INSTRUMENT INFO <midi_bank_msb> <midi_bank_lsb>
3818     <midi_prog>
3819    
3820     Where <midi_bank_msb> is an integer value between 0..127 reflecting
3821     the MIDI bank MSB (coarse) value, <midi_bank_lsb> an integer value
3822     between 0..127 reflecting the MIDI bank LSB (fine) value and
3823     <midi_prog> an integer value between 0..127 reflecting the MIDI
3824     program value of the map entrie's key index triple.
3825    
3826     Possible Answers:
3827    
3828     LinuxSampler will answer by sending a <CRLF> separated list. Each
3829     answer line begins with the information category name followed by
3830     a colon and then a space character <SP> and finally the info
3831     character string to that info category. At the moment the
3832     following categories are defined:
3833    
3834     "NAME" -
3835    
3836     Name for this MIDI instrument map entry (if defined). This
3837     name shall be used by frontends for displaying a name for this
3838     mapped instrument. It can be set and changed with the "MAP
3839     MIDI_INSTRUMENT" (Section 6.7.1) command and does not have to
3840     be unique.
3841    
3842     "ENGINE_NAME" -
3843    
3844     Name of the engine to be deployed for this instrument.
3845    
3846     "INSTRUMENT_FILE" -
3847    
3848     File name of the instrument.
3849    
3850     "INSTRUMENT_NR" -
3851    
3852     Index of the instrument within the file.
3853    
3854     "INSTRUMENT_NAME" -
3855    
3856     Name of the loaded instrument as reflected by its file. In
3857     contrast to the "NAME" field, the "INSTRUMENT_NAME" field
3858     cannot be changed.
3859    
3860    
3861    
3862    
3863     Schoenebeck Expires May 30, 2007 [Page 69]
3864    
3865     Internet-Draft LinuxSampler Control Protocol November 2006
3866    
3867    
3868     "LOAD_MODE" -
3869    
3870     Life time of instrument (see "MAP MIDI_INSTRUMENT"
3871     (Section 6.7.1) for details about this setting).
3872    
3873     "VOLUME" -
3874    
3875     master volume of the instrument as optionally dotted number
3876     (where a value < 1.0 means attenuation and a value > 1.0 means
3877     amplification)
3878    
3879     The mentioned fields above don't have to be in particular order.
3880    
3881     Example:
3882    
3883     C: "GET MIDI_INSTRUMENT INFO 3 45 120"
3884    
3885     S: "NAME: Drums for Foo Song"
3886    
3887     "ENGINE_NAME: GigEngine"
3888    
3889     "INSTRUMENT_FILE: /usr/share/joesdrumkit.gig"
3890    
3891     "INSTRUMENT_NR: 0"
3892    
3893     "INSTRUMENT_NAME: Joe's Drumkit"
3894    
3895     "LOAD_MODE: PERSISTENT"
3896    
3897     "VOLUME: 1.0"
3898    
3899     "."
3900    
3901     6.7.6. Clear MIDI instrument map
3902    
3903     The front-end can clear the whole MIDI instrument map, that is delete
3904     all entries by sending the following command:
3905    
3906     CLEAR MIDI_INSTRUMENTS
3907    
3908     Possible Answers:
3909    
3910     "OK" -
3911    
3912     always
3913    
3914     Example:
3915    
3916    
3917    
3918    
3919     Schoenebeck Expires May 30, 2007 [Page 70]
3920    
3921     Internet-Draft LinuxSampler Control Protocol November 2006
3922    
3923    
3924     C: "CLEAR MIDI_INSTRUMENTS"
3925    
3926     S: "OK"
3927    
3928    
3929    
3930    
3931    
3932    
3933    
3934    
3935    
3936    
3937    
3938    
3939    
3940    
3941    
3942    
3943    
3944    
3945    
3946    
3947    
3948    
3949    
3950    
3951    
3952    
3953    
3954    
3955    
3956    
3957    
3958    
3959    
3960    
3961    
3962    
3963    
3964    
3965    
3966    
3967    
3968    
3969    
3970    
3971    
3972    
3973    
3974    
3975     Schoenebeck Expires May 30, 2007 [Page 71]
3976    
3977     Internet-Draft LinuxSampler Control Protocol November 2006
3978    
3979    
3980 schoenebeck 575 7. Command Syntax
3981 senoner 542
3982 schoenebeck 575 The grammar of the control protocol as descibed in Section 6 is
3983     defined below using Backus-Naur Form (BNF as described in [RFC2234])
3984     where applicable.
3985 senoner 542
3986 schoenebeck 575 input =
3987 schoenebeck 708
3988 schoenebeck 575 line LF
3989 schoenebeck 708
3990 schoenebeck 575 / line CR LF
3991 senoner 542
3992 schoenebeck 575 line =
3993 schoenebeck 708
3994 schoenebeck 575 /* epsilon (empty line ignored) */
3995 schoenebeck 708
3996 schoenebeck 575 / comment
3997 schoenebeck 708
3998 schoenebeck 575 / command
3999 schoenebeck 708
4000 schoenebeck 575 / error
4001 senoner 542
4002 schoenebeck 575 comment =
4003 schoenebeck 708
4004 schoenebeck 575 '#'
4005 schoenebeck 708
4006 schoenebeck 575 / comment '#'
4007 schoenebeck 708
4008 schoenebeck 575 / comment SP
4009 schoenebeck 708
4010 schoenebeck 575 / comment number
4011 schoenebeck 708
4012 schoenebeck 575 / comment string
4013 senoner 542
4014 schoenebeck 575 command =
4015 schoenebeck 708
4016 schoenebeck 575 ADD SP CHANNEL
4017 schoenebeck 708
4018 schoenebeck 945 / MAP SP map_instruction
4019    
4020     / UNMAP SP unmap_instruction
4021    
4022 schoenebeck 575 / GET SP get_instruction
4023 schoenebeck 708
4024 schoenebeck 575 / CREATE SP create_instruction
4025 schoenebeck 708
4026 schoenebeck 575 / DESTROY SP destroy_instruction
4027 schoenebeck 708
4028    
4029    
4030    
4031 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 72]
4032 schoenebeck 940
4033     Internet-Draft LinuxSampler Control Protocol November 2006
4034 schoenebeck 708
4035    
4036 schoenebeck 945 / LIST SP list_instruction
4037 schoenebeck 708
4038 schoenebeck 945 / LOAD SP load_instruction
4039    
4040     / REMOVE SP remove_instruction
4041    
4042 schoenebeck 575 / SET SP set_instruction
4043 schoenebeck 708
4044 schoenebeck 575 / SUBSCRIBE SP subscribe_event
4045 schoenebeck 708
4046 schoenebeck 575 / UNSUBSCRIBE SP unsubscribe_event
4047 schoenebeck 708
4048 schoenebeck 575 / SELECT SP text
4049 schoenebeck 708
4050 schoenebeck 945 / RESET SP reset_instruction
4051 schoenebeck 708
4052 schoenebeck 945 / CLEAR SP clear_instruction
4053    
4054 schoenebeck 575 / RESET
4055 schoenebeck 708
4056 schoenebeck 575 / QUIT
4057 senoner 542
4058 schoenebeck 575 subscribe_event =
4059 schoenebeck 708
4060 schoenebeck 575 CHANNEL_COUNT
4061 schoenebeck 708
4062 schoenebeck 575 / VOICE_COUNT
4063 schoenebeck 708
4064 schoenebeck 575 / STREAM_COUNT
4065 schoenebeck 708
4066 schoenebeck 575 / BUFFER_FILL
4067 schoenebeck 708
4068 schoenebeck 575 / CHANNEL_INFO
4069 schoenebeck 708
4070 schoenebeck 575 / MISCELLANEOUS
4071 senoner 542
4072 schoenebeck 940 / TOTAL_VOICE_COUNT
4073    
4074 schoenebeck 575 unsubscribe_event =
4075 senoner 542
4076 schoenebeck 708 CHANNEL_COUNT
4077 senoner 542
4078 schoenebeck 708 / VOICE_COUNT
4079 senoner 542
4080 schoenebeck 708 / STREAM_COUNT
4081 senoner 542
4082 schoenebeck 708 / BUFFER_FILL
4083 senoner 542
4084 schoenebeck 945
4085    
4086    
4087     Schoenebeck Expires May 30, 2007 [Page 73]
4088    
4089     Internet-Draft LinuxSampler Control Protocol November 2006
4090    
4091    
4092 schoenebeck 575 / CHANNEL_INFO
4093 schoenebeck 708
4094 schoenebeck 575 / MISCELLANEOUS
4095    
4096 schoenebeck 940 / TOTAL_VOICE_COUNT
4097 schoenebeck 708
4098 schoenebeck 945 map_instruction =
4099 schoenebeck 708
4100 schoenebeck 945 MIDI_INSTRUMENT SP midi_bank_msb SP midi_bank_lsb SP midi_prog SP
4101     engine_name SP filename SP instrument_index SP volume_value
4102 schoenebeck 708
4103 schoenebeck 945 / MIDI_INSTRUMENT SP midi_bank_msb SP midi_bank_lsb SP midi_prog
4104     SP engine_name SP filename SP instrument_index SP volume_value SP
4105     instr_load_mode
4106 schoenebeck 708
4107 schoenebeck 945 / MIDI_INSTRUMENT SP midi_bank_msb SP midi_bank_lsb SP midi_prog
4108     SP engine_name SP filename SP instrument_index SP volume_value SP
4109     entry_name
4110 schoenebeck 708
4111 schoenebeck 945 / MIDI_INSTRUMENT SP midi_bank_msb SP midi_bank_lsb SP midi_prog
4112     SP engine_name SP filename SP instrument_index SP volume_value SP
4113     instr_load_mode SP entry_name
4114 schoenebeck 708
4115 schoenebeck 945 unmap_instruction =
4116    
4117     MIDI_INSTRUMENT SP midi_bank_msb SP midi_bank_lsb SP midi_prog
4118    
4119     remove_instruction =
4120    
4121     CHANNEL SP sampler_channel
4122    
4123 schoenebeck 940 get_instruction =
4124 schoenebeck 708
4125 schoenebeck 940 AVAILABLE_ENGINES
4126 schoenebeck 708
4127 schoenebeck 575 / AVAILABLE_MIDI_INPUT_DRIVERS
4128 schoenebeck 708
4129 schoenebeck 575 / MIDI_INPUT_DRIVER SP INFO SP string
4130 schoenebeck 708
4131 schoenebeck 575 / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
4132 schoenebeck 708
4133 schoenebeck 575 / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP
4134     key_val_list
4135 schoenebeck 708
4136 schoenebeck 575 / AVAILABLE_AUDIO_OUTPUT_DRIVERS
4137 schoenebeck 708
4138 schoenebeck 575 / AUDIO_OUTPUT_DRIVER SP INFO SP string
4139 schoenebeck 708
4140 schoenebeck 945
4141    
4142    
4143     Schoenebeck Expires May 30, 2007 [Page 74]
4144    
4145     Internet-Draft LinuxSampler Control Protocol November 2006
4146    
4147    
4148 schoenebeck 575 / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
4149 schoenebeck 708
4150 schoenebeck 575 / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP
4151     key_val_list
4152 schoenebeck 708
4153 schoenebeck 575 / AUDIO_OUTPUT_DEVICES
4154 schoenebeck 708
4155 schoenebeck 575 / MIDI_INPUT_DEVICES
4156 schoenebeck 708
4157 schoenebeck 575 / AUDIO_OUTPUT_DEVICE SP INFO SP number
4158 schoenebeck 708
4159 schoenebeck 575 / MIDI_INPUT_DEVICE SP INFO SP number
4160 schoenebeck 708
4161 schoenebeck 575 / MIDI_INPUT_PORT SP INFO SP number SP number
4162 schoenebeck 708
4163 schoenebeck 575 / MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
4164 schoenebeck 708
4165 schoenebeck 575 / AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
4166 schoenebeck 708
4167 schoenebeck 575 / AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP
4168     string
4169 schoenebeck 708
4170 schoenebeck 575 / CHANNELS
4171 schoenebeck 708
4172 schoenebeck 575 / CHANNEL SP INFO SP sampler_channel
4173 schoenebeck 708
4174 schoenebeck 575 / CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
4175 schoenebeck 708
4176 schoenebeck 575 / CHANNEL SP STREAM_COUNT SP sampler_channel
4177 schoenebeck 708
4178 schoenebeck 940 / CHANNEL SP VOICE_COUNT SP sampler_channel
4179 schoenebeck 708
4180 schoenebeck 940 / ENGINE SP INFO SP engine_name
4181 schoenebeck 708
4182 schoenebeck 575 / SERVER SP INFO
4183    
4184 schoenebeck 940 / TOTAL_VOICE_COUNT
4185    
4186     / TOTAL_VOICE_COUNT_MAX
4187    
4188 schoenebeck 945 / MIDI_INSTRUMENTS
4189    
4190     / MIDI_INSTRUMENT SP INFO SP midi_bank_msb SP midi_bank_lsb SP
4191     midi_prog
4192    
4193 schoenebeck 575 set_instruction =
4194 schoenebeck 708
4195 schoenebeck 945
4196    
4197    
4198    
4199     Schoenebeck Expires May 30, 2007 [Page 75]
4200    
4201     Internet-Draft LinuxSampler Control Protocol November 2006
4202    
4203    
4204 schoenebeck 575 AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '='
4205     param_val_list
4206 schoenebeck 708
4207 schoenebeck 575 / AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '='
4208     param_val_list
4209 schoenebeck 708
4210 schoenebeck 575 / MIDI_INPUT_DEVICE_PARAMETER SP number SP string '='
4211     param_val_list
4212 schoenebeck 708
4213 schoenebeck 575 / MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '='
4214     param_val_list
4215 schoenebeck 708
4216 schoenebeck 575 / CHANNEL SP set_chan_instruction
4217 schoenebeck 708
4218 schoenebeck 575 / ECHO SP boolean
4219    
4220 schoenebeck 708 create_instruction =
4221 schoenebeck 575
4222 schoenebeck 708 AUDIO_OUTPUT_DEVICE SP string SP key_val_list
4223 schoenebeck 575
4224 schoenebeck 708 / AUDIO_OUTPUT_DEVICE SP string
4225 schoenebeck 575
4226 schoenebeck 708 / MIDI_INPUT_DEVICE SP string SP key_val_list
4227 senoner 542
4228 schoenebeck 575 / MIDI_INPUT_DEVICE SP string
4229 senoner 542
4230 schoenebeck 945 reset_instruction =
4231    
4232     CHANNEL SP sampler_channel
4233    
4234     clear_instruction =
4235    
4236     MIDI_INSTRUMENTS
4237    
4238 schoenebeck 575 destroy_instruction =
4239 schoenebeck 708
4240 schoenebeck 575 AUDIO_OUTPUT_DEVICE SP number
4241 schoenebeck 708
4242 schoenebeck 575 / MIDI_INPUT_DEVICE SP number
4243 senoner 542
4244 schoenebeck 575 load_instruction =
4245 schoenebeck 708
4246 schoenebeck 575 INSTRUMENT SP load_instr_args
4247 schoenebeck 708
4248 schoenebeck 945 / ENGINE SP load_engine_args
4249 schoenebeck 940
4250 schoenebeck 945 set_chan_instruction =
4251 schoenebeck 940
4252    
4253 schoenebeck 945
4254    
4255     Schoenebeck Expires May 30, 2007 [Page 76]
4256 schoenebeck 940
4257     Internet-Draft LinuxSampler Control Protocol November 2006
4258    
4259    
4260 schoenebeck 575 AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
4261 schoenebeck 708
4262 schoenebeck 575 / AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index
4263     SP audio_channel_index
4264 schoenebeck 708
4265 schoenebeck 575 / AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
4266 schoenebeck 708
4267 schoenebeck 575 / MIDI_INPUT SP sampler_channel SP device_index SP
4268     midi_input_port_index SP midi_input_channel_index
4269 schoenebeck 708
4270 schoenebeck 575 / MIDI_INPUT_DEVICE SP sampler_channel SP device_index
4271 schoenebeck 708
4272 schoenebeck 575 / MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
4273 schoenebeck 708
4274 schoenebeck 575 / MIDI_INPUT_CHANNEL SP sampler_channel SP
4275     midi_input_channel_index
4276 schoenebeck 708
4277 schoenebeck 575 / MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
4278 schoenebeck 708
4279 schoenebeck 575 / VOLUME SP sampler_channel SP volume_value
4280 senoner 542
4281 schoenebeck 708 / MUTE SP sampler_channel SP boolean
4282    
4283     / SOLO SP sampler_channel SP boolean
4284    
4285 schoenebeck 575 key_val_list =
4286 schoenebeck 708
4287 schoenebeck 575 string '=' param_val_list
4288 schoenebeck 708
4289 schoenebeck 575 / key_val_list SP string '=' param_val_list
4290 senoner 542
4291 schoenebeck 575 buffer_size_type =
4292 schoenebeck 708
4293 schoenebeck 575 BYTES
4294 schoenebeck 708
4295 schoenebeck 575 / PERCENTAGE
4296 senoner 542
4297 schoenebeck 575 list_instruction =
4298 schoenebeck 708
4299 schoenebeck 575 AUDIO_OUTPUT_DEVICES
4300 schoenebeck 708
4301 schoenebeck 575 / MIDI_INPUT_DEVICES
4302 schoenebeck 708
4303 schoenebeck 945 / CHANNELS
4304 schoenebeck 708
4305 schoenebeck 945 / AVAILABLE_ENGINES
4306 schoenebeck 708
4307    
4308 senoner 542
4309 schoenebeck 945
4310    
4311     Schoenebeck Expires May 30, 2007 [Page 77]
4312 schoenebeck 940
4313     Internet-Draft LinuxSampler Control Protocol November 2006
4314 senoner 542
4315    
4316 schoenebeck 940 / AVAILABLE_MIDI_INPUT_DRIVERS
4317 senoner 542
4318 schoenebeck 940 / AVAILABLE_AUDIO_OUTPUT_DRIVERS
4319 senoner 542
4320 schoenebeck 945 / MIDI_INSTRUMENTS
4321    
4322 schoenebeck 940 load_instr_args =
4323 schoenebeck 708
4324     filename SP instrument_index SP sampler_channel
4325    
4326     / NON_MODAL SP filename SP instrument_index SP sampler_channel
4327    
4328 schoenebeck 575 load_engine_args =
4329 schoenebeck 708
4330 schoenebeck 575 engine_name SP sampler_channel
4331 senoner 542
4332 schoenebeck 945 instr_load_mode =
4333    
4334     ON_DEMAND
4335    
4336     / ON_DEMAND_HOLD
4337    
4338     / PERSISTENT
4339    
4340 schoenebeck 575 device_index =
4341 schoenebeck 708
4342 schoenebeck 575 number
4343 senoner 542
4344 schoenebeck 575 audio_channel_index =
4345 schoenebeck 708
4346 schoenebeck 575 number
4347 senoner 542
4348 schoenebeck 575 audio_output_type_name =
4349 schoenebeck 708
4350 schoenebeck 575 string
4351 senoner 542
4352 schoenebeck 575 midi_input_port_index =
4353 schoenebeck 708
4354 schoenebeck 575 number
4355 senoner 542
4356 schoenebeck 575 midi_input_channel_index =
4357 schoenebeck 708
4358 schoenebeck 575 number
4359 schoenebeck 708
4360 schoenebeck 575 / ALL
4361 senoner 542
4362 schoenebeck 575 midi_input_type_name =
4363 schoenebeck 708
4364 schoenebeck 945
4365    
4366    
4367     Schoenebeck Expires May 30, 2007 [Page 78]
4368    
4369     Internet-Draft LinuxSampler Control Protocol November 2006
4370    
4371    
4372 schoenebeck 575 string
4373 senoner 542
4374 schoenebeck 945 midi_bank_msb =
4375 schoenebeck 708
4376 schoenebeck 945 number
4377 schoenebeck 708
4378 schoenebeck 945 midi_bank_lsb =
4379 schoenebeck 940
4380 schoenebeck 945 number
4381 schoenebeck 940
4382 schoenebeck 945 midi_prog =
4383 schoenebeck 940
4384 schoenebeck 945 number
4385 schoenebeck 940
4386 schoenebeck 945 volume_value =
4387 schoenebeck 940
4388 schoenebeck 945 dotnum
4389    
4390 schoenebeck 575 / number
4391 senoner 542
4392 schoenebeck 575 sampler_channel =
4393 schoenebeck 708
4394 schoenebeck 575 number
4395 senoner 542
4396 schoenebeck 575 instrument_index =
4397 schoenebeck 708
4398 schoenebeck 575 number
4399 senoner 542
4400 schoenebeck 708 engine_name =
4401 senoner 542
4402 schoenebeck 708 string
4403 senoner 542
4404 schoenebeck 708 filename =
4405 senoner 542
4406 schoenebeck 708 stringval
4407 senoner 542
4408 schoenebeck 945 entry_name =
4409    
4410     stringval
4411    
4412 schoenebeck 708 param_val_list =
4413 senoner 542
4414 schoenebeck 708 param_val
4415 senoner 542
4416 schoenebeck 708 / param_val_list','param_val
4417 senoner 542
4418 schoenebeck 708 param_val =
4419 senoner 542
4420 schoenebeck 945
4421    
4422    
4423     Schoenebeck Expires May 30, 2007 [Page 79]
4424    
4425     Internet-Draft LinuxSampler Control Protocol November 2006
4426    
4427    
4428 schoenebeck 708 string
4429 senoner 542
4430 schoenebeck 940 / stringval
4431 senoner 542
4432 schoenebeck 708 / number
4433 senoner 542
4434 schoenebeck 708 / dotnum
4435 senoner 542
4436    
4437    
4438    
4439    
4440    
4441 schoenebeck 575
4442    
4443    
4444    
4445    
4446    
4447    
4448    
4449    
4450    
4451    
4452    
4453 schoenebeck 945
4454    
4455    
4456    
4457    
4458    
4459    
4460    
4461    
4462    
4463    
4464    
4465    
4466    
4467    
4468    
4469    
4470    
4471    
4472    
4473    
4474    
4475    
4476    
4477    
4478    
4479     Schoenebeck Expires May 30, 2007 [Page 80]
4480 schoenebeck 940
4481     Internet-Draft LinuxSampler Control Protocol November 2006
4482 schoenebeck 575
4483    
4484     8. Events
4485 senoner 542
4486     This chapter will describe all currently defined events supported by
4487     LinuxSampler.
4488    
4489 schoenebeck 940 8.1. Number of sampler channels changed
4490 senoner 542
4491     Client may want to be notified when the total number of channels on
4492     the back-end changes by issuing the following command:
4493    
4494 schoenebeck 558 SUBSCRIBE CHANNEL_COUNT
4495 senoner 542
4496     Server will start sending the following notification messages:
4497    
4498 schoenebeck 558 "NOTIFY:CHANNEL_COUNT:<channels>"
4499 senoner 542
4500     where <channels> will be replaced by the new number of sampler
4501     channels.
4502    
4503 schoenebeck 940 8.2. Number of active voices changed
4504 senoner 542
4505 schoenebeck 708 Client may want to be notified when the number of voices on the back-
4506     end changes by issuing the following command:
4507 senoner 542
4508     SUBSCRIBE VOICE_COUNT
4509    
4510     Server will start sending the following notification messages:
4511    
4512     "NOTIFY:VOICE_COUNT:<sampler-channel> <voices>
4513    
4514     where <sampler-channel> will be replaced by the sampler channel the
4515     voice count change occurred and <voices> by the new number of active
4516     voices on that channel.
4517    
4518 schoenebeck 940 8.3. Number of active disk streams changed
4519 senoner 542
4520     Client may want to be notified when the number of streams on the
4521     back-end changes by issuing the following command: SUBSCRIBE
4522     STREAM_COUNT
4523    
4524     SUBSCRIBE STREAM_COUNT
4525    
4526     Server will start sending the following notification messages:
4527    
4528     "NOTIFY:STREAM_COUNT:<sampler-channel> <streams>"
4529    
4530     where <sampler-channel> will be replaced by the sampler channel the
4531     stream count change occurred and <streams> by the new number of
4532    
4533    
4534    
4535 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 81]
4536 schoenebeck 940
4537     Internet-Draft LinuxSampler Control Protocol November 2006
4538 senoner 542
4539    
4540     active disk streams on that channel.
4541    
4542 schoenebeck 940 8.4. Disk stream buffer fill state changed
4543 senoner 542
4544     Client may want to be notified when the buffer fill state of a disk
4545     stream on the back-end changes by issuing the following command:
4546    
4547     SUBSCRIBE BUFFER_FILL
4548    
4549     Server will start sending the following notification messages:
4550    
4551     "NOTIFY:BUFFER_FILL:<sampler-channel> <fill-data>"
4552    
4553     where <sampler-channel> will be replaced by the sampler channel the
4554     buffer fill state change occurred on and <fill-data> will be replaced
4555 schoenebeck 708 by the buffer fill data for this channel as described in
4556     Section 6.4.13 as if the "GET CHANNEL BUFFER_FILL PERCENTAGE"
4557     (Section 6.4.13) command was issued on this channel.
4558 senoner 542
4559 schoenebeck 940 8.5. Channel information changed
4560 senoner 542
4561     Client may want to be notified when changes were made to sampler
4562 schoenebeck 561 channels on the back-end by issuing the following command:
4563 senoner 542
4564 schoenebeck 558 SUBSCRIBE CHANNEL_INFO
4565 senoner 542
4566     Server will start sending the following notification messages:
4567    
4568 schoenebeck 558 "NOTIFY:CHANNEL_INFO:<sampler-channel>"
4569 senoner 542
4570     where <sampler-channel> will be replaced by the sampler channel the
4571     channel info change occurred. The front-end will have to send the
4572     respective command to actually get the channel info. Because these
4573     messages will be triggered by LSCP commands issued by other clients
4574     rather than real time events happening on the server, it is believed
4575     that an empty notification message is sufficient here.
4576    
4577 schoenebeck 940 8.6. Total number of active voices changed
4578 senoner 542
4579 schoenebeck 940 Client may want to be notified when the total number of voices on the
4580     back-end changes by issuing the following command:
4581 senoner 542
4582 schoenebeck 940 SUBSCRIBE TOTAL_VOICE_COUNT
4583 senoner 542
4584     Server will start sending the following notification messages:
4585    
4586    
4587    
4588    
4589    
4590    
4591 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 82]
4592 schoenebeck 940
4593     Internet-Draft LinuxSampler Control Protocol November 2006
4594 senoner 542
4595 schoenebeck 708
4596 schoenebeck 940 "NOTIFY:TOTAL_VOICE_COUNT:<voices>
4597 schoenebeck 708
4598 schoenebeck 940 where <voices> will be replaced by the new number of all currently
4599     active voices.
4600 schoenebeck 708
4601 schoenebeck 940 8.7. Miscellaneous and debugging events
4602 senoner 542
4603 schoenebeck 940 Client may want to be notified of miscellaneous and debugging events
4604     occurring at the server by issuing the following command:
4605 senoner 542
4606 schoenebeck 940 SUBSCRIBE MISCELLANEOUS
4607 senoner 542
4608 schoenebeck 940 Server will start sending the following notification messages:
4609 senoner 542
4610 schoenebeck 940 "NOTIFY:MISCELLANEOUS:<string>"
4611 senoner 542
4612 schoenebeck 940 where <string> will be replaced by whatever data server wants to send
4613     to the client. Client MAY display this data to the user AS IS to
4614     facilitate debugging.
4615 senoner 542
4616    
4617    
4618    
4619    
4620    
4621    
4622    
4623    
4624    
4625    
4626    
4627    
4628    
4629    
4630    
4631    
4632    
4633    
4634    
4635    
4636    
4637    
4638    
4639    
4640    
4641    
4642    
4643    
4644    
4645    
4646    
4647 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 83]
4648 schoenebeck 940
4649     Internet-Draft LinuxSampler Control Protocol November 2006
4650 senoner 542
4651    
4652 schoenebeck 575 9. Security Considerations
4653 senoner 542
4654     As there is so far no method of authentication and authorization
4655     defined and so not required for a client applications to succeed to
4656     connect, running LinuxSampler might be a security risk for the host
4657     system the LinuxSampler instance is running on.
4658    
4659    
4660    
4661    
4662    
4663    
4664    
4665    
4666    
4667    
4668    
4669    
4670    
4671    
4672    
4673    
4674    
4675    
4676    
4677    
4678    
4679    
4680    
4681    
4682    
4683    
4684    
4685    
4686    
4687    
4688    
4689    
4690    
4691    
4692    
4693    
4694    
4695    
4696    
4697    
4698    
4699    
4700    
4701    
4702    
4703 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 84]
4704 schoenebeck 940
4705     Internet-Draft LinuxSampler Control Protocol November 2006
4706 senoner 542
4707    
4708 schoenebeck 575 10. Acknowledgments
4709 senoner 542
4710     This document has benefited greatly from the comments of the
4711     following people, discussed on the LinuxSampler developer's mailing
4712     list:
4713    
4714     Rui Nuno Capela
4715 schoenebeck 708
4716 senoner 542 Vladimir Senkov
4717 schoenebeck 708
4718 senoner 542 Mark Knecht
4719 schoenebeck 708
4720 schoenebeck 561 Grigor Iliev
4721 senoner 542
4722    
4723 schoenebeck 708 11. References
4724    
4725 senoner 542 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
4726 schoenebeck 575 Requirement Levels", RFC 2119, 1997.
4727 senoner 542
4728 schoenebeck 575 [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
4729     Specifications", RFC 2234, 1997.
4730 senoner 542
4731 schoenebeck 575 [RFC793] Defense Advanced Research Projects Agency, "TRANSMISSION
4732     CONTROL PROTOCOL", RFC 793, 1981.
4733    
4734    
4735 schoenebeck 940
4736    
4737    
4738    
4739    
4740    
4741    
4742    
4743    
4744    
4745    
4746    
4747    
4748    
4749    
4750    
4751    
4752    
4753    
4754    
4755    
4756    
4757    
4758    
4759 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 85]
4760 schoenebeck 940
4761     Internet-Draft LinuxSampler Control Protocol November 2006
4762    
4763    
4764 senoner 542 Author's Address
4765    
4766     C. Schoenebeck
4767     Interessengemeinschaft Software Engineering e. V.
4768     Max-Planck-Str. 39
4769     74081 Heilbronn
4770     Germany
4771    
4772 schoenebeck 708 Email: schoenebeck at software minus engineering dot org
4773 senoner 542
4774    
4775    
4776    
4777    
4778    
4779    
4780    
4781    
4782    
4783    
4784    
4785    
4786    
4787    
4788    
4789    
4790    
4791 schoenebeck 940
4792    
4793    
4794    
4795    
4796    
4797    
4798    
4799    
4800    
4801    
4802    
4803    
4804    
4805    
4806    
4807    
4808    
4809    
4810    
4811    
4812    
4813    
4814    
4815 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 86]
4816 schoenebeck 940
4817     Internet-Draft LinuxSampler Control Protocol November 2006
4818    
4819    
4820 senoner 542 Intellectual Property Statement
4821    
4822     The IETF takes no position regarding the validity or scope of any
4823     intellectual property or other rights that might be claimed to
4824     pertain to the implementation or use of the technology described in
4825     this document or the extent to which any license under such rights
4826     might or might not be available; neither does it represent that it
4827     has made any effort to identify any such rights. Information on the
4828     IETF's procedures with respect to rights in standards-track and
4829 schoenebeck 708 standards-related documentation can be found in BCP 11. Copies of
4830 senoner 542 claims of rights made available for publication and any assurances of
4831     licenses to be made available, or the result of an attempt made to
4832     obtain a general license or permission for the use of such
4833     proprietary rights by implementors or users of this specification can
4834     be obtained from the IETF Secretariat.
4835    
4836     The IETF invites any interested party to bring to its attention any
4837     copyrights, patents or patent applications, or other proprietary
4838     rights which may cover technology that may be required to practice
4839     this standard. Please address the information to the IETF Executive
4840     Director.
4841    
4842    
4843     Full Copyright Statement
4844    
4845 schoenebeck 940 Copyright (C) The Internet Society (2006). All Rights Reserved.
4846 senoner 542
4847     This document and translations of it may be copied and furnished to
4848     others, and derivative works that comment on or otherwise explain it
4849     or assist in its implementation may be prepared, copied, published
4850     and distributed, in whole or in part, without restriction of any
4851     kind, provided that the above copyright notice and this paragraph are
4852     included on all such copies and derivative works. However, this
4853     document itself may not be modified in any way, such as by removing
4854     the copyright notice or references to the Internet Society or other
4855     Internet organizations, except as needed for the purpose of
4856     developing Internet standards in which case the procedures for
4857     copyrights defined in the Internet Standards process must be
4858     followed, or as required to translate it into languages other than
4859     English.
4860    
4861     The limited permissions granted above are perpetual and will not be
4862     revoked by the Internet Society or its successors or assignees.
4863    
4864     This document and the information contained herein is provided on an
4865     "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
4866     TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
4867     BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
4868    
4869    
4870    
4871 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 87]
4872 schoenebeck 940
4873     Internet-Draft LinuxSampler Control Protocol November 2006
4874 senoner 542
4875    
4876     HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
4877     MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
4878    
4879    
4880     Acknowledgment
4881    
4882     Funding for the RFC Editor function is currently provided by the
4883     Internet Society.
4884    
4885    
4886    
4887    
4888    
4889    
4890    
4891    
4892    
4893    
4894    
4895    
4896    
4897    
4898    
4899    
4900    
4901    
4902    
4903    
4904    
4905    
4906    
4907    
4908    
4909    
4910    
4911    
4912    
4913    
4914    
4915    
4916    
4917    
4918    
4919    
4920    
4921    
4922    
4923    
4924    
4925    
4926    
4927 schoenebeck 945 Schoenebeck Expires May 30, 2007 [Page 88]
4928 schoenebeck 940

  ViewVC Help
Powered by ViewVC