/[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 575 by schoenebeck, Tue May 24 03:26:22 2005 UTC
# Line 2  Line 2 
2    
3  LinuxSampler Developers                                   C. Schoenebeck  LinuxSampler Developers                                   C. Schoenebeck
4  Internet-Draft                           Interessengemeinschaft Software  Internet-Draft                           Interessengemeinschaft Software
5  Expires: November 19, 2005                             Engineering e. V.  Expires: November 22, 2005                             Engineering e. V.
6                                                              May 21, 2005                                                              May 24, 2005
7    
8    
9                       LinuxSampler Control Protocol                       LinuxSampler Control Protocol
10                                  lscp.txt                                  LSCP 1.0
11    
12  Status of this Memo  Status of this Memo
13    
# Line 30  Status of this Memo Line 30  Status of this Memo
30     The list of Internet-Draft Shadow Directories can be accessed at     The list of Internet-Draft Shadow Directories can be accessed at
31     http://www.ietf.org/shadow.html.     http://www.ietf.org/shadow.html.
32    
33     This Internet-Draft will expire on November 19, 2005.     This Internet-Draft will expire on November 22, 2005.
34    
35  Copyright Notice  Copyright Notice
36    
# Line 40  Abstract Line 40  Abstract
40    
41     The LinuxSampler Control Protocol (LSCP) is an application-level     The LinuxSampler Control Protocol (LSCP) is an application-level
42     protocol primarily intended for local and remote controlling the     protocol primarily intended for local and remote controlling the
43     LinuxSampler main application, which is a sophisticated console     LinuxSampler backend application, which is a sophisticated
44     application essentially playing back audio samples and manipulating     server-like console application essentially playing back audio
45     the samples in real time to certain extent.     samples and manipulating the samples in real time to certain extent.
46    
47    
48    
# Line 52  Abstract Line 52  Abstract
52    
53    
54    
55  Schoenebeck            Expires November 19, 2005                [Page 1]  Schoenebeck            Expires November 22, 2005                [Page 1]
56    
57  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
58    
# Line 60  Internet-Draft       LinuxSampler Contro Line 60  Internet-Draft       LinuxSampler Contro
60  Table of Contents  Table of Contents
61    
62     1.   Requirements notation  . . . . . . . . . . . . . . . . . . .   4     1.   Requirements notation  . . . . . . . . . . . . . . . . . . .   4
63     2.   Introduction . . . . . . . . . . . . . . . . . . . . . . . .   5     2.   Versioning of this specification . . . . . . . . . . . . . .   5
64     3.   Focus of this protocol . . . . . . . . . . . . . . . . . . .   6     3.   Introduction . . . . . . . . . . . . . . . . . . . . . . . .   6
65     4.   Communication Overview . . . . . . . . . . . . . . . . . . .   7     4.   Focus of this protocol . . . . . . . . . . . . . . . . . . .   7
66       4.1  Request/response communication method  . . . . . . . . . .   7     5.   Communication Overview . . . . . . . . . . . . . . . . . . .   8
67         4.1.1  Result format  . . . . . . . . . . . . . . . . . . . .   8       5.1  Request/response communication method  . . . . . . . . . .   8
68       4.2  Subscribe/notify communication method  . . . . . . . . . .   9         5.1.1  Result format  . . . . . . . . . . . . . . . . . . . .   9
69     5.   Description for control commands . . . . . . . . . . . . . .  12       5.2  Subscribe/notify communication method  . . . . . . . . . .  10
70       5.1  Ignored lines and comments . . . . . . . . . . . . . . . .  12     6.   Description for control commands . . . . . . . . . . . . . .  13
71       5.2  Configuring audio drivers  . . . . . . . . . . . . . . . .  12       6.1  Ignored lines and comments . . . . . . . . . . . . . . . .  13
72         5.2.1  Getting amount of available audio output drivers . . .  12       6.2  Configuring audio drivers  . . . . . . . . . . . . . . . .  13
73         5.2.2  Getting all available audio output drivers . . . . . .  13         6.2.1  Getting amount of available audio output drivers . . .  13
74         5.2.3  Getting information about a specific audio output         6.2.2  Getting all available audio output drivers . . . . . .  14
75                driver . . . . . . . . . . . . . . . . . . . . . . . .  13         6.2.3  Getting information about a specific audio output
76         5.2.4  Getting information about specific audio output                driver . . . . . . . . . . . . . . . . . . . . . . . .  14
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 . . . . . . . . . . . . . . . . . . .  15
79         5.2.6  Destroying an audio output device  . . . . . . . . . .  17         6.2.5  Creating an audio output device  . . . . . . . . . . .  18
80         5.2.7  Getting all created audio output device count  . . . .  18         6.2.6  Destroying an audio output device  . . . . . . . . . .  18
81         5.2.8  Getting all created audio output device list . . . . .  18         6.2.7  Getting all created audio output device count  . . . .  19
82         5.2.9  Getting current settings of an audio output device . .  19         6.2.8  Getting all created audio output device list . . . . .  19
83         5.2.10   Changing settings of audio output devices  . . . . .  20         6.2.9  Getting current settings of an audio output device . .  20
84         5.2.11   Getting information about an audio channel . . . . .  20         6.2.10   Changing settings of audio output devices  . . . . .  21
85         5.2.12   Getting information about specific audio channel         6.2.11   Getting information about an audio channel . . . . .  21
86                  parameter  . . . . . . . . . . . . . . . . . . . . .  22         6.2.12   Getting information about specific audio channel
87         5.2.13   Changing settings of audio output channels . . . . .  23                  parameter  . . . . . . . . . . . . . . . . . . . . .  23
88       5.3  Configuring MIDI input drivers . . . . . . . . . . . . . .  24         6.2.13   Changing settings of audio output channels . . . . .  24
89         5.3.1  Getting amount of available MIDI input drivers . . . .  24       6.3  Configuring MIDI input drivers . . . . . . . . . . . . . .  25
90         5.3.2  Getting all available MIDI input drivers . . . . . . .  25         6.3.1  Getting amount of available MIDI input drivers . . . .  26
91         5.3.3  Getting information about a specific MIDI input         6.3.2  Getting all available MIDI input drivers . . . . . . .  26
92                driver . . . . . . . . . . . . . . . . . . . . . . . .  25         6.3.3  Getting information about a specific MIDI input
93         5.3.4  Getting information about specific MIDI input                driver . . . . . . . . . . . . . . . . . . . . . . . .  26
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 . . . . . . . . . . . . . . . . . . .  27
96         5.3.6  Destroying a MIDI input device . . . . . . . . . . . .  29         6.3.5  Creating a MIDI input device . . . . . . . . . . . . .  29
97         5.3.7  Getting all created MIDI input device count  . . . . .  29         6.3.6  Destroying a MIDI input device . . . . . . . . . . . .  30
98         5.3.8  Getting all created MIDI input device list . . . . . .  29         6.3.7  Getting all created MIDI input device count  . . . . .  30
99         5.3.9  Getting current settings of a MIDI input device  . . .  30         6.3.8  Getting all created MIDI input device list . . . . . .  31
100         5.3.10   Changing settings of MIDI input devices  . . . . . .  31         6.3.9  Getting current settings of a MIDI input device  . . .  31
101         5.3.11   Getting information about a MIDI port  . . . . . . .  31         6.3.10   Changing settings of MIDI input devices  . . . . . .  32
102         5.3.12   Getting information about specific MIDI port         6.3.11   Getting information about a MIDI port  . . . . . . .  33
103                  parameter  . . . . . . . . . . . . . . . . . . . . .  32         6.3.12   Getting information about specific MIDI port
104         5.3.13   Changing settings of MIDI input ports  . . . . . . .  33                  parameter  . . . . . . . . . . . . . . . . . . . . .  33
105       5.4  Configuring sampler channels . . . . . . . . . . . . . . .  34         6.3.13   Changing settings of MIDI input ports  . . . . . . .  35
106         5.4.1  Loading an instrument  . . . . . . . . . . . . . . . .  34       6.4  Configuring sampler channels . . . . . . . . . . . . . . .  35
107         5.4.2  Loading a sampler engine . . . . . . . . . . . . . . .  35         6.4.1  Loading an instrument  . . . . . . . . . . . . . . . .  35
108    
109    
110    
111  Schoenebeck            Expires November 19, 2005                [Page 2]  Schoenebeck            Expires November 22, 2005                [Page 2]
112    
113  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
114    
115    
116         5.4.3  Getting all created sampler channel count  . . . . . .  36         6.4.2  Loading a sampler engine . . . . . . . . . . . . . . .  36
117         5.4.4  Getting all created sampler channel list . . . . . . .  36         6.4.3  Getting all created sampler channel count  . . . . . .  37
118         5.4.5  Adding a new sampler channel . . . . . . . . . . . . .  36         6.4.4  Getting all created sampler channel list . . . . . . .  37
119         5.4.6  Removing a sampler channel . . . . . . . . . . . . . .  37         6.4.5  Adding a new sampler channel . . . . . . . . . . . . .  38
120         5.4.7  Getting amount of available engines  . . . . . . . . .  38         6.4.6  Removing a sampler channel . . . . . . . . . . . . . .  39
121         5.4.8  Getting all available engines  . . . . . . . . . . . .  38         6.4.7  Getting amount of available engines  . . . . . . . . .  39
122         5.4.9  Getting information about an engine  . . . . . . . . .  38         6.4.8  Getting all available engines  . . . . . . . . . . . .  39
123         5.4.10   Getting sampler channel information  . . . . . . . .  39         6.4.9  Getting information about an engine  . . . . . . . . .  40
124         5.4.11   Current number of active voices  . . . . . . . . . .  41         6.4.10   Getting sampler channel information  . . . . . . . .  41
125         5.4.12   Current number of active disk streams  . . . . . . .  41         6.4.11   Current number of active voices  . . . . . . . . . .  42
126         5.4.13   Current fill state of disk stream buffers  . . . . .  42         6.4.12   Current number of active disk streams  . . . . . . .  43
127         5.4.14   Setting audio output device  . . . . . . . . . . . .  42         6.4.13   Current fill state of disk stream buffers  . . . . .  43
128         5.4.15   Setting audio output type  . . . . . . . . . . . . .  43         6.4.14   Setting audio output device  . . . . . . . . . . . .  44
129         5.4.16   Setting audio output channel . . . . . . . . . . . .  44         6.4.15   Setting audio output type  . . . . . . . . . . . . .  45
130         5.4.17   Setting MIDI input device  . . . . . . . . . . . . .  44         6.4.16   Setting audio output channel . . . . . . . . . . . .  45
131         5.4.18   Setting MIDI input type  . . . . . . . . . . . . . .  45         6.4.17   Setting MIDI input device  . . . . . . . . . . . . .  46
132         5.4.19   Setting MIDI input port  . . . . . . . . . . . . . .  45         6.4.18   Setting MIDI input type  . . . . . . . . . . . . . .  46
133         5.4.20   Setting MIDI input channel . . . . . . . . . . . . .  46         6.4.19   Setting MIDI input port  . . . . . . . . . . . . . .  47
134         5.4.21   Setting channel volume . . . . . . . . . . . . . . .  46         6.4.20   Setting MIDI input channel . . . . . . . . . . . . .  48
135         5.4.22   Resetting a sampler channel  . . . . . . . . . . . .  47         6.4.21   Setting channel volume . . . . . . . . . . . . . . .  48
136       5.5  Controlling connection . . . . . . . . . . . . . . . . . .  48         6.4.22   Resetting a sampler channel  . . . . . . . . . . . .  49
137         5.5.1  Register front-end for receiving event messages  . . .  48       6.5  Controlling connection . . . . . . . . . . . . . . . . . .  49
138         5.5.2  Unregister front-end for not receiving event         6.5.1  Register front-end for receiving event messages  . . .  49
139                messages . . . . . . . . . . . . . . . . . . . . . . .  48         6.5.2  Unregister front-end for not receiving event
140         5.5.3  Enable or disable echo of commands . . . . . . . . . .  49                messages . . . . . . . . . . . . . . . . . . . . . . .  50
141         5.5.4  Close client connection  . . . . . . . . . . . . . . .  49         6.5.3  Enable or disable echo of commands . . . . . . . . . .  51
142       5.6  Global commands  . . . . . . . . . . . . . . . . . . . . .  50         6.5.4  Close client connection  . . . . . . . . . . . . . . .  51
143         5.6.1  Reset sampler  . . . . . . . . . . . . . . . . . . . .  50       6.6  Global commands  . . . . . . . . . . . . . . . . . . . . .  51
144     6.   Command Syntax . . . . . . . . . . . . . . . . . . . . . . .  51         6.6.1  Reset sampler  . . . . . . . . . . . . . . . . . . . .  51
145     7.   Events . . . . . . . . . . . . . . . . . . . . . . . . . . .  52         6.6.2  General sampler informations . . . . . . . . . . . . .  52
146       7.1  Number of sampler channels changed . . . . . . . . . . . .  52     7.   Command Syntax . . . . . . . . . . . . . . . . . . . . . . .  53
147       7.2  Number of active voices changed  . . . . . . . . . . . . .  52     8.   Events . . . . . . . . . . . . . . . . . . . . . . . . . . .  58
148       7.3  Number of active disk streams changed  . . . . . . . . . .  52       8.1  Number of sampler channels changed . . . . . . . . . . . .  58
149       7.4  Disk stream buffer fill state changed  . . . . . . . . . .  53       8.2  Number of active voices changed  . . . . . . . . . . . . .  58
150       7.5  Channel information changed  . . . . . . . . . . . . . . .  53       8.3  Number of active disk streams changed  . . . . . . . . . .  58
151       7.6  Miscellaneous and debugging events . . . . . . . . . . . .  53       8.4  Disk stream buffer fill state changed  . . . . . . . . . .  59
152     8.   Security Considerations  . . . . . . . . . . . . . . . . . .  55       8.5  Channel information changed  . . . . . . . . . . . . . . .  59
153     9.   Acknowledgments  . . . . . . . . . . . . . . . . . . . . . .  56       8.6  Miscellaneous and debugging events . . . . . . . . . . . .  59
154     10.  References . . . . . . . . . . . . . . . . . . . . . . . . .  56     9.   Security Considerations  . . . . . . . . . . . . . . . . . .  61
155          Author's Address . . . . . . . . . . . . . . . . . . . . . .  56     10.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . .  62
156          Intellectual Property and Copyright Statements . . . . . . .  57     11.  References . . . . . . . . . . . . . . . . . . . . . . . . .  62
157            Author's Address . . . . . . . . . . . . . . . . . . . . . .  62
158            Intellectual Property and Copyright Statements . . . . . . .  63
159    
160    
161    
# Line 162  Internet-Draft       LinuxSampler Contro Line 164  Internet-Draft       LinuxSampler Contro
164    
165    
166    
167    Schoenebeck            Expires November 22, 2005                [Page 3]
   
 Schoenebeck            Expires November 19, 2005                [Page 3]  
168    
169  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
170    
# Line 220  Internet-Draft       LinuxSampler Contro Line 220  Internet-Draft       LinuxSampler Contro
220    
221    
222    
223  Schoenebeck            Expires November 19, 2005                [Page 4]  Schoenebeck            Expires November 22, 2005                [Page 4]
224    
225  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
226    
227    
228  2.  Introduction  2.  Versioning of this specification
229    
230       LSCP will certainly be extended and enhanced by-and-by.  Each
231       official release of the LSCP specification will be tagged with a
232       unique version tuple.  The version tuple consists at least of a major
233       and minor version number like:
234    
235          "1.2"
236    
237       In this example the major version number would be "1" and the minor
238       version number would be "2".  Note that the version tuple might also
239       have more than two elements.  The major version number defines a
240       group of backward compatible versions.  That means a frontend is
241       compatible to the connected sampler if and only if the LSCP versions
242       to which each of the two parties complies to, match both of the
243       following rules:
244    
245       Compatibility:
246    
247       1.  The frontend's LSCP major version and the sampler's LSCP major
248           version are exactly equal.
249       2.  The frontend's LSCP minor version is less or equal than the
250           sampler's LSCP minor version.
251    
252       Compatibility can only be claimed if both rules are true.  The
253       frontend can use the "GET SERVER INFO" (Section 6.6.2) command to get
254       the version of the LSCP specification the sampler complies with.
255    
256    
257    
258    
259    
260    
261    
262    
263    
264    
265    
266    
267    
268    
269    
270    
271    
272    
273    
274    
275    
276    
277    
278    
279    Schoenebeck            Expires November 22, 2005                [Page 5]
280    
281    Internet-Draft       LinuxSampler Control Protocol              May 2005
282    
283    
284    3.  Introduction
285    
286     LinuxSampler is a so called software sampler application capable to     LinuxSampler is a so called software sampler application capable to
287     playback audio samples from a computer's Random Access Memory (RAM)     playback audio samples from a computer's Random Access Memory (RAM)
# Line 237  Internet-Draft       LinuxSampler Contro Line 293  Internet-Draft       LinuxSampler Contro
293     connected to an arbitrary MIDI input method and arbitrary MIDI     connected to an arbitrary MIDI input method and arbitrary MIDI
294     channel (e.g.  sampler channel 17 could be connected to an ALSA     channel (e.g.  sampler channel 17 could be connected to an ALSA
295     sequencer device 64:0 and listening to MIDI channel 1 there).  Each     sequencer device 64:0 and listening to MIDI channel 1 there).  Each
296     sampler engine will be assigned an own instance of one of the     sampler channel will be associated with an instance of one of the
297     available sampler engines (e.g.  GigEngine, DLSEngine).  The audio     available sampler engines (e.g.  GigEngine, DLSEngine).  The audio
298     output of each sampler channel can be routed to an arbitrary audio     output of each sampler channel can be routed to an arbitrary audio
299     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 332  Internet-Draft       LinuxSampler Contro
332    
333    
334    
335  Schoenebeck            Expires November 19, 2005                [Page 5]  Schoenebeck            Expires November 22, 2005                [Page 6]
336    
337  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
338    
339    
340  3.  Focus of this protocol  4.  Focus of this protocol
341    
342     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
343     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 388  Internet-Draft       LinuxSampler Contro
388    
389    
390    
391  Schoenebeck            Expires November 19, 2005                [Page 6]  Schoenebeck            Expires November 22, 2005                [Page 7]
392    
393  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
394    
395    
396  4.  Communication Overview  5.  Communication Overview
397    
398     There are two distinct methods of communication between a running     There are two distinct methods of communication between a running
399     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 405  Internet-Draft       LinuxSampler Contro
405     more effort to be implemented in the front-end application.  The two     more effort to be implemented in the front-end application.  The two
406     communication methods will be described next.     communication methods will be described next.
407    
408  4.1  Request/response communication method  5.1  Request/response communication method
409    
410     This simple communication method is based on TCP.  The front-end     This simple communication method is based on TCP [RFC793].  The
411     application establishes a TCP connection to the LinuxSampler instance     front-end application establishes a TCP connection to the
412     on a certain host system.  Then the front-end application will send     LinuxSampler instance on a certain host system.  Then the front-end
413     certain ASCII based commands as defined in this document (every     application will send certain ASCII based commands as defined in this
414     command line must be CRLF terminated - see "Conventions used in this     document (every command line must be CRLF terminated - see
415     document" at the beginning of this document) and the LinuxSampler     "Conventions used in this document" at the beginning of this
416     application will response after a certain process time with an     document) and the LinuxSampler application will response after a
417     appropriate ASCII based answer, also as defined in this document.  So     certain process time with an appropriate ASCII based answer, also as
418     this TCP communication is simply based on query and answer paradigm.     defined in this document.  So this TCP communication is simply based
419     That way LinuxSampler is only able to answer on queries from     on query and answer paradigm.  That way LinuxSampler is only able to
420     front-ends, but not able to automatically send messages to the client     answer on queries from front-ends, but not able to automatically send
421     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
422     LinuxSampler for every single command, instead it should keep the     reconnect to LinuxSampler for every single command, instead it should
423     connection established and simply resend message(s) for subsequent     keep the connection established and simply resend message(s) for
424     commands.  To keep information in the front-end up-to-date the     subsequent commands.  To keep information in the front-end up-to-date
425     front-end has to periodically send new requests to get the current     the front-end has to periodically send new requests to get the
426     information from the LinuxSampler instance.  This is often referred     current information from the LinuxSampler instance.  This is often
427     to as "polling".  While polling is simple to implement and may be OK     referred to as "polling".  While polling is simple to implement and
428     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
429     network traffic overhead and information being out of date.  It is     such as network traffic overhead and information being out of date.
430     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
431     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
432     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
433     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 444  Internet-Draft       LinuxSampler Contro
444    
445    
446    
447  Schoenebeck            Expires November 19, 2005                [Page 7]  Schoenebeck            Expires November 22, 2005                [Page 8]
448    
449  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
450    
451    
452  4.1.1  Result format  5.1.1  Result format
453    
454     Result set could be one of the following types:     Result set could be one of the following types:
455    
# Line 444  Internet-Draft       LinuxSampler Contro Line 500  Internet-Draft       LinuxSampler Contro
500    
501    
502    
503  Schoenebeck            Expires November 19, 2005                [Page 8]  Schoenebeck            Expires November 22, 2005                [Page 9]
504    
505  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
506    
# Line 490  Internet-Draft       LinuxSampler Contro Line 546  Internet-Draft       LinuxSampler Contro
546        C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"        C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"
547        S: "WRN[0]:32:Sample rate not supported, using 44100 instead."        S: "WRN[0]:32:Sample rate not supported, using 44100 instead."
548    
549  4.2  Subscribe/notify communication method  5.2  Subscribe/notify communication method
550    
551     This more sophisticated communication method is actually only an     This more sophisticated communication method is actually only an
552     extension of the simple request/response communication method.  The     extension of the simple request/response communication method.  The
# Line 500  Internet-Draft       LinuxSampler Contro Line 556  Internet-Draft       LinuxSampler Contro
556    
557    
558    
559  Schoenebeck            Expires November 19, 2005                [Page 9]  Schoenebeck            Expires November 22, 2005               [Page 10]
560    
561  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
562    
# Line 542  Internet-Draft       LinuxSampler Contro Line 598  Internet-Draft       LinuxSampler Contro
598    
599     where <event-id> will be replace by the respective event that client     where <event-id> will be replace by the respective event that client
600     is no longer interested in receiving.  For a list of supported events     is no longer interested in receiving.  For a list of supported events
601     see Section 7.     see Section 8.
602    
603     Example: the fill states of disk stream buffers have changed on     Example: the fill states of disk stream buffers have changed on
604     sampler channel 4 and the LinuxSampler instance will react by sending     sampler channel 4 and the LinuxSampler instance will react by sending
# Line 556  Internet-Draft       LinuxSampler Contro Line 612  Internet-Draft       LinuxSampler Contro
612    
613    
614    
615  Schoenebeck            Expires November 19, 2005               [Page 10]  Schoenebeck            Expires November 22, 2005               [Page 11]
616    
617  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
618    
# Line 612  Internet-Draft       LinuxSampler Contro Line 668  Internet-Draft       LinuxSampler Contro
668    
669    
670    
671  Schoenebeck            Expires November 19, 2005               [Page 11]  Schoenebeck            Expires November 22, 2005               [Page 12]
672    
673  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
674    
675    
676  5.  Description for control commands  6.  Description for control commands
677    
678     This chapter will describe the available control commands that can be     This chapter will describe the available control commands that can be
679     sent on the TCP connection in detail.  Some certain commands (e.g.     sent on the TCP connection in detail.  Some certain commands (e.g.
680     "GET CHANNEL INFO" (Section 5.4.10) or "GET ENGINE INFO" (Section     "GET CHANNEL INFO" (Section 6.4.10) or "GET ENGINE INFO" (Section
681     5.4.9)) lead to multiple-line responses.  In this case LinuxSampler     6.4.9)) lead to multiple-line responses.  In this case LinuxSampler
682     signals the end of the response by a "." (single dot) line.     signals the end of the response by a "." (single dot) line.
683    
684  5.1  Ignored lines and comments  6.1  Ignored lines and comments
685    
686     White lines, that is lines which only contain space and tabulator     White lines, that is lines which only contain space and tabulator
687     characters, and lines that start with a "#" character are ignored,     characters, and lines that start with a "#" character are ignored,
688     thus it's possible for example to group commands and to place     thus it's possible for example to group commands and to place
689     comments in a LSCP script file.     comments in a LSCP script file.
690    
691  5.2  Configuring audio drivers  6.2  Configuring audio drivers
692    
693     Instances of drivers in LinuxSampler are called devices.  You can use     Instances of drivers in LinuxSampler are called devices.  You can use
694     multiple audio devices simultaneously, e.g.  to output the sound of     multiple audio devices simultaneously, e.g.  to output the sound of
# Line 661  Internet-Draft       LinuxSampler Contro Line 717  Internet-Draft       LinuxSampler Contro
717     retrieve what parameters drivers are offering, how to retrieve their     retrieve what parameters drivers are offering, how to retrieve their
718     possible values, etc.     possible values, etc.
719    
720  5.2.1  Getting amount of available audio output drivers  6.2.1  Getting amount of available audio output drivers
721    
722     Use the following command to get the number of audio output drivers     Use the following command to get the number of audio output drivers
723     currently available for the LinuxSampler instance:     currently available for the LinuxSampler instance:
724    
725    
726    
727  Schoenebeck            Expires November 19, 2005               [Page 12]  Schoenebeck            Expires November 22, 2005               [Page 13]
728    
729  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
730    
# Line 685  Internet-Draft       LinuxSampler Contro Line 741  Internet-Draft       LinuxSampler Contro
741        C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"        C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
742        S: "2"        S: "2"
743    
744  5.2.2  Getting all available audio output drivers  6.2.2  Getting all available audio output drivers
745    
746     Use the following command to list all audio output drivers currently     Use the following command to list all audio output drivers currently
747     available for the LinuxSampler instance:     available for the LinuxSampler instance:
# Line 702  Internet-Draft       LinuxSampler Contro Line 758  Internet-Draft       LinuxSampler Contro
758        C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"        C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"
759        S: "ALSA,JACK"        S: "ALSA,JACK"
760    
761  5.2.3  Getting information about a specific audio output driver  6.2.3  Getting information about a specific audio output driver
762    
763     Use the following command to get detailed information about a     Use the following command to get detailed information about a
764     specific audio output driver:     specific audio output driver:
# Line 710  Internet-Draft       LinuxSampler Contro Line 766  Internet-Draft       LinuxSampler Contro
766        GET AUDIO_OUTPUT_DRIVER INFO <audio-output-driver>        GET AUDIO_OUTPUT_DRIVER INFO <audio-output-driver>
767    
768     Where <audio-output-driver> is the name of the audio output driver,     Where <audio-output-driver> is the name of the audio output driver,
769     returned by the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 5.2.2)     returned by the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2)
770     command.     command.
771    
772     Possible Answers:     Possible Answers:
# Line 724  Internet-Draft       LinuxSampler Contro Line 780  Internet-Draft       LinuxSampler Contro
780    
781    
782    
783  Schoenebeck            Expires November 19, 2005               [Page 13]  Schoenebeck            Expires November 22, 2005               [Page 14]
784    
785  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
786    
# Line 750  Internet-Draft       LinuxSampler Contro Line 806  Internet-Draft       LinuxSampler Contro
806        FRAGMENTSIZE,CARD"        FRAGMENTSIZE,CARD"
807           "."           "."
808    
809  5.2.4  Getting information about specific audio output driver parameter  6.2.4  Getting information about specific audio output driver parameter
810    
811     Use the following command to get detailed information about a     Use the following command to get detailed information about a
812     specific audio output driver parameter:     specific audio output driver parameter:
# Line 758  Internet-Draft       LinuxSampler Contro Line 814  Internet-Draft       LinuxSampler Contro
814        GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO <audio> <prm> [<deplist>]        GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO <audio> <prm> [<deplist>]
815    
816     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
817     the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 5.2.2) command,     the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2) command,
818     <prm> a specific parameter name for which information should be     <prm> a specific parameter name for which information should be
819     obtained (as returned by the "GET AUDIO_OUTPUT_DRIVER INFO" (Section     obtained (as returned by the "GET AUDIO_OUTPUT_DRIVER INFO" (Section
820     5.2.3) command) and <deplist> is an optional list of parameters on     6.2.3) command) and <deplist> is an optional list of parameters on
821     which the sought parameter <prm> depends on, <deplist> is a list of     which the sought parameter <prm> depends on, <deplist> is a list of
822     key-value pairs in form of "key1=val1 key2=val2 ...", where character     key-value pairs in form of "key1=val1 key2=val2 ...", where character
823     string values are encapsulated into apostrophes (').  Arguments given     string values are encapsulated into apostrophes (').  Arguments given
# Line 780  Internet-Draft       LinuxSampler Contro Line 836  Internet-Draft       LinuxSampler Contro
836    
837    
838    
839  Schoenebeck            Expires November 19, 2005               [Page 14]  Schoenebeck            Expires November 22, 2005               [Page 15]
840    
841  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
842    
# Line 800  Internet-Draft       LinuxSampler Contro Line 856  Internet-Draft       LinuxSampler Contro
856        MANDATORY -        MANDATORY -
857           either true or false, defines if this parameter must be given           either true or false, defines if this parameter must be given
858           when the device is to be created with the 'CREATE           when the device is to be created with the 'CREATE
859           AUDIO_OUTPUT_DEVICE' (Section 5.2.5) command (always returned,           AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command (always returned,
860           no matter which driver parameter)           no matter which driver parameter)
861        FIX -        FIX -
862           either true or false, if false then this parameter can be           either true or false, if false then this parameter can be
863           changed at any time, once the device is created by the 'CREATE           changed at any time, once the device is created by the 'CREATE
864           AUDIO_OUTPUT_DEVICE' (Section 5.2.5) command (always returned,           AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command (always returned,
865           no matter which driver parameter)           no matter which driver parameter)
866        MULTIPLICITY -        MULTIPLICITY -
867           either true or false, defines if this parameter allows only one           either true or false, defines if this parameter allows only one
# Line 825  Internet-Draft       LinuxSampler Contro Line 881  Internet-Draft       LinuxSampler Contro
881        DEFAULT -        DEFAULT -
882           reflects the default value for this parameter which is used           reflects the default value for this parameter which is used
883           when the device is created and not explicitly given with the           when the device is created and not explicitly given with the
884           'CREATE AUDIO_OUTPUT_DEVICE' (Section 5.2.5) command, in case           'CREATE AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command, in case
885           of MULTIPLCITY=true, this is a comma separated list, that's why           of MULTIPLCITY=true, this is a comma separated list, that's why
886           character strings are encapsulated into apostrophes (')           character strings are encapsulated into apostrophes (')
887           (optionally returned, dependent to driver parameter)           (optionally returned, dependent to driver parameter)
# Line 836  Internet-Draft       LinuxSampler Contro Line 892  Internet-Draft       LinuxSampler Contro
892    
893    
894    
895  Schoenebeck            Expires November 19, 2005               [Page 15]  Schoenebeck            Expires November 22, 2005               [Page 16]
896    
897  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
898    
# Line 892  Internet-Draft       LinuxSampler Contro Line 948  Internet-Draft       LinuxSampler Contro
948    
949    
950    
951  Schoenebeck            Expires November 19, 2005               [Page 16]  Schoenebeck            Expires November 22, 2005               [Page 17]
952    
953  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
954    
# Line 900  Internet-Draft       LinuxSampler Contro Line 956  Internet-Draft       LinuxSampler Contro
956           "RANGE_MAX: 96000"           "RANGE_MAX: 96000"
957           "."           "."
958    
959  5.2.5  Creating an audio output device  6.2.5  Creating an audio output device
960    
961     Use the following command to create a new audio output device for     Use the following command to create a new audio output device for
962     the desired audio output system:     the desired audio output system:
# Line 908  Internet-Draft       LinuxSampler Contro Line 964  Internet-Draft       LinuxSampler Contro
964        CREATE AUDIO_OUTPUT_DEVICE <audio-output-driver> [<param-list>]        CREATE AUDIO_OUTPUT_DEVICE <audio-output-driver> [<param-list>]
965    
966     Where <audio-output-driver> should be replaced by the desired audio     Where <audio-output-driver> should be replaced by the desired audio
967     output system and <param-list> by an optional list of driver specific     output system as returned by the "LIST
968     parameters in form of "key1=val1 key2=val2 ...", where character     AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2) command and
969     string values should be encapsulated into apostrophes (').  Note that     <param-list> by an optional list of driver specific parameters in
970     there might be drivers which require parameter(s) to be given with     form of "key1=val1 key2=val2 ...", where character string values
971     this command.  Use the previously described commands in this chapter     should be encapsulated into apostrophes (').  Note that there might
972     to get this information.     be drivers which require parameter(s) to be given with this command.
973       Use the previously described commands in this chapter to get this
974       information.
975    
976     Possible Answers:     Possible Answers:
977    
# Line 938  Internet-Draft       LinuxSampler Contro Line 996  Internet-Draft       LinuxSampler Contro
996        C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"        C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"
997        S: "OK[1]"        S: "OK[1]"
998    
999  5.2.6  Destroying an audio output device  6.2.6  Destroying an audio output device
1000    
1001     Use the following command to destroy a created output device:     Use the following command to destroy a created output device:
1002    
       DESTROY AUDIO_OUTPUT_DEVICE <device-id>  
1003    
    Where <device-id> should be replaced by the numerical ID of the audio  
1004    
1005    
1006    
1007  Schoenebeck            Expires November 19, 2005               [Page 17]  Schoenebeck            Expires November 22, 2005               [Page 18]
1008    
1009  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
1010    
1011    
1012          DESTROY AUDIO_OUTPUT_DEVICE <device-id>
1013    
1014       Where <device-id> should be replaced by the numerical ID of the audio
1015     output device as given by the "CREATE AUDIO_OUTPUT_DEVICE" (Section     output device as given by the "CREATE AUDIO_OUTPUT_DEVICE" (Section
1016     5.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 5.2.8) command.     6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command.
1017    
1018     Possible Answers:     Possible Answers:
1019    
# Line 975  Internet-Draft       LinuxSampler Contro Line 1034  Internet-Draft       LinuxSampler Contro
1034        C: "DESTROY AUDIO_OUTPUT_DEVICE 0"        C: "DESTROY AUDIO_OUTPUT_DEVICE 0"
1035        S: "OK"        S: "OK"
1036    
1037  5.2.7  Getting all created audio output device count  6.2.7  Getting all created audio output device count
1038    
1039     Use the following command to count all created audio output devices:     Use the following command to count all created audio output devices:
1040    
# Line 991  Internet-Draft       LinuxSampler Contro Line 1050  Internet-Draft       LinuxSampler Contro
1050        C: "GET AUDIO_OUTPUT_DEVICES"        C: "GET AUDIO_OUTPUT_DEVICES"
1051        S: "4"        S: "4"
1052    
1053  5.2.8  Getting all created audio output device list  6.2.8  Getting all created audio output device list
1054    
1055     Use the following command to list all created audio output devices:     Use the following command to list all created audio output devices:
1056    
# Line 999  Internet-Draft       LinuxSampler Contro Line 1058  Internet-Draft       LinuxSampler Contro
1058    
1059     Possible Answers:     Possible Answers:
1060    
       LinuxSampler will answer by sending a comma separated list with  
       the numerical IDs of all audio output devices.  
   
1061    
1062    
1063  Schoenebeck            Expires November 19, 2005               [Page 18]  Schoenebeck            Expires November 22, 2005               [Page 19]
1064    
1065  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
1066    
1067    
1068          LinuxSampler will answer by sending a comma separated list with
1069          the numerical IDs of all audio output devices.
1070    
1071     Example:     Example:
1072    
1073        C: "LIST AUDIO_OUTPUT_DEVICES"        C: "LIST AUDIO_OUTPUT_DEVICES"
1074        S: "0,1,4,5"        S: "0,1,4,5"
1075    
1076  5.2.9  Getting current settings of an audio output device  6.2.9  Getting current settings of an audio output device
1077    
1078     Use the following command to get current settings of a specific,     Use the following command to get current settings of a specific,
1079     created audio output device:     created audio output device:
# Line 1023  Internet-Draft       LinuxSampler Contro Line 1082  Internet-Draft       LinuxSampler Contro
1082    
1083     Where <device-id> should be replaced by numerical ID of the audio     Where <device-id> should be replaced by numerical ID of the audio
1084     output device as e.g.  returned by the "LIST AUDIO_OUTPUT_DEVICES"     output device as e.g.  returned by the "LIST AUDIO_OUTPUT_DEVICES"
1085     (Section 5.2.8) command.     (Section 6.2.8) command.
1086    
1087     Possible Answers:     Possible Answers:
1088    
# Line 1037  Internet-Draft       LinuxSampler Contro Line 1096  Internet-Draft       LinuxSampler Contro
1096    
1097        DRIVER -        DRIVER -
1098           identifier of the used audio output driver, as also returned by           identifier of the used audio output driver, as also returned by
1099           the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 5.2.2)           the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2)
1100           command           command
1101        CHANNELS -        CHANNELS -
1102           amount of audio output channels this device currently offers           amount of audio output channels this device currently offers
# Line 1051  Internet-Draft       LinuxSampler Contro Line 1110  Internet-Draft       LinuxSampler Contro
1110     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
1111     fields above are only those fields which are returned by all audio     fields above are only those fields which are returned by all audio
1112     output devices.  Every audio output driver might have its own,     output devices.  Every audio output driver might have its own,
1113     additional driver specific parameters (see Section 5.2.3) which are     additional driver specific parameters (see Section 6.2.3) which are
1114     also returned by this command.     also returned by this command.
1115    
    Example:  
   
   
1116    
1117    
1118    
1119  Schoenebeck            Expires November 19, 2005               [Page 19]  Schoenebeck            Expires November 22, 2005               [Page 20]
1120    
1121  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
1122    
1123    
1124       Example:
1125    
1126        C: "GET AUDIO_OUTPUT_DEVICE INFO 0"        C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
1127        S: "DRIVER: ALSA"        S: "DRIVER: ALSA"
1128           "CHANNELS: 2"           "CHANNELS: 2"
# Line 1075  Internet-Draft       LinuxSampler Contro Line 1133  Internet-Draft       LinuxSampler Contro
1133           "CARD: '0,0'"           "CARD: '0,0'"
1134           "."           "."
1135    
1136  5.2.10  Changing settings of audio output devices  6.2.10  Changing settings of audio output devices
1137    
1138     Use the following command to alter a specific setting of a created     Use the following command to alter a specific setting of a created
1139     audio output device:     audio output device:
# Line 1083  Internet-Draft       LinuxSampler Contro Line 1141  Internet-Draft       LinuxSampler Contro
1141        SET AUDIO_OUTPUT_DEVICE_PARAMETER <device-id> <key>=<value>        SET AUDIO_OUTPUT_DEVICE_PARAMETER <device-id> <key>=<value>
1142    
1143     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
1144     output device, <key> by the name of the parameter to change and     output device as given by the "CREATE AUDIO_OUTPUT_DEVICE" (Section
1145     <value> by the new value for this parameter.     6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command, <key>
1146       by the name of the parameter to change and <value> by the new value
1147       for this parameter.
1148    
1149     Possible Answers:     Possible Answers:
1150    
# Line 1103  Internet-Draft       LinuxSampler Contro Line 1163  Internet-Draft       LinuxSampler Contro
1163        C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"        C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"
1164        S: "OK"        S: "OK"
1165    
1166  5.2.11  Getting information about an audio channel  6.2.11  Getting information about an audio channel
1167    
1168     Use the following command to get information about an audio channel:     Use the following command to get information about an audio channel:
1169    
1170        GET AUDIO_OUTPUT_CHANNEL INFO <device-id> <audio-chan>        GET AUDIO_OUTPUT_CHANNEL INFO <device-id> <audio-chan>
1171    
    Where <device-id> is the numerical ID of the audio output device and  
    <audio-chan> the audio channel number.  
1172    
    Possible Answers:  
1173    
1174    
1175    Schoenebeck            Expires November 22, 2005               [Page 21]
 Schoenebeck            Expires November 19, 2005               [Page 20]  
1176    
1177  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
1178    
1179    
1180       Where <device-id> is the numerical ID of the audio output device as
1181       given by the "CREATE AUDIO_OUTPUT_DEVICE" (Section 6.2.5) or "LIST
1182       AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command and <audio-chan> the
1183       audio channel number.
1184    
1185       Possible Answers:
1186    
1187        LinuxSampler will answer by sending a <CRLF> separated list.  Each        LinuxSampler will answer by sending a <CRLF> separated list.  Each
1188        answer line begins with the information category name followed by        answer line begins with the information category name followed by
1189        a colon and then a space character <SP> and finally the info        a colon and then a space character <SP> and finally the info
# Line 1162  Internet-Draft       LinuxSampler Contro Line 1225  Internet-Draft       LinuxSampler Contro
1225           "IS_MIX_CHANNEL: false"           "IS_MIX_CHANNEL: false"
1226           "."           "."
1227    
       C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"  
       S: "NAME: studio monitor left"  
          "IS_MIX_CHANNEL: true"  
          "MIX_CHANNEL_DESTINATION: 1"  
          "."  
   
1228    
1229    
1230    
1231    Schoenebeck            Expires November 22, 2005               [Page 22]
 Schoenebeck            Expires November 19, 2005               [Page 21]  
1232    
1233  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
1234    
1235    
1236          C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"
1237          S: "NAME: studio monitor left"
1238             "IS_MIX_CHANNEL: true"
1239             "MIX_CHANNEL_DESTINATION: 1"
1240             "."
1241    
1242        C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"        C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"
1243        S: "NAME: 'ardour (left)'"        S: "NAME: 'ardour (left)'"
1244           "IS_MIX_CHANNEL: false"           "IS_MIX_CHANNEL: false"
1245           "JACK_BINDINGS: 'ardour:0'"           "JACK_BINDINGS: 'ardour:0'"
1246           "."           "."
1247    
1248  5.2.12  Getting information about specific audio channel parameter  6.2.12  Getting information about specific audio channel parameter
1249    
1250     Use the following command to get detailed information about specific     Use the following command to get detailed information about specific
1251     audio channel parameter:     audio channel parameter:
# Line 1191  Internet-Draft       LinuxSampler Contro Line 1253  Internet-Draft       LinuxSampler Contro
1253        GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO <dev-id> <chan> <param>        GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO <dev-id> <chan> <param>
1254    
1255     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
1256     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
1257     <chan> the audio channel number and <param> a specific channel     AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command, <chan> the audio
1258     parameter name for which information should be obtained (as returned     channel number and <param> a specific channel parameter name for
1259     by the "GET AUDIO_OUTPUT_CHANNEL INFO" (Section 5.2.11) command).     which information should be obtained (as returned by the "GET
1260       AUDIO_OUTPUT_CHANNEL INFO" (Section 6.2.11) command).
1261    
1262     Possible Answers:     Possible Answers:
1263    
# Line 1217  Internet-Draft       LinuxSampler Contro Line 1280  Internet-Draft       LinuxSampler Contro
1280           FIX -           FIX -
1281              either true or false, if true then this parameter is read              either true or false, if true then this parameter is read
1282              only, thus cannot be altered (always returned)              only, thus cannot be altered (always returned)
1283    
1284    
1285    
1286    
1287    Schoenebeck            Expires November 22, 2005               [Page 23]
1288    
1289    Internet-Draft       LinuxSampler Control Protocol              May 2005
1290    
1291    
1292           MULTIPLICITY -           MULTIPLICITY -
1293              either true or false, defines if this parameter allows only              either true or false, defines if this parameter allows only
1294              one value or a list of values, where true means multiple              one value or a list of values, where true means multiple
# Line 1225  Internet-Draft       LinuxSampler Contro Line 1297  Internet-Draft       LinuxSampler Contro
1297           RANGE_MIN -           RANGE_MIN -
1298              defines lower limit of the allowed value range for this              defines lower limit of the allowed value range for this
1299              parameter, can be an integer value as well as a dotted              parameter, can be an integer value as well as a dotted
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 22]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
1300              number, usually used in conjunction with 'RANGE_MAX', but              number, usually used in conjunction with 'RANGE_MAX', but
1301              may also appear without (optionally returned, dependent to              may also appear without (optionally returned, dependent to
1302              driver and channel parameter)              driver and channel parameter)
# Line 1259  Internet-Draft       LinuxSampler Contro Line 1323  Internet-Draft       LinuxSampler Contro
1323           "POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"           "POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"
1324           "."           "."
1325    
1326  5.2.13  Changing settings of audio output channels  6.2.13  Changing settings of audio output channels
1327    
1328     Use the following command to alter a specific setting of an audio     Use the following command to alter a specific setting of an audio
1329     output channel:     output channel:
# Line 1267  Internet-Draft       LinuxSampler Contro Line 1331  Internet-Draft       LinuxSampler Contro
1331        SET AUDIO_OUTPUT_CHANNEL_PARAMETER <dev-id> <chn> <key>=<value>        SET AUDIO_OUTPUT_CHANNEL_PARAMETER <dev-id> <chn> <key>=<value>
1332    
1333     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
1334     device, <chn> by the audio channel number, <key> by the name of the     output device as returned by the "CREATE AUDIO_OUTPUT_DEVICE"
1335       (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
1336       command, <chn> by the audio channel number, <key> by the name of the
1337     parameter to change and <value> by the new value for this parameter.     parameter to change and <value> by the new value for this parameter.
1338    
1339     Possible Answers:     Possible Answers:
1340    
1341    
1342    
1343    Schoenebeck            Expires November 22, 2005               [Page 24]
1344    
1345    Internet-Draft       LinuxSampler Control Protocol              May 2005
1346    
1347    
1348        "OK" -        "OK" -
1349           in case setting was successfully changed           in case setting was successfully changed
1350        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
# Line 1282  Internet-Draft       LinuxSampler Contro Line 1355  Internet-Draft       LinuxSampler Contro
1355           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
1356           error message           error message
1357    
   
   
 Schoenebeck            Expires November 19, 2005               [Page 23]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
1358     Example:     Example:
1359    
1360        C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"        C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"
# Line 1297  Internet-Draft       LinuxSampler Contro Line 1363  Internet-Draft       LinuxSampler Contro
1363        C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"        C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"
1364        S: "OK"        S: "OK"
1365    
1366  5.3  Configuring MIDI input drivers  6.3  Configuring MIDI input drivers
1367    
1368     Instances of drivers in LinuxSampler are called devices.  You can use     Instances of drivers in LinuxSampler are called devices.  You can use
1369     multiple MIDI devices simultaneously, e.g.  to use MIDI over ethernet     multiple MIDI devices simultaneously, e.g.  to use MIDI over ethernet
# Line 1328  Internet-Draft       LinuxSampler Contro Line 1394  Internet-Draft       LinuxSampler Contro
1394     retrieve what parameters drivers are offering, how to retrieve their     retrieve what parameters drivers are offering, how to retrieve their
1395     possible values, etc.     possible values, etc.
1396    
 5.3.1  Getting amount of available MIDI input drivers  
   
    Use the following command to get the number of MIDI input drivers  
    currently available for the LinuxSampler instance:  
1397    
       GET AVAILABLE_MIDI_INPUT_DRIVERS  
1398    
1399     Possible Answers:  Schoenebeck            Expires November 22, 2005               [Page 25]
1400    
1401    Internet-Draft       LinuxSampler Control Protocol              May 2005
1402    
1403    
1404    6.3.1  Getting amount of available MIDI input drivers
1405    
1406       Use the following command to get the number of MIDI input drivers
1407       currently available for the LinuxSampler instance:
1408    
1409  Schoenebeck            Expires November 19, 2005               [Page 24]        GET AVAILABLE_MIDI_INPUT_DRIVERS
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
1410    
1411       Possible Answers:
1412    
1413        LinuxSampler will answer by sending the number of available MIDI        LinuxSampler will answer by sending the number of available MIDI
1414        input drivers.        input drivers.
# Line 1353  Internet-Draft       LinuxSampler Contro Line 1418  Internet-Draft       LinuxSampler Contro
1418        C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"        C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"
1419        S: "2"        S: "2"
1420    
1421  5.3.2  Getting all available MIDI input drivers  6.3.2  Getting all available MIDI input drivers
1422    
1423     Use the following command to list all MIDI input drivers currently     Use the following command to list all MIDI input drivers currently
1424     available for the LinuxSampler instance:     available for the LinuxSampler instance:
# Line 1370  Internet-Draft       LinuxSampler Contro Line 1435  Internet-Draft       LinuxSampler Contro
1435        C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"        C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
1436        S: "ALSA,JACK"        S: "ALSA,JACK"
1437    
1438  5.3.3  Getting information about a specific MIDI input driver  6.3.3  Getting information about a specific MIDI input driver
1439    
1440     Use the following command to get detailed information about a     Use the following command to get detailed information about a
1441     specific MIDI input driver:     specific MIDI input driver:
1442    
1443        GET MIDI_INPUT_DRIVER INFO <midi-input-driver>        GET MIDI_INPUT_DRIVER INFO <midi-input-driver>
1444    
1445     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
1446       returned by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2)
1447       command.
1448    
1449     Possible Answers:     Possible Answers:
1450    
1451    
1452    
1453    
1454    
1455    Schoenebeck            Expires November 22, 2005               [Page 26]
1456    
1457    Internet-Draft       LinuxSampler Control Protocol              May 2005
1458    
1459    
1460        LinuxSampler will answer by sending a <CRLF> separated list.  Each        LinuxSampler will answer by sending a <CRLF> separated list.  Each
1461        answer line begins with the information category name followed by        answer line begins with the information category name followed by
1462        a colon and then a space character <SP> and finally the info        a colon and then a space character <SP> and finally the info
# Line 1392  Internet-Draft       LinuxSampler Contro Line 1468  Internet-Draft       LinuxSampler Contro
1468           VERSION -           VERSION -
1469              arbitrary character string regarding the driver's version              arbitrary character string regarding the driver's version
1470           PARAMETERS -           PARAMETERS -
   
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 25]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
1471              comma separated list of all parameters available for the              comma separated list of all parameters available for the
1472              given MIDI input driver              given MIDI input driver
1473        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 1413  Internet-Draft       LinuxSampler Contro Line 1480  Internet-Draft       LinuxSampler Contro
1480           "PARAMETERS: DRIVER,ACTIVE"           "PARAMETERS: DRIVER,ACTIVE"
1481           "."           "."
1482    
1483  5.3.4  Getting information about specific MIDI input driver parameter  6.3.4  Getting information about specific MIDI input driver parameter
1484    
1485     Use the following command to get detailed information about a     Use the following command to get detailed information about a
1486     specific parameter of a specific MIDI input driver:     specific parameter of a specific MIDI input driver:
# Line 1421  Internet-Draft       LinuxSampler Contro Line 1488  Internet-Draft       LinuxSampler Contro
1488        GET MIDI_INPUT_DRIVER_PARAMETER INFO <midit> <param> [<deplist>]        GET MIDI_INPUT_DRIVER_PARAMETER INFO <midit> <param> [<deplist>]
1489    
1490     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
1491     "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 5.3.2) command, <param>     "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2) command, <param>
1492     a specific parameter name for which information should be obtained     a specific parameter name for which information should be obtained
1493     (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)
1494     command) and <deplist> is an optional list of parameters on which the     command) and <deplist> is an optional list of parameters on which the
1495     sought parameter <param> depends on, <deplist> is a key-value pair     sought parameter <param> depends on, <deplist> is a key-value pair
1496     list in form of "key1=val1 key2=val2 ...", where character string     list in form of "key1=val1 key2=val2 ...", where character string
# Line 1438  Internet-Draft       LinuxSampler Contro Line 1505  Internet-Draft       LinuxSampler Contro
1505     answer line begins with the information category name followed by a     answer line begins with the information category name followed by a
1506     colon and then a space character <SP> and finally the info character     colon and then a space character <SP> and finally the info character
1507     string to that info category.  There is information which is always     string to that info category.  There is information which is always
1508    
1509    
1510    
1511    Schoenebeck            Expires November 22, 2005               [Page 27]
1512    
1513    Internet-Draft       LinuxSampler Control Protocol              May 2005
1514    
1515    
1516     returned, independent of the given driver parameter and there is     returned, independent of the given driver parameter and there is
1517     optional information which is only shown dependent to given driver     optional information which is only shown dependent to given driver
1518     parameter.  At the moment the following information categories are     parameter.  At the moment the following information categories are
# Line 1448  Internet-Draft       LinuxSampler Contro Line 1523  Internet-Draft       LinuxSampler Contro
1523           value(s) or "FLOAT" for dotted number(s) or "STRING" for           value(s) or "FLOAT" for dotted number(s) or "STRING" for
1524           character string(s) (always returned, no matter which driver           character string(s) (always returned, no matter which driver
1525           parameter)           parameter)
   
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 26]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
1526        DESCRIPTION -        DESCRIPTION -
1527           arbitrary text describing the purpose of the parameter (always           arbitrary text describing the purpose of the parameter (always
1528           returned, no matter which driver parameter)           returned, no matter which driver parameter)
1529        MANDATORY -        MANDATORY -
1530           either true or false, defines if this parameter must be given           either true or false, defines if this parameter must be given
1531           when the device is to be created with the 'CREATE           when the device is to be created with the 'CREATE
1532           MIDI_INPUT_DEVICE' (Section 5.3.5) command (always returned, no           MIDI_INPUT_DEVICE' (Section 6.3.5) command (always returned, no
1533           matter which driver parameter)           matter which driver parameter)
1534        FIX -        FIX -
1535           either true or false, if false then this parameter can be           either true or false, if false then this parameter can be
1536           changed at any time, once the device is created by the 'CREATE           changed at any time, once the device is created by the 'CREATE
1537           MIDI_INPUT_DEVICE' (Section 5.3.5) command (always returned, no           MIDI_INPUT_DEVICE' (Section 6.3.5) command (always returned, no
1538           matter which driver parameter)           matter which driver parameter)
1539        MULTIPLICITY -        MULTIPLICITY -
1540           either true or false, defines if this parameter allows only one           either true or false, defines if this parameter allows only one
# Line 1488  Internet-Draft       LinuxSampler Contro Line 1554  Internet-Draft       LinuxSampler Contro
1554        DEFAULT -        DEFAULT -
1555           reflects the default value for this parameter which is used           reflects the default value for this parameter which is used
1556           when the device is created and not explicitly given with the           when the device is created and not explicitly given with the
1557           'CREATE MIDI_INPUT_DEVICE' (Section 5.3.5) command, in case of           'CREATE MIDI_INPUT_DEVICE' (Section 6.3.5) command, in case of
1558           MULTIPLCITY=true, this is a comma separated list, that's why           MULTIPLCITY=true, this is a comma separated list, that's why
1559           character strings are encapsulated into apostrophes (')           character strings are encapsulated into apostrophes (')
1560           (optionally returned, dependent to driver parameter)           (optionally returned, dependent to driver parameter)
1561        RANGE_MIN -        RANGE_MIN -
1562           defines lower limit of the allowed value range for this           defines lower limit of the allowed value range for this
1563           parameter, can be an integer value as well as a dotted number,           parameter, can be an integer value as well as a dotted number,
1564    
1565    
1566    
1567    Schoenebeck            Expires November 22, 2005               [Page 28]
1568    
1569    Internet-Draft       LinuxSampler Control Protocol              May 2005
1570    
1571    
1572           this parameter is often used in conjunction with RANGE_MAX, but           this parameter is often used in conjunction with RANGE_MAX, but
1573           may also appear without (optionally returned, dependent to           may also appear without (optionally returned, dependent to
1574           driver parameter)           driver parameter)
# Line 1504  Internet-Draft       LinuxSampler Contro Line 1578  Internet-Draft       LinuxSampler Contro
1578           this parameter is often used in conjunction with RANGE_MIN, but           this parameter is often used in conjunction with RANGE_MIN, but
1579           may also appear without (optionally returned, dependent to           may also appear without (optionally returned, dependent to
1580           driver parameter)           driver parameter)
   
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 27]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
1581        POSSIBILITIES -        POSSIBILITIES -
1582           comma separated list of possible values for this parameter,           comma separated list of possible values for this parameter,
1583           character strings are encapsulated into apostrophes (optionally           character strings are encapsulated into apostrophes (optionally
# Line 1531  Internet-Draft       LinuxSampler Contro Line 1596  Internet-Draft       LinuxSampler Contro
1596           "DEFAULT: true"           "DEFAULT: true"
1597           "."           "."
1598    
1599  5.3.5  Creating a MIDI input device  6.3.5  Creating a MIDI input device
1600    
1601     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
1602     desired MIDI input system:     desired MIDI input system:
# Line 1539  Internet-Draft       LinuxSampler Contro Line 1604  Internet-Draft       LinuxSampler Contro
1604        CREATE MIDI_INPUT_DEVICE <midi-input-driver> [<param-list>]        CREATE MIDI_INPUT_DEVICE <midi-input-driver> [<param-list>]
1605    
1606     Where <midi-input-driver> should be replaced by the desired MIDI     Where <midi-input-driver> should be replaced by the desired MIDI
1607     input system and <param-list> by an optional list of driver specific     input system as returned by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
1608     parameters in form of "key1=val1 key2=val2 ...", where character     (Section 6.3.2) command and <param-list> by an optional list of
1609     string values should be encapsulated into apostrophes (').  Note that     driver specific parameters in form of "key1=val1 key2=val2 ...",
1610     there might be drivers which require parameter(s) to be given with     where character string values should be encapsulated into apostrophes
1611     this command.  Use the previously described commands in this chapter     (').  Note that there might be drivers which require parameter(s) to
1612     to get that information.     be given with this command.  Use the previously described commands in
1613       this chapter to get that information.
1614    
1615     Possible Answers:     Possible Answers:
1616    
1617        "OK[<device-id>]" -        "OK[<device-id>]" -
1618           in case the device was successfully created, where <device-id>           in case the device was successfully created, where <device-id>
1619           is the numerical ID of the new device           is the numerical ID of the new device
1620    
1621    
1622    
1623    Schoenebeck            Expires November 22, 2005               [Page 29]
1624    
1625    Internet-Draft       LinuxSampler Control Protocol              May 2005
1626    
1627    
1628        "WRN[<device-id>]:<warning-code>:<warning-message>" -        "WRN[<device-id>]:<warning-code>:<warning-message>" -
1629           in case the driver was loaded successfully, where <device-id>           in case the driver was loaded successfully, where <device-id>
1630           is the numerical ID of the new device, but there are noteworthy           is the numerical ID of the new device, but there are noteworthy
# Line 1562  Internet-Draft       LinuxSampler Contro Line 1636  Internet-Draft       LinuxSampler Contro
1636    
1637     Example:     Example:
1638    
   
   
 Schoenebeck            Expires November 19, 2005               [Page 28]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
1639        C: "CREATE MIDI_INPUT_DEVICE ALSA"        C: "CREATE MIDI_INPUT_DEVICE ALSA"
1640        S: "OK[0]"        S: "OK[0]"
1641    
1642  5.3.6  Destroying a MIDI input device  6.3.6  Destroying a MIDI input device
1643    
1644     Use the following command to destroy a created MIDI input device:     Use the following command to destroy a created MIDI input device:
1645    
1646        DESTROY MIDI_INPUT_DEVICE <device-id>        DESTROY MIDI_INPUT_DEVICE <device-id>
1647    
1648     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
1649       returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
1650       MIDI_INPUT_DEVICES" (Section 6.3.8) command.
1651    
1652     Possible Answers:     Possible Answers:
1653    
# Line 1597  Internet-Draft       LinuxSampler Contro Line 1666  Internet-Draft       LinuxSampler Contro
1666        C: "DESTROY MIDI_INPUT_DEVICE 0"        C: "DESTROY MIDI_INPUT_DEVICE 0"
1667        S: "OK"        S: "OK"
1668    
1669  5.3.7  Getting all created MIDI input device count  6.3.7  Getting all created MIDI input device count
1670    
1671     Use the following command to count all created MIDI input devices:     Use the following command to count all created MIDI input devices:
1672    
# Line 1605  Internet-Draft       LinuxSampler Contro Line 1674  Internet-Draft       LinuxSampler Contro
1674    
1675     Possible Answers:     Possible Answers:
1676    
1677    
1678    
1679    Schoenebeck            Expires November 22, 2005               [Page 30]
1680    
1681    Internet-Draft       LinuxSampler Control Protocol              May 2005
1682    
1683    
1684        LinuxSampler will answer by sending the current number of all MIDI        LinuxSampler will answer by sending the current number of all MIDI
1685        input devices.        input devices.
1686    
# Line 1613  Internet-Draft       LinuxSampler Contro Line 1689  Internet-Draft       LinuxSampler Contro
1689        C: "GET MIDI_INPUT_DEVICES"        C: "GET MIDI_INPUT_DEVICES"
1690        S: "3"        S: "3"
1691    
1692  5.3.8  Getting all created MIDI input device list  6.3.8  Getting all created MIDI input device list
1693    
1694     Use the following command to list all created MIDI input devices:     Use the following command to list all created MIDI input devices:
1695    
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 29]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
1696        LIST MIDI_INPUT_DEVICES        LIST MIDI_INPUT_DEVICES
1697    
1698     Possible Answers:     Possible Answers:
# Line 1640  Internet-Draft       LinuxSampler Contro Line 1708  Internet-Draft       LinuxSampler Contro
1708        C: "LIST MIDI_INPUT_DEVICES"        C: "LIST MIDI_INPUT_DEVICES"
1709        S: "1,3"        S: "1,3"
1710    
1711  5.3.9  Getting current settings of a MIDI input device  6.3.9  Getting current settings of a MIDI input device
1712    
1713     Use the following command to get current settings of a specific,     Use the following command to get current settings of a specific,
1714     created MIDI input device:     created MIDI input device:
1715    
1716        GET MIDI_INPUT_DEVICE INFO <device-id>        GET MIDI_INPUT_DEVICE INFO <device-id>
1717    
1718     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
1719       returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
1720       MIDI_INPUT_DEVICES" (Section 6.3.8) command.
1721    
1722     Possible Answers:     Possible Answers:
1723    
# Line 1659  Internet-Draft       LinuxSampler Contro Line 1729  Internet-Draft       LinuxSampler Contro
1729        apostrophes (').  At the moment the following information        apostrophes (').  At the moment the following information
1730        categories are defined (independent of driver):        categories are defined (independent of driver):
1731    
1732    
1733    
1734    
1735    Schoenebeck            Expires November 22, 2005               [Page 31]
1736    
1737    Internet-Draft       LinuxSampler Control Protocol              May 2005
1738    
1739    
1740    
1741           DRIVER -           DRIVER -
1742              identifier of the used MIDI input driver, as e.g.  returned              identifier of the used MIDI input driver, as e.g.  returned
1743              by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 5.3.2)              by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2)
1744              command              command
1745           ACTIVE -           ACTIVE -
1746              either true or false, if false then the MIDI device is              either true or false, if false then the MIDI device is
# Line 1672  Internet-Draft       LinuxSampler Contro Line 1751  Internet-Draft       LinuxSampler Contro
1751     fields above are only those fields which are returned by all MIDI     fields above are only those fields which are returned by all MIDI
1752     input devices.  Every MIDI input driver might have its own,     input devices.  Every MIDI input driver might have its own,
1753     additional driver specific parameters (see "GET MIDI_INPUT_DRIVER     additional driver specific parameters (see "GET MIDI_INPUT_DRIVER
1754     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  
   
   
1755     command.     command.
1756    
1757     Example:     Example:
# Line 1690  Internet-Draft       LinuxSampler Contro Line 1761  Internet-Draft       LinuxSampler Contro
1761           "ACTIVE: true"           "ACTIVE: true"
1762           "."           "."
1763    
1764  5.3.10  Changing settings of MIDI input devices  6.3.10  Changing settings of MIDI input devices
1765    
1766     Use the following command to alter a specific setting of a created     Use the following command to alter a specific setting of a created
1767     MIDI input device:     MIDI input device:
# Line 1698  Internet-Draft       LinuxSampler Contro Line 1769  Internet-Draft       LinuxSampler Contro
1769        SET MIDI_INPUT_DEVICE_PARAMETER <device-id> <key>=<value>        SET MIDI_INPUT_DEVICE_PARAMETER <device-id> <key>=<value>
1770    
1771     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
1772     input device, <key> by the name of the parameter to change and     input device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section
1773     <value> by the new value for this parameter.     6.3.5) or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command, <key> by
1774       the name of the parameter to change and <value> by the new value for
1775       this parameter.
1776    
1777     Possible Answers:     Possible Answers:
1778    
# Line 1713  Internet-Draft       LinuxSampler Contro Line 1786  Internet-Draft       LinuxSampler Contro
1786           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
1787           error message           error message
1788    
1789    
1790    
1791    Schoenebeck            Expires November 22, 2005               [Page 32]
1792    
1793    Internet-Draft       LinuxSampler Control Protocol              May 2005
1794    
1795    
1796     Example:     Example:
1797    
1798        C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"        C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"
1799        S: "OK"        S: "OK"
1800    
1801  5.3.11  Getting information about a MIDI port  6.3.11  Getting information about a MIDI port
1802    
1803     Use the following command to get information about a MIDI port:     Use the following command to get information about a MIDI port:
1804    
1805        GET MIDI_INPUT_PORT INFO <device-id> <midi-port>        GET MIDI_INPUT_PORT INFO <device-id> <midi-port>
1806    
1807     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
1808     <midi-port> the MIDI input port number.     returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
1809       MIDI_INPUT_DEVICES" (Section 6.3.8) command and <midi-port> the MIDI
1810       input port number.
1811    
1812     Possible Answers:     Possible Answers:
1813    
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 31]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
1814        LinuxSampler will answer by sending a <CRLF> separated list.  Each        LinuxSampler will answer by sending a <CRLF> separated list.  Each
1815        answer line begins with the information category name followed by        answer line begins with the information category name followed by
1816        a colon and then a space character <SP> and finally the info        a colon and then a space character <SP> and finally the info
# Line 1756  Internet-Draft       LinuxSampler Contro Line 1830  Internet-Draft       LinuxSampler Contro
1830           "ALSA_SEQ_BINDINGS: '64:0'"           "ALSA_SEQ_BINDINGS: '64:0'"
1831           "."           "."
1832    
1833  5.3.12  Getting information about specific MIDI port parameter  6.3.12  Getting information about specific MIDI port parameter
1834    
1835     Use the following command to get detailed information about specific     Use the following command to get detailed information about specific
1836     MIDI port parameter:     MIDI port parameter:
# Line 1764  Internet-Draft       LinuxSampler Contro Line 1838  Internet-Draft       LinuxSampler Contro
1838        GET MIDI_INPUT_PORT_PARAMETER INFO <dev-id> <port> <param>        GET MIDI_INPUT_PORT_PARAMETER INFO <dev-id> <port> <param>
1839    
1840     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
1841     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
1842     <port> the MIDI port number and <param> a specific port parameter     MIDI_INPUT_DEVICES" (Section 6.3.8) command, <port> the MIDI port
1843     name for which information should be obtained (as returned by the     number and <param> a specific port parameter name for which
1844     "GET MIDI_INPUT_PORT INFO" (Section 5.3.11) command).  
1845    
1846    
1847    Schoenebeck            Expires November 22, 2005               [Page 33]
1848    
1849    Internet-Draft       LinuxSampler Control Protocol              May 2005
1850    
1851    
1852       information should be obtained (as returned by the "GET
1853       MIDI_INPUT_PORT INFO" (Section 6.3.11) command).
1854    
1855     Possible Answers:     Possible Answers:
1856    
# Line 1784  Internet-Draft       LinuxSampler Contro Line 1867  Internet-Draft       LinuxSampler Contro
1867           value(s) or "FLOAT" for dotted number(s) or "STRING" for           value(s) or "FLOAT" for dotted number(s) or "STRING" for
1868           character string(s) (always returned)           character string(s) (always returned)
1869        DESCRIPTION -        DESCRIPTION -
   
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 32]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
1870           arbitrary text describing the purpose of the parameter (always           arbitrary text describing the purpose of the parameter (always
1871           returned)           returned)
1872        FIX -        FIX -
# Line 1823  Internet-Draft       LinuxSampler Contro Line 1897  Internet-Draft       LinuxSampler Contro
1897    
1898     Example:     Example:
1899    
1900    
1901    
1902    
1903    Schoenebeck            Expires November 22, 2005               [Page 34]
1904    
1905    Internet-Draft       LinuxSampler Control Protocol              May 2005
1906    
1907    
1908        C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"        C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"
1909        S: "DESCRIPTION: bindings to other ALSA sequencer clients"        S: "DESCRIPTION: bindings to other ALSA sequencer clients"
1910           "TYPE: STRING"           "TYPE: STRING"
# Line 1831  Internet-Draft       LinuxSampler Contro Line 1913  Internet-Draft       LinuxSampler Contro
1913           "POSSIBILITIES: '64:0','68:0','68:1'"           "POSSIBILITIES: '64:0','68:0','68:1'"
1914           "."           "."
1915    
1916  5.3.13  Changing settings of MIDI input ports  6.3.13  Changing settings of MIDI input ports
1917    
1918     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
1919     port:     port:
# Line 1839  Internet-Draft       LinuxSampler Contro Line 1921  Internet-Draft       LinuxSampler Contro
1921        SET MIDI_INPUT_PORT_PARAMETER <device-id> <port> <key>=<value>        SET MIDI_INPUT_PORT_PARAMETER <device-id> <port> <key>=<value>
1922    
1923     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
1924     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)
1925     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
1926       MIDI port number, <key> by the name of the parameter to change and
1927       <value> by the new value for this parameter.
   
 Schoenebeck            Expires November 19, 2005               [Page 33]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
