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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 561 by schoenebeck, Sat May 21 20:01:32 2005 UTC revision 945 by schoenebeck, Sun Nov 26 16:39:49 2006 UTC
# Line 1  Line 1 
1    
2    
3    
4  LinuxSampler Developers                                   C. Schoenebeck  LinuxSampler Developers                                   C. Schoenebeck
5  Internet-Draft                           Interessengemeinschaft Software  Internet-Draft                           Interessengemeinschaft Software
6  Expires: November 19, 2005                             Engineering e. V.  Expires: May 30, 2007                                  Engineering e. V.
7                                                              May 21, 2005                                                         November 26, 2006
8    
9    
10                       LinuxSampler Control Protocol                       LinuxSampler Control Protocol
11                                  lscp.txt                                  LSCP 1.2
12    
13  Status of this Memo  Status of this Memo
14    
15     This document is an Internet-Draft and is in full conformance with     This document is an Internet-Draft and is in full conformance with
16     all provisions of Section 10 of RFC2026.     all provisions of Section 10 of RFC 2026.
17    
18     Internet-Drafts are working documents of the Internet Engineering     Internet-Drafts are working documents of the Internet Engineering
19     Task Force (IETF), its areas, and its working groups.  Note that     Task Force (IETF), its areas, and its working groups.  Note that
20     other groups may also distribute working documents as     other groups may also distribute working documents as Internet-
21     Internet-Drafts.     Drafts.
22    
23     Internet-Drafts are draft documents valid for a maximum of six months     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     and may be updated, replaced, or obsoleted by other documents at any
# Line 30  Status of this Memo Line 31  Status of this Memo
31     The list of Internet-Draft Shadow Directories can be accessed at     The list of Internet-Draft Shadow Directories can be accessed at
32     http://www.ietf.org/shadow.html.     http://www.ietf.org/shadow.html.
33    
34     This Internet-Draft will expire on November 19, 2005.     This Internet-Draft will expire on May 30, 2007.
35    
36  Copyright Notice  Copyright Notice
37    
38     Copyright (C) The Internet Society (2005).  All Rights Reserved.     Copyright (C) The Internet Society (2006).  All Rights Reserved.
39    
40  Abstract  Abstract
41    
42     The LinuxSampler Control Protocol (LSCP) is an application-level     The LinuxSampler Control Protocol (LSCP) is an application-level
43     protocol primarily intended for local and remote controlling the     protocol primarily intended for local and remote controlling the
44     LinuxSampler main application, which is a sophisticated console     LinuxSampler backend application, which is a sophisticated server-
45     application essentially playing back audio samples and manipulating     like console application essentially playing back audio samples and
46     the samples in real time to certain extent.     manipulating the samples in real time to certain extent.
   
47    
48    
49    
# Line 52  Abstract Line 52  Abstract
52    
53    
54    
55  Schoenebeck            Expires November 19, 2005                [Page 1]  Schoenebeck               Expires May 30, 2007                  [Page 1]
56    
57  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
58    
59    
60  Table of Contents  Table of Contents
61    
62     1.   Requirements notation  . . . . . . . . . . . . . . . . . . .   4     1.  Requirements notation  . . . . . . . . . . . . . . . . . . . .  5
63     2.   Introduction . . . . . . . . . . . . . . . . . . . . . . . .   5     2.  Versioning of this specification . . . . . . . . . . . . . . .  6
64     3.   Focus of this protocol . . . . . . . . . . . . . . . . . . .   6     3.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  7
65     4.   Communication Overview . . . . . . . . . . . . . . . . . . .   7     4.  Focus of this protocol . . . . . . . . . . . . . . . . . . . .  8
66       4.1  Request/response communication method  . . . . . . . . . .   7     5.  Communication Overview . . . . . . . . . . . . . . . . . . . .  9
67         4.1.1  Result format  . . . . . . . . . . . . . . . . . . . .   8       5.1.  Request/response communication method  . . . . . . . . . .  9
68       4.2  Subscribe/notify communication method  . . . . . . . . . .   9         5.1.1.  Result format  . . . . . . . . . . . . . . . . . . . . 10
69     5.   Description for control commands . . . . . . . . . . . . . .  12       5.2.  Subscribe/notify communication method  . . . . . . . . . . 12
70       5.1  Ignored lines and comments . . . . . . . . . . . . . . . .  12     6.  Description for control commands . . . . . . . . . . . . . . . 14
71       5.2  Configuring audio drivers  . . . . . . . . . . . . . . . .  12       6.1.  Ignored lines and comments . . . . . . . . . . . . . . . . 14
72         5.2.1  Getting amount of available audio output drivers . . .  12       6.2.  Configuring audio drivers  . . . . . . . . . . . . . . . . 14
73         5.2.2  Getting all available audio output drivers . . . . . .  13         6.2.1.  Getting amount of available audio output drivers . . . 14
74         5.2.3  Getting information about a specific audio output         6.2.2.  Getting all available audio output drivers . . . . . . 15
75                driver . . . . . . . . . . . . . . . . . . . . . . . .  13         6.2.3.  Getting information about a specific audio output
76         5.2.4  Getting information about specific audio output                 driver . . . . . . . . . . . . . . . . . . . . . . . . 15
77                driver parameter . . . . . . . . . . . . . . . . . . .  14         6.2.4.  Getting information about specific audio output
78         5.2.5  Creating an audio output device  . . . . . . . . . . .  17                 driver parameter . . . . . . . . . . . . . . . . . . . 16
79         5.2.6  Destroying an audio output device  . . . . . . . . . .  17         6.2.5.  Creating an audio output device  . . . . . . . . . . . 20
80         5.2.7  Getting all created audio output device count  . . . .  18         6.2.6.  Destroying an audio output device  . . . . . . . . . . 21
81         5.2.8  Getting all created audio output device list . . . . .  18         6.2.7.  Getting all created audio output device count  . . . . 22
82         5.2.9  Getting current settings of an audio output device . .  19         6.2.8.  Getting all created audio output device list . . . . . 22
83         5.2.10   Changing settings of audio output devices  . . . . .  20         6.2.9.  Getting current settings of an audio output device . . 22
84         5.2.11   Getting information about an audio channel . . . . .  20         6.2.10. Changing settings of audio output devices  . . . . . . 24
85         5.2.12   Getting information about specific audio channel         6.2.11. Getting information about an audio channel . . . . . . 24
86                  parameter  . . . . . . . . . . . . . . . . . . . . .  22         6.2.12. Getting information about specific audio channel
87         5.2.13   Changing settings of audio output channels . . . . .  23                 parameter  . . . . . . . . . . . . . . . . . . . . . . 26
88       5.3  Configuring MIDI input drivers . . . . . . . . . . . . . .  24         6.2.13. Changing settings of audio output channels . . . . . . 28
89         5.3.1  Getting amount of available MIDI input drivers . . . .  24       6.3.  Configuring MIDI input drivers . . . . . . . . . . . . . . 29
90         5.3.2  Getting all available MIDI input drivers . . . . . . .  25         6.3.1.  Getting amount of available MIDI input drivers . . . . 30
91         5.3.3  Getting information about a specific MIDI input         6.3.2.  Getting all available MIDI input drivers . . . . . . . 30
92                driver . . . . . . . . . . . . . . . . . . . . . . . .  25         6.3.3.  Getting information about a specific MIDI input
93         5.3.4  Getting information about specific MIDI input                 driver . . . . . . . . . . . . . . . . . . . . . . . . 30
94                driver parameter . . . . . . . . . . . . . . . . . . .  26         6.3.4.  Getting information about specific MIDI input
95         5.3.5  Creating a MIDI input device . . . . . . . . . . . . .  28                 driver parameter . . . . . . . . . . . . . . . . . . . 31
96         5.3.6  Destroying a MIDI input device . . . . . . . . . . . .  29         6.3.5.  Creating a MIDI input device . . . . . . . . . . . . . 34
97         5.3.7  Getting all created MIDI input device count  . . . . .  29         6.3.6.  Destroying a MIDI input device . . . . . . . . . . . . 35
98         5.3.8  Getting all created MIDI input device list . . . . . .  29         6.3.7.  Getting all created MIDI input device count  . . . . . 36
99         5.3.9  Getting current settings of a MIDI input device  . . .  30         6.3.8.  Getting all created MIDI input device list . . . . . . 36
100         5.3.10   Changing settings of MIDI input devices  . . . . . .  31         6.3.9.  Getting current settings of a MIDI input device  . . . 36
101         5.3.11   Getting information about a MIDI port  . . . . . . .  31         6.3.10. Changing settings of MIDI input devices  . . . . . . . 38
102         5.3.12   Getting information about specific MIDI port         6.3.11. Getting information about a MIDI port  . . . . . . . . 38
103                  parameter  . . . . . . . . . . . . . . . . . . . . .  32         6.3.12. Getting information about specific MIDI port
104         5.3.13   Changing settings of MIDI input ports  . . . . . . .  33                 parameter  . . . . . . . . . . . . . . . . . . . . . . 39
105       5.4  Configuring sampler channels . . . . . . . . . . . . . . .  34         6.3.13. Changing settings of MIDI input ports  . . . . . . . . 41
106         5.4.1  Loading an instrument  . . . . . . . . . . . . . . . .  34       6.4.  Configuring sampler channels . . . . . . . . . . . . . . . 42
107         5.4.2  Loading a sampler engine . . . . . . . . . . . . . . .  35         6.4.1.  Loading an instrument  . . . . . . . . . . . . . . . . 42
108    
109    
110    
111  Schoenebeck            Expires November 19, 2005                [Page 2]  Schoenebeck               Expires May 30, 2007                  [Page 2]
112    
113  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
114    
115    
116         5.4.3  Getting all created sampler channel count  . . . . . .  36         6.4.2.  Loading a sampler engine . . . . . . . . . . . . . . . 43
117         5.4.4  Getting all created sampler channel list . . . . . . .  36         6.4.3.  Getting all created sampler channel count  . . . . . . 44
118         5.4.5  Adding a new sampler channel . . . . . . . . . . . . .  36         6.4.4.  Getting all created sampler channel list . . . . . . . 44
119         5.4.6  Removing a sampler channel . . . . . . . . . . . . . .  37         6.4.5.  Adding a new sampler channel . . . . . . . . . . . . . 44
120         5.4.7  Getting amount of available engines  . . . . . . . . .  38         6.4.6.  Removing a sampler channel . . . . . . . . . . . . . . 45
121         5.4.8  Getting all available engines  . . . . . . . . . . . .  38         6.4.7.  Getting amount of available engines  . . . . . . . . . 46
122         5.4.9  Getting information about an engine  . . . . . . . . .  38         6.4.8.  Getting all available engines  . . . . . . . . . . . . 46
123         5.4.10   Getting sampler channel information  . . . . . . . .  39         6.4.9.  Getting information about an engine  . . . . . . . . . 47
124         5.4.11   Current number of active voices  . . . . . . . . . .  41         6.4.10. Getting sampler channel information  . . . . . . . . . 48
125         5.4.12   Current number of active disk streams  . . . . . . .  41         6.4.11. Current number of active voices  . . . . . . . . . . . 51
126         5.4.13   Current fill state of disk stream buffers  . . . . .  42         6.4.12. Current number of active disk streams  . . . . . . . . 51
127         5.4.14   Setting audio output device  . . . . . . . . . . . .  42         6.4.13. Current fill state of disk stream buffers  . . . . . . 51
128         5.4.15   Setting audio output type  . . . . . . . . . . . . .  43         6.4.14. Setting audio output device  . . . . . . . . . . . . . 52
129         5.4.16   Setting audio output channel . . . . . . . . . . . .  44         6.4.15. Setting audio output type  . . . . . . . . . . . . . . 53
130         5.4.17   Setting MIDI input device  . . . . . . . . . . . . .  44         6.4.16. Setting audio output channel . . . . . . . . . . . . . 54
131         5.4.18   Setting MIDI input type  . . . . . . . . . . . . . .  45         6.4.17. Setting MIDI input device  . . . . . . . . . . . . . . 55
132         5.4.19   Setting MIDI input port  . . . . . . . . . . . . . .  45         6.4.18. Setting MIDI input type  . . . . . . . . . . . . . . . 55
133         5.4.20   Setting MIDI input channel . . . . . . . . . . . . .  46         6.4.19. Setting MIDI input port  . . . . . . . . . . . . . . . 56
134         5.4.21   Setting channel volume . . . . . . . . . . . . . . .  46         6.4.20. Setting MIDI input channel . . . . . . . . . . . . . . 57
135         5.4.22   Resetting a sampler channel  . . . . . . . . . . . .  47         6.4.21. Setting channel volume . . . . . . . . . . . . . . . . 57
136       5.5  Controlling connection . . . . . . . . . . . . . . . . . .  48         6.4.22. Muting a sampler channel . . . . . . . . . . . . . . . 58
137         5.5.1  Register front-end for receiving event messages  . . .  48         6.4.23. Soloing a sampler channel  . . . . . . . . . . . . . . 59
138         5.5.2  Unregister front-end for not receiving event         6.4.24. Resetting a sampler channel  . . . . . . . . . . . . . 59
139                messages . . . . . . . . . . . . . . . . . . . . . . .  48       6.5.  Controlling connection . . . . . . . . . . . . . . . . . . 60
140         5.5.3  Enable or disable echo of commands . . . . . . . . . .  49         6.5.1.  Register front-end for receiving event messages  . . . 60
141         5.5.4  Close client connection  . . . . . . . . . . . . . . .  49         6.5.2.  Unregister front-end for not receiving event
142       5.6  Global commands  . . . . . . . . . . . . . . . . . . . . .  50                 messages . . . . . . . . . . . . . . . . . . . . . . . 61
143         5.6.1  Reset sampler  . . . . . . . . . . . . . . . . . . . .  50         6.5.3.  Enable or disable echo of commands . . . . . . . . . . 62
144     6.   Command Syntax . . . . . . . . . . . . . . . . . . . . . . .  51         6.5.4.  Close client connection  . . . . . . . . . . . . . . . 62
145     7.   Events . . . . . . . . . . . . . . . . . . . . . . . . . . .  52       6.6.  Global commands  . . . . . . . . . . . . . . . . . . . . . 62
146       7.1  Number of sampler channels changed . . . . . . . . . . . .  52         6.6.1.  Current number of active voices  . . . . . . . . . . . 62
147       7.2  Number of active voices changed  . . . . . . . . . . . . .  52         6.6.2.  Maximum amount of active voices  . . . . . . . . . . . 63
148       7.3  Number of active disk streams changed  . . . . . . . . . .  52         6.6.3.  Reset sampler  . . . . . . . . . . . . . . . . . . . . 63
149       7.4  Disk stream buffer fill state changed  . . . . . . . . . .  53         6.6.4.  General sampler informations . . . . . . . . . . . . . 63
150       7.5  Channel information changed  . . . . . . . . . . . . . . .  53       6.7.  MIDI Instrument Mapping  . . . . . . . . . . . . . . . . . 64
151       7.6  Miscellaneous and debugging events . . . . . . . . . . . .  53         6.7.1.  Create or replace a MIDI instrument map entry  . . . . 64
152     8.   Security Considerations  . . . . . . . . . . . . . . . . . .  55         6.7.2.  Getting ammount of MIDI instrument map entries . . . . 67
153     9.   Acknowledgments  . . . . . . . . . . . . . . . . . . . . . .  56         6.7.3.  Getting indeces of all MIDI instrument map entries . . 67
154     10.  References . . . . . . . . . . . . . . . . . . . . . . . . .  56         6.7.4.  Remove an entry from the MIDI instrument map . . . . . 68
155          Author's Address . . . . . . . . . . . . . . . . . . . . . .  56         6.7.5.  Get current settings of MIDI instrument map entry  . . 69
156          Intellectual Property and Copyright Statements . . . . . . .  57         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    
165    
166    
167    Schoenebeck               Expires May 30, 2007                  [Page 3]
168    
169    Internet-Draft        LinuxSampler Control Protocol        November 2006
170    
171    
172         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    
# Line 164  Internet-Draft       LinuxSampler Contro Line 197  Internet-Draft       LinuxSampler Contro
197    
198    
199    
200  Schoenebeck            Expires November 19, 2005                [Page 3]  
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              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
226    
227    
228  1.  Requirements notation  1.  Requirements notation
# Line 178  Internet-Draft       LinuxSampler Contro Line 234  Internet-Draft       LinuxSampler Contro
234     This protocol is always case-sensitive if not explicitly claimed the     This protocol is always case-sensitive if not explicitly claimed the
235     opposite.     opposite.
236    
237     In examples, "C:" and "S:" indicate lines sent by the client     In examples, "C:" and "S:" indicate lines sent by the client (front-
238     (front-end) and server (LinuxSampler) respectively.  Lines in     end) and server (LinuxSampler) respectively.  Lines in examples must
239     examples must be interpreted as every line being CRLF terminated     be interpreted as every line being CRLF terminated (carriage return
240     (carriage return character followed by line feed character as defined     character followed by line feed character as defined in the ASCII
241     in the ASCII standard), thus the following example:     standard), thus the following example:
242    
243        C: "some line"        C: "some line"
244    
245           "another line"           "another line"
246    
247     must actually be interpreted as client sending the following message:     must actually be interpreted as client sending the following message:
# Line 203  Internet-Draft       LinuxSampler Contro Line 260  Internet-Draft       LinuxSampler Contro
260     sequence scenario:     sequence scenario:
261    
262     o  server sending message "a"     o  server sending message "a"
263    
264     o  followed by a delay (pause) with arbitrary duration     o  followed by a delay (pause) with arbitrary duration
265    
266     o  followed by server sending message "bcd<CR>"     o  followed by server sending message "bcd<CR>"
267    
268     o  again followed by a delay (pause) with arbitrary duration     o  again followed by a delay (pause) with arbitrary duration
269    
270     o  followed by server sending the message "<LF>"     o  followed by server sending the message "<LF>"
271    
272     where again <CR> and <LF> symbolize the carriage return and line feed     where again <CR> and <LF> symbolize the carriage return and line feed
# Line 215  Internet-Draft       LinuxSampler Contro Line 276  Internet-Draft       LinuxSampler Contro
276    
277    
278    
279    Schoenebeck               Expires May 30, 2007                  [Page 5]
280    
281    Internet-Draft        LinuxSampler Control Protocol        November 2006
282    
283    
284    2.  Versioning of this specification
285    
286       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    
306       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       frontend can use the "GET SERVER INFO" (Section 6.6.4) command to get
311       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  Schoenebeck            Expires November 19, 2005                [Page 4]  
329    
330    
331    
332    
333    
334    
335    Schoenebeck               Expires May 30, 2007                  [Page 6]
336    
337  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
338    
339    
340  2.  Introduction  3.  Introduction
341    
342     LinuxSampler is a so called software sampler application capable to     LinuxSampler is a so called software sampler application capable to
343     playback audio samples from a computer's Random Access Memory (RAM)     playback audio samples from a computer's Random Access Memory (RAM)
# Line 235  Internet-Draft       LinuxSampler Contro Line 347  Internet-Draft       LinuxSampler Contro
347     virtual channels which will be referred in this document as "sampler     virtual channels which will be referred in this document as "sampler
348     channels".  The channels are in such way virtual as they can be     channels".  The channels are in such way virtual as they can be
349     connected to an arbitrary MIDI input method and arbitrary MIDI     connected to an arbitrary MIDI input method and arbitrary MIDI
350     channel (e.g.  sampler channel 17 could be connected to an ALSA     channel (e.g. sampler channel 17 could be connected to an ALSA
351     sequencer device 64:0 and listening to MIDI channel 1 there).  Each     sequencer device 64:0 and listening to MIDI channel 1 there).  Each
352     sampler engine will be assigned an own instance of one of the     sampler channel will be associated with an instance of one of the
353     available sampler engines (e.g.  GigEngine, DLSEngine).  The audio     available sampler engines (e.g.  GigEngine, DLSEngine).  The audio
354     output of each sampler channel can be routed to an arbitrary audio     output of each sampler channel can be routed to an arbitrary audio
355     output method (ALSA / JACK) and an arbitrary audio output channel     output method (ALSA / JACK) and an arbitrary audio output channel
# Line 276  Internet-Draft       LinuxSampler Contro Line 388  Internet-Draft       LinuxSampler Contro
388    
389    
390    
391  Schoenebeck            Expires November 19, 2005                [Page 5]  Schoenebeck               Expires May 30, 2007                  [Page 7]
392    
393  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
394    
395    
396  3.  Focus of this protocol  4.  Focus of this protocol
397    
398     Main focus of this protocol is to provide a way to configure a     Main focus of this protocol is to provide a way to configure a
399     running LinuxSampler instance and to retrieve information about it.     running LinuxSampler instance and to retrieve information about it.
# Line 332  Internet-Draft       LinuxSampler Contro Line 444  Internet-Draft       LinuxSampler Contro
444    
445    
446    
447  Schoenebeck            Expires November 19, 2005                [Page 6]  Schoenebeck               Expires May 30, 2007                  [Page 8]
448    
449  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
450    
451    
452  4.  Communication Overview  5.  Communication Overview
453    
454     There are two distinct methods of communication between a running     There are two distinct methods of communication between a running
455     instance of LinuxSampler and one or more control applications, so     instance of LinuxSampler and one or more control applications, so
# Line 349  Internet-Draft       LinuxSampler Contro Line 461  Internet-Draft       LinuxSampler Contro
461     more effort to be implemented in the front-end application.  The two     more effort to be implemented in the front-end application.  The two
462     communication methods will be described next.     communication methods will be described next.
463    
464  4.1  Request/response communication method  5.1.  Request/response communication method
465    
466     This simple communication method is based on TCP.  The front-end     This simple communication method is based on TCP [RFC793].  The
467     application establishes a TCP connection to the LinuxSampler instance     front-end application establishes a TCP connection to the
468     on a certain host system.  Then the front-end application will send     LinuxSampler instance on a certain host system.  Then the front-end
469     certain ASCII based commands as defined in this document (every     application will send certain ASCII based commands as defined in this
470     command line must be CRLF terminated - see "Conventions used in this     document (every command line must be CRLF terminated - see
471     document" at the beginning of this document) and the LinuxSampler     "Conventions used in this document" at the beginning of this
472     application will response after a certain process time with an     document) and the LinuxSampler application will response after a
473     appropriate ASCII based answer, also as defined in this document.  So     certain process time with an appropriate ASCII based answer, also as
474     this TCP communication is simply based on query and answer paradigm.     defined in this document.  So this TCP communication is simply based
475     That way LinuxSampler is only able to answer on queries from     on query and answer paradigm.  That way LinuxSampler is only able to
476     front-ends, but not able to automatically send messages to the client     answer on queries from front-ends, but not able to automatically send
477     if it's not asked to.  The fronted should not reconnect to     messages to the client if it's not asked to.  The fronted should not
478     LinuxSampler for every single command, instead it should keep the     reconnect to LinuxSampler for every single command, instead it should
479     connection established and simply resend message(s) for subsequent     keep the connection established and simply resend message(s) for
480     commands.  To keep information in the front-end up-to-date the     subsequent commands.  To keep information in the front-end up-to-date
481     front-end has to periodically send new requests to get the current     the front-end has to periodically send new requests to get the
482     information from the LinuxSampler instance.  This is often referred     current information from the LinuxSampler instance.  This is often
483     to as "polling".  While polling is simple to implement and may be OK     referred to as "polling".  While polling is simple to implement and
484     to use in some cases, there may be disadvantages to polling such as     may be OK to use in some cases, there may be disadvantages to polling
485     network traffic overhead and information being out of date.  It is     such as network traffic overhead and information being out of date.
486     possible for a client or several clients to open more than one     It is possible for a client or several clients to open more than one
487     connection to the server at the same time.  It is also possible to     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     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     those requests are sent over the same connection server MUST execute
# Line 388  Internet-Draft       LinuxSampler Contro Line 500  Internet-Draft       LinuxSampler Contro
500    
501    
502    
503  Schoenebeck            Expires November 19, 2005                [Page 7]  Schoenebeck               Expires May 30, 2007                  [Page 9]
504    
505  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
506    
507    
508  4.1.1  Result format  5.1.1.  Result format
509    
510     Result set could be one of the following types:     Result set could be one of the following types:
511    
512     1.  Normal     1.  Normal
513    
514     2.  Warning     2.  Warning
515    
516     3.  Error     3.  Error
517    
518     Warning and Error result sets MUST be single line and have the     Warning and Error result sets MUST be single line and have the
519     following format:     following format:
520    
521     o  "WRN:<warning-code>:<warning-message>"     o  "WRN:<warning-code>:<warning-message>"
522    
523     o  "ERR:<error-code>:<error-message>"     o  "ERR:<error-code>:<error-message>"
524    
525     Where <warning-code> and <error-code> are numeric unique identifiers     Where <warning-code> and <error-code> are numeric unique identifiers
# Line 414  Internet-Draft       LinuxSampler Contro Line 529  Internet-Draft       LinuxSampler Contro
529     Examples:     Examples:
530    
531        C: "LOAD INSTRUMENT '/home/me/Boesendorfer24bit.gig" 0 0        C: "LOAD INSTRUMENT '/home/me/Boesendorfer24bit.gig" 0 0
532    
533        S: "WRN:32:This is a 24 bit patch which is not supported natively        S: "WRN:32:This is a 24 bit patch which is not supported natively
534        yet."        yet."
535    
536        C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA EAR"        C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA EAR"
537    
538        S: "ERR:3456:Audio output driver 'ALSA' does not have a parameter        S: "ERR:3456:Audio output driver 'ALSA' does not have a parameter
539        'EAR'."        'EAR'."
540    
541        C: "GET AUDIO_OUTPUT_DEVICE INFO 123456"        C: "GET AUDIO_OUTPUT_DEVICE INFO 123456"
542    
543        S: "ERR:9:There is no audio output device with index 123456."        S: "ERR:9:There is no audio output device with index 123456."
544    
545     Normal result sets could be:     Normal result sets could be:
546    
547     1.  Empty     1.  Empty
548    
549     2.  Single line     2.  Single line
550    
551     3.  Multi-line     3.  Multi-line
552    
553     Empty result set is issued when the server only needed to acknowledge     Empty result set is issued when the server only needed to acknowledge
554     the fact that the request was received and it was processed     the fact that the request was received and it was processed
555     successfully and no additional information is available.  This result     successfully and no additional information is available.  This result
    set has the following format:  
