/[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 1028 - (show annotations) (download) (as text)
Sun Jan 14 17:33:03 2007 UTC (13 years, 8 months ago) by schoenebeck
File MIME type: text/html
File size: 295120 byte(s)
LSCP spec document has been updated

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