1928    
1929     Possible Answers:     Possible Answers:
1930    
# Line 1865  Internet-Draft       LinuxSampler Contro Line 1942  Internet-Draft       LinuxSampler Contro
1942    
1943    
1944    
1945  5.4  Configuring sampler channels  6.4  Configuring sampler channels
1946    
1947     The following commands describe how to add and remove sampler     The following commands describe how to add and remove sampler
1948     channels, deploy sampler engines, load instruments and connect     channels, associate a sampler channel with a sampler engine, load
1949     sampler channels to MIDI and audio devices.     instruments and connect sampler channels to MIDI and audio devices.
1950    
1951  5.4.1  Loading an instrument  6.4.1  Loading an instrument
1952    
1953     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
1954     one of the following commands:     one of the following commands:
1955    
1956    
1957    
1958    
1959    Schoenebeck            Expires November 22, 2005               [Page 35]
1960    
1961    Internet-Draft       LinuxSampler Control Protocol              May 2005
1962    
1963    
1964        LOAD INSTRUMENT [NON_MODAL] '<filename>' <instr-index>        LOAD INSTRUMENT [NON_MODAL] '<filename>' <instr-index>
1965        <sampler-channel>        <sampler-channel>
1966    
# Line 1890  Internet-Draft       LinuxSampler Contro Line 1975  Internet-Draft       LinuxSampler Contro
1975     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
1976     version returns immediately and a background process is launched to     version returns immediately and a background process is launched to
1977     load the instrument on the channel.  The GET CHANNEL INFO (Section     load the instrument on the channel.  The GET CHANNEL INFO (Section
1978     5.4.10) command can be used to obtain loading progress from     6.4.10) command can be used to obtain loading progress from
1979     INSTRUMENT_STATUS field.  LOAD command will perform sanity checks     INSTRUMENT_STATUS field.  LOAD command will perform sanity checks
1980     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
1981     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 1983  Internet-Draft       LinuxSampler Contro
1983    
1984     Possible Answers:     Possible Answers:
1985    
   
   
 Schoenebeck            Expires November 19, 2005               [Page 34]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
