/[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 992 - (show annotations) (download) (as text)
Wed Dec 20 19:52:00 2006 UTC (14 years, 2 months ago) by iliev
File MIME type: text/html
File size: 266513 byte(s)
www.linuxsampler.org/api/draft-linuxsampler-protocol.txt

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