/[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 1390 - (show annotations) (download) (as text)
Sun Oct 7 14:07:48 2007 UTC (11 years, 2 months ago) by schoenebeck
File MIME type: text/html
File size: 393691 byte(s)
* updated LSCP specs draft regarding escape sequences

1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <html lang="en"><head><title>LinuxSampler Control Protocol (draft)</title>
3 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
4 <meta name="description" content="LinuxSampler Control Protocol (draft)">
5 <meta name="keywords" content="LSCP">
6 <meta name="generator" content="xml2rfc v1.32 (http://xml.resource.org/)">
7 <style type='text/css'><!--
8 body {
9 font-family: verdana, charcoal, helvetica, arial, sans-serif;
10 font-size: small; color: #000; background-color: #FFF;
11 margin: 2em;
12 }
13 h1, h2, h3, h4, h5, h6 {
14 font-family: helvetica, monaco, "MS Sans Serif", arial, sans-serif;
15 font-weight: bold; font-style: normal;
16 }
17 h1 { color: #900; background-color: transparent; text-align: right; }
18 h3 { color: #333; background-color: transparent; }
19
20 td.RFCbug {
21 font-size: x-small; text-decoration: none;
22 width: 30px; height: 30px; padding-top: 2px;
23 text-align: justify; vertical-align: middle;
24 background-color: #000;
25 }
26 td.RFCbug span.RFC {
27 font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
28 font-weight: bold; color: #666;
29 }
30 td.RFCbug span.hotText {
31 font-family: charcoal, monaco, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
32 font-weight: normal; text-align: center; color: #FFF;
33 }
34
35 table.TOCbug { width: 30px; height: 15px; }
36 td.TOCbug {
37 text-align: center; width: 30px; height: 15px;
38 color: #FFF; background-color: #900;
39 }
40 td.TOCbug a {
41 font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, sans-serif;
42 font-weight: bold; font-size: x-small; text-decoration: none;
43 color: #FFF; background-color: transparent;
44 }
45
46 td.header {
47 font-family: arial, helvetica, sans-serif; font-size: x-small;
48 vertical-align: top; width: 33%;
49 color: #FFF; background-color: #666;
50 }
51 td.author { font-weight: bold; font-size: x-small; margin-left: 4em; }
52 td.author-text { font-size: x-small; }
53
54 /* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */
55 a.info {
56 /* This is the key. */
57 position: relative;
58 z-index: 24;
59 text-decoration: none;
60 }
61 a.info:hover {
62 z-index: 25;
63 color: #FFF; background-color: #900;
64 }
65 a.info span { display: none; }
66 a.info:hover span.info {
67 /* The span will display just on :hover state. */
68 display: block;
69 position: absolute;
70 font-size: smaller;
71 top: 2em; left: -5em; width: 15em;
72 padding: 2px; border: 1px solid #333;
73 color: #900; background-color: #EEE;
74 text-align: left;
75 }
76
77 a { font-weight: bold; }
78 a:link { color: #900; background-color: transparent; }
79 a:visited { color: #633; background-color: transparent; }
80 a:active { color: #633; background-color: transparent; }
81
82 p { margin-left: 2em; margin-right: 2em; }
83 p.copyright { font-size: x-small; }
84 p.toc { font-size: small; font-weight: bold; margin-left: 3em; }
85 table.toc { margin: 0 0 0 3em; padding: 0; border: 0; vertical-align: text-top; }
86 td.toc { font-size: small; font-weight: bold; vertical-align: text-top; }
87
88 ol.text { margin-left: 2em; margin-right: 2em; }
89 ul.text { margin-left: 2em; margin-right: 2em; }
90 li { margin-left: 3em; }
91
92 /* RFC-2629 <spanx>s and <artwork>s. */
93 em { font-style: italic; }
94 strong { font-weight: bold; }
95 dfn { font-weight: bold; font-style: normal; }
96 cite { font-weight: normal; font-style: normal; }
97 tt { color: #036; }
98 tt, pre, pre dfn, pre em, pre cite, pre span {
99 font-family: "Courier New", Courier, monospace; font-size: small;
100 }
101 pre {
102 text-align: left; padding: 4px;
103 color: #000; background-color: #CCC;
104 }
105 pre dfn { color: #900; }
106 pre em { color: #66F; background-color: #FFC; font-weight: normal; }
107 pre .key { color: #33C; font-weight: bold; }
108 pre .id { color: #900; }
109 pre .str { color: #000; background-color: #CFF; }
110 pre .val { color: #066; }
111 pre .rep { color: #909; }
112 pre .oth { color: #000; background-color: #FCF; }
113 pre .err { background-color: #FCC; }
114
115 /* RFC-2629 <texttable>s. */
116 table.all, table.full, table.headers, table.none {
117 font-size: small; text-align: center; border-width: 2px;
118 vertical-align: top; border-collapse: collapse;
119 }
120 table.all, table.full { border-style: solid; border-color: black; }
121 table.headers, table.none { border-style: none; }
122 th {
123 font-weight: bold; border-color: black;
124 border-width: 2px 2px 3px 2px;
125 }
126 table.all th, table.full th { border-style: solid; }
127 table.headers th { border-style: none none solid none; }
128 table.none th { border-style: none; }
129 table.all td {
130 border-style: solid; border-color: #333;
131 border-width: 1px 2px;
132 }
133 table.full td, table.headers td, table.none td { border-style: none; }
134
135 hr { height: 1px; }
136 hr.insert {
137 width: 80%; border-style: none; border-width: 0;
138 color: #CCC; background-color: #CCC;
139 }
140 --></style>
141 </head>
142 <body>
143 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
144 <table summary="layout" width="66%" border="0" cellpadding="0" cellspacing="0"><tr><td><table summary="layout" width="100%" border="0" cellpadding="2" cellspacing="1">
145 <tr><td class="header">LinuxSampler Developers</td><td class="header">C. Schoenebeck</td></tr>
146 <tr><td class="header">Internet-Draft</td><td class="header">Interessengemeinschaft Software</td></tr>
147 <tr><td class="header">Intended status: Standards Track</td><td class="header">Engineering e. V.</td></tr>
148 <tr><td class="header">Expires: April 9, 2008</td><td class="header">October 7, 2007</td></tr>
149 </table></td></tr></table>
150 <h1><br />LinuxSampler Control Protocol (draft)<br />LSCP 1.2cvs</h1>
151
152 <h3>Status of this Memo</h3>
153 <p>
154 By submitting this Internet-Draft,
155 each author represents that any applicable patent or other IPR claims of which
156 he or she is aware have been or will be disclosed,
157 and any of which he or she becomes aware will be disclosed,
158 in accordance with Section&nbsp;6 of BCP&nbsp;79.</p>
159 <p>
160 Internet-Drafts are working documents of the Internet Engineering
161 Task Force (IETF), its areas, and its working groups.
162 Note that other groups may also distribute working documents as
163 Internet-Drafts.</p>
164 <p>
165 Internet-Drafts are draft documents valid for a maximum of six months
166 and may be updated, replaced, or obsoleted by other documents at any time.
167 It is inappropriate to use Internet-Drafts as reference material or to cite
168 them other than as &ldquo;work in progress.&rdquo;</p>
169 <p>
170 The list of current Internet-Drafts can be accessed at
171 <a href='http://www.ietf.org/ietf/1id-abstracts.txt'>http://www.ietf.org/ietf/1id-abstracts.txt</a>.</p>
172 <p>
173 The list of Internet-Draft Shadow Directories can be accessed at
174 <a href='http://www.ietf.org/shadow.html'>http://www.ietf.org/shadow.html</a>.</p>
175 <p>
176 This Internet-Draft will expire on April 9, 2008.</p>
177
178 <h3>Copyright Notice</h3>
179 <p>
180 Copyright &copy; The IETF Trust (2007).</p>
181
182 <h3>Abstract</h3>
183
184 <p>The LinuxSampler Control Protocol (LSCP) is an
185 application-level protocol primarily intended for local and
186 remote controlling the LinuxSampler backend application, which is a
187 sophisticated server-like console application essentially playing
188 back audio samples and manipulating the samples in real time to
189 certain extent.
190 </p><a name="toc"></a><br /><hr />
191 <h3>Table of Contents</h3>
192 <p class="toc">
193 <a href="#anchor1">1.</a>&nbsp;
194 Requirements notation<br />
195 <a href="#LSCP versioning">2.</a>&nbsp;
196 Versioning of this specification<br />
197 <a href="#anchor2">3.</a>&nbsp;
198 Introduction<br />
199 <a href="#anchor3">4.</a>&nbsp;
200 Focus of this protocol<br />
201 <a href="#anchor4">5.</a>&nbsp;
202 Communication Overview<br />
203 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor5">5.1.</a>&nbsp;
204 Request/response communication method<br />
205 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor6">5.1.1.</a>&nbsp;
206 Result format<br />
207 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor7">5.2.</a>&nbsp;
208 Subscribe/notify communication method<br />
209 <a href="#control_commands">6.</a>&nbsp;
210 Description for control commands<br />
211 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor8">6.1.</a>&nbsp;
212 Ignored lines and comments<br />
213 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor9">6.2.</a>&nbsp;
214 Configuring audio drivers<br />
215 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_AUDIO_OUTPUT_DRIVERS">6.2.1.</a>&nbsp;
216 Getting amount of available audio output drivers<br />
217 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">6.2.2.</a>&nbsp;
218 Getting all available audio output drivers<br />
219 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DRIVER INFO">6.2.3.</a>&nbsp;
220 Getting information about a specific audio
221 output driver<br />
222 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO">6.2.4.</a>&nbsp;
223 Getting information about specific audio
224 output driver parameter<br />
225 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CREATE AUDIO_OUTPUT_DEVICE">6.2.5.</a>&nbsp;
226 Creating an audio output device<br />
227 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DESTROY AUDIO_OUTPUT_DEVICE">6.2.6.</a>&nbsp;
228 Destroying an audio output device<br />
229 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DEVICES">6.2.7.</a>&nbsp;
230 Getting all created audio output device count<br />
231 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AUDIO_OUTPUT_DEVICES">6.2.8.</a>&nbsp;
232 Getting all created audio output device list<br />
233 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DEVICE INFO">6.2.9.</a>&nbsp;
234 Getting current settings of an audio output device<br />
235 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET AUDIO_OUTPUT_DEVICE_PARAMETER">6.2.10.</a>&nbsp;
236 Changing settings of audio output devices<br />
237 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_CHANNEL INFO">6.2.11.</a>&nbsp;
238 Getting information about an audio channel<br />
239 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO">6.2.12.</a>&nbsp;
240 Getting information about specific audio channel parameter<br />
241 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET AUDIO_OUTPUT_CHANNEL_PARAMETER">6.2.13.</a>&nbsp;
242 Changing settings of audio output channels<br />
243 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor10">6.3.</a>&nbsp;
244 Configuring MIDI input drivers<br />
245 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_MIDI_INPUT_DRIVERS">6.3.1.</a>&nbsp;
246 Getting amount of available MIDI input drivers<br />
247 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_MIDI_INPUT_DRIVERS">6.3.2.</a>&nbsp;
248 Getting all available MIDI input drivers<br />
249 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DRIVER INFO">6.3.3.</a>&nbsp;
250 Getting information about a specific MIDI input driver<br />
251 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DRIVER_PARAMETER INFO">6.3.4.</a>&nbsp;
252 Getting information about specific MIDI input driver parameter<br />
253 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CREATE MIDI_INPUT_DEVICE">6.3.5.</a>&nbsp;
254 Creating a MIDI input device<br />
255 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DESTROY MIDI_INPUT_DEVICE">6.3.6.</a>&nbsp;
256 Destroying a MIDI input device<br />
257 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DEVICES">6.3.7.</a>&nbsp;
258 Getting all created MIDI input device count<br />
259 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST MIDI_INPUT_DEVICES">6.3.8.</a>&nbsp;
260 Getting all created MIDI input device list<br />
261 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DEVICE INFO">6.3.9.</a>&nbsp;
262 Getting current settings of a MIDI input device<br />
263 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET MIDI_INPUT_DEVICE_PARAMETER">6.3.10.</a>&nbsp;
264 Changing settings of MIDI input devices<br />
265 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_PORT INFO">6.3.11.</a>&nbsp;
266 Getting information about a MIDI port<br />
267 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_PORT_PARAMETER INFO">6.3.12.</a>&nbsp;
268 Getting information about specific MIDI port parameter<br />
269 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET MIDI_INPUT_PORT_PARAMETER">6.3.13.</a>&nbsp;
270 Changing settings of MIDI input ports<br />
271 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor11">6.4.</a>&nbsp;
272 Configuring sampler channels<br />
273 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LOAD INSTRUMENT">6.4.1.</a>&nbsp;
274 Loading an instrument<br />
275 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LOAD ENGINE">6.4.2.</a>&nbsp;
276 Loading a sampler engine<br />
277 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNELS">6.4.3.</a>&nbsp;
278 Getting all created sampler channel count<br />
279 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST CHANNELS">6.4.4.</a>&nbsp;
280 Getting all created sampler channel list<br />
281 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD CHANNEL">6.4.5.</a>&nbsp;
282 Adding a new sampler channel<br />
283 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE CHANNEL">6.4.6.</a>&nbsp;
284 Removing a sampler channel<br />
285 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_ENGINES">6.4.7.</a>&nbsp;
286 Getting amount of available engines<br />
287 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_ENGINES">6.4.8.</a>&nbsp;
288 Getting all available engines<br />
289 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET ENGINE INFO">6.4.9.</a>&nbsp;
290 Getting information about an engine<br />
291 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL INFO">6.4.10.</a>&nbsp;
292 Getting sampler channel information<br />
293 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL VOICE_COUNT">6.4.11.</a>&nbsp;
294 Current number of active voices<br />
295 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL STREAM_COUNT">6.4.12.</a>&nbsp;
296 Current number of active disk streams<br />
297 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL BUFFER_FILL">6.4.13.</a>&nbsp;
298 Current fill state of disk stream buffers<br />
299 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_DEVICE">6.4.14.</a>&nbsp;
300 Setting audio output device<br />
301 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_TYPE">6.4.15.</a>&nbsp;
302 Setting audio output type<br />
303 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_CHANNEL">6.4.16.</a>&nbsp;
304 Setting audio output channel<br />
305 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_DEVICE">6.4.17.</a>&nbsp;
306 Setting MIDI input device<br />
307 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_TYPE">6.4.18.</a>&nbsp;
308 Setting MIDI input type<br />
309 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_PORT">6.4.19.</a>&nbsp;
310 Setting MIDI input port<br />
311 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_CHANNEL">6.4.20.</a>&nbsp;
312 Setting MIDI input channel<br />
313 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL VOLUME">6.4.21.</a>&nbsp;
314 Setting channel volume<br />
315 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MUTE">6.4.22.</a>&nbsp;
316 Muting a sampler channel<br />
317 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL SOLO">6.4.23.</a>&nbsp;
318 Soloing a sampler channel<br />
319 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INSTRUMENT_MAP">6.4.24.</a>&nbsp;
320 Assigning a MIDI instrument map to a sampler channel<br />
321 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CREATE FX_SEND">6.4.25.</a>&nbsp;
322 Adding an effect send to a sampler channel<br />
323 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DESTROY FX_SEND">6.4.26.</a>&nbsp;
324 Removing an effect send from a sampler channel<br />
325 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET FX_SENDS">6.4.27.</a>&nbsp;
326 Getting amount of effect sends on a sampler channel<br />
327 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST FX_SENDS">6.4.28.</a>&nbsp;
328 Listing all effect sends on a sampler channel<br />
329 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET FX_SEND INFO">6.4.29.</a>&nbsp;
330 Getting effect send information<br />
331 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET FX_SEND NAME">6.4.30.</a>&nbsp;
332 Changing effect send's name<br />
333 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET FX_SEND AUDIO_OUTPUT_CHANNEL">6.4.31.</a>&nbsp;
334 Altering effect send's audio routing<br />
335 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET FX_SEND MIDI_CONTROLLER">6.4.32.</a>&nbsp;
336 Altering effect send's MIDI controller<br />
337 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET FX_SEND LEVEL">6.4.33.</a>&nbsp;
338 Altering effect send's send level<br />
339 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#RESET CHANNEL">6.4.34.</a>&nbsp;
340 Resetting a sampler channel<br />
341 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor12">6.5.</a>&nbsp;
342 Controlling connection<br />
343 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE">6.5.1.</a>&nbsp;
344 Register front-end for receiving event messages<br />
345 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#UNSUBSCRIBE">6.5.2.</a>&nbsp;
346 Unregister front-end for not receiving event messages<br />
347 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET ECHO">6.5.3.</a>&nbsp;
348 Enable or disable echo of commands<br />
349 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#QUIT">6.5.4.</a>&nbsp;
350 Close client connection<br />
351 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor13">6.6.</a>&nbsp;
352 Global commands<br />
353 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET TOTAL_VOICE_COUNT">6.6.1.</a>&nbsp;
354 Current number of active voices<br />
355 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET TOTAL_VOICE_COUNT_MAX">6.6.2.</a>&nbsp;
356 Maximum amount of active voices<br />
357 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#RESET">6.6.3.</a>&nbsp;
358 Reset sampler<br />
359 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET SERVER INFO">6.6.4.</a>&nbsp;
360 General sampler informations<br />
361 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET VOLUME">6.6.5.</a>&nbsp;
362 Getting global volume attenuation<br />
363 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET VOLUME">6.6.6.</a>&nbsp;
364 Setting global volume attenuation<br />
365 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#MIDI Instrument Mapping">6.7.</a>&nbsp;
366 MIDI Instrument Mapping<br />
367 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD MIDI_INSTRUMENT_MAP">6.7.1.</a>&nbsp;
368 Create a new MIDI instrument map<br />
369 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE MIDI_INSTRUMENT_MAP">6.7.2.</a>&nbsp;
370 Delete one particular or all MIDI instrument maps<br />
371 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENT_MAPS">6.7.3.</a>&nbsp;
372 Get amount of existing MIDI instrument maps<br />
373 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST MIDI_INSTRUMENT_MAPS">6.7.4.</a>&nbsp;
374 Getting all created MIDI instrument maps<br />
375 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENT_MAP INFO">6.7.5.</a>&nbsp;
376 Getting MIDI instrument map information<br />
377 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET MIDI_INSTRUMENT_MAP NAME">6.7.6.</a>&nbsp;
378 Renaming a MIDI instrument map<br />
379 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#MAP MIDI_INSTRUMENT">6.7.7.</a>&nbsp;
380 Create or replace a MIDI instrument map entry<br />
381 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENTS">6.7.8.</a>&nbsp;
382 Getting ammount of MIDI instrument map entries<br />
383 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST MIDI_INSTRUMENTS">6.7.9.</a>&nbsp;
384 Getting indeces of all entries of a MIDI instrument map<br />
385 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#UNMAP MIDI_INSTRUMENT">6.7.10.</a>&nbsp;
386 Remove an entry from the MIDI instrument map<br />
387 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENT INFO">6.7.11.</a>&nbsp;
388 Get current settings of MIDI instrument map entry<br />
389 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CLEAR MIDI_INSTRUMENTS">6.7.12.</a>&nbsp;
390 Clear MIDI instrument map<br />
391 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#Managing Instruments Database">6.8.</a>&nbsp;
392 Managing Instruments Database<br />
393 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD DB_INSTRUMENT_DIRECTORY">6.8.1.</a>&nbsp;
394 Creating a new instrument directory<br />
395 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE DB_INSTRUMENT_DIRECTORY">6.8.2.</a>&nbsp;
396 Deleting an instrument directory<br />
397 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENT_DIRECTORIES">6.8.3.</a>&nbsp;
398 Getting amount of instrument directories<br />
399 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST DB_INSTRUMENT_DIRECTORIES">6.8.4.</a>&nbsp;
400 Listing all directories in specific directory<br />
401 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENT_DIRECTORY INFO">6.8.5.</a>&nbsp;
402 Getting instrument directory information<br />
403 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET DB_INSTRUMENT_DIRECTORY NAME">6.8.6.</a>&nbsp;
404 Renaming an instrument directory<br />
405 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#MOVE DB_INSTRUMENT_DIRECTORY">6.8.7.</a>&nbsp;
406 Moving an instrument directory<br />
407 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#COPY DB_INSTRUMENT_DIRECTORY">6.8.8.</a>&nbsp;
408 Copying instrument directories<br />
409 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">6.8.9.</a>&nbsp;
410 Changing the description of directory<br />
411 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#FIND DB_INSTRUMENT_DIRECTORIES">6.8.10.</a>&nbsp;
412 Finding directories<br />
413 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD DB_INSTRUMENTS">6.8.11.</a>&nbsp;
414 Adding instruments to the instruments database<br />
415 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE DB_INSTRUMENT">6.8.12.</a>&nbsp;
416 Removing an instrument<br />
417 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENTS">6.8.13.</a>&nbsp;
418 Getting amount of instruments<br />
419 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST DB_INSTRUMENTS">6.8.14.</a>&nbsp;
420 Listing all instruments in specific directory<br />
421 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENT INFO">6.8.15.</a>&nbsp;
422 Getting instrument information<br />
423 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET DB_INSTRUMENT NAME">6.8.16.</a>&nbsp;
424 Renaming an instrument<br />
425 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#MOVE DB_INSTRUMENT">6.8.17.</a>&nbsp;
426 Moving an instrument<br />
427 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#COPY DB_INSTRUMENT">6.8.18.</a>&nbsp;
428 Copying instruments<br />
429 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET DB_INSTRUMENT DESCRIPTION">6.8.19.</a>&nbsp;
430 Changing the description of instrument<br />
431 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#FIND DB_INSTRUMENTS">6.8.20.</a>&nbsp;
432 Finding instruments<br />
433 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENTS_JOB INFO">6.8.21.</a>&nbsp;
434 Getting job status information<br />
435 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#FORMAT INSTRUMENTS_DB">6.8.22.</a>&nbsp;
436 Formatting the instruments database<br />
437 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#editing_instruments">6.9.</a>&nbsp;
438 Editing Instruments<br />
439 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#EDIT INSTRUMENT">6.9.1.</a>&nbsp;
440 Opening an appropriate instrument editor application<br />
441 <a href="#command_syntax">7.</a>&nbsp;
442 Command Syntax<br />
443 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#character_set">7.1.</a>&nbsp;
444 Character Set and Escape Sequences<br />
445 <a href="#events">8.</a>&nbsp;
446 Events<br />
447 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT">8.1.</a>&nbsp;
448 Number of audio output devices changed<br />
449 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO">8.2.</a>&nbsp;
450 Audio output device's settings changed<br />
451 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INPUT_DEVICE_COUNT">8.3.</a>&nbsp;
452 Number of MIDI input devices changed<br />
453 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INPUT_DEVICE_INFO">8.4.</a>&nbsp;
454 MIDI input device's settings changed<br />
455 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE CHANNEL_COUNT">8.5.</a>&nbsp;
456 Number of sampler channels changed<br />
457 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE VOICE_COUNT">8.6.</a>&nbsp;
458 Number of active voices changed<br />
459 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE STREAM_COUNT">8.7.</a>&nbsp;
460 Number of active disk streams changed<br />
461 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE BUFFER_FILL">8.8.</a>&nbsp;
462 Disk stream buffer fill state changed<br />
463 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE CHANNEL_INFO">8.9.</a>&nbsp;
464 Channel information changed<br />
465 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE FX_SEND_COUNT">8.10.</a>&nbsp;
466 Number of effect sends changed<br />
467 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE FX_SEND_INFO">8.11.</a>&nbsp;
468 Effect send information changed<br />
469 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE TOTAL_VOICE_COUNT">8.12.</a>&nbsp;
470 Total number of active voices changed<br />
471 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT">8.13.</a>&nbsp;
472 Number of MIDI instrument maps changed<br />
473 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO">8.14.</a>&nbsp;
474 MIDI instrument map information changed<br />
475 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_COUNT">8.15.</a>&nbsp;
476 Number of MIDI instruments changed<br />
477 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_INFO">8.16.</a>&nbsp;
478 MIDI instrument information changed<br />
479 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE GLOBAL_INFO">8.17.</a>&nbsp;
480 Global settings changed<br />
481 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT">8.18.</a>&nbsp;
482 Number of database instrument directories changed<br />
483 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO">8.19.</a>&nbsp;
484 Database instrument directory information changed<br />
485 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENT_COUNT">8.20.</a>&nbsp;
486 Number of database instruments changed<br />
487 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENT_INFO">8.21.</a>&nbsp;
488 Database instrument information changed<br />
489 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENTS_JOB_INFO">8.22.</a>&nbsp;
490 Database job status information changed<br />
491 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MISCELLANEOUS">8.23.</a>&nbsp;
492 Miscellaneous and debugging events<br />
493 <a href="#anchor14">9.</a>&nbsp;
494 Security Considerations<br />
495 <a href="#anchor15">10.</a>&nbsp;
496 Acknowledgments<br />
497 <a href="#rfc.references1">11.</a>&nbsp;
498 References<br />
499 <a href="#rfc.authors">&#167;</a>&nbsp;
500 Author's Address<br />
501 <a href="#rfc.copyright">&#167;</a>&nbsp;
502 Intellectual Property and Copyright Statements<br />
503 </p>
504 <br clear="all" />
505
506 <a name="anchor1"></a><br /><hr />
507 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
508 <a name="rfc.section.1"></a><h3>1.&nbsp;
509 Requirements notation</h3>
510
511 <p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
512 "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
513 and "OPTIONAL" in this document are to be interpreted as
514 described in <a class='info' href='#RFC2119'>[RFC2119]<span> (</span><span class='info'>Bradner, S., &ldquo;Key words for use in RFCs to Indicate Requirement Levels,&rdquo; 1997.</span><span>)</span></a>.
515 </p>
516 <p>This protocol is always case-sensitive if not explicitly
517 claimed the opposite.
518 </p>
519 <p>In examples, "C:" and "S:" indicate lines sent by the client
520 (front-end) and server (LinuxSampler) respectively. Lines in
521 examples must be interpreted as every line being CRLF
522 terminated (carriage return character followed by line feed
523 character as defined in the ASCII standard <a class='info' href='#RFC20'>[RFC20]<span> (</span><span class='info'>UCLA, &ldquo;ASCII format for Network Interchange,&rdquo; 1969.</span><span>)</span></a>),
524 thus the following example:
525 </p>
526 <p>
527 </p>
528 <blockquote class="text">
529 <p>C: "some line"
530 </p>
531 <p>&nbsp;&nbsp;&nbsp;"another line"
532 </p>
533 </blockquote><p>
534
535 </p>
536 <p>must actually be interpreted as client sending the following
537 message:
538 </p>
539 <p>
540 </p>
541 <blockquote class="text">
542 <p>"some line&lt;CR&gt;&lt;LF&gt;another
543 line&lt;CR&gt;&lt;LF&gt;"
544 </p>
545 </blockquote><p>
546
547 </p>
548 <p>where &lt;CR&gt; symbolizes the carriage return character and
549 &lt;LF&gt; the line feed character as defined in the ASCII
550 standard.
551 </p>
552 <p>Due to technical reasons, messages can arbitrary be
553 fragmented, means the following example:
554 </p>
555 <p>
556 </p>
557 <blockquote class="text">
558 <p>S: "abcd"
559 </p>
560 </blockquote><p>
561
562 </p>
563 <p>could also happen to be sent in three messages like in the
564 following sequence scenario:
565 </p>
566 <p>
567 </p>
568 <ul class="text">
569 <li>server sending message "a"
570 </li>
571 <li>followed by a delay (pause) with
572 arbitrary duration
573 </li>
574 <li>followed by server sending message
575 "bcd&lt;CR&gt;"
576 </li>
577 <li>again followed by a delay (pause) with arbitrary
578 duration
579 </li>
580 <li>followed by server sending the message
581 "&lt;LF&gt;"
582 </li>
583 </ul><p>
584
585 </p>
586 <p>where again &lt;CR&gt; and &lt;LF&gt; symbolize the carriage
587 return and line feed characters respectively.
588 </p>
589 <a name="LSCP versioning"></a><br /><hr />
590 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
591 <a name="rfc.section.2"></a><h3>2.&nbsp;
592 Versioning of this specification</h3>
593
594 <p>LSCP will certainly be extended and enhanced by-and-by. Each official
595 release of the LSCP specification will be tagged with a unique version
596 tuple. The version tuple consists at least of a major and minor version
597 number like:
598
599 </p>
600 <p>
601 </p>
602 <blockquote class="text">
603 <p>"1.2"
604 </p>
605 </blockquote><p>
606
607 </p>
608 <p>
609 In this example the major version number would be "1" and the minor
610 version number would be "2". Note that the version tuple might also
611 have more than two elements. The major version number defines a
612 group of backward compatible versions. That means a frontend is
613 compatible to the connected sampler if and only if the LSCP versions
614 to which each of the two parties complies to, match both of the
615 following rules:
616
617 </p>
618 <p>Compatibility:
619 </p>
620 <p>
621 </p>
622 <ol class="text">
623 <li>The frontend's LSCP major version and the sampler's LSCP
624 major version are exactly equal.
625 </li>
626 <li>The frontend's LSCP minor version is less or equal than
627 the sampler's LSCP minor version.
628 </li>
629 </ol><p>
630
631 </p>
632 <p>
633 Compatibility can only be claimed if both rules are true.
634 The frontend can use the
635 <a class='info' href='#GET SERVER INFO'>"GET SERVER INFO"<span> (</span><span class='info'>General sampler informations</span><span>)</span></a> command to
636 get the version of the LSCP specification the sampler complies with.
637
638 </p>
639 <a name="anchor2"></a><br /><hr />
640 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
641 <a name="rfc.section.3"></a><h3>3.&nbsp;
642 Introduction</h3>
643
644 <p>LinuxSampler is a so called software sampler application
645 capable to playback audio samples from a computer's Random
646 Access Memory (RAM) as well as directly streaming it from disk.
647 LinuxSampler is designed to be modular. It provides several so
648 called "sampler engines" where each engine is specialized for a
649 certain purpose. LinuxSampler has virtual channels which will be
650 referred in this document as "sampler channels". The channels
651 are in such way virtual as they can be connected to an
652 arbitrary MIDI input method and arbitrary MIDI channel (e.g.
653 sampler channel 17 could be connected to an ALSA sequencer
654 device 64:0 and listening to MIDI channel 1 there). Each sampler
655 channel will be associated with an instance of one of the available
656 sampler engines (e.g. GigEngine, DLSEngine). The audio output of
657 each sampler channel can be routed to an arbitrary audio output
658 method (ALSA / JACK) and an arbitrary audio output channel
659 there.
660 </p>
661 <a name="anchor3"></a><br /><hr />
662 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
663 <a name="rfc.section.4"></a><h3>4.&nbsp;
664 Focus of this protocol</h3>
665
666 <p>Main focus of this protocol is to provide a way to configure
667 a running LinuxSampler instance and to retrieve information
668 about it. The focus of this protocol is not to provide a way to
669 control synthesis parameters or even to trigger or release
670 notes. Or in other words; the focus are those functionalities
671 which are not covered by MIDI or which may at most be handled
672 via MIDI System Exclusive Messages.
673 </p>
674 <a name="anchor4"></a><br /><hr />
675 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
676 <a name="rfc.section.5"></a><h3>5.&nbsp;
677 Communication Overview</h3>
678
679 <p>There are two distinct methods of communication between a
680 running instance of LinuxSampler and one or more control
681 applications, so called "front-ends": a simple request/response
682 communication method used by the clients to give commands to the
683 server as well as to inquire about server's status and a
684 subscribe/notify communication method used by the client to
685 subscribe to and receive notifications of certain events as they
686 happen on the server. The latter needs more effort to be
687 implemented in the front-end application. The two communication
688 methods will be described next.
689 </p>
690 <a name="anchor5"></a><br /><hr />
691 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
692 <a name="rfc.section.5.1"></a><h3>5.1.&nbsp;
693 Request/response communication method</h3>
694
695 <p>This simple communication method is based on
696 <a class='info' href='#RFC793'>TCP<span> (</span><span class='info'>Defense Advanced Research Projects Agency, &ldquo;TRANSMISSION CONTROL PROTOCOL,&rdquo; 1981.</span><span>)</span></a> [RFC793]. The
697 front-end application establishes a TCP connection to the
698 LinuxSampler instance on a certain host system. Then the
699 front-end application will send certain ASCII based commands
700 as defined in this document (every command line must be CRLF
701 terminated - see "Conventions used in this document" at the
702 beginning of this document) and the LinuxSampler application
703 will response after a certain process time with an
704 appropriate ASCII based answer, also as defined in this
705 document. So this TCP communication is simply based on query
706 and answer paradigm. That way LinuxSampler is only able to
707 answer on queries from front-ends, but not able to
708 automatically send messages to the client if it's not asked
709 to. The fronted should not reconnect to LinuxSampler for
710 every single command, instead it should keep the connection
711 established and simply resend message(s) for subsequent
712 commands. To keep information in the front-end up-to-date
713 the front-end has to periodically send new requests to get
714 the current information from the LinuxSampler instance. This
715 is often referred to as "polling". While polling is simple
716 to implement and may be OK to use in some cases, there may
717 be disadvantages to polling such as network traffic overhead
718 and information being out of date.
719 It is possible for a client or several clients to open more
720 than one connection to the server at the same time. It is
721 also possible to send more than one request to the server
722 at the same time but if those requests are sent over the
723 same connection server MUST execute them sequentially. Upon
724 executing a request server will produce a result set and
725 send it to the client. Each and every request made by the
726 client MUST result in a result set being sent back to the
727 client. No other data other than a result set may be sent by
728 a server to a client. No result set may be sent to a client
729 without the client sending request to the server first. On
730 any particular connection, result sets MUST be sent in their
731 entirety without being interrupted by other result sets. If
732 several requests got queued up at the server they MUST be
733 processed in the order they were received and result sets
734 MUST be sent back in the same order.
735 </p>
736 <a name="anchor6"></a><br /><hr />
737 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
738 <a name="rfc.section.5.1.1"></a><h3>5.1.1.&nbsp;
739 Result format</h3>
740
741 <p>Result set could be one of the following types:
742 </p>
743 <p>
744 </p>
745 <ol class="text">
746 <li>Normal
747 </li>
748 <li>Warning
749 </li>
750 <li>Error
751 </li>
752 </ol><p>
753
754 </p>
755 <p>Warning and Error result sets MUST be single line and
756 have the following format:
757 </p>
758 <p>
759 </p>
760 <ul class="text">
761 <li>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;"
762 </li>
763 <li>"ERR:&lt;error-code&gt;:&lt;error-message&gt;"
764 </li>
765 </ul><p>
766
767 </p>
768 <p>Where &lt;warning-code&gt; and &lt;error-code&gt; are
769 numeric unique identifiers of the warning or error and
770 &lt;warning-message&gt; and &lt;error-message&gt; are
771 human readable descriptions of the warning or error
772 respectively.
773 </p>
774 <p>Examples:
775 </p>
776 <p>
777 </p>
778 <blockquote class="text">
779 <p>C: "LOAD INSTRUMENT '/home/me/Boesendorfer24bit.gig" 0 0
780 </p>
781 <p>S: "WRN:32:This is a 24 bit patch which is not supported natively yet."
782 </p>
783 </blockquote><p>
784
785 </p>
786 <p>
787 </p>
788 <blockquote class="text">
789 <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA EAR"
790 </p>
791 <p>S: "ERR:3456:Audio output driver 'ALSA' does not have a parameter 'EAR'."
792 </p>
793 </blockquote><p>
794
795 </p>
796 <p>
797 </p>
798 <blockquote class="text">
799 <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 123456"
800 </p>
801 <p>S: "ERR:9:There is no audio output device with index 123456."
802 </p>
803 </blockquote><p>
804
805 </p>
806 <p>Normal result sets could be:
807 </p>
808 <p>
809 </p>
810 <ol class="text">
811 <li>Empty
812 </li>
813 <li>Single line
814 </li>
815 <li>Multi-line
816 </li>
817 </ol><p>
818
819 </p>
820 <p> Empty result set is issued when the server only
821 needed to acknowledge the fact that the request was
822 received and it was processed successfully and no
823 additional information is available. This result set has
824 the following format:
825 </p>
826 <p>
827 </p>
828 <blockquote class="text">
829 <p>"OK"
830 </p>
831 </blockquote><p>
832
833 </p>
834 <p>Example:
835 </p>
836 <p>
837 </p>
838 <blockquote class="text">
839 <p>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 CHANNELS=4"
840 </p>
841 <p>S: "OK"
842 </p>
843 </blockquote><p>
844
845 </p>
846 <p>Single line result sets are command specific. One
847 example of a single line result set is an empty line.
848 Multi-line result sets are command specific and may
849 include one or more lines of information. They MUST
850 always end with the following line:
851 </p>
852 <p>
853 </p>
854 <blockquote class="text">
855 <p>"."
856 </p>
857 </blockquote><p>
858
859 </p>
860 <p>Example:
861 </p>
862 <p>
863 </p>
864 <blockquote class="text">
865 <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
866 </p>
867 <p>S: "DRIVER: ALSA"
868 </p>
869 <p>&nbsp;&nbsp;&nbsp;"CHANNELS: 2"
870 </p>
871 <p>&nbsp;&nbsp;&nbsp;"SAMPLERATE: 44100"
872 </p>
873 <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
874 </p>
875 <p>&nbsp;&nbsp;&nbsp;"FRAGMENTS: 2"
876 </p>
877 <p>&nbsp;&nbsp;&nbsp;"FRAGMENTSIZE: 128"
878 </p>
879 <p>&nbsp;&nbsp;&nbsp;"CARD: '0,0'"
880 </p>
881 <p>&nbsp;&nbsp;&nbsp;"."
882 </p>
883 </blockquote><p>
884
885 </p>
886 <p>In addition to above mentioned formats, warnings and
887 empty result sets MAY be indexed. In this case, they
888 have the following formats respectively:
889 </p>
890 <p>
891 </p>
892 <ul class="text">
893 <li>"WRN[&lt;index&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;"
894 </li>
895 <li>"OK[&lt;index&gt;]"
896 </li>
897 </ul><p>
898
899 </p>
900 <p>where &lt;index&gt; is command specific and is used
901 to indicate channel number that the result set was
902 related to or other integer value.
903 </p>
904 <p>Each line of the result set MUST end with
905 &lt;CRLF&gt;.
906 </p>
907 <p>Examples:
908 </p>
909 <p>
910 </p>
911 <blockquote class="text">
912 <p>C: "ADD CHANNEL"
913 </p>
914 <p>S: "OK[12]"
915 </p>
916 </blockquote><p>
917
918 </p>
919 <p>
920 </p>
921 <blockquote class="text">
922 <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"
923 </p>
924 <p>S: "WRN[0]:32:Sample rate not supported, using 44100 instead."
925 </p>
926 </blockquote><p>
927
928 </p>
929 <a name="anchor7"></a><br /><hr />
930 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
931 <a name="rfc.section.5.2"></a><h3>5.2.&nbsp;
932 Subscribe/notify communication method</h3>
933
934 <p>This more sophisticated communication method is actually
935 only an extension of the simple request/response
936 communication method. The front-end still uses a TCP
937 connection and sends the same commands on the TCP
938 connection. Two extra commands are SUBSCRIBE and UNSUBSCRIBE
939 commands that allow a client to tell the server that it is
940 interested in receiving notifications about certain events
941 as they happen on the server. The SUBSCRIBE command has the
942 following syntax:
943 </p>
944 <p>
945 </p>
946 <blockquote class="text">
947 <p>SUBSCRIBE &lt;event-id&gt;
948 </p>
949 </blockquote><p>
950
951 </p>
952 <p>where &lt;event-id&gt; will be replaced by the respective
953 event that client wants to subscribe to. Upon receiving such
954 request, server SHOULD respond with OK and start sending
955 EVENT notifications when a given even has occurred to the
956 front-end when an event has occurred. It MAY be possible
957 certain events may be sent before OK response during real
958 time nature of their generation. Event messages have the
959 following format:
960 </p>
961 <p>
962 </p>
963 <blockquote class="text">
964 <p>NOTIFY:&lt;event-id&gt;:&lt;custom-event-data&gt;
965 </p>
966 </blockquote><p>
967
968 </p>
969 <p>where &lt;event-id&gt; uniquely identifies the event that
970 has occurred and &lt;custom-event-data&gt; is event
971 specific.
972 </p>
973 <p>Several rules must be followed by the server when
974 generating events:
975 </p>
976 <p>
977 </p>
978 <ol class="text">
979 <li>Events MUST NOT be sent to any client who has not
980 issued an appropriate SUBSCRIBE command.
981 </li>
982 <li>Events MUST only be sent using the same
983 connection that was used to subscribe to them.
984 </li>
985 <li>When response is being sent to the client, event
986 MUST be inserted in the stream before or after the
987 response, but NOT in the middle. Same is true about
988 the response. It should never be inserted in the
989 middle of the event message as well as any other
990 response.
991 </li>
992 </ol><p>
993
994 </p>
995 <p>If the client is not interested in a particular event
996 anymore it MAY issue UNSUBSCRIBE command using the following
997 syntax:
998 </p>
999 <p>
1000 </p>
1001 <blockquote class="text">
1002 <p>UNSUBSCRIBE &lt;event-id&gt;
1003 </p>
1004 </blockquote><p>
1005
1006 </p>
1007 <p>where &lt;event-id&gt; will be replace by the respective
1008 event that client is no longer interested in receiving. For
1009 a list of supported events see <a class='info' href='#events'>Section&nbsp;8<span> (</span><span class='info'>Events</span><span>)</span></a>.
1010 </p>
1011 <p>Example: the fill states of disk stream buffers have
1012 changed on sampler channel 4 and the LinuxSampler instance
1013 will react by sending the following message to all clients
1014 who subscribed to this event:
1015 </p>
1016 <p>
1017 </p>
1018 <blockquote class="text">
1019 <p>NOTIFY:CHANNEL_BUFFER_FILL:4 [35]62%,[33]80%,[37]98%
1020 </p>
1021 </blockquote><p>
1022
1023 </p>
1024 <p>Which means there are currently three active streams on
1025 sampler channel 4, where the stream with ID "35" is filled
1026 by 62%, stream with ID 33 is filled by 80% and stream with
1027 ID 37 is filled by 98%.
1028 </p>
1029 <p>Clients may choose to open more than one connection to
1030 the server and use some connections to receive notifications
1031 while using other connections to issue commands to the
1032 back-end. This is entirely legal and up to the
1033 implementation. This does not change the protocol in any way
1034 and no special restrictions exist on the server to allow or
1035 disallow this or to track what connections belong to what
1036 front-ends. Server will listen on a single port, accept
1037 multiple connections and support protocol described in this
1038 specification in it's entirety on this single port on each
1039 connection that it accepted.
1040 </p>
1041 <p>Due to the fact that TCP is used for this communication,
1042 dead peers will be detected automatically by the OS TCP
1043 stack. While it may take a while to detect dead peers if no
1044 traffic is being sent from server to client (TCP keep-alive
1045 timer is set to 2 hours on many OSes) it will not be an
1046 issue here as when notifications are sent by the server,
1047 dead client will be detected quickly.
1048 </p>
1049 <p>When connection is closed for any reason server MUST
1050 forget all subscriptions that were made on this connection.
1051 If client reconnects it MUST resubscribe to all events that
1052 it wants to receive.
1053 </p>
1054 <a name="control_commands"></a><br /><hr />
1055 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1056 <a name="rfc.section.6"></a><h3>6.&nbsp;
1057 Description for control commands</h3>
1058
1059 <p>This chapter will describe the available control commands
1060 that can be sent on the TCP connection in detail. Some certain
1061 commands (e.g. <a class='info' href='#GET CHANNEL INFO'>"GET CHANNEL INFO"<span> (</span><span class='info'>Getting sampler channel information</span><span>)</span></a>
1062 or <a class='info' href='#GET ENGINE INFO'>"GET ENGINE INFO"<span> (</span><span class='info'>Getting information about an engine</span><span>)</span></a>) lead to
1063 multiple-line responses. In this case LinuxSampler signals the
1064 end of the response by a "." (single dot) line.
1065 </p>
1066 <a name="anchor8"></a><br /><hr />
1067 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1068 <a name="rfc.section.6.1"></a><h3>6.1.&nbsp;
1069 Ignored lines and comments</h3>
1070
1071 <p>White lines, that is lines which only contain space and
1072 tabulator characters, and lines that start with a "#"
1073 character are ignored, thus it's possible for example to
1074 group commands and to place comments in a LSCP script
1075 file.
1076 </p>
1077 <a name="anchor9"></a><br /><hr />
1078 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1079 <a name="rfc.section.6.2"></a><h3>6.2.&nbsp;
1080 Configuring audio drivers</h3>
1081
1082 <p>Instances of drivers in LinuxSampler are called devices.
1083 You can use multiple audio devices simultaneously, e.g. to
1084 output the sound of one sampler channel using the ALSA audio
1085 output driver, and on another sampler channel you might want
1086 to use the JACK audio output driver. For particular audio
1087 output systems it's also possible to create several devices
1088 of the same audio output driver, e.g. two separate ALSA
1089 audio output devices for using two different sound cards at
1090 the same time. This chapter describes all commands to
1091 configure LinuxSampler's audio output devices and their
1092 parameters.
1093 </p>
1094 <p>Instead of defining commands and parameters for each
1095 driver individually, all possible parameters, their meanings
1096 and possible values have to be obtained at runtime. This
1097 makes the protocol a bit abstract, but has the advantage,
1098 that front-ends can be written independently of what drivers
1099 are currently implemented and what parameters these drivers
1100 are actually offering. This means front-ends can even handle
1101 drivers which are implemented somewhere in future without
1102 modifying the front-end at all.
1103 </p>
1104 <p>Note: examples in this chapter showing particular
1105 parameters of drivers are not meant as specification of the
1106 drivers' parameters. Driver implementations in LinuxSampler
1107 might have complete different parameter names and meanings
1108 than shown in these examples or might change in future, so
1109 these examples are only meant for showing how to retrieve
1110 what parameters drivers are offering, how to retrieve their
1111 possible values, etc.
1112 </p>
1113 <a name="GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"></a><br /><hr />
1114 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1115 <a name="rfc.section.6.2.1"></a><h3>6.2.1.&nbsp;
1116 Getting amount of available audio output drivers</h3>
1117
1118 <p>Use the following command to get the number of
1119 audio output drivers currently available for the
1120 LinuxSampler instance:
1121 </p>
1122 <p>
1123 </p>
1124 <blockquote class="text">
1125 <p>GET AVAILABLE_AUDIO_OUTPUT_DRIVERS
1126 </p>
1127 </blockquote><p>
1128
1129 </p>
1130 <p>Possible Answers:
1131 </p>
1132 <p>
1133 </p>
1134 <blockquote class="text">
1135 <p>LinuxSampler will answer by sending the
1136 number of audio output drivers.
1137 </p>
1138 </blockquote><p>
1139
1140 </p>
1141 <p>Example:
1142 </p>
1143 <p>
1144 </p>
1145 <blockquote class="text">
1146 <p>C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
1147 </p>
1148 <p>S: "2"
1149 </p>
1150 </blockquote><p>
1151
1152 </p>
1153 <a name="LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"></a><br /><hr />
1154 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1155 <a name="rfc.section.6.2.2"></a><h3>6.2.2.&nbsp;
1156 Getting all available audio output drivers</h3>
1157
1158 <p>Use the following command to list all audio output
1159 drivers currently available for the LinuxSampler
1160 instance:
1161 </p>
1162 <p>
1163 </p>
1164 <blockquote class="text">
1165 <p>LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS
1166 </p>
1167 </blockquote><p>
1168
1169 </p>
1170 <p>Possible Answers:
1171 </p>
1172 <p>
1173 </p>
1174 <blockquote class="text">
1175 <p>LinuxSampler will answer by sending comma
1176 separated character strings, each symbolizing an
1177 audio output driver.
1178 </p>
1179 </blockquote><p>
1180
1181 </p>
1182 <p>Example:
1183 </p>
1184 <p>
1185 </p>
1186 <blockquote class="text">
1187 <p>C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"
1188 </p>
1189 <p>S: "ALSA,JACK"
1190 </p>
1191 </blockquote><p>
1192
1193 </p>
1194 <a name="GET AUDIO_OUTPUT_DRIVER INFO"></a><br /><hr />
1195 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1196 <a name="rfc.section.6.2.3"></a><h3>6.2.3.&nbsp;
1197 Getting information about a specific audio
1198 output driver</h3>
1199
1200 <p>Use the following command to get detailed information
1201 about a specific audio output driver:
1202 </p>
1203 <p>
1204 </p>
1205 <blockquote class="text">
1206 <p>GET AUDIO_OUTPUT_DRIVER INFO
1207 &lt;audio-output-driver&gt;
1208 </p>
1209 </blockquote><p>
1210
1211 </p>
1212 <p>Where &lt;audio-output-driver&gt; is the name of the
1213 audio output driver, returned by the
1214 <a class='info' href='#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS'>"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"<span> (</span><span class='info'>Getting all available audio output drivers</span><span>)</span></a> command.
1215 </p>
1216 <p>Possible Answers:
1217 </p>
1218 <p>
1219 </p>
1220 <blockquote class="text">
1221 <p>LinuxSampler will answer by sending a
1222 &lt;CRLF&gt; separated list. Each answer line
1223 begins with the information category name
1224 followed by a colon and then a space character
1225 &lt;SP&gt; and finally the info character string
1226 to that info category. At the moment the
1227 following information categories are
1228 defined:
1229 </p>
1230 <p>
1231 </p>
1232 <blockquote class="text">
1233 <p>DESCRIPTION -
1234 </p>
1235 <blockquote class="text">
1236 <p> character string describing the
1237 audio output driver
1238 </p>
1239 </blockquote>
1240
1241
1242 <p>VERSION -
1243 </p>
1244 <blockquote class="text">
1245 <p>character string reflecting the
1246 driver's version
1247 </p>
1248 </blockquote>
1249
1250
1251 <p>PARAMETERS -
1252 </p>
1253 <blockquote class="text">
1254 <p>comma separated list of all
1255 parameters available for the given
1256 audio output driver, at least
1257 parameters 'channels', 'samplerate'
1258 and 'active' are offered by all audio
1259 output drivers
1260 </p>
1261 </blockquote>
1262
1263
1264 </blockquote>
1265
1266
1267 <p>The mentioned fields above don't have to be
1268 in particular order.
1269 </p>
1270 </blockquote><p>
1271
1272 </p>
1273 <p>Example:
1274 </p>
1275 <p>
1276 </p>
1277 <blockquote class="text">
1278 <p>C: "GET AUDIO_OUTPUT_DRIVER INFO ALSA"
1279 </p>
1280 <p>S: "DESCRIPTION: Advanced Linux Sound
1281 Architecture"
1282 </p>
1283 <p>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"
1284 </p>
1285 <p>&nbsp;&nbsp;&nbsp;"PARAMETERS:
1286 DRIVER,CHANNELS,SAMPLERATE,ACTIVE,FRAGMENTS,
1287 FRAGMENTSIZE,CARD"
1288 </p>
1289 <p>&nbsp;&nbsp;&nbsp;"."
1290 </p>
1291 </blockquote><p>
1292
1293 </p>
1294 <a name="GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO"></a><br /><hr />
1295 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1296 <a name="rfc.section.6.2.4"></a><h3>6.2.4.&nbsp;
1297 Getting information about specific audio
1298 output driver parameter</h3>
1299
1300 <p>Use the following command to get detailed information
1301 about a specific audio output driver parameter:
1302 </p>
1303 <p>
1304 </p>
1305 <blockquote class="text">
1306 <p>GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO &lt;audio&gt; &lt;prm&gt; [&lt;deplist&gt;]
1307 </p>
1308 </blockquote><p>
1309
1310 </p>
1311 <p>Where &lt;audio&gt; is the name of the audio output
1312 driver as returned by the <a class='info' href='#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS'>"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"<span> (</span><span class='info'>Getting all available audio output drivers</span><span>)</span></a> command,
1313 &lt;prm&gt; a specific parameter name for which information should be
1314 obtained (as returned by the
1315 <a class='info' href='#GET AUDIO_OUTPUT_DRIVER INFO'>"GET AUDIO_OUTPUT_DRIVER INFO"<span> (</span><span class='info'>Getting information about a specific audio output driver</span><span>)</span></a> command) and
1316 &lt;deplist&gt; is an optional list of parameters on which the sought
1317 parameter &lt;prm&gt; depends on, &lt;deplist&gt; is a list of key-value
1318 pairs in form of "key1=val1 key2=val2 ...", where character string values
1319 are encapsulated into apostrophes ('). Arguments given with &lt;deplist&gt;
1320 which are not dependency parameters of &lt;prm&gt; will be ignored, means
1321 the front-end application can simply put all parameters into &lt;deplist&gt;
1322 with the values already selected by the user.
1323 </p>
1324 <p>Possible Answers:
1325 </p>
1326 <p>
1327 </p>
1328 <blockquote class="text">
1329 <p>LinuxSampler will answer by sending a
1330 &lt;CRLF&gt; separated list.
1331 Each answer line begins with the information category name
1332 followed by a colon and then a space character &lt;SP&gt; and
1333 finally
1334 the info character string to that info category. There are
1335 information which is always returned, independently of the
1336 given driver parameter and there are optional information
1337 which is only shown dependently to given driver parameter. At
1338 the moment the following information categories are defined:
1339 </p>
1340 </blockquote><p>
1341
1342 </p>
1343 <p>
1344 </p>
1345 <blockquote class="text">
1346 <p>TYPE -
1347 </p>
1348 <blockquote class="text">
1349 <p>either "BOOL" for boolean value(s) or
1350 "INT" for integer
1351 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1352 character string(s)
1353 (always returned, no matter which driver parameter)
1354 </p>
1355 </blockquote>
1356
1357
1358 <p>DESCRIPTION -
1359 </p>
1360 <blockquote class="text">
1361 <p>arbitrary text describing the purpose of the parameter
1362 (always returned, no matter which driver parameter)
1363 </p>
1364 </blockquote>
1365
1366
1367 <p>MANDATORY -
1368 </p>
1369 <blockquote class="text">
1370 <p>either true or false, defines if this parameter must be
1371 given when the device is to be created with the
1372 <a class='info' href='#CREATE AUDIO_OUTPUT_DEVICE'>'CREATE AUDIO_OUTPUT_DEVICE'<span> (</span><span class='info'>Creating an audio output device</span><span>)</span></a>
1373 command (always returned, no matter which driver parameter)
1374 </p>
1375 </blockquote>
1376
1377
1378 <p>FIX -
1379 </p>
1380 <blockquote class="text">
1381 <p>either true or false, if false then this parameter can
1382 be changed at any time, once the device is created by
1383 the <a class='info' href='#CREATE AUDIO_OUTPUT_DEVICE'>'CREATE AUDIO_OUTPUT_DEVICE'<span> (</span><span class='info'>Creating an audio output device</span><span>)</span></a>
1384 command (always returned, no matter which driver parameter)
1385 </p>
1386 </blockquote>
1387
1388
1389 <p>MULTIPLICITY -
1390 </p>
1391 <blockquote class="text">
1392 <p>either true or false, defines if this parameter allows
1393 only one value or a list of values, where true means
1394 multiple values and false only a single value allowed
1395 (always returned, no matter which driver parameter)
1396 </p>
1397 </blockquote>
1398
1399
1400 <p>DEPENDS -
1401 </p>
1402 <blockquote class="text">
1403 <p>comma separated list of parameters this parameter depends
1404 on, means the values for fields 'DEFAULT', 'RANGE_MIN',
1405 'RANGE_MAX' and 'POSSIBILITIES' might depend on these
1406 listed parameters, for example assuming that an audio
1407 driver (like the ALSA driver) offers parameters 'card'
1408 and 'samplerate' then parameter 'samplerate' would
1409 depend on 'card' because the possible values for
1410 'samplerate' depends on the sound card which can be
1411 chosen by the 'card' parameter
1412 (optionally returned, dependent to driver parameter)
1413 </p>
1414 </blockquote>
1415
1416
1417 <p>DEFAULT -
1418 </p>
1419 <blockquote class="text">
1420 <p>reflects the default value for this parameter which is
1421 used when the device is created and not explicitly
1422 given with the <a class='info' href='#CREATE AUDIO_OUTPUT_DEVICE'>'CREATE AUDIO_OUTPUT_DEVICE'<span> (</span><span class='info'>Creating an audio output device</span><span>)</span></a> command,
1423 in case of MULTIPLCITY=true, this is a comma separated
1424 list, that's why character strings are encapsulated into
1425 apostrophes (')
1426 (optionally returned, dependent to driver parameter)
1427 </p>
1428 </blockquote>
1429
1430
1431 <p>RANGE_MIN -
1432 </p>
1433 <blockquote class="text">
1434 <p>defines lower limit of the allowed value range for this
1435 parameter, can be an integer value as well as a dotted
1436 number, this parameter is often used in conjunction
1437 with RANGE_MAX, but may also appear without
1438 (optionally returned, dependent to driver parameter)
1439 </p>
1440 </blockquote>
1441
1442
1443 <p>RANGE_MAX -
1444 </p>
1445 <blockquote class="text">
1446 <p>defines upper limit of the allowed value range for this
1447 parameter, can be an integer value as well as a dotted
1448 number, this parameter is often used in conjunction with
1449 RANGE_MIN, but may also appear without
1450 (optionally returned, dependent to driver parameter)
1451 </p>
1452 </blockquote>
1453
1454
1455 <p>POSSIBILITIES -
1456 </p>
1457 <blockquote class="text">
1458 <p>comma separated list of possible values for this
1459 parameter, character strings are encapsulated into
1460 apostrophes
1461 (optionally returned, dependent to driver parameter)
1462 </p>
1463 </blockquote>
1464
1465
1466 </blockquote><p>
1467
1468 </p>
1469 <p>The mentioned fields above don't have to be in particular order.
1470 </p>
1471 <p>Examples:
1472 </p>
1473 <p>
1474 </p>
1475 <blockquote class="text">
1476 <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA CARD"
1477 </p>
1478 <p>S: "DESCRIPTION: sound card to be used"
1479 </p>
1480 <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
1481 </p>
1482 <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1483 </p>
1484 <p>&nbsp;&nbsp;&nbsp;"FIX: true"
1485 </p>
1486 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1487 </p>
1488 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: '0,0'"
1489 </p>
1490 <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: '0,0','1,0','2,0'"
1491 </p>
1492 <p>&nbsp;&nbsp;&nbsp;"."
1493 </p>
1494 </blockquote><p>
1495
1496 </p>
1497 <p>
1498 </p>
1499 <blockquote class="text">
1500 <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE"
1501 </p>
1502 <p>S: "DESCRIPTION: output sample rate in Hz"
1503 </p>
1504 <p>&nbsp;&nbsp;&nbsp;"TYPE: INT"
1505 </p>
1506 <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1507 </p>
1508 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
1509 </p>
1510 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1511 </p>
1512 <p>&nbsp;&nbsp;&nbsp;"DEPENDS: card"
1513 </p>
1514 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"
1515 </p>
1516 <p>&nbsp;&nbsp;&nbsp;"."
1517 </p>
1518 </blockquote><p>
1519
1520 </p>
1521 <p>
1522 </p>
1523 <blockquote class="text">
1524 <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE CARD='0,0'"
1525 </p>
1526 <p>S: "DESCRIPTION: output sample rate in Hz"
1527 </p>
1528 <p>&nbsp;&nbsp;&nbsp;"TYPE: INT"
1529 </p>
1530 <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1531 </p>
1532 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
1533 </p>
1534 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1535 </p>
1536 <p>&nbsp;&nbsp;&nbsp;"DEPENDS: card"
1537 </p>
1538 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"
1539 </p>
1540 <p>&nbsp;&nbsp;&nbsp;"RANGE_MIN: 22050"
1541 </p>
1542 <p>&nbsp;&nbsp;&nbsp;"RANGE_MAX: 96000"
1543 </p>
1544 <p>&nbsp;&nbsp;&nbsp;"."
1545 </p>
1546 </blockquote><p>
1547
1548 </p>
1549 <a name="CREATE AUDIO_OUTPUT_DEVICE"></a><br /><hr />
1550 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1551 <a name="rfc.section.6.2.5"></a><h3>6.2.5.&nbsp;
1552 Creating an audio output device</h3>
1553
1554 <p>Use the following command to create a new audio output device for the desired audio output system:
1555 </p>
1556 <p>
1557 </p>
1558 <blockquote class="text">
1559 <p>CREATE AUDIO_OUTPUT_DEVICE &lt;audio-output-driver&gt; [&lt;param-list&gt;]
1560 </p>
1561 </blockquote><p>
1562
1563 </p>
1564 <p>Where &lt;audio-output-driver&gt; should be replaced by the desired audio
1565 output system as returned by the
1566 <a class='info' href='#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS'>"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"<span> (</span><span class='info'>Getting all available audio output drivers</span><span>)</span></a>
1567 command and &lt;param-list&gt; by an optional list of driver
1568 specific parameters in form of "key1=val1 key2=val2 ...", where
1569 character string values should be encapsulated into apostrophes (').
1570 Note that there might be drivers which require parameter(s) to be
1571 given with this command. Use the previously described commands in
1572 this chapter to get this information.
1573 </p>
1574 <p>Possible Answers:
1575 </p>
1576 <p>
1577 </p>
1578 <blockquote class="text">
1579 <p>"OK[&lt;device-id&gt;]" -
1580 </p>
1581 <blockquote class="text">
1582 <p>in case the device was successfully created, where
1583 &lt;device-id&gt; is the numerical ID of the new device
1584 </p>
1585 </blockquote>
1586
1587
1588 <p>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1589 </p>
1590 <blockquote class="text">
1591 <p>in case the device was created successfully, where
1592 &lt;device-id&gt; is the numerical ID of the new device, but there
1593 are noteworthy issue(s) related (e.g. sound card doesn't
1594 support given hardware parameters and the driver is using
1595 fall-back values), providing an appropriate warning code and
1596 warning message
1597 </p>
1598 </blockquote>
1599
1600
1601 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1602 </p>
1603 <blockquote class="text">
1604 <p>in case it failed, providing an appropriate error code and error message
1605 </p>
1606 </blockquote>
1607
1608
1609 </blockquote><p>
1610
1611 </p>
1612 <p>Examples:
1613 </p>
1614 <p>
1615 </p>
1616 <blockquote class="text">
1617 <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA"
1618 </p>
1619 <p>S: "OK[0]"
1620 </p>
1621 </blockquote><p>
1622
1623 </p>
1624 <p>
1625 </p>
1626 <blockquote class="text">
1627 <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"
1628 </p>
1629 <p>S: "OK[1]"
1630 </p>
1631 </blockquote><p>
1632
1633 </p>
1634 <a name="DESTROY AUDIO_OUTPUT_DEVICE"></a><br /><hr />
1635 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1636 <a name="rfc.section.6.2.6"></a><h3>6.2.6.&nbsp;
1637 Destroying an audio output device</h3>
1638
1639 <p>Use the following command to destroy a created output device:
1640 </p>
1641 <p>
1642 </p>
1643 <blockquote class="text">
1644 <p>DESTROY AUDIO_OUTPUT_DEVICE &lt;device-id&gt;
1645 </p>
1646 </blockquote><p>
1647
1648 </p>
1649 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1650 audio output device as given by the
1651 <a class='info' href='#CREATE AUDIO_OUTPUT_DEVICE'>"CREATE AUDIO_OUTPUT_DEVICE"<span> (</span><span class='info'>Creating an audio output device</span><span>)</span></a>
1652 or <a class='info' href='#LIST AUDIO_OUTPUT_DEVICES'>"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class='info'>Getting all created audio output device list</span><span>)</span></a>
1653 command.
1654 </p>
1655 <p>Possible Answers:
1656 </p>
1657 <p>
1658 </p>
1659 <blockquote class="text">
1660 <p>"OK" -
1661 </p>
1662 <blockquote class="text">
1663 <p>in case the device was successfully destroyed
1664 </p>
1665 </blockquote>
1666
1667
1668 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1669 </p>
1670 <blockquote class="text">
1671 <p>in case the device was destroyed successfully, but there are
1672 noteworthy issue(s) related (e.g. an audio over ethernet
1673 driver was unloaded but the other host might not be
1674 informed about this situation), providing an appropriate
1675 warning code and warning message
1676 </p>
1677 </blockquote>
1678
1679
1680 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1681 </p>
1682 <blockquote class="text">
1683 <p>in case it failed, providing an appropriate error code and
1684 error message
1685 </p>
1686 </blockquote>
1687
1688
1689 </blockquote><p>
1690
1691 </p>
1692 <p>Example:
1693 </p>
1694 <p>
1695 </p>
1696 <blockquote class="text">
1697 <p>C: "DESTROY AUDIO_OUTPUT_DEVICE 0"
1698 </p>
1699 <p>S: "OK"
1700 </p>
1701 </blockquote><p>
1702
1703 </p>
1704 <a name="GET AUDIO_OUTPUT_DEVICES"></a><br /><hr />
1705 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1706 <a name="rfc.section.6.2.7"></a><h3>6.2.7.&nbsp;
1707 Getting all created audio output device count</h3>
1708
1709 <p>Use the following command to count all created audio output devices:
1710 </p>
1711 <p>
1712 </p>
1713 <blockquote class="text">
1714 <p>GET AUDIO_OUTPUT_DEVICES
1715 </p>
1716 </blockquote><p>
1717
1718 </p>
1719 <p>Possible Answers:
1720 </p>
1721 <p>
1722 </p>
1723 <blockquote class="text">
1724 <p>LinuxSampler will answer by sending the current number of all
1725 audio output devices.
1726 </p>
1727 </blockquote><p>
1728
1729 </p>
1730 <p>Example:
1731 </p>
1732 <p>
1733 </p>
1734 <blockquote class="text">
1735 <p>C: "GET AUDIO_OUTPUT_DEVICES"
1736 </p>
1737 <p>S: "4"
1738 </p>
1739 </blockquote><p>
1740
1741 </p>
1742 <a name="LIST AUDIO_OUTPUT_DEVICES"></a><br /><hr />
1743 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1744 <a name="rfc.section.6.2.8"></a><h3>6.2.8.&nbsp;
1745 Getting all created audio output device list</h3>
1746
1747 <p>Use the following command to list all created audio output devices:
1748 </p>
1749 <p>
1750 </p>
1751 <blockquote class="text">
1752 <p>LIST AUDIO_OUTPUT_DEVICES
1753 </p>
1754 </blockquote><p>
1755
1756 </p>
1757 <p>Possible Answers:
1758 </p>
1759 <p>
1760 </p>
1761 <blockquote class="text">
1762 <p>LinuxSampler will answer by sending a comma separated list with
1763 the numerical IDs of all audio output devices.
1764 </p>
1765 </blockquote><p>
1766
1767 </p>
1768 <p>Example:
1769 </p>
1770 <p>
1771 </p>
1772 <blockquote class="text">
1773 <p>C: "LIST AUDIO_OUTPUT_DEVICES"
1774 </p>
1775 <p>S: "0,1,4,5"
1776 </p>
1777 </blockquote><p>
1778
1779 </p>
1780 <a name="GET AUDIO_OUTPUT_DEVICE INFO"></a><br /><hr />
1781 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1782 <a name="rfc.section.6.2.9"></a><h3>6.2.9.&nbsp;
1783 Getting current settings of an audio output device</h3>
1784
1785 <p>Use the following command to get current settings of a specific, created audio output device:
1786 </p>
1787 <p>
1788 </p>
1789 <blockquote class="text">
1790 <p>GET AUDIO_OUTPUT_DEVICE INFO &lt;device-id&gt;
1791 </p>
1792 </blockquote><p>
1793
1794 </p>
1795 <p>Where &lt;device-id&gt; should be replaced by numerical ID
1796 of the audio output device as e.g. returned by the
1797 <a class='info' href='#LIST AUDIO_OUTPUT_DEVICES'>"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class='info'>Getting all created audio output device list</span><span>)</span></a> command.
1798 </p>
1799 <p>Possible Answers:
1800 </p>
1801 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1802 Each answer line begins with the information category name
1803 followed by a colon and then a space character &lt;SP&gt; and finally
1804 the info character string to that info category. As some
1805 parameters might allow multiple values, character strings are
1806 encapsulated into apostrophes ('). At the moment the following
1807 information categories are defined (independently of device):
1808 </p>
1809 <p>
1810 </p>
1811 <blockquote class="text">
1812 <p>DRIVER -
1813 </p>
1814 <blockquote class="text">
1815 <p>identifier of the used audio output driver, as also
1816 returned by the
1817 <a class='info' href='#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS'>"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"<span> (</span><span class='info'>Getting all available audio output drivers</span><span>)</span></a>
1818 command
1819 </p>
1820 </blockquote>
1821
1822
1823 <p>CHANNELS -
1824 </p>
1825 <blockquote class="text">
1826 <p>amount of audio output channels this device currently
1827 offers
1828 </p>
1829 </blockquote>
1830
1831
1832 <p>SAMPLERATE -
1833 </p>
1834 <blockquote class="text">
1835 <p>playback sample rate the device uses
1836 </p>
1837 </blockquote>
1838
1839
1840 <p>ACTIVE -
1841 </p>
1842 <blockquote class="text">
1843 <p>either true or false, if false then the audio device is
1844 inactive and doesn't output any sound, nor do the
1845 sampler channels connected to this audio device render
1846 any audio
1847 </p>
1848 </blockquote>
1849
1850
1851 </blockquote><p>
1852
1853 </p>
1854 <p>The mentioned fields above don't have to be in particular
1855 order. The fields above are only those fields which are
1856 returned by all audio output devices. Every audio output driver
1857 might have its own, additional driver specific parameters (see
1858 <a class='info' href='#GET AUDIO_OUTPUT_DRIVER INFO'>Section&nbsp;6.2.3<span> (</span><span class='info'>Getting information about a specific audio output driver</span><span>)</span></a>)
1859 which are also returned by this command.
1860 </p>
1861 <p>Example:
1862 </p>
1863 <p>
1864 </p>
1865 <blockquote class="text">
1866 <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
1867 </p>
1868 <p>S: "DRIVER: ALSA"
1869 </p>
1870 <p>&nbsp;&nbsp;&nbsp;"CHANNELS: 2"
1871 </p>
1872 <p>&nbsp;&nbsp;&nbsp;"SAMPLERATE: 44100"
1873 </p>
1874 <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
1875 </p>
1876 <p>&nbsp;&nbsp;&nbsp;"FRAGMENTS: 2"
1877 </p>
1878 <p>&nbsp;&nbsp;&nbsp;"FRAGMENTSIZE: 128"
1879 </p>
1880 <p>&nbsp;&nbsp;&nbsp;"CARD: '0,0'"
1881 </p>
1882 <p>&nbsp;&nbsp;&nbsp;"."
1883 </p>
1884 </blockquote><p>
1885
1886 </p>
1887 <a name="SET AUDIO_OUTPUT_DEVICE_PARAMETER"></a><br /><hr />
1888 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1889 <a name="rfc.section.6.2.10"></a><h3>6.2.10.&nbsp;
1890 Changing settings of audio output devices</h3>
1891
1892 <p>Use the following command to alter a specific setting of a created audio output device:
1893 </p>
1894 <p>
1895 </p>
1896 <blockquote class="text">
1897 <p>SET AUDIO_OUTPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;
1898 </p>
1899 </blockquote><p>
1900
1901 </p>
1902 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1903 audio output device as given by the
1904 <a class='info' href='#CREATE AUDIO_OUTPUT_DEVICE'>"CREATE AUDIO_OUTPUT_DEVICE"<span> (</span><span class='info'>Creating an audio output device</span><span>)</span></a>
1905 or <a class='info' href='#LIST AUDIO_OUTPUT_DEVICES'>"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class='info'>Getting all created audio output device list</span><span>)</span></a>
1906 command, &lt;key&gt; by the name of the parameter to change
1907 and &lt;value&gt; by the new value for this parameter.
1908 </p>
1909 <p>Possible Answers:
1910 </p>
1911 <p>
1912 </p>
1913 <blockquote class="text">
1914 <p>"OK" -
1915 </p>
1916 <blockquote class="text">
1917 <p>in case setting was successfully changed
1918 </p>
1919 </blockquote>
1920
1921
1922 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1923 </p>
1924 <blockquote class="text">
1925 <p>in case setting was changed successfully, but there are
1926 noteworthy issue(s) related, providing an appropriate
1927 warning code and warning message
1928 </p>
1929 </blockquote>
1930
1931
1932 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1933 </p>
1934 <blockquote class="text">
1935 <p>in case it failed, providing an appropriate error code and
1936 error message
1937 </p>
1938 </blockquote>
1939
1940
1941 </blockquote><p>
1942
1943 </p>
1944 <p>Example:
1945 </p>
1946 <p>
1947 </p>
1948 <blockquote class="text">
1949 <p>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"
1950 </p>
1951 <p>S: "OK"
1952 </p>
1953 </blockquote><p>
1954
1955 </p>
1956 <a name="GET AUDIO_OUTPUT_CHANNEL INFO"></a><br /><hr />
1957 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1958 <a name="rfc.section.6.2.11"></a><h3>6.2.11.&nbsp;
1959 Getting information about an audio channel</h3>
1960
1961 <p>Use the following command to get information about an audio channel:
1962 </p>
1963 <p>
1964 </p>
1965 <blockquote class="text">
1966 <p>GET AUDIO_OUTPUT_CHANNEL INFO &lt;device-id&gt; &lt;audio-chan&gt;
1967 </p>
1968 </blockquote><p>
1969
1970 </p>
1971 <p>Where &lt;device-id&gt; is the numerical ID of the audio output device as given by the
1972 <a class='info' href='#CREATE AUDIO_OUTPUT_DEVICE'>"CREATE AUDIO_OUTPUT_DEVICE"<span> (</span><span class='info'>Creating an audio output device</span><span>)</span></a>
1973 or <a class='info' href='#LIST AUDIO_OUTPUT_DEVICES'>"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class='info'>Getting all created audio output device list</span><span>)</span></a>
1974 command and &lt;audio-chan&gt; the audio channel number.
1975 </p>
1976 <p>Possible Answers:
1977 </p>
1978 <p>
1979 </p>
1980 <blockquote class="text">
1981 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1982 Each answer line begins with the information category name
1983 followed by a colon and then a space character &lt;SP&gt; and finally
1984 the info character string to that info category. At the moment
1985 the following information categories are defined:
1986 </p>
1987 <p>
1988 </p>
1989 <blockquote class="text">
1990 <p>NAME -
1991 </p>
1992 <blockquote class="text">
1993 <p>arbitrary character string naming the channel, which
1994 doesn't have to be unique (always returned by all audio channels)
1995 </p>
1996 </blockquote>
1997
1998
1999 <p>IS_MIX_CHANNEL -
2000 </p>
2001 <blockquote class="text">
2002 <p>either true or false, a mix-channel is not a real,
2003 independent audio channel, but a virtual channel which
2004 is mixed to another real channel, this mechanism is
2005 needed for sampler engines which need more audio
2006 channels than the used audio system might be able to offer
2007 (always returned by all audio channels)
2008 </p>
2009 </blockquote>
2010
2011
2012 <p>MIX_CHANNEL_DESTINATION -
2013 </p>
2014 <blockquote class="text">
2015 <p>numerical ID (positive integer including 0)
2016 which reflects the real audio channel (of the same audio
2017 output device) this mix channel refers to, means where
2018 the audio signal actually will be routed / added to
2019 (only returned in case the audio channel is mix channel)
2020 </p>
2021 </blockquote>
2022
2023
2024 </blockquote>
2025
2026
2027 </blockquote><p>
2028
2029 </p>
2030 <p>The mentioned fields above don't have to be in particular
2031 order. The fields above are only those fields which are
2032 generally returned for the described cases by all audio
2033 channels regardless of the audio driver. Every audio channel
2034 might have its own, additional driver and channel specific
2035 parameters.
2036 </p>
2037 <p>Examples:
2038 </p>
2039 <p>
2040 </p>
2041 <blockquote class="text">
2042 <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 0"
2043 </p>
2044 <p>S: "NAME: studio monitor left"
2045 </p>
2046 <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
2047 </p>
2048 <p>&nbsp;&nbsp;&nbsp;"."
2049 </p>
2050 </blockquote><p>
2051
2052 </p>
2053 <p>
2054 </p>
2055 <blockquote class="text">
2056 <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 1"
2057 </p>
2058 <p>S: "NAME: studio monitor right"
2059 </p>
2060 <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
2061 </p>
2062 <p>&nbsp;&nbsp;&nbsp;"."
2063 </p>
2064 </blockquote><p>
2065
2066 </p>
2067 <p>
2068 </p>
2069 <blockquote class="text">
2070 <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"
2071 </p>
2072 <p>S: "NAME: studio monitor left"
2073 </p>
2074 <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: true"
2075 </p>
2076 <p>&nbsp;&nbsp;&nbsp;"MIX_CHANNEL_DESTINATION: 1"
2077 </p>
2078 <p>&nbsp;&nbsp;&nbsp;"."
2079 </p>
2080 </blockquote><p>
2081
2082 </p>
2083 <p>
2084 </p>
2085 <blockquote class="text">
2086 <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"
2087 </p>
2088 <p>S: "NAME: 'ardour (left)'"
2089 </p>
2090 <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
2091 </p>
2092 <p>&nbsp;&nbsp;&nbsp;"JACK_BINDINGS: 'ardour:0'"
2093 </p>
2094 <p>&nbsp;&nbsp;&nbsp;"."
2095 </p>
2096 </blockquote><p>
2097
2098 </p>
2099 <a name="GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO"></a><br /><hr />
2100 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2101 <a name="rfc.section.6.2.12"></a><h3>6.2.12.&nbsp;
2102 Getting information about specific audio channel parameter</h3>
2103
2104 <p>Use the following command to get detailed information about specific audio channel parameter:
2105 </p>
2106 <p>
2107 </p>
2108 <blockquote class="text">
2109 <p>GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO &lt;dev-id&gt; &lt;chan&gt; &lt;param&gt;
2110 </p>
2111 </blockquote><p>
2112
2113 </p>
2114 <p>Where &lt;dev-id&gt; is the numerical ID of the audio output device as returned by the
2115 <a class='info' href='#CREATE AUDIO_OUTPUT_DEVICE'>"CREATE AUDIO_OUTPUT_DEVICE"<span> (</span><span class='info'>Creating an audio output device</span><span>)</span></a>
2116 or <a class='info' href='#LIST AUDIO_OUTPUT_DEVICES'>"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class='info'>Getting all created audio output device list</span><span>)</span></a>
2117 command, &lt;chan&gt; the audio channel number
2118 and &lt;param&gt; a specific channel parameter name for which information should
2119 be obtained (as returned by the <a class='info' href='#GET AUDIO_OUTPUT_CHANNEL INFO'>"GET AUDIO_OUTPUT_CHANNEL INFO"<span> (</span><span class='info'>Getting information about an audio channel</span><span>)</span></a> command).
2120 </p>
2121 <p>Possible Answers:
2122 </p>
2123 <p>
2124 </p>
2125 <blockquote class="text">
2126 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2127 Each answer line begins with the information category name
2128 followed by a colon and then a space character &lt;SP&gt; and finally
2129 the info character string to that info category. There are
2130 information which is always returned, independently of the
2131 given channel parameter and there is optional information
2132 which is only shown dependently to the given audio channel. At
2133 the moment the following information categories are defined:
2134 </p>
2135 <p>
2136 </p>
2137 <blockquote class="text">
2138 <p>TYPE -
2139 </p>
2140 <blockquote class="text">
2141 <p>either "BOOL" for boolean value(s) or "INT" for integer
2142 value(s) or "FLOAT" for dotted number(s) or "STRING" for
2143 character string(s)
2144 (always returned)
2145 </p>
2146 </blockquote>
2147
2148
2149 <p>DESCRIPTION -
2150 </p>
2151 <blockquote class="text">
2152 <p>arbitrary text describing the purpose of the parameter (always returned)
2153 </p>
2154 </blockquote>
2155
2156
2157 <p>FIX -
2158 </p>
2159 <blockquote class="text">
2160 <p>either true or false, if true then this parameter is
2161 read only, thus cannot be altered
2162 (always returned)
2163 </p>
2164 </blockquote>
2165
2166
2167 <p>MULTIPLICITY -
2168 </p>
2169 <blockquote class="text">
2170 <p>either true or false, defines if this parameter allows
2171 only one value or a list of values, where true means
2172 multiple values and false only a single value allowed
2173 (always returned)
2174 </p>
2175 </blockquote>
2176
2177
2178 <p>RANGE_MIN -
2179 </p>
2180 <blockquote class="text">
2181 <p>defines lower limit of the allowed value range for this
2182 parameter, can be an integer value as well as a dotted
2183 number, usually used in conjunction with 'RANGE_MAX',
2184 but may also appear without
2185 (optionally returned, dependent to driver and channel
2186 parameter)
2187 </p>
2188 </blockquote>
2189
2190
2191 <p>RANGE_MAX -
2192 </p>
2193 <blockquote class="text">
2194 <p>defines upper limit of the allowed value range for this
2195 parameter, can be an integer value as well as a dotted
2196 number, usually used in conjunction with 'RANGE_MIN',
2197 but may also appear without
2198 (optionally returned, dependent to driver and channel
2199 parameter)
2200 </p>
2201 </blockquote>
2202
2203
2204 <p>POSSIBILITIES -
2205 </p>
2206 <blockquote class="text">
2207 <p>comma separated list of possible values for this
2208 parameter, character strings are encapsulated into
2209 apostrophes
2210 (optionally returned, dependent to driver and channel
2211 parameter)
2212 </p>
2213 </blockquote>
2214
2215
2216 </blockquote>
2217
2218
2219 <p>The mentioned fields above don't have to be in particular order.
2220 </p>
2221 </blockquote><p>
2222
2223 </p>
2224 <p>Example:
2225 </p>
2226 <p>
2227 </p>
2228 <blockquote class="text">
2229 <p>C: "GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO 1 0 JACK_BINDINGS"
2230 </p>
2231 <p>S: "DESCRIPTION: bindings to other JACK clients"
2232 </p>
2233 <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
2234 </p>
2235 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
2236 </p>
2237 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"
2238 </p>
2239 <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"
2240 </p>
2241 <p>&nbsp;&nbsp;&nbsp;"."
2242 </p>
2243 </blockquote><p>
2244
2245 </p>
2246 <a name="SET AUDIO_OUTPUT_CHANNEL_PARAMETER"></a><br /><hr />
2247 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2248 <a name="rfc.section.6.2.13"></a><h3>6.2.13.&nbsp;
2249 Changing settings of audio output channels</h3>
2250
2251 <p>Use the following command to alter a specific setting of an audio output channel:
2252 </p>
2253 <p>
2254 </p>
2255 <blockquote class="text">
2256 <p>SET AUDIO_OUTPUT_CHANNEL_PARAMETER &lt;dev-id&gt; &lt;chn&gt; &lt;key&gt;=&lt;value&gt;
2257 </p>
2258 </blockquote><p>
2259
2260 </p>
2261 <p>Where &lt;dev-id&gt; should be replaced by the numerical ID of the audio output device as returned by the
2262 <a class='info' href='#CREATE AUDIO_OUTPUT_DEVICE'>"CREATE AUDIO_OUTPUT_DEVICE"<span> (</span><span class='info'>Creating an audio output device</span><span>)</span></a>
2263 or <a class='info' href='#LIST AUDIO_OUTPUT_DEVICES'>"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class='info'>Getting all created audio output device list</span><span>)</span></a>
2264 command, &lt;chn&gt; by the audio channel number, &lt;key&gt; by the name of the
2265 parameter to change and &lt;value&gt; by the new value for this parameter.
2266 </p>
2267 <p>Possible Answers:
2268 </p>
2269 <p>
2270 </p>
2271 <blockquote class="text">
2272 <p>"OK" -
2273 </p>
2274 <blockquote class="text">
2275 <p>in case setting was successfully changed
2276 </p>
2277 </blockquote>
2278
2279
2280 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2281 </p>
2282 <blockquote class="text">
2283 <p>in case setting was changed successfully, but there are
2284 noteworthy issue(s) related, providing an appropriate
2285 warning code and warning message
2286 </p>
2287 </blockquote>
2288
2289
2290 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2291 </p>
2292 <blockquote class="text">
2293 <p>in case it failed, providing an appropriate error code and
2294 error message
2295 </p>
2296 </blockquote>
2297
2298
2299 </blockquote><p>
2300
2301 </p>
2302 <p>Example:
2303 </p>
2304 <p>
2305 </p>
2306 <blockquote class="text">
2307 <p>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"
2308 </p>
2309 <p>S: "OK"
2310 </p>
2311 </blockquote><p>
2312
2313 </p>
2314 <p>
2315 </p>
2316 <blockquote class="text">
2317 <p>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"
2318 </p>
2319 <p>S: "OK"
2320 </p>
2321 </blockquote><p>
2322
2323 </p>
2324 <a name="anchor10"></a><br /><hr />
2325 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2326 <a name="rfc.section.6.3"></a><h3>6.3.&nbsp;
2327 Configuring MIDI input drivers</h3>
2328
2329 <p>Instances of drivers in LinuxSampler are called devices. You can use
2330 multiple MIDI devices simultaneously, e.g. to use MIDI over ethernet as
2331 MIDI input on one sampler channel and ALSA as MIDI input on another sampler
2332 channel. For particular MIDI input systems it's also possible to create
2333 several devices of the same MIDI input type. This chapter describes all
2334 commands to configure LinuxSampler's MIDI input devices and their parameters.
2335 </p>
2336 <p>Instead of defining commands and parameters for each driver individually,
2337 all possible parameters, their meanings and possible values have to be obtained
2338 at runtime. This makes the protocol a bit abstract, but has the advantage, that
2339 front-ends can be written independently of what drivers are currently implemented
2340 and what parameters these drivers are actually offering. This means front-ends can
2341 even handle drivers which are implemented somewhere in future without modifying
2342 the front-end at all.
2343 </p>
2344 <p>Commands for configuring MIDI input devices are pretty much the same as the
2345 commands for configuring audio output drivers, already described in the last
2346 chapter.
2347 </p>
2348 <p>Note: examples in this chapter showing particular parameters of drivers are
2349 not meant as specification of the drivers' parameters. Driver implementations in
2350 LinuxSampler might have complete different parameter names and meanings than shown
2351 in these examples or might change in future, so these examples are only meant for
2352 showing how to retrieve what parameters drivers are offering, how to retrieve their
2353 possible values, etc.
2354 </p>
2355 <a name="GET AVAILABLE_MIDI_INPUT_DRIVERS"></a><br /><hr />
2356 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2357 <a name="rfc.section.6.3.1"></a><h3>6.3.1.&nbsp;
2358 Getting amount of available MIDI input drivers</h3>
2359
2360 <p>Use the following command to get the number of
2361 MIDI input drivers currently available for the
2362 LinuxSampler instance:
2363 </p>
2364 <p>
2365 </p>
2366 <blockquote class="text">
2367 <p>GET AVAILABLE_MIDI_INPUT_DRIVERS
2368 </p>
2369 </blockquote><p>
2370
2371 </p>
2372 <p>Possible Answers:
2373 </p>
2374 <p>
2375 </p>
2376 <blockquote class="text">
2377 <p>LinuxSampler will answer by sending the
2378 number of available MIDI input drivers.
2379 </p>
2380 </blockquote><p>
2381
2382 </p>
2383 <p>Example:
2384 </p>
2385 <p>
2386 </p>
2387 <blockquote class="text">
2388 <p>C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"
2389 </p>
2390 <p>S: "2"
2391 </p>
2392 </blockquote><p>
2393
2394 </p>
2395 <a name="LIST AVAILABLE_MIDI_INPUT_DRIVERS"></a><br /><hr />
2396 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2397 <a name="rfc.section.6.3.2"></a><h3>6.3.2.&nbsp;
2398 Getting all available MIDI input drivers</h3>
2399
2400 <p>Use the following command to list all MIDI input drivers currently available
2401 for the LinuxSampler instance:
2402 </p>
2403 <p>
2404 </p>
2405 <blockquote class="text">
2406 <p>LIST AVAILABLE_MIDI_INPUT_DRIVERS
2407 </p>
2408 </blockquote><p>
2409
2410 </p>
2411 <p>Possible Answers:
2412 </p>
2413 <p>
2414 </p>
2415 <blockquote class="text">
2416 <p>LinuxSampler will answer by sending comma separated character
2417 strings, each symbolizing a MIDI input driver.
2418 </p>
2419 </blockquote><p>
2420
2421 </p>
2422 <p>Example:
2423 </p>
2424 <p>
2425 </p>
2426 <blockquote class="text">
2427 <p>C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
2428 </p>
2429 <p>S: "ALSA,JACK"
2430 </p>
2431 </blockquote><p>
2432
2433 </p>
2434 <a name="GET MIDI_INPUT_DRIVER INFO"></a><br /><hr />
2435 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2436 <a name="rfc.section.6.3.3"></a><h3>6.3.3.&nbsp;
2437 Getting information about a specific MIDI input driver</h3>
2438
2439 <p>Use the following command to get detailed information about a specific MIDI input driver:
2440 </p>
2441 <p>
2442 </p>
2443 <blockquote class="text">
2444 <p>GET MIDI_INPUT_DRIVER INFO &lt;midi-input-driver&gt;
2445 </p>
2446 </blockquote><p>
2447
2448 </p>
2449 <p>Where &lt;midi-input-driver&gt; is the name of the MIDI input driver as returned
2450 by the <a class='info' href='#LIST AVAILABLE_MIDI_INPUT_DRIVERS'>"LIST AVAILABLE_MIDI_INPUT_DRIVERS"<span> (</span><span class='info'>Getting all available MIDI input drivers</span><span>)</span></a> command.
2451 </p>
2452 <p>Possible Answers:
2453 </p>
2454 <p>
2455 </p>
2456 <blockquote class="text">
2457 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2458 Each answer line begins with the information category name
2459 followed by a colon and then a space character &lt;SP&gt; and finally
2460 the info character string to that info category. At the moment
2461 the following information categories are defined:
2462 </p>
2463 <p>
2464 </p>
2465 <blockquote class="text">
2466 <p>DESCRIPTION -
2467 </p>
2468 <blockquote class="text">
2469 <p>arbitrary description text about the MIDI input driver
2470 </p>
2471 </blockquote>
2472
2473
2474 <p>VERSION -
2475 </p>
2476 <blockquote class="text">
2477 <p>arbitrary character string regarding the driver's version
2478 </p>
2479 </blockquote>
2480
2481
2482 <p>PARAMETERS -
2483 </p>
2484 <blockquote class="text">
2485 <p>comma separated list of all parameters available for the given MIDI input driver
2486 </p>
2487 </blockquote>
2488
2489
2490 </blockquote>
2491
2492
2493 <p>The mentioned fields above don't have to be in particular order.
2494 </p>
2495 </blockquote><p>
2496
2497 </p>
2498 <p>Example:
2499 </p>
2500 <p>
2501 </p>
2502 <blockquote class="text">
2503 <p>C: "GET MIDI_INPUT_DRIVER INFO ALSA"
2504 </p>
2505 <p>S: "DESCRIPTION: Advanced Linux Sound Architecture"
2506 </p>
2507 <p>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"
2508 </p>
2509 <p>&nbsp;&nbsp;&nbsp;"PARAMETERS: DRIVER,ACTIVE"
2510 </p>
2511 <p>&nbsp;&nbsp;&nbsp;"."
2512 </p>
2513 </blockquote><p>
2514
2515 </p>
2516 <a name="GET MIDI_INPUT_DRIVER_PARAMETER INFO"></a><br /><hr />
2517 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2518 <a name="rfc.section.6.3.4"></a><h3>6.3.4.&nbsp;
2519 Getting information about specific MIDI input driver parameter</h3>
2520
2521 <p>Use the following command to get detailed information about a specific parameter of a specific MIDI input driver:
2522 </p>
2523 <p>
2524 </p>
2525 <blockquote class="text">
2526 <p>GET MIDI_INPUT_DRIVER_PARAMETER INFO &lt;midit&gt; &lt;param&gt; [&lt;deplist&gt;]
2527 </p>
2528 </blockquote><p>
2529
2530 </p>
2531 <p>Where &lt;midit&gt; is the name of the MIDI input driver as returned
2532 by the <a class='info' href='#LIST AVAILABLE_MIDI_INPUT_DRIVERS'>"LIST AVAILABLE_MIDI_INPUT_DRIVERS"<span> (</span><span class='info'>Getting all available MIDI input drivers</span><span>)</span></a> command, &lt;param&gt; a specific
2533 parameter name for which information should be obtained (as returned by the
2534 <a class='info' href='#GET MIDI_INPUT_DRIVER INFO'>"GET MIDI_INPUT_DRIVER INFO"<span> (</span><span class='info'>Getting information about a specific MIDI input driver</span><span>)</span></a> command) and &lt;deplist&gt; is an optional list
2535 of parameters on which the sought parameter &lt;param&gt; depends on,
2536 &lt;deplist&gt; is a key-value pair list in form of "key1=val1 key2=val2 ...",
2537 where character string values are encapsulated into apostrophes ('). Arguments
2538 given with &lt;deplist&gt; which are not dependency parameters of &lt;param&gt;
2539 will be ignored, means the front-end application can simply put all parameters
2540 in &lt;deplist&gt; with the values selected by the user.
2541 </p>
2542 <p>Possible Answers:
2543 </p>
2544 <p>LinuxSampler will answer by sending a &lt;CRLF> separated list.
2545 Each answer line begins with the information category name
2546 followed by a colon and then a space character &lt;SP> and finally
2547 the info character string to that info category. There is
2548 information which is always returned, independent of the
2549 given driver parameter and there is optional information
2550 which is only shown dependent to given driver parameter. At
2551 the moment the following information categories are defined:
2552 </p>
2553 <p>
2554 </p>
2555 <blockquote class="text">
2556 <p>TYPE -
2557 </p>
2558 <blockquote class="text">
2559 <p>either "BOOL" for boolean value(s) or "INT" for integer
2560 value(s) or "FLOAT" for dotted number(s) or "STRING" for
2561 character string(s)
2562 (always returned, no matter which driver parameter)
2563 </p>
2564 </blockquote>
2565
2566
2567 <p>DESCRIPTION -
2568 </p>
2569 <blockquote class="text">
2570 <p>arbitrary text describing the purpose of the parameter
2571 (always returned, no matter which driver parameter)
2572 </p>
2573 </blockquote>
2574
2575
2576 <p>MANDATORY -
2577 </p>
2578 <blockquote class="text">
2579 <p>either true or false, defines if this parameter must be
2580 given when the device is to be created with the
2581 <a class='info' href='#CREATE MIDI_INPUT_DEVICE'>'CREATE MIDI_INPUT_DEVICE'<span> (</span><span class='info'>Creating a MIDI input device</span><span>)</span></a> command
2582 (always returned, no matter which driver parameter)
2583 </p>
2584 </blockquote>
2585
2586
2587 <p>FIX -
2588 </p>
2589 <blockquote class="text">
2590 <p>either true or false, if false then this parameter can
2591 be changed at any time, once the device is created by
2592 the <a class='info' href='#CREATE MIDI_INPUT_DEVICE'>'CREATE MIDI_INPUT_DEVICE'<span> (</span><span class='info'>Creating a MIDI input device</span><span>)</span></a> command
2593 (always returned, no matter which driver parameter)
2594 </p>
2595 </blockquote>
2596
2597
2598 <p>MULTIPLICITY -
2599 </p>
2600 <blockquote class="text">
2601 <p>either true or false, defines if this parameter allows
2602 only one value or a list of values, where true means
2603 multiple values and false only a single value allowed
2604 (always returned, no matter which driver parameter)
2605 </p>
2606 </blockquote>
2607
2608
2609 <p>DEPENDS -
2610 </p>
2611 <blockquote class="text">
2612 <p>comma separated list of parameters this parameter depends
2613 on, means the values for fields 'DEFAULT', 'RANGE_MIN',
2614 'RANGE_MAX' and 'POSSIBILITIES' might depend on these
2615 listed parameters, for example assuming that an audio
2616 driver (like the ALSA driver) offers parameters 'card'
2617 and 'samplerate' then parameter 'samplerate' would
2618 depend on 'card' because the possible values for
2619 'samplerate' depends on the sound card which can be
2620 chosen by the 'card' parameter
2621 (optionally returned, dependent to driver parameter)
2622 </p>
2623 </blockquote>
2624
2625
2626 <p>DEFAULT -
2627 </p>
2628 <blockquote class="text">
2629 <p>reflects the default value for this parameter which is
2630 used when the device is created and not explicitly
2631 given with the <a class='info' href='#CREATE MIDI_INPUT_DEVICE'>'CREATE MIDI_INPUT_DEVICE'<span> (</span><span class='info'>Creating a MIDI input device</span><span>)</span></a> command,
2632 in case of MULTIPLCITY=true, this is a comma separated
2633 list, that's why character strings are encapsulated into
2634 apostrophes (')
2635 (optionally returned, dependent to driver parameter)
2636 </p>
2637 </blockquote>
2638
2639
2640 <p>RANGE_MIN -
2641 </p>
2642 <blockquote class="text">
2643 <p>defines lower limit of the allowed value range for this
2644 parameter, can be an integer value as well as a dotted
2645 number, this parameter is often used in conjunction
2646 with RANGE_MAX, but may also appear without
2647 (optionally returned, dependent to driver parameter)
2648 </p>
2649 </blockquote>
2650
2651
2652 <p>RANGE_MAX -
2653 </p>
2654 <blockquote class="text">
2655 <p>defines upper limit of the allowed value range for this
2656 parameter, can be an integer value as well as a dotted
2657 number, this parameter is often used in conjunction with
2658 RANGE_MIN, but may also appear without
2659 (optionally returned, dependent to driver parameter)
2660 </p>
2661 </blockquote>
2662
2663
2664 <p>POSSIBILITIES -
2665 </p>
2666 <blockquote class="text">
2667 <p>comma separated list of possible values for this
2668 parameter, character strings are encapsulated into
2669 apostrophes
2670 (optionally returned, dependent to driver parameter)
2671 </p>
2672 </blockquote>
2673
2674
2675 </blockquote><p>
2676
2677 </p>
2678 <p>The mentioned fields above don't have to be in particular order.
2679 </p>
2680 <p>Example:
2681 </p>
2682 <p>
2683 </p>
2684 <blockquote class="text">
2685 <p>C: "GET MIDI_INPUT_DRIVER_PARAMETER INFO ALSA ACTIVE"
2686 </p>
2687 <p>S: "DESCRIPTION: Whether device is enabled"
2688 </p>
2689 <p>&nbsp;&nbsp;&nbsp;"TYPE: BOOL"
2690 </p>
2691 <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
2692 </p>
2693 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
2694 </p>
2695 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
2696 </p>
2697 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: true"
2698 </p>
2699 <p>&nbsp;&nbsp;&nbsp;"."
2700 </p>
2701 </blockquote><p>
2702
2703 </p>
2704 <a name="CREATE MIDI_INPUT_DEVICE"></a><br /><hr />
2705 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2706 <a name="rfc.section.6.3.5"></a><h3>6.3.5.&nbsp;
2707 Creating a MIDI input device</h3>
2708
2709 <p>Use the following command to create a new MIDI input device for the desired MIDI input system:
2710 </p>
2711 <p>
2712 </p>
2713 <blockquote class="text">
2714 <p>CREATE MIDI_INPUT_DEVICE &lt;midi-input-driver&gt; [&lt;param-list&gt;]
2715 </p>
2716 </blockquote><p>
2717
2718 </p>
2719 <p>Where &lt;midi-input-driver&gt; should be replaced by the desired MIDI input system as returned
2720 by the <a class='info' href='#LIST AVAILABLE_MIDI_INPUT_DRIVERS'>"LIST AVAILABLE_MIDI_INPUT_DRIVERS"<span> (</span><span class='info'>Getting all available MIDI input drivers</span><span>)</span></a> command and &lt;param-list&gt; by an
2721 optional list of driver specific parameters in form of "key1=val1 key2=val2 ...", where
2722 character string values should be encapsulated into apostrophes (').
2723 Note that there might be drivers which require parameter(s) to be
2724 given with this command. Use the previously described commands in
2725 this chapter to get that information.
2726 </p>
2727 <p>Possible Answers:
2728 </p>
2729 <p>
2730 </p>
2731 <blockquote class="text">
2732 <p>"OK[&lt;device-id&gt;]" -
2733 </p>
2734 <blockquote class="text">
2735 <p>in case the device was successfully created, where
2736 &lt;device-id&gt; is the numerical ID of the new device
2737 </p>
2738 </blockquote>
2739
2740
2741 <p>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2742 </p>
2743 <blockquote class="text">
2744 <p>in case the driver was loaded successfully, where
2745 &lt;device-id&gt; is the numerical ID of the new device, but
2746 there are noteworthy issue(s) related, providing an
2747 appropriate warning code and warning message
2748 </p>
2749 </blockquote>
2750
2751
2752 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2753 </p>
2754 <blockquote class="text">
2755 <p>in case it failed, providing an appropriate error code and error message
2756 </p>
2757 </blockquote>
2758
2759
2760 </blockquote><p>
2761
2762 </p>
2763 <p>Example:
2764 </p>
2765 <p>
2766 </p>
2767 <blockquote class="text">
2768 <p>C: "CREATE MIDI_INPUT_DEVICE ALSA"
2769 </p>
2770 <p>S: "OK[0]"
2771 </p>
2772 </blockquote><p>
2773
2774 </p>
2775 <a name="DESTROY MIDI_INPUT_DEVICE"></a><br /><hr />
2776 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2777 <a name="rfc.section.6.3.6"></a><h3>6.3.6.&nbsp;
2778 Destroying a MIDI input device</h3>
2779
2780 <p>Use the following command to destroy a created MIDI input device:
2781 </p>
2782 <p>
2783 </p>
2784 <blockquote class="text">
2785 <p>DESTROY MIDI_INPUT_DEVICE &lt;device-id&gt;
2786 </p>
2787 </blockquote><p>
2788
2789 </p>
2790 <p>Where &lt;device-id&gt; should be replaced by the device's numerical ID as returned by the
2791 <a class='info' href='#CREATE MIDI_INPUT_DEVICE'>"CREATE MIDI_INPUT_DEVICE"<span> (</span><span class='info'>Creating a MIDI input device</span><span>)</span></a>
2792 or <a class='info' href='#LIST MIDI_INPUT_DEVICES'>"LIST MIDI_INPUT_DEVICES"<span> (</span><span class='info'>Getting all created MIDI input device list</span><span>)</span></a>
2793 command.
2794 </p>
2795 <p>Possible Answers:
2796 </p>
2797 <p>
2798 </p>
2799 <blockquote class="text">
2800 <p>"OK" -
2801 </p>
2802 <blockquote class="text">
2803 <p>in case the device was successfully destroyed
2804 </p>
2805 </blockquote>
2806
2807
2808 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2809 </p>
2810 <blockquote class="text">
2811 <p>in case the device was destroyed, but there are noteworthy
2812 issue(s) related, providing an appropriate warning code and
2813 warning message
2814 </p>
2815 </blockquote>
2816
2817
2818 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2819 </p>
2820 <blockquote class="text">
2821 <p>in case it failed, providing an appropriate error code and error message
2822 </p>
2823 </blockquote>
2824
2825
2826 </blockquote><p>
2827
2828 </p>
2829 <p>Example:
2830 </p>
2831 <p>
2832 </p>
2833 <blockquote class="text">
2834 <p>C: "DESTROY MIDI_INPUT_DEVICE 0"
2835 </p>
2836 <p>S: "OK"
2837 </p>
2838 </blockquote><p>
2839
2840 </p>
2841 <a name="GET MIDI_INPUT_DEVICES"></a><br /><hr />
2842 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2843 <a name="rfc.section.6.3.7"></a><h3>6.3.7.&nbsp;
2844 Getting all created MIDI input device count</h3>
2845
2846 <p>Use the following command to count all created MIDI input devices:
2847 </p>
2848 <p>
2849 </p>
2850 <blockquote class="text">
2851 <p>GET MIDI_INPUT_DEVICES
2852 </p>
2853 </blockquote><p>
2854
2855 </p>
2856 <p>Possible Answers:
2857 </p>
2858 <p>
2859 </p>
2860 <blockquote class="text">
2861 <p>LinuxSampler will answer by sending the current number of all
2862 MIDI input devices.
2863 </p>
2864 </blockquote><p>
2865
2866 </p>
2867 <p>Example:
2868 </p>
2869 <p>
2870 </p>
2871 <blockquote class="text">
2872 <p>C: "GET MIDI_INPUT_DEVICES"
2873 </p>
2874 <p>S: "3"
2875 </p>
2876 </blockquote><p>
2877
2878 </p>
2879 <a name="LIST MIDI_INPUT_DEVICES"></a><br /><hr />
2880 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2881 <a name="rfc.section.6.3.8"></a><h3>6.3.8.&nbsp;
2882 Getting all created MIDI input device list</h3>
2883
2884 <p>Use the following command to list all created MIDI input devices:
2885 </p>
2886 <p>
2887 </p>
2888 <blockquote class="text">
2889 <p>LIST MIDI_INPUT_DEVICES
2890 </p>
2891 </blockquote><p>
2892
2893 </p>
2894 <p>Possible Answers:
2895 </p>
2896 <p>
2897 </p>
2898 <blockquote class="text">
2899 <p>LinuxSampler will answer by sending a comma separated list
2900 with the numerical Ids of all created MIDI input devices.
2901 </p>
2902 </blockquote><p>
2903
2904 </p>
2905 <p>Examples:
2906 </p>
2907 <p>
2908 </p>
2909 <blockquote class="text">
2910 <p>C: "LIST MIDI_INPUT_DEVICES"
2911 </p>
2912 <p>S: "0,1,2"
2913 </p>
2914 </blockquote><p>
2915
2916 </p>
2917 <p>
2918 </p>
2919 <blockquote class="text">
2920 <p>C: "LIST MIDI_INPUT_DEVICES"
2921 </p>
2922 <p>S: "1,3"
2923 </p>
2924 </blockquote><p>
2925
2926 </p>
2927 <a name="GET MIDI_INPUT_DEVICE INFO"></a><br /><hr />
2928 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2929 <a name="rfc.section.6.3.9"></a><h3>6.3.9.&nbsp;
2930 Getting current settings of a MIDI input device</h3>
2931
2932 <p>Use the following command to get current settings of a specific, created MIDI input device:
2933 </p>
2934 <p>
2935 </p>
2936 <blockquote class="text">
2937 <p>GET MIDI_INPUT_DEVICE INFO &lt;device-id&gt;
2938 </p>
2939 </blockquote><p>
2940
2941 </p>
2942 <p>Where &lt;device-id&gt; is the numerical ID of the MIDI input device as returned by the
2943 <a class='info' href='#CREATE MIDI_INPUT_DEVICE'>"CREATE MIDI_INPUT_DEVICE"<span> (</span><span class='info'>Creating a MIDI input device</span><span>)</span></a>
2944 or <a class='info' href='#LIST MIDI_INPUT_DEVICES'>"LIST MIDI_INPUT_DEVICES"<span> (</span><span class='info'>Getting all created MIDI input device list</span><span>)</span></a>
2945 command.
2946 </p>
2947 <p>Possible Answers:
2948 </p>
2949 <p>
2950 </p>
2951 <blockquote class="text">
2952 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2953 Each answer line begins with the information category name
2954 followed by a colon and then a space character &lt;SP&gt; and finally
2955 the info character string to that info category. As some
2956 parameters might allow multiple values, character strings are
2957 encapsulated into apostrophes ('). At the moment the following
2958 information categories are defined (independent of driver):
2959 </p>
2960 <p>
2961 </p>
2962 <blockquote class="text">
2963 <p>DRIVER -
2964 </p>
2965 <blockquote class="text">
2966 <p>identifier of the used MIDI input driver, as e.g.
2967 returned by the <a class='info' href='#LIST AVAILABLE_MIDI_INPUT_DRIVERS'>"LIST AVAILABLE_MIDI_INPUT_DRIVERS"<span> (</span><span class='info'>Getting all available MIDI input drivers</span><span>)</span></a>
2968 command
2969 </p>
2970 </blockquote>
2971
2972
2973 </blockquote>
2974
2975 <blockquote class="text">
2976 <p>ACTIVE -
2977 </p>
2978 <blockquote class="text">
2979 <p>either true or false, if false then the MIDI device is
2980 inactive and doesn't listen to any incoming MIDI events
2981 and thus doesn't forward them to connected sampler
2982 channels
2983 </p>
2984 </blockquote>
2985
2986
2987 </blockquote>
2988
2989
2990 </blockquote><p>
2991
2992 </p>
2993 <p>The mentioned fields above don't have to be in particular
2994 order. The fields above are only those fields which are
2995 returned by all MIDI input devices. Every MIDI input driver
2996 might have its own, additional driver specific parameters (see
2997 <a class='info' href='#GET MIDI_INPUT_DRIVER INFO'>"GET MIDI_INPUT_DRIVER INFO"<span> (</span><span class='info'>Getting information about a specific MIDI input driver</span><span>)</span></a> command) which are also returned
2998 by this command.
2999 </p>
3000 <p>Example:
3001 </p>
3002 <p>
3003 </p>
3004 <blockquote class="text">
3005 <p>C: "GET MIDI_INPUT_DEVICE INFO 0"
3006 </p>
3007 <p>S: "DRIVER: ALSA"
3008 </p>
3009 <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
3010 </p>
3011 <p>&nbsp;&nbsp;&nbsp;"."
3012 </p>
3013 </blockquote><p>
3014
3015 </p>
3016 <a name="SET MIDI_INPUT_DEVICE_PARAMETER"></a><br /><hr />
3017 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3018 <a name="rfc.section.6.3.10"></a><h3>6.3.10.&nbsp;
3019 Changing settings of MIDI input devices</h3>
3020
3021 <p>Use the following command to alter a specific setting of a created MIDI input device:
3022 </p>
3023 <p>
3024 </p>
3025 <blockquote class="text">
3026 <p>SET MIDI_INPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;
3027 </p>
3028 </blockquote><p>
3029
3030 </p>
3031 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
3032 MIDI input device as returned by the
3033 <a class='info' href='#CREATE MIDI_INPUT_DEVICE'>"CREATE MIDI_INPUT_DEVICE"<span> (</span><span class='info'>Creating a MIDI input device</span><span>)</span></a>
3034 or <a class='info' href='#LIST MIDI_INPUT_DEVICES'>"LIST MIDI_INPUT_DEVICES"<span> (</span><span class='info'>Getting all created MIDI input device list</span><span>)</span></a>
3035 command, &lt;key&gt; by the name of the parameter to change and
3036 &lt;value&gt; by the new value for this parameter.
3037 </p>
3038 <p>Possible Answers:
3039 </p>
3040 <p>
3041 </p>
3042 <blockquote class="text">
3043 <p>"OK" -
3044 </p>
3045 <blockquote class="text">
3046 <p>in case setting was successfully changed
3047 </p>
3048 </blockquote>
3049
3050
3051 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3052 </p>
3053 <blockquote class="text">
3054 <p>in case setting was changed successfully, but there are
3055 noteworthy issue(s) related, providing an appropriate
3056 warning code and warning message
3057 </p>
3058 </blockquote>
3059
3060
3061 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3062 </p>
3063 <blockquote class="text">
3064 <p>in case it failed, providing an appropriate error code and error message
3065 </p>
3066 </blockquote>
3067
3068
3069 </blockquote><p>
3070
3071 </p>
3072 <p>Example:
3073 </p>
3074 <p>
3075 </p>
3076 <blockquote class="text">
3077 <p>C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"
3078 </p>
3079 <p>S: "OK"
3080 </p>
3081 </blockquote><p>
3082
3083 </p>
3084 <a name="GET MIDI_INPUT_PORT INFO"></a><br /><hr />
3085 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3086 <a name="rfc.section.6.3.11"></a><h3>6.3.11.&nbsp;
3087 Getting information about a MIDI port</h3>
3088
3089 <p>Use the following command to get information about a MIDI port:
3090 </p>
3091 <p>
3092 </p>
3093 <blockquote class="text">
3094 <p>GET MIDI_INPUT_PORT INFO &lt;device-id&gt; &lt;midi-port&gt;
3095 </p>
3096 </blockquote><p>
3097
3098 </p>
3099 <p>Where &lt;device-id&gt; is the numerical ID of the MIDI input device as returned by the
3100 <a class='info' href='#CREATE MIDI_INPUT_DEVICE'>"CREATE MIDI_INPUT_DEVICE"<span> (</span><span class='info'>Creating a MIDI input device</span><span>)</span></a>
3101 or <a class='info' href='#LIST MIDI_INPUT_DEVICES'>"LIST MIDI_INPUT_DEVICES"<span> (</span><span class='info'>Getting all created MIDI input device list</span><span>)</span></a>
3102 command and &lt;midi-port&gt; the MIDI input port number.
3103 </p>
3104 <p>Possible Answers:
3105 </p>
3106 <p>
3107 </p>
3108 <blockquote class="text">
3109 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3110 Each answer line begins with the information category name
3111 followed by a colon and then a space character &lt;SP&gt; and finally
3112 the info character string to that info category. At the moment
3113 the following information categories are defined:
3114 </p>
3115 <p>NAME -
3116 </p>
3117 <blockquote class="text">
3118 <p>arbitrary character string naming the port
3119 </p>
3120 </blockquote>
3121
3122
3123 </blockquote><p>
3124
3125 </p>
3126 <p>The field above is only the one which is returned by all MIDI
3127 ports regardless of the MIDI driver and port. Every MIDI port
3128 might have its own, additional driver and port specific
3129 parameters.
3130 </p>
3131 <p>Example:
3132 </p>
3133 <p>
3134 </p>
3135 <blockquote class="text">
3136 <p>C: "GET MIDI_INPUT_PORT INFO 0 0"
3137 </p>
3138 <p>S: "NAME: 'Masterkeyboard'"
3139 </p>
3140 <p>&nbsp;&nbsp;&nbsp;"ALSA_SEQ_BINDINGS: '64:0'"
3141 </p>
3142 <p>&nbsp;&nbsp;&nbsp;"."
3143 </p>
3144 </blockquote><p>
3145
3146 </p>
3147 <a name="GET MIDI_INPUT_PORT_PARAMETER INFO"></a><br /><hr />
3148 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3149 <a name="rfc.section.6.3.12"></a><h3>6.3.12.&nbsp;
3150 Getting information about specific MIDI port parameter</h3>
3151
3152 <p>Use the following command to get detailed information about specific MIDI port parameter:
3153 </p>
3154 <p>
3155 </p>
3156 <blockquote class="text">
3157 <p>GET MIDI_INPUT_PORT_PARAMETER INFO &lt;dev-id&gt; &lt;port&gt; &lt;param&gt;
3158 </p>
3159 </blockquote><p>
3160
3161 </p>
3162 <p>Where &lt;dev-id&gt; is the numerical ID of the MIDI input device as returned by the
3163 <a class='info' href='#CREATE MIDI_INPUT_DEVICE'>"CREATE MIDI_INPUT_DEVICE"<span> (</span><span class='info'>Creating a MIDI input device</span><span>)</span></a>
3164 or <a class='info' href='#LIST MIDI_INPUT_DEVICES'>"LIST MIDI_INPUT_DEVICES"<span> (</span><span class='info'>Getting all created MIDI input device list</span><span>)</span></a>
3165 command, &lt;port&gt; the MIDI port number and
3166 &lt;param&gt; a specific port parameter name for which information should be
3167 obtained (as returned by the <a class='info' href='#GET MIDI_INPUT_PORT INFO'>"GET MIDI_INPUT_PORT INFO"<span> (</span><span class='info'>Getting information about a MIDI port</span><span>)</span></a> command).
3168 </p>
3169 <p>Possible Answers:
3170 </p>
3171 <p>
3172 </p>
3173 <blockquote class="text">
3174 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3175 Each answer line begins with the information category name
3176 followed by a colon and then a space character &lt;SP&gt; and finally
3177 the info character string to that info category. There is
3178 information which is always returned, independently of the
3179 given channel parameter and there is optional information
3180 which are only shown dependently to the given MIDI port. At the
3181 moment the following information categories are defined:
3182 </p>
3183 <p>TYPE -
3184 </p>
3185 <blockquote class="text">
3186 <p>either "BOOL" for boolean value(s) or "INT" for integer
3187 value(s) or "FLOAT" for dotted number(s) or "STRING" for
3188 character string(s)
3189 (always returned)
3190 </p>
3191 </blockquote>
3192
3193
3194 <p>DESCRIPTION -
3195 </p>
3196 <blockquote class="text">
3197 <p>arbitrary text describing the purpose of the parameter
3198 (always returned)
3199 </p>
3200 </blockquote>
3201
3202
3203 <p>FIX -
3204 </p>
3205 <blockquote class="text">
3206 <p>either true or false, if true then this parameter is
3207 read only, thus cannot be altered
3208 (always returned)
3209 </p>
3210 </blockquote>
3211
3212
3213 <p>MULTIPLICITY -
3214 </p>
3215 <blockquote class="text">
3216 <p>either true or false, defines if this parameter allows
3217 only one value or a list of values, where true means
3218 multiple values and false only a single value allowed
3219 (always returned)
3220 </p>
3221 </blockquote>
3222
3223
3224 <p>RANGE_MIN -
3225 </p>
3226 <blockquote class="text">
3227 <p>defines lower limit of the allowed value range for this
3228 parameter, can be an integer value as well as a dotted
3229 number, this parameter is usually used in conjunction
3230 with 'RANGE_MAX' but may also appear without
3231 (optionally returned, dependent to driver and port
3232 parameter)
3233 </p>
3234 </blockquote>
3235
3236
3237 <p>RANGE_MAX -
3238 </p>
3239 <blockquote class="text">
3240 <p>defines upper limit of the allowed value range for this
3241 parameter, can be an integer value as well as a dotted
3242 number, this parameter is usually used in conjunction
3243 with 'RANGE_MIN' but may also appear without
3244 (optionally returned, dependent to driver and port
3245 parameter)
3246 </p>
3247 </blockquote>
3248
3249
3250 <p>POSSIBILITIES -
3251 </p>
3252 <blockquote class="text">
3253 <p>comma separated list of possible values for this
3254 parameter, character strings are encapsulated into
3255 apostrophes
3256 (optionally returned, dependent to device and port
3257 parameter)
3258 </p>
3259 </blockquote>
3260
3261
3262 </blockquote><p>
3263
3264 </p>
3265 <p>The mentioned fields above don't have to be in particular order.
3266 </p>
3267 <p>Example:
3268 </p>
3269 <p>
3270 </p>
3271 <blockquote class="text">
3272 <p>C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"
3273 </p>
3274 <p>S: "DESCRIPTION: bindings to other ALSA sequencer clients"
3275 </p>
3276 <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
3277 </p>
3278 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
3279 </p>
3280 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"
3281 </p>
3282 <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: '64:0','68:0','68:1'"
3283 </p>
3284 <p>&nbsp;&nbsp;&nbsp;"."
3285 </p>
3286 </blockquote><p>
3287
3288 </p>
3289 <a name="SET MIDI_INPUT_PORT_PARAMETER"></a><br /><hr />
3290 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3291 <a name="rfc.section.6.3.13"></a><h3>6.3.13.&nbsp;
3292 Changing settings of MIDI input ports</h3>
3293
3294 <p>Use the following command to alter a specific setting of a MIDI input port:
3295 </p>
3296 <p>
3297 </p>
3298 <blockquote class="text">
3299 <p>SET MIDI_INPUT_PORT_PARAMETER &lt;device-id&gt; &lt;port&gt; &lt;key&gt;=&lt;value&gt;
3300 </p>
3301 </blockquote><p>
3302
3303 </p>
3304 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
3305 MIDI device as returned by the
3306 <a class='info' href='#CREATE MIDI_INPUT_DEVICE'>"CREATE MIDI_INPUT_DEVICE"<span> (</span><span class='info'>Creating a MIDI input device</span><span>)</span></a>
3307 or <a class='info' href='#LIST MIDI_INPUT_DEVICES'>"LIST MIDI_INPUT_DEVICES"<span> (</span><span class='info'>Getting all created MIDI input device list</span><span>)</span></a>
3308 command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of
3309 the parameter to change and &lt;value&gt; by the new value for this
3310 parameter (encapsulated into apostrophes) or NONE (not encapsulated into apostrophes)
3311 for specifying no value for parameters allowing a list of values.
3312 </p>
3313 <p>Possible Answers:
3314 </p>
3315 <p>
3316 </p>
3317 <blockquote class="text">
3318 <p>"OK" -
3319 </p>
3320 <blockquote class="text">
3321 <p>in case setting was successfully changed
3322 </p>
3323 </blockquote>
3324
3325
3326 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3327 </p>
3328 <blockquote class="text">
3329 <p>in case setting was changed successfully, but there are
3330 noteworthy issue(s) related, providing an appropriate
3331 warning code and warning message
3332 </p>
3333 </blockquote>
3334
3335
3336 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3337 </p>
3338 <blockquote class="text">
3339 <p>in case it failed, providing an appropriate error code and error message
3340 </p>
3341 </blockquote>
3342
3343
3344 </blockquote><p>
3345
3346 </p>
3347 <p>Example:
3348 </p>
3349 <p>
3350 </p>
3351 <blockquote class="text">
3352 <p>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='20:0'"
3353 </p>
3354 <p>S: "OK"
3355 </p>
3356 </blockquote><p>
3357
3358 </p>
3359 <p>
3360 </p>
3361 <blockquote class="text">
3362 <p>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE"
3363 </p>
3364 <p>S: "OK"
3365 </p>
3366 </blockquote><p>
3367
3368 </p>
3369 <a name="anchor11"></a><br /><hr />
3370 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3371 <a name="rfc.section.6.4"></a><h3>6.4.&nbsp;
3372 Configuring sampler channels</h3>
3373
3374 <p>The following commands describe how to add and remove sampler channels, associate a
3375 sampler channel with a sampler engine, load instruments and connect sampler channels to
3376 MIDI and audio devices.
3377 </p>
3378 <a name="LOAD INSTRUMENT"></a><br /><hr />
3379 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3380 <a name="rfc.section.6.4.1"></a><h3>6.4.1.&nbsp;
3381 Loading an instrument</h3>
3382
3383 <p>An instrument file can be loaded and assigned to a sampler channel by one of the following commands:
3384 </p>
3385 <p>
3386 </p>
3387 <blockquote class="text">
3388 <p>LOAD INSTRUMENT [NON_MODAL] '&lt;filename&gt;' &lt;instr-index&gt; &lt;sampler-channel&gt;
3389 </p>
3390 </blockquote><p>
3391
3392 </p>
3393 <p>Where &lt;filename&gt; is the name of the instrument file on the
3394 LinuxSampler instance's host system, &lt;instr-index&gt; the index of the
3395 instrument in the instrument file and &lt;sampler-channel> is the
3396 number of the sampler channel the instrument should be assigned to.
3397 Each sampler channel can only have one instrument.
3398 </p>
3399 <p>Notice: since LSCP 1.2 the &lt;filename&gt; argument supports
3400 escape characters for special characters (see chapter
3401 "<a class='info' href='#character_set'>Character Set and Escape Sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>"
3402 for details) and accordingly backslash characters in the filename
3403 MUST now be escaped as well!
3404 </p>
3405 <p>The difference between regular and NON_MODAL versions of the command
3406 is that the regular command returns OK only after the instrument has been
3407 fully loaded and the channel is ready to be used while NON_MODAL version
3408 returns immediately and a background process is launched to load the instrument
3409 on the channel. The <a class='info' href='#GET CHANNEL INFO'>GET CHANNEL INFO<span> (</span><span class='info'>Getting sampler channel information</span><span>)</span></a>
3410 command can be used to obtain loading
3411 progress from INSTRUMENT_STATUS field. LOAD command will perform sanity checks
3412 such as making sure that the file could be read and it is of a proper format
3413 and SHOULD return ERR and SHOULD not launch the background process should any
3414 errors be detected at that point.
3415 </p>
3416 <p>Possible Answers:
3417 </p>
3418 <p>
3419 </p>
3420 <blockquote class="text">
3421 <p>"OK" -
3422 </p>
3423 <blockquote class="text">
3424 <p>in case the instrument was successfully loaded
3425 </p>
3426 </blockquote>
3427
3428
3429 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3430 </p>
3431 <blockquote class="text">
3432 <p>in case the instrument was loaded successfully, but there
3433 are noteworthy issue(s) related (e.g. Engine doesn't support
3434 one or more patch parameters provided by the loaded
3435 instrument file), providing an appropriate warning code and
3436 warning message
3437 </p>
3438 </blockquote>
3439
3440
3441 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3442 </p>
3443 <blockquote class="text">
3444 <p>in case it failed, providing an appropriate error code and error message
3445 </p>
3446 </blockquote>
3447
3448
3449 </blockquote><p>
3450
3451 </p>
3452 <p>Example:
3453 </p>
3454 <p>
3455 </p>
3456 <blockquote class="text">
3457 <p>
3458 </p>
3459 </blockquote><p>
3460
3461 </p>
3462 <a name="LOAD ENGINE"></a><br /><hr />
3463 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3464 <a name="rfc.section.6.4.2"></a><h3>6.4.2.&nbsp;
3465 Loading a sampler engine</h3>
3466
3467 <p>A sampler engine type can be associated to a specific sampler
3468 channel by the following command:
3469 </p>
3470 <p>
3471 </p>
3472 <blockquote class="text">
3473 <p>LOAD ENGINE &lt;engine-name&gt; &lt;sampler-channel&gt;
3474 </p>
3475 </blockquote><p>
3476
3477 </p>
3478 <p>Where &lt;engine-name&gt; is an engine name as obtained by the
3479 <a class='info' href='#LIST AVAILABLE_ENGINES'>"LIST AVAILABLE_ENGINES"<span> (</span><span class='info'>Getting all available engines</span><span>)</span></a> command and &lt;sampler-channel&gt;
3480 the sampler channel as returned by the
3481 <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a> or
3482 <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command where
3483 the engine type should be assigned to. This command should be issued
3484 after adding a new sampler channel and before any other control
3485 commands on the new sampler channel. It can also be used to change
3486 the engine type of a sampler channel. This command has (currently) no
3487 way to define or force if a new engine instance should be created and
3488 assigned to the given sampler channel or if an already existing
3489 instance of that engine type, shared with other sampler channels,
3490 should be used.
3491 </p>
3492 <p>Possible Answers:
3493 </p>
3494 <p>
3495 </p>
3496 <blockquote class="text">
3497 <p>"OK" -
3498 </p>
3499 <blockquote class="text">
3500 <p>in case the engine was successfully deployed
3501 </p>
3502 </blockquote>
3503
3504
3505 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3506 </p>
3507 <blockquote class="text">
3508 <p>in case the engine was deployed successfully, but there
3509 are noteworthy issue(s) related, providing an appropriate
3510 warning code and warning message
3511 </p>
3512 </blockquote>
3513
3514
3515 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3516 </p>
3517 <blockquote class="text">
3518 <p>in case it failed, providing an appropriate error code and
3519 error message
3520 </p>
3521 </blockquote>
3522
3523
3524 </blockquote><p>
3525
3526 </p>
3527 <p>Example:
3528 </p>
3529 <p>
3530 </p>
3531 <blockquote class="text">
3532 <p>
3533 </p>
3534 </blockquote><p>
3535
3536 </p>
3537 <a name="GET CHANNELS"></a><br /><hr />
3538 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3539 <a name="rfc.section.6.4.3"></a><h3>6.4.3.&nbsp;
3540 Getting all created sampler channel count</h3>
3541
3542 <p>The number of sampler channels can change on runtime. To get the
3543 current amount of sampler channels, the front-end can send the
3544 following command:
3545 </p>
3546 <p>
3547 </p>
3548 <blockquote class="text">
3549 <p>GET CHANNELS
3550 </p>
3551 </blockquote><p>
3552
3553 </p>
3554 <p>Possible Answers:
3555 </p>
3556 <p>
3557 </p>
3558 <blockquote class="text">
3559 <p>LinuxSampler will answer by returning the current number of sampler channels.
3560 </p>
3561 </blockquote><p>
3562
3563 </p>
3564 <p>Example:
3565 </p>
3566 <p>
3567 </p>
3568 <blockquote class="text">
3569 <p>C: "GET CHANNELS"
3570 </p>
3571 <p>S: "12"
3572 </p>
3573 </blockquote><p>
3574
3575 </p>
3576 <a name="LIST CHANNELS"></a><br /><hr />
3577 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3578 <a name="rfc.section.6.4.4"></a><h3>6.4.4.&nbsp;
3579 Getting all created sampler channel list</h3>
3580
3581 <p>The number of sampler channels can change on runtime. To get the
3582 current list of sampler channels, the front-end can send the
3583 following command:
3584 </p>
3585 <p>
3586 </p>
3587 <blockquote class="text">
3588 <p>LIST CHANNELS
3589 </p>
3590 </blockquote><p>
3591
3592 </p>
3593 <p>Possible Answers:
3594 </p>
3595 <p>
3596 </p>
3597 <blockquote class="text">
3598 <p>LinuxSampler will answer by returning a comma separated list
3599 with all sampler channels numerical IDs.
3600 </p>
3601 </blockquote><p>
3602
3603 </p>
3604 <p>Example:
3605 </p>
3606 <p>
3607 </p>
3608 <blockquote class="text">
3609 <p>C: "LIST CHANNELS"
3610 </p>
3611 <p>S: "0,1,2,3,4,5,6,9,10,11,15,20"
3612 </p>
3613 </blockquote><p>
3614
3615 </p>
3616 <a name="ADD CHANNEL"></a><br /><hr />
3617 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3618 <a name="rfc.section.6.4.5"></a><h3>6.4.5.&nbsp;
3619 Adding a new sampler channel</h3>
3620
3621 <p>A new sampler channel can be added to the end of the sampler
3622 channel list by sending the following command:
3623 </p>
3624 <p>
3625 </p>
3626 <blockquote class="text">
3627 <p>ADD CHANNEL
3628 </p>
3629 </blockquote><p>
3630
3631 </p>
3632 <p>This will increment the sampler channel count by one and the new
3633 sampler channel will be appended to the end of the sampler channel
3634 list. The front-end should send the respective, related commands
3635 right after to e.g. load an engine, load an instrument and setting
3636 input, output method and eventually other commands to initialize
3637 the new channel. The front-end should use the sampler channel
3638 returned by the answer of this command to perform the previously
3639 recommended commands, to avoid race conditions e.g. with other
3640 front-ends that might also have sent an "ADD CHANNEL" command.
3641 </p>
3642 <p>Possible Answers:
3643 </p>
3644 <p>
3645 </p>
3646 <blockquote class="text">
3647 <p>"OK[&lt;sampler-channel&gt;]" -
3648 </p>
3649 <blockquote class="text">
3650 <p>in case a new sampler channel could be added, where
3651 &lt;sampler-channel&gt; reflects the channel number of the new
3652 created sampler channel which should be used to set up
3653 the sampler channel by sending subsequent initialization
3654 commands
3655 </p>
3656 </blockquote>
3657
3658
3659 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3660 </p>
3661 <blockquote class="text">
3662 <p>in case a new channel was added successfully, but there are
3663 noteworthy issue(s) related, providing an appropriate
3664 warning code and warning message
3665 </p>
3666 </blockquote>
3667
3668
3669 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3670 </p>
3671 <blockquote class="text">
3672 <p>in case it failed, providing an appropriate error code and
3673 error message
3674 </p>
3675 </blockquote>
3676
3677
3678 </blockquote><p>
3679
3680 </p>
3681 <p>Example:
3682 </p>
3683 <p>
3684 </p>
3685 <blockquote class="text">
3686 <p>
3687 </p>
3688 </blockquote><p>
3689
3690 </p>
3691 <a name="REMOVE CHANNEL"></a><br /><hr />
3692 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3693 <a name="rfc.section.6.4.6"></a><h3>6.4.6.&nbsp;
3694 Removing a sampler channel</h3>
3695
3696 <p>A sampler channel can be removed by sending the following command:
3697 </p>
3698 <p>
3699 </p>
3700 <blockquote class="text">
3701 <p>REMOVE CHANNEL &lt;sampler-channel&gt;
3702 </p>
3703 </blockquote><p>
3704
3705 </p>
3706 <p>Where &lt;sampler-channel&gt; should be replaced by the
3707 number of the sampler channel as given by the
3708 <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
3709 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a>
3710 command. The channel numbers of all subsequent sampler channels
3711 remain the same.
3712 </p>
3713 <p>Possible Answers:
3714 </p>
3715 <p>
3716 </p>
3717 <blockquote class="text">
3718 <p>"OK" -
3719 </p>
3720 <blockquote class="text">
3721 <p>in case the given sampler channel could be removed
3722 </p>
3723 </blockquote>
3724
3725
3726 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3727 </p>
3728 <blockquote class="text">
3729 <p>in case the given channel was removed, but there are
3730 noteworthy issue(s) related, providing an appropriate
3731 warning code and warning message
3732 </p>
3733 </blockquote>
3734
3735
3736 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3737 </p>
3738 <blockquote class="text">
3739 <p>in case it failed, providing an appropriate error code and
3740 error message
3741 </p>
3742 </blockquote>
3743
3744
3745 </blockquote><p>
3746
3747 </p>
3748 <p>Example:
3749 </p>
3750 <p>
3751 </p>
3752 <blockquote class="text">
3753 <p>
3754 </p>
3755 </blockquote><p>
3756
3757 </p>
3758 <a name="GET AVAILABLE_ENGINES"></a><br /><hr />
3759 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3760 <a name="rfc.section.6.4.7"></a><h3>6.4.7.&nbsp;
3761 Getting amount of available engines</h3>
3762
3763 <p>The front-end can ask for the number of available engines by sending the following command:
3764 </p>
3765 <p>
3766 </p>
3767 <blockquote class="text">
3768 <p>GET AVAILABLE_ENGINES
3769 </p>
3770 </blockquote><p>
3771
3772 </p>
3773 <p>Possible Answers:
3774 </p>
3775 <p>
3776 </p>
3777 <blockquote class="text">
3778 <p>LinuxSampler will answer by sending the number of available engines.
3779 </p>
3780 </blockquote><p>
3781
3782 </p>
3783 <p>Example:
3784 </p>
3785 <p>
3786 </p>
3787 <blockquote class="text">
3788 <p>C: "GET AVAILABLE_ENGINES"
3789 </p>
3790 <p>S: "4"
3791 </p>
3792 </blockquote><p>
3793
3794 </p>
3795 <a name="LIST AVAILABLE_ENGINES"></a><br /><hr />
3796 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3797 <a name="rfc.section.6.4.8"></a><h3>6.4.8.&nbsp;
3798 Getting all available engines</h3>
3799
3800 <p>The front-end can ask for a list of all available engines by sending the following command:
3801 </p>
3802 <p>
3803 </p>
3804 <blockquote class="text">
3805 <p>LIST AVAILABLE_ENGINES
3806 </p>
3807 </blockquote><p>
3808
3809 </p>
3810 <p>Possible Answers:
3811 </p>
3812 <p>
3813 </p>
3814 <blockquote class="text">
3815 <p>LinuxSampler will answer by sending a comma separated list
3816 of the engines' names encapsulated into apostrophes (').
3817 Engine names can consist of lower and upper cases,
3818 digits and underlines ("_" character).
3819 </p>
3820 </blockquote><p>
3821
3822 </p>
3823 <p>Example:
3824 </p>
3825 <p>
3826 </p>
3827 <blockquote class="text">
3828 <p>C: "LIST AVAILABLE_ENGINES"
3829 </p>
3830 <p>S: "'GigEngine','AkaiEngine','DLSEngine','JoesCustomEngine'"
3831 </p>
3832 </blockquote><p>
3833
3834 </p>
3835 <a name="GET ENGINE INFO"></a><br /><hr />
3836 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3837 <a name="rfc.section.6.4.9"></a><h3>6.4.9.&nbsp;
3838 Getting information about an engine</h3>
3839
3840 <p>The front-end can ask for information about a specific engine by
3841 sending the following command:
3842 </p>
3843 <p>
3844 </p>
3845 <blockquote class="text">
3846 <p>GET ENGINE INFO &lt;engine-name&gt;
3847 </p>
3848 </blockquote><p>
3849
3850 </p>
3851 <p>Where &lt;engine-name&gt; is an engine name as obtained by the
3852 <a class='info' href='#LIST AVAILABLE_ENGINES'>"LIST AVAILABLE_ENGINES"<span> (</span><span class='info'>Getting all available engines</span><span>)</span></a> command.
3853 </p>
3854 <p>Possible Answers:
3855 </p>
3856 <p>
3857 </p>
3858 <blockquote class="text">
3859 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3860 Each answer line begins with the information category name
3861 followed by a colon and then a space character &lt;SP&gt; and finally
3862 the info character string to that info category. At the moment
3863 the following categories are defined:
3864 </p>
3865 <p>
3866 </p>
3867 <blockquote class="text">
3868 <p>DESCRIPTION -
3869 </p>
3870 <blockquote class="text">
3871 <p>arbitrary description text about the engine
3872 </p>
3873 </blockquote>
3874
3875
3876 <p>VERSION -
3877 </p>
3878 <blockquote class="text">
3879 <p>arbitrary character string regarding the engine's version
3880 </p>
3881 </blockquote>
3882
3883
3884 </blockquote>
3885
3886
3887 </blockquote><p>
3888
3889 </p>
3890 <p>The mentioned fields above don't have to be in particular order.
3891 </p>
3892 <p>Example:
3893 </p>
3894 <p>
3895 </p>
3896 <blockquote class="text">
3897 <p>C: "GET ENGINE INFO JoesCustomEngine"
3898 </p>
3899 <p>S: "DESCRIPTION: this is Joe's custom sampler engine"
3900 </p>
3901 <p>&nbsp;&nbsp;&nbsp;"VERSION: testing-1.0"
3902 </p>
3903 <p>&nbsp;&nbsp;&nbsp;"."
3904 </p>
3905 </blockquote><p>
3906
3907 </p>
3908 <a name="GET CHANNEL INFO"></a><br /><hr />
3909 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3910 <a name="rfc.section.6.4.10"></a><h3>6.4.10.&nbsp;
3911 Getting sampler channel information</h3>
3912
3913 <p>The front-end can ask for the current settings of a sampler channel
3914 by sending the following command:
3915 </p>
3916 <p>
3917 </p>
3918 <blockquote class="text">
3919 <p>GET CHANNEL INFO &lt;sampler-channel&gt;
3920 </p>
3921 </blockquote><p>
3922
3923 </p>
3924 <p>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
3925 as returned by the <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
3926 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command.
3927 </p>
3928 <p>Possible Answers:
3929 </p>
3930 <p>
3931 </p>
3932 <blockquote class="text">
3933 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3934 Each answer line begins with the settings category name
3935 followed by a colon and then a space character &lt;SP&gt; and finally
3936 the info character string to that setting category. At the
3937 moment the following categories are defined:
3938 </p>
3939 <p>
3940 </p>
3941 <blockquote class="text">
3942 <p>ENGINE_NAME -
3943 </p>
3944 <blockquote class="text">
3945 <p>name of the engine that is associated with the sampler
3946 channel, "NONE" if there's no engine associated yet for
3947 this sampler channel
3948 </p>
3949 </blockquote>
3950
3951
3952 <p>AUDIO_OUTPUT_DEVICE -
3953 </p>
3954 <blockquote class="text">
3955 <p>numerical ID of the audio output device which is
3956 currently connected to this sampler channel to output
3957 the audio signal, "NONE" if there's no device
3958 connected to this sampler channel
3959 </p>
3960 </blockquote>
3961
3962
3963 <p>AUDIO_OUTPUT_CHANNELS -
3964 </p>
3965 <blockquote class="text">
3966 <p>number of output channels the sampler channel offers