/[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 940 - (hide annotations) (download) (as text)
Sat Nov 25 17:18:12 2006 UTC (17 years, 8 months ago) by schoenebeck
File MIME type: text/html
File size: 215075 byte(s)
with the latest LS release (0.4.0) we also have a new
LSCP spec release (1.1) now

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