/[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 1201 - (show annotations) (download) (as text)
Thu May 24 14:22:39 2007 UTC (15 years, 8 months ago) by iliev
File MIME type: text/html
File size: 370051 byte(s)
* added commands for monitoring the instrument scan progress

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