1986        "OK" -        "OK" -
1987           in case the instrument was successfully loaded           in case the instrument was successfully loaded
1988        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
# Line 1921  Internet-Draft       LinuxSampler Contro Line 1999  Internet-Draft       LinuxSampler Contro
1999    
2000    
2001    
2002  5.4.2  Loading a sampler engine  6.4.2  Loading a sampler engine
2003    
2004     A sample engine can be deployed and assigned to a specific sampler     A sampler engine type can be associated to a specific sampler channel
2005     channel by the following command:     by the following command:
2006    
2007        LOAD ENGINE <engine-name> <sampler-channel>        LOAD ENGINE <engine-name> <sampler-channel>
2008    
2009     Where <engine-name> is an engine name as obtained by the "LIST     Where <engine-name> is an engine name as obtained by the "LIST
2010     AVAILABLE_ENGINES" (Section 5.4.8) command and <sampler-channel> the     AVAILABLE_ENGINES" (Section 6.4.8) command and <sampler-channel> the
2011     sampler channel the deployed engine should be assigned to.  Even if     sampler channel as returned by the "ADD CHANNEL" (Section 6.4.5) or
2012     the respective sampler channel has already a deployed engine with  
2013     that engine name, a new engine instance will be assigned to the  
2014     sampler channel.  
2015    Schoenebeck            Expires November 22, 2005               [Page 36]
2016    
2017    Internet-Draft       LinuxSampler Control Protocol              May 2005
2018    
2019    
2020       "LIST CHANNELS" (Section 6.4.4) command where the engine type should
2021       be assigned to.  This command should be issued after adding a new
2022       sampler channel and before any other control commands on the new
2023       sampler channel.  It can also be used to change the engine type of a
2024       sampler channel.  This command has (currently) no way to define or
2025       force if a new engine instance should be created and assigned to the
2026       given sampler channel or if an already existing instance of that
2027       engine type, shared with other sampler channels, should be used.
2028    
2029     Possible Answers:     Possible Answers:
2030    
# Line 1951  Internet-Draft       LinuxSampler Contro Line 2042  Internet-Draft       LinuxSampler Contro
2042    
2043    
2044    
2045    6.4.3  Getting all created sampler channel count
   
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 35]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
 5.4.3  Getting all created sampler channel count  
