/[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 1048 - (show annotations) (download) (as text)
Mon Feb 19 19:46:20 2007 UTC (17 years, 1 month ago) by schoenebeck
File MIME type: text/html
File size: 295978 byte(s)
- an optional argument "NON_MODAL" has been added to the
  "MAP MIDI_INSTRUMENT" LSCP command, because all
  mapping commands block now by default

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.31 (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.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.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.full th { border-style: solid; }
127 table.headers th { border-style: none none solid none; }
128 table.none th { border-style: none; }
129 table.full td {
130 border-style: solid; border-color: #333;
131 border-width: 1px 2px;
132 }
133 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: August 23, 2007</td><td class="header">February 19, 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 August 23, 2007.</p>
177
178 <h3>Copyright Notice</h3>
179 <p>
180 Copyright &copy; The Internet Society (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 TOTAL_VOICE_COUNT">8.10.</a>&nbsp;
412 Total number of active voices changed<br />
413 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT">8.11.</a>&nbsp;
414 Number of MIDI instrument maps changed<br />
415 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO">8.12.</a>&nbsp;
416 MIDI instrument map information changed<br />
417 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_COUNT">8.13.</a>&nbsp;
418 Number of MIDI instruments changed<br />
419 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_INFO">8.14.</a>&nbsp;
420 MIDI instrument information changed<br />
421 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MISCELLANEOUS">8.15.</a>&nbsp;
422 Miscellaneous and debugging events<br />
423 <a href="#anchor14">9.</a>&nbsp;
424 Security Considerations<br />
425 <a href="#anchor15">10.</a>&nbsp;
426 Acknowledgments<br />
427 <a href="#rfc.references1">11.</a>&nbsp;
428 References<br />
429 <a href="#rfc.authors">&#167;</a>&nbsp;
430 Author's Address<br />
431 <a href="#rfc.copyright">&#167;</a>&nbsp;
432 Intellectual Property and Copyright Statements<br />
433 </p>
434 <br clear="all" />
435
436 <a name="anchor1"></a><br /><hr />
437 <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>
438 <a name="rfc.section.1"></a><h3>1.&nbsp;
439 Requirements notation</h3>
440
441 <p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
442 "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
443 and "OPTIONAL" in this document are to be interpreted as
444 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>.
445 </p>
446 <p>This protocol is always case-sensitive if not explicitly
447 claimed the opposite.
448 </p>
449 <p>In examples, "C:" and "S:" indicate lines sent by the client
450 (front-end) and server (LinuxSampler) respectively. Lines in
451 examples must be interpreted as every line being CRLF
452 terminated (carriage return character followed by line feed
453 character as defined in the ASCII standard), thus the following
454 example:
455 </p>
456 <p>
457 </p>
458 <blockquote class="text">
459 <p>C: "some line"
460 </p>
461 <p>&nbsp;&nbsp;&nbsp;"another line"
462 </p>
463 </blockquote><p>
464
465 </p>
466 <p>must actually be interpreted as client sending the following
467 message:
468 </p>
469 <p>
470 </p>
471 <blockquote class="text">
472 <p>"some line&lt;CR&gt;&lt;LF&gt;another
473 line&lt;CR&gt;&lt;LF&gt;"
474 </p>
475 </blockquote><p>
476
477 </p>
478 <p>where &lt;CR&gt; symbolizes the carriage return character and
479 &lt;LF&gt; the line feed character as defined in the ASCII
480 standard.
481 </p>
482 <p>Due to technical reasons, messages can arbitrary be
483 fragmented, means the following example:
484 </p>
485 <p>
486 </p>
487 <blockquote class="text">
488 <p>S: "abcd"
489 </p>
490 </blockquote><p>
491
492 </p>
493 <p>could also happen to be sent in three messages like in the
494 following sequence scenario:
495 </p>
496 <p>
497 </p>
498 <ul class="text">
499 <li>server sending message "a"
500 </li>
501 <li>followed by a delay (pause) with
502 arbitrary duration
503 </li>
504 <li>followed by server sending message
505 "bcd&lt;CR&gt;"
506 </li>
507 <li>again followed by a delay (pause) with arbitrary
508 duration
509 </li>
510 <li>followed by server sending the message
511 "&lt;LF&gt;"
512 </li>
513 </ul><p>
514
515 </p>
516 <p>where again &lt;CR&gt; and &lt;LF&gt; symbolize the carriage
517 return and line feed characters respectively.
518 </p>
519 <a name="LSCP versioning"></a><br /><hr />
520 <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>
521 <a name="rfc.section.2"></a><h3>2.&nbsp;
522 Versioning of this specification</h3>
523
524 <p>LSCP will certainly be extended and enhanced by-and-by. Each official
525 release of the LSCP specification will be tagged with a unique version
526 tuple. The version tuple consists at least of a major and minor version
527 number like:
528
529 </p>
530 <p>
531 </p>
532 <blockquote class="text">
533 <p>"1.2"
534 </p>
535 </blockquote><p>
536
537 </p>
538 <p>
539 In this example the major version number would be "1" and the minor
540 version number would be "2". Note that the version tuple might also
541 have more than two elements. The major version number defines a
542 group of backward compatible versions. That means a frontend is
543 compatible to the connected sampler if and only if the LSCP versions
544 to which each of the two parties complies to, match both of the
545 following rules:
546
547 </p>
548 <p>Compatibility:
549 </p>
550 <p>
551 </p>
552 <ol class="text">
553 <li>The frontend's LSCP major version and the sampler's LSCP
554 major version are exactly equal.
555 </li>
556 <li>The frontend's LSCP minor version is less or equal than
557 the sampler's LSCP minor version.
558 </li>
559 </ol><p>
560
561 </p>
562 <p>
563 Compatibility can only be claimed if both rules are true.
564 The frontend can use the
565 <a class='info' href='#GET SERVER INFO'>"GET SERVER INFO"<span> (</span><span class='info'>General sampler informations</span><span>)</span></a> command to
566 get the version of the LSCP specification the sampler complies with.
567
568 </p>
569 <a name="anchor2"></a><br /><hr />
570 <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>
571 <a name="rfc.section.3"></a><h3>3.&nbsp;
572 Introduction</h3>
573
574 <p>LinuxSampler is a so called software sampler application
575 capable to playback audio samples from a computer's Random
576 Access Memory (RAM) as well as directly streaming it from disk.
577 LinuxSampler is designed to be modular. It provides several so
578 called "sampler engines" where each engine is specialized for a
579 certain purpose. LinuxSampler has virtual channels which will be
580 referred in this document as "sampler channels". The channels
581 are in such way virtual as they can be connected to an
582 arbitrary MIDI input method and arbitrary MIDI channel (e.g.
583 sampler channel 17 could be connected to an ALSA sequencer
584 device 64:0 and listening to MIDI channel 1 there). Each sampler
585 channel will be associated with an instance of one of the available
586 sampler engines (e.g. GigEngine, DLSEngine). The audio output of
587 each sampler channel can be routed to an arbitrary audio output
588 method (ALSA / JACK) and an arbitrary audio output channel
589 there.
590 </p>
591 <a name="anchor3"></a><br /><hr />
592 <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>
593 <a name="rfc.section.4"></a><h3>4.&nbsp;
594 Focus of this protocol</h3>
595
596 <p>Main focus of this protocol is to provide a way to configure
597 a running LinuxSampler instance and to retrieve information
598 about it. The focus of this protocol is not to provide a way to
599 control synthesis parameters or even to trigger or release
600 notes. Or in other words; the focus are those functionalities
601 which are not covered by MIDI or which may at most be handled
602 via MIDI System Exclusive Messages.
603 </p>
604 <a name="anchor4"></a><br /><hr />
605 <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>
606 <a name="rfc.section.5"></a><h3>5.&nbsp;
607 Communication Overview</h3>
608
609 <p>There are two distinct methods of communication between a
610 running instance of LinuxSampler and one or more control
611 applications, so called "front-ends": a simple request/response
612 communication method used by the clients to give commands to the
613 server as well as to inquire about server's status and a
614 subscribe/notify communication method used by the client to
615 subscribe to and receive notifications of certain events as they
616 happen on the server. The latter needs more effort to be
617 implemented in the front-end application. The two communication
618 methods will be described next.
619 </p>
620 <a name="anchor5"></a><br /><hr />
621 <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>
622 <a name="rfc.section.5.1"></a><h3>5.1.&nbsp;
623 Request/response communication method</h3>
624
625 <p>This simple communication method is based on
626 <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
627 front-end application establishes a TCP connection to the
628 LinuxSampler instance on a certain host system. Then the
629 front-end application will send certain ASCII based commands
630 as defined in this document (every command line must be CRLF
631 terminated - see "Conventions used in this document" at the
632 beginning of this document) and the LinuxSampler application
633 will response after a certain process time with an
634 appropriate ASCII based answer, also as defined in this
635 document. So this TCP communication is simply based on query
636 and answer paradigm. That way LinuxSampler is only able to
637 answer on queries from front-ends, but not able to
638 automatically send messages to the client if it's not asked
639 to. The fronted should not reconnect to LinuxSampler for
640 every single command, instead it should keep the connection
641 established and simply resend message(s) for subsequent
642 commands. To keep information in the front-end up-to-date
643 the front-end has to periodically send new requests to get
644 the current information from the LinuxSampler instance. This
645 is often referred to as "polling". While polling is simple
646 to implement and may be OK to use in some cases, there may
647 be disadvantages to polling such as network traffic overhead
648 and information being out of date.
649 It is possible for a client or several clients to open more
650 than one connection to the server at the same time. It is
651 also possible to send more than one request to the server
652 at the same time but if those requests are sent over the
653 same connection server MUST execute them sequentially. Upon
654 executing a request server will produce a result set and
655 send it to the client. Each and every request made by the
656 client MUST result in a result set being sent back to the
657 client. No other data other than a result set may be sent by
658 a server to a client. No result set may be sent to a client
659 without the client sending request to the server first. On
660 any particular connection, result sets MUST be sent in their
661 entirety without being interrupted by other result sets. If
662 several requests got queued up at the server they MUST be
663 processed in the order they were received and result sets
664 MUST be sent back in the same order.
665 </p>
666 <a name="anchor6"></a><br /><hr />
667 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
668 <a name="rfc.section.5.1.1"></a><h3>5.1.1.&nbsp;
669 Result format</h3>
670
671 <p>Result set could be one of the following types:
672 </p>
673 <p>
674 </p>
675 <ol class="text">
676 <li>Normal
677 </li>
678 <li>Warning
679 </li>
680 <li>Error
681 </li>
682 </ol><p>
683
684 </p>
685 <p>Warning and Error result sets MUST be single line and
686 have the following format:
687 </p>
688 <p>
689 </p>
690 <ul class="text">
691 <li>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;"
692 </li>
693 <li>"ERR:&lt;error-code&gt;:&lt;error-message&gt;"
694 </li>
695 </ul><p>
696
697 </p>
698 <p>Where &lt;warning-code&gt; and &lt;error-code&gt; are
699 numeric unique identifiers of the warning or error and
700 &lt;warning-message&gt; and &lt;error-message&gt; are
701 human readable descriptions of the warning or error
702 respectively.
703 </p>
704 <p>Examples:
705 </p>
706 <p>
707 </p>
708 <blockquote class="text">
709 <p>C: "LOAD INSTRUMENT '/home/me/Boesendorfer24bit.gig" 0 0
710 </p>
711 <p>S: "WRN:32:This is a 24 bit patch which is not supported natively yet."
712 </p>
713 </blockquote><p>
714
715 </p>
716 <p>
717 </p>
718 <blockquote class="text">
719 <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA EAR"
720 </p>
721 <p>S: "ERR:3456:Audio output driver 'ALSA' does not have a parameter 'EAR'."
722 </p>
723 </blockquote><p>
724
725 </p>
726 <p>
727 </p>
728 <blockquote class="text">
729 <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 123456"
730 </p>
731 <p>S: "ERR:9:There is no audio output device with index 123456."
732 </p>
733 </blockquote><p>
734
735 </p>
736 <p>Normal result sets could be:
737 </p>
738 <p>
739 </p>
740 <ol class="text">
741 <li>Empty
742 </li>
743 <li>Single line
744 </li>
745 <li>Multi-line
746 </li>
747 </ol><p>
748
749 </p>
750 <p> Empty result set is issued when the server only
751 needed to acknowledge the fact that the request was
752 received and it was processed successfully and no
753 additional information is available. This result set has
754 the following format:
755 </p>
756 <p>
757 </p>
758 <blockquote class="text">
759 <p>"OK"
760 </p>
761 </blockquote><p>
762
763 </p>
764 <p>Example:
765 </p>
766 <p>
767 </p>
768 <blockquote class="text">
769 <p>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 CHANNELS=4"
770 </p>
771 <p>S: "OK"
772 </p>
773 </blockquote><p>
774
775 </p>
776 <p>Single line result sets are command specific. One
777 example of a single line result set is an empty line.
778 Multi-line result sets are command specific and may
779 include one or more lines of information. They MUST
780 always end with the following line:
781 </p>
782 <p>
783 </p>
784 <blockquote class="text">
785 <p>"."
786 </p>
787 </blockquote><p>
788
789 </p>
790 <p>Example:
791 </p>
792 <p>
793 </p>
794 <blockquote class="text">
795 <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
796 </p>
797 <p>S: "DRIVER: ALSA"
798 </p>
799 <p>&nbsp;&nbsp;&nbsp;"CHANNELS: 2"
800 </p>
801 <p>&nbsp;&nbsp;&nbsp;"SAMPLERATE: 44100"
802 </p>
803 <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
804 </p>
805 <p>&nbsp;&nbsp;&nbsp;"FRAGMENTS: 2"
806 </p>
807 <p>&nbsp;&nbsp;&nbsp;"FRAGMENTSIZE: 128"
808 </p>
809 <p>&nbsp;&nbsp;&nbsp;"CARD: '0,0'"
810 </p>
811 <p>&nbsp;&nbsp;&nbsp;"."
812 </p>
813 </blockquote><p>
814
815 </p>
816 <p>In addition to above mentioned formats, warnings and
817 empty result sets MAY be indexed. In this case, they
818 have the following formats respectively:
819 </p>
820 <p>
821 </p>
822 <ul class="text">
823 <li>"WRN[&lt;index&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;"
824 </li>
825 <li>"OK[&lt;index&gt;]"
826 </li>
827 </ul><p>
828
829 </p>
830 <p>where &lt;index&gt; is command specific and is used
831 to indicate channel number that the result set was
832 related to or other integer value.
833 </p>
834 <p>Each line of the result set MUST end with
835 &lt;CRLF&gt;.
836 </p>
837 <p>Examples:
838 </p>
839 <p>
840 </p>
841 <blockquote class="text">
842 <p>C: "ADD CHANNEL"
843 </p>
844 <p>S: "OK[12]"
845 </p>
846 </blockquote><p>
847
848 </p>
849 <p>
850 </p>
851 <blockquote class="text">
852 <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"
853 </p>
854 <p>S: "WRN[0]:32:Sample rate not supported, using 44100 instead."
855 </p>
856 </blockquote><p>
857
858 </p>
859 <a name="anchor7"></a><br /><hr />
860 <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>
861 <a name="rfc.section.5.2"></a><h3>5.2.&nbsp;
862 Subscribe/notify communication method</h3>
863
864 <p>This more sophisticated communication method is actually
865 only an extension of the simple request/response
866 communication method. The front-end still uses a TCP
867 connection and sends the same commands on the TCP
868 connection. Two extra commands are SUBSCRIBE and UNSUBSCRIBE
869 commands that allow a client to tell the server that it is
870 interested in receiving notifications about certain events
871 as they happen on the server. The SUBSCRIBE command has the
872 following syntax:
873 </p>
874 <p>
875 </p>
876 <blockquote class="text">
877 <p>SUBSCRIBE &lt;event-id&gt;
878 </p>
879 </blockquote><p>
880
881 </p>
882 <p>where &lt;event-id&gt; will be replaced by the respective
883 event that client wants to subscribe to. Upon receiving such
884 request, server SHOULD respond with OK and start sending
885 EVENT notifications when a given even has occurred to the
886 front-end when an event has occurred. It MAY be possible
887 certain events may be sent before OK response during real
888 time nature of their generation. Event messages have the
889 following format:
890 </p>
891 <p>
892 </p>
893 <blockquote class="text">
894 <p>NOTIFY:&lt;event-id&gt;:&lt;custom-event-data&gt;
895 </p>
896 </blockquote><p>
897
898 </p>
899 <p>where &lt;event-id&gt; uniquely identifies the event that
900 has occurred and &lt;custom-event-data&gt; is event
901 specific.
902 </p>
903 <p>Several rules must be followed by the server when
904 generating events:
905 </p>
906 <p>
907 </p>
908 <ol class="text">
909 <li>Events MUST NOT be sent to any client who has not
910 issued an appropriate SUBSCRIBE command.
911 </li>
912 <li>Events MUST only be sent using the same
913 connection that was used to subscribe to them.
914 </li>
915 <li>When response is being sent to the client, event
916 MUST be inserted in the stream before or after the
917 response, but NOT in the middle. Same is true about
918 the response. It should never be inserted in the
919 middle of the event message as well as any other
920 response.
921 </li>
922 </ol><p>
923
924 </p>
925 <p>If the client is not interested in a particular event
926 anymore it MAY issue UNSUBSCRIBE command using the following
927 syntax:
928 </p>
929 <p>
930 </p>
931 <blockquote class="text">
932 <p>UNSUBSCRIBE &lt;event-id&gt;
933 </p>
934 </blockquote><p>
935
936 </p>
937 <p>where &lt;event-id&gt; will be replace by the respective
938 event that client is no longer interested in receiving. For
939 a list of supported events see <a class='info' href='#events'>Section&nbsp;8<span> (</span><span class='info'>Events</span><span>)</span></a>.
940 </p>
941 <p>Example: the fill states of disk stream buffers have
942 changed on sampler channel 4 and the LinuxSampler instance
943 will react by sending the following message to all clients
944 who subscribed to this event:
945 </p>
946 <p>
947 </p>
948 <blockquote class="text">
949 <p>NOTIFY:CHANNEL_BUFFER_FILL:4 [35]62%,[33]80%,[37]98%
950 </p>
951 </blockquote><p>
952
953 </p>
954 <p>Which means there are currently three active streams on
955 sampler channel 4, where the stream with ID "35" is filled
956 by 62%, stream with ID 33 is filled by 80% and stream with
957 ID 37 is filled by 98%.
958 </p>
959 <p>Clients may choose to open more than one connection to
960 the server and use some connections to receive notifications
961 while using other connections to issue commands to the
962 back-end. This is entirely legal and up to the
963 implementation. This does not change the protocol in any way
964 and no special restrictions exist on the server to allow or
965 disallow this or to track what connections belong to what
966 front-ends. Server will listen on a single port, accept
967 multiple connections and support protocol described in this
968 specification in it's entirety on this single port on each
969 connection that it accepted.
970 </p>
971 <p>Due to the fact that TCP is used for this communication,
972 dead peers will be detected automatically by the OS TCP
973 stack. While it may take a while to detect dead peers if no
974 traffic is being sent from server to client (TCP keep-alive
975 timer is set to 2 hours on many OSes) it will not be an
976 issue here as when notifications are sent by the server,
977 dead client will be detected quickly.
978 </p>
979 <p>When connection is closed for any reason server MUST
980 forget all subscriptions that were made on this connection.
981 If client reconnects it MUST resubscribe to all events that
982 it wants to receive.
983 </p>
984 <a name="control_commands"></a><br /><hr />
985 <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>
986 <a name="rfc.section.6"></a><h3>6.&nbsp;
987 Description for control commands</h3>
988
989 <p>This chapter will describe the available control commands
990 that can be sent on the TCP connection in detail. Some certain
991 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>
992 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
993 multiple-line responses. In this case LinuxSampler signals the
994 end of the response by a "." (single dot) line.
995 </p>
996 <a name="anchor8"></a><br /><hr />
997 <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>
998 <a name="rfc.section.6.1"></a><h3>6.1.&nbsp;
999 Ignored lines and comments</h3>
1000
1001 <p>White lines, that is lines which only contain space and
1002 tabulator characters, and lines that start with a "#"
1003 character are ignored, thus it's possible for example to
1004 group commands and to place comments in a LSCP script
1005 file.
1006 </p>
1007 <a name="anchor9"></a><br /><hr />
1008 <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>
1009 <a name="rfc.section.6.2"></a><h3>6.2.&nbsp;
1010 Configuring audio drivers</h3>
1011
1012 <p>Instances of drivers in LinuxSampler are called devices.
1013 You can use multiple audio devices simultaneously, e.g. to
1014 output the sound of one sampler channel using the ALSA audio
1015 output driver, and on another sampler channel you might want
1016 to use the JACK audio output driver. For particular audio
1017 output systems it's also possible to create several devices
1018 of the same audio output driver, e.g. two separate ALSA
1019 audio output devices for using two different sound cards at
1020 the same time. This chapter describes all commands to
1021 configure LinuxSampler's audio output devices and their
1022 parameters.
1023 </p>
1024 <p>Instead of defining commands and parameters for each
1025 driver individually, all possible parameters, their meanings
1026 and possible values have to be obtained at runtime. This
1027 makes the protocol a bit abstract, but has the advantage,
1028 that front-ends can be written independently of what drivers
1029 are currently implemented and what parameters these drivers
1030 are actually offering. This means front-ends can even handle
1031 drivers which are implemented somewhere in future without
1032 modifying the front-end at all.
1033 </p>
1034 <p>Note: examples in this chapter showing particular
1035 parameters of drivers are not meant as specification of the
1036 drivers' parameters. Driver implementations in LinuxSampler
1037 might have complete different parameter names and meanings
1038 than shown in these examples or might change in future, so
1039 these examples are only meant for showing how to retrieve
1040 what parameters drivers are offering, how to retrieve their
1041 possible values, etc.
1042 </p>
1043 <a name="GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"></a><br /><hr />
1044 <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>
1045 <a name="rfc.section.6.2.1"></a><h3>6.2.1.&nbsp;
1046 Getting amount of available audio output drivers</h3>
1047
1048 <p>Use the following command to get the number of
1049 audio output drivers currently available for the
1050 LinuxSampler instance:
1051 </p>
1052 <p>
1053 </p>
1054 <blockquote class="text">
1055 <p>GET AVAILABLE_AUDIO_OUTPUT_DRIVERS
1056 </p>
1057 </blockquote><p>
1058
1059 </p>
1060 <p>Possible Answers:
1061 </p>
1062 <p>
1063 </p>
1064 <blockquote class="text">
1065 <p>LinuxSampler will answer by sending the
1066 number of audio output drivers.
1067 </p>
1068 </blockquote><p>
1069
1070 </p>
1071 <p>Example:
1072 </p>
1073 <p>
1074 </p>
1075 <blockquote class="text">
1076 <p>C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
1077 </p>
1078 <p>S: "2"
1079 </p>
1080 </blockquote><p>
1081
1082 </p>
1083 <a name="LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"></a><br /><hr />
1084 <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>
1085 <a name="rfc.section.6.2.2"></a><h3>6.2.2.&nbsp;
1086 Getting all available audio output drivers</h3>
1087
1088 <p>Use the following command to list all audio output
1089 drivers currently available for the LinuxSampler
1090 instance:
1091 </p>
1092 <p>
1093 </p>
1094 <blockquote class="text">
1095 <p>LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS
1096 </p>
1097 </blockquote><p>
1098
1099 </p>
1100 <p>Possible Answers:
1101 </p>
1102 <p>
1103 </p>
1104 <blockquote class="text">
1105 <p>LinuxSampler will answer by sending comma
1106 separated character strings, each symbolizing an
1107 audio output driver.
1108 </p>
1109 </blockquote><p>
1110
1111 </p>
1112 <p>Example:
1113 </p>
1114 <p>
1115 </p>
1116 <blockquote class="text">
1117 <p>C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"
1118 </p>
1119 <p>S: "ALSA,JACK"
1120 </p>
1121 </blockquote><p>
1122
1123 </p>
1124 <a name="GET AUDIO_OUTPUT_DRIVER INFO"></a><br /><hr />
1125 <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>
1126 <a name="rfc.section.6.2.3"></a><h3>6.2.3.&nbsp;
1127 Getting information about a specific audio
1128 output driver</h3>
1129
1130 <p>Use the following command to get detailed information
1131 about a specific audio output driver:
1132 </p>
1133 <p>
1134 </p>
1135 <blockquote class="text">
1136 <p>GET AUDIO_OUTPUT_DRIVER INFO
1137 &lt;audio-output-driver&gt;
1138 </p>
1139 </blockquote><p>
1140
1141 </p>
1142 <p>Where &lt;audio-output-driver&gt; is the name of the
1143 audio output driver, returned by the
1144 <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.
1145 </p>
1146 <p>Possible Answers:
1147 </p>
1148 <p>
1149 </p>
1150 <blockquote class="text">
1151 <p>LinuxSampler will answer by sending a
1152 &lt;CRLF&gt; separated list. Each answer line
1153 begins with the information category name
1154 followed by a colon and then a space character
1155 &lt;SP&gt; and finally the info character string
1156 to that info category. At the moment the
1157 following information categories are
1158 defined:
1159 </p>
1160 <p>
1161 </p>
1162 <blockquote class="text">
1163 <p>DESCRIPTION -
1164 </p>
1165 <blockquote class="text">
1166 <p> character string describing the
1167 audio output driver
1168 </p>
1169 </blockquote>
1170
1171
1172 <p>VERSION -
1173 </p>
1174 <blockquote class="text">
1175 <p>character string reflecting the
1176 driver's version
1177 </p>
1178 </blockquote>
1179
1180
1181 <p>PARAMETERS -
1182 </p>
1183 <blockquote class="text">
1184 <p>comma separated list of all
1185 parameters available for the given
1186 audio output driver, at least
1187 parameters 'channels', 'samplerate'
1188 and 'active' are offered by all audio
1189 output drivers
1190 </p>
1191 </blockquote>
1192
1193
1194 </blockquote>
1195
1196
1197 <p>The mentioned fields above don't have to be
1198 in particular order.
1199 </p>
1200 </blockquote><p>
1201
1202 </p>
1203 <p>Example:
1204 </p>
1205 <p>
1206 </p>
1207 <blockquote class="text">
1208 <p>C: "GET AUDIO_OUTPUT_DRIVER INFO ALSA"
1209 </p>
1210 <p>S: "DESCRIPTION: Advanced Linux Sound
1211 Architecture"
1212 </p>
1213 <p>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"
1214 </p>
1215 <p>&nbsp;&nbsp;&nbsp;"PARAMETERS:
1216 DRIVER,CHANNELS,SAMPLERATE,ACTIVE,FRAGMENTS,
1217 FRAGMENTSIZE,CARD"
1218 </p>
1219 <p>&nbsp;&nbsp;&nbsp;"."
1220 </p>
1221 </blockquote><p>
1222
1223 </p>
1224 <a name="GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO"></a><br /><hr />
1225 <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>
1226 <a name="rfc.section.6.2.4"></a><h3>6.2.4.&nbsp;
1227 Getting information about specific audio
1228 output driver parameter</h3>
1229
1230 <p>Use the following command to get detailed information
1231 about a specific audio output driver parameter:
1232 </p>
1233 <p>
1234 </p>
1235 <blockquote class="text">
1236 <p>GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO &lt;audio&gt; &lt;prm&gt; [&lt;deplist&gt;]
1237 </p>
1238 </blockquote><p>
1239
1240 </p>
1241 <p>Where &lt;audio&gt; is the name of the audio output
1242 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,
1243 &lt;prm&gt; a specific parameter name for which information should be
1244 obtained (as returned by the
1245 <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
1246 &lt;deplist&gt; is an optional list of parameters on which the sought
1247 parameter &lt;prm&gt; depends on, &lt;deplist&gt; is a list of key-value
1248 pairs in form of "key1=val1 key2=val2 ...", where character string values
1249 are encapsulated into apostrophes ('). Arguments given with &lt;deplist&gt;
1250 which are not dependency parameters of &lt;prm&gt; will be ignored, means
1251 the front-end application can simply put all parameters into &lt;deplist&gt;
1252 with the values already selected by the user.
1253 </p>
1254 <p>Possible Answers:
1255 </p>
1256 <p>
1257 </p>
1258 <blockquote class="text">
1259 <p>LinuxSampler will answer by sending a
1260 &lt;CRLF&gt; separated list.
1261 Each answer line begins with the information category name
1262 followed by a colon and then a space character &lt;SP&gt; and
1263 finally
1264 the info character string to that info category. There are
1265 information which is always returned, independently of the
1266 given driver parameter and there are optional information
1267 which is only shown dependently to given driver parameter. At
1268 the moment the following information categories are defined:
1269 </p>
1270 </blockquote><p>
1271
1272 </p>
1273 <p>
1274 </p>
1275 <blockquote class="text">
1276 <p>TYPE -
1277 </p>
1278 <blockquote class="text">
1279 <p>either "BOOL" for boolean value(s) or
1280 "INT" for integer
1281 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1282 character string(s)
1283 (always returned, no matter which driver parameter)
1284 </p>
1285 </blockquote>
1286
1287
1288 <p>DESCRIPTION -
1289 </p>
1290 <blockquote class="text">
1291 <p>arbitrary text describing the purpose of the parameter
1292 (always returned, no matter which driver parameter)
1293 </p>
1294 </blockquote>
1295
1296
1297 <p>MANDATORY -
1298 </p>
1299 <blockquote class="text">
1300 <p>either true or false, defines if this parameter must be
1301 given when the device is to be created with the
1302 <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>
1303 command (always returned, no matter which driver parameter)
1304 </p>
1305 </blockquote>
1306
1307
1308 <p>FIX -
1309 </p>
1310 <blockquote class="text">
1311 <p>either true or false, if false then this parameter can
1312 be changed at any time, once the device is created by
1313 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>
1314 command (always returned, no matter which driver parameter)
1315 </p>
1316 </blockquote>
1317
1318
1319 <p>MULTIPLICITY -
1320 </p>
1321 <blockquote class="text">
1322 <p>either true or false, defines if this parameter allows
1323 only one value or a list of values, where true means
1324 multiple values and false only a single value allowed
1325 (always returned, no matter which driver parameter)
1326 </p>
1327 </blockquote>
1328
1329
1330 <p>DEPENDS -
1331 </p>
1332 <blockquote class="text">
1333 <p>comma separated list of parameters this parameter depends
1334 on, means the values for fields 'DEFAULT', 'RANGE_MIN',
1335 'RANGE_MAX' and 'POSSIBILITIES' might depend on these
1336 listed parameters, for example assuming that an audio
1337 driver (like the ALSA driver) offers parameters 'card'
1338 and 'samplerate' then parameter 'samplerate' would
1339 depend on 'card' because the possible values for
1340 'samplerate' depends on the sound card which can be
1341 chosen by the 'card' parameter
1342 (optionally returned, dependent to driver parameter)
1343 </p>
1344 </blockquote>
1345
1346
1347 <p>DEFAULT -
1348 </p>
1349 <blockquote class="text">
1350 <p>reflects the default value for this parameter which is
1351 used when the device is created and not explicitly
1352 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,
1353 in case of MULTIPLCITY=true, this is a comma separated
1354 list, that's why character strings are encapsulated into
1355 apostrophes (')
1356 (optionally returned, dependent to driver parameter)
1357 </p>
1358 </blockquote>
1359
1360
1361 <p>RANGE_MIN -
1362 </p>
1363 <blockquote class="text">
1364 <p>defines lower limit of the allowed value range for this
1365 parameter, can be an integer value as well as a dotted
1366 number, this parameter is often used in conjunction
1367 with RANGE_MAX, but may also appear without
1368 (optionally returned, dependent to driver parameter)
1369 </p>
1370 </blockquote>
1371
1372
1373 <p>RANGE_MAX -
1374 </p>
1375 <blockquote class="text">
1376 <p>defines upper limit of the allowed value range for this
1377 parameter, can be an integer value as well as a dotted
1378 number, this parameter is often used in conjunction with
1379 RANGE_MIN, but may also appear without
1380 (optionally returned, dependent to driver parameter)
1381 </p>
1382 </blockquote>
1383
1384
1385 <p>POSSIBILITIES -
1386 </p>
1387 <blockquote class="text">
1388 <p>comma separated list of possible values for this
1389 parameter, character strings are encapsulated into
1390 apostrophes
1391 (optionally returned, dependent to driver parameter)
1392 </p>
1393 </blockquote>
1394
1395
1396 </blockquote><p>
1397
1398 </p>
1399 <p>The mentioned fields above don't have to be in particular order.
1400 </p>
1401 <p>Examples:
1402 </p>
1403 <p>
1404 </p>
1405 <blockquote class="text">
1406 <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA CARD"
1407 </p>
1408 <p>S: "DESCRIPTION: sound card to be used"
1409 </p>
1410 <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
1411 </p>
1412 <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1413 </p>
1414 <p>&nbsp;&nbsp;&nbsp;"FIX: true"
1415 </p>
1416 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1417 </p>
1418 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: '0,0'"
1419 </p>
1420 <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: '0,0','1,0','2,0'"
1421 </p>
1422 <p>&nbsp;&nbsp;&nbsp;"."
1423 </p>
1424 </blockquote><p>
1425
1426 </p>
1427 <p>
1428 </p>
1429 <blockquote class="text">
1430 <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE"
1431 </p>
1432 <p>S: "DESCRIPTION: output sample rate in Hz"
1433 </p>
1434 <p>&nbsp;&nbsp;&nbsp;"TYPE: INT"
1435 </p>
1436 <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1437 </p>
1438 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
1439 </p>
1440 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1441 </p>
1442 <p>&nbsp;&nbsp;&nbsp;"DEPENDS: card"
1443 </p>
1444 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"
1445 </p>
1446 <p>&nbsp;&nbsp;&nbsp;"."
1447 </p>
1448 </blockquote><p>
1449
1450 </p>
1451 <p>
1452 </p>
1453 <blockquote class="text">
1454 <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE CARD='0,0'"
1455 </p>
1456 <p>S: "DESCRIPTION: output sample rate in Hz"
1457 </p>
1458 <p>&nbsp;&nbsp;&nbsp;"TYPE: INT"
1459 </p>
1460 <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1461 </p>
1462 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
1463 </p>
1464 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1465 </p>
1466 <p>&nbsp;&nbsp;&nbsp;"DEPENDS: card"
1467 </p>
1468 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"
1469 </p>
1470 <p>&nbsp;&nbsp;&nbsp;"RANGE_MIN: 22050"
1471 </p>
1472 <p>&nbsp;&nbsp;&nbsp;"RANGE_MAX: 96000"
1473 </p>
1474 <p>&nbsp;&nbsp;&nbsp;"."
1475 </p>
1476 </blockquote><p>
1477
1478 </p>
1479 <a name="CREATE AUDIO_OUTPUT_DEVICE"></a><br /><hr />
1480 <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>
1481 <a name="rfc.section.6.2.5"></a><h3>6.2.5.&nbsp;
1482 Creating an audio output device</h3>
1483
1484 <p>Use the following command to create a new audio output device for the desired audio output system:
1485 </p>
1486 <p>
1487 </p>
1488 <blockquote class="text">
1489 <p>CREATE AUDIO_OUTPUT_DEVICE &lt;audio-output-driver&gt; [&lt;param-list&gt;]
1490 </p>
1491 </blockquote><p>
1492
1493 </p>
1494 <p>Where &lt;audio-output-driver&gt; should be replaced by the desired audio
1495 output system as returned by the
1496 <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>
1497 command and &lt;param-list&gt; by an optional list of driver
1498 specific parameters in form of "key1=val1 key2=val2 ...", where
1499 character string values should be encapsulated into apostrophes (').
1500 Note that there might be drivers which require parameter(s) to be
1501 given with this command. Use the previously described commands in
1502 this chapter to get this information.
1503 </p>
1504 <p>Possible Answers:
1505 </p>
1506 <p>
1507 </p>
1508 <blockquote class="text">
1509 <p>"OK[&lt;device-id&gt;]" -
1510 </p>
1511 <blockquote class="text">
1512 <p>in case the device was successfully created, where
1513 &lt;device-id&gt; is the numerical ID of the new device
1514 </p>
1515 </blockquote>
1516
1517
1518 <p>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1519 </p>
1520 <blockquote class="text">
1521 <p>in case the device was created successfully, where
1522 &lt;device-id&gt; is the numerical ID of the new device, but there
1523 are noteworthy issue(s) related (e.g. sound card doesn't
1524 support given hardware parameters and the driver is using
1525 fall-back values), providing an appropriate warning code and
1526 warning message
1527 </p>
1528 </blockquote>
1529
1530
1531 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1532 </p>
1533 <blockquote class="text">
1534 <p>in case it failed, providing an appropriate error code and error message
1535 </p>
1536 </blockquote>
1537
1538
1539 </blockquote><p>
1540
1541 </p>
1542 <p>Examples:
1543 </p>
1544 <p>
1545 </p>
1546 <blockquote class="text">
1547 <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA"
1548 </p>
1549 <p>S: "OK[0]"
1550 </p>
1551 </blockquote><p>
1552
1553 </p>
1554 <p>
1555 </p>
1556 <blockquote class="text">
1557 <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"
1558 </p>
1559 <p>S: "OK[1]"
1560 </p>
1561 </blockquote><p>
1562
1563 </p>
1564 <a name="DESTROY AUDIO_OUTPUT_DEVICE"></a><br /><hr />
1565 <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>
1566 <a name="rfc.section.6.2.6"></a><h3>6.2.6.&nbsp;
1567 Destroying an audio output device</h3>
1568
1569 <p>Use the following command to destroy a created output device:
1570 </p>
1571 <p>
1572 </p>
1573 <blockquote class="text">
1574 <p>DESTROY AUDIO_OUTPUT_DEVICE &lt;device-id&gt;
1575 </p>
1576 </blockquote><p>
1577
1578 </p>
1579 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1580 audio output device as given by the
1581 <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>
1582 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>
1583 command.
1584 </p>
1585 <p>Possible Answers:
1586 </p>
1587 <p>
1588 </p>
1589 <blockquote class="text">
1590 <p>"OK" -
1591 </p>
1592 <blockquote class="text">
1593 <p>in case the device was successfully destroyed
1594 </p>
1595 </blockquote>
1596
1597
1598 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1599 </p>
1600 <blockquote class="text">
1601 <p>in case the device was destroyed successfully, but there are
1602 noteworthy issue(s) related (e.g. an audio over ethernet
1603 driver was unloaded but the other host might not be
1604 informed about this situation), providing an appropriate
1605 warning code and warning message
1606 </p>
1607 </blockquote>
1608
1609
1610 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1611 </p>
1612 <blockquote class="text">
1613 <p>in case it failed, providing an appropriate error code and
1614 error message
1615 </p>
1616 </blockquote>
1617
1618
1619 </blockquote><p>
1620
1621 </p>
1622 <p>Example:
1623 </p>
1624 <p>
1625 </p>
1626 <blockquote class="text">
1627 <p>C: "DESTROY AUDIO_OUTPUT_DEVICE 0"
1628 </p>
1629 <p>S: "OK"
1630 </p>
1631 </blockquote><p>
1632
1633 </p>
1634 <a name="GET AUDIO_OUTPUT_DEVICES"></a><br /><hr />
1635 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1636 <a name="rfc.section.6.2.7"></a><h3>6.2.7.&nbsp;
1637 Getting all created audio output device count</h3>
1638
1639 <p>Use the following command to count all created audio output devices:
1640 </p>
1641 <p>
1642 </p>
1643 <blockquote class="text">
1644 <p>GET AUDIO_OUTPUT_DEVICES
1645 </p>
1646 </blockquote><p>
1647
1648 </p>
1649 <p>Possible Answers:
1650 </p>
1651 <p>
1652 </p>
1653 <blockquote class="text">
1654 <p>LinuxSampler will answer by sending the current number of all
1655 audio output devices.
1656 </p>
1657 </blockquote><p>
1658
1659 </p>
1660 <p>Example:
1661 </p>
1662 <p>
1663 </p>
1664 <blockquote class="text">
1665 <p>C: "GET AUDIO_OUTPUT_DEVICES"
1666 </p>
1667 <p>S: "4"
1668 </p>
1669 </blockquote><p>
1670
1671 </p>
1672 <a name="LIST AUDIO_OUTPUT_DEVICES"></a><br /><hr />
1673 <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>
1674 <a name="rfc.section.6.2.8"></a><h3>6.2.8.&nbsp;
1675 Getting all created audio output device list</h3>
1676
1677 <p>Use the following command to list all created audio output devices:
1678 </p>
1679 <p>
1680 </p>
1681 <blockquote class="text">
1682 <p>LIST AUDIO_OUTPUT_DEVICES
1683 </p>
1684 </blockquote><p>
1685
1686 </p>
1687 <p>Possible Answers:
1688 </p>
1689 <p>
1690 </p>
1691 <blockquote class="text">
1692 <p>LinuxSampler will answer by sending a comma separated list with
1693 the numerical IDs of all audio output devices.
1694 </p>
1695 </blockquote><p>
1696
1697 </p>
1698 <p>Example:
1699 </p>
1700 <p>
1701 </p>
1702 <blockquote class="text">
1703 <p>C: "LIST AUDIO_OUTPUT_DEVICES"
1704 </p>
1705 <p>S: "0,1,4,5"
1706 </p>
1707 </blockquote><p>
1708
1709 </p>
1710 <a name="GET AUDIO_OUTPUT_DEVICE INFO"></a><br /><hr />
1711 <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>
1712 <a name="rfc.section.6.2.9"></a><h3>6.2.9.&nbsp;
1713 Getting current settings of an audio output device</h3>
1714
1715 <p>Use the following command to get current settings of a specific, created audio output device:
1716 </p>
1717 <p>
1718 </p>
1719 <blockquote class="text">
1720 <p>GET AUDIO_OUTPUT_DEVICE INFO &lt;device-id&gt;
1721 </p>
1722 </blockquote><p>
1723
1724 </p>
1725 <p>Where &lt;device-id&gt; should be replaced by numerical ID
1726 of the audio output device as e.g. returned by the
1727 <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.
1728 </p>
1729 <p>Possible Answers:
1730 </p>
1731 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1732 Each answer line begins with the information category name
1733 followed by a colon and then a space character &lt;SP&gt; and finally
1734 the info character string to that info category. As some
1735 parameters might allow multiple values, character strings are
1736 encapsulated into apostrophes ('). At the moment the following
1737 information categories are defined (independently of device):
1738 </p>
1739 <p>
1740 </p>
1741 <blockquote class="text">
1742 <p>DRIVER -
1743 </p>
1744 <blockquote class="text">
1745 <p>identifier of the used audio output driver, as also
1746 returned by the
1747 <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>
1748 command
1749 </p>
1750 </blockquote>
1751
1752
1753 <p>CHANNELS -
1754 </p>
1755 <blockquote class="text">
1756 <p>amount of audio output channels this device currently
1757 offers
1758 </p>
1759 </blockquote>
1760
1761
1762 <p>SAMPLERATE -
1763 </p>
1764 <blockquote class="text">
1765 <p>playback sample rate the device uses
1766 </p>
1767 </blockquote>
1768
1769
1770 <p>ACTIVE -
1771 </p>
1772 <blockquote class="text">
1773 <p>either true or false, if false then the audio device is
1774 inactive and doesn't output any sound, nor do the
1775 sampler channels connected to this audio device render
1776 any audio
1777 </p>
1778 </blockquote>
1779
1780
1781 </blockquote><p>
1782
1783 </p>
1784 <p>The mentioned fields above don't have to be in particular
1785 order. The fields above are only those fields which are
1786 returned by all audio output devices. Every audio output driver
1787 might have its own, additional driver specific parameters (see
1788 <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>)
1789 which are also returned by this command.
1790 </p>
1791 <p>Example:
1792 </p>
1793 <p>
1794 </p>
1795 <blockquote class="text">
1796 <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
1797 </p>
1798 <p>S: "DRIVER: ALSA"
1799 </p>
1800 <p>&nbsp;&nbsp;&nbsp;"CHANNELS: 2"
1801 </p>
1802 <p>&nbsp;&nbsp;&nbsp;"SAMPLERATE: 44100"
1803 </p>
1804 <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
1805 </p>
1806 <p>&nbsp;&nbsp;&nbsp;"FRAGMENTS: 2"
1807 </p>
1808 <p>&nbsp;&nbsp;&nbsp;"FRAGMENTSIZE: 128"
1809 </p>
1810 <p>&nbsp;&nbsp;&nbsp;"CARD: '0,0'"
1811 </p>
1812 <p>&nbsp;&nbsp;&nbsp;"."
1813 </p>
1814 </blockquote><p>
1815
1816 </p>
1817 <a name="SET AUDIO_OUTPUT_DEVICE_PARAMETER"></a><br /><hr />
1818 <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>
1819 <a name="rfc.section.6.2.10"></a><h3>6.2.10.&nbsp;
1820 Changing settings of audio output devices</h3>
1821
1822 <p>Use the following command to alter a specific setting of a created audio output device:
1823 </p>
1824 <p>
1825 </p>
1826 <blockquote class="text">
1827 <p>SET AUDIO_OUTPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;
1828 </p>
1829 </blockquote><p>
1830
1831 </p>
1832 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1833 audio output device as given by the
1834 <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>
1835 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>
1836 command, &lt;key&gt; by the name of the parameter to change
1837 and &lt;value&gt; by the new value for this parameter.
1838 </p>
1839 <p>Possible Answers:
1840 </p>
1841 <p>
1842 </p>
1843 <blockquote class="text">
1844 <p>"OK" -
1845 </p>
1846 <blockquote class="text">
1847 <p>in case setting was successfully changed
1848 </p>
1849 </blockquote>
1850
1851
1852 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1853 </p>
1854 <blockquote class="text">
1855 <p>in case setting was changed successfully, but there are
1856 noteworthy issue(s) related, providing an appropriate
1857 warning code and warning message
1858 </p>
1859 </blockquote>
1860
1861
1862 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1863 </p>
1864 <blockquote class="text">
1865 <p>in case it failed, providing an appropriate error code and
1866 error message
1867 </p>
1868 </blockquote>
1869
1870
1871 </blockquote><p>
1872
1873 </p>
1874 <p>Example:
1875 </p>
1876 <p>
1877 </p>
1878 <blockquote class="text">
1879 <p>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"
1880 </p>
1881 <p>S: "OK"
1882 </p>
1883 </blockquote><p>
1884
1885 </p>
1886 <a name="GET AUDIO_OUTPUT_CHANNEL INFO"></a><br /><hr />
1887 <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>
1888 <a name="rfc.section.6.2.11"></a><h3>6.2.11.&nbsp;
1889 Getting information about an audio channel</h3>
1890
1891 <p>Use the following command to get information about an audio channel:
1892 </p>
1893 <p>
1894 </p>
1895 <blockquote class="text">
1896 <p>GET AUDIO_OUTPUT_CHANNEL INFO &lt;device-id&gt; &lt;audio-chan&gt;
1897 </p>
1898 </blockquote><p>
1899
1900 </p>
1901 <p>Where &lt;device-id&gt; is the numerical ID of the audio output device as given by the
1902 <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>
1903 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>
1904 command and &lt;audio-chan&gt; the audio channel number.
1905 </p>
1906 <p>Possible Answers:
1907 </p>
1908 <p>
1909 </p>
1910 <blockquote class="text">
1911 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1912 Each answer line begins with the information category name
1913 followed by a colon and then a space character &lt;SP&gt; and finally
1914 the info character string to that info category. At the moment
1915 the following information categories are defined:
1916 </p>
1917 <p>
1918 </p>
1919 <blockquote class="text">
1920 <p>NAME -
1921 </p>
1922 <blockquote class="text">
1923 <p>arbitrary character string naming the channel, which
1924 doesn't have to be unique (always returned by all audio channels)
1925 </p>
1926 </blockquote>
1927
1928
1929 <p>IS_MIX_CHANNEL -
1930 </p>
1931 <blockquote class="text">
1932 <p>either true or false, a mix-channel is not a real,
1933 independent audio channel, but a virtual channel which
1934 is mixed to another real channel, this mechanism is
1935 needed for sampler engines which need more audio
1936 channels than the used audio system might be able to offer
1937 (always returned by all audio channels)
1938 </p>
1939 </blockquote>
1940
1941
1942 <p>MIX_CHANNEL_DESTINATION -
1943 </p>
1944 <blockquote class="text">
1945 <p>numerical ID (positive integer including 0)
1946 which reflects the real audio channel (of the same audio
1947 output device) this mix channel refers to, means where
1948 the audio signal actually will be routed / added to
1949 (only returned in case the audio channel is mix channel)
1950 </p>
1951 </blockquote>
1952
1953
1954 </blockquote>
1955
1956
1957 </blockquote><p>
1958
1959 </p>
1960 <p>The mentioned fields above don't have to be in particular
1961 order. The fields above are only those fields which are
1962 generally returned for the described cases by all audio
1963 channels regardless of the audio driver. Every audio channel
1964 might have its own, additional driver and channel specific
1965 parameters.
1966 </p>
1967 <p>Examples:
1968 </p>
1969 <p>
1970 </p>
1971 <blockquote class="text">
1972 <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 0"
1973 </p>
1974 <p>S: "NAME: studio monitor left"
1975 </p>
1976 <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
1977 </p>
1978 <p>&nbsp;&nbsp;&nbsp;"."
1979 </p>
1980 </blockquote><p>
1981
1982 </p>
1983 <p>
1984 </p>
1985 <blockquote class="text">
1986 <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 1"
1987 </p>
1988 <p>S: "NAME: studio monitor right"
1989 </p>
1990 <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
1991 </p>
1992 <p>&nbsp;&nbsp;&nbsp;"."
1993 </p>
1994 </blockquote><p>
1995
1996 </p>
1997 <p>
1998 </p>
1999 <blockquote class="text">
2000 <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"
2001 </p>
2002 <p>S: "NAME: studio monitor left"
2003 </p>
2004 <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: true"
2005 </p>
2006 <p>&nbsp;&nbsp;&nbsp;"MIX_CHANNEL_DESTINATION: 1"
2007 </p>
2008 <p>&nbsp;&nbsp;&nbsp;"."
2009 </p>
2010 </blockquote><p>
2011
2012 </p>
2013 <p>
2014 </p>
2015 <blockquote class="text">
2016 <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"
2017 </p>
2018 <p>S: "NAME: 'ardour (left)'"
2019 </p>
2020 <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
2021 </p>
2022 <p>&nbsp;&nbsp;&nbsp;"JACK_BINDINGS: 'ardour:0'"
2023 </p>
2024 <p>&nbsp;&nbsp;&nbsp;"."
2025 </p>
2026 </blockquote><p>
2027
2028 </p>
2029 <a name="GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO"></a><br /><hr />
2030 <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>
2031 <a name="rfc.section.6.2.12"></a><h3>6.2.12.&nbsp;
2032 Getting information about specific audio channel parameter</h3>
2033
2034 <p>Use the following command to get detailed information about specific audio channel parameter:
2035 </p>
2036 <p>
2037 </p>
2038 <blockquote class="text">
2039 <p>GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO &lt;dev-id&gt; &lt;chan&gt; &lt;param&gt;
2040 </p>
2041 </blockquote><p>
2042
2043 </p>
2044 <p>Where &lt;dev-id&gt; is the numerical ID of the audio output device as returned by the
2045 <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>
2046 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>
2047 command, &lt;chan&gt; the audio channel number
2048 and &lt;param&gt; a specific channel parameter name for which information should
2049 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).
2050 </p>
2051 <p>Possible Answers:
2052 </p>
2053 <p>
2054 </p>
2055 <blockquote class="text">
2056 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2057 Each answer line begins with the information category name
2058 followed by a colon and then a space character &lt;SP&gt; and finally
2059 the info character string to that info category. There are
2060 information which is always returned, independently of the
2061 given channel parameter and there is optional information
2062 which is only shown dependently to the given audio channel. At
2063 the moment the following information categories are defined:
2064 </p>
2065 <p>
2066 </p>
2067 <blockquote class="text">
2068 <p>TYPE -
2069 </p>
2070 <blockquote class="text">
2071 <p>either "BOOL" for boolean value(s) or "INT" for integer
2072 value(s) or "FLOAT" for dotted number(s) or "STRING" for
2073 character string(s)
2074 (always returned)
2075 </p>
2076 </blockquote>
2077
2078
2079 <p>DESCRIPTION -
2080 </p>
2081 <blockquote class="text">
2082 <p>arbitrary text describing the purpose of the parameter (always returned)
2083 </p>
2084 </blockquote>
2085
2086
2087 <p>FIX -
2088 </p>
2089 <blockquote class="text">
2090 <p>either true or false, if true then this parameter is
2091 read only, thus cannot be altered
2092 (always returned)
2093 </p>
2094 </blockquote>
2095
2096
2097 <p>MULTIPLICITY -
2098 </p>
2099 <blockquote class="text">
2100 <p>either true or false, defines if this parameter allows
2101 only one value or a list of values, where true means
2102 multiple values and false only a single value allowed
2103 (always returned)
2104 </p>
2105 </blockquote>
2106
2107
2108 <p>RANGE_MIN -
2109 </p>
2110 <blockquote class="text">
2111 <p>defines lower limit of the allowed value range for this
2112 parameter, can be an integer value as well as a dotted
2113 number, usually used in conjunction with 'RANGE_MAX',
2114 but may also appear without
2115 (optionally returned, dependent to driver and channel
2116 parameter)
2117 </p>
2118 </blockquote>
2119
2120
2121 <p>RANGE_MAX -
2122 </p>
2123 <blockquote class="text">
2124 <p>defines upper limit of the allowed value range for this
2125 parameter, can be an integer value as well as a dotted
2126 number, usually used in conjunction with 'RANGE_MIN',
2127 but may also appear without
2128 (optionally returned, dependent to driver and channel
2129 parameter)
2130 </p>
2131 </blockquote>
2132
2133
2134 <p>POSSIBILITIES -
2135 </p>
2136 <blockquote class="text">
2137 <p>comma separated list of possible values for this
2138 parameter, character strings are encapsulated into
2139 apostrophes
2140 (optionally returned, dependent to driver and channel
2141 parameter)
2142 </p>
2143 </blockquote>
2144
2145
2146 </blockquote>
2147
2148
2149 <p>The mentioned fields above don't have to be in particular order.
2150 </p>
2151 </blockquote><p>
2152
2153 </p>
2154 <p>Example:
2155 </p>
2156 <p>
2157 </p>
2158 <blockquote class="text">
2159 <p>C: "GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO 1 0 JACK_BINDINGS"
2160 </p>
2161 <p>S: "DESCRIPTION: bindings to other JACK clients"
2162 </p>
2163 <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
2164 </p>
2165 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
2166 </p>
2167 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"
2168 </p>
2169 <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"
2170 </p>
2171 <p>&nbsp;&nbsp;&nbsp;"."
2172 </p>
2173 </blockquote><p>
2174
2175 </p>
2176 <a name="SET AUDIO_OUTPUT_CHANNEL_PARAMETER"></a><br /><hr />
2177 <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>
2178 <a name="rfc.section.6.2.13"></a><h3>6.2.13.&nbsp;
2179 Changing settings of audio output channels</h3>
2180
2181 <p>Use the following command to alter a specific setting of an audio output channel:
2182 </p>
2183 <p>
2184 </p>
2185 <blockquote class="text">
2186 <p>SET AUDIO_OUTPUT_CHANNEL_PARAMETER &lt;dev-id&gt; &lt;chn&gt; &lt;key&gt;=&lt;value&gt;
2187 </p>
2188 </blockquote><p>
2189
2190 </p>
2191 <p>Where &lt;dev-id&gt; should be replaced by the numerical ID of the audio output device as returned by the
2192 <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>
2193 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>
2194 command, &lt;chn&gt; by the audio channel number, &lt;key&gt; by the name of the
2195 parameter to change and &lt;value&gt; by the new value for this parameter.
2196 </p>
2197 <p>Possible Answers:
2198 </p>
2199 <p>
2200 </p>
2201 <blockquote class="text">
2202 <p>"OK" -
2203 </p>
2204 <blockquote class="text">
2205 <p>in case setting was successfully changed
2206 </p>
2207 </blockquote>
2208
2209
2210 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2211 </p>
2212 <blockquote class="text">
2213 <p>in case setting was changed successfully, but there are
2214 noteworthy issue(s) related, providing an appropriate
2215 warning code and warning message
2216 </p>
2217 </blockquote>
2218
2219
2220 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2221 </p>
2222 <blockquote class="text">
2223 <p>in case it failed, providing an appropriate error code and
2224 error message
2225 </p>
2226 </blockquote>
2227
2228
2229 </blockquote><p>
2230
2231 </p>
2232 <p>Example:
2233 </p>
2234 <p>
2235 </p>
2236 <blockquote class="text">
2237 <p>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"
2238 </p>
2239 <p>S: "OK"
2240 </p>
2241 </blockquote><p>
2242
2243 </p>
2244 <p>
2245 </p>
2246 <blockquote class="text">
2247 <p>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"
2248 </p>
2249 <p>S: "OK"
2250 </p>
2251 </blockquote><p>
2252
2253 </p>
2254 <a name="anchor10"></a><br /><hr />
2255 <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>
2256 <a name="rfc.section.6.3"></a><h3>6.3.&nbsp;
2257 Configuring MIDI input drivers</h3>
2258
2259 <p>Instances of drivers in LinuxSampler are called devices. You can use
2260 multiple MIDI devices simultaneously, e.g. to use MIDI over ethernet as
2261 MIDI input on one sampler channel and ALSA as MIDI input on another sampler
2262 channel. For particular MIDI input systems it's also possible to create
2263 several devices of the same MIDI input type. This chapter describes all
2264 commands to configure LinuxSampler's MIDI input devices and their parameters.
2265 </p>
2266 <p>Instead of defining commands and parameters for each driver individually,
2267 all possible parameters, their meanings and possible values have to be obtained
2268 at runtime. This makes the protocol a bit abstract, but has the advantage, that
2269 front-ends can be written independently of what drivers are currently implemented
2270 and what parameters these drivers are actually offering. This means front-ends can
2271 even handle drivers which are implemented somewhere in future without modifying
2272 the front-end at all.
2273 </p>
2274 <p>Commands for configuring MIDI input devices are pretty much the same as the
2275 commands for configuring audio output drivers, already described in the last
2276 chapter.
2277 </p>
2278 <p>Note: examples in this chapter showing particular parameters of drivers are
2279 not meant as specification of the drivers' parameters. Driver implementations in
2280 LinuxSampler might have complete different parameter names and meanings than shown
2281 in these examples or might change in future, so these examples are only meant for
2282 showing how to retrieve what parameters drivers are offering, how to retrieve their
2283 possible values, etc.
2284 </p>
2285 <a name="GET AVAILABLE_MIDI_INPUT_DRIVERS"></a><br /><hr />
2286 <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>
2287 <a name="rfc.section.6.3.1"></a><h3>6.3.1.&nbsp;
2288 Getting amount of available MIDI input drivers</h3>
2289
2290 <p>Use the following command to get the number of
2291 MIDI input drivers currently available for the
2292 LinuxSampler instance:
2293 </p>
2294 <p>
2295 </p>
2296 <blockquote class="text">
2297 <p>GET AVAILABLE_MIDI_INPUT_DRIVERS
2298 </p>
2299 </blockquote><p>
2300
2301 </p>
2302 <p>Possible Answers:
2303 </p>
2304 <p>
2305 </p>
2306 <blockquote class="text">
2307 <p>LinuxSampler will answer by sending the
2308 number of available MIDI input drivers.
2309 </p>
2310 </blockquote><p>
2311
2312 </p>
2313 <p>Example:
2314 </p>
2315 <p>
2316 </p>
2317 <blockquote class="text">
2318 <p>C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"
2319 </p>
2320 <p>S: "2"
2321 </p>
2322 </blockquote><p>
2323
2324 </p>
2325 <a name="LIST AVAILABLE_MIDI_INPUT_DRIVERS"></a><br /><hr />
2326 <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>
2327 <a name="rfc.section.6.3.2"></a><h3>6.3.2.&nbsp;
2328 Getting all available MIDI input drivers</h3>
2329
2330 <p>Use the following command to list all MIDI input drivers currently available
2331 for the LinuxSampler instance:
2332 </p>
2333 <p>
2334 </p>
2335 <blockquote class="text">
2336 <p>LIST AVAILABLE_MIDI_INPUT_DRIVERS
2337 </p>
2338 </blockquote><p>
2339
2340 </p>
2341 <p>Possible Answers:
2342 </p>
2343 <p>
2344 </p>
2345 <blockquote class="text">
2346 <p>LinuxSampler will answer by sending comma separated character
2347 strings, each symbolizing a MIDI input driver.
2348 </p>
2349 </blockquote><p>
2350
2351 </p>
2352 <p>Example:
2353 </p>
2354 <p>
2355 </p>
2356 <blockquote class="text">
2357 <p>C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
2358 </p>
2359 <p>S: "ALSA,JACK"
2360 </p>
2361 </blockquote><p>
2362
2363 </p>
2364 <a name="GET MIDI_INPUT_DRIVER INFO"></a><br /><hr />
2365 <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>
2366 <a name="rfc.section.6.3.3"></a><h3>6.3.3.&nbsp;
2367 Getting information about a specific MIDI input driver</h3>
2368
2369 <p>Use the following command to get detailed information about a specific MIDI input driver:
2370 </p>
2371 <p>
2372 </p>
2373 <blockquote class="text">
2374 <p>GET MIDI_INPUT_DRIVER INFO &lt;midi-input-driver&gt;
2375 </p>
2376 </blockquote><p>
2377
2378 </p>
2379 <p>Where &lt;midi-input-driver&gt; is the name of the MIDI input driver as returned
2380 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.
2381 </p>
2382 <p>Possible Answers:
2383 </p>
2384 <p>
2385 </p>
2386 <blockquote class="text">
2387 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2388 Each answer line begins with the information category name
2389 followed by a colon and then a space character &lt;SP&gt; and finally
2390 the info character string to that info category. At the moment
2391 the following information categories are defined:
2392 </p>
2393 <p>
2394 </p>
2395 <blockquote class="text">
2396 <p>DESCRIPTION -
2397 </p>
2398 <blockquote class="text">
2399 <p>arbitrary description text about the MIDI input driver
2400 </p>
2401 </blockquote>
2402
2403
2404 <p>VERSION -
2405 </p>
2406 <blockquote class="text">
2407 <p>arbitrary character string regarding the driver's version
2408 </p>
2409 </blockquote>
2410
2411
2412 <p>PARAMETERS -
2413 </p>
2414 <blockquote class="text">
2415 <p>comma separated list of all parameters available for the given MIDI input driver
2416 </p>
2417 </blockquote>
2418
2419
2420 </blockquote>
2421
2422
2423 <p>The mentioned fields above don't have to be in particular order.
2424 </p>
2425 </blockquote><p>
2426
2427 </p>
2428 <p>Example:
2429 </p>
2430 <p>
2431 </p>
2432 <blockquote class="text">
2433 <p>C: "GET MIDI_INPUT_DRIVER INFO ALSA"
2434 </p>
2435 <p>S: "DESCRIPTION: Advanced Linux Sound Architecture"
2436 </p>
2437 <p>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"
2438 </p>
2439 <p>&nbsp;&nbsp;&nbsp;"PARAMETERS: DRIVER,ACTIVE"
2440 </p>
2441 <p>&nbsp;&nbsp;&nbsp;"."
2442 </p>
2443 </blockquote><p>
2444
2445 </p>
2446 <a name="GET MIDI_INPUT_DRIVER_PARAMETER INFO"></a><br /><hr />
2447 <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>
2448 <a name="rfc.section.6.3.4"></a><h3>6.3.4.&nbsp;
2449 Getting information about specific MIDI input driver parameter</h3>
2450
2451 <p>Use the following command to get detailed information about a specific parameter of a specific MIDI input driver:
2452 </p>
2453 <p>
2454 </p>
2455 <blockquote class="text">
2456 <p>GET MIDI_INPUT_DRIVER_PARAMETER INFO &lt;midit&gt; &lt;param&gt; [&lt;deplist&gt;]
2457 </p>
2458 </blockquote><p>
2459
2460 </p>
2461 <p>Where &lt;midit&gt; is the name of the MIDI input driver as returned
2462 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
2463 parameter name for which information should be obtained (as returned by the
2464 <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
2465 of parameters on which the sought parameter &lt;param&gt; depends on,
2466 &lt;deplist&gt; is a key-value pair list in form of "key1=val1 key2=val2 ...",
2467 where character string values are encapsulated into apostrophes ('). Arguments
2468 given with &lt;deplist&gt; which are not dependency parameters of &lt;param&gt;
2469 will be ignored, means the front-end application can simply put all parameters
2470 in &lt;deplist&gt; with the values selected by the user.
2471 </p>
2472 <p>Possible Answers:
2473 </p>
2474 <p>LinuxSampler will answer by sending a &lt;CRLF> separated list.
2475 Each answer line begins with the information category name
2476 followed by a colon and then a space character &lt;SP> and finally
2477 the info character string to that info category. There is
2478 information which is always returned, independent of the
2479 given driver parameter and there is optional information
2480 which is only shown dependent to given driver parameter. At
2481 the moment the following information categories are defined:
2482 </p>
2483 <p>
2484 </p>
2485 <blockquote class="text">
2486 <p>TYPE -
2487 </p>
2488 <blockquote class="text">
2489 <p>either "BOOL" for boolean value(s) or "INT" for integer
2490 value(s) or "FLOAT" for dotted number(s) or "STRING" for
2491 character string(s)
2492 (always returned, no matter which driver parameter)
2493 </p>
2494 </blockquote>
2495
2496
2497 <p>DESCRIPTION -
2498 </p>
2499 <blockquote class="text">
2500 <p>arbitrary text describing the purpose of the parameter
2501 (always returned, no matter which driver parameter)
2502 </p>
2503 </blockquote>
2504
2505
2506 <p>MANDATORY -
2507 </p>
2508 <blockquote class="text">
2509 <p>either true or false, defines if this parameter must be
2510 given when the device is to be created with the
2511 <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
2512 (always returned, no matter which driver parameter)
2513 </p>
2514 </blockquote>
2515
2516
2517 <p>FIX -
2518 </p>
2519 <blockquote class="text">
2520 <p>either true or false, if false then this parameter can
2521 be changed at any time, once the device is created by
2522 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
2523 (always returned, no matter which driver parameter)
2524 </p>
2525 </blockquote>
2526
2527
2528 <p>MULTIPLICITY -
2529 </p>
2530 <blockquote class="text">
2531 <p>either true or false, defines if this parameter allows
2532 only one value or a list of values, where true means
2533 multiple values and false only a single value allowed
2534 (always returned, no matter which driver parameter)
2535 </p>
2536 </blockquote>
2537
2538
2539 <p>DEPENDS -
2540 </p>
2541 <blockquote class="text">
2542 <p>comma separated list of parameters this parameter depends
2543 on, means the values for fields 'DEFAULT', 'RANGE_MIN',
2544 'RANGE_MAX' and 'POSSIBILITIES' might depend on these
2545 listed parameters, for example assuming that an audio
2546 driver (like the ALSA driver) offers parameters 'card'
2547 and 'samplerate' then parameter 'samplerate' would
2548 depend on 'card' because the possible values for
2549 'samplerate' depends on the sound card which can be
2550 chosen by the 'card' parameter
2551 (optionally returned, dependent to driver parameter)
2552 </p>
2553 </blockquote>
2554
2555
2556 <p>DEFAULT -
2557 </p>
2558 <blockquote class="text">
2559 <p>reflects the default value for this parameter which is
2560 used when the device is created and not explicitly
2561 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,
2562 in case of MULTIPLCITY=true, this is a comma separated
2563 list, that's why character strings are encapsulated into
2564 apostrophes (')
2565 (optionally returned, dependent to driver parameter)
2566 </p>
2567 </blockquote>
2568
2569
2570 <p>RANGE_MIN -
2571 </p>
2572 <blockquote class="text">
2573 <p>defines lower limit of the allowed value range for this
2574 parameter, can be an integer value as well as a dotted
2575 number, this parameter is often used in conjunction
2576 with RANGE_MAX, but may also appear without
2577 (optionally returned, dependent to driver parameter)
2578 </p>
2579 </blockquote>
2580
2581
2582 <p>RANGE_MAX -
2583 </p>
2584 <blockquote class="text">
2585 <p>defines upper limit of the allowed value range for this
2586 parameter, can be an integer value as well as a dotted
2587 number, this parameter is often used in conjunction with
2588 RANGE_MIN, but may also appear without
2589 (optionally returned, dependent to driver parameter)
2590 </p>
2591 </blockquote>
2592
2593
2594 <p>POSSIBILITIES -
2595 </p>
2596 <blockquote class="text">
2597 <p>comma separated list of possible values for this
2598 parameter, character strings are encapsulated into
2599 apostrophes
2600 (optionally returned, dependent to driver parameter)
2601 </p>
2602 </blockquote>
2603
2604
2605 </blockquote><p>
2606
2607 </p>
2608 <p>The mentioned fields above don't have to be in particular order.
2609 </p>
2610 <p>Example:
2611 </p>
2612 <p>
2613 </p>
2614 <blockquote class="text">
2615 <p>C: "GET MIDI_INPUT_DRIVER_PARAMETER INFO ALSA ACTIVE"
2616 </p>
2617 <p>S: "DESCRIPTION: Whether device is enabled"
2618 </p>
2619 <p>&nbsp;&nbsp;&nbsp;"TYPE: BOOL"
2620 </p>
2621 <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
2622 </p>
2623 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
2624 </p>
2625 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
2626 </p>
2627 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: true"
2628 </p>
2629 <p>&nbsp;&nbsp;&nbsp;"."
2630 </p>
2631 </blockquote><p>
2632
2633 </p>
2634 <a name="CREATE MIDI_INPUT_DEVICE"></a><br /><hr />
2635 <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>
2636 <a name="rfc.section.6.3.5"></a><h3>6.3.5.&nbsp;
2637 Creating a MIDI input device</h3>
2638
2639 <p>Use the following command to create a new MIDI input device for the desired MIDI input system:
2640 </p>
2641 <p>
2642 </p>
2643 <blockquote class="text">
2644 <p>CREATE MIDI_INPUT_DEVICE &lt;midi-input-driver&gt; [&lt;param-list&gt;]
2645 </p>
2646 </blockquote><p>
2647
2648 </p>
2649 <p>Where &lt;midi-input-driver&gt; should be replaced by the desired MIDI input system as returned
2650 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
2651 optional list of driver specific parameters in form of "key1=val1 key2=val2 ...", where
2652 character string values should be encapsulated into apostrophes (').
2653 Note that there might be drivers which require parameter(s) to be
2654 given with this command. Use the previously described commands in
2655 this chapter to get that information.
2656 </p>
2657 <p>Possible Answers:
2658 </p>
2659 <p>
2660 </p>
2661 <blockquote class="text">
2662 <p>"OK[&lt;device-id&gt;]" -
2663 </p>
2664 <blockquote class="text">
2665 <p>in case the device was successfully created, where
2666 &lt;device-id&gt; is the numerical ID of the new device
2667 </p>
2668 </blockquote>
2669
2670
2671 <p>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2672 </p>
2673 <blockquote class="text">
2674 <p>in case the driver was loaded successfully, where
2675 &lt;device-id&gt; is the numerical ID of the new device, but
2676 there are noteworthy issue(s) related, providing an
2677 appropriate warning code and warning message
2678 </p>
2679 </blockquote>
2680
2681
2682 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2683 </p>
2684 <blockquote class="text">
2685 <p>in case it failed, providing an appropriate error code and error message
2686 </p>
2687 </blockquote>
2688
2689
2690 </blockquote><p>
2691
2692 </p>
2693 <p>Example:
2694 </p>
2695 <p>
2696 </p>
2697 <blockquote class="text">
2698 <p>C: "CREATE MIDI_INPUT_DEVICE ALSA"
2699 </p>
2700 <p>S: "OK[0]"
2701 </p>
2702 </blockquote><p>
2703
2704 </p>
2705 <a name="DESTROY MIDI_INPUT_DEVICE"></a><br /><hr />
2706 <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>
2707 <a name="rfc.section.6.3.6"></a><h3>6.3.6.&nbsp;
2708 Destroying a MIDI input device</h3>
2709
2710 <p>Use the following command to destroy a created MIDI input device:
2711 </p>
2712 <p>
2713 </p>
2714 <blockquote class="text">
2715 <p>DESTROY MIDI_INPUT_DEVICE &lt;device-id&gt;
2716 </p>
2717 </blockquote><p>
2718
2719 </p>
2720 <p>Where &lt;device-id&gt; should be replaced by the device's numerical ID as returned by the
2721 <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>
2722 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>
2723 command.
2724 </p>
2725 <p>Possible Answers:
2726 </p>
2727 <p>
2728 </p>
2729 <blockquote class="text">
2730 <p>"OK" -
2731 </p>
2732 <blockquote class="text">
2733 <p>in case the device was successfully destroyed
2734 </p>
2735 </blockquote>
2736
2737
2738 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2739 </p>
2740 <blockquote class="text">
2741 <p>in case the device was destroyed, but there are noteworthy
2742 issue(s) related, providing an appropriate warning code and
2743 warning message
2744 </p>
2745 </blockquote>
2746
2747
2748 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2749 </p>
2750 <blockquote class="text">
2751 <p>in case it failed, providing an appropriate error code and error message
2752 </p>
2753 </blockquote>
2754
2755
2756 </blockquote><p>
2757
2758 </p>
2759 <p>Example:
2760 </p>
2761 <p>
2762 </p>
2763 <blockquote class="text">
2764 <p>C: "DESTROY MIDI_INPUT_DEVICE 0"
2765 </p>
2766 <p>S: "OK"
2767 </p>
2768 </blockquote><p>
2769
2770 </p>
2771 <a name="GET MIDI_INPUT_DEVICES"></a><br /><hr />
2772 <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>
2773 <a name="rfc.section.6.3.7"></a><h3>6.3.7.&nbsp;
2774 Getting all created MIDI input device count</h3>
2775
2776 <p>Use the following command to count all created MIDI input devices:
2777 </p>
2778 <p>
2779 </p>
2780 <blockquote class="text">
2781 <p>GET MIDI_INPUT_DEVICES
2782 </p>
2783 </blockquote><p>
2784
2785 </p>
2786 <p>Possible Answers:
2787 </p>
2788 <p>
2789 </p>
2790 <blockquote class="text">
2791 <p>LinuxSampler will answer by sending the current number of all
2792 MIDI input devices.
2793 </p>
2794 </blockquote><p>
2795
2796 </p>
2797 <p>Example:
2798 </p>
2799 <p>
2800 </p>
2801 <blockquote class="text">
2802 <p>C: "GET MIDI_INPUT_DEVICES"
2803 </p>
2804 <p>S: "3"
2805 </p>
2806 </blockquote><p>
2807
2808 </p>
2809 <a name="LIST MIDI_INPUT_DEVICES"></a><br /><hr />
2810 <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>
2811 <a name="rfc.section.6.3.8"></a><h3>6.3.8.&nbsp;
2812 Getting all created MIDI input device list</h3>
2813
2814 <p>Use the following command to list all created MIDI input devices:
2815 </p>
2816 <p>
2817 </p>
2818 <blockquote class="text">
2819 <p>LIST MIDI_INPUT_DEVICES
2820 </p>
2821 </blockquote><p>
2822
2823 </p>
2824 <p>Possible Answers:
2825 </p>
2826 <p>
2827 </p>
2828 <blockquote class="text">
2829 <p>LinuxSampler will answer by sending a comma separated list
2830 with the numerical Ids of all created MIDI input devices.
2831 </p>
2832 </blockquote><p>
2833
2834 </p>
2835 <p>Examples:
2836 </p>
2837 <p>
2838 </p>
2839 <blockquote class="text">
2840 <p>C: "LIST MIDI_INPUT_DEVICES"
2841 </p>
2842 <p>S: "0,1,2"
2843 </p>
2844 </blockquote><p>
2845
2846 </p>
2847 <p>
2848 </p>
2849 <blockquote class="text">
2850 <p>C: "LIST MIDI_INPUT_DEVICES"
2851 </p>
2852 <p>S: "1,3"
2853 </p>
2854 </blockquote><p>
2855
2856 </p>
2857 <a name="GET MIDI_INPUT_DEVICE INFO"></a><br /><hr />
2858 <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>
2859 <a name="rfc.section.6.3.9"></a><h3>6.3.9.&nbsp;
2860 Getting current settings of a MIDI input device</h3>
2861
2862 <p>Use the following command to get current settings of a specific, created MIDI input device:
2863 </p>
2864 <p>
2865 </p>
2866 <blockquote class="text">
2867 <p>GET MIDI_INPUT_DEVICE INFO &lt;device-id&gt;
2868 </p>
2869 </blockquote><p>
2870
2871 </p>
2872 <p>Where &lt;device-id&gt; is the numerical ID of the MIDI input device as returned by the
2873 <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>
2874 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>
2875 command.
2876 </p>
2877 <p>Possible Answers:
2878 </p>
2879 <p>
2880 </p>
2881 <blockquote class="text">
2882 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2883 Each answer line begins with the information category name
2884 followed by a colon and then a space character &lt;SP&gt; and finally
2885 the info character string to that info category. As some
2886 parameters might allow multiple values, character strings are
2887 encapsulated into apostrophes ('). At the moment the following
2888 information categories are defined (independent of driver):
2889 </p>
2890 <p>
2891 </p>
2892 <blockquote class="text">
2893 <p>DRIVER -
2894 </p>
2895 <blockquote class="text">
2896 <p>identifier of the used MIDI input driver, as e.g.
2897 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>
2898 command
2899 </p>
2900 </blockquote>
2901
2902
2903 </blockquote>
2904
2905 <blockquote class="text">
2906 <p>ACTIVE -
2907 </p>
2908 <blockquote class="text">
2909 <p>either true or false, if false then the MIDI device is
2910 inactive and doesn't listen to any incoming MIDI events
2911 and thus doesn't forward them to connected sampler
2912 channels
2913 </p>
2914 </blockquote>
2915
2916
2917 </blockquote>
2918
2919
2920 </blockquote><p>
2921
2922 </p>
2923 <p>The mentioned fields above don't have to be in particular
2924 order. The fields above are only those fields which are
2925 returned by all MIDI input devices. Every MIDI input driver
2926 might have its own, additional driver specific parameters (see
2927 <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
2928 by this command.
2929 </p>
2930 <p>Example:
2931 </p>
2932 <p>
2933 </p>
2934 <blockquote class="text">
2935 <p>C: "GET MIDI_INPUT_DEVICE INFO 0"
2936 </p>
2937 <p>S: "DRIVER: ALSA"
2938 </p>
2939 <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
2940 </p>
2941 <p>&nbsp;&nbsp;&nbsp;"."
2942 </p>
2943 </blockquote><p>
2944
2945 </p>
2946 <a name="SET MIDI_INPUT_DEVICE_PARAMETER"></a><br /><hr />
2947 <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>
2948 <a name="rfc.section.6.3.10"></a><h3>6.3.10.&nbsp;
2949 Changing settings of MIDI input devices</h3>
2950
2951 <p>Use the following command to alter a specific setting of a created MIDI input device:
2952 </p>
2953 <p>
2954 </p>
2955 <blockquote class="text">
2956 <p>SET MIDI_INPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;
2957 </p>
2958 </blockquote><p>
2959
2960 </p>
2961 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
2962 MIDI input device as returned by the
2963 <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>
2964 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>
2965 command, &lt;key&gt; by the name of the parameter to change and
2966 &lt;value&gt; by the new value for this parameter.
2967 </p>
2968 <p>Possible Answers:
2969 </p>
2970 <p>
2971 </p>
2972 <blockquote class="text">
2973 <p>"OK" -
2974 </p>
2975 <blockquote class="text">
2976 <p>in case setting was successfully changed
2977 </p>
2978 </blockquote>
2979
2980
2981 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2982 </p>
2983 <blockquote class="text">
2984 <p>in case setting was changed successfully, but there are
2985 noteworthy issue(s) related, providing an appropriate
2986 warning code and warning message
2987 </p>
2988 </blockquote>
2989
2990
2991 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2992 </p>
2993 <blockquote class="text">
2994 <p>in case it failed, providing an appropriate error code and error message
2995 </p>
2996 </blockquote>
2997
2998
2999 </blockquote><p>
3000
3001 </p>
3002 <p>Example:
3003 </p>
3004 <p>
3005 </p>
3006 <blockquote class="text">
3007 <p>C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"
3008 </p>
3009 <p>S: "OK"
3010 </p>
3011 </blockquote><p>
3012
3013 </p>
3014 <a name="GET MIDI_INPUT_PORT INFO"></a><br /><hr />
3015 <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>
3016 <a name="rfc.section.6.3.11"></a><h3>6.3.11.&nbsp;
3017 Getting information about a MIDI port</h3>
3018
3019 <p>Use the following command to get information about a MIDI port:
3020 </p>
3021 <p>
3022 </p>
3023 <blockquote class="text">
3024 <p>GET MIDI_INPUT_PORT INFO &lt;device-id&gt; &lt;midi-port&gt;
3025 </p>
3026 </blockquote><p>
3027
3028 </p>
3029 <p>Where &lt;device-id&gt; is the numerical ID of the MIDI input device as returned by the
3030 <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>
3031 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>
3032 command and &lt;midi-port&gt; the MIDI input port number.
3033 </p>
3034 <p>Possible Answers:
3035 </p>
3036 <p>
3037 </p>
3038 <blockquote class="text">
3039 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3040 Each answer line begins with the information category name
3041 followed by a colon and then a space character &lt;SP&gt; and finally
3042 the info character string to that info category. At the moment
3043 the following information categories are defined:
3044 </p>
3045 <p>NAME -
3046 </p>
3047 <blockquote class="text">
3048 <p>arbitrary character string naming the port
3049 </p>
3050 </blockquote>
3051
3052
3053 </blockquote><p>
3054
3055 </p>
3056 <p>The field above is only the one which is returned by all MIDI
3057 ports regardless of the MIDI driver and port. Every MIDI port
3058 might have its own, additional driver and port specific
3059 parameters.
3060 </p>
3061 <p>Example:
3062 </p>
3063 <p>
3064 </p>
3065 <blockquote class="text">
3066 <p>C: "GET MIDI_INPUT_PORT INFO 0 0"
3067 </p>
3068 <p>S: "NAME: 'Masterkeyboard'"
3069 </p>
3070 <p>&nbsp;&nbsp;&nbsp;"ALSA_SEQ_BINDINGS: '64:0'"
3071 </p>
3072 <p>&nbsp;&nbsp;&nbsp;"."
3073 </p>
3074 </blockquote><p>
3075
3076 </p>
3077 <a name="GET MIDI_INPUT_PORT_PARAMETER INFO"></a><br /><hr />
3078 <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>
3079 <a name="rfc.section.6.3.12"></a><h3>6.3.12.&nbsp;
3080 Getting information about specific MIDI port parameter</h3>
3081
3082 <p>Use the following command to get detailed information about specific MIDI port parameter:
3083 </p>
3084 <p>
3085 </p>
3086 <blockquote class="text">
3087 <p>GET MIDI_INPUT_PORT_PARAMETER INFO &lt;dev-id&gt; &lt;port&gt; &lt;param&gt;
3088 </p>
3089 </blockquote><p>
3090
3091 </p>
3092 <p>Where &lt;dev-id&gt; is the numerical ID of the MIDI input device as returned by the
3093 <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>
3094 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>
3095 command, &lt;port&gt; the MIDI port number and
3096 &lt;param&gt; a specific port parameter name for which information should be
3097 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).
3098 </p>
3099 <p>Possible Answers:
3100 </p>
3101 <p>
3102 </p>
3103 <blockquote class="text">
3104 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3105 Each answer line begins with the information category name
3106 followed by a colon and then a space character &lt;SP&gt; and finally
3107 the info character string to that info category. There is
3108 information which is always returned, independently of the
3109 given channel parameter and there is optional information
3110 which are only shown dependently to the given MIDI port. At the
3111 moment the following information categories are defined:
3112 </p>
3113 <p>TYPE -
3114 </p>
3115 <blockquote class="text">
3116 <p>either "BOOL" for boolean value(s) or "INT" for integer
3117 value(s) or "FLOAT" for dotted number(s) or "STRING" for
3118 character string(s)
3119 (always returned)
3120 </p>
3121 </blockquote>
3122
3123
3124 <p>DESCRIPTION -
3125 </p>
3126 <blockquote class="text">
3127 <p>arbitrary text describing the purpose of the parameter
3128 (always returned)
3129 </p>
3130 </blockquote>
3131
3132
3133 <p>FIX -
3134 </p>
3135 <blockquote class="text">
3136 <p>either true or false, if true then this parameter is
3137 read only, thus cannot be altered
3138 (always returned)
3139 </p>
3140 </blockquote>
3141
3142
3143 <p>MULTIPLICITY -
3144 </p>
3145 <blockquote class="text">
3146 <p>either true or false, defines if this parameter allows
3147 only one value or a list of values, where true means
3148 multiple values and false only a single value allowed
3149 (always returned)
3150 </p>
3151 </blockquote>
3152
3153
3154 <p>RANGE_MIN -
3155 </p>
3156 <blockquote class="text">
3157 <p>defines lower limit of the allowed value range for this
3158 parameter, can be an integer value as well as a dotted
3159 number, this parameter is usually used in conjunction
3160 with 'RANGE_MAX' but may also appear without
3161 (optionally returned, dependent to driver and port
3162 parameter)
3163 </p>
3164 </blockquote>
3165
3166
3167 <p>RANGE_MAX -
3168 </p>
3169 <blockquote class="text">
3170 <p>defines upper limit of the allowed value range for this
3171 parameter, can be an integer value as well as a dotted
3172 number, this parameter is usually used in conjunction
3173 with 'RANGE_MIN' but may also appear without
3174 (optionally returned, dependent to driver and port
3175 parameter)
3176 </p>
3177 </blockquote>
3178
3179
3180 <p>POSSIBILITIES -
3181 </p>
3182 <blockquote class="text">
3183 <p>comma separated list of possible values for this
3184 parameter, character strings are encapsulated into
3185 apostrophes
3186 (optionally returned, dependent to device and port
3187 parameter)
3188 </p>
3189 </blockquote>
3190
3191
3192 </blockquote><p>
3193
3194 </p>
3195 <p>The mentioned fields above don't have to be in particular order.
3196 </p>
3197 <p>Example:
3198 </p>
3199 <p>
3200 </p>
3201 <blockquote class="text">
3202 <p>C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"
3203 </p>
3204 <p>S: "DESCRIPTION: bindings to other ALSA sequencer clients"
3205 </p>
3206 <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
3207 </p>
3208 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
3209 </p>
3210 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"
3211 </p>
3212 <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: '64:0','68:0','68:1'"
3213 </p>
3214 <p>&nbsp;&nbsp;&nbsp;"."
3215 </p>
3216 </blockquote><p>
3217
3218 </p>
3219 <a name="SET MIDI_INPUT_PORT_PARAMETER"></a><br /><hr />
3220 <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>
3221 <a name="rfc.section.6.3.13"></a><h3>6.3.13.&nbsp;
3222 Changing settings of MIDI input ports</h3>
3223
3224 <p>Use the following command to alter a specific setting of a MIDI input port:
3225 </p>
3226 <p>
3227 </p>
3228 <blockquote class="text">
3229 <p>SET MIDI_INPUT_PORT_PARAMETER &lt;device-id&gt; &lt;port&gt; &lt;key&gt;=&lt;value&gt;
3230 </p>
3231 </blockquote><p>
3232
3233 </p>
3234 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
3235 MIDI device as returned by the
3236 <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>
3237 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>
3238 command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of
3239 the parameter to change and &lt;value&gt; by the new value for this
3240 parameter.
3241 </p>
3242 <p>Possible Answers:
3243 </p>
3244 <p>
3245 </p>
3246 <blockquote class="text">
3247 <p>"OK" -
3248 </p>
3249 <blockquote class="text">
3250 <p>in case setting was successfully changed
3251 </p>
3252 </blockquote>
3253
3254
3255 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3256 </p>
3257 <blockquote class="text">
3258 <p>in case setting was changed successfully, but there are
3259 noteworthy issue(s) related, providing an appropriate
3260 warning code and warning message
3261 </p>
3262 </blockquote>
3263
3264
3265 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3266 </p>
3267 <blockquote class="text">
3268 <p>in case it failed, providing an appropriate error code and error message
3269 </p>
3270 </blockquote>
3271
3272
3273 </blockquote><p>
3274
3275 </p>
3276 <p>Example:
3277 </p>
3278 <p>
3279 </p>
3280 <blockquote class="text">
3281 <p>
3282 </p>
3283 </blockquote><p>
3284
3285 </p>
3286 <a name="anchor11"></a><br /><hr />
3287 <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>
3288 <a name="rfc.section.6.4"></a><h3>6.4.&nbsp;
3289 Configuring sampler channels</h3>
3290
3291 <p>The following commands describe how to add and remove sampler channels, associate a
3292 sampler channel with a sampler engine, load instruments and connect sampler channels to
3293 MIDI and audio devices.
3294 </p>
3295 <a name="LOAD INSTRUMENT"></a><br /><hr />
3296 <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>
3297 <a name="rfc.section.6.4.1"></a><h3>6.4.1.&nbsp;
3298 Loading an instrument</h3>
3299
3300 <p>An instrument file can be loaded and assigned to a sampler channel by one of the following commands:
3301 </p>
3302 <p>
3303 </p>
3304 <blockquote class="text">
3305 <p>LOAD INSTRUMENT [NON_MODAL] '&lt;filename&gt;' &lt;instr-index&gt; &lt;sampler-channel&gt;
3306 </p>
3307 </blockquote><p>
3308
3309 </p>
3310 <p>Where &lt;filename&gt; is the name of the instrument file on the
3311 LinuxSampler instance's host system, &lt;instr-index&gt; the index of the
3312 instrument in the instrument file and &lt;sampler-channel> is the
3313 number of the sampler channel the instrument should be assigned to.
3314 Each sampler channel can only have one instrument.
3315 </p>
3316 <p>The difference between regular and NON_MODAL versions of the command
3317 is that the regular command returns OK only after the instrument has been
3318 fully loaded and the channel is ready to be used while NON_MODAL version
3319 returns immediately and a background process is launched to load the instrument
3320 on the channel. The <a class='info' href='#GET CHANNEL INFO'>GET CHANNEL INFO<span> (</span><span class='info'>Getting sampler channel information</span><span>)</span></a>
3321 command can be used to obtain loading
3322 progress from INSTRUMENT_STATUS field. LOAD command will perform sanity checks
3323 such as making sure that the file could be read and it is of a proper format
3324 and SHOULD return ERR and SHOULD not launch the background process should any
3325 errors be detected at that point.
3326 </p>
3327 <p>Possible Answers:
3328 </p>
3329 <p>
3330 </p>
3331 <blockquote class="text">
3332 <p>"OK" -
3333 </p>
3334 <blockquote class="text">
3335 <p>in case the instrument was successfully loaded
3336 </p>
3337 </blockquote>
3338
3339
3340 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3341 </p>
3342 <blockquote class="text">
3343 <p>in case the instrument was loaded successfully, but there
3344 are noteworthy issue(s) related (e.g. Engine doesn't support
3345 one or more patch parameters provided by the loaded
3346 instrument file), providing an appropriate warning code and
3347 warning message
3348 </p>
3349 </blockquote>
3350
3351
3352 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3353 </p>
3354 <blockquote class="text">
3355 <p>in case it failed, providing an appropriate error code and error message
3356 </p>
3357 </blockquote>
3358
3359
3360 </blockquote><p>
3361
3362 </p>
3363 <p>Example:
3364 </p>
3365 <p>
3366 </p>
3367 <blockquote class="text">
3368 <p>
3369 </p>
3370 </blockquote><p>
3371
3372 </p>
3373 <a name="LOAD ENGINE"></a><br /><hr />
3374 <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>
3375 <a name="rfc.section.6.4.2"></a><h3>6.4.2.&nbsp;
3376 Loading a sampler engine</h3>
3377
3378 <p>A sampler engine type can be associated to a specific sampler
3379 channel by the following command:
3380 </p>
3381 <p>
3382 </p>
3383 <blockquote class="text">
3384 <p>LOAD ENGINE &lt;engine-name&gt; &lt;sampler-channel&gt;
3385 </p>
3386 </blockquote><p>
3387
3388 </p>
3389 <p>Where &lt;engine-name&gt; is an engine name as obtained by the
3390 <a class='info' href='#LIST AVAILABLE_ENGINES'>"LIST AVAILABLE_ENGINES"<span> (</span><span class='info'>Getting all available engines</span><span>)</span></a> command and &lt;sampler-channel&gt;
3391 the sampler channel as returned by the
3392 <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a> or
3393 <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command where
3394 the engine type should be assigned to. This command should be issued
3395 after adding a new sampler channel and before any other control
3396 commands on the new sampler channel. It can also be used to change
3397 the engine type of a sampler channel. This command has (currently) no
3398 way to define or force if a new engine instance should be created and
3399 assigned to the given sampler channel or if an already existing
3400 instance of that engine type, shared with other sampler channels,
3401 should be used.
3402 </p>
3403 <p>Possible Answers:
3404 </p>
3405 <p>
3406 </p>
3407 <blockquote class="text">
3408 <p>"OK" -
3409 </p>
3410 <blockquote class="text">
3411 <p>in case the engine was successfully deployed
3412 </p>
3413 </blockquote>
3414
3415
3416 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3417 </p>
3418 <blockquote class="text">
3419 <p>in case the engine was deployed successfully, but there
3420 are noteworthy issue(s) related, providing an appropriate
3421 warning code and warning message
3422 </p>
3423 </blockquote>
3424
3425
3426 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3427 </p>
3428 <blockquote class="text">
3429 <p>in case it failed, providing an appropriate error code and
3430 error message
3431 </p>
3432 </blockquote>
3433
3434
3435 </blockquote><p>
3436
3437 </p>
3438 <p>Example:
3439 </p>
3440 <p>
3441 </p>
3442 <blockquote class="text">
3443 <p>
3444 </p>
3445 </blockquote><p>
3446
3447 </p>
3448 <a name="GET CHANNELS"></a><br /><hr />
3449 <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>
3450 <a name="rfc.section.6.4.3"></a><h3>6.4.3.&nbsp;
3451 Getting all created sampler channel count</h3>
3452
3453 <p>The number of sampler channels can change on runtime. To get the
3454 current amount of sampler channels, the front-end can send the
3455 following command:
3456 </p>
3457 <p>
3458 </p>
3459 <blockquote class="text">
3460 <p>GET CHANNELS
3461 </p>
3462 </blockquote><p>
3463
3464 </p>
3465 <p>Possible Answers:
3466 </p>
3467 <p>
3468 </p>
3469 <blockquote class="text">
3470 <p>LinuxSampler will answer by returning the current number of sampler channels.
3471 </p>
3472 </blockquote><p>
3473
3474 </p>
3475 <p>Example:
3476 </p>
3477 <p>
3478 </p>
3479 <blockquote class="text">
3480 <p>C: "GET CHANNELS"
3481 </p>
3482 <p>S: "12"
3483 </p>
3484 </blockquote><p>
3485
3486 </p>
3487 <a name="LIST CHANNELS"></a><br /><hr />
3488 <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>
3489 <a name="rfc.section.6.4.4"></a><h3>6.4.4.&nbsp;
3490 Getting all created sampler channel list</h3>
3491
3492 <p>The number of sampler channels can change on runtime. To get the
3493 current list of sampler channels, the front-end can send the
3494 following command:
3495 </p>
3496 <p>
3497 </p>
3498 <blockquote class="text">
3499 <p>LIST CHANNELS
3500 </p>
3501 </blockquote><p>
3502
3503 </p>
3504 <p>Possible Answers:
3505 </p>
3506 <p>
3507 </p>
3508 <blockquote class="text">
3509 <p>LinuxSampler will answer by returning a comma separated list
3510 with all sampler channels numerical IDs.
3511 </p>
3512 </blockquote><p>
3513
3514 </p>
3515 <p>Example:
3516 </p>
3517 <p>
3518 </p>
3519 <blockquote class="text">
3520 <p>C: "LIST CHANNELS"
3521 </p>
3522 <p>S: "0,1,2,3,4,5,6,9,10,11,15,20"
3523 </p>
3524 </blockquote><p>
3525
3526 </p>
3527 <a name="ADD CHANNEL"></a><br /><hr />
3528 <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>
3529 <a name="rfc.section.6.4.5"></a><h3>6.4.5.&nbsp;
3530 Adding a new sampler channel</h3>
3531
3532 <p>A new sampler channel can be added to the end of the sampler
3533 channel list by sending the following command:
3534 </p>
3535 <p>
3536 </p>
3537 <blockquote class="text">
3538 <p>ADD CHANNEL
3539 </p>
3540 </blockquote><p>
3541
3542 </p>
3543 <p>This will increment the sampler channel count by one and the new
3544 sampler channel will be appended to the end of the sampler channel
3545 list. The front-end should send the respective, related commands
3546 right after to e.g. load an engine, load an instrument and setting
3547 input, output method and eventually other commands to initialize
3548 the new channel. The front-end should use the sampler channel
3549 returned by the answer of this command to perform the previously
3550 recommended commands, to avoid race conditions e.g. with other
3551 front-ends that might also have sent an "ADD CHANNEL" command.
3552 </p>
3553 <p>Possible Answers:
3554 </p>
3555 <p>
3556 </p>
3557 <blockquote class="text">
3558 <p>"OK[&lt;sampler-channel&gt;]" -
3559 </p>
3560 <blockquote class="text">
3561 <p>in case a new sampler channel could be added, where
3562 &lt;sampler-channel&gt; reflects the channel number of the new
3563 created sampler channel which should be used to set up
3564 the sampler channel by sending subsequent initialization
3565 commands
3566 </p>
3567 </blockquote>
3568
3569
3570 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3571 </p>
3572 <blockquote class="text">
3573 <p>in case a new channel was added successfully, but there are
3574 noteworthy issue(s) related, providing an appropriate
3575 warning code and warning message
3576 </p>
3577 </blockquote>
3578
3579
3580 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3581 </p>
3582 <blockquote class="text">
3583 <p>in case it failed, providing an appropriate error code and
3584 error message
3585 </p>
3586 </blockquote>
3587
3588
3589 </blockquote><p>
3590
3591 </p>
3592 <p>Example:
3593 </p>
3594 <p>
3595 </p>
3596 <blockquote class="text">
3597 <p>
3598 </p>
3599 </blockquote><p>
3600
3601 </p>
3602 <a name="REMOVE CHANNEL"></a><br /><hr />
3603 <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>
3604 <a name="rfc.section.6.4.6"></a><h3>6.4.6.&nbsp;
3605 Removing a sampler channel</h3>
3606
3607 <p>A sampler channel can be removed by sending the following command:
3608 </p>
3609 <p>
3610 </p>
3611 <blockquote class="text">
3612 <p>REMOVE CHANNEL &lt;sampler-channel&gt;
3613 </p>
3614 </blockquote><p>
3615
3616 </p>
3617 <p>Where &lt;sampler-channel&gt; should be replaced by the
3618 number of the sampler channel as given by the
3619 <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
3620 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a>
3621 command. The channel numbers of all subsequent sampler channels
3622 remain the same.
3623 </p>
3624 <p>Possible Answers:
3625 </p>
3626 <p>
3627 </p>
3628 <blockquote class="text">
3629 <p>"OK" -
3630 </p>
3631 <blockquote class="text">
3632 <p>in case the given sampler channel could be removed
3633 </p>
3634 </blockquote>
3635
3636
3637 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3638 </p>
3639 <blockquote class="text">
3640 <p>in case the given channel was removed, but there are
3641 noteworthy issue(s) related, providing an appropriate
3642 warning code and warning message
3643 </p>
3644 </blockquote>
3645
3646
3647 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3648 </p>
3649 <blockquote class="text">
3650 <p>in case it failed, providing an appropriate error code and
3651 error message
3652 </p>
3653 </blockquote>
3654
3655
3656 </blockquote><p>
3657
3658 </p>
3659 <p>Example:
3660 </p>
3661 <p>
3662 </p>
3663 <blockquote class="text">
3664 <p>
3665 </p>
3666 </blockquote><p>
3667
3668 </p>
3669 <a name="GET AVAILABLE_ENGINES"></a><br /><hr />
3670 <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>
3671 <a name="rfc.section.6.4.7"></a><h3>6.4.7.&nbsp;
3672 Getting amount of available engines</h3>
3673
3674 <p>The front-end can ask for the number of available engines by sending the following command:
3675 </p>
3676 <p>
3677 </p>
3678 <blockquote class="text">
3679 <p>GET AVAILABLE_ENGINES
3680 </p>
3681 </blockquote><p>
3682
3683 </p>
3684 <p>Possible Answers:
3685 </p>
3686 <p>
3687 </p>
3688 <blockquote class="text">
3689 <p>LinuxSampler will answer by sending the number of available engines.
3690 </p>
3691 </blockquote><p>
3692
3693 </p>
3694 <p>Example:
3695 </p>
3696 <p>
3697 </p>
3698 <blockquote class="text">
3699 <p>C: "GET AVAILABLE_ENGINES"
3700 </p>
3701 <p>S: "4"
3702 </p>
3703 </blockquote><p>
3704
3705 </p>
3706 <a name="LIST AVAILABLE_ENGINES"></a><br /><hr />
3707 <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>
3708 <a name="rfc.section.6.4.8"></a><h3>6.4.8.&nbsp;
3709 Getting all available engines</h3>
3710
3711 <p>The front-end can ask for a list of all available engines by sending the following command:
3712 </p>
3713 <p>
3714 </p>
3715 <blockquote class="text">
3716 <p>LIST AVAILABLE_ENGINES
3717 </p>
3718 </blockquote><p>
3719
3720 </p>
3721 <p>Possible Answers:
3722 </p>
3723 <p>
3724 </p>
3725 <blockquote class="text">
3726 <p>LinuxSampler will answer by sending a comma separated list
3727 of the engines' names encapsulated into apostrophes (').
3728 Engine names can consist of lower and upper cases,
3729 digits and underlines ("_" character).
3730 </p>
3731 </blockquote><p>
3732
3733 </p>
3734 <p>Example:
3735 </p>
3736 <p>
3737 </p>
3738 <blockquote class="text">
3739 <p>C: "LIST AVAILABLE_ENGINES"
3740 </p>
3741 <p>S: "'GigEngine','AkaiEngine','DLSEngine','JoesCustomEngine'"
3742 </p>
3743 </blockquote><p>
3744
3745 </p>
3746 <a name="GET ENGINE INFO"></a><br /><hr />
3747 <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>
3748 <a name="rfc.section.6.4.9"></a><h3>6.4.9.&nbsp;
3749 Getting information about an engine</h3>
3750
3751 <p>The front-end can ask for information about a specific engine by
3752 sending the following command:
3753 </p>
3754 <p>
3755 </p>
3756 <blockquote class="text">
3757 <p>GET ENGINE INFO &lt;engine-name&gt;
3758 </p>
3759 </blockquote><p>
3760
3761 </p>
3762 <p>Where &lt;engine-name&gt; is an engine name as obtained by the
3763 <a class='info' href='#LIST AVAILABLE_ENGINES'>"LIST AVAILABLE_ENGINES"<span> (</span><span class='info'>Getting all available engines</span><span>)</span></a> command.
3764 </p>
3765 <p>Possible Answers:
3766 </p>
3767 <p>
3768 </p>
3769 <blockquote class="text">
3770 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3771 Each answer line begins with the information category name
3772 followed by a colon and then a space character &lt;SP&gt; and finally
3773 the info character string to that info category. At the moment
3774 the following categories are defined:
3775 </p>
3776 <p>
3777 </p>
3778 <blockquote class="text">
3779 <p>DESCRIPTION -
3780 </p>
3781 <blockquote class="text">
3782 <p>arbitrary description text about the engine
3783 </p>
3784 </blockquote>
3785
3786
3787 <p>VERSION -
3788 </p>
3789 <blockquote class="text">
3790 <p>arbitrary character string regarding the engine's version
3791 </p>
3792 </blockquote>
3793
3794
3795 </blockquote>
3796
3797
3798 </blockquote><p>
3799
3800 </p>
3801 <p>The mentioned fields above don't have to be in particular order.
3802 </p>
3803 <p>Example:
3804 </p>
3805 <p>
3806 </p>
3807 <blockquote class="text">
3808 <p>C: "GET ENGINE INFO JoesCustomEngine"
3809 </p>
3810 <p>S: "DESCRIPTION: this is Joe's custom sampler engine"
3811 </p>
3812 <p>&nbsp;&nbsp;&nbsp;"VERSION: testing-1.0"
3813 </p>
3814 <p>&nbsp;&nbsp;&nbsp;"."
3815 </p>
3816 </blockquote><p>
3817
3818 </p>
3819 <a name="GET CHANNEL INFO"></a><br /><hr />
3820 <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>
3821 <a name="rfc.section.6.4.10"></a><h3>6.4.10.&nbsp;
3822 Getting sampler channel information</h3>
3823
3824 <p>The front-end can ask for the current settings of a sampler channel
3825 by sending the following command:
3826 </p>
3827 <p>
3828 </p>
3829 <blockquote class="text">
3830 <p>GET CHANNEL INFO &lt;sampler-channel&gt;
3831 </p>
3832 </blockquote><p>
3833
3834 </p>
3835 <p>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
3836 as returned by the <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
3837 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command.
3838 </p>
3839 <p>Possible Answers:
3840 </p>
3841 <p>
3842 </p>
3843 <blockquote class="text">
3844 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3845 Each answer line begins with the settings category name
3846 followed by a colon and then a space character &lt;SP&gt; and finally
3847 the info character string to that setting category. At the
3848 moment the following categories are defined:
3849 </p>
3850 <p>
3851 </p>
3852 <blockquote class="text">
3853 <p>ENGINE_NAME -
3854 </p>
3855 <blockquote class="text">
3856 <p>name of the engine that is associated with the sampler
3857 channel, "NONE" if there's no engine associated yet for
3858 this sampler channel
3859 </p>
3860 </blockquote>
3861
3862
3863 <p>AUDIO_OUTPUT_DEVICE -
3864 </p>
3865 <blockquote class="text">
3866 <p>numerical ID of the audio output device which is
3867 currently connected to this sampler channel to output
3868 the audio signal, "NONE" if there's no device
3869 connected to this sampler channel
3870 </p>
3871 </blockquote>
3872
3873
3874 <p>AUDIO_OUTPUT_CHANNELS -
3875 </p>
3876 <blockquote class="text">
3877 <p>number of output channels the sampler channel offers
3878 (dependent to used sampler engine and loaded instrument)
3879 </p>
3880 </blockquote>
3881
3882
3883 <p>AUDIO_OUTPUT_ROUTING -
3884 </p>
3885 <blockquote class="text">
3886 <p>comma separated list which reflects to which audio
3887 channel of the selected audio output device each
3888 sampler output channel is routed to, e.g. "0,3" would
3889 mean the engine's output channel 0 is routed to channel
3890 0 of the audio output device and the engine's output
3891 channel 1 is routed to the channel 3 of the audio
3892 output device
3893 </p>
3894 </blockquote>
3895
3896
3897 <p>INSTRUMENT_FILE -
3898 </p>
3899 <blockquote class="text">
3900 <p>the file name of the loaded instrument, "NONE" if
3901 there's no instrument yet loaded for this sampler
3902 channel
3903 </p>
3904 </blockquote>
3905
3906
3907 <p>INSTRUMENT_NR -
3908 </p>
3909 <blockquote class="text">
3910 <p>the instrument index number of the loaded instrument
3911 </p>
3912 </blockquote>
3913
3914
3915 <p>INSTRUMENT_NAME -
3916 </p>
3917 <blockquote class="text">
3918 <p>the instrument name of the loaded instrument
3919 </p>
3920 </blockquote>
3921
3922
3923 <p>INSTRUMENT_STATUS -
3924 </p>
3925 <blockquote class="text">
3926 <p>integer values 0 to 100 indicating loading progress percentage for the instrument. Negative
3927 value indicates a loading exception. Value of 100 indicates that the instrument is fully
3928 loaded.
3929 </p>
3930 </blockquote>
3931
3932
3933 <p>MIDI_INPUT_DEVICE -
3934 </p>
3935 <blockquote class="text">
3936 <p>numerical ID of the MIDI input device which is
3937 currently connected to this sampler channel to deliver
3938 MIDI input commands, "NONE" if there's no device
3939 connected to this sampler channel
3940 </p>
3941 </blockquote>
3942
3943
3944 <p>MIDI_INPUT_PORT -
3945 </p>
3946 <blockquote class="text">
3947 <p>port number of the MIDI input device
3948 </p>
3949 </blockquote>
3950
3951
3952 <p>MIDI_INPUT_CHANNEL -
3953 </p>
3954 <blockquote class="text">
3955 <p>the MIDI input channel number this sampler channel
3956 should listen to or "ALL" to listen on all MIDI channels
3957 </p>
3958 </blockquote>
3959
3960
3961 <p>VOLUME -
3962 </p>
3963 <blockquote class="text">
3964 <p>optionally dotted number for the channel volume factor
3965 (where a value &lt; 1.0 means attenuation and a value >
3966 1.0 means amplification)
3967 </p>
3968 </blockquote>
3969
3970
3971 <p>MUTE -
3972 </p>
3973 <blockquote class="text">
3974 <p>Determines whether the channel is muted, "true" if the
3975 channel is muted, "false" if the channel is not muted, and
3976 "MUTED_BY_SOLO" if the channel is muted because of the
3977 presence of a solo channel and will be unmuted when
3978 there are no solo channels left
3979 </p>
3980 </blockquote>
3981
3982
3983 <p>SOLO -
3984 </p>
3985 <blockquote class="text">
3986 <p>Determines whether this is a solo channel, "true" if
3987 the channel is a solo channel; "false" otherwise
3988 </p>
3989 </blockquote>
3990
3991
3992 <p>MIDI_INSTRUMENT_MAP -
3993 </p>
3994 <blockquote class="text">
3995 <p>Determines to which MIDI instrument map this sampler
3996 channel is assigned to. Read chapter
3997 <a class='info' href='#SET CHANNEL MIDI_INSTRUMENT_MAP'>"SET CHANNEL MIDI_INSTRUMENT_MAP"<span> (</span><span class='info'>Assigning a MIDI instrument map to a sampler channel</span><span>)</span></a>
3998 for a list of possible values.
3999 </p>
4000 </blockquote>
4001
4002
4003 </blockquote>
4004
4005
4006 </blockquote><p>
4007
4008 </p>
4009 <p>The mentioned fields above don't have to be in particular order.
4010 </p>
4011 <p>Example:
4012 </p>
4013 <p>
4014 </p>
4015 <blockquote class="text">
4016 <p>C: "GET CHANNEL INFO 34"
4017 </p>
4018 <p>S: "ENGINE_NAME: GigEngine"
4019 </p>
4020 <p>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"
4021 </p>
4022 <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_DEVICE: 0"
4023 </p>
4024 <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_CHANNELS: 2"
4025 </p>
4026 <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 0,1"
4027 </p>
4028 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"
4029 </p>
4030 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"
4031 </p>
4032 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NAME: Fazioli Piano"
4033 </p>
4034 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_STATUS: 100"
4035 </p>
4036 <p>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_DEVICE: 0"
4037 </p>
4038 <p>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_PORT: 0"
4039 </p>
4040 <p>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_CHANNEL: 5"
4041 </p>
4042 <p>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"
4043 </p>
4044 <p>&nbsp;&nbsp;&nbsp;"MUTE: false"
4045 </p>
4046 <p>&nbsp;&nbsp;&nbsp;"SOLO: false"
4047 </p>
4048 <p>&nbsp;&nbsp;&nbsp;"MIDI_INSTRUMENT_MAP: NONE"
4049 </p>
4050 <p>&nbsp;&nbsp;&nbsp;"."
4051 </p>
4052 </blockquote><p>
4053
4054 </p>
4055 <a name="GET CHANNEL VOICE_COUNT"></a><br /><hr />
4056 <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>
4057 <a name="rfc.section.6.4.11"></a><h3>6.4.11.&nbsp;
4058 Current number of active voices</h3>
4059
4060 <p>The front-end can ask for the current number of active voices on a
4061 sampler channel by sending the following command:
4062 </p>
4063 <p>
4064 </p>
4065 <blockquote class="text">
4066 <p>GET CHANNEL VOICE_COUNT &lt;sampler-channel&gt;
4067 </p>
4068 </blockquote><p>
4069
4070 </p>
4071 <p>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
4072 as returned by the <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
4073 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command.
4074 </p>
4075 <p>Possible Answers:
4076 </p>
4077 <p>
4078 </p>
4079 <blockquote class="text">
4080 <p>LinuxSampler will answer by returning the number of active
4081 voices on that channel.
4082 </p>
4083 </blockquote><p>
4084
4085 </p>
4086 <p>Example:
4087 </p>
4088 <p>
4089 </p>
4090 <blockquote class="text">
4091 <p>
4092 </p>
4093 </blockquote><p>
4094
4095 </p>
4096 <a name="GET CHANNEL STREAM_COUNT"></a><br /><hr />
4097 <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>
4098 <a name="rfc.section.6.4.12"></a><h3>6.4.12.&nbsp;
4099 Current number of active disk streams</h3>
4100
4101 <p>The front-end can ask for the current number of active disk streams
4102 on a sampler channel by sending the following command:
4103 </p>
4104 <p>
4105 </p>
4106 <blockquote class="text">
4107 <p>GET CHANNEL STREAM_COUNT &lt;sampler-channel&gt;
4108 </p>
4109 </blockquote><p>
4110
4111 </p>
4112 <p>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
4113 as returned by the <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
4114 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command.
4115 </p>
4116 <p>Possible Answers:
4117 </p>
4118 <p>
4119 </p>
4120 <blockquote class="text">
4121 <p>LinuxSampler will answer by returning the number of active
4122 disk streams on that channel in case the engine supports disk
4123 streaming, if the engine doesn't support disk streaming it will
4124 return "NA" for not available.
4125 </p>
4126 </blockquote><p>
4127
4128 </p>
4129 <p>Example:
4130 </p>
4131 <p>
4132 </p>
4133 <blockquote class="text">
4134 <p>
4135 </p>
4136 </blockquote><p>
4137
4138 </p>
4139 <a name="GET CHANNEL BUFFER_FILL"></a><br /><hr />
4140 <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>
4141 <a name="rfc.section.6.4.13"></a><h3>6.4.13.&nbsp;
4142 Current fill state of disk stream buffers</h3>
4143
4144 <p>The front-end can ask for the current fill state of all disk streams
4145 on a sampler channel by sending the following command:
4146 </p>
4147 <p>
4148 </p>
4149 <blockquote class="text">
4150 <p>GET CHANNEL BUFFER_FILL BYTES &lt;sampler-channel&gt;
4151 </p>
4152 </blockquote><p>
4153
4154 </p>
4155 <p>to get the fill state in bytes or
4156 </p>
4157 <p>
4158 </p>
4159 <blockquote class="text">
4160 <p>GET CHANNEL BUFFER_FILL PERCENTAGE &lt;sampler-channel&gt;
4161 </p>
4162 </blockquote><p>
4163
4164 </p>
4165 <p>to get the fill state in percent, where &lt;sampler-channel&gt; is the
4166 sampler channel number the front-end is interested in
4167 as returned by the <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
4168 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command.
4169 </p>
4170 <p>Possible Answers:
4171 </p>
4172 <p>
4173 </p>
4174 <blockquote class="text">
4175 <p>LinuxSampler will either answer by returning a comma separated
4176 string with the fill state of all disk stream buffers on that
4177 channel or an empty line if there are no active disk streams or
4178 "NA" for *not available* in case the engine which is deployed
4179 doesn't support disk streaming. Each entry in the answer list
4180 will begin with the stream's ID in brackets followed by the
4181 numerical representation of the fill size (either in bytes or
4182 percentage). Note: due to efficiency reasons the fill states in
4183 the response are not in particular order, thus the front-end has
4184 to sort them by itself if necessary.
4185 </p>
4186 </blockquote><p>
4187
4188 </p>
4189 <p>Examples:
4190 </p>
4191 <p>
4192 </p>
4193 <blockquote class="text">
4194 <p>C: "GET CHANNEL BUFFER_FILL BYTES 4"
4195 </p>
4196 <p>S: "[115]420500,[116]510300,[75]110000,[120]230700"
4197 </p>
4198 </blockquote><p>
4199
4200 </p>
4201 <blockquote class="text">
4202 <p>C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
4203 </p>
4204 <p>S: "[115]90%,[116]98%,[75]40%,[120]62%"
4205 </p>
4206 </blockquote><p>
4207
4208 </p>
4209 <blockquote class="text">
4210 <p>C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
4211 </p>
4212 <p>S: ""
4213 </p>
4214 </blockquote><p>
4215
4216 </p>
4217 <a name="SET CHANNEL AUDIO_OUTPUT_DEVICE"></a><br /><hr />
4218 <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>
4219 <a name="rfc.section.6.4.14"></a><h3>6.4.14.&nbsp;
4220 Setting audio output device</h3>
4221
4222 <p>The front-end can set the audio output device on a specific sampler
4223 channel by sending the following command:
4224 </p>
4225 <p>
4226 </p>
4227 <blockquote class="text">
4228 <p>SET CHANNEL AUDIO_OUTPUT_DEVICE &lt;sampler-channel&gt; &lt;audio-device-id&gt;
4229 </p>
4230 </blockquote><p>
4231
4232 </p>
4233 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4234 number as returned by the <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
4235 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command and
4236 &lt;audio-device-id&gt; is the numerical ID of the audio output device as given by the
4237 <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>
4238 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>
4239 command.
4240 </p>
4241 <p>Possible Answers:
4242 </p>
4243 <p>
4244 </p>
4245 <blockquote class="text">
4246 <p>"OK" -
4247 </p>
4248 <blockquote class="text">
4249 <p>on success
4250 </p>
4251 </blockquote>
4252
4253
4254 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4255 </p>
4256 <blockquote class="text">
4257 <p>if audio output device was set, but there are noteworthy
4258 issue(s) related, providing an appropriate warning code and
4259 warning message
4260 </p>
4261 </blockquote>
4262
4263
4264 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4265 </p>
4266 <blockquote class="text">
4267 <p>in case it failed, providing an appropriate error code and error message
4268 </p>
4269 </blockquote>
4270
4271
4272 </blockquote><p>
4273
4274 </p>
4275 <p>Examples:
4276 </p>
4277 <p>
4278 </p>
4279 <blockquote class="text">
4280 <p>
4281 </p>
4282 </blockquote><p>
4283
4284 </p>
4285 <a name="SET CHANNEL AUDIO_OUTPUT_TYPE"></a><br /><hr />
4286 <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>
4287 <a name="rfc.section.6.4.15"></a><h3>6.4.15.&nbsp;
4288 Setting audio output type</h3>
4289
4290 <p>DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
4291 </p>
4292 <p>The front-end can alter the audio output type on a specific sampler
4293 channel by sending the following command:
4294 </p>
4295 <p>
4296 </p>
4297 <blockquote class="text">
4298 <p>SET CHANNEL AUDIO_OUTPUT_TYPE &lt;sampler-channel&gt; &lt;audio-output-type&gt;
4299 </p>
4300 </blockquote><p>
4301
4302 </p>
4303 <p>Where &lt;audio-output-type&gt; is currently either "ALSA" or "JACK" and
4304 &lt;sampler-channel&gt; is the respective sampler channel number.
4305 </p>
4306 <p>Possible Answers:
4307 </p>
4308 <p>
4309 </p>
4310 <blockquote class="text">
4311 <p>"OK" -
4312 </p>
4313 <blockquote class="text">
4314 <p>on success
4315 </p>
4316 </blockquote>
4317
4318
4319 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4320 </p>
4321 <blockquote class="text">
4322 <p>if audio output type was set, but there are noteworthy
4323 issue(s) related, providing an appropriate warning code and
4324 warning message
4325 </p>
4326 </blockquote>
4327
4328
4329 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4330 </p>
4331 <blockquote class="text">
4332 <p>in case it failed, providing an appropriate error code and error message
4333 </p>
4334 </blockquote>
4335
4336
4337 </blockquote><p>
4338
4339 </p>
4340 <p>Examples:
4341 </p>
4342 <p>
4343 </p>
4344 <blockquote class="text">
4345 <p>
4346 </p>
4347 </blockquote><p>
4348
4349 </p>
4350 <a name="SET CHANNEL AUDIO_OUTPUT_CHANNEL"></a><br /><hr />
4351 <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>
4352 <a name="rfc.section.6.4.16"></a><h3>6.4.16.&nbsp;
4353 Setting audio output channel</h3>
4354
4355 <p>The front-end can alter the audio output channel on a specific
4356 sampler channel by sending the following command:
4357 </p>
4358 <p>
4359 </p>
4360 <blockquote class="text">
4361 <p>SET CHANNEL AUDIO_OUTPUT_CHANNEL &lt;sampler-chan&gt; &lt;audio-out&gt; &lt;audio-in&gt;
4362 </p>
4363 </blockquote><p>
4364
4365 </p>
4366 <p>Where &lt;sampler-chan&gt; is the sampler channel number
4367 as returned by the <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
4368 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command, &lt;audio-out&gt; is the
4369 numerical ID of the sampler channel's audio output channel which should be
4370 rerouted and &lt;audio-in&gt; is the numerical ID of the audio channel of the selected audio
4371 output device where &lt;audio-out&gt; should be routed to.
4372 </p>
4373 <p>Possible Answers:
4374 </p>
4375 <p>
4376 </p>
4377 <blockquote class="text">
4378 <p>"OK" -
4379 </p>
4380 <blockquote class="text">
4381 <p>on success
4382 </p>
4383 </blockquote>
4384
4385
4386 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4387 </p>
4388 <blockquote class="text">
4389 <p>if audio output channel was set, but there are noteworthy
4390 issue(s) related, providing an appropriate warning code and
4391 warning message
4392 </p>
4393 </blockquote>
4394
4395
4396 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4397 </p>
4398 <blockquote class="text">
4399 <p>in case it failed, providing an appropriate error code and error message
4400 </p>
4401 </blockquote>
4402
4403
4404 </blockquote><p>
4405
4406 </p>
4407 <p>Examples:
4408 </p>
4409 <p>
4410 </p>
4411 <blockquote class="text">
4412 <p>
4413 </p>
4414 </blockquote><p>
4415
4416 </p>
4417 <a name="SET CHANNEL MIDI_INPUT_DEVICE"></a><br /><hr />
4418 <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>
4419 <a name="rfc.section.6.4.17"></a><h3>6.4.17.&nbsp;
4420 Setting MIDI input device</h3>
4421
4422 <p>The front-end can set the MIDI input device on a specific sampler
4423 channel by sending the following command:
4424 </p>
4425 <p>
4426 </p>
4427 <blockquote class="text">
4428 <p>SET CHANNEL MIDI_INPUT_DEVICE &lt;sampler-channel&gt; &lt;midi-device-id&gt;
4429 </p>
4430 </blockquote><p>
4431
4432 </p>
4433 <p>Where &lt;sampler-channel&gt; is the sampler channel number
4434 as returned by the <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
4435 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command
4436 and &lt;midi-device-id&gt; is the numerical ID of the MIDI input device as returned by the
4437 <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>
4438 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> command.
4439 </p>
4440 <p>Possible Answers:
4441 </p>
4442 <p>
4443 </p>
4444 <blockquote class="text">
4445 <p>"OK" -
4446 </p>
4447 <blockquote class="text">
4448 <p>on success
4449 </p>
4450 </blockquote>
4451
4452
4453 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4454 </p>
4455 <blockquote class="text">
4456 <p>if MIDI input device was set, but there are noteworthy
4457 issue(s) related, providing an appropriate warning code and
4458 warning message
4459 </p>
4460 </blockquote>
4461
4462
4463 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4464 </p>
4465 <blockquote class="text">
4466 <p>in case it failed, providing an appropriate error code and error message
4467 </p>
4468 </blockquote>
4469
4470
4471 </blockquote><p>
4472
4473 </p>
4474 <p>Examples:
4475 </p>
4476 <p>
4477 </p>
4478 <blockquote class="text">
4479 <p>
4480 </p>
4481 </blockquote><p>
4482
4483 </p>
4484 <a name="SET CHANNEL MIDI_INPUT_TYPE"></a><br /><hr />
4485 <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>
4486 <a name="rfc.section.6.4.18"></a><h3>6.4.18.&nbsp;
4487 Setting MIDI input type</h3>
4488
4489 <p>DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
4490 </p>
4491 <p>The front-end can alter the MIDI input type on a specific sampler
4492 channel by sending the following command:
4493 </p>
4494 <p>
4495 </p>
4496 <blockquote class="text">
4497 <p>SET CHANNEL MIDI_INPUT_TYPE &lt;sampler-channel&gt; &lt;midi-input-type&gt;
4498 </p>
4499 </blockquote><p>
4500
4501 </p>
4502 <p>Where &lt;midi-input-type&gt; is currently only "ALSA" and
4503 &lt;sampler-channel&gt; is the respective sampler channel number.
4504 </p>
4505 <p>Possible Answers:
4506 </p>
4507 <p>
4508 </p>
4509 <blockquote class="text">
4510 <p>"OK" -
4511 </p>
4512 <blockquote class="text">
4513 <p>on success
4514 </p>
4515 </blockquote>
4516
4517
4518 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4519 </p>
4520 <blockquote class="text">
4521 <p>if MIDI input type was set, but there are noteworthy
4522 issue(s) related, providing an appropriate warning code and
4523 warning message
4524 </p>
4525 </blockquote>
4526
4527
4528 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4529 </p>
4530 <blockquote class="text">
4531 <p>in case it failed, providing an appropriate error code and error message
4532 </p>
4533 </blockquote>
4534
4535
4536 </blockquote><p>
4537
4538 </p>
4539 <p>Examples:
4540 </p>
4541 <p>
4542 </p>
4543 <blockquote class="text">
4544 <p>
4545 </p>
4546 </blockquote><p>
4547
4548 </p>
4549 <a name="SET CHANNEL MIDI_INPUT_PORT"></a><br /><hr />
4550 <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>
4551 <a name="rfc.section.6.4.19"></a><h3>6.4.19.&nbsp;
4552 Setting MIDI input port</h3>
4553
4554 <p>The front-end can alter the MIDI input port on a specific sampler
4555 channel by sending the following command:
4556 </p>
4557 <p>
4558 </p>
4559 <blockquote class="text">
4560 <p>SET CHANNEL MIDI_INPUT_PORT &lt;sampler-channel&gt; &lt;midi-input-port&gt;
4561 </p>
4562 </blockquote><p>
4563
4564 </p>
4565 <p>Where &lt;midi-input-port&gt; is a MIDI input port number of the
4566 MIDI input device connected to the sampler channel given by
4567 &lt;sampler-channel&gt;.
4568 </p>
4569 <p>Possible Answers:
4570 </p>
4571 <p>
4572 </p>
4573 <blockquote class="text">
4574 <p>"OK" -
4575 </p>
4576 <blockquote class="text">
4577 <p>on success
4578 </p>
4579 </blockquote>
4580
4581
4582 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4583 </p>
4584 <blockquote class="text">
4585 <p>if MIDI input port was set, but there are noteworthy
4586 issue(s) related, providing an appropriate warning code and
4587 warning message
4588 </p>
4589 </blockquote>
4590
4591
4592 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4593 </p>
4594 <blockquote class="text">
4595 <p>in case it failed, providing an appropriate error code and error message
4596 </p>
4597 </blockquote>
4598
4599
4600 </blockquote><p>
4601
4602 </p>
4603 <p>Examples:
4604 </p>
4605 <p>
4606 </p>
4607 <blockquote class="text">
4608 <p>
4609 </p>
4610 </blockquote><p>
4611
4612 </p>
4613 <a name="SET CHANNEL MIDI_INPUT_CHANNEL"></a><br /><hr />
4614 <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>
4615 <a name="rfc.section.6.4.20"></a><h3>6.4.20.&nbsp;
4616 Setting MIDI input channel</h3>
4617
4618 <p>The front-end can alter the MIDI channel a sampler channel should
4619 listen to by sending the following command:
4620 </p>
4621 <p>
4622 </p>
4623 <blockquote class="text">
4624 <p>SET CHANNEL MIDI_INPUT_CHANNEL &lt;sampler-channel&gt; &lt;midi-input-chan&gt;
4625 </p>
4626 </blockquote><p>
4627
4628 </p>
4629 <p>Where &lt;midi-input-chan&gt; is the number of the new MIDI input channel where
4630 &lt;sampler-channel&gt; should listen to or "ALL" to listen on all 16 MIDI
4631 channels.
4632 </p>
4633 <p>Possible Answers:
4634 </p>
4635 <p>
4636 </p>
4637 <blockquote class="text">
4638 <p>"OK" -
4639 </p>
4640 <blockquote class="text">
4641 <p>on success
4642 </p>
4643 </blockquote>
4644
4645
4646 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4647 </p>
4648 <blockquote class="text">
4649 <p>if MIDI input channel was set, but there are noteworthy
4650 issue(s) related, providing an appropriate warning code and
4651 warning message
4652 </p>
4653 </blockquote>
4654
4655
4656 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4657 </p>
4658 <blockquote class="text">
4659 <p>in case it failed, providing an appropriate error code and error message
4660 </p>
4661 </blockquote>
4662
4663
4664 </blockquote><p>
4665
4666 </p>
4667 <p>Examples:
4668 </p>
4669 <p>
4670 </p>
4671 <blockquote class="text">
4672 <p>
4673 </p>
4674 </blockquote><p>
4675
4676 </p>
4677 <a name="SET CHANNEL VOLUME"></a><br /><hr />
4678 <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>
4679 <a name="rfc.section.6.4.21"></a><h3>6.4.21.&nbsp;
4680 Setting channel volume</h3>
4681
4682 <p>The front-end can alter the volume of a sampler channel by sending
4683 the following command:
4684 </p>
4685 <p>
4686 </p>
4687 <blockquote class="text">
4688 <p>SET CHANNEL VOLUME &lt;sampler-channel&gt; &lt;volume&gt;
4689 </p>
4690 </blockquote><p>
4691
4692 </p>
4693 <p>Where &lt;volume&gt; is an optionally dotted positive number (a value
4694 smaller than 1.0 means attenuation, whereas a value greater than
4695 1.0 means amplification) and &lt;sampler-channel&gt; defines the sampler
4696 channel where this volume factor should be set.
4697 </p>
4698 <p>Possible Answers:
4699 </p>
4700 <p>
4701 </p>
4702 <blockquote class="text">
4703 <p>"OK" -
4704 </p>
4705 <blockquote class="text">
4706 <p>on success
4707 </p>
4708 </blockquote>
4709
4710
4711 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4712 </p>
4713 <blockquote class="text">
4714 <p>if channel volume was set, but there are noteworthy
4715 issue(s) related, providing an appropriate warning code and
4716 warning message
4717 </p>
4718 </blockquote>
4719
4720
4721 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4722 </p>
4723 <blockquote class="text">
4724 <p>in case it failed, providing an appropriate error code and error message
4725 </p>
4726 </blockquote>
4727
4728
4729 </blockquote><p>
4730
4731 </p>
4732 <p>Examples:
4733 </p>
4734 <p>
4735 </p>
4736 <blockquote class="text">
4737 <p>
4738 </p>
4739 </blockquote><p>
4740
4741 </p>
4742 <a name="SET CHANNEL MUTE"></a><br /><hr />
4743 <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>
4744 <a name="rfc.section.6.4.22"></a><h3>6.4.22.&nbsp;
4745 Muting a sampler channel</h3>
4746
4747 <p>The front-end can mute/unmute a specific sampler
4748 channel by sending the following command:
4749 </p>
4750 <p>
4751 </p>
4752 <blockquote class="text">
4753 <p>SET CHANNEL MUTE &lt;sampler-channel&gt; &lt;mute&gt;
4754 </p>
4755 </blockquote><p>
4756
4757 </p>
4758 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4759 number as returned by the <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
4760 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command and
4761 &lt;mute&gt; should be replaced either by "1" to mute the channel or "0"
4762 to unmute the channel.
4763 </p>
4764 <p>Possible Answers:
4765 </p>
4766 <p>
4767 </p>
4768 <blockquote class="text">
4769 <p>"OK" -
4770 </p>
4771 <blockquote class="text">
4772 <p>on success
4773 </p>
4774 </blockquote>
4775
4776
4777 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4778 </p>
4779 <blockquote class="text">
4780 <p>if the channel was muted/unmuted, but there are noteworthy
4781 issue(s) related, providing an appropriate warning code and
4782 warning message
4783 </p>
4784 </blockquote>
4785
4786
4787 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4788 </p>
4789 <blockquote class="text">
4790 <p>in case it failed, providing an appropriate error code and error message
4791 </p>
4792 </blockquote>
4793
4794
4795 </blockquote><p>
4796
4797 </p>
4798 <p>Examples:
4799 </p>
4800 <p>
4801 </p>
4802 <blockquote class="text">
4803 <p>
4804 </p>
4805 </blockquote><p>
4806
4807 </p>
4808 <a name="SET CHANNEL SOLO"></a><br /><hr />
4809 <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>
4810 <a name="rfc.section.6.4.23"></a><h3>6.4.23.&nbsp;
4811 Soloing a sampler channel</h3>
4812
4813 <p>The front-end can solo/unsolo a specific sampler channel
4814 by sending the following command:
4815 </p>
4816 <p>
4817 </p>
4818 <blockquote class="text">
4819 <p>SET CHANNEL SOLO &lt;sampler-channel&gt; &lt;solo&gt;
4820 </p>
4821 </blockquote><p>
4822
4823 </p>
4824 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4825 number as returned by the <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
4826 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command and
4827 &lt;solo&gt; should be replaced either by "1" to solo the channel or "0"
4828 to unsolo the channel.
4829 </p>
4830 <p>Possible Answers:
4831 </p>
4832 <p>
4833 </p>
4834 <blockquote class="text">
4835 <p>"OK" -
4836 </p>
4837 <blockquote class="text">
4838 <p>on success
4839 </p>
4840 </blockquote>
4841
4842
4843 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4844 </p>
4845 <blockquote class="text">
4846 <p>if the channel was soloed/unsoloed, but there are noteworthy
4847 issue(s) related, providing an appropriate warning code and
4848 warning message
4849 </p>
4850 </blockquote>
4851
4852
4853 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4854 </p>
4855 <blockquote class="text">
4856 <p>in case it failed, providing an appropriate error code and error message
4857 </p>
4858 </blockquote>
4859
4860
4861 </blockquote><p>
4862
4863 </p>
4864 <p>Examples:
4865 </p>
4866 <p>
4867 </p>
4868 <blockquote class="text">
4869 <p>
4870 </p>
4871 </blockquote><p>
4872
4873 </p>
4874 <a name="SET CHANNEL MIDI_INSTRUMENT_MAP"></a><br /><hr />
4875 <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>
4876 <a name="rfc.section.6.4.24"></a><h3>6.4.24.&nbsp;
4877 Assigning a MIDI instrument map to a sampler channel</h3>
4878
4879 <p>The front-end can assign a MIDI instrument map to a specific sampler channel
4880 by sending the following command:
4881 </p>
4882 <p>
4883 </p>
4884 <blockquote class="text">
4885 <p>SET CHANNEL MIDI_INSTRUMENT_MAP &lt;sampler-channel&gt; &lt;map&gt;
4886 </p>
4887 </blockquote><p>
4888
4889 </p>
4890 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4891 number as returned by the <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
4892 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command and
4893 &lt;map&gt; can have the following possibilites:
4894 </p>
4895 <p>
4896 </p>
4897 <blockquote class="text">
4898 <p>"NONE" -
4899 </p>
4900 <blockquote class="text">
4901 <p>This is the default setting. In this case
4902 the sampler channel is not assigned any MIDI
4903 instrument map and thus will ignore all MIDI
4904 program change messages.
4905 </p>
4906 </blockquote>
4907
4908
4909 <p>"DEFAULT" -
4910 </p>
4911 <blockquote class="text">
4912 <p>The sampler channel will always use the
4913 default MIDI instrument map to handle MIDI
4914 program change messages.
4915 </p>
4916 </blockquote>
4917
4918
4919 <p>numeric ID -
4920 </p>
4921 <blockquote class="text">
4922 <p>You can assign a specific MIDI instrument map
4923 by replacing &lt;map&gt; with the respective numeric
4924 ID of the MIDI instrument map as returned by the
4925 <a class='info' href='#LIST MIDI_INSTRUMENT_MAPS'>"LIST MIDI_INSTRUMENT_MAPS"<span> (</span><span class='info'>Getting all created MIDI instrument maps</span><span>)</span></a>
4926 command. Once that map will be deleted, the sampler
4927 channel would fall back to "NONE".
4928 </p>
4929 </blockquote>
4930
4931
4932 </blockquote><p>
4933
4934 </p>
4935 <p>Read chapter <a class='info' href='#MIDI Instrument Mapping'>"MIDI Instrument Mapping"<span> (</span><span class='info'>MIDI Instrument Mapping</span><span>)</span></a>
4936 for details regarding MIDI instrument mapping.
4937 </p>
4938 <p>Possible Answers:
4939 </p>
4940 <p>
4941 </p>
4942 <blockquote class="text">
4943 <p>"OK" -
4944 </p>
4945 <blockquote class="text">
4946 <p>on success
4947 </p>
4948 </blockquote>
4949
4950
4951 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4952 </p>
4953 <blockquote class="text">
4954 <p>in case it failed, providing an appropriate error code and error message
4955 </p>
4956 </blockquote>
4957
4958
4959 </blockquote><p>
4960
4961 </p>
4962 <p>Examples:
4963 </p>
4964 <p>
4965 </p>
4966 <blockquote class="text">
4967 <p>
4968 </p>
4969 </blockquote><p>
4970
4971 </p>
4972 <a name="CREATE FX_SEND"></a><br /><hr />
4973 <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>
4974 <a name="rfc.section.6.4.25"></a><h3>6.4.25.&nbsp;
4975 Adding an effect send to a sampler channel</h3>
4976
4977 <p>The front-end can create an additional effect send on a specific sampler channel
4978 by sending the following command:
4979 </p>
4980 <p>
4981 </p>
4982 <blockquote class="text">
4983 <p>CREATE FX_SEND &lt;sampler-channel&gt; &lt;midi-ctrl&gt; [&lt;name&gt;]
4984 </p>
4985 </blockquote><p>
4986
4987 </p>
4988 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4989 number as returned by the <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
4990 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command, that is the
4991 sampler channel on which the effect send should be created on, &lt;midi-ctrl&gt;
4992 is a number between 0..127 defining the MIDI controller which can alter the
4993 effect send level and &lt;name&gt; is an optional argument defining a name
4994 for the effect send entity. The name does not have to be unique.
4995 </p>
4996 <p>By default, that is as initial routing, the effect send's audio channels
4997 are automatically routed to the last audio channels of the sampler channel's
4998 audio output device, that way you can i.e. first increase the amount of audio
4999 channels on the audio output device for having dedicated effect send output
5000 channels and when "CREATE FX_SEND" is called, those channels will automatically
5001 be picked. You can alter the destination channels however with
5002 <a class='info' href='#SET FX_SEND AUDIO_OUTPUT_CHANNEL'>"SET FX_SEND AUDIO_OUTPUT_CHANNEL"<span> (</span><span class='info'>Altering effect send's audio routing</span><span>)</span></a>.
5003
5004 </p>
5005 <p>Note: Create effect sends on a sampler channel only when needed, because having effect
5006 sends on a sampler channel will decrease runtime performance, because for implementing channel
5007 effect sends, separate (sampler channel local) audio buffers are needed to render and mix
5008 the voices and route the audio signal afterwards to the master outputs and effect send
5009 outputs (along with their respective effect send levels). A sampler channel without effect
5010 sends however can mix its voices directly into the audio output devices's audio buffers
5011 and is thus faster.
5012
5013 </p>
5014 <p>Possible Answers:
5015 </p>
5016 <p>
5017 </p>
5018 <blockquote class="text">
5019 <p>"OK[&lt;fx-send-id&gt;]" -
5020 </p>
5021 <blockquote class="text">
5022 <p>in case a new effect send could be added to the
5023 sampler channel, where &lt;fx-send-id&gt; reflects the
5024 unique ID of the newly created effect send entity
5025 </p>
5026 </blockquote>
5027
5028
5029 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5030 </p>
5031 <blockquote class="text">
5032 <p>when a new effect send could not be added, i.e.
5033 due to invalid parameters
5034 </p>
5035 </blockquote>
5036
5037
5038 </blockquote><p>
5039
5040 </p>
5041 <p>Examples:
5042 </p>
5043 <p>
5044 </p>
5045 <blockquote class="text">
5046 <p>C: "CREATE FX_SEND 0 91 'Reverb Send'"
5047 </p>
5048 <p>S: "OK[0]"
5049 </p>
5050 </blockquote><p>
5051
5052 </p>
5053 <p>
5054 </p>
5055 <blockquote class="text">
5056 <p>C: "CREATE FX_SEND 0 93"
5057 </p>
5058 <p>S: "OK[1]"
5059 </p>
5060 </blockquote><p>
5061
5062 </p>
5063 <a name="DESTROY FX_SEND"></a><br /><hr />
5064 <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>
5065 <a name="rfc.section.6.4.26"></a><h3>6.4.26.&nbsp;
5066 Removing an effect send from a sampler channel</h3>
5067
5068 <p>The front-end can remove an existing effect send on a specific sampler channel
5069 by sending the following command:
5070 </p>
5071 <p>
5072 </p>
5073 <blockquote class="text">
5074 <p>DESTROY FX_SEND &lt;sampler-channel&gt; &lt;fx-send-id&gt;
5075 </p>
5076 </blockquote><p>
5077
5078 </p>
5079 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5080 number as returned by the <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
5081 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command, that is the
5082 sampler channel from which the effect send should be removed from and
5083 &lt;fx-send-id&gt; is the respective effect send number as returned by the
5084 <a class='info' href='#CREATE FX_SEND'>"CREATE FX_SEND"<span> (</span><span class='info'>Adding an effect send to a sampler channel</span><span>)</span></a>
5085 or <a class='info' href='#LIST FX_SENDS'>"LIST FX_SENDS"<span> (</span><span class='info'>Listing all effect sends on a sampler channel</span><span>)</span></a> command.
5086 </p>
5087 <p>Possible Answers:
5088 </p>
5089 <p>
5090 </p>
5091 <blockquote class="text">
5092 <p>"OK" -
5093 </p>
5094 <blockquote class="text">
5095 <p>on success
5096 </p>
5097 </blockquote>
5098
5099
5100 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5101 </p>
5102 <blockquote class="text">
5103 <p>in case it failed, providing an appropriate error code and
5104 error message
5105 </p>
5106 </blockquote>
5107
5108
5109 </blockquote><p>
5110
5111 </p>
5112 <p>Example:
5113 </p>
5114 <p>
5115 </p>
5116 <blockquote class="text">
5117 <p>C: "DESTROY FX_SEND 0 0"
5118 </p>
5119 <p>S: "OK"
5120 </p>
5121 </blockquote><p>
5122
5123 </p>
5124 <a name="GET FX_SENDS"></a><br /><hr />
5125 <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>
5126 <a name="rfc.section.6.4.27"></a><h3>6.4.27.&nbsp;
5127 Getting amount of effect sends on a sampler channel</h3>
5128
5129 <p>The front-end can ask for the amount of effect sends on a specific sampler channel
5130 by sending the following command:
5131 </p>
5132 <p>
5133 </p>
5134 <blockquote class="text">
5135 <p>GET FX_SENDS &lt;sampler-channel&gt;
5136 </p>
5137 </blockquote><p>
5138
5139 </p>
5140 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5141 number as returned by the <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
5142 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command.
5143 </p>
5144 <p>Possible Answers:
5145 </p>
5146 <p>
5147 </p>
5148 <blockquote class="text">
5149 <p>The sampler will answer by returning the number of effect
5150 sends on the given sampler channel.
5151 </p>
5152 </blockquote><p>
5153
5154 </p>
5155 <p>Example:
5156 </p>
5157 <p>
5158 </p>
5159 <blockquote class="text">
5160 <p>C: "GET FX_SENDS 0"
5161 </p>
5162 <p>S: "2"
5163 </p>
5164 </blockquote><p>
5165
5166 </p>
5167 <a name="LIST FX_SENDS"></a><br /><hr />
5168 <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>
5169 <a name="rfc.section.6.4.28"></a><h3>6.4.28.&nbsp;
5170 Listing all effect sends on a sampler channel</h3>
5171
5172 <p>The front-end can ask for a list of effect sends on a specific sampler channel
5173 by sending the following command:
5174 </p>
5175 <p>
5176 </p>
5177 <blockquote class="text">
5178 <p>LIST FX_SENDS &lt;sampler-channel&gt;
5179 </p>
5180 </blockquote><p>
5181
5182 </p>
5183 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5184 number as returned by the <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
5185 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command.
5186 </p>
5187 <p>Possible Answers:
5188 </p>
5189 <p>
5190 </p>
5191 <blockquote class="text">
5192 <p>The sampler will answer by returning a comma separated list
5193 with all effect sends' numerical IDs on the given sampler
5194 channel.
5195 </p>
5196 </blockquote><p>
5197
5198 </p>
5199 <p>Examples:
5200 </p>
5201 <p>
5202 </p>
5203 <blockquote class="text">
5204 <p>C: "LIST FX_SENDS 0"
5205 </p>
5206 <p>S: "0,1"
5207 </p>
5208 </blockquote><p>
5209
5210 </p>
5211 <p>
5212 </p>
5213 <blockquote class="text">
5214 <p>C: "LIST FX_SENDS 1"
5215 </p>
5216 <p>S: ""
5217 </p>
5218 </blockquote><p>
5219
5220 </p>
5221 <a name="GET FX_SEND INFO"></a><br /><hr />
5222 <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>
5223 <a name="rfc.section.6.4.29"></a><h3>6.4.29.&nbsp;
5224 Getting effect send information</h3>
5225
5226 <p>The front-end can ask for the current settings of an effect send entity
5227 by sending the following command:
5228 </p>
5229 <p>
5230 </p>
5231 <blockquote class="text">
5232 <p>GET FX_SEND INFO &lt;sampler-channel&gt; &lt;fx-send-id&gt;
5233 </p>
5234 </blockquote><p>
5235
5236 </p>
5237 <p>Where &lt;sampler-channel&gt; is the sampler channel number
5238 as returned by the <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
5239 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command and
5240 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5241 as returned by the <a class='info' href='#CREATE FX_SEND'>"CREATE FX_SEND"<span> (</span><span class='info'>Adding an effect send to a sampler channel</span><span>)</span></a>
5242 or <a class='info' href='#LIST FX_SENDS'>"LIST FX_SENDS"<span> (</span><span class='info'>Listing all effect sends on a sampler channel</span><span>)</span></a> command.
5243
5244 </p>
5245 <p>Possible Answers:
5246 </p>
5247 <p>
5248 </p>
5249 <blockquote class="text">
5250 <p>The sampler will answer by sending a &lt;CRLF&gt; separated list.
5251 Each answer line begins with the settings category name
5252 followed by a colon and then a space character &lt;SP&gt; and finally
5253 the info character string to that setting category. At the
5254 moment the following categories are defined:
5255 </p>
5256 <p>
5257 </p>
5258 <blockquote class="text">
5259 <p>NAME -
5260 </p>
5261 <blockquote class="text">
5262 <p>name of the effect send entity
5263 </p>
5264 </blockquote>
5265
5266
5267 <p>MIDI_CONTROLLER -
5268 </p>
5269 <blockquote class="text">
5270 <p>a value between 0 and 127 reflecting the MIDI controller
5271 which is able to modify the effect send's send level
5272 </p>
5273 </blockquote>
5274
5275
5276 <p>LEVEL -
5277 </p>
5278 <blockquote class="text">
5279 <p>optionally dotted number reflecting the effect send's
5280 current send level (where a value &lt; 1.0 means attenuation
5281 and a value > 1.0 means amplification)
5282 </p>
5283 </blockquote>
5284
5285
5286 <p>AUDIO_OUTPUT_ROUTING -
5287 </p>
5288 <blockquote class="text">
5289 <p>comma separated list which reflects to which audio
5290 channel of the selected audio output device each
5291 effect send output channel is routed to, e.g. "0,3" would
5292 mean the effect send's output channel 0 is routed to channel
5293 0 of the audio output device and the effect send's output
5294 channel 1 is routed to the channel 3 of the audio
5295 output device (see
5296 <a class='info' href='#SET FX_SEND AUDIO_OUTPUT_CHANNEL'>"SET FX_SEND AUDIO_OUTPUT_CHANNEL"<span> (</span><span class='info'>Altering effect send's audio routing</span><span>)</span></a>
5297 for details)
5298 </p>
5299 </blockquote>
5300
5301
5302 </blockquote>
5303
5304
5305 </blockquote><p>
5306
5307 </p>
5308 <p>The mentioned fields above don't have to be in particular order.
5309 </p>
5310 <p>Example:
5311 </p>
5312 <p>
5313 </p>
5314 <blockquote class="text">
5315 <p>C: "GET FX_SEND INFO 0 0"
5316 </p>
5317 <p>S: "NAME: Reverb Send"
5318 </p>
5319 <p>&nbsp;&nbsp;&nbsp;"MIDI_CONTROLLER: 91"
5320 </p>
5321 <p>&nbsp;&nbsp;&nbsp;"LEVEL: 0.3"
5322 </p>
5323 <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 2,3"
5324 </p>
5325 <p>&nbsp;&nbsp;&nbsp;"."
5326 </p>
5327 </blockquote><p>
5328
5329 </p>
5330 <a name="SET FX_SEND AUDIO_OUTPUT_CHANNEL"></a><br /><hr />
5331 <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>
5332 <a name="rfc.section.6.4.30"></a><h3>6.4.30.&nbsp;
5333 Altering effect send's audio routing</h3>
5334
5335 <p>The front-end can alter the destination of an effect send's audio channel on a specific
5336 sampler channel by sending the following command:
5337 </p>
5338 <p>
5339 </p>
5340 <blockquote class="text">
5341 <p>SET FX_SEND AUDIO_OUTPUT_CHANNEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;audio-src&gt; &lt;audio-dst&gt;
5342 </p>
5343 </blockquote><p>
5344
5345 </p>
5346 <p>Where &lt;sampler-chan&gt; is the sampler channel number
5347 as returned by the <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
5348 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command,
5349 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5350 as returned by the <a class='info' href='#CREATE FX_SEND'>"CREATE FX_SEND"<span> (</span><span class='info'>Adding an effect send to a sampler channel</span><span>)</span></a>
5351 or <a class='info' href='#LIST FX_SENDS'>"LIST FX_SENDS"<span> (</span><span class='info'>Listing all effect sends on a sampler channel</span><span>)</span></a> command,
5352 &lt;audio-src&gt; is the numerical ID of the effect send's audio channel
5353 which should be rerouted and &lt;audio-dst&gt; is the numerical ID of
5354 the audio channel of the selected audio output device where &lt;audio-src&gt;
5355 should be routed to.
5356 </p>
5357 <p>Note that effect sends can only route audio to the same audio output
5358 device as assigned to the effect send's sampler channel. Also note that an
5359 effect send entity does always have exactly as much audio channels as its
5360 sampler channel. So if the sampler channel is stereo, the effect send does
5361 have two audio channels as well. Also keep in mind that the amount of audio
5362 channels on a sampler channel might be dependant not only to the deployed
5363 sampler engine on the sampler channel, but also dependant to the instrument
5364 currently loaded. However you can (effectively) turn an i.e. stereo effect
5365 send into a mono one by simply altering its audio routing appropriately.
5366 </p>
5367 <p>Possible Answers:
5368 </p>
5369 <p>
5370 </p>
5371 <blockquote class="text">
5372 <p>"OK" -
5373 </p>
5374 <blockquote class="text">
5375 <p>on success
5376 </p>
5377 </blockquote>
5378
5379
5380 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5381 </p>
5382 <blockquote class="text">
5383 <p>if audio output channel was set, but there are noteworthy
5384 issue(s) related, providing an appropriate warning code and
5385 warning message
5386 </p>
5387 </blockquote>
5388
5389
5390 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5391 </p>
5392 <blockquote class="text">
5393 <p>in case it failed, providing an appropriate error code and error message
5394 </p>
5395 </blockquote>
5396
5397
5398 </blockquote><p>
5399
5400 </p>
5401 <p>Example:
5402 </p>
5403 <p>
5404 </p>
5405 <blockquote class="text">
5406 <p>C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2"
5407 </p>
5408 <p>S: "OK"
5409 </p>
5410 </blockquote><p>
5411
5412 </p>
5413 <a name="SET FX_SEND MIDI_CONTROLLER"></a><br /><hr />
5414 <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>
5415 <a name="rfc.section.6.4.31"></a><h3>6.4.31.&nbsp;
5416 Altering effect send's MIDI controller</h3>
5417
5418 <p>The front-end can alter the MIDI controller of an effect
5419 send entity by sending the following command:
5420 </p>
5421 <p>
5422 </p>
5423 <blockquote class="text">
5424 <p>SET FX_SEND MIDI_CONTROLLER &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;midi-ctrl&gt;
5425 </p>
5426 </blockquote><p>
5427
5428 </p>
5429 <p>Where &lt;sampler-chan&gt; is the sampler channel number
5430 as returned by the <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
5431 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command,
5432 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5433 as returned by the <a class='info' href='#CREATE FX_SEND'>"CREATE FX_SEND"<span> (</span><span class='info'>Adding an effect send to a sampler channel</span><span>)</span></a>
5434 or <a class='info' href='#LIST FX_SENDS'>"LIST FX_SENDS"<span> (</span><span class='info'>Listing all effect sends on a sampler channel</span><span>)</span></a> command and
5435 &lt;midi-ctrl&gt; reflects the MIDI controller which shall be
5436 able to modify the effect send's send level.
5437 </p>
5438 <p>Possible Answers:
5439 </p>
5440 <p>
5441 </p>
5442 <blockquote class="text">
5443 <p>"OK" -
5444 </p>
5445 <blockquote class="text">
5446 <p>on success
5447 </p>
5448 </blockquote>
5449
5450
5451 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5452 </p>
5453 <blockquote class="text">
5454 <p>if MIDI controller was set, but there are noteworthy
5455 issue(s) related, providing an appropriate warning code and
5456 warning message
5457 </p>
5458 </blockquote>
5459
5460
5461 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5462 </p>
5463 <blockquote class="text">
5464 <p>in case it failed, providing an appropriate error code and error message
5465 </p>
5466 </blockquote>
5467
5468
5469 </blockquote><p>
5470
5471 </p>
5472 <p>Example:
5473 </p>
5474 <p>
5475 </p>
5476 <blockquote class="text">
5477 <p>C: "SET FX_SEND MIDI_CONTROLLER 0 0 91"
5478 </p>
5479 <p>S: "OK"
5480 </p>
5481 </blockquote><p>
5482
5483 </p>
5484 <a name="SET FX_SEND LEVEL"></a><br /><hr />
5485 <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>
5486 <a name="rfc.section.6.4.32"></a><h3>6.4.32.&nbsp;
5487 Altering effect send's send level</h3>
5488
5489 <p>The front-end can alter the current send level of an effect
5490 send entity by sending the following command:
5491 </p>
5492 <p>
5493 </p>
5494 <blockquote class="text">
5495 <p>SET FX_SEND LEVEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;volume&gt;
5496 </p>
5497 </blockquote><p>
5498
5499 </p>
5500 <p>Where &lt;sampler-chan&gt; is the sampler channel number
5501 as returned by the <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
5502 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command,
5503 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5504 as returned by the <a class='info' href='#CREATE FX_SEND'>"CREATE FX_SEND"<span> (</span><span class='info'>Adding an effect send to a sampler channel</span><span>)</span></a>
5505 or <a class='info' href='#LIST FX_SENDS'>"LIST FX_SENDS"<span> (</span><span class='info'>Listing all effect sends on a sampler channel</span><span>)</span></a> command and
5506 &lt;volume&gt; is an optionally dotted positive number (a value
5507 smaller than 1.0 means attenuation, whereas a value greater than
5508 1.0 means amplification) reflecting the new send level.
5509 </p>
5510 <p>Possible Answers:
5511 </p>
5512 <p>
5513 </p>
5514 <blockquote class="text">
5515 <p>"OK" -
5516 </p>
5517 <blockquote class="text">
5518 <p>on success
5519 </p>
5520 </blockquote>
5521
5522
5523 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5524 </p>
5525 <blockquote class="text">
5526 <p>if new send level was set, but there are noteworthy
5527 issue(s) related, providing an appropriate warning code and
5528 warning message
5529 </p>
5530 </blockquote>
5531
5532
5533 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5534 </p>
5535 <blockquote class="text">
5536 <p>in case it failed, providing an appropriate error code and error message
5537 </p>
5538 </blockquote>
5539
5540
5541 </blockquote><p>
5542
5543 </p>
5544 <p>Example:
5545 </p>
5546 <p>
5547 </p>
5548 <blockquote class="text">
5549 <p>C: "SET FX_SEND LEVEL 0 0 0.15"
5550 </p>
5551 <p>S: "OK"
5552 </p>
5553 </blockquote><p>
5554
5555 </p>
5556 <a name="RESET CHANNEL"></a><br /><hr />
5557 <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>
5558 <a name="rfc.section.6.4.33"></a><h3>6.4.33.&nbsp;
5559 Resetting a sampler channel</h3>
5560
5561 <p>The front-end can reset a particular sampler channel by sending the following command:
5562 </p>
5563 <p>
5564 </p>
5565 <blockquote class="text">
5566 <p>RESET CHANNEL &lt;sampler-channel&gt;
5567 </p>
5568 </blockquote><p>
5569
5570 </p>
5571 <p>
5572 Where &lt;sampler-channel&gt; defines the sampler channel to be reset.
5573 This will cause the engine on that sampler channel, its voices and
5574 eventually disk streams and all control and status variables to be
5575 reset.
5576 </p>
5577 <p>Possible Answers:
5578 </p>
5579 <p>
5580 </p>
5581 <blockquote class="text">
5582 <p>"OK" -
5583 </p>
5584 <blockquote class="text">
5585 <p>on success
5586 </p>
5587 </blockquote>
5588
5589
5590 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5591 </p>
5592 <blockquote class="text">
5593 <p>if channel was reset, but there are noteworthy issue(s)
5594 related, providing an appropriate warning code and warning
5595 message
5596 </p>
5597 </blockquote>
5598
5599
5600 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5601 </p>
5602 <blockquote class="text">
5603 <p>in case it failed, providing an appropriate error code and
5604 error message
5605 </p>
5606 </blockquote>
5607
5608
5609 </blockquote><p>
5610
5611 </p>
5612 <p>Examples:
5613 </p>
5614 <p>
5615 </p>
5616 <blockquote class="text">
5617 <p>
5618 </p>
5619 </blockquote><p>
5620
5621 </p>
5622 <a name="anchor12"></a><br /><hr />
5623 <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>
5624 <a name="rfc.section.6.5"></a><h3>6.5.&nbsp;
5625 Controlling connection</h3>
5626
5627 <p>The following commands are used to control the connection to LinuxSampler.
5628 </p>
5629 <a name="SUBSCRIBE"></a><br /><hr />
5630 <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>
5631 <a name="rfc.section.6.5.1"></a><h3>6.5.1.&nbsp;
5632 Register front-end for receiving event messages</h3>
5633
5634 <p>The front-end can register itself to the LinuxSampler application to
5635 be informed about noteworthy events by sending this command:
5636 </p>
5637 <p>
5638 </p>
5639 <blockquote class="text">
5640 <p>SUBSCRIBE &lt;event-id&gt;
5641 </p>
5642 </blockquote><p>
5643
5644 </p>
5645 <p>where &lt;event-id&gt; will be replaced by the respective event that
5646 client wants to subscribe to.
5647 </p>
5648 <p>Possible Answers:
5649 </p>
5650 <p>
5651 </p>
5652 <blockquote class="text">
5653 <p>"OK" -
5654 </p>
5655 <blockquote class="text">
5656 <p>on success
5657 </p>
5658 </blockquote>
5659
5660
5661 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5662 </p>
5663 <blockquote class="text">
5664 <p>if registration succeeded, but there are noteworthy
5665 issue(s) related, providing an appropriate warning code and
5666 warning message
5667 </p>
5668 </blockquote>
5669
5670
5671 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5672 </p>
5673 <blockquote class="text">
5674 <p>in case it failed, providing an appropriate error code and
5675 error message
5676 </p>
5677 </blockquote>
5678
5679
5680 </blockquote><p>
5681
5682 </p>
5683 <p>Examples:
5684 </p>
5685 <p>
5686 </p>
5687 <blockquote class="text">
5688 <p>
5689 </p>
5690 </blockquote><p>
5691
5692 </p>
5693 <a name="UNSUBSCRIBE"></a><br /><hr />
5694 <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>
5695 <a name="rfc.section.6.5.2"></a><h3>6.5.2.&nbsp;
5696 Unregister front-end for not receiving event messages</h3>
5697
5698 <p>The front-end can unregister itself if it doesn't want to receive event
5699 messages anymore by sending the following command:
5700 </p>
5701 <p>
5702 </p>
5703 <blockquote class="text">
5704 <p>UNSUBSCRIBE &lt;event-id&gt;
5705 </p>
5706 </blockquote><p>
5707
5708 </p>
5709 <p>Where &lt;event-id&gt; will be replaced by the respective event that
5710 client doesn't want to receive anymore.
5711 </p>
5712 <p>Possible Answers:
5713 </p>
5714 <p>
5715 </p>
5716 <blockquote class="text">
5717 <p>"OK" -
5718 </p>
5719 <blockquote class="text">
5720 <p>on success
5721 </p>
5722 </blockquote>
5723
5724
5725 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5726 </p>
5727 <blockquote class="text">
5728 <p>if unregistration succeeded, but there are noteworthy
5729 issue(s) related, providing an appropriate warning code and
5730 warning message
5731 </p>
5732 </blockquote>
5733
5734
5735 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5736 </p>
5737 <blockquote class="text">
5738 <p>in case it failed, providing an appropriate error code and
5739 error message
5740 </p>
5741 </blockquote>
5742
5743
5744 </blockquote><p>
5745
5746 </p>
5747 <p>Examples:
5748 </p>
5749 <p>
5750 </p>
5751 <blockquote class="text">
5752 <p>
5753 </p>
5754 </blockquote><p>
5755
5756 </p>
5757 <a name="SET ECHO"></a><br /><hr />
5758 <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>
5759 <a name="rfc.section.6.5.3"></a><h3>6.5.3.&nbsp;
5760 Enable or disable echo of commands</h3>
5761
5762 <p>To enable or disable back sending of commands to the client the following command can be used:
5763 </p>
5764 <p>
5765 </p>
5766 <blockquote class="text">
5767 <p>SET ECHO &lt;value&gt;
5768 </p>
5769 </blockquote><p>
5770
5771 </p>
5772 <p>Where &lt;value&gt; should be replaced either by "1" to enable echo mode
5773 or "0" to disable echo mode. When echo mode is enabled, all
5774 commands send to LinuxSampler will be immediately send back and
5775 after this echo the actual response to the command will be
5776 returned. Echo mode will only be altered for the client connection
5777 that issued the "SET ECHO" command, not globally for all client
5778 connections.
5779 </p>
5780 <p>Possible Answers:
5781 </p>
5782 <p>
5783 </p>
5784 <blockquote class="text">
5785 <p>"OK" -
5786 </p>
5787 <blockquote class="text">
5788 <p>usually
5789 </p>
5790 </blockquote>
5791
5792
5793 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5794 </p>
5795 <blockquote class="text">
5796 <p>on syntax error, e.g. non boolean value
5797 </p>
5798 </blockquote>
5799
5800
5801 </blockquote><p>
5802
5803 </p>
5804 <p>Examples:
5805 </p>
5806 <p>
5807 </p>
5808 <blockquote class="text">
5809 <p>
5810 </p>
5811 </blockquote><p>
5812
5813 </p>
5814 <a name="QUIT"></a><br /><hr />
5815 <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>
5816 <a name="rfc.section.6.5.4"></a><h3>6.5.4.&nbsp;
5817 Close client connection</h3>
5818
5819 <p>The client can close its network connection to LinuxSampler by sending the following command:
5820 </p>
5821 <p>
5822 </p>
5823 <blockquote class="text">
5824 <p>QUIT
5825 </p>
5826 </blockquote><p>
5827
5828 </p>
5829 <p>This is probably more interesting for manual telnet connections to
5830 LinuxSampler than really useful for a front-end implementation.
5831 </p>
5832 <a name="anchor13"></a><br /><hr />
5833 <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>
5834 <a name="rfc.section.6.6"></a><h3>6.6.&nbsp;
5835 Global commands</h3>
5836
5837 <p>The following commands have global impact on the sampler.
5838 </p>
5839 <a name="GET TOTAL_VOICE_COUNT"></a><br /><hr />
5840 <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>
5841 <a name="rfc.section.6.6.1"></a><h3>6.6.1.&nbsp;
5842 Current number of active voices</h3>
5843
5844 <p>The front-end can ask for the current number of active voices on
5845 the sampler by sending the following command:
5846 </p>
5847 <p>
5848 </p>
5849 <blockquote class="text">
5850 <p>GET TOTAL_VOICE_COUNT
5851 </p>
5852 </blockquote><p>
5853
5854 </p>
5855 <p>Possible Answers:
5856 </p>
5857 <p>
5858 </p>
5859 <blockquote class="text">
5860 <p>LinuxSampler will answer by returning the number of all active
5861 voices on the sampler.
5862 </p>
5863 </blockquote><p>
5864
5865 </p>
5866 <a name="GET TOTAL_VOICE_COUNT_MAX"></a><br /><hr />
5867 <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>
5868 <a name="rfc.section.6.6.2"></a><h3>6.6.2.&nbsp;
5869 Maximum amount of active voices</h3>
5870
5871 <p>The front-end can ask for the maximum number of active voices
5872 by sending the following command:
5873 </p>
5874 <p>
5875 </p>
5876 <blockquote class="text">
5877 <p>GET TOTAL_VOICE_COUNT_MAX
5878 </p>
5879 </blockquote><p>
5880
5881 </p>
5882 <p>Possible Answers:
5883 </p>
5884 <p>
5885 </p>
5886 <blockquote class="text">
5887 <p>LinuxSampler will answer by returning the maximum number
5888 of active voices.
5889 </p>
5890 </blockquote><p>
5891
5892 </p>
5893 <a name="RESET"></a><br /><hr />
5894 <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>
5895 <a name="rfc.section.6.6.3"></a><h3>6.6.3.&nbsp;
5896 Reset sampler</h3>
5897
5898 <p>The front-end can reset the whole sampler by sending the following command:
5899 </p>
5900 <p>
5901 </p>
5902 <blockquote class="text">
5903 <p>RESET
5904 </p>
5905 </blockquote><p>
5906
5907 </p>
5908 <p>Possible Answers:
5909 </p>
5910 <p>
5911 </p>
5912 <blockquote class="text">
5913 <p>"OK" -
5914 </p>
5915 <blockquote class="text">
5916 <p>always
5917 </p>
5918 </blockquote>
5919
5920
5921 </blockquote><p>
5922
5923 </p>
5924 <p>Examples:
5925 </p>
5926 <p>
5927 </p>
5928 <blockquote class="text">
5929 <p>
5930 </p>
5931 </blockquote><p>
5932
5933 </p>
5934 <a name="GET SERVER INFO"></a><br /><hr />
5935 <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>
5936 <a name="rfc.section.6.6.4"></a><h3>6.6.4.&nbsp;
5937 General sampler informations</h3>
5938
5939 <p>The client can ask for general informations about the LinuxSampler
5940 instance by sending the following command:
5941 </p>
5942 <p>
5943 </p>
5944 <blockquote class="text">
5945 <p>GET SERVER INFO
5946 </p>
5947 </blockquote><p>
5948
5949 </p>
5950 <p>Possible Answers:
5951 </p>
5952 <p>
5953 </p>
5954 <blockquote class="text">
5955 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
5956 Each answer line begins with the information category name
5957 followed by a colon and then a space character &lt;SP&gt; and finally
5958 the info character string to that information category. At the
5959 moment the following categories are defined:
5960
5961 </p>
5962 <p>
5963 </p>
5964 <blockquote class="text">
5965 <p>DESCRIPTION -
5966 </p>
5967 <blockquote class="text">
5968 <p>arbitrary textual description about the sampler
5969 </p>
5970 </blockquote>
5971
5972
5973 <p>VERSION -
5974 </p>
5975 <blockquote class="text">
5976 <p>version of the sampler
5977 </p>
5978 </blockquote>
5979
5980
5981 <p>PROTOCOL_VERSION -
5982 </p>
5983 <blockquote class="text">
5984 <p>version of the LSCP specification the sampler
5985 complies with (see <a class='info' href='#LSCP versioning'>Section&nbsp;2<span> (</span><span class='info'>Versioning of this specification</span><span>)</span></a> for details)
5986 </p>
5987 </blockquote>
5988
5989
5990 </blockquote>
5991
5992
5993 </blockquote><p>
5994
5995 </p>
5996 <p>The mentioned fields above don't have to be in particular order.
5997 Other fields might be added in future.
5998 </p>
5999 <a name="GET VOLUME"></a><br /><hr />
6000 <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>
6001 <a name="rfc.section.6.6.5"></a><h3>6.6.5.&nbsp;
6002 Getting global volume attenuation</h3>
6003
6004 <p>The client can ask for the current global sampler-wide volume
6005 attenuation by sending the following command:
6006 </p>
6007 <p>
6008 </p>
6009 <blockquote class="text">
6010 <p>GET VOLUME
6011 </p>
6012 </blockquote><p>
6013
6014 </p>
6015 <p>Possible Answers:
6016 </p>
6017 <p>
6018 </p>
6019 <blockquote class="text">
6020 <p>The sampler will always answer by returning the optional
6021 dotted floating point coefficient, reflecting the current
6022 global volume attenuation.
6023
6024 </p>
6025 </blockquote><p>
6026
6027 </p>
6028 <p>Note: it is up to the respective sampler engine whether to obey
6029 that global volume parameter or not, but in general all engines SHOULD
6030 use this parameter.
6031 </p>
6032 <a name="SET VOLUME"></a><br /><hr />
6033 <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>
6034 <a name="rfc.section.6.6.6"></a><h3>6.6.6.&nbsp;
6035 Setting global volume attenuation</h3>
6036
6037 <p>The client can alter the current global sampler-wide volume
6038 attenuation by sending the following command:
6039 </p>
6040 <p>
6041 </p>
6042 <blockquote class="text">
6043 <p>SET VOLUME &lt;volume&gt;
6044 </p>
6045 </blockquote><p>
6046
6047 </p>
6048 <p>Where &lt;volume&gt; should be replaced by the optional dotted
6049 floating point value, reflecting the new global volume parameter.
6050 This value might usually be in the range between 0.0 and 1.0, that
6051 is for attenuating the overall volume.
6052 </p>
6053 <p>Possible Answers:
6054 </p>
6055 <p>
6056 </p>
6057 <blockquote class="text">
6058 <p>"OK" -
6059 </p>
6060 <blockquote class="text">
6061 <p>on success
6062 </p>
6063 </blockquote>
6064
6065
6066 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6067 </p>
6068 <blockquote class="text">
6069 <p>if the global volume was set, but there are noteworthy
6070 issue(s) related, providing an appropriate warning code and
6071 warning message
6072 </p>
6073 </blockquote>
6074
6075
6076 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6077 </p>
6078 <blockquote class="text">
6079 <p>in case it failed, providing an appropriate error code and error message
6080 </p>
6081 </blockquote>
6082
6083
6084 </blockquote><p>
6085
6086 </p>
6087 <a name="MIDI Instrument Mapping"></a><br /><hr />
6088 <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>
6089 <a name="rfc.section.6.7"></a><h3>6.7.&nbsp;
6090 MIDI Instrument Mapping</h3>
6091
6092 <p>The MIDI protocol provides a way to switch between instruments
6093 by sending so called MIDI bank select and MIDI program change
6094 messages which are essentially just numbers. The following commands
6095 allow to actually map arbitrary MIDI bank select / program change
6096 numbers with real instruments.
6097 </p>
6098 <p>The sampler allows to manage an arbitrary amount of MIDI
6099 instrument maps which define which instrument to load on
6100 which MIDI program change message.
6101 </p>
6102 <p>By default, that is when the sampler is launched, there is no
6103 map, thus the sampler will simply ignore all program change
6104 messages. The front-end has to explicitly create at least one
6105 map, add entries to the map and tell the respective sampler
6106 channel(s) which MIDI instrument map to use, so the sampler
6107 knows how to react on a given program change message on the
6108 respective sampler channel, that is by switching to the
6109 respectively defined engine type and loading the respective
6110 instrument. See command
6111 <a class='info' href='#SET CHANNEL MIDI_INSTRUMENT_MAP'>"SET CHANNEL MIDI_INSTRUMENT_MAP"<span> (</span><span class='info'>Assigning a MIDI instrument map to a sampler channel</span><span>)</span></a>
6112 for how to assign a MIDI instrument map to a sampler channel.
6113 </p>
6114 <p>Also note per MIDI specification a bank select message does not
6115 cause to switch to another instrument. Instead when receiving a
6116 bank select message the bank value will be stored and a subsequent
6117 program change message (which may occur at any time) will finally
6118 cause the sampler to switch to the respective instrument as
6119 reflected by the current MIDI instrument map.
6120 </p>
6121 <a name="ADD MIDI_INSTRUMENT MAP"></a><br /><hr />
6122 <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>
6123 <a name="rfc.section.6.7.1"></a><h3>6.7.1.&nbsp;
6124 Create a new MIDI instrument map</h3>
6125
6126 <p>The front-end can add a new MIDI instrument map by sending
6127 the following command:
6128 </p>
6129 <p>
6130 </p>
6131 <blockquote class="text">
6132 <p>ADD MIDI_INSTRUMENT_MAP [&lt;name&gt;]
6133 </p>
6134 </blockquote><p>
6135
6136 </p>
6137 <p>Where &lt;name&gt; is an optional argument allowing to
6138 assign a custom name to the new map. MIDI instrument Map
6139 names do not have to be unique.
6140 </p>
6141 <p>Possible Answers:
6142 </p>
6143 <p>
6144 </p>
6145 <blockquote class="text">
6146 <p>"OK[&lt;map&gt;]" -
6147 </p>
6148 <blockquote class="text">
6149 <p>in case a new MIDI instrument map could
6150 be added, where &lt;map&gt; reflects the
6151 unique ID of the newly created MIDI
6152 instrument map
6153 </p>
6154 </blockquote>
6155
6156
6157 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6158 </p>
6159 <blockquote class="text">
6160 <p>when a new map could not be created, which
6161 might never occur in practice
6162 </p>
6163 </blockquote>
6164
6165
6166 </blockquote><p>
6167
6168 </p>
6169 <p>Examples:
6170 </p>
6171 <p>
6172 </p>
6173 <blockquote class="text">
6174 <p>C: "ADD MIDI_INSTRUMENT_MAP 'Standard Map'"
6175 </p>
6176 <p>S: "OK[0]"
6177 </p>
6178 </blockquote><p>
6179
6180 </p>
6181 <p>
6182 </p>
6183 <blockquote class="text">
6184 <p>C: "ADD MIDI_INSTRUMENT_MAP 'Standard Drumkit'"
6185 </p>
6186 <p>S: "OK[1]"
6187 </p>
6188 </blockquote><p>
6189
6190 </p>
6191 <p>
6192 </p>
6193 <blockquote class="text">
6194 <p>C: "ADD MIDI_INSTRUMENT_MAP"
6195 </p>
6196 <p>S: "OK[5]"
6197 </p>
6198 </blockquote><p>
6199
6200 </p>
6201 <a name="REMOVE MIDI_INSTRUMENT_MAP"></a><br /><hr />
6202 <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>
6203 <a name="rfc.section.6.7.2"></a><h3>6.7.2.&nbsp;
6204 Delete one particular or all MIDI instrument maps</h3>
6205
6206 <p>The front-end can delete a particular MIDI instrument map
6207 by sending the following command:
6208 </p>
6209 <p>
6210 </p>
6211 <blockquote class="text">
6212 <p>REMOVE MIDI_INSTRUMENT_MAP &lt;map&gt;
6213 </p>
6214 </blockquote><p>
6215
6216 </p>
6217 <p>Where &lt;map&gt; reflects the unique ID of the map to delete
6218 as returned by the <a class='info' href='#LIST MIDI_INSTRUMENT_MAPS'>"LIST MIDI_INSTRUMENT_MAPS"<span> (</span><span class='info'>Getting all created MIDI instrument maps</span><span>)</span></a>
6219 command.
6220 </p>
6221 <p>The front-end can delete all MIDI instrument maps by
6222 sending the following command:
6223 </p>
6224 <p>
6225 </p>
6226 <blockquote class="text">
6227 <p>REMOVE MIDI_INSTRUMENT_MAP ALL
6228 </p>
6229 </blockquote><p>
6230
6231 </p>
6232 <p>Possible Answers:
6233 </p>
6234 <p>
6235 </p>
6236 <blockquote class="text">
6237 <p>"OK" -
6238 </p>
6239 <blockquote class="text">
6240 <p>in case the map(s) could be deleted
6241 </p>
6242 </blockquote>
6243
6244
6245 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6246 </p>
6247 <blockquote class="text">
6248 <p>when the given map does not exist
6249 </p>
6250 </blockquote>
6251
6252
6253 </blockquote><p>
6254
6255 </p>
6256 <p>Examples:
6257 </p>
6258 <p>
6259 </p>
6260 <blockquote class="text">
6261 <p>C: "REMOVE MIDI_INSTRUMENT_MAP 0"
6262 </p>
6263 <p>S: "OK"
6264 </p>
6265 </blockquote><p>
6266
6267 </p>
6268 <p>
6269 </p>
6270 <blockquote class="text">
6271 <p>C: "REMOVE MIDI_INSTRUMENT_MAP ALL"
6272 </p>
6273 <p>S: "OK"
6274 </p>
6275 </blockquote><p>
6276
6277 </p>
6278 <a name="GET MIDI_INSTRUMENT_MAPS"></a><br /><hr />
6279 <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>
6280 <a name="rfc.section.6.7.3"></a><h3>6.7.3.&nbsp;
6281 Get amount of existing MIDI instrument maps</h3>
6282
6283 <p>The front-end can retrieve the current amount of MIDI
6284 instrument maps by sending the following command:
6285 </p>
6286 <p>
6287 </p>
6288 <blockquote class="text">
6289 <p>GET MIDI_INSTRUMENT_MAPS
6290 </p>
6291 </blockquote><p>
6292
6293 </p>
6294 <p>Possible Answers:
6295 </p>
6296 <p>
6297 </p>
6298 <blockquote class="text">
6299 <p>The sampler will answer by returning the current
6300 number of MIDI instrument maps.
6301 </p>
6302 </blockquote><p>
6303
6304 </p>
6305 <p>Example:
6306 </p>
6307 <p>
6308 </p>
6309 <blockquote class="text">
6310 <p>C: "GET MIDI_INSTRUMENT_MAPS"
6311 </p>
6312 <p>S: "2"
6313 </p>
6314 </blockquote><p>
6315
6316 </p>
6317 <a name="LIST MIDI_INSTRUMENT_MAPS"></a><br /><hr />
6318 <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>
6319 <a name="rfc.section.6.7.4"></a><h3>6.7.4.&nbsp;
6320 Getting all created MIDI instrument maps</h3>
6321
6322 <p>The number of MIDI instrument maps can change on runtime. To get the
6323 current list of MIDI instrument maps, the front-end can send the
6324 following command:
6325 </p>
6326 <p>
6327 </p>
6328 <blockquote class="text">
6329 <p>LIST MIDI_INSTRUMENT_MAPS
6330 </p>
6331 </blockquote><p>
6332
6333 </p>
6334 <p>Possible Answers:
6335 </p>
6336 <p>
6337 </p>
6338 <blockquote class="text">
6339 <p>The sampler will answer by returning a comma separated list
6340 with all MIDI instrument maps' numerical IDs.
6341 </p>
6342 </blockquote><p>
6343
6344 </p>
6345 <p>Example:
6346 </p>
6347 <p>
6348 </p>
6349 <blockquote class="text">
6350 <p>C: "LIST MIDI_INSTRUMENT_MAPS"
6351 </p>
6352 <p>S: "0,1,5,12"
6353 </p>
6354 </blockquote><p>
6355
6356 </p>
6357 <a name="GET MIDI_INSTRUMENT_MAP INFO"></a><br /><hr />
6358 <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>
6359 <a name="rfc.section.6.7.5"></a><h3>6.7.5.&nbsp;
6360 Getting MIDI instrument map information</h3>
6361
6362 <p>The front-end can ask for the current settings of a MIDI
6363 instrument map by sending the following command:
6364 </p>
6365 <p>
6366 </p>
6367 <blockquote class="text">
6368 <p>GET MIDI_INSTRUMENT_MAP INFO &lt;map&gt;
6369 </p>
6370 </blockquote><p>
6371
6372 </p>
6373 <p>Where &lt;map&gt; is the numerical ID of the map the
6374 front-end is interested in as returned by the
6375 <a class='info' href='#LIST MIDI_INSTRUMENT_MAPS'>"LIST MIDI_INSTRUMENT_MAPS"<span> (</span><span class='info'>Getting all created MIDI instrument maps</span><span>)</span></a>
6376 command.
6377 </p>
6378 <p>Possible Answers:
6379 </p>
6380 <p>
6381 </p>
6382 <blockquote class="text">
6383 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6384 Each answer line begins with the settings category name
6385 followed by a colon and then a space character &lt;SP&gt; and finally
6386 the info character string to that setting category. At the
6387 moment the following categories are defined:
6388 </p>
6389 <p>
6390 </p>
6391 <blockquote class="text">
6392 <p>NAME -
6393 </p>
6394 <blockquote class="text">
6395 <p>custom name of the given map,
6396 which does not have to be unique
6397 </p>
6398 </blockquote>
6399
6400
6401 </blockquote>
6402
6403
6404 </blockquote><p>
6405
6406 </p>
6407 <p>The mentioned fields above don't have to be in particular order.
6408 </p>
6409 <p>Example:
6410 </p>
6411 <p>
6412 </p>
6413 <blockquote class="text">
6414 <p>C: "GET MIDI_INSTRUMENT_MAP INFO 0"
6415 </p>
6416 <p>S: "NAME: Standard Map"
6417 </p>
6418 <p>&nbsp;&nbsp;&nbsp;"."
6419 </p>
6420 </blockquote><p>
6421
6422 </p>
6423 <a name="SET MIDI_INSTRUMENT_MAP NAME"></a><br /><hr />
6424 <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>
6425 <a name="rfc.section.6.7.6"></a><h3>6.7.6.&nbsp;
6426 Renaming a MIDI instrument map</h3>
6427
6428 <p>The front-end can alter the custom name of a MIDI
6429 instrument map by sending the following command:
6430 </p>
6431 <p>
6432 </p>
6433 <blockquote class="text">
6434 <p>SET MIDI_INSTRUMENT_MAP NAME &lt;map&gt; &lt;name&gt;
6435 </p>
6436 </blockquote><p>
6437
6438 </p>
6439 <p>Where &lt;map&gt; is the numerical ID of the map and
6440 &lt;name&gt; the new custom name of the map, which does not
6441 have to be unique.
6442 </p>
6443 <p>Possible Answers:
6444 </p>
6445 <p>
6446 </p>
6447 <blockquote class="text">
6448 <p>"OK" -
6449 </p>
6450 <blockquote class="text">
6451 <p>on success
6452 </p>
6453 </blockquote>
6454
6455
6456 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6457 </p>
6458 <blockquote class="text">
6459 <p>in case the given map does not exist
6460 </p>
6461 </blockquote>
6462
6463
6464 </blockquote><p>
6465
6466 </p>
6467 <p>Example:
6468 </p>
6469 <p>
6470 </p>
6471 <blockquote class="text">
6472 <p>C: "SET MIDI_INSTRUMENT_MAP NAME 0 'Foo instruments'"
6473 </p>
6474 <p>S: "OK"
6475 </p>
6476 </blockquote><p>
6477
6478 </p>
6479 <a name="MAP MIDI_INSTRUMENT"></a><br /><hr />
6480 <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>
6481 <a name="rfc.section.6.7.7"></a><h3>6.7.7.&nbsp;
6482 Create or replace a MIDI instrument map entry</h3>
6483
6484 <p>The front-end can create a new or replace an existing entry
6485 in a sampler's MIDI instrument map by sending the following
6486 command:
6487 </p>
6488 <p>
6489 </p>
6490 <blockquote class="text">
6491 <p>MAP MIDI_INSTRUMENT [NON_MODAL] &lt;map&gt;
6492 &lt;midi_bank&gt; &lt;midi_prog&gt; &lt;engine_name&gt;
6493 &lt;filename&gt; &lt;instrument_index&gt; &lt;volume_value&gt;
6494 [&lt;instr_load_mode&gt;] [&lt;name&gt;]
6495 </p>
6496 </blockquote><p>
6497
6498 </p>
6499 <p>Where &lt;map&gt; is the numeric ID of the map to alter,
6500 &lt;midi_bank&gt; is an integer value between
6501 0..16383 reflecting the MIDI bank select index,
6502 &lt;midi_prog&gt; an
6503 integer value between 0..127 reflecting the MIDI program change
6504 index, &lt;engine_name&gt; a sampler engine name as returned by
6505 the <a class='info' href='#LIST AVAILABLE_ENGINES'>"LIST AVAILABLE_ENGINES"<span> (</span><span class='info'>Getting all available engines</span><span>)</span></a>
6506 command (not encapsulated into apostrophes), &lt;filename&gt; the name
6507 of the instrument's file to be deployed (encapsulated into apostrophes),
6508 &lt;instrument_index&gt; the index (integer value) of the instrument
6509 within the given file, &lt;volume_value&gt; reflects the master
6510 volume of the instrument as optionally dotted number (where a
6511 value &lt; 1.0 means attenuation and a value > 1.0 means
6512 amplification). This parameter easily allows to adjust the
6513 volume of all intruments within a custom instrument map
6514 without having to adjust their instrument files. The
6515 OPTIONAL &lt;instr_load_mode&gt; argument defines the life
6516 time of the instrument, that is when the instrument should
6517 be loaded, when freed and has exactly the following
6518 possibilities:
6519 </p>
6520 <p>
6521 </p>
6522 <blockquote class="text">
6523 <p>"ON_DEMAND" -
6524 </p>
6525 <blockquote class="text">
6526 <p>The instrument will be loaded when needed,
6527 that is when demanded by at least one sampler
6528 channel. It will immediately be freed from memory
6529 when not needed by any sampler channel anymore.
6530 </p>
6531 </blockquote>
6532
6533
6534 <p>"ON_DEMAND_HOLD" -
6535 </p>
6536 <blockquote class="text">
6537 <p>The instrument will be loaded when needed,
6538 that is when demanded by at least one sampler
6539 channel. It will be kept in memory even when
6540 not needed by any sampler channel anymore.
6541 Instruments with this mode are only freed
6542 when the sampler is reset or all mapping
6543 entries with this mode (and respective
6544 instrument) are explicitly changed to
6545 "ON_DEMAND" and no sampler channel is using
6546 the instrument anymore.
6547 </p>
6548 </blockquote>
6549
6550
6551 <p>"PERSISTENT" -
6552 </p>
6553 <blockquote class="text">
6554 <p>The instrument will immediately be loaded
6555 into memory when this mapping
6556 command is sent and the instrument is kept all
6557 the time. Instruments with this mode are
6558 only freed when the sampler is reset or all
6559 mapping entries with this mode (and
6560 respective instrument) are explicitly
6561 changed to "ON_DEMAND" and no sampler
6562 channel is using the instrument anymore.
6563 </p>
6564 </blockquote>
6565
6566
6567 <p>not supplied -
6568 </p>
6569 <blockquote class="text">
6570 <p>In case there is no &lt;instr_load_mode&gt;
6571 argument given, it will be up to the
6572 InstrumentManager to decide which mode to use.
6573 Usually it will use "ON_DEMAND" if an entry
6574 for the given instrument does not exist in
6575 the InstrumentManager's list yet, otherwise
6576 if an entry already exists, it will simply
6577 stick with the mode currently reflected by
6578 the already existing entry, that is it will
6579 not change the mode.
6580 </p>
6581 </blockquote>
6582
6583
6584 </blockquote><p>
6585
6586 </p>
6587 <p>
6588 The &lt;instr_load_mode&gt; argument thus allows to define an
6589 appropriate strategy (low memory consumption vs. fast
6590 instrument switching) for each instrument individually. Note, the
6591 following restrictions apply to this argument: "ON_DEMAND_HOLD" and
6592 "PERSISTENT" have to be supported by the respective sampler engine
6593 (which is technically the case when the engine provides an
6594 InstrumentManager for its format). If this is not the case the
6595 argument will automatically fall back to the default value
6596 "ON_DEMAND". Also the load mode of one instrument may
6597 automatically change the laod mode of other instrument(s), i.e.
6598 because the instruments are part of the same file and the
6599 engine does not allow a way to manage load modes for them
6600 individually. Due to this, in case the frontend shows the
6601 load modes of entries, the frontend should retrieve the actual
6602 mode by i.e. sending
6603 <a class='info' href='#GET MIDI_INSTRUMENT INFO'>"GET MIDI_INSTRUMENT INFO"<span> (</span><span class='info'>Get current settings of MIDI instrument map entry</span><span>)</span></a>
6604 command(s). Finally the OPTIONAL &lt;name&gt; argument allows to
6605 set a custom name (encapsulated into apostrophes) for the mapping
6606 entry, useful for frontends for displaying an appropriate name for
6607 mapped instruments (using
6608 <a class='info' href='#GET MIDI_INSTRUMENT INFO'>"GET MIDI_INSTRUMENT INFO"<span> (</span><span class='info'>Get current settings of MIDI instrument map entry</span><span>)</span></a>).
6609
6610 </p>
6611 <p>
6612 By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is
6613 completely established in the sampler. The OPTIONAL "NON_MODAL" argument
6614 however causes the respective "MAP MIDI_INSTRUMENT" command to return
6615 immediately, that is to let the sampler establish the mapping in the
6616 background. So this argument might be especially useful for mappings with
6617 a "PERSISTENT" type, because these have to load the respective instruments
6618 immediately and might thus block for a very long time. It is recommended
6619 however to use the OPTIONAL "NON_MODAL" argument only if really necessary,
6620 because it has the following drawbacks: as "NON_MODAL" instructions return
6621 immediately, they may not necessarily return an error i.e. when the given
6622 instrument file turns out to be corrupt, beside that subsequent commands
6623 in a LSCP instruction sequence might fail, because mandatory mappings are
6624 not yet completed.
6625
6626 </p>
6627 <p>Possible Answers:
6628 </p>
6629 <p>
6630 </p>
6631 <blockquote class="text">
6632 <p>"OK" -
6633 </p>
6634 <blockquote class="text">
6635 <p>usually
6636 </p>
6637 </blockquote>
6638
6639
6640 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6641 </p>
6642 <blockquote class="text">
6643 <p>when the given map or engine does not exist or a value
6644 is out of range
6645 </p>
6646 </blockquote>
6647
6648
6649 </blockquote><p>
6650
6651 </p>
6652 <p>Examples:
6653 </p>
6654 <p>
6655 </p>
6656 <blockquote class="text">
6657 <p>C: "MAP MIDI_INSTRUMENT 0 3 0 gig '/usr/share/Steinway D.gig' 0 0.8 PERSISTENT"
6658 </p>
6659 <p>S: "OK"
6660 </p>
6661 </blockquote><p>
6662
6663 </p>
6664 <p>
6665 </p>
6666 <blockquote class="text">
6667 <p>C: "MAP MIDI_INSTRUMENT 0 4 50 gig '/home/john/foostrings.gig' 7 1.0"
6668 </p>
6669 <p>S: "OK"
6670 </p>
6671 </blockquote><p>
6672
6673 </p>
6674 <p>
6675 </p>
6676 <blockquote class="text">
6677 <p>C: "MAP MIDI_INSTRUMENT 0 0 0 gig '/usr/share/piano.gig' 0 1.0 'Normal Piano'"
6678 </p>
6679 <p>S: "OK"
6680 </p>
6681 <p>C: "MAP MIDI_INSTRUMENT 0 1 0 gig '/usr/share/piano.gig' 0 0.25 'Silent Piano'"
6682 </p>
6683 <p>S: "OK"
6684 </p>
6685 </blockquote><p>
6686
6687 </p>
6688 <p>
6689 </p>
6690 <blockquote class="text">
6691 <p>C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"
6692 </p>
6693 <p>S: "OK"
6694 </p>
6695 </blockquote><p>
6696
6697 </p>
6698 <a name="GET MIDI_INSTRUMENTS"></a><br /><hr />
6699 <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>
6700 <a name="rfc.section.6.7.8"></a><h3>6.7.8.&nbsp;
6701 Getting ammount of MIDI instrument map entries</h3>
6702
6703 <p>The front-end can query the amount of currently existing
6704 entries in a MIDI instrument map by sending the following
6705 command:
6706 </p>
6707 <p>
6708 </p>
6709 <blockquote class="text">
6710 <p>GET MIDI_INSTRUMENTS &lt;map&gt;
6711 </p>
6712 </blockquote><p>
6713
6714 </p>
6715 <p>The front-end can query the amount of currently existing
6716 entries in all MIDI instrument maps by sending the following
6717 command:
6718 </p>
6719 <p>
6720 </p>
6721 <blockquote class="text">
6722 <p>GET MIDI_INSTRUMENTS ALL
6723 </p>
6724 </blockquote><p>
6725
6726 </p>
6727 <p>Possible Answers:
6728 </p>
6729 <p>
6730 </p>
6731 <blockquote class="text">
6732 <p>The sampler will answer by sending the current number of
6733 entries in the MIDI instrument map(s).
6734 </p>
6735 </blockquote><p>
6736
6737 </p>
6738 <p>Example:
6739 </p>
6740 <p>
6741 </p>
6742 <blockquote class="text">
6743 <p>C: "GET MIDI_INSTRUMENTS 0"
6744 </p>
6745 <p>S: "234"
6746 </p>
6747 </blockquote><p>
6748
6749 </p>
6750 <p>
6751 </p>
6752 <blockquote class="text">
6753 <p>C: "GET MIDI_INSTRUMENTS ALL"
6754 </p>
6755 <p>S: "954"
6756 </p>
6757 </blockquote><p>
6758
6759 </p>
6760 <a name="LIST MIDI_INSTRUMENTS"></a><br /><hr />
6761 <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>
6762 <a name="rfc.section.6.7.9"></a><h3>6.7.9.&nbsp;
6763 Getting indeces of all entries of a MIDI instrument map</h3>
6764
6765 <p>The front-end can query a list of all currently existing
6766 entries in a certain MIDI instrument map by sending the following
6767 command:
6768 </p>
6769 <p>
6770 </p>
6771 <blockquote class="text">
6772 <p>LIST MIDI_INSTRUMENTS &lt;map&gt;
6773 </p>
6774 </blockquote><p>
6775
6776 </p>
6777 <p>Where &lt;map&gt; is the numeric ID of the MIDI instrument map.
6778 </p>
6779 <p>The front-end can query a list of all currently existing
6780 entries of all MIDI instrument maps by sending the following
6781 command:
6782 </p>
6783 <p>
6784 </p>
6785 <blockquote class="text">
6786 <p>LIST MIDI_INSTRUMENTS ALL
6787 </p>
6788 </blockquote><p>
6789
6790 </p>
6791 <p>Possible Answers:
6792 </p>
6793 <p>
6794 </p>
6795 <blockquote class="text">
6796 <p>The sampler will answer by sending a comma separated
6797 list of map ID - MIDI bank - MIDI program triples, where
6798 each triple is encapsulated into curly braces. The
6799 list is returned in one single line. Each triple
6800 just reflects the key of the respective map entry,
6801 thus subsequent
6802 <a class='info' href='#GET MIDI_INSTRUMENT INFO'>"GET MIDI_INSTRUMENT INFO"<span> (</span><span class='info'>Get current settings of MIDI instrument map entry</span><span>)</span></a>
6803 command(s) are necessary to retrieve detailed informations
6804 about each entry.
6805 </p>
6806 </blockquote><p>
6807
6808 </p>
6809 <p>Example:
6810 </p>
6811 <p>
6812 </p>
6813 <blockquote class="text">
6814 <p>C: "LIST MIDI_INSTRUMENTS 0"
6815 </p>
6816 <p>S: "{0,0,0},{0,0,1},{0,0,3},{0,1,4},{1,127,127}"
6817 </p>
6818 </blockquote><p>
6819
6820 </p>
6821 <a name="UNMAP MIDI_INSTRUMENT"></a><br /><hr />
6822 <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>
6823 <a name="rfc.section.6.7.10"></a><h3>6.7.10.&nbsp;
6824 Remove an entry from the MIDI instrument map</h3>
6825
6826 <p>The front-end can delete an entry from a MIDI instrument
6827 map by sending the following command:
6828 </p>
6829 <p>
6830 </p>
6831 <blockquote class="text">
6832 <p>UNMAP MIDI_INSTRUMENT &lt;map&gt; &lt;midi_bank&gt; &lt;midi_prog&gt;
6833 </p>
6834 </blockquote><p>
6835
6836 </p>
6837 <p>
6838 Where &lt;map&gt; is the numeric ID of the MIDI instrument map,
6839 &lt;midi_bank&gt; is an integer value between 0..16383
6840 reflecting the MIDI bank value and
6841 &lt;midi_prog&gt; an integer value between
6842 0..127 reflecting the MIDI program value of the map's entrie's key
6843 index triple.
6844
6845 </p>
6846 <p>Possible Answers:
6847 </p>
6848 <p>
6849 </p>
6850 <blockquote class="text">
6851 <p>"OK" -
6852 </p>
6853 <blockquote class="text">
6854 <p>usually
6855 </p>
6856 </blockquote>
6857
6858
6859 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6860 </p>
6861 <blockquote class="text">
6862 <p>when index out of bounds
6863 </p>
6864 </blockquote>
6865
6866
6867 </blockquote><p>
6868
6869 </p>
6870 <p>Example:
6871 </p>
6872 <p>
6873 </p>
6874 <blockquote class="text">
6875 <p>C: "UNMAP MIDI_INSTRUMENT 0 2 127"
6876 </p>
6877 <p>S: "OK"
6878 </p>
6879 </blockquote><p>
6880
6881 </p>
6882 <a name="GET MIDI_INSTRUMENT INFO"></a><br /><hr />
6883 <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>
6884 <a name="rfc.section.6.7.11"></a><h3>6.7.11.&nbsp;
6885 Get current settings of MIDI instrument map entry</h3>
6886
6887 <p>The front-end can retrieve the current settings of a certain
6888 instrument map entry by sending the following command:
6889 </p>
6890 <p>
6891 </p>
6892 <blockquote class="text">
6893 <p>GET MIDI_INSTRUMENT INFO &lt;map&gt; &lt;midi_bank&gt; &lt;midi_prog&gt;
6894 </p>
6895 </blockquote><p>
6896
6897 </p>
6898 <p>
6899 Where &lt;map&gt; is the numeric ID of the MIDI instrument map,
6900 &lt;midi_bank&gt; is an integer value between 0..16383
6901 reflecting the MIDI bank value, &lt;midi_bank&gt;
6902 and &lt;midi_prog&gt; an integer value between
6903 0..127 reflecting the MIDI program value of the map's entrie's key
6904 index triple.
6905
6906 </p>
6907 <p>Possible Answers:
6908 </p>
6909 <p>
6910 </p>
6911 <blockquote class="text">
6912 <p>LinuxSampler will answer by sending a &lt;CRLF&gt;
6913 separated list. Each answer line begins with the
6914 information category name followed by a colon and then
6915 a space character &lt;SP&gt; and finally the info
6916 character string to that info category. At the moment
6917 the following categories are defined:
6918 </p>
6919 <p>"NAME" -
6920 </p>
6921 <blockquote class="text">
6922 <p>Name for this MIDI instrument map entry (if defined).
6923 This name shall be used by frontends for displaying a
6924 name for this mapped instrument. It can be set and
6925 changed with the
6926 <a class='info' href='#MAP MIDI_INSTRUMENT'>"MAP MIDI_INSTRUMENT"<span> (</span><span class='info'>Create or replace a MIDI instrument map entry</span><span>)</span></a>
6927 command and does not have to be unique.
6928 </p>
6929 </blockquote>
6930
6931
6932 <p>"ENGINE_NAME" -
6933 </p>
6934 <blockquote class="text">
6935 <p>Name of the engine to be deployed for this
6936 instrument.
6937 </p>
6938 </blockquote>
6939
6940
6941 <p>"INSTRUMENT_FILE" -
6942 </p>
6943 <blockquote class="text">
6944 <p>File name of the instrument.
6945 </p>
6946 </blockquote>
6947
6948
6949 <p>"INSTRUMENT_NR" -
6950 </p>
6951 <blockquote class="text">
6952 <p>Index of the instrument within the file.
6953 </p>
6954 </blockquote>
6955
6956
6957 <p>"INSTRUMENT_NAME" -
6958 </p>
6959 <blockquote class="text">
6960 <p>Name of the loaded instrument as reflected by its file.
6961 In contrast to the "NAME" field, the "INSTRUMENT_NAME" field
6962 cannot be changed.
6963 </p>
6964 </blockquote>
6965
6966
6967 <p>"LOAD_MODE" -
6968 </p>
6969 <blockquote class="text">
6970 <p>Life time of instrument
6971 (see <a class='info' href='#MAP MIDI_INSTRUMENT'>"MAP MIDI_INSTRUMENT"<span> (</span><span class='info'>Create or replace a MIDI instrument map entry</span><span>)</span></a> for details about this setting).
6972 </p>
6973 </blockquote>
6974
6975
6976 <p>"VOLUME" -
6977 </p>
6978 <blockquote class="text">
6979 <p>master volume of the instrument as optionally
6980 dotted number (where a value &lt; 1.0 means attenuation
6981 and a value > 1.0 means amplification)
6982 </p>
6983 </blockquote>
6984
6985
6986 <p>The mentioned fields above don't have to be in particular order.
6987 </p>
6988 </blockquote><p>
6989
6990 </p>
6991 <p>Example:
6992 </p>
6993 <p>
6994 </p>
6995 <blockquote class="text">
6996 <p>C: "GET MIDI_INSTRUMENT INFO 1 45 120"
6997 </p>
6998 <p>S: "NAME: Drums for Foo Song"
6999 </p>
7000 <p>&nbsp;&nbsp;&nbsp;"ENGINE_NAME: GigEngine"
7001 </p>
7002 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_FILE: /usr/share/joesdrumkit.gig"
7003 </p>
7004 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"
7005 </p>
7006 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NAME: Joe's Drumkit"
7007 </p>
7008 <p>&nbsp;&nbsp;&nbsp;"LOAD_MODE: PERSISTENT"
7009 </p>
7010 <p>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"
7011 </p>
7012 <p>&nbsp;&nbsp;&nbsp;"."
7013 </p>
7014 </blockquote><p>
7015
7016 </p>
7017 <a name="CLEAR MIDI_INSTRUMENTS"></a><br /><hr />
7018 <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>
7019 <a name="rfc.section.6.7.12"></a><h3>6.7.12.&nbsp;
7020 Clear MIDI instrument map</h3>
7021
7022 <p>The front-end can clear a whole MIDI instrument map, that
7023 is delete all its entries by sending the following command:
7024 </p>
7025 <p>
7026 </p>
7027 <blockquote class="text">
7028 <p>CLEAR MIDI_INSTRUMENTS &lt;map&gt;
7029 </p>
7030 </blockquote><p>
7031
7032 </p>
7033 <p>Where &lt;map&gt; is the numeric ID of the map to clear.
7034 </p>
7035 <p>The front-end can clear all MIDI instrument maps, that
7036 is delete all entries of all maps by sending the following
7037 command:
7038 </p>
7039 <p>
7040 </p>
7041 <blockquote class="text">
7042 <p>CLEAR MIDI_INSTRUMENTS ALL
7043 </p>
7044 </blockquote><p>
7045
7046 </p>
7047 <p>The command "CLEAR MIDI_INSTRUMENTS ALL" does not delete the
7048 maps, only their entries, thus the map's settings like
7049 custom name will be preservevd.
7050 </p>
7051 <p>Possible Answers:
7052 </p>
7053 <p>
7054 </p>
7055 <blockquote class="text">
7056 <p>"OK" -
7057 </p>
7058 <blockquote class="text">
7059 <p>always
7060 </p>
7061 </blockquote>
7062
7063
7064 </blockquote><p>
7065
7066 </p>
7067 <p>Examples:
7068 </p>
7069 <p>
7070 </p>
7071 <blockquote class="text">
7072 <p>C: "CLEAR MIDI_INSTRUMENTS 0"
7073 </p>
7074 <p>S: "OK"
7075 </p>
7076 </blockquote><p>
7077
7078 </p>
7079 <p>
7080 </p>
7081 <blockquote class="text">
7082 <p>C: "CLEAR MIDI_INSTRUMENTS ALL"
7083 </p>
7084 <p>S: "OK"
7085 </p>
7086 </blockquote><p>
7087
7088 </p>
7089 <a name="command_syntax"></a><br /><hr />
7090 <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>
7091 <a name="rfc.section.7"></a><h3>7.&nbsp;
7092 Command Syntax</h3>
7093
7094 <p>The grammar of the control protocol as descibed in <a class='info' href='#control_commands'>Section&nbsp;6<span> (</span><span class='info'>Description for control commands</span><span>)</span></a>
7095 is defined below using Backus-Naur Form (BNF as described in <a class='info' href='#RFC2234'>[RFC2234]<span> (</span><span class='info'>Crocker, D. and P. Overell, &ldquo;Augmented BNF for Syntax Specifications,&rdquo; 1997.</span><span>)</span></a>)
7096 where applicable.
7097
7098 </p>
7099 <p>input =
7100 </p>
7101 <blockquote class="text">
7102 <p>line LF
7103
7104 </p>
7105 <p>/ line CR LF
7106
7107 </p>
7108 </blockquote><p>
7109
7110 </p>
7111 <p>line =
7112 </p>
7113 <blockquote class="text">
7114 <p>/* epsilon (empty line ignored) */
7115
7116 </p>
7117 <p>/ comment
7118
7119 </p>
7120 <p>/ command
7121
7122 </p>
7123 <p>/ error
7124
7125 </p>
7126 </blockquote><p>
7127
7128 </p>
7129 <p>comment =
7130 </p>
7131 <blockquote class="text">
7132 <p>'#'
7133
7134 </p>
7135 <p>/ comment '#'
7136
7137 </p>
7138 <p>/ comment SP
7139
7140 </p>
7141 <p>/ comment number
7142
7143 </p>
7144 <p>/ comment string
7145
7146 </p>
7147 </blockquote><p>
7148
7149 </p>
7150 <p>command =
7151 </p>
7152 <blockquote class="text">
7153 <p>ADD SP add_instruction
7154
7155 </p>
7156 <p>/ MAP SP map_instruction
7157
7158 </p>
7159 <p>/ UNMAP SP unmap_instruction
7160
7161 </p>
7162 <p>/ GET SP get_instruction
7163
7164 </p>
7165 <p>/ CREATE SP create_instruction
7166
7167 </p>
7168 <p>/ DESTROY SP destroy_instruction
7169
7170 </p>
7171 <p>/ LIST SP list_instruction
7172
7173 </p>
7174 <p>/ LOAD SP load_instruction
7175
7176 </p>
7177 <p>/ REMOVE SP remove_instruction
7178
7179 </p>
7180 <p>/ SET SP set_instruction
7181
7182 </p>
7183 <p>/ SUBSCRIBE SP subscribe_event
7184
7185 </p>
7186 <p>/ UNSUBSCRIBE SP unsubscribe_event
7187
7188 </p>
7189 <p>/ SELECT SP text
7190
7191 </p>
7192 <p>/ RESET SP reset_instruction
7193
7194 </p>
7195 <p>/ CLEAR SP clear_instruction
7196
7197 </p>
7198 <p>/ RESET
7199
7200 </p>
7201 <p>/ QUIT
7202
7203 </p>
7204 </blockquote><p>
7205
7206 </p>
7207 <p>add_instruction =
7208 </p>
7209 <blockquote class="text">
7210 <p>CHANNEL
7211
7212 </p>
7213 <p>/ MIDI_INSTRUMENT_MAP
7214
7215 </p>
7216 <p>/ MIDI_INSTRUMENT_MAP SP map_name
7217
7218 </p>
7219 </blockquote><p>
7220
7221 </p>
7222 <p>subscribe_event =
7223 </p>
7224 <blockquote class="text">
7225 <p>AUDIO_OUTPUT_DEVICE_COUNT
7226
7227 </p>
7228 <p>/ AUDIO_OUTPUT_DEVICE_INFO
7229
7230 </p>
7231 <p>/ MIDI_INPUT_DEVICE_COUNT
7232
7233 </p>
7234 <p>/ MIDI_INPUT_DEVICE_INFO
7235
7236 </p>
7237 <p>/ CHANNEL_COUNT
7238
7239 </p>
7240 <p>/ VOICE_COUNT
7241
7242 </p>
7243 <p>/ STREAM_COUNT
7244
7245 </p>
7246 <p>/ BUFFER_FILL
7247
7248 </p>
7249 <p>/ CHANNEL_INFO
7250
7251 </p>
7252 <p>/ MIDI_INSTRUMENT_MAP_COUNT
7253
7254 </p>
7255 <p>/ MIDI_INSTRUMENT_MAP_INFO
7256
7257 </p>
7258 <p>/ MIDI_INSTRUMENT_COUNT
7259
7260 </p>
7261 <p>/ MIDI_INSTRUMENT_INFO
7262
7263 </p>
7264 <p>/ MISCELLANEOUS
7265
7266 </p>
7267 <p>/ TOTAL_VOICE_COUNT
7268
7269 </p>
7270 </blockquote><p>
7271
7272 </p>
7273 <p>unsubscribe_event =
7274 </p>
7275 <blockquote class="text">
7276 <p>AUDIO_OUTPUT_DEVICE_COUNT
7277
7278 </p>
7279 <p>/ AUDIO_OUTPUT_DEVICE_INFO
7280
7281 </p>
7282 <p>/ MIDI_INPUT_DEVICE_COUNT
7283
7284 </p>
7285 <p>/ MIDI_INPUT_DEVICE_INFO
7286
7287 </p>
7288 <p>/ CHANNEL_COUNT
7289
7290 </p>
7291 <p>/ VOICE_COUNT
7292
7293 </p>
7294 <p>/ STREAM_COUNT
7295
7296 </p>
7297 <p>/ BUFFER_FILL
7298
7299 </p>
7300 <p>/ CHANNEL_INFO
7301
7302 </p>
7303 <p>/ MIDI_INSTRUMENT_MAP_COUNT
7304
7305 </p>
7306 <p>/ MIDI_INSTRUMENT_MAP_INFO
7307
7308 </p>
7309 <p>/ MIDI_INSTRUMENT_COUNT
7310
7311 </p>
7312 <p>/ MIDI_INSTRUMENT_INFO
7313
7314 </p>
7315 <p>/ MISCELLANEOUS
7316
7317 </p>
7318 <p>/ TOTAL_VOICE_COUNT
7319
7320 </p>
7321 </blockquote><p>
7322
7323 </p>
7324 <p>map_instruction =
7325 </p>
7326 <blockquote class="text">
7327 <p>MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value
7328
7329 </p>
7330 <p>/ MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode
7331
7332 </p>
7333 <p>/ MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP entry_name
7334
7335 </p>
7336 <p>/ MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode SP entry_name
7337
7338 </p>
7339 </blockquote><p>
7340
7341 </p>
7342 <p>unmap_instruction =
7343 </p>
7344 <blockquote class="text">
7345 <p>MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog
7346
7347 </p>
7348 </blockquote><p>
7349
7350 </p>
7351 <p>remove_instruction =
7352 </p>
7353 <blockquote class="text">
7354 <p>CHANNEL SP sampler_channel
7355
7356 </p>
7357 <p>/ MIDI_INSTRUMENT_MAP SP midi_map
7358
7359 </p>
7360 <p>/ MIDI_INSTRUMENT_MAP SP ALL
7361
7362 </p>
7363 </blockquote><p>
7364
7365 </p>
7366 <p>get_instruction =
7367 </p>
7368 <blockquote class="text">
7369 <p>AVAILABLE_ENGINES
7370
7371 </p>
7372 <p>/ AVAILABLE_MIDI_INPUT_DRIVERS
7373
7374 </p>
7375 <p>/ MIDI_INPUT_DRIVER SP INFO SP string
7376
7377 </p>
7378 <p>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
7379
7380 </p>
7381 <p>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
7382
7383 </p>
7384 <p>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
7385
7386 </p>
7387 <p>/ AUDIO_OUTPUT_DRIVER SP INFO SP string
7388
7389 </p>
7390 <p>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
7391
7392 </p>
7393 <p>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
7394
7395 </p>
7396 <p>/ AUDIO_OUTPUT_DEVICES
7397
7398 </p>
7399 <p>/ MIDI_INPUT_DEVICES
7400
7401 </p>
7402 <p>/ AUDIO_OUTPUT_DEVICE SP INFO SP number
7403
7404 </p>
7405 <p>/ MIDI_INPUT_DEVICE SP INFO SP number
7406
7407 </p>
7408 <p>/ MIDI_INPUT_PORT SP INFO SP number SP number
7409
7410 </p>
7411 <p>/ MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
7412
7413 </p>
7414 <p>/ AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
7415
7416 </p>
7417 <p>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP string
7418
7419 </p>
7420 <p>/ CHANNELS
7421
7422 </p>
7423 <p>/ CHANNEL SP INFO SP sampler_channel
7424
7425 </p>
7426 <p>/ CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
7427
7428 </p>
7429 <p>/ CHANNEL SP STREAM_COUNT SP sampler_channel
7430
7431 </p>
7432 <p>/ CHANNEL SP VOICE_COUNT SP sampler_channel
7433
7434 </p>
7435 <p>/ ENGINE SP INFO SP engine_name
7436
7437 </p>
7438 <p>/ SERVER SP INFO
7439
7440 </p>
7441 <p>/ TOTAL_VOICE_COUNT
7442
7443 </p>
7444 <p>/ TOTAL_VOICE_COUNT_MAX
7445
7446 </p>
7447 <p>/ MIDI_INSTRUMENTS SP midi_map
7448
7449 </p>
7450 <p>/ MIDI_INSTRUMENTS SP ALL
7451
7452 </p>
7453 <p>/ MIDI_INSTRUMENT SP INFO SP midi_map SP midi_bank SP midi_prog
7454
7455 </p>
7456 <p>/ MIDI_INSTRUMENT_MAPS
7457
7458 </p>
7459 <p>/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map
7460
7461 </p>
7462 <p>/ FX_SENDS SP sampler_channel
7463
7464 </p>
7465 <p>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
7466
7467 </p>
7468 <p>/ VOLUME
7469
7470 </p>
7471 </blockquote><p>
7472
7473 </p>
7474 <p>set_instruction =
7475 </p>
7476 <blockquote class="text">
7477 <p>AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
7478
7479 </p>
7480 <p>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '=' param_val_list
7481
7482 </p>
7483 <p>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
7484
7485 </p>
7486 <p>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list
7487
7488 </p>
7489 <p>/ CHANNEL SP set_chan_instruction
7490
7491 </p>
7492 <p>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
7493
7494 </p>
7495 <p>/ FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id SP audio_channel_index SP audio_channel_index
7496
7497 </p>
7498 <p>/ FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP midi_ctrl
7499
7500 </p>
7501 <p>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
7502
7503 </p>
7504 <p>/ ECHO SP boolean
7505
7506 </p>
7507 <p>/ VOLUME SP volume_value
7508
7509 </p>
7510 </blockquote><p>
7511
7512 </p>
7513 <p>create_instruction =
7514 </p>
7515 <blockquote class="text">
7516 <p>AUDIO_OUTPUT_DEVICE SP string SP key_val_list
7517
7518 </p>
7519 <p>/ AUDIO_OUTPUT_DEVICE SP string
7520
7521 </p>
7522 <p>/ MIDI_INPUT_DEVICE SP string SP key_val_list
7523
7524 </p>
7525 <p>/ MIDI_INPUT_DEVICE SP string
7526
7527 </p>
7528 <p>/ FX_SEND SP sampler_channel SP midi_ctrl
7529
7530 </p>
7531 <p>/ FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name
7532
7533 </p>
7534 </blockquote><p>
7535
7536 </p>
7537 <p>reset_instruction =
7538 </p>
7539 <blockquote class="text">
7540 <p>CHANNEL SP sampler_channel
7541
7542 </p>
7543 </blockquote><p>
7544
7545 </p>
7546 <p>clear_instruction =
7547 </p>
7548 <blockquote class="text">
7549 <p>MIDI_INSTRUMENTS SP midi_map
7550
7551 </p>
7552 <p>/ MIDI_INSTRUMENTS SP ALL
7553
7554 </p>
7555 </blockquote><p>
7556
7557 </p>
7558 <p>destroy_instruction =
7559 </p>
7560 <blockquote class="text">
7561 <p>AUDIO_OUTPUT_DEVICE SP number
7562
7563 </p>
7564 <p>/ MIDI_INPUT_DEVICE SP number
7565
7566 </p>
7567 <p>/ FX_SEND SP sampler_channel SP fx_send_id
7568
7569 </p>
7570 </blockquote><p>
7571
7572 </p>
7573 <p>load_instruction =
7574 </p>
7575 <blockquote class="text">
7576 <p>INSTRUMENT SP load_instr_args
7577
7578 </p>
7579 <p>/ ENGINE SP load_engine_args
7580
7581 </p>
7582 </blockquote><p>
7583
7584 </p>
7585 <p>set_chan_instruction =
7586 </p>
7587 <blockquote class="text">
7588 <p>AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
7589
7590 </p>
7591 <p>/ AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index SP audio_channel_index
7592
7593 </p>
7594 <p>/ AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
7595
7596 </p>
7597 <p>/ MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index SP midi_input_channel_index
7598
7599 </p>
7600 <p>/ MIDI_INPUT_DEVICE SP sampler_channel SP device_index
7601
7602 </p>
7603 <p>/ MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
7604
7605 </p>
7606 <p>/ MIDI_INPUT_CHANNEL SP sampler_channel SP midi_input_channel_index
7607
7608 </p>
7609 <p>/ MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
7610
7611 </p>
7612 <p>/ VOLUME SP sampler_channel SP volume_value
7613
7614 </p>
7615 <p>/ MUTE SP sampler_channel SP boolean
7616
7617 </p>
7618 <p>/ SOLO SP sampler_channel SP boolean
7619
7620 </p>
7621 <p>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP midi_map
7622
7623 </p>
7624 <p>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP NONE
7625
7626 </p>
7627 <p>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP DEFAULT
7628
7629 </p>
7630 </blockquote><p>
7631
7632 </p>
7633 <p>modal_arg =
7634 </p>
7635 <blockquote class="text">
7636 <p>/* epsilon (empty argument) */
7637
7638 </p>
7639 <p>/ NON_MODAL SP
7640
7641 </p>
7642 </blockquote><p>
7643
7644 </p>
7645 <p>key_val_list =
7646 </p>
7647 <blockquote class="text">
7648 <p>string '=' param_val_list
7649
7650 </p>
7651 <p>/ key_val_list SP string '=' param_val_list
7652
7653 </p>
7654 </blockquote><p>
7655
7656 </p>
7657 <p>buffer_size_type =
7658 </p>
7659 <blockquote class="text">
7660 <p>BYTES
7661
7662 </p>
7663 <p>/ PERCENTAGE
7664
7665 </p>
7666 </blockquote><p>
7667
7668 </p>
7669 <p>list_instruction =
7670 </p>
7671 <blockquote class="text">
7672 <p>AUDIO_OUTPUT_DEVICES
7673
7674 </p>
7675 <p>/ MIDI_INPUT_DEVICES
7676
7677 </p>
7678 <p>/ CHANNELS
7679
7680 </p>
7681 <p>/ AVAILABLE_ENGINES
7682
7683 </p>
7684 <p>/ AVAILABLE_MIDI_INPUT_DRIVERS
7685
7686 </p>
7687 <p>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
7688
7689 </p>
7690 <p>/ MIDI_INSTRUMENTS SP midi_map
7691
7692 </p>
7693 <p>/ MIDI_INSTRUMENTS SP ALL
7694
7695 </p>
7696 <p>/ MIDI_INSTRUMENT_MAPS
7697
7698 </p>
7699 <p>/ FX_SENDS SP sampler_channel
7700
7701 </p>
7702 </blockquote><p>
7703
7704 </p>
7705 <p>load_instr_args =
7706 </p>
7707 <blockquote class="text">
7708 <p>filename SP instrument_index SP sampler_channel
7709
7710 </p>
7711 <p>/ NON_MODAL SP filename SP instrument_index SP sampler_channel
7712
7713 </p>
7714 </blockquote><p>
7715
7716 </p>
7717 <p>load_engine_args =
7718 </p>
7719 <blockquote class="text">
7720 <p>engine_name SP sampler_channel
7721
7722 </p>
7723 </blockquote><p>
7724
7725 </p>
7726 <p>instr_load_mode =
7727 </p>
7728 <blockquote class="text">
7729 <p>ON_DEMAND
7730
7731 </p>
7732 <p>/ ON_DEMAND_HOLD
7733
7734 </p>
7735 <p>/ PERSISTENT
7736
7737 </p>
7738 </blockquote><p>
7739
7740 </p>
7741 <p>device_index =
7742 </p>
7743 <blockquote class="text">
7744 <p>number
7745
7746 </p>
7747 </blockquote><p>
7748
7749 </p>
7750 <p>audio_channel_index =
7751 </p>
7752 <blockquote class="text">
7753 <p>number
7754
7755 </p>
7756 </blockquote><p>
7757
7758 </p>
7759 <p>audio_output_type_name =
7760 </p>
7761 <blockquote class="text">
7762 <p>string
7763
7764 </p>
7765 </blockquote><p>
7766
7767 </p>
7768 <p>midi_input_port_index =
7769 </p>
7770 <blockquote class="text">
7771 <p>number
7772
7773 </p>
7774 </blockquote><p>
7775
7776 </p>
7777 <p>midi_input_channel_index =
7778 </p>
7779 <blockquote class="text">
7780 <p>number
7781
7782 </p>
7783 <p>/ ALL
7784
7785 </p>
7786 </blockquote><p>
7787
7788 </p>
7789 <p>midi_input_type_name =
7790 </p>
7791 <blockquote class="text">
7792 <p>string
7793
7794 </p>
7795 </blockquote><p>
7796
7797 </p>
7798 <p>midi_map =
7799 </p>
7800 <blockquote class="text">
7801 <p>number
7802
7803 </p>
7804 </blockquote><p>
7805
7806 </p>
7807 <p>midi_bank =
7808 </p>
7809 <blockquote class="text">
7810 <p>number
7811
7812 </p>
7813 </blockquote><p>
7814
7815 </p>
7816 <p>midi_prog =
7817 </p>
7818 <blockquote class="text">
7819 <p>number
7820
7821 </p>
7822 </blockquote><p>
7823
7824 </p>
7825 <p>midi_ctrl =
7826 </p>
7827 <blockquote class="text">
7828 <p>number
7829
7830 </p>
7831 </blockquote><p>
7832
7833 </p>
7834 <p>volume_value =
7835 </p>
7836 <blockquote class="text">
7837 <p>dotnum
7838
7839 </p>
7840 <p>/ number
7841
7842 </p>
7843 </blockquote><p>
7844
7845 </p>
7846 <p>sampler_channel =
7847 </p>
7848 <blockquote class="text">
7849 <p>number
7850
7851 </p>
7852 </blockquote><p>
7853
7854 </p>
7855 <p>instrument_index =
7856 </p>
7857 <blockquote class="text">
7858 <p>number
7859
7860 </p>
7861 </blockquote><p>
7862
7863 </p>
7864 <p>fx_send_id =
7865 </p>
7866 <blockquote class="text">
7867 <p>number
7868
7869 </p>
7870 </blockquote><p>
7871
7872 </p>
7873 <p>engine_name =
7874 </p>
7875 <blockquote class="text">
7876 <p>string
7877
7878 </p>
7879 </blockquote><p>
7880
7881 </p>
7882 <p>filename =
7883 </p>
7884 <blockquote class="text">
7885 <p>stringval
7886
7887 </p>
7888 </blockquote><p>
7889
7890 </p>
7891 <p>map_name =
7892 </p>
7893 <blockquote class="text">
7894 <p>stringval
7895
7896 </p>
7897 </blockquote><p>
7898
7899 </p>
7900 <p>entry_name =
7901 </p>
7902 <blockquote class="text">
7903 <p>stringval
7904
7905 </p>
7906 </blockquote><p>
7907
7908 </p>
7909 <p>fx_send_name =
7910 </p>
7911 <blockquote class="text">
7912 <p>stringval
7913
7914 </p>
7915 </blockquote><p>
7916
7917 </p>
7918 <p>param_val_list =
7919 </p>
7920 <blockquote class="text">
7921 <p>param_val
7922
7923 </p>
7924 <p>/ param_val_list','param_val
7925
7926 </p>
7927 </blockquote><p>
7928
7929 </p>
7930 <p>param_val =
7931 </p>
7932 <blockquote class="text">
7933 <p>string
7934
7935 </p>
7936 <p>/ stringval
7937
7938 </p>
7939 <p>/ number
7940
7941 </p>
7942 <p>/ dotnum
7943
7944 </p>
7945 </blockquote><p>
7946
7947 </p>
7948 <a name="events"></a><br /><hr />
7949 <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>
7950 <a name="rfc.section.8"></a><h3>8.&nbsp;
7951 Events</h3>
7952
7953 <p>This chapter will describe all currently defined events supported by LinuxSampler.
7954 </p>
7955 <a name="SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT"></a><br /><hr />
7956 <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>
7957 <a name="rfc.section.8.1"></a><h3>8.1.&nbsp;
7958 Number of audio output devices changed</h3>
7959
7960 <p>Client may want to be notified when the total number of audio output devices on the
7961 back-end changes by issuing the following command:
7962 </p>
7963 <p>
7964 </p>
7965 <blockquote class="text">
7966 <p>SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT
7967 </p>
7968 </blockquote><p>
7969
7970 </p>
7971 <p>Server will start sending the following notification messages:
7972 </p>
7973 <p>
7974 </p>
7975 <blockquote class="text">
7976 <p>"NOTIFY:AUDIO_OUTPUT_DEVICE_COUNT:&lt;devices&gt;"
7977 </p>
7978 </blockquote><p>
7979
7980 </p>
7981 <p>where &lt;devices&gt; will be replaced by the new number
7982 of audio output devices.
7983 </p>
7984 <a name="SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO"></a><br /><hr />
7985 <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>
7986 <a name="rfc.section.8.2"></a><h3>8.2.&nbsp;
7987 Audio output device's settings changed</h3>
7988
7989 <p>Client may want to be notified when changes were made to audio output devices on the
7990 back-end by issuing the following command:
7991 </p>
7992 <p>
7993 </p>
7994 <blockquote class="text">
7995 <p>SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO
7996 </p>
7997 </blockquote><p>
7998
7999 </p>
8000 <p>Server will start sending the following notification messages:
8001 </p>
8002 <p>
8003 </p>
8004 <blockquote class="text">
8005 <p>"NOTIFY:AUDIO_OUTPUT_DEVICE_INFO:&lt;device-id&gt;"
8006 </p>
8007 </blockquote><p>
8008
8009 </p>
8010 <p>where &lt;device-id&gt; will be replaced by the numerical ID of the audio output device,
8011 which settings has been changed. The front-end will have to send
8012 the respective command to actually get the audio output device info. Because these messages
8013 will be triggered by LSCP commands issued by other clients rather than real
8014 time events happening on the server, it is believed that an empty notification
8015 message is sufficient here.
8016 </p>
8017 <a name="SUBSCRIBE MIDI_INPUT_DEVICE_COUNT"></a><br /><hr />
8018 <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>
8019 <a name="rfc.section.8.3"></a><h3>8.3.&nbsp;
8020 Number of MIDI input devices changed</h3>
8021
8022 <p>Client may want to be notified when the total number of MIDI input devices on the
8023 back-end changes by issuing the following command:
8024 </p>
8025 <p>
8026 </p>
8027 <blockquote class="text">
8028 <p>SUBSCRIBE MIDI_INPUT_DEVICE_COUNT
8029 </p>
8030 </blockquote><p>
8031
8032 </p>
8033 <p>Server will start sending the following notification messages:
8034 </p>
8035 <p>
8036 </p>
8037 <blockquote class="text">
8038 <p>"NOTIFY:MIDI_INPUT_DEVICE_COUNT:&lt;devices&gt;"
8039 </p>
8040 </blockquote><p>
8041
8042 </p>
8043 <p>where &lt;devices&gt; will be replaced by the new number
8044 of MIDI input devices.
8045 </p>
8046 <a name="SUBSCRIBE MIDI_INPUT_DEVICE_INFO"></a><br /><hr />
8047 <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>
8048 <a name="rfc.section.8.4"></a><h3>8.4.&nbsp;
8049 MIDI input device's settings changed</h3>
8050
8051 <p>Client may want to be notified when changes were made to MIDI input devices on the
8052 back-end by issuing the following command:
8053 </p>
8054 <p>
8055 </p>
8056 <blockquote class="text">
8057 <p>SUBSCRIBE MIDI_INPUT_DEVICE_INFO
8058 </p>
8059 </blockquote><p>
8060
8061 </p>
8062 <p>Server will start sending the following notification messages:
8063 </p>
8064 <p>
8065 </p>
8066 <blockquote class="text">
8067 <p>"NOTIFY:MIDI_INPUT_DEVICE_INFO:&lt;device-id&gt;"
8068 </p>
8069 </blockquote><p>
8070
8071 </p>
8072 <p>where &lt;device-id&gt; will be replaced by the numerical ID of the MIDI input device,
8073 which settings has been changed. The front-end will have to send
8074 the respective command to actually get the MIDI input device info. Because these messages
8075 will be triggered by LSCP commands issued by other clients rather than real
8076 time events happening on the server, it is believed that an empty notification
8077 message is sufficient here.
8078 </p>
8079 <a name="SUBSCRIBE CHANNEL_COUNT"></a><br /><hr />
8080 <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>
8081 <a name="rfc.section.8.5"></a><h3>8.5.&nbsp;
8082 Number of sampler channels changed</h3>
8083
8084 <p>Client may want to be notified when the total number of channels on the
8085 back-end changes by issuing the following command:
8086 </p>
8087 <p>
8088 </p>
8089 <blockquote class="text">
8090 <p>SUBSCRIBE CHANNEL_COUNT
8091 </p>
8092 </blockquote><p>
8093
8094 </p>
8095 <p>Server will start sending the following notification messages:
8096 </p>
8097 <p>
8098 </p>
8099 <blockquote class="text">
8100 <p>"NOTIFY:CHANNEL_COUNT:&lt;channels&gt;"
8101 </p>
8102 </blockquote><p>
8103
8104 </p>
8105 <p>where &lt;channels&gt; will be replaced by the new number
8106 of sampler channels.
8107 </p>
8108 <a name="SUBSCRIBE VOICE_COUNT"></a><br /><hr />
8109 <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>
8110 <a name="rfc.section.8.6"></a><h3>8.6.&nbsp;
8111 Number of active voices changed</h3>
8112
8113 <p>Client may want to be notified when the number of voices on the
8114 back-end changes by issuing the following command:
8115 </p>
8116 <p>
8117 </p>
8118 <blockquote class="text">
8119 <p>SUBSCRIBE VOICE_COUNT
8120 </p>
8121 </blockquote><p>
8122
8123 </p>
8124 <p>Server will start sending the following notification messages:
8125 </p>
8126 <p>
8127 </p>
8128 <blockquote class="text">
8129 <p>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;
8130 </p>
8131 </blockquote><p>
8132
8133 </p>
8134 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
8135 voice count change occurred and &lt;voices&gt; by the new number of
8136 active voices on that channel.
8137 </p>
8138 <a name="SUBSCRIBE STREAM_COUNT"></a><br /><hr />
8139 <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>
8140 <a name="rfc.section.8.7"></a><h3>8.7.&nbsp;
8141 Number of active disk streams changed</h3>
8142
8143 <p>Client may want to be notified when the number of streams on the back-end
8144 changes by issuing the following command: SUBSCRIBE STREAM_COUNT
8145 </p>
8146 <p>
8147 </p>
8148 <blockquote class="text">
8149 <p>SUBSCRIBE STREAM_COUNT
8150 </p>
8151 </blockquote><p>
8152
8153 </p>
8154 <p>Server will start sending the following notification messages:
8155 </p>
8156 <p>
8157 </p>
8158 <blockquote class="text">
8159 <p>"NOTIFY:STREAM_COUNT:&lt;sampler-channel&gt; &lt;streams&gt;"
8160 </p>
8161 </blockquote><p>
8162
8163 </p>
8164 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
8165 stream count change occurred and &lt;streams&gt; by the new number of
8166 active disk streams on that channel.
8167 </p>
8168 <a name="SUBSCRIBE BUFFER_FILL"></a><br /><hr />
8169 <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>
8170 <a name="rfc.section.8.8"></a><h3>8.8.&nbsp;
8171 Disk stream buffer fill state changed</h3>
8172
8173 <p>Client may want to be notified when the buffer fill state of a disk stream
8174 on the back-end changes by issuing the following command:
8175 </p>
8176 <p>
8177 </p>
8178 <blockquote class="text">
8179 <p>SUBSCRIBE BUFFER_FILL
8180 </p>
8181 </blockquote><p>
8182
8183 </p>
8184 <p>Server will start sending the following notification messages:
8185 </p>
8186 <p>
8187 </p>
8188 <blockquote class="text">
8189 <p>"NOTIFY:BUFFER_FILL:&lt;sampler-channel&gt; &lt;fill-data&gt;"
8190 </p>
8191 </blockquote><p>
8192
8193 </p>
8194 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
8195 buffer fill state change occurred on and &lt;fill-data&gt; will be replaced by the
8196 buffer fill data for this channel as described in <a class='info' href='#GET CHANNEL BUFFER_FILL'>Section&nbsp;6.4.13<span> (</span><span class='info'>Current fill state of disk stream buffers</span><span>)</span></a>
8197 as if the <a class='info' href='#GET CHANNEL BUFFER_FILL'>"GET CHANNEL BUFFER_FILL PERCENTAGE"<span> (</span><span class='info'>Current fill state of disk stream buffers</span><span>)</span></a> command was issued on this channel.
8198 </p>
8199 <a name="SUBSCRIBE CHANNEL_INFO"></a><br /><hr />
8200 <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>
8201 <a name="rfc.section.8.9"></a><h3>8.9.&nbsp;
8202 Channel information changed</h3>
8203
8204 <p>Client may want to be notified when changes were made to sampler channels on the
8205 back-end by issuing the following command:
8206 </p>
8207 <p>
8208 </p>
8209 <blockquote class="text">
8210 <p>SUBSCRIBE CHANNEL_INFO
8211 </p>
8212 </blockquote><p>
8213
8214 </p>
8215 <p>Server will start sending the following notification messages:
8216 </p>
8217 <p>
8218 </p>
8219 <blockquote class="text">
8220 <p>"NOTIFY:CHANNEL_INFO:&lt;sampler-channel&gt;"
8221 </p>
8222 </blockquote><p>
8223
8224 </p>
8225 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
8226 channel info change occurred. The front-end will have to send
8227 the respective command to actually get the channel info. Because these messages
8228 will be triggered by LSCP commands issued by other clients rather than real
8229 time events happening on the server, it is believed that an empty notification
8230 message is sufficient here.
8231 </p>
8232 <a name="SUBSCRIBE TOTAL_VOICE_COUNT"></a><br /><hr />
8233 <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>
8234 <a name="rfc.section.8.10"></a><h3>8.10.&nbsp;
8235 Total number of active voices changed</h3>
8236
8237 <p>Client may want to be notified when the total number of voices on the
8238 back-end changes by issuing the following command:
8239 </p>
8240 <p>
8241 </p>
8242 <blockquote class="text">
8243 <p>SUBSCRIBE TOTAL_VOICE_COUNT
8244 </p>
8245 </blockquote><p>
8246
8247 </p>
8248 <p>Server will start sending the following notification messages:
8249 </p>
8250 <p>
8251 </p>
8252 <blockquote class="text">
8253 <p>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;
8254 </p>
8255 </blockquote><p>
8256
8257 </p>
8258 <p>where &lt;voices&gt; will be replaced by the new number of
8259 all currently active voices.
8260 </p>
8261 <a name="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT"></a><br /><hr />
8262 <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>
8263 <a name="rfc.section.8.11"></a><h3>8.11.&nbsp;
8264 Number of MIDI instrument maps changed</h3>
8265
8266 <p>Client may want to be notified when the number of MIDI instrument maps on the
8267 back-end changes by issuing the following command:
8268 </p>
8269 <p>
8270 </p>
8271 <blockquote class="text">
8272 <p>SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT
8273 </p>
8274 </blockquote><p>
8275
8276 </p>
8277 <p>Server will start sending the following notification messages:
8278 </p>
8279 <p>
8280 </p>
8281 <blockquote class="text">
8282 <p>"NOTIFY:MIDI_INSTRUMENT_MAP_COUNT:&lt;maps&gt;"
8283 </p>
8284 </blockquote><p>
8285
8286 </p>
8287 <p>where &lt;maps&gt; will be replaced by the new number
8288 of MIDI instrument maps.
8289 </p>
8290 <a name="SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO"></a><br /><hr />
8291 <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>
8292 <a name="rfc.section.8.12"></a><h3>8.12.&nbsp;
8293 MIDI instrument map information changed</h3>
8294
8295 <p>Client may want to be notified when changes were made to MIDI instrument maps on the
8296 back-end by issuing the following command:
8297 </p>
8298 <p>
8299 </p>
8300 <blockquote class="text">
8301 <p>SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO
8302 </p>
8303 </blockquote><p>
8304
8305 </p>
8306 <p>Server will start sending the following notification messages:
8307 </p>
8308 <p>
8309 </p>
8310 <blockquote class="text">
8311 <p>"NOTIFY:MIDI_INSTRUMENT_MAP_INFO:&lt;map-id&gt;"
8312 </p>
8313 </blockquote><p>
8314
8315 </p>
8316 <p>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
8317 for which information changes occurred. The front-end will have to send
8318 the respective command to actually get the MIDI instrument map info. Because these messages
8319 will be triggered by LSCP commands issued by other clients rather than real
8320 time events happening on the server, it is believed that an empty notification
8321 message is sufficient here.
8322 </p>
8323 <a name="SUBSCRIBE MIDI_INSTRUMENT_COUNT"></a><br /><hr />
8324 <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>
8325 <a name="rfc.section.8.13"></a><h3>8.13.&nbsp;
8326 Number of MIDI instruments changed</h3>
8327
8328 <p>Client may want to be notified when the number of MIDI instrument maps on the
8329 back-end changes by issuing the following command:
8330 </p>
8331 <p>
8332 </p>
8333 <blockquote class="text">
8334 <p>SUBSCRIBE MIDI_INSTRUMENT_COUNT
8335 </p>
8336 </blockquote><p>
8337
8338 </p>
8339 <p>Server will start sending the following notification messages:
8340 </p>
8341 <p>
8342 </p>
8343 <blockquote class="text">
8344 <p>"NOTIFY:MIDI_INSTRUMENT_COUNT:&lt;map-id&gt; &lt;instruments&gt;"
8345 </p>
8346 </blockquote><p>
8347
8348 </p>
8349 <p>where &lt;map-id&gt; is the numerical ID of the MIDI instrument map, in which
8350 the nuber of instruments has changed and &lt;instruments&gt; will be replaced by
8351 the new number of MIDI instruments in the specified map.
8352 </p>
8353 <a name="SUBSCRIBE MIDI_INSTRUMENT_INFO"></a><br /><hr />
8354 <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>
8355 <a name="rfc.section.8.14"></a><h3>8.14.&nbsp;
8356 MIDI instrument information changed</h3>
8357
8358 <p>Client may want to be notified when changes were made to MIDI instruments on the
8359 back-end by issuing the following command:
8360 </p>
8361 <p>
8362 </p>
8363 <blockquote class="text">
8364 <p>SUBSCRIBE MIDI_INSTRUMENT_INFO
8365 </p>
8366 </blockquote><p>
8367
8368 </p>
8369 <p>Server will start sending the following notification messages:
8370 </p>
8371 <p>
8372 </p>
8373 <blockquote class="text">
8374 <p>"NOTIFY:MIDI_INSTRUMENT_INFO:&lt;map-id&gt; &lt;bank&gt; &lt;program&gt;"
8375 </p>
8376 </blockquote><p>
8377
8378 </p>
8379 <p>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
8380 in which a MIDI instrument is changed. &lt;bank&gt; and &lt;program&gt; specifies
8381 the location of the changed MIDI instrument in the map. The front-end will have to send
8382 the respective command to actually get the MIDI instrument info. Because these messages
8383 will be triggered by LSCP commands issued by other clients rather than real
8384 time events happening on the server, it is believed that an empty notification
8385 message is sufficient here.
8386 </p>
8387 <a name="SUBSCRIBE MISCELLANEOUS"></a><br /><hr />
8388 <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>
8389 <a name="rfc.section.8.15"></a><h3>8.15.&nbsp;
8390 Miscellaneous and debugging events</h3>
8391
8392 <p>Client may want to be notified of miscellaneous and debugging events occurring at
8393 the server by issuing the following command:
8394 </p>
8395 <p>
8396 </p>
8397 <blockquote class="text">
8398 <p>SUBSCRIBE MISCELLANEOUS
8399 </p>
8400 </blockquote><p>
8401
8402 </p>
8403 <p>Server will start sending the following notification messages:
8404 </p>
8405 <p>
8406 </p>
8407 <blockquote class="text">
8408 <p>"NOTIFY:MISCELLANEOUS:&lt;string&gt;"
8409 </p>
8410 </blockquote><p>
8411
8412 </p>
8413 <p>where &lt;string&gt; will be replaced by whatever data server
8414 wants to send to the client. Client MAY display this data to the
8415 user AS IS to facilitate debugging.
8416 </p>
8417 <a name="anchor14"></a><br /><hr />
8418 <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>
8419 <a name="rfc.section.9"></a><h3>9.&nbsp;
8420 Security Considerations</h3>
8421
8422 <p>As there is so far no method of authentication and authorization
8423 defined and so not required for a client applications to succeed to
8424 connect, running LinuxSampler might be a security risk for the host
8425 system the LinuxSampler instance is running on.
8426 </p>
8427 <a name="anchor15"></a><br /><hr />
8428 <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>
8429 <a name="rfc.section.10"></a><h3>10.&nbsp;
8430 Acknowledgments</h3>
8431
8432 <p>This document has benefited greatly from the comments of the
8433 following people, discussed on the LinuxSampler developer's mailing
8434 list:
8435 </p>
8436 <p>
8437 </p>
8438 <blockquote class="text">
8439 <p>Rui Nuno Capela
8440 </p>
8441 <p>Vladimir Senkov
8442 </p>
8443 <p>Mark Knecht
8444 </p>
8445 <p>Grigor Iliev
8446 </p>
8447 </blockquote><p>
8448
8449 </p>
8450 <a name="rfc.references1"></a><br /><hr />
8451 <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>
8452 <h3>11.&nbsp;References</h3>
8453 <table width="99%" border="0">
8454 <tr><td class="author-text" valign="top"><a name="RFC2119">[RFC2119]</a></td>
8455 <td class="author-text">Bradner, S., &ldquo;<a href="ftp://ftp.isi.edu/in-notes/rfc2119.txt">Key words for use in RFCs to Indicate Requirement Levels</a>,&rdquo; RFC&nbsp;2119, 1997.</td></tr>
8456 <tr><td class="author-text" valign="top"><a name="RFC2234">[RFC2234]</a></td>
8457 <td class="author-text">Crocker, D. and P. Overell, &ldquo;<a href="ftp://ftp.isi.edu/in-notes/rfc2234.txt">Augmented BNF for Syntax Specifications</a>,&rdquo; RFC&nbsp;2234, 1997.</td></tr>
8458 <tr><td class="author-text" valign="top"><a name="RFC793">[RFC793]</a></td>
8459 <td class="author-text">Defense Advanced Research Projects Agency, &ldquo;<a href="ftp://ftp.isi.edu/in-notes/rfc793.txt">TRANSMISSION CONTROL PROTOCOL</a>,&rdquo; RFC&nbsp;793, 1981.</td></tr>
8460 </table>
8461
8462 <a name="rfc.authors"></a><br /><hr />
8463 <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>
8464 <h3>Author's Address</h3>
8465 <table width="99%" border="0" cellpadding="0" cellspacing="0">
8466 <tr><td class="author-text">&nbsp;</td>
8467 <td class="author-text">C.
8468 Schoenebeck</td></tr>
8469 <tr><td class="author-text">&nbsp;</td>
8470 <td class="author-text">Interessengemeinschaft Software Engineering e. V.</td></tr>
8471 <tr><td class="author-text">&nbsp;</td>
8472 <td class="author-text">Max-Planck-Str. 39</td></tr>
8473 <tr><td class="author-text">&nbsp;</td>
8474 <td class="author-text">74081 Heilbronn</td></tr>
8475 <tr><td class="author-text">&nbsp;</td>
8476 <td class="author-text">Germany</td></tr>
8477 <tr><td class="author" align="right">Email:&nbsp;</td>
8478 <td class="author-text"><a href="mailto:schoenebeck at software minus engineering dot org">schoenebeck at software minus engineering dot org</a></td></tr>
8479 </table>
8480 <a name="rfc.copyright"></a><br /><hr />
8481 <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>
8482 <h3>Full Copyright Statement</h3>
8483 <p class='copyright'>
8484 Copyright &copy; The Internet Society (2007).</p>
8485 <p class='copyright'>
8486 This document is subject to the rights,
8487 licenses and restrictions contained in BCP&nbsp;78,
8488 and except as set forth therein,
8489 the authors retain all their rights.</p>
8490 <p class='copyright'>
8491 This document and the information contained herein are provided
8492 on an &ldquo;AS IS&rdquo; basis and THE CONTRIBUTOR,
8493 THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY),
8494 THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM
8495 ALL WARRANTIES,
8496 EXPRESS OR IMPLIED,
8497 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
8498 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
8499 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.</p>
8500 <h3>Intellectual Property</h3>
8501 <p class='copyright'>
8502 The IETF takes no position regarding the validity or scope of any
8503 Intellectual Property Rights or other rights that might be claimed
8504 to pertain to the implementation or use of the technology
8505 described in this document or the extent to which any license
8506 under such rights might or might not be available; nor does it
8507 represent that it has made any independent effort to identify any
8508 such rights.
8509 Information on the procedures with respect to
8510 rights in RFC documents can be found in BCP&nbsp;78 and BCP&nbsp;79.</p>
8511 <p class='copyright'>
8512 Copies of IPR disclosures made to the IETF Secretariat and any
8513 assurances of licenses to be made available,
8514 or the result of an attempt made to obtain a general license or
8515 permission for the use of such proprietary rights by implementers or
8516 users of this specification can be obtained from the IETF on-line IPR
8517 repository at <a href='http://www.ietf.org/ipr'>http://www.ietf.org/ipr</a>.</p>
8518 <p class='copyright'>
8519 The IETF invites any interested party to bring to its attention
8520 any copyrights,
8521 patents or patent applications,
8522 or other
8523 proprietary rights that may cover technology that may be required
8524 to implement this standard.
8525 Please address the information to the IETF at <a href='mailto:ietf-ipr@ietf.org'>ietf-ipr@ietf.org</a>.</p>
8526 <h3>Acknowledgment</h3>
8527 <p class='copyright'>
8528 Funding for the RFC Editor function is provided by
8529 the IETF Administrative Support Activity (IASA).</p>
8530 </body></html>

  ViewVC Help
Powered by ViewVC