556    
       "OK"  
557    
    Example:  
558    
559        C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 CHANNELS=4"  Schoenebeck               Expires May 30, 2007                 [Page 10]
560    
561    Internet-Draft        LinuxSampler Control Protocol        November 2006
562    
563    
564       set has the following format:
565    
566          "OK"
567    
568  Schoenebeck            Expires November 19, 2005                [Page 8]     Example:
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
569    
570          C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 CHANNELS=4"
571    
572        S: "OK"        S: "OK"
573    
# Line 461  Internet-Draft       LinuxSampler Contro Line 581  Internet-Draft       LinuxSampler Contro
581     Example:     Example:
582    
583        C: "GET AUDIO_OUTPUT_DEVICE INFO 0"        C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
584    
585        S: "DRIVER: ALSA"        S: "DRIVER: ALSA"
586    
587           "CHANNELS: 2"           "CHANNELS: 2"
588    
589           "SAMPLERATE: 44100"           "SAMPLERATE: 44100"
590    
591           "ACTIVE: true"           "ACTIVE: true"
592    
593           "FRAGMENTS: 2"           "FRAGMENTS: 2"
594    
595           "FRAGMENTSIZE: 128"           "FRAGMENTSIZE: 128"
596    
597           "CARD: '0,0'"           "CARD: '0,0'"
598    
599           "."           "."
600    
601     In addition to above mentioned formats, warnings and empty result     In addition to above mentioned formats, warnings and empty result
# Line 475  Internet-Draft       LinuxSampler Contro Line 603  Internet-Draft       LinuxSampler Contro
603     respectively:     respectively:
604    
605     o  "WRN[<index>]:<warning-code>:<warning-message>"     o  "WRN[<index>]:<warning-code>:<warning-message>"
606    
607     o  "OK[<index>]"     o  "OK[<index>]"
608    
609     where <index> is command specific and is used to indicate channel     where <index> is command specific and is used to indicate channel
610     number that the result set was related to or other integer value.     number that the result set was related to or other integer value.
611    
612    
613    
614    
615    Schoenebeck               Expires May 30, 2007                 [Page 11]
616    
617    Internet-Draft        LinuxSampler Control Protocol        November 2006
618    
619    
620     Each line of the result set MUST end with <CRLF>.     Each line of the result set MUST end with <CRLF>.
621    
622     Examples:     Examples:
623    
624        C: "ADD CHANNEL"        C: "ADD CHANNEL"
625    
626        S: "OK[12]"        S: "OK[12]"
627    
628        C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"        C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"
629    
630        S: "WRN[0]:32:Sample rate not supported, using 44100 instead."        S: "WRN[0]:32:Sample rate not supported, using 44100 instead."
631    
632  4.2  Subscribe/notify communication method  5.2.  Subscribe/notify communication method
633    
634     This more sophisticated communication method is actually only an     This more sophisticated communication method is actually only an
635     extension of the simple request/response communication method.  The     extension of the simple request/response communication method.  The
636     front-end still uses a TCP connection and sends the same commands on     front-end still uses a TCP connection and sends the same commands on
637     the TCP connection.  Two extra commands are SUBSCRIBE and UNSUBSCRIBE     the TCP connection.  Two extra commands are SUBSCRIBE and UNSUBSCRIBE
638     commands that allow a client to tell the server that it is interested     commands that allow a client to tell the server that it is interested
   
   
   
 Schoenebeck            Expires November 19, 2005                [Page 9]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
639     in receiving notifications about certain events as they happen on the     in receiving notifications about certain events as they happen on the
640     server.  The SUBSCRIBE command has the following syntax:     server.  The SUBSCRIBE command has the following syntax:
641    
# Line 527  Internet-Draft       LinuxSampler Contro Line 658  Internet-Draft       LinuxSampler Contro
658    
659     1.  Events MUST NOT be sent to any client who has not issued an     1.  Events MUST NOT be sent to any client who has not issued an
660         appropriate SUBSCRIBE command.         appropriate SUBSCRIBE command.
661    
662     2.  Events MUST only be sent using the same connection that was used     2.  Events MUST only be sent using the same connection that was used
663         to subscribe to them.         to subscribe to them.
664    
665     3.  When response is being sent to the client, event MUST be inserted     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         in the stream before or after the response, but NOT in the
667         middle.  Same is true about the response.  It should never be         middle.  Same is true about the response.  It should never be
668    
669    
670    
671    Schoenebeck               Expires May 30, 2007                 [Page 12]
672    
673    Internet-Draft        LinuxSampler Control Protocol        November 2006
674    
675    
676         inserted in the middle of the event message as well as any other         inserted in the middle of the event message as well as any other
677         response.         response.
678    
# Line 542  Internet-Draft       LinuxSampler Contro Line 683  Internet-Draft       LinuxSampler Contro
683    
684     where <event-id> will be replace by the respective event that client     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     is no longer interested in receiving.  For a list of supported events
686     see Section 7.     see Section 8.
687    
688     Example: the fill states of disk stream buffers have changed on     Example: the fill states of disk stream buffers have changed on
689     sampler channel 4 and the LinuxSampler instance will react by sending     sampler channel 4 and the LinuxSampler instance will react by sending
# Line 554  Internet-Draft       LinuxSampler Contro Line 695  Internet-Draft       LinuxSampler Contro
695     channel 4, where the stream with ID "35" is filled by 62%, stream     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%.     with ID 33 is filled by 80% and stream with ID 37 is filled by 98%.
697    
   
   
 Schoenebeck            Expires November 19, 2005               [Page 10]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
698     Clients may choose to open more than one connection to the server and     Clients may choose to open more than one connection to the server and
699     use some connections to receive notifications while using other     use some connections to receive notifications while using other
700     connections to issue commands to the back-end.  This is entirely     connections to issue commands to the back-end.  This is entirely
# Line 590  Internet-Draft       LinuxSampler Contro Line 724  Internet-Draft       LinuxSampler Contro
724    
725    
726    
727    Schoenebeck               Expires May 30, 2007                 [Page 13]
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 11]  
728    
729  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
730    
731    
732  5.  Description for control commands  6.  Description for control commands
733    
734     This chapter will describe the available control commands that can be     This chapter will describe the available control commands that can be
735     sent on the TCP connection in detail.  Some certain commands (e.g.     sent on the TCP connection in detail.  Some certain commands (e.g.
736     "GET CHANNEL INFO" (Section 5.4.10) or "GET ENGINE INFO" (Section     "GET CHANNEL INFO" (Section 6.4.10) or "GET ENGINE INFO"
737     5.4.9)) lead to multiple-line responses.  In this case LinuxSampler     (Section 6.4.9)) lead to multiple-line responses.  In this case
738     signals the end of the response by a "." (single dot) line.     LinuxSampler signals the end of the response by a "." (single dot)
739       line.
740    
741  5.1  Ignored lines and comments  6.1.  Ignored lines and comments
742    
743     White lines, that is lines which only contain space and tabulator     White lines, that is lines which only contain space and tabulator
744     characters, and lines that start with a "#" character are ignored,     characters, and lines that start with a "#" character are ignored,
745     thus it's possible for example to group commands and to place     thus it's possible for example to group commands and to place
746     comments in a LSCP script file.     comments in a LSCP script file.
747    
748  5.2  Configuring audio drivers  6.2.  Configuring audio drivers
749    
750     Instances of drivers in LinuxSampler are called devices.  You can use     Instances of drivers in LinuxSampler are called devices.  You can use
751     multiple audio devices simultaneously, e.g.  to output the sound of     multiple audio devices simultaneously, e.g. to output the sound of
752     one sampler channel using the ALSA audio output driver, and on     one sampler channel using the ALSA audio output driver, and on
753     another sampler channel you might want to use the JACK audio output     another sampler channel you might want to use the JACK audio output
754     driver.  For particular audio output systems it's also possible to     driver.  For particular audio output systems it's also possible to
755     create several devices of the same audio output driver, e.g.  two     create several devices of the same audio output driver, e.g. two
756     separate ALSA audio output devices for using two different sound     separate ALSA audio output devices for using two different sound
757     cards at the same time.  This chapter describes all commands to     cards at the same time.  This chapter describes all commands to
758     configure LinuxSampler's audio output devices and their parameters.     configure LinuxSampler's audio output devices and their parameters.
# Line 649  Internet-Draft       LinuxSampler Contro Line 762  Internet-Draft       LinuxSampler Contro
762     values have to be obtained at runtime.  This makes the protocol a bit     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     abstract, but has the advantage, that front-ends can be written
764     independently of what drivers are currently implemented and what     independently of what drivers are currently implemented and what
765     parameters these drivers are actually offering.  This means     parameters these drivers are actually offering.  This means front-
766     front-ends can even handle drivers which are implemented somewhere in     ends can even handle drivers which are implemented somewhere in
767     future without modifying the front-end at all.     future without modifying the front-end at all.
768    
769     Note: examples in this chapter showing particular parameters of     Note: examples in this chapter showing particular parameters of
# Line 661  Internet-Draft       LinuxSampler Contro Line 774  Internet-Draft       LinuxSampler Contro
774     retrieve what parameters drivers are offering, how to retrieve their     retrieve what parameters drivers are offering, how to retrieve their
775     possible values, etc.     possible values, etc.
776    
777  5.2.1  Getting amount of available audio output drivers  6.2.1.  Getting amount of available audio output drivers
778    
779     Use the following command to get the number of audio output drivers     Use the following command to get the number of audio output drivers
    currently available for the LinuxSampler instance:  
780    
781    
782    
783  Schoenebeck            Expires November 19, 2005               [Page 12]  Schoenebeck               Expires May 30, 2007                 [Page 14]
784    
785  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
786    
787    
788       currently available for the LinuxSampler instance:
789    
790        GET AVAILABLE_AUDIO_OUTPUT_DRIVERS        GET AVAILABLE_AUDIO_OUTPUT_DRIVERS
791    
# Line 683  Internet-Draft       LinuxSampler Contro Line 797  Internet-Draft       LinuxSampler Contro
797     Example:     Example:
798    
799        C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"        C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
800    
801        S: "2"        S: "2"
802    
803  5.2.2  Getting all available audio output drivers  6.2.2.  Getting all available audio output drivers
804    
805     Use the following command to list all audio output drivers currently     Use the following command to list all audio output drivers currently
806     available for the LinuxSampler instance:     available for the LinuxSampler instance:
# Line 700  Internet-Draft       LinuxSampler Contro Line 815  Internet-Draft       LinuxSampler Contro
815     Example:     Example:
816    
817        C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"        C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"
818    
819        S: "ALSA,JACK"        S: "ALSA,JACK"
820    
821  5.2.3  Getting information about a specific audio output driver  6.2.3.  Getting information about a specific audio output driver
822    
823     Use the following command to get detailed information about a     Use the following command to get detailed information about a
824     specific audio output driver:     specific audio output driver:
# Line 710  Internet-Draft       LinuxSampler Contro Line 826  Internet-Draft       LinuxSampler Contro
826        GET AUDIO_OUTPUT_DRIVER INFO <audio-output-driver>        GET AUDIO_OUTPUT_DRIVER INFO <audio-output-driver>
827    
828     Where <audio-output-driver> is the name of the audio output driver,     Where <audio-output-driver> is the name of the audio output driver,
829     returned by the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 5.2.2)     returned by the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2)
830     command.     command.
831    
832     Possible Answers:     Possible Answers:
833    
       LinuxSampler will answer by sending a <CRLF> separated list.  Each  
       answer line begins with the information category name followed by  
       a colon and then a space character <SP> and finally the info  
       character string to that info category.  At the moment the  
       following information categories are defined:  
