/[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 709 - (show annotations) (download) (as text)
Thu Jul 21 09:36:52 2005 UTC (15 years ago) by schoenebeck
File MIME type: text/html
File size: 190435 byte(s)
just updated date

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