2046    
2047     The number of sampler channels can change on runtime.  To get the     The number of sampler channels can change on runtime.  To get the
2048     current amount of sampler channels, the front-end can send the     current amount of sampler channels, the front-end can send the
# Line 1979  Internet-Draft       LinuxSampler Contro Line 2060  Internet-Draft       LinuxSampler Contro
2060        C: "GET CHANNELS"        C: "GET CHANNELS"
2061        S: "12"        S: "12"
2062    
2063  5.4.4  Getting all created sampler channel list  6.4.4  Getting all created sampler channel list
2064    
2065     The number of sampler channels can change on runtime.  To get the     The number of sampler channels can change on runtime.  To get the
2066     current list of sampler channels, the front-end can send the     current list of sampler channels, the front-end can send the
2067     following command:     following command:
2068    
2069    
2070    
2071    Schoenebeck            Expires November 22, 2005               [Page 37]
2072    
2073    Internet-Draft       LinuxSampler Control Protocol              May 2005
2074    
2075    
2076        LIST CHANNELS        LIST CHANNELS
2077    
2078     Possible Answers:     Possible Answers:
# Line 1997  Internet-Draft       LinuxSampler Contro Line 2085  Internet-Draft       LinuxSampler Contro
2085        C: "LIST CHANNELS"        C: "LIST CHANNELS"
2086        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"
2087    
2088  5.4.5  Adding a new sampler channel  6.4.5  Adding a new sampler channel
2089    
2090     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
2091     list by sending the following command:     list by sending the following command:
# Line 2009  Internet-Draft       LinuxSampler Contro Line 2097  Internet-Draft       LinuxSampler Contro
2097     list.  The front-end should send the respective, related commands     list.  The front-end should send the respective, related commands
2098     right after to e.g.  load an engine, load an instrument and setting     right after to e.g.  load an engine, load an instrument and setting
2099     input, output method and eventually other commands to initialize the     input, output method and eventually other commands to initialize the
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 36]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
2100     new channel.  The front-end should use the sampler channel returned     new channel.  The front-end should use the sampler channel returned
2101     by the answer of this command to perform the previously recommended     by the answer of this command to perform the previously recommended
2102     commands, to avoid race conditions e.g.  with other front-ends that     commands, to avoid race conditions e.g.  with other front-ends that
# Line 2041  Internet-Draft       LinuxSampler Contro Line 2121  Internet-Draft       LinuxSampler Contro
2121    
2122    
2123    
2124  5.4.6  Removing a sampler channel  
2125    
2126    
2127    Schoenebeck            Expires November 22, 2005               [Page 38]
2128    
2129    Internet-Draft       LinuxSampler Control Protocol              May 2005
2130    
2131    
2132    6.4.6  Removing a sampler channel
2133    
2134     A sampler channel can be removed by sending the following command:     A sampler channel can be removed by sending the following command:
2135    
2136        REMOVE CHANNEL <sampler-channel>        REMOVE CHANNEL <sampler-channel>
2137    
2138     Where <sampler-channel> should be replaced by the number of the     Where <sampler-channel> should be replaced by the number of the
2139     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
2140     "LIST CHANNELS" (Section 5.4.4) command.  The channel numbers of all     "LIST CHANNELS" (Section 6.4.4) command.  The channel numbers of all
2141     subsequent sampler channels remain the same.     subsequent sampler channels remain the same.
2142    
2143     Possible Answers:     Possible Answers:
# Line 2068  Internet-Draft       LinuxSampler Contro Line 2156  Internet-Draft       LinuxSampler Contro
2156    
2157    
2158    
2159  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  
2160    
2161     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
2162     the following command:     the following command:
# Line 2092  Internet-Draft       LinuxSampler Contro Line 2173  Internet-Draft       LinuxSampler Contro
2173        C: "GET AVAILABLE_ENGINES"        C: "GET AVAILABLE_ENGINES"
2174        S: "4"        S: "4"
2175    
2176  5.4.8  Getting all available engines  6.4.8  Getting all available engines
2177    
2178     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
2179     the following command:     the following command:
2180    
2181    
2182    
2183    Schoenebeck            Expires November 22, 2005               [Page 39]
2184    
2185    Internet-Draft       LinuxSampler Control Protocol              May 2005
2186    
2187    
2188        LIST AVAILABLE_ENGINES        LIST AVAILABLE_ENGINES
2189    
2190     Possible Answers:     Possible Answers:
# Line 2111  Internet-Draft       LinuxSampler Contro Line 2199  Internet-Draft       LinuxSampler Contro
2199        C: "LIST AVAILABLE_ENGINES"        C: "LIST AVAILABLE_ENGINES"
2200        S: "'GigEngine','AkaiEngine','DLSEngine','JoesCustomEngine'"        S: "'GigEngine','AkaiEngine','DLSEngine','JoesCustomEngine'"
2201    
2202  5.4.9  Getting information about an engine  6.4.9  Getting information about an engine
2203    
2204     The front-end can ask for information about a specific engine by     The front-end can ask for information about a specific engine by
2205     sending the following command:     sending the following command:
# Line 2119  Internet-Draft       LinuxSampler Contro Line 2207  Internet-Draft       LinuxSampler Contro
2207        GET ENGINE INFO <engine-name>        GET ENGINE INFO <engine-name>
2208    
2209     Where <engine-name> is an engine name as obtained by the "LIST     Where <engine-name> is an engine name as obtained by the "LIST
2210     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  
   