834    
835    
836    
837    
838  Schoenebeck            Expires November 19, 2005               [Page 13]  
839    Schoenebeck               Expires May 30, 2007                 [Page 15]
840    
841  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
842    
843    
844          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           DESCRIPTION -           DESCRIPTION -
853    
854              character string describing the audio output driver              character string describing the audio output driver
855    
856           VERSION -           VERSION -
857    
858              character string reflecting the driver's version              character string reflecting the driver's version
859    
860           PARAMETERS -           PARAMETERS -
861    
862              comma separated list of all parameters available for the              comma separated list of all parameters available for the
863              given audio output driver, at least parameters 'channels',              given audio output driver, at least parameters 'channels',
864              'samplerate' and 'active' are offered by all audio output              'samplerate' and 'active' are offered by all audio output
865              drivers              drivers
866    
867        The mentioned fields above don't have to be in particular order.        The mentioned fields above don't have to be in particular order.
868    
869     Example:     Example:
870    
871        C: "GET AUDIO_OUTPUT_DRIVER INFO ALSA"        C: "GET AUDIO_OUTPUT_DRIVER INFO ALSA"
872    
873        S: "DESCRIPTION: Advanced Linux Sound Architecture"        S: "DESCRIPTION: Advanced Linux Sound Architecture"
874    
875           "VERSION: 1.0"           "VERSION: 1.0"
876    
877           "PARAMETERS: DRIVER,CHANNELS,SAMPLERATE,ACTIVE,FRAGMENTS,           "PARAMETERS: DRIVER,CHANNELS,SAMPLERATE,ACTIVE,FRAGMENTS,
878        FRAGMENTSIZE,CARD"        FRAGMENTSIZE,CARD"
879    
880           "."           "."
881    
882  5.2.4  Getting information about specific audio output driver parameter  6.2.4.  Getting information about specific audio output driver parameter
883    
884     Use the following command to get detailed information about a     Use the following command to get detailed information about a
885     specific audio output driver parameter:     specific audio output driver parameter:
# Line 758  Internet-Draft       LinuxSampler Contro Line 887  Internet-Draft       LinuxSampler Contro
887        GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO <audio> <prm> [<deplist>]        GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO <audio> <prm> [<deplist>]
888    
889     Where <audio> is the name of the audio output driver as returned by     Where <audio> is the name of the audio output driver as returned by
890     the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 5.2.2) command,     the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2) command,
891     <prm> a specific parameter name for which information should be     <prm> a specific parameter name for which information should be
892     obtained (as returned by the "GET AUDIO_OUTPUT_DRIVER INFO" (Section  
893     5.2.3) command) and <deplist> is an optional list of parameters on  
894     which the sought parameter <prm> depends on, <deplist> is a list of  
895     key-value pairs in form of "key1=val1 key2=val2 ...", where character  Schoenebeck               Expires May 30, 2007                 [Page 16]
896     string values are encapsulated into apostrophes (').  Arguments given  
897     with <deplist> which are not dependency parameters of <prm> will be  Internet-Draft        LinuxSampler Control Protocol        November 2006
898     ignored, means the front-end application can simply put all  
899     parameters into <deplist> with the values already selected by the  
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     user.     user.
909    
910     Possible Answers:     Possible Answers:
# Line 777  Internet-Draft       LinuxSampler Contro Line 914  Internet-Draft       LinuxSampler Contro
914        a colon and then a space character <SP> and finally the info        a colon and then a space character <SP> and finally the info
915        character string to that info category.  There are information        character string to that info category.  There are information
916        which is always returned, independently of the given driver        which is always returned, independently of the given driver
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 14]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
917        parameter and there are optional information which is only shown        parameter and there are optional information which is only shown
918        dependently to given driver parameter.  At the moment the        dependently to given driver parameter.  At the moment the
919        following information categories are defined:        following information categories are defined:
920    
921        TYPE -        TYPE -
922    
923           either "BOOL" for boolean value(s) or "INT" for integer           either "BOOL" for boolean value(s) or "INT" for integer
924           value(s) or "FLOAT" for dotted number(s) or "STRING" for           value(s) or "FLOAT" for dotted number(s) or "STRING" for
925           character string(s) (always returned, no matter which driver           character string(s) (always returned, no matter which driver
926           parameter)           parameter)
927    
928        DESCRIPTION -        DESCRIPTION -
929    
930           arbitrary text describing the purpose of the parameter (always           arbitrary text describing the purpose of the parameter (always
931           returned, no matter which driver parameter)           returned, no matter which driver parameter)
932    
933        MANDATORY -        MANDATORY -
934    
935           either true or false, defines if this parameter must be given           either true or false, defines if this parameter must be given
936           when the device is to be created with the 'CREATE           when the device is to be created with the 'CREATE
937           AUDIO_OUTPUT_DEVICE' (Section 5.2.5) command (always returned,           AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command (always returned,
938           no matter which driver parameter)           no matter which driver parameter)
939    
940        FIX -        FIX -
941    
942           either true or false, if false then this parameter can be           either true or false, if false then this parameter can be
943           changed at any time, once the device is created by the 'CREATE           changed at any time, once the device is created by the 'CREATE
944           AUDIO_OUTPUT_DEVICE' (Section 5.2.5) command (always returned,           AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command (always returned,
945           no matter which driver parameter)           no matter which driver parameter)
946    
947    
948    
949    
950    
951    Schoenebeck               Expires May 30, 2007                 [Page 17]
952    
953    Internet-Draft        LinuxSampler Control Protocol        November 2006
954    
955    
956        MULTIPLICITY -        MULTIPLICITY -
957    
958           either true or false, defines if this parameter allows only one           either true or false, defines if this parameter allows only one
959           value or a list of values, where true means multiple values and           value or a list of values, where true means multiple values and
960           false only a single value allowed (always returned, no matter           false only a single value allowed (always returned, no matter
961           which driver parameter)           which driver parameter)
962    
963        DEPENDS -        DEPENDS -
964    
965           comma separated list of parameters this parameter depends on,           comma separated list of parameters this parameter depends on,
966           means the values for fields 'DEFAULT', 'RANGE_MIN', 'RANGE_MAX'           means the values for fields 'DEFAULT', 'RANGE_MIN', 'RANGE_MAX'
967           and 'POSSIBILITIES' might depend on these listed parameters,           and 'POSSIBILITIES' might depend on these listed parameters,
# Line 822  Internet-Draft       LinuxSampler Contro Line 971  Internet-Draft       LinuxSampler Contro
971           possible values for 'samplerate' depends on the sound card           possible values for 'samplerate' depends on the sound card
972           which can be chosen by the 'card' parameter (optionally           which can be chosen by the 'card' parameter (optionally
973           returned, dependent to driver parameter)           returned, dependent to driver parameter)
974    
975        DEFAULT -        DEFAULT -
976    
977           reflects the default value for this parameter which is used           reflects the default value for this parameter which is used
978           when the device is created and not explicitly given with the           when the device is created and not explicitly given with the
979           'CREATE AUDIO_OUTPUT_DEVICE' (Section 5.2.5) command, in case           'CREATE AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command, in case
980           of MULTIPLCITY=true, this is a comma separated list, that's why           of MULTIPLCITY=true, this is a comma separated list, that's why
981           character strings are encapsulated into apostrophes (')           character strings are encapsulated into apostrophes (')
982           (optionally returned, dependent to driver parameter)           (optionally returned, dependent to driver parameter)
983    
984        RANGE_MIN -        RANGE_MIN -
985    
986           defines lower limit of the allowed value range for this           defines lower limit of the allowed value range for this
987           parameter, can be an integer value as well as a dotted number,           parameter, can be an integer value as well as a dotted number,
988           this parameter is often used in conjunction with RANGE_MAX, but           this parameter is often used in conjunction with RANGE_MAX, but
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 15]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
989           may also appear without (optionally returned, dependent to           may also appear without (optionally returned, dependent to
990           driver parameter)           driver parameter)
991    
992        RANGE_MAX -        RANGE_MAX -
993    
994           defines upper limit of the allowed value range for this           defines upper limit of the allowed value range for this
995           parameter, can be an integer value as well as a dotted number,           parameter, can be an integer value as well as a dotted number,
996           this parameter is often used in conjunction with RANGE_MIN, but           this parameter is often used in conjunction with RANGE_MIN, but
997           may also appear without (optionally returned, dependent to           may also appear without (optionally returned, dependent to
998           driver parameter)           driver parameter)
999    
1000        POSSIBILITIES -        POSSIBILITIES -
1001    
1002           comma separated list of possible values for this parameter,           comma separated list of possible values for this parameter,
1003           character strings are encapsulated into apostrophes (optionally           character strings are encapsulated into apostrophes (optionally
1004    
1005    
1006    
1007    Schoenebeck               Expires May 30, 2007                 [Page 18]
1008    
1009    Internet-Draft        LinuxSampler Control Protocol        November 2006
1010    
1011    
1012           returned, dependent to driver parameter)           returned, dependent to driver parameter)
1013    
1014     The mentioned fields above don't have to be in particular order.     The mentioned fields above don't have to be in particular order.
# Line 859  Internet-Draft       LinuxSampler Contro Line 1016  Internet-Draft       LinuxSampler Contro
1016     Examples:     Examples:
1017    
1018        C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA CARD"        C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA CARD"
1019    
1020        S: "DESCRIPTION: sound card to be used"        S: "DESCRIPTION: sound card to be used"
1021    
1022           "TYPE: STRING"           "TYPE: STRING"
1023    
1024           "MANDATORY: false"           "MANDATORY: false"
1025    
1026           "FIX: true"           "FIX: true"
1027    
1028           "MULTIPLICITY: false"           "MULTIPLICITY: false"
1029    
1030           "DEFAULT: '0,0'"           "DEFAULT: '0,0'"
1031    
1032           "POSSIBILITIES: '0,0','1,0','2,0'"           "POSSIBILITIES: '0,0','1,0','2,0'"
1033    
1034           "."           "."
1035    
1036        C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE"        C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE"
1037    
1038        S: "DESCRIPTION: output sample rate in Hz"        S: "DESCRIPTION: output sample rate in Hz"
1039    
1040           "TYPE: INT"           "TYPE: INT"
1041    
1042           "MANDATORY: false"           "MANDATORY: false"
1043    
1044           "FIX: false"           "FIX: false"
1045    
1046           "MULTIPLICITY: false"           "MULTIPLICITY: false"
1047    
1048           "DEPENDS: card"           "DEPENDS: card"
1049    
1050           "DEFAULT: 44100"           "DEFAULT: 44100"
1051    
1052           "."           "."
1053    
1054        C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE        C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE
1055        CARD='0,0'"        CARD='0,0'"
1056    
1057        S: "DESCRIPTION: output sample rate in Hz"        S: "DESCRIPTION: output sample rate in Hz"
1058    
1059    
1060    
1061    
1062    
1063    Schoenebeck               Expires May 30, 2007                 [Page 19]
1064    
1065    Internet-Draft        LinuxSampler Control Protocol        November 2006
1066    
1067    
1068           "TYPE: INT"           "TYPE: INT"
1069    
1070           "MANDATORY: false"           "MANDATORY: false"
          "FIX: false"  
          "MULTIPLICITY: false"  
          "DEPENDS: card"  
          "DEFAULT: 44100"  
          "RANGE_MIN: 22050"  
1071    
1072             "FIX: false"
1073    
1074             "MULTIPLICITY: false"
1075    
1076             "DEPENDS: card"
1077    
1078  Schoenebeck            Expires November 19, 2005               [Page 16]           "DEFAULT: 44100"
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
1079    
1080             "RANGE_MIN: 22050"
1081    
1082           "RANGE_MAX: 96000"           "RANGE_MAX: 96000"
1083    
1084           "."           "."
1085    
1086  5.2.5  Creating an audio output device  6.2.5.  Creating an audio output device
1087    
1088     Use the following command to create a new audio output device for     Use the following command to create a new audio output device for the
1089     the desired audio output system:     desired audio output system:
1090    
1091        CREATE AUDIO_OUTPUT_DEVICE <audio-output-driver> [<param-list>]        CREATE AUDIO_OUTPUT_DEVICE <audio-output-driver> [<param-list>]
1092    
1093     Where <audio-output-driver> should be replaced by the desired audio     Where <audio-output-driver> should be replaced by the desired audio
1094     output system and <param-list> by an optional list of driver specific     output system as returned by the "LIST
1095     parameters in form of "key1=val1 key2=val2 ...", where character     AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2) command and <param-
1096     string values should be encapsulated into apostrophes (').  Note that     list> by an optional list of driver specific parameters in form of
1097     there might be drivers which require parameter(s) to be given with     "key1=val1 key2=val2 ...", where character string values should be
1098     this command.  Use the previously described commands in this chapter     encapsulated into apostrophes (').  Note that there might be drivers
1099     to get this information.     which require parameter(s) to be given with this command.  Use the
1100       previously described commands in this chapter to get this
1101       information.
1102    
1103     Possible Answers:     Possible Answers:
1104    
1105        "OK[<device-id>]" -        "OK[<device-id>]" -
1106    
1107           in case the device was successfully created, where <device-id>           in case the device was successfully created, where <device-id>
1108           is the numerical ID of the new device           is the numerical ID of the new device
1109    
1110        "WRN[<device-id>]:<warning-code>:<warning-message>" -        "WRN[<device-id>]:<warning-code>:<warning-message>" -
1111    
1112           in case the device was created successfully, where <device-id>           in case the device was created successfully, where <device-id>
1113           is the numerical ID of the new device, but there are noteworthy           is the numerical ID of the new device, but there are noteworthy
1114           issue(s) related (e.g.  sound card doesn't support given           issue(s) related (e.g. sound card doesn't support given
1115           hardware parameters and the driver is using fall-back values),           hardware parameters and the driver is using fall-back values),
1116    
1117    
1118    
1119    Schoenebeck               Expires May 30, 2007                 [Page 20]
1120    
1121    Internet-Draft        LinuxSampler Control Protocol        November 2006
1122    
1123    
1124           providing an appropriate warning code and warning message           providing an appropriate warning code and warning message
1125    
1126        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
1127    
1128           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
1129           error message           error message
1130    
1131     Examples:     Examples:
1132    
1133        C: "CREATE AUDIO_OUTPUT_DEVICE ALSA"        C: "CREATE AUDIO_OUTPUT_DEVICE ALSA"
1134    
1135        S: "OK[0]"        S: "OK[0]"
1136    
1137        C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"        C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"
1138    
1139        S: "OK[1]"        S: "OK[1]"
1140    
1141  5.2.6  Destroying an audio output device  6.2.6.  Destroying an audio output device
1142    
1143     Use the following command to destroy a created output device:     Use the following command to destroy a created output device:
1144    
1145        DESTROY AUDIO_OUTPUT_DEVICE <device-id>        DESTROY AUDIO_OUTPUT_DEVICE <device-id>
1146    
1147     Where <device-id> should be replaced by the numerical ID of the audio     Where <device-id> should be replaced by the numerical ID of the audio
1148       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.
 Schoenebeck            Expires November 19, 2005               [Page 17]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
    output device as given by the "CREATE AUDIO_OUTPUT_DEVICE" (Section  
    5.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 5.2.8) command.  
1151    
1152     Possible Answers:     Possible Answers:
1153    
1154        "OK" -        "OK" -
1155    
1156           in case the device was successfully destroyed           in case the device was successfully destroyed
1157    
1158        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
1159    
1160           in case the device was destroyed successfully, but there are           in case the device was destroyed successfully, but there are
1161           noteworthy issue(s) related (e.g.  an audio over ethernet           noteworthy issue(s) related (e.g. an audio over ethernet driver
1162           driver was unloaded but the other host might not be informed           was unloaded but the other host might not be informed about
1163           about this situation), providing an appropriate warning code           this situation), providing an appropriate warning code and
1164           and warning message           warning message
1165    
1166        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
1167    
1168           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
1169           error message           error message
1170    
1171     Example:     Example:
1172    
1173    
1174    
1175    Schoenebeck               Expires May 30, 2007                 [Page 21]
1176    
1177    Internet-Draft        LinuxSampler Control Protocol        November 2006
1178    
1179    
1180        C: "DESTROY AUDIO_OUTPUT_DEVICE 0"        C: "DESTROY AUDIO_OUTPUT_DEVICE 0"
1181    
1182        S: "OK"        S: "OK"
1183    
1184  5.2.7  Getting all created audio output device count  6.2.7.  Getting all created audio output device count
1185    
1186     Use the following command to count all created audio output devices:     Use the following command to count all created audio output devices:
1187    
# Line 989  Internet-Draft       LinuxSampler Contro Line 1195  Internet-Draft       LinuxSampler Contro
1195     Example:     Example:
1196    
1197        C: "GET AUDIO_OUTPUT_DEVICES"        C: "GET AUDIO_OUTPUT_DEVICES"
1198    
1199        S: "4"        S: "4"
1200    
1201  5.2.8  Getting all created audio output device list  6.2.8.  Getting all created audio output device list
1202    
1203     Use the following command to list all created audio output devices:     Use the following command to list all created audio output devices:
1204    
# Line 1002  Internet-Draft       LinuxSampler Contro Line 1209  Internet-Draft       LinuxSampler Contro
1209        LinuxSampler will answer by sending a comma separated list with        LinuxSampler will answer by sending a comma separated list with
1210        the numerical IDs of all audio output devices.        the numerical IDs of all audio output devices.
1211    
   
   
 Schoenebeck            Expires November 19, 2005               [Page 18]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
1212     Example:     Example:
1213    
1214        C: "LIST AUDIO_OUTPUT_DEVICES"        C: "LIST AUDIO_OUTPUT_DEVICES"
1215    
1216        S: "0,1,4,5"        S: "0,1,4,5"
1217    
1218  5.2.9  Getting current settings of an audio output device  6.2.9.  Getting current settings of an audio output device
1219    
1220     Use the following command to get current settings of a specific,     Use the following command to get current settings of a specific,
1221     created audio output device:     created audio output device:
# Line 1022  Internet-Draft       LinuxSampler Contro Line 1223  Internet-Draft       LinuxSampler Contro
1223        GET AUDIO_OUTPUT_DEVICE INFO <device-id>        GET AUDIO_OUTPUT_DEVICE INFO <device-id>
1224    
1225     Where <device-id> should be replaced by numerical ID of the audio     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"     output device as e.g. returned by the "LIST AUDIO_OUTPUT_DEVICES"
1227     (Section 5.2.8) command.     (Section 6.2.8) command.
1228    
1229    
1230    
1231    Schoenebeck               Expires May 30, 2007                 [Page 22]
1232    
1233    Internet-Draft        LinuxSampler Control Protocol        November 2006
1234    
1235    
1236     Possible Answers:     Possible Answers:
1237    
# Line 1036  Internet-Draft       LinuxSampler Contro Line 1244  Internet-Draft       LinuxSampler Contro
1244     (independently of device):     (independently of device):
1245    
1246        DRIVER -        DRIVER -
1247    
1248           identifier of the used audio output driver, as also returned by           identifier of the used audio output driver, as also returned by
1249           the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 5.2.2)           the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2)
1250           command           command
1251    
1252        CHANNELS -        CHANNELS -
1253    
1254           amount of audio output channels this device currently offers           amount of audio output channels this device currently offers
1255    
1256        SAMPLERATE -        SAMPLERATE -
1257    
1258           playback sample rate the device uses           playback sample rate the device uses
1259    
1260        ACTIVE -        ACTIVE -
1261    
1262           either true or false, if false then the audio device is           either true or false, if false then the audio device is
1263           inactive and doesn't output any sound, nor do the sampler           inactive and doesn't output any sound, nor do the sampler
1264           channels connected to this audio device render any audio           channels connected to this audio device render any audio
# Line 1051  Internet-Draft       LinuxSampler Contro Line 1266  Internet-Draft       LinuxSampler Contro
1266     The mentioned fields above don't have to be in particular order.  The     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     fields above are only those fields which are returned by all audio
1268     output devices.  Every audio output driver might have its own,     output devices.  Every audio output driver might have its own,
1269     additional driver specific parameters (see Section 5.2.3) which are     additional driver specific parameters (see Section 6.2.3) which are
1270     also returned by this command.     also returned by this command.
1271    
1272     Example:     Example:
1273    
1274          C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
1275    
1276          S: "DRIVER: ALSA"
1277    
1278             "CHANNELS: 2"
1279    
1280             "SAMPLERATE: 44100"
1281    
1282             "ACTIVE: true"
1283    
1284    
1285    
1286    
1287  Schoenebeck            Expires November 19, 2005               [Page 19]  Schoenebeck               Expires May 30, 2007                 [Page 23]
1288    
1289  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
1290    
1291    
       C: "GET AUDIO_OUTPUT_DEVICE INFO 0"  
       S: "DRIVER: ALSA"  
          "CHANNELS: 2"  
          "SAMPLERATE: 44100"  
          "ACTIVE: true"  
