/[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 3503 - (show annotations) (download) (as text)
Mon Mar 11 15:46:15 2019 UTC (11 months, 2 weeks ago) by schoenebeck
File MIME type: text/html
File size: 394061 byte(s)
* Updated LSCP reference documentation.

1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3
4 <html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
5 <head profile="http://www.w3.org/2006/03/hcard http://dublincore.org/documents/2008/08/04/dc-html/">
6 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
7
8 <title>LinuxSampler Control Protocol</title>
9
10 <style type="text/css" title="Xml2Rfc (sans serif)">
11 /*<![CDATA[*/
12 a {
13 text-decoration: none;
14 }
15 /* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */
16 a.info {
17 /* This is the key. */
18 position: relative;
19 z-index: 24;
20 text-decoration: none;
21 }
22 a.info:hover {
23 z-index: 25;
24 color: #FFF; background-color: #900;
25 }
26 a.info span { display: none; }
27 a.info:hover span.info {
28 /* The span will display just on :hover state. */
29 display: block;
30 position: absolute;
31 font-size: smaller;
32 top: 2em; left: -5em; width: 15em;
33 padding: 2px; border: 1px solid #333;
34 color: #900; background-color: #EEE;
35 text-align: left;
36 }
37 a.smpl {
38 color: black;
39 }
40 a:hover {
41 text-decoration: underline;
42 }
43 a:active {
44 text-decoration: underline;
45 }
46 address {
47 margin-top: 1em;
48 margin-left: 2em;
49 font-style: normal;
50 }
51 body {
52 color: black;
53 font-family: verdana, helvetica, arial, sans-serif;
54 font-size: 10pt;
55 max-width: 55em;
56
57 }
58 cite {
59 font-style: normal;
60 }
61 dd {
62 margin-right: 2em;
63 }
64 dl {
65 margin-left: 2em;
66 }
67
68 ul.empty {
69 list-style-type: none;
70 }
71 ul.empty li {
72 margin-top: .5em;
73 }
74 dl p {
75 margin-left: 0em;
76 }
77 dt {
78 margin-top: .5em;
79 }
80 h1 {
81 font-size: 14pt;
82 line-height: 21pt;
83 page-break-after: avoid;
84 }
85 h1.np {
86 page-break-before: always;
87 }
88 h1 a {
89 color: #333333;
90 }
91 h2 {
92 font-size: 12pt;
93 line-height: 15pt;
94 page-break-after: avoid;
95 }
96 h3, h4, h5, h6 {
97 font-size: 10pt;
98 page-break-after: avoid;
99 }
100 h2 a, h3 a, h4 a, h5 a, h6 a {
101 color: black;
102 }
103 img {
104 margin-left: 3em;
105 }
106 li {
107 margin-left: 2em;
108 margin-right: 2em;
109 }
110 ol {
111 margin-left: 2em;
112 margin-right: 2em;
113 }
114 ol p {
115 margin-left: 0em;
116 }
117 p {
118 margin-left: 2em;
119 margin-right: 2em;
120 }
121 pre {
122 margin-left: 3em;
123 background-color: lightyellow;
124 padding: .25em;
125 }
126 pre.text2 {
127 border-style: dotted;
128 border-width: 1px;
129 background-color: #f0f0f0;
130 width: 69em;
131 }
132 pre.inline {
133 background-color: white;
134 padding: 0em;
135 }
136 pre.text {
137 border-style: dotted;
138 border-width: 1px;
139 background-color: #f8f8f8;
140 width: 69em;
141 }
142 pre.drawing {
143 border-style: solid;
144 border-width: 1px;
145 background-color: #f8f8f8;
146 padding: 2em;
147 }
148 table {
149 margin-left: 2em;
150 }
151 table.tt {
152 vertical-align: top;
153 }
154 table.full {
155 border-style: outset;
156 border-width: 1px;
157 }
158 table.headers {
159 border-style: outset;
160 border-width: 1px;
161 }
162 table.tt td {
163 vertical-align: top;
164 }
165 table.full td {
166 border-style: inset;
167 border-width: 1px;
168 }
169 table.tt th {
170 vertical-align: top;
171 }
172 table.full th {
173 border-style: inset;
174 border-width: 1px;
175 }
176 table.headers th {
177 border-style: none none inset none;
178 border-width: 1px;
179 }
180 table.left {
181 margin-right: auto;
182 }
183 table.right {
184 margin-left: auto;
185 }
186 table.center {
187 margin-left: auto;
188 margin-right: auto;
189 }
190 caption {
191 caption-side: bottom;
192 font-weight: bold;
193 font-size: 9pt;
194 margin-top: .5em;
195 }
196
197 table.header {
198 border-spacing: 1px;
199 width: 95%;
200 font-size: 10pt;
201 color: white;
202 }
203 td.top {
204 vertical-align: top;
205 }
206 td.topnowrap {
207 vertical-align: top;
208 white-space: nowrap;
209 }
210 table.header td {
211 background-color: gray;
212 width: 50%;
213 }
214 table.header a {
215 color: white;
216 }
217 td.reference {
218 vertical-align: top;
219 white-space: nowrap;
220 padding-right: 1em;
221 }
222 thead {
223 display:table-header-group;
224 }
225 ul.toc, ul.toc ul {
226 list-style: none;
227 margin-left: 1.5em;
228 margin-right: 0em;
229 padding-left: 0em;
230 }
231 ul.toc li {
232 line-height: 150%;
233 font-weight: bold;
234 font-size: 10pt;
235 margin-left: 0em;
236 margin-right: 0em;
237 }
238 ul.toc li li {
239 line-height: normal;
240 font-weight: normal;
241 font-size: 9pt;
242 margin-left: 0em;
243 margin-right: 0em;
244 }
245 li.excluded {
246 font-size: 0pt;
247 }
248 ul p {
249 margin-left: 0em;
250 }
251
252 .comment {
253 background-color: yellow;
254 }
255 .center {
256 text-align: center;
257 }
258 .error {
259 color: red;
260 font-style: italic;
261 font-weight: bold;
262 }
263 .figure {
264 font-weight: bold;
265 text-align: center;
266 font-size: 9pt;
267 }
268 .filename {
269 color: #333333;
270 font-weight: bold;
271 font-size: 12pt;
272 line-height: 21pt;
273 text-align: center;
274 }
275 .fn {
276 font-weight: bold;
277 }
278 .hidden {
279 display: none;
280 }
281 .left {
282 text-align: left;
283 }
284 .right {
285 text-align: right;
286 }
287 .title {
288 color: #990000;
289 font-size: 18pt;
290 line-height: 18pt;
291 font-weight: bold;
292 text-align: center;
293 margin-top: 36pt;
294 }
295 .vcardline {
296 display: block;
297 }
298 .warning {
299 font-size: 14pt;
300 background-color: yellow;
301 }
302
303
304 @media print {
305 .noprint {
306 display: none;
307 }
308
309 a {
310 color: black;
311 text-decoration: none;
312 }
313
314 table.header {
315 width: 90%;
316 }
317
318 td.header {
319 width: 50%;
320 color: black;
321 background-color: white;
322 vertical-align: top;
323 font-size: 12pt;
324 }
325
326 ul.toc a::after {
327 content: leader('.') target-counter(attr(href), page);
328 }
329
330 ul.ind li li a {
331 content: target-counter(attr(href), page);
332 }
333
334 .print2col {
335 column-count: 2;
336 -moz-column-count: 2;
337 column-fill: auto;
338 }
339 }
340
341 @page {
342 @top-left {
343 content: "Internet-Draft";
344 }
345 @top-right {
346 content: "December 2010";
347 }
348 @top-center {
349 content: "Abbreviated Title";
350 }
351 @bottom-left {
352 content: "Doe";
353 }
354 @bottom-center {
355 content: "Expires June 2011";
356 }
357 @bottom-right {
358 content: "[Page " counter(page) "]";
359 }
360 }
361
362 @page:first {
363 @top-left {
364 content: normal;
365 }
366 @top-right {
367 content: normal;
368 }
369 @top-center {
370 content: normal;
371 }
372 }
373 /*]]>*/
374 </style>
375
376 <link href="#rfc.toc" rel="Contents"/>
377 <link href="#rfc.section.1" rel="Chapter" title="1 Requirements notation"/>
378 <link href="#rfc.section.2" rel="Chapter" title="2 Versioning of this specification"/>
379 <link href="#rfc.section.3" rel="Chapter" title="3 Introduction"/>
380 <link href="#rfc.section.4" rel="Chapter" title="4 Focus of this protocol"/>
381 <link href="#rfc.section.5" rel="Chapter" title="5 Communication Overview"/>
382 <link href="#rfc.section.5.1" rel="Chapter" title="5.1 Request/response communication method"/>
383 <link href="#rfc.section.5.1.1" rel="Chapter" title="5.1.1 Result format"/>
384 <link href="#rfc.section.5.2" rel="Chapter" title="5.2 Subscribe/notify communication method"/>
385 <link href="#rfc.section.6" rel="Chapter" title="6 Description for control commands"/>
386 <link href="#rfc.section.6.1" rel="Chapter" title="6.1 Ignored lines and comments"/>
387 <link href="#rfc.section.6.2" rel="Chapter" title="6.2 Configuring audio drivers"/>
388 <link href="#rfc.section.6.2.1" rel="Chapter" title="6.2.1 Getting amount of available audio output drivers"/>
389 <link href="#rfc.section.6.2.2" rel="Chapter" title="6.2.2 Getting all available audio output drivers"/>
390 <link href="#rfc.section.6.2.3" rel="Chapter" title="6.2.3 Getting information about a specific audio output driver"/>
391 <link href="#rfc.section.6.2.4" rel="Chapter" title="6.2.4 Getting information about specific audio output driver parameter"/>
392 <link href="#rfc.section.6.2.5" rel="Chapter" title="6.2.5 Creating an audio output device"/>
393 <link href="#rfc.section.6.2.6" rel="Chapter" title="6.2.6 Destroying an audio output device"/>
394 <link href="#rfc.section.6.2.7" rel="Chapter" title="6.2.7 Getting all created audio output device count"/>
395 <link href="#rfc.section.6.2.8" rel="Chapter" title="6.2.8 Getting all created audio output device list"/>
396 <link href="#rfc.section.6.2.9" rel="Chapter" title="6.2.9 Getting current settings of an audio output device"/>
397 <link href="#rfc.section.6.2.10" rel="Chapter" title="6.2.10 Changing settings of audio output devices"/>
398 <link href="#rfc.section.6.2.11" rel="Chapter" title="6.2.11 Getting information about an audio channel"/>
399 <link href="#rfc.section.6.2.12" rel="Chapter" title="6.2.12 Getting information about specific audio channel parameter"/>
400 <link href="#rfc.section.6.2.13" rel="Chapter" title="6.2.13 Changing settings of audio output channels"/>
401 <link href="#rfc.section.6.3" rel="Chapter" title="6.3 Configuring MIDI input drivers"/>
402 <link href="#rfc.section.6.3.1" rel="Chapter" title="6.3.1 Getting amount of available MIDI input drivers"/>
403 <link href="#rfc.section.6.3.2" rel="Chapter" title="6.3.2 Getting all available MIDI input drivers"/>
404 <link href="#rfc.section.6.3.3" rel="Chapter" title="6.3.3 Getting information about a specific MIDI input driver"/>
405 <link href="#rfc.section.6.3.4" rel="Chapter" title="6.3.4 Getting information about specific MIDI input driver parameter"/>
406 <link href="#rfc.section.6.3.5" rel="Chapter" title="6.3.5 Creating a MIDI input device"/>
407 <link href="#rfc.section.6.3.6" rel="Chapter" title="6.3.6 Destroying a MIDI input device"/>
408 <link href="#rfc.section.6.3.7" rel="Chapter" title="6.3.7 Getting all created MIDI input device count"/>
409 <link href="#rfc.section.6.3.8" rel="Chapter" title="6.3.8 Getting all created MIDI input device list"/>
410 <link href="#rfc.section.6.3.9" rel="Chapter" title="6.3.9 Getting current settings of a MIDI input device"/>
411 <link href="#rfc.section.6.3.10" rel="Chapter" title="6.3.10 Changing settings of MIDI input devices"/>
412 <link href="#rfc.section.6.3.11" rel="Chapter" title="6.3.11 Getting information about a MIDI port"/>
413 <link href="#rfc.section.6.3.12" rel="Chapter" title="6.3.12 Getting information about specific MIDI port parameter"/>
414 <link href="#rfc.section.6.3.13" rel="Chapter" title="6.3.13 Changing settings of MIDI input ports"/>
415 <link href="#rfc.section.6.4" rel="Chapter" title="6.4 Configuring sampler channels"/>
416 <link href="#rfc.section.6.4.1" rel="Chapter" title="6.4.1 Loading an instrument"/>
417 <link href="#rfc.section.6.4.2" rel="Chapter" title="6.4.2 Loading a sampler engine"/>
418 <link href="#rfc.section.6.4.3" rel="Chapter" title="6.4.3 Getting all created sampler channel count"/>
419 <link href="#rfc.section.6.4.4" rel="Chapter" title="6.4.4 Getting all created sampler channel list"/>
420 <link href="#rfc.section.6.4.5" rel="Chapter" title="6.4.5 Adding a new sampler channel"/>
421 <link href="#rfc.section.6.4.6" rel="Chapter" title="6.4.6 Removing a sampler channel"/>
422 <link href="#rfc.section.6.4.7" rel="Chapter" title="6.4.7 Getting amount of available engines"/>
423 <link href="#rfc.section.6.4.8" rel="Chapter" title="6.4.8 Getting all available engines"/>
424 <link href="#rfc.section.6.4.9" rel="Chapter" title="6.4.9 Getting information about an engine"/>
425 <link href="#rfc.section.6.4.10" rel="Chapter" title="6.4.10 Getting sampler channel information"/>
426 <link href="#rfc.section.6.4.11" rel="Chapter" title="6.4.11 Current number of active voices"/>
427 <link href="#rfc.section.6.4.12" rel="Chapter" title="6.4.12 Current number of active disk streams"/>
428 <link href="#rfc.section.6.4.13" rel="Chapter" title="6.4.13 Current fill state of disk stream buffers"/>
429 <link href="#rfc.section.6.4.14" rel="Chapter" title="6.4.14 Setting audio output device"/>
430 <link href="#rfc.section.6.4.15" rel="Chapter" title="6.4.15 Setting audio output type"/>
431 <link href="#rfc.section.6.4.16" rel="Chapter" title="6.4.16 Setting audio output channel"/>
432 <link href="#rfc.section.6.4.17" rel="Chapter" title="6.4.17 Add MIDI input to sampler channel"/>
433 <link href="#rfc.section.6.4.18" rel="Chapter" title="6.4.18 Remove MIDI input(s) from sampler channel"/>
434 <link href="#rfc.section.6.4.19" rel="Chapter" title="6.4.19 Getting all MIDI inputs of a sampler channel"/>
435 <link href="#rfc.section.6.4.20" rel="Chapter" title="6.4.20 Setting MIDI input device"/>
436 <link href="#rfc.section.6.4.21" rel="Chapter" title="6.4.21 Setting MIDI input type"/>
437 <link href="#rfc.section.6.4.22" rel="Chapter" title="6.4.22 Setting MIDI input port"/>
438 <link href="#rfc.section.6.4.23" rel="Chapter" title="6.4.23 Setting MIDI input channel"/>
439 <link href="#rfc.section.6.4.24" rel="Chapter" title="6.4.24 Setting channel volume"/>
440 <link href="#rfc.section.6.4.25" rel="Chapter" title="6.4.25 Muting a sampler channel"/>
441 <link href="#rfc.section.6.4.26" rel="Chapter" title="6.4.26 Soloing a sampler channel"/>
442 <link href="#rfc.section.6.4.27" rel="Chapter" title="6.4.27 Assigning a MIDI instrument map to a sampler channel"/>
443 <link href="#rfc.section.6.4.28" rel="Chapter" title="6.4.28 Adding an effect send to a sampler channel"/>
444 <link href="#rfc.section.6.4.29" rel="Chapter" title="6.4.29 Removing an effect send from a sampler channel"/>
445 <link href="#rfc.section.6.4.30" rel="Chapter" title="6.4.30 Getting amount of effect sends on a sampler channel"/>
446 <link href="#rfc.section.6.4.31" rel="Chapter" title="6.4.31 Listing all effect sends on a sampler channel"/>
447 <link href="#rfc.section.6.4.32" rel="Chapter" title="6.4.32 Getting effect send information"/>
448 <link href="#rfc.section.6.4.33" rel="Chapter" title="6.4.33 Changing effect send's name"/>
449 <link href="#rfc.section.6.4.34" rel="Chapter" title="6.4.34 Altering effect send's audio routing"/>
450 <link href="#rfc.section.6.4.35" rel="Chapter" title="6.4.35 Assigning destination effect to an effect send"/>
451 <link href="#rfc.section.6.4.36" rel="Chapter" title="6.4.36 Removing destination effect from an effect send"/>
452 <link href="#rfc.section.6.4.37" rel="Chapter" title="6.4.37 Altering effect send's MIDI controller"/>
453 <link href="#rfc.section.6.4.38" rel="Chapter" title="6.4.38 Altering effect send's send level"/>
454 <link href="#rfc.section.6.4.39" rel="Chapter" title="6.4.39 Sending MIDI messages to sampler channel"/>
455 <link href="#rfc.section.6.4.40" rel="Chapter" title="6.4.40 Resetting a sampler channel"/>
456 <link href="#rfc.section.6.5" rel="Chapter" title="6.5 Controlling connection"/>
457 <link href="#rfc.section.6.5.1" rel="Chapter" title="6.5.1 Register front-end for receiving event messages"/>
458 <link href="#rfc.section.6.5.2" rel="Chapter" title="6.5.2 Unregister front-end for not receiving event messages"/>
459 <link href="#rfc.section.6.5.3" rel="Chapter" title="6.5.3 Enable or disable echo of commands"/>
460 <link href="#rfc.section.6.5.4" rel="Chapter" title="6.5.4 Close client connection"/>
461 <link href="#rfc.section.6.6" rel="Chapter" title="6.6 Global commands"/>
462 <link href="#rfc.section.6.6.1" rel="Chapter" title="6.6.1 Current number of active voices"/>
463 <link href="#rfc.section.6.6.2" rel="Chapter" title="6.6.2 Maximum amount of active voices"/>
464 <link href="#rfc.section.6.6.3" rel="Chapter" title="6.6.3 Current number of active disk streams"/>
465 <link href="#rfc.section.6.6.4" rel="Chapter" title="6.6.4 Reset sampler"/>
466 <link href="#rfc.section.6.6.5" rel="Chapter" title="6.6.5 General sampler information"/>
467 <link href="#rfc.section.6.6.6" rel="Chapter" title="6.6.6 Getting global volume attenuation"/>
468 <link href="#rfc.section.6.6.7" rel="Chapter" title="6.6.7 Setting global volume attenuation"/>
469 <link href="#rfc.section.6.6.8" rel="Chapter" title="6.6.8 Getting global voice limit"/>
470 <link href="#rfc.section.6.6.9" rel="Chapter" title="6.6.9 Setting global voice limit"/>
471 <link href="#rfc.section.6.6.10" rel="Chapter" title="6.6.10 Getting global disk stream limit"/>
472 <link href="#rfc.section.6.6.11" rel="Chapter" title="6.6.11 Setting global disk stream limit"/>
473 <link href="#rfc.section.6.7" rel="Chapter" title="6.7 MIDI Instrument Mapping"/>
474 <link href="#rfc.section.6.7.1" rel="Chapter" title="6.7.1 Create a new MIDI instrument map"/>
475 <link href="#rfc.section.6.7.2" rel="Chapter" title="6.7.2 Delete one particular or all MIDI instrument maps"/>
476 <link href="#rfc.section.6.7.3" rel="Chapter" title="6.7.3 Get amount of existing MIDI instrument maps"/>
477 <link href="#rfc.section.6.7.4" rel="Chapter" title="6.7.4 Getting all created MIDI instrument maps"/>
478 <link href="#rfc.section.6.7.5" rel="Chapter" title="6.7.5 Getting MIDI instrument map information"/>
479 <link href="#rfc.section.6.7.6" rel="Chapter" title="6.7.6 Renaming a MIDI instrument map"/>
480 <link href="#rfc.section.6.7.7" rel="Chapter" title="6.7.7 Create or replace a MIDI instrument map entry"/>
481 <link href="#rfc.section.6.7.8" rel="Chapter" title="6.7.8 Getting amount of MIDI instrument map entries"/>
482 <link href="#rfc.section.6.7.9" rel="Chapter" title="6.7.9 Getting indeces of all entries of a MIDI instrument map"/>
483 <link href="#rfc.section.6.7.10" rel="Chapter" title="6.7.10 Remove an entry from the MIDI instrument map"/>
484 <link href="#rfc.section.6.7.11" rel="Chapter" title="6.7.11 Get current settings of MIDI instrument map entry"/>
485 <link href="#rfc.section.6.7.12" rel="Chapter" title="6.7.12 Clear MIDI instrument map"/>
486 <link href="#rfc.section.6.8" rel="Chapter" title="6.8 Managing Instruments Database"/>
487 <link href="#rfc.section.6.8.1" rel="Chapter" title="6.8.1 Creating a new instrument directory"/>
488 <link href="#rfc.section.6.8.2" rel="Chapter" title="6.8.2 Deleting an instrument directory"/>
489 <link href="#rfc.section.6.8.3" rel="Chapter" title="6.8.3 Getting amount of instrument directories"/>
490 <link href="#rfc.section.6.8.4" rel="Chapter" title="6.8.4 Listing all directories in specific directory"/>
491 <link href="#rfc.section.6.8.5" rel="Chapter" title="6.8.5 Getting instrument directory information"/>
492 <link href="#rfc.section.6.8.6" rel="Chapter" title="6.8.6 Renaming an instrument directory"/>
493 <link href="#rfc.section.6.8.7" rel="Chapter" title="6.8.7 Moving an instrument directory"/>
494 <link href="#rfc.section.6.8.8" rel="Chapter" title="6.8.8 Copying instrument directories"/>
495 <link href="#rfc.section.6.8.9" rel="Chapter" title="6.8.9 Changing the description of directory"/>
496 <link href="#rfc.section.6.8.10" rel="Chapter" title="6.8.10 Finding directories"/>
497 <link href="#rfc.section.6.8.11" rel="Chapter" title="6.8.11 Adding instruments to the instruments database"/>
498 <link href="#rfc.section.6.8.12" rel="Chapter" title="6.8.12 Removing an instrument"/>
499 <link href="#rfc.section.6.8.13" rel="Chapter" title="6.8.13 Getting amount of instruments"/>
500 <link href="#rfc.section.6.8.14" rel="Chapter" title="6.8.14 Listing all instruments in specific directory"/>
501 <link href="#rfc.section.6.8.15" rel="Chapter" title="6.8.15 Getting instrument information"/>
502 <link href="#rfc.section.6.8.16" rel="Chapter" title="6.8.16 Renaming an instrument"/>
503 <link href="#rfc.section.6.8.17" rel="Chapter" title="6.8.17 Moving an instrument"/>
504 <link href="#rfc.section.6.8.18" rel="Chapter" title="6.8.18 Copying instruments"/>
505 <link href="#rfc.section.6.8.19" rel="Chapter" title="6.8.19 Changing the description of instrument"/>
506 <link href="#rfc.section.6.8.20" rel="Chapter" title="6.8.20 Finding instruments"/>
507 <link href="#rfc.section.6.8.21" rel="Chapter" title="6.8.21 Getting job status information"/>
508 <link href="#rfc.section.6.8.22" rel="Chapter" title="6.8.22 Formatting the instruments database"/>
509 <link href="#rfc.section.6.8.23" rel="Chapter" title="6.8.23 Checking for lost instrument files"/>
510 <link href="#rfc.section.6.8.24" rel="Chapter" title="6.8.24 Replacing an instrument file"/>
511 <link href="#rfc.section.6.9" rel="Chapter" title="6.9 Editing Instruments"/>
512 <link href="#rfc.section.6.9.1" rel="Chapter" title="6.9.1 Opening an appropriate instrument editor application"/>
513 <link href="#rfc.section.6.10" rel="Chapter" title="6.10 Managing Files"/>
514 <link href="#rfc.section.6.10.1" rel="Chapter" title="6.10.1 Retrieving amount of instruments of a file"/>
515 <link href="#rfc.section.6.10.2" rel="Chapter" title="6.10.2 Retrieving all instruments of a file"/>
516 <link href="#rfc.section.6.10.3" rel="Chapter" title="6.10.3 Retrieving information about one instrument in a file"/>
517 <link href="#rfc.section.6.11" rel="Chapter" title="6.11 Managing Effects"/>
518 <link href="#rfc.section.6.11.1" rel="Chapter" title="6.11.1 Retrieve amount of available effects"/>
519 <link href="#rfc.section.6.11.2" rel="Chapter" title="6.11.2 Get list of available effects"/>
520 <link href="#rfc.section.6.11.3" rel="Chapter" title="6.11.3 Retrieving general information about an effect"/>
521 <link href="#rfc.section.6.11.4" rel="Chapter" title="6.11.4 Creating an instance of an effect by its portable ID"/>
522 <link href="#rfc.section.6.11.5" rel="Chapter" title="6.11.5 Creating an instance of an effect by its numerical ID"/>
523 <link href="#rfc.section.6.11.6" rel="Chapter" title="6.11.6 Destroy an effect instance"/>
524 <link href="#rfc.section.6.11.7" rel="Chapter" title="6.11.7 Retrieve amount of effect instances"/>
525 <link href="#rfc.section.6.11.8" rel="Chapter" title="6.11.8 Get list of effect instances"/>
526 <link href="#rfc.section.6.11.9" rel="Chapter" title="6.11.9 Retrieving current information about an effect instance"/>
527 <link href="#rfc.section.6.11.10" rel="Chapter" title="6.11.10 Retrieving information about an effect parameter"/>
528 <link href="#rfc.section.6.11.11" rel="Chapter" title="6.11.11 Altering an effect parameter"/>
529 <link href="#rfc.section.6.11.12" rel="Chapter" title="6.11.12 Retrieve amount of send effect chains"/>
530 <link href="#rfc.section.6.11.13" rel="Chapter" title="6.11.13 Retrieve list of send effect chains"/>
531 <link href="#rfc.section.6.11.14" rel="Chapter" title="6.11.14 Add send effect chain"/>
532 <link href="#rfc.section.6.11.15" rel="Chapter" title="6.11.15 Remove send effect chain"/>
533 <link href="#rfc.section.6.11.16" rel="Chapter" title="6.11.16 Retrieving information about a send effect chain"/>
534 <link href="#rfc.section.6.11.17" rel="Chapter" title="6.11.17 Append effect instance to a send effect chain"/>
535 <link href="#rfc.section.6.11.18" rel="Chapter" title="6.11.18 Insert effect instance to a send effect chain"/>
536 <link href="#rfc.section.6.11.19" rel="Chapter" title="6.11.19 Remove effect instance from send effect chain"/>
537 <link href="#rfc.section.7" rel="Chapter" title="7 Command Syntax"/>
538 <link href="#rfc.section.7.1" rel="Chapter" title="7.1 Character Set and Escape Sequences"/>
539 <link href="#rfc.section.8" rel="Chapter" title="8 Events"/>
540 <link href="#rfc.section.8.1" rel="Chapter" title="8.1 Number of audio output devices changed"/>
541 <link href="#rfc.section.8.2" rel="Chapter" title="8.2 Audio output device's settings changed"/>
542 <link href="#rfc.section.8.3" rel="Chapter" title="8.3 Number of MIDI input devices changed"/>
543 <link href="#rfc.section.8.4" rel="Chapter" title="8.4 MIDI input device's settings changed"/>
544 <link href="#rfc.section.8.5" rel="Chapter" title="8.5 Number of sampler channels changed"/>
545 <link href="#rfc.section.8.6" rel="Chapter" title="8.6 MIDI data on a sampler channel arrived"/>
546 <link href="#rfc.section.8.7" rel="Chapter" title="8.7 MIDI data on a MIDI input device arrived"/>
547 <link href="#rfc.section.8.8" rel="Chapter" title="8.8 Number of active voices changed"/>
548 <link href="#rfc.section.8.9" rel="Chapter" title="8.9 Number of active disk streams changed"/>
549 <link href="#rfc.section.8.10" rel="Chapter" title="8.10 Disk stream buffer fill state changed"/>
550 <link href="#rfc.section.8.11" rel="Chapter" title="8.11 Channel information changed"/>
551 <link href="#rfc.section.8.12" rel="Chapter" title="8.12 Number of effect sends changed"/>
552 <link href="#rfc.section.8.13" rel="Chapter" title="8.13 Effect send information changed"/>
553 <link href="#rfc.section.8.14" rel="Chapter" title="8.14 Total number of active voices changed"/>
554 <link href="#rfc.section.8.15" rel="Chapter" title="8.15 Total number of active disk streams changed"/>
555 <link href="#rfc.section.8.16" rel="Chapter" title="8.16 Number of MIDI instrument maps changed"/>
556 <link href="#rfc.section.8.17" rel="Chapter" title="8.17 MIDI instrument map information changed"/>
557 <link href="#rfc.section.8.18" rel="Chapter" title="8.18 Number of MIDI instruments changed"/>
558 <link href="#rfc.section.8.19" rel="Chapter" title="8.19 MIDI instrument information changed"/>
559 <link href="#rfc.section.8.20" rel="Chapter" title="8.20 Global settings changed"/>
560 <link href="#rfc.section.8.21" rel="Chapter" title="8.21 Number of database instrument directories changed"/>
561 <link href="#rfc.section.8.22" rel="Chapter" title="8.22 Database instrument directory information changed"/>
562 <link href="#rfc.section.8.23" rel="Chapter" title="8.23 Number of database instruments changed"/>
563 <link href="#rfc.section.8.24" rel="Chapter" title="8.24 Database instrument information changed"/>
564 <link href="#rfc.section.8.25" rel="Chapter" title="8.25 Database job status information changed"/>
565 <link href="#rfc.section.8.26" rel="Chapter" title="8.26 Number of effect instances changed"/>
566 <link href="#rfc.section.8.27" rel="Chapter" title="8.27 Effect instance information changed"/>
567 <link href="#rfc.section.8.28" rel="Chapter" title="8.28 Number of send effect chains changed"/>
568 <link href="#rfc.section.8.29" rel="Chapter" title="8.29 Send effect chain information changed"/>
569 <link href="#rfc.section.8.30" rel="Chapter" title="8.30 Miscellaneous and debugging events"/>
570 <link href="#rfc.section.9" rel="Chapter" title="9 Security Considerations"/>
571 <link href="#rfc.section.10" rel="Chapter" title="10 Acknowledgments"/>
572 <link href="#rfc.references" rel="Chapter" title="11 References"/>
573 <link href="#rfc.authors" rel="Chapter"/>
574
575
576 <meta name="generator" content="xml2rfc version 2.5.1 - http://tools.ietf.org/tools/xml2rfc" />
577 <link rel="schema.dct" href="http://purl.org/dc/terms/" />
578
579 <meta name="dct.creator" content="Schoenebeck, C., Ed." />
580 <meta name="dct.identifier" content="urn:ietf:id:LSCP 1.7" />
581 <meta name="dct.issued" scheme="ISO8601" content="2019-3-11" />
582 <meta name="dct.abstract" content="The LinuxSampler Control Protocol (LSCP) is an application-level protocol primarily intended for local and remote controlling the LinuxSampler backend application, which is a sophisticated server-like console application essentially playing back audio samples and manipulating the samples in real time to certain extent." />
583 <meta name="description" content="The LinuxSampler Control Protocol (LSCP) is an application-level protocol primarily intended for local and remote controlling the LinuxSampler backend application, which is a sophisticated server-like console application essentially playing back audio samples and manipulating the samples in real time to certain extent." />
584
585 </head>
586
587 <body>
588
589 <table class="header">
590 <tbody>
591
592 <tr>
593 <td class="left">LinuxSampler Developers</td>
594 <td class="right">C. Schoenebeck, Ed.</td>
595 </tr>
596 <tr>
597 <td class="left">Internet-Draft</td>
598 <td class="right">LinuxSampler.org</td>
599 </tr>
600 <tr>
601 <td class="left">Intended status: Informational</td>
602 <td class="right">March 11, 2019</td>
603 </tr>
604 <tr>
605 <td class="left">Expires: September 12, 2019</td>
606 <td class="right"></td>
607 </tr>
608
609
610 </tbody>
611 </table>
612
613 <p class="title">LinuxSampler Control Protocol<br />
614 <span class="filename">LSCP 1.7</span></p>
615
616 <h1 id="rfc.abstract">
617 <a href="#rfc.abstract">Abstract</a>
618 </h1>
619 <p>The LinuxSampler Control Protocol (LSCP) is an application-level protocol primarily intended for local and remote controlling the LinuxSampler backend application, which is a sophisticated server-like console application essentially playing back audio samples and manipulating the samples in real time to certain extent.</p>
620 <h1 id="rfc.status">
621 <a href="#rfc.status">Status of This Memo</a>
622 </h1>
623 <p>This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.</p>
624 <p>Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.</p>
625 <p>Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."</p>
626 <p>This Internet-Draft will expire on September 12, 2019.</p>
627 <h1 id="rfc.copyrightnotice">
628 <a href="#rfc.copyrightnotice">Copyright Notice</a>
629 </h1>
630 <p>Copyright (c) 2019 IETF Trust and the persons identified as the document authors. All rights reserved.</p>
631 <p>This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.</p>
632 <p>This document may not be modified, and derivative works of it may not be created, and it may not be published except as an Internet-Draft.</p>
633
634
635 <hr class="noprint" />
636 <h1 class="np" id="rfc.toc"><a href="#rfc.toc">Table of Contents</a></h1>
637 <ul class="toc">
638
639 <li>1. <a href="#rfc.section.1">Requirements notation</a></li>
640 <li>2. <a href="#rfc.section.2">Versioning of this specification</a></li>
641 <li>3. <a href="#rfc.section.3">Introduction</a></li>
642 <li>4. <a href="#rfc.section.4">Focus of this protocol</a></li>
643 <li>5. <a href="#rfc.section.5">Communication Overview</a></li>
644 <ul><li>5.1. <a href="#rfc.section.5.1">Request/response communication method</a></li>
645 <ul><li>5.1.1. <a href="#rfc.section.5.1.1">Result format</a></li>
646 </ul><li>5.2. <a href="#rfc.section.5.2">Subscribe/notify communication method</a></li>
647 </ul><li>6. <a href="#rfc.section.6">Description for control commands</a></li>
648 <ul><li>6.1. <a href="#rfc.section.6.1">Ignored lines and comments</a></li>
649 <li>6.2. <a href="#rfc.section.6.2">Configuring audio drivers</a></li>
650 <ul><li>6.2.1. <a href="#rfc.section.6.2.1">Getting amount of available audio output drivers</a></li>
651 <li>6.2.2. <a href="#rfc.section.6.2.2">Getting all available audio output drivers</a></li>
652 <li>6.2.3. <a href="#rfc.section.6.2.3">Getting information about a specific audio output driver</a></li>
653 <li>6.2.4. <a href="#rfc.section.6.2.4">Getting information about specific audio output driver parameter</a></li>
654 <li>6.2.5. <a href="#rfc.section.6.2.5">Creating an audio output device</a></li>
655 <li>6.2.6. <a href="#rfc.section.6.2.6">Destroying an audio output device</a></li>
656 <li>6.2.7. <a href="#rfc.section.6.2.7">Getting all created audio output device count</a></li>
657 <li>6.2.8. <a href="#rfc.section.6.2.8">Getting all created audio output device list</a></li>
658 <li>6.2.9. <a href="#rfc.section.6.2.9">Getting current settings of an audio output device</a></li>
659 <li>6.2.10. <a href="#rfc.section.6.2.10">Changing settings of audio output devices</a></li>
660 <li>6.2.11. <a href="#rfc.section.6.2.11">Getting information about an audio channel</a></li>
661 <li>6.2.12. <a href="#rfc.section.6.2.12">Getting information about specific audio channel parameter</a></li>
662 <li>6.2.13. <a href="#rfc.section.6.2.13">Changing settings of audio output channels</a></li>
663 </ul><li>6.3. <a href="#rfc.section.6.3">Configuring MIDI input drivers</a></li>
664 <ul><li>6.3.1. <a href="#rfc.section.6.3.1">Getting amount of available MIDI input drivers</a></li>
665 <li>6.3.2. <a href="#rfc.section.6.3.2">Getting all available MIDI input drivers</a></li>
666 <li>6.3.3. <a href="#rfc.section.6.3.3">Getting information about a specific MIDI input driver</a></li>
667 <li>6.3.4. <a href="#rfc.section.6.3.4">Getting information about specific MIDI input driver parameter</a></li>
668 <li>6.3.5. <a href="#rfc.section.6.3.5">Creating a MIDI input device</a></li>
669 <li>6.3.6. <a href="#rfc.section.6.3.6">Destroying a MIDI input device</a></li>
670 <li>6.3.7. <a href="#rfc.section.6.3.7">Getting all created MIDI input device count</a></li>
671 <li>6.3.8. <a href="#rfc.section.6.3.8">Getting all created MIDI input device list</a></li>
672 <li>6.3.9. <a href="#rfc.section.6.3.9">Getting current settings of a MIDI input device</a></li>
673 <li>6.3.10. <a href="#rfc.section.6.3.10">Changing settings of MIDI input devices</a></li>
674 <li>6.3.11. <a href="#rfc.section.6.3.11">Getting information about a MIDI port</a></li>
675 <li>6.3.12. <a href="#rfc.section.6.3.12">Getting information about specific MIDI port parameter</a></li>
676 <li>6.3.13. <a href="#rfc.section.6.3.13">Changing settings of MIDI input ports</a></li>
677 </ul><li>6.4. <a href="#rfc.section.6.4">Configuring sampler channels</a></li>
678 <ul><li>6.4.1. <a href="#rfc.section.6.4.1">Loading an instrument</a></li>
679 <li>6.4.2. <a href="#rfc.section.6.4.2">Loading a sampler engine</a></li>
680 <li>6.4.3. <a href="#rfc.section.6.4.3">Getting all created sampler channel count</a></li>
681 <li>6.4.4. <a href="#rfc.section.6.4.4">Getting all created sampler channel list</a></li>
682 <li>6.4.5. <a href="#rfc.section.6.4.5">Adding a new sampler channel</a></li>
683 <li>6.4.6. <a href="#rfc.section.6.4.6">Removing a sampler channel</a></li>
684 <li>6.4.7. <a href="#rfc.section.6.4.7">Getting amount of available engines</a></li>
685 <li>6.4.8. <a href="#rfc.section.6.4.8">Getting all available engines</a></li>
686 <li>6.4.9. <a href="#rfc.section.6.4.9">Getting information about an engine</a></li>
687 <li>6.4.10. <a href="#rfc.section.6.4.10">Getting sampler channel information</a></li>
688 <li>6.4.11. <a href="#rfc.section.6.4.11">Current number of active voices</a></li>
689 <li>6.4.12. <a href="#rfc.section.6.4.12">Current number of active disk streams</a></li>
690 <li>6.4.13. <a href="#rfc.section.6.4.13">Current fill state of disk stream buffers</a></li>
691 <li>6.4.14. <a href="#rfc.section.6.4.14">Setting audio output device</a></li>
692 <li>6.4.15. <a href="#rfc.section.6.4.15">Setting audio output type</a></li>
693 <li>6.4.16. <a href="#rfc.section.6.4.16">Setting audio output channel</a></li>
694 <li>6.4.17. <a href="#rfc.section.6.4.17">Add MIDI input to sampler channel</a></li>
695 <li>6.4.18. <a href="#rfc.section.6.4.18">Remove MIDI input(s) from sampler channel</a></li>
696 <li>6.4.19. <a href="#rfc.section.6.4.19">Getting all MIDI inputs of a sampler channel</a></li>
697 <li>6.4.20. <a href="#rfc.section.6.4.20">Setting MIDI input device</a></li>
698 <li>6.4.21. <a href="#rfc.section.6.4.21">Setting MIDI input type</a></li>
699 <li>6.4.22. <a href="#rfc.section.6.4.22">Setting MIDI input port</a></li>
700 <li>6.4.23. <a href="#rfc.section.6.4.23">Setting MIDI input channel</a></li>
701 <li>6.4.24. <a href="#rfc.section.6.4.24">Setting channel volume</a></li>
702 <li>6.4.25. <a href="#rfc.section.6.4.25">Muting a sampler channel</a></li>
703 <li>6.4.26. <a href="#rfc.section.6.4.26">Soloing a sampler channel</a></li>
704 <li>6.4.27. <a href="#rfc.section.6.4.27">Assigning a MIDI instrument map to a sampler channel</a></li>
705 <li>6.4.28. <a href="#rfc.section.6.4.28">Adding an effect send to a sampler channel</a></li>
706 <li>6.4.29. <a href="#rfc.section.6.4.29">Removing an effect send from a sampler channel</a></li>
707 <li>6.4.30. <a href="#rfc.section.6.4.30">Getting amount of effect sends on a sampler channel</a></li>
708 <li>6.4.31. <a href="#rfc.section.6.4.31">Listing all effect sends on a sampler channel</a></li>
709 <li>6.4.32. <a href="#rfc.section.6.4.32">Getting effect send information</a></li>
710 <li>6.4.33. <a href="#rfc.section.6.4.33">Changing effect send's name</a></li>
711 <li>6.4.34. <a href="#rfc.section.6.4.34">Altering effect send's audio routing</a></li>
712 <li>6.4.35. <a href="#rfc.section.6.4.35">Assigning destination effect to an effect send</a></li>
713 <li>6.4.36. <a href="#rfc.section.6.4.36">Removing destination effect from an effect send</a></li>
714 <li>6.4.37. <a href="#rfc.section.6.4.37">Altering effect send's MIDI controller</a></li>
715 <li>6.4.38. <a href="#rfc.section.6.4.38">Altering effect send's send level</a></li>
716 <li>6.4.39. <a href="#rfc.section.6.4.39">Sending MIDI messages to sampler channel</a></li>
717 <li>6.4.40. <a href="#rfc.section.6.4.40">Resetting a sampler channel</a></li>
718 </ul><li>6.5. <a href="#rfc.section.6.5">Controlling connection</a></li>
719 <ul><li>6.5.1. <a href="#rfc.section.6.5.1">Register front-end for receiving event messages</a></li>
720 <li>6.5.2. <a href="#rfc.section.6.5.2">Unregister front-end for not receiving event messages</a></li>
721 <li>6.5.3. <a href="#rfc.section.6.5.3">Enable or disable echo of commands</a></li>
722 <li>6.5.4. <a href="#rfc.section.6.5.4">Close client connection</a></li>
723 </ul><li>6.6. <a href="#rfc.section.6.6">Global commands</a></li>
724 <ul><li>6.6.1. <a href="#rfc.section.6.6.1">Current number of active voices</a></li>
725 <li>6.6.2. <a href="#rfc.section.6.6.2">Maximum amount of active voices</a></li>
726 <li>6.6.3. <a href="#rfc.section.6.6.3">Current number of active disk streams</a></li>
727 <li>6.6.4. <a href="#rfc.section.6.6.4">Reset sampler</a></li>
728 <li>6.6.5. <a href="#rfc.section.6.6.5">General sampler information</a></li>
729 <li>6.6.6. <a href="#rfc.section.6.6.6">Getting global volume attenuation</a></li>
730 <li>6.6.7. <a href="#rfc.section.6.6.7">Setting global volume attenuation</a></li>
731 <li>6.6.8. <a href="#rfc.section.6.6.8">Getting global voice limit</a></li>
732 <li>6.6.9. <a href="#rfc.section.6.6.9">Setting global voice limit</a></li>
733 <li>6.6.10. <a href="#rfc.section.6.6.10">Getting global disk stream limit</a></li>
734 <li>6.6.11. <a href="#rfc.section.6.6.11">Setting global disk stream limit</a></li>
735 </ul><li>6.7. <a href="#rfc.section.6.7">MIDI Instrument Mapping</a></li>
736 <ul><li>6.7.1. <a href="#rfc.section.6.7.1">Create a new MIDI instrument map</a></li>
737 <li>6.7.2. <a href="#rfc.section.6.7.2">Delete one particular or all MIDI instrument maps</a></li>
738 <li>6.7.3. <a href="#rfc.section.6.7.3">Get amount of existing MIDI instrument maps</a></li>
739 <li>6.7.4. <a href="#rfc.section.6.7.4">Getting all created MIDI instrument maps</a></li>
740 <li>6.7.5. <a href="#rfc.section.6.7.5">Getting MIDI instrument map information</a></li>
741 <li>6.7.6. <a href="#rfc.section.6.7.6">Renaming a MIDI instrument map</a></li>
742 <li>6.7.7. <a href="#rfc.section.6.7.7">Create or replace a MIDI instrument map entry</a></li>
743 <li>6.7.8. <a href="#rfc.section.6.7.8">Getting amount of MIDI instrument map entries</a></li>
744 <li>6.7.9. <a href="#rfc.section.6.7.9">Getting indeces of all entries of a MIDI instrument map</a></li>
745 <li>6.7.10. <a href="#rfc.section.6.7.10">Remove an entry from the MIDI instrument map</a></li>
746 <li>6.7.11. <a href="#rfc.section.6.7.11">Get current settings of MIDI instrument map entry</a></li>
747 <li>6.7.12. <a href="#rfc.section.6.7.12">Clear MIDI instrument map</a></li>
748 </ul><li>6.8. <a href="#rfc.section.6.8">Managing Instruments Database</a></li>
749 <ul><li>6.8.1. <a href="#rfc.section.6.8.1">Creating a new instrument directory</a></li>
750 <li>6.8.2. <a href="#rfc.section.6.8.2">Deleting an instrument directory</a></li>
751 <li>6.8.3. <a href="#rfc.section.6.8.3">Getting amount of instrument directories</a></li>
752 <li>6.8.4. <a href="#rfc.section.6.8.4">Listing all directories in specific directory</a></li>
753 <li>6.8.5. <a href="#rfc.section.6.8.5">Getting instrument directory information</a></li>
754 <li>6.8.6. <a href="#rfc.section.6.8.6">Renaming an instrument directory</a></li>
755 <li>6.8.7. <a href="#rfc.section.6.8.7">Moving an instrument directory</a></li>
756 <li>6.8.8. <a href="#rfc.section.6.8.8">Copying instrument directories</a></li>
757 <li>6.8.9. <a href="#rfc.section.6.8.9">Changing the description of directory</a></li>
758 <li>6.8.10. <a href="#rfc.section.6.8.10">Finding directories</a></li>
759 <li>6.8.11. <a href="#rfc.section.6.8.11">Adding instruments to the instruments database</a></li>
760 <li>6.8.12. <a href="#rfc.section.6.8.12">Removing an instrument</a></li>
761 <li>6.8.13. <a href="#rfc.section.6.8.13">Getting amount of instruments</a></li>
762 <li>6.8.14. <a href="#rfc.section.6.8.14">Listing all instruments in specific directory</a></li>
763 <li>6.8.15. <a href="#rfc.section.6.8.15">Getting instrument information</a></li>
764 <li>6.8.16. <a href="#rfc.section.6.8.16">Renaming an instrument</a></li>
765 <li>6.8.17. <a href="#rfc.section.6.8.17">Moving an instrument</a></li>
766 <li>6.8.18. <a href="#rfc.section.6.8.18">Copying instruments</a></li>
767 <li>6.8.19. <a href="#rfc.section.6.8.19">Changing the description of instrument</a></li>
768 <li>6.8.20. <a href="#rfc.section.6.8.20">Finding instruments</a></li>
769 <li>6.8.21. <a href="#rfc.section.6.8.21">Getting job status information</a></li>
770 <li>6.8.22. <a href="#rfc.section.6.8.22">Formatting the instruments database</a></li>
771 <li>6.8.23. <a href="#rfc.section.6.8.23">Checking for lost instrument files</a></li>
772 <li>6.8.24. <a href="#rfc.section.6.8.24">Replacing an instrument file</a></li>
773 </ul><li>6.9. <a href="#rfc.section.6.9">Editing Instruments</a></li>
774 <ul><li>6.9.1. <a href="#rfc.section.6.9.1">Opening an appropriate instrument editor application</a></li>
775 </ul><li>6.10. <a href="#rfc.section.6.10">Managing Files</a></li>
776 <ul><li>6.10.1. <a href="#rfc.section.6.10.1">Retrieving amount of instruments of a file</a></li>
777 <li>6.10.2. <a href="#rfc.section.6.10.2">Retrieving all instruments of a file</a></li>
778 <li>6.10.3. <a href="#rfc.section.6.10.3">Retrieving information about one instrument in a file</a></li>
779 </ul><li>6.11. <a href="#rfc.section.6.11">Managing Effects</a></li>
780 <ul><li>6.11.1. <a href="#rfc.section.6.11.1">Retrieve amount of available effects</a></li>
781 <li>6.11.2. <a href="#rfc.section.6.11.2">Get list of available effects</a></li>
782 <li>6.11.3. <a href="#rfc.section.6.11.3">Retrieving general information about an effect</a></li>
783 <li>6.11.4. <a href="#rfc.section.6.11.4">Creating an instance of an effect by its portable ID</a></li>
784 <li>6.11.5. <a href="#rfc.section.6.11.5">Creating an instance of an effect by its numerical ID</a></li>
785 <li>6.11.6. <a href="#rfc.section.6.11.6">Destroy an effect instance</a></li>
786 <li>6.11.7. <a href="#rfc.section.6.11.7">Retrieve amount of effect instances</a></li>
787 <li>6.11.8. <a href="#rfc.section.6.11.8">Get list of effect instances</a></li>
788 <li>6.11.9. <a href="#rfc.section.6.11.9">Retrieving current information about an effect instance</a></li>
789 <li>6.11.10. <a href="#rfc.section.6.11.10">Retrieving information about an effect parameter</a></li>
790 <li>6.11.11. <a href="#rfc.section.6.11.11">Altering an effect parameter</a></li>
791 <li>6.11.12. <a href="#rfc.section.6.11.12">Retrieve amount of send effect chains</a></li>
792 <li>6.11.13. <a href="#rfc.section.6.11.13">Retrieve list of send effect chains</a></li>
793 <li>6.11.14. <a href="#rfc.section.6.11.14">Add send effect chain</a></li>
794 <li>6.11.15. <a href="#rfc.section.6.11.15">Remove send effect chain</a></li>
795 <li>6.11.16. <a href="#rfc.section.6.11.16">Retrieving information about a send effect chain</a></li>
796 <li>6.11.17. <a href="#rfc.section.6.11.17">Append effect instance to a send effect chain</a></li>
797 <li>6.11.18. <a href="#rfc.section.6.11.18">Insert effect instance to a send effect chain</a></li>
798 <li>6.11.19. <a href="#rfc.section.6.11.19">Remove effect instance from send effect chain</a></li>
799 </ul></ul><li>7. <a href="#rfc.section.7">Command Syntax</a></li>
800 <ul><li>7.1. <a href="#rfc.section.7.1">Character Set and Escape Sequences</a></li>
801 </ul><li>8. <a href="#rfc.section.8">Events</a></li>
802 <ul><li>8.1. <a href="#rfc.section.8.1">Number of audio output devices changed</a></li>
803 <li>8.2. <a href="#rfc.section.8.2">Audio output device's settings changed</a></li>
804 <li>8.3. <a href="#rfc.section.8.3">Number of MIDI input devices changed</a></li>
805 <li>8.4. <a href="#rfc.section.8.4">MIDI input device's settings changed</a></li>
806 <li>8.5. <a href="#rfc.section.8.5">Number of sampler channels changed</a></li>
807 <li>8.6. <a href="#rfc.section.8.6">MIDI data on a sampler channel arrived</a></li>
808 <li>8.7. <a href="#rfc.section.8.7">MIDI data on a MIDI input device arrived</a></li>
809 <li>8.8. <a href="#rfc.section.8.8">Number of active voices changed</a></li>
810 <li>8.9. <a href="#rfc.section.8.9">Number of active disk streams changed</a></li>
811 <li>8.10. <a href="#rfc.section.8.10">Disk stream buffer fill state changed</a></li>
812 <li>8.11. <a href="#rfc.section.8.11">Channel information changed</a></li>
813 <li>8.12. <a href="#rfc.section.8.12">Number of effect sends changed</a></li>
814 <li>8.13. <a href="#rfc.section.8.13">Effect send information changed</a></li>
815 <li>8.14. <a href="#rfc.section.8.14">Total number of active voices changed</a></li>
816 <li>8.15. <a href="#rfc.section.8.15">Total number of active disk streams changed</a></li>
817 <li>8.16. <a href="#rfc.section.8.16">Number of MIDI instrument maps changed</a></li>
818 <li>8.17. <a href="#rfc.section.8.17">MIDI instrument map information changed</a></li>
819 <li>8.18. <a href="#rfc.section.8.18">Number of MIDI instruments changed</a></li>
820 <li>8.19. <a href="#rfc.section.8.19">MIDI instrument information changed</a></li>
821 <li>8.20. <a href="#rfc.section.8.20">Global settings changed</a></li>
822 <li>8.21. <a href="#rfc.section.8.21">Number of database instrument directories changed</a></li>
823 <li>8.22. <a href="#rfc.section.8.22">Database instrument directory information changed</a></li>
824 <li>8.23. <a href="#rfc.section.8.23">Number of database instruments changed</a></li>
825 <li>8.24. <a href="#rfc.section.8.24">Database instrument information changed</a></li>
826 <li>8.25. <a href="#rfc.section.8.25">Database job status information changed</a></li>
827 <li>8.26. <a href="#rfc.section.8.26">Number of effect instances changed</a></li>
828 <li>8.27. <a href="#rfc.section.8.27">Effect instance information changed</a></li>
829 <li>8.28. <a href="#rfc.section.8.28">Number of send effect chains changed</a></li>
830 <li>8.29. <a href="#rfc.section.8.29">Send effect chain information changed</a></li>
831 <li>8.30. <a href="#rfc.section.8.30">Miscellaneous and debugging events</a></li>
832 </ul><li>9. <a href="#rfc.section.9">Security Considerations</a></li>
833 <li>10. <a href="#rfc.section.10">Acknowledgments</a></li>
834 <li>11. <a href="#rfc.references">References</a></li>
835 <li><a href="#rfc.authors">Author's Address</a></li>
836
837
838 </ul>
839
840 <h1 id="rfc.section.1"><a href="#rfc.section.1">1.</a> Requirements notation</h1>
841 <p id="rfc.section.1.p.1">The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in <a href="#RFC2119">[RFC2119]</a>.</p>
842 <p id="rfc.section.1.p.2">This protocol is always case-sensitive if not explicitly claimed the opposite.</p>
843 <p id="rfc.section.1.p.3">In examples, "C:" and "S:" indicate lines sent by the client (front-end) and server (LinuxSampler) respectively. Lines in examples must be interpreted as every line being CRLF terminated (carriage return character followed by line feed character as defined in the ASCII standard <a href="#RFC20">[RFC20]</a>), thus the following example:</p>
844 <p/>
845
846 <ul class="empty">
847 <li>C: "some line"</li>
848 <li>"another line"</li>
849 </ul>
850
851 <p> </p>
852 <p id="rfc.section.1.p.5">must actually be interpreted as client sending the following message:</p>
853 <p/>
854
855 <ul class="empty">
856 <li>"some line&lt;CR&gt;&lt;LF&gt;another line&lt;CR&gt;&lt;LF&gt;"</li>
857 </ul>
858
859 <p> </p>
860 <p id="rfc.section.1.p.7">where &lt;CR&gt; symbolizes the carriage return character and &lt;LF&gt; the line feed character as defined in the ASCII standard.</p>
861 <p id="rfc.section.1.p.8">Due to technical reasons, messages can arbitrary be fragmented, means the following example:</p>
862 <p/>
863
864 <ul class="empty">
865 <li>S: "abcd"</li>
866 </ul>
867
868 <p> </p>
869 <p id="rfc.section.1.p.10">could also happen to be sent in three messages like in the following sequence scenario:</p>
870 <p/>
871
872 <ul>
873 <li>server sending message "a"</li>
874 <li>followed by a delay (pause) with arbitrary duration</li>
875 <li>followed by server sending message "bcd&lt;CR&gt;"</li>
876 <li>again followed by a delay (pause) with arbitrary duration</li>
877 <li>followed by server sending the message "&lt;LF&gt;"</li>
878 </ul>
879
880 <p> </p>
881 <p id="rfc.section.1.p.12">where again &lt;CR&gt; and &lt;LF&gt; symbolize the carriage return and line feed characters respectively.</p>
882 <h1 id="rfc.section.2"><a href="#rfc.section.2">2.</a> <a href="#LSCP versioning" id="LSCP versioning">Versioning of this specification</a></h1>
883 <p id="rfc.section.2.p.1">LSCP will certainly be extended and enhanced by-and-by. Each official release of the LSCP specification will be tagged with a unique version tuple. The version tuple consists at least of a major and minor version number like: </p>
884 <p/>
885
886 <ul class="empty">
887 <li>"1.2"</li>
888 </ul>
889
890 <p> </p>
891 <p id="rfc.section.2.p.3">In this example the major version number would be "1" and the minor version number would be "2". Note that the version tuple might also have more than two elements. The major version number defines a group of backward compatible versions. That means a frontend is compatible to the connected sampler if and only if the LSCP versions to which each of the two parties complies to, match both of the following rules: </p>
892 <p id="rfc.section.2.p.4">Compatibility:</p>
893 <p/>
894
895 <ol>
896 <li>The frontend's LSCP major version and the sampler's LSCP major version are exactly equal.</li>
897 <li>The frontend's LSCP minor version is less or equal than the sampler's LSCP minor version.</li>
898 </ol>
899
900 <p> </p>
901 <p id="rfc.section.2.p.6">Compatibility can only be claimed if both rules are true. The frontend can use the <a href="#GET SERVER INFO">"GET SERVER INFO"</a> <cite title="NONE">[GET SERVER INFO]</cite> command to get the version of the LSCP specification the sampler complies with. </p>
902 <h1 id="rfc.section.3"><a href="#rfc.section.3">3.</a> Introduction</h1>
903 <p id="rfc.section.3.p.1">LinuxSampler is a so called software sampler application capable to playback audio samples from a computer's Random Access Memory (RAM) as well as directly streaming it from disk. LinuxSampler is designed to be modular. It provides several so called "sampler engines" where each engine is specialized for a certain purpose. LinuxSampler has virtual channels which will be referred in this document as "sampler channels". The channels are in such way virtual as they can be connected to an arbitrary MIDI input method and arbitrary MIDI channel (e.g. sampler channel 17 could be connected to an ALSA sequencer device 64:0 and listening to MIDI channel 1 there). Each sampler channel will be associated with an instance of one of the available sampler engines (e.g. GigEngine, DLSEngine). The audio output of each sampler channel can be routed to an arbitrary audio output method (ALSA / JACK) and an arbitrary audio output channel there.</p>
904 <h1 id="rfc.section.4"><a href="#rfc.section.4">4.</a> Focus of this protocol</h1>
905 <p id="rfc.section.4.p.1">Main focus of this protocol is to provide a way to configure a running LinuxSampler instance and to retrieve information about it. The focus of this protocol is not to provide a way to control synthesis parameters or even to trigger or release notes. Or in other words; the focus are those functionalities which are not covered by MIDI or which may at most be handled via MIDI System Exclusive Messages.</p>
906 <h1 id="rfc.section.5"><a href="#rfc.section.5">5.</a> Communication Overview</h1>
907 <p id="rfc.section.5.p.1">There are two distinct methods of communication between a running instance of LinuxSampler and one or more control applications, so called "front-ends": a simple request/response communication method used by the clients to give commands to the server as well as to inquire about server's status and a subscribe/notify communication method used by the client to subscribe to and receive notifications of certain events as they happen on the server. The latter needs more effort to be implemented in the front-end application. The two communication methods will be described next.</p>
908 <h1 id="rfc.section.5.1"><a href="#rfc.section.5.1">5.1.</a> Request/response communication method</h1>
909 <p id="rfc.section.5.1.p.1">This simple communication method is based on <a href="#RFC793">TCP</a> <cite title="NONE">[RFC793]</cite>. The front-end application establishes a TCP connection to the LinuxSampler instance on a certain host system. Then the front-end application will send certain ASCII based commands as defined in this document (every command line must be CRLF terminated - see "Conventions used in this document" at the beginning of this document) and the LinuxSampler application will response after a certain process time with an appropriate ASCII based answer, also as defined in this document. So this TCP communication is simply based on query and answer paradigm. That way LinuxSampler is only able to answer on queries from front-ends, but not able to automatically send messages to the client if it's not asked to. The fronted should not reconnect to LinuxSampler for every single command, instead it should keep the connection established and simply resend message(s) for subsequent commands. To keep information in the front-end up-to-date the front-end has to periodically send new requests to get the current information from the LinuxSampler instance. This is often referred to as "polling". While polling is simple to implement and may be OK to use in some cases, there may be disadvantages to polling such as network traffic overhead and information being out of date. It is possible for a client or several clients to open more than one connection to the server at the same time. It is also possible to send more than one request to the server at the same time but if those requests are sent over the same connection server MUST execute them sequentially. Upon executing a request server will produce a result set and send it to the client. Each and every request made by the client MUST result in a result set being sent back to the client. No other data other than a result set may be sent by a server to a client. No result set may be sent to a client without the client sending request to the server first. On any particular connection, result sets MUST be sent in their entirety without being interrupted by other result sets. If several requests got queued up at the server they MUST be processed in the order they were received and result sets MUST be sent back in the same order.</p>
910 <h1 id="rfc.section.5.1.1"><a href="#rfc.section.5.1.1">5.1.1.</a> Result format</h1>
911 <p id="rfc.section.5.1.1.p.1">Result set could be one of the following types:</p>
912 <p/>
913
914 <ol>
915 <li>Normal</li>
916 <li>Warning</li>
917 <li>Error</li>
918 </ol>
919
920 <p> </p>
921 <p id="rfc.section.5.1.1.p.3">Warning and Error result sets MUST be single line and have the following format:</p>
922 <p/>
923
924 <ul>
925 <li>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;"</li>
926 <li>"ERR:&lt;error-code&gt;:&lt;error-message&gt;"</li>
927 </ul>
928
929 <p> </p>
930 <p id="rfc.section.5.1.1.p.5">Where &lt;warning-code&gt; and &lt;error-code&gt; are numeric unique identifiers of the warning or error and &lt;warning-message&gt; and &lt;error-message&gt; are human readable descriptions of the warning or error respectively.</p>
931 <p id="rfc.section.5.1.1.p.6">Examples:</p>
932 <p/>
933
934 <ul class="empty">
935 <li>C: "LOAD INSTRUMENT '/home/me/Boesendorfer24bit.gig" 0 0</li>
936 <li>S: "WRN:32:This is a 24 bit patch which is not supported natively yet."</li>
937 </ul>
938
939 <p> </p>
940 <p/>
941
942 <ul class="empty">
943 <li>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA EAR"</li>
944 <li>S: "ERR:3456:Audio output driver 'ALSA' does not have a parameter 'EAR'."</li>
945 </ul>
946
947 <p> </p>
948 <p/>
949
950 <ul class="empty">
951 <li>C: "GET AUDIO_OUTPUT_DEVICE INFO 123456"</li>
952 <li>S: "ERR:9:There is no audio output device with index 123456."</li>
953 </ul>
954
955 <p> </p>
956 <p id="rfc.section.5.1.1.p.10">Normal result sets could be:</p>
957 <p/>
958
959 <ol>
960 <li>Empty</li>
961 <li>Single line</li>
962 <li>Multi-line</li>
963 </ol>
964
965 <p> </p>
966 <p id="rfc.section.5.1.1.p.12">Empty result set is issued when the server only needed to acknowledge the fact that the request was received and it was processed successfully and no additional information is available. This result set has the following format:</p>
967 <p/>
968
969 <ul class="empty">
970 <li>"OK"</li>
971 </ul>
972
973 <p> </p>
974 <p id="rfc.section.5.1.1.p.14">Example:</p>
975 <p/>
976
977 <ul class="empty">
978 <li>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 CHANNELS=4"</li>
979 <li>S: "OK"</li>
980 </ul>
981
982 <p> </p>
983 <p id="rfc.section.5.1.1.p.16">Single line result sets are command specific. One example of a single line result set is an empty line. Multi-line result sets are command specific and may include one or more lines of information. They MUST always end with the following line:</p>
984 <p/>
985
986 <ul class="empty">
987 <li>"."</li>
988 </ul>
989
990 <p> </p>
991 <p id="rfc.section.5.1.1.p.18">Example:</p>
992 <p/>
993
994 <ul class="empty">
995 <li>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"</li>
996 <li>S: "DRIVER: ALSA"</li>
997 <li>"CHANNELS: 2"</li>
998 <li>"SAMPLERATE: 44100"</li>
999 <li>"ACTIVE: true"</li>
1000 <li>"FRAGMENTS: 2"</li>
1001 <li>"FRAGMENTSIZE: 128"</li>
1002 <li>"CARD: '0,0'"</li>
1003 <li>"."</li>
1004 </ul>
1005
1006 <p> </p>
1007 <p id="rfc.section.5.1.1.p.20">In addition to above mentioned formats, warnings and empty result sets MAY be indexed. In this case, they have the following formats respectively:</p>
1008 <p/>
1009
1010 <ul>
1011 <li>"WRN[&lt;index&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;"</li>
1012 <li>"OK[&lt;index&gt;]"</li>
1013 </ul>
1014
1015 <p> </p>
1016 <p id="rfc.section.5.1.1.p.22">where &lt;index&gt; is command specific and is used to indicate channel number that the result set was related to or other integer value.</p>
1017 <p id="rfc.section.5.1.1.p.23">Each line of the result set MUST end with &lt;CRLF&gt;.</p>
1018 <p id="rfc.section.5.1.1.p.24">Examples:</p>
1019 <p/>
1020
1021 <ul class="empty">
1022 <li>C: "ADD CHANNEL"</li>
1023 <li>S: "OK[12]"</li>
1024 </ul>
1025
1026 <p> </p>
1027 <p/>
1028
1029 <ul class="empty">
1030 <li>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"</li>
1031 <li>S: "WRN[0]:32:Sample rate not supported, using 44100 instead."</li>
1032 </ul>
1033
1034 <p> </p>
1035 <h1 id="rfc.section.5.2"><a href="#rfc.section.5.2">5.2.</a> Subscribe/notify communication method</h1>
1036 <p id="rfc.section.5.2.p.1">This more sophisticated communication method is actually only an extension of the simple request/response communication method. The front-end still uses a TCP connection and sends the same commands on the TCP connection. Two extra commands are SUBSCRIBE and UNSUBSCRIBE commands that allow a client to tell the server that it is interested in receiving notifications about certain events as they happen on the server. The SUBSCRIBE command has the following syntax:</p>
1037 <p/>
1038
1039 <ul class="empty">
1040 <li>SUBSCRIBE &lt;event-id&gt;</li>
1041 </ul>
1042
1043 <p> </p>
1044 <p id="rfc.section.5.2.p.3">where &lt;event-id&gt; will be replaced by the respective event that client wants to subscribe to. Upon receiving such request, server SHOULD respond with OK and start sending EVENT notifications when a given even has occurred to the front-end when an event has occurred. It MAY be possible certain events may be sent before OK response during real time nature of their generation. Event messages have the following format:</p>
1045 <p/>
1046
1047 <ul class="empty">
1048 <li>NOTIFY:&lt;event-id&gt;:&lt;custom-event-data&gt;</li>
1049 </ul>
1050
1051 <p> </p>
1052 <p id="rfc.section.5.2.p.5">where &lt;event-id&gt; uniquely identifies the event that has occurred and &lt;custom-event-data&gt; is event specific.</p>
1053 <p id="rfc.section.5.2.p.6">Several rules must be followed by the server when generating events:</p>
1054 <p/>
1055
1056 <ol>
1057 <li>Events MUST NOT be sent to any client who has not issued an appropriate SUBSCRIBE command.</li>
1058 <li>Events MUST only be sent using the same connection that was used to subscribe to them.</li>
1059 <li>When response is being sent to the client, event MUST be inserted in the stream before or after the response, but NOT in the middle. Same is true about the response. It should never be inserted in the middle of the event message as well as any other response.</li>
1060 </ol>
1061
1062 <p> </p>
1063 <p id="rfc.section.5.2.p.8">If the client is not interested in a particular event anymore it MAY issue UNSUBSCRIBE command using the following syntax:</p>
1064 <p/>
1065
1066 <ul class="empty">
1067 <li>UNSUBSCRIBE &lt;event-id&gt;</li>
1068 </ul>
1069
1070 <p> </p>
1071 <p id="rfc.section.5.2.p.10">where &lt;event-id&gt; will be replace by the respective event that client is no longer interested in receiving. For a list of supported events see <a href="#events">Section 8</a>.</p>
1072 <p id="rfc.section.5.2.p.11">Example: the fill states of disk stream buffers have changed on sampler channel 4 and the LinuxSampler instance will react by sending the following message to all clients who subscribed to this event:</p>
1073 <p/>
1074
1075 <ul class="empty">
1076 <li>NOTIFY:CHANNEL_BUFFER_FILL:4 [35]62%,[33]80%,[37]98%</li>
1077 </ul>
1078
1079 <p> </p>
1080 <p id="rfc.section.5.2.p.13">Which means there are currently three active streams on sampler channel 4, where the stream with ID "35" is filled by 62%, stream with ID 33 is filled by 80% and stream with ID 37 is filled by 98%.</p>
1081 <p id="rfc.section.5.2.p.14">Clients may choose to open more than one connection to the server and use some connections to receive notifications while using other connections to issue commands to the back-end. This is entirely legal and up to the implementation. This does not change the protocol in any way and no special restrictions exist on the server to allow or disallow this or to track what connections belong to what front-ends. Server will listen on a single port, accept multiple connections and support protocol described in this specification in it's entirety on this single port on each connection that it accepted.</p>
1082 <p id="rfc.section.5.2.p.15">Due to the fact that TCP is used for this communication, dead peers will be detected automatically by the OS TCP stack. While it may take a while to detect dead peers if no traffic is being sent from server to client (TCP keep-alive timer is set to 2 hours on many OSes) it will not be an issue here as when notifications are sent by the server, dead client will be detected quickly.</p>
1083 <p id="rfc.section.5.2.p.16">When connection is closed for any reason server MUST forget all subscriptions that were made on this connection. If client reconnects it MUST resubscribe to all events that it wants to receive.</p>
1084 <h1 id="rfc.section.6"><a href="#rfc.section.6">6.</a> <a href="#control_commands" id="control_commands">Description for control commands</a></h1>
1085 <p id="rfc.section.6.p.1">This chapter will describe the available control commands that can be sent on the TCP connection in detail. Some certain commands (e.g. <a href="#GET CHANNEL INFO">"GET CHANNEL INFO"</a> <cite title="NONE">[GET CHANNEL INFO]</cite> or <a href="#GET ENGINE INFO">"GET ENGINE INFO"</a> <cite title="NONE">[GET ENGINE INFO]</cite>) lead to multiple-line responses. In this case LinuxSampler signals the end of the response by a "." (single dot) line.</p>
1086 <h1 id="rfc.section.6.1"><a href="#rfc.section.6.1">6.1.</a> Ignored lines and comments</h1>
1087 <p id="rfc.section.6.1.p.1">White lines, that is lines which only contain space and tabulator characters, and lines that start with a "#" character are ignored, thus it's possible for example to group commands and to place comments in a LSCP script file.</p>
1088 <h1 id="rfc.section.6.2"><a href="#rfc.section.6.2">6.2.</a> Configuring audio drivers</h1>
1089 <p id="rfc.section.6.2.p.1">Instances of drivers in LinuxSampler are called devices. You can use multiple audio devices simultaneously, e.g. to output the sound of one sampler channel using the ALSA audio output driver, and on another sampler channel you might want to use the JACK audio output driver. For particular audio output systems it's also possible to create several devices of the same audio output driver, e.g. two separate ALSA audio output devices for using two different sound cards at the same time. This chapter describes all commands to configure LinuxSampler's audio output devices and their parameters.</p>
1090 <p id="rfc.section.6.2.p.2">Instead of defining commands and parameters for each driver individually, all possible parameters, their meanings and possible values have to be obtained at runtime. This makes the protocol a bit abstract, but has the advantage, that front-ends can be written independently of what drivers are currently implemented and what parameters these drivers are actually offering. This means front-ends can even handle drivers which are implemented somewhere in future without modifying the front-end at all.</p>
1091 <p id="rfc.section.6.2.p.3">Note: examples in this chapter showing particular parameters of drivers are not meant as specification of the drivers' parameters. Driver implementations in LinuxSampler might have complete different parameter names and meanings than shown in these examples or might change in future, so these examples are only meant for showing how to retrieve what parameters drivers are offering, how to retrieve their possible values, etc.</p>
1092 <h1 id="rfc.section.6.2.1"><a href="#rfc.section.6.2.1">6.2.1.</a> <a href="#GET AVAILABLE_AUDIO_OUTPUT_DRIVERS" id="GET AVAILABLE_AUDIO_OUTPUT_DRIVERS">Getting amount of available audio output drivers</a></h1>
1093 <p id="rfc.section.6.2.1.p.1">Use the following command to get the number of audio output drivers currently available for the LinuxSampler instance:</p>
1094 <p/>
1095
1096 <ul class="empty">
1097 <li>GET AVAILABLE_AUDIO_OUTPUT_DRIVERS</li>
1098 </ul>
1099
1100 <p> </p>
1101 <p id="rfc.section.6.2.1.p.3">Possible Answers:</p>
1102 <p/>
1103
1104 <ul class="empty">
1105 <li>LinuxSampler will answer by sending the number of audio output drivers.</li>
1106 </ul>
1107
1108 <p> </p>
1109 <p id="rfc.section.6.2.1.p.5">Example:</p>
1110 <p/>
1111
1112 <ul class="empty">
1113 <li>C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"</li>
1114 <li>S: "2"</li>
1115 </ul>
1116
1117 <p> </p>
1118 <h1 id="rfc.section.6.2.2"><a href="#rfc.section.6.2.2">6.2.2.</a> <a href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" id="LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">Getting all available audio output drivers</a></h1>
1119 <p id="rfc.section.6.2.2.p.1">Use the following command to list all audio output drivers currently available for the LinuxSampler instance:</p>
1120 <p/>
1121
1122 <ul class="empty">
1123 <li>LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS</li>
1124 </ul>
1125
1126 <p> </p>
1127 <p id="rfc.section.6.2.2.p.3">Possible Answers:</p>
1128 <p/>
1129
1130 <ul class="empty">
1131 <li>LinuxSampler will answer by sending comma separated character strings, each symbolizing an audio output driver.</li>
1132 </ul>
1133
1134 <p> </p>
1135 <p id="rfc.section.6.2.2.p.5">Example:</p>
1136 <p/>
1137
1138 <ul class="empty">
1139 <li>C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"</li>
1140 <li>S: "ALSA,JACK"</li>
1141 </ul>
1142
1143 <p> </p>
1144 <h1 id="rfc.section.6.2.3"><a href="#rfc.section.6.2.3">6.2.3.</a> <a href="#GET AUDIO_OUTPUT_DRIVER INFO" id="GET AUDIO_OUTPUT_DRIVER INFO">Getting information about a specific audio output driver</a></h1>
1145 <p id="rfc.section.6.2.3.p.1">Use the following command to get detailed information about a specific audio output driver:</p>
1146 <p/>
1147
1148 <ul class="empty">
1149 <li>GET AUDIO_OUTPUT_DRIVER INFO &lt;audio-output-driver&gt;</li>
1150 </ul>
1151
1152 <p> </p>
1153 <p id="rfc.section.6.2.3.p.3">Where &lt;audio-output-driver&gt; is the name of the audio output driver, returned by the <a href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"</a> <cite title="NONE">[LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS]</cite> command.</p>
1154 <p id="rfc.section.6.2.3.p.4">Possible Answers:</p>
1155 <p/>
1156
1157 <ul class="empty">
1158 <li>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list. Each answer line begins with the information category name followed by a colon and then a space character &lt;SP&gt; and finally the info character string to that info category. At the moment the following information categories are defined:</li>
1159 <li>
1160 <ul class="empty">
1161 <li>DESCRIPTION - <ul class="empty"><li>character string describing the audio output driver</li></ul><p> </p></li>
1162 <li>VERSION - <ul class="empty"><li>character string reflecting the driver's version</li></ul><p> </p></li>
1163 <li>PARAMETERS - <ul class="empty"><li>comma separated list of all parameters available for the given audio output driver, at least parameters 'channels', 'samplerate' and 'active' are offered by all audio output drivers</li></ul><p> </p></li>
1164 </ul>
1165 <p> </p>
1166 </li>
1167 <li>The mentioned fields above don't have to be in particular order.</li>
1168 </ul>
1169
1170 <p> </p>
1171 <p id="rfc.section.6.2.3.p.6">Example:</p>
1172 <p/>
1173
1174 <ul class="empty">
1175 <li>C: "GET AUDIO_OUTPUT_DRIVER INFO ALSA"</li>
1176 <li>S: "DESCRIPTION: Advanced Linux Sound Architecture"</li>
1177 <li>"VERSION: 1.0"</li>
1178 <li>"PARAMETERS: DRIVER,CHANNELS,SAMPLERATE,ACTIVE,FRAGMENTS, FRAGMENTSIZE,CARD"</li>
1179 <li>"."</li>
1180 </ul>
1181
1182 <p> </p>
1183 <h1 id="rfc.section.6.2.4"><a href="#rfc.section.6.2.4">6.2.4.</a> <a href="#GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO" id="GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO">Getting information about specific audio output driver parameter</a></h1>
1184 <p id="rfc.section.6.2.4.p.1">Use the following command to get detailed information about a specific audio output driver parameter:</p>
1185 <p/>
1186
1187 <ul class="empty">
1188 <li>GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO &lt;audio&gt; &lt;prm&gt; [&lt;deplist&gt;]</li>
1189 </ul>
1190
1191 <p> </p>
1192 <p id="rfc.section.6.2.4.p.3">Where &lt;audio&gt; is the name of the audio output driver as returned by the <a href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"</a> <cite title="NONE">[LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS]</cite> command, &lt;prm&gt; a specific parameter name for which information should be obtained (as returned by the <a href="#GET AUDIO_OUTPUT_DRIVER INFO">"GET AUDIO_OUTPUT_DRIVER INFO"</a> <cite title="NONE">[GET AUDIO_OUTPUT_DRIVER INFO]</cite> command) and &lt;deplist&gt; is an optional list of parameters on which the sought parameter &lt;prm&gt; depends on, &lt;deplist&gt; is a list of key-value pairs in form of "key1=val1 key2=val2 ...", where character string values are encapsulated into apostrophes ('). Arguments given with &lt;deplist&gt; which are not dependency parameters of &lt;prm&gt; will be ignored, means the front-end application can simply put all parameters into &lt;deplist&gt; with the values already selected by the user.</p>
1193 <p id="rfc.section.6.2.4.p.4">Possible Answers:</p>
1194 <p/>
1195
1196 <ul class="empty">
1197 <li>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list. Each answer line begins with the information category name followed by a colon and then a space character &lt;SP&gt; and finally the info character string to that info category. There are information which is always returned, independently of the given driver parameter and there are optional information which is only shown dependently to given driver parameter. At the moment the following information categories are defined:</li>
1198 </ul>
1199
1200 <p> </p>
1201 <p/>
1202
1203 <ul class="empty">
1204 <li>TYPE - <ul class="empty"><li>either "BOOL" for boolean value(s) or "INT" for integer value(s) or "FLOAT" for dotted number(s) or "STRING" for character string(s) (always returned, no matter which driver parameter)</li></ul><p> </p></li>
1205 <li>DESCRIPTION - <ul class="empty"><li>arbitrary text describing the purpose of the parameter (always returned, no matter which driver parameter)</li></ul><p> </p></li>
1206 <li>MANDATORY - <ul class="empty"><li>either true or false, defines if this parameter must be given when the device is to be created with the <a href="#CREATE AUDIO_OUTPUT_DEVICE">'CREATE AUDIO_OUTPUT_DEVICE'</a> <cite title="NONE">[CREATE AUDIO_OUTPUT_DEVICE]</cite> command (always returned, no matter which driver parameter)</li></ul><p> </p></li>
1207 <li>FIX - <ul class="empty"><li>either true or false, if false then this parameter can be changed at any time, once the device is created by the <a href="#CREATE AUDIO_OUTPUT_DEVICE">'CREATE AUDIO_OUTPUT_DEVICE'</a> <cite title="NONE">[CREATE AUDIO_OUTPUT_DEVICE]</cite> command (always returned, no matter which driver parameter)</li></ul><p> </p></li>
1208 <li>MULTIPLICITY - <ul class="empty"><li>either true or false, defines if this parameter allows only one value or a list of values, where true means multiple values and false only a single value allowed (always returned, no matter which driver parameter)</li></ul><p> </p></li>
1209 <li>DEPENDS - <ul class="empty"><li>comma separated list of parameters this parameter depends on, means the values for fields 'DEFAULT', 'RANGE_MIN', 'RANGE_MAX' and 'POSSIBILITIES' might depend on these listed parameters, for example assuming that an audio driver (like the ALSA driver) offers parameters 'card' and 'samplerate' then parameter 'samplerate' would depend on 'card' because the possible values for 'samplerate' depends on the sound card which can be chosen by the 'card' parameter (optionally returned, dependent to driver parameter)</li></ul><p> </p></li>
1210 <li>DEFAULT - <ul class="empty"><li>reflects the default value for this parameter which is used when the device is created and not explicitly given with the <a href="#CREATE AUDIO_OUTPUT_DEVICE">'CREATE AUDIO_OUTPUT_DEVICE'</a> <cite title="NONE">[CREATE AUDIO_OUTPUT_DEVICE]</cite> command, in case of MULTIPLCITY=true, this is a comma separated list, that's why character strings are encapsulated into apostrophes (') (optionally returned, dependent to driver parameter)</li></ul><p> </p></li>
1211 <li>RANGE_MIN - <ul class="empty"><li>defines lower limit of the allowed value range for this parameter, can be an integer value as well as a dotted number, this parameter is often used in conjunction with RANGE_MAX, but may also appear without (optionally returned, dependent to driver parameter)</li></ul><p> </p></li>
1212 <li>RANGE_MAX - <ul class="empty"><li>defines upper limit of the allowed value range for this parameter, can be an integer value as well as a dotted number, this parameter is often used in conjunction with RANGE_MIN, but may also appear without (optionally returned, dependent to driver parameter)</li></ul><p> </p></li>
1213 <li>POSSIBILITIES - <ul class="empty"><li>comma separated list of possible values for this parameter, character strings are encapsulated into apostrophes (optionally returned, dependent to driver parameter)</li></ul><p> </p></li>
1214 </ul>
1215
1216 <p> </p>
1217 <p id="rfc.section.6.2.4.p.7">The mentioned fields above don't have to be in particular order.</p>
1218 <p id="rfc.section.6.2.4.p.8">Examples:</p>
1219 <p/>
1220
1221 <ul class="empty">
1222 <li>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA CARD"</li>
1223 <li>S: "DESCRIPTION: sound card to be used"</li>
1224 <li>"TYPE: STRING"</li>
1225 <li>"MANDATORY: false"</li>
1226 <li>"FIX: true"</li>
1227 <li>"MULTIPLICITY: false"</li>
1228 <li>"DEFAULT: '0,0'"</li>
1229 <li>"POSSIBILITIES: '0,0','1,0','2,0'"</li>
1230 <li>"."</li>
1231 </ul>
1232
1233 <p> </p>
1234 <p/>
1235
1236 <ul class="empty">
1237 <li>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE"</li>
1238 <li>S: "DESCRIPTION: output sample rate in Hz"</li>
1239 <li>"TYPE: INT"</li>
1240 <li>"MANDATORY: false"</li>
1241 <li>"FIX: false"</li>
1242 <li>"MULTIPLICITY: false"</li>
1243 <li>"DEPENDS: card"</li>
1244 <li>"DEFAULT: 44100"</li>
1245 <li>"."</li>
1246 </ul>
1247
1248 <p> </p>
1249 <p/>
1250
1251 <ul class="empty">
1252 <li>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE CARD='0,0'"</li>
1253 <li>S: "DESCRIPTION: output sample rate in Hz"</li>
1254 <li>"TYPE: INT"</li>
1255 <li>"MANDATORY: false"</li>
1256 <li>"FIX: false"</li>
1257 <li>"MULTIPLICITY: false"</li>
1258 <li>"DEPENDS: card"</li>
1259 <li>"DEFAULT: 44100"</li>
1260 <li>"RANGE_MIN: 22050"</li>
1261 <li>"RANGE_MAX: 96000"</li>
1262 <li>"."</li>
1263 </ul>
1264
1265 <p> </p>
1266 <h1 id="rfc.section.6.2.5"><a href="#rfc.section.6.2.5">6.2.5.</a> <a href="#CREATE AUDIO_OUTPUT_DEVICE" id="CREATE AUDIO_OUTPUT_DEVICE">Creating an audio output device</a></h1>
1267 <p id="rfc.section.6.2.5.p.1">Use the following command to create a new audio output device for the desired audio output system:</p>
1268 <p/>
1269
1270 <ul class="empty">
1271 <li>CREATE AUDIO_OUTPUT_DEVICE &lt;audio-output-driver&gt; [&lt;param-list&gt;]</li>
1272 </ul>
1273
1274 <p> </p>
1275 <p id="rfc.section.6.2.5.p.3">Where &lt;audio-output-driver&gt; should be replaced by the desired audio output system as returned by the <a href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"</a> <cite title="NONE">[LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS]</cite> command and &lt;param-list&gt; by an optional list of driver specific parameters in form of "key1=val1 key2=val2 ...", where character string values should be encapsulated into apostrophes ('). Note that there might be drivers which require parameter(s) to be given with this command. Use the previously described commands in this chapter to get this information.</p>
1276 <p id="rfc.section.6.2.5.p.4">Possible Answers:</p>
1277 <p/>
1278
1279 <ul class="empty">
1280 <li>"OK[&lt;device-id&gt;]" - <ul class="empty"><li>in case the device was successfully created, where &lt;device-id&gt; is the numerical ID of the new device</li></ul><p> </p></li>
1281 <li>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" - <ul class="empty"><li>in case the device was created successfully, where &lt;device-id&gt; is the numerical ID of the new device, but there are noteworthy issue(s) related (e.g. sound card doesn't support given hardware parameters and the driver is using fall-back values), providing an appropriate warning code and warning message</li></ul><p> </p></li>
1282 <li>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" - <ul class="empty"><li>in case it failed, providing an appropriate error code and error message</li></ul><p> </p></li>
1283 </ul>
1284
1285 <p> </p>
1286 <p id="rfc.section.6.2.5.p.6">Examples:</p>
1287 <p/>
1288
1289 <ul class="empty">
1290 <li>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA"</li>
1291 <li>S: "OK[0]"</li>
1292 </ul>
1293
1294 <p> </p>
1295 <p/>
1296
1297 <ul class="empty">
1298 <li>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"</li>
1299 <li>S: "OK[1]"</li>
1300 </ul>
1301
1302 <p> </p>
1303 <h1 id="rfc.section.6.2.6"><a href="#rfc.section.6.2.6">6.2.6.</a> <a href="#DESTROY AUDIO_OUTPUT_DEVICE" id="DESTROY AUDIO_OUTPUT_DEVICE">Destroying an audio output device</a></h1>
1304 <p id="rfc.section.6.2.6.p.1">Use the following command to destroy a created output device:</p>
1305 <p/>
1306
1307 <ul class="empty">
1308 <li>DESTROY AUDIO_OUTPUT_DEVICE &lt;device-id&gt;</li>
1309 </ul>
1310
1311 <p> </p>
1312 <p id="rfc.section.6.2.6.p.3">Where &lt;device-id&gt; should be replaced by the numerical ID of the audio output device as given by the <a href="#CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</a> <cite title="NONE">[CREATE AUDIO_OUTPUT_DEVICE]</cite> or <a href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</a> <cite title="NONE">[LIST AUDIO_OUTPUT_DEVICES]</cite> command.</p>
1313 <p id="rfc.section.6.2.6.p.4">Possible Answers:</p>
1314 <p/>
1315
1316 <ul class="empty">
1317 <li>"OK" - <ul class="empty"><li>in case the device was successfully destroyed</li></ul><p> </p></li>
1318 <li>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" - <ul class="empty"><li>in case the device was destroyed successfully, but there are noteworthy issue(s) related (e.g. an audio over ethernet driver was unloaded but the other host might not be informed about this situation), providing an appropriate warning code and warning message</li></ul><p> </p></li>
1319 <li>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" - <ul class="empty"><li>in case it failed, providing an appropriate error code and error message</li></ul><p> </p></li>
1320 </ul>
1321
1322 <p> </p>
1323 <p id="rfc.section.6.2.6.p.6">Example:</p>
1324 <p/>
1325
1326 <ul class="empty">
1327 <li>C: "DESTROY AUDIO_OUTPUT_DEVICE 0"</li>
1328 <li>S: "OK"</li>
1329 </ul>
1330
1331 <p> </p>
1332 <h1 id="rfc.section.6.2.7"><a href="#rfc.section.6.2.7">6.2.7.</a> <a href="#GET AUDIO_OUTPUT_DEVICES" id="GET AUDIO_OUTPUT_DEVICES">Getting all created audio output device count</a></h1>
1333 <p id="rfc.section.6.2.7.p.1">Use the following command to count all created audio output devices:</p>
1334 <p/>
1335
1336 <ul class="empty">
1337 <li>GET AUDIO_OUTPUT_DEVICES</li>
1338 </ul>
1339
1340 <p> </p>
1341 <p id="rfc.section.6.2.7.p.3">Possible Answers:</p>
1342 <p/>
1343
1344 <ul class="empty">
1345 <li>LinuxSampler will answer by sending the current number of all audio output devices.</li>
1346 </ul>
1347
1348 <p> </p>
1349 <p id="rfc.section.6.2.7.p.5">Example:</p>
1350 <p/>
1351
1352 <ul class="empty">
1353 <li>C: "GET AUDIO_OUTPUT_DEVICES"</li>
1354 <li>S: "4"</li>
1355 </ul>
1356
1357 <p> </p>
1358 <h1 id="rfc.section.6.2.8"><a href="#rfc.section.6.2.8">6.2.8.</a> <a href="#LIST AUDIO_OUTPUT_DEVICES" id="LIST AUDIO_OUTPUT_DEVICES">Getting all created audio output device list</a></h1>
1359 <p id="rfc.section.6.2.8.p.1">Use the following command to list all created audio output devices:</p>
1360 <p/>
1361
1362 <ul class="empty">
1363 <li>LIST AUDIO_OUTPUT_DEVICES</li>
1364 </ul>
1365
1366 <p> </p>
1367 <p id="rfc.section.6.2.8.p.3">Possible Answers:</p>
1368 <p/>
1369
1370 <ul class="empty">
1371 <li>LinuxSampler will answer by sending a comma separated list with the numerical IDs of all audio output devices.</li>
1372 </ul>
1373
1374 <p> </p>
1375 <p id="rfc.section.6.2.8.p.5">Example:</p>
1376 <p/>
1377
1378 <ul class="empty">
1379 <li>C: "LIST AUDIO_OUTPUT_DEVICES"</li>
1380 <li>S: "0,1,4,5"</li>
1381 </ul>
1382
1383 <p> </p>
1384 <h1 id="rfc.section.6.2.9"><a href="#rfc.section.6.2.9">6.2.9.</a> <a href="#GET AUDIO_OUTPUT_DEVICE INFO" id="GET AUDIO_OUTPUT_DEVICE INFO">Getting current settings of an audio output device</a></h1>
1385 <p id="rfc.section.6.2.9.p.1">Use the following command to get current settings of a specific, created audio output device:</p>
1386 <p/>
1387
1388 <ul class="empty">
1389 <li>GET AUDIO_OUTPUT_DEVICE INFO &lt;device-id&gt;</li>
1390 </ul>
1391
1392 <p> </p>
1393 <p id="rfc.section.6.2.9.p.3">Where &lt;device-id&gt; should be replaced by numerical ID of the audio output device as e.g. returned by the <a href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</a> <cite title="NONE">[LIST AUDIO_OUTPUT_DEVICES]</cite> command.</p>
1394 <p id="rfc.section.6.2.9.p.4">Possible Answers:</p>
1395 <p id="rfc.section.6.2.9.p.5">LinuxSampler will answer by sending a &lt;CRLF&gt; separated list. Each answer line begins with the information category name followed by a colon and then a space character &lt;SP&gt; and finally the info character string to that info category. As some parameters might allow multiple values, character strings are encapsulated into apostrophes ('). At the moment the following information categories are defined (independently of device):</p>
1396 <p/>
1397
1398 <ul class="empty">
1399 <li>DRIVER - <ul class="empty"><li>identifier of the used audio output driver, as also returned by the <a href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"</a> <cite title="NONE">[LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS]</cite> command</li></ul><p> </p></li>
1400 <li>CHANNELS - <ul class="empty"><li>amount of audio output channels this device currently offers</li></ul><p> </p></li>
1401 <li>SAMPLERATE - <ul class="empty"><li>playback sample rate the device uses</li></ul><p> </p></li>
1402 <li>ACTIVE - <ul class="empty"><li>either true or false, if false then the audio device is inactive and doesn't output any sound, nor do the sampler channels connected to this audio device render any audio</li></ul><p> </p></li>
1403 </ul>
1404
1405 <p> </p>
1406 <p id="rfc.section.6.2.9.p.7">The mentioned fields above don't have to be in particular order. The fields above are only those fields which are returned by all audio output devices. Every audio output driver might have its own, additional driver specific parameters (see <a href="#GET AUDIO_OUTPUT_DRIVER INFO">Section 6.2.3</a>) which are also returned by this command.</p>
1407 <p id="rfc.section.6.2.9.p.8">Example:</p>
1408 <p/>
1409
1410 <ul class="empty">
1411 <li>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"</li>
1412 <li>S: "DRIVER: ALSA"</li>
1413 <li>"CHANNELS: 2"</li>
1414 <li>"SAMPLERATE: 44100"</li>
1415 <li>"ACTIVE: true"</li>
1416 <li>"FRAGMENTS: 2"</li>
1417 <li>"FRAGMENTSIZE: 128"</li>
1418 <li>"CARD: '0,0'"</li>
1419 <li>"."</li>
1420 </ul>
1421
1422 <p> </p>
1423 <h1 id="rfc.section.6.2.10"><a href="#rfc.section.6.2.10">6.2.10.</a> <a href="#SET AUDIO_OUTPUT_DEVICE_PARAMETER" id="SET AUDIO_OUTPUT_DEVICE_PARAMETER">Changing settings of audio output devices</a></h1>
1424 <p id="rfc.section.6.2.10.p.1">Use the following command to alter a specific setting of a created audio output device:</p>
1425 <p/>
1426
1427 <ul class="empty">
1428 <li>SET AUDIO_OUTPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;</li>
1429 </ul>
1430
1431 <p> </p>
1432 <p id="rfc.section.6.2.10.p.3">Where &lt;device-id&gt; should be replaced by the numerical ID of the audio output device as given by the <a href="#CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</a> <cite title="NONE">[CREATE AUDIO_OUTPUT_DEVICE]</cite> or <a href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</a> <cite title="NONE">[LIST AUDIO_OUTPUT_DEVICES]</cite> command, &lt;key&gt; by the name of the parameter to change and &lt;value&gt; by the new value for this parameter.</p>
1433 <p id="rfc.section.6.2.10.p.4">Possible Answers:</p>
1434 <p/>
1435
1436 <ul class="empty">
1437 <li>"OK" - <ul class="empty"><li>in case setting was successfully changed</li></ul><p> </p></li>
1438 <li>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" - <ul class="empty"><li>in case setting was changed successfully, but there are noteworthy issue(s) related, providing an appropriate warning code and warning message</li></ul><p> </p></li>
1439 <li>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" - <ul class="empty"><li>in case it failed, providing an appropriate error code and error message</li></ul><p> </p></li>
1440 </ul>
1441
1442 <p> </p>
1443 <p id="rfc.section.6.2.10.p.6">Example:</p>
1444 <p/>
1445
1446 <ul class="empty">
1447 <li>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"</li>
1448 <li>S: "OK"</li>
1449 </ul>
1450
1451 <p> </p>
1452 <h1 id="rfc.section.6.2.11"><a href="#rfc.section.6.2.11">6.2.11.</a> <a href="#GET AUDIO_OUTPUT_CHANNEL INFO" id="GET AUDIO_OUTPUT_CHANNEL INFO">Getting information about an audio channel</a></h1>
1453 <p id="rfc.section.6.2.11.p.1">Use the following command to get information about an audio channel:</p>
1454 <p/>
1455
1456 <ul class="empty">
1457 <li>GET AUDIO_OUTPUT_CHANNEL INFO &lt;device-id&gt; &lt;audio-chan&gt;</li>
1458 </ul>
1459
1460 <p> </p>
1461 <p id="rfc.section.6.2.11.p.3">Where &lt;device-id&gt; is the numerical ID of the audio output device as given by the <a href="#CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</a> <cite title="NONE">[CREATE AUDIO_OUTPUT_DEVICE]</cite> or <a href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</a> <cite title="NONE">[LIST AUDIO_OUTPUT_DEVICES]</cite> command and &lt;audio-chan&gt; the audio channel number.</p>
1462 <p id="rfc.section.6.2.11.p.4">Possible Answers:</p>
1463 <p/>
1464
1465 <ul class="empty">
1466 <li>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list. Each answer line begins with the information category name followed by a colon and then a space character &lt;SP&gt; and finally the info character string to that info category. At the moment the following information categories are defined:</li>
1467 <li>
1468 <ul class="empty">
1469 <li>NAME - <ul class="empty"><li>arbitrary character string naming the channel, which doesn't have to be unique (always returned by all audio channels)</li></ul><p> </p></li>
1470 <li>IS_MIX_CHANNEL - <ul class="empty"><li>either true or false, a mix-channel is not a real, independent audio channel, but a virtual channel which is mixed to another real channel, this mechanism is needed for sampler engines which need more audio channels than the used audio system might be able to offer (always returned by all audio channels)</li></ul><p> </p></li>
1471 <li>MIX_CHANNEL_DESTINATION - <ul class="empty"><li>numerical ID (positive integer including 0) which reflects the real audio channel (of the same audio output device) this mix channel refers to, means where the audio signal actually will be routed / added to (only returned in case the audio channel is mix channel)</li></ul><p> </p></li>
1472 </ul>
1473 <p> </p>
1474 </li>
1475 </ul>
1476
1477 <p> </p>
1478 <p id="rfc.section.6.2.11.p.6">The mentioned fields above don't have to be in particular order. The fields above are only those fields which are generally returned for the described cases by all audio channels regardless of the audio driver. Every audio channel might have its own, additional driver and channel specific parameters.</p>
1479 <p id="rfc.section.6.2.11.p.7">Examples:</p>
1480 <p/>
1481
1482 <ul class="empty">
1483 <li>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 0"</li>
1484 <li>S: "NAME: studio monitor left"</li>
1485 <li>"IS_MIX_CHANNEL: false"</li>
1486 <li>"."</li>
1487 </ul>
1488
1489 <p> </p>
1490 <p/>
1491
1492 <ul class="empty">
1493 <li>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 1"</li>
1494 <li>S: "NAME: studio monitor right"</li>
1495 <li>"IS_MIX_CHANNEL: false"</li>
1496 <li>"."</li>
1497 </ul>
1498
1499 <p> </p>
1500 <p/>
1501
1502 <ul class="empty">
1503 <li>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"</li>
1504 <li>S: "NAME: studio monitor left"</li>
1505 <li>"IS_MIX_CHANNEL: true"</li>
1506 <li>"MIX_CHANNEL_DESTINATION: 1"</li>
1507 <li>"."</li>
1508 </ul>
1509
1510 <p> </p>
1511 <p/>
1512
1513 <ul class="empty">
1514 <li>C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"</li>
1515 <li>S: "NAME: 'ardour (left)'"</li>
1516 <li>"IS_MIX_CHANNEL: false"</li>
1517 <li>"JACK_BINDINGS: 'ardour:0'"</li>
1518 <li>"."</li>
1519 </ul>
1520
1521 <p> </p>
1522 <h1 id="rfc.section.6.2.12"><a href="#rfc.section.6.2.12">6.2.12.</a> <a href="#GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO" id="GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO">Getting information about specific audio channel parameter</a></h1>
1523 <p id="rfc.section.6.2.12.p.1">Use the following command to get detailed information about specific audio channel parameter:</p>
1524 <p/>
1525
1526 <ul class="empty">
1527 <li>GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO &lt;dev-id&gt; &lt;chan&gt; &lt;param&gt;</li>
1528 </ul>
1529
1530 <p> </p>
1531 <p id="rfc.section.6.2.12.p.3">Where &lt;dev-id&gt; is the numerical ID of the audio output device as returned by the <a href="#CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</a> <cite title="NONE">[CREATE AUDIO_OUTPUT_DEVICE]</cite> or <a href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</a> <cite title="NONE">[LIST AUDIO_OUTPUT_DEVICES]</cite> command, &lt;chan&gt; the audio channel number and &lt;param&gt; a specific channel parameter name for which information should be obtained (as returned by the <a href="#GET AUDIO_OUTPUT_CHANNEL INFO">"GET AUDIO_OUTPUT_CHANNEL INFO"</a> <cite title="NONE">[GET AUDIO_OUTPUT_CHANNEL INFO]</cite> command).</p>
1532 <p id="rfc.section.6.2.12.p.4">Possible Answers:</p>
1533 <p/>
1534
1535 <ul class="empty">
1536 <li>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list. Each answer line begins with the information category name followed by a colon and then a space character &lt;SP&gt; and finally the info character string to that info category. There are information which is always returned, independently of the given channel parameter and there is optional information which is only shown dependently to the given audio channel. At the moment the following information categories are defined:</li>
1537 <li>
1538 <ul class="empty">
1539 <li>TYPE - <ul class="empty"><li>either "BOOL" for boolean value(s) or "INT" for integer value(s) or "FLOAT" for dotted number(s) or "STRING" for character string(s) (always returned)</li></ul><p> </p></li>
1540 <li>DESCRIPTION - <ul class="empty"><li>arbitrary text describing the purpose of the parameter (always returned)</li></ul><p> </p></li>
1541 <li>FIX - <ul class="empty"><li>either true or false, if true then this parameter is read only, thus cannot be altered (always returned)</li></ul><p> </p></li>
1542 <li>MULTIPLICITY - <ul class="empty"><li>either true or false, defines if this parameter allows only one value or a list of values, where true means multiple values and false only a single value allowed (always returned)</li></ul><p> </p></li>
1543 <li>RANGE_MIN - <ul class="empty"><li>defines lower limit of the allowed value range for this parameter, can be an integer value as well as a dotted number, usually used in conjunction with 'RANGE_MAX', but may also appear without (optionally returned, dependent to driver and channel parameter)</li></ul><p> </p></li>
1544 <li>RANGE_MAX - <ul class="empty"><li>defines upper limit of the allowed value range for this parameter, can be an integer value as well as a dotted number, usually used in conjunction with 'RANGE_MIN', but may also appear without (optionally returned, dependent to driver and channel parameter)</li></ul><p> </p></li>
1545 <li>POSSIBILITIES - <ul class="empty"><li>comma separated list of possible values for this parameter, character strings are encapsulated into apostrophes (optionally returned, dependent to driver and channel parameter)</li></ul><p> </p></li>
1546 </ul>
1547 <p> </p>
1548 </li>
1549 <li>The mentioned fields above don't have to be in particular order.</li>
1550 </ul>
1551
1552 <p> </p>
1553 <p id="rfc.section.6.2.12.p.6">Example:</p>
1554 <p/>
1555
1556 <ul class="empty">
1557 <li>C: "GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO 1 0 JACK_BINDINGS"</li>
1558 <li>S: "DESCRIPTION: bindings to other JACK clients"</li>
1559 <li>"TYPE: STRING"</li>
1560 <li>"FIX: false"</li>
1561 <li>"MULTIPLICITY: true"</li>
1562 <li>"POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"</li>
1563 <li>"."</li>
1564 </ul>
1565
1566 <p> </p>
1567 <h1 id="rfc.section.6.2.13"><a href="#rfc.section.6.2.13">6.2.13.</a> <a href="#SET AUDIO_OUTPUT_CHANNEL_PARAMETER" id="SET AUDIO_OUTPUT_CHANNEL_PARAMETER">Changing settings of audio output channels</a></h1>
1568 <p id="rfc.section.6.2.13.p.1">Use the following command to alter a specific setting of an audio output channel:</p>
1569 <p/>
1570
1571 <ul class="empty">
1572 <li>SET AUDIO_OUTPUT_CHANNEL_PARAMETER &lt;dev-id&gt; &lt;chn&gt; &lt;key&gt;=&lt;value&gt;</li>
1573 </ul>
1574
1575 <p> </p>
1576 <p id="rfc.section.6.2.13.p.3">Where &lt;dev-id&gt; should be replaced by the numerical ID of the audio output device as returned by the <a href="#CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"</a> <cite title="NONE">[CREATE AUDIO_OUTPUT_DEVICE]</cite> or <a href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"</a> <cite title="NONE">[LIST AUDIO_OUTPUT_DEVICES]</cite> command, &lt;chn&gt; by the audio channel number, &lt;key&gt; by the name of the parameter to change and &lt;value&gt; by the new value for this parameter.</p>
1577 <p id="rfc.section.6.2.13.p.4">Possible Answers:</p>
1578 <p/>
1579
1580 <ul class="empty">
1581 <li>"OK" - <ul class="empty"><li>in case setting was successfully changed</li></ul><p> </p></li>
1582 <li>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" - <ul class="empty"><li>in case setting was changed successfully, but there are noteworthy issue(s) related, providing an appropriate warning code and warning message</li></ul><p> </p></li>
1583 <li>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" - <ul class="empty"><li>in case it failed, providing an appropriate error code and error message</li></ul><p> </p></li>
1584 </ul>
1585
1586 <p> </p>
1587 <p id="rfc.section.6.2.13.p.6">Example:</p>
1588 <p/>
1589
1590 <ul class="empty">
1591 <li>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"</li>
1592 <li>S: "OK"</li>
1593 </ul>
1594
1595 <p> </p>
1596 <p/>
1597
1598 <ul class="empty">
1599 <li>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"</li>
1600 <li>S: "OK"</li>
1601 </ul>
1602
1603 <p> </p>
1604 <h1 id="rfc.section.6.3"><a href="#rfc.section.6.3">6.3.</a> Configuring MIDI input drivers</h1>
1605 <p id="rfc.section.6.3.p.1">Instances of drivers in LinuxSampler are called devices. You can use multiple MIDI devices simultaneously, e.g. to use MIDI over ethernet as MIDI input on one sampler channel and ALSA as MIDI input on another sampler channel. For particular MIDI input systems it's also possible to create several devices of the same MIDI input type. This chapter describes all commands to configure LinuxSampler's MIDI input devices and their parameters.</p>
1606 <p id="rfc.section.6.3.p.2">Instead of defining commands and parameters for each driver individually, all possible parameters, their meanings and possible values have to be obtained at runtime. This makes the protocol a bit abstract, but has the advantage, that front-ends can be written independently of what drivers are currently implemented and what parameters these drivers are actually offering. This means front-ends can even handle drivers which are implemented somewhere in future without modifying the front-end at all.</p>
1607 <p id="rfc.section.6.3.p.3">Commands for configuring MIDI input devices are pretty much the same as the commands for configuring audio output drivers, already described in the last chapter.</p>
1608 <p id="rfc.section.6.3.p.4">Note: examples in this chapter showing particular parameters of drivers are not meant as specification of the drivers' parameters. Driver implementations in LinuxSampler might have complete different parameter names and meanings than shown in these examples or might change in future, so these examples are only meant for showing how to retrieve what parameters drivers are offering, how to retrieve their possible values, etc.</p>
1609 <h1 id="rfc.section.6.3.1"><a href="#rfc.section.6.3.1">6.3.1.</a> <a href="#GET AVAILABLE_MIDI_INPUT_DRIVERS" id="GET AVAILABLE_MIDI_INPUT_DRIVERS">Getting amount of available MIDI input drivers</a></h1>
1610 <p id="rfc.section.6.3.1.p.1">Use the following command to get the number of MIDI input drivers currently available for the LinuxSampler instance:</p>
1611 <p/>
1612
1613 <ul class="empty">
1614 <li>GET AVAILABLE_MIDI_INPUT_DRIVERS</li>
1615 </ul>
1616
1617 <p> </p>
1618 <p id="rfc.section.6.3.1.p.3">Possible Answers:</p>
1619 <p/>
1620
1621 <ul class="empty">
1622 <li>LinuxSampler will answer by sending the number of available MIDI input drivers.</li>
1623 </ul>
1624
1625 <p> </p>
1626 <p id="rfc.section.6.3.1.p.5">Example:</p>
1627 <p/>
1628
1629 <ul class="empty">
1630 <li>C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"</li>
1631 <li>S: "2"</li>
1632 </ul>
1633
1634 <p> </p>
1635 <h1 id="rfc.section.6.3.2"><a href="#rfc.section.6.3.2">6.3.2.</a> <a href="#LIST AVAILABLE_MIDI_INPUT_DRIVERS" id="LIST AVAILABLE_MIDI_INPUT_DRIVERS">Getting all available MIDI input drivers</a></h1>
1636 <p id="rfc.section.6.3.2.p.1">Use the following command to list all MIDI input drivers currently available for the LinuxSampler instance:</p>
1637 <p/>
1638
1639 <ul class="empty">
1640 <li>LIST AVAILABLE_MIDI_INPUT_DRIVERS</li>
1641 </ul>
1642
1643 <p> </p>
1644 <p id="rfc.section.6.3.2.p.3">Possible Answers:</p>
1645 <p/>
1646
1647 <ul class="empty">
1648 <li>LinuxSampler will answer by sending comma separated character strings, each symbolizing a MIDI input driver.</li>
1649 </ul>
1650
1651 <p> </p>
1652 <p id="rfc.section.6.3.2.p.5">Example:</p>
1653 <p/>
1654
1655 <ul class="empty">
1656 <li>C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"</li>
1657 <li>S: "ALSA,JACK"</li>
1658 </ul>
1659
1660 <p> </p>
1661 <h1 id="rfc.section.6.3.3"><a href="#rfc.section.6.3.3">6.3.3.</a> <a href="#GET MIDI_INPUT_DRIVER INFO" id="GET MIDI_INPUT_DRIVER INFO">Getting information about a specific MIDI input driver</a></h1>
1662 <p id="rfc.section.6.3.3.p.1">Use the following command to get detailed information about a specific MIDI input driver:</p>
1663 <p/>
1664
1665 <ul class="empty">
1666 <li>GET MIDI_INPUT_DRIVER INFO &lt;midi-input-driver&gt;</li>
1667 </ul>
1668
1669 <p> </p>
1670 <p id="rfc.section.6.3.3.p.3">Where &lt;midi-input-driver&gt; is the name of the MIDI input driver as returned by the <a href="#LIST AVAILABLE_MIDI_INPUT_DRIVERS">"LIST AVAILABLE_MIDI_INPUT_DRIVERS"</a> <cite title="NONE">[LIST AVAILABLE_MIDI_INPUT_DRIVERS]</cite> command.</p>
1671 <p id="rfc.section.6.3.3.p.4">Possible Answers:</p>
1672 <p/>
1673
1674 <ul class="empty">
1675 <li>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list. Each answer line begins with the information category name followed by a colon and then a space character &lt;SP&gt; and finally the info character string to that info category. At the moment the following information categories are defined:</li>
1676 <li>
1677 <ul class="empty">
1678 <li>DESCRIPTION - <ul class="empty"><li>arbitrary description text about the MIDI input driver</li></ul><p> </p></li>
1679 <li>VERSION - <ul class="empty"><li>arbitrary character string regarding the driver's version</li></ul><p> </p></li>
1680 <li>PARAMETERS - <ul class="empty"><li>comma separated list of all parameters available for the given MIDI input driver</li></ul><p> </p></li>
1681 </ul>
1682 <p> </p>
1683 </li>
1684 <li>The mentioned fields above don't have to be in particular order.</li>
1685 </ul>
1686
1687 <p> </p>
1688 <p id="rfc.section.6.3.3.p.6">Example:</p>
1689 <p/>
1690
1691 <ul class="empty">
1692 <li>C: "GET MIDI_INPUT_DRIVER INFO ALSA"</li>
1693 <li>S: "DESCRIPTION: Advanced Linux Sound Architecture"</li>
1694 <li>"VERSION: 1.0"</li>
1695 <li>"PARAMETERS: DRIVER,ACTIVE"</li>
1696 <li>"."</li>
1697 </ul>
1698
1699 <p> </p>
1700 <h1 id="rfc.section.6.3.4"><a href="#rfc.section.6.3.4">6.3.4.</a> <a href="#GET MIDI_INPUT_DRIVER_PARAMETER INFO" id="GET MIDI_INPUT_DRIVER_PARAMETER INFO">Getting information about specific MIDI input driver parameter</a></h1>
1701 <p id="rfc.section.6.3.4.p.1">Use the following command to get detailed information about a specific parameter of a specific MIDI input driver:</p>
1702 <p/>
1703
1704 <ul class="empty">
1705 <li>GET MIDI_INPUT_DRIVER_PARAMETER INFO &lt;midit&gt; &lt;param&gt; [&lt;deplist&gt;]</li>
1706 </ul>
1707
1708 <p> </p>
1709 <p id="rfc.section.6.3.4.p.3">Where &lt;midit&gt; is the name of the MIDI input driver as returned by the <a href="#LIST AVAILABLE_MIDI_INPUT_DRIVERS">"LIST AVAILABLE_MIDI_INPUT_DRIVERS"</a> <cite title="NONE">[LIST AVAILABLE_MIDI_INPUT_DRIVERS]</cite> command, &lt;param&gt; a specific parameter name for which information should be obtained (as returned by the <a href="#GET MIDI_INPUT_DRIVER INFO">"GET MIDI_INPUT_DRIVER INFO"</a> <cite title="NONE">[GET MIDI_INPUT_DRIVER INFO]</cite> command) and &lt;deplist&gt; is an optional list of parameters on which the sought parameter &lt;param&gt; depends on, &lt;deplist&gt; is a key-value pair list in form of "key1=val1 key2=val2 ...", where character string values are encapsulated into apostrophes ('). Arguments given with &lt;deplist&gt; which are not dependency parameters of &lt;param&gt; will be ignored, means the front-end application can simply put all parameters in &lt;deplist&gt; with the values selected by the user.</p>
1710 <p id="rfc.section.6.3.4.p.4">Possible Answers:</p>
1711 <p id="rfc.section.6.3.4.p.5">LinuxSampler will answer by sending a &lt;CRLF&gt; separated list. Each answer line begins with the information category name followed by a colon and then a space character &lt;SP&gt; and finally the info character string to that info category. There is information which is always returned, independent of the given driver parameter and there is optional information which is only shown dependent to given driver parameter. At the moment the following information categories are defined:</p>
1712 <p/>
1713
1714 <ul class="empty">
1715 <li>TYPE - <ul class="empty"><li>either "BOOL" for boolean value(s) or "INT" for integer value(s) or "FLOAT" for dotted number(s) or "STRING" for character string(s) (always returned, no matter which driver parameter)</li></ul><p> </p></li>
1716 <li>DESCRIPTION - <ul class="empty"><li>arbitrary text describing the purpose of the parameter (always returned, no matter which driver parameter)</li></ul><p> </p></li>
1717 <li>MANDATORY - <ul class="empty"><li>either true or false, defines if this parameter must be given when the device is to be created with the <a href="#CREATE MIDI_INPUT_DEVICE">'CREATE MIDI_INPUT_DEVICE'</a> <cite title="NONE">[CREATE MIDI_INPUT_DEVICE]</cite> command (always returned, no matter which driver parameter)</li></ul><p> </p></li>
1718 <li>FIX - <ul class="empty"><li>either true or false, if false then this parameter can be changed at any time, once the device is created by the <a href="#CREATE MIDI_INPUT_DEVICE">'CREATE MIDI_INPUT_DEVICE'</a> <cite title="NONE">[CREATE MIDI_INPUT_DEVICE]</cite> command (always returned, no matter which driver parameter)</li></ul><p> </p></li>
1719 <li>MULTIPLICITY - <ul class="empty"><li>either true or false, defines if this parameter allows only one value or a list of values, where true means multiple values and false only a single value allowed (always returned, no matter which driver parameter)</li></ul><p> </p></li>
1720 <li>DEPENDS - <ul class="empty"><li>comma separated list of parameters this parameter depends on, means the values for fields 'DEFAULT', 'RANGE_MIN', 'RANGE_MAX' and 'POSSIBILITIES' might depend on these listed parameters, for example assuming that an audio driver (like the ALSA driver) offers parameters 'card' and 'samplerate' then parameter 'samplerate' would depend on 'card' because the possible values for 'samplerate' depends on the sound card which can be chosen by the 'card' parameter (optionally returned, dependent to driver parameter)</li></ul><p> </p></li>
1721 <li>DEFAULT - <ul class="empty"><li>reflects the default value for this parameter which is used when the device is created and not explicitly given with the <a href="#CREATE MIDI_INPUT_DEVICE">'CREATE MIDI_INPUT_DEVICE'</a> <cite title="NONE">[CREATE MIDI_INPUT_DEVICE]</cite> command, in case of MULTIPLCITY=true, this is a comma separated list, that's why character strings are encapsulated into apostrophes (') (optionally returned, dependent to driver parameter)</li></ul><p> </p></li>
1722 <li>RANGE_MIN - <ul class="empty"><li>defines lower limit of the allowed value range for this parameter, can be an integer value as well as a dotted number, this parameter is often used in conjunction with RANGE_MAX, but may also appear without (optionally returned, dependent to driver parameter)</li></ul><p> </p></li>
1723 <li>RANGE_MAX - <ul class="empty"><li>defines upper limit of the allowed value range for this parameter, can be an integer value as well as a dotted number, this parameter is often used in conjunction with RANGE_MIN, but may also appear without (optionally returned, dependent to driver parameter)</li></ul><p> </p></li>
1724 <li>POSSIBILITIES - <ul class="empty"><li>comma separated list of possible values for this parameter, character strings are encapsulated into apostrophes (optionally returned, dependent to driver parameter)</li></ul><p> </p></li>
1725 </ul>
1726
1727 <p> </p>
1728 <p id="rfc.section.6.3.4.p.7">The mentioned fields above don't have to be in particular order.</p>
1729 <p id="rfc.section.6.3.4.p.8">Example:</p>
1730 <p/>
1731
1732 <ul class="empty">
1733 <li>C: "GET MIDI_INPUT_DRIVER_PARAMETER INFO ALSA ACTIVE"</li>
1734 <li>S: "DESCRIPTION: Whether device is enabled"</li>
1735 <li>"TYPE: BOOL"</li>
1736 <li>"MANDATORY: false"</li>
1737 <li>"FIX: false"</li>
1738 <li>"MULTIPLICITY: false"</li>
1739 <li>"DEFAULT: true"</li>
1740 <li>"."</li>
1741 </ul>
1742
1743 <p> </p>
1744 <h1 id="rfc.section.6.3.5"><a href="#rfc.section.6.3.5">6.3.5.</a> <a href="#CREATE MIDI_INPUT_DEVICE" id="CREATE MIDI_INPUT_DEVICE">Creating a MIDI input device</a></h1>
1745 <p id="rfc.section.6.3.5.p.1">Use the following command to create a new MIDI input device for the desired MIDI input system:</p>
1746 <p/>
1747
1748 <ul class="empty">
1749 <li>CREATE MIDI_INPUT_DEVICE &lt;midi-input-driver&gt; [&lt;param-list&gt;]</li>
1750 </ul>
1751
1752 <p> </p>
1753 <p id="rfc.section.6.3.5.p.3">Where &lt;midi-input-driver&gt; should be replaced by the desired MIDI input system as returned by the <a href="#LIST AVAILABLE_MIDI_INPUT_DRIVERS">"LIST AVAILABLE_MIDI_INPUT_DRIVERS"</a> <cite title="NONE">[LIST AVAILABLE_MIDI_INPUT_DRIVERS]</cite> command and &lt;param-list&gt; by an optional list of driver specific parameters in form of "key1=val1 key2=val2 ...", where character string values should be encapsulated into apostrophes ('). Note that there might be drivers which require parameter(s) to be given with this command. Use the previously described commands in this chapter to get that information.</p>
1754 <p id="rfc.section.6.3.5.p.4">Possible Answers:</p>
1755 <p/>
1756
1757 <ul class="empty">
1758 <li>"OK[&lt;device-id&gt;]" - <ul class="empty"><li>in case the device was successfully created, where &lt;device-id&gt; is the numerical ID of the new device</li></ul><p> </p></li>
1759 <li>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" - <ul class="empty"><li>in case the driver was loaded successfully, where &lt;device-id&gt; is the numerical ID of the new device, but there are noteworthy issue(s) related, providing an appropriate warning code and warning message</li></ul><p> </p></li>
1760 <li>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" - <ul class="empty"><li>in case it failed, providing an appropriate error code and error message</li></ul><p> </p></li>
1761 </ul>
1762
1763 <p> </p>
1764 <p id="rfc.section.6.3.5.p.6">Example:</p>
1765 <p/>
1766
1767 <ul class="empty">
1768 <li>C: "CREATE MIDI_INPUT_DEVICE ALSA"</li>
1769 <li>S: "OK[0]"</li>
1770 </ul>
1771
1772 <p> </p>
1773 <h1 id="rfc.section.6.3.6"><a href="#rfc.section.6.3.6">6.3.6.</a> <a href="#DESTROY MIDI_INPUT_DEVICE" id="DESTROY MIDI_INPUT_DEVICE">Destroying a MIDI input device</a></h1>
1774 <p id="rfc.section.6.3.6.p.1">Use the following command to destroy a created MIDI input device:</p>
1775 <p/>
1776
1777 <ul class="empty">
1778 <li>DESTROY MIDI_INPUT_DEVICE &lt;device-id&gt;</li>
1779 </ul>
1780
1781 <p> </p>
1782 <p id="rfc.section.6.3.6.p.3">Where &lt;device-id&gt; should be replaced by the device's numerical ID as returned by the <a href="#CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</a> <cite title="NONE">[CREATE MIDI_INPUT_DEVICE]</cite> or <a href="#LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</a> <cite title="NONE">[LIST MIDI_INPUT_DEVICES]</cite> command.</p>
1783 <p id="rfc.section.6.3.6.p.4">Possible Answers:</p>
1784 <p/>
1785
1786 <ul class="empty">
1787 <li>"OK" - <ul class="empty"><li>in case the device was successfully destroyed</li></ul><p> </p></li>
1788 <li>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" - <ul class="empty"><li>in case the device was destroyed, but there are noteworthy issue(s) related, providing an appropriate warning code and warning message</li></ul><p> </p></li>
1789 <li>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" - <ul class="empty"><li>in case it failed, providing an appropriate error code and error message</li></ul><p> </p></li>
1790 </ul>
1791
1792 <p> </p>
1793 <p id="rfc.section.6.3.6.p.6">Example:</p>
1794 <p/>
1795
1796 <ul class="empty">
1797 <li>C: "DESTROY MIDI_INPUT_DEVICE 0"</li>
1798 <li>S: "OK"</li>
1799 </ul>
1800
1801 <p> </p>
1802 <h1 id="rfc.section.6.3.7"><a href="#rfc.section.6.3.7">6.3.7.</a> <a href="#GET MIDI_INPUT_DEVICES" id="GET MIDI_INPUT_DEVICES">Getting all created MIDI input device count</a></h1>
1803 <p id="rfc.section.6.3.7.p.1">Use the following command to count all created MIDI input devices:</p>
1804 <p/>
1805
1806 <ul class="empty">
1807 <li>GET MIDI_INPUT_DEVICES</li>
1808 </ul>
1809
1810 <p> </p>
1811 <p id="rfc.section.6.3.7.p.3">Possible Answers:</p>
1812 <p/>
1813
1814 <ul class="empty">
1815 <li>LinuxSampler will answer by sending the current number of all MIDI input devices.</li>
1816 </ul>
1817
1818 <p> </p>
1819 <p id="rfc.section.6.3.7.p.5">Example:</p>
1820 <p/>
1821
1822 <ul class="empty">
1823 <li>C: "GET MIDI_INPUT_DEVICES"</li>
1824 <li>S: "3"</li>
1825 </ul>
1826
1827 <p> </p>
1828 <h1 id="rfc.section.6.3.8"><a href="#rfc.section.6.3.8">6.3.8.</a> <a href="#LIST MIDI_INPUT_DEVICES" id="LIST MIDI_INPUT_DEVICES">Getting all created MIDI input device list</a></h1>
1829 <p id="rfc.section.6.3.8.p.1">Use the following command to list all created MIDI input devices:</p>
1830 <p/>
1831
1832 <ul class="empty">
1833 <li>LIST MIDI_INPUT_DEVICES</li>
1834 </ul>
1835
1836 <p> </p>
1837 <p id="rfc.section.6.3.8.p.3">Possible Answers:</p>
1838 <p/>
1839
1840 <ul class="empty">
1841 <li>LinuxSampler will answer by sending a comma separated list with the numerical Ids of all created MIDI input devices.</li>
1842 </ul>
1843
1844 <p> </p>
1845 <p id="rfc.section.6.3.8.p.5">Examples:</p>
1846 <p/>
1847
1848 <ul class="empty">
1849 <li>C: "LIST MIDI_INPUT_DEVICES"</li>
1850 <li>S: "0,1,2"</li>
1851 </ul>
1852
1853 <p> </p>
1854 <p/>
1855
1856 <ul class="empty">
1857 <li>C: "LIST MIDI_INPUT_DEVICES"</li>
1858 <li>S: "1,3"</li>
1859 </ul>
1860
1861 <p> </p>
1862 <h1 id="rfc.section.6.3.9"><a href="#rfc.section.6.3.9">6.3.9.</a> <a href="#GET MIDI_INPUT_DEVICE INFO" id="GET MIDI_INPUT_DEVICE INFO">Getting current settings of a MIDI input device</a></h1>
1863 <p id="rfc.section.6.3.9.p.1">Use the following command to get current settings of a specific, created MIDI input device:</p>
1864 <p/>
1865
1866 <ul class="empty">
1867 <li>GET MIDI_INPUT_DEVICE INFO &lt;device-id&gt;</li>
1868 </ul>
1869
1870 <p> </p>
1871 <p id="rfc.section.6.3.9.p.3">Where &lt;device-id&gt; is the numerical ID of the MIDI input device as returned by the <a href="#CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</a> <cite title="NONE">[CREATE MIDI_INPUT_DEVICE]</cite> or <a href="#LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</a> <cite title="NONE">[LIST MIDI_INPUT_DEVICES]</cite> command.</p>
1872 <p id="rfc.section.6.3.9.p.4">Possible Answers:</p>
1873 <p/>
1874
1875 <ul class="empty">
1876 <li>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list. Each answer line begins with the information category name followed by a colon and then a space character &lt;SP&gt; and finally the info character string to that info category. As some parameters might allow multiple values, character strings are encapsulated into apostrophes ('). At the moment the following information categories are defined (independent of driver):</li>
1877 <li>
1878 <ul class="empty">
1879 <li>DRIVER - <ul class="empty"><li>identifier of the used MIDI input driver, as e.g. returned by the <a href="#LIST AVAILABLE_MIDI_INPUT_DRIVERS">"LIST AVAILABLE_MIDI_INPUT_DRIVERS"</a> <cite title="NONE">[LIST AVAILABLE_MIDI_INPUT_DRIVERS]</cite> command</li></ul><p> </p></li>
1880 </ul>
1881 <p> </p>
1882 <ul class="empty">
1883 <li>ACTIVE - <ul class="empty"><li>either true or false, if false then the MIDI device is inactive and doesn't listen to any incoming MIDI events and thus doesn't forward them to connected sampler channels</li></ul><p> </p></li>
1884 </ul>
1885 <p> </p>
1886 </li>
1887 </ul>
1888
1889 <p> </p>
1890 <p id="rfc.section.6.3.9.p.6">The mentioned fields above don't have to be in particular order. The fields above are only those fields which are returned by all MIDI input devices. Every MIDI input driver might have its own, additional driver specific parameters (see <a href="#GET MIDI_INPUT_DRIVER INFO">"GET MIDI_INPUT_DRIVER INFO"</a> <cite title="NONE">[GET MIDI_INPUT_DRIVER INFO]</cite> command) which are also returned by this command.</p>
1891 <p id="rfc.section.6.3.9.p.7">Example:</p>
1892 <p/>
1893
1894 <ul class="empty">
1895 <li>C: "GET MIDI_INPUT_DEVICE INFO 0"</li>
1896 <li>S: "DRIVER: ALSA"</li>
1897 <li>"ACTIVE: true"</li>
1898 <li>"."</li>
1899 </ul>
1900
1901 <p> </p>
1902 <h1 id="rfc.section.6.3.10"><a href="#rfc.section.6.3.10">6.3.10.</a> <a href="#SET MIDI_INPUT_DEVICE_PARAMETER" id="SET MIDI_INPUT_DEVICE_PARAMETER">Changing settings of MIDI input devices</a></h1>
1903 <p id="rfc.section.6.3.10.p.1">Use the following command to alter a specific setting of a created MIDI input device:</p>
1904 <p/>
1905
1906 <ul class="empty">
1907 <li>SET MIDI_INPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;</li>
1908 </ul>
1909
1910 <p> </p>
1911 <p id="rfc.section.6.3.10.p.3">Where &lt;device-id&gt; should be replaced by the numerical ID of the MIDI input device as returned by the <a href="#CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</a> <cite title="NONE">[CREATE MIDI_INPUT_DEVICE]</cite> or <a href="#LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</a> <cite title="NONE">[LIST MIDI_INPUT_DEVICES]</cite> command, &lt;key&gt; by the name of the parameter to change and &lt;value&gt; by the new value for this parameter.</p>
1912 <p id="rfc.section.6.3.10.p.4">Possible Answers:</p>
1913 <p/>
1914
1915 <ul class="empty">
1916 <li>"OK" - <ul class="empty"><li>in case setting was successfully changed</li></ul><p> </p></li>
1917 <li>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" - <ul class="empty"><li>in case setting was changed successfully, but there are noteworthy issue(s) related, providing an appropriate warning code and warning message</li></ul><p> </p></li>
1918 <li>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" - <ul class="empty"><li>in case it failed, providing an appropriate error code and error message</li></ul><p> </p></li>
1919 </ul>
1920
1921 <p> </p>
1922 <p id="rfc.section.6.3.10.p.6">Example:</p>
1923 <p/>
1924
1925 <ul class="empty">
1926 <li>C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"</li>
1927 <li>S: "OK"</li>
1928 </ul>
1929
1930 <p> </p>
1931 <h1 id="rfc.section.6.3.11"><a href="#rfc.section.6.3.11">6.3.11.</a> <a href="#GET MIDI_INPUT_PORT INFO" id="GET MIDI_INPUT_PORT INFO">Getting information about a MIDI port</a></h1>
1932 <p id="rfc.section.6.3.11.p.1">Use the following command to get information about a MIDI port:</p>
1933 <p/>
1934
1935 <ul class="empty">
1936 <li>GET MIDI_INPUT_PORT INFO &lt;device-id&gt; &lt;midi-port&gt;</li>
1937 </ul>
1938
1939 <p> </p>
1940 <p id="rfc.section.6.3.11.p.3">Where &lt;device-id&gt; is the numerical ID of the MIDI input device as returned by the <a href="#CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</a> <cite title="NONE">[CREATE MIDI_INPUT_DEVICE]</cite> or <a href="#LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</a> <cite title="NONE">[LIST MIDI_INPUT_DEVICES]</cite> command and &lt;midi-port&gt; the MIDI input port number.</p>
1941 <p id="rfc.section.6.3.11.p.4">Possible Answers:</p>
1942 <p/>
1943
1944 <ul class="empty">
1945 <li>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list. Each answer line begins with the information category name followed by a colon and then a space character &lt;SP&gt; and finally the info character string to that info category. At the moment the following information categories are defined:</li>
1946 <li>NAME - <ul class="empty"><li>arbitrary character string naming the port</li></ul><p> </p></li>
1947 </ul>
1948
1949 <p> </p>
1950 <p id="rfc.section.6.3.11.p.6">The field above is only the one which is returned by all MIDI ports regardless of the MIDI driver and port. Every MIDI port might have its own, additional driver and port specific parameters.</p>
1951 <p id="rfc.section.6.3.11.p.7">Example:</p>
1952 <p/>
1953
1954 <ul class="empty">
1955 <li>C: "GET MIDI_INPUT_PORT INFO 0 0"</li>
1956 <li>S: "NAME: 'Masterkeyboard'"</li>
1957 <li>"ALSA_SEQ_BINDINGS: '64:0'"</li>
1958 <li>"."</li>
1959 </ul>
1960
1961 <p> </p>
1962 <h1 id="rfc.section.6.3.12"><a href="#rfc.section.6.3.12">6.3.12.</a> <a href="#GET MIDI_INPUT_PORT_PARAMETER INFO" id="GET MIDI_INPUT_PORT_PARAMETER INFO">Getting information about specific MIDI port parameter</a></h1>
1963 <p id="rfc.section.6.3.12.p.1">Use the following command to get detailed information about specific MIDI port parameter:</p>
1964 <p/>
1965
1966 <ul class="empty">
1967 <li>GET MIDI_INPUT_PORT_PARAMETER INFO &lt;dev-id&gt; &lt;port&gt; &lt;param&gt;</li>
1968 </ul>
1969
1970 <p> </p>
1971 <p id="rfc.section.6.3.12.p.3">Where &lt;dev-id&gt; is the numerical ID of the MIDI input device as returned by the <a href="#CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</a> <cite title="NONE">[CREATE MIDI_INPUT_DEVICE]</cite> or <a href="#LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</a> <cite title="NONE">[LIST MIDI_INPUT_DEVICES]</cite> command, &lt;port&gt; the MIDI port number and &lt;param&gt; a specific port parameter name for which information should be obtained (as returned by the <a href="#GET MIDI_INPUT_PORT INFO">"GET MIDI_INPUT_PORT INFO"</a> <cite title="NONE">[GET MIDI_INPUT_PORT INFO]</cite> command).</p>
1972 <p id="rfc.section.6.3.12.p.4">Possible Answers:</p>
1973 <p/>
1974
1975 <ul class="empty">
1976 <li>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list. Each answer line begins with the information category name followed by a colon and then a space character &lt;SP&gt; and finally the info character string to that info category. There is information which is always returned, independently of the given channel parameter and there is optional information which are only shown dependently to the given MIDI port. At the moment the following information categories are defined:</li>
1977 <li>TYPE - <ul class="empty"><li>either "BOOL" for boolean value(s) or "INT" for integer value(s) or "FLOAT" for dotted number(s) or "STRING" for character string(s) (always returned)</li></ul><p> </p></li>
1978 <li>DESCRIPTION - <ul class="empty"><li>arbitrary text describing the purpose of the parameter (always returned)</li></ul><p> </p></li>
1979 <li>FIX - <ul class="empty"><li>either true or false, if true then this parameter is read only, thus cannot be altered (always returned)</li></ul><p> </p></li>
1980 <li>MULTIPLICITY - <ul class="empty"><li>either true or false, defines if this parameter allows only one value or a list of values, where true means multiple values and false only a single value allowed (always returned)</li></ul><p> </p></li>
1981 <li>RANGE_MIN - <ul class="empty"><li>defines lower limit of the allowed value range for this parameter, can be an integer value as well as a dotted number, this parameter is usually used in conjunction with 'RANGE_MAX' but may also appear without (optionally returned, dependent to driver and port parameter)</li></ul><p> </p></li>
1982 <li>RANGE_MAX - <ul class="empty"><li>defines upper limit of the allowed value range for this parameter, can be an integer value as well as a dotted number, this parameter is usually used in conjunction with 'RANGE_MIN' but may also appear without (optionally returned, dependent to driver and port parameter)</li></ul><p> </p></li>
1983 <li>POSSIBILITIES - <ul class="empty"><li>comma separated list of possible values for this parameter, character strings are encapsulated into apostrophes (optionally returned, dependent to device and port parameter)</li></ul><p> </p></li>
1984 </ul>
1985
1986 <p> </p>
1987 <p id="rfc.section.6.3.12.p.6">The mentioned fields above don't have to be in particular order.</p>
1988 <p id="rfc.section.6.3.12.p.7">Example:</p>
1989 <p/>
1990
1991 <ul class="empty">
1992 <li>C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"</li>
1993 <li>S: "DESCRIPTION: bindings to other ALSA sequencer clients"</li>
1994 <li>"TYPE: STRING"</li>
1995 <li>"FIX: false"</li>
1996 <li>"MULTIPLICITY: true"</li>
1997 <li>"POSSIBILITIES: '64:0','68:0','68:1'"</li>
1998 <li>"."</li>
1999 </ul>
2000
2001 <p> </p>
2002 <h1 id="rfc.section.6.3.13"><a href="#rfc.section.6.3.13">6.3.13.</a> <a href="#SET MIDI_INPUT_PORT_PARAMETER" id="SET MIDI_INPUT_PORT_PARAMETER">Changing settings of MIDI input ports</a></h1>
2003 <p id="rfc.section.6.3.13.p.1">Use the following command to alter a specific setting of a MIDI input port:</p>
2004 <p/>
2005
2006 <ul class="empty">
2007 <li>SET MIDI_INPUT_PORT_PARAMETER &lt;device-id&gt; &lt;port&gt; &lt;key&gt;=&lt;value&gt;</li>
2008 </ul>
2009
2010 <p> </p>
2011 <p id="rfc.section.6.3.13.p.3">Where &lt;device-id&gt; should be replaced by the numerical ID of the MIDI device as returned by the <a href="#CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"</a> <cite title="NONE">[CREATE MIDI_INPUT_DEVICE]</cite> or <a href="#LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</a> <cite title="NONE">[LIST MIDI_INPUT_DEVICES]</cite> command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of the parameter to change and &lt;value&gt; by the new value for this parameter (encapsulated into apostrophes) or NONE (not encapsulated into apostrophes) for specifying no value for parameters allowing a list of values.</p>
2012 <p id="rfc.section.6.3.13.p.4">Possible Answers:</p>
2013 <p/>
2014
2015 <ul class="empty">
2016 <li>"OK" - <ul class="empty"><li>in case setting was successfully changed</li></ul><p> </p></li>
2017 <li>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" - <ul class="empty"><li>in case setting was changed successfully, but there are noteworthy issue(s) related, providing an appropriate warning code and warning message</li></ul><p> </p></li>
2018 <li>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" - <ul class="empty"><li>in case it failed, providing an appropriate error code and error message</li></ul><p> </p></li>
2019 </ul>
2020
2021 <p> </p>
2022 <p id="rfc.section.6.3.13.p.6">Example:</p>
2023 <p/>
2024
2025 <ul class="empty">
2026 <li>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='20:0'"</li>
2027 <li>S: "OK"</li>
2028 </ul>
2029
2030 <p> </p>
2031 <p/>
2032
2033 <ul class="empty">
2034 <li>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE"</li>
2035 <li>S: "OK"</li>
2036 </ul>
2037
2038 <p> </p>
2039 <h1 id="rfc.section.6.4"><a href="#rfc.section.6.4">6.4.</a> Configuring sampler channels</h1>
2040 <p id="rfc.section.6.4.p.1">The following commands describe how to add and remove sampler channels, associate a sampler channel with a sampler engine, load instruments and connect sampler channels to MIDI and audio devices.</p>
2041 <h1 id="rfc.section.6.4.1"><a href="#rfc.section.6.4.1">6.4.1.</a> <a href="#LOAD INSTRUMENT" id="LOAD INSTRUMENT">Loading an instrument</a></h1>
2042 <p id="rfc.section.6.4.1.p.1">An instrument file can be loaded and assigned to a sampler channel by one of the following commands:</p>
2043 <p/>
2044
2045 <ul class="empty">
2046 <li>LOAD INSTRUMENT [NON_MODAL] '&lt;filename&gt;' &lt;instr-index&gt; &lt;sampler-channel&gt;</li>
2047 </ul>
2048
2049 <p> </p>
2050 <p id="rfc.section.6.4.1.p.3">Where &lt;filename&gt; is the name of the instrument file on the LinuxSampler instance's host system, &lt;instr-index&gt; the index of the instrument in the instrument file and &lt;sampler-channel&gt; is the number of the sampler channel the instrument should be assigned to. Each sampler channel can only have one instrument.</p>
2051 <p id="rfc.section.6.4.1.p.4">Notice: since LSCP 1.2 the &lt;filename&gt; argument supports escape characters for special characters (see chapter "<a href="#character_set">Character Set and Escape Sequences</a> <cite title="NONE">[character_set]</cite>" for details) and accordingly backslash characters in the filename MUST now be escaped as well!</p>
2052 <p id="rfc.section.6.4.1.p.5">The difference between regular and NON_MODAL versions of the command is that the regular command returns OK only after the instrument has been fully loaded and the channel is ready to be used while NON_MODAL version returns immediately and a background process is launched to load the instrument on the channel. The <a href="#GET CHANNEL INFO">GET CHANNEL INFO</a> <cite title="NONE">[GET CHANNEL INFO]</cite> command can be used to obtain loading progress from INSTRUMENT_STATUS field. LOAD command will perform sanity checks such as making sure that the file could be read and it is of a proper format and SHOULD return ERR and SHOULD not launch the background process should any errors be detected at that point.</p>
2053 <p id="rfc.section.6.4.1.p.6">Possible Answers:</p>
2054 <p/>
2055
2056 <ul class="empty">
2057 <li>"OK" - <ul class="empty"><li>in case the instrument was successfully loaded</li></ul><p> </p></li>
2058 <li>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" - <ul class="empty"><li>in case the instrument was loaded successfully, but there are noteworthy issue(s) related (e.g. Engine doesn't support one or more patch parameters provided by the loaded instrument file), providing an appropriate warning code and warning message</li></ul><p> </p></li>
2059 <li>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" - <ul class="empty"><li>in case it failed, providing an appropriate error code and error message</li></ul><p> </p></li>
2060 </ul>
2061
2062 <p> </p>
2063 <p id="rfc.section.6.4.1.p.8">Example (Unix):</p>
2064 <p/>
2065
2066 <ul class="empty">
2067 <li>C: LOAD INSTRUMENT '/home/joe/gigs/cello.gig' 0 0</li>
2068 <li>S: OK</li>
2069 </ul>
2070
2071 <p> </p>
2072 <p id="rfc.section.6.4.1.p.10">Example (Windows):</p>
2073 <p/>
2074
2075 <ul class="empty">
2076 <li>C: LOAD INSTRUMENT 'D:/MySounds/cello.gig' 0 0</li>
2077 <li>S: OK</li>
2078 </ul>
2079
2080 <p> </p>
2081 <h1 id="rfc.section.6.4.2"><a href="#rfc.section.6.4.2">6.4.2.</a> <a href="#LOAD ENGINE" id="LOAD ENGINE">Loading a sampler engine</a></h1>
2082 <p id="rfc.section.6.4.2.p.1">A sampler engine type can be associated to a specific sampler channel by the following command:</p>
2083 <p/>
2084
2085 <ul class="empty">
2086 <li>LOAD ENGINE &lt;engine-name&gt; &lt;sampler-channel&gt;</li>
2087 </ul>
2088
2089 <p> </p>
2090 <p id="rfc.section.6.4.2.p.3">Where &lt;engine-name&gt; is an engine name as obtained by the <a href="#LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</a> <cite title="NONE">[LIST AVAILABLE_ENGINES]</cite> command and &lt;sampler-channel&gt; the sampler channel as returned by the <a href="#ADD CHANNEL">"ADD CHANNEL"</a> <cite title="NONE">[ADD CHANNEL]</cite> or <a href="#LIST CHANNELS">"LIST CHANNELS"</a> <cite title="NONE">[LIST CHANNELS]</cite> command where the engine type should be assigned to. This command should be issued after adding a new sampler channel and before any other control commands on the new sampler channel. It can also be used to change the engine type of a sampler channel. This command has (currently) no way to define or force if a new engine instance should be created and assigned to the given sampler channel or if an already existing instance of that engine type, shared with other sampler channels, should be used.</p>
2091 <p id="rfc.section.6.4.2.p.4">Possible Answers:</p>
2092 <p/>
2093
2094 <ul class="empty">
2095 <li>"OK" - <ul class="empty"><li>in case the engine was successfully deployed</li></ul><p> </p></li>
2096 <li>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" - <ul class="empty"><li>in case the engine was deployed successfully, but there are noteworthy issue(s) related, providing an appropriate warning code and warning message</li></ul><p> </p></li>
2097 <li>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" - <ul class="empty"><li>in case it failed, providing an appropriate error code and error message</li></ul><p> </p></li>
2098 </ul>
2099
2100 <p> </p>
2101 <p id="rfc.section.6.4.2.p.6">Example:</p>
2102 <p/>
2103
2104 <ul class="empty">
2105 <li/>
2106 </ul>
2107
2108 <p> </p>
2109 <h1 id="rfc.section.6.4.3"><a href="#rfc.section.6.4.3">6.4.3.</a> <a href="#GET CHANNELS" id="GET CHANNELS">Getting all created sampler channel count</a></h1>
2110 <p id="rfc.section.6.4.3.p.1">The number of sampler channels can change on runtime. To get the current amount of sampler channels, the front-end can send the following command:</p>
2111 <p/>
2112
2113 <ul class="empty">
2114 <li>GET CHANNELS</li>
2115 </ul>
2116
2117 <p> </p>
2118 <p id="rfc.section.6.4.3.p.3">Possible Answers:</p>
2119 <p/>
2120
2121 <ul class="empty">
2122 <li>LinuxSampler will answer by returning the current number of sampler channels.</li>
2123 </ul>
2124
2125 <p> </p>
2126 <p id="rfc.section.6.4.3.p.5">Example:</p>
2127 <p/>
2128
2129 <ul class="empty">
2130 <li>C: "GET CHANNELS"</li>
2131 <li>S: "12"</li>
2132 </ul>
2133
2134 <p> </p>
2135 <h1 id="rfc.section.6.4.4"><a href="#rfc.section.6.4.4">6.4.4.</a> <a href="#LIST CHANNELS" id="LIST CHANNELS">Getting all created sampler channel list</a></h1>
2136 <p id="rfc.section.6.4.4.p.1">The number of sampler channels can change on runtime. To get the current list of sampler channels, the front-end can send the following command:</p>
2137 <p/>
2138
2139 <ul class="empty">
2140 <li>LIST CHANNELS</li>
2141 </ul>
2142
2143 <p> </p>
2144 <p id="rfc.section.6.4.4.p.3">Possible Answers:</p>
2145 <p/>
2146
2147 <ul class="empty">
2148 <li>LinuxSampler will answer by returning a comma separated list with all sampler channels numerical IDs.</li>
2149 </ul>
2150
2151 <p> </p>
2152 <p id="rfc.section.6.4.4.p.5">Example:</p>
2153 <p/>
2154
2155 <ul class="empty">
2156 <li>C: "LIST CHANNELS"</li>
2157 <li>S: "0,1,2,3,4,5,6,9,10,11,15,20"</li>
2158 </ul>
2159
2160 <p> </p>
2161 <h1 id="rfc.section.6.4.5"><a href="#rfc.section.6.4.5">6.4.5.</a> <a href="#ADD CHANNEL" id="ADD CHANNEL">Adding a new sampler channel</a></h1>
2162 <p id="rfc.section.6.4.5.p.1">A new sampler channel can be added to the end of the sampler channel list by sending the following command:</p>
2163 <p/>
2164
2165 <ul class="empty">
2166 <li>ADD CHANNEL</li>
2167 </ul>
2168
2169 <p> </p>
2170 <p id="rfc.section.6.4.5.p.3">This will increment the sampler channel count by one and the new sampler channel will be appended to the end of the sampler channel list. The front-end should send the respective, related commands right after to e.g. load an engine, load an instrument and setting input, output method and eventually other commands to initialize the new channel. The front-end should use the sampler channel returned by the answer of this command to perform the previously recommended commands, to avoid race conditions e.g. with other front-ends that might also have sent an "ADD CHANNEL" command.</p>
2171 <p id="rfc.section.6.4.5.p.4">Possible Answers:</p>
2172 <p/>
2173
2174 <ul class="empty">
2175 <li>"OK[&lt;sampler-channel&gt;]" - <ul class="empty"><li>in case a new sampler channel could be added, where &lt;sampler-channel&gt; reflects the channel number of the new created sampler channel which should be used to set up the sampler channel by sending subsequent initialization commands</li></ul><p> </p></li>
2176 <li>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" - <ul class="empty"><li>in case a new channel was added successfully, but there are noteworthy issue(s) related, providing an appropriate warning code and warning message</li></ul><p> </p></li>
2177 <li>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" - <ul class="empty"><li>in case it failed, providing an appropriate error code and error message</li></ul><p> </p></li>
2178 </ul>
2179
2180 <p> </p>
2181 <p id="rfc.section.6.4.5.p.6">Example:</p>
2182 <p/>
2183
2184 <ul class="empty">
2185 <li/>
2186 </ul>
2187
2188 <p> </p>
2189 <h1 id="rfc.section.6.4.6"><a href="#rfc.section.6.4.6">6.4.6.</a> <a href="#REMOVE CHANNEL" id="REMOVE CHANNEL">Removing a sampler channel</a></h1>
2190 <p id="rfc.section.6.4.6.p.1">A sampler channel can be removed by sending the following command:</p>
2191 <p/>
2192
2193 <ul class="empty">
2194 <li>REMOVE CHANNEL &lt;sampler-channel&gt;</li>
2195 </ul>
2196
2197 <p> </p>
2198 <p id="rfc.section.6.4.6.p.3">Where &lt;sampler-channel&gt; should be replaced by the number of the sampler channel as given by the <a href="#ADD CHANNEL">"ADD CHANNEL"</a> <cite title="NONE">[ADD CHANNEL]</cite> or <a href="#LIST CHANNELS">"LIST CHANNELS"</a> <cite title="NONE">[LIST CHANNELS]</cite> command. The channel numbers of all subsequent sampler channels remain the same.</p>
2199 <p id="rfc.section.6.4.6.p.4">Possible Answers:</p>
2200 <p/>
2201
2202 <ul class="empty">
2203 <li>"OK" - <ul class="empty"><li>in case the given sampler channel could be removed</li></ul><p> </p></li>
2204 <li>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" - <ul class="empty"><li>in case the given channel was removed, but there are noteworthy issue(s) related, providing an appropriate warning code and warning message</li></ul><p> </p></li>
2205 <li>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" - <ul class="empty"><li>in case it failed, providing an appropriate error code and error message</li></ul><p> </p></li>
2206 </ul>
2207
2208 <p> </p>
2209 <p id="rfc.section.6.4.6.p.6">Example:</p>
2210 <p/>
2211
2212 <ul class="empty">
2213 <li/>
2214 </ul>
2215
2216 <p> </p>
2217 <h1 id="rfc.section.6.4.7"><a href="#rfc.section.6.4.7">6.4.7.</a> <a href="#GET AVAILABLE_ENGINES" id="GET AVAILABLE_ENGINES">Getting amount of available engines</a></h1>
2218 <p id="rfc.section.6.4.7.p.1">The front-end can ask for the number of available engines by sending the following command:</p>
2219 <p/>
2220