/[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 1251 - (show annotations) (download) (as text)
Fri Jun 22 14:24:57 2007 UTC (13 years, 8 months ago) by schoenebeck
File MIME type: text/html
File size: 373989 byte(s)
- updated LSCP spec draft regarding extended ASCII character
  set and support for escape sequences

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