1292           "FRAGMENTS: 2"           "FRAGMENTS: 2"
1293    
1294           "FRAGMENTSIZE: 128"           "FRAGMENTSIZE: 128"
1295    
1296           "CARD: '0,0'"           "CARD: '0,0'"
1297    
1298           "."           "."
1299    
1300  5.2.10  Changing settings of audio output devices  6.2.10.  Changing settings of audio output devices
1301    
1302     Use the following command to alter a specific setting of a created     Use the following command to alter a specific setting of a created
1303     audio output device:     audio output device:
# Line 1083  Internet-Draft       LinuxSampler Contro Line 1305  Internet-Draft       LinuxSampler Contro
1305        SET AUDIO_OUTPUT_DEVICE_PARAMETER <device-id> <key>=<value>        SET AUDIO_OUTPUT_DEVICE_PARAMETER <device-id> <key>=<value>
1306    
1307     Where <device-id> should be replaced by the numerical ID of the audio     Where <device-id> should be replaced by the numerical ID of the audio
1308     output device, <key> by the name of the parameter to change and     output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
1309     <value> by the new value for this parameter.     (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    
1313     Possible Answers:     Possible Answers:
1314    
1315        "OK" -        "OK" -
1316    
1317           in case setting was successfully changed           in case setting was successfully changed
1318    
1319        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
1320    
1321           in case setting was changed successfully, but there are           in case setting was changed successfully, but there are
1322           noteworthy issue(s) related, providing an appropriate warning           noteworthy issue(s) related, providing an appropriate warning
1323           code and warning message           code and warning message
1324    
1325        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
1326    
1327           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
1328           error message           error message
1329    
1330     Example:     Example:
1331    
1332        C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"        C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"
1333    
1334        S: "OK"        S: "OK"
1335    
1336  5.2.11  Getting information about an audio channel  6.2.11.  Getting information about an audio channel
1337    
1338     Use the following command to get information about an audio channel:     Use the following command to get information about an audio channel:
1339    
       GET AUDIO_OUTPUT_CHANNEL INFO <device-id> <audio-chan>  
1340    
    Where <device-id> is the numerical ID of the audio output device and  
    <audio-chan> the audio channel number.  
1341    
1342     Possible Answers:  
1343    Schoenebeck               Expires May 30, 2007                 [Page 24]
1344    
1345    Internet-Draft        LinuxSampler Control Protocol        November 2006
1346    
1347    
1348          GET AUDIO_OUTPUT_CHANNEL INFO <device-id> <audio-chan>
1349    
1350  Schoenebeck            Expires November 19, 2005               [Page 20]     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  Internet-Draft       LinuxSampler Control Protocol              May 2005     AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command and <audio-chan> the
1353       audio channel number.
1354    
1355       Possible Answers:
1356    
1357        LinuxSampler will answer by sending a <CRLF> separated list.  Each        LinuxSampler will answer by sending a <CRLF> separated list.  Each
1358        answer line begins with the information category name followed by        answer line begins with the information category name followed by
# Line 1127  Internet-Draft       LinuxSampler Contro Line 1360  Internet-Draft       LinuxSampler Contro
1360        character string to that info category.  At the moment the        character string to that info category.  At the moment the
1361        following information categories are defined:        following information categories are defined:
1362    
1363    
1364    
1365           NAME -           NAME -
1366    
1367              arbitrary character string naming the channel, which doesn't              arbitrary character string naming the channel, which doesn't
1368              have to be unique (always returned by all audio channels)              have to be unique (always returned by all audio channels)
1369    
1370           IS_MIX_CHANNEL -           IS_MIX_CHANNEL -
1371    
1372              either true or false, a mix-channel is not a real,              either true or false, a mix-channel is not a real,
1373              independent audio channel, but a virtual channel which is              independent audio channel, but a virtual channel which is
1374              mixed to another real channel, this mechanism is needed for              mixed to another real channel, this mechanism is needed for
1375              sampler engines which need more audio channels than the used              sampler engines which need more audio channels than the used
1376              audio system might be able to offer (always returned by all              audio system might be able to offer (always returned by all
1377              audio channels)              audio channels)
1378    
1379           MIX_CHANNEL_DESTINATION -           MIX_CHANNEL_DESTINATION -
1380    
1381              numerical ID (positive integer including 0) which reflects              numerical ID (positive integer including 0) which reflects
1382              the real audio channel (of the same audio output device)              the real audio channel (of the same audio output device)
1383              this mix channel refers to, means where the audio signal              this mix channel refers to, means where the audio signal
# Line 1152  Internet-Draft       LinuxSampler Contro Line 1392  Internet-Draft       LinuxSampler Contro
1392    
1393     Examples:     Examples:
1394    
1395    
1396    
1397    
1398    
1399    Schoenebeck               Expires May 30, 2007                 [Page 25]
1400    
1401    Internet-Draft        LinuxSampler Control Protocol        November 2006
1402    
1403    
1404        C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 0"        C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 0"
1405    
1406        S: "NAME: studio monitor left"        S: "NAME: studio monitor left"
1407    
1408           "IS_MIX_CHANNEL: false"           "IS_MIX_CHANNEL: false"
1409    
1410           "."           "."
1411    
1412        C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 1"        C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 1"
1413    
1414        S: "NAME: studio monitor right"        S: "NAME: studio monitor right"
1415    
1416           "IS_MIX_CHANNEL: false"           "IS_MIX_CHANNEL: false"
          "."  
1417    
       C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"  
       S: "NAME: studio monitor left"  
          "IS_MIX_CHANNEL: true"  
          "MIX_CHANNEL_DESTINATION: 1"  
1418           "."           "."
1419    
1420          C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"
1421    
1422          S: "NAME: studio monitor left"
1423    
1424             "IS_MIX_CHANNEL: true"
1425    
1426             "MIX_CHANNEL_DESTINATION: 1"
1427    
1428  Schoenebeck            Expires November 19, 2005               [Page 21]           "."
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
1429    
1430        C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"        C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"
1431    
1432        S: "NAME: 'ardour (left)'"        S: "NAME: 'ardour (left)'"
1433    
1434           "IS_MIX_CHANNEL: false"           "IS_MIX_CHANNEL: false"
1435    
1436           "JACK_BINDINGS: 'ardour:0'"           "JACK_BINDINGS: 'ardour:0'"
1437    
1438           "."           "."
1439    
1440  5.2.12  Getting information about specific audio channel parameter  6.2.12.  Getting information about specific audio channel parameter
1441    
1442     Use the following command to get detailed information about specific     Use the following command to get detailed information about specific
1443     audio channel parameter:     audio channel parameter:
# Line 1191  Internet-Draft       LinuxSampler Contro Line 1445  Internet-Draft       LinuxSampler Contro
1445        GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO <dev-id> <chan> <param>        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     Where <dev-id> is the numerical ID of the audio output device as
1448     returned by the "LIST AUDIO_OUTPUT_DEVICES" (Section 5.2.8) command,     returned by the "CREATE AUDIO_OUTPUT_DEVICE" (Section 6.2.5) or "LIST
1449     <chan> the audio channel number and <param> a specific channel     AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command, <chan> the audio
1450     parameter name for which information should be obtained (as returned     channel number and <param> a specific channel parameter name for
1451     by the "GET AUDIO_OUTPUT_CHANNEL INFO" (Section 5.2.11) command).     which information should be obtained (as returned by the "GET
1452    
1453    
1454    
1455    Schoenebeck               Expires May 30, 2007                 [Page 26]
1456    
1457    Internet-Draft        LinuxSampler Control Protocol        November 2006
1458    
1459    
1460       AUDIO_OUTPUT_CHANNEL INFO" (Section 6.2.11) command).
1461    
1462     Possible Answers:     Possible Answers:
1463    
# Line 1207  Internet-Draft       LinuxSampler Contro Line 1470  Internet-Draft       LinuxSampler Contro
1470        dependently to the given audio channel.  At the moment the        dependently to the given audio channel.  At the moment the
1471        following information categories are defined:        following information categories are defined:
1472    
1473    
1474    
1475           TYPE -           TYPE -
1476    
1477              either "BOOL" for boolean value(s) or "INT" for integer              either "BOOL" for boolean value(s) or "INT" for integer
1478              value(s) or "FLOAT" for dotted number(s) or "STRING" for              value(s) or "FLOAT" for dotted number(s) or "STRING" for
1479              character string(s) (always returned)              character string(s) (always returned)
1480    
1481           DESCRIPTION -           DESCRIPTION -
1482    
1483              arbitrary text describing the purpose of the parameter              arbitrary text describing the purpose of the parameter
1484              (always returned)              (always returned)
1485    
1486           FIX -           FIX -
1487    
1488              either true or false, if true then this parameter is read              either true or false, if true then this parameter is read
1489              only, thus cannot be altered (always returned)              only, thus cannot be altered (always returned)
1490    
1491           MULTIPLICITY -           MULTIPLICITY -
1492    
1493              either true or false, defines if this parameter allows only              either true or false, defines if this parameter allows only
1494              one value or a list of values, where true means multiple              one value or a list of values, where true means multiple
1495              values and false only a single value allowed (always              values and false only a single value allowed (always
1496              returned)              returned)
1497    
1498           RANGE_MIN -           RANGE_MIN -
1499    
1500              defines lower limit of the allowed value range for this              defines lower limit of the allowed value range for this
1501              parameter, can be an integer value as well as a dotted              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    
1506    
1507    
1508    
1509    
1510  Schoenebeck            Expires November 19, 2005               [Page 22]  
1511    Schoenebeck               Expires May 30, 2007                 [Page 27]
1512    
1513  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
1514    
1515    
             number, usually used in conjunction with 'RANGE_MAX', but  
             may also appear without (optionally returned, dependent to  
             driver and channel parameter)  
1516           RANGE_MAX -           RANGE_MAX -
1517    
1518              defines upper limit of the allowed value range for this              defines upper limit of the allowed value range for this
1519              parameter, can be an integer value as well as a dotted              parameter, can be an integer value as well as a dotted
1520              number, usually used in conjunction with 'RANGE_MIN', but              number, usually used in conjunction with 'RANGE_MIN', but
1521              may also appear without (optionally returned, dependent to              may also appear without (optionally returned, dependent to
1522              driver and channel parameter)              driver and channel parameter)
1523    
1524           POSSIBILITIES -           POSSIBILITIES -
1525    
1526              comma separated list of possible values for this parameter,              comma separated list of possible values for this parameter,
1527              character strings are encapsulated into apostrophes              character strings are encapsulated into apostrophes
1528              (optionally returned, dependent to driver and channel              (optionally returned, dependent to driver and channel
1529              parameter)              parameter)
1530    
1531        The mentioned fields above don't have to be in particular order.        The mentioned fields above don't have to be in particular order.
1532    
1533     Example:     Example:
1534    
1535        C: "GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO 1 0 JACK_BINDINGS"        C: "GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO 1 0 JACK_BINDINGS"
1536    
1537        S: "DESCRIPTION: bindings to other JACK clients"        S: "DESCRIPTION: bindings to other JACK clients"
1538    
1539           "TYPE: STRING"           "TYPE: STRING"
1540    
1541           "FIX: false"           "FIX: false"
1542    
1543           "MULTIPLICITY: true"           "MULTIPLICITY: true"
1544    
1545           "POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"           "POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"
1546    
1547           "."           "."
1548    
1549  5.2.13  Changing settings of audio output channels  6.2.13.  Changing settings of audio output channels
1550    
1551     Use the following command to alter a specific setting of an audio     Use the following command to alter a specific setting of an audio
1552     output channel:     output channel:
# Line 1267  Internet-Draft       LinuxSampler Contro Line 1554  Internet-Draft       LinuxSampler Contro
1554        SET AUDIO_OUTPUT_CHANNEL_PARAMETER <dev-id> <chn> <key>=<value>        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     Where <dev-id> should be replaced by the numerical ID of the audio
1557     device, <chn> by the audio channel number, <key> by the name of the     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     parameter to change and <value> by the new value for this parameter.     parameter to change and <value> by the new value for this parameter.
1561    
1562     Possible Answers:     Possible Answers:
1563    
1564    
1565    
1566    
1567    Schoenebeck               Expires May 30, 2007                 [Page 28]
1568    
1569    Internet-Draft        LinuxSampler Control Protocol        November 2006
1570    
1571    
1572        "OK" -        "OK" -
1573    
1574           in case setting was successfully changed           in case setting was successfully changed
1575    
1576        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
1577    
1578           in case setting was changed successfully, but there are           in case setting was changed successfully, but there are
1579           noteworthy issue(s) related, providing an appropriate warning           noteworthy issue(s) related, providing an appropriate warning
1580           code and warning message           code and warning message
1581    
1582        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
1583    
1584           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
1585           error message           error message
1586    
   
   
 Schoenebeck            Expires November 19, 2005               [Page 23]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
1587     Example:     Example:
1588    
1589        C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"        C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"
1590    
1591        S: "OK"        S: "OK"
1592    
1593        C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"        C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"
1594    
1595        S: "OK"        S: "OK"
1596    
1597  5.3  Configuring MIDI input drivers  6.3.  Configuring MIDI input drivers
1598    
1599     Instances of drivers in LinuxSampler are called devices.  You can use     Instances of drivers in LinuxSampler are called devices.  You can use
1600     multiple MIDI devices simultaneously, e.g.  to use MIDI over ethernet     multiple MIDI devices simultaneously, e.g. to use MIDI over ethernet
1601     as MIDI input on one sampler channel and ALSA as MIDI input on     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     another sampler channel.  For particular MIDI input systems it's also
1603     possible to create several devices of the same MIDI input type.  This     possible to create several devices of the same MIDI input type.  This
# Line 1312  Internet-Draft       LinuxSampler Contro Line 1609  Internet-Draft       LinuxSampler Contro
1609     values have to be obtained at runtime.  This makes the protocol a bit     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     abstract, but has the advantage, that front-ends can be written
1611     independently of what drivers are currently implemented and what     independently of what drivers are currently implemented and what
1612     parameters these drivers are actually offering.  This means     parameters these drivers are actually offering.  This means front-
1613     front-ends can even handle drivers which are implemented somewhere in     ends can even handle drivers which are implemented somewhere in
1614     future without modifying the front-end at all.     future without modifying the front-end at all.
1615    
1616     Commands for configuring MIDI input devices are pretty much the same     Commands for configuring MIDI input devices are pretty much the same
1617     as the commands for configuring audio output drivers, already     as the commands for configuring audio output drivers, already
1618     described in the last chapter.     described in the last chapter.
1619    
1620    
1621    
1622    
1623    Schoenebeck               Expires May 30, 2007                 [Page 29]
1624    
1625    Internet-Draft        LinuxSampler Control Protocol        November 2006
1626    
1627    
1628     Note: examples in this chapter showing particular parameters of     Note: examples in this chapter showing particular parameters of
1629     drivers are not meant as specification of the drivers' parameters.     drivers are not meant as specification of the drivers' parameters.
1630     Driver implementations in LinuxSampler might have complete different     Driver implementations in LinuxSampler might have complete different
# Line 1328  Internet-Draft       LinuxSampler Contro Line 1633  Internet-Draft       LinuxSampler Contro
1633     retrieve what parameters drivers are offering, how to retrieve their     retrieve what parameters drivers are offering, how to retrieve their
1634     possible values, etc.     possible values, etc.
1635    
1636  5.3.1  Getting amount of available MIDI input drivers  6.3.1.  Getting amount of available MIDI input drivers
1637    
1638     Use the following command to get the number of MIDI input drivers     Use the following command to get the number of MIDI input drivers
1639     currently available for the LinuxSampler instance:     currently available for the LinuxSampler instance:
# Line 1337  Internet-Draft       LinuxSampler Contro Line 1642  Internet-Draft       LinuxSampler Contro
1642    
1643     Possible Answers:     Possible Answers:
1644    
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 24]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
1645        LinuxSampler will answer by sending the number of available MIDI        LinuxSampler will answer by sending the number of available MIDI
1646        input drivers.        input drivers.
1647    
1648     Example:     Example:
1649    
1650        C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"        C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"
1651    
1652        S: "2"        S: "2"
1653    
1654  5.3.2  Getting all available MIDI input drivers  6.3.2.  Getting all available MIDI input drivers
1655    
1656     Use the following command to list all MIDI input drivers currently     Use the following command to list all MIDI input drivers currently
1657     available for the LinuxSampler instance:     available for the LinuxSampler instance:
# Line 1368  Internet-Draft       LinuxSampler Contro Line 1666  Internet-Draft       LinuxSampler Contro
1666     Example:     Example:
1667    
1668        C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"        C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
1669    
1670        S: "ALSA,JACK"        S: "ALSA,JACK"
1671    
1672  5.3.3  Getting information about a specific MIDI input driver  6.3.3.  Getting information about a specific MIDI input driver
1673    
1674     Use the following command to get detailed information about a     Use the following command to get detailed information about a
1675     specific MIDI input driver:     specific MIDI input driver:
1676    
1677    
1678    
1679    Schoenebeck               Expires May 30, 2007                 [Page 30]
1680    
1681    Internet-Draft        LinuxSampler Control Protocol        November 2006
1682    
1683    
1684        GET MIDI_INPUT_DRIVER INFO <midi-input-driver>        GET MIDI_INPUT_DRIVER INFO <midi-input-driver>
1685    
1686     Where <midi-input-driver> is the name of the MIDI input driver.     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    
1690     Possible Answers:     Possible Answers:
1691    
# Line 1387  Internet-Draft       LinuxSampler Contro Line 1695  Internet-Draft       LinuxSampler Contro
1695        character string to that info category.  At the moment the        character string to that info category.  At the moment the
1696        following information categories are defined:        following information categories are defined:
1697    
          DESCRIPTION -  
             arbitrary description text about the MIDI input driver  
          VERSION -  
             arbitrary character string regarding the driver's version  
          PARAMETERS -  
1698    
1699    
1700             DESCRIPTION -
1701    
1702                arbitrary description text about the MIDI input driver
1703    
1704             VERSION -
1705    
1706  Schoenebeck            Expires November 19, 2005               [Page 25]              arbitrary character string regarding the driver's version
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
1707    
1708             PARAMETERS -
1709    
1710              comma separated list of all parameters available for the              comma separated list of all parameters available for the
1711              given MIDI input driver              given MIDI input driver
1712    
1713        The mentioned fields above don't have to be in particular order.        The mentioned fields above don't have to be in particular order.
1714    
1715     Example:     Example:
1716    
1717        C: "GET MIDI_INPUT_DRIVER INFO ALSA"        C: "GET MIDI_INPUT_DRIVER INFO ALSA"
1718    
1719        S: "DESCRIPTION: Advanced Linux Sound Architecture"        S: "DESCRIPTION: Advanced Linux Sound Architecture"
1720    
1721           "VERSION: 1.0"           "VERSION: 1.0"
1722    
1723           "PARAMETERS: DRIVER,ACTIVE"           "PARAMETERS: DRIVER,ACTIVE"
1724    
1725           "."           "."
1726    
1727  5.3.4  Getting information about specific MIDI input driver parameter  6.3.4.  Getting information about specific MIDI input driver parameter
1728    
1729     Use the following command to get detailed information about a     Use the following command to get detailed information about a
1730     specific parameter of a specific MIDI input driver:     specific parameter of a specific MIDI input driver:
1731    
1732    
1733    
1734    
1735    Schoenebeck               Expires May 30, 2007                 [Page 31]
1736    
1737    Internet-Draft        LinuxSampler Control Protocol        November 2006
1738    
1739    
1740        GET MIDI_INPUT_DRIVER_PARAMETER INFO <midit> <param> [<deplist>]        GET MIDI_INPUT_DRIVER_PARAMETER INFO <midit> <param> [<deplist>]
1741    
1742     Where <midit> is the name of the MIDI input driver as returned by the     Where <midit> is the name of the MIDI input driver as returned by the
1743     "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 5.3.2) command, <param>     "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2) command, <param>
1744     a specific parameter name for which information should be obtained     a specific parameter name for which information should be obtained
1745     (as returned by the "GET MIDI_INPUT_DRIVER INFO" (Section 5.3.3)     (as returned by the "GET MIDI_INPUT_DRIVER INFO" (Section 6.3.3)
1746     command) and <deplist> is an optional list of parameters on which the     command) and <deplist> is an optional list of parameters on which the
1747     sought parameter <param> depends on, <deplist> is a key-value pair     sought parameter <param> depends on, <deplist> is a key-value pair
1748     list in form of "key1=val1 key2=val2 ...", where character string     list in form of "key1=val1 key2=val2 ...", where character string
# Line 1444  Internet-Draft       LinuxSampler Contro Line 1763  Internet-Draft       LinuxSampler Contro
1763     defined:     defined:
1764    
1765        TYPE -        TYPE -
1766    
1767           either "BOOL" for boolean value(s) or "INT" for integer           either "BOOL" for boolean value(s) or "INT" for integer
1768           value(s) or "FLOAT" for dotted number(s) or "STRING" for           value(s) or "FLOAT" for dotted number(s) or "STRING" for
1769           character string(s) (always returned, no matter which driver           character string(s) (always returned, no matter which driver
1770           parameter)           parameter)
1771    
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 26]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
1772        DESCRIPTION -        DESCRIPTION -
1773    
1774           arbitrary text describing the purpose of the parameter (always           arbitrary text describing the purpose of the parameter (always
1775           returned, no matter which driver parameter)           returned, no matter which driver parameter)
1776    
1777        MANDATORY -        MANDATORY -
1778    
1779           either true or false, defines if this parameter must be given           either true or false, defines if this parameter must be given
1780           when the device is to be created with the 'CREATE           when the device is to be created with the 'CREATE
1781           MIDI_INPUT_DEVICE' (Section 5.3.5) command (always returned, no           MIDI_INPUT_DEVICE' (Section 6.3.5) command (always returned, no
1782           matter which driver parameter)           matter which driver parameter)
1783    
1784        FIX -        FIX -
1785    
1786           either true or false, if false then this parameter can be           either true or false, if false then this parameter can be
1787           changed at any time, once the device is created by the 'CREATE           changed at any time, once the device is created by the 'CREATE
1788           MIDI_INPUT_DEVICE' (Section 5.3.5) command (always returned, no  
1789    
1790    
1791    Schoenebeck               Expires May 30, 2007                 [Page 32]
1792    
1793    Internet-Draft        LinuxSampler Control Protocol        November 2006
1794    
1795    
1796             MIDI_INPUT_DEVICE' (Section 6.3.5) command (always returned, no
1797           matter which driver parameter)           matter which driver parameter)
1798    
1799        MULTIPLICITY -        MULTIPLICITY -
1800    
1801           either true or false, defines if this parameter allows only one           either true or false, defines if this parameter allows only one
1802           value or a list of values, where true means multiple values and           value or a list of values, where true means multiple values and
1803           false only a single value allowed (always returned, no matter           false only a single value allowed (always returned, no matter
1804           which driver parameter)           which driver parameter)
1805    
1806        DEPENDS -        DEPENDS -
1807    
1808           comma separated list of parameters this parameter depends on,           comma separated list of parameters this parameter depends on,
1809           means the values for fields 'DEFAULT', 'RANGE_MIN', 'RANGE_MAX'           means the values for fields 'DEFAULT', 'RANGE_MIN', 'RANGE_MAX'
1810           and 'POSSIBILITIES' might depend on these listed parameters,           and 'POSSIBILITIES' might depend on these listed parameters,
# Line 1485  Internet-Draft       LinuxSampler Contro Line 1814  Internet-Draft       LinuxSampler Contro
1814           possible values for 'samplerate' depends on the sound card           possible values for 'samplerate' depends on the sound card
1815           which can be chosen by the 'card' parameter (optionally           which can be chosen by the 'card' parameter (optionally
1816           returned, dependent to driver parameter)           returned, dependent to driver parameter)
1817    
1818        DEFAULT -        DEFAULT -
1819    
1820           reflects the default value for this parameter which is used           reflects the default value for this parameter which is used
1821           when the device is created and not explicitly given with the           when the device is created and not explicitly given with the
1822           'CREATE MIDI_INPUT_DEVICE' (Section 5.3.5) command, in case of           'CREATE MIDI_INPUT_DEVICE' (Section 6.3.5) command, in case of
1823           MULTIPLCITY=true, this is a comma separated list, that's why           MULTIPLCITY=true, this is a comma separated list, that's why
1824           character strings are encapsulated into apostrophes (')           character strings are encapsulated into apostrophes (')
1825           (optionally returned, dependent to driver parameter)           (optionally returned, dependent to driver parameter)
1826    
1827        RANGE_MIN -        RANGE_MIN -
1828    
1829           defines lower limit of the allowed value range for this           defines lower limit of the allowed value range for this
1830           parameter, can be an integer value as well as a dotted number,           parameter, can be an integer value as well as a dotted number,
1831           this parameter is often used in conjunction with RANGE_MAX, but           this parameter is often used in conjunction with RANGE_MAX, but
1832           may also appear without (optionally returned, dependent to           may also appear without (optionally returned, dependent to
1833           driver parameter)           driver parameter)
1834    
1835        RANGE_MAX -        RANGE_MAX -
1836    
1837           defines upper limit of the allowed value range for this           defines upper limit of the allowed value range for this
1838           parameter, can be an integer value as well as a dotted number,           parameter, can be an integer value as well as a dotted number,
1839           this parameter is often used in conjunction with RANGE_MIN, but           this parameter is often used in conjunction with RANGE_MIN, but
# Line 1508  Internet-Draft       LinuxSampler Contro Line 1843  Internet-Draft       LinuxSampler Contro
1843    
1844    
1845    
1846  Schoenebeck            Expires November 19, 2005               [Page 27]  
1847    Schoenebeck               Expires May 30, 2007                 [Page 33]
1848    
1849  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
1850    
1851    
1852        POSSIBILITIES -        POSSIBILITIES -
1853    
1854           comma separated list of possible values for this parameter,           comma separated list of possible values for this parameter,
1855           character strings are encapsulated into apostrophes (optionally           character strings are encapsulated into apostrophes (optionally
1856           returned, dependent to driver parameter)           returned, dependent to driver parameter)
# Line 1523  Internet-Draft       LinuxSampler Contro Line 1860  Internet-Draft       LinuxSampler Contro
1860     Example:     Example:
1861    
1862        C: "GET MIDI_INPUT_DRIVER_PARAMETER INFO ALSA ACTIVE"        C: "GET MIDI_INPUT_DRIVER_PARAMETER INFO ALSA ACTIVE"
1863    
1864        S: "DESCRIPTION: Whether device is enabled"        S: "DESCRIPTION: Whether device is enabled"
1865    
1866           "TYPE: BOOL"           "TYPE: BOOL"
1867    
1868           "MANDATORY: false"           "MANDATORY: false"
1869    
1870           "FIX: false"           "FIX: false"
1871    
1872           "MULTIPLICITY: false"           "MULTIPLICITY: false"
1873    
1874           "DEFAULT: true"           "DEFAULT: true"
1875    
1876           "."           "."
1877    
1878  5.3.5  Creating a MIDI input device  6.3.5.  Creating a MIDI input device
1879    
1880     Use the following command to create a new MIDI input device for  the     Use the following command to create a new MIDI input device for the
1881     desired MIDI input system:     desired MIDI input system:
1882    
1883        CREATE MIDI_INPUT_DEVICE <midi-input-driver> [<param-list>]        CREATE MIDI_INPUT_DEVICE <midi-input-driver> [<param-list>]
1884    
1885     Where <midi-input-driver> should be replaced by the desired MIDI     Where <midi-input-driver> should be replaced by the desired MIDI
1886     input system and <param-list> by an optional list of driver specific     input system as returned by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
1887     parameters in form of "key1=val1 key2=val2 ...", where character     (Section 6.3.2) command and <param-list> by an optional list of
1888     string values should be encapsulated into apostrophes (').  Note that     driver specific parameters in form of "key1=val1 key2=val2 ...",
1889     there might be drivers which require parameter(s) to be given with     where character string values should be encapsulated into apostrophes
1890     this command.  Use the previously described commands in this chapter     (').  Note that there might be drivers which require parameter(s) to
1891     to get that information.     be given with this command.  Use the previously described commands in
1892       this chapter to get that information.
1893    
1894     Possible Answers:     Possible Answers:
1895    
1896        "OK[<device-id>]" -        "OK[<device-id>]" -
1897    
1898           in case the device was successfully created, where <device-id>           in case the device was successfully created, where <device-id>
1899           is the numerical ID of the new device           is the numerical ID of the new device
1900    
1901    
1902    
1903    Schoenebeck               Expires May 30, 2007                 [Page 34]
1904    
1905    Internet-Draft        LinuxSampler Control Protocol        November 2006
1906    
1907    
1908        "WRN[<device-id>]:<warning-code>:<warning-message>" -        "WRN[<device-id>]:<warning-code>:<warning-message>" -
1909    
1910           in case the driver was loaded successfully, where <device-id>           in case the driver was loaded successfully, where <device-id>
1911           is the numerical ID of the new device, but there are noteworthy           is the numerical ID of the new device, but there are noteworthy
1912           issue(s) related, providing an appropriate warning code and           issue(s) related, providing an appropriate warning code and
1913           warning message           warning message
1914    
1915        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
1916    
1917           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
1918           error message           error message
1919    
1920     Example:     Example:
1921    
   
   
 Schoenebeck            Expires November 19, 2005               [Page 28]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
1922        C: "CREATE MIDI_INPUT_DEVICE ALSA"        C: "CREATE MIDI_INPUT_DEVICE ALSA"
1923    
1924        S: "OK[0]"        S: "OK[0]"
1925    
1926  5.3.6  Destroying a MIDI input device  6.3.6.  Destroying a MIDI input device
1927    
1928     Use the following command to destroy a created MIDI input device:     Use the following command to destroy a created MIDI input device:
1929    
1930        DESTROY MIDI_INPUT_DEVICE <device-id>        DESTROY MIDI_INPUT_DEVICE <device-id>
1931    
1932     Where <device-id> should be replaced by the device's numerical ID.     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    
1936     Possible Answers:     Possible Answers:
1937    
1938        "OK" -        "OK" -
1939    
1940           in case the device was successfully destroyed           in case the device was successfully destroyed
1941    
1942        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
1943    
1944           in case the device was destroyed, but there are noteworthy           in case the device was destroyed, but there are noteworthy
1945           issue(s) related, providing an appropriate warning code and           issue(s) related, providing an appropriate warning code and
1946           warning message           warning message
1947    
1948        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
1949    
1950           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
1951           error message           error message
1952    
1953     Example:     Example:
1954    
1955    
1956    
1957    
1958    
1959    Schoenebeck               Expires May 30, 2007                 [Page 35]
1960    
1961    Internet-Draft        LinuxSampler Control Protocol        November 2006
1962    
1963    
1964        C: "DESTROY MIDI_INPUT_DEVICE 0"        C: "DESTROY MIDI_INPUT_DEVICE 0"
1965    
1966        S: "OK"        S: "OK"
1967    
1968  5.3.7  Getting all created MIDI input device count  6.3.7.  Getting all created MIDI input device count
1969    
1970     Use the following command to count all created MIDI input devices:     Use the following command to count all created MIDI input devices:
1971    
# Line 1611  Internet-Draft       LinuxSampler Contro Line 1979  Internet-Draft       LinuxSampler Contro
1979     Example:     Example:
1980    
1981        C: "GET MIDI_INPUT_DEVICES"        C: "GET MIDI_INPUT_DEVICES"
1982    
1983        S: "3"        S: "3"
1984    
1985  5.3.8  Getting all created MIDI input device list  6.3.8.  Getting all created MIDI input device list
1986    
1987     Use the following command to list all created MIDI input devices:     Use the following command to list all created MIDI input devices:
1988    
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 29]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
1989        LIST MIDI_INPUT_DEVICES        LIST MIDI_INPUT_DEVICES
1990    
1991     Possible Answers:     Possible Answers:
# Line 1635  Internet-Draft       LinuxSampler Contro Line 1996  Internet-Draft       LinuxSampler Contro
1996     Examples:     Examples:
1997    
1998        C: "LIST MIDI_INPUT_DEVICES"        C: "LIST MIDI_INPUT_DEVICES"
1999    
2000        S: "0,1,2"        S: "0,1,2"
2001    
2002        C: "LIST MIDI_INPUT_DEVICES"        C: "LIST MIDI_INPUT_DEVICES"
2003    
2004        S: "1,3"        S: "1,3"
2005    
2006  5.3.9  Getting current settings of a MIDI input device  6.3.9.  Getting current settings of a MIDI input device
2007    
2008     Use the following command to get current settings of a specific,     Use the following command to get current settings of a specific,
2009     created MIDI input device:     created MIDI input device:
2010    
2011    
2012    
2013    
2014    
2015    Schoenebeck               Expires May 30, 2007                 [Page 36]
2016    
2017    Internet-Draft        LinuxSampler Control Protocol        November 2006
2018    
2019    
2020        GET MIDI_INPUT_DEVICE INFO <device-id>        GET MIDI_INPUT_DEVICE INFO <device-id>
2021    
2022     Where <device-id> is the numerical ID of the MIDI input device.     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    
2026     Possible Answers:     Possible Answers:
2027    
# Line 1659  Internet-Draft       LinuxSampler Contro Line 2033  Internet-Draft       LinuxSampler Contro
2033        apostrophes (').  At the moment the following information        apostrophes (').  At the moment the following information
2034        categories are defined (independent of driver):        categories are defined (independent of driver):
2035    
2036    
2037    
2038           DRIVER -           DRIVER -
2039              identifier of the used MIDI input driver, as e.g.  returned  
2040              by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 5.3.2)              identifier of the used MIDI input driver, as e.g. returned
2041                by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2)
2042              command              command
2043    
2044           ACTIVE -           ACTIVE -
2045    
2046              either true or false, if false then the MIDI device is              either true or false, if false then the MIDI device is
2047              inactive and doesn't listen to any incoming MIDI events and              inactive and doesn't listen to any incoming MIDI events and
2048              thus doesn't forward them to connected sampler channels              thus doesn't forward them to connected sampler channels
# Line 1672  Internet-Draft       LinuxSampler Contro Line 2051  Internet-Draft       LinuxSampler Contro
2051     fields above are only those fields which are returned by all MIDI     fields above are only those fields which are returned by all MIDI
2052     input devices.  Every MIDI input driver might have its own,     input devices.  Every MIDI input driver might have its own,
2053     additional driver specific parameters (see "GET MIDI_INPUT_DRIVER     additional driver specific parameters (see "GET MIDI_INPUT_DRIVER
2054     INFO" (Section 5.3.3) command) which are also returned by this     INFO" (Section 6.3.3) command) which are also returned by this
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 30]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
2055     command.     command.
2056    
2057     Example:     Example:
2058    
2059        C: "GET MIDI_INPUT_DEVICE INFO 0"        C: "GET MIDI_INPUT_DEVICE INFO 0"
2060    
2061        S: "DRIVER: ALSA"        S: "DRIVER: ALSA"
2062    
2063           "ACTIVE: true"           "ACTIVE: true"
2064    
2065           "."           "."
2066    
2067  5.3.10  Changing settings of MIDI input devices  
2068    
2069    
2070    
2071    Schoenebeck               Expires May 30, 2007                 [Page 37]
2072    
2073    Internet-Draft        LinuxSampler Control Protocol        November 2006
2074    
2075    
2076    6.3.10.  Changing settings of MIDI input devices
2077    
2078     Use the following command to alter a specific setting of a created     Use the following command to alter a specific setting of a created
2079     MIDI input device:     MIDI input device:
# Line 1698  Internet-Draft       LinuxSampler Contro Line 2081  Internet-Draft       LinuxSampler Contro
2081        SET MIDI_INPUT_DEVICE_PARAMETER <device-id> <key>=<value>        SET MIDI_INPUT_DEVICE_PARAMETER <device-id> <key>=<value>
2082    
2083     Where <device-id> should be replaced by the numerical ID of the MIDI     Where <device-id> should be replaced by the numerical ID of the MIDI
2084     input device, <key> by the name of the parameter to change and     input device as returned by the "CREATE MIDI_INPUT_DEVICE"
2085     <value> by the new value for this parameter.     (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    
2089     Possible Answers:     Possible Answers:
2090    
2091        "OK" -        "OK" -
2092    
2093           in case setting was successfully changed           in case setting was successfully changed
2094    
2095        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
2096    
2097           in case setting was changed successfully, but there are           in case setting was changed successfully, but there are
2098           noteworthy issue(s) related, providing an appropriate warning           noteworthy issue(s) related, providing an appropriate warning
2099           code and warning message           code and warning message
2100    
2101        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
2102    
2103           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
2104           error message           error message
2105    
2106     Example:     Example:
2107    
2108        C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"        C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"
2109    
2110        S: "OK"        S: "OK"
2111    
2112  5.3.11  Getting information about a MIDI port  6.3.11.  Getting information about a MIDI port
2113    
2114     Use the following command to get information about a MIDI port:     Use the following command to get information about a MIDI port:
2115    
2116        GET MIDI_INPUT_PORT INFO <device-id> <midi-port>        GET MIDI_INPUT_PORT INFO <device-id> <midi-port>
2117    
2118     Where <device-id> is the numerical ID of the MIDI input device and     Where <device-id> is the numerical ID of the MIDI input device as
2119     <midi-port> the MIDI input port number.     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    
2123     Possible Answers:     Possible Answers:
2124    
2125    
2126    
2127    Schoenebeck               Expires May 30, 2007                 [Page 38]
 Schoenebeck            Expires November 19, 2005               [Page 31]  
2128    
2129  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
2130    
2131    
2132        LinuxSampler will answer by sending a <CRLF> separated list.  Each        LinuxSampler will answer by sending a <CRLF> separated list.  Each
# Line 1742  Internet-Draft       LinuxSampler Contro Line 2134  Internet-Draft       LinuxSampler Contro
2134        a colon and then a space character <SP> and finally the info        a colon and then a space character <SP> and finally the info
2135        character string to that info category.  At the moment the        character string to that info category.  At the moment the
2136        following information categories are defined:        following information categories are defined:
2137    
2138        NAME -        NAME -
2139    
2140           arbitrary character string naming the port           arbitrary character string naming the port
2141    
2142     The field above is only the one which is returned by all MIDI ports     The field above is only the one which is returned by all MIDI ports
# Line 1752  Internet-Draft       LinuxSampler Contro Line 2146  Internet-Draft       LinuxSampler Contro
2146     Example:     Example:
2147    
2148        C: "GET MIDI_INPUT_PORT INFO 0 0"        C: "GET MIDI_INPUT_PORT INFO 0 0"
2149    
2150        S: "NAME: 'Masterkeyboard'"        S: "NAME: 'Masterkeyboard'"
2151    
2152           "ALSA_SEQ_BINDINGS: '64:0'"           "ALSA_SEQ_BINDINGS: '64:0'"
2153    
2154           "."           "."
2155    
2156  5.3.12  Getting information about specific MIDI port parameter  6.3.12.  Getting information about specific MIDI port parameter
2157    
2158     Use the following command to get detailed information about specific     Use the following command to get detailed information about specific
2159     MIDI port parameter:     MIDI port parameter:
# Line 1764  Internet-Draft       LinuxSampler Contro Line 2161  Internet-Draft       LinuxSampler Contro
2161        GET MIDI_INPUT_PORT_PARAMETER INFO <dev-id> <port> <param>        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     Where <dev-id> is the numerical ID of the MIDI input device as
2164     returned by the "LIST MIDI_INPUT_DEVICES" (Section 5.3.8) command,     returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
2165     <port> the MIDI port number and <param> a specific port parameter     MIDI_INPUT_DEVICES" (Section 6.3.8) command, <port> the MIDI port
2166     name for which information should be obtained (as returned by the     number and <param> a specific port parameter name for which
2167     "GET MIDI_INPUT_PORT INFO" (Section 5.3.11) command).     information should be obtained (as returned by the "GET
2168       MIDI_INPUT_PORT INFO" (Section 6.3.11) command).
2169    
2170     Possible Answers:     Possible Answers:
2171    
# Line 1779  Internet-Draft       LinuxSampler Contro Line 2177  Internet-Draft       LinuxSampler Contro
2177        parameter and there is optional information which are only shown        parameter and there is optional information which are only shown
2178        dependently to the given MIDI port.  At the moment the following        dependently to the given MIDI port.  At the moment the following
2179        information categories are defined:        information categories are defined:
       TYPE -  
          either "BOOL" for boolean value(s) or "INT" for integer  
          value(s) or "FLOAT" for dotted number(s) or "STRING" for  
          character string(s) (always returned)  
       DESCRIPTION -  
2180    
2181    
2182    
2183    Schoenebeck               Expires May 30, 2007                 [Page 39]
 Schoenebeck            Expires November 19, 2005               [Page 32]  
2184    
2185  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
2186    
2187    
2188          TYPE -
2189    
2190             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    
2194          DESCRIPTION -
2195    
2196           arbitrary text describing the purpose of the parameter (always           arbitrary text describing the purpose of the parameter (always
2197           returned)           returned)
2198    
2199        FIX -        FIX -
2200    
2201           either true or false, if true then this parameter is read only,           either true or false, if true then this parameter is read only,
2202           thus cannot be altered (always returned)           thus cannot be altered (always returned)
2203    
2204        MULTIPLICITY -        MULTIPLICITY -
2205    
2206           either true or false, defines if this parameter allows only one           either true or false, defines if this parameter allows only one
2207           value or a list of values, where true means multiple values and           value or a list of values, where true means multiple values and
2208           false only a single value allowed (always returned)           false only a single value allowed (always returned)
2209    
2210        RANGE_MIN -        RANGE_MIN -
2211    
2212           defines lower limit of the allowed value range for this           defines lower limit of the allowed value range for this
2213           parameter, can be an integer value as well as a dotted number,           parameter, can be an integer value as well as a dotted number,
2214           this parameter is usually used in conjunction with 'RANGE_MAX'           this parameter is usually used in conjunction with 'RANGE_MAX'
2215           but may also appear without (optionally returned, dependent to           but may also appear without (optionally returned, dependent to
2216           driver and port parameter)           driver and port parameter)
2217    
2218        RANGE_MAX -        RANGE_MAX -
2219    
2220           defines upper limit of the allowed value range for this           defines upper limit of the allowed value range for this
2221           parameter, can be an integer value as well as a dotted number,           parameter, can be an integer value as well as a dotted number,
2222           this parameter is usually used in conjunction with 'RANGE_MIN'           this parameter is usually used in conjunction with 'RANGE_MIN'
2223           but may also appear without (optionally returned, dependent to           but may also appear without (optionally returned, dependent to
2224           driver and port parameter)           driver and port parameter)
2225    
2226        POSSIBILITIES -        POSSIBILITIES -
2227    
2228           comma separated list of possible values for this parameter,           comma separated list of possible values for this parameter,
2229           character strings are encapsulated into apostrophes (optionally           character strings are encapsulated into apostrophes (optionally
2230           returned, dependent to device and port parameter)           returned, dependent to device and port parameter)
# Line 1823  Internet-Draft       LinuxSampler Contro Line 2233  Internet-Draft       LinuxSampler Contro
2233    
2234     Example:     Example:
2235    
2236    
2237    
2238    
2239    Schoenebeck               Expires May 30, 2007                 [Page 40]
2240    
2241    Internet-Draft        LinuxSampler Control Protocol        November 2006
2242    
2243    
2244        C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"        C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"
2245    
2246        S: "DESCRIPTION: bindings to other ALSA sequencer clients"        S: "DESCRIPTION: bindings to other ALSA sequencer clients"
2247    
2248           "TYPE: STRING"           "TYPE: STRING"
2249    
2250           "FIX: false"           "FIX: false"
2251    
2252           "MULTIPLICITY: true"           "MULTIPLICITY: true"
2253    
2254           "POSSIBILITIES: '64:0','68:0','68:1'"           "POSSIBILITIES: '64:0','68:0','68:1'"
2255    
2256           "."           "."
2257    
2258  5.3.13  Changing settings of MIDI input ports  6.3.13.  Changing settings of MIDI input ports
2259    
2260     Use the following command to alter a specific setting of a MIDI input     Use the following command to alter a specific setting of a MIDI input
2261     port:     port:
# Line 1839  Internet-Draft       LinuxSampler Contro Line 2263  Internet-Draft       LinuxSampler Contro
2263        SET MIDI_INPUT_PORT_PARAMETER <device-id> <port> <key>=<value>        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     Where <device-id> should be replaced by the numerical ID of the MIDI
2266     device, <port> by the MIDI port number, <key> by the name of the     device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5)
2267     parameter to change and <value> by the new value for this parameter.     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.
   
 Schoenebeck            Expires November 19, 2005               [Page 33]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
2270    
2271     Possible Answers:     Possible Answers:
2272    
2273        "OK" -        "OK" -
2274    
2275           in case setting was successfully changed           in case setting was successfully changed
2276    
2277        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
2278    
2279           in case setting was changed successfully, but there are           in case setting was changed successfully, but there are
2280           noteworthy issue(s) related, providing an appropriate warning           noteworthy issue(s) related, providing an appropriate warning
2281           code and warning message           code and warning message
2282    
2283        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
2284    
2285           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
2286           error message           error message
2287    
# Line 1865  Internet-Draft       LinuxSampler Contro Line 2289  Internet-Draft       LinuxSampler Contro
2289    
2290    
2291    
2292  5.4  Configuring sampler channels  
2293    
2294    
2295    Schoenebeck               Expires May 30, 2007                 [Page 41]
2296    
2297    Internet-Draft        LinuxSampler Control Protocol        November 2006
2298    
2299    
2300    
2301    
2302    6.4.  Configuring sampler channels
2303    
2304     The following commands describe how to add and remove sampler     The following commands describe how to add and remove sampler
2305     channels, deploy sampler engines, load instruments and connect     channels, associate a sampler channel with a sampler engine, load
2306     sampler channels to MIDI and audio devices.     instruments and connect sampler channels to MIDI and audio devices.
2307    
2308  5.4.1  Loading an instrument  6.4.1.  Loading an instrument
2309    
2310     An instrument file can be loaded and assigned to a sampler channel by     An instrument file can be loaded and assigned to a sampler channel by
2311     one of the following commands:     one of the following commands:
2312    
2313        LOAD INSTRUMENT [NON_MODAL] '<filename>' <instr-index>        LOAD INSTRUMENT [NON_MODAL] '<filename>' <instr-index> <sampler-
2314        <sampler-channel>        channel>
2315    
2316     Where <filename> is the name of the instrument file on the     Where <filename> is the name of the instrument file on the
2317     LinuxSampler instance's host system, <instr-index> the index of the     LinuxSampler instance's host system, <instr-index> the index of the
# Line 1889  Internet-Draft       LinuxSampler Contro Line 2323  Internet-Draft       LinuxSampler Contro
2323     is that the regular command returns OK only after the instrument has     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     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     version returns immediately and a background process is launched to
2326     load the instrument on the channel.  The GET CHANNEL INFO (Section     load the instrument on the channel.  The GET CHANNEL INFO
2327     5.4.10) command can be used to obtain loading progress from     (Section 6.4.10) command can be used to obtain loading progress from
2328     INSTRUMENT_STATUS field.  LOAD command will perform sanity checks     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     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     format and SHOULD return ERR and SHOULD not launch the background
# Line 1898  Internet-Draft       LinuxSampler Contro Line 2332  Internet-Draft       LinuxSampler Contro
2332    
2333     Possible Answers:     Possible Answers:
2334    
   
   
 Schoenebeck            Expires November 19, 2005               [Page 34]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
2335        "OK" -        "OK" -
2336    
2337           in case the instrument was successfully loaded           in case the instrument was successfully loaded
2338    
2339        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
2340    
2341           in case the instrument was loaded successfully, but there are           in case the instrument was loaded successfully, but there are
2342           noteworthy issue(s) related (e.g.  Engine doesn't support one           noteworthy issue(s) related (e.g.  Engine doesn't support one
2343           or more patch parameters provided by the loaded instrument           or more patch parameters provided by the loaded instrument
2344           file), providing an appropriate warning code and warning           file), providing an appropriate warning code and warning
2345           message           message
2346    
2347    
2348    
2349    
2350    
2351    Schoenebeck               Expires May 30, 2007                 [Page 42]
2352    
2353    Internet-Draft        LinuxSampler Control Protocol        November 2006
2354    
2355    
2356        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
2357    
2358           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
2359           error message           error message
2360    
# Line 1921  Internet-Draft       LinuxSampler Contro Line 2362  Internet-Draft       LinuxSampler Contro
2362    
2363    
2364    
2365  5.4.2  Loading a sampler engine  6.4.2.  Loading a sampler engine
2366    
2367     A sample engine can be deployed and assigned to a specific sampler     A sampler engine type can be associated to a specific sampler channel
2368     channel by the following command:     by the following command:
2369    
2370        LOAD ENGINE <engine-name> <sampler-channel>        LOAD ENGINE <engine-name> <sampler-channel>
2371    
2372     Where <engine-name> is an engine name as obtained by the "LIST     Where <engine-name> is an engine name as obtained by the "LIST
2373     AVAILABLE_ENGINES" (Section 5.4.8) command and <sampler-channel> the     AVAILABLE_ENGINES" (Section 6.4.8) command and <sampler-channel> the
2374     sampler channel the deployed engine should be assigned to.  Even if     sampler channel as returned by the "ADD CHANNEL" (Section 6.4.5) or
2375     the respective sampler channel has already a deployed engine with     "LIST CHANNELS" (Section 6.4.4) command where the engine type should
2376     that engine name, a new engine instance will be assigned to the     be assigned to.  This command should be issued after adding a new
2377     sampler channel.     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     Possible Answers:     Possible Answers:
2385    
2386        "OK" -        "OK" -
2387    
2388           in case the engine was successfully deployed           in case the engine was successfully deployed
2389    
2390        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
2391    
2392           in case the engine was deployed successfully, but there are           in case the engine was deployed successfully, but there are
2393           noteworthy issue(s) related, providing an appropriate warning           noteworthy issue(s) related, providing an appropriate warning
2394           code and warning message           code and warning message
2395    
2396        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
2397    
2398           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
2399           error message           error message
2400    
# Line 1953  Internet-Draft       LinuxSampler Contro Line 2404  Internet-Draft       LinuxSampler Contro
2404    
2405    
2406    
2407    Schoenebeck               Expires May 30, 2007                 [Page 43]
2408    
2409    Internet-Draft        LinuxSampler Control Protocol        November 2006
2410    
2411    
2412    
 Schoenebeck            Expires November 19, 2005               [Page 35]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
