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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

1 senoner 542 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2     <html lang="en"><head><title>LinuxSampler Control Protocol</title>
3     <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
4     <meta name="description" content="LinuxSampler Control Protocol">
5     <meta name="keywords" content="LSCP">
6 schoenebeck 940 <meta name="generator" content="xml2rfc v1.30 (http://xml.resource.org/)">
7 senoner 542 <style type='text/css'>
8     <!--
9     body {
10     font-family: verdana, charcoal, helvetica, arial, sans-serif;
11     margin: 2em;
12     font-size: small ; color: #000000 ; background-color: #ffffff ; }
13     .title { color: #990000; font-size: x-large ;
14     font-weight: bold; text-align: right;
15     font-family: helvetica, monaco, "MS Sans Serif", arial, sans-serif;
16     background-color: transparent; }
17     .filename { color: #666666; font-size: 18px; line-height: 28px;
18     font-weight: bold; text-align: right;
19     font-family: helvetica, arial, sans-serif;
20     background-color: transparent; }
21 schoenebeck 708 td.rfcbug { background-color: #000000 ; width: 30px ; height: 30px ;
22 senoner 542 text-align: justify; vertical-align: middle ; padding-top: 2px ; }
23     td.rfcbug span.RFC { color: #666666; font-weight: bold; text-decoration: none;
24     background-color: #000000 ;
25     font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
26     font-size: x-small ; }
27     td.rfcbug span.hotText { color: #ffffff; font-weight: normal; text-decoration: none;
28     text-align: center ;
29     font-family: charcoal, monaco, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
30     font-size: x-small ; background-color: #000000; }
31 schoenebeck 940 /* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */
32 senoner 542 div#counter{margin-top: 100px}
33    
34     a.info{
35     position:relative; /*this is the key*/
36     z-index:24;
37     text-decoration:none}
38    
39     a.info:hover{z-index:25; background-color:#990000 ; color: #ffffff ;}
40    
41     a.info span{display: none}
42    
43 schoenebeck 708 a.info:hover span.info{ /*the span will display just on :hover state*/
44 senoner 542 display:block;
45     position:absolute;
46     font-size: smaller ;
47     top:2em; left:2em; width:15em;
48     padding: 2px ;
49     border:1px solid #333333;
50     background-color:#eeeeee; color:#990000;
51     text-align: left ;}
52    
53     A { font-weight: bold; }
54     A:link { color: #990000; background-color: transparent ; }
55     A:visited { color: #333333; background-color: transparent ; }
56     A:active { color: #333333; background-color: transparent ; }
57    
58     p { margin-left: 2em; margin-right: 2em; }
59     p.copyright { font-size: x-small ; }
60     p.toc { font-size: small ; font-weight: bold ; margin-left: 3em ;}
61 schoenebeck 940 table.toc { margin: 0 0 0 3em; padding: 0; border: 0; vertical-align: text-top; }
62     td.toc { font-size: small; font-weight: bold; vertical-align: text-top; }
63 senoner 542
64     span.emph { font-style: italic; }
65     span.strong { font-weight: bold; }
66 schoenebeck 708 span.verb, span.vbare { font-family: "Courier New", Courier, monospace ; }
67 senoner 542
68 schoenebeck 708 span.vemph { font-style: italic; font-family: "Courier New", Courier, monospace ; }
69     span.vstrong { font-weight: bold; font-family: "Courier New", Courier, monospace ; }
70     span.vdeluxe { font-weight: bold; font-style: italic; font-family: "Courier New", Courier, monospace ; }
71    
72 senoner 542 ol.text { margin-left: 2em; margin-right: 2em; }
73     ul.text { margin-left: 2em; margin-right: 2em; }
74     li { margin-left: 3em; }
75    
76     pre { margin-left: 3em; color: #333333; background-color: transparent;
77     font-family: "Courier New", Courier, monospace ; font-size: small ;
78 schoenebeck 708 text-align: left;
79 senoner 542 }
80    
81     h3 { color: #333333; font-size: medium ;
82     font-family: helvetica, arial, sans-serif ;
83     background-color: transparent; }
84     h4 { font-size: small; font-family: helvetica, arial, sans-serif ; }
85    
86     table.bug { width: 30px ; height: 15px ; }
87     td.bug { color: #ffffff ; background-color: #990000 ;
88     text-align: center ; width: 30px ; height: 15px ;
89     }
90     td.bug A.link2 { color: #ffffff ; font-weight: bold;
91     text-decoration: none;
92     font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, sans-serif;
93     font-size: x-small ; background-color: transparent }
94    
95     td.header { color: #ffffff; font-size: x-small ;
96     font-family: arial, helvetica, sans-serif; vertical-align: top;
97     background-color: #666666 ; width: 33% ; }
98     td.author { font-weight: bold; margin-left: 4em; font-size: x-small ; }
99     td.author-text { font-size: x-small; }
100 schoenebeck 940 table.full { vertical-align: top ; border-collapse: collapse ;
101 senoner 542 border-style: solid solid solid solid ;
102     border-color: black black black black ;
103     font-size: small ; text-align: center ; }
104 schoenebeck 940 table.headers, table.none { vertical-align: top ; border-collapse: collapse ;
105     border-style: none;
106     font-size: small ; text-align: center ; }
107     table.full th { font-weight: bold ;
108     border-style: solid ;
109 senoner 542 border-color: black black black black ; }
110 schoenebeck 940 table.headers th { font-weight: bold ;
111     border-style: none none solid none;
112     border-color: black black black black ; }
113     table.none th { font-weight: bold ;
114     border-style: none; }
115     table.full td {
116 senoner 542 border-style: solid solid solid solid ;
117     border-color: #333333 #333333 #333333 #333333 ; }
118 schoenebeck 940 table.headers td, table.none td { border-style: none; }
119 senoner 542
120     hr { height: 1px }
121     -->
122     </style>
123     </head>
124     <body>
125     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
126     <table summary="layout" width="66%" border="0" cellpadding="0" cellspacing="0"><tr><td><table summary="layout" width="100%" border="0" cellpadding="2" cellspacing="1">
127     <tr><td class="header">LinuxSampler Developers</td><td class="header">C. Schoenebeck</td></tr>
128     <tr><td class="header">Internet-Draft</td><td class="header">Interessengemeinschaft Software</td></tr>
129 schoenebeck 945 <tr><td class="header">Expires: May 30, 2007</td><td class="header">Engineering e. V.</td></tr>
130     <tr><td class="header">&nbsp;</td><td class="header">November 26, 2006</td></tr>
131 senoner 542 </table></td></tr></table>
132     <div align="right"><span class="title"><br />LinuxSampler Control Protocol</span></div>
133 schoenebeck 945 <div align="right"><span class="title"><br />LSCP 1.2</span></div>
134 senoner 542
135     <h3>Status of this Memo</h3>
136     <p>
137     This document is an Internet-Draft and is
138 schoenebeck 708 in full conformance with all provisions of Section&nbsp;10 of RFC&nbsp;2026.</p>
139 senoner 542 <p>
140     Internet-Drafts are working documents of the Internet Engineering
141     Task Force (IETF), its areas, and its working groups.
142     Note that other groups may also distribute working documents as
143     Internet-Drafts.</p>
144     <p>
145     Internet-Drafts are draft documents valid for a maximum of six months
146     and may be updated, replaced, or obsoleted by other documents at any time.
147     It is inappropriate to use Internet-Drafts as reference material or to cite
148 schoenebeck 708 them other than as &ldquo;work in progress.&rdquo;</p>
149 senoner 542 <p>
150     The list of current Internet-Drafts can be accessed at
151     <a href='http://www.ietf.org/ietf/1id-abstracts.txt'>http://www.ietf.org/ietf/1id-abstracts.txt</a>.</p>
152     <p>
153     The list of Internet-Draft Shadow Directories can be accessed at
154     <a href='http://www.ietf.org/shadow.html'>http://www.ietf.org/shadow.html</a>.</p>
155     <p>
156 schoenebeck 945 This Internet-Draft will expire on May 30, 2007.</p>
157 senoner 542
158     <h3>Copyright Notice</h3>
159     <p>
160 schoenebeck 940 Copyright &copy; The Internet Society (2006). All Rights Reserved.</p>
161 senoner 542
162     <h3>Abstract</h3>
163    
164     <p>The LinuxSampler Control Protocol (LSCP) is an
165     application-level protocol primarily intended for local and
166 schoenebeck 575 remote controlling the LinuxSampler backend application, which is a
167     sophisticated server-like console application essentially playing
168     back audio samples and manipulating the samples in real time to
169     certain extent.
170 senoner 542 </p><a name="toc"></a><br /><hr />
171     <h3>Table of Contents</h3>
172     <p class="toc">
173     <a href="#anchor1">1.</a>&nbsp;
174     Requirements notation<br />
175 schoenebeck 575 <a href="#LSCP versioning">2.</a>&nbsp;
176     Versioning of this specification<br />
177     <a href="#anchor2">3.</a>&nbsp;
178 senoner 542 Introduction<br />
179 schoenebeck 575 <a href="#anchor3">4.</a>&nbsp;
180 senoner 542 Focus of this protocol<br />
181 schoenebeck 575 <a href="#anchor4">5.</a>&nbsp;
182 senoner 542 Communication Overview<br />
183 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor5">5.1.</a>&nbsp;
184 senoner 542 Request/response communication method<br />
185 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor6">5.1.1.</a>&nbsp;
186 senoner 542 Result format<br />
187 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor7">5.2.</a>&nbsp;
188 senoner 542 Subscribe/notify communication method<br />
189 schoenebeck 575 <a href="#control_commands">6.</a>&nbsp;
190 senoner 542 Description for control commands<br />
191 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor8">6.1.</a>&nbsp;
192 senoner 542 Ignored lines and comments<br />
193 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor9">6.2.</a>&nbsp;
194 senoner 542 Configuring audio drivers<br />
195 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_AUDIO_OUTPUT_DRIVERS">6.2.1.</a>&nbsp;
196 senoner 542 Getting amount of available audio output drivers<br />
197 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">6.2.2.</a>&nbsp;
198 senoner 542 Getting all available audio output drivers<br />
199 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DRIVER INFO">6.2.3.</a>&nbsp;
200 senoner 542 Getting information about a specific audio
201     output driver<br />
202 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO">6.2.4.</a>&nbsp;
203 senoner 542 Getting information about specific audio
204     output driver parameter<br />
205 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CREATE AUDIO_OUTPUT_DEVICE">6.2.5.</a>&nbsp;
206 senoner 542 Creating an audio output device<br />
207 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DESTROY AUDIO_OUTPUT_DEVICE">6.2.6.</a>&nbsp;
208 senoner 542 Destroying an audio output device<br />
209 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DEVICES">6.2.7.</a>&nbsp;
210 senoner 542 Getting all created audio output device count<br />
211 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AUDIO_OUTPUT_DEVICES">6.2.8.</a>&nbsp;
212 senoner 542 Getting all created audio output device list<br />
213 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DEVICE INFO">6.2.9.</a>&nbsp;
214 senoner 542 Getting current settings of an audio output device<br />
215 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET AUDIO_OUTPUT_DEVICE_PARAMETER">6.2.10.</a>&nbsp;
216 senoner 542 Changing settings of audio output devices<br />
217 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_CHANNEL INFO">6.2.11.</a>&nbsp;
218 senoner 542 Getting information about an audio channel<br />
219 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO">6.2.12.</a>&nbsp;
220 senoner 542 Getting information about specific audio channel parameter<br />
221 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET AUDIO_OUTPUT_CHANNEL_PARAMETER">6.2.13.</a>&nbsp;
222 senoner 542 Changing settings of audio output channels<br />
223 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor10">6.3.</a>&nbsp;
224 senoner 542 Configuring MIDI input drivers<br />
225 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_MIDI_INPUT_DRIVERS">6.3.1.</a>&nbsp;
226 senoner 542 Getting amount of available MIDI input drivers<br />
227 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_MIDI_INPUT_DRIVERS">6.3.2.</a>&nbsp;
228 senoner 542 Getting all available MIDI input drivers<br />
229 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DRIVER INFO">6.3.3.</a>&nbsp;
230 senoner 542 Getting information about a specific MIDI input driver<br />
231 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DRIVER_PARAMETER INFO">6.3.4.</a>&nbsp;
232 senoner 542 Getting information about specific MIDI input driver parameter<br />
233 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CREATE MIDI_INPUT_DEVICE">6.3.5.</a>&nbsp;
234 senoner 542 Creating a MIDI input device<br />
235 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DESTROY MIDI_INPUT_DEVICE">6.3.6.</a>&nbsp;
236 senoner 542 Destroying a MIDI input device<br />
237 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DEVICES">6.3.7.</a>&nbsp;
238 senoner 542 Getting all created MIDI input device count<br />
239 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST MIDI_INPUT_DEVICES">6.3.8.</a>&nbsp;
240 senoner 542 Getting all created MIDI input device list<br />
241 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DEVICE INFO">6.3.9.</a>&nbsp;
242 senoner 542 Getting current settings of a MIDI input device<br />
243 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET MIDI_INPUT_DEVICE_PARAMETER">6.3.10.</a>&nbsp;
244 senoner 542 Changing settings of MIDI input devices<br />
245 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_PORT INFO">6.3.11.</a>&nbsp;
246 senoner 542 Getting information about a MIDI port<br />
247 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_PORT_PARAMETER INFO">6.3.12.</a>&nbsp;
248 senoner 542 Getting information about specific MIDI port parameter<br />
249 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET MIDI_INPUT_PORT_PARAMETER">6.3.13.</a>&nbsp;
250 senoner 542 Changing settings of MIDI input ports<br />
251 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor11">6.4.</a>&nbsp;
252 senoner 542 Configuring sampler channels<br />
253 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LOAD INSTRUMENT">6.4.1.</a>&nbsp;
254 senoner 542 Loading an instrument<br />
255 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LOAD ENGINE">6.4.2.</a>&nbsp;
256 senoner 542 Loading a sampler engine<br />
257 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNELS">6.4.3.</a>&nbsp;
258 senoner 542 Getting all created sampler channel count<br />
259 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST CHANNELS">6.4.4.</a>&nbsp;
260 senoner 542 Getting all created sampler channel list<br />
261 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD CHANNEL">6.4.5.</a>&nbsp;
262 senoner 542 Adding a new sampler channel<br />
263 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE CHANNEL">6.4.6.</a>&nbsp;
264 senoner 542 Removing a sampler channel<br />
265 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_ENGINES">6.4.7.</a>&nbsp;
266 senoner 542 Getting amount of available engines<br />
267 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_ENGINES">6.4.8.</a>&nbsp;
268 senoner 542 Getting all available engines<br />
269 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET ENGINE INFO">6.4.9.</a>&nbsp;
270 senoner 542 Getting information about an engine<br />
271 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL INFO">6.4.10.</a>&nbsp;
272 senoner 542 Getting sampler channel information<br />
273 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL VOICE_COUNT">6.4.11.</a>&nbsp;
274 senoner 542 Current number of active voices<br />
275 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL STREAM_COUNT">6.4.12.</a>&nbsp;
276 senoner 542 Current number of active disk streams<br />
277 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL BUFFER_FILL">6.4.13.</a>&nbsp;
278 senoner 542 Current fill state of disk stream buffers<br />
279 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_DEVICE">6.4.14.</a>&nbsp;
280 senoner 542 Setting audio output device<br />
281 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_TYP">6.4.15.</a>&nbsp;
282 senoner 542 Setting audio output type<br />
283 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_CHANNEL">6.4.16.</a>&nbsp;
284 senoner 542 Setting audio output channel<br />
285 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_DEVICE">6.4.17.</a>&nbsp;
286 senoner 542 Setting MIDI input device<br />
287 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_TYPE">6.4.18.</a>&nbsp;
288 senoner 542 Setting MIDI input type<br />
289 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_PORT">6.4.19.</a>&nbsp;
290 senoner 542 Setting MIDI input port<br />
291 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_CHANNEL">6.4.20.</a>&nbsp;
292 senoner 542 Setting MIDI input channel<br />
293 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL VOLUME">6.4.21.</a>&nbsp;
294 senoner 542 Setting channel volume<br />
295 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MUTE">6.4.22.</a>&nbsp;
296 schoenebeck 708 Muting a sampler channel<br />
297 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL SOLO">6.4.23.</a>&nbsp;
298 schoenebeck 708 Soloing a sampler channel<br />
299 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#RESET CHANNEL">6.4.24.</a>&nbsp;
300 senoner 542 Resetting a sampler channel<br />
301 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor12">6.5.</a>&nbsp;
302 senoner 542 Controlling connection<br />
303 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE">6.5.1.</a>&nbsp;
304 senoner 542 Register front-end for receiving event messages<br />
305 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#UNSUBSCRIBE">6.5.2.</a>&nbsp;
306 senoner 542 Unregister front-end for not receiving event messages<br />
307 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET ECHO">6.5.3.</a>&nbsp;
308 senoner 542 Enable or disable echo of commands<br />
309 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#QUIT">6.5.4.</a>&nbsp;
310 senoner 542 Close client connection<br />
311 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor13">6.6.</a>&nbsp;
312 senoner 542 Global commands<br />
313 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET TOTAL_VOICE_COUNT">6.6.1.</a>&nbsp;
314     Current number of active voices<br />
315     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET TOTAL_VOICE_COUNT_MAX">6.6.2.</a>&nbsp;
316     Maximum amount of active voices<br />
317     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#RESET">6.6.3.</a>&nbsp;
318 senoner 542 Reset sampler<br />
319 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET SERVER INFO">6.6.4.</a>&nbsp;
320 schoenebeck 575 General sampler informations<br />
321 schoenebeck 945 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor14">6.7.</a>&nbsp;
322     MIDI Instrument Mapping<br />
323     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#MAP MIDI_INSTRUMENT">6.7.1.</a>&nbsp;
324     Create or replace a MIDI instrument map entry<br />
325     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENTS">6.7.2.</a>&nbsp;
326     Getting ammount of MIDI instrument map entries<br />
327     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST MIDI_INSTRUMENTS">6.7.3.</a>&nbsp;
328     Getting indeces of all MIDI instrument map entries<br />
329     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#UNMAP MIDI_INSTRUMENT">6.7.4.</a>&nbsp;
330     Remove an entry from the MIDI instrument map<br />
331     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENT INFO">6.7.5.</a>&nbsp;
332     Get current settings of MIDI instrument map entry<br />
333     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CLEAR MIDI_INSTRUMENTS">6.7.6.</a>&nbsp;
334     Clear MIDI instrument map<br />
335 schoenebeck 575 <a href="#command_syntax">7.</a>&nbsp;
336 senoner 542 Command Syntax<br />
337 schoenebeck 575 <a href="#events">8.</a>&nbsp;
338 senoner 542 Events<br />
339 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE CHANNEL">8.1.</a>&nbsp;
340 senoner 542 Number of sampler channels changed<br />
341 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE VOICE_COUNT">8.2.</a>&nbsp;
342 senoner 542 Number of active voices changed<br />
343 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE STREAM_COUNT">8.3.</a>&nbsp;
344 senoner 542 Number of active disk streams changed<br />
345 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE BUFFER_FILL">8.4.</a>&nbsp;
346 senoner 542 Disk stream buffer fill state changed<br />
347 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE INFO">8.5.</a>&nbsp;
348 senoner 542 Channel information changed<br />
349 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE TOTAL_VOICE_COUNT">8.6.</a>&nbsp;
350     Total number of active voices changed<br />
351     &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MISCELLANEOUS">8.7.</a>&nbsp;
352 senoner 542 Miscellaneous and debugging events<br />
353 schoenebeck 945 <a href="#anchor15">9.</a>&nbsp;
354 senoner 542 Security Considerations<br />
355 schoenebeck 945 <a href="#anchor16">10.</a>&nbsp;
356 senoner 542 Acknowledgments<br />
357 schoenebeck 575 <a href="#rfc.references1">11.</a>&nbsp;
358 senoner 542 References<br />
359     <a href="#rfc.authors">&#167;</a>&nbsp;
360     Author's Address<br />
361     <a href="#rfc.copyright">&#167;</a>&nbsp;
362     Intellectual Property and Copyright Statements<br />
363     </p>
364     <br clear="all" />
365    
366     <a name="anchor1"></a><br /><hr />
367     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
368     <a name="rfc.section.1"></a><h3>1.&nbsp;Requirements notation</h3>
369    
370     <p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
371     "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
372     and "OPTIONAL" in this document are to be interpreted as
373 schoenebeck 708 described in <a class="info" href="#RFC2119">[RFC2119]<span> (</span><span class="info">Bradner, S., &ldquo;Key words for use in RFCs to Indicate Requirement Levels,&rdquo; 1997.</span><span>)</span></a>.
374 senoner 542 </p>
375     <p>This protocol is always case-sensitive if not explicitly
376     claimed the opposite.
377     </p>
378     <p>In examples, "C:" and "S:" indicate lines sent by the client
379     (front-end) and server (LinuxSampler) respectively. Lines in
380     examples must be interpreted as every line being CRLF
381     terminated (carriage return character followed by line feed
382     character as defined in the ASCII standard), thus the following
383     example:
384     </p>
385 schoenebeck 708 <p>
386     </p>
387 senoner 542 <blockquote class="text">
388     <p>C: "some line"
389     </p>
390     <p>&nbsp;&nbsp;&nbsp;"another line"
391     </p>
392 schoenebeck 708 </blockquote><p>
393 schoenebeck 940
394 schoenebeck 708 </p>
395 senoner 542 <p>must actually be interpreted as client sending the following
396     message:
397     </p>
398 schoenebeck 708 <p>
399     </p>
400 senoner 542 <blockquote class="text">
401     <p>"some line&lt;CR&gt;&lt;LF&gt;another
402     line&lt;CR&gt;&lt;LF&gt;"
403     </p>
404 schoenebeck 708 </blockquote><p>
405 schoenebeck 940
406 schoenebeck 708 </p>
407 senoner 542 <p>where &lt;CR&gt; symbolizes the carriage return character and
408     &lt;LF&gt; the line feed character as defined in the ASCII
409     standard.
410     </p>
411     <p>Due to technical reasons, messages can arbitrary be
412     fragmented, means the following example:
413     </p>
414 schoenebeck 708 <p>
415     </p>
416 senoner 542 <blockquote class="text">
417     <p>S: "abcd"
418     </p>
419 schoenebeck 708 </blockquote><p>
420 schoenebeck 940
421 schoenebeck 708 </p>
422 senoner 542 <p>could also happen to be sent in three messages like in the
423     following sequence scenario:
424     </p>
425 schoenebeck 708 <p>
426     </p>
427 senoner 542 <ul class="text">
428     <li>server sending message "a"
429     </li>
430     <li>followed by a delay (pause) with
431     arbitrary duration
432     </li>
433     <li>followed by server sending message
434     "bcd&lt;CR&gt;"
435     </li>
436     <li>again followed by a delay (pause) with arbitrary
437     duration
438     </li>
439     <li>followed by server sending the message
440     "&lt;LF&gt;"
441     </li>
442 schoenebeck 708 </ul><p>
443 schoenebeck 940
444 schoenebeck 708 </p>
445 senoner 542 <p>where again &lt;CR&gt; and &lt;LF&gt; symbolize the carriage
446     return and line feed characters respectively.
447     </p>
448 schoenebeck 575 <a name="LSCP versioning"></a><br /><hr />
449     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
450     <a name="rfc.section.2"></a><h3>2.&nbsp;Versioning of this specification</h3>
451    
452     <p>LSCP will certainly be extended and enhanced by-and-by. Each official
453     release of the LSCP specification will be tagged with a unique version
454     tuple. The version tuple consists at least of a major and minor version
455     number like:
456 schoenebeck 940
457 schoenebeck 575 </p>
458 schoenebeck 708 <p>
459     </p>
460 schoenebeck 575 <blockquote class="text">
461     <p>"1.2"
462     </p>
463 schoenebeck 708 </blockquote><p>
464 schoenebeck 940
465 schoenebeck 708 </p>
466 schoenebeck 575 <p>
467     In this example the major version number would be "1" and the minor
468     version number would be "2". Note that the version tuple might also
469     have more than two elements. The major version number defines a
470     group of backward compatible versions. That means a frontend is
471     compatible to the connected sampler if and only if the LSCP versions
472     to which each of the two parties complies to, match both of the
473     following rules:
474 schoenebeck 940
475 schoenebeck 575 </p>
476     <p>Compatibility:
477     </p>
478 schoenebeck 708 <p>
479     </p>
480 schoenebeck 575 <ol class="text">
481     <li>The frontend's LSCP major version and the sampler's LSCP
482     major version are exactly equal.
483     </li>
484     <li>The frontend's LSCP minor version is less or equal than
485     the sampler's LSCP minor version.
486     </li>
487 schoenebeck 708 </ol><p>
488 schoenebeck 940
489 schoenebeck 708 </p>
490 schoenebeck 575 <p>
491     Compatibility can only be claimed if both rules are true.
492     The frontend can use the
493 schoenebeck 708 <a class="info" href="#GET SERVER INFO">"GET SERVER INFO"<span> (</span><span class="info">General sampler informations</span><span>)</span></a> command to
494 schoenebeck 575 get the version of the LSCP specification the sampler complies with.
495 schoenebeck 940
496 schoenebeck 575 </p>
497 senoner 542 <a name="anchor2"></a><br /><hr />
498     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
499 schoenebeck 575 <a name="rfc.section.3"></a><h3>3.&nbsp;Introduction</h3>
500 senoner 542
501     <p>LinuxSampler is a so called software sampler application
502     capable to playback audio samples from a computer's Random
503     Access Memory (RAM) as well as directly streaming it from disk.
504     LinuxSampler is designed to be modular. It provides several so
505     called "sampler engines" where each engine is specialized for a
506     certain purpose. LinuxSampler has virtual channels which will be
507     referred in this document as "sampler channels". The channels
508     are in such way virtual as they can be connected to an
509     arbitrary MIDI input method and arbitrary MIDI channel (e.g.
510     sampler channel 17 could be connected to an ALSA sequencer
511     device 64:0 and listening to MIDI channel 1 there). Each sampler
512 schoenebeck 575 channel will be associated with an instance of one of the available
513 senoner 542 sampler engines (e.g. GigEngine, DLSEngine). The audio output of
514     each sampler channel can be routed to an arbitrary audio output
515     method (ALSA / JACK) and an arbitrary audio output channel
516     there.
517     </p>
518     <a name="anchor3"></a><br /><hr />
519     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
520 schoenebeck 575 <a name="rfc.section.4"></a><h3>4.&nbsp;Focus of this protocol</h3>
521 senoner 542
522     <p>Main focus of this protocol is to provide a way to configure
523     a running LinuxSampler instance and to retrieve information
524     about it. The focus of this protocol is not to provide a way to
525     control synthesis parameters or even to trigger or release
526     notes. Or in other words; the focus are those functionalities
527     which are not covered by MIDI or which may at most be handled
528     via MIDI System Exclusive Messages.
529     </p>
530     <a name="anchor4"></a><br /><hr />
531     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
532 schoenebeck 575 <a name="rfc.section.5"></a><h3>5.&nbsp;Communication Overview</h3>
533 senoner 542
534     <p>There are two distinct methods of communication between a
535     running instance of LinuxSampler and one or more control
536     applications, so called "front-ends": a simple request/response
537     communication method used by the clients to give commands to the
538     server as well as to inquire about server's status and a
539     subscribe/notify communication method used by the client to
540     subscribe to and receive notifications of certain events as they
541     happen on the server. The latter needs more effort to be
542     implemented in the front-end application. The two communication
543     methods will be described next.
544     </p>
545 schoenebeck 940 <a name="anchor5"></a><br /><hr />
546     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
547     <a name="rfc.section.5.1"></a><h3>5.1.&nbsp;Request/response communication method</h3>
548 senoner 542
549 schoenebeck 575 <p>This simple communication method is based on
550 schoenebeck 940 <a class="info" href="#RFC793">TCP<span> (</span><span class="info">Defense Advanced Research Projects Agency, &ldquo;TRANSMISSION CONTROL PROTOCOL,&rdquo; 1981.</span><span>)</span></a> [RFC793]. The
551 senoner 542 front-end application establishes a TCP connection to the
552     LinuxSampler instance on a certain host system. Then the
553     front-end application will send certain ASCII based commands
554     as defined in this document (every command line must be CRLF
555     terminated - see "Conventions used in this document" at the
556     beginning of this document) and the LinuxSampler application
557     will response after a certain process time with an
558     appropriate ASCII based answer, also as defined in this
559     document. So this TCP communication is simply based on query
560     and answer paradigm. That way LinuxSampler is only able to
561     answer on queries from front-ends, but not able to
562     automatically send messages to the client if it's not asked
563     to. The fronted should not reconnect to LinuxSampler for
564     every single command, instead it should keep the connection
565     established and simply resend message(s) for subsequent
566     commands. To keep information in the front-end up-to-date
567     the front-end has to periodically send new requests to get
568     the current information from the LinuxSampler instance. This
569     is often referred to as "polling". While polling is simple
570     to implement and may be OK to use in some cases, there may
571     be disadvantages to polling such as network traffic overhead
572     and information being out of date.
573     It is possible for a client or several clients to open more
574     than one connection to the server at the same time. It is
575     also possible to send more than one request to the server
576     at the same time but if those requests are sent over the
577     same connection server MUST execute them sequentially. Upon
578     executing a request server will produce a result set and
579     send it to the client. Each and every request made by the
580     client MUST result in a result set being sent back to the
581     client. No other data other than a result set may be sent by
582     a server to a client. No result set may be sent to a client
583     without the client sending request to the server first. On
584     any particular connection, result sets MUST be sent in their
585     entirety without being interrupted by other result sets. If
586     several requests got queued up at the server they MUST be
587     processed in the order they were received and result sets
588     MUST be sent back in the same order.
589     </p>
590 schoenebeck 940 <a name="anchor6"></a><br /><hr />
591     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
592     <a name="rfc.section.5.1.1"></a><h3>5.1.1.&nbsp;Result format</h3>
593 senoner 542
594     <p>Result set could be one of the following types:
595     </p>
596 schoenebeck 708 <p>
597     </p>
598 senoner 542 <ol class="text">
599     <li>Normal
600     </li>
601     <li>Warning
602     </li>
603     <li>Error
604     </li>
605 schoenebeck 708 </ol><p>
606 schoenebeck 940
607 schoenebeck 708 </p>
608 senoner 542 <p>Warning and Error result sets MUST be single line and
609     have the following format:
610     </p>
611 schoenebeck 708 <p>
612     </p>
613 senoner 542 <ul class="text">
614     <li>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;"
615     </li>
616     <li>"ERR:&lt;error-code&gt;:&lt;error-message&gt;"
617     </li>
618 schoenebeck 708 </ul><p>
619 schoenebeck 940
620 schoenebeck 708 </p>
621 senoner 542 <p>Where &lt;warning-code&gt; and &lt;error-code&gt; are
622     numeric unique identifiers of the warning or error and
623     &lt;warning-message&gt; and &lt;error-message&gt; are
624     human readable descriptions of the warning or error
625     respectively.
626     </p>
627     <p>Examples:
628     </p>
629 schoenebeck 708 <p>
630     </p>
631 senoner 542 <blockquote class="text">
632     <p>C: "LOAD INSTRUMENT '/home/me/Boesendorfer24bit.gig" 0 0
633     </p>
634     <p>S: "WRN:32:This is a 24 bit patch which is not supported natively yet."
635     </p>
636 schoenebeck 708 </blockquote><p>
637 schoenebeck 940
638 schoenebeck 708 </p>
639     <p>
640     </p>
641 senoner 542 <blockquote class="text">
642     <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA EAR"
643     </p>
644     <p>S: "ERR:3456:Audio output driver 'ALSA' does not have a parameter 'EAR'."
645     </p>
646 schoenebeck 708 </blockquote><p>
647 schoenebeck 940
648 schoenebeck 708 </p>
649     <p>
650     </p>
651 senoner 542 <blockquote class="text">
652     <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 123456"
653     </p>
654     <p>S: "ERR:9:There is no audio output device with index 123456."
655     </p>
656 schoenebeck 708 </blockquote><p>
657 schoenebeck 940
658 schoenebeck 708 </p>
659 senoner 542 <p>Normal result sets could be:
660     </p>
661 schoenebeck 708 <p>
662     </p>
663 senoner 542 <ol class="text">
664     <li>Empty
665     </li>
666     <li>Single line
667     </li>
668     <li>Multi-line
669     </li>
670 schoenebeck 708 </ol><p>
671 schoenebeck 940
672 schoenebeck 708 </p>
673 senoner 542 <p> Empty result set is issued when the server only
674     needed to acknowledge the fact that the request was
675     received and it was processed successfully and no
676     additional information is available. This result set has
677     the following format:
678     </p>
679 schoenebeck 708 <p>
680     </p>
681 senoner 542 <blockquote class="text">
682     <p>"OK"
683     </p>
684 schoenebeck 708 </blockquote><p>
685 schoenebeck 940
686 schoenebeck 708 </p>
687 senoner 542 <p>Example:
688     </p>
689 schoenebeck 708 <p>
690     </p>
691 senoner 542 <blockquote class="text">
692     <p>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 CHANNELS=4"
693     </p>
694     <p>S: "OK"
695     </p>
696 schoenebeck 708 </blockquote><p>
697 schoenebeck 940
698 schoenebeck 708 </p>
699 senoner 542 <p>Single line result sets are command specific. One
700     example of a single line result set is an empty line.
701     Multi-line result sets are command specific and may
702     include one or more lines of information. They MUST
703     always end with the following line:
704     </p>
705 schoenebeck 708 <p>
706     </p>
707 senoner 542 <blockquote class="text">
708     <p>"."
709     </p>
710 schoenebeck 708 </blockquote><p>
711 schoenebeck 940
712 schoenebeck 708 </p>
713 senoner 542 <p>Example:
714     </p>
715 schoenebeck 708 <p>
716     </p>
717 senoner 542 <blockquote class="text">
718     <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
719     </p>
720     <p>S: "DRIVER: ALSA"
721     </p>
722     <p>&nbsp;&nbsp;&nbsp;"CHANNELS: 2"
723     </p>
724     <p>&nbsp;&nbsp;&nbsp;"SAMPLERATE: 44100"
725     </p>
726     <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
727     </p>
728     <p>&nbsp;&nbsp;&nbsp;"FRAGMENTS: 2"
729     </p>
730     <p>&nbsp;&nbsp;&nbsp;"FRAGMENTSIZE: 128"
731     </p>
732     <p>&nbsp;&nbsp;&nbsp;"CARD: '0,0'"
733     </p>
734     <p>&nbsp;&nbsp;&nbsp;"."
735     </p>
736 schoenebeck 708 </blockquote><p>
737 schoenebeck 940
738 schoenebeck 708 </p>
739 senoner 542 <p>In addition to above mentioned formats, warnings and
740     empty result sets MAY be indexed. In this case, they
741     have the following formats respectively:
742     </p>
743 schoenebeck 708 <p>
744     </p>
745 senoner 542 <ul class="text">
746     <li>"WRN[&lt;index&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;"
747     </li>
748     <li>"OK[&lt;index&gt;]"
749     </li>
750 schoenebeck 708 </ul><p>
751 schoenebeck 940
752 schoenebeck 708 </p>
753 senoner 542 <p>where &lt;index&gt; is command specific and is used
754     to indicate channel number that the result set was
755     related to or other integer value.
756     </p>
757     <p>Each line of the result set MUST end with
758     &lt;CRLF&gt;.
759     </p>
760     <p>Examples:
761     </p>
762 schoenebeck 708 <p>
763     </p>
764 senoner 542 <blockquote class="text">
765     <p>C: "ADD CHANNEL"
766     </p>
767     <p>S: "OK[12]"
768     </p>
769 schoenebeck 708 </blockquote><p>
770 schoenebeck 940
771 schoenebeck 708 </p>
772     <p>
773     </p>
774 senoner 542 <blockquote class="text">
775     <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"
776     </p>
777     <p>S: "WRN[0]:32:Sample rate not supported, using 44100 instead."
778     </p>
779 schoenebeck 708 </blockquote><p>
780 schoenebeck 940
781 schoenebeck 708 </p>
782 schoenebeck 940 <a name="anchor7"></a><br /><hr />
783     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
784     <a name="rfc.section.5.2"></a><h3>5.2.&nbsp;Subscribe/notify communication method</h3>
785 senoner 542
786     <p>This more sophisticated communication method is actually
787     only an extension of the simple request/response
788     communication method. The front-end still uses a TCP
789     connection and sends the same commands on the TCP
790     connection. Two extra commands are SUBSCRIBE and UNSUBSCRIBE
791     commands that allow a client to tell the server that it is
792     interested in receiving notifications about certain events
793     as they happen on the server. The SUBSCRIBE command has the
794     following syntax:
795     </p>
796 schoenebeck 708 <p>
797     </p>
798 senoner 542 <blockquote class="text">
799     <p>SUBSCRIBE &lt;event-id&gt;
800     </p>
801 schoenebeck 708 </blockquote><p>
802 schoenebeck 940
803 schoenebeck 708 </p>
804 senoner 542 <p>where &lt;event-id&gt; will be replaced by the respective
805     event that client wants to subscribe to. Upon receiving such
806     request, server SHOULD respond with OK and start sending
807     EVENT notifications when a given even has occurred to the
808     front-end when an event has occurred. It MAY be possible
809     certain events may be sent before OK response during real
810     time nature of their generation. Event messages have the
811     following format:
812     </p>
813 schoenebeck 708 <p>
814     </p>
815 senoner 542 <blockquote class="text">
816     <p>NOTIFY:&lt;event-id&gt;:&lt;custom-event-data&gt;
817     </p>
818 schoenebeck 708 </blockquote><p>
819 schoenebeck 940
820 schoenebeck 708 </p>
821 senoner 542 <p>where &lt;event-id&gt; uniquely identifies the event that
822     has occurred and &lt;custom-event-data&gt; is event
823     specific.
824     </p>
825     <p>Several rules must be followed by the server when
826     generating events:
827     </p>
828 schoenebeck 708 <p>
829     </p>
830 senoner 542 <ol class="text">
831     <li>Events MUST NOT be sent to any client who has not
832     issued an appropriate SUBSCRIBE command.
833     </li>
834     <li>Events MUST only be sent using the same
835     connection that was used to subscribe to them.
836     </li>
837     <li>When response is being sent to the client, event
838     MUST be inserted in the stream before or after the
839     response, but NOT in the middle. Same is true about
840     the response. It should never be inserted in the
841     middle of the event message as well as any other
842     response.
843     </li>
844 schoenebeck 708 </ol><p>
845 schoenebeck 940
846 schoenebeck 708 </p>
847 senoner 542 <p>If the client is not interested in a particular event
848     anymore it MAY issue UNSUBSCRIBE command using the following
849     syntax:
850     </p>
851 schoenebeck 708 <p>
852     </p>
853 senoner 542 <blockquote class="text">
854     <p>UNSUBSCRIBE &lt;event-id&gt;
855     </p>
856 schoenebeck 708 </blockquote><p>
857 schoenebeck 940
858 schoenebeck 708 </p>
859 senoner 542 <p>where &lt;event-id&gt; will be replace by the respective
860     event that client is no longer interested in receiving. For
861 schoenebeck 708 a list of supported events see <a class="info" href="#events">Section&nbsp;8<span> (</span><span class="info">Events</span><span>)</span></a>.
862 senoner 542 </p>
863     <p>Example: the fill states of disk stream buffers have
864     changed on sampler channel 4 and the LinuxSampler instance
865     will react by sending the following message to all clients
866     who subscribed to this event:
867     </p>
868 schoenebeck 708 <p>
869     </p>
870 senoner 542 <blockquote class="text">
871     <p>NOTIFY:CHANNEL_BUFFER_FILL:4 [35]62%,[33]80%,[37]98%
872     </p>
873 schoenebeck 708 </blockquote><p>
874 schoenebeck 940
875 schoenebeck 708 </p>
876 senoner 542 <p>Which means there are currently three active streams on
877     sampler channel 4, where the stream with ID "35" is filled
878     by 62%, stream with ID 33 is filled by 80% and stream with
879     ID 37 is filled by 98%.
880     </p>
881     <p>Clients may choose to open more than one connection to
882     the server and use some connections to receive notifications
883     while using other connections to issue commands to the
884     back-end. This is entirely legal and up to the
885     implementation. This does not change the protocol in any way
886     and no special restrictions exist on the server to allow or
887     disallow this or to track what connections belong to what
888     front-ends. Server will listen on a single port, accept
889     multiple connections and support protocol described in this
890     specification in it's entirety on this single port on each
891     connection that it accepted.
892     </p>
893     <p>Due to the fact that TCP is used for this communication,
894     dead peers will be detected automatically by the OS TCP
895     stack. While it may take a while to detect dead peers if no
896     traffic is being sent from server to client (TCP keep-alive
897     timer is set to 2 hours on many OSes) it will not be an
898     issue here as when notifications are sent by the server,
899     dead client will be detected quickly.
900     </p>
901     <p>When connection is closed for any reason server MUST
902     forget all subscriptions that were made on this connection.
903     If client reconnects it MUST resubscribe to all events that
904     it wants to receive.
905     </p>
906 schoenebeck 575 <a name="control_commands"></a><br /><hr />
907 senoner 542 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
908 schoenebeck 575 <a name="rfc.section.6"></a><h3>6.&nbsp;Description for control commands</h3>
909 senoner 542
910     <p>This chapter will describe the available control commands
911     that can be sent on the TCP connection in detail. Some certain
912 schoenebeck 708 commands (e.g. <a class="info" href="#GET CHANNEL INFO">"GET CHANNEL INFO"<span> (</span><span class="info">Getting sampler channel information</span><span>)</span></a>
913     or <a class="info" href="#GET ENGINE INFO">"GET ENGINE INFO"<span> (</span><span class="info">Getting information about an engine</span><span>)</span></a>) lead to
914 senoner 542 multiple-line responses. In this case LinuxSampler signals the
915     end of the response by a "." (single dot) line.
916     </p>
917 schoenebeck 940 <a name="anchor8"></a><br /><hr />
918     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
919     <a name="rfc.section.6.1"></a><h3>6.1.&nbsp;Ignored lines and comments</h3>
920 senoner 542
921     <p>White lines, that is lines which only contain space and
922     tabulator characters, and lines that start with a "#"
923     character are ignored, thus it's possible for example to
924     group commands and to place comments in a LSCP script
925     file.
926     </p>
927 schoenebeck 940 <a name="anchor9"></a><br /><hr />
928     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
929     <a name="rfc.section.6.2"></a><h3>6.2.&nbsp;Configuring audio drivers</h3>
930 senoner 542
931     <p>Instances of drivers in LinuxSampler are called devices.
932     You can use multiple audio devices simultaneously, e.g. to
933     output the sound of one sampler channel using the ALSA audio
934     output driver, and on another sampler channel you might want
935     to use the JACK audio output driver. For particular audio
936     output systems it's also possible to create several devices
937     of the same audio output driver, e.g. two separate ALSA
938     audio output devices for using two different sound cards at
939     the same time. This chapter describes all commands to
940     configure LinuxSampler's audio output devices and their
941     parameters.
942     </p>
943     <p>Instead of defining commands and parameters for each
944     driver individually, all possible parameters, their meanings
945     and possible values have to be obtained at runtime. This
946     makes the protocol a bit abstract, but has the advantage,
947     that front-ends can be written independently of what drivers
948     are currently implemented and what parameters these drivers
949     are actually offering. This means front-ends can even handle
950     drivers which are implemented somewhere in future without
951     modifying the front-end at all.
952     </p>
953     <p>Note: examples in this chapter showing particular
954     parameters of drivers are not meant as specification of the
955     drivers' parameters. Driver implementations in LinuxSampler
956     might have complete different parameter names and meanings
957     than shown in these examples or might change in future, so
958     these examples are only meant for showing how to retrieve
959     what parameters drivers are offering, how to retrieve their
960     possible values, etc.
961     </p>
962 schoenebeck 940 <a name="GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"></a><br /><hr />
963     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
964     <a name="rfc.section.6.2.1"></a><h3>6.2.1.&nbsp;Getting amount of available audio output drivers</h3>
965 senoner 542
966     <p>Use the following command to get the number of
967     audio output drivers currently available for the
968     LinuxSampler instance:
969     </p>
970 schoenebeck 708 <p>
971     </p>
972 senoner 542 <blockquote class="text">
973     <p>GET AVAILABLE_AUDIO_OUTPUT_DRIVERS
974     </p>
975 schoenebeck 708 </blockquote><p>
976 schoenebeck 940
977 schoenebeck 708 </p>
978 senoner 542 <p>Possible Answers:
979     </p>
980 schoenebeck 708 <p>
981     </p>
982 senoner 542 <blockquote class="text">
983     <p>LinuxSampler will answer by sending the
984     number of audio output drivers.
985     </p>
986 schoenebeck 708 </blockquote><p>
987 schoenebeck 940
988 schoenebeck 708 </p>
989 senoner 542 <p>Example:
990     </p>
991 schoenebeck 708 <p>
992     </p>
993 senoner 542 <blockquote class="text">
994     <p>C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
995     </p>
996     <p>S: "2"
997     </p>
998 schoenebeck 708 </blockquote><p>
999 schoenebeck 940
1000 schoenebeck 708 </p>
1001 schoenebeck 940 <a name="LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"></a><br /><hr />
1002     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
1003     <a name="rfc.section.6.2.2"></a><h3>6.2.2.&nbsp;Getting all available audio output drivers</h3>
1004 senoner 542
1005     <p>Use the following command to list all audio output
1006     drivers currently available for the LinuxSampler
1007     instance:
1008     </p>
1009 schoenebeck 708 <p>
1010     </p>
1011 senoner 542 <blockquote class="text">
1012     <p>LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS
1013     </p>
1014 schoenebeck 708 </blockquote><p>
1015 schoenebeck 940
1016 schoenebeck 708 </p>
1017 senoner 542 <p>Possible Answers:
1018     </p>
1019 schoenebeck 708 <p>
1020     </p>
1021 senoner 542 <blockquote class="text">
1022     <p>LinuxSampler will answer by sending comma
1023     separated character strings, each symbolizing an
1024     audio output driver.
1025     </p>
1026 schoenebeck 708 </blockquote><p>
1027 schoenebeck 940
1028 schoenebeck 708 </p>
1029 senoner 542 <p>Example:
1030     </p>
1031 schoenebeck 708 <p>
1032     </p>
1033 senoner 542 <blockquote class="text">
1034     <p>C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"
1035     </p>
1036     <p>S: "ALSA,JACK"
1037     </p>
1038 schoenebeck 708 </blockquote><p>
1039 schoenebeck 940
1040 schoenebeck 708 </p>
1041 schoenebeck 940 <a name="GET AUDIO_OUTPUT_DRIVER INFO"></a><br /><hr />
1042     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
1043     <a name="rfc.section.6.2.3"></a><h3>6.2.3.&nbsp;Getting information about a specific audio
1044     output driver</h3>
1045 senoner 542
1046     <p>Use the following command to get detailed information
1047     about a specific audio output driver:
1048     </p>
1049 schoenebeck 708 <p>
1050     </p>
1051 senoner 542 <blockquote class="text">
1052     <p>GET AUDIO_OUTPUT_DRIVER INFO
1053     &lt;audio-output-driver&gt;
1054     </p>
1055 schoenebeck 708 </blockquote><p>
1056 schoenebeck 940
1057 schoenebeck 708 </p>
1058 senoner 542 <p>Where &lt;audio-output-driver&gt; is the name of the
1059     audio output driver, returned by the
1060 schoenebeck 708 <a class="info" href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"<span> (</span><span class="info">Getting all available audio output drivers</span><span>)</span></a> command.
1061 senoner 542 </p>
1062     <p>Possible Answers:
1063     </p>
1064 schoenebeck 708 <p>
1065     </p>
1066 senoner 542 <blockquote class="text">
1067     <p>LinuxSampler will answer by sending a
1068     &lt;CRLF&gt; separated list. Each answer line
1069     begins with the information category name
1070     followed by a colon and then a space character
1071     &lt;SP&gt; and finally the info character string
1072     to that info category. At the moment the
1073     following information categories are
1074     defined:
1075     </p>
1076 schoenebeck 708 <p>
1077     </p>
1078 senoner 542 <blockquote class="text">
1079     <p>DESCRIPTION -
1080     </p>
1081     <blockquote class="text">
1082     <p> character string describing the
1083     audio output driver
1084     </p>
1085 schoenebeck 940 </blockquote>
1086    
1087 senoner 542
1088     <p>VERSION -
1089     </p>
1090     <blockquote class="text">
1091     <p>character string reflecting the
1092     driver's version
1093     </p>
1094 schoenebeck 940 </blockquote>
1095    
1096 senoner 542
1097     <p>PARAMETERS -
1098     </p>
1099     <blockquote class="text">
1100     <p>comma separated list of all
1101     parameters available for the given
1102     audio output driver, at least
1103     parameters 'channels', 'samplerate'
1104     and 'active' are offered by all audio
1105     output drivers
1106     </p>
1107 schoenebeck 940 </blockquote>
1108    
1109 senoner 542
1110 schoenebeck 940 </blockquote>
1111    
1112 senoner 542
1113     <p>The mentioned fields above don't have to be
1114     in particular order.
1115     </p>
1116 schoenebeck 708 </blockquote><p>
1117 schoenebeck 940
1118 schoenebeck 708 </p>
1119 senoner 542 <p>Example:
1120     </p>
1121 schoenebeck 708 <p>
1122     </p>
1123 senoner 542 <blockquote class="text">
1124     <p>C: "GET AUDIO_OUTPUT_DRIVER INFO ALSA"
1125     </p>
1126     <p>S: "DESCRIPTION: Advanced Linux Sound
1127     Architecture"
1128     </p>
1129     <p>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"
1130     </p>
1131     <p>&nbsp;&nbsp;&nbsp;"PARAMETERS:
1132     DRIVER,CHANNELS,SAMPLERATE,ACTIVE,FRAGMENTS,
1133     FRAGMENTSIZE,CARD"
1134     </p>
1135     <p>&nbsp;&nbsp;&nbsp;"."
1136     </p>
1137 schoenebeck 708 </blockquote><p>
1138 schoenebeck 940
1139 schoenebeck 708 </p>
1140 schoenebeck 940 <a name="GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO"></a><br /><hr />
1141     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
1142     <a name="rfc.section.6.2.4"></a><h3>6.2.4.&nbsp;Getting information about specific audio
1143     output driver parameter</h3>
1144 senoner 542
1145     <p>Use the following command to get detailed information
1146     about a specific audio output driver parameter:
1147     </p>
1148 schoenebeck 708 <p>
1149     </p>
1150 senoner 542 <blockquote class="text">
1151     <p>GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO &lt;audio&gt; &lt;prm&gt; [&lt;deplist&gt;]
1152     </p>
1153 schoenebeck 708 </blockquote><p>
1154 schoenebeck 940
1155 schoenebeck 708 </p>
1156 senoner 542 <p>Where &lt;audio&gt; is the name of the audio output
1157 schoenebeck 708 driver as returned by the <a class="info" href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"<span> (</span><span class="info">Getting all available audio output drivers</span><span>)</span></a> command,
1158 senoner 542 &lt;prm&gt; a specific parameter name for which information should be
1159     obtained (as returned by the
1160 schoenebeck 708 <a class="info" href="#GET AUDIO_OUTPUT_DRIVER INFO">"GET AUDIO_OUTPUT_DRIVER INFO"<span> (</span><span class="info">Getting information about a specific audio output driver</span><span>)</span></a> command) and
1161 senoner 542 &lt;deplist&gt; is an optional list of parameters on which the sought
1162     parameter &lt;prm&gt; depends on, &lt;deplist&gt; is a list of key-value
1163     pairs in form of "key1=val1 key2=val2 ...", where character string values
1164     are encapsulated into apostrophes ('). Arguments given with &lt;deplist&gt;
1165     which are not dependency parameters of &lt;prm&gt; will be ignored, means
1166     the front-end application can simply put all parameters into &lt;deplist&gt;
1167     with the values already selected by the user.
1168     </p>
1169     <p>Possible Answers:
1170     </p>
1171 schoenebeck 708 <p>
1172     </p>
1173 senoner 542 <blockquote class="text">
1174     <p>LinuxSampler will answer by sending a
1175     &lt;CRLF&gt; separated list.
1176     Each answer line begins with the information category name
1177     followed by a colon and then a space character &lt;SP&gt; and
1178     finally
1179     the info character string to that info category. There are
1180     information which is always returned, independently of the
1181     given driver parameter and there are optional information
1182     which is only shown dependently to given driver parameter. At
1183     the moment the following information categories are defined:
1184     </p>
1185 schoenebeck 708 </blockquote><p>
1186 schoenebeck 940
1187 schoenebeck 708 </p>
1188     <p>
1189     </p>
1190 senoner 542 <blockquote class="text">
1191     <p>TYPE -
1192     </p>
1193     <blockquote class="text">
1194     <p>either "BOOL" for boolean value(s) or
1195     "INT" for integer
1196     value(s) or "FLOAT" for dotted number(s) or "STRING" for
1197     character string(s)
1198     (always returned, no matter which driver parameter)
1199     </p>
1200 schoenebeck 940 </blockquote>
1201    
1202 senoner 542
1203     <p>DESCRIPTION -
1204     </p>
1205     <blockquote class="text">
1206     <p>arbitrary text describing the purpose of the parameter
1207     (always returned, no matter which driver parameter)
1208     </p>
1209 schoenebeck 940 </blockquote>
1210    
1211 senoner 542
1212     <p>MANDATORY -
1213     </p>
1214     <blockquote class="text">
1215     <p>either true or false, defines if this parameter must be
1216     given when the device is to be created with the
1217 schoenebeck 708 <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">'CREATE AUDIO_OUTPUT_DEVICE'<span> (</span><span class="info">Creating an audio output device</span><span>)</span></a>
1218 senoner 542 command (always returned, no matter which driver parameter)
1219     </p>
1220 schoenebeck 940 </blockquote>
1221    
1222 senoner 542
1223     <p>FIX -
1224     </p>
1225     <blockquote class="text">
1226     <p>either true or false, if false then this parameter can
1227     be changed at any time, once the device is created by
1228 schoenebeck 708 the <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">'CREATE AUDIO_OUTPUT_DEVICE'<span> (</span><span class="info">Creating an audio output device</span><span>)</span></a>
1229 senoner 542 command (always returned, no matter which driver parameter)
1230     </p>
1231 schoenebeck 940 </blockquote>
1232    
1233 senoner 542
1234     <p>MULTIPLICITY -
1235     </p>
1236     <blockquote class="text">
1237     <p>either true or false, defines if this parameter allows
1238     only one value or a list of values, where true means
1239     multiple values and false only a single value allowed
1240     (always returned, no matter which driver parameter)
1241     </p>
1242 schoenebeck 940 </blockquote>
1243    
1244 senoner 542
1245     <p>DEPENDS -
1246     </p>
1247     <blockquote class="text">
1248 schoenebeck 561 <p>comma separated list of parameters this parameter depends
1249 senoner 542 on, means the values for fields 'DEFAULT', 'RANGE_MIN',
1250     'RANGE_MAX' and 'POSSIBILITIES' might depend on these
1251     listed parameters, for example assuming that an audio
1252     driver (like the ALSA driver) offers parameters 'card'
1253     and 'samplerate' then parameter 'samplerate' would
1254     depend on 'card' because the possible values for
1255     'samplerate' depends on the sound card which can be
1256     chosen by the 'card' parameter
1257     (optionally returned, dependent to driver parameter)
1258     </p>
1259 schoenebeck 940 </blockquote>
1260    
1261 senoner 542
1262     <p>DEFAULT -
1263     </p>
1264     <blockquote class="text">
1265     <p>reflects the default value for this parameter which is
1266     used when the device is created and not explicitly
1267 schoenebeck 708 given with the <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">'CREATE AUDIO_OUTPUT_DEVICE'<span> (</span><span class="info">Creating an audio output device</span><span>)</span></a> command,
1268 senoner 542 in case of MULTIPLCITY=true, this is a comma separated
1269     list, that's why character strings are encapsulated into
1270     apostrophes (')
1271     (optionally returned, dependent to driver parameter)
1272     </p>
1273 schoenebeck 940 </blockquote>
1274    
1275 senoner 542
1276     <p>RANGE_MIN -
1277     </p>
1278     <blockquote class="text">
1279     <p>defines lower limit of the allowed value range for this
1280     parameter, can be an integer value as well as a dotted
1281     number, this parameter is often used in conjunction
1282     with RANGE_MAX, but may also appear without
1283     (optionally returned, dependent to driver parameter)
1284     </p>
1285 schoenebeck 940 </blockquote>
1286    
1287 senoner 542
1288     <p>RANGE_MAX -
1289     </p>
1290     <blockquote class="text">
1291     <p>defines upper limit of the allowed value range for this
1292     parameter, can be an integer value as well as a dotted
1293     number, this parameter is often used in conjunction with
1294     RANGE_MIN, but may also appear without
1295     (optionally returned, dependent to driver parameter)
1296     </p>
1297 schoenebeck 940 </blockquote>
1298    
1299 senoner 542
1300     <p>POSSIBILITIES -
1301     </p>
1302     <blockquote class="text">
1303     <p>comma separated list of possible values for this
1304     parameter, character strings are encapsulated into
1305     apostrophes
1306     (optionally returned, dependent to driver parameter)
1307     </p>
1308 schoenebeck 940 </blockquote>
1309    
1310 senoner 542
1311 schoenebeck 708 </blockquote><p>
1312 schoenebeck 940
1313 schoenebeck 708 </p>
1314 senoner 542 <p>The mentioned fields above don't have to be in particular order.
1315     </p>
1316     <p>Examples:
1317     </p>
1318 schoenebeck 708 <p>
1319     </p>
1320 senoner 542 <blockquote class="text">
1321     <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA CARD"
1322     </p>
1323     <p>S: "DESCRIPTION: sound card to be used"
1324     </p>
1325     <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
1326     </p>
1327     <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1328     </p>
1329     <p>&nbsp;&nbsp;&nbsp;"FIX: true"
1330     </p>
1331     <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1332     </p>
1333     <p>&nbsp;&nbsp;&nbsp;"DEFAULT: '0,0'"
1334     </p>
1335     <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: '0,0','1,0','2,0'"
1336     </p>
1337     <p>&nbsp;&nbsp;&nbsp;"."
1338     </p>
1339 schoenebeck 708 </blockquote><p>
1340 schoenebeck 940
1341 schoenebeck 708 </p>
1342     <p>
1343     </p>
1344 senoner 542 <blockquote class="text">
1345     <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE"
1346     </p>
1347     <p>S: "DESCRIPTION: output sample rate in Hz"
1348     </p>
1349     <p>&nbsp;&nbsp;&nbsp;"TYPE: INT"
1350     </p>
1351     <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1352     </p>
1353     <p>&nbsp;&nbsp;&nbsp;"FIX: false"
1354     </p>
1355     <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1356     </p>
1357     <p>&nbsp;&nbsp;&nbsp;"DEPENDS: card"
1358     </p>
1359     <p>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"
1360     </p>
1361     <p>&nbsp;&nbsp;&nbsp;"."
1362     </p>
1363 schoenebeck 708 </blockquote><p>
1364 schoenebeck 940
1365 schoenebeck 708 </p>
1366     <p>
1367     </p>
1368 senoner 542 <blockquote class="text">
1369     <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE CARD='0,0'"
1370     </p>
1371     <p>S: "DESCRIPTION: output sample rate in Hz"
1372     </p>
1373     <p>&nbsp;&nbsp;&nbsp;"TYPE: INT"
1374     </p>
1375     <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1376     </p>
1377     <p>&nbsp;&nbsp;&nbsp;"FIX: false"
1378     </p>
1379     <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1380     </p>
1381     <p>&nbsp;&nbsp;&nbsp;"DEPENDS: card"
1382     </p>
1383     <p>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"
1384     </p>
1385     <p>&nbsp;&nbsp;&nbsp;"RANGE_MIN: 22050"
1386     </p>
1387     <p>&nbsp;&nbsp;&nbsp;"RANGE_MAX: 96000"
1388     </p>
1389     <p>&nbsp;&nbsp;&nbsp;"."
1390     </p>
1391 schoenebeck 708 </blockquote><p>
1392 schoenebeck 940
1393 schoenebeck 708 </p>
1394 schoenebeck 940 <a name="CREATE AUDIO_OUTPUT_DEVICE"></a><br /><hr />
1395     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
1396     <a name="rfc.section.6.2.5"></a><h3>6.2.5.&nbsp;Creating an audio output device</h3>
1397 senoner 542
1398     <p>Use the following command to create a new audio output device for the desired audio output system:
1399     </p>
1400 schoenebeck 708 <p>
1401     </p>
1402 senoner 542 <blockquote class="text">
1403     <p>CREATE AUDIO_OUTPUT_DEVICE &lt;audio-output-driver&gt; [&lt;param-list&gt;]
1404     </p>
1405 schoenebeck 708 </blockquote><p>
1406 schoenebeck 940
1407 schoenebeck 708 </p>
1408 senoner 542 <p>Where &lt;audio-output-driver&gt; should be replaced by the desired audio
1409 schoenebeck 575 output system as returned by the
1410 schoenebeck 708 <a class="info" href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"<span> (</span><span class="info">Getting all available audio output drivers</span><span>)</span></a>
1411 schoenebeck 575 command and &lt;param-list&gt; by an optional list of driver
1412 senoner 542 specific parameters in form of "key1=val1 key2=val2 ...", where
1413     character string values should be encapsulated into apostrophes (').
1414     Note that there might be drivers which require parameter(s) to be
1415     given with this command. Use the previously described commands in
1416     this chapter to get this information.
1417     </p>
1418     <p>Possible Answers:
1419     </p>
1420 schoenebeck 708 <p>
1421     </p>
1422 senoner 542 <blockquote class="text">
1423     <p>"OK[&lt;device-id&gt;]" -
1424     </p>
1425     <blockquote class="text">
1426     <p>in case the device was successfully created, where
1427     &lt;device-id&gt; is the numerical ID of the new device
1428     </p>
1429 schoenebeck 940 </blockquote>
1430    
1431 senoner 542
1432     <p>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1433     </p>
1434     <blockquote class="text">
1435     <p>in case the device was created successfully, where
1436     &lt;device-id&gt; is the numerical ID of the new device, but there
1437     are noteworthy issue(s) related (e.g. sound card doesn't
1438     support given hardware parameters and the driver is using
1439     fall-back values), providing an appropriate warning code and
1440     warning message
1441     </p>
1442 schoenebeck 940 </blockquote>
1443    
1444 senoner 542
1445     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1446     </p>
1447     <blockquote class="text">
1448     <p>in case it failed, providing an appropriate error code and error message
1449     </p>
1450 schoenebeck 940 </blockquote>
1451    
1452 senoner 542
1453 schoenebeck 708 </blockquote><p>
1454 schoenebeck 940
1455 schoenebeck 708 </p>
1456 senoner 542 <p>Examples:
1457     </p>
1458 schoenebeck 708 <p>
1459     </p>
1460 senoner 542 <blockquote class="text">
1461     <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA"
1462     </p>
1463     <p>S: "OK[0]"
1464     </p>
1465 schoenebeck 708 </blockquote><p>
1466 schoenebeck 940
1467 schoenebeck 708 </p>
1468     <p>
1469     </p>
1470 senoner 542 <blockquote class="text">
1471     <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"
1472     </p>
1473     <p>S: "OK[1]"
1474     </p>
1475 schoenebeck 708 </blockquote><p>
1476 schoenebeck 940
1477 schoenebeck 708 </p>
1478 schoenebeck 940 <a name="DESTROY AUDIO_OUTPUT_DEVICE"></a><br /><hr />
1479     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
1480     <a name="rfc.section.6.2.6"></a><h3>6.2.6.&nbsp;Destroying an audio output device</h3>
1481 senoner 542
1482     <p>Use the following command to destroy a created output device:
1483     </p>
1484 schoenebeck 708 <p>
1485     </p>
1486 senoner 542 <blockquote class="text">
1487     <p>DESTROY AUDIO_OUTPUT_DEVICE &lt;device-id&gt;
1488     </p>
1489 schoenebeck 708 </blockquote><p>
1490 schoenebeck 940
1491 schoenebeck 708 </p>
1492 senoner 542 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1493     audio output device as given by the
1494 schoenebeck 708 <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"<span> (</span><span class="info">Creating an audio output device</span><span>)</span></a>
1495     or <a class="info" href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class="info">Getting all created audio output device list</span><span>)</span></a>
1496 senoner 542 command.
1497     </p>
1498     <p>Possible Answers:
1499     </p>
1500 schoenebeck 708 <p>
1501     </p>
1502 senoner 542 <blockquote class="text">
1503     <p>"OK" -
1504     </p>
1505     <blockquote class="text">
1506     <p>in case the device was successfully destroyed
1507     </p>
1508 schoenebeck 940 </blockquote>
1509    
1510 senoner 542
1511     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1512     </p>
1513     <blockquote class="text">
1514     <p>in case the device was destroyed successfully, but there are
1515     noteworthy issue(s) related (e.g. an audio over ethernet
1516     driver was unloaded but the other host might not be
1517     informed about this situation), providing an appropriate
1518     warning code and warning message
1519     </p>
1520 schoenebeck 940 </blockquote>
1521    
1522 senoner 542
1523     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1524     </p>
1525     <blockquote class="text">
1526     <p>in case it failed, providing an appropriate error code and
1527     error message
1528     </p>
1529 schoenebeck 940 </blockquote>
1530    
1531 senoner 542
1532 schoenebeck 708 </blockquote><p>
1533 schoenebeck 940
1534 schoenebeck 708 </p>
1535 senoner 542 <p>Example:
1536     </p>
1537 schoenebeck 708 <p>
1538     </p>
1539 senoner 542 <blockquote class="text">
1540     <p>C: "DESTROY AUDIO_OUTPUT_DEVICE 0"
1541     </p>
1542     <p>S: "OK"
1543     </p>
1544 schoenebeck 708 </blockquote><p>
1545 schoenebeck 940
1546 schoenebeck 708 </p>
1547 schoenebeck 940 <a name="GET AUDIO_OUTPUT_DEVICES"></a><br /><hr />
1548     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
1549     <a name="rfc.section.6.2.7"></a><h3>6.2.7.&nbsp;Getting all created audio output device count</h3>
1550 senoner 542
1551     <p>Use the following command to count all created audio output devices:
1552     </p>
1553 schoenebeck 708 <p>
1554     </p>
1555 senoner 542 <blockquote class="text">
1556     <p>GET AUDIO_OUTPUT_DEVICES
1557     </p>
1558 schoenebeck 708 </blockquote><p>
1559 schoenebeck 940
1560 schoenebeck 708 </p>
1561 senoner 542 <p>Possible Answers:
1562     </p>
1563 schoenebeck 708 <p>
1564     </p>
1565 senoner 542 <blockquote class="text">
1566     <p>LinuxSampler will answer by sending the current number of all
1567     audio output devices.
1568     </p>
1569 schoenebeck 708 </blockquote><p>
1570 schoenebeck 940
1571 schoenebeck 708 </p>
1572 senoner 542 <p>Example:
1573     </p>
1574 schoenebeck 708 <p>
1575     </p>
1576 senoner 542 <blockquote class="text">
1577     <p>C: "GET AUDIO_OUTPUT_DEVICES"
1578     </p>
1579     <p>S: "4"
1580     </p>
1581 schoenebeck 708 </blockquote><p>
1582 schoenebeck 940
1583 schoenebeck 708 </p>
1584 schoenebeck 940 <a name="LIST AUDIO_OUTPUT_DEVICES"></a><br /><hr />
1585     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
1586     <a name="rfc.section.6.2.8"></a><h3>6.2.8.&nbsp;Getting all created audio output device list</h3>
1587 senoner 542
1588     <p>Use the following command to list all created audio output devices:
1589     </p>
1590 schoenebeck 708 <p>
1591     </p>
1592 senoner 542 <blockquote class="text">
1593     <p>LIST AUDIO_OUTPUT_DEVICES
1594     </p>
1595 schoenebeck 708 </blockquote><p>
1596 schoenebeck 940
1597 schoenebeck 708 </p>
1598 senoner 542 <p>Possible Answers:
1599     </p>
1600 schoenebeck 708 <p>
1601     </p>
1602 senoner 542 <blockquote class="text">
1603     <p>LinuxSampler will answer by sending a comma separated list with
1604     the numerical IDs of all audio output devices.
1605     </p>
1606 schoenebeck 708 </blockquote><p>
1607 schoenebeck 940
1608 schoenebeck 708 </p>
1609 senoner 542 <p>Example:
1610     </p>
1611 schoenebeck 708 <p>
1612     </p>
1613 senoner 542 <blockquote class="text">
1614     <p>C: "LIST AUDIO_OUTPUT_DEVICES"
1615     </p>
1616     <p>S: "0,1,4,5"
1617     </p>
1618 schoenebeck 708 </blockquote><p>
1619 schoenebeck 940
1620 schoenebeck 708 </p>
1621 schoenebeck 940 <a name="GET AUDIO_OUTPUT_DEVICE INFO"></a><br /><hr />
1622     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
1623     <a name="rfc.section.6.2.9"></a><h3>6.2.9.&nbsp;Getting current settings of an audio output device</h3>
1624 senoner 542
1625     <p>Use the following command to get current settings of a specific, created audio output device:
1626     </p>
1627 schoenebeck 708 <p>
1628     </p>
1629 senoner 542 <blockquote class="text">
1630     <p>GET AUDIO_OUTPUT_DEVICE INFO &lt;device-id&gt;
1631     </p>
1632 schoenebeck 708 </blockquote><p>
1633 schoenebeck 940
1634 schoenebeck 708 </p>
1635 senoner 542 <p>Where &lt;device-id&gt; should be replaced by numerical ID
1636     of the audio output device as e.g. returned by the
1637 schoenebeck 708 <a class="info" href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class="info">Getting all created audio output device list</span><span>)</span></a> command.
1638 senoner 542 </p>
1639     <p>Possible Answers:
1640     </p>
1641     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1642     Each answer line begins with the information category name
1643     followed by a colon and then a space character &lt;SP&gt; and finally
1644     the info character string to that info category. As some
1645     parameters might allow multiple values, character strings are
1646     encapsulated into apostrophes ('). At the moment the following
1647     information categories are defined (independently of device):
1648     </p>
1649 schoenebeck 708 <p>
1650     </p>
1651 senoner 542 <blockquote class="text">
1652     <p>DRIVER -
1653     </p>
1654     <blockquote class="text">
1655     <p>identifier of the used audio output driver, as also
1656     returned by the
1657 schoenebeck 708 <a class="info" href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"<span> (</span><span class="info">Getting all available audio output drivers</span><span>)</span></a>
1658 senoner 542 command
1659     </p>
1660 schoenebeck 940 </blockquote>
1661    
1662 senoner 542
1663     <p>CHANNELS -
1664     </p>
1665     <blockquote class="text">
1666     <p>amount of audio output channels this device currently
1667     offers
1668     </p>
1669 schoenebeck 940 </blockquote>
1670    
1671 senoner 542
1672     <p>SAMPLERATE -
1673     </p>
1674     <blockquote class="text">
1675     <p>playback sample rate the device uses
1676     </p>
1677 schoenebeck 940 </blockquote>
1678    
1679 senoner 542
1680     <p>ACTIVE -
1681     </p>
1682     <blockquote class="text">
1683     <p>either true or false, if false then the audio device is
1684     inactive and doesn't output any sound, nor do the
1685     sampler channels connected to this audio device render
1686     any audio
1687     </p>
1688 schoenebeck 940 </blockquote>
1689    
1690 senoner 542
1691 schoenebeck 708 </blockquote><p>
1692 schoenebeck 940
1693 schoenebeck 708 </p>
1694 senoner 542 <p>The mentioned fields above don't have to be in particular
1695     order. The fields above are only those fields which are
1696     returned by all audio output devices. Every audio output driver
1697     might have its own, additional driver specific parameters (see
1698 schoenebeck 708 <a class="info" href="#GET AUDIO_OUTPUT_DRIVER INFO">Section&nbsp;6.2.3<span> (</span><span class="info">Getting information about a specific audio output driver</span><span>)</span></a>)
1699 senoner 542 which are also returned by this command.
1700     </p>
1701     <p>Example:
1702     </p>
1703 schoenebeck 708 <p>
1704     </p>
1705 senoner 542 <blockquote class="text">
1706     <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
1707     </p>
1708     <p>S: "DRIVER: ALSA"
1709     </p>
1710     <p>&nbsp;&nbsp;&nbsp;"CHANNELS: 2"
1711     </p>
1712     <p>&nbsp;&nbsp;&nbsp;"SAMPLERATE: 44100"
1713     </p>
1714     <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
1715     </p>
1716     <p>&nbsp;&nbsp;&nbsp;"FRAGMENTS: 2"
1717     </p>
1718     <p>&nbsp;&nbsp;&nbsp;"FRAGMENTSIZE: 128"
1719     </p>
1720     <p>&nbsp;&nbsp;&nbsp;"CARD: '0,0'"
1721     </p>
1722     <p>&nbsp;&nbsp;&nbsp;"."
1723     </p>
1724 schoenebeck 708 </blockquote><p>
1725 schoenebeck 940
1726 schoenebeck 708 </p>
1727 schoenebeck 940 <a name="SET AUDIO_OUTPUT_DEVICE_PARAMETER"></a><br /><hr />
1728     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
1729     <a name="rfc.section.6.2.10"></a><h3>6.2.10.&nbsp;Changing settings of audio output devices</h3>
1730 senoner 542
1731     <p>Use the following command to alter a specific setting of a created audio output device:
1732     </p>
1733 schoenebeck 708 <p>
1734     </p>
1735 senoner 542 <blockquote class="text">
1736     <p>SET AUDIO_OUTPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;
1737     </p>
1738 schoenebeck 708 </blockquote><p>
1739 schoenebeck 940
1740 schoenebeck 708 </p>
1741 senoner 542 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1742 schoenebeck 575 audio output device as given by the
1743 schoenebeck 708 <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"<span> (</span><span class="info">Creating an audio output device</span><span>)</span></a>
1744     or <a class="info" href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class="info">Getting all created audio output device list</span><span>)</span></a>
1745 schoenebeck 575 command, &lt;key&gt; by the name of the parameter to change
1746 senoner 542 and &lt;value&gt; by the new value for this parameter.
1747     </p>
1748     <p>Possible Answers:
1749     </p>
1750 schoenebeck 708 <p>
1751     </p>
1752 senoner 542 <blockquote class="text">
1753     <p>"OK" -
1754     </p>
1755     <blockquote class="text">
1756     <p>in case setting was successfully changed
1757     </p>
1758 schoenebeck 940 </blockquote>
1759    
1760 senoner 542
1761     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1762     </p>
1763     <blockquote class="text">
1764     <p>in case setting was changed successfully, but there are
1765     noteworthy issue(s) related, providing an appropriate
1766     warning code and warning message
1767     </p>
1768 schoenebeck 940 </blockquote>
1769    
1770 senoner 542
1771     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1772     </p>
1773     <blockquote class="text">
1774     <p>in case it failed, providing an appropriate error code and
1775     error message
1776     </p>
1777 schoenebeck 940 </blockquote>
1778    
1779 senoner 542
1780 schoenebeck 708 </blockquote><p>
1781 schoenebeck 940
1782 schoenebeck 708 </p>
1783 senoner 542 <p>Example:
1784     </p>
1785 schoenebeck 708 <p>
1786     </p>
1787 senoner 542 <blockquote class="text">
1788     <p>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"
1789     </p>
1790     <p>S: "OK"
1791     </p>
1792 schoenebeck 708 </blockquote><p>
1793 schoenebeck 940
1794 schoenebeck 708 </p>
1795 schoenebeck 940 <a name="GET AUDIO_OUTPUT_CHANNEL INFO"></a><br /><hr />
1796     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
1797     <a name="rfc.section.6.2.11"></a><h3>6.2.11.&nbsp;Getting information about an audio channel</h3>
1798 senoner 542
1799     <p>Use the following command to get information about an audio channel:
1800     </p>
1801 schoenebeck 708 <p>
1802     </p>
1803 senoner 542 <blockquote class="text">
1804     <p>GET AUDIO_OUTPUT_CHANNEL INFO &lt;device-id&gt; &lt;audio-chan&gt;
1805     </p>
1806 schoenebeck 708 </blockquote><p>
1807 schoenebeck 940
1808 schoenebeck 708 </p>
1809 schoenebeck 575 <p>Where &lt;device-id&gt; is the numerical ID of the audio output device as given by the
1810 schoenebeck 708 <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"<span> (</span><span class="info">Creating an audio output device</span><span>)</span></a>
1811     or <a class="info" href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class="info">Getting all created audio output device list</span><span>)</span></a>
1812 schoenebeck 575 command and &lt;audio-chan&gt; the audio channel number.
1813 senoner 542 </p>
1814     <p>Possible Answers:
1815     </p>
1816 schoenebeck 708 <p>
1817     </p>
1818 senoner 542 <blockquote class="text">
1819     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1820     Each answer line begins with the information category name
1821     followed by a colon and then a space character &lt;SP&gt; and finally
1822     the info character string to that info category. At the moment
1823     the following information categories are defined:
1824     </p>
1825 schoenebeck 708 <p>
1826     </p>
1827 senoner 542 <blockquote class="text">
1828     <p>NAME -
1829     </p>
1830     <blockquote class="text">
1831     <p>arbitrary character string naming the channel, which
1832     doesn't have to be unique (always returned by all audio channels)
1833     </p>
1834 schoenebeck 940 </blockquote>
1835    
1836 senoner 542
1837     <p>IS_MIX_CHANNEL -
1838     </p>
1839     <blockquote class="text">
1840     <p>either true or false, a mix-channel is not a real,
1841     independent audio channel, but a virtual channel which
1842     is mixed to another real channel, this mechanism is
1843     needed for sampler engines which need more audio
1844     channels than the used audio system might be able to offer
1845     (always returned by all audio channels)
1846     </p>
1847 schoenebeck 940 </blockquote>
1848    
1849 senoner 542
1850     <p>MIX_CHANNEL_DESTINATION -
1851     </p>
1852     <blockquote class="text">
1853     <p>numerical ID (positive integer including 0)
1854     which reflects the real audio channel (of the same audio
1855     output device) this mix channel refers to, means where
1856     the audio signal actually will be routed / added to
1857     (only returned in case the audio channel is mix channel)
1858     </p>
1859 schoenebeck 940 </blockquote>
1860    
1861 senoner 542
1862 schoenebeck 940 </blockquote>
1863    
1864 senoner 542
1865 schoenebeck 708 </blockquote><p>
1866 schoenebeck 940
1867 schoenebeck 708 </p>
1868 senoner 542 <p>The mentioned fields above don't have to be in particular
1869     order. The fields above are only those fields which are
1870     generally returned for the described cases by all audio
1871     channels regardless of the audio driver. Every audio channel
1872     might have its own, additional driver and channel specific
1873     parameters.
1874     </p>
1875     <p>Examples:
1876     </p>
1877 schoenebeck 708 <p>
1878     </p>
1879 senoner 542 <blockquote class="text">
1880     <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 0"
1881     </p>
1882     <p>S: "NAME: studio monitor left"
1883     </p>
1884     <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
1885     </p>
1886     <p>&nbsp;&nbsp;&nbsp;"."
1887     </p>
1888 schoenebeck 708 </blockquote><p>
1889 schoenebeck 940
1890 schoenebeck 708 </p>
1891     <p>
1892     </p>
1893 senoner 542 <blockquote class="text">
1894     <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 1"
1895     </p>
1896     <p>S: "NAME: studio monitor right"
1897     </p>
1898     <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
1899     </p>
1900     <p>&nbsp;&nbsp;&nbsp;"."
1901     </p>
1902 schoenebeck 708 </blockquote><p>
1903 schoenebeck 940
1904 schoenebeck 708 </p>
1905     <p>
1906     </p>
1907 senoner 542 <blockquote class="text">
1908     <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"
1909     </p>
1910     <p>S: "NAME: studio monitor left"
1911     </p>
1912     <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: true"
1913     </p>
1914     <p>&nbsp;&nbsp;&nbsp;"MIX_CHANNEL_DESTINATION: 1"
1915     </p>
1916     <p>&nbsp;&nbsp;&nbsp;"."
1917     </p>
1918 schoenebeck 708 </blockquote><p>
1919 schoenebeck 940
1920 schoenebeck 708 </p>
1921     <p>
1922     </p>
1923 senoner 542 <blockquote class="text">
1924     <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"
1925     </p>
1926     <p>S: "NAME: 'ardour (left)'"
1927     </p>
1928     <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
1929     </p>
1930     <p>&nbsp;&nbsp;&nbsp;"JACK_BINDINGS: 'ardour:0'"
1931     </p>
1932     <p>&nbsp;&nbsp;&nbsp;"."
1933     </p>
1934 schoenebeck 708 </blockquote><p>
1935 schoenebeck 940
1936 schoenebeck 708 </p>
1937 schoenebeck 940 <a name="GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO"></a><br /><hr />
1938     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
1939     <a name="rfc.section.6.2.12"></a><h3>6.2.12.&nbsp;Getting information about specific audio channel parameter</h3>
1940 senoner 542
1941     <p>Use the following command to get detailed information about specific audio channel parameter:
1942     </p>
1943 schoenebeck 708 <p>
1944     </p>
1945 senoner 542 <blockquote class="text">
1946     <p>GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO &lt;dev-id&gt; &lt;chan&gt; &lt;param&gt;
1947     </p>
1948 schoenebeck 708 </blockquote><p>
1949 schoenebeck 940
1950 schoenebeck 708 </p>
1951 schoenebeck 575 <p>Where &lt;dev-id&gt; is the numerical ID of the audio output device as returned by the
1952 schoenebeck 708 <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"<span> (</span><span class="info">Creating an audio output device</span><span>)</span></a>
1953     or <a class="info" href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class="info">Getting all created audio output device list</span><span>)</span></a>
1954 senoner 542 command, &lt;chan&gt; the audio channel number
1955     and &lt;param&gt; a specific channel parameter name for which information should
1956 schoenebeck 708 be obtained (as returned by the <a class="info" href="#GET AUDIO_OUTPUT_CHANNEL INFO">"GET AUDIO_OUTPUT_CHANNEL INFO"<span> (</span><span class="info">Getting information about an audio channel</span><span>)</span></a> command).
1957 senoner 542 </p>
1958     <p>Possible Answers:
1959     </p>
1960 schoenebeck 708 <p>
1961     </p>
1962 senoner 542 <blockquote class="text">
1963     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1964     Each answer line begins with the information category name
1965     followed by a colon and then a space character &lt;SP&gt; and finally
1966     the info character string to that info category. There are
1967     information which is always returned, independently of the
1968     given channel parameter and there is optional information
1969     which is only shown dependently to the given audio channel. At
1970     the moment the following information categories are defined:
1971     </p>
1972 schoenebeck 708 <p>
1973     </p>
1974 senoner 542 <blockquote class="text">
1975     <p>TYPE -
1976     </p>
1977     <blockquote class="text">
1978     <p>either "BOOL" for boolean value(s) or "INT" for integer
1979     value(s) or "FLOAT" for dotted number(s) or "STRING" for
1980     character string(s)
1981     (always returned)
1982     </p>
1983 schoenebeck 940 </blockquote>
1984    
1985 senoner 542
1986     <p>DESCRIPTION -
1987     </p>
1988     <blockquote class="text">
1989     <p>arbitrary text describing the purpose of the parameter (always returned)
1990     </p>
1991 schoenebeck 940 </blockquote>
1992    
1993 senoner 542
1994     <p>FIX -
1995     </p>
1996     <blockquote class="text">
1997     <p>either true or false, if true then this parameter is
1998     read only, thus cannot be altered
1999     (always returned)
2000     </p>
2001 schoenebeck 940 </blockquote>
2002    
2003 senoner 542
2004     <p>MULTIPLICITY -
2005     </p>
2006     <blockquote class="text">
2007     <p>either true or false, defines if this parameter allows
2008     only one value or a list of values, where true means
2009     multiple values and false only a single value allowed
2010     (always returned)
2011     </p>
2012 schoenebeck 940 </blockquote>
2013    
2014 senoner 542
2015     <p>RANGE_MIN -
2016     </p>
2017     <blockquote class="text">
2018     <p>defines lower limit of the allowed value range for this
2019     parameter, can be an integer value as well as a dotted
2020     number, usually used in conjunction with 'RANGE_MAX',
2021     but may also appear without
2022     (optionally returned, dependent to driver and channel
2023     parameter)
2024     </p>
2025 schoenebeck 940 </blockquote>
2026    
2027 senoner 542
2028     <p>RANGE_MAX -
2029     </p>
2030     <blockquote class="text">
2031     <p>defines upper limit of the allowed value range for this
2032     parameter, can be an integer value as well as a dotted
2033     number, usually used in conjunction with 'RANGE_MIN',
2034     but may also appear without
2035     (optionally returned, dependent to driver and channel
2036     parameter)
2037     </p>
2038 schoenebeck 940 </blockquote>
2039    
2040 senoner 542
2041     <p>POSSIBILITIES -
2042     </p>
2043     <blockquote class="text">
2044     <p>comma separated list of possible values for this
2045     parameter, character strings are encapsulated into
2046     apostrophes
2047     (optionally returned, dependent to driver and channel
2048     parameter)
2049     </p>
2050 schoenebeck 940 </blockquote>
2051    
2052 senoner 542
2053 schoenebeck 940 </blockquote>
2054    
2055 senoner 542
2056     <p>The mentioned fields above don't have to be in particular order.
2057     </p>
2058 schoenebeck 708 </blockquote><p>
2059 schoenebeck 940
2060 schoenebeck 708 </p>
2061 senoner 542 <p>Example:
2062     </p>
2063 schoenebeck 708 <p>
2064     </p>
2065 senoner 542 <blockquote class="text">
2066     <p>C: "GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO 1 0 JACK_BINDINGS"
2067     </p>
2068     <p>S: "DESCRIPTION: bindings to other JACK clients"
2069     </p>
2070     <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
2071     </p>
2072     <p>&nbsp;&nbsp;&nbsp;"FIX: false"
2073     </p>
2074     <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"
2075     </p>
2076     <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"
2077     </p>
2078     <p>&nbsp;&nbsp;&nbsp;"."
2079     </p>
2080 schoenebeck 708 </blockquote><p>
2081 schoenebeck 940
2082 schoenebeck 708 </p>
2083 schoenebeck 940 <a name="SET AUDIO_OUTPUT_CHANNEL_PARAMETER"></a><br /><hr />
2084     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
2085     <a name="rfc.section.6.2.13"></a><h3>6.2.13.&nbsp;Changing settings of audio output channels</h3>
2086 senoner 542
2087     <p>Use the following command to alter a specific setting of an audio output channel:
2088     </p>
2089 schoenebeck 708 <p>
2090     </p>
2091 senoner 542 <blockquote class="text">
2092     <p>SET AUDIO_OUTPUT_CHANNEL_PARAMETER &lt;dev-id&gt; &lt;chn&gt; &lt;key&gt;=&lt;value&gt;
2093     </p>
2094 schoenebeck 708 </blockquote><p>
2095 schoenebeck 940
2096 schoenebeck 708 </p>
2097 schoenebeck 575 <p>Where &lt;dev-id&gt; should be replaced by the numerical ID of the audio output device as returned by the
2098 schoenebeck 708 <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"<span> (</span><span class="info">Creating an audio output device</span><span>)</span></a>
2099     or <a class="info" href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class="info">Getting all created audio output device list</span><span>)</span></a>
2100 schoenebeck 575 command, &lt;chn&gt; by the audio channel number, &lt;key&gt; by the name of the
2101 senoner 542 parameter to change and &lt;value&gt; by the new value for this parameter.
2102     </p>
2103     <p>Possible Answers:
2104     </p>
2105 schoenebeck 708 <p>
2106     </p>
2107 senoner 542 <blockquote class="text">
2108     <p>"OK" -
2109     </p>
2110     <blockquote class="text">
2111     <p>in case setting was successfully changed
2112     </p>
2113 schoenebeck 940 </blockquote>
2114    
2115 senoner 542
2116     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2117     </p>
2118     <blockquote class="text">
2119     <p>in case setting was changed successfully, but there are
2120     noteworthy issue(s) related, providing an appropriate
2121     warning code and warning message
2122     </p>
2123 schoenebeck 940 </blockquote>
2124    
2125 senoner 542
2126     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2127     </p>
2128     <blockquote class="text">
2129     <p>in case it failed, providing an appropriate error code and
2130     error message
2131     </p>
2132 schoenebeck 940 </blockquote>
2133    
2134 senoner 542
2135 schoenebeck 708 </blockquote><p>
2136 schoenebeck 940
2137 schoenebeck 708 </p>
2138 senoner 542 <p>Example:
2139     </p>
2140 schoenebeck 708 <p>
2141     </p>
2142 senoner 542 <blockquote class="text">
2143     <p>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"
2144     </p>
2145     <p>S: "OK"
2146     </p>
2147 schoenebeck 708 </blockquote><p>
2148 schoenebeck 940
2149 schoenebeck 708 </p>
2150     <p>
2151     </p>
2152 senoner 542 <blockquote class="text">
2153     <p>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"
2154     </p>
2155     <p>S: "OK"
2156     </p>
2157 schoenebeck 708 </blockquote><p>
2158 schoenebeck 940
2159 schoenebeck 708 </p>
2160 schoenebeck 940 <a name="anchor10"></a><br /><hr />
2161     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
2162     <a name="rfc.section.6.3"></a><h3>6.3.&nbsp;Configuring MIDI input drivers</h3>
2163 senoner 542
2164     <p>Instances of drivers in LinuxSampler are called devices. You can use
2165     multiple MIDI devices simultaneously, e.g. to use MIDI over ethernet as
2166     MIDI input on one sampler channel and ALSA as MIDI input on another sampler
2167     channel. For particular MIDI input systems it's also possible to create
2168     several devices of the same MIDI input type. This chapter describes all
2169     commands to configure LinuxSampler's MIDI input devices and their parameters.
2170     </p>
2171     <p>Instead of defining commands and parameters for each driver individually,
2172     all possible parameters, their meanings and possible values have to be obtained
2173     at runtime. This makes the protocol a bit abstract, but has the advantage, that
2174     front-ends can be written independently of what drivers are currently implemented
2175     and what parameters these drivers are actually offering. This means front-ends can
2176     even handle drivers which are implemented somewhere in future without modifying
2177     the front-end at all.
2178     </p>
2179     <p>Commands for configuring MIDI input devices are pretty much the same as the
2180     commands for configuring audio output drivers, already described in the last
2181     chapter.
2182     </p>
2183     <p>Note: examples in this chapter showing particular parameters of drivers are
2184     not meant as specification of the drivers' parameters. Driver implementations in
2185     LinuxSampler might have complete different parameter names and meanings than shown
2186     in these examples or might change in future, so these examples are only meant for
2187     showing how to retrieve what parameters drivers are offering, how to retrieve their
2188     possible values, etc.
2189     </p>
2190 schoenebeck 940 <a name="GET AVAILABLE_MIDI_INPUT_DRIVERS"></a><br /><hr />
2191     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
2192     <a name="rfc.section.6.3.1"></a><h3>6.3.1.&nbsp;Getting amount of available MIDI input drivers</h3>
2193 senoner 542
2194     <p>Use the following command to get the number of
2195     MIDI input drivers currently available for the
2196     LinuxSampler instance:
2197     </p>
2198 schoenebeck 708 <p>
2199     </p>
2200 senoner 542 <blockquote class="text">
2201     <p>GET AVAILABLE_MIDI_INPUT_DRIVERS
2202     </p>
2203 schoenebeck 708 </blockquote><p>
2204 schoenebeck 940
2205 schoenebeck 708 </p>
2206 senoner 542 <p>Possible Answers:
2207     </p>
2208 schoenebeck 708 <p>
2209     </p>
2210 senoner 542 <blockquote class="text">
2211     <p>LinuxSampler will answer by sending the
2212     number of available MIDI input drivers.
2213     </p>
2214 schoenebeck 708 </blockquote><p>
2215 schoenebeck 940
2216 schoenebeck 708 </p>
2217 senoner 542 <p>Example:
2218     </p>
2219 schoenebeck 708 <p>
2220     </p>
2221 senoner 542 <blockquote class="text">
2222     <p>C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"
2223     </p>
2224     <p>S: "2"
2225     </p>
2226 schoenebeck 708 </blockquote><p>
2227 schoenebeck 940
2228 schoenebeck 708 </p>
2229 schoenebeck 940 <a name="LIST AVAILABLE_MIDI_INPUT_DRIVERS"></a><br /><hr />
2230     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
2231     <a name="rfc.section.6.3.2"></a><h3>6.3.2.&nbsp;Getting all available MIDI input drivers</h3>
2232 senoner 542
2233     <p>Use the following command to list all MIDI input drivers currently available
2234     for the LinuxSampler instance:
2235     </p>
2236 schoenebeck 708 <p>
2237     </p>
2238 senoner 542 <blockquote class="text">
2239     <p>LIST AVAILABLE_MIDI_INPUT_DRIVERS
2240     </p>
2241 schoenebeck 708 </blockquote><p>
2242 schoenebeck 940
2243 schoenebeck 708 </p>
2244 senoner 542 <p>Possible Answers:
2245     </p>
2246 schoenebeck 708 <p>
2247     </p>
2248 senoner 542 <blockquote class="text">
2249     <p>LinuxSampler will answer by sending comma separated character
2250     strings, each symbolizing a MIDI input driver.
2251     </p>
2252 schoenebeck 708 </blockquote><p>
2253 schoenebeck 940
2254 schoenebeck 708 </p>
2255 senoner 542 <p>Example:
2256     </p>
2257 schoenebeck 708 <p>
2258     </p>
2259 senoner 542 <blockquote class="text">
2260     <p>C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
2261     </p>
2262     <p>S: "ALSA,JACK"
2263     </p>
2264 schoenebeck 708 </blockquote><p>
2265 schoenebeck 940
2266 schoenebeck 708 </p>
2267 schoenebeck 940 <a name="GET MIDI_INPUT_DRIVER INFO"></a><br /><hr />
2268     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
2269     <a name="rfc.section.6.3.3"></a><h3>6.3.3.&nbsp;Getting information about a specific MIDI input driver</h3>
2270 senoner 542
2271     <p>Use the following command to get detailed information about a specific MIDI input driver:
2272     </p>
2273 schoenebeck