/[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 974 - (show annotations) (download) (as text)
Fri Dec 15 21:46:48 2006 UTC (16 years, 1 month ago) by schoenebeck
File MIME type: text/html
File size: 255481 byte(s)
- revised and extended LSCP command set for MIDI
  instrument mapping

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