2413    
2414  5.4.3  Getting all created sampler channel count  6.4.3.  Getting all created sampler channel count
2415    
2416     The number of sampler channels can change on runtime.  To get the     The number of sampler channels can change on runtime.  To get the
2417     current amount of sampler channels, the front-end can send the     current amount of sampler channels, the front-end can send the
# Line 1977  Internet-Draft       LinuxSampler Contro Line 2427  Internet-Draft       LinuxSampler Contro
2427     Example:     Example:
2428    
2429        C: "GET CHANNELS"        C: "GET CHANNELS"
2430    
2431        S: "12"        S: "12"
2432    
2433  5.4.4  Getting all created sampler channel list  6.4.4.  Getting all created sampler channel list
2434    
2435     The number of sampler channels can change on runtime.  To get the     The number of sampler channels can change on runtime.  To get the
2436     current list of sampler channels, the front-end can send the     current list of sampler channels, the front-end can send the
# Line 1995  Internet-Draft       LinuxSampler Contro Line 2446  Internet-Draft       LinuxSampler Contro
2446     Example:     Example:
2447    
2448        C: "LIST CHANNELS"        C: "LIST CHANNELS"
2449    
2450        S: "0,1,2,3,4,5,6,9,10,11,15,20"        S: "0,1,2,3,4,5,6,9,10,11,15,20"
2451    
2452  5.4.5  Adding a new sampler channel  6.4.5.  Adding a new sampler channel
2453    
2454     A new sampler channel can be added to the end of the sampler channel     A new sampler channel can be added to the end of the sampler channel
2455     list by sending the following command:     list by sending the following command:
# Line 2005  Internet-Draft       LinuxSampler Contro Line 2457  Internet-Draft       LinuxSampler Contro
2457        ADD CHANNEL        ADD CHANNEL
2458    
2459     This will increment the sampler channel count by one and the new     This will increment the sampler channel count by one and the new
    sampler channel will be appended to the end of the sampler channel  
    list.  The front-end should send the respective, related commands  
    right after to e.g.  load an engine, load an instrument and setting  
    input, output method and eventually other commands to initialize the  