2211    
2212     Possible Answers:     Possible Answers:
2213    
# Line 2151  Internet-Draft       LinuxSampler Contro Line 2231  Internet-Draft       LinuxSampler Contro
2231           "VERSION: testing-1.0"           "VERSION: testing-1.0"
2232           "."           "."
2233    
2234  5.4.10  Getting sampler channel information  
2235    
2236    
2237    
2238    
2239    Schoenebeck            Expires November 22, 2005               [Page 40]
2240    
2241    Internet-Draft       LinuxSampler Control Protocol              May 2005
2242    
2243    
2244    6.4.10  Getting sampler channel information
2245    
2246     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
2247     by sending the following command:     by sending the following command:
# Line 2159  Internet-Draft       LinuxSampler Contro Line 2249  Internet-Draft       LinuxSampler Contro
2249        GET CHANNEL INFO <sampler-channel>        GET CHANNEL INFO <sampler-channel>
2250    
2251     Where <sampler-channel> is the sampler channel number the front-end     Where <sampler-channel> is the sampler channel number the front-end
2252     is interested in.     is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2253       "LIST CHANNELS" (Section 6.4.4) command.
2254    
2255     Possible Answers:     Possible Answers:
2256    
# Line 2170  Internet-Draft       LinuxSampler Contro Line 2261  Internet-Draft       LinuxSampler Contro
2261        following categories are defined:        following categories are defined:
2262    
2263           ENGINE_NAME -           ENGINE_NAME -
2264              name of the engine that is deployed on the sampler channel,              name of the engine that is associated with the sampler
2265              "NONE" if there's no engine deployed yet for this sampler              channel, "NONE" if there's no engine associated yet for this
2266              channel              sampler channel
2267           AUDIO_OUTPUT_DEVICE -           AUDIO_OUTPUT_DEVICE -
2268              numerical ID of the audio output device which is currently              numerical ID of the audio output device which is currently
2269              connected to this sampler channel to output the audio              connected to this sampler channel to output the audio
2270              signal, "NONE" if there's no device connected to this              signal, "NONE" if there's no device connected to this
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 39]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
2271              sampler channel              sampler channel
2272           AUDIO_OUTPUT_CHANNELS -           AUDIO_OUTPUT_CHANNELS -
2273              number of output channels the sampler channel offers              number of output channels the sampler channel offers
# Line 2206  Internet-Draft       LinuxSampler Contro Line 2289  Internet-Draft       LinuxSampler Contro
2289           INSTRUMENT_STATUS -           INSTRUMENT_STATUS -
2290              integer values 0 to 100 indicating loading progress              integer values 0 to 100 indicating loading progress
2291              percentage for the instrument.  Negative value indicates a              percentage for the instrument.  Negative value indicates a
2292    
2293    
2294    
2295    Schoenebeck            Expires November 22, 2005               [Page 41]
2296    
2297    Internet-Draft       LinuxSampler Control Protocol              May 2005
2298    
2299    
2300              loading exception.  Value of 100 indicates that the              loading exception.  Value of 100 indicates that the
2301              instrument is fully loaded.              instrument is fully loaded.
2302           MIDI_INPUT_DEVICE -           MIDI_INPUT_DEVICE -
# Line 2232  Internet-Draft       LinuxSampler Contro Line 2323  Internet-Draft       LinuxSampler Contro
2323           "VOLUME: 1.0"           "VOLUME: 1.0"
2324           "AUDIO_OUTPUT_DEVICE: 0"           "AUDIO_OUTPUT_DEVICE: 0"
2325           "AUDIO_OUTPUT_CHANNELS: 2"           "AUDIO_OUTPUT_CHANNELS: 2"
   
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 40]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
2326           "AUDIO_OUTPUT_ROUTING: 0,1"           "AUDIO_OUTPUT_ROUTING: 0,1"
2327           "INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"           "INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"
2328           "INSTRUMENT_NR: 0"           "INSTRUMENT_NR: 0"
# Line 2251  Internet-Draft       LinuxSampler Contro Line 2333  Internet-Draft       LinuxSampler Contro
2333           "MIDI_INPUT_CHANNEL: 5"           "MIDI_INPUT_CHANNEL: 5"
2334           "."           "."
2335    
2336  5.4.11  Current number of active voices  6.4.11  Current number of active voices
2337    
2338     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
2339     sampler channel by sending the following command:     sampler channel by sending the following command:
# Line 2259  Internet-Draft       LinuxSampler Contro Line 2341  Internet-Draft       LinuxSampler Contro
2341        GET CHANNEL VOICE_COUNT <sampler-channel>        GET CHANNEL VOICE_COUNT <sampler-channel>
2342    
2343     Where <sampler-channel> is the sampler channel number the front-end     Where <sampler-channel> is the sampler channel number the front-end
2344     is interested in.     is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2345       "LIST CHANNELS" (Section 6.4.4) command.
2346    
2347     Possible Answers:     Possible Answers:
2348    
2349    
2350    
2351    Schoenebeck            Expires November 22, 2005               [Page 42]
2352    
2353    Internet-Draft       LinuxSampler Control Protocol              May 2005
2354    
2355    
2356        LinuxSampler will answer by returning the number of active voices        LinuxSampler will answer by returning the number of active voices
2357        on that channel.        on that channel.
2358    
# Line 2270  Internet-Draft       LinuxSampler Contro Line 2360  Internet-Draft       LinuxSampler Contro
2360    
2361    
2362    
2363  5.4.12  Current number of active disk streams  6.4.12  Current number of active disk streams
2364    
2365     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
2366     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 2368  Internet-Draft       LinuxSampler Contro
2368        GET CHANNEL STREAM_COUNT <sampler-channel>        GET CHANNEL STREAM_COUNT <sampler-channel>
2369    
2370     Where <sampler-channel> is the sampler channel number the front-end     Where <sampler-channel> is the sampler channel number the front-end
2371     is interested in.     is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2372       "LIST CHANNELS" (Section 6.4.4) command.
2373    
2374     Possible Answers:     Possible Answers:
2375    
# Line 2291  Internet-Draft       LinuxSampler Contro Line 2382  Internet-Draft       LinuxSampler Contro
2382    
2383    
2384    
2385    6.4.13  Current fill state of disk stream buffers
 Schoenebeck            Expires November 19, 2005               [Page 41]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
   
   
 5.4.13  Current fill state of disk stream buffers  
