/[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 1110 - (show annotations) (download) (as text)
Thu Mar 22 21:12:10 2007 UTC (13 years ago) by iliev
File MIME type: text/html
File size: 300878 byte(s)
- Added new notification events for tracking
effect send changes and global volume changes

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