2460    
2461    
2462    
2463  Schoenebeck            Expires November 19, 2005               [Page 36]  Schoenebeck               Expires May 30, 2007                 [Page 44]
2464    
2465  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
2466    
2467    
2468       sampler channel will be appended to the end of the sampler channel
2469       list.  The front-end should send the respective, related commands
2470       right after to e.g. load an engine, load an instrument and setting
2471       input, output method and eventually other commands to initialize the
2472     new channel.  The front-end should use the sampler channel returned     new channel.  The front-end should use the sampler channel returned
2473     by the answer of this command to perform the previously recommended     by the answer of this command to perform the previously recommended
2474     commands, to avoid race conditions e.g.  with other front-ends that     commands, to avoid race conditions e.g. with other front-ends that
2475     might also have sent an "ADD CHANNEL" command.     might also have sent an "ADD CHANNEL" command.
2476    
2477     Possible Answers:     Possible Answers:
2478    
2479        "OK[<sampler-channel>]" -        "OK[<sampler-channel>]" -
2480           in case a new sampler channel could be added, where  
2481           <sampler-channel> reflects the channel number of the new           in case a new sampler channel could be added, where <sampler-
2482           created sampler channel which should be used to set up the           channel> reflects the channel number of the new created sampler
2483           sampler channel by sending subsequent initialization commands           channel which should be used to set up the sampler channel by
2484             sending subsequent initialization commands
2485    
2486        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
2487    
2488           in case a new channel was added successfully, but there are           in case a new channel was added successfully, but there are
2489           noteworthy issue(s) related, providing an appropriate warning           noteworthy issue(s) related, providing an appropriate warning
2490           code and warning message           code and warning message
2491    
2492        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
2493    
2494           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
2495           error message           error message
2496    
# Line 2041  Internet-Draft       LinuxSampler Contro Line 2498  Internet-Draft       LinuxSampler Contro
2498    
2499    
2500    
2501  5.4.6  Removing a sampler channel  6.4.6.  Removing a sampler channel
2502    
2503     A sampler channel can be removed by sending the following command:     A sampler channel can be removed by sending the following command:
2504    
2505        REMOVE CHANNEL <sampler-channel>        REMOVE CHANNEL <sampler-channel>
2506    
2507     Where <sampler-channel> should be replaced by the number of the     Where <sampler-channel> should be replaced by the number of the
2508     sampler channel as given by the "ADD CHANNEL" (Section 5.4.5) or     sampler channel as given by the "ADD CHANNEL" (Section 6.4.5) or
2509     "LIST CHANNELS" (Section 5.4.4) command.  The channel numbers of all     "LIST CHANNELS" (Section 6.4.4) command.  The channel numbers of all
2510     subsequent sampler channels remain the same.     subsequent sampler channels remain the same.
2511    
2512     Possible Answers:     Possible Answers:
2513    
2514    
2515    
2516    
2517    
2518    
2519    Schoenebeck               Expires May 30, 2007                 [Page 45]
2520    
2521    Internet-Draft        LinuxSampler Control Protocol        November 2006
2522    
2523    
2524        "OK" -        "OK" -
2525    
2526           in case the given sampler channel could be removed           in case the given sampler channel could be removed
2527    
2528        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
2529    
2530           in case the given channel was removed, but there are noteworthy           in case the given channel was removed, but there are noteworthy
2531           issue(s) related, providing an appropriate warning code and           issue(s) related, providing an appropriate warning code and
2532           warning message           warning message
2533    
2534        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
2535    
2536           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
2537           error message           error message
2538    
# Line 2068  Internet-Draft       LinuxSampler Contro Line 2540  Internet-Draft       LinuxSampler Contro
2540    
2541    
2542    
2543  Schoenebeck            Expires November 19, 2005               [Page 37]  6.4.7.  Getting amount of available engines
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
   
   
 5.4.7  Getting amount of available engines  
2544    
2545     The front-end can ask for the number of available engines by sending     The front-end can ask for the number of available engines by sending
2546     the following command:     the following command:
# Line 2090  Internet-Draft       LinuxSampler Contro Line 2555  Internet-Draft       LinuxSampler Contro
2555     Example:     Example:
2556    
2557        C: "GET AVAILABLE_ENGINES"        C: "GET AVAILABLE_ENGINES"
2558    
2559        S: "4"        S: "4"
2560    
2561  5.4.8  Getting all available engines  6.4.8.  Getting all available engines
2562    
2563     The front-end can ask for a list of all available engines by sending     The front-end can ask for a list of all available engines by sending
2564     the following command:     the following command:
# Line 2101  Internet-Draft       LinuxSampler Contro Line 2567  Internet-Draft       LinuxSampler Contro
2567    
2568     Possible Answers:     Possible Answers:
2569    
2570    
2571    
2572    
2573    
2574    
2575    Schoenebeck               Expires May 30, 2007                 [Page 46]
2576    
2577    Internet-Draft        LinuxSampler Control Protocol        November 2006
2578    
2579    
2580        LinuxSampler will answer by sending a comma separated list of the        LinuxSampler will answer by sending a comma separated list of the
2581        engines' names encapsulated into apostrophes (').  Engine names        engines' names encapsulated into apostrophes (').  Engine names
2582        can consist of lower and upper cases, digits and underlines ("_"        can consist of lower and upper cases, digits and underlines ("_"
# Line 2109  Internet-Draft       LinuxSampler Contro Line 2585  Internet-Draft       LinuxSampler Contro
2585     Example:     Example:
2586    
2587        C: "LIST AVAILABLE_ENGINES"        C: "LIST AVAILABLE_ENGINES"
2588    
2589        S: "'GigEngine','AkaiEngine','DLSEngine','JoesCustomEngine'"        S: "'GigEngine','AkaiEngine','DLSEngine','JoesCustomEngine'"
2590    
2591  5.4.9  Getting information about an engine  6.4.9.  Getting information about an engine
2592    
2593     The front-end can ask for information about a specific engine by     The front-end can ask for information about a specific engine by
2594     sending the following command:     sending the following command:
# Line 2119  Internet-Draft       LinuxSampler Contro Line 2596  Internet-Draft       LinuxSampler Contro
2596        GET ENGINE INFO <engine-name>        GET ENGINE INFO <engine-name>
2597    
2598     Where <engine-name> is an engine name as obtained by the "LIST     Where <engine-name> is an engine name as obtained by the "LIST
2599     AVAILABLE_ENGINES" (Section 5.4.8) command.     AVAILABLE_ENGINES" (Section 6.4.8) command.
   
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 38]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
2600    
2601     Possible Answers:     Possible Answers:
2602    
# Line 2137  Internet-Draft       LinuxSampler Contro Line 2606  Internet-Draft       LinuxSampler Contro
2606        character string to that info category.  At the moment the        character string to that info category.  At the moment the
2607        following categories are defined:        following categories are defined:
2608    
2609    
2610    
2611           DESCRIPTION -           DESCRIPTION -
2612    
2613              arbitrary description text about the engine              arbitrary description text about the engine
2614    
2615           VERSION -           VERSION -
2616    
2617              arbitrary character string regarding the engine's version              arbitrary character string regarding the engine's version
2618    
2619     The mentioned fields above don't have to be in particular order.     The mentioned fields above don't have to be in particular order.
# Line 2147  Internet-Draft       LinuxSampler Contro Line 2621  Internet-Draft       LinuxSampler Contro
2621     Example:     Example:
2622    
2623        C: "GET ENGINE INFO JoesCustomEngine"        C: "GET ENGINE INFO JoesCustomEngine"
2624    
2625        S: "DESCRIPTION: this is Joe's custom sampler engine"        S: "DESCRIPTION: this is Joe's custom sampler engine"
2626    
2627    
2628    
2629    
2630    
2631    Schoenebeck               Expires May 30, 2007                 [Page 47]
2632    
2633    Internet-Draft        LinuxSampler Control Protocol        November 2006
2634    
2635    
2636           "VERSION: testing-1.0"           "VERSION: testing-1.0"
2637    
2638           "."           "."
2639    
2640  5.4.10  Getting sampler channel information  6.4.10.  Getting sampler channel information
2641    
2642     The front-end can ask for the current settings of a sampler channel     The front-end can ask for the current settings of a sampler channel
2643     by sending the following command:     by sending the following command:
# Line 2159  Internet-Draft       LinuxSampler Contro Line 2645  Internet-Draft       LinuxSampler Contro
2645        GET CHANNEL INFO <sampler-channel>        GET CHANNEL INFO <sampler-channel>
2646    
2647     Where <sampler-channel> is the sampler channel number the front-end     Where <sampler-channel> is the sampler channel number the front-end
2648     is interested in.     is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2649       "LIST CHANNELS" (Section 6.4.4) command.
2650    
2651     Possible Answers:     Possible Answers:
2652    
# Line 2169  Internet-Draft       LinuxSampler Contro Line 2656  Internet-Draft       LinuxSampler Contro
2656        character string to that setting category.  At the moment the        character string to that setting category.  At the moment the
2657        following categories are defined:        following categories are defined:
2658    
          ENGINE_NAME -  
             name of the engine that is deployed on the sampler channel,  
             "NONE" if there's no engine deployed yet for this sampler  
             channel  
          AUDIO_OUTPUT_DEVICE -  
             numerical ID of the audio output device which is currently  
             connected to this sampler channel to output the audio  
             signal, "NONE" if there's no device connected to this  
2659    
2660    
2661             ENGINE_NAME -
2662    
2663  Schoenebeck            Expires November 19, 2005               [Page 39]              name of the engine that is associated with the sampler
2664                channel, "NONE" if there's no engine associated yet for this
2665  Internet-Draft       LinuxSampler Control Protocol              May 2005              sampler channel
2666    
2667             AUDIO_OUTPUT_DEVICE -
2668    
2669                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              sampler channel              sampler channel
2673    
2674           AUDIO_OUTPUT_CHANNELS -           AUDIO_OUTPUT_CHANNELS -
2675    
2676              number of output channels the sampler channel offers              number of output channels the sampler channel offers
2677              (dependent to used sampler engine and loaded instrument)              (dependent to used sampler engine and loaded instrument)
2678    
2679           AUDIO_OUTPUT_ROUTING -           AUDIO_OUTPUT_ROUTING -
2680    
2681              comma separated list which reflects to which audio channel              comma separated list which reflects to which audio channel
2682              of the selected audio output device each sampler output              of the selected audio output device each sampler output
2683              channel is routed to, e.g.  "0,3" would mean the engine's              channel is routed to, e.g. "0,3" would mean the engine's
2684    
2685    
2686    
2687    Schoenebeck               Expires May 30, 2007                 [Page 48]
2688    
2689    Internet-Draft        LinuxSampler Control Protocol        November 2006
2690    
2691    
2692              output channel 0 is routed to channel 0 of the audio output              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              device and the engine's output channel 1 is routed to the
2694              channel 3 of the audio output device              channel 3 of the audio output device
2695    
2696           INSTRUMENT_FILE -           INSTRUMENT_FILE -
2697    
2698              the file name of the loaded instrument, "NONE" if there's no              the file name of the loaded instrument, "NONE" if there's no
2699              instrument yet loaded for this sampler channel              instrument yet loaded for this sampler channel
2700    
2701           INSTRUMENT_NR -           INSTRUMENT_NR -
2702    
2703              the instrument index number of the loaded instrument              the instrument index number of the loaded instrument
2704    
2705           INSTRUMENT_NAME -           INSTRUMENT_NAME -
2706    
2707              the instrument name of the loaded instrument              the instrument name of the loaded instrument
2708    
2709           INSTRUMENT_STATUS -           INSTRUMENT_STATUS -
2710    
2711              integer values 0 to 100 indicating loading progress              integer values 0 to 100 indicating loading progress
2712              percentage for the instrument.  Negative value indicates a              percentage for the instrument.  Negative value indicates a
2713              loading exception.  Value of 100 indicates that the              loading exception.  Value of 100 indicates that the
2714              instrument is fully loaded.              instrument is fully loaded.
2715    
2716           MIDI_INPUT_DEVICE -           MIDI_INPUT_DEVICE -
2717    
2718              numerical ID of the MIDI input device which is currently              numerical ID of the MIDI input device which is currently
2719              connected to this sampler channel to deliver MIDI input              connected to this sampler channel to deliver MIDI input
2720              commands, "NONE" if there's no device connected to this              commands, "NONE" if there's no device connected to this
2721              sampler channel              sampler channel
2722    
2723           MIDI_INPUT_PORT -           MIDI_INPUT_PORT -
2724    
2725              port number of the MIDI input device              port number of the MIDI input device
2726    
2727           MIDI_INPUT_CHANNEL -           MIDI_INPUT_CHANNEL -
2728    
2729              the MIDI input channel number this sampler channel should              the MIDI input channel number this sampler channel should
2730              listen to or "ALL" to listen on all MIDI channels              listen to or "ALL" to listen on all MIDI channels
2731    
2732           VOLUME -           VOLUME -
2733    
2734              optionally dotted number for the channel volume factor              optionally dotted number for the channel volume factor
2735              (where a value < 1.0 means attenuation and a value > 1.0              (where a value < 1.0 means attenuation and a value > 1.0
2736              means amplification)              means amplification)
2737    
2738    
2739    
2740    
2741    
2742    
2743    Schoenebeck               Expires May 30, 2007                 [Page 49]
2744    
2745    Internet-Draft        LinuxSampler Control Protocol        November 2006
2746    
2747    
2748             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     The mentioned fields above don't have to be in particular order.     The mentioned fields above don't have to be in particular order.
2762    
2763     Example:     Example:
2764    
2765        C: "GET CHANNEL INFO 34"        C: "GET CHANNEL INFO 34"
       S: "ENGINE_NAME: GigEngine"  
          "VOLUME: 1.0"  
          "AUDIO_OUTPUT_DEVICE: 0"  
          "AUDIO_OUTPUT_CHANNELS: 2"  
   
2766    
2767          S: "ENGINE_NAME: GigEngine"
2768    
2769             "VOLUME: 1.0"
2770    
2771  Schoenebeck            Expires November 19, 2005               [Page 40]           "AUDIO_OUTPUT_DEVICE: 0"
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
2772    
2773             "AUDIO_OUTPUT_CHANNELS: 2"
2774    
2775           "AUDIO_OUTPUT_ROUTING: 0,1"           "AUDIO_OUTPUT_ROUTING: 0,1"
2776    
2777           "INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"           "INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"
2778    
2779           "INSTRUMENT_NR: 0"           "INSTRUMENT_NR: 0"
2780    
2781           "INSTRUMENT_NAME: Fazioli Piano"           "INSTRUMENT_NAME: Fazioli Piano"
2782    
2783           "INSTRUMENT_STATUS: 100"           "INSTRUMENT_STATUS: 100"
2784    
2785           "MIDI_INPUT_DEVICE: 0"           "MIDI_INPUT_DEVICE: 0"
2786    
2787           "MIDI_INPUT_PORT: 0"           "MIDI_INPUT_PORT: 0"
2788    
2789           "MIDI_INPUT_CHANNEL: 5"           "MIDI_INPUT_CHANNEL: 5"
2790    
2791           "."           "."
2792    
2793  5.4.11  Current number of active voices  
2794    
2795    
2796    
2797    
2798    
2799    Schoenebeck               Expires May 30, 2007                 [Page 50]
2800    
2801    Internet-Draft        LinuxSampler Control Protocol        November 2006
2802    
2803    
2804    6.4.11.  Current number of active voices
2805    
2806     The front-end can ask for the current number of active voices on a     The front-end can ask for the current number of active voices on a
2807     sampler channel by sending the following command:     sampler channel by sending the following command:
# Line 2259  Internet-Draft       LinuxSampler Contro Line 2809  Internet-Draft       LinuxSampler Contro
2809        GET CHANNEL VOICE_COUNT <sampler-channel>        GET CHANNEL VOICE_COUNT <sampler-channel>
2810    
2811     Where <sampler-channel> is the sampler channel number the front-end     Where <sampler-channel> is the sampler channel number the front-end
2812     is interested in.     is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2813       "LIST CHANNELS" (Section 6.4.4) command.
2814    
2815     Possible Answers:     Possible Answers:
2816    
# Line 2270  Internet-Draft       LinuxSampler Contro Line 2821  Internet-Draft       LinuxSampler Contro
2821    
2822    
2823    
2824  5.4.12  Current number of active disk streams  6.4.12.  Current number of active disk streams
2825    
2826     The front-end can ask for the current number of active disk streams     The front-end can ask for the current number of active disk streams
2827     on a sampler channel by sending the following command:     on a sampler channel by sending the following command:
# Line 2278  Internet-Draft       LinuxSampler Contro Line 2829  Internet-Draft       LinuxSampler Contro
2829        GET CHANNEL STREAM_COUNT <sampler-channel>        GET CHANNEL STREAM_COUNT <sampler-channel>
2830    
2831     Where <sampler-channel> is the sampler channel number the front-end     Where <sampler-channel> is the sampler channel number the front-end
2832     is interested in.     is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2833       "LIST CHANNELS" (Section 6.4.4) command.
2834    
2835     Possible Answers:     Possible Answers:
2836    
# Line 2291  Internet-Draft       LinuxSampler Contro Line 2843  Internet-Draft       LinuxSampler Contro
2843    
2844    
2845    
2846    6.4.13.  Current fill state of disk stream buffers
2847    
2848  Schoenebeck            Expires November 19, 2005               [Page 41]     The front-end can ask for the current fill state of all disk streams
2849       on a sampler channel by sending the following command:
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
2850    
2851    
2852    
2853    
 5.4.13  Current fill state of disk stream buffers  
2854    
2855     The front-end can ask for the current fill state of all disk streams  Schoenebeck               Expires May 30, 2007                 [Page 51]
2856     on a sampler channel by sending the following command:  
2857    Internet-Draft        LinuxSampler Control Protocol        November 2006
2858    
2859    
2860        GET CHANNEL BUFFER_FILL BYTES <sampler-channel>        GET CHANNEL BUFFER_FILL BYTES <sampler-channel>
2861    
# Line 2311  Internet-Draft       LinuxSampler Contro Line 2864  Internet-Draft       LinuxSampler Contro
2864        GET CHANNEL BUFFER_FILL PERCENTAGE <sampler-channel>        GET CHANNEL BUFFER_FILL PERCENTAGE <sampler-channel>
2865    
2866     to get the fill state in percent, where <sampler-channel> is the     to get the fill state in percent, where <sampler-channel> is the
2867     sampler channel number the front-end is interested in.     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    
2871     Possible Answers:     Possible Answers:
2872    
# Line 2329  Internet-Draft       LinuxSampler Contro Line 2884  Internet-Draft       LinuxSampler Contro
2884     Examples:     Examples:
2885    
2886        C: "GET CHANNEL BUFFER_FILL BYTES 4"        C: "GET CHANNEL BUFFER_FILL BYTES 4"
2887    
2888        S: "[115]420500,[116]510300,[75]110000,[120]230700"        S: "[115]420500,[116]510300,[75]110000,[120]230700"
2889    
2890        C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"        C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
2891    
2892        S: "[115]90%,[116]98%,[75]40%,[120]62%"        S: "[115]90%,[116]98%,[75]40%,[120]62%"
2893    
2894        C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"        C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
2895    
2896        S: ""        S: ""
2897    
2898  5.4.14  Setting audio output device  6.4.14.  Setting audio output device
2899    
2900     The front-end can set the audio output device on a specific sampler     The front-end can set the audio output device on a specific sampler
2901     channel by sending the following command:     channel by sending the following command:
# Line 2343  Internet-Draft       LinuxSampler Contro Line 2903  Internet-Draft       LinuxSampler Contro
2903        SET CHANNEL AUDIO_OUTPUT_DEVICE <sampler-channel>        SET CHANNEL AUDIO_OUTPUT_DEVICE <sampler-channel>
2904        <audio-device-id>        <audio-device-id>
2905    
2906     Where <audio-device-id> is the numerical ID of the audio output     Where <sampler-channel> is the respective sampler channel number as
2907     device and <sampler-channel> is the respective sampler channel     returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
2908    
2909    
2910    
2911  Schoenebeck            Expires November 19, 2005               [Page 42]  Schoenebeck               Expires May 30, 2007                 [Page 52]
2912    
2913  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
2914    
2915    
2916     number.     (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    
2921     Possible Answers:     Possible Answers:
2922    
2923        "OK" -        "OK" -
2924    
2925           on success           on success
2926    
2927        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
2928    
2929           if audio output device was set, but there are noteworthy           if audio output device was set, but there are noteworthy
2930           issue(s) related, providing an appropriate warning code and           issue(s) related, providing an appropriate warning code and
2931           warning message           warning message
2932    
2933        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
2934    
2935           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
2936           error message           error message
2937    
# Line 2371  Internet-Draft       LinuxSampler Contro Line 2939  Internet-Draft       LinuxSampler Contro
2939    
2940    
2941    
2942  5.4.15  Setting audio output type  6.4.15.  Setting audio output type
2943    
2944     DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!     DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
2945    
2946     The front-end can alter the audio output type on a specific sampler     The front-end can alter the audio output type on a specific sampler
2947     channel by sending the following command:     channel by sending the following command:
2948    
2949        SET CHANNEL AUDIO_OUTPUT_TYPE <sampler-channel>        SET CHANNEL AUDIO_OUTPUT_TYPE <sampler-channel> <audio-output-
2950        <audio-output-type>        type>
2951    
2952     Where <audio-output-type> is currently either "ALSA" or "JACK" and     Where <audio-output-type> is currently either "ALSA" or "JACK" and
2953     <sampler-channel> is the respective sampler channel number.     <sampler-channel> is the respective sampler channel number.
# Line 2387  Internet-Draft       LinuxSampler Contro Line 2955  Internet-Draft       LinuxSampler Contro
2955     Possible Answers:     Possible Answers:
2956    
2957        "OK" -        "OK" -
2958    
2959           on success           on success
2960    
2961        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
2962    
2963    
2964    
2965    
2966    
2967    Schoenebeck               Expires May 30, 2007                 [Page 53]
2968    
2969    Internet-Draft        LinuxSampler Control Protocol        November 2006
2970    
2971    
2972           if audio output type was set, but there are noteworthy issue(s)           if audio output type was set, but there are noteworthy issue(s)
2973           related, providing an appropriate warning code and warning           related, providing an appropriate warning code and warning
2974           message           message
2975    
2976        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
2977    
2978           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
2979           error message           error message
2980    
# Line 2400  Internet-Draft       LinuxSampler Contro Line 2982  Internet-Draft       LinuxSampler Contro
2982    
2983    
2984    
2985    6.4.16.  Setting audio output channel
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 43]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
 5.4.16  Setting audio output channel  
2986    
2987     The front-end can alter the audio output channel on a specific     The front-end can alter the audio output channel on a specific
2988     sampler channel by sending the following command:     sampler channel by sending the following command:
# Line 2417  Internet-Draft       LinuxSampler Contro Line 2990  Internet-Draft       LinuxSampler Contro
2990        SET CHANNEL AUDIO_OUTPUT_CHANNEL <sampler-chan> <audio-out>        SET CHANNEL AUDIO_OUTPUT_CHANNEL <sampler-chan> <audio-out>
2991        <audio-in>        <audio-in>
2992    
2993     Where <sampler-chan> is the sampler channel number, <audio-out> is     Where <sampler-chan> is the sampler channel number as returned by the
2994     the numerical ID of the sampler channel's audio output channel which     "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
2995     should be rerouted and <audio-in> is the numerical ID of the audio     command, <audio-out> is the numerical ID of the sampler channel's
2996     channel of the selected audio output device where <audio-out> should     audio output channel which should be rerouted and <audio-in> is the
2997     be routed to.     numerical ID of the audio channel of the selected audio output device
2998       where <audio-out> should be routed to.
2999    
3000     Possible Answers:     Possible Answers:
3001    
3002        "OK" -        "OK" -
3003    
3004           on success           on success
3005    
3006        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
3007    
3008           if audio output channel was set, but there are noteworthy           if audio output channel was set, but there are noteworthy
3009           issue(s) related, providing an appropriate warning code and           issue(s) related, providing an appropriate warning code and
3010           warning message           warning message
3011    
3012        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
3013    
3014           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
3015           error message           error message
3016    
# Line 2439  Internet-Draft       LinuxSampler Contro Line 3018  Internet-Draft       LinuxSampler Contro
3018    
3019    
3020    
3021  5.4.17  Setting MIDI input device  
3022    
3023    Schoenebeck               Expires May 30, 2007                 [Page 54]
3024    
3025    Internet-Draft        LinuxSampler Control Protocol        November 2006
3026    
3027    
3028    
3029    
3030    6.4.17.  Setting MIDI input device
3031    
3032     The front-end can set the MIDI input device on a specific sampler     The front-end can set the MIDI input device on a specific sampler
3033     channel by sending the following command:     channel by sending the following command:
3034    
3035        SET CHANNEL MIDI_INPUT_DEVICE <sampler-channel> <midi-device-id>        SET CHANNEL MIDI_INPUT_DEVICE <sampler-channel> <midi-device-id>
3036    
3037     Where <sampler-channel> is the sampler channel number and     Where <sampler-channel> is the sampler channel number as returned by
3038     <midi-device-id> is the the numerical ID of the MIDI input device.     the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3039       command and <midi-device-id> is the numerical ID of the MIDI input
3040       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    
3043     Possible Answers:     Possible Answers:
3044    
3045        "OK" -        "OK" -
3046    
3047           on success           on success
3048    
3049        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
3050    
3051           if MIDI input device was set, but there are noteworthy issue(s)           if MIDI input device was set, but there are noteworthy issue(s)
3052           related, providing an appropriate warning code and warning           related, providing an appropriate warning code and warning
3053           message           message
3054    
   
   
 Schoenebeck            Expires November 19, 2005               [Page 44]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
3055        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
3056    
3057           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
3058           error message           error message
3059    
# Line 2473  Internet-Draft       LinuxSampler Contro Line 3061  Internet-Draft       LinuxSampler Contro
3061    
3062    
3063    
3064  5.4.18  Setting MIDI input type  6.4.18.  Setting MIDI input type
3065    
3066     DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!     DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
3067    
# Line 2482  Internet-Draft       LinuxSampler Contro Line 3070  Internet-Draft       LinuxSampler Contro
3070    
3071        SET CHANNEL MIDI_INPUT_TYPE <sampler-channel> <midi-input-type>        SET CHANNEL MIDI_INPUT_TYPE <sampler-channel> <midi-input-type>
3072    
3073     Where <midi-input-type> is currently only "ALSA" and     Where <midi-input-type> is currently only "ALSA" and <sampler-
3074     <sampler-channel> is the respective sampler channel number.     channel> is the respective sampler channel number.
3075    
3076    
3077    
3078    
3079    Schoenebeck               Expires May 30, 2007                 [Page 55]
3080    
3081    Internet-Draft        LinuxSampler Control Protocol        November 2006
3082    
3083    
3084     Possible Answers:     Possible Answers:
3085    
3086        "OK" -        "OK" -
3087    
3088           on success           on success
3089    
3090        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
3091    
3092           if MIDI input type was set, but there are noteworthy issue(s)           if MIDI input type was set, but there are noteworthy issue(s)
3093           related, providing an appropriate warning code and warning           related, providing an appropriate warning code and warning
3094           message           message
3095    
3096        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
3097    
3098           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
3099           error message           error message
3100    
# Line 2501  Internet-Draft       LinuxSampler Contro Line 3102  Internet-Draft       LinuxSampler Contro
3102    
3103    
3104    
3105  5.4.19  Setting MIDI input port  6.4.19.  Setting MIDI input port
3106    
3107     The front-end can alter the MIDI input port on a specific sampler     The front-end can alter the MIDI input port on a specific sampler
3108     channel by sending the following command:     channel by sending the following command:
# Line 2513  Internet-Draft       LinuxSampler Contro Line 3114  Internet-Draft       LinuxSampler Contro
3114    
3115     Possible Answers:     Possible Answers:
3116    
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 45]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
3117        "OK" -        "OK" -
3118    
3119           on success           on success
3120    
3121        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
3122    
3123           if MIDI input port was set, but there are noteworthy issue(s)           if MIDI input port was set, but there are noteworthy issue(s)
3124           related, providing an appropriate warning code and warning           related, providing an appropriate warning code and warning
3125           message           message
3126    
3127        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
3128    
3129           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
3130           error message           error message
3131    
3132    
3133    
3134    
3135    Schoenebeck               Expires May 30, 2007                 [Page 56]
3136    
3137    Internet-Draft        LinuxSampler Control Protocol        November 2006
3138    
3139    
3140     Examples:     Examples:
3141    
3142    
3143    
3144  5.4.20  Setting MIDI input channel  6.4.20.  Setting MIDI input channel
3145    
3146     The front-end can alter the MIDI channel a sampler channel should     The front-end can alter the MIDI channel a sampler channel should
3147     listen to by sending the following command:     listen to by sending the following command:
# Line 2549  Internet-Draft       LinuxSampler Contro Line 3155  Internet-Draft       LinuxSampler Contro
3155     Possible Answers:     Possible Answers:
3156    
3157        "OK" -        "OK" -
3158    
3159           on success           on success
3160    
3161        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
3162    
3163           if MIDI input channel was set, but there are noteworthy           if MIDI input channel was set, but there are noteworthy
3164           issue(s) related, providing an appropriate warning code and           issue(s) related, providing an appropriate warning code and
3165           warning message           warning message
3166    
3167        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
3168    
3169           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
3170           error message           error message
3171    
# Line 2562  Internet-Draft       LinuxSampler Contro Line 3173  Internet-Draft       LinuxSampler Contro
3173    
3174    
3175    
3176  5.4.21  Setting channel volume  6.4.21.  Setting channel volume
3177    
3178     The front-end can alter the volume of a sampler channel by sending     The front-end can alter the volume of a sampler channel by sending
3179     the following command:     the following command:
3180    
3181        SET CHANNEL VOLUME <sampler-channel> <volume>        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    
3189    
 Schoenebeck            Expires November 19, 2005               [Page 46]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