2386    
2387     The front-end can ask for the current fill state of all disk streams     The front-end can ask for the current fill state of all disk streams
2388     on a sampler channel by sending the following command:     on a sampler channel by sending the following command:
# Line 2311  Internet-Draft       LinuxSampler Contro Line 2394  Internet-Draft       LinuxSampler Contro
2394        GET CHANNEL BUFFER_FILL PERCENTAGE <sampler-channel>        GET CHANNEL BUFFER_FILL PERCENTAGE <sampler-channel>
2395    
2396     to get the fill state in percent, where <sampler-channel> is the     to get the fill state in percent, where <sampler-channel> is the
2397     sampler channel number the front-end is interested in.     sampler channel number the front-end is interested in as returned by
2398       the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
2399       command.
2400    
2401     Possible Answers:     Possible Answers:
2402    
2403    
2404    
2405    
2406    
2407    Schoenebeck            Expires November 22, 2005               [Page 43]
2408    
2409    Internet-Draft       LinuxSampler Control Protocol              May 2005
2410    
2411    
2412        LinuxSampler will either answer by returning a comma separated        LinuxSampler will either answer by returning a comma separated
2413        string with the fill state of all disk stream buffers on that        string with the fill state of all disk stream buffers on that
2414        channel or an empty line if there are no active disk streams or        channel or an empty line if there are no active disk streams or
# Line 2335  Internet-Draft       LinuxSampler Contro Line 2429  Internet-Draft       LinuxSampler Contro
2429        C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"        C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
2430        S: ""        S: ""
2431    
2432  5.4.14  Setting audio output device  6.4.14  Setting audio output device
2433    
2434     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
2435     channel by sending the following command:     channel by sending the following command:
# Line 2343  Internet-Draft       LinuxSampler Contro Line 2437  Internet-Draft       LinuxSampler Contro
2437        SET CHANNEL AUDIO_OUTPUT_DEVICE <sampler-channel>        SET CHANNEL AUDIO_OUTPUT_DEVICE <sampler-channel>
2438        <audio-device-id>        <audio-device-id>
2439    
2440     Where <audio-device-id> is the numerical ID of the audio output     Where <sampler-channel> is the respective sampler channel number as
2441     device and <sampler-channel> is the respective sampler channel     returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
2442       (Section 6.4.4) command and <audio-device-id> is the numerical ID of
2443       the audio output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
2444       (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
2445  Schoenebeck            Expires November 19, 2005               [Page 42]     command.
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
    number.  
2446    
2447     Possible Answers:     Possible Answers:
2448    
# Line 2371  Internet-Draft       LinuxSampler Contro Line 2460  Internet-Draft       LinuxSampler Contro
2460    
2461    
2462    
2463  5.4.15  Setting audio output type  Schoenebeck            Expires November 22, 2005               [Page 44]
2464    
2465    Internet-Draft       LinuxSampler Control Protocol              May 2005
2466    
2467    
2468    
2469    
2470    6.4.15  Setting audio output type
2471    
2472     DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!     DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
2473    
# Line 2400  Internet-Draft       LinuxSampler Contro Line 2496  Internet-Draft       LinuxSampler Contro
2496    
2497    
2498    
2499    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  
2500    
2501     The front-end can alter the audio output channel on a specific     The front-end can alter the audio output channel on a specific
2502     sampler channel by sending the following command:     sampler channel by sending the following command:
# Line 2417  Internet-Draft       LinuxSampler Contro Line 2504  Internet-Draft       LinuxSampler Contro
2504        SET CHANNEL AUDIO_OUTPUT_CHANNEL <sampler-chan> <audio-out>        SET CHANNEL AUDIO_OUTPUT_CHANNEL <sampler-chan> <audio-out>
2505        <audio-in>        <audio-in>
2506    
2507     Where <sampler-chan> is the sampler channel number, <audio-out> is     Where <sampler-chan> is the sampler channel number as returned by the
2508     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)
2509     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
2510     channel of the selected audio output device where <audio-out> should     audio output channel which should be rerouted and <audio-in> is the
2511     be routed to.     numerical ID of the audio channel of the selected audio output device
2512       where <audio-out> should be routed to.
2513    
2514     Possible Answers:     Possible Answers:
2515    
2516    
2517    
2518    
2519    Schoenebeck            Expires November 22, 2005               [Page 45]
2520    
2521    Internet-Draft       LinuxSampler Control Protocol              May 2005
2522    
2523    
2524        "OK" -        "OK" -
2525           on success           on success
2526        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
# Line 2439  Internet-Draft       LinuxSampler Contro Line 2535  Internet-Draft       LinuxSampler Contro
2535    
2536    
2537    
2538  5.4.17  Setting MIDI input device  6.4.17  Setting MIDI input device
2539    
2540     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
2541     channel by sending the following command:     channel by sending the following command:
2542    
2543        SET CHANNEL MIDI_INPUT_DEVICE <sampler-channel> <midi-device-id>        SET CHANNEL MIDI_INPUT_DEVICE <sampler-channel> <midi-device-id>
2544    
2545     Where <sampler-channel> is the sampler channel number and     Where <sampler-channel> is the sampler channel number as returned by
2546     <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)
2547       command and <midi-device-id> is  the numerical ID of the MIDI input
2548       device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5)
2549       or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command.
2550    
2551     Possible Answers:     Possible Answers:
2552    
# Line 2457  Internet-Draft       LinuxSampler Contro Line 2556  Internet-Draft       LinuxSampler Contro
2556           if MIDI input device was set, but there are noteworthy issue(s)           if MIDI input device was set, but there are noteworthy issue(s)
2557           related, providing an appropriate warning code and warning           related, providing an appropriate warning code and warning
2558           message           message
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 44]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
2559        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
2560           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
2561           error message           error message
# Line 2473  Internet-Draft       LinuxSampler Contro Line 2564  Internet-Draft       LinuxSampler Contro
2564    
2565    
2566    
2567  5.4.18  Setting MIDI input type  6.4.18  Setting MIDI input type
2568    
2569     DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!     DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
2570    
2571     The front-end can alter the MIDI input type on a specific sampler     The front-end can alter the MIDI input type on a specific sampler
2572    
2573    
2574    
2575    Schoenebeck            Expires November 22, 2005               [Page 46]
2576    
2577    Internet-Draft       LinuxSampler Control Protocol              May 2005
2578    
2579    
2580     channel by sending the following command:     channel by sending the following command:
2581    
2582        SET CHANNEL MIDI_INPUT_TYPE <sampler-channel> <midi-input-type>        SET CHANNEL MIDI_INPUT_TYPE <sampler-channel> <midi-input-type>
# Line 2501  Internet-Draft       LinuxSampler Contro Line 2600  Internet-Draft       LinuxSampler Contro
2600    
2601    
2602    
2603  5.4.19  Setting MIDI input port  6.4.19  Setting MIDI input port
2604    
2605     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
2606     channel by sending the following command:     channel by sending the following command:
# Line 2513  Internet-Draft       LinuxSampler Contro Line 2612  Internet-Draft       LinuxSampler Contro
2612    
2613     Possible Answers:     Possible Answers:
2614    
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 45]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
2615        "OK" -        "OK" -
2616           on success           on success
2617        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
# Line 2535  Internet-Draft       LinuxSampler Contro Line 2626  Internet-Draft       LinuxSampler Contro
2626    
2627    
2628    
2629  5.4.20  Setting MIDI input channel  
2630    
2631    Schoenebeck            Expires November 22, 2005               [Page 47]
2632    
2633    Internet-Draft       LinuxSampler Control Protocol              May 2005
2634    
2635    
2636    
2637    
2638    6.4.20  Setting MIDI input channel
2639    
2640     The front-end can alter the MIDI channel a sampler channel should     The front-end can alter the MIDI channel a sampler channel should
2641     listen to by sending the following command:     listen to by sending the following command:
# Line 2562  Internet-Draft       LinuxSampler Contro Line 2662  Internet-Draft       LinuxSampler Contro
2662    
2663    
2664    
2665  5.4.21  Setting channel volume  6.4.21  Setting channel volume
2666    
2667     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
2668     the following command:     the following command:
2669    
2670        SET CHANNEL VOLUME <sampler-channel> <volume>        SET CHANNEL VOLUME <sampler-channel> <volume>
2671    
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 46]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
2672     Where <volume> is an optionally dotted positive number (a value     Where <volume> is an optionally dotted positive number (a value
2673     smaller than 1.0 means attenuation, whereas a value greater than 1.0     smaller than 1.0 means attenuation, whereas a value greater than 1.0
2674     means amplification) and <sampler-channel> defines the sampler     means amplification) and <sampler-channel> defines the sampler
# Line 2589  Internet-Draft       LinuxSampler Contro Line 2681  Internet-Draft       LinuxSampler Contro
2681        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
2682           if channel volume was set, but there are noteworthy issue(s)           if channel volume was set, but there are noteworthy issue(s)
2683           related, providing an appropriate warning code and warning           related, providing an appropriate warning code and warning
2684    
2685    
2686    
2687    Schoenebeck            Expires November 22, 2005               [Page 48]
2688    
2689    Internet-Draft       LinuxSampler Control Protocol              May 2005
2690    
2691    
2692           message           message
2693        "ERR:<error-code>:<error-message>" -        "ERR:<error-code>:<error-message>" -
2694           in case it failed, providing an appropriate error code and           in case it failed, providing an appropriate error code and
# Line 2598  Internet-Draft       LinuxSampler Contro Line 2698  Internet-Draft       LinuxSampler Contro
2698    
2699    
2700    
2701  5.4.22  Resetting a sampler channel  6.4.22  Resetting a sampler channel
2702    
2703     The front-end can reset a particular sampler channel by sending the     The front-end can reset a particular sampler channel by sending the
2704     following command:     following command:
# Line 2626  Internet-Draft       LinuxSampler Contro Line 2726  Internet-Draft       LinuxSampler Contro
2726    
2727    
2728    
2729    6.5  Controlling connection
2730    
2731       The following commands are used to control the connection to
2732       LinuxSampler.
2733    
2734  Schoenebeck            Expires November 19, 2005               [Page 47]  6.5.1  Register front-end for receiving event messages
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
2735    
2736       The front-end can register itself to the LinuxSampler application to
2737       be informed about noteworthy events by sending this command:
2738    
2739    
2740    
 5.5  Controlling connection  
