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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

1 <!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 <meta name="generator" content="xml2rfc v1.30 (http://xml.resource.org/)">
7 <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 td.rfcbug { background-color: #000000 ; width: 30px ; height: 30px ;
22 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 /* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */
32 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 a.info:hover span.info{ /*the span will display just on :hover state*/
44 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 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
64 span.emph { font-style: italic; }
65 span.strong { font-weight: bold; }
66 span.verb, span.vbare { font-family: "Courier New", Courier, monospace ; }
67
68 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 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 text-align: left;
79 }
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 table.full { vertical-align: top ; border-collapse: collapse ;
101 border-style: solid solid solid solid ;
102 border-color: black black black black ;
103 font-size: small ; text-align: center ; }
104 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 border-color: black black black black ; }
110 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 border-style: solid solid solid solid ;
117 border-color: #333333 #333333 #333333 #333333 ; }
118 table.headers td, table.none td { border-style: none; }
119
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 <tr><td class="header">Expires: May 30, 2007</td><td class="header">Engineering e. V.</td></tr>
130 <tr><td class="header">&nbsp;</td><td class="header">November 26, 2006</td></tr>
131 </table></td></tr></table>
132 <div align="right"><span class="title"><br />LinuxSampler Control Protocol</span></div>
133 <div align="right"><span class="title"><br />LSCP 1.2</span></div>
134
135 <h3>Status of this Memo</h3>
136 <p>
137 This document is an Internet-Draft and is
138 in full conformance with all provisions of Section&nbsp;10 of RFC&nbsp;2026.</p>
139 <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 them other than as &ldquo;work in progress.&rdquo;</p>
149 <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 This Internet-Draft will expire on May 30, 2007.</p>
157
158 <h3>Copyright Notice</h3>
159 <p>
160 Copyright &copy; The Internet Society (2006). All Rights Reserved.</p>
161
162 <h3>Abstract</h3>
163
164 <p>The LinuxSampler Control Protocol (LSCP) is an
165 application-level protocol primarily intended for local and
166 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 </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 <a href="#LSCP versioning">2.</a>&nbsp;
176 Versioning of this specification<br />
177 <a href="#anchor2">3.</a>&nbsp;
178 Introduction<br />
179 <a href="#anchor3">4.</a>&nbsp;
180 Focus of this protocol<br />
181 <a href="#anchor4">5.</a>&nbsp;
182 Communication Overview<br />
183 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor5">5.1.</a>&nbsp;
184 Request/response communication method<br />
185 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor6">5.1.1.</a>&nbsp;
186 Result format<br />
187 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor7">5.2.</a>&nbsp;
188 Subscribe/notify communication method<br />
189 <a href="#control_commands">6.</a>&nbsp;
190 Description for control commands<br />
191 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor8">6.1.</a>&nbsp;
192 Ignored lines and comments<br />
193 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor9">6.2.</a>&nbsp;
194 Configuring audio drivers<br />
195 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_AUDIO_OUTPUT_DRIVERS">6.2.1.</a>&nbsp;
196 Getting amount of available audio output drivers<br />
197 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">6.2.2.</a>&nbsp;
198 Getting all available audio output drivers<br />
199 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DRIVER INFO">6.2.3.</a>&nbsp;
200 Getting information about a specific audio
201 output driver<br />
202 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO">6.2.4.</a>&nbsp;
203 Getting information about specific audio
204 output driver parameter<br />
205 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CREATE AUDIO_OUTPUT_DEVICE">6.2.5.</a>&nbsp;
206 Creating an audio output device<br />
207 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DESTROY AUDIO_OUTPUT_DEVICE">6.2.6.</a>&nbsp;
208 Destroying an audio output device<br />
209 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DEVICES">6.2.7.</a>&nbsp;
210 Getting all created audio output device count<br />
211 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AUDIO_OUTPUT_DEVICES">6.2.8.</a>&nbsp;
212 Getting all created audio output device list<br />
213 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DEVICE INFO">6.2.9.</a>&nbsp;
214 Getting current settings of an audio output device<br />
215 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET AUDIO_OUTPUT_DEVICE_PARAMETER">6.2.10.</a>&nbsp;
216 Changing settings of audio output devices<br />
217 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_CHANNEL INFO">6.2.11.</a>&nbsp;
218 Getting information about an audio channel<br />
219 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO">6.2.12.</a>&nbsp;
220 Getting information about specific audio channel parameter<br />
221 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET AUDIO_OUTPUT_CHANNEL_PARAMETER">6.2.13.</a>&nbsp;
222 Changing settings of audio output channels<br />
223 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor10">6.3.</a>&nbsp;
224 Configuring MIDI input drivers<br />
225 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_MIDI_INPUT_DRIVERS">6.3.1.</a>&nbsp;
226 Getting amount of available MIDI input drivers<br />
227 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_MIDI_INPUT_DRIVERS">6.3.2.</a>&nbsp;
228 Getting all available MIDI input drivers<br />
229 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DRIVER INFO">6.3.3.</a>&nbsp;
230 Getting information about a specific MIDI input driver<br />
231 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DRIVER_PARAMETER INFO">6.3.4.</a>&nbsp;
232 Getting information about specific MIDI input driver parameter<br />
233 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CREATE MIDI_INPUT_DEVICE">6.3.5.</a>&nbsp;
234 Creating a MIDI input device<br />
235 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DESTROY MIDI_INPUT_DEVICE">6.3.6.</a>&nbsp;
236 Destroying a MIDI input device<br />
237 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DEVICES">6.3.7.</a>&nbsp;
238 Getting all created MIDI input device count<br />
239 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST MIDI_INPUT_DEVICES">6.3.8.</a>&nbsp;
240 Getting all created MIDI input device list<br />
241 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DEVICE INFO">6.3.9.</a>&nbsp;
242 Getting current settings of a MIDI input device<br />
243 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET MIDI_INPUT_DEVICE_PARAMETER">6.3.10.</a>&nbsp;
244 Changing settings of MIDI input devices<br />
245 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_PORT INFO">6.3.11.</a>&nbsp;
246 Getting information about a MIDI port<br />
247 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_PORT_PARAMETER INFO">6.3.12.</a>&nbsp;
248 Getting information about specific MIDI port parameter<br />
249 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET MIDI_INPUT_PORT_PARAMETER">6.3.13.</a>&nbsp;
250 Changing settings of MIDI input ports<br />
251 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor11">6.4.</a>&nbsp;
252 Configuring sampler channels<br />
253 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LOAD INSTRUMENT">6.4.1.</a>&nbsp;
254 Loading an instrument<br />
255 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LOAD ENGINE">6.4.2.</a>&nbsp;
256 Loading a sampler engine<br />
257 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNELS">6.4.3.</a>&nbsp;
258 Getting all created sampler channel count<br />
259 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST CHANNELS">6.4.4.</a>&nbsp;
260 Getting all created sampler channel list<br />
261 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD CHANNEL">6.4.5.</a>&nbsp;
262 Adding a new sampler channel<br />
263 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE CHANNEL">6.4.6.</a>&nbsp;
264 Removing a sampler channel<br />
265 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_ENGINES">6.4.7.</a>&nbsp;
266 Getting amount of available engines<br />
267 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_ENGINES">6.4.8.</a>&nbsp;
268 Getting all available engines<br />
269 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET ENGINE INFO">6.4.9.</a>&nbsp;
270 Getting information about an engine<br />
271 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL INFO">6.4.10.</a>&nbsp;
272 Getting sampler channel information<br />
273 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL VOICE_COUNT">6.4.11.</a>&nbsp;
274 Current number of active voices<br />
275 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL STREAM_COUNT">6.4.12.</a>&nbsp;
276 Current number of active disk streams<br />
277 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL BUFFER_FILL">6.4.13.</a>&nbsp;
278 Current fill state of disk stream buffers<br />
279 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_DEVICE">6.4.14.</a>&nbsp;
280 Setting audio output device<br />
281 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_TYP">6.4.15.</a>&nbsp;
282 Setting audio output type<br />
283 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_CHANNEL">6.4.16.</a>&nbsp;
284 Setting audio output channel<br />
285 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_DEVICE">6.4.17.</a>&nbsp;
286 Setting MIDI input device<br />
287 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_TYPE">6.4.18.</a>&nbsp;
288 Setting MIDI input type<br />
289 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_PORT">6.4.19.</a>&nbsp;
290 Setting MIDI input port<br />
291 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_CHANNEL">6.4.20.</a>&nbsp;
292 Setting MIDI input channel<br />
293 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL VOLUME">6.4.21.</a>&nbsp;
294 Setting channel volume<br />
295 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MUTE">6.4.22.</a>&nbsp;
296 Muting a sampler channel<br />
297 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL SOLO">6.4.23.</a>&nbsp;
298 Soloing a sampler channel<br />
299 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#RESET CHANNEL">6.4.24.</a>&nbsp;
300 Resetting a sampler channel<br />
301 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor12">6.5.</a>&nbsp;
302 Controlling connection<br />
303 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE">6.5.1.</a>&nbsp;
304 Register front-end for receiving event messages<br />
305 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#UNSUBSCRIBE">6.5.2.</a>&nbsp;
306 Unregister front-end for not receiving event messages<br />
307 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET ECHO">6.5.3.</a>&nbsp;
308 Enable or disable echo of commands<br />
309 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#QUIT">6.5.4.</a>&nbsp;
310 Close client connection<br />
311 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor13">6.6.</a>&nbsp;
312 Global commands<br />
313 &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 Reset sampler<br />
319 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET SERVER INFO">6.6.4.</a>&nbsp;
320 General sampler informations<br />
321 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor14">6.7.</a>&nbsp;
322 MIDI Instrument Mapping<br />
323 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#MAP MIDI_INSTRUMENT">6.7.1.</a>&nbsp;
324 Create or replace a MIDI instrument map entry<br />
325 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENTS">6.7.2.</a>&nbsp;
326 Getting ammount of MIDI instrument map entries<br />
327 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST MIDI_INSTRUMENTS">6.7.3.</a>&nbsp;
328 Getting indeces of all MIDI instrument map entries<br />
329 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#UNMAP MIDI_INSTRUMENT">6.7.4.</a>&nbsp;
330 Remove an entry from the MIDI instrument map<br />
331 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENT INFO">6.7.5.</a>&nbsp;
332 Get current settings of MIDI instrument map entry<br />
333 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CLEAR MIDI_INSTRUMENTS">6.7.6.</a>&nbsp;
334 Clear MIDI instrument map<br />
335 <a href="#command_syntax">7.</a>&nbsp;
336 Command Syntax<br />
337 <a href="#events">8.</a>&nbsp;
338 Events<br />
339 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE CHANNEL">8.1.</a>&nbsp;
340 Number of sampler channels changed<br />
341 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE VOICE_COUNT">8.2.</a>&nbsp;
342 Number of active voices changed<br />
343 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE STREAM_COUNT">8.3.</a>&nbsp;
344 Number of active disk streams changed<br />
345 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE BUFFER_FILL">8.4.</a>&nbsp;
346 Disk stream buffer fill state changed<br />
347 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE INFO">8.5.</a>&nbsp;
348 Channel information changed<br />
349 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE TOTAL_VOICE_COUNT">8.6.</a>&nbsp;
350 Total number of active voices changed<br />
351 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MISCELLANEOUS">8.7.</a>&nbsp;
352 Miscellaneous and debugging events<br />
353 <a href="#anchor15">9.</a>&nbsp;
354 Security Considerations<br />
355 <a href="#anchor16">10.</a>&nbsp;
356 Acknowledgments<br />
357 <a href="#rfc.references1">11.</a>&nbsp;
358 References<br />
359 <a href="#rfc.authors">&#167;</a>&nbsp;
360 Author's Address<br />
361 <a href="#rfc.copyright">&#167;</a>&nbsp;
362 Intellectual Property and Copyright Statements<br />
363 </p>
364 <br clear="all" />
365
366 <a name="anchor1"></a><br /><hr />
367 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
368 <a name="rfc.section.1"></a><h3>1.&nbsp;Requirements notation</h3>
369
370 <p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
371 "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
372 and "OPTIONAL" in this document are to be interpreted as
373 described in <a class="info" href="#RFC2119">[RFC2119]<span> (</span><span class="info">Bradner, S., &ldquo;Key words for use in RFCs to Indicate Requirement Levels,&rdquo; 1997.</span><span>)</span></a>.
374 </p>
375 <p>This protocol is always case-sensitive if not explicitly
376 claimed the opposite.
377 </p>
378 <p>In examples, "C:" and "S:" indicate lines sent by the client
379 (front-end) and server (LinuxSampler) respectively. Lines in
380 examples must be interpreted as every line being CRLF
381 terminated (carriage return character followed by line feed
382 character as defined in the ASCII standard), thus the following
383 example:
384 </p>
385 <p>
386 </p>
387 <blockquote class="text">
388 <p>C: "some line"
389 </p>
390 <p>&nbsp;&nbsp;&nbsp;"another line"
391 </p>
392 </blockquote><p>
393
394 </p>
395 <p>must actually be interpreted as client sending the following
396 message:
397 </p>
398 <p>
399 </p>
400 <blockquote class="text">
401 <p>"some line&lt;CR&gt;&lt;LF&gt;another
402 line&lt;CR&gt;&lt;LF&gt;"
403 </p>
404 </blockquote><p>
405
406 </p>
407 <p>where &lt;CR&gt; symbolizes the carriage return character and
408 &lt;LF&gt; the line feed character as defined in the ASCII
409 standard.
410 </p>
411 <p>Due to technical reasons, messages can arbitrary be
412 fragmented, means the following example:
413 </p>
414 <p>
415 </p>
416 <blockquote class="text">
417 <p>S: "abcd"
418 </p>
419 </blockquote><p>
420
421 </p>
422 <p>could also happen to be sent in three messages like in the
423 following sequence scenario:
424 </p>
425 <p>
426 </p>
427 <ul class="text">
428 <li>server sending message "a"
429 </li>
430 <li>followed by a delay (pause) with
431 arbitrary duration
432 </li>
433 <li>followed by server sending message
434 "bcd&lt;CR&gt;"
435 </li>
436 <li>again followed by a delay (pause) with arbitrary
437 duration
438 </li>
439 <li>followed by server sending the message
440 "&lt;LF&gt;"
441 </li>
442 </ul><p>
443
444 </p>
445 <p>where again &lt;CR&gt; and &lt;LF&gt; symbolize the carriage
446 return and line feed characters respectively.
447 </p>
448 <a name="LSCP versioning"></a><br /><hr />
449 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
450 <a name="rfc.section.2"></a><h3>2.&nbsp;Versioning of this specification</h3>
451
452 <p>LSCP will certainly be extended and enhanced by-and-by. Each official
453 release of the LSCP specification will be tagged with a unique version
454 tuple. The version tuple consists at least of a major and minor version
455 number like:
456
457 </p>
458 <p>
459 </p>
460 <blockquote class="text">
461 <p>"1.2"
462 </p>
463 </blockquote><p>
464
465 </p>
466 <p>
467 In this example the major version number would be "1" and the minor
468 version number would be "2". Note that the version tuple might also
469 have more than two elements. The major version number defines a
470 group of backward compatible versions. That means a frontend is
471 compatible to the connected sampler if and only if the LSCP versions
472 to which each of the two parties complies to, match both of the
473 following rules:
474
475 </p>
476 <p>Compatibility:
477 </p>
478 <p>
479 </p>
480 <ol class="text">
481 <li>The frontend's LSCP major version and the sampler's LSCP
482 major version are exactly equal.
483 </li>
484 <li>The frontend's LSCP minor version is less or equal than
485 the sampler's LSCP minor version.
486 </li>
487 </ol><p>
488
489 </p>
490 <p>
491 Compatibility can only be claimed if both rules are true.
492 The frontend can use the
493 <a class="info" href="#GET SERVER INFO">"GET SERVER INFO"<span> (</span><span class="info">General sampler informations</span><span>)</span></a> command to
494 get the version of the LSCP specification the sampler complies with.
495
496 </p>
497 <a name="anchor2"></a><br /><hr />
498 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
499 <a name="rfc.section.3"></a><h3>3.&nbsp;Introduction</h3>
500
501 <p>LinuxSampler is a so called software sampler application
502 capable to playback audio samples from a computer's Random
503 Access Memory (RAM) as well as directly streaming it from disk.
504 LinuxSampler is designed to be modular. It provides several so
505 called "sampler engines" where each engine is specialized for a
506 certain purpose. LinuxSampler has virtual channels which will be
507 referred in this document as "sampler channels". The channels
508 are in such way virtual as they can be connected to an
509 arbitrary MIDI input method and arbitrary MIDI channel (e.g.
510 sampler channel 17 could be connected to an ALSA sequencer
511 device 64:0 and listening to MIDI channel 1 there). Each sampler
512 channel will be associated with an instance of one of the available
513 sampler engines (e.g. GigEngine, DLSEngine). The audio output of
514 each sampler channel can be routed to an arbitrary audio output
515 method (ALSA / JACK) and an arbitrary audio output channel
516 there.
517 </p>
518 <a name="anchor3"></a><br /><hr />
519 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
520 <a name="rfc.section.4"></a><h3>4.&nbsp;Focus of this protocol</h3>
521
522 <p>Main focus of this protocol is to provide a way to configure
523 a running LinuxSampler instance and to retrieve information
524 about it. The focus of this protocol is not to provide a way to
525 control synthesis parameters or even to trigger or release
526 notes. Or in other words; the focus are those functionalities
527 which are not covered by MIDI or which may at most be handled
528 via MIDI System Exclusive Messages.
529 </p>
530 <a name="anchor4"></a><br /><hr />
531 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
532 <a name="rfc.section.5"></a><h3>5.&nbsp;Communication Overview</h3>
533
534 <p>There are two distinct methods of communication between a
535 running instance of LinuxSampler and one or more control
536 applications, so called "front-ends": a simple request/response
537 communication method used by the clients to give commands to the
538 server as well as to inquire about server's status and a
539 subscribe/notify communication method used by the client to
540 subscribe to and receive notifications of certain events as they
541 happen on the server. The latter needs more effort to be
542 implemented in the front-end application. The two communication
543 methods will be described next.
544 </p>
545 <a name="anchor5"></a><br /><hr />
546 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
547 <a name="rfc.section.5.1"></a><h3>5.1.&nbsp;Request/response communication method</h3>
548
549 <p>This simple communication method is based on
550 <a class="info" href="#RFC793">TCP<span> (</span><span class="info">Defense Advanced Research Projects Agency, &ldquo;TRANSMISSION CONTROL PROTOCOL,&rdquo; 1981.</span><span>)</span></a> [RFC793]. The
551 front-end application establishes a TCP connection to the
552 LinuxSampler instance on a certain host system. Then the
553 front-end application will send certain ASCII based commands
554 as defined in this document (every command line must be CRLF
555 terminated - see "Conventions used in this document" at the
556 beginning of this document) and the LinuxSampler application
557 will response after a certain process time with an
558 appropriate ASCII based answer, also as defined in this
559 document. So this TCP communication is simply based on query
560 and answer paradigm. That way LinuxSampler is only able to
561 answer on queries from front-ends, but not able to
562 automatically send messages to the client if it's not asked
563 to. The fronted should not reconnect to LinuxSampler for
564 every single command, instead it should keep the connection
565 established and simply resend message(s) for subsequent
566 commands. To keep information in the front-end up-to-date
567 the front-end has to periodically send new requests to get
568 the current information from the LinuxSampler instance. This
569 is often referred to as "polling". While polling is simple
570 to implement and may be OK to use in some cases, there may
571 be disadvantages to polling such as network traffic overhead
572 and information being out of date.
573 It is possible for a client or several clients to open more
574 than one connection to the server at the same time. It is
575 also possible to send more than one request to the server
576 at the same time but if those requests are sent over the
577 same connection server MUST execute them sequentially. Upon
578 executing a request server will produce a result set and
579 send it to the client. Each and every request made by the
580 client MUST result in a result set being sent back to the
581 client. No other data other than a result set may be sent by
582 a server to a client. No result set may be sent to a client
583 without the client sending request to the server first. On
584 any particular connection, result sets MUST be sent in their
585 entirety without being interrupted by other result sets. If
586 several requests got queued up at the server they MUST be
587 processed in the order they were received and result sets
588 MUST be sent back in the same order.
589 </p>
590 <a name="anchor6"></a><br /><hr />
591 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
592 <a name="rfc.section.5.1.1"></a><h3>5.1.1.&nbsp;Result format</h3>
593
594 <p>Result set could be one of the following types:
595 </p>
596 <p>
597 </p>
598 <ol class="text">
599 <li>Normal
600 </li>
601 <li>Warning
602 </li>
603 <li>Error
604 </li>
605 </ol><p>
606
607 </p>
608 <p>Warning and Error result sets MUST be single line and
609 have the following format:
610 </p>
611 <p>
612 </p>
613 <ul class="text">
614 <li>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;"
615 </li>
616 <li>"ERR:&lt;error-code&gt;:&lt;error-message&gt;"
617 </li>
618 </ul><p>
619
620 </p>
621 <p>Where &lt;warning-code&gt; and &lt;error-code&gt; are
622 numeric unique identifiers of the warning or error and
623 &lt;warning-message&gt; and &lt;error-message&gt; are
624 human readable descriptions of the warning or error
625 respectively.
626 </p>
627 <p>Examples:
628 </p>
629 <p>
630 </p>
631 <blockquote class="text">
632 <p>C: "LOAD INSTRUMENT '/home/me/Boesendorfer24bit.gig" 0 0
633 </p>
634 <p>S: "WRN:32:This is a 24 bit patch which is not supported natively yet."
635 </p>
636 </blockquote><p>
637
638 </p>
639 <p>
640 </p>
641 <blockquote class="text">
642 <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA EAR"
643 </p>
644 <p>S: "ERR:3456:Audio output driver 'ALSA' does not have a parameter 'EAR'."
645 </p>
646 </blockquote><p>
647
648 </p>
649 <p>
650 </p>
651 <blockquote class="text">
652 <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 123456"
653 </p>
654 <p>S: "ERR:9:There is no audio output device with index 123456."
655 </p>
656 </blockquote><p>
657
658 </p>
659 <p>Normal result sets could be:
660 </p>
661 <p>
662 </p>
663 <ol class="text">
664 <li>Empty
665 </li>
666 <li>Single line
667 </li>
668 <li>Multi-line
669 </li>
670 </ol><p>
671
672 </p>
673 <p> Empty result set is issued when the server only
674 needed to acknowledge the fact that the request was
675 received and it was processed successfully and no
676 additional information is available. This result set has
677 the following format:
678 </p>
679 <p>
680 </p>
681 <blockquote class="text">
682 <p>"OK"
683 </p>
684 </blockquote><p>
685
686 </p>
687 <p>Example:
688 </p>
689 <p>
690 </p>
691 <blockquote class="text">
692 <p>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 CHANNELS=4"
693 </p>
694 <p>S: "OK"
695 </p>
696 </blockquote><p>
697
698 </p>
699 <p>Single line result sets are command specific. One
700 example of a single line result set is an empty line.
701 Multi-line result sets are command specific and may
702 include one or more lines of information. They MUST
703 always end with the following line:
704 </p>
705 <p>
706 </p>
707 <blockquote class="text">
708 <p>"."
709 </p>
710 </blockquote><p>
711
712 </p>
713 <p>Example:
714 </p>
715 <p>
716 </p>
717 <blockquote class="text">
718 <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
719 </p>
720 <p>S: "DRIVER: ALSA"
721 </p>
722 <p>&nbsp;&nbsp;&nbsp;"CHANNELS: 2"
723 </p>
724 <p>&nbsp;&nbsp;&nbsp;"SAMPLERATE: 44100"
725 </p>
726 <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
727 </p>
728 <p>&nbsp;&nbsp;&nbsp;"FRAGMENTS: 2"
729 </p>
730 <p>&nbsp;&nbsp;&nbsp;"FRAGMENTSIZE: 128"
731 </p>
732 <p>&nbsp;&nbsp;&nbsp;"CARD: '0,0'"
733 </p>
734 <p>&nbsp;&nbsp;&nbsp;"."
735 </p>
736 </blockquote><p>
737
738 </p>
739 <p>In addition to above mentioned formats, warnings and
740 empty result sets MAY be indexed. In this case, they
741 have the following formats respectively:
742 </p>
743 <p>
744 </p>
745 <ul class="text">
746 <li>"WRN[&lt;index&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;"
747 </li>
748 <li>"OK[&lt;index&gt;]"
749 </li>
750 </ul><p>
751
752 </p>
753 <p>where &lt;index&gt; is command specific and is used
754 to indicate channel number that the result set was
755 related to or other integer value.
756 </p>
757 <p>Each line of the result set MUST end with
758 &lt;CRLF&gt;.
759 </p>
760 <p>Examples:
761 </p>
762 <p>
763 </p>
764 <blockquote class="text">
765 <p>C: "ADD CHANNEL"
766 </p>
767 <p>S: "OK[12]"
768 </p>
769 </blockquote><p>
770
771 </p>
772 <p>
773 </p>
774 <blockquote class="text">
775 <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"
776 </p>
777 <p>S: "WRN[0]:32:Sample rate not supported, using 44100 instead."
778 </p>
779 </blockquote><p>
780
781 </p>
782 <a name="anchor7"></a><br /><hr />
783 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
784 <a name="rfc.section.5.2"></a><h3>5.2.&nbsp;Subscribe/notify communication method</h3>
785
786 <p>This more sophisticated communication method is actually
787 only an extension of the simple request/response
788 communication method. The front-end still uses a TCP
789 connection and sends the same commands on the TCP
790 connection. Two extra commands are SUBSCRIBE and UNSUBSCRIBE
791 commands that allow a client to tell the server that it is
792 interested in receiving notifications about certain events
793 as they happen on the server. The SUBSCRIBE command has the
794 following syntax:
795 </p>
796 <p>
797 </p>
798 <blockquote class="text">
799 <p>SUBSCRIBE &lt;event-id&gt;
800 </p>
801 </blockquote><p>
802
803 </p>
804 <p>where &lt;event-id&gt; will be replaced by the respective
805 event that client wants to subscribe to. Upon receiving such
806 request, server SHOULD respond with OK and start sending
807 EVENT notifications when a given even has occurred to the
808 front-end when an event has occurred. It MAY be possible
809 certain events may be sent before OK response during real
810 time nature of their generation. Event messages have the
811 following format:
812 </p>
813 <p>
814 </p>
815 <blockquote class="text">
816 <p>NOTIFY:&lt;event-id&gt;:&lt;custom-event-data&gt;
817 </p>
818 </blockquote><p>
819
820 </p>
821 <p>where &lt;event-id&gt; uniquely identifies the event that
822 has occurred and &lt;custom-event-data&gt; is event
823 specific.
824 </p>
825 <p>Several rules must be followed by the server when
826 generating events:
827 </p>
828 <p>
829 </p>
830 <ol class="text">
831 <li>Events MUST NOT be sent to any client who has not
832 issued an appropriate SUBSCRIBE command.
833 </li>
834 <li>Events MUST only be sent using the same
835 connection that was used to subscribe to them.
836 </li>
837 <li>When response is being sent to the client, event
838 MUST be inserted in the stream before or after the
839 response, but NOT in the middle. Same is true about
840 the response. It should never be inserted in the
841 middle of the event message as well as any other
842 response.
843 </li>
844 </ol><p>
845
846 </p>
847 <p>If the client is not interested in a particular event
848 anymore it MAY issue UNSUBSCRIBE command using the following
849 syntax:
850 </p>
851 <p>
852 </p>
853 <blockquote class="text">
854 <p>UNSUBSCRIBE &lt;event-id&gt;
855 </p>
856 </blockquote><p>
857
858 </p>
859 <p>where &lt;event-id&gt; will be replace by the respective
860 event that client is no longer interested in receiving. For
861 a list of supported events see <a class="info" href="#events">Section&nbsp;8<span> (</span><span class="info">Events</span><span>)</span></a>.
862 </p>
863 <p>Example: the fill states of disk stream buffers have
864 changed on sampler channel 4 and the LinuxSampler instance
865 will react by sending the following message to all clients
866 who subscribed to this event:
867 </p>
868 <p>
869 </p>
870 <blockquote class="text">
871 <p>NOTIFY:CHANNEL_BUFFER_FILL:4 [35]62%,[33]80%,[37]98%
872 </p>
873 </blockquote><p>
874
875 </p>
876 <p>Which means there are currently three active streams on
877 sampler channel 4, where the stream with ID "35" is filled
878 by 62%, stream with ID 33 is filled by 80% and stream with
879 ID 37 is filled by 98%.
880 </p>
881 <p>Clients may choose to open more than one connection to
882 the server and use some connections to receive notifications
883 while using other connections to issue commands to the
884 back-end. This is entirely legal and up to the
885 implementation. This does not change the protocol in any way
886 and no special restrictions exist on the server to allow or
887 disallow this or to track what connections belong to what
888 front-ends. Server will listen on a single port, accept
889 multiple connections and support protocol described in this
890 specification in it's entirety on this single port on each
891 connection that it accepted.
892 </p>
893 <p>Due to the fact that TCP is used for this communication,
894 dead peers will be detected automatically by the OS TCP
895 stack. While it may take a while to detect dead peers if no
896 traffic is being sent from server to client (TCP keep-alive
897 timer is set to 2 hours on many OSes) it will not be an
898 issue here as when notifications are sent by the server,
899 dead client will be detected quickly.
900 </p>
901 <p>When connection is closed for any reason server MUST
902 forget all subscriptions that were made on this connection.
903 If client reconnects it MUST resubscribe to all events that
904 it wants to receive.
905 </p>
906 <a name="control_commands"></a><br /><hr />
907 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
908 <a name="rfc.section.6"></a><h3>6.&nbsp;Description for control commands</h3>
909
910 <p>This chapter will describe the available control commands
911 that can be sent on the TCP connection in detail. Some certain
912 commands (e.g. <a class="info" href="#GET CHANNEL INFO">"GET CHANNEL INFO"<span> (</span><span class="info">Getting sampler channel information</span><span>)</span></a>
913 or <a class="info" href="#GET ENGINE INFO">"GET ENGINE INFO"<span> (</span><span class="info">Getting information about an engine</span><span>)</span></a>) lead to
914 multiple-line responses. In this case LinuxSampler signals the
915 end of the response by a "." (single dot) line.
916 </p>
917 <a name="anchor8"></a><br /><hr />
918 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
919 <a name="rfc.section.6.1"></a><h3>6.1.&nbsp;Ignored lines and comments</h3>
920
921 <p>White lines, that is lines which only contain space and
922 tabulator characters, and lines that start with a "#"
923 character are ignored, thus it's possible for example to
924 group commands and to place comments in a LSCP script
925 file.
926 </p>
927 <a name="anchor9"></a><br /><hr />
928 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
929 <a name="rfc.section.6.2"></a><h3>6.2.&nbsp;Configuring audio drivers</h3>
930
931 <p>Instances of drivers in LinuxSampler are called devices.
932 You can use multiple audio devices simultaneously, e.g. to
933 output the sound of one sampler channel using the ALSA audio
934 output driver, and on another sampler channel you might want
935 to use the JACK audio output driver. For particular audio
936 output systems it's also possible to create several devices
937 of the same audio output driver, e.g. two separate ALSA
938 audio output devices for using two different sound cards at
939 the same time. This chapter describes all commands to
940 configure LinuxSampler's audio output devices and their
941 parameters.
942 </p>
943 <p>Instead of defining commands and parameters for each
944 driver individually, all possible parameters, their meanings
945 and possible values have to be obtained at runtime. This
946 makes the protocol a bit abstract, but has the advantage,
947 that front-ends can be written independently of what drivers
948 are currently implemented and what parameters these drivers
949 are actually offering. This means front-ends can even handle
950 drivers which are implemented somewhere in future without
951 modifying the front-end at all.
952 </p>
953 <p>Note: examples in this chapter showing particular
954 parameters of drivers are not meant as specification of the
955 drivers' parameters. Driver implementations in LinuxSampler
956 might have complete different parameter names and meanings
957 than shown in these examples or might change in future, so
958 these examples are only meant for showing how to retrieve
959 what parameters drivers are offering, how to retrieve their
960 possible values, etc.
961 </p>
962 <a name="GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"></a><br /><hr />
963 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
964 <a name="rfc.section.6.2.1"></a><h3>6.2.1.&nbsp;Getting amount of available audio output drivers</h3>
965
966 <p>Use the following command to get the number of
967 audio output drivers currently available for the
968 LinuxSampler instance:
969 </p>
970 <p>
971 </p>
972 <blockquote class="text">
973 <p>GET AVAILABLE_AUDIO_OUTPUT_DRIVERS
974 </p>
975 </blockquote><p>
976
977 </p>
978 <p>Possible Answers:
979 </p>
980 <p>
981 </p>
982 <blockquote class="text">
983 <p>LinuxSampler will answer by sending the
984 number of audio output drivers.
985 </p>
986 </blockquote><p>
987
988 </p>
989 <p>Example:
990 </p>
991 <p>
992 </p>
993 <blockquote class="text">
994 <p>C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
995 </p>
996 <p>S: "2"
997 </p>
998 </blockquote><p>
999
1000 </p>
1001 <a name="LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"></a><br /><hr />
1002 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
1003 <a name="rfc.section.6.2.2"></a><h3>6.2.2.&nbsp;Getting all available audio output drivers</h3>
1004
1005 <p>Use the following command to list all audio output
1006 drivers currently available for the LinuxSampler
1007 instance:
1008 </p>
1009 <p>
1010 </p>
1011 <blockquote class="text">
1012 <p>LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS
1013 </p>
1014 </blockquote><p>
1015
1016 </p>
1017 <p>Possible Answers:
1018 </p>
1019 <p>
1020 </p>
1021 <blockquote class="text">
1022 <p>LinuxSampler will answer by sending comma
1023 separated character strings, each symbolizing an
1024 audio output driver.
1025 </p>
1026 </blockquote><p>
1027
1028 </p>
1029 <p>Example:
1030 </p>
1031 <p>
1032 </p>
1033 <blockquote class="text">
1034 <p>C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"
1035 </p>
1036 <p>S: "ALSA,JACK"
1037 </p>
1038 </blockquote><p>
1039
1040 </p>
1041 <a name="GET AUDIO_OUTPUT_DRIVER INFO"></a><br /><hr />
1042 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
1043 <a name="rfc.section.6.2.3"></a><h3>6.2.3.&nbsp;Getting information about a specific audio
1044 output driver</h3>
1045
1046 <p>Use the following command to get detailed information
1047 about a specific audio output driver:
1048 </p>
1049 <p>
1050 </p>
1051 <blockquote class="text">
1052 <p>GET AUDIO_OUTPUT_DRIVER INFO
1053 &lt;audio-output-driver&gt;
1054 </p>
1055 </blockquote><p>
1056
1057 </p>
1058 <p>Where &lt;audio-output-driver&gt; is the name of the
1059 audio output driver, returned by the
1060 <a class="info" href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"<span> (</span><span class="info">Getting all available audio output drivers</span><span>)</span></a> command.
1061 </p>
1062 <p>Possible Answers:
1063 </p>
1064 <p>
1065 </p>
1066 <blockquote class="text">
1067 <p>LinuxSampler will answer by sending a
1068 &lt;CRLF&gt; separated list. Each answer line
1069 begins with the information category name
1070 followed by a colon and then a space character
1071 &lt;SP&gt; and finally the info character string
1072 to that info category. At the moment the
1073 following information categories are
1074 defined:
1075 </p>
1076 <p>
1077 </p>
1078 <blockquote class="text">
1079 <p>DESCRIPTION -
1080 </p>
1081 <blockquote class="text">
1082 <p> character string describing the
1083 audio output driver
1084 </p>
1085 </blockquote>
1086
1087
1088 <p>VERSION -
1089 </p>
1090 <blockquote class="text">
1091 <p>character string reflecting the
1092 driver's version
1093 </p>
1094 </blockquote>
1095
1096
1097 <p>PARAMETERS -
1098 </p>
1099 <blockquote class="text">
1100 <p>comma separated list of all
1101 parameters available for the given
1102 audio output driver, at least
1103 parameters 'channels', 'samplerate'
1104 and 'active' are offered by all audio
1105 output drivers
1106 </p>
1107 </blockquote>
1108
1109
1110 </blockquote>
1111
1112
1113 <p>The mentioned fields above don't have to be
1114 in particular order.
1115 </p>
1116 </blockquote><p>
1117
1118 </p>
1119 <p>Example:
1120 </p>
1121 <p>
1122 </p>
1123 <blockquote class="text">
1124 <p>C: "GET AUDIO_OUTPUT_DRIVER INFO ALSA"
1125 </p>
1126 <p>S: "DESCRIPTION: Advanced Linux Sound
1127 Architecture"
1128 </p>
1129 <p>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"
1130 </p>
1131 <p>&nbsp;&nbsp;&nbsp;"PARAMETERS:
1132 DRIVER,CHANNELS,SAMPLERATE,ACTIVE,FRAGMENTS,
1133 FRAGMENTSIZE,CARD"
1134 </p>
1135 <p>&nbsp;&nbsp;&nbsp;"."
1136 </p>
1137 </blockquote><p>
1138
1139 </p>
1140 <a name="GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO"></a><br /><hr />
1141 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
1142 <a name="rfc.section.6.2.4"></a><h3>6.2.4.&nbsp;Getting information about specific audio
1143 output driver parameter</h3>
1144
1145 <p>Use the following command to get detailed information
1146 about a specific audio output driver parameter:
1147 </p>
1148 <p>
1149 </p>
1150 <blockquote class="text">
1151 <p>GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO &lt;audio&gt; &lt;prm&gt; [&lt;deplist&gt;]
1152 </p>
1153 </blockquote><p>
1154
1155 </p>
1156 <p>Where &lt;audio&gt; is the name of the audio output
1157 driver as returned by the <a class="info" href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"<span> (</span><span class="info">Getting all available audio output drivers</span><span>)</span></a> command,
1158 &lt;prm&gt; a specific parameter name for which information should be
1159 obtained (as returned by the
1160 <a class="info" href="#GET AUDIO_OUTPUT_DRIVER INFO">"GET AUDIO_OUTPUT_DRIVER INFO"<span> (</span><span class="info">Getting information about a specific audio output driver</span><span>)</span></a> command) and
1161 &lt;deplist&gt; is an optional list of parameters on which the sought
1162 parameter &lt;prm&gt; depends on, &lt;deplist&gt; is a list of key-value
1163 pairs in form of "key1=val1 key2=val2 ...", where character string values
1164 are encapsulated into apostrophes ('). Arguments given with &lt;deplist&gt;
1165 which are not dependency parameters of &lt;prm&gt; will be ignored, means
1166 the front-end application can simply put all parameters into &lt;deplist&gt;
1167 with the values already selected by the user.
1168 </p>
1169 <p>Possible Answers:
1170 </p>
1171 <p>
1172 </p>
1173 <blockquote class="text">
1174 <p>LinuxSampler will answer by sending a
1175 &lt;CRLF&gt; separated list.
1176 Each answer line begins with the information category name
1177 followed by a colon and then a space character &lt;SP&gt; and
1178 finally
1179 the info character string to that info category. There are
1180 information which is always returned, independently of the
1181 given driver parameter and there are optional information
1182 which is only shown dependently to given driver parameter. At
1183 the moment the following information categories are defined:
1184 </p>
1185 </blockquote><p>
1186
1187 </p>
1188 <p>
1189 </p>
1190 <blockquote class="text">
1191 <p>TYPE -
1192 </p>
1193 <blockquote class="text">
1194 <p>either "BOOL" for boolean value(s) or
1195 "INT" for integer
1196 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1197 character string(s)
1198 (always returned, no matter which driver parameter)
1199 </p>
1200 </blockquote>
1201
1202
1203 <p>DESCRIPTION -
1204 </p>
1205 <blockquote class="text">
1206 <p>arbitrary text describing the purpose of the parameter
1207 (always returned, no matter which driver parameter)
1208 </p>
1209 </blockquote>
1210
1211
1212 <p>MANDATORY -
1213 </p>
1214 <blockquote class="text">
1215 <p>either true or false, defines if this parameter must be
1216 given when the device is to be created with the
1217 <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">'CREATE AUDIO_OUTPUT_DEVICE'<span> (</span><span class="info">Creating an audio output device</span><span>)</span></a>
1218 command (always returned, no matter which driver parameter)
1219 </p>
1220 </blockquote>
1221
1222
1223 <p>FIX -
1224 </p>
1225 <blockquote class="text">
1226 <p>either true or false, if false then this parameter can
1227 be changed at any time, once the device is created by
1228 the <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">'CREATE AUDIO_OUTPUT_DEVICE'<span> (</span><span class="info">Creating an audio output device</span><span>)</span></a>
1229 command (always returned, no matter which driver parameter)
1230 </p>
1231 </blockquote>
1232
1233
1234 <p>MULTIPLICITY -
1235 </p>
1236 <blockquote class="text">
1237 <p>either true or false, defines if this parameter allows
1238 only one value or a list of values, where true means
1239 multiple values and false only a single value allowed
1240 (always returned, no matter which driver parameter)
1241 </p>
1242 </blockquote>
1243
1244
1245 <p>DEPENDS -
1246 </p>
1247 <blockquote class="text">
1248 <p>comma separated list of parameters this parameter depends
1249 on, means the values for fields 'DEFAULT', 'RANGE_MIN',
1250 'RANGE_MAX' and 'POSSIBILITIES' might depend on these
1251 listed parameters, for example assuming that an audio
1252 driver (like the ALSA driver) offers parameters 'card'
1253 and 'samplerate' then parameter 'samplerate' would
1254 depend on 'card' because the possible values for
1255 'samplerate' depends on the sound card which can be
1256 chosen by the 'card' parameter
1257 (optionally returned, dependent to driver parameter)
1258 </p>
1259 </blockquote>
1260
1261
1262 <p>DEFAULT -
1263 </p>
1264 <blockquote class="text">
1265 <p>reflects the default value for this parameter which is
1266 used when the device is created and not explicitly
1267 given with the <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">'CREATE AUDIO_OUTPUT_DEVICE'<span> (</span><span class="info">Creating an audio output device</span><span>)</span></a> command,
1268 in case of MULTIPLCITY=true, this is a comma separated
1269 list, that's why character strings are encapsulated into
1270 apostrophes (')
1271 (optionally returned, dependent to driver parameter)
1272 </p>
1273 </blockquote>
1274
1275
1276 <p>RANGE_MIN -
1277 </p>
1278 <blockquote class="text">
1279 <p>defines lower limit of the allowed value range for this
1280 parameter, can be an integer value as well as a dotted
1281 number, this parameter is often used in conjunction
1282 with RANGE_MAX, but may also appear without
1283 (optionally returned, dependent to driver parameter)
1284 </p>
1285 </blockquote>
1286
1287
1288 <p>RANGE_MAX -
1289 </p>
1290 <blockquote class="text">
1291 <p>defines upper limit of the allowed value range for this
1292 parameter, can be an integer value as well as a dotted
1293 number, this parameter is often used in conjunction with
1294 RANGE_MIN, but may also appear without
1295 (optionally returned, dependent to driver parameter)
1296 </p>
1297 </blockquote>
1298
1299
1300 <p>POSSIBILITIES -
1301 </p>
1302 <blockquote class="text">
1303 <p>comma separated list of possible values for this
1304 parameter, character strings are encapsulated into
1305 apostrophes
1306 (optionally returned, dependent to driver parameter)
1307 </p>
1308 </blockquote>
1309
1310
1311 </blockquote><p>
1312
1313 </p>
1314 <p>The mentioned fields above don't have to be in particular order.
1315 </p>
1316 <p>Examples:
1317 </p>
1318 <p>
1319 </p>
1320 <blockquote class="text">
1321 <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA CARD"
1322 </p>
1323 <p>S: "DESCRIPTION: sound card to be used"
1324 </p>
1325 <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
1326 </p>
1327 <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1328 </p>
1329 <p>&nbsp;&nbsp;&nbsp;"FIX: true"
1330 </p>
1331 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1332 </p>
1333 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: '0,0'"
1334 </p>
1335 <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: '0,0','1,0','2,0'"
1336 </p>
1337 <p>&nbsp;&nbsp;&nbsp;"."
1338 </p>
1339 </blockquote><p>
1340
1341 </p>
1342 <p>
1343 </p>
1344 <blockquote class="text">
1345 <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE"
1346 </p>
1347 <p>S: "DESCRIPTION: output sample rate in Hz"
1348 </p>
1349 <p>&nbsp;&nbsp;&nbsp;"TYPE: INT"
1350 </p>
1351 <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1352 </p>
1353 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
1354 </p>
1355 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1356 </p>
1357 <p>&nbsp;&nbsp;&nbsp;"DEPENDS: card"
1358 </p>
1359 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"
1360 </p>
1361 <p>&nbsp;&nbsp;&nbsp;"."
1362 </p>
1363 </blockquote><p>
1364
1365 </p>
1366 <p>
1367 </p>
1368 <blockquote class="text">
1369 <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE CARD='0,0'"
1370 </p>
1371 <p>S: "DESCRIPTION: output sample rate in Hz"
1372 </p>
1373 <p>&nbsp;&nbsp;&nbsp;"TYPE: INT"
1374 </p>
1375 <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1376 </p>
1377 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
1378 </p>
1379 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1380 </p>
1381 <p>&nbsp;&nbsp;&nbsp;"DEPENDS: card"
1382 </p>
1383 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"
1384 </p>
1385 <p>&nbsp;&nbsp;&nbsp;"RANGE_MIN: 22050"
1386 </p>
1387 <p>&nbsp;&nbsp;&nbsp;"RANGE_MAX: 96000"
1388 </p>
1389 <p>&nbsp;&nbsp;&nbsp;"."
1390 </p>
1391 </blockquote><p>
1392
1393 </p>
1394 <a name="CREATE AUDIO_OUTPUT_DEVICE"></a><br /><hr />
1395 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
1396 <a name="rfc.section.6.2.5"></a><h3>6.2.5.&nbsp;Creating an audio output device</h3>
1397
1398 <p>Use the following command to create a new audio output device for the desired audio output system:
1399 </p>
1400 <p>
1401 </p>
1402 <blockquote class="text">
1403 <p>CREATE AUDIO_OUTPUT_DEVICE &lt;audio-output-driver&gt; [&lt;param-list&gt;]
1404 </p>
1405 </blockquote><p>
1406
1407 </p>
1408 <p>Where &lt;audio-output-driver&gt; should be replaced by the desired audio
1409 output system as returned by the
1410 <a class="info" href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"<span> (</span><span class="info">Getting all available audio output drivers</span><span>)</span></a>
1411 command and &lt;param-list&gt; by an optional list of driver
1412 specific parameters in form of "key1=val1 key2=val2 ...", where
1413 character string values should be encapsulated into apostrophes (').
1414 Note that there might be drivers which require parameter(s) to be
1415 given with this command. Use the previously described commands in
1416 this chapter to get this information.
1417 </p>
1418 <p>Possible Answers:
1419 </p>
1420 <p>
1421 </p>
1422 <blockquote class="text">
1423 <p>"OK[&lt;device-id&gt;]" -
1424 </p>
1425 <blockquote class="text">
1426 <p>in case the device was successfully created, where
1427 &lt;device-id&gt; is the numerical ID of the new device
1428 </p>
1429 </blockquote>
1430
1431
1432 <p>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1433 </p>
1434 <blockquote class="text">
1435 <p>in case the device was created successfully, where
1436 &lt;device-id&gt; is the numerical ID of the new device, but there
1437 are noteworthy issue(s) related (e.g. sound card doesn't
1438 support given hardware parameters and the driver is using
1439 fall-back values), providing an appropriate warning code and
1440 warning message
1441 </p>
1442 </blockquote>
1443
1444
1445 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1446 </p>
1447 <blockquote class="text">
1448 <p>in case it failed, providing an appropriate error code and error message
1449 </p>
1450 </blockquote>
1451
1452
1453 </blockquote><p>
1454
1455 </p>
1456 <p>Examples:
1457 </p>
1458 <p>
1459 </p>
1460 <blockquote class="text">
1461 <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA"
1462 </p>
1463 <p>S: "OK[0]"
1464 </p>
1465 </blockquote><p>
1466
1467 </p>
1468 <p>
1469 </p>
1470 <blockquote class="text">
1471 <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"
1472 </p>
1473 <p>S: "OK[1]"
1474 </p>
1475 </blockquote><p>
1476
1477 </p>
1478 <a name="DESTROY AUDIO_OUTPUT_DEVICE"></a><br /><hr />
1479 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
1480 <a name="rfc.section.6.2.6"></a><h3>6.2.6.&nbsp;Destroying an audio output device</h3>
1481
1482 <p>Use the following command to destroy a created output device:
1483 </p>
1484 <p>
1485 </p>
1486 <blockquote class="text">
1487 <p>DESTROY AUDIO_OUTPUT_DEVICE &lt;device-id&gt;
1488 </p>
1489 </blockquote><p>
1490
1491 </p>
1492 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1493 audio output device as given by the
1494 <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"<span> (</span><span class="info">Creating an audio output device</span><span>)</span></a>
1495 or <a class="info" href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class="info">Getting all created audio output device list</span><span>)</span></a>
1496 command.
1497 </p>
1498 <p>Possible Answers:
1499 </p>
1500 <p>
1501 </p>
1502 <blockquote class="text">
1503 <p>"OK" -
1504 </p>
1505 <blockquote class="text">
1506 <p>in case the device was successfully destroyed
1507 </p>
1508 </blockquote>
1509
1510
1511 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1512 </p>
1513 <blockquote class="text">
1514 <p>in case the device was destroyed successfully, but there are
1515 noteworthy issue(s) related (e.g. an audio over ethernet
1516 driver was unloaded but the other host might not be
1517 informed about this situation), providing an appropriate
1518 warning code and warning message
1519 </p>
1520 </blockquote>
1521
1522
1523 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1524 </p>
1525 <blockquote class="text">
1526 <p>in case it failed, providing an appropriate error code and
1527 error message
1528 </p>
1529 </blockquote>
1530
1531
1532 </blockquote><p>
1533
1534 </p>
1535 <p>Example:
1536 </p>
1537 <p>
1538 </p>
1539 <blockquote class="text">
1540 <p>C: "DESTROY AUDIO_OUTPUT_DEVICE 0"
1541 </p>
1542 <p>S: "OK"
1543 </p>
1544 </blockquote><p>
1545
1546 </p>
1547 <a name="GET AUDIO_OUTPUT_DEVICES"></a><br /><hr />
1548 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
1549 <a name="rfc.section.6.2.7"></a><h3>6.2.7.&nbsp;Getting all created audio output device count</h3>
1550
1551 <p>Use the following command to count all created audio output devices:
1552 </p>
1553 <p>
1554 </p>
1555 <blockquote class="text">
1556 <p>GET AUDIO_OUTPUT_DEVICES
1557 </p>
1558 </blockquote><p>
1559
1560 </p>
1561 <p>Possible Answers:
1562 </p>
1563 <p>
1564 </p>
1565 <blockquote class="text">
1566 <p>LinuxSampler will answer by sending the current number of all
1567 audio output devices.
1568 </p>
1569 </blockquote><p>
1570
1571 </p>
1572 <p>Example:
1573 </p>
1574 <p>
1575 </p>
1576 <blockquote class="text">
1577 <p>C: "GET AUDIO_OUTPUT_DEVICES"
1578 </p>
1579 <p>S: "4"
1580 </p>
1581 </blockquote><p>
1582
1583 </p>
1584 <a name="LIST AUDIO_OUTPUT_DEVICES"></a><br /><hr />
1585 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
1586 <a name="rfc.section.6.2.8"></a><h3>6.2.8.&nbsp;Getting all created audio output device list</h3>
1587
1588 <p>Use the following command to list all created audio output devices:
1589 </p>
1590 <p>
1591 </p>
1592 <blockquote class="text">
1593 <p>LIST AUDIO_OUTPUT_DEVICES
1594 </p>
1595 </blockquote><p>
1596
1597 </p>
1598 <p>Possible Answers:
1599 </p>
1600 <p>
1601 </p>
1602 <blockquote class="text">
1603 <p>LinuxSampler will answer by sending a comma separated list with
1604 the numerical IDs of all audio output devices.
1605 </p>
1606 </blockquote><p>
1607
1608 </p>
1609 <p>Example:
1610 </p>
1611 <p>
1612 </p>
1613 <blockquote class="text">
1614 <p>C: "LIST AUDIO_OUTPUT_DEVICES"
1615 </p>
1616 <p>S: "0,1,4,5"
1617 </p>
1618 </blockquote><p>
1619
1620 </p>
1621 <a name="GET AUDIO_OUTPUT_DEVICE INFO"></a><br /><hr />
1622 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
1623 <a name="rfc.section.6.2.9"></a><h3>6.2.9.&nbsp;Getting current settings of an audio output device</h3>
1624
1625 <p>Use the following command to get current settings of a specific, created audio output device:
1626 </p>
1627 <p>
1628 </p>
1629 <blockquote class="text">
1630 <p>GET AUDIO_OUTPUT_DEVICE INFO &lt;device-id&gt;
1631 </p>
1632 </blockquote><p>
1633
1634 </p>
1635 <p>Where &lt;device-id&gt; should be replaced by numerical ID
1636 of the audio output device as e.g. returned by the
1637 <a class="info" href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class="info">Getting all created audio output device list</span><span>)</span></a> command.
1638 </p>
1639 <p>Possible Answers:
1640 </p>
1641 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1642 Each answer line begins with the information category name
1643 followed by a colon and then a space character &lt;SP&gt; and finally
1644 the info character string to that info category. As some
1645 parameters might allow multiple values, character strings are
1646 encapsulated into apostrophes ('). At the moment the following
1647 information categories are defined (independently of device):
1648 </p>
1649 <p>
1650 </p>
1651 <blockquote class="text">
1652 <p>DRIVER -
1653 </p>
1654 <blockquote class="text">
1655 <p>identifier of the used audio output driver, as also
1656 returned by the
1657 <a class="info" href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"<span> (</span><span class="info">Getting all available audio output drivers</span><span>)</span></a>
1658 command
1659 </p>
1660 </blockquote>
1661
1662
1663 <p>CHANNELS -
1664 </p>
1665 <blockquote class="text">
1666 <p>amount of audio output channels this device currently
1667 offers
1668 </p>
1669 </blockquote>
1670
1671
1672 <p>SAMPLERATE -
1673 </p>
1674 <blockquote class="text">
1675 <p>playback sample rate the device uses
1676 </p>
1677 </blockquote>
1678
1679
1680 <p>ACTIVE -
1681 </p>
1682 <blockquote class="text">
1683 <p>either true or false, if false then the audio device is
1684 inactive and doesn't output any sound, nor do the
1685 sampler channels connected to this audio device render
1686 any audio
1687 </p>
1688 </blockquote>
1689
1690
1691 </blockquote><p>
1692
1693 </p>
1694 <p>The mentioned fields above don't have to be in particular
1695 order. The fields above are only those fields which are
1696 returned by all audio output devices. Every audio output driver
1697 might have its own, additional driver specific parameters (see
1698 <a class="info" href="#GET AUDIO_OUTPUT_DRIVER INFO">Section&nbsp;6.2.3<span> (</span><span class="info">Getting information about a specific audio output driver</span><span>)</span></a>)
1699 which are also returned by this command.
1700 </p>
1701 <p>Example:
1702 </p>
1703 <p>
1704 </p>
1705 <blockquote class="text">
1706 <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
1707 </p>
1708 <p>S: "DRIVER: ALSA"
1709 </p>
1710 <p>&nbsp;&nbsp;&nbsp;"CHANNELS: 2"
1711 </p>
1712 <p>&nbsp;&nbsp;&nbsp;"SAMPLERATE: 44100"
1713 </p>
1714 <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
1715 </p>
1716 <p>&nbsp;&nbsp;&nbsp;"FRAGMENTS: 2"
1717 </p>
1718 <p>&nbsp;&nbsp;&nbsp;"FRAGMENTSIZE: 128"
1719 </p>
1720 <p>&nbsp;&nbsp;&nbsp;"CARD: '0,0'"
1721 </p>
1722 <p>&nbsp;&nbsp;&nbsp;"."
1723 </p>
1724 </blockquote><p>
1725
1726 </p>
1727 <a name="SET AUDIO_OUTPUT_DEVICE_PARAMETER"></a><br /><hr />
1728 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
1729 <a name="rfc.section.6.2.10"></a><h3>6.2.10.&nbsp;Changing settings of audio output devices</h3>
1730
1731 <p>Use the following command to alter a specific setting of a created audio output device:
1732 </p>
1733 <p>
1734 </p>
1735 <blockquote class="text">
1736 <p>SET AUDIO_OUTPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;
1737 </p>
1738 </blockquote><p>
1739
1740 </p>
1741 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1742 audio output device as given by the
1743 <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"<span> (</span><span class="info">Creating an audio output device</span><span>)</span></a>
1744 or <a class="info" href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class="info">Getting all created audio output device list</span><span>)</span></a>
1745 command, &lt;key&gt; by the name of the parameter to change
1746 and &lt;value&gt; by the new value for this parameter.
1747 </p>
1748 <p>Possible Answers:
1749 </p>
1750 <p>
1751 </p>
1752 <blockquote class="text">
1753 <p>"OK" -
1754 </p>
1755 <blockquote class="text">
1756 <p>in case setting was successfully changed
1757 </p>
1758 </blockquote>
1759
1760
1761 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1762 </p>
1763 <blockquote class="text">
1764 <p>in case setting was changed successfully, but there are
1765 noteworthy issue(s) related, providing an appropriate
1766 warning code and warning message
1767 </p>
1768 </blockquote>
1769
1770
1771 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1772 </p>
1773 <blockquote class="text">
1774 <p>in case it failed, providing an appropriate error code and
1775 error message
1776 </p>
1777 </blockquote>
1778
1779
1780 </blockquote><p>
1781
1782 </p>
1783 <p>Example:
1784 </p>
1785 <p>
1786 </p>
1787 <blockquote class="text">
1788 <p>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"
1789 </p>
1790 <p>S: "OK"
1791 </p>
1792 </blockquote><p>
1793
1794 </p>
1795 <a name="GET AUDIO_OUTPUT_CHANNEL INFO"></a><br /><hr />
1796 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
1797 <a name="rfc.section.6.2.11"></a><h3>6.2.11.&nbsp;Getting information about an audio channel</h3>
1798
1799 <p>Use the following command to get information about an audio channel:
1800 </p>
1801 <p>
1802 </p>
1803 <blockquote class="text">
1804 <p>GET AUDIO_OUTPUT_CHANNEL INFO &lt;device-id&gt; &lt;audio-chan&gt;
1805 </p>
1806 </blockquote><p>
1807
1808 </p>
1809 <p>Where &lt;device-id&gt; is the numerical ID of the audio output device as given by the
1810 <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"<span> (</span><span class="info">Creating an audio output device</span><span>)</span></a>
1811 or <a class="info" href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class="info">Getting all created audio output device list</span><span>)</span></a>
1812 command and &lt;audio-chan&gt; the audio channel number.
1813 </p>
1814 <p>Possible Answers:
1815 </p>
1816 <p>
1817 </p>
1818 <blockquote class="text">
1819 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1820 Each answer line begins with the information category name
1821 followed by a colon and then a space character &lt;SP&gt; and finally
1822 the info character string to that info category. At the moment
1823 the following information categories are defined:
1824 </p>
1825 <p>
1826 </p>
1827 <blockquote class="text">
1828 <p>NAME -
1829 </p>
1830 <blockquote class="text">
1831 <p>arbitrary character string naming the channel, which
1832 doesn't have to be unique (always returned by all audio channels)
1833 </p>
1834 </blockquote>
1835
1836
1837 <p>IS_MIX_CHANNEL -
1838 </p>
1839 <blockquote class="text">
1840 <p>either true or false, a mix-channel is not a real,
1841 independent audio channel, but a virtual channel which
1842 is mixed to another real channel, this mechanism is
1843 needed for sampler engines which need more audio
1844 channels than the used audio system might be able to offer
1845 (always returned by all audio channels)
1846 </p>
1847 </blockquote>
1848
1849
1850 <p>MIX_CHANNEL_DESTINATION -
1851 </p>
1852 <blockquote class="text">
1853 <p>numerical ID (positive integer including 0)
1854 which reflects the real audio channel (of the same audio
1855 output device) this mix channel refers to, means where
1856 the audio signal actually will be routed / added to
1857 (only returned in case the audio channel is mix channel)
1858 </p>
1859 </blockquote>
1860
1861
1862 </blockquote>
1863
1864
1865 </blockquote><p>
1866
1867 </p>
1868 <p>The mentioned fields above don't have to be in particular
1869 order. The fields above are only those fields which are
1870 generally returned for the described cases by all audio
1871 channels regardless of the audio driver. Every audio channel
1872 might have its own, additional driver and channel specific
1873 parameters.
1874 </p>
1875 <p>Examples:
1876 </p>
1877 <p>
1878 </p>
1879 <blockquote class="text">
1880 <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 0"
1881 </p>
1882 <p>S: "NAME: studio monitor left"
1883 </p>
1884 <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
1885 </p>
1886 <p>&nbsp;&nbsp;&nbsp;"."
1887 </p>
1888 </blockquote><p>
1889
1890 </p>
1891 <p>
1892 </p>
1893 <blockquote class="text">
1894 <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 1"
1895 </p>
1896 <p>S: "NAME: studio monitor right"
1897 </p>
1898 <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
1899 </p>
1900 <p>&nbsp;&nbsp;&nbsp;"."
1901 </p>
1902 </blockquote><p>
1903
1904 </p>
1905 <p>
1906 </p>
1907 <blockquote class="text">
1908 <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"
1909 </p>
1910 <p>S: "NAME: studio monitor left"
1911 </p>
1912 <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: true"
1913 </p>
1914 <p>&nbsp;&nbsp;&nbsp;"MIX_CHANNEL_DESTINATION: 1"
1915 </p>
1916 <p>&nbsp;&nbsp;&nbsp;"."
1917 </p>
1918 </blockquote><p>
1919
1920 </p>
1921 <p>
1922 </p>
1923 <blockquote class="text">
1924 <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"
1925 </p>
1926 <p>S: "NAME: 'ardour (left)'"
1927 </p>
1928 <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
1929 </p>
1930 <p>&nbsp;&nbsp;&nbsp;"JACK_BINDINGS: 'ardour:0'"
1931 </p>
1932 <p>&nbsp;&nbsp;&nbsp;"."
1933 </p>
1934 </blockquote><p>
1935
1936 </p>
1937 <a name="GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO"></a><br /><hr />
1938 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
1939 <a name="rfc.section.6.2.12"></a><h3>6.2.12.&nbsp;Getting information about specific audio channel parameter</h3>
1940
1941 <p>Use the following command to get detailed information about specific audio channel parameter:
1942 </p>
1943 <p>
1944 </p>
1945 <blockquote class="text">
1946 <p>GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO &lt;dev-id&gt; &lt;chan&gt; &lt;param&gt;
1947 </p>
1948 </blockquote><p>
1949
1950 </p>
1951 <p>Where &lt;dev-id&gt; is the numerical ID of the audio output device as returned by the
1952 <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"<span> (</span><span class="info">Creating an audio output device</span><span>)</span></a>
1953 or <a class="info" href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class="info">Getting all created audio output device list</span><span>)</span></a>
1954 command, &lt;chan&gt; the audio channel number
1955 and &lt;param&gt; a specific channel parameter name for which information should
1956 be obtained (as returned by the <a class="info" href="#GET AUDIO_OUTPUT_CHANNEL INFO">"GET AUDIO_OUTPUT_CHANNEL INFO"<span> (</span><span class="info">Getting information about an audio channel</span><span>)</span></a> command).
1957 </p>
1958 <p>Possible Answers:
1959 </p>
1960 <p>
1961 </p>
1962 <blockquote class="text">
1963 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1964 Each answer line begins with the information category name
1965 followed by a colon and then a space character &lt;SP&gt; and finally
1966 the info character string to that info category. There are
1967 information which is always returned, independently of the
1968 given channel parameter and there is optional information
1969 which is only shown dependently to the given audio channel. At
1970 the moment the following information categories are defined:
1971 </p>
1972 <p>
1973 </p>
1974 <blockquote class="text">
1975 <p>TYPE -
1976 </p>
1977 <blockquote class="text">
1978 <p>either "BOOL" for boolean value(s) or "INT" for integer
1979 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1980 character string(s)
1981 (always returned)
1982 </p>
1983 </blockquote>
1984
1985
1986 <p>DESCRIPTION -
1987 </p>
1988 <blockquote class="text">
1989 <p>arbitrary text describing the purpose of the parameter (always returned)
1990 </p>
1991 </blockquote>
1992
1993
1994 <p>FIX -
1995 </p>
1996 <blockquote class="text">
1997 <p>either true or false, if true then this parameter is
1998 read only, thus cannot be altered
1999 (always returned)
2000 </p>
2001 </blockquote>
2002
2003
2004 <p>MULTIPLICITY -
2005 </p>
2006 <blockquote class="text">
2007 <p>either true or false, defines if this parameter allows
2008 only one value or a list of values, where true means
2009 multiple values and false only a single value allowed
2010 (always returned)
2011 </p>
2012 </blockquote>
2013
2014
2015 <p>RANGE_MIN -
2016 </p>
2017 <blockquote class="text">
2018 <p>defines lower limit of the allowed value range for this
2019 parameter, can be an integer value as well as a dotted
2020 number, usually used in conjunction with 'RANGE_MAX',
2021 but may also appear without
2022 (optionally returned, dependent to driver and channel
2023 parameter)
2024 </p>
2025 </blockquote>
2026
2027
2028 <p>RANGE_MAX -
2029 </p>
2030 <blockquote class="text">
2031 <p>defines upper limit of the allowed value range for this
2032 parameter, can be an integer value as well as a dotted
2033 number, usually used in conjunction with 'RANGE_MIN',
2034 but may also appear without
2035 (optionally returned, dependent to driver and channel
2036 parameter)
2037 </p>
2038 </blockquote>
2039
2040
2041 <p>POSSIBILITIES -
2042 </p>
2043 <blockquote class="text">
2044 <p>comma separated list of possible values for this
2045 parameter, character strings are encapsulated into
2046 apostrophes
2047 (optionally returned, dependent to driver and channel
2048 parameter)
2049 </p>
2050 </blockquote>
2051
2052
2053 </blockquote>
2054
2055
2056 <p>The mentioned fields above don't have to be in particular order.
2057 </p>
2058 </blockquote><p>
2059
2060 </p>
2061 <p>Example:
2062 </p>
2063 <p>
2064 </p>
2065 <blockquote class="text">
2066 <p>C: "GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO 1 0 JACK_BINDINGS"
2067 </p>
2068 <p>S: "DESCRIPTION: bindings to other JACK clients"
2069 </p>
2070 <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
2071 </p>
2072 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
2073 </p>
2074 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"
2075 </p>
2076 <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"
2077 </p>
2078 <p>&nbsp;&nbsp;&nbsp;"."
2079 </p>
2080 </blockquote><p>
2081
2082 </p>
2083 <a name="SET AUDIO_OUTPUT_CHANNEL_PARAMETER"></a><br /><hr />
2084 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
2085 <a name="rfc.section.6.2.13"></a><h3>6.2.13.&nbsp;Changing settings of audio output channels</h3>
2086
2087 <p>Use the following command to alter a specific setting of an audio output channel:
2088 </p>
2089 <p>
2090 </p>
2091 <blockquote class="text">
2092 <p>SET AUDIO_OUTPUT_CHANNEL_PARAMETER &lt;dev-id&gt; &lt;chn&gt; &lt;key&gt;=&lt;value&gt;
2093 </p>
2094 </blockquote><p>
2095
2096 </p>
2097 <p>Where &lt;dev-id&gt; should be replaced by the numerical ID of the audio output device as returned by the
2098 <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"<span> (</span><span class="info">Creating an audio output device</span><span>)</span></a>
2099 or <a class="info" href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class="info">Getting all created audio output device list</span><span>)</span></a>
2100 command, &lt;chn&gt; by the audio channel number, &lt;key&gt; by the name of the
2101 parameter to change and &lt;value&gt; by the new value for this parameter.
2102 </p>
2103 <p>Possible Answers:
2104 </p>
2105 <p>
2106 </p>
2107 <blockquote class="text">
2108 <p>"OK" -
2109 </p>
2110 <blockquote class="text">
2111 <p>in case setting was successfully changed
2112 </p>
2113 </blockquote>
2114
2115
2116 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2117 </p>
2118 <blockquote class="text">
2119 <p>in case setting was changed successfully, but there are
2120 noteworthy issue(s) related, providing an appropriate
2121 warning code and warning message
2122 </p>
2123 </blockquote>
2124
2125
2126 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2127 </p>
2128 <blockquote class="text">
2129 <p>in case it failed, providing an appropriate error code and
2130 error message
2131 </p>
2132 </blockquote>
2133
2134
2135 </blockquote><p>
2136
2137 </p>
2138 <p>Example:
2139 </p>
2140 <p>
2141 </p>
2142 <blockquote class="text">
2143 <p>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"
2144 </p>
2145 <p>S: "OK"
2146 </p>
2147 </blockquote><p>
2148
2149 </p>
2150 <p>
2151 </p>
2152 <blockquote class="text">
2153 <p>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"
2154 </p>
2155 <p>S: "OK"
2156 </p>
2157 </blockquote><p>
2158
2159 </p>
2160 <a name="anchor10"></a><br /><hr />
2161 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
2162 <a name="rfc.section.6.3"></a><h3>6.3.&nbsp;Configuring MIDI input drivers</h3>
2163
2164 <p>Instances of drivers in LinuxSampler are called devices. You can use
2165 multiple MIDI devices simultaneously, e.g. to use MIDI over ethernet as
2166 MIDI input on one sampler channel and ALSA as MIDI input on another sampler
2167 channel. For particular MIDI input systems it's also possible to create
2168 several devices of the same MIDI input type. This chapter describes all
2169 commands to configure LinuxSampler's MIDI input devices and their parameters.
2170 </p>
2171 <p>Instead of defining commands and parameters for each driver individually,
2172 all possible parameters, their meanings and possible values have to be obtained
2173 at runtime. This makes the protocol a bit abstract, but has the advantage, that
2174 front-ends can be written independently of what drivers are currently implemented
2175 and what parameters these drivers are actually offering. This means front-ends can
2176 even handle drivers which are implemented somewhere in future without modifying
2177 the front-end at all.
2178 </p>
2179 <p>Commands for configuring MIDI input devices are pretty much the same as the
2180 commands for configuring audio output drivers, already described in the last
2181 chapter.
2182 </p>
2183 <p>Note: examples in this chapter showing particular parameters of drivers are
2184 not meant as specification of the drivers' parameters. Driver implementations in
2185 LinuxSampler might have complete different parameter names and meanings than shown
2186 in these examples or might change in future, so these examples are only meant for
2187 showing how to retrieve what parameters drivers are offering, how to retrieve their
2188 possible values, etc.
2189 </p>
2190 <a name="GET AVAILABLE_MIDI_INPUT_DRIVERS"></a><br /><hr />
2191 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
2192 <a name="rfc.section.6.3.1"></a><h3>6.3.1.&nbsp;Getting amount of available MIDI input drivers</h3>
2193
2194 <p>Use the following command to get the number of
2195 MIDI input drivers currently available for the
2196 LinuxSampler instance:
2197 </p>
2198 <p>
2199 </p>
2200 <blockquote class="text">
2201 <p>GET AVAILABLE_MIDI_INPUT_DRIVERS
2202 </p>
2203 </blockquote><p>
2204
2205 </p>
2206 <p>Possible Answers:
2207 </p>
2208 <p>
2209 </p>
2210 <blockquote class="text">
2211 <p>LinuxSampler will answer by sending the
2212 number of available MIDI input drivers.
2213 </p>
2214 </blockquote><p>
2215
2216 </p>
2217 <p>Example:
2218 </p>
2219 <p>
2220 </p>
2221 <blockquote class="text">
2222 <p>C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"
2223 </p>
2224 <p>S: "2"
2225 </p>
2226 </blockquote><p>
2227
2228 </p>
2229 <a name="LIST AVAILABLE_MIDI_INPUT_DRIVERS"></a><br /><hr />
2230 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
2231 <a name="rfc.section.6.3.2"></a><h3>6.3.2.&nbsp;Getting all available MIDI input drivers</h3>
2232
2233 <p>Use the following command to list all MIDI input drivers currently available
2234 for the LinuxSampler instance:
2235 </p>
2236 <p>
2237 </p>
2238 <blockquote class="text">
2239 <p>LIST AVAILABLE_MIDI_INPUT_DRIVERS
2240 </p>
2241 </blockquote><p>
2242
2243 </p>
2244 <p>Possible Answers:
2245 </p>
2246 <p>
2247 </p>
2248 <blockquote class="text">
2249 <p>LinuxSampler will answer by sending comma separated character
2250 strings, each symbolizing a MIDI input driver.
2251 </p>
2252 </blockquote><p>
2253
2254 </p>
2255 <p>Example:
2256 </p>
2257 <p>
2258 </p>
2259 <blockquote class="text">
2260 <p>C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
2261 </p>
2262 <p>S: "ALSA,JACK"
2263 </p>
2264 </blockquote><p>
2265
2266 </p>
2267 <a name="GET MIDI_INPUT_DRIVER INFO"></a><br /><hr />
2268 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
2269 <a name="rfc.section.6.3.3"></a><h3>6.3.3.&nbsp;Getting information about a specific MIDI input driver</h3>
2270
2271 <p>Use the following command to get detailed information about a specific MIDI input driver:
2272 </p>
2273 <p>
2274 </p>
2275 <blockquote class="text">
2276 <p>GET MIDI_INPUT_DRIVER INFO &lt;midi-input-driver&gt;
2277 </p>
2278 </blockquote><p>
2279
2280 </p>
2281 <p>Where &lt;midi-input-driver&gt; is the name of the MIDI input driver as returned
2282 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.
2283 </p>
2284 <p>Possible Answers:
2285 </p>
2286 <p>
2287 </p>
2288 <blockquote class="text">
2289 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2290 Each answer line begins with the information category name
2291 followed by a colon and then a space character &lt;SP&gt; and finally
2292 the info character string to that info category. At the moment
2293 the following information categories are defined:
2294 </p>
2295 <p>
2296 </p>
2297 <blockquote class="text">
2298 <p>DESCRIPTION -
2299 </p>
2300 <blockquote class="text">
2301 <p>arbitrary description text about the MIDI input driver
2302 </p>
2303 </blockquote>
2304
2305
2306 <p>VERSION -
2307 </p>
2308 <blockquote class="text">
2309 <p>arbitrary character string regarding the driver's version
2310 </p>
2311 </blockquote>
2312
2313
2314 <p>PARAMETERS -
2315 </p>
2316 <blockquote class="text">
2317 <p>comma separated list of all parameters available for the given MIDI input driver
2318 </p>
2319 </blockquote>
2320
2321
2322 </blockquote>
2323
2324
2325 <p>The mentioned fields above don't have to be in particular order.
2326 </p>
2327 </blockquote><p>
2328
2329 </p>
2330 <p>Example:
2331 </p>
2332 <p>
2333 </p>
2334 <blockquote class="text">
2335 <p>C: "GET MIDI_INPUT_DRIVER INFO ALSA"
2336 </p>
2337 <p>S: "DESCRIPTION: Advanced Linux Sound Architecture"
2338 </p>
2339 <p>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"
2340 </p>
2341 <p>&nbsp;&nbsp;&nbsp;"PARAMETERS: DRIVER,ACTIVE"
2342 </p>
2343 <p>&nbsp;&nbsp;&nbsp;"."
2344 </p>
2345 </blockquote><p>
2346
2347 </p>
2348 <a name="GET MIDI_INPUT_DRIVER_PARAMETER INFO"></a><br /><hr />
2349 <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>
2350 <a name="rfc.section.6.3.4"></a><h3>6.3.4.&nbsp;Getting information about specific MIDI input driver parameter</h3>
2351
2352 <p>Use the following command to get detailed information about a specific parameter of a specific MIDI input driver:
2353 </p>
2354 <p>
2355 </p>
2356 <blockquote class="text">
2357 <p>GET MIDI_INPUT_DRIVER_PARAMETER INFO &lt;midit&gt; &lt;param&gt; [&lt;deplist&gt;]
2358 </p>
2359 </blockquote><p>
2360
2361 </p>
2362 <p>Where &lt;midit&gt; is the name of the MIDI input driver as returned
2363 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, &lt;param&gt; a specific
2364 parameter name for which information should be obtained (as returned by the
2365 <a class="info" href="#GET MIDI_INPUT_DRIVER INFO">"GET MIDI_INPUT_DRIVER INFO"<span> (</span><span class="info">Getting information about a specific MIDI input driver</span><span>)</span></a> command) and &lt;deplist&gt; is an optional list
2366 of parameters on which the sought parameter &lt;param&gt; depends on,
2367 &lt;deplist&gt; is a key-value pair list in form of "key1=val1 key2=val2 ...",
2368 where character string values are encapsulated into apostrophes ('). Arguments
2369 given with &lt;deplist&gt; which are not dependency parameters of &lt;param&gt;
2370 will be ignored, means the front-end application can simply put all parameters
2371 in &lt;deplist&gt; with the values selected by the user.
2372 </p>
2373 <p>Possible Answers:
2374 </p>
2375 <p>LinuxSampler will answer by sending a &lt;CRLF> separated list.
2376 Each answer line begins with the information category name
2377 followed by a colon and then a space character &lt;SP> and finally
2378 the info character string to that info category. There is
2379 information which is always returned, independent of the
2380 given driver parameter and there is optional information
2381 which is only shown dependent to given driver parameter. At
2382 the moment the following information categories are defined:
2383 </p>
2384 <p>
2385 </p>
2386 <blockquote class="text">
2387 <p>TYPE -
2388 </p>
2389 <blockquote class="text">
2390 <p>either "BOOL" for boolean value(s) or "INT" for integer
2391 value(s) or "FLOAT" for dotted number(s) or "STRING" for
2392 character string(s)
2393 (always returned, no matter which driver parameter)
2394 </p>
2395 </blockquote>
2396
2397
2398 <p>DESCRIPTION -
2399 </p>
2400 <blockquote class="text">
2401 <p>arbitrary text describing the purpose of the parameter
2402 (always returned, no matter which driver parameter)
2403 </p>
2404 </blockquote>
2405
2406
2407 <p>MANDATORY -
2408 </p>
2409 <blockquote class="text">
2410 <p>either true or false, defines if this parameter must be
2411 given when the device is to be created with the
2412 <a class="info" href="#CREATE MIDI_INPUT_DEVICE">'CREATE MIDI_INPUT_DEVICE'<span> (</span><span class="info">Creating a MIDI input device</span><span>)</span></a> command
2413 (always returned, no matter which driver parameter)
2414 </p>
2415 </blockquote>
2416
2417
2418 <p>FIX -
2419 </p>
2420 <blockquote class="text">
2421 <p>either true or false, if false then this parameter can
2422 be changed at any time, once the device is created by
2423 the <a class="info" href="#CREATE MIDI_INPUT_DEVICE">'CREATE MIDI_INPUT_DEVICE'<span> (</span><span class="info">Creating a MIDI input device</span><span>)</span></a> command
2424 (always returned, no matter which driver parameter)
2425 </p>
2426 </blockquote>
2427
2428
2429 <p>MULTIPLICITY -
2430 </p>
2431 <blockquote class="text">
2432 <p>either true or false, defines if this parameter allows
2433 only one value or a list of values, where true means
2434 multiple values and false only a single value allowed
2435 (always returned, no matter which driver parameter)
2436 </p>
2437 </blockquote>
2438
2439
2440 <p>DEPENDS -
2441 </p>
2442 <blockquote class="text">
2443 <p>comma separated list of parameters this parameter depends
2444 on, means the values for fields 'DEFAULT', 'RANGE_MIN',
2445 'RANGE_MAX' and 'POSSIBILITIES' might depend on these
2446 listed parameters, for example assuming that an audio
2447 driver (like the ALSA driver) offers parameters 'card'
2448 and 'samplerate' then parameter 'samplerate' would
2449 depend on 'card' because the possible values for
2450 'samplerate' depends on the sound card which can be
2451 chosen by the 'card' parameter
2452 (optionally returned, dependent to driver parameter)
2453 </p>
2454 </blockquote>
2455
2456
2457 <p>DEFAULT -
2458 </p>
2459 <blockquote class="text">
2460 <p>reflects the default value for this parameter which is
2461 used when the device is created and not explicitly
2462 given with the <a class="info" href="#CREATE MIDI_INPUT_DEVICE">'CREATE MIDI_INPUT_DEVICE'<span> (</span><span class="info">Creating a MIDI input device</span><span>)</span></a> command,
2463 in case of MULTIPLCITY=true, this is a comma separated
2464 list, that's why character strings are encapsulated into
2465 apostrophes (')
2466 (optionally returned, dependent to driver parameter)
2467 </p>
2468 </blockquote>
2469
2470
2471 <p>RANGE_MIN -
2472 </p>
2473 <blockquote class="text">
2474 <p>defines lower limit of the allowed value range for this
2475 parameter, can be an integer value as well as a dotted
2476 number, this parameter is often used in conjunction
2477 with RANGE_MAX, but may also appear without
2478 (optionally returned, dependent to driver parameter)
2479 </p>
2480 </blockquote>
2481
2482
2483 <p>RANGE_MAX -
2484 </p>
2485 <blockquote class="text">
2486 <p>defines upper limit of the allowed value range for this
2487 parameter, can be an integer value as well as a dotted
2488 number, this parameter is often used in conjunction with
2489 RANGE_MIN, but may also appear without
2490 (optionally returned, dependent to driver parameter)
2491 </p>
2492 </blockquote>
2493
2494
2495 <p>POSSIBILITIES -
2496 </p>
2497 <blockquote class="text">
2498 <p>comma separated list of possible values for this
2499 parameter, character strings are encapsulated into
2500 apostrophes
2501 (optionally returned, dependent to driver parameter)
2502 </p>
2503 </blockquote>
2504
2505
2506 </blockquote><p>
2507
2508 </p>
2509 <p>The mentioned fields above don't have to be in particular order.
2510 </p>
2511 <p>Example:
2512 </p>
2513 <p>
2514 </p>
2515 <blockquote class="text">
2516 <p>C: "GET MIDI_INPUT_DRIVER_PARAMETER INFO ALSA ACTIVE"
2517 </p>
2518 <p>S: "DESCRIPTION: Whether device is enabled"
2519 </p>
2520 <p>&nbsp;&nbsp;&nbsp;"TYPE: BOOL"
2521 </p>
2522 <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
2523 </p>
2524 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
2525 </p>
2526 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
2527 </p>
2528 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: true"
2529 </p>
2530 <p>&nbsp;&nbsp;&nbsp;"."
2531 </p>
2532 </blockquote><p>
2533
2534 </p>
2535 <a name="CREATE MIDI_INPUT_DEVICE"></a><br /><hr />
2536 <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>
2537 <a name="rfc.section.6.3.5"></a><h3>6.3.5.&nbsp;Creating a MIDI input device</h3>
2538
2539 <p>Use the following command to create a new MIDI input device for the desired MIDI input system:
2540 </p>
2541 <p>
2542 </p>
2543 <blockquote class="text">
2544 <p>CREATE MIDI_INPUT_DEVICE &lt;midi-input-driver&gt; [&lt;param-list&gt;]
2545 </p>
2546 </blockquote><p>
2547
2548 </p>
2549 <p>Where &lt;midi-input-driver&gt; should be replaced by the desired MIDI input system as returned
2550 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 and &lt;param-list&gt; by an
2551 optional list of driver specific parameters in form of "key1=val1 key2=val2 ...", where
2552 character string values should be encapsulated into apostrophes (').
2553 Note that there might be drivers which require parameter(s) to be
2554 given with this command. Use the previously described commands in
2555 this chapter to get that information.
2556 </p>
2557 <p>Possible Answers:
2558 </p>
2559 <p>
2560 </p>
2561 <blockquote class="text">
2562 <p>"OK[&lt;device-id&gt;]" -
2563 </p>
2564 <blockquote class="text">
2565 <p>in case the device was successfully created, where
2566 &lt;device-id&gt; is the numerical ID of the new device
2567 </p>
2568 </blockquote>
2569
2570
2571 <p>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2572 </p>
2573 <blockquote class="text">
2574 <p>in case the driver was loaded successfully, where
2575 &lt;device-id&gt; is the numerical ID of the new device, but
2576 there are noteworthy issue(s) related, providing an
2577 appropriate warning code and warning message
2578 </p>
2579 </blockquote>
2580
2581
2582 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2583 </p>
2584 <blockquote class="text">
2585 <p>in case it failed, providing an appropriate error code and error message
2586 </p>
2587 </blockquote>
2588
2589
2590 </blockquote><p>
2591
2592 </p>
2593 <p>Example:
2594 </p>
2595 <p>
2596 </p>
2597 <blockquote class="text">
2598 <p>C: "CREATE MIDI_INPUT_DEVICE ALSA"
2599 </p>
2600 <p>S: "OK[0]"
2601 </p>
2602 </blockquote><p>
2603
2604 </p>
2605 <a name="DESTROY MIDI_INPUT_DEVICE"></a><br /><hr />
2606 <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>
2607 <a name="rfc.section.6.3.6"></a><h3>6.3.6.&nbsp;Destroying a MIDI input device</h3>
2608
2609 <p>Use the following command to destroy a created MIDI input device:
2610 </p>
2611 <p>
2612 </p>
2613 <blockquote class="text">
2614 <p>DESTROY MIDI_INPUT_DEVICE &lt;device-id&gt;
2615 </p>
2616 </blockquote><p>
2617
2618 </p>
2619 <p>Where &lt;device-id&gt; should be replaced by the device's numerical ID as returned by the
2620 <a class="info" href="#CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"<span> (</span><span class="info">Creating a MIDI input device</span><span>)</span></a>
2621 or <a class="info" href="#LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"<span> (</span><span class="info">Getting all created MIDI input device list</span><span>)</span></a>
2622 command.
2623 </p>
2624 <p>Possible Answers:
2625 </p>
2626 <p>
2627 </p>
2628 <blockquote class="text">
2629 <p>"OK" -
2630 </p>
2631 <blockquote class="text">
2632 <p>in case the device was successfully destroyed
2633 </p>
2634 </blockquote>
2635
2636
2637 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2638 </p>
2639 <blockquote class="text">
2640 <p>in case the device was destroyed, but there are noteworthy
2641 issue(s) related, providing an appropriate warning code and
2642 warning message
2643 </p>
2644 </blockquote>
2645
2646
2647 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2648 </p>
2649 <blockquote class="text">
2650 <p>in case it failed, providing an appropriate error code and error message
2651 </p>
2652 </blockquote>
2653
2654
2655 </blockquote><p>
2656
2657 </p>
2658 <p>Example:
2659 </p>
2660 <p>
2661 </p>
2662 <blockquote class="text">
2663 <p>C: "DESTROY MIDI_INPUT_DEVICE 0"
2664 </p>
2665 <p>S: "OK"
2666 </p>
2667 </blockquote><p>
2668
2669 </p>
2670 <a name="GET MIDI_INPUT_DEVICES"></a><br /><hr />
2671 <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>
2672 <a name="rfc.section.6.3.7"></a><h3>6.3.7.&nbsp;Getting all created MIDI input device count</h3>
2673
2674 <p>Use the following command to count all created MIDI input devices:
2675 </p>
2676 <p>
2677 </p>
2678 <blockquote class="text">
2679 <p>GET MIDI_INPUT_DEVICES
2680 </p>
2681 </blockquote><p>
2682
2683 </p>
2684 <p>Possible Answers:
2685 </p>
2686 <p>
2687 </p>
2688 <blockquote class="text">
2689 <p>LinuxSampler will answer by sending the current number of all
2690 MIDI input devices.
2691 </p>
2692 </blockquote><p>
2693
2694 </p>
2695 <p>Example:
2696 </p>
2697 <p>
2698 </p>
2699 <blockquote class="text">
2700 <p>C: "GET MIDI_INPUT_DEVICES"
2701 </p>
2702 <p>S: "3"
2703 </p>
2704 </blockquote><p>
2705
2706 </p>
2707 <a name="LIST MIDI_INPUT_DEVICES"></a><br /><hr />
2708 <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>
2709 <a name="rfc.section.6.3.8"></a><h3>6.3.8.&nbsp;Getting all created MIDI input device list</h3>
2710
2711 <p>Use the following command to list all created MIDI input devices:
2712 </p>
2713 <p>
2714 </p>
2715 <blockquote class="text">
2716 <p>LIST MIDI_INPUT_DEVICES
2717 </p>
2718 </blockquote><p>
2719
2720 </p>
2721 <p>Possible Answers:
2722 </p>
2723 <p>
2724 </p>
2725 <blockquote class="text">
2726 <p>LinuxSampler will answer by sending a comma separated list
2727 with the numerical Ids of all created MIDI input devices.
2728 </p>
2729 </blockquote><p>
2730
2731 </p>
2732 <p>Examples:
2733 </p>
2734 <p>
2735 </p>
2736 <blockquote class="text">
2737 <p>C: "LIST MIDI_INPUT_DEVICES"
2738 </p>
2739 <p>S: "0,1,2"
2740 </p>
2741 </blockquote><p>
2742
2743 </p>
2744 <p>
2745 </p>
2746 <blockquote class="text">
2747 <p>C: "LIST MIDI_INPUT_DEVICES"
2748 </p>
2749 <p>S: "1,3"
2750 </p>
2751 </blockquote><p>
2752
2753 </p>
2754 <a name="GET MIDI_INPUT_DEVICE INFO"></a><br /><hr />
2755 <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>
2756 <a name="rfc.section.6.3.9"></a><h3>6.3.9.&nbsp;Getting current settings of a MIDI input device</h3>
2757
2758 <p>Use the following command to get current settings of a specific, created MIDI input device:
2759 </p>
2760 <p>
2761 </p>
2762 <blockquote class="text">
2763 <p>GET MIDI_INPUT_DEVICE INFO &lt;device-id&gt;
2764 </p>
2765 </blockquote><p>
2766
2767 </p>
2768 <p>Where &lt;device-id&gt; is the numerical ID of the MIDI input device as returned by the
2769 <a class="info" href="#CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"<span> (</span><span class="info">Creating a MIDI input device</span><span>)</span></a>
2770 or <a class="info" href="#LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"<span> (</span><span class="info">Getting all created MIDI input device list</span><span>)</span></a>
2771 command.
2772 </p>
2773 <p>Possible Answers:
2774 </p>
2775 <p>
2776 </p>
2777 <blockquote class="text">
2778 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2779 Each answer line begins with the information category name
2780 followed by a colon and then a space character &lt;SP&gt; and finally
2781 the info character string to that info category. As some
2782 parameters might allow multiple values, character strings are
2783 encapsulated into apostrophes ('). At the moment the following
2784 information categories are defined (independent of driver):
2785 </p>
2786 <p>
2787 </p>
2788 <blockquote class="text">
2789 <p>DRIVER -
2790 </p>
2791 <blockquote class="text">
2792 <p>identifier of the used MIDI input driver, as e.g.
2793 returned 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>
2794 command
2795 </p>
2796 </blockquote>
2797
2798
2799 </blockquote>
2800
2801 <blockquote class="text">
2802 <p>ACTIVE -
2803 </p>
2804 <blockquote class="text">
2805 <p>either true or false, if false then the MIDI device is
2806 inactive and doesn't listen to any incoming MIDI events
2807 and thus doesn't forward them to connected sampler
2808 channels
2809 </p>
2810 </blockquote>
2811
2812
2813 </blockquote>
2814
2815
2816 </blockquote><p>
2817
2818 </p>
2819 <p>The mentioned fields above don't have to be in particular
2820 order. The fields above are only those fields which are
2821 returned by all MIDI input devices. Every MIDI input driver
2822 might have its own, additional driver specific parameters (see
2823 <a class="info" href="#GET MIDI_INPUT_DRIVER INFO">"GET MIDI_INPUT_DRIVER INFO"<span> (</span><span class="info">Getting information about a specific MIDI input driver</span><span>)</span></a> command) which are also returned
2824 by this command.
2825 </p>
2826 <p>Example:
2827 </p>
2828 <p>
2829 </p>
2830 <blockquote class="text">
2831 <p>C: "GET MIDI_INPUT_DEVICE INFO 0"
2832 </p>
2833 <p>S: "DRIVER: ALSA"
2834 </p>
2835 <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
2836 </p>
2837 <p>&nbsp;&nbsp;&nbsp;"."
2838 </p>
2839 </blockquote><p>
2840
2841 </p>
2842 <a name="SET MIDI_INPUT_DEVICE_PARAMETER"></a><br /><hr />
2843 <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>
2844 <a name="rfc.section.6.3.10"></a><h3>6.3.10.&nbsp;Changing settings of MIDI input devices</h3>
2845
2846 <p>Use the following command to alter a specific setting of a created MIDI input device:
2847 </p>
2848 <p>
2849 </p>
2850 <blockquote class="text">
2851 <p>SET MIDI_INPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;
2852 </p>
2853 </blockquote><p>
2854
2855 </p>
2856 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
2857 MIDI input device as returned by the
2858 <a class="info" href="#CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"<span> (</span><span class="info">Creating a MIDI input device</span><span>)</span></a>
2859 or <a class="info" href="#LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"<span> (</span><span class="info">Getting all created MIDI input device list</span><span>)</span></a>
2860 command, &lt;key&gt; by the name of the parameter to change and
2861 &lt;value&gt; by the new value for this parameter.
2862 </p>
2863 <p>Possible Answers:
2864 </p>
2865 <p>
2866 </p>
2867 <blockquote class="text">
2868 <p>"OK" -
2869 </p>
2870 <blockquote class="text">
2871 <p>in case setting was successfully changed
2872 </p>
2873 </blockquote>
2874
2875
2876 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2877 </p>
2878 <blockquote class="text">
2879 <p>in case setting was changed successfully, but there are
2880 noteworthy issue(s) related, providing an appropriate
2881 warning code and warning message
2882 </p>
2883 </blockquote>
2884
2885
2886 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2887 </p>
2888 <blockquote class="text">
2889 <p>in case it failed, providing an appropriate error code and error message
2890 </p>
2891 </blockquote>
2892
2893
2894 </blockquote><p>
2895
2896 </p>
2897 <p>Example:
2898 </p>
2899 <p>
2900 </p>
2901 <blockquote class="text">
2902 <p>C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"
2903 </p>
2904 <p>S: "OK"
2905 </p>
2906 </blockquote><p>
2907
2908 </p>
2909 <a name="GET MIDI_INPUT_PORT INFO"></a><br /><hr />
2910 <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>
2911 <a name="rfc.section.6.3.11"></a><h3>6.3.11.&nbsp;Getting information about a MIDI port</h3>
2912
2913 <p>Use the following command to get information about a MIDI port:
2914 </p>
2915 <p>
2916 </p>
2917 <blockquote class="text">
2918 <p>GET MIDI_INPUT_PORT INFO &lt;device-id&gt; &lt;midi-port&gt;
2919 </p>
2920 </blockquote><p>
2921
2922 </p>
2923 <p>Where &lt;device-id&gt; is the numerical ID of the MIDI input device as returned by the
2924 <a class="info" href="#CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"<span> (</span><span class="info">Creating a MIDI input device</span><span>)</span></a>
2925 or <a class="info" href="#LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"<span> (</span><span class="info">Getting all created MIDI input device list</span><span>)</span></a>
2926 command and &lt;midi-port&gt; the MIDI input port number.
2927 </p>
2928 <p>Possible Answers:
2929 </p>
2930 <p>
2931 </p>
2932 <blockquote class="text">
2933 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2934 Each answer line begins with the information category name
2935 followed by a colon and then a space character &lt;SP&gt; and finally
2936 the info character string to that info category. At the moment
2937 the following information categories are defined:
2938 </p>
2939 <p>NAME -
2940 </p>
2941 <blockquote class="text">
2942 <p>arbitrary character string naming the port
2943 </p>
2944 </blockquote>
2945
2946
2947 </blockquote><p>
2948
2949 </p>
2950 <p>The field above is only the one which is returned by all MIDI
2951 ports regardless of the MIDI driver and port. Every MIDI port
2952 might have its own, additional driver and port specific
2953 parameters.
2954 </p>
2955 <p>Example:
2956 </p>
2957 <p>
2958 </p>
2959 <blockquote class="text">
2960 <p>C: "GET MIDI_INPUT_PORT INFO 0 0"
2961 </p>
2962 <p>S: "NAME: 'Masterkeyboard'"
2963 </p>
2964 <p>&nbsp;&nbsp;&nbsp;"ALSA_SEQ_BINDINGS: '64:0'"
2965 </p>
2966 <p>&nbsp;&nbsp;&nbsp;"."
2967 </p>
2968 </blockquote><p>
2969
2970 </p>
2971 <a name="GET MIDI_INPUT_PORT_PARAMETER INFO"></a><br /><hr />
2972 <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>
2973 <a name="rfc.section.6.3.12"></a><h3>6.3.12.&nbsp;Getting information about specific MIDI port parameter</h3>
2974
2975 <p>Use the following command to get detailed information about specific MIDI port parameter:
2976 </p>
2977 <p>
2978 </p>
2979 <blockquote class="text">
2980 <p>GET MIDI_INPUT_PORT_PARAMETER INFO &lt;dev-id&gt; &lt;port&gt; &lt;param&gt;
2981 </p>
2982 </blockquote><p>
2983
2984 </p>
2985 <p>Where &lt;dev-id&gt; is the numerical ID of the MIDI input device as returned by the
2986 <a class="info" href="#CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"<span> (</span><span class="info">Creating a MIDI input device</span><span>)</span></a>
2987 or <a class="info" href="#LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"<span> (</span><span class="info">Getting all created MIDI input device list</span><span>)</span></a>
2988 command, &lt;port&gt; the MIDI port number and
2989 &lt;param&gt; a specific port parameter name for which information should be
2990 obtained (as returned by the <a class="info" href="#GET MIDI_INPUT_PORT INFO">"GET MIDI_INPUT_PORT INFO"<span> (</span><span class="info">Getting information about a MIDI port</span><span>)</span></a> command).
2991 </p>
2992 <p>Possible Answers:
2993 </p>
2994 <p>
2995 </p>
2996 <blockquote class="text">
2997 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2998 Each answer line begins with the information category name
2999 followed by a colon and then a space character &lt;SP&gt; and finally
3000 the info character string to that info category. There is
3001 information which is always returned, independently of the
3002 given channel parameter and there is optional information
3003 which are only shown dependently to the given MIDI port. At the
3004 moment the following information categories are defined:
3005 </p>
3006 <p>TYPE -
3007 </p>
3008 <blockquote class="text">
3009 <p>either "BOOL" for boolean value(s) or "INT" for integer
3010 value(s) or "FLOAT" for dotted number(s) or "STRING" for
3011 character string(s)
3012 (always returned)
3013 </p>
3014 </blockquote>
3015
3016
3017 <p>DESCRIPTION -
3018 </p>
3019 <blockquote class="text">
3020 <p>arbitrary text describing the purpose of the parameter
3021 (always returned)
3022 </p>
3023 </blockquote>
3024
3025
3026 <p>FIX -
3027 </p>
3028 <blockquote class="text">
3029 <p>either true or false, if true then this parameter is
3030 read only, thus cannot be altered
3031 (always returned)
3032 </p>
3033 </blockquote>
3034
3035
3036 <p>MULTIPLICITY -
3037 </p>
3038 <blockquote class="text">
3039 <p>either true or false, defines if this parameter allows
3040 only one value or a list of values, where true means
3041 multiple values and false only a single value allowed
3042 (always returned)
3043 </p>
3044 </blockquote>
3045
3046
3047 <p>RANGE_MIN -
3048 </p>
3049 <blockquote class="text">
3050 <p>defines lower limit of the allowed value range for this
3051 parameter, can be an integer value as well as a dotted
3052 number, this parameter is usually used in conjunction
3053 with 'RANGE_MAX' but may also appear without
3054 (optionally returned, dependent to driver and port
3055 parameter)
3056 </p>
3057 </blockquote>
3058
3059
3060 <p>RANGE_MAX -
3061 </p>
3062 <blockquote class="text">
3063 <p>defines upper limit of the allowed value range for this
3064 parameter, can be an integer value as well as a dotted
3065 number, this parameter is usually used in conjunction
3066 with 'RANGE_MIN' but may also appear without
3067 (optionally returned, dependent to driver and port
3068 parameter)
3069 </p>
3070 </blockquote>
3071
3072
3073 <p>POSSIBILITIES -
3074 </p>
3075 <blockquote class="text">
3076 <p>comma separated list of possible values for this
3077 parameter, character strings are encapsulated into
3078 apostrophes
3079 (optionally returned, dependent to device and port
3080 parameter)
3081 </p>
3082 </blockquote>
3083
3084
3085 </blockquote><p>
3086
3087 </p>
3088 <p>The mentioned fields above don't have to be in particular order.
3089 </p>
3090 <p>Example:
3091 </p>
3092 <p>
3093 </p>
3094 <blockquote class="text">
3095 <p>C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"
3096 </p>
3097 <p>S: "DESCRIPTION: bindings to other ALSA sequencer clients"
3098 </p>
3099 <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
3100 </p>
3101 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
3102 </p>
3103 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"
3104 </p>
3105 <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: '64:0','68:0','68:1'"
3106 </p>
3107 <p>&nbsp;&nbsp;&nbsp;"."
3108 </p>
3109 </blockquote><p>
3110
3111 </p>
3112 <a name="SET MIDI_INPUT_PORT_PARAMETER"></a><br /><hr />
3113 <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>
3114 <a name="rfc.section.6.3.13"></a><h3>6.3.13.&nbsp;Changing settings of MIDI input ports</h3>
3115
3116 <p>Use the following command to alter a specific setting of a MIDI input port:
3117 </p>
3118 <p>
3119 </p>
3120 <blockquote class="text">
3121 <p>SET MIDI_INPUT_PORT_PARAMETER &lt;device-id&gt; &lt;port&gt; &lt;key&gt;=&lt;value&gt;
3122 </p>
3123 </blockquote><p>
3124
3125 </p>
3126 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
3127 MIDI device as returned by the
3128 <a class="info" href="#CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"<span> (</span><span class="info">Creating a MIDI input device</span><span>)</span></a>
3129 or <a class="info" href="#LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"<span> (</span><span class="info">Getting all created MIDI input device list</span><span>)</span></a>
3130 command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of
3131 the parameter to change and &lt;value&gt; by the new value for this
3132 parameter.
3133 </p>
3134 <p>Possible Answers:
3135 </p>
3136 <p>
3137 </p>
3138 <blockquote class="text">
3139 <p>"OK" -
3140 </p>
3141 <blockquote class="text">
3142 <p>in case setting was successfully changed
3143 </p>
3144 </<