3190    
3191    Schoenebeck               Expires May 30, 2007                 [Page 57]
3192    
3193    Internet-Draft        LinuxSampler Control Protocol        November 2006
3194    
    Where <volume> is an optionally dotted positive number (a value  
    smaller than 1.0 means attenuation, whereas a value greater than 1.0  
    means amplification) and <sampler-channel> defines the sampler  
    channel where this volume factor should be set.  
3195    
3196     Possible Answers:     Possible Answers:
3197    
3198        "OK" -        "OK" -
3199    
3200           on success           on success
3201    
3202        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
3203    
3204           if channel volume was set, but there are noteworthy issue(s)           if channel volume was set, but there are noteworthy issue(s)
3205           related, providing an appropriate warning code and warning           related, providing an appropriate warning code and warning
3206           message           message
3207    
3208        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
3209    
3210           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
3211           error message           error message
3212    
# Line 2598  Internet-Draft       LinuxSampler Contro Line 3214  Internet-Draft       LinuxSampler Contro
3214    
3215    
3216    
3217  5.4.22  Resetting a sampler channel  6.4.22.  Muting a sampler channel
3218    
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          "ERR:<error-code>:<error-message>" -
3242    
3243    
3244    
3245    
3246    
3247    Schoenebeck               Expires May 30, 2007                 [Page 58]
3248    
3249    Internet-Draft        LinuxSampler Control Protocol        November 2006
3250    
3251    
3252             in case it failed, providing an appropriate error code and
3253             error message
3254    
3255       Examples:
3256    
3257    
3258    
3259    6.4.23.  Soloing a sampler channel
3260    
3261       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    6.4.24.  Resetting a sampler channel
3293    
3294     The front-end can reset a particular sampler channel by sending the     The front-end can reset a particular sampler channel by sending the
3295     following command:     following command:
# Line 2606  Internet-Draft       LinuxSampler Contro Line 3297  Internet-Draft       LinuxSampler Contro
3297        RESET CHANNEL <sampler-channel>        RESET CHANNEL <sampler-channel>
3298    
3299     Where <sampler-channel> defines the sampler channel to be reset.     Where <sampler-channel> defines the sampler channel to be reset.
3300    
3301    
3302    
3303    Schoenebeck               Expires May 30, 2007                 [Page 59]
3304    
3305    Internet-Draft        LinuxSampler Control Protocol        November 2006
3306    
3307    
3308     This will cause the engine on that sampler channel, its voices and     This will cause the engine on that sampler channel, its voices and
3309     eventually disk streams and all control and status variables to be     eventually disk streams and all control and status variables to be
3310     reset.     reset.
# Line 2613  Internet-Draft       LinuxSampler Contro Line 3312  Internet-Draft       LinuxSampler Contro
3312     Possible Answers:     Possible Answers:
3313    
3314        "OK" -        "OK" -
3315    
3316           on success           on success
3317    
3318        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
3319    
3320           if channel was reset, but there are noteworthy issue(s)           if channel was reset, but there are noteworthy issue(s)
3321           related, providing an appropriate warning code and warning           related, providing an appropriate warning code and warning
3322           message           message
3323    
3324        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
3325    
3326           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
3327           error message           error message
3328    
# Line 2626  Internet-Draft       LinuxSampler Contro Line 3330  Internet-Draft       LinuxSampler Contro
3330    
3331    
3332    
3333    6.5.  Controlling connection
   
 Schoenebeck            Expires November 19, 2005               [Page 47]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
   
   
 5.5  Controlling connection  