2741    
    The following commands are used to control the connection to  
    LinuxSampler.  
2742    
2743  5.5.1  Register front-end for receiving event messages  Schoenebeck            Expires November 22, 2005               [Page 49]
2744    
2745    Internet-Draft       LinuxSampler Control Protocol              May 2005
2746    
    The front-end can register itself to the LinuxSampler application to  
    be informed about noteworthy events by sending this command:  
2747    
2748        SUBSCRIBE <event-id>        SUBSCRIBE <event-id>
2749    
# Line 2666  Internet-Draft       LinuxSampler Contro Line 2766  Internet-Draft       LinuxSampler Contro
2766    
2767    
2768    
2769  5.5.2  Unregister front-end for not receiving event messages  6.5.2  Unregister front-end for not receiving event messages
2770    
2771     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
2772     event messages anymore by sending the following command:     event messages anymore by sending the following command:
# Line 2680  Internet-Draft       LinuxSampler Contro Line 2780  Internet-Draft       LinuxSampler Contro
2780    
2781        "OK" -        "OK" -
2782           on success           on success
   
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 48]  
   
 Internet-Draft       LinuxSampler Control Protocol              May 2005  
   
   
2783        "WRN:<warning-code>:<warning-message>" -        "WRN:<warning-code>:<warning-message>" -
2784           if unregistration succeeded, but there are noteworthy issue(s)           if unregistration succeeded, but there are noteworthy issue(s)
2785           related, providing an appropriate warning code and warning           related, providing an appropriate warning code and warning
# Line 2701  Internet-Draft       LinuxSampler Contro Line 2792  Internet-Draft       LinuxSampler Contro
2792    
2793    
2794    
2795  5.5.3  Enable or disable echo of commands  
2796    
2797    
2798    
2799    Schoenebeck            Expires November 22, 2005               [Page 50]
2800    
2801    Internet-Draft       LinuxSampler Control Protocol              May 2005
2802    
2803    
2804    6.5.3  Enable or disable echo of commands
2805    
2806     To enable or disable back sending of commands to the client the     To enable or disable back sending of commands to the client the
2807     following command can be used:     following command can be used:
# Line 2726  Internet-Draft       LinuxSampler Contro Line 2826  Internet-Draft       LinuxSampler Contro
2826    
2827    
2828    
2829  5.5.4  Close client connection  6.5.4  Close client connection
2830    
2831     The client can close its network connection to LinuxSampler by     The client can close its network connection to LinuxSampler by
2832     sending the following command:     sending the following command:
# Line 2736  Internet-Draft       LinuxSampler Contro Line 2836  Internet-Draft       LinuxSampler Contro
2836     This is probably more interesting for manual telnet connections to     This is probably more interesting for manual telnet connections to
2837     LinuxSampler than really useful for a front-end implementation.     LinuxSampler than really useful for a front-end implementation.
2838    
2839    6.6  Global commands
2840    
2841       The following commands have global impact on the sampler.
2842    
2843    6.6.1  Reset sampler
2844    
2845       The front-end can reset the whole sampler by sending the following
2846       command:
2847    
2848          RESET
2849    
2850       Possible Answers:
2851    
2852    
2853    
2854  Schoenebeck            Expires November 19, 2005               [Page 49]  
2855    Schoenebeck            Expires November 22, 2005               [Page 51]
2856    
2857  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
2858    
2859    
2860  5.6  Global commands        "OK" -
2861             always
2862    
2863     The following commands have global impact on the sampler.     Examples:
2864    
 5.6.1  Reset sampler  
2865    
    The front-end can reset the whole sampler by sending the following  
    command:  
