/[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 575 - (show annotations) (download) (as text)
Tue May 24 03:26:22 2005 UTC (15 years, 2 months ago) by schoenebeck
File MIME type: text/html
File size: 173632 byte(s)
- LSCP syntax (BNF) is now auto generated
- tagged LSCP specification as version 1.0
- minor cleanup

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