/[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 1251 - (show annotations) (download) (as text)
Fri Jun 22 14:24:57 2007 UTC (16 years, 9 months ago) by schoenebeck
File MIME type: text/html
File size: 373989 byte(s)
- updated LSCP spec draft regarding extended ASCII character
  set and support for escape sequences

1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <html lang="en"><head><title>LinuxSampler Control Protocol (draft)</title>
3 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
4 <meta name="description" content="LinuxSampler Control Protocol (draft)">
5 <meta name="keywords" content="LSCP">
6 <meta name="generator" content="xml2rfc v1.32 (http://xml.resource.org/)">
7 <style type='text/css'><!--
8 body {
9 font-family: verdana, charcoal, helvetica, arial, sans-serif;
10 font-size: small; color: #000; background-color: #FFF;
11 margin: 2em;
12 }
13 h1, h2, h3, h4, h5, h6 {
14 font-family: helvetica, monaco, "MS Sans Serif", arial, sans-serif;
15 font-weight: bold; font-style: normal;
16 }
17 h1 { color: #900; background-color: transparent; text-align: right; }
18 h3 { color: #333; background-color: transparent; }
19
20 td.RFCbug {
21 font-size: x-small; text-decoration: none;
22 width: 30px; height: 30px; padding-top: 2px;
23 text-align: justify; vertical-align: middle;
24 background-color: #000;
25 }
26 td.RFCbug span.RFC {
27 font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
28 font-weight: bold; color: #666;
29 }
30 td.RFCbug span.hotText {
31 font-family: charcoal, monaco, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
32 font-weight: normal; text-align: center; color: #FFF;
33 }
34
35 table.TOCbug { width: 30px; height: 15px; }
36 td.TOCbug {
37 text-align: center; width: 30px; height: 15px;
38 color: #FFF; background-color: #900;
39 }
40 td.TOCbug a {
41 font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, sans-serif;
42 font-weight: bold; font-size: x-small; text-decoration: none;
43 color: #FFF; background-color: transparent;
44 }
45
46 td.header {
47 font-family: arial, helvetica, sans-serif; font-size: x-small;
48 vertical-align: top; width: 33%;
49 color: #FFF; background-color: #666;
50 }
51 td.author { font-weight: bold; font-size: x-small; margin-left: 4em; }
52 td.author-text { font-size: x-small; }
53
54 /* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */
55 a.info {
56 /* This is the key. */
57 position: relative;
58 z-index: 24;
59 text-decoration: none;
60 }
61 a.info:hover {
62 z-index: 25;
63 color: #FFF; background-color: #900;
64 }
65 a.info span { display: none; }
66 a.info:hover span.info {
67 /* The span will display just on :hover state. */
68 display: block;
69 position: absolute;
70 font-size: smaller;
71 top: 2em; left: -5em; width: 15em;
72 padding: 2px; border: 1px solid #333;
73 color: #900; background-color: #EEE;
74 text-align: left;
75 }
76
77 a { font-weight: bold; }
78 a:link { color: #900; background-color: transparent; }
79 a:visited { color: #633; background-color: transparent; }
80 a:active { color: #633; background-color: transparent; }
81
82 p { margin-left: 2em; margin-right: 2em; }
83 p.copyright { font-size: x-small; }
84 p.toc { font-size: small; font-weight: bold; margin-left: 3em; }
85 table.toc { margin: 0 0 0 3em; padding: 0; border: 0; vertical-align: text-top; }
86 td.toc { font-size: small; font-weight: bold; vertical-align: text-top; }
87
88 ol.text { margin-left: 2em; margin-right: 2em; }
89 ul.text { margin-left: 2em; margin-right: 2em; }
90 li { margin-left: 3em; }
91
92 /* RFC-2629 <spanx>s and <artwork>s. */
93 em { font-style: italic; }
94 strong { font-weight: bold; }
95 dfn { font-weight: bold; font-style: normal; }
96 cite { font-weight: normal; font-style: normal; }
97 tt { color: #036; }
98 tt, pre, pre dfn, pre em, pre cite, pre span {
99 font-family: "Courier New", Courier, monospace; font-size: small;
100 }
101 pre {
102 text-align: left; padding: 4px;
103 color: #000; background-color: #CCC;
104 }
105 pre dfn { color: #900; }
106 pre em { color: #66F; background-color: #FFC; font-weight: normal; }
107 pre .key { color: #33C; font-weight: bold; }
108 pre .id { color: #900; }
109 pre .str { color: #000; background-color: #CFF; }
110 pre .val { color: #066; }
111 pre .rep { color: #909; }
112 pre .oth { color: #000; background-color: #FCF; }
113 pre .err { background-color: #FCC; }
114
115 /* RFC-2629 <texttable>s. */
116 table.all, table.full, table.headers, table.none {
117 font-size: small; text-align: center; border-width: 2px;
118 vertical-align: top; border-collapse: collapse;
119 }
120 table.all, table.full { border-style: solid; border-color: black; }
121 table.headers, table.none { border-style: none; }
122 th {
123 font-weight: bold; border-color: black;
124 border-width: 2px 2px 3px 2px;
125 }
126 table.all th, table.full th { border-style: solid; }
127 table.headers th { border-style: none none solid none; }
128 table.none th { border-style: none; }
129 table.all td {
130 border-style: solid; border-color: #333;
131 border-width: 1px 2px;
132 }
133 table.full td, table.headers td, table.none td { border-style: none; }
134
135 hr { height: 1px; }
136 hr.insert {
137 width: 80%; border-style: none; border-width: 0;
138 color: #CCC; background-color: #CCC;
139 }
140 --></style>
141 </head>
142 <body>
143 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
144 <table summary="layout" width="66%" border="0" cellpadding="0" cellspacing="0"><tr><td><table summary="layout" width="100%" border="0" cellpadding="2" cellspacing="1">
145 <tr><td class="header">LinuxSampler Developers</td><td class="header">C. Schoenebeck</td></tr>
146 <tr><td class="header">Internet-Draft</td><td class="header">Interessengemeinschaft Software</td></tr>
147 <tr><td class="header">Intended status: Standards Track</td><td class="header">Engineering e. V.</td></tr>
148 <tr><td class="header">Expires: December 24, 2007</td><td class="header">June 22, 2007</td></tr>
149 </table></td></tr></table>
150 <h1><br />LinuxSampler Control Protocol (draft)<br />LSCP 1.2cvs</h1>
151
152 <h3>Status of this Memo</h3>
153 <p>
154 By submitting this Internet-Draft,
155 each author represents that any applicable patent or other IPR claims of which
156 he or she is aware have been or will be disclosed,
157 and any of which he or she becomes aware will be disclosed,
158 in accordance with Section&nbsp;6 of BCP&nbsp;79.</p>
159 <p>
160 Internet-Drafts are working documents of the Internet Engineering
161 Task Force (IETF), its areas, and its working groups.
162 Note that other groups may also distribute working documents as
163 Internet-Drafts.</p>
164 <p>
165 Internet-Drafts are draft documents valid for a maximum of six months
166 and may be updated, replaced, or obsoleted by other documents at any time.
167 It is inappropriate to use Internet-Drafts as reference material or to cite
168 them other than as &ldquo;work in progress.&rdquo;</p>
169 <p>
170 The list of current Internet-Drafts can be accessed at
171 <a href='http://www.ietf.org/ietf/1id-abstracts.txt'>http://www.ietf.org/ietf/1id-abstracts.txt</a>.</p>
172 <p>
173 The list of Internet-Draft Shadow Directories can be accessed at
174 <a href='http://www.ietf.org/shadow.html'>http://www.ietf.org/shadow.html</a>.</p>
175 <p>
176 This Internet-Draft will expire on December 24, 2007.</p>
177
178 <h3>Copyright Notice</h3>
179 <p>
180 Copyright &copy; The IETF Trust (2007).</p>
181
182 <h3>Abstract</h3>
183
184 <p>The LinuxSampler Control Protocol (LSCP) is an
185 application-level protocol primarily intended for local and
186 remote controlling the LinuxSampler backend application, which is a
187 sophisticated server-like console application essentially playing
188 back audio samples and manipulating the samples in real time to
189 certain extent.
190 </p><a name="toc"></a><br /><hr />
191 <h3>Table of Contents</h3>
192 <p class="toc">
193 <a href="#anchor1">1.</a>&nbsp;
194 Requirements notation<br />
195 <a href="#LSCP versioning">2.</a>&nbsp;
196 Versioning of this specification<br />
197 <a href="#anchor2">3.</a>&nbsp;
198 Introduction<br />
199 <a href="#anchor3">4.</a>&nbsp;
200 Focus of this protocol<br />
201 <a href="#anchor4">5.</a>&nbsp;
202 Communication Overview<br />
203 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor5">5.1.</a>&nbsp;
204 Request/response communication method<br />
205 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor6">5.1.1.</a>&nbsp;
206 Result format<br />
207 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor7">5.2.</a>&nbsp;
208 Subscribe/notify communication method<br />
209 <a href="#control_commands">6.</a>&nbsp;
210 Description for control commands<br />
211 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor8">6.1.</a>&nbsp;
212 Ignored lines and comments<br />
213 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor9">6.2.</a>&nbsp;
214 Configuring audio drivers<br />
215 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_AUDIO_OUTPUT_DRIVERS">6.2.1.</a>&nbsp;
216 Getting amount of available audio output drivers<br />
217 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">6.2.2.</a>&nbsp;
218 Getting all available audio output drivers<br />
219 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DRIVER INFO">6.2.3.</a>&nbsp;
220 Getting information about a specific audio
221 output driver<br />
222 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO">6.2.4.</a>&nbsp;
223 Getting information about specific audio
224 output driver parameter<br />
225 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CREATE AUDIO_OUTPUT_DEVICE">6.2.5.</a>&nbsp;
226 Creating an audio output device<br />
227 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DESTROY AUDIO_OUTPUT_DEVICE">6.2.6.</a>&nbsp;
228 Destroying an audio output device<br />
229 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DEVICES">6.2.7.</a>&nbsp;
230 Getting all created audio output device count<br />
231 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AUDIO_OUTPUT_DEVICES">6.2.8.</a>&nbsp;
232 Getting all created audio output device list<br />
233 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DEVICE INFO">6.2.9.</a>&nbsp;
234 Getting current settings of an audio output device<br />
235 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET AUDIO_OUTPUT_DEVICE_PARAMETER">6.2.10.</a>&nbsp;
236 Changing settings of audio output devices<br />
237 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_CHANNEL INFO">6.2.11.</a>&nbsp;
238 Getting information about an audio channel<br />
239 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO">6.2.12.</a>&nbsp;
240 Getting information about specific audio channel parameter<br />
241 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET AUDIO_OUTPUT_CHANNEL_PARAMETER">6.2.13.</a>&nbsp;
242 Changing settings of audio output channels<br />
243 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor10">6.3.</a>&nbsp;
244 Configuring MIDI input drivers<br />
245 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_MIDI_INPUT_DRIVERS">6.3.1.</a>&nbsp;
246 Getting amount of available MIDI input drivers<br />
247 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_MIDI_INPUT_DRIVERS">6.3.2.</a>&nbsp;
248 Getting all available MIDI input drivers<br />
249 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DRIVER INFO">6.3.3.</a>&nbsp;
250 Getting information about a specific MIDI input driver<br />
251 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DRIVER_PARAMETER INFO">6.3.4.</a>&nbsp;
252 Getting information about specific MIDI input driver parameter<br />
253 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CREATE MIDI_INPUT_DEVICE">6.3.5.</a>&nbsp;
254 Creating a MIDI input device<br />
255 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DESTROY MIDI_INPUT_DEVICE">6.3.6.</a>&nbsp;
256 Destroying a MIDI input device<br />
257 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DEVICES">6.3.7.</a>&nbsp;
258 Getting all created MIDI input device count<br />
259 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST MIDI_INPUT_DEVICES">6.3.8.</a>&nbsp;
260 Getting all created MIDI input device list<br />
261 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DEVICE INFO">6.3.9.</a>&nbsp;
262 Getting current settings of a MIDI input device<br />
263 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET MIDI_INPUT_DEVICE_PARAMETER">6.3.10.</a>&nbsp;
264 Changing settings of MIDI input devices<br />
265 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_PORT INFO">6.3.11.</a>&nbsp;
266 Getting information about a MIDI port<br />
267 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_PORT_PARAMETER INFO">6.3.12.</a>&nbsp;
268 Getting information about specific MIDI port parameter<br />
269 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET MIDI_INPUT_PORT_PARAMETER">6.3.13.</a>&nbsp;
270 Changing settings of MIDI input ports<br />
271 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor11">6.4.</a>&nbsp;
272 Configuring sampler channels<br />
273 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LOAD INSTRUMENT">6.4.1.</a>&nbsp;
274 Loading an instrument<br />
275 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LOAD ENGINE">6.4.2.</a>&nbsp;
276 Loading a sampler engine<br />
277 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNELS">6.4.3.</a>&nbsp;
278 Getting all created sampler channel count<br />
279 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST CHANNELS">6.4.4.</a>&nbsp;
280 Getting all created sampler channel list<br />
281 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD CHANNEL">6.4.5.</a>&nbsp;
282 Adding a new sampler channel<br />
283 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE CHANNEL">6.4.6.</a>&nbsp;
284 Removing a sampler channel<br />
285 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_ENGINES">6.4.7.</a>&nbsp;
286 Getting amount of available engines<br />
287 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_ENGINES">6.4.8.</a>&nbsp;
288 Getting all available engines<br />
289 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET ENGINE INFO">6.4.9.</a>&nbsp;
290 Getting information about an engine<br />
291 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL INFO">6.4.10.</a>&nbsp;
292 Getting sampler channel information<br />
293 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL VOICE_COUNT">6.4.11.</a>&nbsp;
294 Current number of active voices<br />
295 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL STREAM_COUNT">6.4.12.</a>&nbsp;
296 Current number of active disk streams<br />
297 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL BUFFER_FILL">6.4.13.</a>&nbsp;
298 Current fill state of disk stream buffers<br />
299 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_DEVICE">6.4.14.</a>&nbsp;
300 Setting audio output device<br />
301 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_TYPE">6.4.15.</a>&nbsp;
302 Setting audio output type<br />
303 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_CHANNEL">6.4.16.</a>&nbsp;
304 Setting audio output channel<br />
305 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_DEVICE">6.4.17.</a>&nbsp;
306 Setting MIDI input device<br />
307 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_TYPE">6.4.18.</a>&nbsp;
308 Setting MIDI input type<br />
309 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_PORT">6.4.19.</a>&nbsp;
310 Setting MIDI input port<br />
311 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_CHANNEL">6.4.20.</a>&nbsp;
312 Setting MIDI input channel<br />
313 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL VOLUME">6.4.21.</a>&nbsp;
314 Setting channel volume<br />
315 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MUTE">6.4.22.</a>&nbsp;
316 Muting a sampler channel<br />
317 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL SOLO">6.4.23.</a>&nbsp;
318 Soloing a sampler channel<br />
319 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INSTRUMENT_MAP">6.4.24.</a>&nbsp;
320 Assigning a MIDI instrument map to a sampler channel<br />
321 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CREATE FX_SEND">6.4.25.</a>&nbsp;
322 Adding an effect send to a sampler channel<br />
323 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DESTROY FX_SEND">6.4.26.</a>&nbsp;
324 Removing an effect send from a sampler channel<br />
325 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET FX_SENDS">6.4.27.</a>&nbsp;
326 Getting amount of effect sends on a sampler channel<br />
327 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST FX_SENDS">6.4.28.</a>&nbsp;
328 Listing all effect sends on a sampler channel<br />
329 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET FX_SEND INFO">6.4.29.</a>&nbsp;
330 Getting effect send information<br />
331 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET FX_SEND NAME">6.4.30.</a>&nbsp;
332 Changing effect send's name<br />
333 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET FX_SEND AUDIO_OUTPUT_CHANNEL">6.4.31.</a>&nbsp;
334 Altering effect send's audio routing<br />
335 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET FX_SEND MIDI_CONTROLLER">6.4.32.</a>&nbsp;
336 Altering effect send's MIDI controller<br />
337 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET FX_SEND LEVEL">6.4.33.</a>&nbsp;
338 Altering effect send's send level<br />
339 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#RESET CHANNEL">6.4.34.</a>&nbsp;
340 Resetting a sampler channel<br />
341 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor12">6.5.</a>&nbsp;
342 Controlling connection<br />
343 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE">6.5.1.</a>&nbsp;
344 Register front-end for receiving event messages<br />
345 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#UNSUBSCRIBE">6.5.2.</a>&nbsp;
346 Unregister front-end for not receiving event messages<br />
347 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET ECHO">6.5.3.</a>&nbsp;
348 Enable or disable echo of commands<br />
349 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#QUIT">6.5.4.</a>&nbsp;
350 Close client connection<br />
351 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor13">6.6.</a>&nbsp;
352 Global commands<br />
353 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET TOTAL_VOICE_COUNT">6.6.1.</a>&nbsp;
354 Current number of active voices<br />
355 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET TOTAL_VOICE_COUNT_MAX">6.6.2.</a>&nbsp;
356 Maximum amount of active voices<br />
357 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#RESET">6.6.3.</a>&nbsp;
358 Reset sampler<br />
359 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET SERVER INFO">6.6.4.</a>&nbsp;
360 General sampler informations<br />
361 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET VOLUME">6.6.5.</a>&nbsp;
362 Getting global volume attenuation<br />
363 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET VOLUME">6.6.6.</a>&nbsp;
364 Setting global volume attenuation<br />
365 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#MIDI Instrument Mapping">6.7.</a>&nbsp;
366 MIDI Instrument Mapping<br />
367 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD MIDI_INSTRUMENT MAP">6.7.1.</a>&nbsp;
368 Create a new MIDI instrument map<br />
369 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE MIDI_INSTRUMENT_MAP">6.7.2.</a>&nbsp;
370 Delete one particular or all MIDI instrument maps<br />
371 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENT_MAPS">6.7.3.</a>&nbsp;
372 Get amount of existing MIDI instrument maps<br />
373 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST MIDI_INSTRUMENT_MAPS">6.7.4.</a>&nbsp;
374 Getting all created MIDI instrument maps<br />
375 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENT_MAP INFO">6.7.5.</a>&nbsp;
376 Getting MIDI instrument map information<br />
377 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET MIDI_INSTRUMENT_MAP NAME">6.7.6.</a>&nbsp;
378 Renaming a MIDI instrument map<br />
379 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#MAP MIDI_INSTRUMENT">6.7.7.</a>&nbsp;
380 Create or replace a MIDI instrument map entry<br />
381 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENTS">6.7.8.</a>&nbsp;
382 Getting ammount of MIDI instrument map entries<br />
383 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST MIDI_INSTRUMENTS">6.7.9.</a>&nbsp;
384 Getting indeces of all entries of a MIDI instrument map<br />
385 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#UNMAP MIDI_INSTRUMENT">6.7.10.</a>&nbsp;
386 Remove an entry from the MIDI instrument map<br />
387 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENT INFO">6.7.11.</a>&nbsp;
388 Get current settings of MIDI instrument map entry<br />
389 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CLEAR MIDI_INSTRUMENTS">6.7.12.</a>&nbsp;
390 Clear MIDI instrument map<br />
391 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#Managing Instruments Database">6.8.</a>&nbsp;
392 Managing Instruments Database<br />
393 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD DB_INSTRUMENT_DIRECTORY">6.8.1.</a>&nbsp;
394 Creating a new instrument directory<br />
395 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE DB_INSTRUMENT_DIRECTORY">6.8.2.</a>&nbsp;
396 Deleting an instrument directory<br />
397 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENT_DIRECTORIES">6.8.3.</a>&nbsp;
398 Getting amount of instrument directories<br />
399 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST DB_INSTRUMENT_DIRECTORIES">6.8.4.</a>&nbsp;
400 Listing all directories in specific directory<br />
401 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENT_DIRECTORY INFO">6.8.5.</a>&nbsp;
402 Getting instrument directory information<br />
403 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET DB_INSTRUMENT_DIRECTORY NAME">6.8.6.</a>&nbsp;
404 Renaming an instrument directory<br />
405 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#MOVE DB_INSTRUMENT_DIRECTORY">6.8.7.</a>&nbsp;
406 Moving an instrument directory<br />
407 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#COPY DB_INSTRUMENT_DIRECTORY">6.8.8.</a>&nbsp;
408 Copying instrument directories<br />
409 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">6.8.9.</a>&nbsp;
410 Changing the description of directory<br />
411 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#FIND DB_INSTRUMENT_DIRECTORIES">6.8.10.</a>&nbsp;
412 Finding directories<br />
413 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD DB_INSTRUMENTS">6.8.11.</a>&nbsp;
414 Adding instruments to the instruments database<br />
415 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE DB_INSTRUMENT">6.8.12.</a>&nbsp;
416 Removing an instrument<br />
417 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENTS">6.8.13.</a>&nbsp;
418 Getting amount of instruments<br />
419 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST DB_INSTRUMENTS">6.8.14.</a>&nbsp;
420 Listing all instruments in specific directory<br />
421 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENT INFO">6.8.15.</a>&nbsp;
422 Getting instrument information<br />
423 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET DB_INSTRUMENT NAME">6.8.16.</a>&nbsp;
424 Renaming an instrument<br />
425 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#MOVE DB_INSTRUMENT">6.8.17.</a>&nbsp;
426 Moving an instrument<br />
427 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#COPY DB_INSTRUMENT">6.8.18.</a>&nbsp;
428 Copying instruments<br />
429 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET DB_INSTRUMENT DESCRIPTION">6.8.19.</a>&nbsp;
430 Changing the description of instrument<br />
431 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#FIND DB_INSTRUMENTS">6.8.20.</a>&nbsp;
432 Finding instruments<br />
433 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENTS_JOB INFO">6.8.21.</a>&nbsp;
434 Getting job status information<br />
435 <a href="#command_syntax">7.</a>&nbsp;
436 Command Syntax<br />
437 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#character_set">7.1.</a>&nbsp;
438 Character Set and Escape Sequences<br />
439 <a href="#events">8.</a>&nbsp;
440 Events<br />
441 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT">8.1.</a>&nbsp;
442 Number of audio output devices changed<br />
443 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO">8.2.</a>&nbsp;
444 Audio output device's settings changed<br />
445 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INPUT_DEVICE_COUNT">8.3.</a>&nbsp;
446 Number of MIDI input devices changed<br />
447 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INPUT_DEVICE_INFO">8.4.</a>&nbsp;
448 MIDI input device's settings changed<br />
449 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE CHANNEL_COUNT">8.5.</a>&nbsp;
450 Number of sampler channels changed<br />
451 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE VOICE_COUNT">8.6.</a>&nbsp;
452 Number of active voices changed<br />
453 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE STREAM_COUNT">8.7.</a>&nbsp;
454 Number of active disk streams changed<br />
455 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE BUFFER_FILL">8.8.</a>&nbsp;
456 Disk stream buffer fill state changed<br />
457 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE CHANNEL_INFO">8.9.</a>&nbsp;
458 Channel information changed<br />
459 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE FX_SEND_COUNT">8.10.</a>&nbsp;
460 Number of effect sends changed<br />
461 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE FX_SEND_INFO">8.11.</a>&nbsp;
462 Effect send information changed<br />
463 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE TOTAL_VOICE_COUNT">8.12.</a>&nbsp;
464 Total number of active voices changed<br />
465 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT">8.13.</a>&nbsp;
466 Number of MIDI instrument maps changed<br />
467 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO">8.14.</a>&nbsp;
468 MIDI instrument map information changed<br />
469 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_COUNT">8.15.</a>&nbsp;
470 Number of MIDI instruments changed<br />
471 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_INFO">8.16.</a>&nbsp;
472 MIDI instrument information changed<br />
473 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE GLOBAL_INFO">8.17.</a>&nbsp;
474 Global settings changed<br />
475 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT">8.18.</a>&nbsp;
476 Number of database instrument directories changed<br />
477 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO">8.19.</a>&nbsp;
478 Database instrument directory information changed<br />
479 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENT_COUNT">8.20.</a>&nbsp;
480 Number of database instruments changed<br />
481 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENT_INFO">8.21.</a>&nbsp;
482 Database instrument information changed<br />
483 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENTS_JOB_INFO">8.22.</a>&nbsp;
484 Database job status information changed<br />
485 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MISCELLANEOUS">8.23.</a>&nbsp;
486 Miscellaneous and debugging events<br />
487 <a href="#anchor14">9.</a>&nbsp;
488 Security Considerations<br />
489 <a href="#anchor15">10.</a>&nbsp;
490 Acknowledgments<br />
491 <a href="#rfc.references1">11.</a>&nbsp;
492 References<br />
493 <a href="#rfc.authors">&#167;</a>&nbsp;
494 Author's Address<br />
495 <a href="#rfc.copyright">&#167;</a>&nbsp;
496 Intellectual Property and Copyright Statements<br />
497 </p>
498 <br clear="all" />
499
500 <a name="anchor1"></a><br /><hr />
501 <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>
502 <a name="rfc.section.1"></a><h3>1.&nbsp;
503 Requirements notation</h3>
504
505 <p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
506 "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
507 and "OPTIONAL" in this document are to be interpreted as
508 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>.
509 </p>
510 <p>This protocol is always case-sensitive if not explicitly
511 claimed the opposite.
512 </p>
513 <p>In examples, "C:" and "S:" indicate lines sent by the client
514 (front-end) and server (LinuxSampler) respectively. Lines in
515 examples must be interpreted as every line being CRLF
516 terminated (carriage return character followed by line feed
517 character as defined in the ASCII standard <a class='info' href='#RFC20'>[RFC20]<span> (</span><span class='info'>UCLA, &ldquo;ASCII format for Network Interchange,&rdquo; 1969.</span><span>)</span></a>),
518 thus the following example:
519 </p>
520 <p>
521 </p>
522 <blockquote class="text">
523 <p>C: "some line"
524 </p>
525 <p>&nbsp;&nbsp;&nbsp;"another line"
526 </p>
527 </blockquote><p>
528
529 </p>
530 <p>must actually be interpreted as client sending the following
531 message:
532 </p>
533 <p>
534 </p>
535 <blockquote class="text">
536 <p>"some line&lt;CR&gt;&lt;LF&gt;another
537 line&lt;CR&gt;&lt;LF&gt;"
538 </p>
539 </blockquote><p>
540
541 </p>
542 <p>where &lt;CR&gt; symbolizes the carriage return character and
543 &lt;LF&gt; the line feed character as defined in the ASCII
544 standard.
545 </p>
546 <p>Due to technical reasons, messages can arbitrary be
547 fragmented, means the following example:
548 </p>
549 <p>
550 </p>
551 <blockquote class="text">
552 <p>S: "abcd"
553 </p>
554 </blockquote><p>
555
556 </p>
557 <p>could also happen to be sent in three messages like in the
558 following sequence scenario:
559 </p>
560 <p>
561 </p>
562 <ul class="text">
563 <li>server sending message "a"
564 </li>
565 <li>followed by a delay (pause) with
566 arbitrary duration
567 </li>
568 <li>followed by server sending message
569 "bcd&lt;CR&gt;"
570 </li>
571 <li>again followed by a delay (pause) with arbitrary
572 duration
573 </li>
574 <li>followed by server sending the message
575 "&lt;LF&gt;"
576 </li>
577 </ul><p>
578
579 </p>
580 <p>where again &lt;CR&gt; and &lt;LF&gt; symbolize the carriage
581 return and line feed characters respectively.
582 </p>
583 <a name="LSCP versioning"></a><br /><hr />
584 <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>
585 <a name="rfc.section.2"></a><h3>2.&nbsp;
586 Versioning of this specification</h3>
587
588 <p>LSCP will certainly be extended and enhanced by-and-by. Each official
589 release of the LSCP specification will be tagged with a unique version
590 tuple. The version tuple consists at least of a major and minor version
591 number like:
592
593 </p>
594 <p>
595 </p>
596 <blockquote class="text">
597 <p>"1.2"
598 </p>
599 </blockquote><p>
600
601 </p>
602 <p>
603 In this example the major version number would be "1" and the minor
604 version number would be "2". Note that the version tuple might also
605 have more than two elements. The major version number defines a
606 group of backward compatible versions. That means a frontend is
607 compatible to the connected sampler if and only if the LSCP versions
608 to which each of the two parties complies to, match both of the
609 following rules:
610
611 </p>
612 <p>Compatibility:
613 </p>
614 <p>
615 </p>
616 <ol class="text">
617 <li>The frontend's LSCP major version and the sampler's LSCP
618 major version are exactly equal.
619 </li>
620 <li>The frontend's LSCP minor version is less or equal than
621 the sampler's LSCP minor version.
622 </li>
623 </ol><p>
624
625 </p>
626 <p>
627 Compatibility can only be claimed if both rules are true.
628 The frontend can use the
629 <a class='info' href='#GET SERVER INFO'>"GET SERVER INFO"<span> (</span><span class='info'>General sampler informations</span><span>)</span></a> command to
630 get the version of the LSCP specification the sampler complies with.
631
632 </p>
633 <a name="anchor2"></a><br /><hr />
634 <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>
635 <a name="rfc.section.3"></a><h3>3.&nbsp;
636 Introduction</h3>
637
638 <p>LinuxSampler is a so called software sampler application
639 capable to playback audio samples from a computer's Random
640 Access Memory (RAM) as well as directly streaming it from disk.
641 LinuxSampler is designed to be modular. It provides several so
642 called "sampler engines" where each engine is specialized for a
643 certain purpose. LinuxSampler has virtual channels which will be
644 referred in this document as "sampler channels". The channels
645 are in such way virtual as they can be connected to an
646 arbitrary MIDI input method and arbitrary MIDI channel (e.g.
647 sampler channel 17 could be connected to an ALSA sequencer
648 device 64:0 and listening to MIDI channel 1 there). Each sampler
649 channel will be associated with an instance of one of the available
650 sampler engines (e.g. GigEngine, DLSEngine). The audio output of
651 each sampler channel can be routed to an arbitrary audio output
652 method (ALSA / JACK) and an arbitrary audio output channel
653 there.
654 </p>
655 <a name="anchor3"></a><br /><hr />
656 <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>
657 <a name="rfc.section.4"></a><h3>4.&nbsp;
658 Focus of this protocol</h3>
659
660 <p>Main focus of this protocol is to provide a way to configure
661 a running LinuxSampler instance and to retrieve information
662 about it. The focus of this protocol is not to provide a way to
663 control synthesis parameters or even to trigger or release
664 notes. Or in other words; the focus are those functionalities
665 which are not covered by MIDI or which may at most be handled
666 via MIDI System Exclusive Messages.
667 </p>
668 <a name="anchor4"></a><br /><hr />
669 <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>
670 <a name="rfc.section.5"></a><h3>5.&nbsp;
671 Communication Overview</h3>
672
673 <p>There are two distinct methods of communication between a
674 running instance of LinuxSampler and one or more control
675 applications, so called "front-ends": a simple request/response
676 communication method used by the clients to give commands to the
677 server as well as to inquire about server's status and a
678 subscribe/notify communication method used by the client to
679 subscribe to and receive notifications of certain events as they
680 happen on the server. The latter needs more effort to be
681 implemented in the front-end application. The two communication
682 methods will be described next.
683 </p>
684 <a name="anchor5"></a><br /><hr />
685 <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>
686 <a name="rfc.section.5.1"></a><h3>5.1.&nbsp;
687 Request/response communication method</h3>
688
689 <p>This simple communication method is based on
690 <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
691 front-end application establishes a TCP connection to the
692 LinuxSampler instance on a certain host system. Then the
693 front-end application will send certain ASCII based commands
694 as defined in this document (every command line must be CRLF
695 terminated - see "Conventions used in this document" at the
696 beginning of this document) and the LinuxSampler application
697 will response after a certain process time with an
698 appropriate ASCII based answer, also as defined in this
699 document. So this TCP communication is simply based on query
700 and answer paradigm. That way LinuxSampler is only able to
701 answer on queries from front-ends, but not able to
702 automatically send messages to the client if it's not asked
703 to. The fronted should not reconnect to LinuxSampler for
704 every single command, instead it should keep the connection
705 established and simply resend message(s) for subsequent
706 commands. To keep information in the front-end up-to-date
707 the front-end has to periodically send new requests to get
708 the current information from the LinuxSampler instance. This
709 is often referred to as "polling". While polling is simple
710 to implement and may be OK to use in some cases, there may
711 be disadvantages to polling such as network traffic overhead
712 and information being out of date.
713 It is possible for a client or several clients to open more
714 than one connection to the server at the same time. It is
715 also possible to send more than one request to the server
716 at the same time but if those requests are sent over the
717 same connection server MUST execute them sequentially. Upon
718 executing a request server will produce a result set and
719 send it to the client. Each and every request made by the
720 client MUST result in a result set being sent back to the
721 client. No other data other than a result set may be sent by
722 a server to a client. No result set may be sent to a client
723 without the client sending request to the server first. On
724 any particular connection, result sets MUST be sent in their
725 entirety without being interrupted by other result sets. If
726 several requests got queued up at the server they MUST be
727 processed in the order they were received and result sets
728 MUST be sent back in the same order.
729 </p>
730 <a name="anchor6"></a><br /><hr />
731 <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>
732 <a name="rfc.section.5.1.1"></a><h3>5.1.1.&nbsp;
733 Result format</h3>
734
735 <p>Result set could be one of the following types:
736 </p>
737 <p>
738 </p>
739 <ol class="text">
740 <li>Normal
741 </li>
742 <li>Warning
743 </li>
744 <li>Error
745 </li>
746 </ol><p>
747
748 </p>
749 <p>Warning and Error result sets MUST be single line and
750 have the following format:
751 </p>
752 <p>
753 </p>
754 <ul class="text">
755 <li>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;"
756 </li>
757 <li>"ERR:&lt;error-code&gt;:&lt;error-message&gt;"
758 </li>
759 </ul><p>
760
761 </p>
762 <p>Where &lt;warning-code&gt; and &lt;error-code&gt; are
763 numeric unique identifiers of the warning or error and
764 &lt;warning-message&gt; and &lt;error-message&gt; are
765 human readable descriptions of the warning or error
766 respectively.
767 </p>
768 <p>Examples:
769 </p>
770 <p>
771 </p>
772 <blockquote class="text">
773 <p>C: "LOAD INSTRUMENT '/home/me/Boesendorfer24bit.gig" 0 0
774 </p>
775 <p>S: "WRN:32:This is a 24 bit patch which is not supported natively yet."
776 </p>
777 </blockquote><p>
778
779 </p>
780 <p>
781 </p>
782 <blockquote class="text">
783 <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA EAR"
784 </p>
785 <p>S: "ERR:3456:Audio output driver 'ALSA' does not have a parameter 'EAR'."
786 </p>
787 </blockquote><p>
788
789 </p>
790 <p>
791 </p>
792 <blockquote class="text">
793 <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 123456"
794 </p>
795 <p>S: "ERR:9:There is no audio output device with index 123456."
796 </p>
797 </blockquote><p>
798
799 </p>
800 <p>Normal result sets could be:
801 </p>
802 <p>
803 </p>
804 <ol class="text">
805 <li>Empty
806 </li>
807 <li>Single line
808 </li>
809 <li>Multi-line
810 </li>
811 </ol><p>
812
813 </p>
814 <p> Empty result set is issued when the server only
815 needed to acknowledge the fact that the request was
816 received and it was processed successfully and no
817 additional information is available. This result set has
818 the following format:
819 </p>
820 <p>
821 </p>
822 <blockquote class="text">
823 <p>"OK"
824 </p>
825 </blockquote><p>
826
827 </p>
828 <p>Example:
829 </p>
830 <p>
831 </p>
832 <blockquote class="text">
833 <p>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 CHANNELS=4"
834 </p>
835 <p>S: "OK"
836 </p>
837 </blockquote><p>
838
839 </p>
840 <p>Single line result sets are command specific. One
841 example of a single line result set is an empty line.
842 Multi-line result sets are command specific and may
843 include one or more lines of information. They MUST
844 always end with the following line:
845 </p>
846 <p>
847 </p>
848 <blockquote class="text">
849 <p>"."
850 </p>
851 </blockquote><p>
852
853 </p>
854 <p>Example:
855 </p>
856 <p>
857 </p>
858 <blockquote class="text">
859 <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
860 </p>
861 <p>S: "DRIVER: ALSA"
862 </p>
863 <p>&nbsp;&nbsp;&nbsp;"CHANNELS: 2"
864 </p>
865 <p>&nbsp;&nbsp;&nbsp;"SAMPLERATE: 44100"
866 </p>
867 <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
868 </p>
869 <p>&nbsp;&nbsp;&nbsp;"FRAGMENTS: 2"
870 </p>
871 <p>&nbsp;&nbsp;&nbsp;"FRAGMENTSIZE: 128"
872 </p>
873 <p>&nbsp;&nbsp;&nbsp;"CARD: '0,0'"
874 </p>
875 <p>&nbsp;&nbsp;&nbsp;"."
876 </p>
877 </blockquote><p>
878
879 </p>
880 <p>In addition to above mentioned formats, warnings and
881 empty result sets MAY be indexed. In this case, they
882 have the following formats respectively:
883 </p>
884 <p>
885 </p>
886 <ul class="text">
887 <li>"WRN[&lt;index&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;"
888 </li>
889 <li>"OK[&lt;index&gt;]"
890 </li>
891 </ul><p>
892
893 </p>
894 <p>where &lt;index&gt; is command specific and is used
895 to indicate channel number that the result set was
896 related to or other integer value.
897 </p>
898 <p>Each line of the result set MUST end with
899 &lt;CRLF&gt;.
900 </p>
901 <p>Examples:
902 </p>
903 <p>
904 </p>
905 <blockquote class="text">
906 <p>C: "ADD CHANNEL"
907 </p>
908 <p>S: "OK[12]"
909 </p>
910 </blockquote><p>
911
912 </p>
913 <p>
914 </p>
915 <blockquote class="text">
916 <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"
917 </p>
918 <p>S: "WRN[0]:32:Sample rate not supported, using 44100 instead."
919 </p>
920 </blockquote><p>
921
922 </p>
923 <a name="anchor7"></a><br /><hr />
924 <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>
925 <a name="rfc.section.5.2"></a><h3>5.2.&nbsp;
926 Subscribe/notify communication method</h3>
927
928 <p>This more sophisticated communication method is actually
929 only an extension of the simple request/response
930 communication method. The front-end still uses a TCP
931 connection and sends the same commands on the TCP
932 connection. Two extra commands are SUBSCRIBE and UNSUBSCRIBE
933 commands that allow a client to tell the server that it is
934 interested in receiving notifications about certain events
935 as they happen on the server. The SUBSCRIBE command has the
936 following syntax:
937 </p>
938 <p>
939 </p>
940 <blockquote class="text">
941 <p>SUBSCRIBE &lt;event-id&gt;
942 </p>
943 </blockquote><p>
944
945 </p>
946 <p>where &lt;event-id&gt; will be replaced by the respective
947 event that client wants to subscribe to. Upon receiving such
948 request, server SHOULD respond with OK and start sending
949 EVENT notifications when a given even has occurred to the
950 front-end when an event has occurred. It MAY be possible
951 certain events may be sent before OK response during real
952 time nature of their generation. Event messages have the
953 following format:
954 </p>
955 <p>
956 </p>
957 <blockquote class="text">
958 <p>NOTIFY:&lt;event-id&gt;:&lt;custom-event-data&gt;
959 </p>
960 </blockquote><p>
961
962 </p>
963 <p>where &lt;event-id&gt; uniquely identifies the event that
964 has occurred and &lt;custom-event-data&gt; is event
965 specific.
966 </p>
967 <p>Several rules must be followed by the server when
968 generating events:
969 </p>
970 <p>
971 </p>
972 <ol class="text">
973 <li>Events MUST NOT be sent to any client who has not
974 issued an appropriate SUBSCRIBE command.
975 </li>
976 <li>Events MUST only be sent using the same
977 connection that was used to subscribe to them.
978 </li>
979 <li>When response is being sent to the client, event
980 MUST be inserted in the stream before or after the
981 response, but NOT in the middle. Same is true about
982 the response. It should never be inserted in the
983 middle of the event message as well as any other
984 response.
985 </li>
986 </ol><p>
987
988 </p>
989 <p>If the client is not interested in a particular event
990 anymore it MAY issue UNSUBSCRIBE command using the following
991 syntax:
992 </p>
993 <p>
994 </p>
995 <blockquote class="text">
996 <p>UNSUBSCRIBE &lt;event-id&gt;
997 </p>
998 </blockquote><p>
999
1000 </p>
1001 <p>where &lt;event-id&gt; will be replace by the respective
1002 event that client is no longer interested in receiving. For
1003 a list of supported events see <a class='info' href='#events'>Section&nbsp;8<span> (</span><span class='info'>Events</span><span>)</span></a>.
1004 </p>
1005 <p>Example: the fill states of disk stream buffers have
1006 changed on sampler channel 4 and the LinuxSampler instance
1007 will react by sending the following message to all clients
1008 who subscribed to this event:
1009 </p>
1010 <p>
1011 </p>
1012 <blockquote class="text">
1013 <p>NOTIFY:CHANNEL_BUFFER_FILL:4 [35]62%,[33]80%,[37]98%
1014 </p>
1015 </blockquote><p>
1016
1017 </p>
1018 <p>Which means there are currently three active streams on
1019 sampler channel 4, where the stream with ID "35" is filled
1020 by 62%, stream with ID 33 is filled by 80% and stream with
1021 ID 37 is filled by 98%.
1022 </p>
1023 <p>Clients may choose to open more than one connection to
1024 the server and use some connections to receive notifications
1025 while using other connections to issue commands to the
1026 back-end. This is entirely legal and up to the
1027 implementation. This does not change the protocol in any way
1028 and no special restrictions exist on the server to allow or
1029 disallow this or to track what connections belong to what
1030 front-ends. Server will listen on a single port, accept
1031 multiple connections and support protocol described in this
1032 specification in it's entirety on this single port on each
1033 connection that it accepted.
1034 </p>
1035 <p>Due to the fact that TCP is used for this communication,
1036 dead peers will be detected automatically by the OS TCP
1037 stack. While it may take a while to detect dead peers if no
1038 traffic is being sent from server to client (TCP keep-alive
1039 timer is set to 2 hours on many OSes) it will not be an
1040 issue here as when notifications are sent by the server,
1041 dead client will be detected quickly.
1042 </p>
1043 <p>When connection is closed for any reason server MUST
1044 forget all subscriptions that were made on this connection.
1045 If client reconnects it MUST resubscribe to all events that
1046 it wants to receive.
1047 </p>
1048 <a name="control_commands"></a><br /><hr />
1049 <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>
1050 <a name="rfc.section.6"></a><h3>6.&nbsp;
1051 Description for control commands</h3>
1052
1053 <p>This chapter will describe the available control commands
1054 that can be sent on the TCP connection in detail. Some certain
1055 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>
1056 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
1057 multiple-line responses. In this case LinuxSampler signals the
1058 end of the response by a "." (single dot) line.
1059 </p>
1060 <a name="anchor8"></a><br /><hr />
1061 <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>
1062 <a name="rfc.section.6.1"></a><h3>6.1.&nbsp;
1063 Ignored lines and comments</h3>
1064
1065 <p>White lines, that is lines which only contain space and
1066 tabulator characters, and lines that start with a "#"
1067 character are ignored, thus it's possible for example to
1068 group commands and to place comments in a LSCP script
1069 file.
1070 </p>
1071 <a name="anchor9"></a><br /><hr />
1072 <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>
1073 <a name="rfc.section.6.2"></a><h3>6.2.&nbsp;
1074 Configuring audio drivers</h3>
1075
1076 <p>Instances of drivers in LinuxSampler are called devices.
1077 You can use multiple audio devices simultaneously, e.g. to
1078 output the sound of one sampler channel using the ALSA audio
1079 output driver, and on another sampler channel you might want
1080 to use the JACK audio output driver. For particular audio
1081 output systems it's also possible to create several devices
1082 of the same audio output driver, e.g. two separate ALSA
1083 audio output devices for using two different sound cards at
1084 the same time. This chapter describes all commands to
1085 configure LinuxSampler's audio output devices and their
1086 parameters.
1087 </p>
1088 <p>Instead of defining commands and parameters for each
1089 driver individually, all possible parameters, their meanings
1090 and possible values have to be obtained at runtime. This
1091 makes the protocol a bit abstract, but has the advantage,
1092 that front-ends can be written independently of what drivers
1093 are currently implemented and what parameters these drivers
1094 are actually offering. This means front-ends can even handle
1095 drivers which are implemented somewhere in future without
1096 modifying the front-end at all.
1097 </p>
1098 <p>Note: examples in this chapter showing particular
1099 parameters of drivers are not meant as specification of the
1100 drivers' parameters. Driver implementations in LinuxSampler
1101 might have complete different parameter names and meanings
1102 than shown in these examples or might change in future, so
1103 these examples are only meant for showing how to retrieve
1104 what parameters drivers are offering, how to retrieve their
1105 possible values, etc.
1106 </p>
1107 <a name="GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"></a><br /><hr />
1108 <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>
1109 <a name="rfc.section.6.2.1"></a><h3>6.2.1.&nbsp;
1110 Getting amount of available audio output drivers</h3>
1111
1112 <p>Use the following command to get the number of
1113 audio output drivers currently available for the
1114 LinuxSampler instance:
1115 </p>
1116 <p>
1117 </p>
1118 <blockquote class="text">
1119 <p>GET AVAILABLE_AUDIO_OUTPUT_DRIVERS
1120 </p>
1121 </blockquote><p>
1122
1123 </p>
1124 <p>Possible Answers:
1125 </p>
1126 <p>
1127 </p>
1128 <blockquote class="text">
1129 <p>LinuxSampler will answer by sending the
1130 number of audio output drivers.
1131 </p>
1132 </blockquote><p>
1133
1134 </p>
1135 <p>Example:
1136 </p>
1137 <p>
1138 </p>
1139 <blockquote class="text">
1140 <p>C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
1141 </p>
1142 <p>S: "2"
1143 </p>
1144 </blockquote><p>
1145
1146 </p>
1147 <a name="LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"></a><br /><hr />
1148 <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>
1149 <a name="rfc.section.6.2.2"></a><h3>6.2.2.&nbsp;
1150 Getting all available audio output drivers</h3>
1151
1152 <p>Use the following command to list all audio output
1153 drivers currently available for the LinuxSampler
1154 instance:
1155 </p>
1156 <p>
1157 </p>
1158 <blockquote class="text">
1159 <p>LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS
1160 </p>
1161 </blockquote><p>
1162
1163 </p>
1164 <p>Possible Answers:
1165 </p>
1166 <p>
1167 </p>
1168 <blockquote class="text">
1169 <p>LinuxSampler will answer by sending comma
1170 separated character strings, each symbolizing an
1171 audio output driver.
1172 </p>
1173 </blockquote><p>
1174
1175 </p>
1176 <p>Example:
1177 </p>
1178 <p>
1179 </p>
1180 <blockquote class="text">
1181 <p>C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"
1182 </p>
1183 <p>S: "ALSA,JACK"
1184 </p>
1185 </blockquote><p>
1186
1187 </p>
1188 <a name="GET AUDIO_OUTPUT_DRIVER INFO"></a><br /><hr />
1189 <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>
1190 <a name="rfc.section.6.2.3"></a><h3>6.2.3.&nbsp;
1191 Getting information about a specific audio
1192 output driver</h3>
1193
1194 <p>Use the following command to get detailed information
1195 about a specific audio output driver:
1196 </p>
1197 <p>
1198 </p>
1199 <blockquote class="text">
1200 <p>GET AUDIO_OUTPUT_DRIVER INFO
1201 &lt;audio-output-driver&gt;
1202 </p>
1203 </blockquote><p>
1204
1205 </p>
1206 <p>Where &lt;audio-output-driver&gt; is the name of the
1207 audio output driver, returned by the
1208 <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.
1209 </p>
1210 <p>Possible Answers:
1211 </p>
1212 <p>
1213 </p>
1214 <blockquote class="text">
1215 <p>LinuxSampler will answer by sending a
1216 &lt;CRLF&gt; separated list. Each answer line
1217 begins with the information category name
1218 followed by a colon and then a space character
1219 &lt;SP&gt; and finally the info character string
1220 to that info category. At the moment the
1221 following information categories are
1222 defined:
1223 </p>
1224 <p>
1225 </p>
1226 <blockquote class="text">
1227 <p>DESCRIPTION -
1228 </p>
1229 <blockquote class="text">
1230 <p> character string describing the
1231 audio output driver
1232 </p>
1233 </blockquote>
1234
1235
1236 <p>VERSION -
1237 </p>
1238 <blockquote class="text">
1239 <p>character string reflecting the
1240 driver's version
1241 </p>
1242 </blockquote>
1243
1244
1245 <p>PARAMETERS -
1246 </p>
1247 <blockquote class="text">
1248 <p>comma separated list of all
1249 parameters available for the given
1250 audio output driver, at least
1251 parameters 'channels', 'samplerate'
1252 and 'active' are offered by all audio
1253 output drivers
1254 </p>
1255 </blockquote>
1256
1257
1258 </blockquote>
1259
1260
1261 <p>The mentioned fields above don't have to be
1262 in particular order.
1263 </p>
1264 </blockquote><p>
1265
1266 </p>
1267 <p>Example:
1268 </p>
1269 <p>
1270 </p>
1271 <blockquote class="text">
1272 <p>C: "GET AUDIO_OUTPUT_DRIVER INFO ALSA"
1273 </p>
1274 <p>S: "DESCRIPTION: Advanced Linux Sound
1275 Architecture"
1276 </p>
1277 <p>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"
1278 </p>
1279 <p>&nbsp;&nbsp;&nbsp;"PARAMETERS:
1280 DRIVER,CHANNELS,SAMPLERATE,ACTIVE,FRAGMENTS,
1281 FRAGMENTSIZE,CARD"
1282 </p>
1283 <p>&nbsp;&nbsp;&nbsp;"."
1284 </p>
1285 </blockquote><p>
1286
1287 </p>
1288 <a name="GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO"></a><br /><hr />
1289 <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>
1290 <a name="rfc.section.6.2.4"></a><h3>6.2.4.&nbsp;
1291 Getting information about specific audio
1292 output driver parameter</h3>
1293
1294 <p>Use the following command to get detailed information
1295 about a specific audio output driver parameter:
1296 </p>
1297 <p>
1298 </p>
1299 <blockquote class="text">
1300 <p>GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO &lt;audio&gt; &lt;prm&gt; [&lt;deplist&gt;]
1301 </p>
1302 </blockquote><p>
1303
1304 </p>
1305 <p>Where &lt;audio&gt; is the name of the audio output
1306 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,
1307 &lt;prm&gt; a specific parameter name for which information should be
1308 obtained (as returned by the
1309 <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
1310 &lt;deplist&gt; is an optional list of parameters on which the sought
1311 parameter &lt;prm&gt; depends on, &lt;deplist&gt; is a list of key-value
1312 pairs in form of "key1=val1 key2=val2 ...", where character string values
1313 are encapsulated into apostrophes ('). Arguments given with &lt;deplist&gt;
1314 which are not dependency parameters of &lt;prm&gt; will be ignored, means
1315 the front-end application can simply put all parameters into &lt;deplist&gt;
1316 with the values already selected by the user.
1317 </p>
1318 <p>Possible Answers:
1319 </p>
1320 <p>
1321 </p>
1322 <blockquote class="text">
1323 <p>LinuxSampler will answer by sending a
1324 &lt;CRLF&gt; separated list.
1325 Each answer line begins with the information category name
1326 followed by a colon and then a space character &lt;SP&gt; and
1327 finally
1328 the info character string to that info category. There are
1329 information which is always returned, independently of the
1330 given driver parameter and there are optional information
1331 which is only shown dependently to given driver parameter. At
1332 the moment the following information categories are defined:
1333 </p>
1334 </blockquote><p>
1335
1336 </p>
1337 <p>
1338 </p>
1339 <blockquote class="text">
1340 <p>TYPE -
1341 </p>
1342 <blockquote class="text">
1343 <p>either "BOOL" for boolean value(s) or
1344 "INT" for integer
1345 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1346 character string(s)
1347 (always returned, no matter which driver parameter)
1348 </p>
1349 </blockquote>
1350
1351
1352 <p>DESCRIPTION -
1353 </p>
1354 <blockquote class="text">
1355 <p>arbitrary text describing the purpose of the parameter
1356 (always returned, no matter which driver parameter)
1357 </p>
1358 </blockquote>
1359
1360
1361 <p>MANDATORY -
1362 </p>
1363 <blockquote class="text">
1364 <p>either true or false, defines if this parameter must be
1365 given when the device is to be created with the
1366 <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>
1367 command (always returned, no matter which driver parameter)
1368 </p>
1369 </blockquote>
1370
1371
1372 <p>FIX -
1373 </p>
1374 <blockquote class="text">
1375 <p>either true or false, if false then this parameter can
1376 be changed at any time, once the device is created by
1377 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>
1378 command (always returned, no matter which driver parameter)
1379 </p>
1380 </blockquote>
1381
1382
1383 <p>MULTIPLICITY -
1384 </p>
1385 <blockquote class="text">
1386 <p>either true or false, defines if this parameter allows
1387 only one value or a list of values, where true means
1388 multiple values and false only a single value allowed
1389 (always returned, no matter which driver parameter)
1390 </p>
1391 </blockquote>
1392
1393
1394 <p>DEPENDS -
1395 </p>
1396 <blockquote class="text">
1397 <p>comma separated list of parameters this parameter depends
1398 on, means the values for fields 'DEFAULT', 'RANGE_MIN',
1399 'RANGE_MAX' and 'POSSIBILITIES' might depend on these
1400 listed parameters, for example assuming that an audio
1401 driver (like the ALSA driver) offers parameters 'card'
1402 and 'samplerate' then parameter 'samplerate' would
1403 depend on 'card' because the possible values for
1404 'samplerate' depends on the sound card which can be
1405 chosen by the 'card' parameter
1406 (optionally returned, dependent to driver parameter)
1407 </p>
1408 </blockquote>
1409
1410
1411 <p>DEFAULT -
1412 </p>
1413 <blockquote class="text">
1414 <p>reflects the default value for this parameter which is
1415 used when the device is created and not explicitly
1416 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,
1417 in case of MULTIPLCITY=true, this is a comma separated
1418 list, that's why character strings are encapsulated into
1419 apostrophes (')
1420 (optionally returned, dependent to driver parameter)
1421 </p>
1422 </blockquote>
1423
1424
1425 <p>RANGE_MIN -
1426 </p>
1427 <blockquote class="text">
1428 <p>defines lower limit of the allowed value range for this
1429 parameter, can be an integer value as well as a dotted
1430 number, this parameter is often used in conjunction
1431 with RANGE_MAX, but may also appear without
1432 (optionally returned, dependent to driver parameter)
1433 </p>
1434 </blockquote>
1435
1436
1437 <p>RANGE_MAX -
1438 </p>
1439 <blockquote class="text">
1440 <p>defines upper limit of the allowed value range for this
1441 parameter, can be an integer value as well as a dotted
1442 number, this parameter is often used in conjunction with
1443 RANGE_MIN, but may also appear without
1444 (optionally returned, dependent to driver parameter)
1445 </p>
1446 </blockquote>
1447
1448
1449 <p>POSSIBILITIES -
1450 </p>
1451 <blockquote class="text">
1452 <p>comma separated list of possible values for this
1453 parameter, character strings are encapsulated into
1454 apostrophes
1455 (optionally returned, dependent to driver parameter)
1456 </p>
1457 </blockquote>
1458
1459
1460 </blockquote><p>
1461
1462 </p>
1463 <p>The mentioned fields above don't have to be in particular order.
1464 </p>
1465 <p>Examples:
1466 </p>
1467 <p>
1468 </p>
1469 <blockquote class="text">
1470 <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA CARD"
1471 </p>
1472 <p>S: "DESCRIPTION: sound card to be used"
1473 </p>
1474 <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
1475 </p>
1476 <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1477 </p>
1478 <p>&nbsp;&nbsp;&nbsp;"FIX: true"
1479 </p>
1480 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1481 </p>
1482 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: '0,0'"
1483 </p>
1484 <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: '0,0','1,0','2,0'"
1485 </p>
1486 <p>&nbsp;&nbsp;&nbsp;"."
1487 </p>
1488 </blockquote><p>
1489
1490 </p>
1491 <p>
1492 </p>
1493 <blockquote class="text">
1494 <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE"
1495 </p>
1496 <p>S: "DESCRIPTION: output sample rate in Hz"
1497 </p>
1498 <p>&nbsp;&nbsp;&nbsp;"TYPE: INT"
1499 </p>
1500 <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1501 </p>
1502 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
1503 </p>
1504 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1505 </p>
1506 <p>&nbsp;&nbsp;&nbsp;"DEPENDS: card"
1507 </p>
1508 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"
1509 </p>
1510 <p>&nbsp;&nbsp;&nbsp;"."
1511 </p>
1512 </blockquote><p>
1513
1514 </p>
1515 <p>
1516 </p>
1517 <blockquote class="text">
1518 <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE CARD='0,0'"
1519 </p>
1520 <p>S: "DESCRIPTION: output sample rate in Hz"
1521 </p>
1522 <p>&nbsp;&nbsp;&nbsp;"TYPE: INT"
1523 </p>
1524 <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1525 </p>
1526 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
1527 </p>
1528 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1529 </p>
1530 <p>&nbsp;&nbsp;&nbsp;"DEPENDS: card"
1531 </p>
1532 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"
1533 </p>
1534 <p>&nbsp;&nbsp;&nbsp;"RANGE_MIN: 22050"
1535 </p>
1536 <p>&nbsp;&nbsp;&nbsp;"RANGE_MAX: 96000"
1537 </p>
1538 <p>&nbsp;&nbsp;&nbsp;"."
1539 </p>
1540 </blockquote><p>
1541
1542 </p>
1543 <a name="CREATE AUDIO_OUTPUT_DEVICE"></a><br /><hr />
1544 <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>
1545 <a name="rfc.section.6.2.5"></a><h3>6.2.5.&nbsp;
1546 Creating an audio output device</h3>
1547
1548 <p>Use the following command to create a new audio output device for the desired audio output system:
1549 </p>
1550 <p>
1551 </p>
1552 <blockquote class="text">
1553 <p>CREATE AUDIO_OUTPUT_DEVICE &lt;audio-output-driver&gt; [&lt;param-list&gt;]
1554 </p>
1555 </blockquote><p>
1556
1557 </p>
1558 <p>Where &lt;audio-output-driver&gt; should be replaced by the desired audio
1559 output system as returned by the
1560 <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>
1561 command and &lt;param-list&gt; by an optional list of driver
1562 specific parameters in form of "key1=val1 key2=val2 ...", where
1563 character string values should be encapsulated into apostrophes (').
1564 Note that there might be drivers which require parameter(s) to be
1565 given with this command. Use the previously described commands in
1566 this chapter to get this information.
1567 </p>
1568 <p>Possible Answers:
1569 </p>
1570 <p>
1571 </p>
1572 <blockquote class="text">
1573 <p>"OK[&lt;device-id&gt;]" -
1574 </p>
1575 <blockquote class="text">
1576 <p>in case the device was successfully created, where
1577 &lt;device-id&gt; is the numerical ID of the new device
1578 </p>
1579 </blockquote>
1580
1581
1582 <p>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1583 </p>
1584 <blockquote class="text">
1585 <p>in case the device was created successfully, where
1586 &lt;device-id&gt; is the numerical ID of the new device, but there
1587 are noteworthy issue(s) related (e.g. sound card doesn't
1588 support given hardware parameters and the driver is using
1589 fall-back values), providing an appropriate warning code and
1590 warning message
1591 </p>
1592 </blockquote>
1593
1594
1595 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1596 </p>
1597 <blockquote class="text">
1598 <p>in case it failed, providing an appropriate error code and error message
1599 </p>
1600 </blockquote>
1601
1602
1603 </blockquote><p>
1604
1605 </p>
1606 <p>Examples:
1607 </p>
1608 <p>
1609 </p>
1610 <blockquote class="text">
1611 <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA"
1612 </p>
1613 <p>S: "OK[0]"
1614 </p>
1615 </blockquote><p>
1616
1617 </p>
1618 <p>
1619 </p>
1620 <blockquote class="text">
1621 <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"
1622 </p>
1623 <p>S: "OK[1]"
1624 </p>
1625 </blockquote><p>
1626
1627 </p>
1628 <a name="DESTROY AUDIO_OUTPUT_DEVICE"></a><br /><hr />
1629 <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>
1630 <a name="rfc.section.6.2.6"></a><h3>6.2.6.&nbsp;
1631 Destroying an audio output device</h3>
1632
1633 <p>Use the following command to destroy a created output device:
1634 </p>
1635 <p>
1636 </p>
1637 <blockquote class="text">
1638 <p>DESTROY AUDIO_OUTPUT_DEVICE &lt;device-id&gt;
1639 </p>
1640 </blockquote><p>
1641
1642 </p>
1643 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1644 audio output device as given by the
1645 <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>
1646 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>
1647 command.
1648 </p>
1649 <p>Possible Answers:
1650 </p>
1651 <p>
1652 </p>
1653 <blockquote class="text">
1654 <p>"OK" -
1655 </p>
1656 <blockquote class="text">
1657 <p>in case the device was successfully destroyed
1658 </p>
1659 </blockquote>
1660
1661
1662 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1663 </p>
1664 <blockquote class="text">
1665 <p>in case the device was destroyed successfully, but there are
1666 noteworthy issue(s) related (e.g. an audio over ethernet
1667 driver was unloaded but the other host might not be
1668 informed about this situation), providing an appropriate
1669 warning code and warning message
1670 </p>
1671 </blockquote>
1672
1673
1674 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1675 </p>
1676 <blockquote class="text">
1677 <p>in case it failed, providing an appropriate error code and
1678 error message
1679 </p>
1680 </blockquote>
1681
1682
1683 </blockquote><p>
1684
1685 </p>
1686 <p>Example:
1687 </p>
1688 <p>
1689 </p>
1690 <blockquote class="text">
1691 <p>C: "DESTROY AUDIO_OUTPUT_DEVICE 0"
1692 </p>
1693 <p>S: "OK"
1694 </p>
1695 </blockquote><p>
1696
1697 </p>
1698 <a name="GET AUDIO_OUTPUT_DEVICES"></a><br /><hr />
1699 <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>
1700 <a name="rfc.section.6.2.7"></a><h3>6.2.7.&nbsp;
1701 Getting all created audio output device count</h3>
1702
1703 <p>Use the following command to count all created audio output devices:
1704 </p>
1705 <p>
1706 </p>
1707 <blockquote class="text">
1708 <p>GET AUDIO_OUTPUT_DEVICES
1709 </p>
1710 </blockquote><p>
1711
1712 </p>
1713 <p>Possible Answers:
1714 </p>
1715 <p>
1716 </p>
1717 <blockquote class="text">
1718 <p>LinuxSampler will answer by sending the current number of all
1719 audio output devices.
1720 </p>
1721 </blockquote><p>
1722
1723 </p>
1724 <p>Example:
1725 </p>
1726 <p>
1727 </p>
1728 <blockquote class="text">
1729 <p>C: "GET AUDIO_OUTPUT_DEVICES"
1730 </p>
1731 <p>S: "4"
1732 </p>
1733 </blockquote><p>
1734
1735 </p>
1736 <a name="LIST AUDIO_OUTPUT_DEVICES"></a><br /><hr />
1737 <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>
1738 <a name="rfc.section.6.2.8"></a><h3>6.2.8.&nbsp;
1739 Getting all created audio output device list</h3>
1740
1741 <p>Use the following command to list all created audio output devices:
1742 </p>
1743 <p>
1744 </p>
1745 <blockquote class="text">
1746 <p>LIST AUDIO_OUTPUT_DEVICES
1747 </p>
1748 </blockquote><p>
1749
1750 </p>
1751 <p>Possible Answers:
1752 </p>
1753 <p>
1754 </p>
1755 <blockquote class="text">
1756 <p>LinuxSampler will answer by sending a comma separated list with
1757 the numerical IDs of all audio output devices.
1758 </p>
1759 </blockquote><p>
1760
1761 </p>
1762 <p>Example:
1763 </p>
1764 <p>
1765 </p>
1766 <blockquote class="text">
1767 <p>C: "LIST AUDIO_OUTPUT_DEVICES"
1768 </p>
1769 <p>S: "0,1,4,5"
1770 </p>
1771 </blockquote><p>
1772
1773 </p>
1774 <a name="GET AUDIO_OUTPUT_DEVICE INFO"></a><br /><hr />
1775 <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>
1776 <a name="rfc.section.6.2.9"></a><h3>6.2.9.&nbsp;
1777 Getting current settings of an audio output device</h3>
1778
1779 <p>Use the following command to get current settings of a specific, created audio output device:
1780 </p>
1781 <p>
1782 </p>
1783 <blockquote class="text">
1784 <p>GET AUDIO_OUTPUT_DEVICE INFO &lt;device-id&gt;
1785 </p>
1786 </blockquote><p>
1787
1788 </p>
1789 <p>Where &lt;device-id&gt; should be replaced by numerical ID
1790 of the audio output device as e.g. returned by the
1791 <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.
1792 </p>
1793 <p>Possible Answers:
1794 </p>
1795 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1796 Each answer line begins with the information category name
1797 followed by a colon and then a space character &lt;SP&gt; and finally
1798 the info character string to that info category. As some
1799 parameters might allow multiple values, character strings are
1800 encapsulated into apostrophes ('). At the moment the following
1801 information categories are defined (independently of device):
1802 </p>
1803 <p>
1804 </p>
1805 <blockquote class="text">
1806 <p>DRIVER -
1807 </p>
1808 <blockquote class="text">
1809 <p>identifier of the used audio output driver, as also
1810 returned by the
1811 <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>
1812 command
1813 </p>
1814 </blockquote>
1815
1816
1817 <p>CHANNELS -
1818 </p>
1819 <blockquote class="text">
1820 <p>amount of audio output channels this device currently
1821 offers
1822 </p>
1823 </blockquote>
1824
1825
1826 <p>SAMPLERATE -
1827 </p>
1828 <blockquote class="text">
1829 <p>playback sample rate the device uses
1830 </p>
1831 </blockquote>
1832
1833
1834 <p>ACTIVE -
1835 </p>
1836 <blockquote class="text">
1837 <p>either true or false, if false then the audio device is
1838 inactive and doesn't output any sound, nor do the
1839 sampler channels connected to this audio device render
1840 any audio
1841 </p>
1842 </blockquote>
1843
1844
1845 </blockquote><p>
1846
1847 </p>
1848 <p>The mentioned fields above don't have to be in particular
1849 order. The fields above are only those fields which are
1850 returned by all audio output devices. Every audio output driver
1851 might have its own, additional driver specific parameters (see
1852 <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>)
1853 which are also returned by this command.
1854 </p>
1855 <p>Example:
1856 </p>
1857 <p>
1858 </p>
1859 <blockquote class="text">
1860 <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
1861 </p>
1862 <p>S: "DRIVER: ALSA"
1863 </p>
1864 <p>&nbsp;&nbsp;&nbsp;"CHANNELS: 2"
1865 </p>
1866 <p>&nbsp;&nbsp;&nbsp;"SAMPLERATE: 44100"
1867 </p>
1868 <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
1869 </p>
1870 <p>&nbsp;&nbsp;&nbsp;"FRAGMENTS: 2"
1871 </p>
1872 <p>&nbsp;&nbsp;&nbsp;"FRAGMENTSIZE: 128"
1873 </p>
1874 <p>&nbsp;&nbsp;&nbsp;"CARD: '0,0'"
1875 </p>
1876 <p>&nbsp;&nbsp;&nbsp;"."
1877 </p>
1878 </blockquote><p>
1879
1880 </p>
1881 <a name="SET AUDIO_OUTPUT_DEVICE_PARAMETER"></a><br /><hr />
1882 <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>
1883 <a name="rfc.section.6.2.10"></a><h3>6.2.10.&nbsp;
1884 Changing settings of audio output devices</h3>
1885
1886 <p>Use the following command to alter a specific setting of a created audio output device:
1887 </p>
1888 <p>
1889 </p>
1890 <blockquote class="text">
1891 <p>SET AUDIO_OUTPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;
1892 </p>
1893 </blockquote><p>
1894
1895 </p>
1896 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1897 audio output device as given by the
1898 <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>
1899 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>
1900 command, &lt;key&gt; by the name of the parameter to change
1901 and &lt;value&gt; by the new value for this parameter.
1902 </p>
1903 <p>Possible Answers:
1904 </p>
1905 <p>
1906 </p>
1907 <blockquote class="text">
1908 <p>"OK" -
1909 </p>
1910 <blockquote class="text">
1911 <p>in case setting was successfully changed
1912 </p>
1913 </blockquote>
1914
1915
1916 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1917 </p>
1918 <blockquote class="text">
1919 <p>in case setting was changed successfully, but there are
1920 noteworthy issue(s) related, providing an appropriate
1921 warning code and warning message
1922 </p>
1923 </blockquote>
1924
1925
1926 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1927 </p>
1928 <blockquote class="text">
1929 <p>in case it failed, providing an appropriate error code and
1930 error message
1931 </p>
1932 </blockquote>
1933
1934
1935 </blockquote><p>
1936
1937 </p>
1938 <p>Example:
1939 </p>
1940 <p>
1941 </p>
1942 <blockquote class="text">
1943 <p>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"
1944 </p>
1945 <p>S: "OK"
1946 </p>
1947 </blockquote><p>
1948
1949 </p>
1950 <a name="GET AUDIO_OUTPUT_CHANNEL INFO"></a><br /><hr />
1951 <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>
1952 <a name="rfc.section.6.2.11"></a><h3>6.2.11.&nbsp;
1953 Getting information about an audio channel</h3>
1954
1955 <p>Use the following command to get information about an audio channel:
1956 </p>
1957 <p>
1958 </p>
1959 <blockquote class="text">
1960 <p>GET AUDIO_OUTPUT_CHANNEL INFO &lt;device-id&gt; &lt;audio-chan&gt;
1961 </p>
1962 </blockquote><p>
1963
1964 </p>
1965 <p>Where &lt;device-id&gt; is the numerical ID of the audio output device as given by the
1966 <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>
1967 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>
1968 command and &lt;audio-chan&gt; the audio channel number.
1969 </p>
1970 <p>Possible Answers:
1971 </p>
1972 <p>
1973 </p>
1974 <blockquote class="text">
1975 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1976 Each answer line begins with the information category name
1977 followed by a colon and then a space character &lt;SP&gt; and finally
1978 the info character string to that info category. At the moment
1979 the following information categories are defined:
1980 </p>
1981 <p>
1982 </p>
1983 <blockquote class="text">
1984 <p>NAME -
1985 </p>
1986 <blockquote class="text">
1987 <p>arbitrary character string naming the channel, which
1988 doesn't have to be unique (always returned by all audio channels)
1989 </p>
1990 </blockquote>
1991
1992
1993 <p>IS_MIX_CHANNEL -
1994 </p>
1995 <blockquote class="text">
1996 <p>either true or false, a mix-channel is not a real,
1997 independent audio channel, but a virtual channel which
1998 is mixed to another real channel, this mechanism is
1999 needed for sampler engines which need more audio
2000 channels than the used audio system might be able to offer
2001 (always returned by all audio channels)
2002 </p>
2003 </blockquote>
2004
2005
2006 <p>MIX_CHANNEL_DESTINATION -
2007 </p>
2008 <blockquote class="text">
2009 <p>numerical ID (positive integer including 0)
2010 which reflects the real audio channel (of the same audio
2011 output device) this mix channel refers to, means where
2012 the audio signal actually will be routed / added to
2013 (only returned in case the audio channel is mix channel)
2014 </p>
2015 </blockquote>
2016
2017
2018 </blockquote>
2019
2020
2021 </blockquote><p>
2022
2023 </p>
2024 <p>The mentioned fields above don't have to be in particular
2025 order. The fields above are only those fields which are
2026 generally returned for the described cases by all audio
2027 channels regardless of the audio driver. Every audio channel
2028 might have its own, additional driver and channel specific
2029 parameters.
2030 </p>
2031 <p>Examples:
2032 </p>
2033 <p>
2034 </p>
2035 <blockquote class="text">
2036 <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 0"
2037 </p>
2038 <p>S: "NAME: studio monitor left"
2039 </p>
2040 <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
2041 </p>
2042 <p>&nbsp;&nbsp;&nbsp;"."
2043 </p>
2044 </blockquote><p>
2045
2046 </p>
2047 <p>
2048 </p>
2049 <blockquote class="text">
2050 <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 1"
2051 </p>
2052 <p>S: "NAME: studio monitor right"
2053 </p>
2054 <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
2055 </p>
2056 <p>&nbsp;&nbsp;&nbsp;"."
2057 </p>
2058 </blockquote><p>
2059
2060 </p>
2061 <p>
2062 </p>
2063 <blockquote class="text">
2064 <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"
2065 </p>
2066 <p>S: "NAME: studio monitor left"
2067 </p>
2068 <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: true"
2069 </p>
2070 <p>&nbsp;&nbsp;&nbsp;"MIX_CHANNEL_DESTINATION: 1"
2071 </p>
2072 <p>&nbsp;&nbsp;&nbsp;"."
2073 </p>
2074 </blockquote><p>
2075
2076 </p>
2077 <p>
2078 </p>
2079 <blockquote class="text">
2080 <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"
2081 </p>
2082 <p>S: "NAME: 'ardour (left)'"
2083 </p>
2084 <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
2085 </p>
2086 <p>&nbsp;&nbsp;&nbsp;"JACK_BINDINGS: 'ardour:0'"
2087 </p>
2088 <p>&nbsp;&nbsp;&nbsp;"."
2089 </p>
2090 </blockquote><p>
2091
2092 </p>
2093 <a name="GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO"></a><br /><hr />
2094 <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>
2095 <a name="rfc.section.6.2.12"></a><h3>6.2.12.&nbsp;
2096 Getting information about specific audio channel parameter</h3>
2097
2098 <p>Use the following command to get detailed information about specific audio channel parameter:
2099 </p>
2100 <p>
2101 </p>
2102 <blockquote class="text">
2103 <p>GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO &lt;dev-id&gt; &lt;chan&gt; &lt;param&gt;
2104 </p>
2105 </blockquote><p>
2106
2107 </p>
2108 <p>Where &lt;dev-id&gt; is the numerical ID of the audio output device as returned by the
2109 <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>
2110 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>
2111 command, &lt;chan&gt; the audio channel number
2112 and &lt;param&gt; a specific channel parameter name for which information should
2113 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).
2114 </p>
2115 <p>Possible Answers:
2116 </p>
2117 <p>
2118 </p>
2119 <blockquote class="text">
2120 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2121 Each answer line begins with the information category name
2122 followed by a colon and then a space character &lt;SP&gt; and finally
2123 the info character string to that info category. There are
2124 information which is always returned, independently of the
2125 given channel parameter and there is optional information
2126 which is only shown dependently to the given audio channel. At
2127 the moment the following information categories are defined:
2128 </p>
2129 <p>
2130 </p>
2131 <blockquote class="text">
2132 <p>TYPE -
2133 </p>
2134 <blockquote class="text">
2135 <p>either "BOOL" for boolean value(s) or "INT" for integer
2136 value(s) or "FLOAT" for dotted number(s) or "STRING" for
2137 character string(s)
2138 (always returned)
2139 </p>
2140 </blockquote>
2141
2142
2143 <p>DESCRIPTION -
2144 </p>
2145 <blockquote class="text">
2146 <p>arbitrary text describing the purpose of the parameter (always returned)
2147 </p>
2148 </blockquote>
2149
2150
2151 <p>FIX -
2152 </p>
2153 <blockquote class="text">
2154 <p>either true or false, if true then this parameter is
2155 read only, thus cannot be altered
2156 (always returned)
2157 </p>
2158 </blockquote>
2159
2160
2161 <p>MULTIPLICITY -
2162 </p>
2163 <blockquote class="text">
2164 <p>either true or false, defines if this parameter allows
2165 only one value or a list of values, where true means
2166 multiple values and false only a single value allowed
2167 (always returned)
2168 </p>
2169 </blockquote>
2170
2171
2172 <p>RANGE_MIN -
2173 </p>
2174 <blockquote class="text">
2175 <p>defines lower limit of the allowed value range for this
2176 parameter, can be an integer value as well as a dotted
2177 number, usually used in conjunction with 'RANGE_MAX',
2178 but may also appear without
2179 (optionally returned, dependent to driver and channel
2180 parameter)
2181 </p>
2182 </blockquote>
2183
2184
2185 <p>RANGE_MAX -
2186 </p>
2187 <blockquote class="text">
2188 <p>defines upper limit of the allowed value range for this
2189 parameter, can be an integer value as well as a dotted
2190 number, usually used in conjunction with 'RANGE_MIN',
2191 but may also appear without
2192 (optionally returned, dependent to driver and channel
2193 parameter)
2194 </p>
2195 </blockquote>
2196
2197
2198 <p>POSSIBILITIES -
2199 </p>
2200 <blockquote class="text">
2201 <p>comma separated list of possible values for this
2202 parameter, character strings are encapsulated into
2203 apostrophes
2204 (optionally returned, dependent to driver and channel
2205 parameter)
2206 </p>
2207 </blockquote>
2208
2209
2210 </blockquote>
2211
2212
2213 <p>The mentioned fields above don't have to be in particular order.
2214 </p>
2215 </blockquote><p>
2216
2217 </p>
2218 <p>Example:
2219 </p>
2220 <p>
2221 </p>
2222 <blockquote class="text">
2223 <p>C: "GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO 1 0 JACK_BINDINGS"
2224 </p>
2225 <p>S: "DESCRIPTION: bindings to other JACK clients"
2226 </p>
2227 <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
2228 </p>
2229 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
2230 </p>
2231 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"
2232 </p>
2233 <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"
2234 </p>
2235 <p>&nbsp;&nbsp;&nbsp;"."
2236 </p>
2237 </blockquote><p>
2238
2239 </p>
2240 <a name="SET AUDIO_OUTPUT_CHANNEL_PARAMETER"></a><br /><hr />
2241 <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>
2242 <a name="rfc.section.6.2.13"></a><h3>6.2.13.&nbsp;
2243 Changing settings of audio output channels</h3>
2244
2245 <p>Use the following command to alter a specific setting of an audio output channel:
2246 </p>
2247 <p>
2248 </p>
2249 <blockquote class="text">
2250 <p>SET AUDIO_OUTPUT_CHANNEL_PARAMETER &lt;dev-id&gt; &lt;chn&gt; &lt;key&gt;=&lt;value&gt;
2251 </p>
2252 </blockquote><p>
2253
2254 </p>
2255 <p>Where &lt;dev-id&gt; should be replaced by the numerical ID of the audio output device as returned by the
2256 <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>
2257 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>
2258 command, &lt;chn&gt; by the audio channel number, &lt;key&gt; by the name of the
2259 parameter to change and &lt;value&gt; by the new value for this parameter.
2260 </p>
2261 <p>Possible Answers:
2262 </p>
2263 <p>
2264 </p>
2265 <blockquote class="text">
2266 <p>"OK" -
2267 </p>
2268 <blockquote class="text">
2269 <p>in case setting was successfully changed
2270 </p>
2271 </blockquote>
2272
2273
2274 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2275 </p>
2276 <blockquote class="text">
2277 <p>in case setting was changed successfully, but there are
2278 noteworthy issue(s) related, providing an appropriate
2279 warning code and warning message
2280 </p>
2281 </blockquote>
2282
2283
2284 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2285 </p>
2286 <blockquote class="text">
2287 <p>in case it failed, providing an appropriate error code and
2288 error message
2289 </p>
2290 </blockquote>
2291
2292
2293 </blockquote><p>
2294
2295 </p>
2296 <p>Example:
2297 </p>
2298 <p>
2299 </p>
2300 <blockquote class="text">
2301 <p>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"
2302 </p>
2303 <p>S: "OK"
2304 </p>
2305 </blockquote><p>
2306
2307 </p>
2308 <p>
2309 </p>
2310 <blockquote class="text">
2311 <p>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"
2312 </p>
2313 <p>S: "OK"
2314 </p>
2315 </blockquote><p>
2316
2317 </p>
2318 <a name="anchor10"></a><br /><hr />
2319 <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>
2320 <a name="rfc.section.6.3"></a><h3>6.3.&nbsp;
2321 Configuring MIDI input drivers</h3>
2322
2323 <p>Instances of drivers in LinuxSampler are called devices. You can use
2324 multiple MIDI devices simultaneously, e.g. to use MIDI over ethernet as
2325 MIDI input on one sampler channel and ALSA as MIDI input on another sampler
2326 channel. For particular MIDI input systems it's also possible to create
2327 several devices of the same MIDI input type. This chapter describes all
2328 commands to configure LinuxSampler's MIDI input devices and their parameters.
2329 </p>
2330 <p>Instead of defining commands and parameters for each driver individually,
2331 all possible parameters, their meanings and possible values have to be obtained
2332 at runtime. This makes the protocol a bit abstract, but has the advantage, that
2333 front-ends can be written independently of what drivers are currently implemented
2334 and what parameters these drivers are actually offering. This means front-ends can
2335 even handle drivers which are implemented somewhere in future without modifying
2336 the front-end at all.
2337 </p>
2338 <p>Commands for configuring MIDI input devices are pretty much the same as the
2339 commands for configuring audio output drivers, already described in the last
2340 chapter.
2341 </p>
2342 <p>Note: examples in this chapter showing particular parameters of drivers are
2343 not meant as specification of the drivers' parameters. Driver implementations in
2344 LinuxSampler might have complete different parameter names and meanings than shown
2345 in these examples or might change in future, so these examples are only meant for
2346 showing how to retrieve what parameters drivers are offering, how to retrieve their
2347 possible values, etc.
2348 </p>
2349 <a name="GET AVAILABLE_MIDI_INPUT_DRIVERS"></a><br /><hr />
2350 <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>
2351 <a name="rfc.section.6.3.1"></a><h3>6.3.1.&nbsp;
2352 Getting amount of available MIDI input drivers</h3>
2353
2354 <p>Use the following command to get the number of
2355 MIDI input drivers currently available for the
2356 LinuxSampler instance:
2357 </p>
2358 <p>
2359 </p>
2360 <blockquote class="text">
2361 <p>GET AVAILABLE_MIDI_INPUT_DRIVERS
2362 </p>
2363 </blockquote><p>
2364
2365 </p>
2366 <p>Possible Answers:
2367 </p>
2368 <p>
2369 </p>
2370 <blockquote class="text">
2371 <p>LinuxSampler will answer by sending the
2372 number of available MIDI input drivers.
2373 </p>
2374 </blockquote><p>
2375
2376 </p>
2377 <p>Example:
2378 </p>
2379 <p>
2380 </p>
2381 <blockquote class="text">
2382 <p>C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"
2383 </p>
2384 <p>S: "2"
2385 </p>
2386 </blockquote><p>
2387
2388 </p>
2389 <a name="LIST AVAILABLE_MIDI_INPUT_DRIVERS"></a><br /><hr />
2390 <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>
2391 <a name="rfc.section.6.3.2"></a><h3>6.3.2.&nbsp;
2392 Getting all available MIDI input drivers</h3>
2393
2394 <p>Use the following command to list all MIDI input drivers currently available
2395 for the LinuxSampler instance:
2396 </p>
2397 <p>
2398 </p>
2399 <blockquote class="text">
2400 <p>LIST AVAILABLE_MIDI_INPUT_DRIVERS
2401 </p>
2402 </blockquote><p>
2403
2404 </p>
2405 <p>Possible Answers:
2406 </p>
2407 <p>
2408 </p>
2409 <blockquote class="text">
2410 <p>LinuxSampler will answer by sending comma separated character
2411 strings, each symbolizing a MIDI input driver.
2412 </p>
2413 </blockquote><p>
2414
2415 </p>
2416 <p>Example:
2417 </p>
2418 <p>
2419 </p>
2420 <blockquote class="text">
2421 <p>C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
2422 </p>
2423 <p>S: "ALSA,JACK"
2424 </p>
2425 </blockquote><p>
2426
2427 </p>
2428 <a name="GET MIDI_INPUT_DRIVER INFO"></a><br /><hr />
2429 <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>
2430 <a name="rfc.section.6.3.3"></a><h3>6.3.3.&nbsp;
2431 Getting information about a specific MIDI input driver</h3>
2432
2433 <p>Use the following command to get detailed information about a specific MIDI input driver:
2434 </p>
2435 <p>
2436 </p>
2437 <blockquote class="text">
2438 <p>GET MIDI_INPUT_DRIVER INFO &lt;midi-input-driver&gt;
2439 </p>
2440 </blockquote><p>
2441
2442 </p>
2443 <p>Where &lt;midi-input-driver&gt; is the name of the MIDI input driver as returned
2444 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.
2445 </p>
2446 <p>Possible Answers:
2447 </p>
2448 <p>
2449 </p>
2450 <blockquote class="text">
2451 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2452 Each answer line begins with the information category name
2453 followed by a colon and then a space character &lt;SP&gt; and finally
2454 the info character string to that info category. At the moment
2455 the following information categories are defined:
2456 </p>
2457 <p>
2458 </p>
2459 <blockquote class="text">
2460 <p>DESCRIPTION -
2461 </p>
2462 <blockquote class="text">
2463 <p>arbitrary description text about the MIDI input driver
2464 </p>
2465 </blockquote>
2466
2467
2468 <p>VERSION -
2469 </p>
2470 <blockquote class="text">
2471 <p>arbitrary character string regarding the driver's version
2472 </p>
2473 </blockquote>
2474
2475
2476 <p>PARAMETERS -
2477 </p>
2478 <blockquote class="text">
2479 <p>comma separated list of all parameters available for the given MIDI input driver
2480 </p>
2481 </blockquote>
2482
2483
2484 </blockquote>
2485
2486
2487 <p>The mentioned fields above don't have to be in particular order.
2488 </p>
2489 </blockquote><p>
2490
2491 </p>
2492 <p>Example:
2493 </p>
2494 <p>
2495 </p>
2496 <blockquote class="text">
2497 <p>C: "GET MIDI_INPUT_DRIVER INFO ALSA"
2498 </p>
2499 <p>S: "DESCRIPTION: Advanced Linux Sound Architecture"
2500 </p>
2501 <p>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"
2502 </p>
2503 <p>&nbsp;&nbsp;&nbsp;"PARAMETERS: DRIVER,ACTIVE"
2504 </p>
2505 <p>&nbsp;&nbsp;&nbsp;"."
2506 </p>
2507 </blockquote><p>
2508
2509 </p>
2510 <a name="GET MIDI_INPUT_DRIVER_PARAMETER INFO"></a><br /><hr />
2511 <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>
2512 <a name="rfc.section.6.3.4"></a><h3>6.3.4.&nbsp;
2513 Getting information about specific MIDI input driver parameter</h3>
2514
2515 <p>Use the following command to get detailed information about a specific parameter of a specific MIDI input driver:
2516 </p>
2517 <p>
2518 </p>
2519 <blockquote class="text">
2520 <p>GET MIDI_INPUT_DRIVER_PARAMETER INFO &lt;midit&gt; &lt;param&gt; [&lt;deplist&gt;]
2521 </p>
2522 </blockquote><p>
2523
2524 </p>
2525 <p>Where &lt;midit&gt; is the name of the MIDI input driver as returned
2526 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
2527 parameter name for which information should be obtained (as returned by the
2528 <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
2529 of parameters on which the sought parameter &lt;param&gt; depends on,
2530 &lt;deplist&gt; is a key-value pair list in form of "key1=val1 key2=val2 ...",
2531 where character string values are encapsulated into apostrophes ('). Arguments
2532 given with &lt;deplist&gt; which are not dependency parameters of &lt;param&gt;
2533 will be ignored, means the front-end application can simply put all parameters
2534 in &lt;deplist&gt; with the values selected by the user.
2535 </p>
2536 <p>Possible Answers:
2537 </p>
2538 <p>LinuxSampler will answer by sending a &lt;CRLF> separated list.
2539 Each answer line begins with the information category name
2540 followed by a colon and then a space character &lt;SP> and finally
2541 the info character string to that info category. There is
2542 information which is always returned, independent of the
2543 given driver parameter and there is optional information
2544 which is only shown dependent to given driver parameter. At
2545 the moment the following information categories are defined:
2546 </p>
2547 <p>
2548 </p>
2549 <blockquote class="text">
2550 <p>TYPE -
2551 </p>
2552 <blockquote class="text">
2553 <p>either "BOOL" for boolean value(s) or "INT" for integer
2554 value(s) or "FLOAT" for dotted number(s) or "STRING" for
2555 character string(s)
2556 (always returned, no matter which driver parameter)
2557 </p>
2558 </blockquote>
2559
2560
2561 <p>DESCRIPTION -
2562 </p>
2563 <blockquote class="text">
2564 <p>arbitrary text describing the purpose of the parameter
2565 (always returned, no matter which driver parameter)
2566 </p>
2567 </blockquote>
2568
2569
2570 <p>MANDATORY -
2571 </p>
2572 <blockquote class="text">
2573 <p>either true or false, defines if this parameter must be
2574 given when the device is to be created with the
2575 <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
2576 (always returned, no matter which driver parameter)
2577 </p>
2578 </blockquote>
2579
2580
2581 <p>FIX -
2582 </p>
2583 <blockquote class="text">
2584 <p>either true or false, if false then this parameter can
2585 be changed at any time, once the device is created by
2586 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
2587 (always returned, no matter which driver parameter)
2588 </p>
2589 </blockquote>
2590
2591
2592 <p>MULTIPLICITY -
2593 </p>
2594 <blockquote class="text">
2595 <p>either true or false, defines if this parameter allows
2596 only one value or a list of values, where true means
2597 multiple values and false only a single value allowed
2598 (always returned, no matter which driver parameter)
2599 </p>
2600 </blockquote>
2601
2602
2603 <p>DEPENDS -
2604 </p>
2605 <blockquote class="text">
2606 <p>comma separated list of parameters this parameter depends
2607 on, means the values for fields 'DEFAULT', 'RANGE_MIN',
2608 'RANGE_MAX' and 'POSSIBILITIES' might depend on these
2609 listed parameters, for example assuming that an audio
2610 driver (like the ALSA driver) offers parameters 'card'
2611 and 'samplerate' then parameter 'samplerate' would
2612 depend on 'card' because the possible values for
2613 'samplerate' depends on the sound card which can be
2614 chosen by the 'card' parameter
2615 (optionally returned, dependent to driver parameter)
2616 </p>
2617 </blockquote>
2618
2619
2620 <p>DEFAULT -
2621 </p>
2622 <blockquote class="text">
2623 <p>reflects the default value for this parameter which is
2624 used when the device is created and not explicitly
2625 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,
2626 in case of MULTIPLCITY=true, this is a comma separated
2627 list, that's why character strings are encapsulated into
2628 apostrophes (')
2629 (optionally returned, dependent to driver parameter)
2630 </p>
2631 </blockquote>
2632
2633
2634 <p>RANGE_MIN -
2635 </p>
2636 <blockquote class="text">
2637 <p>defines lower limit of the allowed value range for this
2638 parameter, can be an integer value as well as a dotted
2639 number, this parameter is often used in conjunction
2640 with RANGE_MAX, but may also appear without
2641 (optionally returned, dependent to driver parameter)
2642 </p>
2643 </blockquote>
2644
2645
2646 <p>RANGE_MAX -
2647 </p>
2648 <blockquote class="text">
2649 <p>defines upper limit of the allowed value range for this
2650 parameter, can be an integer value as well as a dotted
2651 number, this parameter is often used in conjunction with
2652 RANGE_MIN, but may also appear without
2653 (optionally returned, dependent to driver parameter)
2654 </p>
2655 </blockquote>
2656
2657
2658 <p>POSSIBILITIES -
2659 </p>
2660 <blockquote class="text">
2661 <p>comma separated list of possible values for this
2662 parameter, character strings are encapsulated into
2663 apostrophes
2664 (optionally returned, dependent to driver parameter)
2665 </p>
2666 </blockquote>
2667
2668
2669 </blockquote><p>
2670
2671 </p>
2672 <p>The mentioned fields above don't have to be in particular order.
2673 </p>
2674 <p>Example:
2675 </p>
2676 <p>
2677 </p>
2678 <blockquote class="text">
2679 <p>C: "GET MIDI_INPUT_DRIVER_PARAMETER INFO ALSA ACTIVE"
2680 </p>
2681 <p>S: "DESCRIPTION: Whether device is enabled"
2682 </p>
2683 <p>&nbsp;&nbsp;&nbsp;"TYPE: BOOL"
2684 </p>
2685 <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
2686 </p>
2687 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
2688 </p>
2689 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
2690 </p>
2691 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: true"
2692 </p>
2693 <p>&nbsp;&nbsp;&nbsp;"."
2694 </p>
2695 </blockquote><p>
2696
2697 </p>
2698 <a name="CREATE MIDI_INPUT_DEVICE"></a><br /><hr />
2699 <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>
2700 <a name="rfc.section.6.3.5"></a><h3>6.3.5.&nbsp;
2701 Creating a MIDI input device</h3>
2702
2703 <p>Use the following command to create a new MIDI input device for the desired MIDI input system:
2704 </p>
2705 <p>
2706 </p>
2707 <blockquote class="text">
2708 <p>CREATE MIDI_INPUT_DEVICE &lt;midi-input-driver&gt; [&lt;param-list&gt;]
2709 </p>
2710 </blockquote><p>
2711
2712 </p>
2713 <p>Where &lt;midi-input-driver&gt; should be replaced by the desired MIDI input system as returned
2714 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
2715 optional list of driver specific parameters in form of "key1=val1 key2=val2 ...", where
2716 character string values should be encapsulated into apostrophes (').
2717 Note that there might be drivers which require parameter(s) to be
2718 given with this command. Use the previously described commands in
2719 this chapter to get that information.
2720 </p>
2721 <p>Possible Answers:
2722 </p>
2723 <p>
2724 </p>
2725 <blockquote class="text">
2726 <p>"OK[&lt;device-id&gt;]" -
2727 </p>
2728 <blockquote class="text">
2729 <p>in case the device was successfully created, where
2730 &lt;device-id&gt; is the numerical ID of the new device
2731 </p>
2732 </blockquote>
2733
2734
2735 <p>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2736 </p>
2737 <blockquote class="text">
2738 <p>in case the driver was loaded successfully, where
2739 &lt;device-id&gt; is the numerical ID of the new device, but
2740 there are noteworthy issue(s) related, providing an
2741 appropriate warning code and warning message
2742 </p>
2743 </blockquote>
2744
2745
2746 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2747 </p>
2748 <blockquote class="text">
2749 <p>in case it failed, providing an appropriate error code and error message
2750 </p>
2751 </blockquote>
2752
2753
2754 </blockquote><p>
2755
2756 </p>
2757 <p>Example:
2758 </p>
2759 <p>
2760 </p>
2761 <blockquote class="text">
2762 <p>C: "CREATE MIDI_INPUT_DEVICE ALSA"
2763 </p>
2764 <p>S: "OK[0]"
2765 </p>
2766 </blockquote><p>
2767
2768 </p>
2769 <a name="DESTROY MIDI_INPUT_DEVICE"></a><br /><hr />
2770 <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>
2771 <a name="rfc.section.6.3.6"></a><h3>6.3.6.&nbsp;
2772 Destroying a MIDI input device</h3>
2773
2774 <p>Use the following command to destroy a created MIDI input device:
2775 </p>
2776 <p>
2777 </p>
2778 <blockquote class="text">
2779 <p>DESTROY MIDI_INPUT_DEVICE &lt;device-id&gt;
2780 </p>
2781 </blockquote><p>
2782
2783 </p>
2784 <p>Where &lt;device-id&gt; should be replaced by the device's numerical ID as returned by the
2785 <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>
2786 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>
2787 command.
2788 </p>
2789 <p>Possible Answers:
2790 </p>
2791 <p>
2792 </p>
2793 <blockquote class="text">
2794 <p>"OK" -
2795 </p>
2796 <blockquote class="text">
2797 <p>in case the device was successfully destroyed
2798 </p>
2799 </blockquote>
2800
2801
2802 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2803 </p>
2804 <blockquote class="text">
2805 <p>in case the device was destroyed, but there are noteworthy
2806 issue(s) related, providing an appropriate warning code and
2807 warning message
2808 </p>
2809 </blockquote>
2810
2811
2812 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2813 </p>
2814 <blockquote class="text">
2815 <p>in case it failed, providing an appropriate error code and error message
2816 </p>
2817 </blockquote>
2818
2819
2820 </blockquote><p>
2821
2822 </p>
2823 <p>Example:
2824 </p>
2825 <p>
2826 </p>
2827 <blockquote class="text">
2828 <p>C: "DESTROY MIDI_INPUT_DEVICE 0"
2829 </p>
2830 <p>S: "OK"
2831 </p>
2832 </blockquote><p>
2833
2834 </p>
2835 <a name="GET MIDI_INPUT_DEVICES"></a><br /><hr />
2836 <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>
2837 <a name="rfc.section.6.3.7"></a><h3>6.3.7.&nbsp;
2838 Getting all created MIDI input device count</h3>
2839
2840 <p>Use the following command to count all created MIDI input devices:
2841 </p>
2842 <p>
2843 </p>
2844 <blockquote class="text">
2845 <p>GET MIDI_INPUT_DEVICES
2846 </p>
2847 </blockquote><p>
2848
2849 </p>
2850 <p>Possible Answers:
2851 </p>
2852 <p>
2853 </p>
2854 <blockquote class="text">
2855 <p>LinuxSampler will answer by sending the current number of all
2856 MIDI input devices.
2857 </p>
2858 </blockquote><p>
2859
2860 </p>
2861 <p>Example:
2862 </p>
2863 <p>
2864 </p>
2865 <blockquote class="text">
2866 <p>C: "GET MIDI_INPUT_DEVICES"
2867 </p>
2868 <p>S: "3"
2869 </p>
2870 </blockquote><p>
2871
2872 </p>
2873 <a name="LIST MIDI_INPUT_DEVICES"></a><br /><hr />
2874 <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>
2875 <a name="rfc.section.6.3.8"></a><h3>6.3.8.&nbsp;
2876 Getting all created MIDI input device list</h3>
2877
2878 <p>Use the following command to list all created MIDI input devices:
2879 </p>
2880 <p>
2881 </p>
2882 <blockquote class="text">
2883 <p>LIST MIDI_INPUT_DEVICES
2884 </p>
2885 </blockquote><p>
2886
2887 </p>
2888 <p>Possible Answers:
2889 </p>
2890 <p>
2891 </p>
2892 <blockquote class="text">
2893 <p>LinuxSampler will answer by sending a comma separated list
2894 with the numerical Ids of all created MIDI input devices.
2895 </p>
2896 </blockquote><p>
2897
2898 </p>
2899 <p>Examples:
2900 </p>
2901 <p>
2902 </p>
2903 <blockquote class="text">
2904 <p>C: "LIST MIDI_INPUT_DEVICES"
2905 </p>
2906 <p>S: "0,1,2"
2907 </p>
2908 </blockquote><p>
2909
2910 </p>
2911 <p>
2912 </p>
2913 <blockquote class="text">
2914 <p>C: "LIST MIDI_INPUT_DEVICES"
2915 </p>
2916 <p>S: "1,3"
2917 </p>
2918 </blockquote><p>
2919
2920 </p>
2921 <a name="GET MIDI_INPUT_DEVICE INFO"></a><br /><hr />
2922 <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>
2923 <a name="rfc.section.6.3.9"></a><h3>6.3.9.&nbsp;
2924 Getting current settings of a MIDI input device</h3>
2925
2926 <p>Use the following command to get current settings of a specific, created MIDI input device:
2927 </p>
2928 <p>
2929 </p>
2930 <blockquote class="text">
2931 <p>GET MIDI_INPUT_DEVICE INFO &lt;device-id&gt;
2932 </p>
2933 </blockquote><p>
2934
2935 </p>
2936 <p>Where &lt;device-id&gt; is the numerical ID of the MIDI input device as returned by the
2937 <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>
2938 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>
2939 command.
2940 </p>
2941 <p>Possible Answers:
2942 </p>
2943 <p>
2944 </p>
2945 <blockquote class="text">
2946 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2947 Each answer line begins with the information category name
2948 followed by a colon and then a space character &lt;SP&gt; and finally
2949 the info character string to that info category. As some
2950 parameters might allow multiple values, character strings are
2951 encapsulated into apostrophes ('). At the moment the following
2952 information categories are defined (independent of driver):
2953 </p>
2954 <p>
2955 </p>
2956 <blockquote class="text">
2957 <p>DRIVER -
2958 </p>
2959 <blockquote class="text">
2960 <p>identifier of the used MIDI input driver, as e.g.
2961 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>
2962 command
2963 </p>
2964 </blockquote>
2965
2966
2967 </blockquote>
2968
2969 <blockquote class="text">
2970 <p>ACTIVE -
2971 </p>
2972 <blockquote class="text">
2973 <p>either true or false, if false then the MIDI device is
2974 inactive and doesn't listen to any incoming MIDI events
2975 and thus doesn't forward them to connected sampler
2976 channels
2977 </p>
2978 </blockquote>
2979
2980
2981 </blockquote>
2982
2983
2984 </blockquote><p>
2985
2986 </p>
2987 <p>The mentioned fields above don't have to be in particular
2988 order. The fields above are only those fields which are
2989 returned by all MIDI input devices. Every MIDI input driver
2990 might have its own, additional driver specific parameters (see
2991 <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
2992 by this command.
2993 </p>
2994 <p>Example:
2995 </p>
2996 <p>
2997 </p>
2998 <blockquote class="text">
2999 <p>C: "GET MIDI_INPUT_DEVICE INFO 0"
3000 </p>
3001 <p>S: "DRIVER: ALSA"
3002 </p>
3003 <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
3004 </p>
3005 <p>&nbsp;&nbsp;&nbsp;"."
3006 </p>
3007 </blockquote><p>
3008
3009 </p>
3010 <a name="SET MIDI_INPUT_DEVICE_PARAMETER"></a><br /><hr />
3011 <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>
3012 <a name="rfc.section.6.3.10"></a><h3>6.3.10.&nbsp;
3013 Changing settings of MIDI input devices</h3>
3014
3015 <p>Use the following command to alter a specific setting of a created MIDI input device:
3016 </p>
3017 <p>
3018 </p>
3019 <blockquote class="text">
3020 <p>SET MIDI_INPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;
3021 </p>
3022 </blockquote><p>
3023
3024 </p>
3025 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
3026 MIDI input device as returned by the
3027 <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>
3028 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>
3029 command, &lt;key&gt; by the name of the parameter to change and
3030 &lt;value&gt; by the new value for this parameter.
3031 </p>
3032 <p>Possible Answers:
3033 </p>
3034 <p>
3035 </p>
3036 <blockquote class="text">
3037 <p>"OK" -
3038 </p>
3039 <blockquote class="text">
3040 <p>in case setting was successfully changed
3041 </p>
3042 </blockquote>
3043
3044
3045 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3046 </p>
3047 <blockquote class="text">
3048 <p>in case setting was changed successfully, but there are
3049 noteworthy issue(s) related, providing an appropriate
3050 warning code and warning message
3051 </p>
3052 </blockquote>
3053
3054
3055 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3056 </p>
3057 <blockquote class="text">
3058 <p>in case it failed, providing an appropriate error code and error message
3059 </p>
3060 </blockquote>
3061
3062
3063 </blockquote><p>
3064
3065 </p>
3066 <p>Example:
3067 </p>
3068 <p>
3069 </p>
3070 <blockquote class="text">
3071 <p>C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"
3072 </p>
3073 <p>S: "OK"
3074 </p>
3075 </blockquote><p>
3076
3077 </p>
3078 <a name="GET MIDI_INPUT_PORT INFO"></a><br /><hr />
3079 <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>
3080 <a name="rfc.section.6.3.11"></a><h3>6.3.11.&nbsp;
3081 Getting information about a MIDI port</h3>
3082
3083 <p>Use the following command to get information about a MIDI port:
3084 </p>
3085 <p>
3086 </p>
3087 <blockquote class="text">
3088 <p>GET MIDI_INPUT_PORT INFO &lt;device-id&gt; &lt;midi-port&gt;
3089 </p>
3090 </blockquote><p>
3091
3092 </p>
3093 <p>Where &lt;device-id&gt; is the numerical ID of the MIDI input device as returned by the
3094 <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>
3095 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>
3096 command and &lt;midi-port&gt; the MIDI input port number.
3097 </p>
3098 <p>Possible Answers:
3099 </p>
3100 <p>
3101 </p>
3102 <blockquote class="text">
3103 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3104 Each answer line begins with the information category name
3105 followed by a colon and then a space character &lt;SP&gt; and finally
3106 the info character string to that info category. At the moment
3107 the following information categories are defined:
3108 </p>
3109 <p>NAME -
3110 </p>
3111 <blockquote class="text">
3112 <p>arbitrary character string naming the port
3113 </p>
3114 </blockquote>
3115
3116
3117 </blockquote><p>
3118
3119 </p>
3120 <p>The field above is only the one which is returned by all MIDI
3121 ports regardless of the MIDI driver and port. Every MIDI port
3122 might have its own, additional driver and port specific
3123 parameters.
3124 </p>
3125 <p>Example:
3126 </p>
3127 <p>
3128 </p>
3129 <blockquote class="text">
3130 <p>C: "GET MIDI_INPUT_PORT INFO 0 0"
3131 </p>
3132 <p>S: "NAME: 'Masterkeyboard'"
3133 </p>
3134 <p>&nbsp;&nbsp;&nbsp;"ALSA_SEQ_BINDINGS: '64:0'"
3135 </p>
3136 <p>&nbsp;&nbsp;&nbsp;"."
3137 </p>
3138 </blockquote><p>
3139
3140 </p>
3141 <a name="GET MIDI_INPUT_PORT_PARAMETER INFO"></a><br /><hr />
3142 <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>
3143 <a name="rfc.section.6.3.12"></a><h3>6.3.12.&nbsp;
3144 Getting information about specific MIDI port parameter</h3>
3145
3146 <p>Use the following command to get detailed information about specific MIDI port parameter:
3147 </p>
3148 <p>
3149 </p>
3150 <blockquote class="text">
3151 <p>GET MIDI_INPUT_PORT_PARAMETER INFO &lt;dev-id&gt; &lt;port&gt; &lt;param&gt;
3152 </p>
3153 </blockquote><p>
3154
3155 </p>
3156 <p>Where &lt;dev-id&gt; is the numerical ID of the MIDI input device as returned by the
3157 <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>
3158 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>
3159 command, &lt;port&gt; the MIDI port number and
3160 &lt;param&gt; a specific port parameter name for which information should be
3161 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).
3162 </p>
3163 <p>Possible Answers:
3164 </p>
3165 <p>
3166 </p>
3167 <blockquote class="text">
3168 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3169 Each answer line begins with the information category name
3170 followed by a colon and then a space character &lt;SP&gt; and finally
3171 the info character string to that info category. There is
3172 information which is always returned, independently of the
3173 given channel parameter and there is optional information
3174 which are only shown dependently to the given MIDI port. At the
3175 moment the following information categories are defined:
3176 </p>
3177 <p>TYPE -
3178 </p>
3179 <blockquote class="text">
3180 <p>either "BOOL" for boolean value(s) or "INT" for integer
3181 value(s) or "FLOAT" for dotted number(s) or "STRING" for
3182 character string(s)
3183 (always returned)
3184 </p>
3185 </blockquote>
3186
3187
3188 <p>DESCRIPTION -
3189 </p>
3190 <blockquote class="text">
3191 <p>arbitrary text describing the purpose of the parameter
3192 (always returned)
3193 </p>
3194 </blockquote>
3195
3196
3197 <p>FIX -
3198 </p>
3199 <blockquote class="text">
3200 <p>either true or false, if true then this parameter is
3201 read only, thus cannot be altered
3202 (always returned)
3203 </p>
3204 </blockquote>
3205
3206
3207 <p>MULTIPLICITY -
3208 </p>
3209 <blockquote class="text">
3210 <p>either true or false, defines if this parameter allows
3211 only one value or a list of values, where true means
3212 multiple values and false only a single value allowed
3213 (always returned)
3214 </p>
3215 </blockquote>
3216
3217
3218 <p>RANGE_MIN -
3219 </p>
3220 <blockquote class="text">
3221 <p>defines lower limit of the allowed value range for this
3222 parameter, can be an integer value as well as a dotted
3223 number, this parameter is usually used in conjunction
3224 with 'RANGE_MAX' but may also appear without
3225 (optionally returned, dependent to driver and port
3226 parameter)
3227 </p>
3228 </blockquote>
3229
3230
3231 <p>RANGE_MAX -
3232 </p>
3233 <blockquote class="text">
3234 <p>defines upper limit of the allowed value range for this
3235 parameter, can be an integer value as well as a dotted
3236 number, this parameter is usually used in conjunction
3237 with 'RANGE_MIN' but may also appear without
3238 (optionally returned, dependent to driver and port
3239 parameter)
3240 </p>
3241 </blockquote>
3242
3243
3244 <p>POSSIBILITIES -
3245 </p>
3246 <blockquote class="text">
3247 <p>comma separated list of possible values for this
3248 parameter, character strings are encapsulated into
3249 apostrophes
3250 (optionally returned, dependent to device and port
3251 parameter)
3252 </p>
3253 </blockquote>
3254
3255
3256 </blockquote><p>
3257
3258 </p>
3259 <p>The mentioned fields above don't have to be in particular order.
3260 </p>
3261 <p>Example:
3262 </p>
3263 <p>
3264 </p>
3265 <blockquote class="text">
3266 <p>C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"
3267 </p>
3268 <p>S: "DESCRIPTION: bindings to other ALSA sequencer clients"
3269 </p>
3270 <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
3271 </p>
3272 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
3273 </p>
3274 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"
3275 </p>
3276 <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: '64:0','68:0','68:1'"
3277 </p>
3278 <p>&nbsp;&nbsp;&nbsp;"."
3279 </p>
3280 </blockquote><p>
3281
3282 </p>
3283 <a name="SET MIDI_INPUT_PORT_PARAMETER"></a><br /><hr />
3284 <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>
3285 <a name="rfc.section.6.3.13"></a><h3>6.3.13.&nbsp;
3286 Changing settings of MIDI input ports</h3>
3287
3288 <p>Use the following command to alter a specific setting of a MIDI input port:
3289 </p>
3290 <p>
3291 </p>
3292 <blockquote class="text">
3293 <p>SET MIDI_INPUT_PORT_PARAMETER &lt;device-id&gt; &lt;port&gt; &lt;key&gt;=&lt;value&gt;
3294 </p>
3295 </blockquote><p>
3296
3297 </p>
3298 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
3299 MIDI device as returned by the
3300 <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>
3301 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>
3302 command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of
3303 the parameter to change and &lt;value&gt; by the new value for this
3304 parameter.
3305 </p>
3306 <p>Possible Answers:
3307 </p>
3308 <p>
3309 </p>
3310 <blockquote class="text">
3311 <p>"OK" -
3312 </p>
3313 <blockquote class="text">
3314 <p>in case setting was successfully changed
3315 </p>
3316 </blockquote>
3317
3318
3319 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3320 </p>
3321 <blockquote class="text">
3322 <p>in case setting was changed successfully, but there are
3323 noteworthy issue(s) related, providing an appropriate
3324 warning code and warning message
3325 </p>
3326 </blockquote>
3327
3328
3329 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3330 </p>
3331 <blockquote class="text">
3332 <p>in case it failed, providing an appropriate error code and error message
3333 </p>
3334 </blockquote>
3335
3336
3337 </blockquote><p>
3338
3339 </p>
3340 <p>Example:
3341 </p>
3342 <p>
3343 </p>
3344 <blockquote class="text">
3345 <p>
3346 </p>
3347 </blockquote><p>
3348
3349 </p>
3350 <a name="anchor11"></a><br /><hr />
3351 <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>
3352 <a name="rfc.section.6.4"></a><h3>6.4.&nbsp;
3353 Configuring sampler channels</h3>
3354
3355 <p>The following commands describe how to add and remove sampler channels, associate a
3356 sampler channel with a sampler engine, load instruments and connect sampler channels to
3357 MIDI and audio devices.
3358 </p>
3359 <a name="LOAD INSTRUMENT"></a><br /><hr />
3360 <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>
3361 <a name="rfc.section.6.4.1"></a><h3>6.4.1.&nbsp;
3362 Loading an instrument</h3>
3363
3364 <p>An instrument file can be loaded and assigned to a sampler channel by one of the following commands:
3365 </p>
3366 <p>
3367 </p>
3368 <blockquote class="text">
3369 <p>LOAD INSTRUMENT [NON_MODAL] '&lt;filename&gt;' &lt;instr-index&gt; &lt;sampler-channel&gt;
3370 </p>
3371 </blockquote><p>
3372
3373 </p>
3374 <p>Where &lt;filename&gt; is the name of the instrument file on the
3375 LinuxSampler instance's host system, &lt;instr-index&gt; the index of the
3376 instrument in the instrument file and &lt;sampler-channel> is the
3377 number of the sampler channel the instrument should be assigned to.
3378 Each sampler channel can only have one instrument.
3379 </p>
3380 <p>Notice: since LSCP 1.2 the &lt;filename&gt; argument supports
3381 escape characters for special characters (see chapter
3382 "<a class='info' href='#character_set'>Character Set and Escape Sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>"
3383 for details) and accordingly backslash characters in the filename
3384 MUST now be escaped as well!
3385 </p>
3386 <p>The difference between regular and NON_MODAL versions of the command
3387 is that the regular command returns OK only after the instrument has been
3388 fully loaded and the channel is ready to be used while NON_MODAL version
3389 returns immediately and a background process is launched to load the instrument
3390 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>
3391 command can be used to obtain loading
3392 progress from INSTRUMENT_STATUS field. LOAD command will perform sanity checks
3393 such as making sure that the file could be read and it is of a proper format
3394 and SHOULD return ERR and SHOULD not launch the background process should any
3395 errors be detected at that point.
3396 </p>
3397 <p>Possible Answers:
3398 </p>
3399 <p>
3400 </p>
3401 <blockquote class="text">
3402 <p>"OK" -
3403 </p>
3404 <blockquote class="text">
3405 <p>in case the instrument was successfully loaded
3406 </p>
3407 </blockquote>
3408
3409
3410 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3411 </p>
3412 <blockquote class="text">
3413 <p>in case the instrument was loaded successfully, but there
3414 are noteworthy issue(s) related (e.g. Engine doesn't support
3415 one or more patch parameters provided by the loaded
3416 instrument file), providing an appropriate warning code and
3417 warning message
3418 </p>
3419 </blockquote>
3420
3421
3422 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3423 </p>
3424 <blockquote class="text">
3425 <p>in case it failed, providing an appropriate error code and error message
3426 </p>
3427 </blockquote>
3428
3429
3430 </blockquote><p>
3431
3432 </p>
3433 <p>Example:
3434 </p>
3435 <p>
3436 </p>
3437 <blockquote class="text">
3438 <p>
3439 </p>
3440 </blockquote><p>
3441
3442 </p>
3443 <a name="LOAD ENGINE"></a><br /><hr />
3444 <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>
3445 <a name="rfc.section.6.4.2"></a><h3>6.4.2.&nbsp;
3446 Loading a sampler engine</h3>
3447
3448 <p>A sampler engine type can be associated to a specific sampler
3449 channel by the following command:
3450 </p>
3451 <p>
3452 </p>
3453 <blockquote class="text">
3454 <p>LOAD ENGINE &lt;engine-name&gt; &lt;sampler-channel&gt;
3455 </p>
3456 </blockquote><p>
3457
3458 </p>
3459 <p>Where &lt;engine-name&gt; is an engine name as obtained by the
3460 <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;
3461 the sampler channel as returned by the
3462 <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a> or
3463 <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
3464 the engine type should be assigned to. This command should be issued
3465 after adding a new sampler channel and before any other control
3466 commands on the new sampler channel. It can also be used to change
3467 the engine type of a sampler channel. This command has (currently) no
3468 way to define or force if a new engine instance should be created and
3469 assigned to the given sampler channel or if an already existing
3470 instance of that engine type, shared with other sampler channels,
3471 should be used.
3472 </p>
3473 <p>Possible Answers:
3474 </p>
3475 <p>
3476 </p>
3477 <blockquote class="text">
3478 <p>"OK" -
3479 </p>
3480 <blockquote class="text">
3481 <p>in case the engine was successfully deployed
3482 </p>
3483 </blockquote>
3484
3485
3486 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3487 </p>
3488 <blockquote class="text">
3489 <p>in case the engine was deployed successfully, but there
3490 are noteworthy issue(s) related, providing an appropriate
3491 warning code and warning message
3492 </p>
3493 </blockquote>
3494
3495
3496 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3497 </p>
3498 <blockquote class="text">
3499 <p>in case it failed, providing an appropriate error code and
3500 error message
3501 </p>
3502 </blockquote>
3503
3504
3505 </blockquote><p>
3506
3507 </p>
3508 <p>Example:
3509 </p>
3510 <p>
3511 </p>
3512 <blockquote class="text">
3513 <p>
3514 </p>
3515 </blockquote><p>
3516
3517 </p>
3518 <a name="GET CHANNELS"></a><br /><hr />
3519 <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>
3520 <a name="rfc.section.6.4.3"></a><h3>6.4.3.&nbsp;
3521 Getting all created sampler channel count</h3>
3522
3523 <p>The number of sampler channels can change on runtime. To get the
3524 current amount of sampler channels, the front-end can send the
3525 following command:
3526 </p>
3527 <p>
3528 </p>
3529 <blockquote class="text">
3530 <p>GET CHANNELS
3531 </p>
3532 </blockquote><p>
3533
3534 </p>
3535 <p>Possible Answers:
3536 </p>
3537 <p>
3538 </p>
3539 <blockquote class="text">
3540 <p>LinuxSampler will answer by returning the current number of sampler channels.
3541 </p>
3542 </blockquote><p>
3543
3544 </p>
3545 <p>Example:
3546 </p>
3547 <p>
3548 </p>
3549 <blockquote class="text">
3550 <p>C: "GET CHANNELS"
3551 </p>
3552 <p>S: "12"
3553 </p>
3554 </blockquote><p>
3555
3556 </p>
3557 <a name="LIST CHANNELS"></a><br /><hr />
3558 <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>
3559 <a name="rfc.section.6.4.4"></a><h3>6.4.4.&nbsp;
3560 Getting all created sampler channel list</h3>
3561
3562 <p>The number of sampler channels can change on runtime. To get the
3563 current list of sampler channels, the front-end can send the
3564 following command:
3565 </p>
3566 <p>
3567 </p>
3568 <blockquote class="text">
3569 <p>LIST CHANNELS
3570 </p>
3571 </blockquote><p>
3572
3573 </p>
3574 <p>Possible Answers:
3575 </p>
3576 <p>
3577 </p>
3578 <blockquote class="text">
3579 <p>LinuxSampler will answer by returning a comma separated list
3580 with all sampler channels numerical IDs.
3581 </p>
3582 </blockquote><p>
3583
3584 </p>
3585 <p>Example:
3586 </p>
3587 <p>
3588 </p>
3589 <blockquote class="text">
3590 <p>C: "LIST CHANNELS"
3591 </p>
3592 <p>S: "0,1,2,3,4,5,6,9,10,11,15,20"
3593 </p>
3594 </blockquote><p>
3595
3596 </p>
3597 <a name="ADD CHANNEL"></a><br /><hr />
3598 <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>
3599 <a name="rfc.section.6.4.5"></a><h3>6.4.5.&nbsp;
3600 Adding a new sampler channel</h3>
3601
3602 <p>A new sampler channel can be added to the end of the sampler
3603 channel list by sending the following command:
3604 </p>
3605 <p>
3606 </p>
3607 <blockquote class="text">
3608 <p>ADD CHANNEL
3609 </p>
3610 </blockquote><p>
3611
3612 </p>
3613 <p>This will increment the sampler channel count by one and the new
3614 sampler channel will be appended to the end of the sampler channel
3615 list. The front-end should send the respective, related commands
3616 right after to e.g. load an engine, load an instrument and setting
3617 input, output method and eventually other commands to initialize
3618 the new channel. The front-end should use the sampler channel
3619 returned by the answer of this command to perform the previously
3620 recommended commands, to avoid race conditions e.g. with other
3621 front-ends that might also have sent an "ADD CHANNEL" command.
3622 </p>
3623 <p>Possible Answers:
3624 </p>
3625 <p>
3626 </p>
3627 <blockquote class="text">
3628 <p>"OK[&lt;sampler-channel&gt;]" -
3629 </p>
3630 <blockquote class="text">
3631 <p>in case a new sampler channel could be added, where
3632 &lt;sampler-channel&gt; reflects the channel number of the new
3633 created sampler channel which should be used to set up
3634 the sampler channel by sending subsequent initialization
3635 commands
3636 </p>
3637 </blockquote>
3638
3639
3640 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3641 </p>
3642 <blockquote class="text">
3643 <p>in case a new channel was added successfully, but there are
3644 noteworthy issue(s) related, providing an appropriate
3645 warning code and warning message
3646 </p>
3647 </blockquote>
3648
3649
3650 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3651 </p>
3652 <blockquote class="text">
3653 <p>in case it failed, providing an appropriate error code and
3654 error message
3655 </p>
3656 </blockquote>
3657
3658
3659 </blockquote><p>
3660
3661 </p>
3662 <p>Example:
3663 </p>
3664 <p>
3665 </p>
3666 <blockquote class="text">
3667 <p>
3668 </p>
3669 </blockquote><p>
3670
3671 </p>
3672 <a name="REMOVE CHANNEL"></a><br /><hr />
3673 <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>
3674 <a name="rfc.section.6.4.6"></a><h3>6.4.6.&nbsp;
3675 Removing a sampler channel</h3>
3676
3677 <p>A sampler channel can be removed by sending the following command:
3678 </p>
3679 <p>
3680 </p>
3681 <blockquote class="text">
3682 <p>REMOVE CHANNEL &lt;sampler-channel&gt;
3683 </p>
3684 </blockquote><p>
3685
3686 </p>
3687 <p>Where &lt;sampler-channel&gt; should be replaced by the
3688 number of the sampler channel as given by the
3689 <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
3690 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a>
3691 command. The channel numbers of all subsequent sampler channels
3692 remain the same.
3693 </p>
3694 <p>Possible Answers:
3695 </p>
3696 <p>
3697 </p>
3698 <blockquote class="text">
3699 <p>"OK" -
3700 </p>
3701 <blockquote class="text">
3702 <p>in case the given sampler channel could be removed
3703 </p>
3704 </blockquote>
3705
3706
3707 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3708 </p>
3709 <blockquote class="text">
3710 <p>in case the given channel was removed, but there are
3711 noteworthy issue(s) related, providing an appropriate
3712 warning code and warning message
3713 </p>
3714 </blockquote>
3715
3716
3717 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3718 </p>
3719 <blockquote class="text">
3720 <p>in case it failed, providing an appropriate error code and
3721 error message
3722 </p>
3723 </blockquote>
3724
3725
3726 </blockquote><p>
3727
3728 </p>
3729 <p>Example:
3730 </p>
3731 <p>
3732 </p>
3733 <blockquote class="text">
3734 <p>
3735 </p>
3736 </blockquote><p>
3737
3738 </p>
3739 <a name="GET AVAILABLE_ENGINES"></a><br /><hr />
3740 <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>
3741 <a name="rfc.section.6.4.7"></a><h3>6.4.7.&nbsp;
3742 Getting amount of available engines</h3>
3743
3744 <p>The front-end can ask for the number of available engines by sending the following command:
3745 </p>
3746 <p>
3747 </p>
3748 <blockquote class="text">
3749 <p>GET AVAILABLE_ENGINES
3750 </p>
3751 </blockquote><p>
3752
3753 </p>
3754 <p>Possible Answers:
3755 </p>
3756 <p>
3757 </p>
3758 <blockquote class="text">
3759 <p>LinuxSampler will answer by sending the number of available engines.
3760 </p>
3761 </blockquote><p>
3762
3763 </p>
3764 <p>Example:
3765 </p>
3766 <p>
3767 </p>
3768 <blockquote class="text">
3769 <p>C: "GET AVAILABLE_ENGINES"
3770 </p>
3771 <p>S: "4"
3772 </p>
3773 </blockquote><p>
3774
3775 </p>
3776 <a name="LIST AVAILABLE_ENGINES"></a><br /><hr />
3777 <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>
3778 <a name="rfc.section.6.4.8"></a><h3>6.4.8.&nbsp;
3779 Getting all available engines</h3>
3780
3781 <p>The front-end can ask for a list of all available engines by sending the following command:
3782 </p>
3783 <p>
3784 </p>
3785 <blockquote class="text">
3786 <p>LIST AVAILABLE_ENGINES
3787 </p>
3788 </blockquote><p>
3789
3790 </p>
3791 <p>Possible Answers:
3792 </p>
3793 <p>
3794 </p>
3795 <blockquote class="text">
3796 <p>LinuxSampler will answer by sending a comma separated list
3797 of the engines' names encapsulated into apostrophes (').
3798 Engine names can consist of lower and upper cases,
3799 digits and underlines ("_" character).
3800 </p>
3801 </blockquote><p>
3802
3803 </p>
3804 <p>Example:
3805 </p>
3806 <p>
3807 </p>
3808 <blockquote class="text">
3809 <p>C: "LIST AVAILABLE_ENGINES"
3810 </p>
3811 <p>S: "'GigEngine','AkaiEngine','DLSEngine','JoesCustomEngine'"
3812 </p>
3813 </blockquote><p>
3814
3815 </p>
3816 <a name="GET ENGINE INFO"></a><br /><hr />
3817 <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>
3818 <a name="rfc.section.6.4.9"></a><h3>6.4.9.&nbsp;
3819 Getting information about an engine</h3>
3820
3821 <p>The front-end can ask for information about a specific engine by
3822 sending the following command:
3823 </p>
3824 <p>
3825 </p>
3826 <blockquote class="text">
3827 <p>GET ENGINE INFO &lt;engine-name&gt;
3828 </p>
3829 </blockquote><p>
3830
3831 </p>
3832 <p>Where &lt;engine-name&gt; is an engine name as obtained by the
3833 <a class='info' href='#LIST AVAILABLE_ENGINES'>"LIST AVAILABLE_ENGINES"<span> (</span><span class='info'>Getting all available engines</span><span>)</span></a> command.
3834 </p>
3835 <p>Possible Answers:
3836 </p>
3837 <p>
3838 </p>
3839 <blockquote class="text">
3840 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3841 Each answer line begins with the information category name
3842 followed by a colon and then a space character &lt;SP&gt; and finally
3843 the info character string to that info category. At the moment
3844 the following categories are defined:
3845 </p>
3846 <p>
3847 </p>
3848 <blockquote class="text">
3849 <p>DESCRIPTION -
3850 </p>
3851 <blockquote class="text">
3852 <p>arbitrary description text about the engine
3853 </p>
3854 </blockquote>
3855
3856
3857 <p>VERSION -
3858 </p>
3859 <blockquote class="text">
3860 <p>arbitrary character string regarding the engine's version
3861 </p>
3862 </blockquote>
3863
3864
3865 </blockquote>
3866
3867
3868 </blockquote><p>
3869
3870 </p>
3871 <p>The mentioned fields above don't have to be in particular order.
3872 </p>
3873 <p>Example:
3874 </p>
3875 <p>
3876 </p>
3877 <blockquote class="text">
3878 <p>C: "GET ENGINE INFO JoesCustomEngine"
3879 </p>
3880 <p>S: "DESCRIPTION: this is Joe's custom sampler engine"
3881 </p>
3882 <p>&nbsp;&nbsp;&nbsp;"VERSION: testing-1.0"
3883 </p>
3884 <p>&nbsp;&nbsp;&nbsp;"."
3885 </p>
3886 </blockquote><p>
3887
3888 </p>
3889 <a name="GET CHANNEL INFO"></a><br /><hr />
3890 <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>
3891 <a name="rfc.section.6.4.10"></a><h3>6.4.10.&nbsp;
3892 Getting sampler channel information</h3>
3893
3894 <p>The front-end can ask for the current settings of a sampler channel
3895 by sending the following command:
3896 </p>
3897 <p>
3898 </p>
3899 <blockquote class="text">
3900 <p>GET CHANNEL INFO &lt;sampler-channel&gt;
3901 </p>
3902 </blockquote><p>
3903
3904 </p>
3905 <p>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
3906 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>
3907 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.
3908 </p>
3909 <p>Possible Answers:
3910 </p>
3911 <p>
3912 </p>
3913 <blockquote class="text">
3914 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3915 Each answer line begins with the settings category name
3916 followed by a colon and then a space character &lt;SP&gt; and finally
3917 the info character string to that setting category. At the
3918 moment the following categories are defined:
3919 </p>
3920 <p>
3921 </p>
3922 <blockquote class="text">
3923 <p>ENGINE_NAME -
3924 </p>
3925 <blockquote class="text">
3926 <p>name of the engine that is associated with the sampler
3927 channel, "NONE" if there's no engine associated yet for
3928 this sampler channel
3929 </p>
3930 </blockquote>
3931
3932
3933 <p>AUDIO_OUTPUT_DEVICE -
3934 </p>
3935 <blockquote class="text">
3936 <p>numerical ID of the audio output device which is
3937 currently connected to this sampler channel to output
3938 the audio signal, "NONE" if there's no device
3939 connected to this sampler channel
3940 </p>
3941 </blockquote>
3942
3943
3944 <p>AUDIO_OUTPUT_CHANNELS -
3945 </p>
3946 <blockquote class="text">
3947 <p>number of output channels the sampler channel offers
3948 (dependent to used sampler engine and loaded instrument)
3949 </p>
3950 </blockquote>
3951
3952
3953 <p>AUDIO_OUTPUT_ROUTING -
3954 </p>
3955 <blockquote class="text">
3956 <p>comma separated list which reflects to which audio
3957 channel of the selected audio output device each
3958 sampler output channel is routed to, e.g. "0,3" would
3959 mean the engine's output channel 0 is routed to channel
3960 0 of the audio output device and the engine's output
3961 channel 1 is routed to the channel 3 of the audio
3962 output device
3963 </p>
3964 </blockquote>
3965
3966
3967 <p>INSTRUMENT_FILE -
3968 </p>
3969 <blockquote class="text">
3970 <p>the file name of the loaded instrument, "NONE" if
3971 there's no instrument yet loaded for this sampler
3972 channel
3973 </p>
3974 </blockquote>
3975
3976
3977 <p>INSTRUMENT_NR -
3978 </p>
3979 <blockquote class="text">
3980 <p>the instrument index number of the loaded instrument
3981 </p>
3982 </blockquote>
3983
3984
3985 <p>INSTRUMENT_NAME -
3986 </p>
3987 <blockquote class="text">
3988 <p>the instrument name of the loaded instrument
3989 </p>
3990 </blockquote>
3991
3992
3993 <p>INSTRUMENT_STATUS -
3994 </p>
3995 <blockquote class="text">
3996 <p>integer values 0 to 100 indicating loading progress percentage for the instrument. Negative
3997 value indicates a loading exception. Value of 100 indicates that the instrument is fully
3998 loaded.
3999 </p>
4000 </blockquote>
4001
4002
4003 <p>MIDI_INPUT_DEVICE -
4004 </p>
4005 <blockquote class="text">
4006 <p>numerical ID of the MIDI input device which is
4007 currently connected to this sampler channel to deliver
4008 MIDI input commands, "NONE" if there's no device
4009 connected to this sampler channel
4010 </p>
4011 </blockquote>
4012
4013
4014 <p>MIDI_INPUT_PORT -
4015 </p>
4016 <blockquote class="text">
4017 <p>port number of the MIDI input device
4018 </p>
4019 </blockquote>
4020
4021
4022 <p>MIDI_INPUT_CHANNEL -
4023 </p>
4024 <blockquote class="text">
4025 <p>the MIDI input channel number this sampler channel
4026 should listen to or "ALL" to listen on all MIDI channels
4027 </p>
4028 </blockquote>
4029
4030
4031 <p>VOLUME -
4032 </p>
4033 <blockquote class="text">
4034 <p>optionally dotted number for the channel volume factor
4035 (where a value &lt; 1.0 means attenuation and a value >
4036 1.0 means amplification)
4037 </p>
4038 </blockquote>
4039
4040
4041 <p>MUTE -
4042 </p>
4043 <blockquote class="text">
4044 <p>Determines whether the channel is muted, "true" if the
4045 channel is muted, "false" if the channel is not muted, and
4046 "MUTED_BY_SOLO" if the channel is muted because of the
4047 presence of a solo channel and will be unmuted when
4048 there are no solo channels left
4049 </p>
4050 </blockquote>
4051
4052
4053 <p>SOLO -
4054 </p>
4055 <blockquote class="text">
4056 <p>Determines whether this is a solo channel, "true" if
4057 the channel is a solo channel; "false" otherwise
4058 </p>
4059 </blockquote>
4060
4061
4062 <p>MIDI_INSTRUMENT_MAP -
4063 </p>
4064 <blockquote class="text">
4065 <p>Determines to which MIDI instrument map this sampler
4066 channel is assigned to. Read chapter
4067 <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>
4068 for a list of possible values.
4069 </p>
4070 </blockquote>
4071
4072
4073 </blockquote>
4074
4075
4076 </blockquote><p>
4077
4078 </p>
4079 <p>The mentioned fields above don't have to be in particular order.
4080 </p>
4081 <p>Example:
4082 </p>
4083 <p>
4084 </p>
4085 <blockquote class="text">
4086 <p>C: "GET CHANNEL INFO 34"
4087 </p>
4088 <p>S: "ENGINE_NAME: GigEngine"
4089 </p>
4090 <p>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"
4091 </p>
4092 <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_DEVICE: 0"
4093 </p>
4094 <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_CHANNELS: 2"
4095 </p>
4096 <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 0,1"
4097 </p>
4098 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"
4099 </p>
4100 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"
4101 </p>
4102 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NAME: Fazioli Piano"
4103 </p>
4104 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_STATUS: 100"
4105 </p>
4106 <p>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_DEVICE: 0"
4107 </p>
4108 <p>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_PORT: 0"
4109 </p>
4110 <p>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_CHANNEL: 5"
4111 </p>
4112 <p>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"
4113 </p>
4114 <p>&nbsp;&nbsp;&nbsp;"MUTE: false"
4115 </p>
4116 <p>&nbsp;&nbsp;&nbsp;"SOLO: false"
4117 </p>
4118 <p>&nbsp;&nbsp;&nbsp;"MIDI_INSTRUMENT_MAP: NONE"
4119 </p>
4120 <p>&nbsp;&nbsp;&nbsp;"."
4121 </p>
4122 </blockquote><p>
4123
4124 </p>
4125 <a name="GET CHANNEL VOICE_COUNT"></a><br /><hr />
4126 <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>
4127 <a name="rfc.section.6.4.11"></a><h3>6.4.11.&nbsp;
4128 Current number of active voices</h3>
4129
4130 <p>The front-end can ask for the current number of active voices on a
4131 sampler channel by sending the following command:
4132 </p>
4133 <p>
4134 </p>
4135 <blockquote class="text">
4136 <p>GET CHANNEL VOICE_COUNT &lt;sampler-channel&gt;
4137 </p>
4138 </blockquote><p>
4139
4140 </p>
4141 <p>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
4142 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>
4143 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.
4144 </p>
4145 <p>Possible Answers:
4146 </p>
4147 <p>
4148 </p>
4149 <blockquote class="text">
4150 <p>LinuxSampler will answer by returning the number of active
4151 voices on that channel.
4152 </p>
4153 </blockquote><p>
4154
4155 </p>
4156 <p>Example:
4157 </p>
4158 <p>
4159 </p>
4160 <blockquote class="text">
4161 <p>
4162 </p>
4163 </blockquote><p>
4164
4165 </p>
4166 <a name="GET CHANNEL STREAM_COUNT"></a><br /><hr />
4167 <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>
4168 <a name="rfc.section.6.4.12"></a><h3>6.4.12.&nbsp;
4169 Current number of active disk streams</h3>
4170
4171 <p>The front-end can ask for the current number of active disk streams
4172 on a sampler channel by sending the following command:
4173 </p>
4174 <p>
4175 </p>
4176 <blockquote class="text">
4177 <p>GET CHANNEL STREAM_COUNT &lt;sampler-channel&gt;
4178 </p>
4179 </blockquote><p>
4180
4181 </p>
4182 <p>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
4183 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>
4184 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.
4185 </p>
4186 <p>Possible Answers:
4187 </p>
4188 <p>
4189 </p>
4190 <blockquote class="text">
4191 <p>LinuxSampler will answer by returning the number of active
4192 disk streams on that channel in case the engine supports disk
4193 streaming, if the engine doesn't support disk streaming it will
4194 return "NA" for not available.
4195 </p>
4196 </blockquote><p>
4197
4198 </p>
4199 <p>Example:
4200 </p>
4201 <p>
4202 </p>
4203 <blockquote class="text">
4204 <p>
4205 </p>
4206 </blockquote><p>
4207
4208 </p>
4209 <a name="GET CHANNEL BUFFER_FILL"></a><br /><hr />
4210 <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>
4211 <a name="rfc.section.6.4.13"></a><h3>6.4.13.&nbsp;
4212 Current fill state of disk stream buffers</h3>
4213
4214 <p>The front-end can ask for the current fill state of all disk streams
4215 on a sampler channel by sending the following command:
4216 </p>
4217 <p>
4218 </p>
4219 <blockquote class="text">
4220 <p>GET CHANNEL BUFFER_FILL BYTES &lt;sampler-channel&gt;
4221 </p>
4222 </blockquote><p>
4223
4224 </p>
4225 <p>to get the fill state in bytes or
4226 </p>
4227 <p>
4228 </p>
4229 <blockquote class="text">
4230 <p>GET CHANNEL BUFFER_FILL PERCENTAGE &lt;sampler-channel&gt;
4231 </p>
4232 </blockquote><p>
4233
4234 </p>
4235 <p>to get the fill state in percent, where &lt;sampler-channel&gt; is the
4236 sampler channel number the front-end is interested in
4237 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>
4238 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.
4239 </p>
4240 <p>Possible Answers:
4241 </p>
4242 <p>
4243 </p>
4244 <blockquote class="text">
4245 <p>LinuxSampler will either answer by returning a comma separated
4246 string with the fill state of all disk stream buffers on that
4247 channel or an empty line if there are no active disk streams or
4248 "NA" for *not available* in case the engine which is deployed
4249 doesn't support disk streaming. Each entry in the answer list
4250 will begin with the stream's ID in brackets followed by the
4251 numerical representation of the fill size (either in bytes or
4252 percentage). Note: due to efficiency reasons the fill states in
4253 the response are not in particular order, thus the front-end has
4254 to sort them by itself if necessary.
4255 </p>
4256 </blockquote><p>
4257
4258 </p>
4259 <p>Examples:
4260 </p>
4261 <p>
4262 </p>
4263 <blockquote class="text">
4264 <p>C: "GET CHANNEL BUFFER_FILL BYTES 4"
4265 </p>
4266 <p>S: "[115]420500,[116]510300,[75]110000,[120]230700"
4267 </p>
4268 </blockquote><p>
4269
4270 </p>
4271 <blockquote class="text">
4272 <p>C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
4273 </p>
4274 <p>S: "[115]90%,[116]98%,[75]40%,[120]62%"
4275 </p>
4276 </blockquote><p>
4277
4278 </p>
4279 <blockquote class="text">
4280 <p>C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
4281 </p>
4282 <p>S: ""
4283 </p>
4284 </blockquote><p>
4285
4286 </p>
4287 <a name="SET CHANNEL AUDIO_OUTPUT_DEVICE"></a><br /><hr />
4288 <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>
4289 <a name="rfc.section.6.4.14"></a><h3>6.4.14.&nbsp;
4290 Setting audio output device</h3>
4291
4292 <p>The front-end can set the audio output device 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_DEVICE &lt;sampler-channel&gt; &lt;audio-device-id&gt;
4299 </p>
4300 </blockquote><p>
4301
4302 </p>
4303 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4304 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>
4305 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
4306 &lt;audio-device-id&gt; is the numerical ID of the audio output device as given by the
4307 <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>
4308 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>
4309 command.
4310 </p>
4311 <p>Possible Answers:
4312 </p>
4313 <p>
4314 </p>
4315 <blockquote class="text">
4316 <p>"OK" -
4317 </p>
4318 <blockquote class="text">
4319 <p>on success
4320 </p>
4321 </blockquote>
4322
4323
4324 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4325 </p>
4326 <blockquote class="text">
4327 <p>if audio output device was set, but there are noteworthy
4328 issue(s) related, providing an appropriate warning code and
4329 warning message
4330 </p>
4331 </blockquote>
4332
4333
4334 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4335 </p>
4336 <blockquote class="text">
4337 <p>in case it failed, providing an appropriate error code and error message
4338 </p>
4339 </blockquote>
4340
4341
4342 </blockquote><p>
4343
4344 </p>
4345 <p>Examples:
4346 </p>
4347 <p>
4348 </p>
4349 <blockquote class="text">
4350 <p>
4351 </p>
4352 </blockquote><p>
4353
4354 </p>
4355 <a name="SET CHANNEL AUDIO_OUTPUT_TYPE"></a><br /><hr />
4356 <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>
4357 <a name="rfc.section.6.4.15"></a><h3>6.4.15.&nbsp;
4358 Setting audio output type</h3>
4359
4360 <p>DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
4361 </p>
4362 <p>The front-end can alter the audio output type on a specific sampler
4363 channel by sending the following command:
4364 </p>
4365 <p>
4366 </p>
4367 <blockquote class="text">
4368 <p>SET CHANNEL AUDIO_OUTPUT_TYPE &lt;sampler-channel&gt; &lt;audio-output-type&gt;
4369 </p>
4370 </blockquote><p>
4371
4372 </p>
4373 <p>Where &lt;audio-output-type&gt; is currently either "ALSA" or "JACK" and
4374 &lt;sampler-channel&gt; is the respective sampler channel number.
4375 </p>
4376 <p>Possible Answers:
4377 </p>
4378 <p>
4379 </p>
4380 <blockquote class="text">
4381 <p>"OK" -
4382 </p>
4383 <blockquote class="text">
4384 <p>on success
4385 </p>
4386 </blockquote>
4387
4388
4389 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4390 </p>
4391 <blockquote class="text">
4392 <p>if audio output type was set, but there are noteworthy
4393 issue(s) related, providing an appropriate warning code and
4394 warning message
4395 </p>
4396 </blockquote>
4397
4398
4399 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4400 </p>
4401 <blockquote class="text">
4402 <p>in case it failed, providing an appropriate error code and error message
4403 </p>
4404 </blockquote>
4405
4406
4407 </blockquote><p>
4408
4409 </p>
4410 <p>Examples:
4411 </p>
4412 <p>
4413 </p>
4414 <blockquote class="text">
4415 <p>
4416 </p>
4417 </blockquote><p>
4418
4419 </p>
4420 <a name="SET CHANNEL AUDIO_OUTPUT_CHANNEL"></a><br /><hr />
4421 <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>
4422 <a name="rfc.section.6.4.16"></a><h3>6.4.16.&nbsp;
4423 Setting audio output channel</h3>
4424
4425 <p>The front-end can alter the audio output channel on a specific
4426 sampler channel by sending the following command:
4427 </p>
4428 <p>
4429 </p>
4430 <blockquote class="text">
4431 <p>SET CHANNEL AUDIO_OUTPUT_CHANNEL &lt;sampler-chan&gt; &lt;audio-out&gt; &lt;audio-in&gt;
4432 </p>
4433 </blockquote><p>
4434
4435 </p>
4436 <p>Where &lt;sampler-chan&gt; is the sampler channel number
4437 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>
4438 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
4439 numerical ID of the sampler channel's audio output channel which should be
4440 rerouted and &lt;audio-in&gt; is the numerical ID of the audio channel of the selected audio
4441 output device where &lt;audio-out&gt; should be routed to.
4442 </p>
4443 <p>Possible Answers:
4444 </p>
4445 <p>
4446 </p>
4447 <blockquote class="text">
4448 <p>"OK" -
4449 </p>
4450 <blockquote class="text">
4451 <p>on success
4452 </p>
4453 </blockquote>
4454
4455
4456 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4457 </p>
4458 <blockquote class="text">
4459 <p>if audio output channel was set, but there are noteworthy
4460 issue(s) related, providing an appropriate warning code and
4461 warning message
4462 </p>
4463 </blockquote>
4464
4465
4466 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4467 </p>
4468 <blockquote class="text">
4469 <p>in case it failed, providing an appropriate error code and error message
4470 </p>
4471 </blockquote>
4472
4473
4474 </blockquote><p>
4475
4476 </p>
4477 <p>Examples:
4478 </p>
4479 <p>
4480 </p>
4481 <blockquote class="text">
4482 <p>
4483 </p>
4484 </blockquote><p>
4485
4486 </p>
4487 <a name="SET CHANNEL MIDI_INPUT_DEVICE"></a><br /><hr />
4488 <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>
4489 <a name="rfc.section.6.4.17"></a><h3>6.4.17.&nbsp;
4490 Setting MIDI input device</h3>
4491
4492 <p>The front-end can set the MIDI input device on a specific sampler
4493 channel by sending the following command:
4494 </p>
4495 <p>
4496 </p>
4497 <blockquote class="text">
4498 <p>SET CHANNEL MIDI_INPUT_DEVICE &lt;sampler-channel&gt; &lt;midi-device-id&gt;
4499 </p>
4500 </blockquote><p>
4501
4502 </p>
4503 <p>Where &lt;sampler-channel&gt; is the sampler channel number
4504 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>
4505 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
4506 and &lt;midi-device-id&gt; is the numerical ID of the MIDI input device as returned by the
4507 <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>
4508 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.
4509 </p>
4510 <p>Possible Answers:
4511 </p>
4512 <p>
4513 </p>
4514 <blockquote class="text">
4515 <p>"OK" -
4516 </p>
4517 <blockquote class="text">
4518 <p>on success
4519 </p>
4520 </blockquote>
4521
4522
4523 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4524 </p>
4525 <blockquote class="text">
4526 <p>if MIDI input device was set, but there are noteworthy
4527 issue(s) related, providing an appropriate warning code and
4528 warning message
4529 </p>
4530 </blockquote>
4531
4532
4533 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4534 </p>
4535 <blockquote class="text">
4536 <p>in case it failed, providing an appropriate error code and error message
4537 </p>
4538 </blockquote>
4539
4540
4541 </blockquote><p>
4542
4543 </p>
4544 <p>Examples:
4545 </p>
4546 <p>
4547 </p>
4548 <blockquote class="text">
4549 <p>
4550 </p>
4551 </blockquote><p>
4552
4553 </p>
4554 <a name="SET CHANNEL MIDI_INPUT_TYPE"></a><br /><hr />
4555 <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>
4556 <a name="rfc.section.6.4.18"></a><h3>6.4.18.&nbsp;
4557 Setting MIDI input type</h3>
4558
4559 <p>DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
4560 </p>
4561 <p>The front-end can alter the MIDI input type on a specific sampler
4562 channel by sending the following command:
4563 </p>
4564 <p>
4565 </p>
4566 <blockquote class="text">
4567 <p>SET CHANNEL MIDI_INPUT_TYPE &lt;sampler-channel&gt; &lt;midi-input-type&gt;
4568 </p>
4569 </blockquote><p>
4570
4571 </p>
4572 <p>Where &lt;midi-input-type&gt; is currently only "ALSA" and
4573 &lt;sampler-channel&gt; is the respective sampler channel number.
4574 </p>
4575 <p>Possible Answers:
4576 </p>
4577 <p>
4578 </p>
4579 <blockquote class="text">
4580 <p>"OK" -
4581 </p>
4582 <blockquote class="text">
4583 <p>on success
4584 </p>
4585 </blockquote>
4586
4587
4588 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4589 </p>
4590 <blockquote class="text">
4591 <p>if MIDI input type was set, but there are noteworthy
4592 issue(s) related, providing an appropriate warning code and
4593 warning message
4594 </p>
4595 </blockquote>
4596
4597
4598 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4599 </p>
4600 <blockquote class="text">
4601 <p>in case it failed, providing an appropriate error code and error message
4602 </p>
4603 </blockquote>
4604
4605
4606 </blockquote><p>
4607
4608 </p>
4609 <p>Examples:
4610 </p>
4611 <p>
4612 </p>
4613 <blockquote class="text">
4614 <p>
4615 </p>
4616 </blockquote><p>
4617
4618 </p>
4619 <a name="SET CHANNEL MIDI_INPUT_PORT"></a><br /><hr />
4620 <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>
4621 <a name="rfc.section.6.4.19"></a><h3>6.4.19.&nbsp;
4622 Setting MIDI input port</h3>
4623
4624 <p>The front-end can alter the MIDI input port on a specific sampler
4625 channel by sending the following command:
4626 </p>
4627 <p>
4628 </p>
4629 <blockquote class="text">
4630 <p>SET CHANNEL MIDI_INPUT_PORT &lt;sampler-channel&gt; &lt;midi-input-port&gt;
4631 </p>
4632 </blockquote><p>
4633
4634 </p>
4635 <p>Where &lt;midi-input-port&gt; is a MIDI input port number of the
4636 MIDI input device connected to the sampler channel given by
4637 &lt;sampler-channel&gt;.
4638 </p>
4639 <p>Possible Answers:
4640 </p>
4641 <p>
4642 </p>
4643 <blockquote class="text">
4644 <p>"OK" -
4645 </p>
4646 <blockquote class="text">
4647 <p>on success
4648 </p>
4649 </blockquote>
4650
4651
4652 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4653 </p>
4654 <blockquote class="text">
4655 <p>if MIDI input port was set, but there are noteworthy
4656 issue(s) related, providing an appropriate warning code and
4657 warning message
4658 </p>
4659 </blockquote>
4660
4661
4662 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4663 </p>
4664 <blockquote class="text">
4665 <p>in case it failed, providing an appropriate error code and error message
4666 </p>
4667 </blockquote>
4668
4669
4670 </blockquote><p>
4671
4672 </p>
4673 <p>Examples:
4674 </p>
4675 <p>
4676 </p>
4677 <blockquote class="text">
4678 <p>
4679 </p>
4680 </blockquote><p>
4681
4682 </p>
4683 <a name="SET CHANNEL MIDI_INPUT_CHANNEL"></a><br /><hr />
4684 <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>
4685 <a name="rfc.section.6.4.20"></a><h3>6.4.20.&nbsp;
4686 Setting MIDI input channel</h3>
4687
4688 <p>The front-end can alter the MIDI channel a sampler channel should
4689 listen to by sending the following command:
4690 </p>
4691 <p>
4692 </p>
4693 <blockquote class="text">
4694 <p>SET CHANNEL MIDI_INPUT_CHANNEL &lt;sampler-channel&gt; &lt;midi-input-chan&gt;
4695 </p>
4696 </blockquote><p>
4697
4698 </p>
4699 <p>Where &lt;midi-input-chan&gt; is the number of the new MIDI input channel where
4700 &lt;sampler-channel&gt; should listen to or "ALL" to listen on all 16 MIDI
4701 channels.
4702 </p>
4703 <p>Possible Answers:
4704 </p>
4705 <p>
4706 </p>
4707 <blockquote class="text">
4708 <p>"OK" -
4709 </p>
4710 <blockquote class="text">
4711 <p>on success
4712 </p>
4713 </blockquote>
4714
4715
4716 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4717 </p>
4718 <blockquote class="text">
4719 <p>if MIDI input channel was set, but there are noteworthy
4720 issue(s) related, providing an appropriate warning code and
4721 warning message
4722 </p>
4723 </blockquote>
4724
4725
4726 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4727 </p>
4728 <blockquote class="text">
4729 <p>in case it failed, providing an appropriate error code and error message
4730 </p>
4731 </blockquote>
4732
4733
4734 </blockquote><p>
4735
4736 </p>
4737 <p>Examples:
4738 </p>
4739 <p>
4740 </p>
4741 <blockquote class="text">
4742 <p>
4743 </p>
4744 </blockquote><p>
4745
4746 </p>
4747 <a name="SET CHANNEL VOLUME"></a><br /><hr />
4748 <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>
4749 <a name="rfc.section.6.4.21"></a><h3>6.4.21.&nbsp;
4750 Setting channel volume</h3>
4751
4752 <p>The front-end can alter the volume of a sampler channel by sending
4753 the following command:
4754 </p>
4755 <p>
4756 </p>
4757 <blockquote class="text">
4758 <p>SET CHANNEL VOLUME &lt;sampler-channel&gt; &lt;volume&gt;
4759 </p>
4760 </blockquote><p>
4761
4762 </p>
4763 <p>Where &lt;volume&gt; is an optionally dotted positive number (a value
4764 smaller than 1.0 means attenuation, whereas a value greater than
4765 1.0 means amplification) and &lt;sampler-channel&gt; defines the sampler
4766 channel where this volume factor should be set.
4767 </p>
4768 <p>Possible Answers:
4769 </p>
4770 <p>
4771 </p>
4772 <blockquote class="text">
4773 <p>"OK" -
4774 </p>
4775 <blockquote class="text">
4776 <p>on success
4777 </p>
4778 </blockquote>
4779
4780
4781 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4782 </p>
4783 <blockquote class="text">
4784 <p>if channel volume was set, but there are noteworthy
4785 issue(s) related, providing an appropriate warning code and
4786 warning message
4787 </p>
4788 </blockquote>
4789
4790
4791 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4792 </p>
4793 <blockquote class="text">
4794 <p>in case it failed, providing an appropriate error code and error message
4795 </p>
4796 </blockquote>
4797
4798
4799 </blockquote><p>
4800
4801 </p>
4802 <p>Examples:
4803 </p>
4804 <p>
4805 </p>
4806 <blockquote class="text">
4807 <p>
4808 </p>
4809 </blockquote><p>
4810
4811 </p>
4812 <a name="SET CHANNEL MUTE"></a><br /><hr />
4813 <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>
4814 <a name="rfc.section.6.4.22"></a><h3>6.4.22.&nbsp;
4815 Muting a sampler channel</h3>
4816
4817 <p>The front-end can mute/unmute a specific sampler
4818 channel by sending the following command:
4819 </p>
4820 <p>
4821 </p>
4822 <blockquote class="text">
4823 <p>SET CHANNEL MUTE &lt;sampler-channel&gt; &lt;mute&gt;
4824 </p>
4825 </blockquote><p>
4826
4827 </p>
4828 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4829 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>
4830 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
4831 &lt;mute&gt; should be replaced either by "1" to mute the channel or "0"
4832 to unmute the channel.
4833 </p>
4834 <p>Possible Answers:
4835 </p>
4836 <p>
4837 </p>
4838 <blockquote class="text">
4839 <p>"OK" -
4840 </p>
4841 <blockquote class="text">
4842 <p>on success
4843 </p>
4844 </blockquote>
4845
4846
4847 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4848 </p>
4849 <blockquote class="text">
4850 <p>if the channel was muted/unmuted, but there are noteworthy
4851 issue(s) related, providing an appropriate warning code and
4852 warning message
4853 </p>
4854 </blockquote>
4855
4856
4857 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4858 </p>
4859 <blockquote class="text">
4860 <p>in case it failed, providing an appropriate error code and error message
4861 </p>
4862 </blockquote>
4863
4864
4865 </blockquote><p>
4866
4867 </p>
4868 <p>Examples:
4869 </p>
4870 <p>
4871 </p>
4872 <blockquote class="text">
4873 <p>
4874 </p>
4875 </blockquote><p>
4876
4877 </p>
4878 <a name="SET CHANNEL SOLO"></a><br /><hr />
4879 <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>
4880 <a name="rfc.section.6.4.23"></a><h3>6.4.23.&nbsp;
4881 Soloing a sampler channel</h3>
4882
4883 <p>The front-end can solo/unsolo a specific sampler channel
4884 by sending the following command:
4885 </p>
4886 <p>
4887 </p>
4888 <blockquote class="text">
4889 <p>SET CHANNEL SOLO &lt;sampler-channel&gt; &lt;solo&gt;
4890 </p>
4891 </blockquote><p>
4892
4893 </p>
4894 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4895 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>
4896 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
4897 &lt;solo&gt; should be replaced either by "1" to solo the channel or "0"
4898 to unsolo the channel.
4899 </p>
4900 <p>Possible Answers:
4901 </p>
4902 <p>
4903 </p>
4904 <blockquote class="text">
4905 <p>"OK" -
4906 </p>
4907 <blockquote class="text">
4908 <p>on success
4909 </p>
4910 </blockquote>
4911
4912
4913 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4914 </p>
4915 <blockquote class="text">
4916 <p>if the channel was soloed/unsoloed, but there are noteworthy
4917 issue(s) related, providing an appropriate warning code and
4918 warning message
4919 </p>
4920 </blockquote>
4921
4922
4923 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4924 </p>
4925 <blockquote class="text">
4926 <p>in case it failed, providing an appropriate error code and error message
4927 </p>
4928 </blockquote>
4929
4930
4931 </blockquote><p>
4932
4933 </p>
4934 <p>Examples:
4935 </p>
4936 <p>
4937 </p>
4938 <blockquote class="text">
4939 <p>
4940 </p>
4941 </blockquote><p>
4942
4943 </p>
4944 <a name="SET CHANNEL MIDI_INSTRUMENT_MAP"></a><br /><hr />
4945 <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>
4946 <a name="rfc.section.6.4.24"></a><h3>6.4.24.&nbsp;
4947 Assigning a MIDI instrument map to a sampler channel</h3>
4948
4949 <p>The front-end can assign a MIDI instrument map to a specific sampler channel
4950 by sending the following command:
4951 </p>
4952 <p>
4953 </p>
4954 <blockquote class="text">
4955 <p>SET CHANNEL MIDI_INSTRUMENT_MAP &lt;sampler-channel&gt; &lt;map&gt;
4956 </p>
4957 </blockquote><p>
4958
4959 </p>
4960 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4961 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>
4962 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
4963 &lt;map&gt; can have the following possibilites:
4964 </p>
4965 <p>
4966 </p>
4967 <blockquote class="text">
4968 <p>"NONE" -
4969 </p>
4970 <blockquote class="text">
4971 <p>This is the default setting. In this case
4972 the sampler channel is not assigned any MIDI
4973 instrument map and thus will ignore all MIDI
4974 program change messages.
4975 </p>
4976 </blockquote>
4977
4978
4979 <p>"DEFAULT" -
4980 </p>
4981 <blockquote class="text">
4982 <p>The sampler channel will always use the
4983 default MIDI instrument map to handle MIDI
4984 program change messages.
4985 </p>
4986 </blockquote>
4987
4988
4989 <p>numeric ID -
4990 </p>
4991 <blockquote class="text">
4992 <p>You can assign a specific MIDI instrument map
4993 by replacing &lt;map&gt; with the respective numeric
4994 ID of the MIDI instrument map as returned by the
4995 <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>
4996 command. Once that map will be deleted, the sampler
4997 channel would fall back to "NONE".
4998 </p>
4999 </blockquote>
5000
5001
5002 </blockquote><p>
5003
5004 </p>
5005 <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>
5006 for details regarding MIDI instrument mapping.
5007 </p>
5008 <p>Possible Answers:
5009 </p>
5010 <p>
5011 </p>
5012 <blockquote class="text">
5013 <p>"OK" -
5014 </p>
5015 <blockquote class="text">
5016 <p>on success
5017 </p>
5018 </blockquote>
5019
5020
5021 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5022 </p>
5023 <blockquote class="text">
5024 <p>in case it failed, providing an appropriate error code and error message
5025 </p>
5026 </blockquote>
5027
5028
5029 </blockquote><p>
5030
5031 </p>
5032 <p>Examples:
5033 </p>
5034 <p>
5035 </p>
5036 <blockquote class="text">
5037 <p>
5038 </p>
5039 </blockquote><p>
5040
5041 </p>
5042 <a name="CREATE FX_SEND"></a><br /><hr />
5043 <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>
5044 <a name="rfc.section.6.4.25"></a><h3>6.4.25.&nbsp;
5045 Adding an effect send to a sampler channel</h3>
5046
5047 <p>The front-end can create an additional effect send on a specific sampler channel
5048 by sending the following command:
5049 </p>
5050 <p>
5051 </p>
5052 <blockquote class="text">
5053 <p>CREATE FX_SEND &lt;sampler-channel&gt; &lt;midi-ctrl&gt; [&lt;name&gt;]
5054 </p>
5055 </blockquote><p>
5056
5057 </p>
5058 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5059 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>
5060 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
5061 sampler channel on which the effect send should be created on, &lt;midi-ctrl&gt;
5062 is a number between 0..127 defining the MIDI controller which can alter the
5063 effect send level and &lt;name&gt; is an optional argument defining a name
5064 for the effect send entity. The name does not have to be unique.
5065 </p>
5066 <p>By default, that is as initial routing, the effect send's audio channels
5067 are automatically routed to the last audio channels of the sampler channel's
5068 audio output device, that way you can i.e. first increase the amount of audio
5069 channels on the audio output device for having dedicated effect send output
5070 channels and when "CREATE FX_SEND" is called, those channels will automatically
5071 be picked. You can alter the destination channels however with
5072 <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>.
5073
5074 </p>
5075 <p>Note: Create effect sends on a sampler channel only when needed, because having effect
5076 sends on a sampler channel will decrease runtime performance, because for implementing channel
5077 effect sends, separate (sampler channel local) audio buffers are needed to render and mix
5078 the voices and route the audio signal afterwards to the master outputs and effect send
5079 outputs (along with their respective effect send levels). A sampler channel without effect
5080 sends however can mix its voices directly into the audio output devices's audio buffers
5081 and is thus faster.
5082
5083 </p>
5084 <p>Possible Answers:
5085 </p>
5086 <p>
5087 </p>
5088 <blockquote class="text">
5089 <p>"OK[&lt;fx-send-id&gt;]" -
5090 </p>
5091 <blockquote class="text">
5092 <p>in case a new effect send could be added to the
5093 sampler channel, where &lt;fx-send-id&gt; reflects the
5094 unique ID of the newly created effect send entity
5095 </p>
5096 </blockquote>
5097
5098
5099 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5100 </p>
5101 <blockquote class="text">
5102 <p>when a new effect send could not be added, i.e.
5103 due to invalid parameters
5104 </p>
5105 </blockquote>
5106
5107
5108 </blockquote><p>
5109
5110 </p>
5111 <p>Examples:
5112 </p>
5113 <p>
5114 </p>
5115 <blockquote class="text">
5116 <p>C: "CREATE FX_SEND 0 91 'Reverb Send'"
5117 </p>
5118 <p>S: "OK[0]"
5119 </p>
5120 </blockquote><p>
5121
5122 </p>
5123 <p>
5124 </p>
5125 <blockquote class="text">
5126 <p>C: "CREATE FX_SEND 0 93"
5127 </p>
5128 <p>S: "OK[1]"
5129 </p>
5130 </blockquote><p>
5131
5132 </p>
5133 <a name="DESTROY FX_SEND"></a><br /><hr />
5134 <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>
5135 <a name="rfc.section.6.4.26"></a><h3>6.4.26.&nbsp;
5136 Removing an effect send from a sampler channel</h3>
5137
5138 <p>The front-end can remove an existing effect send on a specific sampler channel
5139 by sending the following command:
5140 </p>
5141 <p>
5142 </p>
5143 <blockquote class="text">
5144 <p>DESTROY FX_SEND &lt;sampler-channel&gt; &lt;fx-send-id&gt;
5145 </p>
5146 </blockquote><p>
5147
5148 </p>
5149 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5150 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>
5151 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
5152 sampler channel from which the effect send should be removed from and
5153 &lt;fx-send-id&gt; is the respective effect send number as returned by the
5154 <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>
5155 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.
5156 </p>
5157 <p>Possible Answers:
5158 </p>
5159 <p>
5160 </p>
5161 <blockquote class="text">
5162 <p>"OK" -
5163 </p>
5164 <blockquote class="text">
5165 <p>on success
5166 </p>
5167 </blockquote>
5168
5169
5170 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5171 </p>
5172 <blockquote class="text">
5173 <p>in case it failed, providing an appropriate error code and
5174 error message
5175 </p>
5176 </blockquote>
5177
5178
5179 </blockquote><p>
5180
5181 </p>
5182 <p>Example:
5183 </p>
5184 <p>
5185 </p>
5186 <blockquote class="text">
5187 <p>C: "DESTROY FX_SEND 0 0"
5188 </p>
5189 <p>S: "OK"
5190 </p>
5191 </blockquote><p>
5192
5193 </p>
5194 <a name="GET FX_SENDS"></a><br /><hr />
5195 <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>
5196 <a name="rfc.section.6.4.27"></a><h3>6.4.27.&nbsp;
5197 Getting amount of effect sends on a sampler channel</h3>
5198
5199 <p>The front-end can ask for the amount of effect sends on a specific sampler channel
5200 by sending the following command:
5201 </p>
5202 <p>
5203 </p>
5204 <blockquote class="text">
5205 <p>GET FX_SENDS &lt;sampler-channel&gt;
5206 </p>
5207 </blockquote><p>
5208
5209 </p>
5210 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5211 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>
5212 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.
5213 </p>
5214 <p>Possible Answers:
5215 </p>
5216 <p>
5217 </p>
5218 <blockquote class="text">
5219 <p>The sampler will answer by returning the number of effect
5220 sends on the given sampler channel.
5221 </p>
5222 </blockquote><p>
5223
5224 </p>
5225 <p>Example:
5226 </p>
5227 <p>
5228 </p>
5229 <blockquote class="text">
5230 <p>C: "GET FX_SENDS 0"
5231 </p>
5232 <p>S: "2"
5233 </p>
5234 </blockquote><p>
5235
5236 </p>
5237 <a name="LIST FX_SENDS"></a><br /><hr />
5238 <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>
5239 <a name="rfc.section.6.4.28"></a><h3>6.4.28.&nbsp;
5240 Listing all effect sends on a sampler channel</h3>
5241
5242 <p>The front-end can ask for a list of effect sends on a specific sampler channel
5243 by sending the following command:
5244 </p>
5245 <p>
5246 </p>
5247 <blockquote class="text">
5248 <p>LIST FX_SENDS &lt;sampler-channel&gt;
5249 </p>
5250 </blockquote><p>
5251
5252 </p>
5253 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5254 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>
5255 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.
5256 </p>
5257 <p>Possible Answers:
5258 </p>
5259 <p>
5260 </p>
5261 <blockquote class="text">
5262 <p>The sampler will answer by returning a comma separated list
5263 with all effect sends' numerical IDs on the given sampler
5264 channel.
5265 </p>
5266 </blockquote><p>
5267
5268 </p>
5269 <p>Examples:
5270 </p>
5271 <p>
5272 </p>
5273 <blockquote class="text">
5274 <p>C: "LIST FX_SENDS 0"
5275 </p>
5276 <p>S: "0,1"
5277 </p>
5278 </blockquote><p>
5279
5280 </p>
5281 <p>
5282 </p>
5283 <blockquote class="text">
5284 <p>C: "LIST FX_SENDS 1"
5285 </p>
5286 <p>S: ""
5287 </p>
5288 </blockquote><p>
5289
5290 </p>
5291 <a name="GET FX_SEND INFO"></a><br /><hr />
5292 <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>
5293 <a name="rfc.section.6.4.29"></a><h3>6.4.29.&nbsp;
5294 Getting effect send information</h3>
5295
5296 <p>The front-end can ask for the current settings of an effect send entity
5297 by sending the following command:
5298 </p>
5299 <p>
5300 </p>
5301 <blockquote class="text">
5302 <p>GET FX_SEND INFO &lt;sampler-channel&gt; &lt;fx-send-id&gt;
5303 </p>
5304 </blockquote><p>
5305
5306 </p>
5307 <p>Where &lt;sampler-channel&gt; is the sampler channel number
5308 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>
5309 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
5310 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5311 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>
5312 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.
5313
5314 </p>
5315 <p>Possible Answers:
5316 </p>
5317 <p>
5318 </p>
5319 <blockquote class="text">
5320 <p>The sampler will answer by sending a &lt;CRLF&gt; separated list.
5321 Each answer line begins with the settings category name
5322 followed by a colon and then a space character &lt;SP&gt; and finally
5323 the info character string to that setting category. At the
5324 moment the following categories are defined:
5325 </p>
5326 <p>
5327 </p>
5328 <blockquote class="text">
5329 <p>NAME -
5330 </p>
5331 <blockquote class="text">
5332 <p>name of the effect send entity
5333 </p>
5334 </blockquote>
5335
5336
5337 <p>MIDI_CONTROLLER -
5338 </p>
5339 <blockquote class="text">
5340 <p>a value between 0 and 127 reflecting the MIDI controller
5341 which is able to modify the effect send's send level
5342 </p>
5343 </blockquote>
5344
5345
5346 <p>LEVEL -
5347 </p>
5348 <blockquote class="text">
5349 <p>optionally dotted number reflecting the effect send's
5350 current send level (where a value &lt; 1.0 means attenuation
5351 and a value > 1.0 means amplification)
5352 </p>
5353 </blockquote>
5354
5355
5356 <p>AUDIO_OUTPUT_ROUTING -
5357 </p>
5358 <blockquote class="text">
5359 <p>comma separated list which reflects to which audio
5360 channel of the selected audio output device each
5361 effect send output channel is routed to, e.g. "0,3" would
5362 mean the effect send's output channel 0 is routed to channel
5363 0 of the audio output device and the effect send's output
5364 channel 1 is routed to the channel 3 of the audio
5365 output device (see
5366 <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>
5367 for details)
5368 </p>
5369 </blockquote>
5370
5371
5372 </blockquote>
5373
5374
5375 </blockquote><p>
5376
5377 </p>
5378 <p>The mentioned fields above don't have to be in particular order.
5379 </p>
5380 <p>Example:
5381 </p>
5382 <p>
5383 </p>
5384 <blockquote class="text">
5385 <p>C: "GET FX_SEND INFO 0 0"
5386 </p>
5387 <p>S: "NAME: Reverb Send"
5388 </p>
5389 <p>&nbsp;&nbsp;&nbsp;"MIDI_CONTROLLER: 91"
5390 </p>
5391 <p>&nbsp;&nbsp;&nbsp;"LEVEL: 0.3"
5392 </p>
5393 <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 2,3"
5394 </p>
5395 <p>&nbsp;&nbsp;&nbsp;"."
5396 </p>
5397 </blockquote><p>
5398
5399 </p>
5400 <a name="SET FX_SEND NAME"></a><br /><hr />
5401 <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>
5402 <a name="rfc.section.6.4.30"></a><h3>6.4.30.&nbsp;
5403 Changing effect send's name</h3>
5404
5405 <p>The front-end can alter the current name of an effect
5406 send entity by sending the following command:
5407 </p>
5408 <p>
5409 </p>
5410 <blockquote class="text">
5411 <p>SET FX_SEND NAME &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;name&gt;
5412 </p>
5413 </blockquote><p>
5414
5415 </p>
5416 <p>Where &lt;sampler-chan&gt; is the sampler channel number
5417 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>
5418 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,
5419 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5420 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>
5421 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
5422 &lt;name&gt; is the new name of the effect send entity, which
5423 does not have to be unique.
5424 </p>
5425 <p>Possible Answers:
5426 </p>
5427 <p>
5428 </p>
5429 <blockquote class="text">
5430 <p>"OK" -
5431 </p>
5432 <blockquote class="text">
5433 <p>on success
5434 </p>
5435 </blockquote>
5436
5437
5438 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5439 </p>
5440 <blockquote class="text">
5441 <p>in case it failed, providing an appropriate error code and error message
5442 </p>
5443 </blockquote>
5444
5445
5446 </blockquote><p>
5447
5448 </p>
5449 <p>Example:
5450 </p>
5451 <p>
5452 </p>
5453 <blockquote class="text">
5454 <p>C: "SET FX_SEND NAME 0 0 'Fx Send 1'"
5455 </p>
5456 <p>S: "OK"
5457 </p>
5458 </blockquote><p>
5459
5460 </p>
5461 <a name="SET FX_SEND AUDIO_OUTPUT_CHANNEL"></a><br /><hr />
5462 <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>
5463 <a name="rfc.section.6.4.31"></a><h3>6.4.31.&nbsp;
5464 Altering effect send's audio routing</h3>
5465
5466 <p>The front-end can alter the destination of an effect send's audio channel on a specific
5467 sampler channel by sending the following command:
5468 </p>
5469 <p>
5470 </p>
5471 <blockquote class="text">
5472 <p>SET FX_SEND AUDIO_OUTPUT_CHANNEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;audio-src&gt; &lt;audio-dst&gt;
5473 </p>
5474 </blockquote><p>
5475
5476 </p>
5477 <p>Where &lt;sampler-chan&gt; is the sampler channel number
5478 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>
5479 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,
5480 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5481 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>
5482 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,
5483 &lt;audio-src&gt; is the numerical ID of the effect send's audio channel
5484 which should be rerouted and &lt;audio-dst&gt; is the numerical ID of
5485 the audio channel of the selected audio output device where &lt;audio-src&gt;
5486 should be routed to.
5487 </p>
5488 <p>Note that effect sends can only route audio to the same audio output
5489 device as assigned to the effect send's sampler channel. Also note that an
5490 effect send entity does always have exactly as much audio channels as its
5491 sampler channel. So if the sampler channel is stereo, the effect send does
5492 have two audio channels as well. Also keep in mind that the amount of audio
5493 channels on a sampler channel might be dependant not only to the deployed
5494 sampler engine on the sampler channel, but also dependant to the instrument
5495 currently loaded. However you can (effectively) turn an i.e. stereo effect
5496 send into a mono one by simply altering its audio routing appropriately.
5497 </p>
5498 <p>Possible Answers:
5499 </p>
5500 <p>
5501 </p>
5502 <blockquote class="text">
5503 <p>"OK" -
5504 </p>
5505 <blockquote class="text">
5506 <p>on success
5507 </p>
5508 </blockquote>
5509
5510
5511 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5512 </p>
5513 <blockquote class="text">
5514 <p>if audio output channel was set, but there are noteworthy
5515 issue(s) related, providing an appropriate warning code and
5516 warning message
5517 </p>
5518 </blockquote>
5519
5520
5521 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5522 </p>
5523 <blockquote class="text">
5524 <p>in case it failed, providing an appropriate error code and error message
5525 </p>
5526 </blockquote>
5527
5528
5529 </blockquote><p>
5530
5531 </p>
5532 <p>Example:
5533 </p>
5534 <p>
5535 </p>
5536 <blockquote class="text">
5537 <p>C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2"
5538 </p>
5539 <p>S: "OK"
5540 </p>
5541 </blockquote><p>
5542
5543 </p>
5544 <a name="SET FX_SEND MIDI_CONTROLLER"></a><br /><hr />
5545 <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>
5546 <a name="rfc.section.6.4.32"></a><h3>6.4.32.&nbsp;
5547 Altering effect send's MIDI controller</h3>
5548
5549 <p>The front-end can alter the MIDI controller of an effect
5550 send entity by sending the following command:
5551 </p>
5552 <p>
5553 </p>
5554 <blockquote class="text">
5555 <p>SET FX_SEND MIDI_CONTROLLER &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;midi-ctrl&gt;
5556 </p>
5557 </blockquote><p>
5558
5559 </p>
5560 <p>Where &lt;sampler-chan&gt; is the sampler channel number
5561 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>
5562 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,
5563 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5564 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>
5565 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
5566 &lt;midi-ctrl&gt; reflects the MIDI controller which shall be
5567 able to modify the effect send's send level.
5568 </p>
5569 <p>Possible Answers:
5570 </p>
5571 <p>
5572 </p>
5573 <blockquote class="text">
5574 <p>"OK" -
5575 </p>
5576 <blockquote class="text">
5577 <p>on success
5578 </p>
5579 </blockquote>
5580
5581
5582 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5583 </p>
5584 <blockquote class="text">
5585 <p>if MIDI controller was set, but there are noteworthy
5586 issue(s) related, providing an appropriate warning code and
5587 warning message
5588 </p>
5589 </blockquote>
5590
5591
5592 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5593 </p>
5594 <blockquote class="text">
5595 <p>in case it failed, providing an appropriate error code and error message
5596 </p>
5597 </blockquote>
5598
5599
5600 </blockquote><p>
5601
5602 </p>
5603 <p>Example:
5604 </p>
5605 <p>
5606 </p>
5607 <blockquote class="text">
5608 <p>C: "SET FX_SEND MIDI_CONTROLLER 0 0 91"
5609 </p>
5610 <p>S: "OK"
5611 </p>
5612 </blockquote><p>
5613
5614 </p>
5615 <a name="SET FX_SEND LEVEL"></a><br /><hr />
5616 <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>
5617 <a name="rfc.section.6.4.33"></a><h3>6.4.33.&nbsp;
5618 Altering effect send's send level</h3>
5619
5620 <p>The front-end can alter the current send level of an effect
5621 send entity by sending the following command:
5622 </p>
5623 <p>
5624 </p>
5625 <blockquote class="text">
5626 <p>SET FX_SEND LEVEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;volume&gt;
5627 </p>
5628 </blockquote><p>
5629
5630 </p>
5631 <p>Where &lt;sampler-chan&gt; is the sampler channel number
5632 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>
5633 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,
5634 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5635 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>
5636 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
5637 &lt;volume&gt; is an optionally dotted positive number (a value
5638 smaller than 1.0 means attenuation, whereas a value greater than
5639 1.0 means amplification) reflecting the new send level.
5640 </p>
5641 <p>Possible Answers:
5642 </p>
5643 <p>
5644 </p>
5645 <blockquote class="text">
5646 <p>"OK" -
5647 </p>
5648 <blockquote class="text">
5649 <p>on success
5650 </p>
5651 </blockquote>
5652
5653
5654 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5655 </p>
5656 <blockquote class="text">
5657 <p>if new send level was set, but there are noteworthy
5658 issue(s) related, providing an appropriate warning code and
5659 warning message
5660 </p>
5661 </blockquote>
5662
5663
5664 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5665 </p>
5666 <blockquote class="text">
5667 <p>in case it failed, providing an appropriate error code and error message
5668 </p>
5669 </blockquote>
5670
5671
5672 </blockquote><p>
5673
5674 </p>
5675 <p>Example:
5676 </p>
5677 <p>
5678 </p>
5679 <blockquote class="text">
5680 <p>C: "SET FX_SEND LEVEL 0 0 0.15"
5681 </p>
5682 <p>S: "OK"
5683 </p>
5684 </blockquote><p>
5685
5686 </p>
5687 <a name="RESET CHANNEL"></a><br /><hr />
5688 <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>
5689 <a name="rfc.section.6.4.34"></a><h3>6.4.34.&nbsp;
5690 Resetting a sampler channel</h3>
5691
5692 <p>The front-end can reset a particular sampler channel by sending the following command:
5693 </p>
5694 <p>
5695 </p>
5696 <blockquote class="text">
5697 <p>RESET CHANNEL &lt;sampler-channel&gt;
5698 </p>
5699 </blockquote><p>
5700
5701 </p>
5702 <p>
5703 Where &lt;sampler-channel&gt; defines the sampler channel to be reset.
5704 This will cause the engine on that sampler channel, its voices and
5705 eventually disk streams and all control and status variables to be
5706 reset.
5707 </p>
5708 <p>Possible Answers:
5709 </p>
5710 <p>
5711 </p>
5712 <blockquote class="text">
5713 <p>"OK" -
5714 </p>
5715 <blockquote class="text">
5716 <p>on success
5717 </p>
5718 </blockquote>
5719
5720
5721 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5722 </p>
5723 <blockquote class="text">
5724 <p>if channel was reset, but there are noteworthy issue(s)
5725 related, providing an appropriate warning code and warning
5726 message
5727 </p>
5728 </blockquote>
5729
5730
5731 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5732 </p>
5733 <blockquote class="text">
5734 <p>in case it failed, providing an appropriate error code and
5735 error message
5736 </p>
5737 </blockquote>
5738
5739
5740 </blockquote><p>
5741
5742 </p>
5743 <p>Examples:
5744 </p>
5745 <p>
5746 </p>
5747 <blockquote class="text">
5748 <p>
5749 </p>
5750 </blockquote><p>
5751
5752 </p>
5753 <a name="anchor12"></a><br /><hr />
5754 <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>
5755 <a name="rfc.section.6.5"></a><h3>6.5.&nbsp;
5756 Controlling connection</h3>
5757
5758 <p>The following commands are used to control the connection to LinuxSampler.
5759 </p>
5760 <a name="SUBSCRIBE"></a><br /><hr />
5761 <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>
5762 <a name="rfc.section.6.5.1"></a><h3>6.5.1.&nbsp;
5763 Register front-end for receiving event messages</h3>
5764
5765 <p>The front-end can register itself to the LinuxSampler application to
5766 be informed about noteworthy events by sending this command:
5767 </p>
5768 <p>
5769 </p>
5770 <blockquote class="text">
5771 <p>SUBSCRIBE &lt;event-id&gt;
5772 </p>
5773 </blockquote><p>
5774
5775 </p>
5776 <p>where &lt;event-id&gt; will be replaced by the respective event that
5777 client wants to subscribe to.
5778 </p>
5779 <p>Possible Answers:
5780 </p>
5781 <p>
5782 </p>
5783 <blockquote class="text">
5784 <p>"OK" -
5785 </p>
5786 <blockquote class="text">
5787 <p>on success
5788 </p>
5789 </blockquote>
5790
5791
5792 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5793 </p>
5794 <blockquote class="text">
5795 <p>if registration succeeded, but there are noteworthy
5796 issue(s) related, providing an appropriate warning code and
5797 warning message
5798 </p>
5799 </blockquote>
5800
5801
5802 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5803 </p>
5804 <blockquote class="text">
5805 <p>in case it failed, providing an appropriate error code and
5806 error message
5807 </p>
5808 </blockquote>
5809
5810
5811 </blockquote><p>
5812
5813 </p>
5814 <p>Examples:
5815 </p>
5816 <p>
5817 </p>
5818 <blockquote class="text">
5819 <p>
5820 </p>
5821 </blockquote><p>
5822
5823 </p>
5824 <a name="UNSUBSCRIBE"></a><br /><hr />
5825 <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>
5826 <a name="rfc.section.6.5.2"></a><h3>6.5.2.&nbsp;
5827 Unregister front-end for not receiving event messages</h3>
5828
5829 <p>The front-end can unregister itself if it doesn't want to receive event
5830 messages anymore by sending the following command:
5831 </p>
5832 <p>
5833 </p>
5834 <blockquote class="text">
5835 <p>UNSUBSCRIBE &lt;event-id&gt;
5836 </p>
5837 </blockquote><p>
5838
5839 </p>
5840 <p>Where &lt;event-id&gt; will be replaced by the respective event that
5841 client doesn't want to receive anymore.
5842 </p>
5843 <p>Possible Answers:
5844 </p>
5845 <p>
5846 </p>
5847 <blockquote class="text">
5848 <p>"OK" -
5849 </p>
5850 <blockquote class="text">
5851 <p>on success
5852 </p>
5853 </blockquote>
5854
5855
5856 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5857 </p>
5858 <blockquote class="text">
5859 <p>if unregistration succeeded, but there are noteworthy
5860 issue(s) related, providing an appropriate warning code and
5861 warning message
5862 </p>
5863 </blockquote>
5864
5865
5866 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5867 </p>
5868 <blockquote class="text">
5869 <p>in case it failed, providing an appropriate error code and
5870 error message
5871 </p>
5872 </blockquote>
5873
5874
5875 </blockquote><p>
5876
5877 </p>
5878 <p>Examples:
5879 </p>
5880 <p>
5881 </p>
5882 <blockquote class="text">
5883 <p>
5884 </p>
5885 </blockquote><p>
5886
5887 </p>
5888 <a name="SET ECHO"></a><br /><hr />
5889 <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>
5890 <a name="rfc.section.6.5.3"></a><h3>6.5.3.&nbsp;
5891 Enable or disable echo of commands</h3>
5892
5893 <p>To enable or disable back sending of commands to the client the following command can be used:
5894 </p>
5895 <p>
5896 </p>
5897 <blockquote class="text">
5898 <p>SET ECHO &lt;value&gt;
5899 </p>
5900 </blockquote><p>
5901
5902 </p>
5903 <p>Where &lt;value&gt; should be replaced either by "1" to enable echo mode
5904 or "0" to disable echo mode. When echo mode is enabled, all
5905 commands send to LinuxSampler will be immediately send back and
5906 after this echo the actual response to the command will be
5907 returned. Echo mode will only be altered for the client connection
5908 that issued the "SET ECHO" command, not globally for all client
5909 connections.
5910 </p>
5911 <p>Possible Answers:
5912 </p>
5913 <p>
5914 </p>
5915 <blockquote class="text">
5916 <p>"OK" -
5917 </p>
5918 <blockquote class="text">
5919 <p>usually
5920 </p>
5921 </blockquote>
5922
5923
5924 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5925 </p>
5926 <blockquote class="text">
5927 <p>on syntax error, e.g. non boolean value
5928 </p>
5929 </blockquote>
5930
5931
5932 </blockquote><p>
5933
5934 </p>
5935 <p>Examples:
5936 </p>
5937 <p>
5938 </p>
5939 <blockquote class="text">
5940 <p>
5941 </p>
5942 </blockquote><p>
5943
5944 </p>
5945 <a name="QUIT"></a><br /><hr />
5946 <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>
5947 <a name="rfc.section.6.5.4"></a><h3>6.5.4.&nbsp;
5948 Close client connection</h3>
5949
5950 <p>The client can close its network connection to LinuxSampler by sending the following command:
5951 </p>
5952 <p>
5953 </p>
5954 <blockquote class="text">
5955 <p>QUIT
5956 </p>
5957 </blockquote><p>
5958
5959 </p>
5960 <p>This is probably more interesting for manual telnet connections to
5961 LinuxSampler than really useful for a front-end implementation.
5962 </p>
5963 <a name="anchor13"></a><br /><hr />
5964 <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>
5965 <a name="rfc.section.6.6"></a><h3>6.6.&nbsp;
5966 Global commands</h3>
5967
5968 <p>The following commands have global impact on the sampler.
5969 </p>
5970 <a name="GET TOTAL_VOICE_COUNT"></a><br /><hr />
5971 <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>
5972 <a name="rfc.section.6.6.1"></a><h3>6.6.1.&nbsp;
5973 Current number of active voices</h3>
5974
5975 <p>The front-end can ask for the current number of active voices on
5976 the sampler by sending the following command:
5977 </p>
5978 <p>
5979 </p>
5980 <blockquote class="text">
5981 <p>GET TOTAL_VOICE_COUNT
5982 </p>
5983 </blockquote><p>
5984
5985 </p>
5986 <p>Possible Answers:
5987 </p>
5988 <p>
5989 </p>
5990 <blockquote class="text">
5991 <p>LinuxSampler will answer by returning the number of all active
5992 voices on the sampler.
5993 </p>
5994 </blockquote><p>
5995
5996 </p>
5997 <a name="GET TOTAL_VOICE_COUNT_MAX"></a><br /><hr />
5998 <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>
5999 <a name="rfc.section.6.6.2"></a><h3>6.6.2.&nbsp;
6000 Maximum amount of active voices</h3>
6001
6002 <p>The front-end can ask for the maximum number of active voices
6003 by sending the following command:
6004 </p>
6005 <p>
6006 </p>
6007 <blockquote class="text">
6008 <p>GET TOTAL_VOICE_COUNT_MAX
6009 </p>
6010 </blockquote><p>
6011
6012 </p>
6013 <p>Possible Answers:
6014 </p>
6015 <p>
6016 </p>
6017 <blockquote class="text">
6018 <p>LinuxSampler will answer by returning the maximum number
6019 of active voices.
6020 </p>
6021 </blockquote><p>
6022
6023 </p>
6024 <a name="RESET"></a><br /><hr />
6025 <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>
6026 <a name="rfc.section.6.6.3"></a><h3>6.6.3.&nbsp;
6027 Reset sampler</h3>
6028
6029 <p>The front-end can reset the whole sampler by sending the following command:
6030 </p>
6031 <p>
6032 </p>
6033 <blockquote class="text">
6034 <p>RESET
6035 </p>
6036 </blockquote><p>
6037
6038 </p>
6039 <p>Possible Answers:
6040 </p>
6041 <p>
6042 </p>
6043 <blockquote class="text">
6044 <p>"OK" -
6045 </p>
6046 <blockquote class="text">
6047 <p>always
6048 </p>
6049 </blockquote>
6050
6051
6052 </blockquote><p>
6053
6054 </p>
6055 <p>Examples:
6056 </p>
6057 <p>
6058 </p>
6059 <blockquote class="text">
6060 <p>
6061 </p>
6062 </blockquote><p>
6063
6064 </p>
6065 <a name="GET SERVER INFO"></a><br /><hr />
6066 <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>
6067 <a name="rfc.section.6.6.4"></a><h3>6.6.4.&nbsp;
6068 General sampler informations</h3>
6069
6070 <p>The client can ask for general informations about the LinuxSampler
6071 instance by sending the following command:
6072 </p>
6073 <p>
6074 </p>
6075 <blockquote class="text">
6076 <p>GET SERVER INFO
6077 </p>
6078 </blockquote><p>
6079
6080 </p>
6081 <p>Possible Answers:
6082 </p>
6083 <p>
6084 </p>
6085 <blockquote class="text">
6086 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6087 Each answer line begins with the information category name
6088 followed by a colon and then a space character &lt;SP&gt; and finally
6089 the info character string to that information category. At the
6090 moment the following categories are defined:
6091
6092 </p>
6093 <p>
6094 </p>
6095 <blockquote class="text">
6096 <p>DESCRIPTION -
6097 </p>
6098 <blockquote class="text">
6099 <p>arbitrary textual description about the sampler
6100 </p>
6101 </blockquote>
6102
6103
6104 <p>VERSION -
6105 </p>
6106 <blockquote class="text">
6107 <p>version of the sampler
6108 </p>
6109 </blockquote>
6110
6111
6112 <p>PROTOCOL_VERSION -
6113 </p>
6114 <blockquote class="text">
6115 <p>version of the LSCP specification the sampler
6116 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)
6117 </p>
6118 </blockquote>
6119
6120
6121 <p>INSTRUMENTS_DB_SUPPORT -
6122 </p>
6123 <blockquote class="text">
6124 <p>either yes or no, specifies whether the
6125 sampler is build with instruments database support.
6126 </p>
6127 </blockquote>
6128
6129
6130 </blockquote>
6131
6132
6133 </blockquote><p>
6134
6135 </p>
6136 <p>The mentioned fields above don't have to be in particular order.
6137 Other fields might be added in future.
6138 </p>
6139 <a name="GET VOLUME"></a><br /><hr />
6140 <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>
6141 <a name="rfc.section.6.6.5"></a><h3>6.6.5.&nbsp;
6142 Getting global volume attenuation</h3>
6143
6144 <p>The client can ask for the current global sampler-wide volume
6145 attenuation by sending the following command:
6146 </p>
6147 <p>
6148 </p>
6149 <blockquote class="text">
6150 <p>GET VOLUME
6151 </p>
6152 </blockquote><p>
6153
6154 </p>
6155 <p>Possible Answers:
6156 </p>
6157 <p>
6158 </p>
6159 <blockquote class="text">
6160 <p>The sampler will always answer by returning the optional
6161 dotted floating point coefficient, reflecting the current
6162 global volume attenuation.
6163
6164 </p>
6165 </blockquote><p>
6166
6167 </p>
6168 <p>Note: it is up to the respective sampler engine whether to obey
6169 that global volume parameter or not, but in general all engines SHOULD
6170 use this parameter.
6171 </p>
6172 <a name="SET VOLUME"></a><br /><hr />
6173 <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>
6174 <a name="rfc.section.6.6.6"></a><h3>6.6.6.&nbsp;
6175 Setting global volume attenuation</h3>
6176
6177 <p>The client can alter the current global sampler-wide volume
6178 attenuation by sending the following command:
6179 </p>
6180 <p>
6181 </p>
6182 <blockquote class="text">
6183 <p>SET VOLUME &lt;volume&gt;
6184 </p>
6185 </blockquote><p>
6186
6187 </p>
6188 <p>Where &lt;volume&gt; should be replaced by the optional dotted
6189 floating point value, reflecting the new global volume parameter.
6190 This value might usually be in the range between 0.0 and 1.0, that
6191 is for attenuating the overall volume.
6192 </p>
6193 <p>Possible Answers:
6194 </p>
6195 <p>
6196 </p>
6197 <blockquote class="text">
6198 <p>"OK" -
6199 </p>
6200 <blockquote class="text">
6201 <p>on success
6202 </p>
6203 </blockquote>
6204
6205
6206 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6207 </p>
6208 <blockquote class="text">
6209 <p>if the global volume was set, but there are noteworthy
6210 issue(s) related, providing an appropriate warning code and
6211 warning message
6212 </p>
6213 </blockquote>
6214
6215
6216 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6217 </p>
6218 <blockquote class="text">
6219 <p>in case it failed, providing an appropriate error code and error message
6220 </p>
6221 </blockquote>
6222
6223
6224 </blockquote><p>
6225
6226 </p>
6227 <a name="MIDI Instrument Mapping"></a><br /><hr />
6228 <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>
6229 <a name="rfc.section.6.7"></a><h3>6.7.&nbsp;
6230 MIDI Instrument Mapping</h3>
6231
6232 <p>The MIDI protocol provides a way to switch between instruments
6233 by sending so called MIDI bank select and MIDI program change
6234 messages which are essentially just numbers. The following commands
6235 allow to actually map arbitrary MIDI bank select / program change
6236 numbers with real instruments.
6237 </p>
6238 <p>The sampler allows to manage an arbitrary amount of MIDI
6239 instrument maps which define which instrument to load on
6240 which MIDI program change message.
6241 </p>
6242 <p>By default, that is when the sampler is launched, there is no
6243 map, thus the sampler will simply ignore all program change
6244 messages. The front-end has to explicitly create at least one
6245 map, add entries to the map and tell the respective sampler
6246 channel(s) which MIDI instrument map to use, so the sampler
6247 knows how to react on a given program change message on the
6248 respective sampler channel, that is by switching to the
6249 respectively defined engine type and loading the respective
6250 instrument. See command
6251 <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>
6252 for how to assign a MIDI instrument map to a sampler channel.
6253 </p>
6254 <p>Also note per MIDI specification a bank select message does not
6255 cause to switch to another instrument. Instead when receiving a
6256 bank select message the bank value will be stored and a subsequent
6257 program change message (which may occur at any time) will finally
6258 cause the sampler to switch to the respective instrument as
6259 reflected by the current MIDI instrument map.
6260 </p>
6261 <a name="ADD MIDI_INSTRUMENT MAP"></a><br /><hr />
6262 <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>
6263 <a name="rfc.section.6.7.1"></a><h3>6.7.1.&nbsp;
6264 Create a new MIDI instrument map</h3>
6265
6266 <p>The front-end can add a new MIDI instrument map by sending
6267 the following command:
6268 </p>
6269 <p>
6270 </p>
6271 <blockquote class="text">
6272 <p>ADD MIDI_INSTRUMENT_MAP [&lt;name&gt;]
6273 </p>
6274 </blockquote><p>
6275
6276 </p>
6277 <p>Where &lt;name&gt; is an optional argument allowing to
6278 assign a custom name to the new map. MIDI instrument Map
6279 names do not have to be unique.
6280 </p>
6281 <p>Possible Answers:
6282 </p>
6283 <p>
6284 </p>
6285 <blockquote class="text">
6286 <p>"OK[&lt;map&gt;]" -
6287 </p>
6288 <blockquote class="text">
6289 <p>in case a new MIDI instrument map could
6290 be added, where &lt;map&gt; reflects the
6291 unique ID of the newly created MIDI
6292 instrument map
6293 </p>
6294 </blockquote>
6295
6296
6297 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6298 </p>
6299 <blockquote class="text">
6300 <p>when a new map could not be created, which
6301 might never occur in practice
6302 </p>
6303 </blockquote>
6304
6305
6306 </blockquote><p>
6307
6308 </p>
6309 <p>Examples:
6310 </p>
6311 <p>
6312 </p>
6313 <blockquote class="text">
6314 <p>C: "ADD MIDI_INSTRUMENT_MAP 'Standard Map'"
6315 </p>
6316 <p>S: "OK[0]"
6317 </p>
6318 </blockquote><p>
6319
6320 </p>
6321 <p>
6322 </p>
6323 <blockquote class="text">
6324 <p>C: "ADD MIDI_INSTRUMENT_MAP 'Standard Drumkit'"
6325 </p>
6326 <p>S: "OK[1]"
6327 </p>
6328 </blockquote><p>
6329
6330 </p>
6331 <p>
6332 </p>
6333 <blockquote class="text">
6334 <p>C: "ADD MIDI_INSTRUMENT_MAP"
6335 </p>
6336 <p>S: "OK[5]"
6337 </p>
6338 </blockquote><p>
6339
6340 </p>
6341 <a name="REMOVE MIDI_INSTRUMENT_MAP"></a><br /><hr />
6342 <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>
6343 <a name="rfc.section.6.7.2"></a><h3>6.7.2.&nbsp;
6344 Delete one particular or all MIDI instrument maps</h3>
6345
6346 <p>The front-end can delete a particular MIDI instrument map
6347 by sending the following command:
6348 </p>
6349 <p>
6350 </p>
6351 <blockquote class="text">
6352 <p>REMOVE MIDI_INSTRUMENT_MAP &lt;map&gt;
6353 </p>
6354 </blockquote><p>
6355
6356 </p>
6357 <p>Where &lt;map&gt; reflects the unique ID of the map to delete
6358 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>
6359 command.
6360 </p>
6361 <p>The front-end can delete all MIDI instrument maps by
6362 sending the following command:
6363 </p>
6364 <p>
6365 </p>
6366 <blockquote class="text">
6367 <p>REMOVE MIDI_INSTRUMENT_MAP ALL
6368 </p>
6369 </blockquote><p>
6370
6371 </p>
6372 <p>Possible Answers:
6373 </p>
6374 <p>
6375 </p>
6376 <blockquote class="text">
6377 <p>"OK" -
6378 </p>
6379 <blockquote class="text">
6380 <p>in case the map(s) could be deleted
6381 </p>
6382 </blockquote>
6383
6384
6385 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6386 </p>
6387 <blockquote class="text">
6388 <p>when the given map does not exist
6389 </p>
6390 </blockquote>
6391
6392
6393 </blockquote><p>
6394
6395 </p>
6396 <p>Examples:
6397 </p>
6398 <p>
6399 </p>
6400 <blockquote class="text">
6401 <p>C: "REMOVE MIDI_INSTRUMENT_MAP 0"
6402 </p>
6403 <p>S: "OK"
6404 </p>
6405 </blockquote><p>
6406
6407 </p>
6408 <p>
6409 </p>
6410 <blockquote class="text">
6411 <p>C: "REMOVE MIDI_INSTRUMENT_MAP ALL"
6412 </p>
6413 <p>S: "OK"
6414 </p>
6415 </blockquote><p>
6416
6417 </p>
6418 <a name="GET MIDI_INSTRUMENT_MAPS"></a><br /><hr />
6419 <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>
6420 <a name="rfc.section.6.7.3"></a><h3>6.7.3.&nbsp;
6421 Get amount of existing MIDI instrument maps</h3>
6422
6423 <p>The front-end can retrieve the current amount of MIDI
6424 instrument maps by sending the following command:
6425 </p>
6426 <p>
6427 </p>
6428 <blockquote class="text">
6429 <p>GET MIDI_INSTRUMENT_MAPS
6430 </p>
6431 </blockquote><p>
6432
6433 </p>
6434 <p>Possible Answers:
6435 </p>
6436 <p>
6437 </p>
6438 <blockquote class="text">
6439 <p>The sampler will answer by returning the current
6440 number of MIDI instrument maps.
6441 </p>
6442 </blockquote><p>
6443
6444 </p>
6445 <p>Example:
6446 </p>
6447 <p>
6448 </p>
6449 <blockquote class="text">
6450 <p>C: "GET MIDI_INSTRUMENT_MAPS"
6451 </p>
6452 <p>S: "2"
6453 </p>
6454 </blockquote><p>
6455
6456 </p>
6457 <a name="LIST MIDI_INSTRUMENT_MAPS"></a><br /><hr />
6458 <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>
6459 <a name="rfc.section.6.7.4"></a><h3>6.7.4.&nbsp;
6460 Getting all created MIDI instrument maps</h3>
6461
6462 <p>The number of MIDI instrument maps can change on runtime. To get the
6463 current list of MIDI instrument maps, the front-end can send the
6464 following command:
6465 </p>
6466 <p>
6467 </p>
6468 <blockquote class="text">
6469 <p>LIST MIDI_INSTRUMENT_MAPS
6470 </p>
6471 </blockquote><p>
6472
6473 </p>
6474 <p>Possible Answers:
6475 </p>
6476 <p>
6477 </p>
6478 <blockquote class="text">
6479 <p>The sampler will answer by returning a comma separated list
6480 with all MIDI instrument maps' numerical IDs.
6481 </p>
6482 </blockquote><p>
6483
6484 </p>
6485 <p>Example:
6486 </p>
6487 <p>
6488 </p>
6489 <blockquote class="text">
6490 <p>C: "LIST MIDI_INSTRUMENT_MAPS"
6491 </p>
6492 <p>S: "0,1,5,12"
6493 </p>
6494 </blockquote><p>
6495
6496 </p>
6497 <a name="GET MIDI_INSTRUMENT_MAP INFO"></a><br /><hr />
6498 <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>
6499 <a name="rfc.section.6.7.5"></a><h3>6.7.5.&nbsp;
6500 Getting MIDI instrument map information</h3>
6501
6502 <p>The front-end can ask for the current settings of a MIDI
6503 instrument map by sending the following command:
6504 </p>
6505 <p>
6506 </p>
6507 <blockquote class="text">
6508 <p>GET MIDI_INSTRUMENT_MAP INFO &lt;map&gt;
6509 </p>
6510 </blockquote><p>
6511
6512 </p>
6513 <p>Where &lt;map&gt; is the numerical ID of the map the
6514 front-end is interested in as returned by the
6515 <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>
6516 command.
6517 </p>
6518 <p>Possible Answers:
6519 </p>
6520 <p>
6521 </p>
6522 <blockquote class="text">
6523 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6524 Each answer line begins with the settings category name
6525 followed by a colon and then a space character &lt;SP&gt; and finally
6526 the info character string to that setting category. At the
6527 moment the following categories are defined:
6528 </p>
6529 <p>
6530 </p>
6531 <blockquote class="text">
6532 <p>NAME -
6533 </p>
6534 <blockquote class="text">
6535 <p>custom name of the given map,
6536 which does not have to be unique
6537 </p>
6538 </blockquote>
6539
6540
6541 <p>DEFAULT -
6542 </p>
6543 <blockquote class="text">
6544 <p>either true or false,
6545 defines whether this map is the default map
6546 </p>
6547 </blockquote>
6548
6549
6550 </blockquote>
6551
6552
6553 </blockquote><p>
6554
6555 </p>
6556 <p>The mentioned fields above don't have to be in particular order.
6557 </p>
6558 <p>Example:
6559 </p>
6560 <p>
6561 </p>
6562 <blockquote class="text">
6563 <p>C: "GET MIDI_INSTRUMENT_MAP INFO 0"
6564 </p>
6565 <p>S: "NAME: Standard Map"
6566 </p>
6567 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: true"
6568 </p>
6569 <p>&nbsp;&nbsp;&nbsp;"."
6570 </p>
6571 </blockquote><p>
6572
6573 </p>
6574 <a name="SET MIDI_INSTRUMENT_MAP NAME"></a><br /><hr />
6575 <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>
6576 <a name="rfc.section.6.7.6"></a><h3>6.7.6.&nbsp;
6577 Renaming a MIDI instrument map</h3>
6578
6579 <p>The front-end can alter the custom name of a MIDI
6580 instrument map by sending the following command:
6581 </p>
6582 <p>
6583 </p>
6584 <blockquote class="text">
6585 <p>SET MIDI_INSTRUMENT_MAP NAME &lt;map&gt; &lt;name&gt;
6586 </p>
6587 </blockquote><p>
6588
6589 </p>
6590 <p>Where &lt;map&gt; is the numerical ID of the map and
6591 &lt;name&gt; the new custom name of the map, which does not
6592 have to be unique.
6593 </p>
6594 <p>Possible Answers:
6595 </p>
6596 <p>
6597 </p>
6598 <blockquote class="text">
6599 <p>"OK" -
6600 </p>
6601 <blockquote class="text">
6602 <p>on success
6603 </p>
6604 </blockquote>
6605
6606
6607 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6608 </p>
6609 <blockquote class="text">
6610 <p>in case the given map does not exist
6611 </p>
6612 </blockquote>
6613
6614
6615 </blockquote><p>
6616
6617 </p>
6618 <p>Example:
6619 </p>
6620 <p>
6621 </p>
6622 <blockquote class="text">
6623 <p>C: "SET MIDI_INSTRUMENT_MAP NAME 0 'Foo instruments'"
6624 </p>
6625 <p>S: "OK"
6626 </p>
6627 </blockquote><p>
6628
6629 </p>
6630 <a name="MAP MIDI_INSTRUMENT"></a><br /><hr />
6631 <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>
6632 <a name="rfc.section.6.7.7"></a><h3>6.7.7.&nbsp;
6633 Create or replace a MIDI instrument map entry</h3>
6634
6635 <p>The front-end can create a new or replace an existing entry
6636 in a sampler's MIDI instrument map by sending the following
6637 command:
6638 </p>
6639 <p>
6640 </p>
6641 <blockquote class="text">
6642 <p>MAP MIDI_INSTRUMENT [NON_MODAL] &lt;map&gt;
6643 &lt;midi_bank&gt; &lt;midi_prog&gt; &lt;engine_name&gt;
6644 &lt;filename&gt; &lt;instrument_index&gt; &lt;volume_value&gt;
6645 [&lt;instr_load_mode&gt;] [&lt;name&gt;]
6646 </p>
6647 </blockquote><p>
6648
6649 </p>
6650 <p>Where &lt;map&gt; is the numeric ID of the map to alter,
6651 &lt;midi_bank&gt; is an integer value between
6652 0..16383 reflecting the MIDI bank select index,
6653 &lt;midi_prog&gt; an
6654 integer value between 0..127 reflecting the MIDI program change
6655 index, &lt;engine_name&gt; a sampler engine name as returned by
6656 the <a class='info' href='#LIST AVAILABLE_ENGINES'>"LIST AVAILABLE_ENGINES"<span> (</span><span class='info'>Getting all available engines</span><span>)</span></a>
6657 command (not encapsulated into apostrophes), &lt;filename&gt; the name
6658 of the instrument's file to be deployed (encapsulated into apostrophes,
6659 supporting escape sequences as described in chapter
6660 "<a class='info' href='#character_set'>Character Set and Escape Sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>"),
6661 &lt;instrument_index&gt; the index (integer value) of the instrument
6662 within the given file, &lt;volume_value&gt; reflects the master
6663 volume of the instrument as optionally dotted number (where a
6664 value &lt; 1.0 means attenuation and a value > 1.0 means
6665 amplification). This parameter easily allows to adjust the
6666 volume of all intruments within a custom instrument map
6667 without having to adjust their instrument files. The
6668 OPTIONAL &lt;instr_load_mode&gt; argument defines the life
6669 time of the instrument, that is when the instrument should
6670 be loaded, when freed and has exactly the following
6671 possibilities:
6672 </p>
6673 <p>
6674 </p>
6675 <blockquote class="text">
6676 <p>"ON_DEMAND" -
6677 </p>
6678 <blockquote class="text">
6679 <p>The instrument will be loaded when needed,
6680 that is when demanded by at least one sampler
6681 channel. It will immediately be freed from memory
6682 when not needed by any sampler channel anymore.
6683 </p>
6684 </blockquote>
6685
6686
6687 <p>"ON_DEMAND_HOLD" -
6688 </p>
6689 <blockquote class="text">
6690 <p>The instrument will be loaded when needed,
6691 that is when demanded by at least one sampler
6692 channel. It will be kept in memory even when
6693 not needed by any sampler channel anymore.
6694 Instruments with this mode are only freed
6695 when the sampler is reset or all mapping
6696 entries with this mode (and respective
6697 instrument) are explicitly changed to
6698 "ON_DEMAND" and no sampler channel is using
6699 the instrument anymore.
6700 </p>
6701 </blockquote>
6702
6703
6704 <p>"PERSISTENT" -
6705 </p>
6706 <blockquote class="text">
6707 <p>The instrument will immediately be loaded
6708 into memory when this mapping
6709 command is sent and the instrument is kept all
6710 the time. Instruments with this mode are
6711 only freed when the sampler is reset or all
6712 mapping entries with this mode (and
6713 respective instrument) are explicitly
6714 changed to "ON_DEMAND" and no sampler
6715 channel is using the instrument anymore.
6716 </p>
6717 </blockquote>
6718
6719
6720 <p>not supplied -
6721 </p>
6722 <blockquote class="text">
6723 <p>In case there is no &lt;instr_load_mode&gt;
6724 argument given, it will be up to the
6725 InstrumentManager to decide which mode to use.
6726 Usually it will use "ON_DEMAND" if an entry
6727 for the given instrument does not exist in
6728 the InstrumentManager's list yet, otherwise
6729 if an entry already exists, it will simply
6730 stick with the mode currently reflected by
6731 the already existing entry, that is it will
6732 not change the mode.
6733 </p>
6734 </blockquote>
6735
6736
6737 </blockquote><p>
6738
6739 </p>
6740 <p>
6741 The &lt;instr_load_mode&gt; argument thus allows to define an
6742 appropriate strategy (low memory consumption vs. fast
6743 instrument switching) for each instrument individually. Note, the
6744 following restrictions apply to this argument: "ON_DEMAND_HOLD" and
6745 "PERSISTENT" have to be supported by the respective sampler engine
6746 (which is technically the case when the engine provides an
6747 InstrumentManager for its format). If this is not the case the
6748 argument will automatically fall back to the default value
6749 "ON_DEMAND". Also the load mode of one instrument may
6750 automatically change the laod mode of other instrument(s), i.e.
6751 because the instruments are part of the same file and the
6752 engine does not allow a way to manage load modes for them
6753 individually. Due to this, in case the frontend shows the
6754 load modes of entries, the frontend should retrieve the actual
6755 mode by i.e. sending
6756 <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>
6757 command(s). Finally the OPTIONAL &lt;name&gt; argument allows to
6758 set a custom name (encapsulated into apostrophes) for the mapping
6759 entry, useful for frontends for displaying an appropriate name for
6760 mapped instruments (using
6761 <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>).
6762
6763 </p>
6764 <p>
6765 By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is
6766 completely established in the sampler. The OPTIONAL "NON_MODAL" argument
6767 however causes the respective "MAP MIDI_INSTRUMENT" command to return
6768 immediately, that is to let the sampler establish the mapping in the
6769 background. So this argument might be especially useful for mappings with
6770 a "PERSISTENT" type, because these have to load the respective instruments
6771 immediately and might thus block for a very long time. It is recommended
6772 however to use the OPTIONAL "NON_MODAL" argument only if really necessary,
6773 because it has the following drawbacks: as "NON_MODAL" instructions return
6774 immediately, they may not necessarily return an error i.e. when the given
6775 instrument file turns out to be corrupt, beside that subsequent commands
6776 in a LSCP instruction sequence might fail, because mandatory mappings are
6777 not yet completed.
6778
6779 </p>
6780 <p>Possible Answers:
6781 </p>
6782 <p>
6783 </p>
6784 <blockquote class="text">
6785 <p>"OK" -
6786 </p>
6787 <blockquote class="text">
6788 <p>usually
6789 </p>
6790 </blockquote>
6791
6792
6793 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6794 </p>
6795 <blockquote class="text">
6796 <p>when the given map or engine does not exist or a value
6797 is out of range
6798 </p>
6799 </blockquote>
6800
6801
6802 </blockquote><p>
6803
6804 </p>
6805 <p>Examples:
6806 </p>
6807 <p>
6808 </p>
6809 <blockquote class="text">
6810 <p>C: "MAP MIDI_INSTRUMENT 0 3 0 gig '/usr/share/Steinway D.gig' 0 0.8 PERSISTENT"
6811 </p>
6812 <p>S: "OK"
6813 </p>
6814 </blockquote><p>
6815
6816 </p>
6817 <p>
6818 </p>
6819 <blockquote class="text">
6820 <p>C: "MAP MIDI_INSTRUMENT 0 4 50 gig '/home/john/foostrings.gig' 7 1.0"
6821 </p>
6822 <p>S: "OK"
6823 </p>
6824 </blockquote><p>
6825
6826 </p>
6827 <p>
6828 </p>
6829 <blockquote class="text">
6830 <p>C: "MAP MIDI_INSTRUMENT 0 0 0 gig '/usr/share/piano.gig' 0 1.0 'Normal Piano'"
6831 </p>
6832 <p>S: "OK"
6833 </p>
6834 <p>C: "MAP MIDI_INSTRUMENT 0 1 0 gig '/usr/share/piano.gig' 0 0.25 'Silent Piano'"
6835 </p>
6836 <p>S: "OK"
6837 </p>
6838 </blockquote><p>
6839
6840 </p>
6841 <p>
6842 </p>
6843 <blockquote class="text">
6844 <p>C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"
6845 </p>
6846 <p>S: "OK"
6847 </p>
6848 </blockquote><p>
6849
6850 </p>
6851 <a name="GET MIDI_INSTRUMENTS"></a><br /><hr />
6852 <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>
6853 <a name="rfc.section.6.7.8"></a><h3>6.7.8.&nbsp;
6854 Getting ammount of MIDI instrument map entries</h3>
6855
6856 <p>The front-end can query the amount of currently existing
6857 entries in a MIDI instrument map by sending the following
6858 command:
6859 </p>
6860 <p>
6861 </p>
6862 <blockquote class="text">
6863 <p>GET MIDI_INSTRUMENTS &lt;map&gt;
6864 </p>
6865 </blockquote><p>
6866
6867 </p>
6868 <p>The front-end can query the amount of currently existing
6869 entries in all MIDI instrument maps by sending the following
6870 command:
6871 </p>
6872 <p>
6873 </p>
6874 <blockquote class="text">
6875 <p>GET MIDI_INSTRUMENTS ALL
6876 </p>
6877 </blockquote><p>
6878
6879 </p>
6880 <p>Possible Answers:
6881 </p>
6882 <p>
6883 </p>
6884 <blockquote class="text">
6885 <p>The sampler will answer by sending the current number of
6886 entries in the MIDI instrument map(s).
6887 </p>
6888 </blockquote><p>
6889
6890 </p>
6891 <p>Example:
6892 </p>
6893 <p>
6894 </p>
6895 <blockquote class="text">
6896 <p>C: "GET MIDI_INSTRUMENTS 0"
6897 </p>
6898 <p>S: "234"
6899 </p>
6900 </blockquote><p>
6901
6902 </p>
6903 <p>
6904 </p>
6905 <blockquote class="text">
6906 <p>C: "GET MIDI_INSTRUMENTS ALL"
6907 </p>
6908 <p>S: "954"
6909 </p>
6910 </blockquote><p>
6911
6912 </p>
6913 <a name="LIST MIDI_INSTRUMENTS"></a><br /><hr />
6914 <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>
6915 <a name="rfc.section.6.7.9"></a><h3>6.7.9.&nbsp;
6916 Getting indeces of all entries of a MIDI instrument map</h3>
6917
6918 <p>The front-end can query a list of all currently existing
6919 entries in a certain MIDI instrument map by sending the following
6920 command:
6921 </p>
6922 <p>
6923 </p>
6924 <blockquote class="text">
6925 <p>LIST MIDI_INSTRUMENTS &lt;map&gt;
6926 </p>
6927 </blockquote><p>
6928
6929 </p>
6930 <p>Where &lt;map&gt; is the numeric ID of the MIDI instrument map.
6931 </p>
6932 <p>The front-end can query a list of all currently existing
6933 entries of all MIDI instrument maps by sending the following
6934 command:
6935 </p>
6936 <p>
6937 </p>
6938 <blockquote class="text">
6939 <p>LIST MIDI_INSTRUMENTS ALL
6940 </p>
6941 </blockquote><p>
6942
6943 </p>
6944 <p>Possible Answers:
6945 </p>
6946 <p>
6947 </p>
6948 <blockquote class="text">
6949 <p>The sampler will answer by sending a comma separated
6950 list of map ID - MIDI bank - MIDI program triples, where
6951 each triple is encapsulated into curly braces. The
6952 list is returned in one single line. Each triple
6953 just reflects the key of the respective map entry,
6954 thus subsequent
6955 <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>
6956 command(s) are necessary to retrieve detailed informations
6957 about each entry.
6958 </p>
6959 </blockquote><p>
6960
6961 </p>
6962 <p>Example:
6963 </p>
6964 <p>
6965 </p>
6966 <blockquote class="text">
6967 <p>C: "LIST MIDI_INSTRUMENTS 0"
6968 </p>
6969 <p>S: "{0,0,0},{0,0,1},{0,0,3},{0,1,4},{1,127,127}"
6970 </p>
6971 </blockquote><p>
6972
6973 </p>
6974 <a name="UNMAP MIDI_INSTRUMENT"></a><br /><hr />
6975 <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>
6976 <a name="rfc.section.6.7.10"></a><h3>6.7.10.&nbsp;
6977 Remove an entry from the MIDI instrument map</h3>
6978
6979 <p>The front-end can delete an entry from a MIDI instrument
6980 map by sending the following command:
6981 </p>
6982 <p>
6983 </p>
6984 <blockquote class="text">
6985 <p>UNMAP MIDI_INSTRUMENT &lt;map&gt; &lt;midi_bank&gt; &lt;midi_prog&gt;
6986 </p>
6987 </blockquote><p>
6988
6989 </p>
6990 <p>
6991 Where &lt;map&gt; is the numeric ID of the MIDI instrument map,
6992 &lt;midi_bank&gt; is an integer value between 0..16383
6993 reflecting the MIDI bank value and
6994 &lt;midi_prog&gt; an integer value between
6995 0..127 reflecting the MIDI program value of the map's entrie's key
6996 index triple.
6997
6998 </p>
6999 <p>Possible Answers:
7000 </p>
7001 <p>
7002 </p>
7003 <blockquote class="text">
7004 <p>"OK" -
7005 </p>
7006 <blockquote class="text">
7007 <p>usually
7008 </p>
7009 </blockquote>
7010
7011
7012 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7013 </p>
7014 <blockquote class="text">
7015 <p>when index out of bounds
7016 </p>
7017 </blockquote>
7018
7019
7020 </blockquote><p>
7021
7022 </p>
7023 <p>Example:
7024 </p>
7025 <p>
7026 </p>
7027 <blockquote class="text">
7028 <p>C: "UNMAP MIDI_INSTRUMENT 0 2 127"
7029 </p>
7030 <p>S: "OK"
7031 </p>
7032 </blockquote><p>
7033
7034 </p>
7035 <a name="GET MIDI_INSTRUMENT INFO"></a><br /><hr />
7036 <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>
7037 <a name="rfc.section.6.7.11"></a><h3>6.7.11.&nbsp;
7038 Get current settings of MIDI instrument map entry</h3>
7039
7040 <p>The front-end can retrieve the current settings of a certain
7041 instrument map entry by sending the following command:
7042 </p>
7043 <p>
7044 </p>
7045 <blockquote class="text">
7046 <p>GET MIDI_INSTRUMENT INFO &lt;map&gt; &lt;midi_bank&gt; &lt;midi_prog&gt;
7047 </p>
7048 </blockquote><p>
7049
7050 </p>
7051 <p>
7052 Where &lt;map&gt; is the numeric ID of the MIDI instrument map,
7053 &lt;midi_bank&gt; is an integer value between 0..16383
7054 reflecting the MIDI bank value, &lt;midi_bank&gt;
7055 and &lt;midi_prog&gt; an integer value between
7056 0..127 reflecting the MIDI program value of the map's entrie's key
7057 index triple.
7058
7059 </p>
7060 <p>Possible Answers:
7061 </p>
7062 <p>
7063 </p>
7064 <blockquote class="text">
7065 <p>LinuxSampler will answer by sending a &lt;CRLF&gt;
7066 separated list. Each answer line begins with the
7067 information category name followed by a colon and then
7068 a space character &lt;SP&gt; and finally the info
7069 character string to that info category. At the moment
7070 the following categories are defined:
7071 </p>
7072 <p>"NAME" -
7073 </p>
7074 <blockquote class="text">
7075 <p>Name for this MIDI instrument map entry (if defined).
7076 This name shall be used by frontends for displaying a
7077 name for this mapped instrument. It can be set and
7078 changed with the
7079 <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>
7080 command and does not have to be unique.
7081 </p>
7082 </blockquote>
7083
7084
7085 <p>"ENGINE_NAME" -
7086 </p>
7087 <blockquote class="text">
7088 <p>Name of the engine to be deployed for this
7089 instrument.
7090 </p>
7091 </blockquote>
7092
7093
7094 <p>"INSTRUMENT_FILE" -
7095 </p>
7096 <blockquote class="text">
7097 <p>File name of the instrument.
7098 </p>
7099 </blockquote>
7100
7101
7102 <p>"INSTRUMENT_NR" -
7103 </p>
7104 <blockquote class="text">
7105 <p>Index of the instrument within the file.
7106 </p>
7107 </blockquote>
7108
7109
7110 <p>"INSTRUMENT_NAME" -
7111 </p>
7112 <blockquote class="text">
7113 <p>Name of the loaded instrument as reflected by its file.
7114 In contrast to the "NAME" field, the "INSTRUMENT_NAME" field
7115 cannot be changed.
7116 </p>
7117 </blockquote>
7118
7119
7120 <p>"LOAD_MODE" -
7121 </p>
7122 <blockquote class="text">
7123 <p>Life time of instrument
7124 (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).
7125 </p>
7126 </blockquote>
7127
7128
7129 <p>"VOLUME" -
7130 </p>
7131 <blockquote class="text">
7132 <p>master volume of the instrument as optionally
7133 dotted number (where a value &lt; 1.0 means attenuation
7134 and a value > 1.0 means amplification)
7135 </p>
7136 </blockquote>
7137
7138
7139 <p>The mentioned fields above don't have to be in particular order.
7140 </p>
7141 </blockquote><p>
7142
7143 </p>
7144 <p>Example:
7145 </p>
7146 <p>
7147 </p>
7148 <blockquote class="text">
7149 <p>C: "GET MIDI_INSTRUMENT INFO 1 45 120"
7150 </p>
7151 <p>S: "NAME: Drums for Foo Song"
7152 </p>
7153 <p>&nbsp;&nbsp;&nbsp;"ENGINE_NAME: GigEngine"
7154 </p>
7155 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_FILE: /usr/share/joesdrumkit.gig"
7156 </p>
7157 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"
7158 </p>
7159 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NAME: Joe's Drumkit"
7160 </p>
7161 <p>&nbsp;&nbsp;&nbsp;"LOAD_MODE: PERSISTENT"
7162 </p>
7163 <p>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"
7164 </p>
7165 <p>&nbsp;&nbsp;&nbsp;"."
7166 </p>
7167 </blockquote><p>
7168
7169 </p>
7170 <a name="CLEAR MIDI_INSTRUMENTS"></a><br /><hr />
7171 <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>
7172 <a name="rfc.section.6.7.12"></a><h3>6.7.12.&nbsp;
7173 Clear MIDI instrument map</h3>
7174
7175 <p>The front-end can clear a whole MIDI instrument map, that
7176 is delete all its entries by sending the following command:
7177 </p>
7178 <p>
7179 </p>
7180 <blockquote class="text">
7181 <p>CLEAR MIDI_INSTRUMENTS &lt;map&gt;
7182 </p>
7183 </blockquote><p>
7184
7185 </p>
7186 <p>Where &lt;map&gt; is the numeric ID of the map to clear.
7187 </p>
7188 <p>The front-end can clear all MIDI instrument maps, that
7189 is delete all entries of all maps by sending the following
7190 command:
7191 </p>
7192 <p>
7193 </p>
7194 <blockquote class="text">
7195 <p>CLEAR MIDI_INSTRUMENTS ALL
7196 </p>
7197 </blockquote><p>
7198
7199 </p>
7200 <p>The command "CLEAR MIDI_INSTRUMENTS ALL" does not delete the
7201 maps, only their entries, thus the map's settings like
7202 custom name will be preservevd.
7203 </p>
7204 <p>Possible Answers:
7205 </p>
7206 <p>
7207 </p>
7208 <blockquote class="text">
7209 <p>"OK" -
7210 </p>
7211 <blockquote class="text">
7212 <p>always
7213 </p>
7214 </blockquote>
7215
7216
7217 </blockquote><p>
7218
7219 </p>
7220 <p>Examples:
7221 </p>
7222 <p>
7223 </p>
7224 <blockquote class="text">
7225 <p>C: "CLEAR MIDI_INSTRUMENTS 0"
7226 </p>
7227 <p>S: "OK"
7228 </p>
7229 </blockquote><p>
7230
7231 </p>
7232 <p>
7233 </p>
7234 <blockquote class="text">
7235 <p>C: "CLEAR MIDI_INSTRUMENTS ALL"
7236 </p>
7237 <p>S: "OK"
7238 </p>
7239 </blockquote><p>
7240
7241 </p>
7242 <a name="Managing Instruments Database"></a><br /><hr />
7243 <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>
7244 <a name="rfc.section.6.8"></a><h3>6.8.&nbsp;
7245 Managing Instruments Database</h3>
7246
7247 <p>The following commands describe how to use and manage
7248 the instruments database.
7249 </p>
7250 <a name="ADD DB_INSTRUMENT_DIRECTORY"></a><br /><hr />
7251 <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>
7252 <a name="rfc.section.6.8.1"></a><h3>6.8.1.&nbsp;
7253 Creating a new instrument directory</h3>
7254
7255 <p>The front-end can add a new instrument directory to the
7256 instruments database by sending the following command:
7257 </p>
7258 <p>
7259 </p>
7260 <blockquote class="text">
7261 <p>ADD DB_INSTRUMENT_DIRECTORY &lt;dir&gt;
7262 </p>
7263 </blockquote><p>
7264
7265 </p>
7266 <p>Where &lt;dir&gt; is the absolute path name of the directory
7267 to be created (encapsulated into apostrophes).
7268 </p>
7269 <p>Possible Answers:
7270 </p>
7271 <p>
7272 </p>
7273 <blockquote class="text">
7274 <p>"OK" -
7275 </p>
7276 <blockquote class="text">
7277 <p>on success
7278 </p>
7279 </blockquote>
7280
7281
7282 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7283 </p>
7284 <blockquote class="text">
7285 <p>when the directory could not be created, which
7286 can happen if the directory already exists or the
7287 name contains not allowed symbols
7288 </p>
7289 </blockquote>
7290
7291
7292 </blockquote><p>
7293
7294 </p>
7295 <p>Examples:
7296 </p>
7297 <p>
7298 </p>
7299 <blockquote class="text">
7300 <p>C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'"
7301 </p>
7302 <p>S: "OK"
7303 </p>
7304 </blockquote><p>
7305
7306 </p>
7307 <a name="REMOVE DB_INSTRUMENT_DIRECTORY"></a><br /><hr />
7308 <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>
7309 <a name="rfc.section.6.8.2"></a><h3>6.8.2.&nbsp;
7310 Deleting an instrument directory</h3>
7311
7312 <p>The front-end can delete a particular instrument directory
7313 from the instruments database by sending the following command:
7314 </p>
7315 <p>
7316 </p>
7317 <blockquote class="text">
7318 <p>REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] &lt;dir&gt;
7319 </p>
7320 </blockquote><p>
7321
7322 </p>
7323 <p>Where &lt;dir&gt; is the absolute path name of the directory
7324 to delete. The optional FORCE argument can be used to
7325 force the deletion of a non-empty directory and all its content.
7326 </p>
7327 <p>Possible Answers:
7328 </p>
7329 <p>
7330 </p>
7331 <blockquote class="text">
7332 <p>"OK" -
7333 </p>
7334 <blockquote class="text">
7335 <p>if the directory is deleted successfully
7336 </p>
7337 </blockquote>
7338
7339
7340 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7341 </p>
7342 <blockquote class="text">
7343 <p>if the given directory does not exist, or
7344 if trying to delete a non-empty directory,
7345 without using the FORCE argument.
7346 </p>
7347 </blockquote>
7348
7349
7350 </blockquote><p>
7351
7352 </p>
7353 <p>Examples:
7354 </p>
7355 <p>
7356 </p>
7357 <blockquote class="text">
7358 <p>C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'"
7359 </p>
7360 <p>S: "OK"
7361 </p>
7362 </blockquote><p>
7363
7364 </p>
7365 <a name="GET DB_INSTRUMENT_DIRECTORIES"></a><br /><hr />
7366 <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>
7367 <a name="rfc.section.6.8.3"></a><h3>6.8.3.&nbsp;
7368 Getting amount of instrument directories</h3>
7369
7370 <p>The front-end can retrieve the current amount of
7371 directories in a specific directory by sending the following command:
7372 </p>
7373 <p>
7374 </p>
7375 <blockquote class="text">
7376 <p>GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;
7377 </p>
7378 </blockquote><p>
7379
7380 </p>
7381 <p>Where &lt;dir&gt; should be replaced by the absolute path
7382 name of the directory. If RECURSIVE is specified, the number of
7383 all directories, including those located in subdirectories of the
7384 specified directory, will be returned.
7385 </p>
7386 <p>Possible Answers:
7387 </p>
7388 <p>
7389 </p>
7390 <blockquote class="text">
7391 <p>The current number of instrument directories
7392 in the specified directory.
7393 </p>
7394 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7395 </p>
7396 <blockquote class="text">
7397 <p>if the given directory does not exist.
7398 </p>
7399 </blockquote>
7400
7401
7402 </blockquote><p>
7403
7404 </p>
7405 <p>Example:
7406 </p>
7407 <p>
7408 </p>
7409 <blockquote class="text">
7410 <p>C: "GET DB_INSTRUMENT_DIRECTORIES '/'"
7411 </p>
7412 <p>S: "2"
7413 </p>
7414 </blockquote><p>
7415
7416 </p>
7417 <a name="LIST DB_INSTRUMENT_DIRECTORIES"></a><br /><hr />
7418 <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>
7419 <a name="rfc.section.6.8.4"></a><h3>6.8.4.&nbsp;
7420 Listing all directories in specific directory</h3>
7421
7422 <p>The front-end can retrieve the current list of directories
7423 in specific directory by sending the following command:
7424 </p>
7425 <p>
7426 </p>
7427 <blockquote class="text">
7428 <p>LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;
7429 </p>
7430 </blockquote><p>
7431
7432 </p>
7433 <p>Where &lt;dir&gt; should be replaced by the absolute path
7434 name of the directory. If RECURSIVE is specified, the absolute path names
7435 of all directories, including those located in subdirectories of the
7436 specified directory, will be returned.
7437 </p>
7438 <p>Possible Answers:
7439 </p>
7440 <p>
7441 </p>
7442 <blockquote class="text">
7443 <p>A comma separated list of all instrument directories
7444 (encapsulated into apostrophes) in the specified directory.
7445 </p>
7446 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7447 </p>
7448 <blockquote class="text">
7449 <p>if the given directory does not exist.
7450 </p>
7451 </blockquote>
7452
7453
7454 </blockquote><p>
7455
7456 </p>
7457 <p>Example:
7458 </p>
7459 <p>
7460 </p>
7461 <blockquote class="text">
7462 <p>C: "LIST DB_INSTRUMENT_DIRECTORIES '/'"
7463 </p>
7464 <p>S: "'Piano Collection','Percussion Collection'"
7465 </p>
7466 </blockquote><p>
7467
7468 </p>
7469 <p>
7470 </p>
7471 <blockquote class="text">
7472 <p>C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'"
7473 </p>
7474 <p>S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano Collection/Acoustic/New','/Percussion Collection'"
7475 </p>
7476 </blockquote><p>
7477
7478 </p>
7479 <a name="GET DB_INSTRUMENT_DIRECTORY INFO"></a><br /><hr />
7480 <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>
7481 <a name="rfc.section.6.8.5"></a><h3>6.8.5.&nbsp;
7482 Getting instrument directory information</h3>
7483
7484 <p>The front-end can ask for the current settings of an
7485 instrument directory by sending the following command:
7486 </p>
7487 <p>
7488 </p>
7489 <blockquote class="text">
7490 <p>GET DB_INSTRUMENT_DIRECTORY INFO &lt;dir&gt;
7491 </p>
7492 </blockquote><p>
7493
7494 </p>
7495 <p>Where &lt;dir&gt; should be replaced by the absolute path
7496 name of the directory the front-end is interested in.
7497 </p>
7498 <p>Possible Answers:
7499 </p>
7500 <p>
7501 </p>
7502 <blockquote class="text">
7503 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
7504 Each answer line begins with the settings category name
7505 followed by a colon and then a space character &lt;SP&gt; and finally
7506 the info character string to that setting category. At the
7507 moment the following categories are defined:
7508 </p>
7509 <p>
7510 </p>
7511 <blockquote class="text">
7512 <p>DESCRIPTION -
7513 </p>
7514 <blockquote class="text">
7515 <p>A brief description of the directory content
7516 </p>
7517 </blockquote>
7518
7519
7520 <p>CREATED -
7521 </p>
7522 <blockquote class="text">
7523 <p>The creation date and time of the directory,
7524 represented in "YYYY-MM-DD HH:MM:SS" format
7525 </p>
7526 </blockquote>
7527
7528
7529 <p>MODIFIED -
7530 </p>
7531 <blockquote class="text">
7532 <p>The date and time of the last modification of the
7533 directory, represented in "YYYY-MM-DD HH:MM:SS" format
7534 </p>
7535 </blockquote>
7536
7537
7538 </blockquote>
7539
7540
7541 </blockquote><p>
7542
7543 </p>
7544 <p>The mentioned fields above don't have to be in particular order.
7545 </p>
7546 <p>Example:
7547 </p>
7548 <p>
7549 </p>
7550 <blockquote class="text">
7551 <p>C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'"
7552 </p>
7553 <p>S: "DESCRIPTION: Piano collection of instruments in GigaSampler format."
7554 </p>
7555 <p>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"
7556 </p>
7557 <p>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"
7558 </p>
7559 <p>&nbsp;&nbsp;&nbsp;"."
7560 </p>
7561 </blockquote><p>
7562
7563 </p>
7564 <a name="SET DB_INSTRUMENT_DIRECTORY NAME"></a><br /><hr />
7565 <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>
7566 <a name="rfc.section.6.8.6"></a><h3>6.8.6.&nbsp;
7567 Renaming an instrument directory</h3>
7568
7569 <p>The front-end can alter the name of a specific
7570 instrument directory by sending the following command:
7571 </p>
7572 <p>
7573 </p>
7574 <blockquote class="text">
7575 <p>SET DB_INSTRUMENT_DIRECTORY NAME &lt;dir&gt; &lt;name&gt;
7576 </p>
7577 </blockquote><p>
7578
7579 </p>
7580 <p>Where &lt;dir&gt; is the absolute path name of the directory and
7581 &lt;name&gt; is the new name for that directory.
7582 </p>
7583 <p>Possible Answers:
7584 </p>
7585 <p>
7586 </p>
7587 <blockquote class="text">
7588 <p>"OK" -
7589 </p>
7590 <blockquote class="text">
7591 <p>on success
7592 </p>
7593 </blockquote>
7594
7595
7596 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7597 </p>
7598 <blockquote class="text">
7599 <p>in case the given directory does not exists,
7600 or if a directory with name equal to the new
7601 name already exists.
7602 </p>
7603 </blockquote>
7604
7605
7606 </blockquote><p>
7607
7608 </p>
7609 <p>Example:
7610 </p>
7611 <p>
7612 </p>
7613 <blockquote class="text">
7614 <p>C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic' 'Acoustic'"
7615 </p>
7616 <p>S: "OK"
7617 </p>
7618 </blockquote><p>
7619
7620 </p>
7621 <a name="MOVE DB_INSTRUMENT_DIRECTORY"></a><br /><hr />
7622 <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>
7623 <a name="rfc.section.6.8.7"></a><h3>6.8.7.&nbsp;
7624 Moving an instrument directory</h3>
7625
7626 <p>The front-end can move a specific
7627 instrument directory by sending the following command:
7628 </p>
7629 <p>
7630 </p>
7631 <blockquote class="text">
7632 <p>MOVE DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;
7633 </p>
7634 </blockquote><p>
7635
7636 </p>
7637 <p>Where &lt;dir&gt; is the absolute path name of the directory
7638 to move and &lt;dst&gt; is the location where the directory will
7639 be moved to.
7640 </p>
7641 <p>Possible Answers:
7642 </p>
7643 <p>
7644 </p>
7645 <blockquote class="text">
7646 <p>"OK" -
7647 </p>
7648 <blockquote class="text">
7649 <p>on success
7650 </p>
7651 </blockquote>
7652
7653
7654 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7655 </p>
7656 <blockquote class="text">
7657 <p>in case a given directory does not exists,
7658 or if a directory with name equal to the name
7659 of the specified directory already exists in
7660 the destination directory. Error is also thrown
7661 when trying to move a directory to a subdirectory
7662 of itself.
7663 </p>
7664 </blockquote>
7665
7666
7667 </blockquote><p>
7668
7669 </p>
7670 <p>Example:
7671 </p>
7672 <p>
7673 </p>
7674 <blockquote class="text">
7675 <p>C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/Acoustic'"
7676 </p>
7677 <p>S: "OK"
7678 </p>
7679 </blockquote><p>
7680
7681 </p>
7682 <a name="COPY DB_INSTRUMENT_DIRECTORY"></a><br /><hr />
7683 <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>
7684 <a name="rfc.section.6.8.8"></a><h3>6.8.8.&nbsp;
7685 Copying instrument directories</h3>
7686
7687 <p>The front-end can copy a specific
7688 instrument directory by sending the following command:
7689 </p>
7690 <p>
7691 </p>
7692 <blockquote class="text">
7693 <p>COPY DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;
7694 </p>
7695 </blockquote><p>
7696
7697 </p>
7698 <p>Where &lt;dir&gt; is the absolute path name of the directory
7699 to copy and &lt;dst&gt; is the location where the directory will
7700 be copied to.
7701 </p>
7702 <p>Possible Answers:
7703 </p>
7704 <p>
7705 </p>
7706 <blockquote class="text">
7707 <p>"OK" -
7708 </p>
7709 <blockquote class="text">
7710 <p>on success
7711 </p>
7712 </blockquote>
7713
7714
7715 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7716 </p>
7717 <blockquote class="text">
7718 <p>in case a given directory does not exists,
7719 or if a directory with name equal to the name
7720 of the specified directory already exists in
7721 the destination directory. Error is also thrown
7722 when trying to copy a directory to a subdirectory
7723 of itself.
7724 </p>
7725 </blockquote>
7726
7727
7728 </blockquote><p>
7729
7730 </p>
7731 <p>Example:
7732 </p>
7733 <p>
7734 </p>
7735 <blockquote class="text">
7736 <p>C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic' '/Acoustic/Pianos'"
7737 </p>
7738 <p>S: "OK"
7739 </p>
7740 </blockquote><p>
7741
7742 </p>
7743 <a name="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"></a><br /><hr />
7744 <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>
7745 <a name="rfc.section.6.8.9"></a><h3>6.8.9.&nbsp;
7746 Changing the description of directory</h3>
7747
7748 <p>The front-end can alter the description of a specific
7749 instrument directory by sending the following command:
7750 </p>
7751 <p>
7752 </p>
7753 <blockquote class="text">
7754 <p>SET DB_INSTRUMENT_DIRECTORY DESCRIPTION &lt;dir&gt; &lt;desc&gt;
7755 </p>
7756 </blockquote><p>
7757
7758 </p>
7759 <p>Where &lt;dir&gt; is the absolute path name of the directory and
7760 &lt;desc&gt; is the new description for the directory.
7761 </p>
7762 <p>Possible Answers:
7763 </p>
7764 <p>
7765 </p>
7766 <blockquote class="text">
7767 <p>"OK" -
7768 </p>
7769 <blockquote class="text">
7770 <p>on success
7771 </p>
7772 </blockquote>
7773
7774
7775 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7776 </p>
7777 <blockquote class="text">
7778 <p>in case the given directory does not exists.
7779 </p>
7780 </blockquote>
7781
7782
7783 </blockquote><p>
7784
7785 </p>
7786 <p>Example:
7787 </p>
7788 <p>
7789 </p>
7790 <blockquote class="text">
7791 <p>C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A collection of piano instruments in various format.'"
7792 </p>
7793 <p>S: "OK"
7794 </p>
7795 </blockquote><p>
7796
7797 </p>
7798 <a name="FIND DB_INSTRUMENT_DIRECTORIES"></a><br /><hr />
7799 <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>
7800 <a name="rfc.section.6.8.10"></a><h3>6.8.10.&nbsp;
7801 Finding directories</h3>
7802
7803 <p>The front-end can search for directories
7804 in specific directory by sending the following command:
7805 </p>
7806 <p>
7807 </p>
7808 <blockquote class="text">
7809 <p>FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;
7810 </p>
7811 </blockquote><p>
7812
7813 </p>
7814 <p>Where &lt;dir&gt; should be replaced by the absolute path
7815 name of the directory to search in. If NON_RECURSIVE is specified, the
7816 directories located in subdirectories of the specified directory will not
7817 be searched. &lt;criteria-list&gt; is a list of search criterias
7818 in form of "key1=val1 key2=val2 ...". The following criterias are
7819 allowed:
7820 </p>
7821 <p>
7822
7823 <p>NAME='&lt;search-string&gt;'
7824 </p>
7825 <blockquote class="text">
7826 <p>Restricts the search to directories, which names
7827 satisfy the supplied search string.
7828 </p>
7829 </blockquote><p>
7830
7831 </p>
7832
7833
7834 <p>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
7835 </p>
7836 <blockquote class="text">
7837 <p>Restricts the search to directories, which creation
7838 date satisfies the specified period, where &lt;date-after&gt;
7839 and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
7840 If &lt;date-after&gt; is omitted the search is restricted to
7841 directories created before &lt;date-before&gt;. If
7842 &lt;date-before&gt; is omitted, the search is restricted
7843 to directories created after &lt;date-after&gt;.
7844 </p>
7845 </blockquote><p>
7846
7847 </p>
7848
7849
7850 <p>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
7851 </p>
7852 <blockquote class="text">
7853 <p>Restricts the search to directories, which
7854 date of last modification satisfies the specified period, where
7855 &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
7856 format. If &lt;date-after&gt; is omitted the search is restricted to
7857 directories, which are last modified before &lt;date-before&gt;. If
7858 &lt;date-before&gt; is omitted, the search is restricted to directories,
7859 which are last modified after &lt;date-after&gt;.
7860 </p>
7861 </blockquote><p>
7862
7863 </p>
7864
7865
7866 <p>DESCRIPTION='&lt;search-string&gt;'
7867 </p>
7868 <blockquote class="text">
7869 <p>Restricts the search to directories with description
7870 that satisfies the supplied search string.
7871 </p>
7872 </blockquote><p>
7873
7874 </p>
7875
7876
7877 <p>Where &lt;search-string&gt; is either a regular expression, or a
7878 word list separated with spaces for OR search and with '+' for AND search.
7879 </p>
7880 <p>Possible Answers:
7881 </p>
7882 <p>
7883 </p>
7884 <blockquote class="text">
7885 <p>A comma separated list with the absolute path names (encapsulated into
7886 apostrophes) of all directories in the specified directory that satisfy
7887 the supplied search criterias.
7888 </p>
7889 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7890 </p>
7891 <blockquote class="text">
7892 <p>if the given directory does not exist.
7893 </p>
7894 </blockquote>
7895
7896
7897 </blockquote><p>
7898
7899 </p>
7900 <p>Example:
7901 </p>
7902 <p>
7903 </p>
7904 <blockquote class="text">
7905 <p>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'"
7906 </p>
7907 <p>S: "'/Piano Collection'"
7908 </p>
7909 </blockquote><p>
7910
7911 </p>
7912 <p>
7913 </p>
7914 <blockquote class="text">
7915 <p>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:30:13'"
7916 </p>
7917 <p>S: "'/Piano Collection','/Percussions'"
7918 </p>
7919 </blockquote><p>
7920
7921 </p>
7922 <a name="ADD DB_INSTRUMENTS"></a><br /><hr />
7923 <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>
7924 <a name="rfc.section.6.8.11"></a><h3>6.8.11.&nbsp;
7925 Adding instruments to the instruments database</h3>
7926
7927 <p>The front-end can add one or more instruments
7928 to the instruments database by sending the following command:
7929 </p>
7930 <p>
7931 </p>
7932 <blockquote class="text">
7933 <p>ADD DB_INSTRUMENTS [NON_MODAL] [&lt;mode&gt;] &lt;db_dir&gt; &lt;file_path&gt; [&lt;instr_index&gt;]
7934 </p>
7935 </blockquote><p>
7936
7937 </p>
7938 <p>Where &lt;db_dir&gt; is the absolute path name of a directory
7939 (encapsulated into apostrophes) in the instruments database in which
7940 only the new instruments (that are not already in the database) will
7941 be added, &lt;file_path&gt; is the absolute path name of a file or
7942 directory in the file system (encapsulated into apostrophes). In case
7943 an instrument file is supplied, only the instruments in the specified
7944 file will be added to the instruments database. If the optional
7945 &lt;instr_index&gt; (the index of the instrument within the given file)
7946 is supplied too, then only the specified instrument will be added.
7947 In case a directory is supplied, the instruments in that directory
7948 will be added. The OPTIONAL &lt;mode&gt; argument is only applied
7949 when a directory is provided as &lt;file_path&gt; and specifies how the
7950 scanning will be done and has exactly the following possibilities:
7951 </p>
7952 <p>
7953 </p>
7954 <blockquote class="text">
7955 <p>"RECURSIVE" -
7956 </p>
7957 <blockquote class="text">
7958 <p>All instruments will be processed, including those
7959 in the subdirectories, and the respective subdirectory
7960 tree structure will be recreated in the instruments
7961 database
7962 </p>
7963 </blockquote>
7964
7965
7966 <p>"NON_RECURSIVE" -
7967 </p>
7968 <blockquote class="text">
7969 <p>Only the instruments in the specified directory
7970 will be added, the instruments in the subdirectories
7971 will not be processed.
7972 </p>
7973 </blockquote>
7974
7975
7976 <p>"FLAT" -
7977 </p>
7978 <blockquote class="text">
7979 <p>All instruments will be processed, including those
7980 in the subdirectories, but the respective subdirectory
7981 structure will not be recreated in the instruments
7982 database. All instruments will be added directly in
7983 the specified database directory.
7984 </p>
7985 </blockquote>
7986
7987
7988 </blockquote><p>
7989
7990 </p>
7991 <p>The difference between regular and NON_MODAL versions of the command
7992 is that the regular command returns when the scanning is finished
7993 while NON_MODAL version returns immediately and a background process is launched.
7994 The <a class='info' href='#GET DB_INSTRUMENTS_JOB INFO'>GET DB_INSTRUMENTS_JOB INFO<span> (</span><span class='info'>Getting job status information</span><span>)</span></a>
7995 command can be used to monitor the scanning progress.
7996 </p>
7997 <p>Possible Answers:
7998 </p>
7999 <p>
8000 </p>
8001 <blockquote class="text">
8002 <p>"OK" -
8003 </p>
8004 <blockquote class="text">
8005 <p>on success when NON_MODAL is not supplied
8006 </p>
8007 </blockquote>
8008
8009
8010 <p>"OK[&lt;job-id&gt;]" -
8011 </p>
8012 <blockquote class="text">
8013 <p>on success when NON_MODAL is supplied, where &lt;job-id&gt;
8014 is a numerical ID used to obtain status information about the job progress.
8015 See <a class='info' href='#GET DB_INSTRUMENTS_JOB INFO'>GET DB_INSTRUMENTS_JOB INFO<span> (</span><span class='info'>Getting job status information</span><span>)</span></a>
8016
8017 </p>
8018 </blockquote>
8019
8020
8021 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8022 </p>
8023 <blockquote class="text">
8024 <p>if an invalid path is specified.
8025 </p>
8026 </blockquote>
8027
8028
8029 </blockquote><p>
8030
8031 </p>
8032 <p>Examples:
8033 </p>
8034 <p>
8035 </p>
8036 <blockquote class="text">
8037 <p>C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI Bosendorfer 290.gig' 0"
8038 </p>
8039 <p>S: "OK"
8040 </p>
8041 </blockquote><p>
8042
8043 </p>
8044 <a name="REMOVE DB_INSTRUMENT"></a><br /><hr />
8045 <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>
8046 <a name="rfc.section.6.8.12"></a><h3>6.8.12.&nbsp;
8047 Removing an instrument</h3>
8048
8049 <p>The front-end can remove a particular instrument
8050 from the instruments database by sending the following command:
8051 </p>
8052 <p>
8053 </p>
8054 <blockquote class="text">
8055 <p>REMOVE DB_INSTRUMENT &lt;instr_path&gt;
8056 </p>
8057 </blockquote><p>
8058
8059 </p>
8060 <p>Where &lt;instr_path&gt; is the absolute path name
8061 (in the instruments database) of the instrument to remove.
8062 </p>
8063 <p>Possible Answers:
8064 </p>
8065 <p>
8066 </p>
8067 <blockquote class="text">
8068 <p>"OK" -
8069 </p>
8070 <blockquote class="text">
8071 <p>if the instrument is removed successfully
8072 </p>
8073 </blockquote>
8074
8075
8076 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8077 </p>
8078 <blockquote class="text">
8079 <p>if the given path does not exist or
8080 is a directory.
8081 </p>
8082 </blockquote>
8083
8084
8085 </blockquote><p>
8086
8087 </p>
8088 <p>Examples:
8089 </p>
8090 <p>
8091 </p>
8092 <blockquote class="text">
8093 <p>C: "REMOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'"
8094 </p>
8095 <p>S: "OK"
8096 </p>
8097 </blockquote><p>
8098
8099 </p>
8100 <a name="GET DB_INSTRUMENTS"></a><br /><hr />
8101 <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>
8102 <a name="rfc.section.6.8.13"></a><h3>6.8.13.&nbsp;
8103 Getting amount of instruments</h3>
8104
8105 <p>The front-end can retrieve the current amount of
8106 instruments in a specific directory by sending the following command:
8107 </p>
8108 <p>
8109 </p>
8110 <blockquote class="text">
8111 <p>GET DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;
8112 </p>
8113 </blockquote><p>
8114
8115 </p>
8116 <p>Where &lt;dir&gt; should be replaced by the absolute path name
8117 of the directory. If RECURSIVE is specified, the number of all
8118 instruments, including those located in subdirectories of the
8119 specified directory, will be returned.
8120 </p>
8121 <p>Possible Answers:
8122 </p>
8123 <p>
8124 </p>
8125 <blockquote class="text">
8126 <p>The current number of instruments
8127 in the specified directory.
8128 </p>
8129 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8130 </p>
8131 <blockquote class="text">
8132 <p>if the given directory does not exist.
8133 </p>
8134 </blockquote>
8135
8136
8137 </blockquote><p>
8138
8139 </p>
8140 <p>Example:
8141 </p>
8142 <p>
8143 </p>
8144 <blockquote class="text">
8145 <p>C: "GET DB_INSTRUMENTS '/Piano Collection'"
8146 </p>
8147 <p>S: "2"
8148 </p>
8149 </blockquote><p>
8150
8151 </p>
8152 <a name="LIST DB_INSTRUMENTS"></a><br /><hr />
8153 <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>
8154 <a name="rfc.section.6.8.14"></a><h3>6.8.14.&nbsp;
8155 Listing all instruments in specific directory</h3>
8156
8157 <p>The front-end can retrieve the current list of instruments
8158 in specific directory by sending the following command:
8159 </p>
8160 <p>
8161 </p>
8162 <blockquote class="text">
8163 <p>LIST DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;
8164 </p>
8165 </blockquote><p>
8166
8167 </p>
8168 <p>Where &lt;dir&gt; should be replaced by the absolute path
8169 name of the directory. If RECURSIVE is specified, the absolute path
8170 names of all instruments, including those located in subdirectories
8171 of the specified directory, will be returned.
8172 </p>
8173 <p>Possible Answers:
8174 </p>
8175 <p>
8176 </p>
8177 <blockquote class="text">
8178 <p>A comma separated list of all instruments
8179 (encapsulated into apostrophes) in the specified directory.
8180 </p>
8181 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8182 </p>
8183 <blockquote class="text">
8184 <p>if the given directory does not exist.
8185 </p>
8186 </blockquote>
8187
8188
8189 </blockquote><p>
8190
8191 </p>
8192 <p>Example:
8193 </p>
8194 <p>
8195 </p>
8196 <blockquote class="text">
8197 <p>C: "LIST DB_INSTRUMENTS '/Piano Collection'"
8198 </p>
8199 <p>S: "'Bosendorfer 290','Steinway D'"
8200 </p>
8201 </blockquote><p>
8202
8203 </p>
8204 <p>
8205 </p>
8206 <blockquote class="text">
8207 <p>C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'"
8208 </p>
8209 <p>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D','/Piano Collection/Lite/Free Piano'"
8210 </p>
8211 </blockquote><p>
8212
8213 </p>
8214 <a name="GET DB_INSTRUMENT INFO"></a><br /><hr />
8215 <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>
8216 <a name="rfc.section.6.8.15"></a><h3>6.8.15.&nbsp;
8217 Getting instrument information</h3>
8218
8219 <p>The front-end can ask for the current settings of an
8220 instrument by sending the following command:
8221 </p>
8222 <p>
8223 </p>
8224 <blockquote class="text">
8225 <p>GET DB_INSTRUMENT INFO &lt;instr_path&gt;
8226 </p>
8227 </blockquote><p>
8228
8229 </p>
8230 <p>Where &lt;instr_path&gt; should be replaced by the absolute path
8231 name of the instrument the front-end is interested in.
8232 </p>
8233 <p>Possible Answers:
8234 </p>
8235 <p>
8236 </p>
8237 <blockquote class="text">
8238 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
8239 Each answer line begins with the settings category name
8240 followed by a colon and then a space character &lt;SP&gt; and finally
8241 the info character string to that setting category. At the
8242 moment the following categories are defined:
8243 </p>
8244 <p>
8245 </p>
8246 <blockquote class="text">
8247 <p>INSTRUMENT_FILE -
8248 </p>
8249 <blockquote class="text">
8250 <p>File name of the instrument.
8251 </p>
8252 </blockquote>
8253
8254
8255 <p>INSTRUMENT_NR -
8256 </p>
8257 <blockquote class="text">
8258 <p>Index of the instrument within the file.
8259 </p>
8260 </blockquote>
8261
8262
8263 <p>FORMAT_FAMILY -
8264 </p>
8265 <blockquote class="text">
8266 <p>The format family of the instrument.
8267 </p>
8268 </blockquote>
8269
8270
8271 <p>FORMAT_VERSION -
8272 </p>
8273 <blockquote class="text">
8274 <p>The format version of the instrument.
8275 </p>
8276 </blockquote>
8277
8278
8279 <p>SIZE -
8280 </p>
8281 <blockquote class="text">
8282 <p>The size of the instrument in bytes.
8283 </p>
8284 </blockquote>
8285
8286
8287 <p>CREATED -
8288 </p>
8289 <blockquote class="text">
8290 <p>The date and time when the instrument is added
8291 in the instruments database, represented in
8292 "YYYY-MM-DD HH:MM:SS" format
8293 </p>
8294 </blockquote>
8295
8296
8297 <p>MODIFIED -
8298 </p>
8299 <blockquote class="text">
8300 <p>The date and time of the last modification of the
8301 instrument's database settings, represented in
8302 "YYYY-MM-DD HH:MM:SS" format
8303 </p>
8304 </blockquote>
8305
8306
8307 <p>DESCRIPTION -
8308 </p>
8309 <blockquote class="text">
8310 <p>A brief description of the instrument
8311 </p>
8312 </blockquote>
8313
8314
8315 <p>IS_DRUM -
8316 </p>
8317 <blockquote class="text">
8318 <p>either true or false, determines whether the
8319 instrument is a drumkit or a chromatic instrument
8320 </p>
8321 </blockquote>
8322
8323
8324 <p>PRODUCT -
8325 </p>
8326 <blockquote class="text">
8327 <p>The product title of the instrument
8328 </p>
8329 </blockquote>
8330
8331
8332 <p>ARTISTS -
8333 </p>
8334 <blockquote class="text">
8335 <p>Lists the artist names
8336 </p>
8337 </blockquote>
8338
8339
8340 <p>KEYWORDS -
8341 </p>
8342 <blockquote class="text">
8343 <p>Provides a list of keywords that refer to the instrument.
8344 Keywords are separated with semicolon and blank.
8345 </p>
8346 </blockquote>
8347
8348
8349 </blockquote>
8350
8351
8352 </blockquote><p>
8353
8354 </p>
8355 <p>The mentioned fields above don't have to be in particular order.
8356 </p>
8357 <p>Example:
8358 </p>
8359 <p>
8360 </p>
8361 <blockquote class="text">
8362 <p>C: "GET DB_INSTRUMENT INFO '/Piano Collection/Bosendorfer 290'"
8363 </p>
8364 <p>S: "INSTRUMENT_FILE: /home/me/gigs/Bosendorfer 290.gig"
8365 </p>
8366 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"
8367 </p>
8368 <p>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"
8369 </p>
8370 <p>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 2"
8371 </p>
8372 <p>&nbsp;&nbsp;&nbsp;"SIZE: 2050871870"
8373 </p>
8374 <p>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"
8375 </p>
8376 <p>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"
8377 </p>
8378 <p>&nbsp;&nbsp;&nbsp;"DESCRIPTION: "
8379 </p>
8380 <p>&nbsp;&nbsp;&nbsp;"IS_DRUM: false"
8381 </p>
8382 <p>&nbsp;&nbsp;&nbsp;"PRODUCT: GRANDIOSO Bosendorfer 290"
8383 </p>
8384 <p>&nbsp;&nbsp;&nbsp;"ARTISTS: Post Musical Instruments"
8385 </p>
8386 <p>&nbsp;&nbsp;&nbsp;"KEYWORDS: Bosendorfer"
8387 </p>
8388 <p>&nbsp;&nbsp;&nbsp;"."
8389 </p>
8390 </blockquote><p>
8391
8392 </p>
8393 <a name="SET DB_INSTRUMENT NAME"></a><br /><hr />
8394 <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>
8395 <a name="rfc.section.6.8.16"></a><h3>6.8.16.&nbsp;
8396 Renaming an instrument</h3>
8397
8398 <p>The front-end can alter the name of a specific
8399 instrument by sending the following command:
8400 </p>
8401 <p>
8402 </p>
8403 <blockquote class="text">
8404 <p>SET DB_INSTRUMENT NAME &lt;instr&gt; &lt;name&gt;
8405 </p>
8406 </blockquote><p>
8407
8408 </p>
8409 <p>Where &lt;instr&gt; is the absolute path name of the instrument and
8410 &lt;name&gt; is the new name for that instrument.
8411 </p>
8412 <p>Possible Answers:
8413 </p>
8414 <p>
8415 </p>
8416 <blockquote class="text">
8417 <p>"OK" -
8418 </p>
8419 <blockquote class="text">
8420 <p>on success
8421 </p>
8422 </blockquote>
8423
8424
8425 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8426 </p>
8427 <blockquote class="text">
8428 <p>in case the given instrument does not exists,
8429 or if an instrument with name equal to the new
8430 name already exists.
8431 </p>
8432 </blockquote>
8433
8434
8435 </blockquote><p>
8436
8437 </p>
8438 <p>Example:
8439 </p>
8440 <p>
8441 </p>
8442 <blockquote class="text">
8443 <p>C: "SET DB_INSTRUMENT NAME '/Piano Collection/Bosendorfer' 'Bosendorfer 290'"
8444 </p>
8445 <p>S: "OK"
8446 </p>
8447 </blockquote><p>
8448
8449 </p>
8450 <a name="MOVE DB_INSTRUMENT"></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 <a name="rfc.section.6.8.17"></a><h3>6.8.17.&nbsp;
8453 Moving an instrument</h3>
8454
8455 <p>The front-end can move a specific instrument to another directory by
8456 sending the following command:
8457 </p>
8458 <p>
8459 </p>
8460 <blockquote class="text">
8461 <p>MOVE DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;
8462 </p>
8463 </blockquote><p>
8464
8465 </p>
8466 <p>Where &lt;instr&gt; is the absolute path name of the instrument
8467 to move and &lt;dst&gt; is the directory where the instrument will
8468 be moved to.
8469 </p>
8470 <p>Possible Answers:
8471 </p>
8472 <p>
8473 </p>
8474 <blockquote class="text">
8475 <p>"OK" -
8476 </p>
8477 <blockquote class="text">
8478 <p>on success
8479 </p>
8480 </blockquote>
8481
8482
8483 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8484 </p>
8485 <blockquote class="text">
8486 <p>in case the given instrument does not exists,
8487 or if an instrument with name equal to the name of the
8488 specified instrument already exists in the destination
8489 directory.
8490 </p>
8491 </blockquote>
8492
8493
8494 </blockquote><p>
8495
8496 </p>
8497 <p>Example:
8498 </p>
8499 <p>
8500 </p>
8501 <blockquote class="text">
8502 <p>C: "MOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Piano Collection/Acoustic'"
8503 </p>
8504 <p>S: "OK"
8505 </p>
8506 </blockquote><p>
8507
8508 </p>
8509 <a name="COPY DB_INSTRUMENT"></a><br /><hr />
8510 <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>
8511 <a name="rfc.section.6.8.18"></a><h3>6.8.18.&nbsp;
8512 Copying instruments</h3>
8513
8514 <p>The front-end can copy a specific instrument to another directory by
8515 sending the following command:
8516 </p>
8517 <p>
8518 </p>
8519 <blockquote class="text">
8520 <p>COPY DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;
8521 </p>
8522 </blockquote><p>
8523
8524 </p>
8525 <p>Where &lt;instr&gt; is the absolute path name of the instrument
8526 to copy and &lt;dst&gt; is the directory where the instrument will
8527 be copied to.
8528 </p>
8529 <p>Possible Answers:
8530 </p>
8531 <p>
8532 </p>
8533 <blockquote class="text">
8534 <p>"OK" -
8535 </p>
8536 <blockquote class="text">
8537 <p>on success
8538 </p>
8539 </blockquote>
8540
8541
8542 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8543 </p>
8544 <blockquote class="text">
8545 <p>in case the given instrument does not exists,
8546 or if an instrument with name equal to the name of the
8547 specified instrument already exists in the destination
8548 directory.
8549 </p>
8550 </blockquote>
8551
8552
8553 </blockquote><p>
8554
8555 </p>
8556 <p>Example:
8557 </p>
8558 <p>
8559 </p>
8560 <blockquote class="text">
8561 <p>C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Acoustic/Pianos/'"
8562 </p>
8563 <p>S: "OK"
8564 </p>
8565 </blockquote><p>
8566
8567 </p>
8568 <a name="SET DB_INSTRUMENT DESCRIPTION"></a><br /><hr />
8569 <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>
8570 <a name="rfc.section.6.8.19"></a><h3>6.8.19.&nbsp;
8571 Changing the description of instrument</h3>
8572
8573 <p>The front-end can alter the description of a specific
8574 instrument by sending the following command:
8575 </p>
8576 <p>
8577 </p>
8578 <blockquote class="text">
8579 <p>SET DB_INSTRUMENT DESCRIPTION &lt;instr&gt; &lt;desc&gt;
8580 </p>
8581 </blockquote><p>
8582
8583 </p>
8584 <p>Where &lt;instr&gt; is the absolute path name of the instrument and
8585 &lt;desc&gt; is the new description for the instrument.
8586 </p>
8587 <p>Possible Answers:
8588 </p>
8589 <p>
8590 </p>
8591 <blockquote class="text">
8592 <p>"OK" -
8593 </p>
8594 <blockquote class="text">
8595 <p>on success
8596 </p>
8597 </blockquote>
8598
8599
8600 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8601 </p>
8602 <blockquote class="text">
8603 <p>in case the given instrument does not exists.
8604 </p>
8605 </blockquote>
8606
8607
8608 </blockquote><p>
8609
8610 </p>
8611 <p>Example:
8612 </p>
8613 <p>
8614 </p>
8615 <blockquote class="text">
8616 <p>C: "SET DB_INSTRUMENT DESCRIPTION '/Piano Collection/Acoustic/Bosendorfer 290' 'No comment :)'"
8617 </p>
8618 <p>S: "OK"
8619 </p>
8620 </blockquote><p>
8621
8622 </p>
8623 <a name="FIND DB_INSTRUMENTS"></a><br /><hr />
8624 <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>
8625 <a name="rfc.section.6.8.20"></a><h3>6.8.20.&nbsp;
8626 Finding instruments</h3>
8627
8628 <p>The front-end can search for instruments
8629 in specific directory by sending the following command:
8630 </p>
8631 <p>
8632 </p>
8633 <blockquote class="text">
8634 <p>FIND DB_INSTRUMENTS [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;
8635 </p>
8636 </blockquote><p>
8637
8638 </p>
8639 <p>Where &lt;dir&gt; should be replaced by the absolute path
8640 name of the directory to search in. If NON_RECURSIVE is specified, the
8641 directories located in subdirectories of the specified directory will not
8642 be searched. &lt;criteria-list&gt; is a list of search criterias
8643 in form of "key1=val1 key2=val2 ...". The following criterias are
8644 allowed:
8645 </p>
8646 <p>
8647
8648 <p>NAME='&lt;search-string&gt;'
8649 </p>
8650 <blockquote class="text">
8651 <p>Restricts the search to instruments, which names
8652 satisfy the supplied search string.
8653 </p>
8654 </blockquote><p>
8655
8656 </p>
8657
8658
8659 <p>SIZE=[&lt;min&gt;]..[&lt;max&gt;]
8660 </p>
8661 <blockquote class="text">
8662 <p>Restricts the search to instruments, which
8663 size is in the specified range. If &lt;min&gt; is omitted,
8664 the search results are restricted to instruments with size less then
8665 or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the
8666 search is restricted to instruments with size greater then
8667 or equal to &lt;min&gt;.
8668 </p>
8669 </blockquote><p>
8670
8671 </p>
8672
8673
8674 <p>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
8675 </p>
8676 <blockquote class="text">
8677 <p>Restricts the search to instruments, which creation
8678 date satisfies the specified period, where &lt;date-after&gt;
8679 and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
8680 If &lt;date-after&gt; is omitted the search is restricted to
8681 instruments created before &lt;date-before&gt;. If
8682 &lt;date-before&gt; is omitted, the search is restricted
8683 to instruments created after &lt;date-after&gt;.
8684 </p>
8685 </blockquote><p>
8686
8687 </p>
8688
8689
8690 <p>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
8691 </p>
8692 <blockquote class="text">
8693 <p>Restricts the search to instruments, which
8694 date of last modification satisfies the specified period, where
8695 &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
8696 format. If &lt;date-after&gt; is omitted the search is restricted to
8697 instruments, which are last modified before &lt;date-before&gt;. If
8698 &lt;date-before&gt; is omitted, the search is restricted to instruments,
8699 which are last modified after &lt;date-after&gt;.
8700 </p>
8701 </blockquote><p>
8702
8703 </p>
8704
8705
8706 <p>DESCRIPTION='&lt;search-string&gt;'
8707 </p>
8708 <blockquote class="text">
8709 <p>Restricts the search to instruments with description
8710 that satisfies the supplied search string.
8711 </p>
8712 </blockquote><p>
8713
8714 </p>
8715
8716
8717 <p>PRODUCT='&lt;search-string&gt;'
8718 </p>
8719 <blockquote class="text">
8720 <p>Restricts the search to instruments with product info
8721 that satisfies the supplied search string.
8722 </p>
8723 </blockquote><p>
8724
8725 </p>
8726
8727
8728 <p>ARTISTS='&lt;search-string&gt;'
8729 </p>
8730 <blockquote class="text">
8731 <p>Restricts the search to instruments with artists info
8732 that satisfies the supplied search string.
8733 </p>
8734 </blockquote><p>
8735
8736 </p>
8737
8738
8739 <p>KEYWORDS='&lt;search-string&gt;'
8740 </p>
8741 <blockquote class="text">
8742 <p>Restricts the search to instruments with keyword list
8743 that satisfies the supplied search string.
8744 </p>
8745 </blockquote><p>
8746
8747 </p>
8748
8749
8750 <p>IS_DRUM=true | false
8751 </p>
8752 <blockquote class="text">
8753 <p>Either true or false. Restricts the search to
8754 drum kits or chromatic instruments.
8755 </p>
8756 </blockquote><p>
8757
8758 </p>
8759
8760
8761 <p>FORMAT_FAMILIES='&lt;format-list&gt;'
8762 </p>
8763 <blockquote class="text">
8764 <p>Restricts the search to instruments of the supplied format families,
8765 where &lt;format-list&gt; is a comma separated list of format families.
8766 </p>
8767 </blockquote><p>
8768
8769 </p>
8770
8771
8772 <p>Where &lt;search-string&gt; is either a regular expression, or a
8773 word list separated with spaces for OR search and with '+' for AND search.
8774 </p>
8775 <p>Possible Answers:
8776 </p>
8777 <p>
8778 </p>
8779 <blockquote class="text">
8780 <p>A comma separated list with the absolute path names (encapsulated into
8781 apostrophes) of all instruments in the specified directory that satisfy
8782 the supplied search criterias.
8783 </p>
8784 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8785 </p>
8786 <blockquote class="text">
8787 <p>if the given directory does not exist.
8788 </p>
8789 </blockquote>
8790
8791
8792 </blockquote><p>
8793
8794 </p>
8795 <p>Example:
8796 </p>
8797 <p>
8798 </p>
8799 <blockquote class="text">
8800 <p>C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+290'"
8801 </p>
8802 <p>S: "'/Piano Collection/Bosendorfer 290'"
8803 </p>
8804 </blockquote><p>
8805
8806 </p>
8807 <p>
8808 </p>
8809 <blockquote class="text">
8810 <p>C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01 09:30:13..'"
8811 </p>
8812 <p>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D'"
8813 </p>
8814 </blockquote><p>
8815
8816 </p>
8817 <a name="GET DB_INSTRUMENTS_JOB INFO"></a><br /><hr />
8818 <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>
8819 <a name="rfc.section.6.8.21"></a><h3>6.8.21.&nbsp;
8820 Getting job status information</h3>
8821
8822 <p>The front-end can ask for the current status of a
8823 particular database instruments job by sending the following command:
8824 </p>
8825 <p>
8826 </p>
8827 <blockquote class="text">
8828 <p>GET DB_INSTRUMENTS_JOB INFO &lt;job-id&gt;
8829 </p>
8830 </blockquote><p>
8831
8832 </p>
8833 <p>Where &lt;job-id&gt; should be replaced by the numerical ID
8834 of the job the front-end is interested in.
8835 </p>
8836 <p>Possible Answers:
8837 </p>
8838 <p>
8839 </p>
8840 <blockquote class="text">
8841 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
8842 Each answer line begins with the settings category name
8843 followed by a colon and then a space character &lt;SP&gt; and finally
8844 the info character string to that setting category. At the
8845 moment the following categories are defined:
8846 </p>
8847 <p>
8848 </p>
8849 <blockquote class="text">
8850 <p>FILES_TOTAL -
8851 </p>
8852 <blockquote class="text">
8853 <p>The total number of files scheduled for scanning
8854 </p>
8855 </blockquote>
8856
8857
8858 <p>FILES_SCANNED -
8859 </p>
8860 <blockquote class="text">
8861 <p>The current number of scanned files
8862 </p>
8863 </blockquote>
8864
8865
8866 <p>SCANNING -
8867 </p>
8868 <blockquote class="text">
8869 <p>The absolute path name of the file which is currently
8870 being scanned
8871 </p>
8872 </blockquote>
8873
8874
8875 <p>STATUS -
8876 </p>
8877 <blockquote class="text">
8878 <p>An integer value between 0 and 100 indicating the
8879 scanning progress percentage of the file which is
8880 currently being scanned
8881 </p>
8882 </blockquote>
8883
8884
8885 </blockquote>
8886
8887
8888 </blockquote><p>
8889
8890 </p>
8891 <p>The mentioned fields above don't have to be in particular order.
8892 </p>
8893 <p>Example:
8894 </p>
8895 <p>
8896 </p>
8897 <blockquote class="text">
8898 <p>C: "GET DB_INSTRUMENTS_JOB INFO 2"
8899 </p>
8900 <p>S: "FILES_TOTAL: 12"
8901 </p>
8902 <p>&nbsp;&nbsp;&nbsp;"FILES_SCANNED: 7"
8903 </p>
8904 <p>&nbsp;&nbsp;&nbsp;"SCANNING: /home/me/gigs/Bosendorfer 290.gig"
8905 </p>
8906 <p>&nbsp;&nbsp;&nbsp;"STATUS: 42"
8907 </p>
8908 <p>&nbsp;&nbsp;&nbsp;"."
8909 </p>
8910 </blockquote><p>
8911
8912 </p>
8913 <a name="command_syntax"></a><br /><hr />
8914 <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>
8915 <a name="rfc.section.7"></a><h3>7.&nbsp;
8916 Command Syntax</h3>
8917
8918 <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>
8919 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>)
8920 where applicable.
8921
8922 </p>
8923 <p>input =
8924 </p>
8925 <blockquote class="text">
8926 <p>line LF
8927
8928 </p>
8929 <p>/ line CR LF
8930
8931 </p>
8932 </blockquote><p>
8933
8934 </p>
8935 <p>line =
8936 </p>
8937 <blockquote class="text">
8938 <p>/* epsilon (empty line ignored) */
8939
8940 </p>
8941 <p>/ comment
8942
8943 </p>
8944 <p>/ command
8945
8946 </p>
8947 <p>/ error
8948
8949 </p>
8950 </blockquote><p>
8951
8952 </p>
8953 <p>comment =
8954 </p>
8955 <blockquote class="text">
8956 <p>'#'
8957
8958 </p>
8959 <p>/ comment '#'
8960
8961 </p>
8962 <p>/ comment SP
8963
8964 </p>
8965 <p>/ comment number
8966
8967 </p>
8968 <p>/ comment string
8969
8970 </p>
8971 </blockquote><p>
8972
8973 </p>
8974 <p>command =
8975 </p>
8976 <blockquote class="text">
8977 <p>ADD SP add_instruction
8978
8979 </p>
8980 <p>/ MAP SP map_instruction
8981
8982 </p>
8983 <p>/ UNMAP SP unmap_instruction
8984
8985 </p>
8986 <p>/ GET SP get_instruction
8987
8988 </p>
8989 <p>/ CREATE SP create_instruction
8990
8991 </p>
8992 <p>/ DESTROY SP destroy_instruction
8993
8994 </p>
8995 <p>/ LIST SP list_instruction
8996
8997 </p>
8998 <p>/ LOAD SP load_instruction
8999
9000 </p>
9001 <p>/ REMOVE SP remove_instruction
9002
9003 </p>
9004 <p>/ SET SP set_instruction
9005
9006 </p>
9007 <p>/ SUBSCRIBE SP subscribe_event
9008
9009 </p>
9010 <p>/ UNSUBSCRIBE SP unsubscribe_event
9011
9012 </p>
9013 <p>/ RESET SP reset_instruction
9014
9015 </p>
9016 <p>/ CLEAR SP clear_instruction
9017
9018 </p>
9019 <p>/ FIND SP find_instruction
9020
9021 </p>
9022 <p>/ MOVE SP move_instruction
9023
9024 </p>
9025 <p>/ COPY SP copy_instruction
9026
9027 </p>
9028 <p>/ EDIT SP edit_instruction
9029
9030 </p>
9031 <p>/ RESET
9032
9033 </p>
9034 <p>/ QUIT
9035
9036 </p>
9037 </blockquote><p>
9038
9039 </p>
9040 <p>add_instruction =
9041 </p>
9042 <blockquote class="text">
9043 <p>CHANNEL
9044
9045 </p>
9046 <p>/ DB_INSTRUMENT_DIRECTORY SP pathname
9047
9048 </p>
9049 <p>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP pathname SP pathname
9050
9051 </p>
9052 <p>/ DB_INSTRUMENTS SP scan_mode SP pathname SP pathname
9053
9054 </p>
9055 <p>/ DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname
9056
9057 </p>
9058 <p>/ DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname SP instrument_index
9059
9060 </p>
9061 <p>/ DB_INSTRUMENTS SP pathname SP pathname
9062
9063 </p>
9064 <p>/ DB_INSTRUMENTS SP pathname SP pathname SP instrument_index
9065
9066 </p>
9067 <p>/ MIDI_INSTRUMENT_MAP
9068
9069 </p>
9070 <p>/ MIDI_INSTRUMENT_MAP SP map_name
9071
9072 </p>
9073 </blockquote><p>
9074
9075 </p>
9076 <p>subscribe_event =
9077 </p>
9078 <blockquote class="text">
9079 <p>AUDIO_OUTPUT_DEVICE_COUNT
9080
9081 </p>
9082 <p>/ AUDIO_OUTPUT_DEVICE_INFO
9083
9084 </p>
9085 <p>/ MIDI_INPUT_DEVICE_COUNT
9086
9087 </p>
9088 <p>/ MIDI_INPUT_DEVICE_INFO
9089
9090 </p>
9091 <p>/ CHANNEL_COUNT
9092
9093 </p>
9094 <p>/ VOICE_COUNT
9095
9096 </p>
9097 <p>/ STREAM_COUNT
9098
9099 </p>
9100 <p>/ BUFFER_FILL
9101
9102 </p>
9103 <p>/ CHANNEL_INFO
9104
9105 </p>
9106 <p>/ FX_SEND_COUNT
9107
9108 </p>
9109 <p>/ FX_SEND_INFO
9110
9111 </p>
9112 <p>/ MIDI_INSTRUMENT_MAP_COUNT
9113
9114 </p>
9115 <p>/ MIDI_INSTRUMENT_MAP_INFO
9116
9117 </p>
9118 <p>/ MIDI_INSTRUMENT_COUNT
9119
9120 </p>
9121 <p>/ MIDI_INSTRUMENT_INFO
9122
9123 </p>
9124 <p>/ DB_INSTRUMENT_DIRECTORY_COUNT
9125
9126 </p>
9127 <p>/ DB_INSTRUMENT_DIRECTORY_INFO
9128
9129 </p>
9130 <p>/ DB_INSTRUMENT_COUNT
9131
9132 </p>
9133 <p>/ DB_INSTRUMENT_INFO
9134
9135 </p>
9136 <p>/ DB_INSTRUMENTS_JOB_INFO
9137
9138 </p>
9139 <p>/ MISCELLANEOUS
9140
9141 </p>
9142 <p>/ TOTAL_VOICE_COUNT
9143
9144 </p>
9145 <p>/ GLOBAL_INFO
9146
9147 </p>
9148 </blockquote><p>
9149
9150 </p>
9151 <p>unsubscribe_event =
9152 </p>
9153 <blockquote class="text">
9154 <p>AUDIO_OUTPUT_DEVICE_COUNT
9155
9156 </p>
9157 <p>/ AUDIO_OUTPUT_DEVICE_INFO
9158
9159 </p>
9160 <p>/ MIDI_INPUT_DEVICE_COUNT
9161
9162 </p>
9163 <p>/ MIDI_INPUT_DEVICE_INFO
9164
9165 </p>
9166 <p>/ CHANNEL_COUNT
9167
9168 </p>
9169 <p>/ VOICE_COUNT
9170
9171 </p>
9172 <p>/ STREAM_COUNT
9173
9174 </p>
9175 <p>/ BUFFER_FILL
9176
9177 </p>
9178 <p>/ CHANNEL_INFO
9179
9180 </p>
9181 <p>/ FX_SEND_COUNT
9182
9183 </p>
9184 <p>/ FX_SEND_INFO
9185
9186 </p>
9187 <p>/ MIDI_INSTRUMENT_MAP_COUNT
9188
9189 </p>
9190 <p>/ MIDI_INSTRUMENT_MAP_INFO
9191
9192 </p>
9193 <p>/ MIDI_INSTRUMENT_COUNT
9194
9195 </p>
9196 <p>/ MIDI_INSTRUMENT_INFO
9197
9198 </p>
9199 <p>/ DB_INSTRUMENT_DIRECTORY_COUNT
9200
9201 </p>
9202 <p>/ DB_INSTRUMENT_DIRECTORY_INFO
9203
9204 </p>
9205 <p>/ DB_INSTRUMENT_COUNT
9206
9207 </p>
9208 <p>/ DB_INSTRUMENT_INFO
9209
9210 </p>
9211 <p>/ DB_INSTRUMENTS_JOB_INFO
9212
9213 </p>
9214 <p>/ MISCELLANEOUS
9215
9216 </p>
9217 <p>/ TOTAL_VOICE_COUNT
9218
9219 </p>
9220 <p>/ GLOBAL_INFO
9221
9222 </p>
9223 </blockquote><p>
9224
9225 </p>
9226 <p>map_instruction =
9227 </p>
9228 <blockquote class="text">
9229 <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
9230
9231 </p>
9232 <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
9233
9234 </p>
9235 <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
9236
9237 </p>
9238 <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
9239
9240 </p>
9241 </blockquote><p>
9242
9243 </p>
9244 <p>unmap_instruction =
9245 </p>
9246 <blockquote class="text">
9247 <p>MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog
9248
9249 </p>
9250 </blockquote><p>
9251
9252 </p>
9253 <p>remove_instruction =
9254 </p>
9255 <blockquote class="text">
9256 <p>CHANNEL SP sampler_channel
9257
9258 </p>
9259 <p>/ MIDI_INSTRUMENT_MAP SP midi_map
9260
9261 </p>
9262 <p>/ MIDI_INSTRUMENT_MAP SP ALL
9263
9264 </p>
9265 <p>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP pathname
9266
9267 </p>
9268 <p>/ DB_INSTRUMENT_DIRECTORY SP pathname
9269
9270 </p>
9271 <p>/ DB_INSTRUMENT SP pathname
9272
9273 </p>
9274 </blockquote><p>
9275
9276 </p>
9277 <p>get_instruction =
9278 </p>
9279 <blockquote class="text">
9280 <p>AVAILABLE_ENGINES
9281
9282 </p>
9283 <p>/ AVAILABLE_MIDI_INPUT_DRIVERS
9284
9285 </p>
9286 <p>/ MIDI_INPUT_DRIVER SP INFO SP string
9287
9288 </p>
9289 <p>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
9290
9291 </p>
9292 <p>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
9293
9294 </p>
9295 <p>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
9296
9297 </p>
9298 <p>/ AUDIO_OUTPUT_DRIVER SP INFO SP string
9299
9300 </p>
9301 <p>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
9302
9303 </p>
9304 <p>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
9305
9306 </p>
9307 <p>/ AUDIO_OUTPUT_DEVICES
9308
9309 </p>
9310 <p>/ MIDI_INPUT_DEVICES
9311
9312 </p>
9313 <p>/ AUDIO_OUTPUT_DEVICE SP INFO SP number
9314
9315 </p>
9316 <p>/ MIDI_INPUT_DEVICE SP INFO SP number
9317
9318 </p>
9319 <p>/ MIDI_INPUT_PORT SP INFO SP number SP number
9320
9321 </p>
9322 <p>/ MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
9323
9324 </p>
9325 <p>/ AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
9326
9327 </p>
9328 <p>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP string
9329
9330 </p>
9331 <p>/ CHANNELS
9332
9333 </p>
9334 <p>/ CHANNEL SP INFO SP sampler_channel
9335
9336 </p>
9337 <p>/ CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
9338
9339 </p>
9340 <p>/ CHANNEL SP STREAM_COUNT SP sampler_channel
9341
9342 </p>
9343 <p>/ CHANNEL SP VOICE_COUNT SP sampler_channel
9344
9345 </p>
9346 <p>/ ENGINE SP INFO SP engine_name
9347
9348 </p>
9349 <p>/ SERVER SP INFO
9350
9351 </p>
9352 <p>/ TOTAL_VOICE_COUNT
9353
9354 </p>
9355 <p>/ TOTAL_VOICE_COUNT_MAX
9356
9357 </p>
9358 <p>/ MIDI_INSTRUMENTS SP midi_map
9359
9360 </p>
9361 <p>/ MIDI_INSTRUMENTS SP ALL
9362
9363 </p>
9364 <p>/ MIDI_INSTRUMENT SP INFO SP midi_map SP midi_bank SP midi_prog
9365
9366 </p>
9367 <p>/ MIDI_INSTRUMENT_MAPS
9368
9369 </p>
9370 <p>/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map
9371
9372 </p>
9373 <p>/ FX_SENDS SP sampler_channel
9374
9375 </p>
9376 <p>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
9377
9378 </p>
9379 <p>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname
9380
9381 </p>
9382 <p>/ DB_INSTRUMENT_DIRECTORIES SP pathname
9383
9384 </p>
9385 <p>/ DB_INSTRUMENT_DIRECTORY SP INFO SP pathname
9386
9387 </p>
9388 <p>/ DB_INSTRUMENTS SP RECURSIVE SP pathname
9389
9390 </p>
9391 <p>/ DB_INSTRUMENTS SP pathname
9392
9393 </p>
9394 <p>/ DB_INSTRUMENT SP INFO SP pathname
9395
9396 </p>
9397 <p>/ DB_INSTRUMENTS_JOB SP INFO SP number
9398
9399 </p>
9400 <p>/ VOLUME
9401
9402 </p>
9403 </blockquote><p>
9404
9405 </p>
9406 <p>set_instruction =
9407 </p>
9408 <blockquote class="text">
9409 <p>AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
9410
9411 </p>
9412 <p>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '=' param_val_list
9413
9414 </p>
9415 <p>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
9416
9417 </p>
9418 <p>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list
9419
9420 </p>
9421 <p>/ CHANNEL SP set_chan_instruction
9422
9423 </p>
9424 <p>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
9425
9426 </p>
9427 <p>/ FX_SEND SP NAME SP sampler_channel SP fx_send_id SP fx_send_name
9428
9429 </p>
9430 <p>/ FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id SP audio_channel_index SP audio_channel_index
9431
9432 </p>
9433 <p>/ FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP midi_ctrl
9434
9435 </p>
9436 <p>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
9437
9438 </p>
9439 <p>/ DB_INSTRUMENT_DIRECTORY SP NAME SP pathname SP dirname
9440
9441 </p>
9442 <p>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP pathname SP stringval
9443
9444 </p>
9445 <p>/ DB_INSTRUMENT SP NAME SP pathname SP dirname
9446
9447 </p>
9448 <p>/ DB_INSTRUMENT SP DESCRIPTION SP pathname SP stringval
9449
9450 </p>
9451 <p>/ ECHO SP boolean
9452
9453 </p>
9454 <p>/ VOLUME SP volume_value
9455
9456 </p>
9457 </blockquote><p>
9458
9459 </p>
9460 <p>create_instruction =
9461 </p>
9462 <blockquote class="text">
9463 <p>AUDIO_OUTPUT_DEVICE SP string SP key_val_list
9464
9465 </p>
9466 <p>/ AUDIO_OUTPUT_DEVICE SP string
9467
9468 </p>
9469 <p>/ MIDI_INPUT_DEVICE SP string SP key_val_list
9470
9471 </p>
9472 <p>/ MIDI_INPUT_DEVICE SP string
9473
9474 </p>
9475 <p>/ FX_SEND SP sampler_channel SP midi_ctrl
9476
9477 </p>
9478 <p>/ FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name
9479
9480 </p>
9481 </blockquote><p>
9482
9483 </p>
9484 <p>reset_instruction =
9485 </p>
9486 <blockquote class="text">
9487 <p>CHANNEL SP sampler_channel
9488
9489 </p>
9490 </blockquote><p>
9491
9492 </p>
9493 <p>clear_instruction =
9494 </p>
9495 <blockquote class="text">
9496 <p>MIDI_INSTRUMENTS SP midi_map
9497
9498 </p>
9499 <p>/ MIDI_INSTRUMENTS SP ALL
9500
9501 </p>
9502 </blockquote><p>
9503
9504 </p>
9505 <p>find_instruction =
9506 </p>
9507 <blockquote class="text">
9508 <p>DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP query_val_list
9509
9510 </p>
9511 <p>/ DB_INSTRUMENTS SP pathname SP query_val_list
9512
9513 </p>
9514 <p>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP pathname SP query_val_list
9515
9516 </p>
9517 <p>/ DB_INSTRUMENT_DIRECTORIES SP pathname SP query_val_list
9518
9519 </p>
9520 </blockquote><p>
9521
9522 </p>
9523 <p>move_instruction =
9524 </p>
9525 <blockquote class="text">
9526 <p>DB_INSTRUMENT_DIRECTORY SP pathname SP pathname
9527
9528 </p>
9529 <p>/ DB_INSTRUMENT SP pathname SP pathname
9530
9531 </p>
9532 </blockquote><p>
9533
9534 </p>
9535 <p>copy_instruction =
9536 </p>
9537 <blockquote class="text">
9538 <p>DB_INSTRUMENT_DIRECTORY SP pathname SP pathname
9539
9540 </p>
9541 <p>/ DB_INSTRUMENT SP pathname SP pathname
9542
9543 </p>
9544 </blockquote><p>
9545
9546 </p>
9547 <p>destroy_instruction =
9548 </p>
9549 <blockquote class="text">
9550 <p>AUDIO_OUTPUT_DEVICE SP number
9551
9552 </p>
9553 <p>/ MIDI_INPUT_DEVICE SP number
9554
9555 </p>
9556 <p>/ FX_SEND SP sampler_channel SP fx_send_id
9557
9558 </p>
9559 </blockquote><p>
9560
9561 </p>
9562 <p>load_instruction =
9563 </p>
9564 <blockquote class="text">
9565 <p>INSTRUMENT SP load_instr_args
9566
9567 </p>
9568 <p>/ ENGINE SP load_engine_args
9569
9570 </p>
9571 </blockquote><p>
9572
9573 </p>
9574 <p>set_chan_instruction =
9575 </p>
9576 <blockquote class="text">
9577 <p>AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
9578
9579 </p>
9580 <p>/ AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index SP audio_channel_index
9581
9582 </p>
9583 <p>/ AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
9584
9585 </p>
9586 <p>/ MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index SP midi_input_channel_index
9587
9588 </p>
9589 <p>/ MIDI_INPUT_DEVICE SP sampler_channel SP device_index
9590
9591 </p>
9592 <p>/ MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
9593
9594 </p>
9595 <p>/ MIDI_INPUT_CHANNEL SP sampler_channel SP midi_input_channel_index
9596
9597 </p>
9598 <p>/ MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
9599
9600 </p>
9601 <p>/ VOLUME SP sampler_channel SP volume_value
9602
9603 </p>
9604 <p>/ MUTE SP sampler_channel SP boolean
9605
9606 </p>
9607 <p>/ SOLO SP sampler_channel SP boolean
9608
9609 </p>
9610 <p>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP midi_map
9611
9612 </p>
9613 <p>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP NONE
9614
9615 </p>
9616 <p>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP DEFAULT
9617
9618 </p>
9619 </blockquote><p>
9620
9621 </p>
9622 <p>edit_instruction =
9623 </p>
9624 <blockquote class="text">
9625 <p>INSTRUMENT SP sampler_channel
9626
9627 </p>
9628 </blockquote><p>
9629
9630 </p>
9631 <p>modal_arg =
9632 </p>
9633 <blockquote class="text">
9634 <p>/* epsilon (empty argument) */
9635
9636 </p>
9637 <p>/ NON_MODAL SP
9638
9639 </p>
9640 </blockquote><p>
9641
9642 </p>
9643 <p>key_val_list =
9644 </p>
9645 <blockquote class="text">
9646 <p>string '=' param_val_list
9647
9648 </p>
9649 <p>/ key_val_list SP string '=' param_val_list
9650
9651 </p>
9652 </blockquote><p>
9653
9654 </p>
9655 <p>buffer_size_type =
9656 </p>
9657 <blockquote class="text">
9658 <p>BYTES
9659
9660 </p>
9661 <p>/ PERCENTAGE
9662
9663 </p>
9664 </blockquote><p>
9665
9666 </p>
9667 <p>list_instruction =
9668 </p>
9669 <blockquote class="text">
9670 <p>AUDIO_OUTPUT_DEVICES
9671
9672 </p>
9673 <p>/ MIDI_INPUT_DEVICES
9674
9675 </p>
9676 <p>/ CHANNELS
9677
9678 </p>
9679 <p>/ AVAILABLE_ENGINES
9680
9681 </p>
9682 <p>/ AVAILABLE_MIDI_INPUT_DRIVERS
9683
9684 </p>
9685 <p>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
9686
9687 </p>
9688 <p>/ MIDI_INSTRUMENTS SP midi_map
9689
9690 </p>
9691 <p>/ MIDI_INSTRUMENTS SP ALL
9692
9693 </p>
9694 <p>/ MIDI_INSTRUMENT_MAPS
9695
9696 </p>
9697 <p>/ FX_SENDS SP sampler_channel
9698
9699 </p>
9700 <p>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname
9701
9702 </p>
9703 <p>/ DB_INSTRUMENT_DIRECTORIES SP pathname
9704
9705 </p>
9706 <p>/ DB_INSTRUMENTS SP RECURSIVE SP pathname
9707
9708 </p>
9709 <p>/ DB_INSTRUMENTS SP pathname
9710
9711 </p>
9712 </blockquote><p>
9713
9714 </p>
9715 <p>load_instr_args =
9716 </p>
9717 <blockquote class="text">
9718 <p>filename SP instrument_index SP sampler_channel
9719
9720 </p>
9721 <p>/ NON_MODAL SP filename SP instrument_index SP sampler_channel
9722
9723 </p>
9724 </blockquote><p>
9725
9726 </p>
9727 <p>load_engine_args =
9728 </p>
9729 <blockquote class="text">
9730 <p>engine_name SP sampler_channel
9731
9732 </p>
9733 </blockquote><p>
9734
9735 </p>
9736 <p>instr_load_mode =
9737 </p>
9738 <blockquote class="text">
9739 <p>ON_DEMAND
9740
9741 </p>
9742 <p>/ ON_DEMAND_HOLD
9743
9744 </p>
9745 <p>/ PERSISTENT
9746
9747 </p>
9748 </blockquote><p>
9749
9750 </p>
9751 <p>device_index =
9752 </p>
9753 <blockquote class="text">
9754 <p>number
9755
9756 </p>
9757 </blockquote><p>
9758
9759 </p>
9760 <p>audio_channel_index =
9761 </p>
9762 <blockquote class="text">
9763 <p>number
9764
9765 </p>
9766 </blockquote><p>
9767
9768 </p>
9769 <p>audio_output_type_name =
9770 </p>
9771 <blockquote class="text">
9772 <p>string
9773
9774 </p>
9775 </blockquote><p>
9776
9777 </p>
9778 <p>midi_input_port_index =
9779 </p>
9780 <blockquote class="text">
9781 <p>number
9782
9783 </p>
9784 </blockquote><p>
9785
9786 </p>
9787 <p>midi_input_channel_index =
9788 </p>
9789 <blockquote class="text">
9790 <p>number
9791
9792 </p>
9793 <p>/ ALL
9794
9795 </p>
9796 </blockquote><p>
9797
9798 </p>
9799 <p>midi_input_type_name =
9800 </p>
9801 <blockquote class="text">
9802 <p>string
9803
9804 </p>
9805 </blockquote><p>
9806
9807 </p>
9808 <p>midi_map =
9809 </p>
9810 <blockquote class="text">
9811 <p>number
9812
9813 </p>
9814 </blockquote><p>
9815
9816 </p>
9817 <p>midi_bank =
9818 </p>
9819 <blockquote class="text">
9820 <p>number
9821
9822 </p>
9823 </blockquote><p>
9824
9825 </p>
9826 <p>midi_prog =
9827 </p>
9828 <blockquote class="text">
9829 <p>number
9830
9831 </p>
9832 </blockquote><p>
9833
9834 </p>
9835 <p>midi_ctrl =
9836 </p>
9837 <blockquote class="text">
9838 <p>number
9839
9840 </p>
9841 </blockquote><p>
9842
9843 </p>
9844 <p>volume_value =
9845 </p>
9846 <blockquote class="text">
9847 <p>dotnum
9848
9849 </p>
9850 <p>/ number
9851
9852 </p>
9853 </blockquote><p>
9854
9855 </p>
9856 <p>sampler_channel =
9857 </p>
9858 <blockquote class="text">
9859 <p>number
9860
9861 </p>
9862 </blockquote><p>
9863
9864 </p>
9865 <p>instrument_index =
9866 </p>
9867 <blockquote class="text">
9868 <p>number
9869
9870 </p>
9871 </blockquote><p>
9872
9873 </p>
9874 <p>fx_send_id =
9875 </p>
9876 <blockquote class="text">
9877 <p>number
9878
9879 </p>
9880 </blockquote><p>
9881
9882 </p>
9883 <p>engine_name =
9884 </p>
9885 <blockquote class="text">
9886 <p>string
9887
9888 </p>
9889 </blockquote><p>
9890
9891 </p>
9892 <p>pathname =
9893 </p>
9894 <blockquote class="text">
9895 <p>stringval
9896
9897 </p>
9898 </blockquote><p>
9899
9900 </p>
9901 <p>dirname =
9902 </p>
9903 <blockquote class="text">
9904 <p>stringval
9905
9906 </p>
9907 </blockquote><p>
9908
9909 </p>
9910 <p>filename =
9911 </p>
9912 <blockquote class="text">
9913 <p>stringval_escaped
9914
9915 </p>
9916 </blockquote><p>
9917
9918 </p>
9919 <p>map_name =
9920 </p>
9921 <blockquote class="text">
9922 <p>stringval
9923
9924 </p>
9925 </blockquote><p>
9926
9927 </p>
9928 <p>entry_name =
9929 </p>
9930 <blockquote class="text">
9931 <p>stringval
9932
9933 </p>
9934 </blockquote><p>
9935
9936 </p>
9937 <p>fx_send_name =
9938 </p>
9939 <blockquote class="text">
9940 <p>stringval
9941
9942 </p>
9943 </blockquote><p>
9944
9945 </p>
9946 <p>param_val_list =
9947 </p>
9948 <blockquote class="text">
9949 <p>param_val
9950
9951 </p>
9952 <p>/ param_val_list','param_val
9953
9954 </p>
9955 </blockquote><p>
9956
9957 </p>
9958 <p>param_val =
9959 </p>
9960 <blockquote class="text">
9961 <p>string
9962
9963 </p>
9964 <p>/ stringval
9965
9966 </p>
9967 <p>/ number
9968
9969 </p>
9970 <p>/ dotnum
9971
9972 </p>
9973 </blockquote><p>
9974
9975 </p>
9976 <p>query_val_list =
9977 </p>
9978 <blockquote class="text">
9979 <p>string '=' query_val
9980
9981 </p>
9982 <p>/ query_val_list SP string '=' query_val
9983
9984 </p>
9985 </blockquote><p>
9986
9987 </p>
9988 <p>query_val =
9989 </p>
9990 <blockquote class="text">
9991 <p>string
9992
9993 </p>
9994 <p>/ stringval
9995
9996 </p>
9997 </blockquote><p>
9998
9999 </p>
10000 <p>scan_mode =
10001 </p>
10002 <blockquote class="text">
10003 <p>RECURSIVE
10004
10005 </p>
10006 <p>/ NON_RECURSIVE
10007
10008 </p>
10009 <p>/ FLAT
10010
10011 </p>
10012 </blockquote><p>
10013
10014 </p>
10015 <a name="character_set"></a><br /><hr />
10016 <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>
10017 <a name="rfc.section.7.1"></a><h3>7.1.&nbsp;
10018 Character Set and Escape Sequences</h3>
10019
10020 <p>Older versions of this protocol up to and including v1.1 only
10021 supported the standard ASCII character set (ASCII code 0 - 127)
10022 <a class='info' href='#RFC20'>[RFC20]<span> (</span><span class='info'>UCLA, &ldquo;ASCII format for Network Interchange,&rdquo; 1969.</span><span>)</span></a>, all younger versions of this protocol
10023 however support the Extended ASCII character set (ASCII code
10024 0 - 255). The same group of younger protocols also support
10025 escape sequences, but only for certain, explicitly declared
10026 parts of the protocol. The supported escape sequences are
10027 defined as follows:
10028 </p><table class="full" align="center" border="0" cellpadding="2" cellspacing="2">
10029 <col align="left"><col align="left">
10030 <tr><th align="left">ASCII Character Sequence</th><th align="left">Translated into (Name)</th></tr>
10031 <tr>
10032 <td align="left">\n</td>
10033 <td align="left">new line</td>
10034 </tr>
10035 <tr>
10036 <td align="left">\r</td>
10037 <td align="left">carriage return</td>
10038 </tr>
10039 <tr>
10040 <td align="left">\f</td>
10041 <td align="left">form feed</td>
10042 </tr>
10043 <tr>
10044 <td align="left">\t</td>
10045 <td align="left">horizontal tab</td>
10046 </tr>
10047 <tr>
10048 <td align="left">\v</td>
10049 <td align="left">vertical tab</td>
10050 </tr>
10051 <tr>
10052 <td align="left">\'</td>
10053 <td align="left">apostrophe</td>
10054 </tr>
10055 <tr>
10056 <td align="left">\"</td>
10057 <td align="left">quotation mark</td>
10058 </tr>
10059 <tr>
10060 <td align="left">\\</td>
10061 <td align="left">backslash</td>
10062 </tr>
10063 <tr>
10064 <td align="left">\OOO</td>
10065 <td align="left">three digit octal ASCII code of the character</td>
10066 </tr>
10067 <tr>
10068 <td align="left">\xHH</td>
10069 <td align="left">two digit hex ASCII code of the character</td>
10070 </tr>
10071 </table>
10072
10073 <p>Notice: due to the transition of certain parts of the
10074 protocol which now support escape sequences, a slight backward
10075 incompatibility to protocols version v1.1 and younger has been
10076 introduced. The only difference is that in parts of the protocol
10077 where escape characters are now supported, a backslash characters
10078 MUST be escaped as well (that is as double backslash), whereas
10079 in the old versions a single backslash was sufficient.
10080 </p>
10081 <a name="events"></a><br /><hr />
10082 <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>
10083 <a name="rfc.section.8"></a><h3>8.&nbsp;
10084 Events</h3>
10085
10086 <p>This chapter will describe all currently defined events supported by LinuxSampler.
10087 </p>
10088 <a name="SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT"></a><br /><hr />
10089 <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>
10090 <a name="rfc.section.8.1"></a><h3>8.1.&nbsp;
10091 Number of audio output devices changed</h3>
10092
10093 <p>Client may want to be notified when the total number of audio output devices on the
10094 back-end changes by issuing the following command:
10095 </p>
10096 <p>
10097 </p>
10098 <blockquote class="text">
10099 <p>SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT
10100 </p>
10101 </blockquote><p>
10102
10103 </p>
10104 <p>Server will start sending the following notification messages:
10105 </p>
10106 <p>
10107 </p>
10108 <blockquote class="text">
10109 <p>"NOTIFY:AUDIO_OUTPUT_DEVICE_COUNT:&lt;devices&gt;"
10110 </p>
10111 </blockquote><p>
10112
10113 </p>
10114 <p>where &lt;devices&gt; will be replaced by the new number
10115 of audio output devices.
10116 </p>
10117 <a name="SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO"></a><br /><hr />
10118 <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>
10119 <a name="rfc.section.8.2"></a><h3>8.2.&nbsp;
10120 Audio output device's settings changed</h3>
10121
10122 <p>Client may want to be notified when changes were made to audio output devices on the
10123 back-end by issuing the following command:
10124 </p>
10125 <p>
10126 </p>
10127 <blockquote class="text">
10128 <p>SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO
10129 </p>
10130 </blockquote><p>
10131
10132 </p>
10133 <p>Server will start sending the following notification messages:
10134 </p>
10135 <p>
10136 </p>
10137 <blockquote class="text">
10138 <p>"NOTIFY:AUDIO_OUTPUT_DEVICE_INFO:&lt;device-id&gt;"
10139 </p>
10140 </blockquote><p>
10141
10142 </p>
10143 <p>where &lt;device-id&gt; will be replaced by the numerical ID of the audio output device,
10144 which settings has been changed. The front-end will have to send
10145 the respective command to actually get the audio output device info. Because these messages
10146 will be triggered by LSCP commands issued by other clients rather than real
10147 time events happening on the server, it is believed that an empty notification
10148 message is sufficient here.
10149 </p>
10150 <a name="SUBSCRIBE MIDI_INPUT_DEVICE_COUNT"></a><br /><hr />
10151 <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>
10152 <a name="rfc.section.8.3"></a><h3>8.3.&nbsp;
10153 Number of MIDI input devices changed</h3>
10154
10155 <p>Client may want to be notified when the total number of MIDI input devices on the
10156 back-end changes by issuing the following command:
10157 </p>
10158 <p>
10159 </p>
10160 <blockquote class="text">
10161 <p>SUBSCRIBE MIDI_INPUT_DEVICE_COUNT
10162 </p>
10163 </blockquote><p>
10164
10165 </p>
10166 <p>Server will start sending the following notification messages:
10167 </p>
10168 <p>
10169 </p>
10170 <blockquote class="text">
10171 <p>"NOTIFY:MIDI_INPUT_DEVICE_COUNT:&lt;devices&gt;"
10172 </p>
10173 </blockquote><p>
10174
10175 </p>
10176 <p>where &lt;devices&gt; will be replaced by the new number
10177 of MIDI input devices.
10178 </p>
10179 <a name="SUBSCRIBE MIDI_INPUT_DEVICE_INFO"></a><br /><hr />
10180 <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>
10181 <a name="rfc.section.8.4"></a><h3>8.4.&nbsp;
10182 MIDI input device's settings changed</h3>
10183
10184 <p>Client may want to be notified when changes were made to MIDI input devices on the
10185 back-end by issuing the following command:
10186 </p>
10187 <p>
10188 </p>
10189 <blockquote class="text">
10190 <p>SUBSCRIBE MIDI_INPUT_DEVICE_INFO
10191 </p>
10192 </blockquote><p>
10193
10194 </p>
10195 <p>Server will start sending the following notification messages:
10196 </p>
10197 <p>
10198 </p>
10199 <blockquote class="text">
10200 <p>"NOTIFY:MIDI_INPUT_DEVICE_INFO:&lt;device-id&gt;"
10201 </p>
10202 </blockquote><p>
10203
10204 </p>
10205 <p>where &lt;device-id&gt; will be replaced by the numerical ID of the MIDI input device,
10206 which settings has been changed. The front-end will have to send
10207 the respective command to actually get the MIDI input device info. Because these messages
10208 will be triggered by LSCP commands issued by other clients rather than real
10209 time events happening on the server, it is believed that an empty notification
10210 message is sufficient here.
10211 </p>
10212 <a name="SUBSCRIBE CHANNEL_COUNT"></a><br /><hr />
10213 <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>
10214 <a name="rfc.section.8.5"></a><h3>8.5.&nbsp;
10215 Number of sampler channels changed</h3>
10216
10217 <p>Client may want to be notified when the total number of channels on the
10218 back-end changes by issuing the following command:
10219 </p>
10220 <p>
10221 </p>
10222 <blockquote class="text">
10223 <p>SUBSCRIBE CHANNEL_COUNT
10224 </p>
10225 </blockquote><p>
10226
10227 </p>
10228 <p>Server will start sending the following notification messages:
10229 </p>
10230 <p>
10231 </p>
10232 <blockquote class="text">
10233 <p>"NOTIFY:CHANNEL_COUNT:&lt;channels&gt;"
10234 </p>
10235 </blockquote><p>
10236
10237 </p>
10238 <p>where &lt;channels&gt; will be replaced by the new number
10239 of sampler channels.
10240 </p>
10241 <a name="SUBSCRIBE VOICE_COUNT"></a><br /><hr />
10242 <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>
10243 <a name="rfc.section.8.6"></a><h3>8.6.&nbsp;
10244 Number of active voices changed</h3>
10245
10246 <p>Client may want to be notified when the number of voices on the
10247 back-end changes by issuing the following command:
10248 </p>
10249 <p>
10250 </p>
10251 <blockquote class="text">
10252 <p>SUBSCRIBE VOICE_COUNT
10253 </p>
10254 </blockquote><p>
10255
10256 </p>
10257 <p>Server will start sending the following notification messages:
10258 </p>
10259 <p>
10260 </p>
10261 <blockquote class="text">
10262 <p>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;"
10263 </p>
10264 </blockquote><p>
10265
10266 </p>
10267 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
10268 voice count change occurred and &lt;voices&gt; by the new number of
10269 active voices on that channel.
10270 </p>
10271 <a name="SUBSCRIBE STREAM_COUNT"></a><br /><hr />
10272 <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>
10273 <a name="rfc.section.8.7"></a><h3>8.7.&nbsp;
10274 Number of active disk streams changed</h3>
10275
10276 <p>Client may want to be notified when the number of streams on the back-end
10277 changes by issuing the following command: SUBSCRIBE STREAM_COUNT
10278 </p>
10279 <p>
10280 </p>
10281 <blockquote class="text">
10282 <p>SUBSCRIBE STREAM_COUNT
10283 </p>
10284 </blockquote><p>
10285
10286 </p>
10287 <p>Server will start sending the following notification messages:
10288 </p>
10289 <p>
10290 </p>
10291 <blockquote class="text">
10292 <p>"NOTIFY:STREAM_COUNT:&lt;sampler-channel&gt; &lt;streams&gt;"
10293 </p>
10294 </blockquote><p>
10295
10296 </p>
10297 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
10298 stream count change occurred and &lt;streams&gt; by the new number of
10299 active disk streams on that channel.
10300 </p>
10301 <a name="SUBSCRIBE BUFFER_FILL"></a><br /><hr />
10302 <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>
10303 <a name="rfc.section.8.8"></a><h3>8.8.&nbsp;
10304 Disk stream buffer fill state changed</h3>
10305
10306 <p>Client may want to be notified when the buffer fill state of a disk stream
10307 on the back-end changes by issuing the following command:
10308 </p>
10309 <p>
10310 </p>
10311 <blockquote class="text">
10312 <p>SUBSCRIBE BUFFER_FILL
10313 </p>
10314 </blockquote><p>
10315
10316 </p>
10317 <p>Server will start sending the following notification messages:
10318 </p>
10319 <p>
10320 </p>
10321 <blockquote class="text">
10322 <p>"NOTIFY:BUFFER_FILL:&lt;sampler-channel&gt; &lt;fill-data&gt;"
10323 </p>
10324 </blockquote><p>
10325
10326 </p>
10327 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
10328 buffer fill state change occurred on and &lt;fill-data&gt; will be replaced by the
10329 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>
10330 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.
10331 </p>
10332 <a name="SUBSCRIBE CHANNEL_INFO"></a><br /><hr />
10333 <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>
10334 <a name="rfc.section.8.9"></a><h3>8.9.&nbsp;
10335 Channel information changed</h3>
10336
10337 <p>Client may want to be notified when changes were made to sampler channels on the
10338 back-end by issuing the following command:
10339 </p>
10340 <p>
10341 </p>
10342 <blockquote class="text">
10343 <p>SUBSCRIBE CHANNEL_INFO
10344 </p>
10345 </blockquote><p>
10346
10347 </p>
10348 <p>Server will start sending the following notification messages:
10349 </p>
10350 <p>
10351 </p>
10352 <blockquote class="text">
10353 <p>"NOTIFY:CHANNEL_INFO:&lt;sampler-channel&gt;"
10354 </p>
10355 </blockquote><p>
10356
10357 </p>
10358 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
10359 channel info change occurred. The front-end will have to send
10360 the respective command to actually get the channel info. Because these messages
10361 will be triggered by LSCP commands issued by other clients rather than real
10362 time events happening on the server, it is believed that an empty notification
10363 message is sufficient here.
10364 </p>
10365 <a name="SUBSCRIBE FX_SEND_COUNT"></a><br /><hr />
10366 <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>
10367 <a name="rfc.section.8.10"></a><h3>8.10.&nbsp;
10368 Number of effect sends changed</h3>
10369
10370 <p>Client may want to be notified when the number of effect sends on
10371 a particular sampler channel is changed by issuing the following command:
10372 </p>
10373 <p>
10374 </p>
10375 <blockquote class="text">
10376 <p>SUBSCRIBE FX_SEND_COUNT
10377 </p>
10378 </blockquote><p>
10379
10380 </p>
10381 <p>Server will start sending the following notification messages:
10382 </p>
10383 <p>
10384 </p>
10385 <blockquote class="text">
10386 <p>"NOTIFY:FX_SEND_COUNT:&lt;channel-id&gt; &lt;fx-sends&gt;"
10387 </p>
10388 </blockquote><p>
10389
10390 </p>
10391 <p>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
10392 channel, on which the effect sends number is changed and &lt;fx-sends&gt; will
10393 be replaced by the new number of effect sends on that channel.
10394 </p>
10395 <a name="SUBSCRIBE FX_SEND_INFO"></a><br /><hr />
10396 <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>
10397 <a name="rfc.section.8.11"></a><h3>8.11.&nbsp;
10398 Effect send information changed</h3>
10399
10400 <p>Client may want to be notified when changes were made to effect sends on a
10401 a particular sampler channel by issuing the following command:
10402 </p>
10403 <p>
10404 </p>
10405 <blockquote class="text">
10406 <p>SUBSCRIBE FX_SEND_INFO
10407 </p>
10408 </blockquote><p>
10409
10410 </p>
10411 <p>Server will start sending the following notification messages:
10412 </p>
10413 <p>
10414 </p>
10415 <blockquote class="text">
10416 <p>"NOTIFY:FX_SEND_INFO:&lt;channel-id&gt; &lt;fx-send-id&gt;"
10417 </p>
10418 </blockquote><p>
10419
10420 </p>
10421 <p>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
10422 channel, on which an effect send entity is changed and &lt;fx-send-id&gt; will
10423 be replaced by the numerical ID of the changed effect send.
10424 </p>
10425 <a name="SUBSCRIBE TOTAL_VOICE_COUNT"></a><br /><hr />
10426 <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>
10427 <a name="rfc.section.8.12"></a><h3>8.12.&nbsp;
10428 Total number of active voices changed</h3>
10429
10430 <p>Client may want to be notified when the total number of voices on the
10431 back-end changes by issuing the following command:
10432 </p>
10433 <p>
10434 </p>
10435 <blockquote class="text">
10436 <p>SUBSCRIBE TOTAL_VOICE_COUNT
10437 </p>
10438 </blockquote><p>
10439
10440 </p>
10441 <p>Server will start sending the following notification messages:
10442 </p>
10443 <p>
10444 </p>
10445 <blockquote class="text">
10446 <p>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;"
10447 </p>
10448 </blockquote><p>
10449
10450 </p>
10451 <p>where &lt;voices&gt; will be replaced by the new number of
10452 all currently active voices.
10453 </p>
10454 <a name="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT"></a><br /><hr />
10455 <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>
10456 <a name="rfc.section.8.13"></a><h3>8.13.&nbsp;
10457 Number of MIDI instrument maps changed</h3>
10458
10459 <p>Client may want to be notified when the number of MIDI instrument maps on the
10460 back-end changes by issuing the following command:
10461 </p>
10462 <p>
10463 </p>
10464 <blockquote class="text">
10465 <p>SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT
10466 </p>
10467 </blockquote><p>
10468
10469 </p>
10470 <p>Server will start sending the following notification messages:
10471 </p>
10472 <p>
10473 </p>
10474 <blockquote class="text">
10475 <p>"NOTIFY:MIDI_INSTRUMENT_MAP_COUNT:&lt;maps&gt;"
10476 </p>
10477 </blockquote><p>
10478
10479 </p>
10480 <p>where &lt;maps&gt; will be replaced by the new number
10481 of MIDI instrument maps.
10482 </p>
10483 <a name="SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO"></a><br /><hr />
10484 <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>
10485 <a name="rfc.section.8.14"></a><h3>8.14.&nbsp;
10486 MIDI instrument map information changed</h3>
10487
10488 <p>Client may want to be notified when changes were made to MIDI instrument maps on the
10489 back-end by issuing the following command:
10490 </p>
10491 <p>
10492 </p>
10493 <blockquote class="text">
10494 <p>SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO
10495 </p>
10496 </blockquote><p>
10497
10498 </p>
10499 <p>Server will start sending the following notification messages:
10500 </p>
10501 <p>
10502 </p>
10503 <blockquote class="text">
10504 <p>"NOTIFY:MIDI_INSTRUMENT_MAP_INFO:&lt;map-id&gt;"
10505 </p>
10506 </blockquote><p>
10507
10508 </p>
10509 <p>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
10510 for which information changes occurred. The front-end will have to send
10511 the respective command to actually get the MIDI instrument map info. Because these messages
10512 will be triggered by LSCP commands issued by other clients rather than real
10513 time events happening on the server, it is believed that an empty notification
10514 message is sufficient here.
10515 </p>
10516 <a name="SUBSCRIBE MIDI_INSTRUMENT_COUNT"></a><br /><hr />
10517 <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>
10518 <a name="rfc.section.8.15"></a><h3>8.15.&nbsp;
10519 Number of MIDI instruments changed</h3>
10520
10521 <p>Client may want to be notified when the number of MIDI instrument maps on the
10522 back-end changes by issuing the following command:
10523 </p>
10524 <p>
10525 </p>
10526 <blockquote class="text">
10527 <p>SUBSCRIBE MIDI_INSTRUMENT_COUNT
10528 </p>
10529 </blockquote><p>
10530
10531 </p>
10532 <p>Server will start sending the following notification messages:
10533 </p>
10534 <p>
10535 </p>
10536 <blockquote class="text">
10537 <p>"NOTIFY:MIDI_INSTRUMENT_COUNT:&lt;map-id&gt; &lt;instruments&gt;"
10538 </p>
10539 </blockquote><p>
10540
10541 </p>
10542 <p>where &lt;map-id&gt; is the numerical ID of the MIDI instrument map, in which
10543 the nuber of instruments has changed and &lt;instruments&gt; will be replaced by
10544 the new number of MIDI instruments in the specified map.
10545 </p>
10546 <a name="SUBSCRIBE MIDI_INSTRUMENT_INFO"></a><br /><hr />
10547 <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>
10548 <a name="rfc.section.8.16"></a><h3>8.16.&nbsp;
10549 MIDI instrument information changed</h3>
10550
10551 <p>Client may want to be notified when changes were made to MIDI instruments on the
10552 back-end by issuing the following command:
10553 </p>
10554 <p>
10555 </p>
10556 <blockquote class="text">
10557 <p>SUBSCRIBE MIDI_INSTRUMENT_INFO
10558 </p>
10559 </blockquote><p>
10560
10561 </p>
10562 <p>Server will start sending the following notification messages:
10563 </p>
10564 <p>
10565 </p>
10566 <blockquote class="text">
10567 <p>"NOTIFY:MIDI_INSTRUMENT_INFO:&lt;map-id&gt; &lt;bank&gt; &lt;program&gt;"
10568 </p>
10569 </blockquote><p>
10570
10571 </p>
10572 <p>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
10573 in which a MIDI instrument is changed. &lt;bank&gt; and &lt;program&gt; specifies
10574 the location of the changed MIDI instrument in the map. The front-end will have to send
10575 the respective command to actually get the MIDI instrument info. Because these messages
10576 will be triggered by LSCP commands issued by other clients rather than real
10577 time events happening on the server, it is believed that an empty notification
10578 message is sufficient here.
10579 </p>
10580 <a name="SUBSCRIBE GLOBAL_INFO"></a><br /><hr />
10581 <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>
10582 <a name="rfc.section.8.17"></a><h3>8.17.&nbsp;
10583 Global settings changed</h3>
10584
10585 <p>Client may want to be notified when changes to the global settings
10586 of the sampler were made by issuing the following command:
10587 </p>
10588 <p>
10589 </p>
10590 <blockquote class="text">
10591 <p>SUBSCRIBE GLOBAL_INFO
10592 </p>
10593 </blockquote><p>
10594
10595 </p>
10596 <p>Server will start sending the following types of notification messages:
10597 </p>
10598 <p>
10599 </p>
10600 <blockquote class="text">
10601 <p>"NOTIFY:GLOBAL_INFO:VOLUME &lt;volume&gt;" - Notifies that the
10602 golbal volume of the sampler is changed, where &lt;volume&gt; will be
10603 replaced by the optional dotted floating point value, reflecting the
10604 new global volume parameter.
10605 </p>
10606 </blockquote><p>
10607
10608 </p>
10609 <a name="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT"></a><br /><hr />
10610 <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>
10611 <a name="rfc.section.8.18"></a><h3>8.18.&nbsp;
10612 Number of database instrument directories changed</h3>
10613
10614 <p>Client may want to be notified when the number of instrument
10615 directories in a particular directory in the instruments database
10616 is changed by issuing the following command:
10617 </p>
10618 <p>
10619 </p>
10620 <blockquote class="text">
10621 <p>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT
10622 </p>
10623 </blockquote><p>
10624
10625 </p>
10626 <p>Server will start sending the following notification messages:
10627 </p>
10628 <p>
10629 </p>
10630 <blockquote class="text">
10631 <p>"NOTIFY:DB_INSTRUMENT_DIRECTORY_COUNT:&lt;dir-path&gt;"
10632 </p>
10633 </blockquote><p>
10634
10635 </p>
10636 <p>where &lt;dir-path&gt; will be replaced by the absolute path
10637 name of the directory in the instruments database,
10638 in which the number of directories is changed.
10639 </p>
10640 <p>Note that when a non-empty directory is removed, this event
10641 is not sent for the subdirectories in that directory.
10642 </p>
10643 <a name="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO"></a><br /><hr />
10644 <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>
10645 <a name="rfc.section.8.19"></a><h3>8.19.&nbsp;
10646 Database instrument directory information changed</h3>
10647
10648 <p>Client may want to be notified when changes were made to directories
10649 in the instruments database by issuing the following command:
10650 </p>
10651 <p>
10652 </p>
10653 <blockquote class="text">
10654 <p>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO
10655 </p>
10656 </blockquote><p>
10657
10658 </p>
10659 <p>Server will start sending the following notification messages:
10660 </p>
10661 <p>
10662 </p>
10663 <blockquote class="text">
10664 <p>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:&lt;dir-path&gt;"
10665 </p>
10666 </blockquote><p>
10667
10668 </p>
10669 <p>where &lt;dir-path&gt; will be replaced by the absolute path name
10670 of the directory, for which information changes occurred. The front-end will have to send
10671 the respective command to actually get the updated directory info. Because these messages
10672 will be triggered by LSCP commands issued by other clients rather than real
10673 time events happening on the server, it is believed that an empty notification
10674 message is sufficient here.
10675 </p>
10676 <p>
10677 </p>
10678 <blockquote class="text">
10679 <p>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:NAME &lt;old-dir-path&gt; &lt;new-name&gt;"
10680 </p>
10681 </blockquote><p>
10682
10683 </p>
10684 <p>where &lt;old-dir-path&gt; is the old absolute path name of the directory
10685 (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
10686 the new name of the directory, encapsulated into apostrophes.
10687 </p>
10688 <a name="SUBSCRIBE DB_INSTRUMENT_COUNT"></a><br /><hr />
10689 <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>
10690 <a name="rfc.section.8.20"></a><h3>8.20.&nbsp;
10691 Number of database instruments changed</h3>
10692
10693 <p>Client may want to be notified when the number of instruments
10694 in a particular directory in the instruments database
10695 is changed by issuing the following command:
10696 </p>
10697 <p>
10698 </p>
10699 <blockquote class="text">
10700 <p>SUBSCRIBE DB_INSTRUMENT_COUNT
10701 </p>
10702 </blockquote><p>
10703
10704 </p>
10705 <p>Server will start sending the following notification messages:
10706 </p>
10707 <p>
10708 </p>
10709 <blockquote class="text">
10710 <p>"NOTIFY:DB_INSTRUMENT_COUNT:&lt;dir-path&gt;"
10711 </p>
10712 </blockquote><p>
10713
10714 </p>
10715 <p>where &lt;dir-path&gt; will be replaced by the absolute path
10716 name of the directory in the instruments database,
10717 in which the number of instruments is changed.
10718 </p>
10719 <p>Note that when a non-empty directory is removed, this event
10720 is not sent for the instruments in that directory.
10721 </p>
10722 <a name="SUBSCRIBE DB_INSTRUMENT_INFO"></a><br /><hr />
10723 <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>
10724 <a name="rfc.section.8.21"></a><h3>8.21.&nbsp;
10725 Database instrument information changed</h3>
10726
10727 <p>Client may want to be notified when changes were made to instruments
10728 in the instruments database by issuing the following command:
10729 </p>
10730 <p>
10731 </p>
10732 <blockquote class="text">
10733 <p>SUBSCRIBE DB_INSTRUMENT_INFO
10734 </p>
10735 </blockquote><p>
10736
10737 </p>
10738 <p>Server will start sending the following notification messages:
10739 </p>
10740 <p>
10741 </p>
10742 <blockquote class="text">
10743 <p>"NOTIFY:DB_INSTRUMENT_INFO:&lt;instr-path&gt;"
10744 </p>
10745 </blockquote><p>
10746
10747 </p>
10748 <p>where &lt;instr-path&gt; will be replaced by the absolute path name
10749 of the instrument, which settings are changed. The front-end will have to send
10750 the respective command to actually get the updated directory info. Because these messages
10751 will be triggered by LSCP commands issued by other clients rather than real
10752 time events happening on the server, it is believed that an empty notification
10753 message is sufficient here.
10754 </p>
10755 <p>
10756 </p>
10757 <blockquote class="text">
10758 <p>"NOTIFY:DB_INSTRUMENT_INFO:NAME &lt;old-instr-path&gt; &lt;new-name&gt;"
10759 </p>
10760 </blockquote><p>
10761
10762 </p>
10763 <p>where &lt;old-instr-path&gt; is the old absolute path name of the instrument
10764 (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
10765 the new name of the instrument, encapsulated into apostrophes.
10766 </p>
10767 <a name="SUBSCRIBE DB_INSTRUMENTS_JOB_INFO"></a><br /><hr />
10768 <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>
10769 <a name="rfc.section.8.22"></a><h3>8.22.&nbsp;
10770 Database job status information changed</h3>
10771
10772 <p>Client may want to be notified when the status of particular database
10773 instruments job is changed by issuing the following command:
10774 </p>
10775 <p>
10776 </p>
10777 <blockquote class="text">
10778 <p>SUBSCRIBE DB_INSTRUMENTS_JOB_INFO
10779 </p>
10780 </blockquote><p>
10781
10782 </p>
10783 <p>Server will start sending the following notification messages:
10784 </p>
10785 <p>
10786 </p>
10787 <blockquote class="text">
10788 <p>"NOTIFY:DB_INSTRUMENTS_JOB_INFO:&lt;job-id&gt;"
10789 </p>
10790 </blockquote><p>
10791
10792 </p>
10793 <p>where &lt;job-id&gt; will be replaced by the numerical ID of the job,
10794 which status is changed. The front-end will have to send the respective
10795 command to actually get the status info. Because these messages
10796 will be triggered by LSCP commands issued by other clients rather than real
10797 time events happening on the server, it is believed that an empty notification
10798 message is sufficient here.
10799 </p>
10800 <a name="SUBSCRIBE MISCELLANEOUS"></a><br /><hr />
10801 <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>
10802 <a name="rfc.section.8.23"></a><h3>8.23.&nbsp;
10803 Miscellaneous and debugging events</h3>
10804
10805 <p>Client may want to be notified of miscellaneous and debugging events occurring at
10806 the server by issuing the following command:
10807 </p>
10808 <p>
10809 </p>
10810 <blockquote class="text">
10811 <p>SUBSCRIBE MISCELLANEOUS
10812 </p>
10813 </blockquote><p>
10814
10815 </p>
10816 <p>Server will start sending the following notification messages:
10817 </p>
10818 <p>
10819 </p>
10820 <blockquote class="text">
10821 <p>"NOTIFY:MISCELLANEOUS:&lt;string&gt;"
10822 </p>
10823 </blockquote><p>
10824
10825 </p>
10826 <p>where &lt;string&gt; will be replaced by whatever data server
10827 wants to send to the client. Client MAY display this data to the
10828 user AS IS to facilitate debugging.
10829 </p>
10830 <a name="anchor14"></a><br /><hr />
10831 <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>
10832 <a name="rfc.section.9"></a><h3>9.&nbsp;
10833 Security Considerations</h3>
10834
10835 <p>As there is so far no method of authentication and authorization
10836 defined and so not required for a client applications to succeed to
10837 connect, running LinuxSampler might be a security risk for the host
10838 system the LinuxSampler instance is running on.
10839 </p>
10840 <a name="anchor15"></a><br /><hr />
10841 <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>
10842 <a name="rfc.section.10"></a><h3>10.&nbsp;
10843 Acknowledgments</h3>
10844
10845 <p>This document has benefited greatly from the comments of the
10846 following people, discussed on the LinuxSampler developer's mailing
10847 list:
10848 </p>
10849 <p>
10850 </p>
10851 <blockquote class="text">
10852 <p>Rui Nuno Capela
10853 </p>
10854 <p>Vladimir Senkov
10855 </p>
10856 <p>Mark Knecht
10857 </p>
10858 <p>Grigor Iliev
10859 </p>
10860 </blockquote><p>
10861
10862 </p>
10863 <a name="rfc.references1"></a><br /><hr />
10864 <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>
10865 <h3>11.&nbsp;References</h3>
10866 <table width="99%" border="0">
10867 <tr><td class="author-text" valign="top"><a name="RFC20">[RFC20]</a></td>
10868 <td class="author-text">UCLA, &ldquo;<a href="ftp://ftp.isi.edu/in-notes/rfc20.txt">ASCII format for Network Interchange</a>,&rdquo; RFC&nbsp;20, 1969.</td></tr>
10869 <tr><td class="author-text" valign="top"><a name="RFC2119">[RFC2119]</a></td>
10870 <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>
10871 <tr><td class="author-text" valign="top"><a name="RFC2234">[RFC2234]</a></td>
10872 <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>
10873 <tr><td class="author-text" valign="top"><a name="RFC793">[RFC793]</a></td>
10874 <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>
10875 </table>
10876
10877 <a name="rfc.authors"></a><br /><hr />
10878 <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>
10879 <h3>Author's Address</h3>
10880 <table width="99%" border="0" cellpadding="0" cellspacing="0">
10881 <tr><td class="author-text">&nbsp;</td>
10882 <td class="author-text">C.
10883 Schoenebeck</td></tr>
10884 <tr><td class="author-text">&nbsp;</td>
10885 <td class="author-text">Interessengemeinschaft Software Engineering e. V.</td></tr>
10886 <tr><td class="author-text">&nbsp;</td>
10887 <td class="author-text">Max-Planck-Str. 39</td></tr>
10888 <tr><td class="author-text">&nbsp;</td>
10889 <td class="author-text">74081 Heilbronn</td></tr>
10890 <tr><td class="author-text">&nbsp;</td>
10891 <td class="author-text">Germany</td></tr>
10892 <tr><td class="author" align="right">Email:&nbsp;</td>
10893 <td class="author-text"><a href="mailto:schoenebeck at software minus engineering dot org">schoenebeck at software minus engineering dot org</a></td></tr>
10894 </table>
10895 <a name="rfc.copyright"></a><br /><hr />
10896 <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>
10897 <h3>Full Copyright Statement</h3>
10898 <p class='copyright'>
10899 Copyright &copy; The IETF Trust (2007).</p>
10900 <p class='copyright'>
10901 This document is subject to the rights,
10902 licenses and restrictions contained in BCP&nbsp;78,
10903 and except as set forth therein,
10904 the authors retain all their rights.</p>
10905 <p class='copyright'>
10906 This document and the information contained herein are provided
10907 on an &ldquo;AS IS&rdquo; basis and THE CONTRIBUTOR,
10908 THE ORGANIZATION HE/SHE REPRESENTS
10909 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST
10910 AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES,
10911 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT
10912 THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY
10913 IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
10914 PURPOSE.</p>
10915 <h3>Intellectual Property</h3>
10916 <p class='copyright'>
10917 The IETF takes no position regarding the validity or scope of any
10918 Intellectual Property Rights or other rights that might be claimed
10919 to pertain to the implementation or use of the technology
10920 described in this document or the extent to which any license
10921 under such rights might or might not be available; nor does it
10922 represent that it has made any independent effort to identify any
10923 such rights.
10924 Information on the procedures with respect to
10925 rights in RFC documents can be found in BCP&nbsp;78 and BCP&nbsp;79.</p>
10926 <p class='copyright'>
10927 Copies of IPR disclosures made to the IETF Secretariat and any
10928 assurances of licenses to be made available,
10929 or the result of an attempt made to obtain a general license or
10930 permission for the use of such proprietary rights by implementers or
10931 users of this specification can be obtained from the IETF on-line IPR
10932 repository at <a href='http://www.ietf.org/ipr'>http://www.ietf.org/ipr</a>.</p>
10933 <p class='copyright'>
10934 The IETF invites any interested party to bring to its attention
10935 any copyrights,
10936 patents or patent applications,
10937 or other
10938 proprietary rights that may cover technology that may be required
10939 to implement this standard.
10940 Please address the information to the IETF at <a href='mailto:ietf-ipr@ietf.org'>ietf-ipr@ietf.org</a>.</p>
10941 <h3>Acknowledgment</h3>
10942 <p class='copyright'>
10943 Funding for the RFC Editor function is provided by
10944 the IETF Administrative Support Activity (IASA).</p>
10945 </body></html>

  ViewVC Help
Powered by ViewVC