2866    
2867        RESET  6.6.2  General sampler informations
2868    
2869       The client can ask for general informations about the LinuxSampler
2870       instance by sending the following command:
2871    
2872          GET SERVER INFO
2873    
2874     Possible Answers:     Possible Answers:
2875    
2876        "OK" -        LinuxSampler will answer by sending a <CRLF> separated list.  Each
2877           always        answer line begins with the information category name followed by
2878          a colon and then a space character <SP> and finally the info
2879          character string to that information category.  At the moment the
2880          following categories are defined:
2881    
2882     Examples:           DESCRIPTION -
2883                arbitrary textual description about the sampler
2884             VERSION -
2885                version of the sampler
2886             PROTOCOL_VERSION -
2887                version of the LSCP specification the sampler complies with
2888                (see Section 2 for details)
2889    
2890       The mentioned fields above don't have to be in particular order.
2891       Other fields might be added in future.
2892    
2893    
2894    
# Line 2782  Internet-Draft       LinuxSampler Contro Line 2908  Internet-Draft       LinuxSampler Contro
2908    
2909    
2910    
2911    Schoenebeck            Expires November 22, 2005               [Page 52]
2912    
2913    Internet-Draft       LinuxSampler Control Protocol              May 2005
2914    
2915    
2916    7.  Command Syntax
2917    
2918       The grammar of the control protocol as descibed in Section 6 is
2919       defined below using Backus-Naur Form (BNF as described in [RFC2234])
2920       where applicable.
2921    
2922       input =
2923          line LF
2924          / line CR LF
2925    
2926       line =
2927          /* epsilon (empty line ignored) */
2928          / comment
2929          / command
2930          / error
2931    
2932       comment =
2933          '#'
2934          / comment '#'
2935          / comment SP
2936          / comment number
2937          / comment string
2938    
2939       command =
2940          ADD SP CHANNEL
2941          / GET SP get_instruction
2942          / CREATE SP create_instruction
2943          / DESTROY SP destroy_instruction
2944          / LIST SP list_instruction
2945          / LOAD SP load_instruction
2946          / REMOVE SP CHANNEL SP sampler_channel
2947          / SET SP set_instruction
2948          / SUBSCRIBE SP subscribe_event
2949          / UNSUBSCRIBE SP unsubscribe_event
2950          / SELECT SP text
2951          / RESET SP CHANNEL SP sampler_channel
2952          / RESET
2953          / QUIT
2954    
2955       subscribe_event =
2956          CHANNEL_COUNT
2957          / VOICE_COUNT
2958          / STREAM_COUNT
2959          / BUFFER_FILL
2960          / CHANNEL_INFO
2961          / MISCELLANEOUS
2962    
2963       unsubscribe_event =
2964    
2965    
2966    
2967    Schoenebeck            Expires November 22, 2005               [Page 53]
2968    
2969    Internet-Draft       LinuxSampler Control Protocol              May 2005
2970    
2971    
2972          CHANNEL_COUNT
2973          / VOICE_COUNT
2974          / STREAM_COUNT
2975          / BUFFER_FILL
2976          / CHANNEL_INFO
2977          / MISCELLANEOUS
2978    
2979       get_instruction =
2980          AVAILABLE_ENGINES
2981          / AVAILABLE_MIDI_INPUT_DRIVERS
2982          / MIDI_INPUT_DRIVER SP INFO SP string
2983          / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
2984          / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP
2985          key_val_list
2986          / AVAILABLE_AUDIO_OUTPUT_DRIVERS
2987          / AUDIO_OUTPUT_DRIVER SP INFO SP string
2988          / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
2989          / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP
2990          key_val_list
2991          / AUDIO_OUTPUT_DEVICES
2992          / MIDI_INPUT_DEVICES
2993          / AUDIO_OUTPUT_DEVICE SP INFO SP number
2994          / MIDI_INPUT_DEVICE SP INFO SP number
2995          / MIDI_INPUT_PORT SP INFO SP number SP number
2996          / MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
2997          / AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
2998          / AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP
2999          string
3000          / CHANNELS
3001          / CHANNEL SP INFO SP sampler_channel
3002          / CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
3003          / CHANNEL SP STREAM_COUNT SP sampler_channel
3004          / CHANNEL SP VOICE_COUNT SP sampler_channel
3005          / ENGINE SP INFO SP engine_name
3006          / SERVER SP INFO
3007    
3008  Schoenebeck            Expires November 19, 2005               [Page 50]     set_instruction =
3009          AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '='
3010          param_val_list
3011          / AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '='
3012          param_val_list
3013          / MIDI_INPUT_DEVICE_PARAMETER SP number SP string '='
3014          param_val_list
3015          / MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '='
3016          param_val_list
3017          / CHANNEL SP set_chan_instruction
3018          / ECHO SP boolean
3019    
3020    
3021    
3022    
3023    Schoenebeck            Expires November 22, 2005               [Page 54]
3024    
3025  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
3026    
3027    
3028  6.  Command Syntax     create_instruction =
3029          AUDIO_OUTPUT_DEVICE SP string SP key_val_list
3030          / AUDIO_OUTPUT_DEVICE SP string
3031          / MIDI_INPUT_DEVICE SP string SP key_val_list
3032          / MIDI_INPUT_DEVICE SP string
3033    
3034       destroy_instruction =
3035          AUDIO_OUTPUT_DEVICE SP number
3036          / MIDI_INPUT_DEVICE SP number
3037    
3038     TODO: will soon automatically included from src/network/lscp.y,     load_instruction =
3039     meanwhile have a look at that file to get the exact definition of the        INSTRUMENT SP load_instr_args
3040     command syntax.        / ENGINE SP load_engine_args
3041    
3042       set_chan_instruction =
3043          AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
3044          / AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index
3045          SP audio_channel_index
3046          / AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
3047          / MIDI_INPUT SP sampler_channel SP device_index SP
3048          midi_input_port_index SP midi_input_channel_index
3049          / MIDI_INPUT_DEVICE SP sampler_channel SP device_index
3050          / MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
3051          / MIDI_INPUT_CHANNEL SP sampler_channel SP
3052          midi_input_channel_index
3053          / MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
3054          / VOLUME SP sampler_channel SP volume_value
3055    
3056       key_val_list =
3057          string '=' param_val_list
3058          / key_val_list SP string '=' param_val_list
3059    
3060       buffer_size_type =
3061          BYTES
3062          / PERCENTAGE
3063    
3064       list_instruction =
3065          AUDIO_OUTPUT_DEVICES
3066          / MIDI_INPUT_DEVICES
3067          / CHANNELS
3068          / AVAILABLE_ENGINES
3069          / AVAILABLE_MIDI_INPUT_DRIVERS
3070          / AVAILABLE_AUDIO_OUTPUT_DRIVERS
3071    
3072       load_instr_args =
3073          filename SP instrument_index SP sampler_channel
3074          / NON_MODAL SP filename SP instrument_index SP sampler_channel
3075    
3076    
3077    
3078    
3079    Schoenebeck            Expires November 22, 2005               [Page 55]
3080    
3081    Internet-Draft       LinuxSampler Control Protocol              May 2005
3082    
3083    
3084       load_engine_args =
3085          engine_name SP sampler_channel
3086    
3087       device_index =
3088          number
3089    
3090       audio_channel_index =
3091          number
3092    
3093       audio_output_type_name =
3094          string
3095    
3096       midi_input_port_index =
3097          number
3098    
3099       midi_input_channel_index =
3100          number
3101          / ALL
3102    
3103       midi_input_type_name =
3104          string
3105    
3106       volume_value =
3107          dotnum
3108          / number
3109    
3110       sampler_channel =
3111          number
3112    
3113       instrument_index =
3114          number
3115    
3116       engine_name =
3117          string
3118    
3119       filename =
3120          stringval
3121    
3122       param_val_list =
3123          param_val
3124          / param_val_list','param_val
3125    
3126       param_val =
3127          string
3128          / '\'' string '\''
3129          / '\"' string '\"'
3130          / number
3131    
3132    
3133    
3134    
3135    Schoenebeck            Expires November 22, 2005               [Page 56]
3136    
3137    Internet-Draft       LinuxSampler Control Protocol              May 2005
3138    
3139    
3140          / dotnum
3141    
3142    
3143    
# Line 2852  Internet-Draft       LinuxSampler Contro Line 3162  Internet-Draft       LinuxSampler Contro
3162    
3163    
3164    
3165  Schoenebeck            Expires November 19, 2005               [Page 51]  
3166    
3167    
3168    
3169    
3170    
3171    
3172    
3173    
3174    
3175    
3176    
3177    
3178    
3179    
3180    
3181    
3182    
3183    
3184    
3185    
3186    
3187    
3188    
3189    
3190    
3191    Schoenebeck            Expires November 22, 2005               [Page 57]
3192    
3193  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
3194    
3195    
3196  7.  Events  8.  Events
3197    
3198     This chapter will describe all currently defined events supported by     This chapter will describe all currently defined events supported by
3199     LinuxSampler.     LinuxSampler.
3200    
3201  7.1  Number of sampler channels changed  8.1  Number of sampler channels changed
3202    
3203     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
3204     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 3212  Internet-Draft       LinuxSampler Contro
3212     where <channels> will be replaced by the new number of sampler     where <channels> will be replaced by the new number of sampler
3213     channels.     channels.
3214    
3215  7.2  Number of active voices changed  8.2  Number of active voices changed
3216    
3217     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
3218     back-end changes by issuing the following command:     back-end changes by issuing the following command:
# Line 2891  Internet-Draft       LinuxSampler Contro Line 3227  Internet-Draft       LinuxSampler Contro
3227     voice count change occurred and <voices> by the new number of active     voice count change occurred and <voices> by the new number of active
3228     voices on that channel.     voices on that channel.
3229    
3230  7.3  Number of active disk streams changed  8.3  Number of active disk streams changed
3231    
3232     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
3233     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 3244  Internet-Draft       LinuxSampler Contro
3244    
3245    
3246    
3247  Schoenebeck            Expires November 19, 2005               [Page 52]  Schoenebeck            Expires November 22, 2005               [Page 58]
3248    
3249  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
3250    
3251    
3252     active disk streams on that channel.     active disk streams on that channel.
3253    
3254  7.4  Disk stream buffer fill state changed  8.4  Disk stream buffer fill state changed
3255    
3256     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
3257     stream on the back-end changes by issuing the following command:     stream on the back-end changes by issuing the following command:
# Line 2929  Internet-Draft       LinuxSampler Contro Line 3265  Internet-Draft       LinuxSampler Contro
3265     where <sampler-channel> will be replaced by the sampler channel the     where <sampler-channel> will be replaced by the sampler channel the
3266     buffer fill state change occurred on and <fill-data> will be replaced     buffer fill state change occurred on and <fill-data> will be replaced
3267     by the buffer fill data for this channel as described in Section     by the buffer fill data for this channel as described in Section
3268     5.4.13 as if the "GET CHANNEL BUFFER_FILL PERCENTAGE" (Section     6.4.13 as if the "GET CHANNEL BUFFER_FILL PERCENTAGE" (Section
3269     5.4.13) command was issued on this channel.     6.4.13) command was issued on this channel.
3270    
3271  7.5  Channel information changed  8.5  Channel information changed
3272    
3273     Client may want to be notified when changes were made to sampler     Client may want to be notified when changes were made to sampler
3274     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 3286  Internet-Draft       LinuxSampler Contro
3286     rather than real time events happening on the server, it is believed     rather than real time events happening on the server, it is believed
3287     that an empty notification message is sufficient here.     that an empty notification message is sufficient here.
3288    
3289  7.6  Miscellaneous and debugging events  8.6  Miscellaneous and debugging events
3290    
3291     Client may want to be notified of miscellaneous and debugging events     Client may want to be notified of miscellaneous and debugging events
3292     occurring at the server by issuing the following command:     occurring at the server by issuing the following command:
# Line 2964  Internet-Draft       LinuxSampler Contro Line 3300  Internet-Draft       LinuxSampler Contro
3300    
3301    
3302    
3303  Schoenebeck            Expires November 19, 2005               [Page 53]  Schoenebeck            Expires November 22, 2005               [Page 59]
3304    
3305  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
3306    
# Line 3020  Internet-Draft       LinuxSampler Contro Line 3356  Internet-Draft       LinuxSampler Contro
3356    
3357    
3358    
3359  Schoenebeck            Expires November 19, 2005               [Page 54]  Schoenebeck            Expires November 22, 2005               [Page 60]
3360    
3361  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
3362    
3363    
3364  8.  Security Considerations  9.  Security Considerations
3365    
3366     As there is so far no method of authentication and authorization     As there is so far no method of authentication and authorization
3367     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 3412  Internet-Draft       LinuxSampler Contro
3412    
3413    
3414    
3415  Schoenebeck            Expires November 19, 2005               [Page 55]  Schoenebeck            Expires November 22, 2005               [Page 61]
3416    
3417  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
3418    
3419    
3420  9.  Acknowledgments  10.  Acknowledgments
3421    
3422     This document has benefited greatly from the comments of the     This document has benefited greatly from the comments of the
3423     following people, discussed on the LinuxSampler developer's mailing     following people, discussed on the LinuxSampler developer's mailing
# Line 3092  Internet-Draft       LinuxSampler Contro Line 3428  Internet-Draft       LinuxSampler Contro
3428        Mark Knecht        Mark Knecht
3429        Grigor Iliev        Grigor Iliev
3430    
3431  10  References  11  References
3432    
3433     [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate     [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
3434                Requirement Levels", BCP 14, RFC 2119, March 1997.                Requirement Levels", RFC 2119, 1997.
3435    
3436       [RFC2234]  Crocker, D. and P. Overell, "Augmented BNF for Syntax
3437                  Specifications", RFC 2234, 1997.
3438    
3439       [RFC793]   Defense Advanced Research Projects Agency, "TRANSMISSION
3440                  CONTROL PROTOCOL", RFC 793, 1981.
3441    
3442    
3443  Author's Address  Author's Address
# Line 3126  Author's Address Line 3468  Author's Address
3468    
3469    
3470    
3471    Schoenebeck            Expires November 22, 2005               [Page 62]
   
   
   
   
   
 Schoenebeck            Expires November 19, 2005               [Page 56]  
3472    
3473  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
3474    
# Line 3188  Full Copyright Statement Line 3524  Full Copyright Statement
3524    
3525    
3526    
3527  Schoenebeck            Expires November 19, 2005               [Page 57]  Schoenebeck            Expires November 22, 2005               [Page 63]
3528    
3529  Internet-Draft       LinuxSampler Control Protocol              May 2005  Internet-Draft       LinuxSampler Control Protocol              May 2005
3530    
# Line 3244  Acknowledgment Line 3580  Acknowledgment
3580    
3581    
3582    
3583  Schoenebeck            Expires November 19, 2005               [Page 58]  Schoenebeck            Expires November 22, 2005               [Page 64]
3584    

Legend:
Removed from v.561  
changed lines
  Added in v.575

  ViewVC Help
Powered by ViewVC