3334    
3335     The following commands are used to control the connection to     The following commands are used to control the connection to
3336     LinuxSampler.     LinuxSampler.
3337    
3338  5.5.1  Register front-end for receiving event messages  6.5.1.  Register front-end for receiving event messages
3339    
3340     The front-end can register itself to the LinuxSampler application to     The front-end can register itself to the LinuxSampler application to
3341     be informed about noteworthy events by sending this command:     be informed about noteworthy events by sending this command:
# Line 2653  Internet-Draft       LinuxSampler Contro Line 3348  Internet-Draft       LinuxSampler Contro
3348     Possible Answers:     Possible Answers:
3349    
3350        "OK" -        "OK" -
3351    
3352           on success           on success
3353    
3354    
3355    
3356    
3357    
3358    
3359    Schoenebeck               Expires May 30, 2007                 [Page 60]
3360    
3361    Internet-Draft        LinuxSampler Control Protocol        November 2006
3362    
3363    
3364        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
3365    
3366           if registration succeeded, but there are noteworthy issue(s)           if registration succeeded, but there are noteworthy issue(s)
3367           related, providing an appropriate warning code and warning           related, providing an appropriate warning code and warning
3368           message           message
3369    
3370        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
3371    
3372           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
3373           error message           error message
3374    
# Line 2666  Internet-Draft       LinuxSampler Contro Line 3376  Internet-Draft       LinuxSampler Contro
3376    
3377    
3378    
3379  5.5.2  Unregister front-end for not receiving event messages  6.5.2.  Unregister front-end for not receiving event messages
3380    
3381     The front-end can unregister itself if it doesn't want to receive     The front-end can unregister itself if it doesn't want to receive
3382     event messages anymore by sending the following command:     event messages anymore by sending the following command:
# Line 2679  Internet-Draft       LinuxSampler Contro Line 3389  Internet-Draft       LinuxSampler Contro
3389     Possible Answers:     Possible Answers:
3390    
3391        "OK" -        "OK" -
          on success  
   
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 48]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
3392    
3393             on success
3394    
3395        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
3396    
3397           if unregistration succeeded, but there are noteworthy issue(s)           if unregistration succeeded, but there are noteworthy issue(s)
3398           related, providing an appropriate warning code and warning           related, providing an appropriate warning code and warning
3399           message           message
3400    
3401        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
3402    
3403           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
3404           error message           error message
3405    
# Line 2701  Internet-Draft       LinuxSampler Contro Line 3407  Internet-Draft       LinuxSampler Contro
3407    
3408    
3409    
3410  5.5.3  Enable or disable echo of commands  
3411    
3412    
3413    
3414    
3415    Schoenebeck               Expires May 30, 2007                 [Page 61]
3416    
3417    Internet-Draft        LinuxSampler Control Protocol        November 2006
3418    
3419    
3420    6.5.3.  Enable or disable echo of commands
3421    
3422     To enable or disable back sending of commands to the client the     To enable or disable back sending of commands to the client the
3423     following command can be used:     following command can be used:
# Line 2718  Internet-Draft       LinuxSampler Contro Line 3434  Internet-Draft       LinuxSampler Contro
3434     Possible Answers:     Possible Answers:
3435    
3436        "OK" -        "OK" -
3437    
3438           usually           usually
3439    
3440        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
3441           on syntax error, e.g.  non boolean value  
3442             on syntax error, e.g. non boolean value
3443    
3444     Examples:     Examples:
3445    
3446    
3447    
3448  5.5.4  Close client connection  6.5.4.  Close client connection
3449    
3450     The client can close its network connection to LinuxSampler by     The client can close its network connection to LinuxSampler by
3451     sending the following command:     sending the following command:
# Line 2736  Internet-Draft       LinuxSampler Contro Line 3455  Internet-Draft       LinuxSampler Contro
3455     This is probably more interesting for manual telnet connections to     This is probably more interesting for manual telnet connections to
3456     LinuxSampler than really useful for a front-end implementation.     LinuxSampler than really useful for a front-end implementation.
3457    
3458    6.6.  Global commands
3459    
3460       The following commands have global impact on the sampler.
3461    
3462    6.6.1.  Current number of active voices
3463    
3464       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            Expires November 19, 2005               [Page 49]  Schoenebeck               Expires May 30, 2007                 [Page 62]
3472    
3473  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
3474    
3475    
3476  5.6  Global commands        GET TOTAL_VOICE_COUNT
3477    
3478     The following commands have global impact on the sampler.     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  5.6.1  Reset sampler        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     The front-end can reset the whole sampler by sending the following     The front-end can reset the whole sampler by sending the following
3498     command:     command:
# Line 2759  Internet-Draft       LinuxSampler Contro Line 3502  Internet-Draft       LinuxSampler Contro
3502     Possible Answers:     Possible Answers:
3503    
3504        "OK" -        "OK" -
3505    
3506           always           always
3507    
3508     Examples:     Examples:
3509    
3510    
3511    
3512    6.6.4.  General sampler informations
3513    
3514       The client can ask for general informations about the LinuxSampler
3515       instance by sending the following command:
3516    
3517          GET SERVER INFO
3518    
3519       Possible Answers:
3520    
3521          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    
3525    
3526    
3527    Schoenebeck               Expires May 30, 2007                 [Page 63]
3528    
3529    Internet-Draft        LinuxSampler Control Protocol        November 2006
3530    
3531    
3532          character string to that information category.  At the moment the
3533          following categories are defined:
3534    
3535    
3536    
3537             DESCRIPTION -
3538    
3539                arbitrary textual description about the sampler
3540    
3541             VERSION -
3542    
3543                version of the sampler
3544    
3545             PROTOCOL_VERSION -
3546    
3547                version of the LSCP specification the sampler complies with
3548                (see Section 2 for details)
3549    
3550       The mentioned fields above don't have to be in particular order.
3551       Other fields might be added in future.
3552    
3553    6.7.  MIDI Instrument Mapping
3554    
3555       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    
3561       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    
3568       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    
3575    6.7.1.  Create or replace a MIDI instrument map entry
3576    
3577       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    
3580    
3581    
3582    
3583    Schoenebeck               Expires May 30, 2007                 [Page 64]
3584    
3585    Internet-Draft        LinuxSampler Control Protocol        November 2006
3586    
3587    
3588          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    
3592       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    
3610          "ON_DEMAND" -
3611    
3612             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    
3617          "ON_DEMAND_HOLD" -
3618    
3619             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    
3627          "PERSISTENT" -
3628    
3629             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    
3637    
3638    
3639    Schoenebeck               Expires May 30, 2007                 [Page 65]
3640    
3641    Internet-Draft        LinuxSampler Control Protocol        November 2006
3642    
3643    
3644          not supplied -
3645    
3646             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    
3654       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    
3673       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    
3680       Possible Answers:
3681    
3682          "OK" -
3683    
3684             usually
3685    
3686          "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    
3697    Internet-Draft        LinuxSampler Control Protocol        November 2006
3698    
3699    
3700          C: "MAP MIDI_INSTRUMENT 3 0 0 gig '/usr/share/Steinway D.gig' 0
3701          0.8 PERSISTENT"
3702    
3703          S: "OK"
3704    
3705  Schoenebeck            Expires November 19, 2005               [Page 50]        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              May 2005  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  6.  Command Syntax     Example:
3769    
3770     TODO: will soon automatically included from src/network/lscp.y,        C: "LIST MIDI_INSTRUMENTS"
    meanwhile have a look at that file to get the exact definition of the  
    command syntax.  
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  Schoenebeck            Expires November 19, 2005               [Page 51]     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              May 2005  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  7.  Events  
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    7.  Command Syntax
3981    
3982       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    
3986       input =
3987    
3988          line LF
3989    
3990          / line CR LF
3991    
3992       line =
3993    
3994          /* epsilon (empty line ignored) */
3995    
3996          / comment
3997    
3998          / command
3999    
4000          / error
4001    
4002       comment =
4003    
4004          '#'
4005    
4006          / comment '#'
4007    
4008          / comment SP
4009    
4010          / comment number
4011    
4012          / comment string
4013    
4014       command =
4015    
4016          ADD SP CHANNEL
4017    
4018          / MAP SP map_instruction
4019    
4020          / UNMAP SP unmap_instruction
4021    
4022          / GET SP get_instruction
4023    
4024          / CREATE SP create_instruction
4025    
4026          / DESTROY SP destroy_instruction
4027    
4028    
4029    
4030    
4031    Schoenebeck               Expires May 30, 2007                 [Page 72]
4032    
4033    Internet-Draft        LinuxSampler Control Protocol        November 2006
4034    
4035    
4036          / LIST SP list_instruction
4037    
4038          / LOAD SP load_instruction
4039    
4040          / REMOVE SP remove_instruction
4041    
4042          / SET SP set_instruction
4043    
4044          / SUBSCRIBE SP subscribe_event
4045    
4046          / UNSUBSCRIBE SP unsubscribe_event
4047    
4048          / SELECT SP text
4049    
4050          / RESET SP reset_instruction
4051    
4052          / CLEAR SP clear_instruction
4053    
4054          / RESET
4055    
4056          / QUIT
4057    
4058       subscribe_event =
4059    
4060          CHANNEL_COUNT
4061    
4062          / VOICE_COUNT
4063    
4064          / STREAM_COUNT
4065    
4066          / BUFFER_FILL
4067    
4068          / CHANNEL_INFO
4069    
4070          / MISCELLANEOUS
4071    
4072          / TOTAL_VOICE_COUNT
4073    
4074       unsubscribe_event =
4075    
4076          CHANNEL_COUNT
4077    
4078          / VOICE_COUNT
4079    
4080          / STREAM_COUNT
4081    
4082          / BUFFER_FILL
4083    
4084    
4085    
4086    
4087    Schoenebeck               Expires May 30, 2007                 [Page 73]
4088    
4089    Internet-Draft        LinuxSampler Control Protocol        November 2006
4090    
4091    
4092          / CHANNEL_INFO
4093    
4094          / MISCELLANEOUS
4095    
4096          / TOTAL_VOICE_COUNT
4097    
4098       map_instruction =
4099    
4100          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    
4103          / 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    
4107          / 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    
4111          / 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    
4115       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       get_instruction =
4124    
4125          AVAILABLE_ENGINES
4126    
4127          / AVAILABLE_MIDI_INPUT_DRIVERS
4128    
4129          / MIDI_INPUT_DRIVER SP INFO SP string
4130    
4131          / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
4132    
4133          / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP
4134          key_val_list
4135    
4136          / AVAILABLE_AUDIO_OUTPUT_DRIVERS
4137    
4138          / AUDIO_OUTPUT_DRIVER SP INFO SP string
4139    
4140    
4141    
4142    
4143    Schoenebeck               Expires May 30, 2007                 [Page 74]
4144    
4145    Internet-Draft        LinuxSampler Control Protocol        November 2006
4146    
4147    
4148          / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
4149    
4150          / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP
4151          key_val_list
4152    
4153          / AUDIO_OUTPUT_DEVICES
4154    
4155          / MIDI_INPUT_DEVICES
4156    
4157          / AUDIO_OUTPUT_DEVICE SP INFO SP number
4158    
4159          / MIDI_INPUT_DEVICE SP INFO SP number
4160    
4161          / MIDI_INPUT_PORT SP INFO SP number SP number
4162    
4163          / MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
4164    
4165          / AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
4166    
4167          / AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP
4168          string
4169    
4170          / CHANNELS
4171    
4172          / CHANNEL SP INFO SP sampler_channel
4173    
4174          / CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
4175    
4176          / CHANNEL SP STREAM_COUNT SP sampler_channel
4177    
4178          / CHANNEL SP VOICE_COUNT SP sampler_channel
4179    
4180          / ENGINE SP INFO SP engine_name
4181    
4182          / SERVER SP INFO
4183    
4184          / TOTAL_VOICE_COUNT
4185    
4186          / TOTAL_VOICE_COUNT_MAX
4187    
4188          / MIDI_INSTRUMENTS
4189    
4190          / MIDI_INSTRUMENT SP INFO SP midi_bank_msb SP midi_bank_lsb SP
4191          midi_prog
4192    
4193       set_instruction =
4194    
4195    
4196    
4197    
4198    
4199    Schoenebeck               Expires May 30, 2007                 [Page 75]
4200    
4201    Internet-Draft        LinuxSampler Control Protocol        November 2006
4202    
4203    
4204          AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '='
4205          param_val_list
4206    
4207          / AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '='
4208          param_val_list
4209    
4210          / MIDI_INPUT_DEVICE_PARAMETER SP number SP string '='
4211          param_val_list
4212    
4213          / MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '='
4214          param_val_list
4215    
4216          / CHANNEL SP set_chan_instruction
4217    
4218          / ECHO SP boolean
4219    
4220       create_instruction =
4221    
4222          AUDIO_OUTPUT_DEVICE SP string SP key_val_list
4223    
4224          / AUDIO_OUTPUT_DEVICE SP string
4225    
4226          / MIDI_INPUT_DEVICE SP string SP key_val_list
4227    
4228          / MIDI_INPUT_DEVICE SP string
4229    
4230       reset_instruction =
4231    
4232          CHANNEL SP sampler_channel
4233    
4234       clear_instruction =
4235    
4236          MIDI_INSTRUMENTS
4237    
4238       destroy_instruction =
4239    
4240          AUDIO_OUTPUT_DEVICE SP number
4241    
4242          / MIDI_INPUT_DEVICE SP number
4243    
4244       load_instruction =
4245    
4246          INSTRUMENT SP load_instr_args
4247    
4248          / ENGINE SP load_engine_args
4249    
4250       set_chan_instruction =
4251    
4252    
4253    
4254    
4255    Schoenebeck               Expires May 30, 2007                 [Page 76]
4256    
4257    Internet-Draft        LinuxSampler Control Protocol        November 2006
4258    
4259    
4260          AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
4261    
4262          / AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index
4263          SP audio_channel_index
4264    
4265          / AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
4266    
4267          / MIDI_INPUT SP sampler_channel SP device_index SP
4268          midi_input_port_index SP midi_input_channel_index
4269    
4270          / MIDI_INPUT_DEVICE SP sampler_channel SP device_index
4271    
4272          / MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
4273    
4274          / MIDI_INPUT_CHANNEL SP sampler_channel SP
4275          midi_input_channel_index
4276    
4277          / MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
4278    
4279          / VOLUME SP sampler_channel SP volume_value
4280    
4281          / MUTE SP sampler_channel SP boolean
4282    
4283          / SOLO SP sampler_channel SP boolean
4284    
4285       key_val_list =
4286    
4287          string '=' param_val_list
4288    
4289          / key_val_list SP string '=' param_val_list
4290    
4291       buffer_size_type =
4292    
4293          BYTES
4294    
4295          / PERCENTAGE
4296    
4297       list_instruction =
4298    
4299          AUDIO_OUTPUT_DEVICES
4300    
4301          / MIDI_INPUT_DEVICES
4302    
4303          / CHANNELS
4304    
4305          / AVAILABLE_ENGINES
4306    
4307    
4308    
4309    
4310    
4311    Schoenebeck               Expires May 30, 2007                 [Page 77]
4312    
4313    Internet-Draft        LinuxSampler Control Protocol        November 2006
4314    
4315    
4316          / AVAILABLE_MIDI_INPUT_DRIVERS
4317    
4318          / AVAILABLE_AUDIO_OUTPUT_DRIVERS
4319    
4320          / MIDI_INSTRUMENTS
4321    
4322       load_instr_args =
4323    
4324          filename SP instrument_index SP sampler_channel
4325    
4326          / NON_MODAL SP filename SP instrument_index SP sampler_channel
4327    
4328       load_engine_args =
4329    
4330          engine_name SP sampler_channel
4331    
4332       instr_load_mode =
4333    
4334          ON_DEMAND
4335    
4336          / ON_DEMAND_HOLD
4337    
4338          / PERSISTENT
4339    
4340       device_index =
4341    
4342          number
4343    
4344       audio_channel_index =
4345    
4346          number
4347    
4348       audio_output_type_name =
4349    
4350          string
4351    
4352       midi_input_port_index =
4353    
4354          number
4355    
4356       midi_input_channel_index =
4357    
4358          number
4359    
4360          / ALL
4361    
4362       midi_input_type_name =
4363    
4364    
4365    
4366    
4367    Schoenebeck               Expires May 30, 2007                 [Page 78]
4368    
4369    Internet-Draft        LinuxSampler Control Protocol        November 2006
4370    
4371    
4372          string
4373    
4374       midi_bank_msb =
4375    
4376          number
4377    
4378       midi_bank_lsb =
4379    
4380          number
4381    
4382       midi_prog =
4383    
4384          number
4385    
4386       volume_value =
4387    
4388          dotnum
4389    
4390          / number
4391    
4392       sampler_channel =
4393    
4394          number
4395    
4396       instrument_index =
4397    
4398          number
4399    
4400       engine_name =
4401    
4402          string
4403    
4404       filename =
4405    
4406          stringval
4407    
4408       entry_name =
4409    
4410          stringval
4411    
4412       param_val_list =
4413    
4414          param_val
4415    
4416          / param_val_list','param_val
4417    
4418       param_val =
4419    
4420    
4421    
4422    
4423    Schoenebeck               Expires May 30, 2007                 [Page 79]
4424    
4425    Internet-Draft        LinuxSampler Control Protocol        November 2006
4426    
4427    
4428          string
4429    
4430          / stringval
4431    
4432          / number
4433    
4434          / dotnum
4435    
4436    
4437    
4438    
4439    
4440    
4441    
4442    
4443    
4444    
4445    
4446    
4447    
4448    
4449    
4450    
4451    
4452    
4453    
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    
4481    Internet-Draft        LinuxSampler Control Protocol        November 2006
4482    
4483    
4484    8.  Events
4485    
4486     This chapter will describe all currently defined events supported by     This chapter will describe all currently defined events supported by
4487     LinuxSampler.     LinuxSampler.
4488    
4489  7.1  Number of sampler channels changed  8.1.  Number of sampler channels changed
4490    
4491     Client may want to be notified when the total number of channels on     Client may want to be notified when the total number of channels on
4492     the back-end changes by issuing the following command:     the back-end changes by issuing the following command:
# Line 2876  Internet-Draft       LinuxSampler Contro Line 4500  Internet-Draft       LinuxSampler Contro
4500     where <channels> will be replaced by the new number of sampler     where <channels> will be replaced by the new number of sampler
4501     channels.     channels.
4502    
4503  7.2  Number of active voices changed  8.2.  Number of active voices changed
4504    
4505     Client may want to be notified when the number of voices on the     Client may want to be notified when the number of voices on the back-
4506     back-end changes by issuing the following command:     end changes by issuing the following command:
4507    
4508        SUBSCRIBE VOICE_COUNT        SUBSCRIBE VOICE_COUNT
4509    
# Line 2891  Internet-Draft       LinuxSampler Contro Line 4515  Internet-Draft       LinuxSampler Contro
4515     voice count change occurred and <voices> by the new number of active     voice count change occurred and <voices> by the new number of active
4516     voices on that channel.     voices on that channel.
4517    
4518  7.3  Number of active disk streams changed  8.3.  Number of active disk streams changed
4519    
4520     Client may want to be notified when the number of streams on the     Client may want to be notified when the number of streams on the
4521     back-end changes by issuing the following command: SUBSCRIBE     back-end changes by issuing the following command: SUBSCRIBE
# Line 2908  Internet-Draft       LinuxSampler Contro Line 4532  Internet-Draft       LinuxSampler Contro
4532    
4533    
4534    
4535  Schoenebeck            Expires November 19, 2005               [Page 52]  Schoenebeck               Expires May 30, 2007                 [Page 81]
4536    
4537  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
4538    
4539    
4540     active disk streams on that channel.     active disk streams on that channel.
4541    
4542  7.4  Disk stream buffer fill state changed  8.4.  Disk stream buffer fill state changed
4543    
4544     Client may want to be notified when the buffer fill state of a disk     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:     stream on the back-end changes by issuing the following command:
# Line 2928  Internet-Draft       LinuxSampler Contro Line 4552  Internet-Draft       LinuxSampler Contro
4552    
4553     where <sampler-channel> will be replaced by the sampler channel the     where <sampler-channel> will be replaced by the sampler channel the
4554     buffer fill state change occurred on and <fill-data> will be replaced     buffer fill state change occurred on and <fill-data> will be replaced
4555     by the buffer fill data for this channel as described in Section     by the buffer fill data for this channel as described in
4556     5.4.13 as if the "GET CHANNEL BUFFER_FILL PERCENTAGE" (Section     Section 6.4.13 as if the "GET CHANNEL BUFFER_FILL PERCENTAGE"
4557     5.4.13) command was issued on this channel.     (Section 6.4.13) command was issued on this channel.
4558    
4559  7.5  Channel information changed  8.5.  Channel information changed
4560    
4561     Client may want to be notified when changes were made to sampler     Client may want to be notified when changes were made to sampler
4562     channels on the back-end by issuing the following command:     channels on the back-end by issuing the following command:
# Line 2950  Internet-Draft       LinuxSampler Contro Line 4574  Internet-Draft       LinuxSampler Contro
4574     rather than real time events happening on the server, it is believed     rather than real time events happening on the server, it is believed
4575     that an empty notification message is sufficient here.     that an empty notification message is sufficient here.
4576    
4577  7.6  Miscellaneous and debugging events  8.6.  Total number of active voices changed
4578    
4579     Client may want to be notified of miscellaneous and debugging events     Client may want to be notified when the total number of voices on the
4580     occurring at the server by issuing the following command:     back-end changes by issuing the following command:
4581    
4582        SUBSCRIBE MISCELLANEOUS        SUBSCRIBE TOTAL_VOICE_COUNT
4583    
4584     Server will start sending the following notification messages:     Server will start sending the following notification messages:
4585    
       "NOTIFY:MISCELLANEOUS:<string>"  
   
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 53]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
    where <string> will be replaced by whatever data server wants to send  
    to the client.  Client MAY display this data to the user AS IS to  
    facilitate debugging.  
   
   
4586    
4587    
4588    
4589    
4590    
4591    Schoenebeck               Expires May 30, 2007                 [Page 82]
4592    
4593    Internet-Draft        LinuxSampler Control Protocol        November 2006
4594    
4595    
4596          "NOTIFY:TOTAL_VOICE_COUNT:<voices>
4597    
4598       where <voices> will be replaced by the new number of all currently
4599       active voices.
4600    
4601    8.7.  Miscellaneous and debugging events
4602    
4603       Client may want to be notified of miscellaneous and debugging events
4604       occurring at the server by issuing the following command:
4605    
4606          SUBSCRIBE MISCELLANEOUS
4607    
4608       Server will start sending the following notification messages:
4609    
4610          "NOTIFY:MISCELLANEOUS:<string>"
4611    
4612       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    
4616    
4617    
# Line 3020  Internet-Draft       LinuxSampler Contro Line 4644  Internet-Draft       LinuxSampler Contro
4644    
4645    
4646    
4647  Schoenebeck            Expires November 19, 2005               [Page 54]  Schoenebeck               Expires May 30, 2007                 [Page 83]
4648    
4649  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
4650    
4651    
4652  8.  Security Considerations  9.  Security Considerations
4653    
4654     As there is so far no method of authentication and authorization     As there is so far no method of authentication and authorization
4655     defined and so not required for a client applications to succeed to     defined and so not required for a client applications to succeed to
# Line 3076  Internet-Draft       LinuxSampler Contro Line 4700  Internet-Draft       LinuxSampler Contro
4700    
4701    
4702    
4703  Schoenebeck            Expires November 19, 2005               [Page 55]  Schoenebeck               Expires May 30, 2007                 [Page 84]
4704    
4705  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
4706    
4707    
4708  9.  Acknowledgments  10.  Acknowledgments
4709    
4710     This document has benefited greatly from the comments of the     This document has benefited greatly from the comments of the
4711     following people, discussed on the LinuxSampler developer's mailing     following people, discussed on the LinuxSampler developer's mailing
4712     list:     list:
4713    
4714        Rui Nuno Capela        Rui Nuno Capela
4715    
4716        Vladimir Senkov        Vladimir Senkov
4717    
4718        Mark Knecht        Mark Knecht
4719    
4720        Grigor Iliev        Grigor Iliev
4721    
4722  10  References  
4723    11.  References
4724    
4725     [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate     [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
4726                Requirement Levels", BCP 14, RFC 2119, March 1997.                Requirement Levels", RFC 2119, 1997.
4727    
4728       [RFC2234]  Crocker, D. and P. Overell, "Augmented BNF for Syntax
4729                  Specifications", RFC 2234, 1997.
4730    
4731       [RFC793]   Defense Advanced Research Projects Agency, "TRANSMISSION
4732                  CONTROL PROTOCOL", RFC 793, 1981.
4733    
4734    
4735    
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               Expires May 30, 2007                 [Page 85]
4760    
4761    Internet-Draft        LinuxSampler Control Protocol        November 2006
4762    
4763    
4764  Author's Address  Author's Address
# Line 3106  Author's Address Line 4769  Author's Address
4769     74081 Heilbronn     74081 Heilbronn
4770     Germany     Germany
4771    
4772     EMail: schoenebeck at software minus engineering dot org     Email: schoenebeck at software minus engineering dot org
4773    
4774    
4775    
4776    
4777    
4778    
4779    
4780    
4781    
4782    
4783    
4784    
4785    
4786    
4787    
4788    
4789    
4790    
4791    
4792    
# Line 3132  Author's Address Line 4812  Author's Address
4812    
4813    
4814    
4815  Schoenebeck            Expires November 19, 2005               [Page 56]  Schoenebeck               Expires May 30, 2007                 [Page 86]
4816    
4817  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
4818    
4819    
4820  Intellectual Property Statement  Intellectual Property Statement
# Line 3146  Intellectual Property Statement Line 4826  Intellectual Property Statement
4826     might or might not be available; neither does it represent that it     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     has made any effort to identify any such rights.  Information on the
4828     IETF's procedures with respect to rights in standards-track and     IETF's procedures with respect to rights in standards-track and
4829     standards-related documentation can be found in BCP-11.  Copies of     standards-related documentation can be found in BCP 11.  Copies of
4830     claims of rights made available for publication and any assurances of     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     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     obtain a general license or permission for the use of such
# Line 3162  Intellectual Property Statement Line 4842  Intellectual Property Statement
4842    
4843  Full Copyright Statement  Full Copyright Statement
4844    
4845     Copyright (C) The Internet Society (2005).  All Rights Reserved.     Copyright (C) The Internet Society (2006).  All Rights Reserved.
4846    
4847     This document and translations of it may be copied and furnished to     This document and translations of it may be copied and furnished to
4848     others, and derivative works that comment on or otherwise explain it     others, and derivative works that comment on or otherwise explain it
# Line 3188  Full Copyright Statement Line 4868  Full Copyright Statement
4868    
4869    
4870    
4871  Schoenebeck            Expires November 19, 2005               [Page 57]  Schoenebeck               Expires May 30, 2007                 [Page 87]
4872    
4873  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft        LinuxSampler Control Protocol        November 2006
4874    
4875    
4876     HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF     HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
# Line 3244  Acknowledgment Line 4924  Acknowledgment
4924    
4925    
4926    
4927  Schoenebeck            Expires November 19, 2005               [Page 58]  Schoenebeck               Expires May 30, 2007                 [Page 88]
4928    
Legend:
Removed from v.561  
changed lines
  Added in v.945
  ViewVC Help
Powered by ViewVC