/[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 1400 - (show annotations) (download) (as text)
Thu Oct 11 18:59:34 2007 UTC (16 years, 5 months ago) by schoenebeck
File MIME type: text/html
File size: 397871 byte(s)
* listed LSCP commands which may return escape sequences
  in their response

1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <html lang="en"><head><title>LinuxSampler Control Protocol (draft)</title>
3 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
4 <meta name="description" content="LinuxSampler Control Protocol (draft)">
5 <meta name="keywords" content="LSCP">
6 <meta name="generator" content="xml2rfc v1.32 (http://xml.resource.org/)">
7 <style type='text/css'><!--
8 body {
9 font-family: verdana, charcoal, helvetica, arial, sans-serif;
10 font-size: small; color: #000; background-color: #FFF;
11 margin: 2em;
12 }
13 h1, h2, h3, h4, h5, h6 {
14 font-family: helvetica, monaco, "MS Sans Serif", arial, sans-serif;
15 font-weight: bold; font-style: normal;
16 }
17 h1 { color: #900; background-color: transparent; text-align: right; }
18 h3 { color: #333; background-color: transparent; }
19
20 td.RFCbug {
21 font-size: x-small; text-decoration: none;
22 width: 30px; height: 30px; padding-top: 2px;
23 text-align: justify; vertical-align: middle;
24 background-color: #000;
25 }
26 td.RFCbug span.RFC {
27 font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
28 font-weight: bold; color: #666;
29 }
30 td.RFCbug span.hotText {
31 font-family: charcoal, monaco, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
32 font-weight: normal; text-align: center; color: #FFF;
33 }
34
35 table.TOCbug { width: 30px; height: 15px; }
36 td.TOCbug {
37 text-align: center; width: 30px; height: 15px;
38 color: #FFF; background-color: #900;
39 }
40 td.TOCbug a {
41 font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, sans-serif;
42 font-weight: bold; font-size: x-small; text-decoration: none;
43 color: #FFF; background-color: transparent;
44 }
45
46 td.header {
47 font-family: arial, helvetica, sans-serif; font-size: x-small;
48 vertical-align: top; width: 33%;
49 color: #FFF; background-color: #666;
50 }
51 td.author { font-weight: bold; font-size: x-small; margin-left: 4em; }
52 td.author-text { font-size: x-small; }
53
54 /* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */
55 a.info {
56 /* This is the key. */
57 position: relative;
58 z-index: 24;
59 text-decoration: none;
60 }
61 a.info:hover {
62 z-index: 25;
63 color: #FFF; background-color: #900;
64 }
65 a.info span { display: none; }
66 a.info:hover span.info {
67 /* The span will display just on :hover state. */
68 display: block;
69 position: absolute;
70 font-size: smaller;
71 top: 2em; left: -5em; width: 15em;
72 padding: 2px; border: 1px solid #333;
73 color: #900; background-color: #EEE;
74 text-align: left;
75 }
76
77 a { font-weight: bold; }
78 a:link { color: #900; background-color: transparent; }
79 a:visited { color: #633; background-color: transparent; }
80 a:active { color: #633; background-color: transparent; }
81
82 p { margin-left: 2em; margin-right: 2em; }
83 p.copyright { font-size: x-small; }
84 p.toc { font-size: small; font-weight: bold; margin-left: 3em; }
85 table.toc { margin: 0 0 0 3em; padding: 0; border: 0; vertical-align: text-top; }
86 td.toc { font-size: small; font-weight: bold; vertical-align: text-top; }
87
88 ol.text { margin-left: 2em; margin-right: 2em; }
89 ul.text { margin-left: 2em; margin-right: 2em; }
90 li { margin-left: 3em; }
91
92 /* RFC-2629 <spanx>s and <artwork>s. */
93 em { font-style: italic; }
94 strong { font-weight: bold; }
95 dfn { font-weight: bold; font-style: normal; }
96 cite { font-weight: normal; font-style: normal; }
97 tt { color: #036; }
98 tt, pre, pre dfn, pre em, pre cite, pre span {
99 font-family: "Courier New", Courier, monospace; font-size: small;
100 }
101 pre {
102 text-align: left; padding: 4px;
103 color: #000; background-color: #CCC;
104 }
105 pre dfn { color: #900; }
106 pre em { color: #66F; background-color: #FFC; font-weight: normal; }
107 pre .key { color: #33C; font-weight: bold; }
108 pre .id { color: #900; }
109 pre .str { color: #000; background-color: #CFF; }
110 pre .val { color: #066; }
111 pre .rep { color: #909; }
112 pre .oth { color: #000; background-color: #FCF; }
113 pre .err { background-color: #FCC; }
114
115 /* RFC-2629 <texttable>s. */
116 table.all, table.full, table.headers, table.none {
117 font-size: small; text-align: center; border-width: 2px;
118 vertical-align: top; border-collapse: collapse;
119 }
120 table.all, table.full { border-style: solid; border-color: black; }
121 table.headers, table.none { border-style: none; }
122 th {
123 font-weight: bold; border-color: black;
124 border-width: 2px 2px 3px 2px;
125 }
126 table.all th, table.full th { border-style: solid; }
127 table.headers th { border-style: none none solid none; }
128 table.none th { border-style: none; }
129 table.all td {
130 border-style: solid; border-color: #333;
131 border-width: 1px 2px;
132 }
133 table.full td, table.headers td, table.none td { border-style: none; }
134
135 hr { height: 1px; }
136 hr.insert {
137 width: 80%; border-style: none; border-width: 0;
138 color: #CCC; background-color: #CCC;
139 }
140 --></style>
141 </head>
142 <body>
143 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
144 <table summary="layout" width="66%" border="0" cellpadding="0" cellspacing="0"><tr><td><table summary="layout" width="100%" border="0" cellpadding="2" cellspacing="1">
145 <tr><td class="header">LinuxSampler Developers</td><td class="header">C. Schoenebeck</td></tr>
146 <tr><td class="header">Internet-Draft</td><td class="header">Interessengemeinschaft Software</td></tr>
147 <tr><td class="header">Intended status: Standards Track</td><td class="header">Engineering e. V.</td></tr>
148 <tr><td class="header">Expires: April 13, 2008</td><td class="header">October 11, 2007</td></tr>
149 </table></td></tr></table>
150 <h1><br />LinuxSampler Control Protocol (draft)<br />LSCP 1.2cvs</h1>
151
152 <h3>Status of this Memo</h3>
153 <p>
154 By submitting this Internet-Draft,
155 each author represents that any applicable patent or other IPR claims of which
156 he or she is aware have been or will be disclosed,
157 and any of which he or she becomes aware will be disclosed,
158 in accordance with Section&nbsp;6 of BCP&nbsp;79.</p>
159 <p>
160 Internet-Drafts are working documents of the Internet Engineering
161 Task Force (IETF), its areas, and its working groups.
162 Note that other groups may also distribute working documents as
163 Internet-Drafts.</p>
164 <p>
165 Internet-Drafts are draft documents valid for a maximum of six months
166 and may be updated, replaced, or obsoleted by other documents at any time.
167 It is inappropriate to use Internet-Drafts as reference material or to cite
168 them other than as &ldquo;work in progress.&rdquo;</p>
169 <p>
170 The list of current Internet-Drafts can be accessed at
171 <a href='http://www.ietf.org/ietf/1id-abstracts.txt'>http://www.ietf.org/ietf/1id-abstracts.txt</a>.</p>
172 <p>
173 The list of Internet-Draft Shadow Directories can be accessed at
174 <a href='http://www.ietf.org/shadow.html'>http://www.ietf.org/shadow.html</a>.</p>
175 <p>
176 This Internet-Draft will expire on April 13, 2008.</p>
177
178 <h3>Copyright Notice</h3>
179 <p>
180 Copyright &copy; The IETF Trust (2007).</p>
181
182 <h3>Abstract</h3>
183
184 <p>The LinuxSampler Control Protocol (LSCP) is an
185 application-level protocol primarily intended for local and
186 remote controlling the LinuxSampler backend application, which is a
187 sophisticated server-like console application essentially playing
188 back audio samples and manipulating the samples in real time to
189 certain extent.
190 </p><a name="toc"></a><br /><hr />
191 <h3>Table of Contents</h3>
192 <p class="toc">
193 <a href="#anchor1">1.</a>&nbsp;
194 Requirements notation<br />
195 <a href="#LSCP versioning">2.</a>&nbsp;
196 Versioning of this specification<br />
197 <a href="#anchor2">3.</a>&nbsp;
198 Introduction<br />
199 <a href="#anchor3">4.</a>&nbsp;
200 Focus of this protocol<br />
201 <a href="#anchor4">5.</a>&nbsp;
202 Communication Overview<br />
203 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor5">5.1.</a>&nbsp;
204 Request/response communication method<br />
205 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor6">5.1.1.</a>&nbsp;
206 Result format<br />
207 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor7">5.2.</a>&nbsp;
208 Subscribe/notify communication method<br />
209 <a href="#control_commands">6.</a>&nbsp;
210 Description for control commands<br />
211 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor8">6.1.</a>&nbsp;
212 Ignored lines and comments<br />
213 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor9">6.2.</a>&nbsp;
214 Configuring audio drivers<br />
215 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_AUDIO_OUTPUT_DRIVERS">6.2.1.</a>&nbsp;
216 Getting amount of available audio output drivers<br />
217 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">6.2.2.</a>&nbsp;
218 Getting all available audio output drivers<br />
219 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DRIVER INFO">6.2.3.</a>&nbsp;
220 Getting information about a specific audio
221 output driver<br />
222 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO">6.2.4.</a>&nbsp;
223 Getting information about specific audio
224 output driver parameter<br />
225 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CREATE AUDIO_OUTPUT_DEVICE">6.2.5.</a>&nbsp;
226 Creating an audio output device<br />
227 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DESTROY AUDIO_OUTPUT_DEVICE">6.2.6.</a>&nbsp;
228 Destroying an audio output device<br />
229 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DEVICES">6.2.7.</a>&nbsp;
230 Getting all created audio output device count<br />
231 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AUDIO_OUTPUT_DEVICES">6.2.8.</a>&nbsp;
232 Getting all created audio output device list<br />
233 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DEVICE INFO">6.2.9.</a>&nbsp;
234 Getting current settings of an audio output device<br />
235 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET AUDIO_OUTPUT_DEVICE_PARAMETER">6.2.10.</a>&nbsp;
236 Changing settings of audio output devices<br />
237 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_CHANNEL INFO">6.2.11.</a>&nbsp;
238 Getting information about an audio channel<br />
239 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO">6.2.12.</a>&nbsp;
240 Getting information about specific audio channel parameter<br />
241 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET AUDIO_OUTPUT_CHANNEL_PARAMETER">6.2.13.</a>&nbsp;
242 Changing settings of audio output channels<br />
243 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor10">6.3.</a>&nbsp;
244 Configuring MIDI input drivers<br />
245 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_MIDI_INPUT_DRIVERS">6.3.1.</a>&nbsp;
246 Getting amount of available MIDI input drivers<br />
247 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_MIDI_INPUT_DRIVERS">6.3.2.</a>&nbsp;
248 Getting all available MIDI input drivers<br />
249 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DRIVER INFO">6.3.3.</a>&nbsp;
250 Getting information about a specific MIDI input driver<br />
251 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DRIVER_PARAMETER INFO">6.3.4.</a>&nbsp;
252 Getting information about specific MIDI input driver parameter<br />
253 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CREATE MIDI_INPUT_DEVICE">6.3.5.</a>&nbsp;
254 Creating a MIDI input device<br />
255 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DESTROY MIDI_INPUT_DEVICE">6.3.6.</a>&nbsp;
256 Destroying a MIDI input device<br />
257 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DEVICES">6.3.7.</a>&nbsp;
258 Getting all created MIDI input device count<br />
259 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST MIDI_INPUT_DEVICES">6.3.8.</a>&nbsp;
260 Getting all created MIDI input device list<br />
261 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DEVICE INFO">6.3.9.</a>&nbsp;
262 Getting current settings of a MIDI input device<br />
263 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET MIDI_INPUT_DEVICE_PARAMETER">6.3.10.</a>&nbsp;
264 Changing settings of MIDI input devices<br />
265 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_PORT INFO">6.3.11.</a>&nbsp;
266 Getting information about a MIDI port<br />
267 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_PORT_PARAMETER INFO">6.3.12.</a>&nbsp;
268 Getting information about specific MIDI port parameter<br />
269 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET MIDI_INPUT_PORT_PARAMETER">6.3.13.</a>&nbsp;
270 Changing settings of MIDI input ports<br />
271 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor11">6.4.</a>&nbsp;
272 Configuring sampler channels<br />
273 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LOAD INSTRUMENT">6.4.1.</a>&nbsp;
274 Loading an instrument<br />
275 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LOAD ENGINE">6.4.2.</a>&nbsp;
276 Loading a sampler engine<br />
277 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNELS">6.4.3.</a>&nbsp;
278 Getting all created sampler channel count<br />
279 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST CHANNELS">6.4.4.</a>&nbsp;
280 Getting all created sampler channel list<br />
281 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD CHANNEL">6.4.5.</a>&nbsp;
282 Adding a new sampler channel<br />
283 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE CHANNEL">6.4.6.</a>&nbsp;
284 Removing a sampler channel<br />
285 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_ENGINES">6.4.7.</a>&nbsp;
286 Getting amount of available engines<br />
287 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_ENGINES">6.4.8.</a>&nbsp;
288 Getting all available engines<br />
289 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET ENGINE INFO">6.4.9.</a>&nbsp;
290 Getting information about an engine<br />
291 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL INFO">6.4.10.</a>&nbsp;
292 Getting sampler channel information<br />
293 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL VOICE_COUNT">6.4.11.</a>&nbsp;
294 Current number of active voices<br />
295 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL STREAM_COUNT">6.4.12.</a>&nbsp;
296 Current number of active disk streams<br />
297 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL BUFFER_FILL">6.4.13.</a>&nbsp;
298 Current fill state of disk stream buffers<br />
299 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_DEVICE">6.4.14.</a>&nbsp;
300 Setting audio output device<br />
301 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_TYPE">6.4.15.</a>&nbsp;
302 Setting audio output type<br />
303 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_CHANNEL">6.4.16.</a>&nbsp;
304 Setting audio output channel<br />
305 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_DEVICE">6.4.17.</a>&nbsp;
306 Setting MIDI input device<br />
307 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_TYPE">6.4.18.</a>&nbsp;
308 Setting MIDI input type<br />
309 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_PORT">6.4.19.</a>&nbsp;
310 Setting MIDI input port<br />
311 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_CHANNEL">6.4.20.</a>&nbsp;
312 Setting MIDI input channel<br />
313 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL VOLUME">6.4.21.</a>&nbsp;
314 Setting channel volume<br />
315 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MUTE">6.4.22.</a>&nbsp;
316 Muting a sampler channel<br />
317 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL SOLO">6.4.23.</a>&nbsp;
318 Soloing a sampler channel<br />
319 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INSTRUMENT_MAP">6.4.24.</a>&nbsp;
320 Assigning a MIDI instrument map to a sampler channel<br />
321 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CREATE FX_SEND">6.4.25.</a>&nbsp;
322 Adding an effect send to a sampler channel<br />
323 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DESTROY FX_SEND">6.4.26.</a>&nbsp;
324 Removing an effect send from a sampler channel<br />
325 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET FX_SENDS">6.4.27.</a>&nbsp;
326 Getting amount of effect sends on a sampler channel<br />
327 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST FX_SENDS">6.4.28.</a>&nbsp;
328 Listing all effect sends on a sampler channel<br />
329 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET FX_SEND INFO">6.4.29.</a>&nbsp;
330 Getting effect send information<br />
331 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET FX_SEND NAME">6.4.30.</a>&nbsp;
332 Changing effect send's name<br />
333 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET FX_SEND AUDIO_OUTPUT_CHANNEL">6.4.31.</a>&nbsp;
334 Altering effect send's audio routing<br />
335 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET FX_SEND MIDI_CONTROLLER">6.4.32.</a>&nbsp;
336 Altering effect send's MIDI controller<br />
337 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET FX_SEND LEVEL">6.4.33.</a>&nbsp;
338 Altering effect send's send level<br />
339 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#RESET CHANNEL">6.4.34.</a>&nbsp;
340 Resetting a sampler channel<br />
341 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor12">6.5.</a>&nbsp;
342 Controlling connection<br />
343 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE">6.5.1.</a>&nbsp;
344 Register front-end for receiving event messages<br />
345 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#UNSUBSCRIBE">6.5.2.</a>&nbsp;
346 Unregister front-end for not receiving event messages<br />
347 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET ECHO">6.5.3.</a>&nbsp;
348 Enable or disable echo of commands<br />
349 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#QUIT">6.5.4.</a>&nbsp;
350 Close client connection<br />
351 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor13">6.6.</a>&nbsp;
352 Global commands<br />
353 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET TOTAL_VOICE_COUNT">6.6.1.</a>&nbsp;
354 Current number of active voices<br />
355 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET TOTAL_VOICE_COUNT_MAX">6.6.2.</a>&nbsp;
356 Maximum amount of active voices<br />
357 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#RESET">6.6.3.</a>&nbsp;
358 Reset sampler<br />
359 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET SERVER INFO">6.6.4.</a>&nbsp;
360 General sampler informations<br />
361 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET VOLUME">6.6.5.</a>&nbsp;
362 Getting global volume attenuation<br />
363 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET VOLUME">6.6.6.</a>&nbsp;
364 Setting global volume attenuation<br />
365 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#MIDI Instrument Mapping">6.7.</a>&nbsp;
366 MIDI Instrument Mapping<br />
367 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD MIDI_INSTRUMENT_MAP">6.7.1.</a>&nbsp;
368 Create a new MIDI instrument map<br />
369 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE MIDI_INSTRUMENT_MAP">6.7.2.</a>&nbsp;
370 Delete one particular or all MIDI instrument maps<br />
371 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENT_MAPS">6.7.3.</a>&nbsp;
372 Get amount of existing MIDI instrument maps<br />
373 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST MIDI_INSTRUMENT_MAPS">6.7.4.</a>&nbsp;
374 Getting all created MIDI instrument maps<br />
375 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENT_MAP INFO">6.7.5.</a>&nbsp;
376 Getting MIDI instrument map information<br />
377 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET MIDI_INSTRUMENT_MAP NAME">6.7.6.</a>&nbsp;
378 Renaming a MIDI instrument map<br />
379 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#MAP MIDI_INSTRUMENT">6.7.7.</a>&nbsp;
380 Create or replace a MIDI instrument map entry<br />
381 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENTS">6.7.8.</a>&nbsp;
382 Getting ammount of MIDI instrument map entries<br />
383 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST MIDI_INSTRUMENTS">6.7.9.</a>&nbsp;
384 Getting indeces of all entries of a MIDI instrument map<br />
385 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#UNMAP MIDI_INSTRUMENT">6.7.10.</a>&nbsp;
386 Remove an entry from the MIDI instrument map<br />
387 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENT INFO">6.7.11.</a>&nbsp;
388 Get current settings of MIDI instrument map entry<br />
389 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CLEAR MIDI_INSTRUMENTS">6.7.12.</a>&nbsp;
390 Clear MIDI instrument map<br />
391 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#Managing Instruments Database">6.8.</a>&nbsp;
392 Managing Instruments Database<br />
393 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD DB_INSTRUMENT_DIRECTORY">6.8.1.</a>&nbsp;
394 Creating a new instrument directory<br />
395 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE DB_INSTRUMENT_DIRECTORY">6.8.2.</a>&nbsp;
396 Deleting an instrument directory<br />
397 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENT_DIRECTORIES">6.8.3.</a>&nbsp;
398 Getting amount of instrument directories<br />
399 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST DB_INSTRUMENT_DIRECTORIES">6.8.4.</a>&nbsp;
400 Listing all directories in specific directory<br />
401 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENT_DIRECTORY INFO">6.8.5.</a>&nbsp;
402 Getting instrument directory information<br />
403 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET DB_INSTRUMENT_DIRECTORY NAME">6.8.6.</a>&nbsp;
404 Renaming an instrument directory<br />
405 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#MOVE DB_INSTRUMENT_DIRECTORY">6.8.7.</a>&nbsp;
406 Moving an instrument directory<br />
407 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#COPY DB_INSTRUMENT_DIRECTORY">6.8.8.</a>&nbsp;
408 Copying instrument directories<br />
409 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">6.8.9.</a>&nbsp;
410 Changing the description of directory<br />
411 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#FIND DB_INSTRUMENT_DIRECTORIES">6.8.10.</a>&nbsp;
412 Finding directories<br />
413 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD DB_INSTRUMENTS">6.8.11.</a>&nbsp;
414 Adding instruments to the instruments database<br />
415 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE DB_INSTRUMENT">6.8.12.</a>&nbsp;
416 Removing an instrument<br />
417 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENTS">6.8.13.</a>&nbsp;
418 Getting amount of instruments<br />
419 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST DB_INSTRUMENTS">6.8.14.</a>&nbsp;
420 Listing all instruments in specific directory<br />
421 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENT INFO">6.8.15.</a>&nbsp;
422 Getting instrument information<br />
423 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET DB_INSTRUMENT NAME">6.8.16.</a>&nbsp;
424 Renaming an instrument<br />
425 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#MOVE DB_INSTRUMENT">6.8.17.</a>&nbsp;
426 Moving an instrument<br />
427 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#COPY DB_INSTRUMENT">6.8.18.</a>&nbsp;
428 Copying instruments<br />
429 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET DB_INSTRUMENT DESCRIPTION">6.8.19.</a>&nbsp;
430 Changing the description of instrument<br />
431 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#FIND DB_INSTRUMENTS">6.8.20.</a>&nbsp;
432 Finding instruments<br />
433 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENTS_JOB INFO">6.8.21.</a>&nbsp;
434 Getting job status information<br />
435 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#FORMAT INSTRUMENTS_DB">6.8.22.</a>&nbsp;
436 Formatting the instruments database<br />
437 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#editing_instruments">6.9.</a>&nbsp;
438 Editing Instruments<br />
439 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#EDIT INSTRUMENT">6.9.1.</a>&nbsp;
440 Opening an appropriate instrument editor application<br />
441 <a href="#command_syntax">7.</a>&nbsp;
442 Command Syntax<br />
443 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#character_set">7.1.</a>&nbsp;
444 Character Set and Escape Sequences<br />
445 <a href="#events">8.</a>&nbsp;
446 Events<br />
447 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT">8.1.</a>&nbsp;
448 Number of audio output devices changed<br />
449 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO">8.2.</a>&nbsp;
450 Audio output device's settings changed<br />
451 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INPUT_DEVICE_COUNT">8.3.</a>&nbsp;
452 Number of MIDI input devices changed<br />
453 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INPUT_DEVICE_INFO">8.4.</a>&nbsp;
454 MIDI input device's settings changed<br />
455 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE CHANNEL_COUNT">8.5.</a>&nbsp;
456 Number of sampler channels changed<br />
457 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE VOICE_COUNT">8.6.</a>&nbsp;
458 Number of active voices changed<br />
459 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE STREAM_COUNT">8.7.</a>&nbsp;
460 Number of active disk streams changed<br />
461 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE BUFFER_FILL">8.8.</a>&nbsp;
462 Disk stream buffer fill state changed<br />
463 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE CHANNEL_INFO">8.9.</a>&nbsp;
464 Channel information changed<br />
465 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE FX_SEND_COUNT">8.10.</a>&nbsp;
466 Number of effect sends changed<br />
467 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE FX_SEND_INFO">8.11.</a>&nbsp;
468 Effect send information changed<br />
469 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE TOTAL_VOICE_COUNT">8.12.</a>&nbsp;
470 Total number of active voices changed<br />
471 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT">8.13.</a>&nbsp;
472 Number of MIDI instrument maps changed<br />
473 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO">8.14.</a>&nbsp;
474 MIDI instrument map information changed<br />
475 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_COUNT">8.15.</a>&nbsp;
476 Number of MIDI instruments changed<br />
477 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_INFO">8.16.</a>&nbsp;
478 MIDI instrument information changed<br />
479 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE GLOBAL_INFO">8.17.</a>&nbsp;
480 Global settings changed<br />
481 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT">8.18.</a>&nbsp;
482 Number of database instrument directories changed<br />
483 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO">8.19.</a>&nbsp;
484 Database instrument directory information changed<br />
485 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENT_COUNT">8.20.</a>&nbsp;
486 Number of database instruments changed<br />
487 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENT_INFO">8.21.</a>&nbsp;
488 Database instrument information changed<br />
489 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENTS_JOB_INFO">8.22.</a>&nbsp;
490 Database job status information changed<br />
491 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MISCELLANEOUS">8.23.</a>&nbsp;
492 Miscellaneous and debugging events<br />
493 <a href="#anchor14">9.</a>&nbsp;
494 Security Considerations<br />
495 <a href="#anchor15">10.</a>&nbsp;
496 Acknowledgments<br />
497 <a href="#rfc.references1">11.</a>&nbsp;
498 References<br />
499 <a href="#rfc.authors">&#167;</a>&nbsp;
500 Author's Address<br />
501 <a href="#rfc.copyright">&#167;</a>&nbsp;
502 Intellectual Property and Copyright Statements<br />
503 </p>
504 <br clear="all" />
505
506 <a name="anchor1"></a><br /><hr />
507 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
508 <a name="rfc.section.1"></a><h3>1.&nbsp;
509 Requirements notation</h3>
510
511 <p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
512 "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
513 and "OPTIONAL" in this document are to be interpreted as
514 described in <a class='info' href='#RFC2119'>[RFC2119]<span> (</span><span class='info'>Bradner, S., &ldquo;Key words for use in RFCs to Indicate Requirement Levels,&rdquo; 1997.</span><span>)</span></a>.
515 </p>
516 <p>This protocol is always case-sensitive if not explicitly
517 claimed the opposite.
518 </p>
519 <p>In examples, "C:" and "S:" indicate lines sent by the client
520 (front-end) and server (LinuxSampler) respectively. Lines in
521 examples must be interpreted as every line being CRLF
522 terminated (carriage return character followed by line feed
523 character as defined in the ASCII standard <a class='info' href='#RFC20'>[RFC20]<span> (</span><span class='info'>UCLA, &ldquo;ASCII format for Network Interchange,&rdquo; 1969.</span><span>)</span></a>),
524 thus the following example:
525 </p>
526 <p>
527 </p>
528 <blockquote class="text">
529 <p>C: "some line"
530 </p>
531 <p>&nbsp;&nbsp;&nbsp;"another line"
532 </p>
533 </blockquote><p>
534
535 </p>
536 <p>must actually be interpreted as client sending the following
537 message:
538 </p>
539 <p>
540 </p>
541 <blockquote class="text">
542 <p>"some line&lt;CR&gt;&lt;LF&gt;another
543 line&lt;CR&gt;&lt;LF&gt;"
544 </p>
545 </blockquote><p>
546
547 </p>
548 <p>where &lt;CR&gt; symbolizes the carriage return character and
549 &lt;LF&gt; the line feed character as defined in the ASCII
550 standard.
551 </p>
552 <p>Due to technical reasons, messages can arbitrary be
553 fragmented, means the following example:
554 </p>
555 <p>
556 </p>
557 <blockquote class="text">
558 <p>S: "abcd"
559 </p>
560 </blockquote><p>
561
562 </p>
563 <p>could also happen to be sent in three messages like in the
564 following sequence scenario:
565 </p>
566 <p>
567 </p>
568 <ul class="text">
569 <li>server sending message "a"
570 </li>
571 <li>followed by a delay (pause) with
572 arbitrary duration
573 </li>
574 <li>followed by server sending message
575 "bcd&lt;CR&gt;"
576 </li>
577 <li>again followed by a delay (pause) with arbitrary
578 duration
579 </li>
580 <li>followed by server sending the message
581 "&lt;LF&gt;"
582 </li>
583 </ul><p>
584
585 </p>
586 <p>where again &lt;CR&gt; and &lt;LF&gt; symbolize the carriage
587 return and line feed characters respectively.
588 </p>
589 <a name="LSCP versioning"></a><br /><hr />
590 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
591 <a name="rfc.section.2"></a><h3>2.&nbsp;
592 Versioning of this specification</h3>
593
594 <p>LSCP will certainly be extended and enhanced by-and-by. Each official
595 release of the LSCP specification will be tagged with a unique version
596 tuple. The version tuple consists at least of a major and minor version
597 number like:
598
599 </p>
600 <p>
601 </p>
602 <blockquote class="text">
603 <p>"1.2"
604 </p>
605 </blockquote><p>
606
607 </p>
608 <p>
609 In this example the major version number would be "1" and the minor
610 version number would be "2". Note that the version tuple might also
611 have more than two elements. The major version number defines a
612 group of backward compatible versions. That means a frontend is
613 compatible to the connected sampler if and only if the LSCP versions
614 to which each of the two parties complies to, match both of the
615 following rules:
616
617 </p>
618 <p>Compatibility:
619 </p>
620 <p>
621 </p>
622 <ol class="text">
623 <li>The frontend's LSCP major version and the sampler's LSCP
624 major version are exactly equal.
625 </li>
626 <li>The frontend's LSCP minor version is less or equal than
627 the sampler's LSCP minor version.
628 </li>
629 </ol><p>
630
631 </p>
632 <p>
633 Compatibility can only be claimed if both rules are true.
634 The frontend can use the
635 <a class='info' href='#GET SERVER INFO'>"GET SERVER INFO"<span> (</span><span class='info'>General sampler informations</span><span>)</span></a> command to
636 get the version of the LSCP specification the sampler complies with.
637
638 </p>
639 <a name="anchor2"></a><br /><hr />
640 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
641 <a name="rfc.section.3"></a><h3>3.&nbsp;
642 Introduction</h3>
643
644 <p>LinuxSampler is a so called software sampler application
645 capable to playback audio samples from a computer's Random
646 Access Memory (RAM) as well as directly streaming it from disk.
647 LinuxSampler is designed to be modular. It provides several so
648 called "sampler engines" where each engine is specialized for a
649 certain purpose. LinuxSampler has virtual channels which will be
650 referred in this document as "sampler channels". The channels
651 are in such way virtual as they can be connected to an
652 arbitrary MIDI input method and arbitrary MIDI channel (e.g.
653 sampler channel 17 could be connected to an ALSA sequencer
654 device 64:0 and listening to MIDI channel 1 there). Each sampler
655 channel will be associated with an instance of one of the available
656 sampler engines (e.g. GigEngine, DLSEngine). The audio output of
657 each sampler channel can be routed to an arbitrary audio output
658 method (ALSA / JACK) and an arbitrary audio output channel
659 there.
660 </p>
661 <a name="anchor3"></a><br /><hr />
662 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
663 <a name="rfc.section.4"></a><h3>4.&nbsp;
664 Focus of this protocol</h3>
665
666 <p>Main focus of this protocol is to provide a way to configure
667 a running LinuxSampler instance and to retrieve information
668 about it. The focus of this protocol is not to provide a way to
669 control synthesis parameters or even to trigger or release
670 notes. Or in other words; the focus are those functionalities
671 which are not covered by MIDI or which may at most be handled
672 via MIDI System Exclusive Messages.
673 </p>
674 <a name="anchor4"></a><br /><hr />
675 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
676 <a name="rfc.section.5"></a><h3>5.&nbsp;
677 Communication Overview</h3>
678
679 <p>There are two distinct methods of communication between a
680 running instance of LinuxSampler and one or more control
681 applications, so called "front-ends": a simple request/response
682 communication method used by the clients to give commands to the
683 server as well as to inquire about server's status and a
684 subscribe/notify communication method used by the client to
685 subscribe to and receive notifications of certain events as they
686 happen on the server. The latter needs more effort to be
687 implemented in the front-end application. The two communication
688 methods will be described next.
689 </p>
690 <a name="anchor5"></a><br /><hr />
691 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
692 <a name="rfc.section.5.1"></a><h3>5.1.&nbsp;
693 Request/response communication method</h3>
694
695 <p>This simple communication method is based on
696 <a class='info' href='#RFC793'>TCP<span> (</span><span class='info'>Defense Advanced Research Projects Agency, &ldquo;TRANSMISSION CONTROL PROTOCOL,&rdquo; 1981.</span><span>)</span></a> [RFC793]. The
697 front-end application establishes a TCP connection to the
698 LinuxSampler instance on a certain host system. Then the
699 front-end application will send certain ASCII based commands
700 as defined in this document (every command line must be CRLF
701 terminated - see "Conventions used in this document" at the
702 beginning of this document) and the LinuxSampler application
703 will response after a certain process time with an
704 appropriate ASCII based answer, also as defined in this
705 document. So this TCP communication is simply based on query
706 and answer paradigm. That way LinuxSampler is only able to
707 answer on queries from front-ends, but not able to
708 automatically send messages to the client if it's not asked
709 to. The fronted should not reconnect to LinuxSampler for
710 every single command, instead it should keep the connection
711 established and simply resend message(s) for subsequent
712 commands. To keep information in the front-end up-to-date
713 the front-end has to periodically send new requests to get
714 the current information from the LinuxSampler instance. This
715 is often referred to as "polling". While polling is simple
716 to implement and may be OK to use in some cases, there may
717 be disadvantages to polling such as network traffic overhead
718 and information being out of date.
719 It is possible for a client or several clients to open more
720 than one connection to the server at the same time. It is
721 also possible to send more than one request to the server
722 at the same time but if those requests are sent over the
723 same connection server MUST execute them sequentially. Upon
724 executing a request server will produce a result set and
725 send it to the client. Each and every request made by the
726 client MUST result in a result set being sent back to the
727 client. No other data other than a result set may be sent by
728 a server to a client. No result set may be sent to a client
729 without the client sending request to the server first. On
730 any particular connection, result sets MUST be sent in their
731 entirety without being interrupted by other result sets. If
732 several requests got queued up at the server they MUST be
733 processed in the order they were received and result sets
734 MUST be sent back in the same order.
735 </p>
736 <a name="anchor6"></a><br /><hr />
737 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
738 <a name="rfc.section.5.1.1"></a><h3>5.1.1.&nbsp;
739 Result format</h3>
740
741 <p>Result set could be one of the following types:
742 </p>
743 <p>
744 </p>
745 <ol class="text">
746 <li>Normal
747 </li>
748 <li>Warning
749 </li>
750 <li>Error
751 </li>
752 </ol><p>
753
754 </p>
755 <p>Warning and Error result sets MUST be single line and
756 have the following format:
757 </p>
758 <p>
759 </p>
760 <ul class="text">
761 <li>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;"
762 </li>
763 <li>"ERR:&lt;error-code&gt;:&lt;error-message&gt;"
764 </li>
765 </ul><p>
766
767 </p>
768 <p>Where &lt;warning-code&gt; and &lt;error-code&gt; are
769 numeric unique identifiers of the warning or error and
770 &lt;warning-message&gt; and &lt;error-message&gt; are
771 human readable descriptions of the warning or error
772 respectively.
773 </p>
774 <p>Examples:
775 </p>
776 <p>
777 </p>
778 <blockquote class="text">
779 <p>C: "LOAD INSTRUMENT '/home/me/Boesendorfer24bit.gig" 0 0
780 </p>
781 <p>S: "WRN:32:This is a 24 bit patch which is not supported natively yet."
782 </p>
783 </blockquote><p>
784
785 </p>
786 <p>
787 </p>
788 <blockquote class="text">
789 <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA EAR"
790 </p>
791 <p>S: "ERR:3456:Audio output driver 'ALSA' does not have a parameter 'EAR'."
792 </p>
793 </blockquote><p>
794
795 </p>
796 <p>
797 </p>
798 <blockquote class="text">
799 <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 123456"
800 </p>
801 <p>S: "ERR:9:There is no audio output device with index 123456."
802 </p>
803 </blockquote><p>
804
805 </p>
806 <p>Normal result sets could be:
807 </p>
808 <p>
809 </p>
810 <ol class="text">
811 <li>Empty
812 </li>
813 <li>Single line
814 </li>
815 <li>Multi-line
816 </li>
817 </ol><p>
818
819 </p>
820 <p> Empty result set is issued when the server only
821 needed to acknowledge the fact that the request was
822 received and it was processed successfully and no
823 additional information is available. This result set has
824 the following format:
825 </p>
826 <p>
827 </p>
828 <blockquote class="text">
829 <p>"OK"
830 </p>
831 </blockquote><p>
832
833 </p>
834 <p>Example:
835 </p>
836 <p>
837 </p>
838 <blockquote class="text">
839 <p>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 CHANNELS=4"
840 </p>
841 <p>S: "OK"
842 </p>
843 </blockquote><p>
844
845 </p>
846 <p>Single line result sets are command specific. One
847 example of a single line result set is an empty line.
848 Multi-line result sets are command specific and may
849 include one or more lines of information. They MUST
850 always end with the following line:
851 </p>
852 <p>
853 </p>
854 <blockquote class="text">
855 <p>"."
856 </p>
857 </blockquote><p>
858
859 </p>
860 <p>Example:
861 </p>
862 <p>
863 </p>
864 <blockquote class="text">
865 <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
866 </p>
867 <p>S: "DRIVER: ALSA"
868 </p>
869 <p>&nbsp;&nbsp;&nbsp;"CHANNELS: 2"
870 </p>
871 <p>&nbsp;&nbsp;&nbsp;"SAMPLERATE: 44100"
872 </p>
873 <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
874 </p>
875 <p>&nbsp;&nbsp;&nbsp;"FRAGMENTS: 2"
876 </p>
877 <p>&nbsp;&nbsp;&nbsp;"FRAGMENTSIZE: 128"
878 </p>
879 <p>&nbsp;&nbsp;&nbsp;"CARD: '0,0'"
880 </p>
881 <p>&nbsp;&nbsp;&nbsp;"."
882 </p>
883 </blockquote><p>
884
885 </p>
886 <p>In addition to above mentioned formats, warnings and
887 empty result sets MAY be indexed. In this case, they
888 have the following formats respectively:
889 </p>
890 <p>
891 </p>
892 <ul class="text">
893 <li>"WRN[&lt;index&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;"
894 </li>
895 <li>"OK[&lt;index&gt;]"
896 </li>
897 </ul><p>
898
899 </p>
900 <p>where &lt;index&gt; is command specific and is used
901 to indicate channel number that the result set was
902 related to or other integer value.
903 </p>
904 <p>Each line of the result set MUST end with
905 &lt;CRLF&gt;.
906 </p>
907 <p>Examples:
908 </p>
909 <p>
910 </p>
911 <blockquote class="text">
912 <p>C: "ADD CHANNEL"
913 </p>
914 <p>S: "OK[12]"
915 </p>
916 </blockquote><p>
917
918 </p>
919 <p>
920 </p>
921 <blockquote class="text">
922 <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"
923 </p>
924 <p>S: "WRN[0]:32:Sample rate not supported, using 44100 instead."
925 </p>
926 </blockquote><p>
927
928 </p>
929 <a name="anchor7"></a><br /><hr />
930 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
931 <a name="rfc.section.5.2"></a><h3>5.2.&nbsp;
932 Subscribe/notify communication method</h3>
933
934 <p>This more sophisticated communication method is actually
935 only an extension of the simple request/response
936 communication method. The front-end still uses a TCP
937 connection and sends the same commands on the TCP
938 connection. Two extra commands are SUBSCRIBE and UNSUBSCRIBE
939 commands that allow a client to tell the server that it is
940 interested in receiving notifications about certain events
941 as they happen on the server. The SUBSCRIBE command has the
942 following syntax:
943 </p>
944 <p>
945 </p>
946 <blockquote class="text">
947 <p>SUBSCRIBE &lt;event-id&gt;
948 </p>
949 </blockquote><p>
950
951 </p>
952 <p>where &lt;event-id&gt; will be replaced by the respective
953 event that client wants to subscribe to. Upon receiving such
954 request, server SHOULD respond with OK and start sending
955 EVENT notifications when a given even has occurred to the
956 front-end when an event has occurred. It MAY be possible
957 certain events may be sent before OK response during real
958 time nature of their generation. Event messages have the
959 following format:
960 </p>
961 <p>
962 </p>
963 <blockquote class="text">
964 <p>NOTIFY:&lt;event-id&gt;:&lt;custom-event-data&gt;
965 </p>
966 </blockquote><p>
967
968 </p>
969 <p>where &lt;event-id&gt; uniquely identifies the event that
970 has occurred and &lt;custom-event-data&gt; is event
971 specific.
972 </p>
973 <p>Several rules must be followed by the server when
974 generating events:
975 </p>
976 <p>
977 </p>
978 <ol class="text">
979 <li>Events MUST NOT be sent to any client who has not
980 issued an appropriate SUBSCRIBE command.
981 </li>
982 <li>Events MUST only be sent using the same
983 connection that was used to subscribe to them.
984 </li>
985 <li>When response is being sent to the client, event
986 MUST be inserted in the stream before or after the
987 response, but NOT in the middle. Same is true about
988 the response. It should never be inserted in the
989 middle of the event message as well as any other
990 response.
991 </li>
992 </ol><p>
993
994 </p>
995 <p>If the client is not interested in a particular event
996 anymore it MAY issue UNSUBSCRIBE command using the following
997 syntax:
998 </p>
999 <p>
1000 </p>
1001 <blockquote class="text">
1002 <p>UNSUBSCRIBE &lt;event-id&gt;
1003 </p>
1004 </blockquote><p>
1005
1006 </p>
1007 <p>where &lt;event-id&gt; will be replace by the respective
1008 event that client is no longer interested in receiving. For
1009 a list of supported events see <a class='info' href='#events'>Section&nbsp;8<span> (</span><span class='info'>Events</span><span>)</span></a>.
1010 </p>
1011 <p>Example: the fill states of disk stream buffers have
1012 changed on sampler channel 4 and the LinuxSampler instance
1013 will react by sending the following message to all clients
1014 who subscribed to this event:
1015 </p>
1016 <p>
1017 </p>
1018 <blockquote class="text">
1019 <p>NOTIFY:CHANNEL_BUFFER_FILL:4 [35]62%,[33]80%,[37]98%
1020 </p>
1021 </blockquote><p>
1022
1023 </p>
1024 <p>Which means there are currently three active streams on
1025 sampler channel 4, where the stream with ID "35" is filled
1026 by 62%, stream with ID 33 is filled by 80% and stream with
1027 ID 37 is filled by 98%.
1028 </p>
1029 <p>Clients may choose to open more than one connection to
1030 the server and use some connections to receive notifications
1031 while using other connections to issue commands to the
1032 back-end. This is entirely legal and up to the
1033 implementation. This does not change the protocol in any way
1034 and no special restrictions exist on the server to allow or
1035 disallow this or to track what connections belong to what
1036 front-ends. Server will listen on a single port, accept
1037 multiple connections and support protocol described in this
1038 specification in it's entirety on this single port on each
1039 connection that it accepted.
1040 </p>
1041 <p>Due to the fact that TCP is used for this communication,
1042 dead peers will be detected automatically by the OS TCP
1043 stack. While it may take a while to detect dead peers if no
1044 traffic is being sent from server to client (TCP keep-alive
1045 timer is set to 2 hours on many OSes) it will not be an
1046 issue here as when notifications are sent by the server,
1047 dead client will be detected quickly.
1048 </p>
1049 <p>When connection is closed for any reason server MUST
1050 forget all subscriptions that were made on this connection.
1051 If client reconnects it MUST resubscribe to all events that
1052 it wants to receive.
1053 </p>
1054 <a name="control_commands"></a><br /><hr />
1055 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1056 <a name="rfc.section.6"></a><h3>6.&nbsp;
1057 Description for control commands</h3>
1058
1059 <p>This chapter will describe the available control commands
1060 that can be sent on the TCP connection in detail. Some certain
1061 commands (e.g. <a class='info' href='#GET CHANNEL INFO'>"GET CHANNEL INFO"<span> (</span><span class='info'>Getting sampler channel information</span><span>)</span></a>
1062 or <a class='info' href='#GET ENGINE INFO'>"GET ENGINE INFO"<span> (</span><span class='info'>Getting information about an engine</span><span>)</span></a>) lead to
1063 multiple-line responses. In this case LinuxSampler signals the
1064 end of the response by a "." (single dot) line.
1065 </p>
1066 <a name="anchor8"></a><br /><hr />
1067 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1068 <a name="rfc.section.6.1"></a><h3>6.1.&nbsp;
1069 Ignored lines and comments</h3>
1070
1071 <p>White lines, that is lines which only contain space and
1072 tabulator characters, and lines that start with a "#"
1073 character are ignored, thus it's possible for example to
1074 group commands and to place comments in a LSCP script
1075 file.
1076 </p>
1077 <a name="anchor9"></a><br /><hr />
1078 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1079 <a name="rfc.section.6.2"></a><h3>6.2.&nbsp;
1080 Configuring audio drivers</h3>
1081
1082 <p>Instances of drivers in LinuxSampler are called devices.
1083 You can use multiple audio devices simultaneously, e.g. to
1084 output the sound of one sampler channel using the ALSA audio
1085 output driver, and on another sampler channel you might want
1086 to use the JACK audio output driver. For particular audio
1087 output systems it's also possible to create several devices
1088 of the same audio output driver, e.g. two separate ALSA
1089 audio output devices for using two different sound cards at
1090 the same time. This chapter describes all commands to
1091 configure LinuxSampler's audio output devices and their
1092 parameters.
1093 </p>
1094 <p>Instead of defining commands and parameters for each
1095 driver individually, all possible parameters, their meanings
1096 and possible values have to be obtained at runtime. This
1097 makes the protocol a bit abstract, but has the advantage,
1098 that front-ends can be written independently of what drivers
1099 are currently implemented and what parameters these drivers
1100 are actually offering. This means front-ends can even handle
1101 drivers which are implemented somewhere in future without
1102 modifying the front-end at all.
1103 </p>
1104 <p>Note: examples in this chapter showing particular
1105 parameters of drivers are not meant as specification of the
1106 drivers' parameters. Driver implementations in LinuxSampler
1107 might have complete different parameter names and meanings
1108 than shown in these examples or might change in future, so
1109 these examples are only meant for showing how to retrieve
1110 what parameters drivers are offering, how to retrieve their
1111 possible values, etc.
1112 </p>
1113 <a name="GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"></a><br /><hr />
1114 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1115 <a name="rfc.section.6.2.1"></a><h3>6.2.1.&nbsp;
1116 Getting amount of available audio output drivers</h3>
1117
1118 <p>Use the following command to get the number of
1119 audio output drivers currently available for the
1120 LinuxSampler instance:
1121 </p>
1122 <p>
1123 </p>
1124 <blockquote class="text">
1125 <p>GET AVAILABLE_AUDIO_OUTPUT_DRIVERS
1126 </p>
1127 </blockquote><p>
1128
1129 </p>
1130 <p>Possible Answers:
1131 </p>
1132 <p>
1133 </p>
1134 <blockquote class="text">
1135 <p>LinuxSampler will answer by sending the
1136 number of audio output drivers.
1137 </p>
1138 </blockquote><p>
1139
1140 </p>
1141 <p>Example:
1142 </p>
1143 <p>
1144 </p>
1145 <blockquote class="text">
1146 <p>C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
1147 </p>
1148 <p>S: "2"
1149 </p>
1150 </blockquote><p>
1151
1152 </p>
1153 <a name="LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"></a><br /><hr />
1154 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1155 <a name="rfc.section.6.2.2"></a><h3>6.2.2.&nbsp;
1156 Getting all available audio output drivers</h3>
1157
1158 <p>Use the following command to list all audio output
1159 drivers currently available for the LinuxSampler
1160 instance:
1161 </p>
1162 <p>
1163 </p>
1164 <blockquote class="text">
1165 <p>LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS
1166 </p>
1167 </blockquote><p>
1168
1169 </p>
1170 <p>Possible Answers:
1171 </p>
1172 <p>
1173 </p>
1174 <blockquote class="text">
1175 <p>LinuxSampler will answer by sending comma
1176 separated character strings, each symbolizing an
1177 audio output driver.
1178 </p>
1179 </blockquote><p>
1180
1181 </p>
1182 <p>Example:
1183 </p>
1184 <p>
1185 </p>
1186 <blockquote class="text">
1187 <p>C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"
1188 </p>
1189 <p>S: "ALSA,JACK"
1190 </p>
1191 </blockquote><p>
1192
1193 </p>
1194 <a name="GET AUDIO_OUTPUT_DRIVER INFO"></a><br /><hr />
1195 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1196 <a name="rfc.section.6.2.3"></a><h3>6.2.3.&nbsp;
1197 Getting information about a specific audio
1198 output driver</h3>
1199
1200 <p>Use the following command to get detailed information
1201 about a specific audio output driver:
1202 </p>
1203 <p>
1204 </p>
1205 <blockquote class="text">
1206 <p>GET AUDIO_OUTPUT_DRIVER INFO
1207 &lt;audio-output-driver&gt;
1208 </p>
1209 </blockquote><p>
1210
1211 </p>
1212 <p>Where &lt;audio-output-driver&gt; is the name of the
1213 audio output driver, returned by the
1214 <a class='info' href='#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS'>"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"<span> (</span><span class='info'>Getting all available audio output drivers</span><span>)</span></a> command.
1215 </p>
1216 <p>Possible Answers:
1217 </p>
1218 <p>
1219 </p>
1220 <blockquote class="text">
1221 <p>LinuxSampler will answer by sending a
1222 &lt;CRLF&gt; separated list. Each answer line
1223 begins with the information category name
1224 followed by a colon and then a space character
1225 &lt;SP&gt; and finally the info character string
1226 to that info category. At the moment the
1227 following information categories are
1228 defined:
1229 </p>
1230 <p>
1231 </p>
1232 <blockquote class="text">
1233 <p>DESCRIPTION -
1234 </p>
1235 <blockquote class="text">
1236 <p> character string describing the
1237 audio output driver
1238 </p>
1239 </blockquote>
1240
1241
1242 <p>VERSION -
1243 </p>
1244 <blockquote class="text">
1245 <p>character string reflecting the
1246 driver's version
1247 </p>
1248 </blockquote>
1249
1250
1251 <p>PARAMETERS -
1252 </p>
1253 <blockquote class="text">
1254 <p>comma separated list of all
1255 parameters available for the given
1256 audio output driver, at least
1257 parameters 'channels', 'samplerate'
1258 and 'active' are offered by all audio
1259 output drivers
1260 </p>
1261 </blockquote>
1262
1263
1264 </blockquote>
1265
1266
1267 <p>The mentioned fields above don't have to be
1268 in particular order.
1269 </p>
1270 </blockquote><p>
1271
1272 </p>
1273 <p>Example:
1274 </p>
1275 <p>
1276 </p>
1277 <blockquote class="text">
1278 <p>C: "GET AUDIO_OUTPUT_DRIVER INFO ALSA"
1279 </p>
1280 <p>S: "DESCRIPTION: Advanced Linux Sound
1281 Architecture"
1282 </p>
1283 <p>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"
1284 </p>
1285 <p>&nbsp;&nbsp;&nbsp;"PARAMETERS:
1286 DRIVER,CHANNELS,SAMPLERATE,ACTIVE,FRAGMENTS,
1287 FRAGMENTSIZE,CARD"
1288 </p>
1289 <p>&nbsp;&nbsp;&nbsp;"."
1290 </p>
1291 </blockquote><p>
1292
1293 </p>
1294 <a name="GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO"></a><br /><hr />
1295 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1296 <a name="rfc.section.6.2.4"></a><h3>6.2.4.&nbsp;
1297 Getting information about specific audio
1298 output driver parameter</h3>
1299
1300 <p>Use the following command to get detailed information
1301 about a specific audio output driver parameter:
1302 </p>
1303 <p>
1304 </p>
1305 <blockquote class="text">
1306 <p>GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO &lt;audio&gt; &lt;prm&gt; [&lt;deplist&gt;]
1307 </p>
1308 </blockquote><p>
1309
1310 </p>
1311 <p>Where &lt;audio&gt; is the name of the audio output
1312 driver as returned by the <a class='info' href='#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS'>"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"<span> (</span><span class='info'>Getting all available audio output drivers</span><span>)</span></a> command,
1313 &lt;prm&gt; a specific parameter name for which information should be
1314 obtained (as returned by the
1315 <a class='info' href='#GET AUDIO_OUTPUT_DRIVER INFO'>"GET AUDIO_OUTPUT_DRIVER INFO"<span> (</span><span class='info'>Getting information about a specific audio output driver</span><span>)</span></a> command) and
1316 &lt;deplist&gt; is an optional list of parameters on which the sought
1317 parameter &lt;prm&gt; depends on, &lt;deplist&gt; is a list of key-value
1318 pairs in form of "key1=val1 key2=val2 ...", where character string values
1319 are encapsulated into apostrophes ('). Arguments given with &lt;deplist&gt;
1320 which are not dependency parameters of &lt;prm&gt; will be ignored, means
1321 the front-end application can simply put all parameters into &lt;deplist&gt;
1322 with the values already selected by the user.
1323 </p>
1324 <p>Possible Answers:
1325 </p>
1326 <p>
1327 </p>
1328 <blockquote class="text">
1329 <p>LinuxSampler will answer by sending a
1330 &lt;CRLF&gt; separated list.
1331 Each answer line begins with the information category name
1332 followed by a colon and then a space character &lt;SP&gt; and
1333 finally
1334 the info character string to that info category. There are
1335 information which is always returned, independently of the
1336 given driver parameter and there are optional information
1337 which is only shown dependently to given driver parameter. At
1338 the moment the following information categories are defined:
1339 </p>
1340 </blockquote><p>
1341
1342 </p>
1343 <p>
1344 </p>
1345 <blockquote class="text">
1346 <p>TYPE -
1347 </p>
1348 <blockquote class="text">
1349 <p>either "BOOL" for boolean value(s) or
1350 "INT" for integer
1351 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1352 character string(s)
1353 (always returned, no matter which driver parameter)
1354 </p>
1355 </blockquote>
1356
1357
1358 <p>DESCRIPTION -
1359 </p>
1360 <blockquote class="text">
1361 <p>arbitrary text describing the purpose of the parameter
1362 (always returned, no matter which driver parameter)
1363 </p>
1364 </blockquote>
1365
1366
1367 <p>MANDATORY -
1368 </p>
1369 <blockquote class="text">
1370 <p>either true or false, defines if this parameter must be
1371 given when the device is to be created with the
1372 <a class='info' href='#CREATE AUDIO_OUTPUT_DEVICE'>'CREATE AUDIO_OUTPUT_DEVICE'<span> (</span><span class='info'>Creating an audio output device</span><span>)</span></a>
1373 command (always returned, no matter which driver parameter)
1374 </p>
1375 </blockquote>
1376
1377
1378 <p>FIX -
1379 </p>
1380 <blockquote class="text">
1381 <p>either true or false, if false then this parameter can
1382 be changed at any time, once the device is created by
1383 the <a class='info' href='#CREATE AUDIO_OUTPUT_DEVICE'>'CREATE AUDIO_OUTPUT_DEVICE'<span> (</span><span class='info'>Creating an audio output device</span><span>)</span></a>
1384 command (always returned, no matter which driver parameter)
1385 </p>
1386 </blockquote>
1387
1388
1389 <p>MULTIPLICITY -
1390 </p>
1391 <blockquote class="text">
1392 <p>either true or false, defines if this parameter allows
1393 only one value or a list of values, where true means
1394 multiple values and false only a single value allowed
1395 (always returned, no matter which driver parameter)
1396 </p>
1397 </blockquote>
1398
1399
1400 <p>DEPENDS -
1401 </p>
1402 <blockquote class="text">
1403 <p>comma separated list of parameters this parameter depends
1404 on, means the values for fields 'DEFAULT', 'RANGE_MIN',
1405 'RANGE_MAX' and 'POSSIBILITIES' might depend on these
1406 listed parameters, for example assuming that an audio
1407 driver (like the ALSA driver) offers parameters 'card'
1408 and 'samplerate' then parameter 'samplerate' would
1409 depend on 'card' because the possible values for
1410 'samplerate' depends on the sound card which can be
1411 chosen by the 'card' parameter
1412 (optionally returned, dependent to driver parameter)
1413 </p>
1414 </blockquote>
1415
1416
1417 <p>DEFAULT -
1418 </p>
1419 <blockquote class="text">
1420 <p>reflects the default value for this parameter which is
1421 used when the device is created and not explicitly
1422 given with the <a class='info' href='#CREATE AUDIO_OUTPUT_DEVICE'>'CREATE AUDIO_OUTPUT_DEVICE'<span> (</span><span class='info'>Creating an audio output device</span><span>)</span></a> command,
1423 in case of MULTIPLCITY=true, this is a comma separated
1424 list, that's why character strings are encapsulated into
1425 apostrophes (')
1426 (optionally returned, dependent to driver parameter)
1427 </p>
1428 </blockquote>
1429
1430
1431 <p>RANGE_MIN -
1432 </p>
1433 <blockquote class="text">
1434 <p>defines lower limit of the allowed value range for this
1435 parameter, can be an integer value as well as a dotted
1436 number, this parameter is often used in conjunction
1437 with RANGE_MAX, but may also appear without
1438 (optionally returned, dependent to driver parameter)
1439 </p>
1440 </blockquote>
1441
1442
1443 <p>RANGE_MAX -
1444 </p>
1445 <blockquote class="text">
1446 <p>defines upper limit of the allowed value range for this
1447 parameter, can be an integer value as well as a dotted
1448 number, this parameter is often used in conjunction with
1449 RANGE_MIN, but may also appear without
1450 (optionally returned, dependent to driver parameter)
1451 </p>
1452 </blockquote>
1453
1454
1455 <p>POSSIBILITIES -
1456 </p>
1457 <blockquote class="text">
1458 <p>comma separated list of possible values for this
1459 parameter, character strings are encapsulated into
1460 apostrophes
1461 (optionally returned, dependent to driver parameter)
1462 </p>
1463 </blockquote>
1464
1465
1466 </blockquote><p>
1467
1468 </p>
1469 <p>The mentioned fields above don't have to be in particular order.
1470 </p>
1471 <p>Examples:
1472 </p>
1473 <p>
1474 </p>
1475 <blockquote class="text">
1476 <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA CARD"
1477 </p>
1478 <p>S: "DESCRIPTION: sound card to be used"
1479 </p>
1480 <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
1481 </p>
1482 <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1483 </p>
1484 <p>&nbsp;&nbsp;&nbsp;"FIX: true"
1485 </p>
1486 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1487 </p>
1488 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: '0,0'"
1489 </p>
1490 <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: '0,0','1,0','2,0'"
1491 </p>
1492 <p>&nbsp;&nbsp;&nbsp;"."
1493 </p>
1494 </blockquote><p>
1495
1496 </p>
1497 <p>
1498 </p>
1499 <blockquote class="text">
1500 <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE"
1501 </p>
1502 <p>S: "DESCRIPTION: output sample rate in Hz"
1503 </p>
1504 <p>&nbsp;&nbsp;&nbsp;"TYPE: INT"
1505 </p>
1506 <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1507 </p>
1508 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
1509 </p>
1510 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1511 </p>
1512 <p>&nbsp;&nbsp;&nbsp;"DEPENDS: card"
1513 </p>
1514 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"
1515 </p>
1516 <p>&nbsp;&nbsp;&nbsp;"."
1517 </p>
1518 </blockquote><p>
1519
1520 </p>
1521 <p>
1522 </p>
1523 <blockquote class="text">
1524 <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE CARD='0,0'"
1525 </p>
1526 <p>S: "DESCRIPTION: output sample rate in Hz"
1527 </p>
1528 <p>&nbsp;&nbsp;&nbsp;"TYPE: INT"
1529 </p>
1530 <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1531 </p>
1532 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
1533 </p>
1534 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1535 </p>
1536 <p>&nbsp;&nbsp;&nbsp;"DEPENDS: card"
1537 </p>
1538 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"
1539 </p>
1540 <p>&nbsp;&nbsp;&nbsp;"RANGE_MIN: 22050"
1541 </p>
1542 <p>&nbsp;&nbsp;&nbsp;"RANGE_MAX: 96000"
1543 </p>
1544 <p>&nbsp;&nbsp;&nbsp;"."
1545 </p>
1546 </blockquote><p>
1547
1548 </p>
1549 <a name="CREATE AUDIO_OUTPUT_DEVICE"></a><br /><hr />
1550 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1551 <a name="rfc.section.6.2.5"></a><h3>6.2.5.&nbsp;
1552 Creating an audio output device</h3>
1553
1554 <p>Use the following command to create a new audio output device for the desired audio output system:
1555 </p>
1556 <p>
1557 </p>
1558 <blockquote class="text">
1559 <p>CREATE AUDIO_OUTPUT_DEVICE &lt;audio-output-driver&gt; [&lt;param-list&gt;]
1560 </p>
1561 </blockquote><p>
1562
1563 </p>
1564 <p>Where &lt;audio-output-driver&gt; should be replaced by the desired audio
1565 output system as returned by the
1566 <a class='info' href='#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS'>"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"<span> (</span><span class='info'>Getting all available audio output drivers</span><span>)</span></a>
1567 command and &lt;param-list&gt; by an optional list of driver
1568 specific parameters in form of "key1=val1 key2=val2 ...", where
1569 character string values should be encapsulated into apostrophes (').
1570 Note that there might be drivers which require parameter(s) to be
1571 given with this command. Use the previously described commands in
1572 this chapter to get this information.
1573 </p>
1574 <p>Possible Answers:
1575 </p>
1576 <p>
1577 </p>
1578 <blockquote class="text">
1579 <p>"OK[&lt;device-id&gt;]" -
1580 </p>
1581 <blockquote class="text">
1582 <p>in case the device was successfully created, where
1583 &lt;device-id&gt; is the numerical ID of the new device
1584 </p>
1585 </blockquote>
1586
1587
1588 <p>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1589 </p>
1590 <blockquote class="text">
1591 <p>in case the device was created successfully, where
1592 &lt;device-id&gt; is the numerical ID of the new device, but there
1593 are noteworthy issue(s) related (e.g. sound card doesn't
1594 support given hardware parameters and the driver is using
1595 fall-back values), providing an appropriate warning code and
1596 warning message
1597 </p>
1598 </blockquote>
1599
1600
1601 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1602 </p>
1603 <blockquote class="text">
1604 <p>in case it failed, providing an appropriate error code and error message
1605 </p>
1606 </blockquote>
1607
1608
1609 </blockquote><p>
1610
1611 </p>
1612 <p>Examples:
1613 </p>
1614 <p>
1615 </p>
1616 <blockquote class="text">
1617 <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA"
1618 </p>
1619 <p>S: "OK[0]"
1620 </p>
1621 </blockquote><p>
1622
1623 </p>
1624 <p>
1625 </p>
1626 <blockquote class="text">
1627 <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"
1628 </p>
1629 <p>S: "OK[1]"
1630 </p>
1631 </blockquote><p>
1632
1633 </p>
1634 <a name="DESTROY AUDIO_OUTPUT_DEVICE"></a><br /><hr />
1635 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1636 <a name="rfc.section.6.2.6"></a><h3>6.2.6.&nbsp;
1637 Destroying an audio output device</h3>
1638
1639 <p>Use the following command to destroy a created output device:
1640 </p>
1641 <p>
1642 </p>
1643 <blockquote class="text">
1644 <p>DESTROY AUDIO_OUTPUT_DEVICE &lt;device-id&gt;
1645 </p>
1646 </blockquote><p>
1647
1648 </p>
1649 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1650 audio output device as given by the
1651 <a class='info' href='#CREATE AUDIO_OUTPUT_DEVICE'>"CREATE AUDIO_OUTPUT_DEVICE"<span> (</span><span class='info'>Creating an audio output device</span><span>)</span></a>
1652 or <a class='info' href='#LIST AUDIO_OUTPUT_DEVICES'>"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class='info'>Getting all created audio output device list</span><span>)</span></a>
1653 command.
1654 </p>
1655 <p>Possible Answers:
1656 </p>
1657 <p>
1658 </p>
1659 <blockquote class="text">
1660 <p>"OK" -
1661 </p>
1662 <blockquote class="text">
1663 <p>in case the device was successfully destroyed
1664 </p>
1665 </blockquote>
1666
1667
1668 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1669 </p>
1670 <blockquote class="text">
1671 <p>in case the device was destroyed successfully, but there are
1672 noteworthy issue(s) related (e.g. an audio over ethernet
1673 driver was unloaded but the other host might not be
1674 informed about this situation), providing an appropriate
1675 warning code and warning message
1676 </p>
1677 </blockquote>
1678
1679
1680 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1681 </p>
1682 <blockquote class="text">
1683 <p>in case it failed, providing an appropriate error code and
1684 error message
1685 </p>
1686 </blockquote>
1687
1688
1689 </blockquote><p>
1690
1691 </p>
1692 <p>Example:
1693 </p>
1694 <p>
1695 </p>
1696 <blockquote class="text">
1697 <p>C: "DESTROY AUDIO_OUTPUT_DEVICE 0"
1698 </p>
1699 <p>S: "OK"
1700 </p>
1701 </blockquote><p>
1702
1703 </p>
1704 <a name="GET AUDIO_OUTPUT_DEVICES"></a><br /><hr />
1705 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1706 <a name="rfc.section.6.2.7"></a><h3>6.2.7.&nbsp;
1707 Getting all created audio output device count</h3>
1708
1709 <p>Use the following command to count all created audio output devices:
1710 </p>
1711 <p>
1712 </p>
1713 <blockquote class="text">
1714 <p>GET AUDIO_OUTPUT_DEVICES
1715 </p>
1716 </blockquote><p>
1717
1718 </p>
1719 <p>Possible Answers:
1720 </p>
1721 <p>
1722 </p>
1723 <blockquote class="text">
1724 <p>LinuxSampler will answer by sending the current number of all
1725 audio output devices.
1726 </p>
1727 </blockquote><p>
1728
1729 </p>
1730 <p>Example:
1731 </p>
1732 <p>
1733 </p>
1734 <blockquote class="text">
1735 <p>C: "GET AUDIO_OUTPUT_DEVICES"
1736 </p>
1737 <p>S: "4"
1738 </p>
1739 </blockquote><p>
1740
1741 </p>
1742 <a name="LIST AUDIO_OUTPUT_DEVICES"></a><br /><hr />
1743 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1744 <a name="rfc.section.6.2.8"></a><h3>6.2.8.&nbsp;
1745 Getting all created audio output device list</h3>
1746
1747 <p>Use the following command to list all created audio output devices:
1748 </p>
1749 <p>
1750 </p>
1751 <blockquote class="text">
1752 <p>LIST AUDIO_OUTPUT_DEVICES
1753 </p>
1754 </blockquote><p>
1755
1756 </p>
1757 <p>Possible Answers:
1758 </p>
1759 <p>
1760 </p>
1761 <blockquote class="text">
1762 <p>LinuxSampler will answer by sending a comma separated list with
1763 the numerical IDs of all audio output devices.
1764 </p>
1765 </blockquote><p>
1766
1767 </p>
1768 <p>Example:
1769 </p>
1770 <p>
1771 </p>
1772 <blockquote class="text">
1773 <p>C: "LIST AUDIO_OUTPUT_DEVICES"
1774 </p>
1775 <p>S: "0,1,4,5"
1776 </p>
1777 </blockquote><p>
1778
1779 </p>
1780 <a name="GET AUDIO_OUTPUT_DEVICE INFO"></a><br /><hr />
1781 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1782 <a name="rfc.section.6.2.9"></a><h3>6.2.9.&nbsp;
1783 Getting current settings of an audio output device</h3>
1784
1785 <p>Use the following command to get current settings of a specific, created audio output device:
1786 </p>
1787 <p>
1788 </p>
1789 <blockquote class="text">
1790 <p>GET AUDIO_OUTPUT_DEVICE INFO &lt;device-id&gt;
1791 </p>
1792 </blockquote><p>
1793
1794 </p>
1795 <p>Where &lt;device-id&gt; should be replaced by numerical ID
1796 of the audio output device as e.g. returned by the
1797 <a class='info' href='#LIST AUDIO_OUTPUT_DEVICES'>"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class='info'>Getting all created audio output device list</span><span>)</span></a> command.
1798 </p>
1799 <p>Possible Answers:
1800 </p>
1801 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1802 Each answer line begins with the information category name
1803 followed by a colon and then a space character &lt;SP&gt; and finally
1804 the info character string to that info category. As some
1805 parameters might allow multiple values, character strings are
1806 encapsulated into apostrophes ('). At the moment the following
1807 information categories are defined (independently of device):
1808 </p>
1809 <p>
1810 </p>
1811 <blockquote class="text">
1812 <p>DRIVER -
1813 </p>
1814 <blockquote class="text">
1815 <p>identifier of the used audio output driver, as also
1816 returned by the
1817 <a class='info' href='#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS'>"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"<span> (</span><span class='info'>Getting all available audio output drivers</span><span>)</span></a>
1818 command
1819 </p>
1820 </blockquote>
1821
1822
1823 <p>CHANNELS -
1824 </p>
1825 <blockquote class="text">
1826 <p>amount of audio output channels this device currently
1827 offers
1828 </p>
1829 </blockquote>
1830
1831
1832 <p>SAMPLERATE -
1833 </p>
1834 <blockquote class="text">
1835 <p>playback sample rate the device uses
1836 </p>
1837 </blockquote>
1838
1839
1840 <p>ACTIVE -
1841 </p>
1842 <blockquote class="text">
1843 <p>either true or false, if false then the audio device is
1844 inactive and doesn't output any sound, nor do the
1845 sampler channels connected to this audio device render
1846 any audio
1847 </p>
1848 </blockquote>
1849
1850
1851 </blockquote><p>
1852
1853 </p>
1854 <p>The mentioned fields above don't have to be in particular
1855 order. The fields above are only those fields which are
1856 returned by all audio output devices. Every audio output driver
1857 might have its own, additional driver specific parameters (see
1858 <a class='info' href='#GET AUDIO_OUTPUT_DRIVER INFO'>Section&nbsp;6.2.3<span> (</span><span class='info'>Getting information about a specific audio output driver</span><span>)</span></a>)
1859 which are also returned by this command.
1860 </p>
1861 <p>Example:
1862 </p>
1863 <p>
1864 </p>
1865 <blockquote class="text">
1866 <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
1867 </p>
1868 <p>S: "DRIVER: ALSA"
1869 </p>
1870 <p>&nbsp;&nbsp;&nbsp;"CHANNELS: 2"
1871 </p>
1872 <p>&nbsp;&nbsp;&nbsp;"SAMPLERATE: 44100"
1873 </p>
1874 <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
1875 </p>
1876 <p>&nbsp;&nbsp;&nbsp;"FRAGMENTS: 2"
1877 </p>
1878 <p>&nbsp;&nbsp;&nbsp;"FRAGMENTSIZE: 128"
1879 </p>
1880 <p>&nbsp;&nbsp;&nbsp;"CARD: '0,0'"
1881 </p>
1882 <p>&nbsp;&nbsp;&nbsp;"."
1883 </p>
1884 </blockquote><p>
1885
1886 </p>
1887 <a name="SET AUDIO_OUTPUT_DEVICE_PARAMETER"></a><br /><hr />
1888 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1889 <a name="rfc.section.6.2.10"></a><h3>6.2.10.&nbsp;
1890 Changing settings of audio output devices</h3>
1891
1892 <p>Use the following command to alter a specific setting of a created audio output device:
1893 </p>
1894 <p>
1895 </p>
1896 <blockquote class="text">
1897 <p>SET AUDIO_OUTPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;
1898 </p>
1899 </blockquote><p>
1900
1901 </p>
1902 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1903 audio output device as given by the
1904 <a class='info' href='#CREATE AUDIO_OUTPUT_DEVICE'>"CREATE AUDIO_OUTPUT_DEVICE"<span> (</span><span class='info'>Creating an audio output device</span><span>)</span></a>
1905 or <a class='info' href='#LIST AUDIO_OUTPUT_DEVICES'>"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class='info'>Getting all created audio output device list</span><span>)</span></a>
1906 command, &lt;key&gt; by the name of the parameter to change
1907 and &lt;value&gt; by the new value for this parameter.
1908 </p>
1909 <p>Possible Answers:
1910 </p>
1911 <p>
1912 </p>
1913 <blockquote class="text">
1914 <p>"OK" -
1915 </p>
1916 <blockquote class="text">
1917 <p>in case setting was successfully changed
1918 </p>
1919 </blockquote>
1920
1921
1922 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1923 </p>
1924 <blockquote class="text">
1925 <p>in case setting was changed successfully, but there are
1926 noteworthy issue(s) related, providing an appropriate
1927 warning code and warning message
1928 </p>
1929 </blockquote>
1930
1931
1932 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1933 </p>
1934 <blockquote class="text">
1935 <p>in case it failed, providing an appropriate error code and
1936 error message
1937 </p>
1938 </blockquote>
1939
1940
1941 </blockquote><p>
1942
1943 </p>
1944 <p>Example:
1945 </p>
1946 <p>
1947 </p>
1948 <blockquote class="text">
1949 <p>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"
1950 </p>
1951 <p>S: "OK"
1952 </p>
1953 </blockquote><p>
1954
1955 </p>
1956 <a name="GET AUDIO_OUTPUT_CHANNEL INFO"></a><br /><hr />
1957 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1958 <a name="rfc.section.6.2.11"></a><h3>6.2.11.&nbsp;
1959 Getting information about an audio channel</h3>
1960
1961 <p>Use the following command to get information about an audio channel:
1962 </p>
1963 <p>
1964 </p>
1965 <blockquote class="text">
1966 <p>GET AUDIO_OUTPUT_CHANNEL INFO &lt;device-id&gt; &lt;audio-chan&gt;
1967 </p>
1968 </blockquote><p>
1969
1970 </p>
1971 <p>Where &lt;device-id&gt; is the numerical ID of the audio output device as given by the
1972 <a class='info' href='#CREATE AUDIO_OUTPUT_DEVICE'>"CREATE AUDIO_OUTPUT_DEVICE"<span> (</span><span class='info'>Creating an audio output device</span><span>)</span></a>
1973 or <a class='info' href='#LIST AUDIO_OUTPUT_DEVICES'>"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class='info'>Getting all created audio output device list</span><span>)</span></a>
1974 command and &lt;audio-chan&gt; the audio channel number.
1975 </p>
1976 <p>Possible Answers:
1977 </p>
1978 <p>
1979 </p>
1980 <blockquote class="text">
1981 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1982 Each answer line begins with the information category name
1983 followed by a colon and then a space character &lt;SP&gt; and finally
1984 the info character string to that info category. At the moment
1985 the following information categories are defined:
1986 </p>
1987 <p>
1988 </p>
1989 <blockquote class="text">
1990 <p>NAME -
1991 </p>
1992 <blockquote class="text">
1993 <p>arbitrary character string naming the channel, which
1994 doesn't have to be unique (always returned by all audio channels)
1995 </p>
1996 </blockquote>
1997
1998
1999 <p>IS_MIX_CHANNEL -
2000 </p>
2001 <blockquote class="text">
2002 <p>either true or false, a mix-channel is not a real,
2003 independent audio channel, but a virtual channel which
2004 is mixed to another real channel, this mechanism is
2005 needed for sampler engines which need more audio
2006 channels than the used audio system might be able to offer
2007 (always returned by all audio channels)
2008 </p>
2009 </blockquote>
2010
2011
2012 <p>MIX_CHANNEL_DESTINATION -
2013 </p>
2014 <blockquote class="text">
2015 <p>numerical ID (positive integer including 0)
2016 which reflects the real audio channel (of the same audio
2017 output device) this mix channel refers to, means where
2018 the audio signal actually will be routed / added to
2019 (only returned in case the audio channel is mix channel)
2020 </p>
2021 </blockquote>
2022
2023
2024 </blockquote>
2025
2026
2027 </blockquote><p>
2028
2029 </p>
2030 <p>The mentioned fields above don't have to be in particular
2031 order. The fields above are only those fields which are
2032 generally returned for the described cases by all audio
2033 channels regardless of the audio driver. Every audio channel
2034 might have its own, additional driver and channel specific
2035 parameters.
2036 </p>
2037 <p>Examples:
2038 </p>
2039 <p>
2040 </p>
2041 <blockquote class="text">
2042 <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 0"
2043 </p>
2044 <p>S: "NAME: studio monitor left"
2045 </p>
2046 <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
2047 </p>
2048 <p>&nbsp;&nbsp;&nbsp;"."
2049 </p>
2050 </blockquote><p>
2051
2052 </p>
2053 <p>
2054 </p>
2055 <blockquote class="text">
2056 <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 1"
2057 </p>
2058 <p>S: "NAME: studio monitor right"
2059 </p>
2060 <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
2061 </p>
2062 <p>&nbsp;&nbsp;&nbsp;"."
2063 </p>
2064 </blockquote><p>
2065
2066 </p>
2067 <p>
2068 </p>
2069 <blockquote class="text">
2070 <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"
2071 </p>
2072 <p>S: "NAME: studio monitor left"
2073 </p>
2074 <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: true"
2075 </p>
2076 <p>&nbsp;&nbsp;&nbsp;"MIX_CHANNEL_DESTINATION: 1"
2077 </p>
2078 <p>&nbsp;&nbsp;&nbsp;"."
2079 </p>
2080 </blockquote><p>
2081
2082 </p>
2083 <p>
2084 </p>
2085 <blockquote class="text">
2086 <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"
2087 </p>
2088 <p>S: "NAME: 'ardour (left)'"
2089 </p>
2090 <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
2091 </p>
2092 <p>&nbsp;&nbsp;&nbsp;"JACK_BINDINGS: 'ardour:0'"
2093 </p>
2094 <p>&nbsp;&nbsp;&nbsp;"."
2095 </p>
2096 </blockquote><p>
2097
2098 </p>
2099 <a name="GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO"></a><br /><hr />
2100 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2101 <a name="rfc.section.6.2.12"></a><h3>6.2.12.&nbsp;
2102 Getting information about specific audio channel parameter</h3>
2103
2104 <p>Use the following command to get detailed information about specific audio channel parameter:
2105 </p>
2106 <p>
2107 </p>
2108 <blockquote class="text">
2109 <p>GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO &lt;dev-id&gt; &lt;chan&gt; &lt;param&gt;
2110 </p>
2111 </blockquote><p>
2112
2113 </p>
2114 <p>Where &lt;dev-id&gt; is the numerical ID of the audio output device as returned by the
2115 <a class='info' href='#CREATE AUDIO_OUTPUT_DEVICE'>"CREATE AUDIO_OUTPUT_DEVICE"<span> (</span><span class='info'>Creating an audio output device</span><span>)</span></a>
2116 or <a class='info' href='#LIST AUDIO_OUTPUT_DEVICES'>"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class='info'>Getting all created audio output device list</span><span>)</span></a>
2117 command, &lt;chan&gt; the audio channel number
2118 and &lt;param&gt; a specific channel parameter name for which information should
2119 be obtained (as returned by the <a class='info' href='#GET AUDIO_OUTPUT_CHANNEL INFO'>"GET AUDIO_OUTPUT_CHANNEL INFO"<span> (</span><span class='info'>Getting information about an audio channel</span><span>)</span></a> command).
2120 </p>
2121 <p>Possible Answers:
2122 </p>
2123 <p>
2124 </p>
2125 <blockquote class="text">
2126 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2127 Each answer line begins with the information category name
2128 followed by a colon and then a space character &lt;SP&gt; and finally
2129 the info character string to that info category. There are
2130 information which is always returned, independently of the
2131 given channel parameter and there is optional information
2132 which is only shown dependently to the given audio channel. At
2133 the moment the following information categories are defined:
2134 </p>
2135 <p>
2136 </p>
2137 <blockquote class="text">
2138 <p>TYPE -
2139 </p>
2140 <blockquote class="text">
2141 <p>either "BOOL" for boolean value(s) or "INT" for integer
2142 value(s) or "FLOAT" for dotted number(s) or "STRING" for
2143 character string(s)
2144 (always returned)
2145 </p>
2146 </blockquote>
2147
2148
2149 <p>DESCRIPTION -
2150 </p>
2151 <blockquote class="text">
2152 <p>arbitrary text describing the purpose of the parameter (always returned)
2153 </p>
2154 </blockquote>
2155
2156
2157 <p>FIX -
2158 </p>
2159 <blockquote class="text">
2160 <p>either true or false, if true then this parameter is
2161 read only, thus cannot be altered
2162 (always returned)
2163 </p>
2164 </blockquote>
2165
2166
2167 <p>MULTIPLICITY -
2168 </p>
2169 <blockquote class="text">
2170 <p>either true or false, defines if this parameter allows
2171 only one value or a list of values, where true means
2172 multiple values and false only a single value allowed
2173 (always returned)
2174 </p>
2175 </blockquote>
2176
2177
2178 <p>RANGE_MIN -
2179 </p>
2180 <blockquote class="text">
2181 <p>defines lower limit of the allowed value range for this
2182 parameter, can be an integer value as well as a dotted
2183 number, usually used in conjunction with 'RANGE_MAX',
2184 but may also appear without
2185 (optionally returned, dependent to driver and channel
2186 parameter)
2187 </p>
2188 </blockquote>
2189
2190
2191 <p>RANGE_MAX -
2192 </p>
2193 <blockquote class="text">
2194 <p>defines upper limit of the allowed value range for this
2195 parameter, can be an integer value as well as a dotted
2196 number, usually used in conjunction with 'RANGE_MIN',
2197 but may also appear without
2198 (optionally returned, dependent to driver and channel
2199 parameter)
2200 </p>
2201 </blockquote>
2202
2203
2204 <p>POSSIBILITIES -
2205 </p>
2206 <blockquote class="text">
2207 <p>comma separated list of possible values for this
2208 parameter, character strings are encapsulated into
2209 apostrophes
2210 (optionally returned, dependent to driver and channel
2211 parameter)
2212 </p>
2213 </blockquote>
2214
2215
2216 </blockquote>
2217
2218
2219 <p>The mentioned fields above don't have to be in particular order.
2220 </p>
2221 </blockquote><p>
2222
2223 </p>
2224 <p>Example:
2225 </p>
2226 <p>
2227 </p>
2228 <blockquote class="text">
2229 <p>C: "GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO 1 0 JACK_BINDINGS"
2230 </p>
2231 <p>S: "DESCRIPTION: bindings to other JACK clients"
2232 </p>
2233 <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
2234 </p>
2235 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
2236 </p>
2237 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"
2238 </p>
2239 <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"
2240 </p>
2241 <p>&nbsp;&nbsp;&nbsp;"."
2242 </p>
2243 </blockquote><p>
2244
2245 </p>
2246 <a name="SET AUDIO_OUTPUT_CHANNEL_PARAMETER"></a><br /><hr />
2247 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2248 <a name="rfc.section.6.2.13"></a><h3>6.2.13.&nbsp;
2249 Changing settings of audio output channels</h3>
2250
2251 <p>Use the following command to alter a specific setting of an audio output channel:
2252 </p>
2253 <p>
2254 </p>
2255 <blockquote class="text">
2256 <p>SET AUDIO_OUTPUT_CHANNEL_PARAMETER &lt;dev-id&gt; &lt;chn&gt; &lt;key&gt;=&lt;value&gt;
2257 </p>
2258 </blockquote><p>
2259
2260 </p>
2261 <p>Where &lt;dev-id&gt; should be replaced by the numerical ID of the audio output device as returned by the
2262 <a class='info' href='#CREATE AUDIO_OUTPUT_DEVICE'>"CREATE AUDIO_OUTPUT_DEVICE"<span> (</span><span class='info'>Creating an audio output device</span><span>)</span></a>
2263 or <a class='info' href='#LIST AUDIO_OUTPUT_DEVICES'>"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class='info'>Getting all created audio output device list</span><span>)</span></a>
2264 command, &lt;chn&gt; by the audio channel number, &lt;key&gt; by the name of the
2265 parameter to change and &lt;value&gt; by the new value for this parameter.
2266 </p>
2267 <p>Possible Answers:
2268 </p>
2269 <p>
2270 </p>
2271 <blockquote class="text">
2272 <p>"OK" -
2273 </p>
2274 <blockquote class="text">
2275 <p>in case setting was successfully changed
2276 </p>
2277 </blockquote>
2278
2279
2280 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2281 </p>
2282 <blockquote class="text">
2283 <p>in case setting was changed successfully, but there are
2284 noteworthy issue(s) related, providing an appropriate
2285 warning code and warning message
2286 </p>
2287 </blockquote>
2288
2289
2290 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2291 </p>
2292 <blockquote class="text">
2293 <p>in case it failed, providing an appropriate error code and
2294 error message
2295 </p>
2296 </blockquote>
2297
2298
2299 </blockquote><p>
2300
2301 </p>
2302 <p>Example:
2303 </p>
2304 <p>
2305 </p>
2306 <blockquote class="text">
2307 <p>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"
2308 </p>
2309 <p>S: "OK"
2310 </p>
2311 </blockquote><p>
2312
2313 </p>
2314 <p>
2315 </p>
2316 <blockquote class="text">
2317 <p>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"
2318 </p>
2319 <p>S: "OK"
2320 </p>
2321 </blockquote><p>
2322
2323 </p>
2324 <a name="anchor10"></a><br /><hr />
2325 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2326 <a name="rfc.section.6.3"></a><h3>6.3.&nbsp;
2327 Configuring MIDI input drivers</h3>
2328
2329 <p>Instances of drivers in LinuxSampler are called devices. You can use
2330 multiple MIDI devices simultaneously, e.g. to use MIDI over ethernet as
2331 MIDI input on one sampler channel and ALSA as MIDI input on another sampler
2332 channel. For particular MIDI input systems it's also possible to create
2333 several devices of the same MIDI input type. This chapter describes all
2334 commands to configure LinuxSampler's MIDI input devices and their parameters.
2335 </p>
2336 <p>Instead of defining commands and parameters for each driver individually,
2337 all possible parameters, their meanings and possible values have to be obtained
2338 at runtime. This makes the protocol a bit abstract, but has the advantage, that
2339 front-ends can be written independently of what drivers are currently implemented
2340 and what parameters these drivers are actually offering. This means front-ends can
2341 even handle drivers which are implemented somewhere in future without modifying
2342 the front-end at all.
2343 </p>
2344 <p>Commands for configuring MIDI input devices are pretty much the same as the
2345 commands for configuring audio output drivers, already described in the last
2346 chapter.
2347 </p>
2348 <p>Note: examples in this chapter showing particular parameters of drivers are
2349 not meant as specification of the drivers' parameters. Driver implementations in
2350 LinuxSampler might have complete different parameter names and meanings than shown
2351 in these examples or might change in future, so these examples are only meant for
2352 showing how to retrieve what parameters drivers are offering, how to retrieve their
2353 possible values, etc.
2354 </p>
2355 <a name="GET AVAILABLE_MIDI_INPUT_DRIVERS"></a><br /><hr />
2356 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2357 <a name="rfc.section.6.3.1"></a><h3>6.3.1.&nbsp;
2358 Getting amount of available MIDI input drivers</h3>
2359
2360 <p>Use the following command to get the number of
2361 MIDI input drivers currently available for the
2362 LinuxSampler instance:
2363 </p>
2364 <p>
2365 </p>
2366 <blockquote class="text">
2367 <p>GET AVAILABLE_MIDI_INPUT_DRIVERS
2368 </p>
2369 </blockquote><p>
2370
2371 </p>
2372 <p>Possible Answers:
2373 </p>
2374 <p>
2375 </p>
2376 <blockquote class="text">
2377 <p>LinuxSampler will answer by sending the
2378 number of available MIDI input drivers.
2379 </p>
2380 </blockquote><p>
2381
2382 </p>
2383 <p>Example:
2384 </p>
2385 <p>
2386 </p>
2387 <blockquote class="text">
2388 <p>C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"
2389 </p>
2390 <p>S: "2"
2391 </p>
2392 </blockquote><p>
2393
2394 </p>
2395 <a name="LIST AVAILABLE_MIDI_INPUT_DRIVERS"></a><br /><hr />
2396 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2397 <a name="rfc.section.6.3.2"></a><h3>6.3.2.&nbsp;
2398 Getting all available MIDI input drivers</h3>
2399
2400 <p>Use the following command to list all MIDI input drivers currently available
2401 for the LinuxSampler instance:
2402 </p>
2403 <p>
2404 </p>
2405 <blockquote class="text">
2406 <p>LIST AVAILABLE_MIDI_INPUT_DRIVERS
2407 </p>
2408 </blockquote><p>
2409
2410 </p>
2411 <p>Possible Answers:
2412 </p>
2413 <p>
2414 </p>
2415 <blockquote class="text">
2416 <p>LinuxSampler will answer by sending comma separated character
2417 strings, each symbolizing a MIDI input driver.
2418 </p>
2419 </blockquote><p>
2420
2421 </p>
2422 <p>Example:
2423 </p>
2424 <p>
2425 </p>
2426 <blockquote class="text">
2427 <p>C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
2428 </p>
2429 <p>S: "ALSA,JACK"
2430 </p>
2431 </blockquote><p>
2432
2433 </p>
2434 <a name="GET MIDI_INPUT_DRIVER INFO"></a><br /><hr />
2435 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2436 <a name="rfc.section.6.3.3"></a><h3>6.3.3.&nbsp;
2437 Getting information about a specific MIDI input driver</h3>
2438
2439 <p>Use the following command to get detailed information about a specific MIDI input driver:
2440 </p>
2441 <p>
2442 </p>
2443 <blockquote class="text">
2444 <p>GET MIDI_INPUT_DRIVER INFO &lt;midi-input-driver&gt;
2445 </p>
2446 </blockquote><p>
2447
2448 </p>
2449 <p>Where &lt;midi-input-driver&gt; is the name of the MIDI input driver as returned
2450 by the <a class='info' href='#LIST AVAILABLE_MIDI_INPUT_DRIVERS'>"LIST AVAILABLE_MIDI_INPUT_DRIVERS"<span> (</span><span class='info'>Getting all available MIDI input drivers</span><span>)</span></a> command.
2451 </p>
2452 <p>Possible Answers:
2453 </p>
2454 <p>
2455 </p>
2456 <blockquote class="text">
2457 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2458 Each answer line begins with the information category name
2459 followed by a colon and then a space character &lt;SP&gt; and finally
2460 the info character string to that info category. At the moment
2461 the following information categories are defined:
2462 </p>
2463 <p>
2464 </p>
2465 <blockquote class="text">
2466 <p>DESCRIPTION -
2467 </p>
2468 <blockquote class="text">
2469 <p>arbitrary description text about the MIDI input driver
2470 </p>
2471 </blockquote>
2472
2473
2474 <p>VERSION -
2475 </p>
2476 <blockquote class="text">
2477 <p>arbitrary character string regarding the driver's version
2478 </p>
2479 </blockquote>
2480
2481
2482 <p>PARAMETERS -
2483 </p>
2484 <blockquote class="text">
2485 <p>comma separated list of all parameters available for the given MIDI input driver
2486 </p>
2487 </blockquote>
2488
2489
2490 </blockquote>
2491
2492
2493 <p>The mentioned fields above don't have to be in particular order.
2494 </p>
2495 </blockquote><p>
2496
2497 </p>
2498 <p>Example:
2499 </p>
2500 <p>
2501 </p>
2502 <blockquote class="text">
2503 <p>C: "GET MIDI_INPUT_DRIVER INFO ALSA"
2504 </p>
2505 <p>S: "DESCRIPTION: Advanced Linux Sound Architecture"
2506 </p>
2507 <p>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"
2508 </p>
2509 <p>&nbsp;&nbsp;&nbsp;"PARAMETERS: DRIVER,ACTIVE"
2510 </p>
2511 <p>&nbsp;&nbsp;&nbsp;"."
2512 </p>
2513 </blockquote><p>
2514
2515 </p>
2516 <a name="GET MIDI_INPUT_DRIVER_PARAMETER INFO"></a><br /><hr />
2517 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2518 <a name="rfc.section.6.3.4"></a><h3>6.3.4.&nbsp;
2519 Getting information about specific MIDI input driver parameter</h3>
2520
2521 <p>Use the following command to get detailed information about a specific parameter of a specific MIDI input driver:
2522 </p>
2523 <p>
2524 </p>
2525 <blockquote class="text">
2526 <p>GET MIDI_INPUT_DRIVER_PARAMETER INFO &lt;midit&gt; &lt;param&gt; [&lt;deplist&gt;]
2527 </p>
2528 </blockquote><p>
2529
2530 </p>
2531 <p>Where &lt;midit&gt; is the name of the MIDI input driver as returned
2532 by the <a class='info' href='#LIST AVAILABLE_MIDI_INPUT_DRIVERS'>"LIST AVAILABLE_MIDI_INPUT_DRIVERS"<span> (</span><span class='info'>Getting all available MIDI input drivers</span><span>)</span></a> command, &lt;param&gt; a specific
2533 parameter name for which information should be obtained (as returned by the
2534 <a class='info' href='#GET MIDI_INPUT_DRIVER INFO'>"GET MIDI_INPUT_DRIVER INFO"<span> (</span><span class='info'>Getting information about a specific MIDI input driver</span><span>)</span></a> command) and &lt;deplist&gt; is an optional list
2535 of parameters on which the sought parameter &lt;param&gt; depends on,
2536 &lt;deplist&gt; is a key-value pair list in form of "key1=val1 key2=val2 ...",
2537 where character string values are encapsulated into apostrophes ('). Arguments
2538 given with &lt;deplist&gt; which are not dependency parameters of &lt;param&gt;
2539 will be ignored, means the front-end application can simply put all parameters
2540 in &lt;deplist&gt; with the values selected by the user.
2541 </p>
2542 <p>Possible Answers:
2543 </p>
2544 <p>LinuxSampler will answer by sending a &lt;CRLF> separated list.
2545 Each answer line begins with the information category name
2546 followed by a colon and then a space character &lt;SP> and finally
2547 the info character string to that info category. There is
2548 information which is always returned, independent of the
2549 given driver parameter and there is optional information
2550 which is only shown dependent to given driver parameter. At
2551 the moment the following information categories are defined:
2552 </p>
2553 <p>
2554 </p>
2555 <blockquote class="text">
2556 <p>TYPE -
2557 </p>
2558 <blockquote class="text">
2559 <p>either "BOOL" for boolean value(s) or "INT" for integer
2560 value(s) or "FLOAT" for dotted number(s) or "STRING" for
2561 character string(s)
2562 (always returned, no matter which driver parameter)
2563 </p>
2564 </blockquote>
2565
2566
2567 <p>DESCRIPTION -
2568 </p>
2569 <blockquote class="text">
2570 <p>arbitrary text describing the purpose of the parameter
2571 (always returned, no matter which driver parameter)
2572 </p>
2573 </blockquote>
2574
2575
2576 <p>MANDATORY -
2577 </p>
2578 <blockquote class="text">
2579 <p>either true or false, defines if this parameter must be
2580 given when the device is to be created with the
2581 <a class='info' href='#CREATE MIDI_INPUT_DEVICE'>'CREATE MIDI_INPUT_DEVICE'<span> (</span><span class='info'>Creating a MIDI input device</span><span>)</span></a> command
2582 (always returned, no matter which driver parameter)
2583 </p>
2584 </blockquote>
2585
2586
2587 <p>FIX -
2588 </p>
2589 <blockquote class="text">
2590 <p>either true or false, if false then this parameter can
2591 be changed at any time, once the device is created by
2592 the <a class='info' href='#CREATE MIDI_INPUT_DEVICE'>'CREATE MIDI_INPUT_DEVICE'<span> (</span><span class='info'>Creating a MIDI input device</span><span>)</span></a> command
2593 (always returned, no matter which driver parameter)
2594 </p>
2595 </blockquote>
2596
2597
2598 <p>MULTIPLICITY -
2599 </p>
2600 <blockquote class="text">
2601 <p>either true or false, defines if this parameter allows
2602 only one value or a list of values, where true means
2603 multiple values and false only a single value allowed
2604 (always returned, no matter which driver parameter)
2605 </p>
2606 </blockquote>
2607
2608
2609 <p>DEPENDS -
2610 </p>
2611 <blockquote class="text">
2612 <p>comma separated list of parameters this parameter depends
2613 on, means the values for fields 'DEFAULT', 'RANGE_MIN',
2614 'RANGE_MAX' and 'POSSIBILITIES' might depend on these
2615 listed parameters, for example assuming that an audio
2616 driver (like the ALSA driver) offers parameters 'card'
2617 and 'samplerate' then parameter 'samplerate' would
2618 depend on 'card' because the possible values for
2619 'samplerate' depends on the sound card which can be
2620 chosen by the 'card' parameter
2621 (optionally returned, dependent to driver parameter)
2622 </p>
2623 </blockquote>
2624
2625
2626 <p>DEFAULT -
2627 </p>
2628 <blockquote class="text">
2629 <p>reflects the default value for this parameter which is
2630 used when the device is created and not explicitly
2631 given with the <a class='info' href='#CREATE MIDI_INPUT_DEVICE'>'CREATE MIDI_INPUT_DEVICE'<span> (</span><span class='info'>Creating a MIDI input device</span><span>)</span></a> command,
2632 in case of MULTIPLCITY=true, this is a comma separated
2633 list, that's why character strings are encapsulated into
2634 apostrophes (')
2635 (optionally returned, dependent to driver parameter)
2636 </p>
2637 </blockquote>
2638
2639
2640 <p>RANGE_MIN -
2641 </p>
2642 <blockquote class="text">
2643 <p>defines lower limit of the allowed value range for this
2644 parameter, can be an integer value as well as a dotted
2645 number, this parameter is often used in conjunction
2646 with RANGE_MAX, but may also appear without
2647 (optionally returned, dependent to driver parameter)
2648 </p>
2649 </blockquote>
2650
2651
2652 <p>RANGE_MAX -
2653 </p>
2654 <blockquote class="text">
2655 <p>defines upper limit of the allowed value range for this
2656 parameter, can be an integer value as well as a dotted
2657 number, this parameter is often used in conjunction with
2658 RANGE_MIN, but may also appear without
2659 (optionally returned, dependent to driver parameter)
2660 </p>
2661 </blockquote>
2662
2663
2664 <p>POSSIBILITIES -
2665 </p>
2666 <blockquote class="text">
2667 <p>comma separated list of possible values for this
2668 parameter, character strings are encapsulated into
2669 apostrophes
2670 (optionally returned, dependent to driver parameter)
2671 </p>
2672 </blockquote>
2673
2674
2675 </blockquote><p>
2676
2677 </p>
2678 <p>The mentioned fields above don't have to be in particular order.
2679 </p>
2680 <p>Example:
2681 </p>
2682 <p>
2683 </p>
2684 <blockquote class="text">
2685 <p>C: "GET MIDI_INPUT_DRIVER_PARAMETER INFO ALSA ACTIVE"
2686 </p>
2687 <p>S: "DESCRIPTION: Whether device is enabled"
2688 </p>
2689 <p>&nbsp;&nbsp;&nbsp;"TYPE: BOOL"
2690 </p>
2691 <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
2692 </p>
2693 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
2694 </p>
2695 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
2696 </p>
2697 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: true"
2698 </p>
2699 <p>&nbsp;&nbsp;&nbsp;"."
2700 </p>
2701 </blockquote><p>
2702
2703 </p>
2704 <a name="CREATE MIDI_INPUT_DEVICE"></a><br /><hr />
2705 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2706 <a name="rfc.section.6.3.5"></a><h3>6.3.5.&nbsp;
2707 Creating a MIDI input device</h3>
2708
2709 <p>Use the following command to create a new MIDI input device for the desired MIDI input system:
2710 </p>
2711 <p>
2712 </p>
2713 <blockquote class="text">
2714 <p>CREATE MIDI_INPUT_DEVICE &lt;midi-input-driver&gt; [&lt;param-list&gt;]
2715 </p>
2716 </blockquote><p>
2717
2718 </p>
2719 <p>Where &lt;midi-input-driver&gt; should be replaced by the desired MIDI input system as returned
2720 by the <a class='info' href='#LIST AVAILABLE_MIDI_INPUT_DRIVERS'>"LIST AVAILABLE_MIDI_INPUT_DRIVERS"<span> (</span><span class='info'>Getting all available MIDI input drivers</span><span>)</span></a> command and &lt;param-list&gt; by an
2721 optional list of driver specific parameters in form of "key1=val1 key2=val2 ...", where
2722 character string values should be encapsulated into apostrophes (').
2723 Note that there might be drivers which require parameter(s) to be
2724 given with this command. Use the previously described commands in
2725 this chapter to get that information.
2726 </p>
2727 <p>Possible Answers:
2728 </p>
2729 <p>
2730 </p>
2731 <blockquote class="text">
2732 <p>"OK[&lt;device-id&gt;]" -
2733 </p>
2734 <blockquote class="text">
2735 <p>in case the device was successfully created, where
2736 &lt;device-id&gt; is the numerical ID of the new device
2737 </p>
2738 </blockquote>
2739
2740
2741 <p>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2742 </p>
2743 <blockquote class="text">
2744 <p>in case the driver was loaded successfully, where
2745 &lt;device-id&gt; is the numerical ID of the new device, but
2746 there are noteworthy issue(s) related, providing an
2747 appropriate warning code and warning message
2748 </p>
2749 </blockquote>
2750
2751
2752 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2753 </p>
2754 <blockquote class="text">
2755 <p>in case it failed, providing an appropriate error code and error message
2756 </p>
2757 </blockquote>
2758
2759
2760 </blockquote><p>
2761
2762 </p>
2763 <p>Example:
2764 </p>
2765 <p>
2766 </p>
2767 <blockquote class="text">
2768 <p>C: "CREATE MIDI_INPUT_DEVICE ALSA"
2769 </p>
2770 <p>S: "OK[0]"
2771 </p>
2772 </blockquote><p>
2773
2774 </p>
2775 <a name="DESTROY MIDI_INPUT_DEVICE"></a><br /><hr />
2776 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2777 <a name="rfc.section.6.3.6"></a><h3>6.3.6.&nbsp;
2778 Destroying a MIDI input device</h3>
2779
2780 <p>Use the following command to destroy a created MIDI input device:
2781 </p>
2782 <p>
2783 </p>
2784 <blockquote class="text">
2785 <p>DESTROY MIDI_INPUT_DEVICE &lt;device-id&gt;
2786 </p>
2787 </blockquote><p>
2788
2789 </p>
2790 <p>Where &lt;device-id&gt; should be replaced by the device's numerical ID as returned by the
2791 <a class='info' href='#CREATE MIDI_INPUT_DEVICE'>"CREATE MIDI_INPUT_DEVICE"<span> (</span><span class='info'>Creating a MIDI input device</span><span>)</span></a>
2792 or <a class='info' href='#LIST MIDI_INPUT_DEVICES'>"LIST MIDI_INPUT_DEVICES"<span> (</span><span class='info'>Getting all created MIDI input device list</span><span>)</span></a>
2793 command.
2794 </p>
2795 <p>Possible Answers:
2796 </p>
2797 <p>
2798 </p>
2799 <blockquote class="text">
2800 <p>"OK" -
2801 </p>
2802 <blockquote class="text">
2803 <p>in case the device was successfully destroyed
2804 </p>
2805 </blockquote>
2806
2807
2808 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2809 </p>
2810 <blockquote class="text">
2811 <p>in case the device was destroyed, but there are noteworthy
2812 issue(s) related, providing an appropriate warning code and
2813 warning message
2814 </p>
2815 </blockquote>
2816
2817
2818 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2819 </p>
2820 <blockquote class="text">
2821 <p>in case it failed, providing an appropriate error code and error message
2822 </p>
2823 </blockquote>
2824
2825
2826 </blockquote><p>
2827
2828 </p>
2829 <p>Example:
2830 </p>
2831 <p>
2832 </p>
2833 <blockquote class="text">
2834 <p>C: "DESTROY MIDI_INPUT_DEVICE 0"
2835 </p>
2836 <p>S: "OK"
2837 </p>
2838 </blockquote><p>
2839
2840 </p>
2841 <a name="GET MIDI_INPUT_DEVICES"></a><br /><hr />
2842 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2843 <a name="rfc.section.6.3.7"></a><h3>6.3.7.&nbsp;
2844 Getting all created MIDI input device count</h3>
2845
2846 <p>Use the following command to count all created MIDI input devices:
2847 </p>
2848 <p>
2849 </p>
2850 <blockquote class="text">
2851 <p>GET MIDI_INPUT_DEVICES
2852 </p>
2853 </blockquote><p>
2854
2855 </p>
2856 <p>Possible Answers:
2857 </p>
2858 <p>
2859 </p>
2860 <blockquote class="text">
2861 <p>LinuxSampler will answer by sending the current number of all
2862 MIDI input devices.
2863 </p>
2864 </blockquote><p>
2865
2866 </p>
2867 <p>Example:
2868 </p>
2869 <p>
2870 </p>
2871 <blockquote class="text">
2872 <p>C: "GET MIDI_INPUT_DEVICES"
2873 </p>
2874 <p>S: "3"
2875 </p>
2876 </blockquote><p>
2877
2878 </p>
2879 <a name="LIST MIDI_INPUT_DEVICES"></a><br /><hr />
2880 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2881 <a name="rfc.section.6.3.8"></a><h3>6.3.8.&nbsp;
2882 Getting all created MIDI input device list</h3>
2883
2884 <p>Use the following command to list all created MIDI input devices:
2885 </p>
2886 <p>
2887 </p>
2888 <blockquote class="text">
2889 <p>LIST MIDI_INPUT_DEVICES
2890 </p>
2891 </blockquote><p>
2892
2893 </p>
2894 <p>Possible Answers:
2895 </p>
2896 <p>
2897 </p>
2898 <blockquote class="text">
2899 <p>LinuxSampler will answer by sending a comma separated list
2900 with the numerical Ids of all created MIDI input devices.
2901 </p>
2902 </blockquote><p>
2903
2904 </p>
2905 <p>Examples:
2906 </p>
2907 <p>
2908 </p>
2909 <blockquote class="text">
2910 <p>C: "LIST MIDI_INPUT_DEVICES"
2911 </p>
2912 <p>S: "0,1,2"
2913 </p>
2914 </blockquote><p>
2915
2916 </p>
2917 <p>
2918 </p>
2919 <blockquote class="text">
2920 <p>C: "LIST MIDI_INPUT_DEVICES"
2921 </p>
2922 <p>S: "1,3"
2923 </p>
2924 </blockquote><p>
2925
2926 </p>
2927 <a name="GET MIDI_INPUT_DEVICE INFO"></a><br /><hr />
2928 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2929 <a name="rfc.section.6.3.9"></a><h3>6.3.9.&nbsp;
2930 Getting current settings of a MIDI input device</h3>
2931
2932 <p>Use the following command to get current settings of a specific, created MIDI input device:
2933 </p>
2934 <p>
2935 </p>
2936 <blockquote class="text">
2937 <p>GET MIDI_INPUT_DEVICE INFO &lt;device-id&gt;
2938 </p>
2939 </blockquote><p>
2940
2941 </p>
2942 <p>Where &lt;device-id&gt; is the numerical ID of the MIDI input device as returned by the
2943 <a class='info' href='#CREATE MIDI_INPUT_DEVICE'>"CREATE MIDI_INPUT_DEVICE"<span> (</span><span class='info'>Creating a MIDI input device</span><span>)</span></a>
2944 or <a class='info' href='#LIST MIDI_INPUT_DEVICES'>"LIST MIDI_INPUT_DEVICES"<span> (</span><span class='info'>Getting all created MIDI input device list</span><span>)</span></a>
2945 command.
2946 </p>
2947 <p>Possible Answers:
2948 </p>
2949 <p>
2950 </p>
2951 <blockquote class="text">
2952 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2953 Each answer line begins with the information category name
2954 followed by a colon and then a space character &lt;SP&gt; and finally
2955 the info character string to that info category. As some
2956 parameters might allow multiple values, character strings are
2957 encapsulated into apostrophes ('). At the moment the following
2958 information categories are defined (independent of driver):
2959 </p>
2960 <p>
2961 </p>
2962 <blockquote class="text">
2963 <p>DRIVER -
2964 </p>
2965 <blockquote class="text">
2966 <p>identifier of the used MIDI input driver, as e.g.
2967 returned by the <a class='info' href='#LIST AVAILABLE_MIDI_INPUT_DRIVERS'>"LIST AVAILABLE_MIDI_INPUT_DRIVERS"<span> (</span><span class='info'>Getting all available MIDI input drivers</span><span>)</span></a>
2968 command
2969 </p>
2970 </blockquote>
2971
2972
2973 </blockquote>
2974
2975 <blockquote class="text">
2976 <p>ACTIVE -
2977 </p>
2978 <blockquote class="text">
2979 <p>either true or false, if false then the MIDI device is
2980 inactive and doesn't listen to any incoming MIDI events
2981 and thus doesn't forward them to connected sampler
2982 channels
2983 </p>
2984 </blockquote>
2985
2986
2987 </blockquote>
2988
2989
2990 </blockquote><p>
2991
2992 </p>
2993 <p>The mentioned fields above don't have to be in particular
2994 order. The fields above are only those fields which are
2995 returned by all MIDI input devices. Every MIDI input driver
2996 might have its own, additional driver specific parameters (see
2997 <a class='info' href='#GET MIDI_INPUT_DRIVER INFO'>"GET MIDI_INPUT_DRIVER INFO"<span> (</span><span class='info'>Getting information about a specific MIDI input driver</span><span>)</span></a> command) which are also returned
2998 by this command.
2999 </p>
3000 <p>Example:
3001 </p>
3002 <p>
3003 </p>
3004 <blockquote class="text">
3005 <p>C: "GET MIDI_INPUT_DEVICE INFO 0"
3006 </p>
3007 <p>S: "DRIVER: ALSA"
3008 </p>
3009 <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
3010 </p>
3011 <p>&nbsp;&nbsp;&nbsp;"."
3012 </p>
3013 </blockquote><p>
3014
3015 </p>
3016 <a name="SET MIDI_INPUT_DEVICE_PARAMETER"></a><br /><hr />
3017 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3018 <a name="rfc.section.6.3.10"></a><h3>6.3.10.&nbsp;
3019 Changing settings of MIDI input devices</h3>
3020
3021 <p>Use the following command to alter a specific setting of a created MIDI input device:
3022 </p>
3023 <p>
3024 </p>
3025 <blockquote class="text">
3026 <p>SET MIDI_INPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;
3027 </p>
3028 </blockquote><p>
3029
3030 </p>
3031 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
3032 MIDI input device as returned by the
3033 <a class='info' href='#CREATE MIDI_INPUT_DEVICE'>"CREATE MIDI_INPUT_DEVICE"<span> (</span><span class='info'>Creating a MIDI input device</span><span>)</span></a>
3034 or <a class='info' href='#LIST MIDI_INPUT_DEVICES'>"LIST MIDI_INPUT_DEVICES"<span> (</span><span class='info'>Getting all created MIDI input device list</span><span>)</span></a>
3035 command, &lt;key&gt; by the name of the parameter to change and
3036 &lt;value&gt; by the new value for this parameter.
3037 </p>
3038 <p>Possible Answers:
3039 </p>
3040 <p>
3041 </p>
3042 <blockquote class="text">
3043 <p>"OK" -
3044 </p>
3045 <blockquote class="text">
3046 <p>in case setting was successfully changed
3047 </p>
3048 </blockquote>
3049
3050
3051 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3052 </p>
3053 <blockquote class="text">
3054 <p>in case setting was changed successfully, but there are
3055 noteworthy issue(s) related, providing an appropriate
3056 warning code and warning message
3057 </p>
3058 </blockquote>
3059
3060
3061 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3062 </p>
3063 <blockquote class="text">
3064 <p>in case it failed, providing an appropriate error code and error message
3065 </p>
3066 </blockquote>
3067
3068
3069 </blockquote><p>
3070
3071 </p>
3072 <p>Example:
3073 </p>
3074 <p>
3075 </p>
3076 <blockquote class="text">
3077 <p>C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"
3078 </p>
3079 <p>S: "OK"
3080 </p>
3081 </blockquote><p>
3082
3083 </p>
3084 <a name="GET MIDI_INPUT_PORT INFO"></a><br /><hr />
3085 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3086 <a name="rfc.section.6.3.11"></a><h3>6.3.11.&nbsp;
3087 Getting information about a MIDI port</h3>
3088
3089 <p>Use the following command to get information about a MIDI port:
3090 </p>
3091 <p>
3092 </p>
3093 <blockquote class="text">
3094 <p>GET MIDI_INPUT_PORT INFO &lt;device-id&gt; &lt;midi-port&gt;
3095 </p>
3096 </blockquote><p>
3097
3098 </p>
3099 <p>Where &lt;device-id&gt; is the numerical ID of the MIDI input device as returned by the
3100 <a class='info' href='#CREATE MIDI_INPUT_DEVICE'>"CREATE MIDI_INPUT_DEVICE"<span> (</span><span class='info'>Creating a MIDI input device</span><span>)</span></a>
3101 or <a class='info' href='#LIST MIDI_INPUT_DEVICES'>"LIST MIDI_INPUT_DEVICES"<span> (</span><span class='info'>Getting all created MIDI input device list</span><span>)</span></a>
3102 command and &lt;midi-port&gt; the MIDI input port number.
3103 </p>
3104 <p>Possible Answers:
3105 </p>
3106 <p>
3107 </p>
3108 <blockquote class="text">
3109 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3110 Each answer line begins with the information category name
3111 followed by a colon and then a space character &lt;SP&gt; and finally
3112 the info character string to that info category. At the moment
3113 the following information categories are defined:
3114 </p>
3115 <p>NAME -
3116 </p>
3117 <blockquote class="text">
3118 <p>arbitrary character string naming the port
3119 </p>
3120 </blockquote>
3121
3122
3123 </blockquote><p>
3124
3125 </p>
3126 <p>The field above is only the one which is returned by all MIDI
3127 ports regardless of the MIDI driver and port. Every MIDI port
3128 might have its own, additional driver and port specific
3129 parameters.
3130 </p>
3131 <p>Example:
3132 </p>
3133 <p>
3134 </p>
3135 <blockquote class="text">
3136 <p>C: "GET MIDI_INPUT_PORT INFO 0 0"
3137 </p>
3138 <p>S: "NAME: 'Masterkeyboard'"
3139 </p>
3140 <p>&nbsp;&nbsp;&nbsp;"ALSA_SEQ_BINDINGS: '64:0'"
3141 </p>
3142 <p>&nbsp;&nbsp;&nbsp;"."
3143 </p>
3144 </blockquote><p>
3145
3146 </p>
3147 <a name="GET MIDI_INPUT_PORT_PARAMETER INFO"></a><br /><hr />
3148 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3149 <a name="rfc.section.6.3.12"></a><h3>6.3.12.&nbsp;
3150 Getting information about specific MIDI port parameter</h3>
3151
3152 <p>Use the following command to get detailed information about specific MIDI port parameter:
3153 </p>
3154 <p>
3155 </p>
3156 <blockquote class="text">
3157 <p>GET MIDI_INPUT_PORT_PARAMETER INFO &lt;dev-id&gt; &lt;port&gt; &lt;param&gt;
3158 </p>
3159 </blockquote><p>
3160
3161 </p>
3162 <p>Where &lt;dev-id&gt; is the numerical ID of the MIDI input device as returned by the
3163 <a class='info' href='#CREATE MIDI_INPUT_DEVICE'>"CREATE MIDI_INPUT_DEVICE"<span> (</span><span class='info'>Creating a MIDI input device</span><span>)</span></a>
3164 or <a class='info' href='#LIST MIDI_INPUT_DEVICES'>"LIST MIDI_INPUT_DEVICES"<span> (</span><span class='info'>Getting all created MIDI input device list</span><span>)</span></a>
3165 command, &lt;port&gt; the MIDI port number and
3166 &lt;param&gt; a specific port parameter name for which information should be
3167 obtained (as returned by the <a class='info' href='#GET MIDI_INPUT_PORT INFO'>"GET MIDI_INPUT_PORT INFO"<span> (</span><span class='info'>Getting information about a MIDI port</span><span>)</span></a> command).
3168 </p>
3169 <p>Possible Answers:
3170 </p>
3171 <p>
3172 </p>
3173 <blockquote class="text">
3174 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3175 Each answer line begins with the information category name
3176 followed by a colon and then a space character &lt;SP&gt; and finally
3177 the info character string to that info category. There is
3178 information which is always returned, independently of the
3179 given channel parameter and there is optional information
3180 which are only shown dependently to the given MIDI port. At the
3181 moment the following information categories are defined:
3182 </p>
3183 <p>TYPE -
3184 </p>
3185 <blockquote class="text">
3186 <p>either "BOOL" for boolean value(s) or "INT" for integer
3187 value(s) or "FLOAT" for dotted number(s) or "STRING" for
3188 character string(s)
3189 (always returned)
3190 </p>
3191 </blockquote>
3192
3193
3194 <p>DESCRIPTION -
3195 </p>
3196 <blockquote class="text">
3197 <p>arbitrary text describing the purpose of the parameter
3198 (always returned)
3199 </p>
3200 </blockquote>
3201
3202
3203 <p>FIX -
3204 </p>
3205 <blockquote class="text">
3206 <p>either true or false, if true then this parameter is
3207 read only, thus cannot be altered
3208 (always returned)
3209 </p>
3210 </blockquote>
3211
3212
3213 <p>MULTIPLICITY -
3214 </p>
3215 <blockquote class="text">
3216 <p>either true or false, defines if this parameter allows
3217 only one value or a list of values, where true means
3218 multiple values and false only a single value allowed
3219 (always returned)
3220 </p>
3221 </blockquote>
3222
3223
3224 <p>RANGE_MIN -
3225 </p>
3226 <blockquote class="text">
3227 <p>defines lower limit of the allowed value range for this
3228 parameter, can be an integer value as well as a dotted
3229 number, this parameter is usually used in conjunction
3230 with 'RANGE_MAX' but may also appear without
3231 (optionally returned, dependent to driver and port
3232 parameter)
3233 </p>
3234 </blockquote>
3235
3236
3237 <p>RANGE_MAX -
3238 </p>
3239 <blockquote class="text">
3240 <p>defines upper limit of the allowed value range for this
3241 parameter, can be an integer value as well as a dotted
3242 number, this parameter is usually used in conjunction
3243 with 'RANGE_MIN' but may also appear without
3244 (optionally returned, dependent to driver and port
3245 parameter)
3246 </p>
3247 </blockquote>
3248
3249
3250 <p>POSSIBILITIES -
3251 </p>
3252 <blockquote class="text">
3253 <p>comma separated list of possible values for this
3254 parameter, character strings are encapsulated into
3255 apostrophes
3256 (optionally returned, dependent to device and port
3257 parameter)
3258 </p>
3259 </blockquote>
3260
3261
3262 </blockquote><p>
3263
3264 </p>
3265 <p>The mentioned fields above don't have to be in particular order.
3266 </p>
3267 <p>Example:
3268 </p>
3269 <p>
3270 </p>
3271 <blockquote class="text">
3272 <p>C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"
3273 </p>
3274 <p>S: "DESCRIPTION: bindings to other ALSA sequencer clients"
3275 </p>
3276 <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
3277 </p>
3278 <p>&nbsp;&nbsp;&nbsp;"FIX: false"
3279 </p>
3280 <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"
3281 </p>
3282 <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: '64:0','68:0','68:1'"
3283 </p>
3284 <p>&nbsp;&nbsp;&nbsp;"."
3285 </p>
3286 </blockquote><p>
3287
3288 </p>
3289 <a name="SET MIDI_INPUT_PORT_PARAMETER"></a><br /><hr />
3290 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3291 <a name="rfc.section.6.3.13"></a><h3>6.3.13.&nbsp;
3292 Changing settings of MIDI input ports</h3>
3293
3294 <p>Use the following command to alter a specific setting of a MIDI input port:
3295 </p>
3296 <p>
3297 </p>
3298 <blockquote class="text">
3299 <p>SET MIDI_INPUT_PORT_PARAMETER &lt;device-id&gt; &lt;port&gt; &lt;key&gt;=&lt;value&gt;
3300 </p>
3301 </blockquote><p>
3302
3303 </p>
3304 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
3305 MIDI device as returned by the
3306 <a class='info' href='#CREATE MIDI_INPUT_DEVICE'>"CREATE MIDI_INPUT_DEVICE"<span> (</span><span class='info'>Creating a MIDI input device</span><span>)</span></a>
3307 or <a class='info' href='#LIST MIDI_INPUT_DEVICES'>"LIST MIDI_INPUT_DEVICES"<span> (</span><span class='info'>Getting all created MIDI input device list</span><span>)</span></a>
3308 command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of
3309 the parameter to change and &lt;value&gt; by the new value for this
3310 parameter (encapsulated into apostrophes) or NONE (not encapsulated into apostrophes)
3311 for specifying no value for parameters allowing a list of values.
3312 </p>
3313 <p>Possible Answers:
3314 </p>
3315 <p>
3316 </p>
3317 <blockquote class="text">
3318 <p>"OK" -
3319 </p>
3320 <blockquote class="text">
3321 <p>in case setting was successfully changed
3322 </p>
3323 </blockquote>
3324
3325
3326 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3327 </p>
3328 <blockquote class="text">
3329 <p>in case setting was changed successfully, but there are
3330 noteworthy issue(s) related, providing an appropriate
3331 warning code and warning message
3332 </p>
3333 </blockquote>
3334
3335
3336 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3337 </p>
3338 <blockquote class="text">
3339 <p>in case it failed, providing an appropriate error code and error message
3340 </p>
3341 </blockquote>
3342
3343
3344 </blockquote><p>
3345
3346 </p>
3347 <p>Example:
3348 </p>
3349 <p>
3350 </p>
3351 <blockquote class="text">
3352 <p>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='20:0'"
3353 </p>
3354 <p>S: "OK"
3355 </p>
3356 </blockquote><p>
3357
3358 </p>
3359 <p>
3360 </p>
3361 <blockquote class="text">
3362 <p>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE"
3363 </p>
3364 <p>S: "OK"
3365 </p>
3366 </blockquote><p>
3367
3368 </p>
3369 <a name="anchor11"></a><br /><hr />
3370 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3371 <a name="rfc.section.6.4"></a><h3>6.4.&nbsp;
3372 Configuring sampler channels</h3>
3373
3374 <p>The following commands describe how to add and remove sampler channels, associate a
3375 sampler channel with a sampler engine, load instruments and connect sampler channels to
3376 MIDI and audio devices.
3377 </p>
3378 <a name="LOAD INSTRUMENT"></a><br /><hr />
3379 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3380 <a name="rfc.section.6.4.1"></a><h3>6.4.1.&nbsp;
3381 Loading an instrument</h3>
3382
3383 <p>An instrument file can be loaded and assigned to a sampler channel by one of the following commands:
3384 </p>
3385 <p>
3386 </p>
3387 <blockquote class="text">
3388 <p>LOAD INSTRUMENT [NON_MODAL] '&lt;filename&gt;' &lt;instr-index&gt; &lt;sampler-channel&gt;
3389 </p>
3390 </blockquote><p>
3391
3392 </p>
3393 <p>Where &lt;filename&gt; is the name of the instrument file on the
3394 LinuxSampler instance's host system, &lt;instr-index&gt; the index of the
3395 instrument in the instrument file and &lt;sampler-channel> is the
3396 number of the sampler channel the instrument should be assigned to.
3397 Each sampler channel can only have one instrument.
3398 </p>
3399 <p>Notice: since LSCP 1.2 the &lt;filename&gt; argument supports
3400 escape characters for special characters (see chapter
3401 "<a class='info' href='#character_set'>Character Set and Escape Sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>"
3402 for details) and accordingly backslash characters in the filename
3403 MUST now be escaped as well!
3404 </p>
3405 <p>The difference between regular and NON_MODAL versions of the command
3406 is that the regular command returns OK only after the instrument has been
3407 fully loaded and the channel is ready to be used while NON_MODAL version
3408 returns immediately and a background process is launched to load the instrument
3409 on the channel. The <a class='info' href='#GET CHANNEL INFO'>GET CHANNEL INFO<span> (</span><span class='info'>Getting sampler channel information</span><span>)</span></a>
3410 command can be used to obtain loading
3411 progress from INSTRUMENT_STATUS field. LOAD command will perform sanity checks
3412 such as making sure that the file could be read and it is of a proper format
3413 and SHOULD return ERR and SHOULD not launch the background process should any
3414 errors be detected at that point.
3415 </p>
3416 <p>Possible Answers:
3417 </p>
3418 <p>
3419 </p>
3420 <blockquote class="text">
3421 <p>"OK" -
3422 </p>
3423 <blockquote class="text">
3424 <p>in case the instrument was successfully loaded
3425 </p>
3426 </blockquote>
3427
3428
3429 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3430 </p>
3431 <blockquote class="text">
3432 <p>in case the instrument was loaded successfully, but there
3433 are noteworthy issue(s) related (e.g. Engine doesn't support
3434 one or more patch parameters provided by the loaded
3435 instrument file), providing an appropriate warning code and
3436 warning message
3437 </p>
3438 </blockquote>
3439
3440
3441 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3442 </p>
3443 <blockquote class="text">
3444 <p>in case it failed, providing an appropriate error code and error message
3445 </p>
3446 </blockquote>
3447
3448
3449 </blockquote><p>
3450
3451 </p>
3452 <p>Example:
3453 </p>
3454 <p>
3455 </p>
3456 <blockquote class="text">
3457 <p>
3458 </p>
3459 </blockquote><p>
3460
3461 </p>
3462 <a name="LOAD ENGINE"></a><br /><hr />
3463 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3464 <a name="rfc.section.6.4.2"></a><h3>6.4.2.&nbsp;
3465 Loading a sampler engine</h3>
3466
3467 <p>A sampler engine type can be associated to a specific sampler
3468 channel by the following command:
3469 </p>
3470 <p>
3471 </p>
3472 <blockquote class="text">
3473 <p>LOAD ENGINE &lt;engine-name&gt; &lt;sampler-channel&gt;
3474 </p>
3475 </blockquote><p>
3476
3477 </p>
3478 <p>Where &lt;engine-name&gt; is an engine name as obtained by the
3479 <a class='info' href='#LIST AVAILABLE_ENGINES'>"LIST AVAILABLE_ENGINES"<span> (</span><span class='info'>Getting all available engines</span><span>)</span></a> command and &lt;sampler-channel&gt;
3480 the sampler channel as returned by the
3481 <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a> or
3482 <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command where
3483 the engine type should be assigned to. This command should be issued
3484 after adding a new sampler channel and before any other control
3485 commands on the new sampler channel. It can also be used to change
3486 the engine type of a sampler channel. This command has (currently) no
3487 way to define or force if a new engine instance should be created and
3488 assigned to the given sampler channel or if an already existing
3489 instance of that engine type, shared with other sampler channels,
3490 should be used.
3491 </p>
3492 <p>Possible Answers:
3493 </p>
3494 <p>
3495 </p>
3496 <blockquote class="text">
3497 <p>"OK" -
3498 </p>
3499 <blockquote class="text">
3500 <p>in case the engine was successfully deployed
3501 </p>
3502 </blockquote>
3503
3504
3505 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3506 </p>
3507 <blockquote class="text">
3508 <p>in case the engine was deployed successfully, but there
3509 are noteworthy issue(s) related, providing an appropriate
3510 warning code and warning message
3511 </p>
3512 </blockquote>
3513
3514
3515 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3516 </p>
3517 <blockquote class="text">
3518 <p>in case it failed, providing an appropriate error code and
3519 error message
3520 </p>
3521 </blockquote>
3522
3523
3524 </blockquote><p>
3525
3526 </p>
3527 <p>Example:
3528 </p>
3529 <p>
3530 </p>
3531 <blockquote class="text">
3532 <p>
3533 </p>
3534 </blockquote><p>
3535
3536 </p>
3537 <a name="GET CHANNELS"></a><br /><hr />
3538 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3539 <a name="rfc.section.6.4.3"></a><h3>6.4.3.&nbsp;
3540 Getting all created sampler channel count</h3>
3541
3542 <p>The number of sampler channels can change on runtime. To get the
3543 current amount of sampler channels, the front-end can send the
3544 following command:
3545 </p>
3546 <p>
3547 </p>
3548 <blockquote class="text">
3549 <p>GET CHANNELS
3550 </p>
3551 </blockquote><p>
3552
3553 </p>
3554 <p>Possible Answers:
3555 </p>
3556 <p>
3557 </p>
3558 <blockquote class="text">
3559 <p>LinuxSampler will answer by returning the current number of sampler channels.
3560 </p>
3561 </blockquote><p>
3562
3563 </p>
3564 <p>Example:
3565 </p>
3566 <p>
3567 </p>
3568 <blockquote class="text">
3569 <p>C: "GET CHANNELS"
3570 </p>
3571 <p>S: "12"
3572 </p>
3573 </blockquote><p>
3574
3575 </p>
3576 <a name="LIST CHANNELS"></a><br /><hr />
3577 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3578 <a name="rfc.section.6.4.4"></a><h3>6.4.4.&nbsp;
3579 Getting all created sampler channel list</h3>
3580
3581 <p>The number of sampler channels can change on runtime. To get the
3582 current list of sampler channels, the front-end can send the
3583 following command:
3584 </p>
3585 <p>
3586 </p>
3587 <blockquote class="text">
3588 <p>LIST CHANNELS
3589 </p>
3590 </blockquote><p>
3591
3592 </p>
3593 <p>Possible Answers:
3594 </p>
3595 <p>
3596 </p>
3597 <blockquote class="text">
3598 <p>LinuxSampler will answer by returning a comma separated list
3599 with all sampler channels numerical IDs.
3600 </p>
3601 </blockquote><p>
3602
3603 </p>
3604 <p>Example:
3605 </p>
3606 <p>
3607 </p>
3608 <blockquote class="text">
3609 <p>C: "LIST CHANNELS"
3610 </p>
3611 <p>S: "0,1,2,3,4,5,6,9,10,11,15,20"
3612 </p>
3613 </blockquote><p>
3614
3615 </p>
3616 <a name="ADD CHANNEL"></a><br /><hr />
3617 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3618 <a name="rfc.section.6.4.5"></a><h3>6.4.5.&nbsp;
3619 Adding a new sampler channel</h3>
3620
3621 <p>A new sampler channel can be added to the end of the sampler
3622 channel list by sending the following command:
3623 </p>
3624 <p>
3625 </p>
3626 <blockquote class="text">
3627 <p>ADD CHANNEL
3628 </p>
3629 </blockquote><p>
3630
3631 </p>
3632 <p>This will increment the sampler channel count by one and the new
3633 sampler channel will be appended to the end of the sampler channel
3634 list. The front-end should send the respective, related commands
3635 right after to e.g. load an engine, load an instrument and setting
3636 input, output method and eventually other commands to initialize
3637 the new channel. The front-end should use the sampler channel
3638 returned by the answer of this command to perform the previously
3639 recommended commands, to avoid race conditions e.g. with other
3640 front-ends that might also have sent an "ADD CHANNEL" command.
3641 </p>
3642 <p>Possible Answers:
3643 </p>
3644 <p>
3645 </p>
3646 <blockquote class="text">
3647 <p>"OK[&lt;sampler-channel&gt;]" -
3648 </p>
3649 <blockquote class="text">
3650 <p>in case a new sampler channel could be added, where
3651 &lt;sampler-channel&gt; reflects the channel number of the new
3652 created sampler channel which should be used to set up
3653 the sampler channel by sending subsequent initialization
3654 commands
3655 </p>
3656 </blockquote>
3657
3658
3659 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3660 </p>
3661 <blockquote class="text">
3662 <p>in case a new channel was added successfully, but there are
3663 noteworthy issue(s) related, providing an appropriate
3664 warning code and warning message
3665 </p>
3666 </blockquote>
3667
3668
3669 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3670 </p>
3671 <blockquote class="text">
3672 <p>in case it failed, providing an appropriate error code and
3673 error message
3674 </p>
3675 </blockquote>
3676
3677
3678 </blockquote><p>
3679
3680 </p>
3681 <p>Example:
3682 </p>
3683 <p>
3684 </p>
3685 <blockquote class="text">
3686 <p>
3687 </p>
3688 </blockquote><p>
3689
3690 </p>
3691 <a name="REMOVE CHANNEL"></a><br /><hr />
3692 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3693 <a name="rfc.section.6.4.6"></a><h3>6.4.6.&nbsp;
3694 Removing a sampler channel</h3>
3695
3696 <p>A sampler channel can be removed by sending the following command:
3697 </p>
3698 <p>
3699 </p>
3700 <blockquote class="text">
3701 <p>REMOVE CHANNEL &lt;sampler-channel&gt;
3702 </p>
3703 </blockquote><p>
3704
3705 </p>
3706 <p>Where &lt;sampler-channel&gt; should be replaced by the
3707 number of the sampler channel as given by the
3708 <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
3709 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a>
3710 command. The channel numbers of all subsequent sampler channels
3711 remain the same.
3712 </p>
3713 <p>Possible Answers:
3714 </p>
3715 <p>
3716 </p>
3717 <blockquote class="text">
3718 <p>"OK" -
3719 </p>
3720 <blockquote class="text">
3721 <p>in case the given sampler channel could be removed
3722 </p>
3723 </blockquote>
3724
3725
3726 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3727 </p>
3728 <blockquote class="text">
3729 <p>in case the given channel was removed, but there are
3730 noteworthy issue(s) related, providing an appropriate
3731 warning code and warning message
3732 </p>
3733 </blockquote>
3734
3735
3736 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3737 </p>
3738 <blockquote class="text">
3739 <p>in case it failed, providing an appropriate error code and
3740 error message
3741 </p>
3742 </blockquote>
3743
3744
3745 </blockquote><p>
3746
3747 </p>
3748 <p>Example:
3749 </p>
3750 <p>
3751 </p>
3752 <blockquote class="text">
3753 <p>
3754 </p>
3755 </blockquote><p>
3756
3757 </p>
3758 <a name="GET AVAILABLE_ENGINES"></a><br /><hr />
3759 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3760 <a name="rfc.section.6.4.7"></a><h3>6.4.7.&nbsp;
3761 Getting amount of available engines</h3>
3762
3763 <p>The front-end can ask for the number of available engines by sending the following command:
3764 </p>
3765 <p>
3766 </p>
3767 <blockquote class="text">
3768 <p>GET AVAILABLE_ENGINES
3769 </p>
3770 </blockquote><p>
3771
3772 </p>
3773 <p>Possible Answers:
3774 </p>
3775 <p>
3776 </p>
3777 <blockquote class="text">
3778 <p>LinuxSampler will answer by sending the number of available engines.
3779 </p>
3780 </blockquote><p>
3781
3782 </p>
3783 <p>Example:
3784 </p>
3785 <p>
3786 </p>
3787 <blockquote class="text">
3788 <p>C: "GET AVAILABLE_ENGINES"
3789 </p>
3790 <p>S: "4"
3791 </p>
3792 </blockquote><p>
3793
3794 </p>
3795 <a name="LIST AVAILABLE_ENGINES"></a><br /><hr />
3796 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3797 <a name="rfc.section.6.4.8"></a><h3>6.4.8.&nbsp;
3798 Getting all available engines</h3>
3799
3800 <p>The front-end can ask for a list of all available engines by sending the following command:
3801 </p>
3802 <p>
3803 </p>
3804 <blockquote class="text">
3805 <p>LIST AVAILABLE_ENGINES
3806 </p>
3807 </blockquote><p>
3808
3809 </p>
3810 <p>Possible Answers:
3811 </p>
3812 <p>
3813 </p>
3814 <blockquote class="text">
3815 <p>LinuxSampler will answer by sending a comma separated list
3816 of the engines' names encapsulated into apostrophes (').
3817 Engine names can consist of lower and upper cases,
3818 digits and underlines ("_" character).
3819 </p>
3820 </blockquote><p>
3821
3822 </p>
3823 <p>Example:
3824 </p>
3825 <p>
3826 </p>
3827 <blockquote class="text">
3828 <p>C: "LIST AVAILABLE_ENGINES"
3829 </p>
3830 <p>S: "'GigEngine','AkaiEngine','DLSEngine','JoesCustomEngine'"
3831 </p>
3832 </blockquote><p>
3833
3834 </p>
3835 <a name="GET ENGINE INFO"></a><br /><hr />
3836 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3837 <a name="rfc.section.6.4.9"></a><h3>6.4.9.&nbsp;
3838 Getting information about an engine</h3>
3839
3840 <p>The front-end can ask for information about a specific engine by
3841 sending the following command:
3842 </p>
3843 <p>
3844 </p>
3845 <blockquote class="text">
3846 <p>GET ENGINE INFO &lt;engine-name&gt;
3847 </p>
3848 </blockquote><p>
3849
3850 </p>
3851 <p>Where &lt;engine-name&gt; is an engine name as obtained by the
3852 <a class='info' href='#LIST AVAILABLE_ENGINES'>"LIST AVAILABLE_ENGINES"<span> (</span><span class='info'>Getting all available engines</span><span>)</span></a> command.
3853 </p>
3854 <p>Possible Answers:
3855 </p>
3856 <p>
3857 </p>
3858 <blockquote class="text">
3859 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3860 Each answer line begins with the information category name
3861 followed by a colon and then a space character &lt;SP&gt; and finally
3862 the info character string to that info category. At the moment
3863 the following categories are defined:
3864 </p>
3865 <p>
3866 </p>
3867 <blockquote class="text">
3868 <p>DESCRIPTION -
3869 </p>
3870 <blockquote class="text">
3871 <p>arbitrary description text about the engine
3872 (note that the character string may contain
3873 <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>)
3874 </p>
3875 </blockquote>
3876
3877
3878 <p>VERSION -
3879 </p>
3880 <blockquote class="text">
3881 <p>arbitrary character string regarding the engine's version
3882 </p>
3883 </blockquote>
3884
3885
3886 </blockquote>
3887
3888
3889 </blockquote><p>
3890
3891 </p>
3892 <p>The mentioned fields above don't have to be in particular order.
3893 </p>
3894 <p>Example:
3895 </p>
3896 <p>
3897 </p>
3898 <blockquote class="text">
3899 <p>C: "GET ENGINE INFO JoesCustomEngine"
3900 </p>
3901 <p>S: "DESCRIPTION: this is Joe's custom sampler engine"
3902 </p>
3903 <p>&nbsp;&nbsp;&nbsp;"VERSION: testing-1.0"
3904 </p>
3905 <p>&nbsp;&nbsp;&nbsp;"."
3906 </p>
3907 </blockquote><p>
3908
3909 </p>
3910 <a name="GET CHANNEL INFO"></a><br /><hr />
3911 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3912 <a name="rfc.section.6.4.10"></a><h3>6.4.10.&nbsp;
3913 Getting sampler channel information</h3>
3914
3915 <p>The front-end can ask for the current settings of a sampler channel
3916 by sending the following command:
3917 </p>
3918 <p>
3919 </p>
3920 <blockquote class="text">
3921 <p>GET CHANNEL INFO &lt;sampler-channel&gt;
3922 </p>
3923 </blockquote><p>
3924
3925 </p>
3926 <p>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
3927 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>
3928 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.
3929 </p>
3930 <p>Possible Answers:
3931 </p>
3932 <p>
3933 </p>
3934 <blockquote class="text">
3935 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3936 Each answer line begins with the settings category name
3937 followed by a colon and then a space character &lt;SP&gt; and finally
3938 the info character string to that setting category. At the
3939 moment the following categories are defined:
3940 </p>
3941 <p>
3942 </p>
3943 <blockquote class="text">
3944 <p>ENGINE_NAME -
3945 </p>
3946 <blockquote class="text">
3947 <p>name of the engine that is associated with the sampler
3948 channel, "NONE" if there's no engine associated yet for
3949 this sampler channel
3950 </p>
3951 </blockquote>
3952
3953
3954 <p>AUDIO_OUTPUT_DEVICE -
3955 </p>
3956 <blockquote class="text">
3957 <p>numerical ID of the audio output device which is
3958 currently connected to this sampler channel to output
3959 the audio signal, "NONE" if there's no device
3960 connected to this sampler channel
3961 </p>
3962 </blockquote>
3963
3964
3965 <p>AUDIO_OUTPUT_CHANNELS -
3966 </p>
3967 <blockquote class="text">
3968 <p>number of output channels the sampler channel offers
3969 (dependent to used sampler engine and loaded instrument)
3970 </p>
3971 </blockquote>
3972
3973
3974 <p>AUDIO_OUTPUT_ROUTING -
3975 </p>
3976 <blockquote class="text">
3977 <p>comma separated list which reflects to which audio
3978 channel of the selected audio output device each
3979 sampler output channel is routed to, e.g. "0,3" would
3980 mean the engine's output channel 0 is routed to channel
3981 0 of the audio output device and the engine's output
3982 channel 1 is routed to the channel 3 of the audio
3983 output device
3984 </p>
3985 </blockquote>
3986
3987
3988 <p>INSTRUMENT_FILE -
3989 </p>
3990 <blockquote class="text">
3991 <p>the file name of the loaded instrument, "NONE" if
3992 there's no instrument yet loaded for this sampler
3993 channel (note: since LSCP 1.2 this path may contain
3994 <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>)
3995 </p>
3996 </blockquote>
3997
3998
3999 <p>INSTRUMENT_NR -
4000 </p>
4001 <blockquote class="text">
4002 <p>the instrument index number of the loaded instrument
4003 </p>
4004 </blockquote>
4005
4006
4007 <p>INSTRUMENT_NAME -
4008 </p>
4009 <blockquote class="text">
4010 <p>the instrument name of the loaded instrument
4011 (note: since LSCP 1.2 this character string may contain
4012 <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>)
4013 </p>
4014 </blockquote>
4015
4016
4017 <p>INSTRUMENT_STATUS -
4018 </p>
4019 <blockquote class="text">
4020 <p>integer values 0 to 100 indicating loading progress percentage for the instrument. Negative
4021 value indicates a loading exception. Value of 100 indicates that the instrument is fully
4022 loaded.
4023 </p>
4024 </blockquote>
4025
4026
4027 <p>MIDI_INPUT_DEVICE -
4028 </p>
4029 <blockquote class="text">
4030 <p>numerical ID of the MIDI input device which is
4031 currently connected to this sampler channel to deliver
4032 MIDI input commands, "NONE" if there's no device
4033 connected to this sampler channel
4034 </p>
4035 </blockquote>
4036
4037
4038 <p>MIDI_INPUT_PORT -
4039 </p>
4040 <blockquote class="text">
4041 <p>port number of the MIDI input device
4042 </p>
4043 </blockquote>
4044
4045
4046 <p>MIDI_INPUT_CHANNEL -
4047 </p>
4048 <blockquote class="text">
4049 <p>the MIDI input channel number this sampler channel
4050 should listen to or "ALL" to listen on all MIDI channels
4051 </p>
4052 </blockquote>
4053
4054
4055 <p>VOLUME -
4056 </p>
4057 <blockquote class="text">
4058 <p>optionally dotted number for the channel volume factor
4059 (where a value &lt; 1.0 means attenuation and a value >
4060 1.0 means amplification)
4061 </p>
4062 </blockquote>
4063
4064
4065 <p>MUTE -
4066 </p>
4067 <blockquote class="text">
4068 <p>Determines whether the channel is muted, "true" if the
4069 channel is muted, "false" if the channel is not muted, and
4070 "MUTED_BY_SOLO" if the channel is muted because of the
4071 presence of a solo channel and will be unmuted when
4072 there are no solo channels left
4073 </p>
4074 </blockquote>
4075
4076
4077 <p>SOLO -
4078 </p>
4079 <blockquote class="text">
4080 <p>Determines whether this is a solo channel, "true" if
4081 the channel is a solo channel; "false" otherwise
4082 </p>
4083 </blockquote>
4084
4085
4086 <p>MIDI_INSTRUMENT_MAP -
4087 </p>
4088 <blockquote class="text">
4089 <p>Determines to which MIDI instrument map this sampler
4090 channel is assigned to. Read chapter
4091 <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>
4092 for a list of possible values.
4093 </p>
4094 </blockquote>
4095
4096
4097 </blockquote>
4098
4099
4100 </blockquote><p>
4101
4102 </p>
4103 <p>The mentioned fields above don't have to be in particular order.
4104 </p>
4105 <p>Example:
4106 </p>
4107 <p>
4108 </p>
4109 <blockquote class="text">
4110 <p>C: "GET CHANNEL INFO 34"
4111 </p>
4112 <p>S: "ENGINE_NAME: GigEngine"
4113 </p>
4114 <p>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"
4115 </p>
4116 <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_DEVICE: 0"
4117 </p>
4118 <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_CHANNELS: 2"
4119 </p>
4120 <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 0,1"
4121 </p>
4122 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"
4123 </p>
4124 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"
4125 </p>
4126 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NAME: Fazioli Piano"
4127 </p>
4128 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_STATUS: 100"
4129 </p>
4130 <p>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_DEVICE: 0"
4131 </p>
4132 <p>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_PORT: 0"
4133 </p>
4134 <p>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_CHANNEL: 5"
4135 </p>
4136 <p>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"
4137 </p>
4138 <p>&nbsp;&nbsp;&nbsp;"MUTE: false"
4139 </p>
4140 <p>&nbsp;&nbsp;&nbsp;"SOLO: false"
4141 </p>
4142 <p>&nbsp;&nbsp;&nbsp;"MIDI_INSTRUMENT_MAP: NONE"
4143 </p>
4144 <p>&nbsp;&nbsp;&nbsp;"."
4145 </p>
4146 </blockquote><p>
4147
4148 </p>
4149 <a name="GET CHANNEL VOICE_COUNT"></a><br /><hr />
4150 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4151 <a name="rfc.section.6.4.11"></a><h3>6.4.11.&nbsp;
4152 Current number of active voices</h3>
4153
4154 <p>The front-end can ask for the current number of active voices on a
4155 sampler channel by sending the following command:
4156 </p>
4157 <p>
4158 </p>
4159 <blockquote class="text">
4160 <p>GET CHANNEL VOICE_COUNT &lt;sampler-channel&gt;
4161 </p>
4162 </blockquote><p>
4163
4164 </p>
4165 <p>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
4166 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>
4167 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.
4168 </p>
4169 <p>Possible Answers:
4170 </p>
4171 <p>
4172 </p>
4173 <blockquote class="text">
4174 <p>LinuxSampler will answer by returning the number of active
4175 voices on that channel.
4176 </p>
4177 </blockquote><p>
4178
4179 </p>
4180 <p>Example:
4181 </p>
4182 <p>
4183 </p>
4184 <blockquote class="text">
4185 <p>
4186 </p>
4187 </blockquote><p>
4188
4189 </p>
4190 <a name="GET CHANNEL STREAM_COUNT"></a><br /><hr />
4191 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4192 <a name="rfc.section.6.4.12"></a><h3>6.4.12.&nbsp;
4193 Current number of active disk streams</h3>
4194
4195 <p>The front-end can ask for the current number of active disk streams
4196 on a sampler channel by sending the following command:
4197 </p>
4198 <p>
4199 </p>
4200 <blockquote class="text">
4201 <p>GET CHANNEL STREAM_COUNT &lt;sampler-channel&gt;
4202 </p>
4203 </blockquote><p>
4204
4205 </p>
4206 <p>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
4207 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>
4208 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.
4209 </p>
4210 <p>Possible Answers:
4211 </p>
4212 <p>
4213 </p>
4214 <blockquote class="text">
4215 <p>LinuxSampler will answer by returning the number of active
4216 disk streams on that channel in case the engine supports disk
4217 streaming, if the engine doesn't support disk streaming it will
4218 return "NA" for not available.
4219 </p>
4220 </blockquote><p>
4221
4222 </p>
4223 <p>Example:
4224 </p>
4225 <p>
4226 </p>
4227 <blockquote class="text">
4228 <p>
4229 </p>
4230 </blockquote><p>
4231
4232 </p>
4233 <a name="GET CHANNEL BUFFER_FILL"></a><br /><hr />
4234 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4235 <a name="rfc.section.6.4.13"></a><h3>6.4.13.&nbsp;
4236 Current fill state of disk stream buffers</h3>
4237
4238 <p>The front-end can ask for the current fill state of all disk streams
4239 on a sampler channel by sending the following command:
4240 </p>
4241 <p>
4242 </p>
4243 <blockquote class="text">
4244 <p>GET CHANNEL BUFFER_FILL BYTES &lt;sampler-channel&gt;
4245 </p>
4246 </blockquote><p>
4247
4248 </p>
4249 <p>to get the fill state in bytes or
4250 </p>
4251 <p>
4252 </p>
4253 <blockquote class="text">
4254 <p>GET CHANNEL BUFFER_FILL PERCENTAGE &lt;sampler-channel&gt;
4255 </p>
4256 </blockquote><p>
4257
4258 </p>
4259 <p>to get the fill state in percent, where &lt;sampler-channel&gt; is the
4260 sampler channel number the front-end is interested in
4261 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>
4262 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.
4263 </p>
4264 <p>Possible Answers:
4265 </p>
4266 <p>
4267 </p>
4268 <blockquote class="text">
4269 <p>LinuxSampler will either answer by returning a comma separated
4270 string with the fill state of all disk stream buffers on that
4271 channel or an empty line if there are no active disk streams or
4272 "NA" for *not available* in case the engine which is deployed
4273 doesn't support disk streaming. Each entry in the answer list
4274 will begin with the stream's ID in brackets followed by the
4275 numerical representation of the fill size (either in bytes or
4276 percentage). Note: due to efficiency reasons the fill states in
4277 the response are not in particular order, thus the front-end has
4278 to sort them by itself if necessary.
4279 </p>
4280 </blockquote><p>
4281
4282 </p>
4283 <p>Examples:
4284 </p>
4285 <p>
4286 </p>
4287 <blockquote class="text">
4288 <p>C: "GET CHANNEL BUFFER_FILL BYTES 4"
4289 </p>
4290 <p>S: "[115]420500,[116]510300,[75]110000,[120]230700"
4291 </p>
4292 </blockquote><p>
4293
4294 </p>
4295 <blockquote class="text">
4296 <p>C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
4297 </p>
4298 <p>S: "[115]90%,[116]98%,[75]40%,[120]62%"
4299 </p>
4300 </blockquote><p>
4301
4302 </p>
4303 <blockquote class="text">
4304 <p>C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
4305 </p>
4306 <p>S: ""
4307 </p>
4308 </blockquote><p>
4309
4310 </p>
4311 <a name="SET CHANNEL AUDIO_OUTPUT_DEVICE"></a><br /><hr />
4312 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4313 <a name="rfc.section.6.4.14"></a><h3>6.4.14.&nbsp;
4314 Setting audio output device</h3>
4315
4316 <p>The front-end can set the audio output device on a specific sampler
4317 channel by sending the following command:
4318 </p>
4319 <p>
4320 </p>
4321 <blockquote class="text">
4322 <p>SET CHANNEL AUDIO_OUTPUT_DEVICE &lt;sampler-channel&gt; &lt;audio-device-id&gt;
4323 </p>
4324 </blockquote><p>
4325
4326 </p>
4327 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4328 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>
4329 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
4330 &lt;audio-device-id&gt; is the numerical ID of the audio output device as given by the
4331 <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>
4332 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>
4333 command.
4334 </p>
4335 <p>Possible Answers:
4336 </p>
4337 <p>
4338 </p>
4339 <blockquote class="text">
4340 <p>"OK" -
4341 </p>
4342 <blockquote class="text">
4343 <p>on success
4344 </p>
4345 </blockquote>
4346
4347
4348 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4349 </p>
4350 <blockquote class="text">
4351 <p>if audio output device was set, but there are noteworthy
4352 issue(s) related, providing an appropriate warning code and
4353 warning message
4354 </p>
4355 </blockquote>
4356
4357
4358 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4359 </p>
4360 <blockquote class="text">
4361 <p>in case it failed, providing an appropriate error code and error message
4362 </p>
4363 </blockquote>
4364
4365
4366 </blockquote><p>
4367
4368 </p>
4369 <p>Examples:
4370 </p>
4371 <p>
4372 </p>
4373 <blockquote class="text">
4374 <p>
4375 </p>
4376 </blockquote><p>
4377
4378 </p>
4379 <a name="SET CHANNEL AUDIO_OUTPUT_TYPE"></a><br /><hr />
4380 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4381 <a name="rfc.section.6.4.15"></a><h3>6.4.15.&nbsp;
4382 Setting audio output type</h3>
4383
4384 <p>DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
4385 </p>
4386 <p>The front-end can alter the audio output type on a specific sampler
4387 channel by sending the following command:
4388 </p>
4389 <p>
4390 </p>
4391 <blockquote class="text">
4392 <p>SET CHANNEL AUDIO_OUTPUT_TYPE &lt;sampler-channel&gt; &lt;audio-output-type&gt;
4393 </p>
4394 </blockquote><p>
4395
4396 </p>
4397 <p>Where &lt;audio-output-type&gt; is currently either "ALSA" or "JACK" and
4398 &lt;sampler-channel&gt; is the respective sampler channel number.
4399 </p>
4400 <p>Possible Answers:
4401 </p>
4402 <p>
4403 </p>
4404 <blockquote class="text">
4405 <p>"OK" -
4406 </p>
4407 <blockquote class="text">
4408 <p>on success
4409 </p>
4410 </blockquote>
4411
4412
4413 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4414 </p>
4415 <blockquote class="text">
4416 <p>if audio output type was set, but there are noteworthy
4417 issue(s) related, providing an appropriate warning code and
4418 warning message
4419 </p>
4420 </blockquote>
4421
4422
4423 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4424 </p>
4425 <blockquote class="text">
4426 <p>in case it failed, providing an appropriate error code and error message
4427 </p>
4428 </blockquote>
4429
4430
4431 </blockquote><p>
4432
4433 </p>
4434 <p>Examples:
4435 </p>
4436 <p>
4437 </p>
4438 <blockquote class="text">
4439 <p>
4440 </p>
4441 </blockquote><p>
4442
4443 </p>
4444 <a name="SET CHANNEL AUDIO_OUTPUT_CHANNEL"></a><br /><hr />
4445 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4446 <a name="rfc.section.6.4.16"></a><h3>6.4.16.&nbsp;
4447 Setting audio output channel</h3>
4448
4449 <p>The front-end can alter the audio output channel on a specific
4450 sampler channel by sending the following command:
4451 </p>
4452 <p>
4453 </p>
4454 <blockquote class="text">
4455 <p>SET CHANNEL AUDIO_OUTPUT_CHANNEL &lt;sampler-chan&gt; &lt;audio-out&gt; &lt;audio-in&gt;
4456 </p>
4457 </blockquote><p>
4458
4459 </p>
4460 <p>Where &lt;sampler-chan&gt; is the sampler channel number
4461 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>
4462 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
4463 numerical ID of the sampler channel's audio output channel which should be
4464 rerouted and &lt;audio-in&gt; is the numerical ID of the audio channel of the selected audio
4465 output device where &lt;audio-out&gt; should be routed to.
4466 </p>
4467 <p>Possible Answers:
4468 </p>
4469 <p>
4470 </p>
4471 <blockquote class="text">
4472 <p>"OK" -
4473 </p>
4474 <blockquote class="text">
4475 <p>on success
4476 </p>
4477 </blockquote>
4478
4479
4480 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4481 </p>
4482 <blockquote class="text">
4483 <p>if audio output channel was set, but there are noteworthy
4484 issue(s) related, providing an appropriate warning code and
4485 warning message
4486 </p>
4487 </blockquote>
4488
4489
4490 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4491 </p>
4492 <blockquote class="text">
4493 <p>in case it failed, providing an appropriate error code and error message
4494 </p>
4495 </blockquote>
4496
4497
4498 </blockquote><p>
4499
4500 </p>
4501 <p>Examples:
4502 </p>
4503 <p>
4504 </p>
4505 <blockquote class="text">
4506 <p>
4507 </p>
4508 </blockquote><p>
4509
4510 </p>
4511 <a name="SET CHANNEL MIDI_INPUT_DEVICE"></a><br /><hr />
4512 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4513 <a name="rfc.section.6.4.17"></a><h3>6.4.17.&nbsp;
4514 Setting MIDI input device</h3>
4515
4516 <p>The front-end can set the MIDI input device on a specific sampler
4517 channel by sending the following command:
4518 </p>
4519 <p>
4520 </p>
4521 <blockquote class="text">
4522 <p>SET CHANNEL MIDI_INPUT_DEVICE &lt;sampler-channel&gt; &lt;midi-device-id&gt;
4523 </p>
4524 </blockquote><p>
4525
4526 </p>
4527 <p>Where &lt;sampler-channel&gt; is the sampler channel number
4528 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>
4529 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
4530 and &lt;midi-device-id&gt; is the numerical ID of the MIDI input device as returned by the
4531 <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>
4532 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.
4533 </p>
4534 <p>Possible Answers:
4535 </p>
4536 <p>
4537 </p>
4538 <blockquote class="text">
4539 <p>"OK" -
4540 </p>
4541 <blockquote class="text">
4542 <p>on success
4543 </p>
4544 </blockquote>
4545
4546
4547 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4548 </p>
4549 <blockquote class="text">
4550 <p>if MIDI input device was set, but there are noteworthy
4551 issue(s) related, providing an appropriate warning code and
4552 warning message
4553 </p>
4554 </blockquote>
4555
4556
4557 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4558 </p>
4559 <blockquote class="text">
4560 <p>in case it failed, providing an appropriate error code and error message
4561 </p>
4562 </blockquote>
4563
4564
4565 </blockquote><p>
4566
4567 </p>
4568 <p>Examples:
4569 </p>
4570 <p>
4571 </p>
4572 <blockquote class="text">
4573 <p>
4574 </p>
4575 </blockquote><p>
4576
4577 </p>
4578 <a name="SET CHANNEL MIDI_INPUT_TYPE"></a><br /><hr />
4579 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4580 <a name="rfc.section.6.4.18"></a><h3>6.4.18.&nbsp;
4581 Setting MIDI input type</h3>
4582
4583 <p>DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
4584 </p>
4585 <p>The front-end can alter the MIDI input type on a specific sampler
4586 channel by sending the following command:
4587 </p>
4588 <p>
4589 </p>
4590 <blockquote class="text">
4591 <p>SET CHANNEL MIDI_INPUT_TYPE &lt;sampler-channel&gt; &lt;midi-input-type&gt;
4592 </p>
4593 </blockquote><p>
4594
4595 </p>
4596 <p>Where &lt;midi-input-type&gt; is currently only "ALSA" and
4597 &lt;sampler-channel&gt; is the respective sampler channel number.
4598 </p>
4599 <p>Possible Answers:
4600 </p>
4601 <p>
4602 </p>
4603 <blockquote class="text">
4604 <p>"OK" -
4605 </p>
4606 <blockquote class="text">
4607 <p>on success
4608 </p>
4609 </blockquote>
4610
4611
4612 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4613 </p>
4614 <blockquote class="text">
4615 <p>if MIDI input type was set, but there are noteworthy
4616 issue(s) related, providing an appropriate warning code and
4617 warning message
4618 </p>
4619 </blockquote>
4620
4621
4622 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4623 </p>
4624 <blockquote class="text">
4625 <p>in case it failed, providing an appropriate error code and error message
4626 </p>
4627 </blockquote>
4628
4629
4630 </blockquote><p>
4631
4632 </p>
4633 <p>Examples:
4634 </p>
4635 <p>
4636 </p>
4637 <blockquote class="text">
4638 <p>
4639 </p>
4640 </blockquote><p>
4641
4642 </p>
4643 <a name="SET CHANNEL MIDI_INPUT_PORT"></a><br /><hr />
4644 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4645 <a name="rfc.section.6.4.19"></a><h3>6.4.19.&nbsp;
4646 Setting MIDI input port</h3>
4647
4648 <p>The front-end can alter the MIDI input port on a specific sampler
4649 channel by sending the following command:
4650 </p>
4651 <p>
4652 </p>
4653 <blockquote class="text">
4654 <p>SET CHANNEL MIDI_INPUT_PORT &lt;sampler-channel&gt; &lt;midi-input-port&gt;
4655 </p>
4656 </blockquote><p>
4657
4658 </p>
4659 <p>Where &lt;midi-input-port&gt; is a MIDI input port number of the
4660 MIDI input device connected to the sampler channel given by
4661 &lt;sampler-channel&gt;.
4662 </p>
4663 <p>Possible Answers:
4664 </p>
4665 <p>
4666 </p>
4667 <blockquote class="text">
4668 <p>"OK" -
4669 </p>
4670 <blockquote class="text">
4671 <p>on success
4672 </p>
4673 </blockquote>
4674
4675
4676 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4677 </p>
4678 <blockquote class="text">
4679 <p>if MIDI input port was set, but there are noteworthy
4680 issue(s) related, providing an appropriate warning code and
4681 warning message
4682 </p>
4683 </blockquote>
4684
4685
4686 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4687 </p>
4688 <blockquote class="text">
4689 <p>in case it failed, providing an appropriate error code and error message
4690 </p>
4691 </blockquote>
4692
4693
4694 </blockquote><p>
4695
4696 </p>
4697 <p>Examples:
4698 </p>
4699 <p>
4700 </p>
4701 <blockquote class="text">
4702 <p>
4703 </p>
4704 </blockquote><p>
4705
4706 </p>
4707 <a name="SET CHANNEL MIDI_INPUT_CHANNEL"></a><br /><hr />
4708 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4709 <a name="rfc.section.6.4.20"></a><h3>6.4.20.&nbsp;
4710 Setting MIDI input channel</h3>
4711
4712 <p>The front-end can alter the MIDI channel a sampler channel should
4713 listen to by sending the following command:
4714 </p>
4715 <p>
4716 </p>
4717 <blockquote class="text">
4718 <p>SET CHANNEL MIDI_INPUT_CHANNEL &lt;sampler-channel&gt; &lt;midi-input-chan&gt;
4719 </p>
4720 </blockquote><p>
4721
4722 </p>
4723 <p>Where &lt;midi-input-chan&gt; is the number of the new MIDI input channel where
4724 &lt;sampler-channel&gt; should listen to or "ALL" to listen on all 16 MIDI
4725 channels.
4726 </p>
4727 <p>Possible Answers:
4728 </p>
4729 <p>
4730 </p>
4731 <blockquote class="text">
4732 <p>"OK" -
4733 </p>
4734 <blockquote class="text">
4735 <p>on success
4736 </p>
4737 </blockquote>
4738
4739
4740 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4741 </p>
4742 <blockquote class="text">
4743 <p>if MIDI input channel was set, but there are noteworthy
4744 issue(s) related, providing an appropriate warning code and
4745 warning message
4746 </p>
4747 </blockquote>
4748
4749
4750 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4751 </p>
4752 <blockquote class="text">
4753 <p>in case it failed, providing an appropriate error code and error message
4754 </p>
4755 </blockquote>
4756
4757
4758 </blockquote><p>
4759
4760 </p>
4761 <p>Examples:
4762 </p>
4763 <p>
4764 </p>
4765 <blockquote class="text">
4766 <p>
4767 </p>
4768 </blockquote><p>
4769
4770 </p>
4771 <a name="SET CHANNEL VOLUME"></a><br /><hr />
4772 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4773 <a name="rfc.section.6.4.21"></a><h3>6.4.21.&nbsp;
4774 Setting channel volume</h3>
4775
4776 <p>The front-end can alter the volume of a sampler channel by sending
4777 the following command:
4778 </p>
4779 <p>
4780 </p>
4781 <blockquote class="text">
4782 <p>SET CHANNEL VOLUME &lt;sampler-channel&gt; &lt;volume&gt;
4783 </p>
4784 </blockquote><p>
4785
4786 </p>
4787 <p>Where &lt;volume&gt; is an optionally dotted positive number (a value
4788 smaller than 1.0 means attenuation, whereas a value greater than
4789 1.0 means amplification) and &lt;sampler-channel&gt; defines the sampler
4790 channel where this volume factor should be set.
4791 </p>
4792 <p>Possible Answers:
4793 </p>
4794 <p>
4795 </p>
4796 <blockquote class="text">
4797 <p>"OK" -
4798 </p>
4799 <blockquote class="text">
4800 <p>on success
4801 </p>
4802 </blockquote>
4803
4804
4805 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4806 </p>
4807 <blockquote class="text">
4808 <p>if channel volume was set, but there are noteworthy
4809 issue(s) related, providing an appropriate warning code and
4810 warning message
4811 </p>
4812 </blockquote>
4813
4814
4815 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4816 </p>
4817 <blockquote class="text">
4818 <p>in case it failed, providing an appropriate error code and error message
4819 </p>
4820 </blockquote>
4821
4822
4823 </blockquote><p>
4824
4825 </p>
4826 <p>Examples:
4827 </p>
4828 <p>
4829 </p>
4830 <blockquote class="text">
4831 <p>
4832 </p>
4833 </blockquote><p>
4834
4835 </p>
4836 <a name="SET CHANNEL MUTE"></a><br /><hr />
4837 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4838 <a name="rfc.section.6.4.22"></a><h3>6.4.22.&nbsp;
4839 Muting a sampler channel</h3>
4840
4841 <p>The front-end can mute/unmute a specific sampler
4842 channel by sending the following command:
4843 </p>
4844 <p>
4845 </p>
4846 <blockquote class="text">
4847 <p>SET CHANNEL MUTE &lt;sampler-channel&gt; &lt;mute&gt;
4848 </p>
4849 </blockquote><p>
4850
4851 </p>
4852 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4853 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>
4854 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
4855 &lt;mute&gt; should be replaced either by "1" to mute the channel or "0"
4856 to unmute the channel.
4857 </p>
4858 <p>Possible Answers:
4859 </p>
4860 <p>
4861 </p>
4862 <blockquote class="text">
4863 <p>"OK" -
4864 </p>
4865 <blockquote class="text">
4866 <p>on success
4867 </p>
4868 </blockquote>
4869
4870
4871 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4872 </p>
4873 <blockquote class="text">
4874 <p>if the channel was muted/unmuted, but there are noteworthy
4875 issue(s) related, providing an appropriate warning code and
4876 warning message
4877 </p>
4878 </blockquote>
4879
4880
4881 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4882 </p>
4883 <blockquote class="text">
4884 <p>in case it failed, providing an appropriate error code and error message
4885 </p>
4886 </blockquote>
4887
4888
4889 </blockquote><p>
4890
4891 </p>
4892 <p>Examples:
4893 </p>
4894 <p>
4895 </p>
4896 <blockquote class="text">
4897 <p>
4898 </p>
4899 </blockquote><p>
4900
4901 </p>
4902 <a name="SET CHANNEL SOLO"></a><br /><hr />
4903 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4904 <a name="rfc.section.6.4.23"></a><h3>6.4.23.&nbsp;
4905 Soloing a sampler channel</h3>
4906
4907 <p>The front-end can solo/unsolo a specific sampler channel
4908 by sending the following command:
4909 </p>
4910 <p>
4911 </p>
4912 <blockquote class="text">
4913 <p>SET CHANNEL SOLO &lt;sampler-channel&gt; &lt;solo&gt;
4914 </p>
4915 </blockquote><p>
4916
4917 </p>
4918 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4919 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>
4920 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
4921 &lt;solo&gt; should be replaced either by "1" to solo the channel or "0"
4922 to unsolo the channel.
4923 </p>
4924 <p>Possible Answers:
4925 </p>
4926 <p>
4927 </p>
4928 <blockquote class="text">
4929 <p>"OK" -
4930 </p>
4931 <blockquote class="text">
4932 <p>on success
4933 </p>
4934 </blockquote>
4935
4936
4937 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4938 </p>
4939 <blockquote class="text">
4940 <p>if the channel was soloed/unsoloed, but there are noteworthy
4941 issue(s) related, providing an appropriate warning code and
4942 warning message
4943 </p>
4944 </blockquote>
4945
4946
4947 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4948 </p>
4949 <blockquote class="text">
4950 <p>in case it failed, providing an appropriate error code and error message
4951 </p>
4952 </blockquote>
4953
4954
4955 </blockquote><p>
4956
4957 </p>
4958 <p>Examples:
4959 </p>
4960 <p>
4961 </p>
4962 <blockquote class="text">
4963 <p>
4964 </p>
4965 </blockquote><p>
4966
4967 </p>
4968 <a name="SET CHANNEL MIDI_INSTRUMENT_MAP"></a><br /><hr />
4969 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4970 <a name="rfc.section.6.4.24"></a><h3>6.4.24.&nbsp;
4971 Assigning a MIDI instrument map to a sampler channel</h3>
4972
4973 <p>The front-end can assign a MIDI instrument map to a specific sampler channel
4974 by sending the following command:
4975 </p>
4976 <p>
4977 </p>
4978 <blockquote class="text">
4979 <p>SET CHANNEL MIDI_INSTRUMENT_MAP &lt;sampler-channel&gt; &lt;map&gt;
4980 </p>
4981 </blockquote><p>
4982
4983 </p>
4984 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4985 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>
4986 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
4987 &lt;map&gt; can have the following possibilites:
4988 </p>
4989 <p>
4990 </p>
4991 <blockquote class="text">
4992 <p>"NONE" -
4993 </p>
4994 <blockquote class="text">
4995 <p>This is the default setting. In this case
4996 the sampler channel is not assigned any MIDI
4997 instrument map and thus will ignore all MIDI
4998 program change messages.
4999 </p>
5000 </blockquote>
5001
5002
5003 <p>"DEFAULT" -
5004 </p>
5005 <blockquote class="text">
5006 <p>The sampler channel will always use the
5007 default MIDI instrument map to handle MIDI
5008 program change messages.
5009 </p>
5010 </blockquote>
5011
5012
5013 <p>numeric ID -
5014 </p>
5015 <blockquote class="text">
5016 <p>You can assign a specific MIDI instrument map
5017 by replacing &lt;map&gt; with the respective numeric
5018 ID of the MIDI instrument map as returned by the
5019 <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>
5020 command. Once that map will be deleted, the sampler
5021 channel would fall back to "NONE".
5022 </p>
5023 </blockquote>
5024
5025
5026 </blockquote><p>
5027
5028 </p>
5029 <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>
5030 for details regarding MIDI instrument mapping.
5031 </p>
5032 <p>Possible Answers:
5033 </p>
5034 <p>
5035 </p>
5036 <blockquote class="text">
5037 <p>"OK" -
5038 </p>
5039 <blockquote class="text">
5040 <p>on success
5041 </p>
5042 </blockquote>
5043
5044
5045 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5046 </p>
5047 <blockquote class="text">
5048 <p>in case it failed, providing an appropriate error code and error message
5049 </p>
5050 </blockquote>
5051
5052
5053 </blockquote><p>
5054
5055 </p>
5056 <p>Examples:
5057 </p>
5058 <p>
5059 </p>
5060 <blockquote class="text">
5061 <p>
5062 </p>
5063 </blockquote><p>
5064
5065 </p>
5066 <a name="CREATE FX_SEND"></a><br /><hr />
5067 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5068 <a name="rfc.section.6.4.25"></a><h3>6.4.25.&nbsp;
5069 Adding an effect send to a sampler channel</h3>
5070
5071 <p>The front-end can create an additional effect send on a specific sampler channel
5072 by sending the following command:
5073 </p>
5074 <p>
5075 </p>
5076 <blockquote class="text">
5077 <p>CREATE FX_SEND &lt;sampler-channel&gt; &lt;midi-ctrl&gt; [&lt;name&gt;]
5078 </p>
5079 </blockquote><p>
5080
5081 </p>
5082 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5083 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>
5084 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
5085 sampler channel on which the effect send should be created on, &lt;midi-ctrl&gt;
5086 is a number between 0..127 defining the MIDI controller which can alter the
5087 effect send level and &lt;name&gt; is an optional argument defining a name
5088 for the effect send entity. The name does not have to be unique, but MUST be
5089 encapsulated into apostrophes and supports escape sequences as described in chapter
5090 "<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>".
5091 </p>
5092 <p>By default, that is as initial routing, the effect send's audio channels
5093 are automatically routed to the last audio channels of the sampler channel's
5094 audio output device, that way you can i.e. first increase the amount of audio
5095 channels on the audio output device for having dedicated effect send output
5096 channels and when "CREATE FX_SEND" is called, those channels will automatically
5097 be picked. You can alter the destination channels however with
5098 <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>.
5099
5100 </p>
5101 <p>Note: Create effect sends on a sampler channel only when needed, because having effect
5102 sends on a sampler channel will decrease runtime performance, because for implementing channel
5103 effect sends, separate (sampler channel local) audio buffers are needed to render and mix
5104 the voices and route the audio signal afterwards to the master outputs and effect send
5105 outputs (along with their respective effect send levels). A sampler channel without effect
5106 sends however can mix its voices directly into the audio output devices's audio buffers
5107 and is thus faster.
5108
5109 </p>
5110 <p>Possible Answers:
5111 </p>
5112 <p>
5113 </p>
5114 <blockquote class="text">
5115 <p>"OK[&lt;fx-send-id&gt;]" -
5116 </p>
5117 <blockquote class="text">
5118 <p>in case a new effect send could be added to the
5119 sampler channel, where &lt;fx-send-id&gt; reflects the
5120 unique ID of the newly created effect send entity
5121 </p>
5122 </blockquote>
5123
5124
5125 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5126 </p>
5127 <blockquote class="text">
5128 <p>when a new effect send could not be added, i.e.
5129 due to invalid parameters
5130 </p>
5131 </blockquote>
5132
5133
5134 </blockquote><p>
5135
5136 </p>
5137 <p>Examples:
5138 </p>
5139 <p>
5140 </p>
5141 <blockquote class="text">
5142 <p>C: "CREATE FX_SEND 0 91 'Reverb Send'"
5143 </p>
5144 <p>S: "OK[0]"
5145 </p>
5146 </blockquote><p>
5147
5148 </p>
5149 <p>
5150 </p>
5151 <blockquote class="text">
5152 <p>C: "CREATE FX_SEND 0 93"
5153 </p>
5154 <p>S: "OK[1]"
5155 </p>
5156 </blockquote><p>
5157
5158 </p>
5159 <a name="DESTROY FX_SEND"></a><br /><hr />
5160 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5161 <a name="rfc.section.6.4.26"></a><h3>6.4.26.&nbsp;
5162 Removing an effect send from a sampler channel</h3>
5163
5164 <p>The front-end can remove an existing effect send on a specific sampler channel
5165 by sending the following command:
5166 </p>
5167 <p>
5168 </p>
5169 <blockquote class="text">
5170 <p>DESTROY FX_SEND &lt;sampler-channel&gt; &lt;fx-send-id&gt;
5171 </p>
5172 </blockquote><p>
5173
5174 </p>
5175 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5176 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>
5177 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
5178 sampler channel from which the effect send should be removed from and
5179 &lt;fx-send-id&gt; is the respective effect send number as returned by the
5180 <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>
5181 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.
5182 </p>
5183 <p>Possible Answers:
5184 </p>
5185 <p>
5186 </p>
5187 <blockquote class="text">
5188 <p>"OK" -
5189 </p>
5190 <blockquote class="text">
5191 <p>on success
5192 </p>
5193 </blockquote>
5194
5195
5196 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5197 </p>
5198 <blockquote class="text">
5199 <p>in case it failed, providing an appropriate error code and
5200 error message
5201 </p>
5202 </blockquote>
5203
5204
5205 </blockquote><p>
5206
5207 </p>
5208 <p>Example:
5209 </p>
5210 <p>
5211 </p>
5212 <blockquote class="text">
5213 <p>C: "DESTROY FX_SEND 0 0"
5214 </p>
5215 <p>S: "OK"
5216 </p>
5217 </blockquote><p>
5218
5219 </p>
5220 <a name="GET FX_SENDS"></a><br /><hr />
5221 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5222 <a name="rfc.section.6.4.27"></a><h3>6.4.27.&nbsp;
5223 Getting amount of effect sends on a sampler channel</h3>
5224
5225 <p>The front-end can ask for the amount of effect sends on a specific sampler channel
5226 by sending the following command:
5227 </p>
5228 <p>
5229 </p>
5230 <blockquote class="text">
5231 <p>GET FX_SENDS &lt;sampler-channel&gt;
5232 </p>
5233 </blockquote><p>
5234
5235 </p>
5236 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5237 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>
5238 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.
5239 </p>
5240 <p>Possible Answers:
5241 </p>
5242 <p>
5243 </p>
5244 <blockquote class="text">
5245 <p>The sampler will answer by returning the number of effect
5246 sends on the given sampler channel.
5247 </p>
5248 </blockquote><p>
5249
5250 </p>
5251 <p>Example:
5252 </p>
5253 <p>
5254 </p>
5255 <blockquote class="text">
5256 <p>C: "GET FX_SENDS 0"
5257 </p>
5258 <p>S: "2"
5259 </p>
5260 </blockquote><p>
5261
5262 </p>
5263 <a name="LIST FX_SENDS"></a><br /><hr />
5264 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5265 <a name="rfc.section.6.4.28"></a><h3>6.4.28.&nbsp;
5266 Listing all effect sends on a sampler channel</h3>
5267
5268 <p>The front-end can ask for a list of effect sends on a specific sampler channel
5269 by sending the following command:
5270 </p>
5271 <p>
5272 </p>
5273 <blockquote class="text">
5274 <p>LIST FX_SENDS &lt;sampler-channel&gt;
5275 </p>
5276 </blockquote><p>
5277
5278 </p>
5279 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5280 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>
5281 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.
5282 </p>
5283 <p>Possible Answers:
5284 </p>
5285 <p>
5286 </p>
5287 <blockquote class="text">
5288 <p>The sampler will answer by returning a comma separated list
5289 with all effect sends' numerical IDs on the given sampler
5290 channel.
5291 </p>
5292 </blockquote><p>
5293
5294 </p>
5295 <p>Examples:
5296 </p>
5297 <p>
5298 </p>
5299 <blockquote class="text">
5300 <p>C: "LIST FX_SENDS 0"
5301 </p>
5302 <p>S: "0,1"
5303 </p>
5304 </blockquote><p>
5305
5306 </p>
5307 <p>
5308 </p>
5309 <blockquote class="text">
5310 <p>C: "LIST FX_SENDS 1"
5311 </p>
5312 <p>S: ""
5313 </p>
5314 </blockquote><p>
5315
5316 </p>
5317 <a name="GET FX_SEND INFO"></a><br /><hr />
5318 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5319 <a name="rfc.section.6.4.29"></a><h3>6.4.29.&nbsp;
5320 Getting effect send information</h3>
5321
5322 <p>The front-end can ask for the current settings of an effect send entity
5323 by sending the following command:
5324 </p>
5325 <p>
5326 </p>
5327 <blockquote class="text">
5328 <p>GET FX_SEND INFO &lt;sampler-channel&gt; &lt;fx-send-id&gt;
5329 </p>
5330 </blockquote><p>
5331
5332 </p>
5333 <p>Where &lt;sampler-channel&gt; is the sampler channel number
5334 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>
5335 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
5336 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5337 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>
5338 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.
5339
5340 </p>
5341 <p>Possible Answers:
5342 </p>
5343 <p>
5344 </p>
5345 <blockquote class="text">
5346 <p>The sampler will answer by sending a &lt;CRLF&gt; separated list.
5347 Each answer line begins with the settings category name
5348 followed by a colon and then a space character &lt;SP&gt; and finally
5349 the info character string to that setting category. At the
5350 moment the following categories are defined:
5351 </p>
5352 <p>
5353 </p>
5354 <blockquote class="text">
5355 <p>NAME -
5356 </p>
5357 <blockquote class="text">
5358 <p>name of the effect send entity
5359 (note that this character string may contain
5360 <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>)
5361 </p>
5362 </blockquote>
5363
5364
5365 <p>MIDI_CONTROLLER -
5366 </p>
5367 <blockquote class="text">
5368 <p>a value between 0 and 127 reflecting the MIDI controller
5369 which is able to modify the effect send's send level
5370 </p>
5371 </blockquote>
5372
5373
5374 <p>LEVEL -
5375 </p>
5376 <blockquote class="text">
5377 <p>optionally dotted number reflecting the effect send's
5378 current send level (where a value &lt; 1.0 means attenuation
5379 and a value > 1.0 means amplification)
5380 </p>
5381 </blockquote>
5382
5383
5384 <p>AUDIO_OUTPUT_ROUTING -
5385 </p>
5386 <blockquote class="text">
5387 <p>comma separated list which reflects to which audio
5388 channel of the selected audio output device each
5389 effect send output channel is routed to, e.g. "0,3" would
5390 mean the effect send's output channel 0 is routed to channel
5391 0 of the audio output device and the effect send's output
5392 channel 1 is routed to the channel 3 of the audio
5393 output device (see
5394 <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>
5395 for details)
5396 </p>
5397 </blockquote>
5398
5399
5400 </blockquote>
5401
5402
5403 </blockquote><p>
5404
5405 </p>
5406 <p>The mentioned fields above don't have to be in particular order.
5407 </p>
5408 <p>Example:
5409 </p>
5410 <p>
5411 </p>
5412 <blockquote class="text">
5413 <p>C: "GET FX_SEND INFO 0 0"
5414 </p>
5415 <p>S: "NAME: Reverb Send"
5416 </p>
5417 <p>&nbsp;&nbsp;&nbsp;"MIDI_CONTROLLER: 91"
5418 </p>
5419 <p>&nbsp;&nbsp;&nbsp;"LEVEL: 0.3"
5420 </p>
5421 <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 2,3"
5422 </p>
5423 <p>&nbsp;&nbsp;&nbsp;"."
5424 </p>
5425 </blockquote><p>
5426
5427 </p>
5428 <a name="SET FX_SEND NAME"></a><br /><hr />
5429 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5430 <a name="rfc.section.6.4.30"></a><h3>6.4.30.&nbsp;
5431 Changing effect send's name</h3>
5432
5433 <p>The front-end can alter the current name of an effect
5434 send entity by sending the following command:
5435 </p>
5436 <p>
5437 </p>
5438 <blockquote class="text">
5439 <p>SET FX_SEND NAME &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;name&gt;
5440 </p>
5441 </blockquote><p>
5442
5443 </p>
5444 <p>Where &lt;sampler-chan&gt; is the sampler channel number
5445 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>
5446 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,
5447 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5448 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>
5449 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
5450 &lt;name&gt; is the new name of the effect send entity, which
5451 does not have to be unique (name MUST be encapsulated into apostrophes
5452 and supports escape sequences as described in chapter
5453 "<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>").
5454
5455 </p>
5456 <p>Possible Answers:
5457 </p>
5458 <p>
5459 </p>
5460 <blockquote class="text">
5461 <p>"OK" -
5462 </p>
5463 <blockquote class="text">
5464 <p>on success
5465 </p>
5466 </blockquote>
5467
5468
5469 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5470 </p>
5471 <blockquote class="text">
5472 <p>in case it failed, providing an appropriate error code and error message
5473 </p>
5474 </blockquote>
5475
5476
5477 </blockquote><p>
5478
5479 </p>
5480 <p>Example:
5481 </p>
5482 <p>
5483 </p>
5484 <blockquote class="text">
5485 <p>C: "SET FX_SEND NAME 0 0 'Fx Send 1'"
5486 </p>
5487 <p>S: "OK"
5488 </p>
5489 </blockquote><p>
5490
5491 </p>
5492 <a name="SET FX_SEND AUDIO_OUTPUT_CHANNEL"></a><br /><hr />
5493 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5494 <a name="rfc.section.6.4.31"></a><h3>6.4.31.&nbsp;
5495 Altering effect send's audio routing</h3>
5496
5497 <p>The front-end can alter the destination of an effect send's audio channel on a specific
5498 sampler channel by sending the following command:
5499 </p>
5500 <p>
5501 </p>
5502 <blockquote class="text">
5503 <p>SET FX_SEND AUDIO_OUTPUT_CHANNEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;audio-src&gt; &lt;audio-dst&gt;
5504 </p>
5505 </blockquote><p>
5506
5507 </p>
5508 <p>Where &lt;sampler-chan&gt; is the sampler channel number
5509 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>
5510 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,
5511 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5512 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>
5513 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,
5514 &lt;audio-src&gt; is the numerical ID of the effect send's audio channel
5515 which should be rerouted and &lt;audio-dst&gt; is the numerical ID of
5516 the audio channel of the selected audio output device where &lt;audio-src&gt;
5517 should be routed to.
5518 </p>
5519 <p>Note that effect sends can only route audio to the same audio output
5520 device as assigned to the effect send's sampler channel. Also note that an
5521 effect send entity does always have exactly as much audio channels as its
5522 sampler channel. So if the sampler channel is stereo, the effect send does
5523 have two audio channels as well. Also keep in mind that the amount of audio
5524 channels on a sampler channel might be dependant not only to the deployed
5525 sampler engine on the sampler channel, but also dependant to the instrument
5526 currently loaded. However you can (effectively) turn an i.e. stereo effect
5527 send into a mono one by simply altering its audio routing appropriately.
5528 </p>
5529 <p>Possible Answers:
5530 </p>
5531 <p>
5532 </p>
5533 <blockquote class="text">
5534 <p>"OK" -
5535 </p>
5536 <blockquote class="text">
5537 <p>on success
5538 </p>
5539 </blockquote>
5540
5541
5542 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5543 </p>
5544 <blockquote class="text">
5545 <p>if audio output channel was set, but there are noteworthy
5546 issue(s) related, providing an appropriate warning code and
5547 warning message
5548 </p>
5549 </blockquote>
5550
5551
5552 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5553 </p>
5554 <blockquote class="text">
5555 <p>in case it failed, providing an appropriate error code and error message
5556 </p>
5557 </blockquote>
5558
5559
5560 </blockquote><p>
5561
5562 </p>
5563 <p>Example:
5564 </p>
5565 <p>
5566 </p>
5567 <blockquote class="text">
5568 <p>C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2"
5569 </p>
5570 <p>S: "OK"
5571 </p>
5572 </blockquote><p>
5573
5574 </p>
5575 <a name="SET FX_SEND MIDI_CONTROLLER"></a><br /><hr />
5576 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5577 <a name="rfc.section.6.4.32"></a><h3>6.4.32.&nbsp;
5578 Altering effect send's MIDI controller</h3>
5579
5580 <p>The front-end can alter the MIDI controller of an effect
5581 send entity by sending the following command:
5582 </p>
5583 <p>
5584 </p>
5585 <blockquote class="text">
5586 <p>SET FX_SEND MIDI_CONTROLLER &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;midi-ctrl&gt;
5587 </p>
5588 </blockquote><p>
5589
5590 </p>
5591 <p>Where &lt;sampler-chan&gt; is the sampler channel number
5592 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>
5593 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,
5594 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5595 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>
5596 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
5597 &lt;midi-ctrl&gt; reflects the MIDI controller which shall be
5598 able to modify the effect send's send level.
5599 </p>
5600 <p>Possible Answers:
5601 </p>
5602 <p>
5603 </p>
5604 <blockquote class="text">
5605 <p>"OK" -
5606 </p>
5607 <blockquote class="text">
5608 <p>on success
5609 </p>
5610 </blockquote>
5611
5612
5613 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5614 </p>
5615 <blockquote class="text">
5616 <p>if MIDI controller was set, but there are noteworthy
5617 issue(s) related, providing an appropriate warning code and
5618 warning message
5619 </p>
5620 </blockquote>
5621
5622
5623 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5624 </p>
5625 <blockquote class="text">
5626 <p>in case it failed, providing an appropriate error code and error message
5627 </p>
5628 </blockquote>
5629
5630
5631 </blockquote><p>
5632
5633 </p>
5634 <p>Example:
5635 </p>
5636 <p>
5637 </p>
5638 <blockquote class="text">
5639 <p>C: "SET FX_SEND MIDI_CONTROLLER 0 0 91"
5640 </p>
5641 <p>S: "OK"
5642 </p>
5643 </blockquote><p>
5644
5645 </p>
5646 <a name="SET FX_SEND LEVEL"></a><br /><hr />
5647 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5648 <a name="rfc.section.6.4.33"></a><h3>6.4.33.&nbsp;
5649 Altering effect send's send level</h3>
5650
5651 <p>The front-end can alter the current send level of an effect
5652 send entity by sending the following command:
5653 </p>
5654 <p>
5655 </p>
5656 <blockquote class="text">
5657 <p>SET FX_SEND LEVEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;volume&gt;
5658 </p>
5659 </blockquote><p>
5660
5661 </p>
5662 <p>Where &lt;sampler-chan&gt; is the sampler channel number
5663 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>
5664 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,
5665 &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5666 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>
5667 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
5668 &lt;volume&gt; is an optionally dotted positive number (a value
5669 smaller than 1.0 means attenuation, whereas a value greater than
5670 1.0 means amplification) reflecting the new send level.
5671 </p>
5672 <p>Possible Answers:
5673 </p>
5674 <p>
5675 </p>
5676 <blockquote class="text">
5677 <p>"OK" -
5678 </p>
5679 <blockquote class="text">
5680 <p>on success
5681 </p>
5682 </blockquote>
5683
5684
5685 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5686 </p>
5687 <blockquote class="text">
5688 <p>if new send level was set, but there are noteworthy
5689 issue(s) related, providing an appropriate warning code and
5690 warning message
5691 </p>
5692 </blockquote>
5693
5694
5695 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5696 </p>
5697 <blockquote class="text">
5698 <p>in case it failed, providing an appropriate error code and error message
5699 </p>
5700 </blockquote>
5701
5702
5703 </blockquote><p>
5704
5705 </p>
5706 <p>Example:
5707 </p>
5708 <p>
5709 </p>
5710 <blockquote class="text">
5711 <p>C: "SET FX_SEND LEVEL 0 0 0.15"
5712 </p>
5713 <p>S: "OK"
5714 </p>
5715 </blockquote><p>
5716
5717 </p>
5718 <a name="RESET CHANNEL"></a><br /><hr />
5719 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5720 <a name="rfc.section.6.4.34"></a><h3>6.4.34.&nbsp;
5721 Resetting a sampler channel</h3>
5722
5723 <p>The front-end can reset a particular sampler channel by sending the following command:
5724 </p>
5725 <p>
5726 </p>
5727 <blockquote class="text">
5728 <p>RESET CHANNEL &lt;sampler-channel&gt;
5729 </p>
5730 </blockquote><p>
5731
5732 </p>
5733 <p>
5734 Where &lt;sampler-channel&gt; defines the sampler channel to be reset.
5735 This will cause the engine on that sampler channel, its voices and
5736 eventually disk streams and all control and status variables to be
5737 reset.
5738 </p>
5739 <p>Possible Answers:
5740 </p>
5741 <p>
5742 </p>
5743 <blockquote class="text">
5744 <p>"OK" -
5745 </p>
5746 <blockquote class="text">
5747 <p>on success
5748 </p>
5749 </blockquote>
5750
5751
5752 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5753 </p>
5754 <blockquote class="text">
5755 <p>if channel was reset, but there are noteworthy issue(s)
5756 related, providing an appropriate warning code and warning
5757 message
5758 </p>
5759 </blockquote>
5760
5761
5762 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5763 </p>
5764 <blockquote class="text">
5765 <p>in case it failed, providing an appropriate error code and
5766 error message
5767 </p>
5768 </blockquote>
5769
5770
5771 </blockquote><p>
5772
5773 </p>
5774 <p>Examples:
5775 </p>
5776 <p>
5777 </p>
5778 <blockquote class="text">
5779 <p>
5780 </p>
5781 </blockquote><p>
5782
5783 </p>
5784 <a name="anchor12"></a><br /><hr />
5785 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5786 <a name="rfc.section.6.5"></a><h3>6.5.&nbsp;
5787 Controlling connection</h3>
5788
5789 <p>The following commands are used to control the connection to LinuxSampler.
5790 </p>
5791 <a name="SUBSCRIBE"></a><br /><hr />
5792 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5793 <a name="rfc.section.6.5.1"></a><h3>6.5.1.&nbsp;
5794 Register front-end for receiving event messages</h3>
5795
5796 <p>The front-end can register itself to the LinuxSampler application to
5797 be informed about noteworthy events by sending this command:
5798 </p>
5799 <p>
5800 </p>
5801 <blockquote class="text">
5802 <p>SUBSCRIBE &lt;event-id&gt;
5803 </p>
5804 </blockquote><p>
5805
5806 </p>
5807 <p>where &lt;event-id&gt; will be replaced by the respective event that
5808 client wants to subscribe to.
5809 </p>
5810 <p>Possible Answers:
5811 </p>
5812 <p>
5813 </p>
5814 <blockquote class="text">
5815 <p>"OK" -
5816 </p>
5817 <blockquote class="text">
5818 <p>on success
5819 </p>
5820 </blockquote>
5821
5822
5823 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5824 </p>
5825 <blockquote class="text">
5826 <p>if registration succeeded, but there are noteworthy
5827 issue(s) related, providing an appropriate warning code and
5828 warning message
5829 </p>
5830 </blockquote>
5831
5832
5833 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5834 </p>
5835 <blockquote class="text">
5836 <p>in case it failed, providing an appropriate error code and
5837 error message
5838 </p>
5839 </blockquote>
5840
5841
5842 </blockquote><p>
5843
5844 </p>
5845 <p>Examples:
5846 </p>
5847 <p>
5848 </p>
5849 <blockquote class="text">
5850 <p>
5851 </p>
5852 </blockquote><p>
5853
5854 </p>
5855 <a name="UNSUBSCRIBE"></a><br /><hr />
5856 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5857 <a name="rfc.section.6.5.2"></a><h3>6.5.2.&nbsp;
5858 Unregister front-end for not receiving event messages</h3>
5859
5860 <p>The front-end can unregister itself if it doesn't want to receive event
5861 messages anymore by sending the following command:
5862 </p>
5863 <p>
5864 </p>
5865 <blockquote class="text">
5866 <p>UNSUBSCRIBE &lt;event-id&gt;
5867 </p>
5868 </blockquote><p>
5869
5870 </p>
5871 <p>Where &lt;event-id&gt; will be replaced by the respective event that
5872 client doesn't want to receive anymore.
5873 </p>
5874 <p>Possible Answers:
5875 </p>
5876 <p>
5877 </p>
5878 <blockquote class="text">
5879 <p>"OK" -
5880 </p>
5881 <blockquote class="text">
5882 <p>on success
5883 </p>
5884 </blockquote>
5885
5886
5887 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5888 </p>
5889 <blockquote class="text">
5890 <p>if unregistration succeeded, but there are noteworthy
5891 issue(s) related, providing an appropriate warning code and
5892 warning message
5893 </p>
5894 </blockquote>
5895
5896
5897 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5898 </p>
5899 <blockquote class="text">
5900 <p>in case it failed, providing an appropriate error code and
5901 error message
5902 </p>
5903 </blockquote>
5904
5905
5906 </blockquote><p>
5907
5908 </p>
5909 <p>Examples:
5910 </p>
5911 <p>
5912 </p>
5913 <blockquote class="text">
5914 <p>
5915 </p>
5916 </blockquote><p>
5917
5918 </p>
5919 <a name="SET ECHO"></a><br /><hr />
5920 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5921 <a name="rfc.section.6.5.3"></a><h3>6.5.3.&nbsp;
5922 Enable or disable echo of commands</h3>
5923
5924 <p>To enable or disable back sending of commands to the client the following command can be used:
5925 </p>
5926 <p>
5927 </p>
5928 <blockquote class="text">
5929 <p>SET ECHO &lt;value&gt;
5930 </p>
5931 </blockquote><p>
5932
5933 </p>
5934 <p>Where &lt;value&gt; should be replaced either by "1" to enable echo mode
5935 or "0" to disable echo mode. When echo mode is enabled, all
5936 commands send to LinuxSampler will be immediately send back and
5937 after this echo the actual response to the command will be
5938 returned. Echo mode will only be altered for the client connection
5939 that issued the "SET ECHO" command, not globally for all client
5940 connections.
5941 </p>
5942 <p>Possible Answers:
5943 </p>
5944 <p>
5945 </p>
5946 <blockquote class="text">
5947 <p>"OK" -
5948 </p>
5949 <blockquote class="text">
5950 <p>usually
5951 </p>
5952 </blockquote>
5953
5954
5955 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5956 </p>
5957 <blockquote class="text">
5958 <p>on syntax error, e.g. non boolean value
5959 </p>
5960 </blockquote>
5961
5962
5963 </blockquote><p>
5964
5965 </p>
5966 <p>Examples:
5967 </p>
5968 <p>
5969 </p>
5970 <blockquote class="text">
5971 <p>
5972 </p>
5973 </blockquote><p>
5974
5975 </p>
5976 <a name="QUIT"></a><br /><hr />
5977 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5978 <a name="rfc.section.6.5.4"></a><h3>6.5.4.&nbsp;
5979 Close client connection</h3>
5980
5981 <p>The client can close its network connection to LinuxSampler by sending the following command:
5982 </p>
5983 <p>
5984 </p>
5985 <blockquote class="text">
5986 <p>QUIT
5987 </p>
5988 </blockquote><p>
5989
5990 </p>
5991 <p>This is probably more interesting for manual telnet connections to
5992 LinuxSampler than really useful for a front-end implementation.
5993 </p>
5994 <a name="anchor13"></a><br /><hr />
5995 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5996 <a name="rfc.section.6.6"></a><h3>6.6.&nbsp;
5997 Global commands</h3>
5998
5999 <p>The following commands have global impact on the sampler.
6000 </p>
6001 <a name="GET TOTAL_VOICE_COUNT"></a><br /><hr />
6002 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6003 <a name="rfc.section.6.6.1"></a><h3>6.6.1.&nbsp;
6004 Current number of active voices</h3>
6005
6006 <p>The front-end can ask for the current number of active voices on
6007 the sampler by sending the following command:
6008 </p>
6009 <p>
6010 </p>
6011 <blockquote class="text">
6012 <p>GET TOTAL_VOICE_COUNT
6013 </p>
6014 </blockquote><p>
6015
6016 </p>
6017 <p>Possible Answers:
6018 </p>
6019 <p>
6020 </p>
6021 <blockquote class="text">
6022 <p>LinuxSampler will answer by returning the number of all active
6023 voices on the sampler.
6024 </p>
6025 </blockquote><p>
6026
6027 </p>
6028 <a name="GET TOTAL_VOICE_COUNT_MAX"></a><br /><hr />
6029 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6030 <a name="rfc.section.6.6.2"></a><h3>6.6.2.&nbsp;
6031 Maximum amount of active voices</h3>
6032
6033 <p>The front-end can ask for the maximum number of active voices
6034 by sending the following command:
6035 </p>
6036 <p>
6037 </p>
6038 <blockquote class="text">
6039 <p>GET TOTAL_VOICE_COUNT_MAX
6040 </p>
6041 </blockquote><p>
6042
6043 </p>
6044 <p>Possible Answers:
6045 </p>
6046 <p>
6047 </p>
6048 <blockquote class="text">
6049 <p>LinuxSampler will answer by returning the maximum number
6050 of active voices.
6051 </p>
6052 </blockquote><p>
6053
6054 </p>
6055 <a name="RESET"></a><br /><hr />
6056 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6057 <a name="rfc.section.6.6.3"></a><h3>6.6.3.&nbsp;
6058 Reset sampler</h3>
6059
6060 <p>The front-end can reset the whole sampler by sending the following command:
6061 </p>
6062 <p>
6063 </p>
6064 <blockquote class="text">
6065 <p>RESET
6066 </p>
6067 </blockquote><p>
6068
6069 </p>
6070 <p>Possible Answers:
6071 </p>
6072 <p>
6073 </p>
6074 <blockquote class="text">
6075 <p>"OK" -
6076 </p>
6077 <blockquote class="text">
6078 <p>always
6079 </p>
6080 </blockquote>
6081
6082
6083 </blockquote><p>
6084
6085 </p>
6086 <p>Examples:
6087 </p>
6088 <p>
6089 </p>
6090 <blockquote class="text">
6091 <p>
6092 </p>
6093 </blockquote><p>
6094
6095 </p>
6096 <a name="GET SERVER INFO"></a><br /><hr />
6097 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6098 <a name="rfc.section.6.6.4"></a><h3>6.6.4.&nbsp;
6099 General sampler informations</h3>
6100
6101 <p>The client can ask for general informations about the LinuxSampler
6102 instance by sending the following command:
6103 </p>
6104 <p>
6105 </p>
6106 <blockquote class="text">
6107 <p>GET SERVER INFO
6108 </p>
6109 </blockquote><p>
6110
6111 </p>
6112 <p>Possible Answers:
6113 </p>
6114 <p>
6115 </p>
6116 <blockquote class="text">
6117 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6118 Each answer line begins with the information category name
6119 followed by a colon and then a space character &lt;SP&gt; and finally
6120 the info character string to that information category. At the
6121 moment the following categories are defined:
6122
6123 </p>
6124 <p>
6125 </p>
6126 <blockquote class="text">
6127 <p>DESCRIPTION -
6128 </p>
6129 <blockquote class="text">
6130 <p>arbitrary textual description about the sampler
6131 (note that the character string may contain
6132 <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>)
6133 </p>
6134 </blockquote>
6135
6136
6137 <p>VERSION -
6138 </p>
6139 <blockquote class="text">
6140 <p>version of the sampler
6141 </p>
6142 </blockquote>
6143
6144
6145 <p>PROTOCOL_VERSION -
6146 </p>
6147 <blockquote class="text">
6148 <p>version of the LSCP specification the sampler
6149 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)
6150 </p>
6151 </blockquote>
6152
6153
6154 <p>INSTRUMENTS_DB_SUPPORT -
6155 </p>
6156 <blockquote class="text">
6157 <p>either yes or no, specifies whether the
6158 sampler is build with instruments database support.
6159 </p>
6160 </blockquote>
6161
6162
6163 </blockquote>
6164
6165
6166 </blockquote><p>
6167
6168 </p>
6169 <p>The mentioned fields above don't have to be in particular order.
6170 Other fields might be added in future.
6171 </p>
6172 <a name="GET 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.5"></a><h3>6.6.5.&nbsp;
6175 Getting global volume attenuation</h3>
6176
6177 <p>The client can ask for 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>GET VOLUME
6184 </p>
6185 </blockquote><p>
6186
6187 </p>
6188 <p>Possible Answers:
6189 </p>
6190 <p>
6191 </p>
6192 <blockquote class="text">
6193 <p>The sampler will always answer by returning the optional
6194 dotted floating point coefficient, reflecting the current
6195 global volume attenuation.
6196
6197 </p>
6198 </blockquote><p>
6199
6200 </p>
6201 <p>Note: it is up to the respective sampler engine whether to obey
6202 that global volume parameter or not, but in general all engines SHOULD
6203 use this parameter.
6204 </p>
6205 <a name="SET VOLUME"></a><br /><hr />
6206 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6207 <a name="rfc.section.6.6.6"></a><h3>6.6.6.&nbsp;
6208 Setting global volume attenuation</h3>
6209
6210 <p>The client can alter the current global sampler-wide volume
6211 attenuation by sending the following command:
6212 </p>
6213 <p>
6214 </p>
6215 <blockquote class="text">
6216 <p>SET VOLUME &lt;volume&gt;
6217 </p>
6218 </blockquote><p>
6219
6220 </p>
6221 <p>Where &lt;volume&gt; should be replaced by the optional dotted
6222 floating point value, reflecting the new global volume parameter.
6223 This value might usually be in the range between 0.0 and 1.0, that
6224 is for attenuating the overall volume.
6225 </p>
6226 <p>Possible Answers:
6227 </p>
6228 <p>
6229 </p>
6230 <blockquote class="text">
6231 <p>"OK" -
6232 </p>
6233 <blockquote class="text">
6234 <p>on success
6235 </p>
6236 </blockquote>
6237
6238
6239 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6240 </p>
6241 <blockquote class="text">
6242 <p>if the global volume was set, but there are noteworthy
6243 issue(s) related, providing an appropriate warning code and
6244 warning message
6245 </p>
6246 </blockquote>
6247
6248
6249 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6250 </p>
6251 <blockquote class="text">
6252 <p>in case it failed, providing an appropriate error code and error message
6253 </p>
6254 </blockquote>
6255
6256
6257 </blockquote><p>
6258
6259 </p>
6260 <a name="MIDI Instrument Mapping"></a><br /><hr />
6261 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6262 <a name="rfc.section.6.7"></a><h3>6.7.&nbsp;
6263 MIDI Instrument Mapping</h3>
6264
6265 <p>The MIDI protocol provides a way to switch between instruments
6266 by sending so called MIDI bank select and MIDI program change
6267 messages which are essentially just numbers. The following commands
6268 allow to actually map arbitrary MIDI bank select / program change
6269 numbers with real instruments.
6270 </p>
6271 <p>The sampler allows to manage an arbitrary amount of MIDI
6272 instrument maps which define which instrument to load on
6273 which MIDI program change message.
6274 </p>
6275 <p>By default, that is when the sampler is launched, there is no
6276 map, thus the sampler will simply ignore all program change
6277 messages. The front-end has to explicitly create at least one
6278 map, add entries to the map and tell the respective sampler
6279 channel(s) which MIDI instrument map to use, so the sampler
6280 knows how to react on a given program change message on the
6281 respective sampler channel, that is by switching to the
6282 respectively defined engine type and loading the respective
6283 instrument. See command
6284 <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>
6285 for how to assign a MIDI instrument map to a sampler channel.
6286 </p>
6287 <p>Also note per MIDI specification a bank select message does not
6288 cause to switch to another instrument. Instead when receiving a
6289 bank select message the bank value will be stored and a subsequent
6290 program change message (which may occur at any time) will finally
6291 cause the sampler to switch to the respective instrument as
6292 reflected by the current MIDI instrument map.
6293 </p>
6294 <a name="ADD MIDI_INSTRUMENT_MAP"></a><br /><hr />
6295 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6296 <a name="rfc.section.6.7.1"></a><h3>6.7.1.&nbsp;
6297 Create a new MIDI instrument map</h3>
6298
6299 <p>The front-end can add a new MIDI instrument map by sending
6300 the following command:
6301 </p>
6302 <p>
6303 </p>
6304 <blockquote class="text">
6305 <p>ADD MIDI_INSTRUMENT_MAP [&lt;name&gt;]
6306 </p>
6307 </blockquote><p>
6308
6309 </p>
6310 <p>Where &lt;name&gt; is an optional argument allowing to
6311 assign a custom name to the new map. MIDI instrument Map
6312 names do not have to be unique, but MUST be encapsulated
6313 into apostrophes and support escape sequences as described
6314 in chapter "<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>".
6315
6316 </p>
6317 <p>Possible Answers:
6318 </p>
6319 <p>
6320 </p>
6321 <blockquote class="text">
6322 <p>"OK[&lt;map&gt;]" -
6323 </p>
6324 <blockquote class="text">
6325 <p>in case a new MIDI instrument map could
6326 be added, where &lt;map&gt; reflects the
6327 unique ID of the newly created MIDI
6328 instrument map
6329 </p>
6330 </blockquote>
6331
6332
6333 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6334 </p>
6335 <blockquote class="text">
6336 <p>when a new map could not be created, which
6337 might never occur in practice
6338 </p>
6339 </blockquote>
6340
6341
6342 </blockquote><p>
6343
6344 </p>
6345 <p>Examples:
6346 </p>
6347 <p>
6348 </p>
6349 <blockquote class="text">
6350 <p>C: "ADD MIDI_INSTRUMENT_MAP 'Standard Map'"
6351 </p>
6352 <p>S: "OK[0]"
6353 </p>
6354 </blockquote><p>
6355
6356 </p>
6357 <p>
6358 </p>
6359 <blockquote class="text">
6360 <p>C: "ADD MIDI_INSTRUMENT_MAP 'Standard Drumkit'"
6361 </p>
6362 <p>S: "OK[1]"
6363 </p>
6364 </blockquote><p>
6365
6366 </p>
6367 <p>
6368 </p>
6369 <blockquote class="text">
6370 <p>C: "ADD MIDI_INSTRUMENT_MAP"
6371 </p>
6372 <p>S: "OK[5]"
6373 </p>
6374 </blockquote><p>
6375
6376 </p>
6377 <a name="REMOVE MIDI_INSTRUMENT_MAP"></a><br /><hr />
6378 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6379 <a name="rfc.section.6.7.2"></a><h3>6.7.2.&nbsp;
6380 Delete one particular or all MIDI instrument maps</h3>
6381
6382 <p>The front-end can delete a particular MIDI instrument map
6383 by sending the following command:
6384 </p>
6385 <p>
6386 </p>
6387 <blockquote class="text">
6388 <p>REMOVE MIDI_INSTRUMENT_MAP &lt;map&gt;
6389 </p>
6390 </blockquote><p>
6391
6392 </p>
6393 <p>Where &lt;map&gt; reflects the unique ID of the map to delete
6394 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>
6395 command.
6396 </p>
6397 <p>The front-end can delete all MIDI instrument maps by
6398 sending the following command:
6399 </p>
6400 <p>
6401 </p>
6402 <blockquote class="text">
6403 <p>REMOVE MIDI_INSTRUMENT_MAP ALL
6404 </p>
6405 </blockquote><p>
6406
6407 </p>
6408 <p>Possible Answers:
6409 </p>
6410 <p>
6411 </p>
6412 <blockquote class="text">
6413 <p>"OK" -
6414 </p>
6415 <blockquote class="text">
6416 <p>in case the map(s) could be deleted
6417 </p>
6418 </blockquote>
6419
6420
6421 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6422 </p>
6423 <blockquote class="text">
6424 <p>when the given map does not exist
6425 </p>
6426 </blockquote>
6427
6428
6429 </blockquote><p>
6430
6431 </p>
6432 <p>Examples:
6433 </p>
6434 <p>
6435 </p>
6436 <blockquote class="text">
6437 <p>C: "REMOVE MIDI_INSTRUMENT_MAP 0"
6438 </p>
6439 <p>S: "OK"
6440 </p>
6441 </blockquote><p>
6442
6443 </p>
6444 <p>
6445 </p>
6446 <blockquote class="text">
6447 <p>C: "REMOVE MIDI_INSTRUMENT_MAP ALL"
6448 </p>
6449 <p>S: "OK"
6450 </p>
6451 </blockquote><p>
6452
6453 </p>
6454 <a name="GET MIDI_INSTRUMENT_MAPS"></a><br /><hr />
6455 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6456 <a name="rfc.section.6.7.3"></a><h3>6.7.3.&nbsp;
6457 Get amount of existing MIDI instrument maps</h3>
6458
6459 <p>The front-end can retrieve the current amount of MIDI
6460 instrument maps by sending the following command:
6461 </p>
6462 <p>
6463 </p>
6464 <blockquote class="text">
6465 <p>GET MIDI_INSTRUMENT_MAPS
6466 </p>
6467 </blockquote><p>
6468
6469 </p>
6470 <p>Possible Answers:
6471 </p>
6472 <p>
6473 </p>
6474 <blockquote class="text">
6475 <p>The sampler will answer by returning the current
6476 number of MIDI instrument maps.
6477 </p>
6478 </blockquote><p>
6479
6480 </p>
6481 <p>Example:
6482 </p>
6483 <p>
6484 </p>
6485 <blockquote class="text">
6486 <p>C: "GET MIDI_INSTRUMENT_MAPS"
6487 </p>
6488 <p>S: "2"
6489 </p>
6490 </blockquote><p>
6491
6492 </p>
6493 <a name="LIST MIDI_INSTRUMENT_MAPS"></a><br /><hr />
6494 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6495 <a name="rfc.section.6.7.4"></a><h3>6.7.4.&nbsp;
6496 Getting all created MIDI instrument maps</h3>
6497
6498 <p>The number of MIDI instrument maps can change on runtime. To get the
6499 current list of MIDI instrument maps, the front-end can send the
6500 following command:
6501 </p>
6502 <p>
6503 </p>
6504 <blockquote class="text">
6505 <p>LIST MIDI_INSTRUMENT_MAPS
6506 </p>
6507 </blockquote><p>
6508
6509 </p>
6510 <p>Possible Answers:
6511 </p>
6512 <p>
6513 </p>
6514 <blockquote class="text">
6515 <p>The sampler will answer by returning a comma separated list
6516 with all MIDI instrument maps' numerical IDs.
6517 </p>
6518 </blockquote><p>
6519
6520 </p>
6521 <p>Example:
6522 </p>
6523 <p>
6524 </p>
6525 <blockquote class="text">
6526 <p>C: "LIST MIDI_INSTRUMENT_MAPS"
6527 </p>
6528 <p>S: "0,1,5,12"
6529 </p>
6530 </blockquote><p>
6531
6532 </p>
6533 <a name="GET MIDI_INSTRUMENT_MAP INFO"></a><br /><hr />
6534 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6535 <a name="rfc.section.6.7.5"></a><h3>6.7.5.&nbsp;
6536 Getting MIDI instrument map information</h3>
6537
6538 <p>The front-end can ask for the current settings of a MIDI
6539 instrument map by sending the following command:
6540 </p>
6541 <p>
6542 </p>
6543 <blockquote class="text">
6544 <p>GET MIDI_INSTRUMENT_MAP INFO &lt;map&gt;
6545 </p>
6546 </blockquote><p>
6547
6548 </p>
6549 <p>Where &lt;map&gt; is the numerical ID of the map the
6550 front-end is interested in as returned by the
6551 <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>
6552 command.
6553 </p>
6554 <p>Possible Answers:
6555 </p>
6556 <p>
6557 </p>
6558 <blockquote class="text">
6559 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6560 Each answer line begins with the settings category name
6561 followed by a colon and then a space character &lt;SP&gt; and finally
6562 the info character string to that setting category. At the
6563 moment the following categories are defined:
6564 </p>
6565 <p>
6566 </p>
6567 <blockquote class="text">
6568 <p>NAME -
6569 </p>
6570 <blockquote class="text">
6571 <p>custom name of the given map,
6572 which does not have to be unique
6573 (note that this character string may contain
6574 <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>)
6575 </p>
6576 </blockquote>
6577
6578
6579 <p>DEFAULT -
6580 </p>
6581 <blockquote class="text">
6582 <p>either true or false,
6583 defines whether this map is the default map
6584 </p>
6585 </blockquote>
6586
6587
6588 </blockquote>
6589
6590
6591 </blockquote><p>
6592
6593 </p>
6594 <p>The mentioned fields above don't have to be in particular order.
6595 </p>
6596 <p>Example:
6597 </p>
6598 <p>
6599 </p>
6600 <blockquote class="text">
6601 <p>C: "GET MIDI_INSTRUMENT_MAP INFO 0"
6602 </p>
6603 <p>S: "NAME: Standard Map"
6604 </p>
6605 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: true"
6606 </p>
6607 <p>&nbsp;&nbsp;&nbsp;"."
6608 </p>
6609 </blockquote><p>
6610
6611 </p>
6612 <a name="SET MIDI_INSTRUMENT_MAP NAME"></a><br /><hr />
6613 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6614 <a name="rfc.section.6.7.6"></a><h3>6.7.6.&nbsp;
6615 Renaming a MIDI instrument map</h3>
6616
6617 <p>The front-end can alter the custom name of a MIDI
6618 instrument map by sending the following command:
6619 </p>
6620 <p>
6621 </p>
6622 <blockquote class="text">
6623 <p>SET MIDI_INSTRUMENT_MAP NAME &lt;map&gt; &lt;name&gt;
6624 </p>
6625 </blockquote><p>
6626
6627 </p>
6628 <p>Where &lt;map&gt; is the numerical ID of the map and
6629 &lt;name&gt; the new custom name of the map, which does not
6630 have to be unique (name MUST be encapsulated into apostrophes
6631 and supports escape sequences as described in chapter
6632 "<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>").
6633
6634 </p>
6635 <p>Possible Answers:
6636 </p>
6637 <p>
6638 </p>
6639 <blockquote class="text">
6640 <p>"OK" -
6641 </p>
6642 <blockquote class="text">
6643 <p>on success
6644 </p>
6645 </blockquote>
6646
6647
6648 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6649 </p>
6650 <blockquote class="text">
6651 <p>in case the given map does not exist
6652 </p>
6653 </blockquote>
6654
6655
6656 </blockquote><p>
6657
6658 </p>
6659 <p>Example:
6660 </p>
6661 <p>
6662 </p>
6663 <blockquote class="text">
6664 <p>C: "SET MIDI_INSTRUMENT_MAP NAME 0 'Foo instruments'"
6665 </p>
6666 <p>S: "OK"
6667 </p>
6668 </blockquote><p>
6669
6670 </p>
6671 <a name="MAP MIDI_INSTRUMENT"></a><br /><hr />
6672 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6673 <a name="rfc.section.6.7.7"></a><h3>6.7.7.&nbsp;
6674 Create or replace a MIDI instrument map entry</h3>
6675
6676 <p>The front-end can create a new or replace an existing entry
6677 in a sampler's MIDI instrument map by sending the following
6678 command:
6679 </p>
6680 <p>
6681 </p>
6682 <blockquote class="text">
6683 <p>MAP MIDI_INSTRUMENT [NON_MODAL] &lt;map&gt;
6684 &lt;midi_bank&gt; &lt;midi_prog&gt; &lt;engine_name&gt;
6685 &lt;filename&gt; &lt;instrument_index&gt; &lt;volume_value&gt;
6686 [&lt;instr_load_mode&gt;] [&lt;name&gt;]
6687 </p>
6688 </blockquote><p>
6689
6690 </p>
6691 <p>Where &lt;map&gt; is the numeric ID of the map to alter,
6692 &lt;midi_bank&gt; is an integer value between
6693 0..16383 reflecting the MIDI bank select index,
6694 &lt;midi_prog&gt; an
6695 integer value between 0..127 reflecting the MIDI program change
6696 index, &lt;engine_name&gt; a sampler engine name as returned by
6697 the <a class='info' href='#LIST AVAILABLE_ENGINES'>"LIST AVAILABLE_ENGINES"<span> (</span><span class='info'>Getting all available engines</span><span>)</span></a>
6698 command (not encapsulated into apostrophes), &lt;filename&gt; the name
6699 of the instrument's file to be deployed (encapsulated into apostrophes,
6700 supporting escape sequences as described in chapter
6701 "<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>"),
6702 &lt;instrument_index&gt; the index (integer value) of the instrument
6703 within the given file, &lt;volume_value&gt; reflects the master
6704 volume of the instrument as optionally dotted number (where a
6705 value &lt; 1.0 means attenuation and a value > 1.0 means
6706 amplification). This parameter easily allows to adjust the
6707 volume of all intruments within a custom instrument map
6708 without having to adjust their instrument files. The
6709 OPTIONAL &lt;instr_load_mode&gt; argument defines the life
6710 time of the instrument, that is when the instrument should
6711 be loaded, when freed and has exactly the following
6712 possibilities:
6713 </p>
6714 <p>
6715 </p>
6716 <blockquote class="text">
6717 <p>"ON_DEMAND" -
6718 </p>
6719 <blockquote class="text">
6720 <p>The instrument will be loaded when needed,
6721 that is when demanded by at least one sampler
6722 channel. It will immediately be freed from memory
6723 when not needed by any sampler channel anymore.
6724 </p>
6725 </blockquote>
6726
6727
6728 <p>"ON_DEMAND_HOLD" -
6729 </p>
6730 <blockquote class="text">
6731 <p>The instrument will be loaded when needed,
6732 that is when demanded by at least one sampler
6733 channel. It will be kept in memory even when
6734 not needed by any sampler channel anymore.
6735 Instruments with this mode are only freed
6736 when the sampler is reset or all mapping
6737 entries with this mode (and respective
6738 instrument) are explicitly changed to
6739 "ON_DEMAND" and no sampler channel is using
6740 the instrument anymore.
6741 </p>
6742 </blockquote>
6743
6744
6745 <p>"PERSISTENT" -
6746 </p>
6747 <blockquote class="text">
6748 <p>The instrument will immediately be loaded
6749 into memory when this mapping
6750 command is sent and the instrument is kept all
6751 the time. Instruments with this mode are
6752 only freed when the sampler is reset or all
6753 mapping entries with this mode (and
6754 respective instrument) are explicitly
6755 changed to "ON_DEMAND" and no sampler
6756 channel is using the instrument anymore.
6757 </p>
6758 </blockquote>
6759
6760
6761 <p>not supplied -
6762 </p>
6763 <blockquote class="text">
6764 <p>In case there is no &lt;instr_load_mode&gt;
6765 argument given, it will be up to the
6766 InstrumentManager to decide which mode to use.
6767 Usually it will use "ON_DEMAND" if an entry
6768 for the given instrument does not exist in
6769 the InstrumentManager's list yet, otherwise
6770 if an entry already exists, it will simply
6771 stick with the mode currently reflected by
6772 the already existing entry, that is it will
6773 not change the mode.
6774 </p>
6775 </blockquote>
6776
6777
6778 </blockquote><p>
6779
6780 </p>
6781 <p>
6782 The &lt;instr_load_mode&gt; argument thus allows to define an
6783 appropriate strategy (low memory consumption vs. fast
6784 instrument switching) for each instrument individually. Note, the
6785 following restrictions apply to this argument: "ON_DEMAND_HOLD" and
6786 "PERSISTENT" have to be supported by the respective sampler engine
6787 (which is technically the case when the engine provides an
6788 InstrumentManager for its format). If this is not the case the
6789 argument will automatically fall back to the default value
6790 "ON_DEMAND". Also the load mode of one instrument may
6791 automatically change the laod mode of other instrument(s), i.e.
6792 because the instruments are part of the same file and the
6793 engine does not allow a way to manage load modes for them
6794 individually. Due to this, in case the frontend shows the
6795 load modes of entries, the frontend should retrieve the actual
6796 mode by i.e. sending
6797 <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>
6798 command(s). Finally the OPTIONAL &lt;name&gt; argument allows to set a custom name
6799 (encapsulated into apostrophes, supporting escape sequences as described in chapter
6800 "<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>") for the
6801 mapping entry, useful for frontends for displaying an appropriate name for
6802 mapped instruments (using
6803 <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>).
6804
6805 </p>
6806 <p>
6807 By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is
6808 completely established in the sampler. The OPTIONAL "NON_MODAL" argument
6809 however causes the respective "MAP MIDI_INSTRUMENT" command to return
6810 immediately, that is to let the sampler establish the mapping in the
6811 background. So this argument might be especially useful for mappings with
6812 a "PERSISTENT" type, because these have to load the respective instruments
6813 immediately and might thus block for a very long time. It is recommended
6814 however to use the OPTIONAL "NON_MODAL" argument only if really necessary,
6815 because it has the following drawbacks: as "NON_MODAL" instructions return
6816 immediately, they may not necessarily return an error i.e. when the given
6817 instrument file turns out to be corrupt, beside that subsequent commands
6818 in a LSCP instruction sequence might fail, because mandatory mappings are
6819 not yet completed.
6820
6821 </p>
6822 <p>Possible Answers:
6823 </p>
6824 <p>
6825 </p>
6826 <blockquote class="text">
6827 <p>"OK" -
6828 </p>
6829 <blockquote class="text">
6830 <p>usually
6831 </p>
6832 </blockquote>
6833
6834
6835 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6836 </p>
6837 <blockquote class="text">
6838 <p>when the given map or engine does not exist or a value
6839 is out of range
6840 </p>
6841 </blockquote>
6842
6843
6844 </blockquote><p>
6845
6846 </p>
6847 <p>Examples:
6848 </p>
6849 <p>
6850 </p>
6851 <blockquote class="text">
6852 <p>C: "MAP MIDI_INSTRUMENT 0 3 0 gig '/usr/share/Steinway D.gig' 0 0.8 PERSISTENT"
6853 </p>
6854 <p>S: "OK"
6855 </p>
6856 </blockquote><p>
6857
6858 </p>
6859 <p>
6860 </p>
6861 <blockquote class="text">
6862 <p>C: "MAP MIDI_INSTRUMENT 0 4 50 gig '/home/john/foostrings.gig' 7 1.0"
6863 </p>
6864 <p>S: "OK"
6865 </p>
6866 </blockquote><p>
6867
6868 </p>
6869 <p>
6870 </p>
6871 <blockquote class="text">
6872 <p>C: "MAP MIDI_INSTRUMENT 0 0 0 gig '/usr/share/piano.gig' 0 1.0 'Normal Piano'"
6873 </p>
6874 <p>S: "OK"
6875 </p>
6876 <p>C: "MAP MIDI_INSTRUMENT 0 1 0 gig '/usr/share/piano.gig' 0 0.25 'Silent Piano'"
6877 </p>
6878 <p>S: "OK"
6879 </p>
6880 </blockquote><p>
6881
6882 </p>
6883 <p>
6884 </p>
6885 <blockquote class="text">
6886 <p>C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"
6887 </p>
6888 <p>S: "OK"
6889 </p>
6890 </blockquote><p>
6891
6892 </p>
6893 <a name="GET MIDI_INSTRUMENTS"></a><br /><hr />
6894 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6895 <a name="rfc.section.6.7.8"></a><h3>6.7.8.&nbsp;
6896 Getting ammount of MIDI instrument map entries</h3>
6897
6898 <p>The front-end can query the amount of currently existing
6899 entries in a MIDI instrument map by sending the following
6900 command:
6901 </p>
6902 <p>
6903 </p>
6904 <blockquote class="text">
6905 <p>GET MIDI_INSTRUMENTS &lt;map&gt;
6906 </p>
6907 </blockquote><p>
6908
6909 </p>
6910 <p>The front-end can query the amount of currently existing
6911 entries in all MIDI instrument maps by sending the following
6912 command:
6913 </p>
6914 <p>
6915 </p>
6916 <blockquote class="text">
6917 <p>GET MIDI_INSTRUMENTS ALL
6918 </p>
6919 </blockquote><p>
6920
6921 </p>
6922 <p>Possible Answers:
6923 </p>
6924 <p>
6925 </p>
6926 <blockquote class="text">
6927 <p>The sampler will answer by sending the current number of
6928 entries in the MIDI instrument map(s).
6929 </p>
6930 </blockquote><p>
6931
6932 </p>
6933 <p>Example:
6934 </p>
6935 <p>
6936 </p>
6937 <blockquote class="text">
6938 <p>C: "GET MIDI_INSTRUMENTS 0"
6939 </p>
6940 <p>S: "234"
6941 </p>
6942 </blockquote><p>
6943
6944 </p>
6945 <p>
6946 </p>
6947 <blockquote class="text">
6948 <p>C: "GET MIDI_INSTRUMENTS ALL"
6949 </p>
6950 <p>S: "954"
6951 </p>
6952 </blockquote><p>
6953
6954 </p>
6955 <a name="LIST MIDI_INSTRUMENTS"></a><br /><hr />
6956 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6957 <a name="rfc.section.6.7.9"></a><h3>6.7.9.&nbsp;
6958 Getting indeces of all entries of a MIDI instrument map</h3>
6959
6960 <p>The front-end can query a list of all currently existing
6961 entries in a certain MIDI instrument map by sending the following
6962 command:
6963 </p>
6964 <p>
6965 </p>
6966 <blockquote class="text">
6967 <p>LIST MIDI_INSTRUMENTS &lt;map&gt;
6968 </p>
6969 </blockquote><p>
6970
6971 </p>
6972 <p>Where &lt;map&gt; is the numeric ID of the MIDI instrument map.
6973 </p>
6974 <p>The front-end can query a list of all currently existing
6975 entries of all MIDI instrument maps by sending the following
6976 command:
6977 </p>
6978 <p>
6979 </p>
6980 <blockquote class="text">
6981 <p>LIST MIDI_INSTRUMENTS ALL
6982 </p>
6983 </blockquote><p>
6984
6985 </p>
6986 <p>Possible Answers:
6987 </p>
6988 <p>
6989 </p>
6990 <blockquote class="text">
6991 <p>The sampler will answer by sending a comma separated
6992 list of map ID - MIDI bank - MIDI program triples, where
6993 each triple is encapsulated into curly braces. The
6994 list is returned in one single line. Each triple
6995 just reflects the key of the respective map entry,
6996 thus subsequent
6997 <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>
6998 command(s) are necessary to retrieve detailed informations
6999 about each entry.
7000 </p>
7001 </blockquote><p>
7002
7003 </p>
7004 <p>Example:
7005 </p>
7006 <p>
7007 </p>
7008 <blockquote class="text">
7009 <p>C: "LIST MIDI_INSTRUMENTS 0"
7010 </p>
7011 <p>S: "{0,0,0},{0,0,1},{0,0,3},{0,1,4},{1,127,127}"
7012 </p>
7013 </blockquote><p>
7014
7015 </p>
7016 <a name="UNMAP MIDI_INSTRUMENT"></a><br /><hr />
7017 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7018 <a name="rfc.section.6.7.10"></a><h3>6.7.10.&nbsp;
7019 Remove an entry from the MIDI instrument map</h3>
7020
7021 <p>The front-end can delete an entry from a MIDI instrument
7022 map by sending the following command:
7023 </p>
7024 <p>
7025 </p>
7026 <blockquote class="text">
7027 <p>UNMAP MIDI_INSTRUMENT &lt;map&gt; &lt;midi_bank&gt; &lt;midi_prog&gt;
7028 </p>
7029 </blockquote><p>
7030
7031 </p>
7032 <p>
7033 Where &lt;map&gt; is the numeric ID of the MIDI instrument map,
7034 &lt;midi_bank&gt; is an integer value between 0..16383
7035 reflecting the MIDI bank value and
7036 &lt;midi_prog&gt; an integer value between
7037 0..127 reflecting the MIDI program value of the map's entrie's key
7038 index triple.
7039
7040 </p>
7041 <p>Possible Answers:
7042 </p>
7043 <p>
7044 </p>
7045 <blockquote class="text">
7046 <p>"OK" -
7047 </p>
7048 <blockquote class="text">
7049 <p>usually
7050 </p>
7051 </blockquote>
7052
7053
7054 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7055 </p>
7056 <blockquote class="text">
7057 <p>when index out of bounds
7058 </p>
7059 </blockquote>
7060
7061
7062 </blockquote><p>
7063
7064 </p>
7065 <p>Example:
7066 </p>
7067 <p>
7068 </p>
7069 <blockquote class="text">
7070 <p>C: "UNMAP MIDI_INSTRUMENT 0 2 127"
7071 </p>
7072 <p>S: "OK"
7073 </p>
7074 </blockquote><p>
7075
7076 </p>
7077 <a name="GET MIDI_INSTRUMENT INFO"></a><br /><hr />
7078 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7079 <a name="rfc.section.6.7.11"></a><h3>6.7.11.&nbsp;
7080 Get current settings of MIDI instrument map entry</h3>
7081
7082 <p>The front-end can retrieve the current settings of a certain
7083 instrument map entry by sending the following command:
7084 </p>
7085 <p>
7086 </p>
7087 <blockquote class="text">
7088 <p>GET MIDI_INSTRUMENT INFO &lt;map&gt; &lt;midi_bank&gt; &lt;midi_prog&gt;
7089 </p>
7090 </blockquote><p>
7091
7092 </p>
7093 <p>
7094 Where &lt;map&gt; is the numeric ID of the MIDI instrument map,
7095 &lt;midi_bank&gt; is an integer value between 0..16383
7096 reflecting the MIDI bank value, &lt;midi_bank&gt;
7097 and &lt;midi_prog&gt; an integer value between
7098 0..127 reflecting the MIDI program value of the map's entrie's key
7099 index triple.
7100
7101 </p>
7102 <p>Possible Answers:
7103 </p>
7104 <p>
7105 </p>
7106 <blockquote class="text">
7107 <p>LinuxSampler will answer by sending a &lt;CRLF&gt;
7108 separated list. Each answer line begins with the
7109 information category name followed by a colon and then
7110 a space character &lt;SP&gt; and finally the info
7111 character string to that info category. At the moment
7112 the following categories are defined:
7113 </p>
7114 <p>"NAME" -
7115 </p>
7116 <blockquote class="text">
7117 <p>Name for this MIDI instrument map entry (if defined).
7118 This name shall be used by frontends for displaying a
7119 name for this mapped instrument. It can be set and
7120 changed with the
7121 <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>
7122 command and does not have to be unique.
7123 (note that this character string may contain
7124 <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>)
7125 </p>
7126 </blockquote>
7127
7128
7129 <p>"ENGINE_NAME" -
7130 </p>
7131 <blockquote class="text">
7132 <p>Name of the engine to be deployed for this
7133 instrument.
7134 </p>
7135 </blockquote>
7136
7137
7138 <p>"INSTRUMENT_FILE" -
7139 </p>
7140 <blockquote class="text">
7141 <p>File name of the instrument
7142 (note that this path may contain
7143 <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>).
7144 </p>
7145 </blockquote>
7146
7147
7148 <p>"INSTRUMENT_NR" -
7149 </p>
7150 <blockquote class="text">
7151 <p>Index of the instrument within the file.
7152 </p>
7153 </blockquote>
7154
7155
7156 <p>"INSTRUMENT_NAME" -
7157 </p>
7158 <blockquote class="text">
7159 <p>Name of the loaded instrument as reflected by its file.
7160 In contrast to the "NAME" field, the "INSTRUMENT_NAME" field
7161 cannot be changed (note that this character string may contain
7162 <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>).
7163 </p>
7164 </blockquote>
7165
7166
7167 <p>"LOAD_MODE" -
7168 </p>
7169 <blockquote class="text">
7170 <p>Life time of instrument
7171 (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).
7172 </p>
7173 </blockquote>
7174
7175
7176 <p>"VOLUME" -
7177 </p>
7178 <blockquote class="text">
7179 <p>master volume of the instrument as optionally
7180 dotted number (where a value &lt; 1.0 means attenuation
7181 and a value > 1.0 means amplification)
7182 </p>
7183 </blockquote>
7184
7185
7186 <p>The mentioned fields above don't have to be in particular order.
7187 </p>
7188 </blockquote><p>
7189
7190 </p>
7191 <p>Example:
7192 </p>
7193 <p>
7194 </p>
7195 <blockquote class="text">
7196 <p>C: "GET MIDI_INSTRUMENT INFO 1 45 120"
7197 </p>
7198 <p>S: "NAME: Drums for Foo Song"
7199 </p>
7200 <p>&nbsp;&nbsp;&nbsp;"ENGINE_NAME: GigEngine"
7201 </p>
7202 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_FILE: /usr/share/joesdrumkit.gig"
7203 </p>
7204 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"
7205 </p>
7206 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NAME: Joe's Drumkit"
7207 </p>
7208 <p>&nbsp;&nbsp;&nbsp;"LOAD_MODE: PERSISTENT"
7209 </p>
7210 <p>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"
7211 </p>
7212 <p>&nbsp;&nbsp;&nbsp;"."
7213 </p>
7214 </blockquote><p>
7215
7216 </p>
7217 <a name="CLEAR MIDI_INSTRUMENTS"></a><br /><hr />
7218 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7219 <a name="rfc.section.6.7.12"></a><h3>6.7.12.&nbsp;
7220 Clear MIDI instrument map</h3>
7221
7222 <p>The front-end can clear a whole MIDI instrument map, that
7223 is delete all its entries by sending the following command:
7224 </p>
7225 <p>
7226 </p>
7227 <blockquote class="text">
7228 <p>CLEAR MIDI_INSTRUMENTS &lt;map&gt;
7229 </p>
7230 </blockquote><p>
7231
7232 </p>
7233 <p>Where &lt;map&gt; is the numeric ID of the map to clear.
7234 </p>
7235 <p>The front-end can clear all MIDI instrument maps, that
7236 is delete all entries of all maps by sending the following
7237 command:
7238 </p>
7239 <p>
7240 </p>
7241 <blockquote class="text">
7242 <p>CLEAR MIDI_INSTRUMENTS ALL
7243 </p>
7244 </blockquote><p>
7245
7246 </p>
7247 <p>The command "CLEAR MIDI_INSTRUMENTS ALL" does not delete the
7248 maps, only their entries, thus the map's settings like
7249 custom name will be preservevd.
7250 </p>
7251 <p>Possible Answers:
7252 </p>
7253 <p>
7254 </p>
7255 <blockquote class="text">
7256 <p>"OK" -
7257 </p>
7258 <blockquote class="text">
7259 <p>always
7260 </p>
7261 </blockquote>
7262
7263
7264 </blockquote><p>
7265
7266 </p>
7267 <p>Examples:
7268 </p>
7269 <p>
7270 </p>
7271 <blockquote class="text">
7272 <p>C: "CLEAR MIDI_INSTRUMENTS 0"
7273 </p>
7274 <p>S: "OK"
7275 </p>
7276 </blockquote><p>
7277
7278 </p>
7279 <p>
7280 </p>
7281 <blockquote class="text">
7282 <p>C: "CLEAR MIDI_INSTRUMENTS ALL"
7283 </p>
7284 <p>S: "OK"
7285 </p>
7286 </blockquote><p>
7287
7288 </p>
7289 <a name="Managing Instruments Database"></a><br /><hr />
7290 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7291 <a name="rfc.section.6.8"></a><h3>6.8.&nbsp;
7292 Managing Instruments Database</h3>
7293
7294 <p>The following commands describe how to use and manage
7295 the instruments database.
7296 </p>
7297 <p>Notice:
7298 </p>
7299 <p>
7300 </p>
7301 <blockquote class="text">
7302 <p>All command arguments representing a path or
7303 instrument/directory name support escape sequences as described in chapter
7304 "<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>".
7305
7306 </p>
7307 <p>All occurrences of a forward slash in instrument and directory
7308 names are escaped with its hex (\x2f) or octal (\057) escape sequence.
7309
7310 </p>
7311 </blockquote><p>
7312
7313 </p>
7314 <a name="ADD DB_INSTRUMENT_DIRECTORY"></a><br /><hr />
7315 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7316 <a name="rfc.section.6.8.1"></a><h3>6.8.1.&nbsp;
7317 Creating a new instrument directory</h3>
7318
7319 <p>The front-end can add a new instrument directory to the
7320 instruments database by sending the following command:
7321 </p>
7322 <p>
7323 </p>
7324 <blockquote class="text">
7325 <p>ADD DB_INSTRUMENT_DIRECTORY &lt;dir&gt;
7326 </p>
7327 </blockquote><p>
7328
7329 </p>
7330 <p>Where &lt;dir&gt; is the absolute path name of the directory
7331 to be created (encapsulated into apostrophes).
7332 </p>
7333 <p>Possible Answers:
7334 </p>
7335 <p>
7336 </p>
7337 <blockquote class="text">
7338 <p>"OK" -
7339 </p>
7340 <blockquote class="text">
7341 <p>on success
7342 </p>
7343 </blockquote>
7344
7345
7346 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7347 </p>
7348 <blockquote class="text">
7349 <p>when the directory could not be created, which
7350 can happen if the directory already exists or the
7351 name contains not allowed symbols
7352 </p>
7353 </blockquote>
7354
7355
7356 </blockquote><p>
7357
7358 </p>
7359 <p>Examples:
7360 </p>
7361 <p>
7362 </p>
7363 <blockquote class="text">
7364 <p>C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'"
7365 </p>
7366 <p>S: "OK"
7367 </p>
7368 </blockquote><p>
7369
7370 </p>
7371 <a name="REMOVE DB_INSTRUMENT_DIRECTORY"></a><br /><hr />
7372 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7373 <a name="rfc.section.6.8.2"></a><h3>6.8.2.&nbsp;
7374 Deleting an instrument directory</h3>
7375
7376 <p>The front-end can delete a particular instrument directory
7377 from the instruments database by sending the following command:
7378 </p>
7379 <p>
7380 </p>
7381 <blockquote class="text">
7382 <p>REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] &lt;dir&gt;
7383 </p>
7384 </blockquote><p>
7385
7386 </p>
7387 <p>Where &lt;dir&gt; is the absolute path name of the directory
7388 to delete. The optional FORCE argument can be used to
7389 force the deletion of a non-empty directory and all its content.
7390 </p>
7391 <p>Possible Answers:
7392 </p>
7393 <p>
7394 </p>
7395 <blockquote class="text">
7396 <p>"OK" -
7397 </p>
7398 <blockquote class="text">
7399 <p>if the directory is deleted successfully
7400 </p>
7401 </blockquote>
7402
7403
7404 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7405 </p>
7406 <blockquote class="text">
7407 <p>if the given directory does not exist, or
7408 if trying to delete a non-empty directory,
7409 without using the FORCE argument.
7410 </p>
7411 </blockquote>
7412
7413
7414 </blockquote><p>
7415
7416 </p>
7417 <p>Examples:
7418 </p>
7419 <p>
7420 </p>
7421 <blockquote class="text">
7422 <p>C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'"
7423 </p>
7424 <p>S: "OK"
7425 </p>
7426 </blockquote><p>
7427
7428 </p>
7429 <a name="GET DB_INSTRUMENT_DIRECTORIES"></a><br /><hr />
7430 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7431 <a name="rfc.section.6.8.3"></a><h3>6.8.3.&nbsp;
7432 Getting amount of instrument directories</h3>
7433
7434 <p>The front-end can retrieve the current amount of
7435 directories in a specific directory by sending the following command:
7436 </p>
7437 <p>
7438 </p>
7439 <blockquote class="text">
7440 <p>GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;
7441 </p>
7442 </blockquote><p>
7443
7444 </p>
7445 <p>Where &lt;dir&gt; should be replaced by the absolute path
7446 name of the directory. If RECURSIVE is specified, the number of
7447 all directories, including those located in subdirectories of the
7448 specified directory, will be returned.
7449 </p>
7450 <p>Possible Answers:
7451 </p>
7452 <p>
7453 </p>
7454 <blockquote class="text">
7455 <p>The current number of instrument directories
7456 in the specified directory.
7457 </p>
7458 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7459 </p>
7460 <blockquote class="text">
7461 <p>if the given directory does not exist.
7462 </p>
7463 </blockquote>
7464
7465
7466 </blockquote><p>
7467
7468 </p>
7469 <p>Example:
7470 </p>
7471 <p>
7472 </p>
7473 <blockquote class="text">
7474 <p>C: "GET DB_INSTRUMENT_DIRECTORIES '/'"
7475 </p>
7476 <p>S: "2"
7477 </p>
7478 </blockquote><p>
7479
7480 </p>
7481 <a name="LIST DB_INSTRUMENT_DIRECTORIES"></a><br /><hr />
7482 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7483 <a name="rfc.section.6.8.4"></a><h3>6.8.4.&nbsp;
7484 Listing all directories in specific directory</h3>
7485
7486 <p>The front-end can retrieve the current list of directories
7487 in specific directory by sending the following command:
7488 </p>
7489 <p>
7490 </p>
7491 <blockquote class="text">
7492 <p>LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;
7493 </p>
7494 </blockquote><p>
7495
7496 </p>
7497 <p>Where &lt;dir&gt; should be replaced by the absolute path
7498 name of the directory. If RECURSIVE is specified, the absolute path names
7499 of all directories, including those located in subdirectories of the
7500 specified directory, will be returned.
7501 </p>
7502 <p>Possible Answers:
7503 </p>
7504 <p>
7505 </p>
7506 <blockquote class="text">
7507 <p>A comma separated list of all instrument directories
7508 (encapsulated into apostrophes) in the specified directory.
7509 </p>
7510 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7511 </p>
7512 <blockquote class="text">
7513 <p>if the given directory does not exist.
7514 </p>
7515 </blockquote>
7516
7517
7518 </blockquote><p>
7519
7520 </p>
7521 <p>Example:
7522 </p>
7523 <p>
7524 </p>
7525 <blockquote class="text">
7526 <p>C: "LIST DB_INSTRUMENT_DIRECTORIES '/'"
7527 </p>
7528 <p>S: "'Piano Collection','Percussion Collection'"
7529 </p>
7530 </blockquote><p>
7531
7532 </p>
7533 <p>
7534 </p>
7535 <blockquote class="text">
7536 <p>C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'"
7537 </p>
7538 <p>S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano Collection/Acoustic/New','/Percussion Collection'"
7539 </p>
7540 </blockquote><p>
7541
7542 </p>
7543 <a name="GET DB_INSTRUMENT_DIRECTORY INFO"></a><br /><hr />
7544 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7545 <a name="rfc.section.6.8.5"></a><h3>6.8.5.&nbsp;
7546 Getting instrument directory information</h3>
7547
7548 <p>The front-end can ask for the current settings of an
7549 instrument directory by sending the following command:
7550 </p>
7551 <p>
7552 </p>
7553 <blockquote class="text">
7554 <p>GET DB_INSTRUMENT_DIRECTORY INFO &lt;dir&gt;
7555 </p>
7556 </blockquote><p>
7557
7558 </p>
7559 <p>Where &lt;dir&gt; should be replaced by the absolute path
7560 name of the directory the front-end is interested in.
7561 </p>
7562 <p>Possible Answers:
7563 </p>
7564 <p>
7565 </p>
7566 <blockquote class="text">
7567 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
7568 Each answer line begins with the settings category name
7569 followed by a colon and then a space character &lt;SP&gt; and finally
7570 the info character string to that setting category. At the
7571 moment the following categories are defined:
7572 </p>
7573 <p>
7574 </p>
7575 <blockquote class="text">
7576 <p>DESCRIPTION -
7577 </p>
7578 <blockquote class="text">
7579 <p>A brief description of the directory content.
7580 Note that the character string may contain
7581 <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
7582 </p>
7583 </blockquote>
7584
7585
7586 <p>CREATED -
7587 </p>
7588 <blockquote class="text">
7589 <p>The creation date and time of the directory,
7590 represented in "YYYY-MM-DD HH:MM:SS" format
7591 </p>
7592 </blockquote>
7593
7594
7595 <p>MODIFIED -
7596 </p>
7597 <blockquote class="text">
7598 <p>The date and time of the last modification of the
7599 directory, represented in "YYYY-MM-DD HH:MM:SS" format
7600 </p>
7601 </blockquote>
7602
7603
7604 </blockquote>
7605
7606
7607 </blockquote><p>
7608
7609 </p>
7610 <p>The mentioned fields above don't have to be in particular order.
7611 </p>
7612 <p>Example:
7613 </p>
7614 <p>
7615 </p>
7616 <blockquote class="text">
7617 <p>C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'"
7618 </p>
7619 <p>S: "DESCRIPTION: Piano collection of instruments in GigaSampler format."
7620 </p>
7621 <p>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"
7622 </p>
7623 <p>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"
7624 </p>
7625 <p>&nbsp;&nbsp;&nbsp;"."
7626 </p>
7627 </blockquote><p>
7628
7629 </p>
7630 <a name="SET DB_INSTRUMENT_DIRECTORY NAME"></a><br /><hr />
7631 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7632 <a name="rfc.section.6.8.6"></a><h3>6.8.6.&nbsp;
7633 Renaming an instrument directory</h3>
7634
7635 <p>The front-end can alter the name of a specific
7636 instrument directory by sending the following command:
7637 </p>
7638 <p>
7639 </p>
7640 <blockquote class="text">
7641 <p>SET DB_INSTRUMENT_DIRECTORY NAME &lt;dir&gt; &lt;name&gt;
7642 </p>
7643 </blockquote><p>
7644
7645 </p>
7646 <p>Where &lt;dir&gt; is the absolute path name of the directory and
7647 &lt;name&gt; is the new name for that directory.
7648 </p>
7649 <p>Possible Answers:
7650 </p>
7651 <p>
7652 </p>
7653 <blockquote class="text">
7654 <p>"OK" -
7655 </p>
7656 <blockquote class="text">
7657 <p>on success
7658 </p>
7659 </blockquote>
7660
7661
7662 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7663 </p>
7664 <blockquote class="text">
7665 <p>in case the given directory does not exists,
7666 or if a directory with name equal to the new
7667 name already exists.
7668 </p>
7669 </blockquote>
7670
7671
7672 </blockquote><p>
7673
7674 </p>
7675 <p>Example:
7676 </p>
7677 <p>
7678 </p>
7679 <blockquote class="text">
7680 <p>C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic' 'Acoustic'"
7681 </p>
7682 <p>S: "OK"
7683 </p>
7684 </blockquote><p>
7685
7686 </p>
7687 <a name="MOVE DB_INSTRUMENT_DIRECTORY"></a><br /><hr />
7688 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7689 <a name="rfc.section.6.8.7"></a><h3>6.8.7.&nbsp;
7690 Moving an instrument directory</h3>
7691
7692 <p>The front-end can move a specific
7693 instrument directory by sending the following command:
7694 </p>
7695 <p>
7696 </p>
7697 <blockquote class="text">
7698 <p>MOVE DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;
7699 </p>
7700 </blockquote><p>
7701
7702 </p>
7703 <p>Where &lt;dir&gt; is the absolute path name of the directory
7704 to move and &lt;dst&gt; is the location where the directory will
7705 be moved to.
7706 </p>
7707 <p>Possible Answers:
7708 </p>
7709 <p>
7710 </p>
7711 <blockquote class="text">
7712 <p>"OK" -
7713 </p>
7714 <blockquote class="text">
7715 <p>on success
7716 </p>
7717 </blockquote>
7718
7719
7720 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7721 </p>
7722 <blockquote class="text">
7723 <p>in case a given directory does not exists,
7724 or if a directory with name equal to the name
7725 of the specified directory already exists in
7726 the destination directory. Error is also thrown
7727 when trying to move a directory to a subdirectory
7728 of itself.
7729 </p>
7730 </blockquote>
7731
7732
7733 </blockquote><p>
7734
7735 </p>
7736 <p>Example:
7737 </p>
7738 <p>
7739 </p>
7740 <blockquote class="text">
7741 <p>C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/Acoustic'"
7742 </p>
7743 <p>S: "OK"
7744 </p>
7745 </blockquote><p>
7746
7747 </p>
7748 <a name="COPY DB_INSTRUMENT_DIRECTORY"></a><br /><hr />
7749 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7750 <a name="rfc.section.6.8.8"></a><h3>6.8.8.&nbsp;
7751 Copying instrument directories</h3>
7752
7753 <p>The front-end can copy a specific
7754 instrument directory by sending the following command:
7755 </p>
7756 <p>
7757 </p>
7758 <blockquote class="text">
7759 <p>COPY DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;
7760 </p>
7761 </blockquote><p>
7762
7763 </p>
7764 <p>Where &lt;dir&gt; is the absolute path name of the directory
7765 to copy and &lt;dst&gt; is the location where the directory will
7766 be copied to.
7767 </p>
7768 <p>Possible Answers:
7769 </p>
7770 <p>
7771 </p>
7772 <blockquote class="text">
7773 <p>"OK" -
7774 </p>
7775 <blockquote class="text">
7776 <p>on success
7777 </p>
7778 </blockquote>
7779
7780
7781 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7782 </p>
7783 <blockquote class="text">
7784 <p>in case a given directory does not exists,
7785 or if a directory with name equal to the name
7786 of the specified directory already exists in
7787 the destination directory. Error is also thrown
7788 when trying to copy a directory to a subdirectory
7789 of itself.
7790 </p>
7791 </blockquote>
7792
7793
7794 </blockquote><p>
7795
7796 </p>
7797 <p>Example:
7798 </p>
7799 <p>
7800 </p>
7801 <blockquote class="text">
7802 <p>C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic' '/Acoustic/Pianos'"
7803 </p>
7804 <p>S: "OK"
7805 </p>
7806 </blockquote><p>
7807
7808 </p>
7809 <a name="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"></a><br /><hr />
7810 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7811 <a name="rfc.section.6.8.9"></a><h3>6.8.9.&nbsp;
7812 Changing the description of directory</h3>
7813
7814 <p>The front-end can alter the description of a specific
7815 instrument directory by sending the following command:
7816 </p>
7817 <p>
7818 </p>
7819 <blockquote class="text">
7820 <p>SET DB_INSTRUMENT_DIRECTORY DESCRIPTION &lt;dir&gt; &lt;desc&gt;
7821 </p>
7822 </blockquote><p>
7823
7824 </p>
7825 <p>Where &lt;dir&gt; is the absolute path name of the directory and
7826 &lt;desc&gt; is the new description for the directory
7827 (encapsulated into apostrophes, supporting escape sequences as described in chapter
7828 "<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>").
7829 </p>
7830 <p>Possible Answers:
7831 </p>
7832 <p>
7833 </p>
7834 <blockquote class="text">
7835 <p>"OK" -
7836 </p>
7837 <blockquote class="text">
7838 <p>on success
7839 </p>
7840 </blockquote>
7841
7842
7843 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7844 </p>
7845 <blockquote class="text">
7846 <p>in case the given directory does not exists.
7847 </p>
7848 </blockquote>
7849
7850
7851 </blockquote><p>
7852
7853 </p>
7854 <p>Example:
7855 </p>
7856 <p>
7857 </p>
7858 <blockquote class="text">
7859 <p>C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A collection of piano instruments in various format.'"
7860 </p>
7861 <p>S: "OK"
7862 </p>
7863 </blockquote><p>
7864
7865 </p>
7866 <a name="FIND DB_INSTRUMENT_DIRECTORIES"></a><br /><hr />
7867 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7868 <a name="rfc.section.6.8.10"></a><h3>6.8.10.&nbsp;
7869 Finding directories</h3>
7870
7871 <p>The front-end can search for directories
7872 in specific directory by sending the following command:
7873 </p>
7874 <p>
7875 </p>
7876 <blockquote class="text">
7877 <p>FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;
7878 </p>
7879 </blockquote><p>
7880
7881 </p>
7882 <p>Where &lt;dir&gt; should be replaced by the absolute path
7883 name of the directory to search in. If NON_RECURSIVE is specified, the
7884 directories located in subdirectories of the specified directory will not
7885 be searched. &lt;criteria-list&gt; is a list of search criterias
7886 in form of "key1=val1 key2=val2 ...". The following criterias are
7887 allowed:
7888 </p>
7889 <p>
7890
7891 <p>NAME='&lt;search-string&gt;'
7892 </p>
7893 <blockquote class="text">
7894 <p>Restricts the search to directories, which names
7895 satisfy the supplied search string (encapsulated into apostrophes,
7896 supporting escape sequences as described in chapter
7897 "<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>").
7898 </p>
7899 </blockquote><p>
7900
7901 </p>
7902
7903
7904 <p>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
7905 </p>
7906 <blockquote class="text">
7907 <p>Restricts the search to directories, which creation
7908 date satisfies the specified period, where &lt;date-after&gt;
7909 and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
7910 If &lt;date-after&gt; is omitted the search is restricted to
7911 directories created before &lt;date-before&gt;. If
7912 &lt;date-before&gt; is omitted, the search is restricted
7913 to directories created after &lt;date-after&gt;.
7914 </p>
7915 </blockquote><p>
7916
7917 </p>
7918
7919
7920 <p>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
7921 </p>
7922 <blockquote class="text">
7923 <p>Restricts the search to directories, which
7924 date of last modification satisfies the specified period, where
7925 &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
7926 format. If &lt;date-after&gt; is omitted the search is restricted to
7927 directories, which are last modified before &lt;date-before&gt;. If
7928 &lt;date-before&gt; is omitted, the search is restricted to directories,
7929 which are last modified after &lt;date-after&gt;.
7930 </p>
7931 </blockquote><p>
7932
7933 </p>
7934
7935
7936 <p>DESCRIPTION='&lt;search-string&gt;'
7937 </p>
7938 <blockquote class="text">
7939 <p>Restricts the search to directories with description
7940 that satisfies the supplied search string
7941 (encapsulated into apostrophes, supporting escape
7942 sequences as described in chapter
7943 "<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>").
7944 </p>
7945 </blockquote><p>
7946
7947 </p>
7948
7949
7950 <p>Where &lt;search-string&gt; is either a regular expression, or a
7951 word list separated with spaces for OR search and with '+' for AND search.
7952 </p>
7953 <p>Possible Answers:
7954 </p>
7955 <p>
7956 </p>
7957 <blockquote class="text">
7958 <p>A comma separated list with the absolute path names (encapsulated into
7959 apostrophes) of all directories in the specified directory that satisfy
7960 the supplied search criterias.
7961 </p>
7962 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7963 </p>
7964 <blockquote class="text">
7965 <p>if the given directory does not exist.
7966 </p>
7967 </blockquote>
7968
7969
7970 </blockquote><p>
7971
7972 </p>
7973 <p>Example:
7974 </p>
7975 <p>
7976 </p>
7977 <blockquote class="text">
7978 <p>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'"
7979 </p>
7980 <p>S: "'/Piano Collection'"
7981 </p>
7982 </blockquote><p>
7983
7984 </p>
7985 <p>
7986 </p>
7987 <blockquote class="text">
7988 <p>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:30:13'"
7989 </p>
7990 <p>S: "'/Piano Collection','/Percussions'"
7991 </p>
7992 </blockquote><p>
7993
7994 </p>
7995 <a name="ADD DB_INSTRUMENTS"></a><br /><hr />
7996 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7997 <a name="rfc.section.6.8.11"></a><h3>6.8.11.&nbsp;
7998 Adding instruments to the instruments database</h3>
7999
8000 <p>The front-end can add one or more instruments
8001 to the instruments database by sending the following command:
8002 </p>
8003 <p>
8004 </p>
8005 <blockquote class="text">
8006 <p>ADD DB_INSTRUMENTS [NON_MODAL] [&lt;mode&gt;] &lt;db_dir&gt; &lt;file_path&gt; [&lt;instr_index&gt;]
8007 </p>
8008 </blockquote><p>
8009
8010 </p>
8011 <p>Where &lt;db_dir&gt; is the absolute path name of a directory
8012 (encapsulated into apostrophes) in the instruments database in which
8013 only the new instruments (that are not already in the database) will
8014 be added, &lt;file_path&gt; is the absolute path name of a file or
8015 directory in the file system (encapsulated into apostrophes). In case
8016 an instrument file is supplied, only the instruments in the specified
8017 file will be added to the instruments database. If the optional
8018 &lt;instr_index&gt; (the index of the instrument within the given file)
8019 is supplied too, then only the specified instrument will be added.
8020 In case a directory is supplied, the instruments in that directory
8021 will be added. The OPTIONAL &lt;mode&gt; argument is only applied
8022 when a directory is provided as &lt;file_path&gt; and specifies how the
8023 scanning will be done and has exactly the following possibilities:
8024 </p>
8025 <p>
8026 </p>
8027 <blockquote class="text">
8028 <p>"RECURSIVE" -
8029 </p>
8030 <blockquote class="text">
8031 <p>All instruments will be processed, including those
8032 in the subdirectories, and the respective subdirectory
8033 tree structure will be recreated in the instruments
8034 database
8035 </p>
8036 </blockquote>
8037
8038
8039 <p>"NON_RECURSIVE" -
8040 </p>
8041 <blockquote class="text">
8042 <p>Only the instruments in the specified directory
8043 will be added, the instruments in the subdirectories
8044 will not be processed.
8045 </p>
8046 </blockquote>
8047
8048
8049 <p>"FLAT" -
8050 </p>
8051 <blockquote class="text">
8052 <p>All instruments will be processed, including those
8053 in the subdirectories, but the respective subdirectory
8054 structure will not be recreated in the instruments
8055 database. All instruments will be added directly in
8056 the specified database directory.
8057 </p>
8058 </blockquote>
8059
8060
8061 </blockquote><p>
8062
8063 </p>
8064 <p>The difference between regular and NON_MODAL versions of the command
8065 is that the regular command returns when the scanning is finished
8066 while NON_MODAL version returns immediately and a background process is launched.
8067 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>
8068 command can be used to monitor the scanning progress.
8069 </p>
8070 <p>Possible Answers:
8071 </p>
8072 <p>
8073 </p>
8074 <blockquote class="text">
8075 <p>"OK" -
8076 </p>
8077 <blockquote class="text">
8078 <p>on success when NON_MODAL is not supplied
8079 </p>
8080 </blockquote>
8081
8082
8083 <p>"OK[&lt;job-id&gt;]" -
8084 </p>
8085 <blockquote class="text">
8086 <p>on success when NON_MODAL is supplied, where &lt;job-id&gt;
8087 is a numerical ID used to obtain status information about the job progress.
8088 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>
8089
8090 </p>
8091 </blockquote>
8092
8093
8094 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8095 </p>
8096 <blockquote class="text">
8097 <p>if an invalid path is specified.
8098 </p>
8099 </blockquote>
8100
8101
8102 </blockquote><p>
8103
8104 </p>
8105 <p>Examples:
8106 </p>
8107 <p>
8108 </p>
8109 <blockquote class="text">
8110 <p>C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI Bosendorfer 290.gig' 0"
8111 </p>
8112 <p>S: "OK"
8113 </p>
8114 </blockquote><p>
8115
8116 </p>
8117 <a name="REMOVE DB_INSTRUMENT"></a><br /><hr />
8118 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8119 <a name="rfc.section.6.8.12"></a><h3>6.8.12.&nbsp;
8120 Removing an instrument</h3>
8121
8122 <p>The front-end can remove a particular instrument
8123 from the instruments database by sending the following command:
8124 </p>
8125 <p>
8126 </p>
8127 <blockquote class="text">
8128 <p>REMOVE DB_INSTRUMENT &lt;instr_path&gt;
8129 </p>
8130 </blockquote><p>
8131
8132 </p>
8133 <p>Where &lt;instr_path&gt; is the absolute path name
8134 (in the instruments database) of the instrument to remove.
8135 </p>
8136 <p>Possible Answers:
8137 </p>
8138 <p>
8139 </p>
8140 <blockquote class="text">
8141 <p>"OK" -
8142 </p>
8143 <blockquote class="text">
8144 <p>if the instrument is removed successfully
8145 </p>
8146 </blockquote>
8147
8148
8149 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8150 </p>
8151 <blockquote class="text">
8152 <p>if the given path does not exist or
8153 is a directory.
8154 </p>
8155 </blockquote>
8156
8157
8158 </blockquote><p>
8159
8160 </p>
8161 <p>Examples:
8162 </p>
8163 <p>
8164 </p>
8165 <blockquote class="text">
8166 <p>C: "REMOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'"
8167 </p>
8168 <p>S: "OK"
8169 </p>
8170 </blockquote><p>
8171
8172 </p>
8173 <a name="GET DB_INSTRUMENTS"></a><br /><hr />
8174 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8175 <a name="rfc.section.6.8.13"></a><h3>6.8.13.&nbsp;
8176 Getting amount of instruments</h3>
8177
8178 <p>The front-end can retrieve the current amount of
8179 instruments in a specific directory by sending the following command:
8180 </p>
8181 <p>
8182 </p>
8183 <blockquote class="text">
8184 <p>GET DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;
8185 </p>
8186 </blockquote><p>
8187
8188 </p>
8189 <p>Where &lt;dir&gt; should be replaced by the absolute path name
8190 of the directory. If RECURSIVE is specified, the number of all
8191 instruments, including those located in subdirectories of the
8192 specified directory, will be returned.
8193 </p>
8194 <p>Possible Answers:
8195 </p>
8196 <p>
8197 </p>
8198 <blockquote class="text">
8199 <p>The current number of instruments
8200 in the specified directory.
8201 </p>
8202 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8203 </p>
8204 <blockquote class="text">
8205 <p>if the given directory does not exist.
8206 </p>
8207 </blockquote>
8208
8209
8210 </blockquote><p>
8211
8212 </p>
8213 <p>Example:
8214 </p>
8215 <p>
8216 </p>
8217 <blockquote class="text">
8218 <p>C: "GET DB_INSTRUMENTS '/Piano Collection'"
8219 </p>
8220 <p>S: "2"
8221 </p>
8222 </blockquote><p>
8223
8224 </p>
8225 <a name="LIST DB_INSTRUMENTS"></a><br /><hr />
8226 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8227 <a name="rfc.section.6.8.14"></a><h3>6.8.14.&nbsp;
8228 Listing all instruments in specific directory</h3>
8229
8230 <p>The front-end can retrieve the current list of instruments
8231 in specific directory by sending the following command:
8232 </p>
8233 <p>
8234 </p>
8235 <blockquote class="text">
8236 <p>LIST DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;
8237 </p>
8238 </blockquote><p>
8239
8240 </p>
8241 <p>Where &lt;dir&gt; should be replaced by the absolute path
8242 name of the directory. If RECURSIVE is specified, the absolute path
8243 names of all instruments, including those located in subdirectories
8244 of the specified directory, will be returned.
8245 </p>
8246 <p>Possible Answers:
8247 </p>
8248 <p>
8249 </p>
8250 <blockquote class="text">
8251 <p>A comma separated list of all instruments
8252 (encapsulated into apostrophes) in the specified directory.
8253 </p>
8254 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8255 </p>
8256 <blockquote class="text">
8257 <p>if the given directory does not exist.
8258 </p>
8259 </blockquote>
8260
8261
8262 </blockquote><p>
8263
8264 </p>
8265 <p>Example:
8266 </p>
8267 <p>
8268 </p>
8269 <blockquote class="text">
8270 <p>C: "LIST DB_INSTRUMENTS '/Piano Collection'"
8271 </p>
8272 <p>S: "'Bosendorfer 290','Steinway D'"
8273 </p>
8274 </blockquote><p>
8275
8276 </p>
8277 <p>
8278 </p>
8279 <blockquote class="text">
8280 <p>C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'"
8281 </p>
8282 <p>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D','/Piano Collection/Lite/Free Piano'"
8283 </p>
8284 </blockquote><p>
8285
8286 </p>
8287 <a name="GET DB_INSTRUMENT INFO"></a><br /><hr />
8288 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8289 <a name="rfc.section.6.8.15"></a><h3>6.8.15.&nbsp;
8290 Getting instrument information</h3>
8291
8292 <p>The front-end can ask for the current settings of an
8293 instrument by sending the following command:
8294 </p>
8295 <p>
8296 </p>
8297 <blockquote class="text">
8298 <p>GET DB_INSTRUMENT INFO &lt;instr_path&gt;
8299 </p>
8300 </blockquote><p>
8301
8302 </p>
8303 <p>Where &lt;instr_path&gt; should be replaced by the absolute path
8304 name of the instrument the front-end is interested in.
8305 </p>
8306 <p>Possible Answers:
8307 </p>
8308 <p>
8309 </p>
8310 <blockquote class="text">
8311 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
8312 Each answer line begins with the settings category name
8313 followed by a colon and then a space character &lt;SP&gt; and finally
8314 the info character string to that setting category. At the
8315 moment the following categories are defined:
8316 </p>
8317 <p>
8318 </p>
8319 <blockquote class="text">
8320 <p>INSTRUMENT_FILE -
8321 </p>
8322 <blockquote class="text">
8323 <p>File name of the instrument.
8324 Note that the character string may contain
8325 <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
8326 </p>
8327 </blockquote>
8328
8329
8330 <p>INSTRUMENT_NR -
8331 </p>
8332 <blockquote class="text">
8333 <p>Index of the instrument within the file.
8334 </p>
8335 </blockquote>
8336
8337
8338 <p>FORMAT_FAMILY -
8339 </p>
8340 <blockquote class="text">
8341 <p>The format family of the instrument.
8342 </p>
8343 </blockquote>
8344
8345
8346 <p>FORMAT_VERSION -
8347 </p>
8348 <blockquote class="text">
8349 <p>The format version of the instrument.
8350 </p>
8351 </blockquote>
8352
8353
8354 <p>SIZE -
8355 </p>
8356 <blockquote class="text">
8357 <p>The size of the instrument in bytes.
8358 </p>
8359 </blockquote>
8360
8361
8362 <p>CREATED -
8363 </p>
8364 <blockquote class="text">
8365 <p>The date and time when the instrument is added
8366 in the instruments database, represented in
8367 "YYYY-MM-DD HH:MM:SS" format
8368 </p>
8369 </blockquote>
8370
8371
8372 <p>MODIFIED -
8373 </p>
8374 <blockquote class="text">
8375 <p>The date and time of the last modification of the
8376 instrument's database settings, represented in
8377 "YYYY-MM-DD HH:MM:SS" format
8378 </p>
8379 </blockquote>
8380
8381
8382 <p>DESCRIPTION -
8383 </p>
8384 <blockquote class="text">
8385 <p>A brief description of the instrument.
8386 Note that the character string may contain
8387 <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
8388 </p>
8389 </blockquote>
8390
8391
8392 <p>IS_DRUM -
8393 </p>
8394 <blockquote class="text">
8395 <p>either true or false, determines whether the
8396 instrument is a drumkit or a chromatic instrument
8397 </p>
8398 </blockquote>
8399
8400
8401 <p>PRODUCT -
8402 </p>
8403 <blockquote class="text">
8404 <p>The product title of the instrument.
8405 Note that the character string may contain
8406 <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
8407 </p>
8408 </blockquote>
8409
8410
8411 <p>ARTISTS -
8412 </p>
8413 <blockquote class="text">
8414 <p>Lists the artist names.
8415 Note that the character string may contain
8416 <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
8417 </p>
8418 </blockquote>
8419
8420
8421 <p>KEYWORDS -
8422 </p>
8423 <blockquote class="text">
8424 <p>Provides a list of keywords that refer to the instrument.
8425 Keywords are separated with semicolon and blank.
8426 Note that the character string may contain
8427 <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
8428 </p>
8429 </blockquote>
8430
8431
8432 </blockquote>
8433
8434
8435 </blockquote><p>
8436
8437 </p>
8438 <p>The mentioned fields above don't have to be in particular order.
8439 </p>
8440 <p>Example:
8441 </p>
8442 <p>
8443 </p>
8444 <blockquote class="text">
8445 <p>C: "GET DB_INSTRUMENT INFO '/Piano Collection/Bosendorfer 290'"
8446 </p>
8447 <p>S: "INSTRUMENT_FILE: /home/me/gigs/Bosendorfer 290.gig"
8448 </p>
8449 <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"
8450 </p>
8451 <p>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"
8452 </p>
8453 <p>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 2"
8454 </p>
8455 <p>&nbsp;&nbsp;&nbsp;"SIZE: 2050871870"
8456 </p>
8457 <p>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"
8458 </p>
8459 <p>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"
8460 </p>
8461 <p>&nbsp;&nbsp;&nbsp;"DESCRIPTION: "
8462 </p>
8463 <p>&nbsp;&nbsp;&nbsp;"IS_DRUM: false"
8464 </p>
8465 <p>&nbsp;&nbsp;&nbsp;"PRODUCT: GRANDIOSO Bosendorfer 290"
8466 </p>
8467 <p>&nbsp;&nbsp;&nbsp;"ARTISTS: Post Musical Instruments"
8468 </p>
8469 <p>&nbsp;&nbsp;&nbsp;"KEYWORDS: Bosendorfer"
8470 </p>
8471 <p>&nbsp;&nbsp;&nbsp;"."
8472 </p>
8473 </blockquote><p>
8474
8475 </p>
8476 <a name="SET DB_INSTRUMENT NAME"></a><br /><hr />
8477 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8478 <a name="rfc.section.6.8.16"></a><h3>6.8.16.&nbsp;
8479 Renaming an instrument</h3>
8480
8481 <p>The front-end can alter the name of a specific
8482 instrument by sending the following command:
8483 </p>
8484 <p>
8485 </p>
8486 <blockquote class="text">
8487 <p>SET DB_INSTRUMENT NAME &lt;instr&gt; &lt;name&gt;
8488 </p>
8489 </blockquote><p>
8490
8491 </p>
8492 <p>Where &lt;instr&gt; is the absolute path name of the instrument and
8493 &lt;name&gt; is the new name for that instrument.
8494 </p>
8495 <p>Possible Answers:
8496 </p>
8497 <p>
8498 </p>
8499 <blockquote class="text">
8500 <p>"OK" -
8501 </p>
8502 <blockquote class="text">
8503 <p>on success
8504 </p>
8505 </blockquote>
8506
8507
8508 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8509 </p>
8510 <blockquote class="text">
8511 <p>in case the given instrument does not exists,
8512 or if an instrument with name equal to the new
8513 name already exists.
8514 </p>
8515 </blockquote>
8516
8517
8518 </blockquote><p>
8519
8520 </p>
8521 <p>Example:
8522 </p>
8523 <p>
8524 </p>
8525 <blockquote class="text">
8526 <p>C: "SET DB_INSTRUMENT NAME '/Piano Collection/Bosendorfer' 'Bosendorfer 290'"
8527 </p>
8528 <p>S: "OK"
8529 </p>
8530 </blockquote><p>
8531
8532 </p>
8533 <a name="MOVE DB_INSTRUMENT"></a><br /><hr />
8534 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8535 <a name="rfc.section.6.8.17"></a><h3>6.8.17.&nbsp;
8536 Moving an instrument</h3>
8537
8538 <p>The front-end can move a specific instrument to another directory by
8539 sending the following command:
8540 </p>
8541 <p>
8542 </p>
8543 <blockquote class="text">
8544 <p>MOVE DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;
8545 </p>
8546 </blockquote><p>
8547
8548 </p>
8549 <p>Where &lt;instr&gt; is the absolute path name of the instrument
8550 to move and &lt;dst&gt; is the directory where the instrument will
8551 be moved to.
8552 </p>
8553 <p>Possible Answers:
8554 </p>
8555 <p>
8556 </p>
8557 <blockquote class="text">
8558 <p>"OK" -
8559 </p>
8560 <blockquote class="text">
8561 <p>on success
8562 </p>
8563 </blockquote>
8564
8565
8566 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8567 </p>
8568 <blockquote class="text">
8569 <p>in case the given instrument does not exists,
8570 or if an instrument with name equal to the name of the
8571 specified instrument already exists in the destination
8572 directory.
8573 </p>
8574 </blockquote>
8575
8576
8577 </blockquote><p>
8578
8579 </p>
8580 <p>Example:
8581 </p>
8582 <p>
8583 </p>
8584 <blockquote class="text">
8585 <p>C: "MOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Piano Collection/Acoustic'"
8586 </p>
8587 <p>S: "OK"
8588 </p>
8589 </blockquote><p>
8590
8591 </p>
8592 <a name="COPY DB_INSTRUMENT"></a><br /><hr />
8593 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8594 <a name="rfc.section.6.8.18"></a><h3>6.8.18.&nbsp;
8595 Copying instruments</h3>
8596
8597 <p>The front-end can copy a specific instrument to another directory by
8598 sending the following command:
8599 </p>
8600 <p>
8601 </p>
8602 <blockquote class="text">
8603 <p>COPY DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;
8604 </p>
8605 </blockquote><p>
8606
8607 </p>
8608 <p>Where &lt;instr&gt; is the absolute path name of the instrument
8609 to copy and &lt;dst&gt; is the directory where the instrument will
8610 be copied to.
8611 </p>
8612 <p>Possible Answers:
8613 </p>
8614 <p>
8615 </p>
8616 <blockquote class="text">
8617 <p>"OK" -
8618 </p>
8619 <blockquote class="text">
8620 <p>on success
8621 </p>
8622 </blockquote>
8623
8624
8625 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8626 </p>
8627 <blockquote class="text">
8628 <p>in case the given instrument does not exists,
8629 or if an instrument with name equal to the name of the
8630 specified instrument already exists in the destination
8631 directory.
8632 </p>
8633 </blockquote>
8634
8635
8636 </blockquote><p>
8637
8638 </p>
8639 <p>Example:
8640 </p>
8641 <p>
8642 </p>
8643 <blockquote class="text">
8644 <p>C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Acoustic/Pianos/'"
8645 </p>
8646 <p>S: "OK"
8647 </p>
8648 </blockquote><p>
8649
8650 </p>
8651 <a name="SET DB_INSTRUMENT DESCRIPTION"></a><br /><hr />
8652 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8653 <a name="rfc.section.6.8.19"></a><h3>6.8.19.&nbsp;
8654 Changing the description of instrument</h3>
8655
8656 <p>The front-end can alter the description of a specific
8657 instrument by sending the following command:
8658 </p>
8659 <p>
8660 </p>
8661 <blockquote class="text">
8662 <p>SET DB_INSTRUMENT DESCRIPTION &lt;instr&gt; &lt;desc&gt;
8663 </p>
8664 </blockquote><p>
8665
8666 </p>
8667 <p>Where &lt;instr&gt; is the absolute path name of the instrument and
8668 &lt;desc&gt; is the new description for the instrument
8669 (encapsulated into apostrophes, supporting escape sequences as described in chapter
8670 "<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>").
8671 </p>
8672 <p>Possible Answers:
8673 </p>
8674 <p>
8675 </p>
8676 <blockquote class="text">
8677 <p>"OK" -
8678 </p>
8679 <blockquote class="text">
8680 <p>on success
8681 </p>
8682 </blockquote>
8683
8684
8685 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8686 </p>
8687 <blockquote class="text">
8688 <p>in case the given instrument does not exists.
8689 </p>
8690 </blockquote>
8691
8692
8693 </blockquote><p>
8694
8695 </p>
8696 <p>Example:
8697 </p>
8698 <p>
8699 </p>
8700 <blockquote class="text">
8701 <p>C: "SET DB_INSTRUMENT DESCRIPTION '/Piano Collection/Acoustic/Bosendorfer 290' 'No comment :)'"
8702 </p>
8703 <p>S: "OK"
8704 </p>
8705 </blockquote><p>
8706
8707 </p>
8708 <a name="FIND DB_INSTRUMENTS"></a><br /><hr />
8709 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8710 <a name="rfc.section.6.8.20"></a><h3>6.8.20.&nbsp;
8711 Finding instruments</h3>
8712
8713 <p>The front-end can search for instruments
8714 in specific directory by sending the following command:
8715 </p>
8716 <p>
8717 </p>
8718 <blockquote class="text">
8719 <p>FIND DB_INSTRUMENTS [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;
8720 </p>
8721 </blockquote><p>
8722
8723 </p>
8724 <p>Where &lt;dir&gt; should be replaced by the absolute path
8725 name of the directory to search in. If NON_RECURSIVE is specified, the
8726 directories located in subdirectories of the specified directory will not
8727 be searched. &lt;criteria-list&gt; is a list of search criterias
8728 in form of "key1=val1 key2=val2 ...". The following criterias are
8729 allowed:
8730 </p>
8731 <p>
8732
8733 <p>NAME='&lt;search-string&gt;'
8734 </p>
8735 <blockquote class="text">
8736 <p>Restricts the search to instruments, which names
8737 satisfy the supplied search string (encapsulated into apostrophes,
8738 supporting escape sequences as described in chapter
8739 "<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>").
8740 </p>
8741 </blockquote><p>
8742
8743 </p>
8744
8745
8746 <p>SIZE=[&lt;min&gt;]..[&lt;max&gt;]
8747 </p>
8748 <blockquote class="text">
8749 <p>Restricts the search to instruments, which
8750 size is in the specified range. If &lt;min&gt; is omitted,
8751 the search results are restricted to instruments with size less then
8752 or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the
8753 search is restricted to instruments with size greater then
8754 or equal to &lt;min&gt;.
8755 </p>
8756 </blockquote><p>
8757
8758 </p>
8759
8760
8761 <p>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
8762 </p>
8763 <blockquote class="text">
8764 <p>Restricts the search to instruments, which creation
8765 date satisfies the specified period, where &lt;date-after&gt;
8766 and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
8767 If &lt;date-after&gt; is omitted the search is restricted to
8768 instruments created before &lt;date-before&gt;. If
8769 &lt;date-before&gt; is omitted, the search is restricted
8770 to instruments created after &lt;date-after&gt;.
8771 </p>
8772 </blockquote><p>
8773
8774 </p>
8775
8776
8777 <p>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
8778 </p>
8779 <blockquote class="text">
8780 <p>Restricts the search to instruments, which
8781 date of last modification satisfies the specified period, where
8782 &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
8783 format. If &lt;date-after&gt; is omitted the search is restricted to
8784 instruments, which are last modified before &lt;date-before&gt;. If
8785 &lt;date-before&gt; is omitted, the search is restricted to instruments,
8786 which are last modified after &lt;date-after&gt;.
8787 </p>
8788 </blockquote><p>
8789
8790 </p>
8791
8792
8793 <p>DESCRIPTION='&lt;search-string&gt;'
8794 </p>
8795 <blockquote class="text">
8796 <p>Restricts the search to instruments with description
8797 that satisfies the supplied search string (encapsulated into apostrophes,
8798 supporting escape sequences as described in chapter
8799 "<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>").
8800 </p>
8801 </blockquote><p>
8802
8803 </p>
8804
8805
8806 <p>PRODUCT='&lt;search-string&gt;'
8807 </p>
8808 <blockquote class="text">
8809 <p>Restricts the search to instruments with product info
8810 that satisfies the supplied search string (encapsulated into apostrophes,
8811 supporting escape sequences as described in chapter
8812 "<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>").
8813 </p>
8814 </blockquote><p>
8815
8816 </p>
8817
8818
8819 <p>ARTISTS='&lt;search-string&gt;'
8820 </p>
8821 <blockquote class="text">
8822 <p>Restricts the search to instruments with artists info
8823 that satisfies the supplied search string (encapsulated into apostrophes,
8824 supporting escape sequences as described in chapter
8825 "<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>").
8826 </p>
8827 </blockquote><p>
8828
8829 </p>
8830
8831
8832 <p>KEYWORDS='&lt;search-string&gt;'
8833 </p>
8834 <blockquote class="text">
8835 <p>Restricts the search to instruments with keyword list
8836 that satisfies the supplied search string (encapsulated into apostrophes,
8837 supporting escape sequences as described in chapter
8838 "<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>").
8839 </p>
8840 </blockquote><p>
8841
8842 </p>
8843
8844
8845 <p>IS_DRUM=true | false
8846 </p>
8847 <blockquote class="text">
8848 <p>Either true or false. Restricts the search to
8849 drum kits or chromatic instruments.
8850 </p>
8851 </blockquote><p>
8852
8853 </p>
8854
8855
8856 <p>FORMAT_FAMILIES='&lt;format-list&gt;'
8857 </p>
8858 <blockquote class="text">
8859 <p>Restricts the search to instruments of the supplied format families,
8860 where &lt;format-list&gt; is a comma separated list of format families.
8861 </p>
8862 </blockquote><p>
8863
8864 </p>
8865
8866
8867 <p>Where &lt;search-string&gt; is either a regular expression, or a
8868 word list separated with spaces for OR search and with '+' for AND search.
8869 </p>
8870 <p>Possible Answers:
8871 </p>
8872 <p>
8873 </p>
8874 <blockquote class="text">
8875 <p>A comma separated list with the absolute path names (encapsulated into
8876 apostrophes) of all instruments in the specified directory that satisfy
8877 the supplied search criterias.
8878 </p>
8879 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8880 </p>
8881 <blockquote class="text">
8882 <p>if the given directory does not exist.
8883 </p>
8884 </blockquote>
8885
8886
8887 </blockquote><p>
8888
8889 </p>
8890 <p>Example:
8891 </p>
8892 <p>
8893 </p>
8894 <blockquote class="text">
8895 <p>C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+290'"
8896 </p>
8897 <p>S: "'/Piano Collection/Bosendorfer 290'"
8898 </p>
8899 </blockquote><p>
8900
8901 </p>
8902 <p>
8903 </p>
8904 <blockquote class="text">
8905 <p>C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01 09:30:13..'"
8906 </p>
8907 <p>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D'"
8908 </p>
8909 </blockquote><p>
8910
8911 </p>
8912 <a name="GET DB_INSTRUMENTS_JOB INFO"></a><br /><hr />
8913 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8914 <a name="rfc.section.6.8.21"></a><h3>6.8.21.&nbsp;
8915 Getting job status information</h3>
8916
8917 <p>The front-end can ask for the current status of a
8918 particular database instruments job by sending the following command:
8919 </p>
8920 <p>
8921 </p>
8922 <blockquote class="text">
8923 <p>GET DB_INSTRUMENTS_JOB INFO &lt;job-id&gt;
8924 </p>
8925 </blockquote><p>
8926
8927 </p>
8928 <p>Where &lt;job-id&gt; should be replaced by the numerical ID
8929 of the job the front-end is interested in.
8930 </p>
8931 <p>Possible Answers:
8932 </p>
8933 <p>
8934 </p>
8935 <blockquote class="text">
8936 <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
8937 Each answer line begins with the settings category name
8938 followed by a colon and then a space character &lt;SP&gt; and finally
8939 the info character string to that setting category. At the
8940 moment the following categories are defined:
8941 </p>
8942 <p>
8943 </p>
8944 <blockquote class="text">
8945 <p>FILES_TOTAL -
8946 </p>
8947 <blockquote class="text">
8948 <p>The total number of files scheduled for scanning
8949 </p>
8950 </blockquote>
8951
8952
8953 <p>FILES_SCANNED -
8954 </p>
8955 <blockquote class="text">
8956 <p>The current number of scanned files
8957 </p>
8958 </blockquote>
8959
8960
8961 <p>SCANNING -
8962 </p>
8963 <blockquote class="text">
8964 <p>The absolute path name of the file which is currently
8965 being scanned
8966 </p>
8967 </blockquote>
8968
8969
8970 <p>STATUS -
8971 </p>
8972 <blockquote class="text">
8973 <p>An integer value between 0 and 100 indicating the
8974 scanning progress percentage of the file which is
8975 currently being scanned
8976 </p>
8977 </blockquote>
8978
8979
8980 </blockquote>
8981
8982
8983 </blockquote><p>
8984
8985 </p>
8986 <p>The mentioned fields above don't have to be in particular order.
8987 </p>
8988 <p>Example:
8989 </p>
8990 <p>
8991 </p>
8992 <blockquote class="text">
8993 <p>C: "GET DB_INSTRUMENTS_JOB INFO 2"
8994 </p>
8995 <p>S: "FILES_TOTAL: 12"
8996 </p>
8997 <p>&nbsp;&nbsp;&nbsp;"FILES_SCANNED: 7"
8998 </p>
8999 <p>&nbsp;&nbsp;&nbsp;"SCANNING: /home/me/gigs/Bosendorfer 290.gig"
9000 </p>
9001 <p>&nbsp;&nbsp;&nbsp;"STATUS: 42"
9002 </p>
9003 <p>&nbsp;&nbsp;&nbsp;"."
9004 </p>
9005 </blockquote><p>
9006
9007 </p>
9008 <a name="FORMAT INSTRUMENTS_DB"></a><br /><hr />
9009 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9010 <a name="rfc.section.6.8.22"></a><h3>6.8.22.&nbsp;
9011 Formatting the instruments database</h3>
9012
9013 <p>The front-end can remove all instruments and directories and re-create
9014 the instruments database structure (e.g., in case of a database corruption)
9015 by sending the following command:
9016 </p>
9017 <p>
9018 </p>
9019 <blockquote class="text">
9020 <p>FORMAT INSTRUMENTS_DB
9021 </p>
9022 </blockquote><p>
9023
9024 </p>
9025 <p>Possible Answers:
9026 </p>
9027 <p>
9028 </p>
9029 <blockquote class="text">
9030 <p>"OK" -
9031 </p>
9032 <blockquote class="text">
9033 <p>on success
9034 </p>
9035 </blockquote>
9036
9037
9038 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
9039 </p>
9040 <blockquote class="text">
9041 <p>If the formatting of the instruments database
9042 failed.
9043 </p>
9044 </blockquote>
9045
9046
9047 </blockquote><p>
9048
9049 </p>
9050 <a name="editing_instruments"></a><br /><hr />
9051 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9052 <a name="rfc.section.6.9"></a><h3>6.9.&nbsp;
9053 Editing Instruments</h3>
9054
9055 <p>The sampler allows to edit instruments while playing with the
9056 sampler by spawning an external (3rd party) instrument editor
9057 application for a given instrument. The 3rd party instrument
9058 editor applications have to place a respective plugin DLL file
9059 into the sampler's plugins directory. The sampler will
9060 automatically try to load all plugin DLLs in that directory on
9061 startup and only on startup!
9062 </p>
9063 <p>At the moment there is only one command for this feature set,
9064 but this will most probably change in future.
9065 </p>
9066 <a name="EDIT INSTRUMENT"></a><br /><hr />
9067 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9068 <a name="rfc.section.6.9.1"></a><h3>6.9.1.&nbsp;
9069 Opening an appropriate instrument editor application</h3>
9070
9071 <p>The front-end can request to open an appropriate instrument
9072 editor application by sending the following command:
9073 </p>
9074 <p>
9075 </p>
9076 <blockquote class="text">
9077 <p>EDIT INSTRUMENT &lt;sampler-channel&gt;
9078 </p>
9079 </blockquote><p>
9080
9081 </p>
9082 <p>Where &lt;sampler-channel&gt; should be replaced by the
9083 number of the sampler channel as given by the
9084 <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
9085 or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a>
9086 command.
9087 </p>
9088 <p>The sampler will try to ask all registered instrument
9089 editors (or to be more specific: their sampler plugins)
9090 whether they are capable to handle the instrument on the
9091 given sampler channel. The sampler will simply use the first
9092 instrument editor application which replied with a positive
9093 answer and spawn that instrument editor application within
9094 the sampler's process and provide that application access
9095 to the instrument's data structures, so both applications
9096 can share and access the same instruments data at the same
9097 time, thus allowing to immediately hear changes with the
9098 sampler made by the instrument editor.
9099 </p>
9100 <p>Note: consequently instrument editors are always spawned
9101 locally on the same machine where the sampler is running
9102 on!
9103 </p>
9104 <p>Possible Answers:
9105 </p>
9106 <p>
9107 </p>
9108 <blockquote class="text">
9109 <p>"OK" -
9110 </p>
9111 <blockquote class="text">
9112 <p>when an appropriate instrument editor was
9113 launched
9114 </p>
9115 </blockquote>
9116
9117
9118 <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
9119 </p>
9120 <blockquote class="text">
9121 <p>when an appropriate instrument editor was
9122 launched, but there are noteworthy issues
9123 </p>
9124 </blockquote>
9125
9126
9127 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
9128 </p>
9129 <blockquote class="text">
9130 <p>when an appropriate instrument editor
9131 could not be launched
9132 </p>
9133 </blockquote>
9134
9135
9136 </blockquote><p>
9137
9138 </p>
9139 <p>Examples:
9140 </p>
9141 <p>
9142 </p>
9143 <blockquote class="text">
9144 <p>C: "EDIT INSTRUMENT 0"
9145 </p>
9146 <p>S: "OK"
9147 </p>
9148 </blockquote><p>
9149
9150 </p>
9151 <a name="command_syntax"></a><br /><hr />
9152 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9153 <a name="rfc.section.7"></a><h3>7.&nbsp;
9154 Command Syntax</h3>
9155
9156 <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>
9157 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>)
9158 where applicable.
9159
9160 </p>
9161 <p>input =
9162 </p>
9163 <blockquote class="text">
9164 <p>line LF
9165
9166 </p>
9167 <p>/ line CR LF
9168
9169 </p>
9170 </blockquote><p>
9171
9172 </p>
9173 <p>line =
9174 </p>
9175 <blockquote class="text">
9176 <p>/* epsilon (empty line ignored) */
9177
9178 </p>
9179 <p>/ comment
9180
9181 </p>
9182 <p>/ command
9183
9184 </p>
9185 <p>/ error
9186
9187 </p>
9188 </blockquote><p>
9189
9190 </p>
9191 <p>comment =
9192 </p>
9193 <blockquote class="text">
9194 <p>'#'
9195
9196 </p>
9197 <p>/ comment '#'
9198
9199 </p>
9200 <p>/ comment SP
9201
9202 </p>
9203 <p>/ comment number
9204
9205 </p>
9206 <p>/ comment string
9207
9208 </p>
9209 </blockquote><p>
9210
9211 </p>
9212 <p>command =
9213 </p>
9214 <blockquote class="text">
9215 <p>ADD SP add_instruction
9216
9217 </p>
9218 <p>/ MAP SP map_instruction
9219
9220 </p>
9221 <p>/ UNMAP SP unmap_instruction
9222
9223 </p>
9224 <p>/ GET SP get_instruction
9225
9226 </p>
9227 <p>/ CREATE SP create_instruction
9228
9229 </p>
9230 <p>/ DESTROY SP destroy_instruction
9231
9232 </p>
9233 <p>/ LIST SP list_instruction
9234
9235 </p>
9236 <p>/ LOAD SP load_instruction
9237
9238 </p>
9239 <p>/ REMOVE SP remove_instruction
9240
9241 </p>
9242 <p>/ SET SP set_instruction
9243
9244 </p>
9245 <p>/ SUBSCRIBE SP subscribe_event
9246
9247 </p>
9248 <p>/ UNSUBSCRIBE SP unsubscribe_event
9249
9250 </p>
9251 <p>/ RESET SP reset_instruction
9252
9253 </p>
9254 <p>/ CLEAR SP clear_instruction
9255
9256 </p>
9257 <p>/ FIND SP find_instruction
9258
9259 </p>
9260 <p>/ MOVE SP move_instruction
9261
9262 </p>
9263 <p>/ COPY SP copy_instruction
9264
9265 </p>
9266 <p>/ EDIT SP edit_instruction
9267
9268 </p>
9269 <p>/ FORMAT SP format_instruction
9270
9271 </p>
9272 <p>/ RESET
9273
9274 </p>
9275 <p>/ QUIT
9276
9277 </p>
9278 </blockquote><p>
9279
9280 </p>
9281 <p>add_instruction =
9282 </p>
9283 <blockquote class="text">
9284 <p>CHANNEL
9285
9286 </p>
9287 <p>/ DB_INSTRUMENT_DIRECTORY SP db_path
9288
9289 </p>
9290 <p>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename
9291
9292 </p>
9293 <p>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename
9294
9295 </p>
9296 <p>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
9297
9298 </p>
9299 <p>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index
9300
9301 </p>
9302 <p>/ DB_INSTRUMENTS SP db_path SP filename
9303
9304 </p>
9305 <p>/ DB_INSTRUMENTS SP db_path SP filename SP instrument_index
9306
9307 </p>
9308 <p>/ MIDI_INSTRUMENT_MAP
9309
9310 </p>
9311 <p>/ MIDI_INSTRUMENT_MAP SP map_name
9312
9313 </p>
9314 </blockquote><p>
9315
9316 </p>
9317 <p>subscribe_event =
9318 </p>
9319 <blockquote class="text">
9320 <p>AUDIO_OUTPUT_DEVICE_COUNT
9321
9322 </p>
9323 <p>/ AUDIO_OUTPUT_DEVICE_INFO
9324
9325 </p>
9326 <p>/ MIDI_INPUT_DEVICE_COUNT
9327
9328 </p>
9329 <p>/ MIDI_INPUT_DEVICE_INFO
9330
9331 </p>
9332 <p>/ CHANNEL_COUNT
9333
9334 </p>
9335 <p>/ VOICE_COUNT
9336
9337 </p>
9338 <p>/ STREAM_COUNT
9339
9340 </p>
9341 <p>/ BUFFER_FILL
9342
9343 </p>
9344 <p>/ CHANNEL_INFO
9345
9346 </p>
9347 <p>/ FX_SEND_COUNT
9348
9349 </p>
9350 <p>/ FX_SEND_INFO
9351
9352 </p>
9353 <p>/ MIDI_INSTRUMENT_MAP_COUNT
9354
9355 </p>
9356 <p>/ MIDI_INSTRUMENT_MAP_INFO
9357
9358 </p>
9359 <p>/ MIDI_INSTRUMENT_COUNT
9360
9361 </p>
9362 <p>/ MIDI_INSTRUMENT_INFO
9363
9364 </p>
9365 <p>/ DB_INSTRUMENT_DIRECTORY_COUNT
9366
9367 </p>
9368 <p>/ DB_INSTRUMENT_DIRECTORY_INFO
9369
9370 </p>
9371 <p>/ DB_INSTRUMENT_COUNT
9372
9373 </p>
9374 <p>/ DB_INSTRUMENT_INFO
9375
9376 </p>
9377 <p>/ DB_INSTRUMENTS_JOB_INFO
9378
9379 </p>
9380 <p>/ MISCELLANEOUS
9381
9382 </p>
9383 <p>/ TOTAL_VOICE_COUNT
9384
9385 </p>
9386 <p>/ GLOBAL_INFO
9387
9388 </p>
9389 </blockquote><p>
9390
9391 </p>
9392 <p>unsubscribe_event =
9393 </p>
9394 <blockquote class="text">
9395 <p>AUDIO_OUTPUT_DEVICE_COUNT
9396
9397 </p>
9398 <p>/ AUDIO_OUTPUT_DEVICE_INFO
9399
9400 </p>
9401 <p>/ MIDI_INPUT_DEVICE_COUNT
9402
9403 </p>
9404 <p>/ MIDI_INPUT_DEVICE_INFO
9405
9406 </p>
9407 <p>/ CHANNEL_COUNT
9408
9409 </p>
9410 <p>/ VOICE_COUNT
9411
9412 </p>
9413 <p>/ STREAM_COUNT
9414
9415 </p>
9416 <p>/ BUFFER_FILL
9417
9418 </p>
9419 <p>/ CHANNEL_INFO
9420
9421 </p>
9422 <p>/ FX_SEND_COUNT
9423
9424 </p>
9425 <p>/ FX_SEND_INFO
9426
9427 </p>
9428 <p>/ MIDI_INSTRUMENT_MAP_COUNT
9429
9430 </p>
9431 <p>/ MIDI_INSTRUMENT_MAP_INFO
9432
9433 </p>
9434 <p>/ MIDI_INSTRUMENT_COUNT
9435
9436 </p>
9437 <p>/ MIDI_INSTRUMENT_INFO
9438
9439 </p>
9440 <p>/ DB_INSTRUMENT_DIRECTORY_COUNT
9441
9442 </p>
9443 <p>/ DB_INSTRUMENT_DIRECTORY_INFO
9444
9445 </p>
9446 <p>/ DB_INSTRUMENT_COUNT
9447
9448 </p>
9449 <p>/ DB_INSTRUMENT_INFO
9450
9451 </p>
9452 <p>/ DB_INSTRUMENTS_JOB_INFO
9453
9454 </p>
9455 <p>/ MISCELLANEOUS
9456
9457 </p>
9458 <p>/ TOTAL_VOICE_COUNT
9459
9460 </p>
9461 <p>/ GLOBAL_INFO
9462
9463 </p>
9464 </blockquote><p>
9465
9466 </p>
9467 <p>map_instruction =
9468 </p>
9469 <blockquote class="text">
9470 <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
9471
9472 </p>
9473 <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
9474
9475 </p>
9476 <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
9477
9478 </p>
9479 <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
9480
9481 </p>
9482 </blockquote><p>
9483
9484 </p>
9485 <p>unmap_instruction =
9486 </p>
9487 <blockquote class="text">
9488 <p>MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog
9489
9490 </p>
9491 </blockquote><p>
9492
9493 </p>
9494 <p>remove_instruction =
9495 </p>
9496 <blockquote class="text">
9497 <p>CHANNEL SP sampler_channel
9498
9499 </p>
9500 <p>/ MIDI_INSTRUMENT_MAP SP midi_map
9501
9502 </p>
9503 <p>/ MIDI_INSTRUMENT_MAP SP ALL
9504
9505 </p>
9506 <p>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path
9507
9508 </p>
9509 <p>/ DB_INSTRUMENT_DIRECTORY SP db_path
9510
9511 </p>
9512 <p>/ DB_INSTRUMENT SP db_path
9513
9514 </p>
9515 </blockquote><p>
9516
9517 </p>
9518 <p>get_instruction =
9519 </p>
9520 <blockquote class="text">
9521 <p>AVAILABLE_ENGINES
9522
9523 </p>
9524 <p>/ AVAILABLE_MIDI_INPUT_DRIVERS
9525
9526 </p>
9527 <p>/ MIDI_INPUT_DRIVER SP INFO SP string
9528
9529 </p>
9530 <p>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
9531
9532 </p>
9533 <p>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
9534
9535 </p>
9536 <p>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
9537
9538 </p>
9539 <p>/ AUDIO_OUTPUT_DRIVER SP INFO SP string
9540
9541 </p>
9542 <p>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
9543
9544 </p>
9545 <p>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
9546
9547 </p>
9548 <p>/ AUDIO_OUTPUT_DEVICES
9549
9550 </p>
9551 <p>/ MIDI_INPUT_DEVICES
9552
9553 </p>
9554 <p>/ AUDIO_OUTPUT_DEVICE SP INFO SP number
9555
9556 </p>
9557 <p>/ MIDI_INPUT_DEVICE SP INFO SP number
9558
9559 </p>
9560 <p>/ MIDI_INPUT_PORT SP INFO SP number SP number
9561
9562 </p>
9563 <p>/ MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
9564
9565 </p>
9566 <p>/ AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
9567
9568 </p>
9569 <p>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP string
9570
9571 </p>
9572 <p>/ CHANNELS
9573
9574 </p>
9575 <p>/ CHANNEL SP INFO SP sampler_channel
9576
9577 </p>
9578 <p>/ CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
9579
9580 </p>
9581 <p>/ CHANNEL SP STREAM_COUNT SP sampler_channel
9582
9583 </p>
9584 <p>/ CHANNEL SP VOICE_COUNT SP sampler_channel
9585
9586 </p>
9587 <p>/ ENGINE SP INFO SP engine_name
9588
9589 </p>
9590 <p>/ SERVER SP INFO
9591
9592 </p>
9593 <p>/ TOTAL_VOICE_COUNT
9594
9595 </p>
9596 <p>/ TOTAL_VOICE_COUNT_MAX
9597
9598 </p>
9599 <p>/ MIDI_INSTRUMENTS SP midi_map
9600
9601 </p>
9602 <p>/ MIDI_INSTRUMENTS SP ALL
9603
9604 </p>
9605 <p>/ MIDI_INSTRUMENT SP INFO SP midi_map SP midi_bank SP midi_prog
9606
9607 </p>
9608 <p>/ MIDI_INSTRUMENT_MAPS
9609
9610 </p>
9611 <p>/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map
9612
9613 </p>
9614 <p>/ FX_SENDS SP sampler_channel
9615
9616 </p>
9617 <p>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
9618
9619 </p>
9620 <p>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
9621
9622 </p>
9623 <p>/ DB_INSTRUMENT_DIRECTORIES SP db_path
9624
9625 </p>
9626 <p>/ DB_INSTRUMENT_DIRECTORY SP INFO SP db_path
9627
9628 </p>
9629 <p>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
9630
9631 </p>
9632 <p>/ DB_INSTRUMENTS SP db_path
9633
9634 </p>
9635 <p>/ DB_INSTRUMENT SP INFO SP db_path
9636
9637 </p>
9638 <p>/ DB_INSTRUMENTS_JOB SP INFO SP number
9639
9640 </p>
9641 <p>/ VOLUME
9642
9643 </p>
9644 </blockquote><p>
9645
9646 </p>
9647 <p>set_instruction =
9648 </p>
9649 <blockquote class="text">
9650 <p>AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
9651
9652 </p>
9653 <p>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '=' param_val_list
9654
9655 </p>
9656 <p>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
9657
9658 </p>
9659 <p>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE
9660
9661 </p>
9662 <p>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list
9663
9664 </p>
9665 <p>/ CHANNEL SP set_chan_instruction
9666
9667 </p>
9668 <p>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
9669
9670 </p>
9671 <p>/ FX_SEND SP NAME SP sampler_channel SP fx_send_id SP fx_send_name
9672
9673 </p>
9674 <p>/ FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id SP audio_channel_index SP audio_channel_index
9675
9676 </p>
9677 <p>/ FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP midi_ctrl
9678
9679 </p>
9680 <p>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
9681
9682 </p>
9683 <p>/ DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped
9684
9685 </p>
9686 <p>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped
9687
9688 </p>
9689 <p>/ DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped
9690
9691 </p>
9692 <p>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
9693
9694 </p>
9695 <p>/ ECHO SP boolean
9696
9697 </p>
9698 <p>/ VOLUME SP volume_value
9699
9700 </p>
9701 </blockquote><p>
9702
9703 </p>
9704 <p>create_instruction =
9705 </p>
9706 <blockquote class="text">
9707 <p>AUDIO_OUTPUT_DEVICE SP string SP key_val_list
9708
9709 </p>
9710 <p>/ AUDIO_OUTPUT_DEVICE SP string
9711
9712 </p>
9713 <p>/ MIDI_INPUT_DEVICE SP string SP key_val_list
9714
9715 </p>
9716 <p>/ MIDI_INPUT_DEVICE SP string
9717
9718 </p>
9719 <p>/ FX_SEND SP sampler_channel SP midi_ctrl
9720
9721 </p>
9722 <p>/ FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name
9723
9724 </p>
9725 </blockquote><p>
9726
9727 </p>
9728 <p>reset_instruction =
9729 </p>
9730 <blockquote class="text">
9731 <p>CHANNEL SP sampler_channel
9732
9733 </p>
9734 </blockquote><p>
9735
9736 </p>
9737 <p>clear_instruction =
9738 </p>
9739 <blockquote class="text">
9740 <p>MIDI_INSTRUMENTS SP midi_map
9741
9742 </p>
9743 <p>/ MIDI_INSTRUMENTS SP ALL
9744
9745 </p>
9746 </blockquote><p>
9747
9748 </p>
9749 <p>find_instruction =
9750 </p>
9751 <blockquote class="text">
9752 <p>DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list
9753
9754 </p>
9755 <p>/ DB_INSTRUMENTS SP db_path SP query_val_list
9756
9757 </p>
9758 <p>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP query_val_list
9759
9760 </p>
9761 <p>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
9762
9763 </p>
9764 </blockquote><p>
9765
9766 </p>
9767 <p>move_instruction =
9768 </p>
9769 <blockquote class="text">
9770 <p>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
9771
9772 </p>
9773 <p>/ DB_INSTRUMENT SP db_path SP db_path
9774
9775 </p>
9776 </blockquote><p>
9777
9778 </p>
9779 <p>copy_instruction =
9780 </p>
9781 <blockquote class="text">
9782 <p>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
9783
9784 </p>
9785 <p>/ DB_INSTRUMENT SP db_path SP db_path
9786
9787 </p>
9788 </blockquote><p>
9789
9790 </p>
9791 <p>destroy_instruction =
9792 </p>
9793 <blockquote class="text">
9794 <p>AUDIO_OUTPUT_DEVICE SP number
9795
9796 </p>
9797 <p>/ MIDI_INPUT_DEVICE SP number
9798
9799 </p>
9800 <p>/ FX_SEND SP sampler_channel SP fx_send_id
9801
9802 </p>
9803 </blockquote><p>
9804
9805 </p>
9806 <p>load_instruction =
9807 </p>
9808 <blockquote class="text">
9809 <p>INSTRUMENT SP load_instr_args
9810
9811 </p>
9812 <p>/ ENGINE SP load_engine_args
9813
9814 </p>
9815 </blockquote><p>
9816
9817 </p>
9818 <p>set_chan_instruction =
9819 </p>
9820 <blockquote class="text">
9821 <p>AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
9822
9823 </p>
9824 <p>/ AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index SP audio_channel_index
9825
9826 </p>
9827 <p>/ AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
9828
9829 </p>
9830 <p>/ MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index SP midi_input_channel_index
9831
9832 </p>
9833 <p>/ MIDI_INPUT_DEVICE SP sampler_channel SP device_index
9834
9835 </p>
9836 <p>/ MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
9837
9838 </p>
9839 <p>/ MIDI_INPUT_CHANNEL SP sampler_channel SP midi_input_channel_index
9840
9841 </p>
9842 <p>/ MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
9843
9844 </p>
9845 <p>/ VOLUME SP sampler_channel SP volume_value
9846
9847 </p>
9848 <p>/ MUTE SP sampler_channel SP boolean
9849
9850 </p>
9851 <p>/ SOLO SP sampler_channel SP boolean
9852
9853 </p>
9854 <p>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP midi_map
9855
9856 </p>
9857 <p>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP NONE
9858
9859 </p>
9860 <p>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP DEFAULT
9861
9862 </p>
9863 </blockquote><p>
9864
9865 </p>
9866 <p>edit_instruction =
9867 </p>
9868 <blockquote class="text">
9869 <p>INSTRUMENT SP sampler_channel
9870
9871 </p>
9872 </blockquote><p>
9873
9874 </p>
9875 <p>format_instruction =
9876 </p>
9877 <blockquote class="text">
9878 <p>INSTRUMENTS_DB
9879
9880 </p>
9881 </blockquote><p>
9882
9883 </p>
9884 <p>modal_arg =
9885 </p>
9886 <blockquote class="text">
9887 <p>/* epsilon (empty argument) */
9888
9889 </p>
9890 <p>/ NON_MODAL SP
9891
9892 </p>
9893 </blockquote><p>
9894
9895 </p>
9896 <p>key_val_list =
9897 </p>
9898 <blockquote class="text">
9899 <p>string '=' param_val_list
9900
9901 </p>
9902 <p>/ key_val_list SP string '=' param_val_list
9903
9904 </p>
9905 </blockquote><p>
9906
9907 </p>
9908 <p>buffer_size_type =
9909 </p>
9910 <blockquote class="text">
9911 <p>BYTES
9912
9913 </p>
9914 <p>/ PERCENTAGE
9915
9916 </p>
9917 </blockquote><p>
9918
9919 </p>
9920 <p>list_instruction =
9921 </p>
9922 <blockquote class="text">
9923 <p>AUDIO_OUTPUT_DEVICES
9924
9925 </p>
9926 <p>/ MIDI_INPUT_DEVICES
9927
9928 </p>
9929 <p>/ CHANNELS
9930
9931 </p>
9932 <p>/ AVAILABLE_ENGINES
9933
9934 </p>
9935 <p>/ AVAILABLE_MIDI_INPUT_DRIVERS
9936
9937 </p>
9938 <p>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
9939
9940 </p>
9941 <p>/ MIDI_INSTRUMENTS SP midi_map
9942
9943 </p>
9944 <p>/ MIDI_INSTRUMENTS SP ALL
9945
9946 </p>
9947 <p>/ MIDI_INSTRUMENT_MAPS
9948
9949 </p>
9950 <p>/ FX_SENDS SP sampler_channel
9951
9952 </p>
9953 <p>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
9954
9955 </p>
9956 <p>/ DB_INSTRUMENT_DIRECTORIES SP db_path
9957
9958 </p>
9959 <p>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
9960
9961 </p>
9962 <p>/ DB_INSTRUMENTS SP db_path
9963
9964 </p>
9965 </blockquote><p>
9966
9967 </p>
9968 <p>load_instr_args =
9969 </p>
9970 <blockquote class="text">
9971 <p>filename SP instrument_index SP sampler_channel
9972
9973 </p>
9974 <p>/ NON_MODAL SP filename SP instrument_index SP sampler_channel
9975
9976 </p>
9977 </blockquote><p>
9978
9979 </p>
9980 <p>load_engine_args =
9981 </p>
9982 <blockquote class="text">
9983 <p>engine_name SP sampler_channel
9984
9985 </p>
9986 </blockquote><p>
9987
9988 </p>
9989 <p>instr_load_mode =
9990 </p>
9991 <blockquote class="text">
9992 <p>ON_DEMAND
9993
9994 </p>
9995 <p>/ ON_DEMAND_HOLD
9996
9997 </p>
9998 <p>/ PERSISTENT
9999
10000 </p>
10001 </blockquote><p>
10002
10003 </p>
10004 <p>device_index =
10005 </p>
10006 <blockquote class="text">
10007 <p>number
10008
10009 </p>
10010 </blockquote><p>
10011
10012 </p>
10013 <p>audio_channel_index =
10014 </p>
10015 <blockquote class="text">
10016 <p>number
10017
10018 </p>
10019 </blockquote><p>
10020
10021 </p>
10022 <p>audio_output_type_name =
10023 </p>
10024 <blockquote class="text">
10025 <p>string
10026
10027 </p>
10028 </blockquote><p>
10029
10030 </p>
10031 <p>midi_input_port_index =
10032 </p>
10033 <blockquote class="text">
10034 <p>number
10035
10036 </p>
10037 </blockquote><p>
10038
10039 </p>
10040 <p>midi_input_channel_index =
10041 </p>
10042 <blockquote class="text">
10043 <p>number
10044
10045 </p>
10046 <p>/ ALL
10047
10048 </p>
10049 </blockquote><p>
10050
10051 </p>
10052 <p>midi_input_type_name =
10053 </p>
10054 <blockquote class="text">
10055 <p>string
10056
10057 </p>
10058 </blockquote><p>
10059
10060 </p>
10061 <p>midi_map =
10062 </p>
10063 <blockquote class="text">
10064 <p>number
10065
10066 </p>
10067 </blockquote><p>
10068
10069 </p>
10070 <p>midi_bank =
10071 </p>
10072 <blockquote class="text">
10073 <p>number
10074
10075 </p>
10076 </blockquote><p>
10077
10078 </p>
10079 <p>midi_prog =
10080 </p>
10081 <blockquote class="text">
10082 <p>number
10083
10084 </p>
10085 </blockquote><p>
10086
10087 </p>
10088 <p>midi_ctrl =
10089 </p>
10090 <blockquote class="text">
10091 <p>number
10092
10093 </p>
10094 </blockquote><p>
10095
10096 </p>
10097 <p>volume_value =
10098 </p>
10099 <blockquote class="text">
10100 <p>dotnum
10101
10102 </p>
10103 <p>/ number
10104
10105 </p>
10106 </blockquote><p>
10107
10108 </p>
10109 <p>sampler_channel =
10110 </p>
10111 <blockquote class="text">
10112 <p>number
10113
10114 </p>
10115 </blockquote><p>
10116
10117 </p>
10118 <p>instrument_index =
10119 </p>
10120 <blockquote class="text">
10121 <p>number
10122
10123 </p>
10124 </blockquote><p>
10125
10126 </p>
10127 <p>fx_send_id =
10128 </p>
10129 <blockquote class="text">
10130 <p>number
10131
10132 </p>
10133 </blockquote><p>
10134
10135 </p>
10136 <p>engine_name =
10137 </p>
10138 <blockquote class="text">
10139 <p>string
10140
10141 </p>
10142 </blockquote><p>
10143
10144 </p>
10145 <p>filename =
10146 </p>
10147 <blockquote class="text">
10148 <p>path
10149
10150 </p>
10151 </blockquote><p>
10152
10153 </p>
10154 <p>db_path =
10155 </p>
10156 <blockquote class="text">
10157 <p>path
10158
10159 </p>
10160 </blockquote><p>
10161
10162 </p>
10163 <p>map_name =
10164 </p>
10165 <blockquote class="text">
10166 <p>stringval_escaped
10167
10168 </p>
10169 </blockquote><p>
10170
10171 </p>
10172 <p>entry_name =
10173 </p>
10174 <blockquote class="text">
10175 <p>stringval_escaped
10176
10177 </p>
10178 </blockquote><p>
10179
10180 </p>
10181 <p>fx_send_name =
10182 </p>
10183 <blockquote class="text">
10184 <p>stringval_escaped
10185
10186 </p>
10187 </blockquote><p>
10188
10189 </p>
10190 <p>param_val_list =
10191 </p>
10192 <blockquote class="text">
10193 <p>param_val
10194
10195 </p>
10196 <p>/ param_val_list','param_val
10197
10198 </p>
10199 </blockquote><p>
10200
10201 </p>
10202 <p>param_val =
10203 </p>
10204 <blockquote class="text">
10205 <p>string
10206
10207 </p>
10208 <p>/ stringval
10209
10210 </p>
10211 <p>/ number
10212
10213 </p>
10214 <p>/ dotnum
10215
10216 </p>
10217 </blockquote><p>
10218
10219 </p>
10220 <p>query_val_list =
10221 </p>
10222 <blockquote class="text">
10223 <p>string '=' query_val
10224
10225 </p>
10226 <p>/ query_val_list SP string '=' query_val
10227
10228 </p>
10229 </blockquote><p>
10230
10231 </p>
10232 <p>query_val =
10233 </p>
10234 <blockquote class="text">
10235 <p>text_escaped
10236
10237 </p>
10238 <p>/ stringval_escaped
10239
10240 </p>
10241 </blockquote><p>
10242
10243 </p>
10244 <p>scan_mode =
10245 </p>
10246 <blockquote class="text">
10247 <p>RECURSIVE
10248
10249 </p>
10250 <p>/ NON_RECURSIVE
10251
10252 </p>
10253 <p>/ FLAT
10254
10255 </p>
10256 </blockquote><p>
10257
10258 </p>
10259 <a name="character_set"></a><br /><hr />
10260 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10261 <a name="rfc.section.7.1"></a><h3>7.1.&nbsp;
10262 Character Set and Escape Sequences</h3>
10263
10264 <p>Older versions of this protocol up to and including v1.1 only
10265 supported the standard ASCII character set (ASCII code 0 - 127)
10266 <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
10267 however support the Extended ASCII character set (ASCII code
10268 0 - 255). The same group of younger protocols also support
10269 escape sequences, but only for certain, explicitly declared
10270 parts of the protocol. The supported escape sequences are
10271 defined as follows:
10272 </p><table class="full" align="center" border="0" cellpadding="2" cellspacing="2">
10273 <col align="left"><col align="left">
10274 <tr><th align="left">ASCII Character Sequence</th><th align="left">Translated into (Name)</th></tr>
10275 <tr>
10276 <td align="left">\n</td>
10277 <td align="left">new line</td>
10278 </tr>
10279 <tr>
10280 <td align="left">\r</td>
10281 <td align="left">carriage return</td>
10282 </tr>
10283 <tr>
10284 <td align="left">\f</td>
10285 <td align="left">form feed</td>
10286 </tr>
10287 <tr>
10288 <td align="left">\t</td>
10289 <td align="left">horizontal tab</td>
10290 </tr>
10291 <tr>
10292 <td align="left">\v</td>
10293 <td align="left">vertical tab</td>
10294 </tr>
10295 <tr>
10296 <td align="left">\'</td>
10297 <td align="left">apostrophe</td>
10298 </tr>
10299 <tr>
10300 <td align="left">\"</td>
10301 <td align="left">quotation mark</td>
10302 </tr>
10303 <tr>
10304 <td align="left">\\</td>
10305 <td align="left">backslash</td>
10306 </tr>
10307 <tr>
10308 <td align="left">\OOO</td>
10309 <td align="left">three digit octal ASCII code of the character</td>
10310 </tr>
10311 <tr>
10312 <td align="left">\xHH</td>
10313 <td align="left">two digit hex ASCII code of the character</td>
10314 </tr>
10315 </table>
10316
10317 <p>Notice: due to the transition of certain parts of the
10318 protocol which now support escape sequences, a slight backward
10319 incompatibility to protocols version v1.1 and younger has been
10320 introduced. The only difference is that in parts of the protocol
10321 where escape characters are now supported, a backslash characters
10322 MUST be escaped as well (that is as double backslash), whereas
10323 in the old versions a single backslash was sufficient.
10324 </p>
10325 <p>The following LSCP commands support escape sequences as part
10326 of their filename / path based arguments and / or may contain
10327 a filename / path with escape sequences in their response:
10328 </p>
10329 <blockquote class="text">
10330 <p><a class='info' href='#LOAD INSTRUMENT'>"LOAD INSTRUMENT"<span> (</span><span class='info'>Loading an instrument</span><span>)</span></a>
10331 </p>
10332 <p><a class='info' href='#GET CHANNEL INFO'>"GET CHANNEL INFO"<span> (</span><span class='info'>Getting sampler channel information</span><span>)</span></a>
10333 </p>
10334 <p><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>
10335 </p>
10336 <p><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>
10337 </p>
10338 <p><a class='info' href='#ADD DB_INSTRUMENT_DIRECTORY'>"ADD DB_INSTRUMENT_DIRECTORY"<span> (</span><span class='info'>Creating a new instrument directory</span><span>)</span></a>
10339 </p>
10340 <p><a class='info' href='#ADD DB_INSTRUMENTS'>"ADD DB_INSTRUMENTS"<span> (</span><span class='info'>Adding instruments to the instruments database</span><span>)</span></a>
10341 </p>
10342 <p><a class='info' href='#REMOVE DB_INSTRUMENT_DIRECTORY'>"REMOVE DB_INSTRUMENT_DIRECTORY"<span> (</span><span class='info'>Deleting an instrument directory</span><span>)</span></a>
10343 </p>
10344 <p><a class='info' href='#REMOVE DB_INSTRUMENT'>"REMOVE DB_INSTRUMENT"<span> (</span><span class='info'>Removing an instrument</span><span>)</span></a>
10345 </p>
10346 <p><a class='info' href='#GET DB_INSTRUMENT_DIRECTORIES'>"GET DB_INSTRUMENT_DIRECTORIES"<span> (</span><span class='info'>Getting amount of instrument directories</span><span>)</span></a>
10347 </p>
10348 <p><a class='info' href='#LIST DB_INSTRUMENT_DIRECTORIES'>"LIST DB_INSTRUMENT_DIRECTORIES"<span> (</span><span class='info'>Listing all directories in specific directory</span><span>)</span></a>
10349 </p>
10350 <p><a class='info' href='#GET DB_INSTRUMENT_DIRECTORY INFO'>"GET DB_INSTRUMENT_DIRECTORY INFO"<span> (</span><span class='info'>Getting instrument directory information</span><span>)</span></a>
10351 </p>
10352 <p><a class='info' href='#GET DB_INSTRUMENTS'>"GET DB_INSTRUMENTS"<span> (</span><span class='info'>Getting amount of instruments</span><span>)</span></a>
10353 </p>
10354 <p><a class='info' href='#LIST DB_INSTRUMENTS'>"LIST DB_INSTRUMENTS"<span> (</span><span class='info'>Listing all instruments in specific directory</span><span>)</span></a>
10355 </p>
10356 <p><a class='info' href='#GET DB_INSTRUMENT INFO'>"GET DB_INSTRUMENT INFO"<span> (</span><span class='info'>Getting instrument information</span><span>)</span></a>
10357 </p>
10358 <p><a class='info' href='#SET DB_INSTRUMENT_DIRECTORY NAME'>"SET DB_INSTRUMENT_DIRECTORY NAME"<span> (</span><span class='info'>Renaming an instrument directory</span><span>)</span></a>
10359 </p>
10360 <p><a class='info' href='#SET DB_INSTRUMENT_DIRECTORY DESCRIPTION'>"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"<span> (</span><span class='info'>Changing the description of directory</span><span>)</span></a>
10361 </p>
10362 <p><a class='info' href='#SET DB_INSTRUMENT NAME'>"SET DB_INSTRUMENT NAME"<span> (</span><span class='info'>Renaming an instrument</span><span>)</span></a>
10363 </p>
10364 <p><a class='info' href='#SET DB_INSTRUMENT DESCRIPTION'>"SET DB_INSTRUMENT DESCRIPTION"<span> (</span><span class='info'>Changing the description of instrument</span><span>)</span></a>
10365 </p>
10366 <p><a class='info' href='#FIND DB_INSTRUMENTS'>"FIND DB_INSTRUMENTS"<span> (</span><span class='info'>Finding instruments</span><span>)</span></a>
10367 </p>
10368 <p><a class='info' href='#FIND DB_INSTRUMENT_DIRECTORIES'>"FIND DB_INSTRUMENT_DIRECTORIES"<span> (</span><span class='info'>Finding directories</span><span>)</span></a>
10369 </p>
10370 <p><a class='info' href='#MOVE DB_INSTRUMENT'>"MOVE DB_INSTRUMENT"<span> (</span><span class='info'>Moving an instrument</span><span>)</span></a>
10371 </p>
10372 <p><a class='info' href='#MOVE DB_INSTRUMENT_DIRECTORY'>"MOVE DB_INSTRUMENT_DIRECTORY"<span> (</span><span class='info'>Moving an instrument directory</span><span>)</span></a>
10373 </p>
10374 <p><a class='info' href='#COPY DB_INSTRUMENT'>"COPY DB_INSTRUMENT"<span> (</span><span class='info'>Copying instruments</span><span>)</span></a>
10375 </p>
10376 <p><a class='info' href='#COPY DB_INSTRUMENT_DIRECTORY'>"COPY DB_INSTRUMENT_DIRECTORY"<span> (</span><span class='info'>Copying instrument directories</span><span>)</span></a>
10377 </p>
10378 </blockquote><p>
10379 Note that the forward slash character ('/') has a special meaning in
10380 filename / path based arguments: it acts as separator of the nodes in
10381 the path, thus if a directory- or filename includes a forward slash
10382 (not intended as path node separator), you MUST escape that slash
10383 either with the respective hex escape sequence ("\x2f") or with the
10384 respective octal escape sequence ("\057").
10385
10386 </p>
10387 <p>
10388 The following LSCP commands even support escape sequences as
10389 part of at least one of their text-based arguments (i.e. entity name,
10390 description) and / or may contain escape sequences in at least one of
10391 their text-based fields in their response:
10392 </p>
10393 <blockquote class="text">
10394 <p><a class='info' href='#GET SERVER INFO'>"GET SERVER INFO"<span> (</span><span class='info'>General sampler informations</span><span>)</span></a>
10395 </p>
10396 <p><a class='info' href='#GET ENGINE INFO'>"GET ENGINE INFO"<span> (</span><span class='info'>Getting information about an engine</span><span>)</span></a>
10397 </p>
10398 <p><a class='info' href='#GET CHANNEL INFO'>"GET CHANNEL INFO"<span> (</span><span class='info'>Getting sampler channel information</span><span>)</span></a>
10399 </p>
10400 <p><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>
10401 </p>
10402 <p><a class='info' href='#GET FX_SEND INFO'>"GET FX_SEND INFO"<span> (</span><span class='info'>Getting effect send information</span><span>)</span></a>
10403 </p>
10404 <p><a class='info' href='#SET FX_SEND NAME'>"SET FX_SEND NAME"<span> (</span><span class='info'>Changing effect send's name</span><span>)</span></a>
10405 </p>
10406 <p><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>
10407 </p>
10408 <p><a class='info' href='#GET MIDI_INSTRUMENT_MAP INFO'>"GET MIDI_INSTRUMENT_MAP INFO"<span> (</span><span class='info'>Getting MIDI instrument map information</span><span>)</span></a>
10409 </p>
10410 <p><a class='info' href='#ADD MIDI_INSTRUMENT_MAP'>"ADD MIDI_INSTRUMENT_MAP"<span> (</span><span class='info'>Create a new MIDI instrument map</span><span>)</span></a>
10411 </p>
10412 <p><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>
10413 </p>
10414 <p><a class='info' href='#SET MIDI_INSTRUMENT_MAP NAME'>"SET MIDI_INSTRUMENT_MAP NAME"<span> (</span><span class='info'>Renaming a MIDI instrument map</span><span>)</span></a>
10415 </p>
10416 <p><a class='info' href='#SET DB_INSTRUMENT_DIRECTORY NAME'>"SET DB_INSTRUMENT_DIRECTORY NAME"<span> (</span><span class='info'>Renaming an instrument directory</span><span>)</span></a>
10417 </p>
10418 <p><a class='info' href='#SET DB_INSTRUMENT_DIRECTORY DESCRIPTION'>"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"<span> (</span><span class='info'>Changing the description of directory</span><span>)</span></a>
10419 </p>
10420 <p><a class='info' href='#FIND DB_INSTRUMENT_DIRECTORIES'>"FIND DB_INSTRUMENT_DIRECTORIES"<span> (</span><span class='info'>Finding directories</span><span>)</span></a>
10421 </p>
10422 <p><a class='info' href='#SET DB_INSTRUMENT NAME'>"SET DB_INSTRUMENT NAME"<span> (</span><span class='info'>Renaming an instrument</span><span>)</span></a>
10423 </p>
10424 <p><a class='info' href='#SET DB_INSTRUMENT DESCRIPTION'>"SET DB_INSTRUMENT DESCRIPTION"<span> (</span><span class='info'>Changing the description of instrument</span><span>)</span></a>
10425 </p>
10426 <p><a class='info' href='#FIND DB_INSTRUMENTS'>"FIND DB_INSTRUMENTS"<span> (</span><span class='info'>Finding instruments</span><span>)</span></a>
10427 </p>
10428 </blockquote><p>
10429 Please note that these lists are manually maintained. If you
10430 find a command that also supports escape sequences we forgot to
10431 mention here, please report it!
10432
10433 </p>
10434 <a name="events"></a><br /><hr />
10435 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10436 <a name="rfc.section.8"></a><h3>8.&nbsp;
10437 Events</h3>
10438
10439 <p>This chapter will describe all currently defined events supported by LinuxSampler.
10440 </p>
10441 <a name="SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT"></a><br /><hr />
10442 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10443 <a name="rfc.section.8.1"></a><h3>8.1.&nbsp;
10444 Number of audio output devices changed</h3>
10445
10446 <p>Client may want to be notified when the total number of audio output devices on the
10447 back-end changes by issuing the following command:
10448 </p>
10449 <p>
10450 </p>
10451 <blockquote class="text">
10452 <p>SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT
10453 </p>
10454 </blockquote><p>
10455
10456 </p>
10457 <p>Server will start sending the following notification messages:
10458 </p>
10459 <p>
10460 </p>
10461 <blockquote class="text">
10462 <p>"NOTIFY:AUDIO_OUTPUT_DEVICE_COUNT:&lt;devices&gt;"
10463 </p>
10464 </blockquote><p>
10465
10466 </p>
10467 <p>where &lt;devices&gt; will be replaced by the new number
10468 of audio output devices.
10469 </p>
10470 <a name="SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO"></a><br /><hr />
10471 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10472 <a name="rfc.section.8.2"></a><h3>8.2.&nbsp;
10473 Audio output device's settings changed</h3>
10474
10475 <p>Client may want to be notified when changes were made to audio output devices on the
10476 back-end by issuing the following command:
10477 </p>
10478 <p>
10479 </p>
10480 <blockquote class="text">
10481 <p>SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO
10482 </p>
10483 </blockquote><p>
10484
10485 </p>
10486 <p>Server will start sending the following notification messages:
10487 </p>
10488 <p>
10489 </p>
10490 <blockquote class="text">
10491 <p>"NOTIFY:AUDIO_OUTPUT_DEVICE_INFO:&lt;device-id&gt;"
10492 </p>
10493 </blockquote><p>
10494
10495 </p>
10496 <p>where &lt;device-id&gt; will be replaced by the numerical ID of the audio output device,
10497 which settings has been changed. The front-end will have to send
10498 the respective command to actually get the audio output device info. Because these messages
10499 will be triggered by LSCP commands issued by other clients rather than real
10500 time events happening on the server, it is believed that an empty notification
10501 message is sufficient here.
10502 </p>
10503 <a name="SUBSCRIBE MIDI_INPUT_DEVICE_COUNT"></a><br /><hr />
10504 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10505 <a name="rfc.section.8.3"></a><h3>8.3.&nbsp;
10506 Number of MIDI input devices changed</h3>
10507
10508 <p>Client may want to be notified when the total number of MIDI input devices on the
10509 back-end changes by issuing the following command:
10510 </p>
10511 <p>
10512 </p>
10513 <blockquote class="text">
10514 <p>SUBSCRIBE MIDI_INPUT_DEVICE_COUNT
10515 </p>
10516 </blockquote><p>
10517
10518 </p>
10519 <p>Server will start sending the following notification messages:
10520 </p>
10521 <p>
10522 </p>
10523 <blockquote class="text">
10524 <p>"NOTIFY:MIDI_INPUT_DEVICE_COUNT:&lt;devices&gt;"
10525 </p>
10526 </blockquote><p>
10527
10528 </p>
10529 <p>where &lt;devices&gt; will be replaced by the new number
10530 of MIDI input devices.
10531 </p>
10532 <a name="SUBSCRIBE MIDI_INPUT_DEVICE_INFO"></a><br /><hr />
10533 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10534 <a name="rfc.section.8.4"></a><h3>8.4.&nbsp;
10535 MIDI input device's settings changed</h3>
10536
10537 <p>Client may want to be notified when changes were made to MIDI input devices on the
10538 back-end by issuing the following command:
10539 </p>
10540 <p>
10541 </p>
10542 <blockquote class="text">
10543 <p>SUBSCRIBE MIDI_INPUT_DEVICE_INFO
10544 </p>
10545 </blockquote><p>
10546
10547 </p>
10548 <p>Server will start sending the following notification messages:
10549 </p>
10550 <p>
10551 </p>
10552 <blockquote class="text">
10553 <p>"NOTIFY:MIDI_INPUT_DEVICE_INFO:&lt;device-id&gt;"
10554 </p>
10555 </blockquote><p>
10556
10557 </p>
10558 <p>where &lt;device-id&gt; will be replaced by the numerical ID of the MIDI input device,
10559 which settings has been changed. The front-end will have to send
10560 the respective command to actually get the MIDI input device info. Because these messages
10561 will be triggered by LSCP commands issued by other clients rather than real
10562 time events happening on the server, it is believed that an empty notification
10563 message is sufficient here.
10564 </p>
10565 <a name="SUBSCRIBE CHANNEL_COUNT"></a><br /><hr />
10566 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10567 <a name="rfc.section.8.5"></a><h3>8.5.&nbsp;
10568 Number of sampler channels changed</h3>
10569
10570 <p>Client may want to be notified when the total number of channels on the
10571 back-end changes by issuing the following command:
10572 </p>
10573 <p>
10574 </p>
10575 <blockquote class="text">
10576 <p>SUBSCRIBE CHANNEL_COUNT
10577 </p>
10578 </blockquote><p>
10579
10580 </p>
10581 <p>Server will start sending the following notification messages:
10582 </p>
10583 <p>
10584 </p>
10585 <blockquote class="text">
10586 <p>"NOTIFY:CHANNEL_COUNT:&lt;channels&gt;"
10587 </p>
10588 </blockquote><p>
10589
10590 </p>
10591 <p>where &lt;channels&gt; will be replaced by the new number
10592 of sampler channels.
10593 </p>
10594 <a name="SUBSCRIBE VOICE_COUNT"></a><br /><hr />
10595 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10596 <a name="rfc.section.8.6"></a><h3>8.6.&nbsp;
10597 Number of active voices changed</h3>
10598
10599 <p>Client may want to be notified when the number of voices on the
10600 back-end changes by issuing the following command:
10601 </p>
10602 <p>
10603 </p>
10604 <blockquote class="text">
10605 <p>SUBSCRIBE VOICE_COUNT
10606 </p>
10607 </blockquote><p>
10608
10609 </p>
10610 <p>Server will start sending the following notification messages:
10611 </p>
10612 <p>
10613 </p>
10614 <blockquote class="text">
10615 <p>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;"
10616 </p>
10617 </blockquote><p>
10618
10619 </p>
10620 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
10621 voice count change occurred and &lt;voices&gt; by the new number of
10622 active voices on that channel.
10623 </p>
10624 <a name="SUBSCRIBE STREAM_COUNT"></a><br /><hr />
10625 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10626 <a name="rfc.section.8.7"></a><h3>8.7.&nbsp;
10627 Number of active disk streams changed</h3>
10628
10629 <p>Client may want to be notified when the number of streams on the back-end
10630 changes by issuing the following command: SUBSCRIBE STREAM_COUNT
10631 </p>
10632 <p>
10633 </p>
10634 <blockquote class="text">
10635 <p>SUBSCRIBE STREAM_COUNT
10636 </p>
10637 </blockquote><p>
10638
10639 </p>
10640 <p>Server will start sending the following notification messages:
10641 </p>
10642 <p>
10643 </p>
10644 <blockquote class="text">
10645 <p>"NOTIFY:STREAM_COUNT:&lt;sampler-channel&gt; &lt;streams&gt;"
10646 </p>
10647 </blockquote><p>
10648
10649 </p>
10650 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
10651 stream count change occurred and &lt;streams&gt; by the new number of
10652 active disk streams on that channel.
10653 </p>
10654 <a name="SUBSCRIBE BUFFER_FILL"></a><br /><hr />
10655 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10656 <a name="rfc.section.8.8"></a><h3>8.8.&nbsp;
10657 Disk stream buffer fill state changed</h3>
10658
10659 <p>Client may want to be notified when the buffer fill state of a disk stream
10660 on the back-end changes by issuing the following command:
10661 </p>
10662 <p>
10663 </p>
10664 <blockquote class="text">
10665 <p>SUBSCRIBE BUFFER_FILL
10666 </p>
10667 </blockquote><p>
10668
10669 </p>
10670 <p>Server will start sending the following notification messages:
10671 </p>
10672 <p>
10673 </p>
10674 <blockquote class="text">
10675 <p>"NOTIFY:BUFFER_FILL:&lt;sampler-channel&gt; &lt;fill-data&gt;"
10676 </p>
10677 </blockquote><p>
10678
10679 </p>
10680 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
10681 buffer fill state change occurred on and &lt;fill-data&gt; will be replaced by the
10682 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>
10683 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.
10684 </p>
10685 <a name="SUBSCRIBE CHANNEL_INFO"></a><br /><hr />
10686 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10687 <a name="rfc.section.8.9"></a><h3>8.9.&nbsp;
10688 Channel information changed</h3>
10689
10690 <p>Client may want to be notified when changes were made to sampler channels on the
10691 back-end by issuing the following command:
10692 </p>
10693 <p>
10694 </p>
10695 <blockquote class="text">
10696 <p>SUBSCRIBE CHANNEL_INFO
10697 </p>
10698 </blockquote><p>
10699
10700 </p>
10701 <p>Server will start sending the following notification messages:
10702 </p>
10703 <p>
10704 </p>
10705 <blockquote class="text">
10706 <p>"NOTIFY:CHANNEL_INFO:&lt;sampler-channel&gt;"
10707 </p>
10708 </blockquote><p>
10709
10710 </p>
10711 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
10712 channel info change occurred. The front-end will have to send
10713 the respective command to actually get the channel info. Because these messages
10714 will be triggered by LSCP commands issued by other clients rather than real
10715 time events happening on the server, it is believed that an empty notification
10716 message is sufficient here.
10717 </p>
10718 <a name="SUBSCRIBE FX_SEND_COUNT"></a><br /><hr />
10719 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10720 <a name="rfc.section.8.10"></a><h3>8.10.&nbsp;
10721 Number of effect sends changed</h3>
10722
10723 <p>Client may want to be notified when the number of effect sends on
10724 a particular sampler channel is changed by issuing the following command:
10725 </p>
10726 <p>
10727 </p>
10728 <blockquote class="text">
10729 <p>SUBSCRIBE FX_SEND_COUNT
10730 </p>
10731 </blockquote><p>
10732
10733 </p>
10734 <p>Server will start sending the following notification messages:
10735 </p>
10736 <p>
10737 </p>
10738 <blockquote class="text">
10739 <p>"NOTIFY:FX_SEND_COUNT:&lt;channel-id&gt; &lt;fx-sends&gt;"
10740 </p>
10741 </blockquote><p>
10742
10743 </p>
10744 <p>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
10745 channel, on which the effect sends number is changed and &lt;fx-sends&gt; will
10746 be replaced by the new number of effect sends on that channel.
10747 </p>
10748 <a name="SUBSCRIBE FX_SEND_INFO"></a><br /><hr />
10749 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10750 <a name="rfc.section.8.11"></a><h3>8.11.&nbsp;
10751 Effect send information changed</h3>
10752
10753 <p>Client may want to be notified when changes were made to effect sends on a
10754 a particular sampler channel by issuing the following command:
10755 </p>
10756 <p>
10757 </p>
10758 <blockquote class="text">
10759 <p>SUBSCRIBE FX_SEND_INFO
10760 </p>
10761 </blockquote><p>
10762
10763 </p>
10764 <p>Server will start sending the following notification messages:
10765 </p>
10766 <p>
10767 </p>
10768 <blockquote class="text">
10769 <p>"NOTIFY:FX_SEND_INFO:&lt;channel-id&gt; &lt;fx-send-id&gt;"
10770 </p>
10771 </blockquote><p>
10772
10773 </p>
10774 <p>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
10775 channel, on which an effect send entity is changed and &lt;fx-send-id&gt; will
10776 be replaced by the numerical ID of the changed effect send.
10777 </p>
10778 <a name="SUBSCRIBE TOTAL_VOICE_COUNT"></a><br /><hr />
10779 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10780 <a name="rfc.section.8.12"></a><h3>8.12.&nbsp;
10781 Total number of active voices changed</h3>
10782
10783 <p>Client may want to be notified when the total number of voices on the
10784 back-end changes by issuing the following command:
10785 </p>
10786 <p>
10787 </p>
10788 <blockquote class="text">
10789 <p>SUBSCRIBE TOTAL_VOICE_COUNT
10790 </p>
10791 </blockquote><p>
10792
10793 </p>
10794 <p>Server will start sending the following notification messages:
10795 </p>
10796 <p>
10797 </p>
10798 <blockquote class="text">
10799 <p>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;"
10800 </p>
10801 </blockquote><p>
10802
10803 </p>
10804 <p>where &lt;voices&gt; will be replaced by the new number of
10805 all currently active voices.
10806 </p>
10807 <a name="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT"></a><br /><hr />
10808 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10809 <a name="rfc.section.8.13"></a><h3>8.13.&nbsp;
10810 Number of MIDI instrument maps changed</h3>
10811
10812 <p>Client may want to be notified when the number of MIDI instrument maps on the
10813 back-end changes by issuing the following command:
10814 </p>
10815 <p>
10816 </p>
10817 <blockquote class="text">
10818 <p>SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT
10819 </p>
10820 </blockquote><p>
10821
10822 </p>
10823 <p>Server will start sending the following notification messages:
10824 </p>
10825 <p>
10826 </p>
10827 <blockquote class="text">
10828 <p>"NOTIFY:MIDI_INSTRUMENT_MAP_COUNT:&lt;maps&gt;"
10829 </p>
10830 </blockquote><p>
10831
10832 </p>
10833 <p>where &lt;maps&gt; will be replaced by the new number
10834 of MIDI instrument maps.
10835 </p>
10836 <a name="SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO"></a><br /><hr />
10837 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10838 <a name="rfc.section.8.14"></a><h3>8.14.&nbsp;
10839 MIDI instrument map information changed</h3>
10840
10841 <p>Client may want to be notified when changes were made to MIDI instrument maps on the
10842 back-end by issuing the following command:
10843 </p>
10844 <p>
10845 </p>
10846 <blockquote class="text">
10847 <p>SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO
10848 </p>
10849 </blockquote><p>
10850
10851 </p>
10852 <p>Server will start sending the following notification messages:
10853 </p>
10854 <p>
10855 </p>
10856 <blockquote class="text">
10857 <p>"NOTIFY:MIDI_INSTRUMENT_MAP_INFO:&lt;map-id&gt;"
10858 </p>
10859 </blockquote><p>
10860
10861 </p>
10862 <p>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
10863 for which information changes occurred. The front-end will have to send
10864 the respective command to actually get the MIDI instrument map info. Because these messages
10865 will be triggered by LSCP commands issued by other clients rather than real
10866 time events happening on the server, it is believed that an empty notification
10867 message is sufficient here.
10868 </p>
10869 <a name="SUBSCRIBE MIDI_INSTRUMENT_COUNT"></a><br /><hr />
10870 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10871 <a name="rfc.section.8.15"></a><h3>8.15.&nbsp;
10872 Number of MIDI instruments changed</h3>
10873
10874 <p>Client may want to be notified when the number of MIDI instrument maps on the
10875 back-end changes by issuing the following command:
10876 </p>
10877 <p>
10878 </p>
10879 <blockquote class="text">
10880 <p>SUBSCRIBE MIDI_INSTRUMENT_COUNT
10881 </p>
10882 </blockquote><p>
10883
10884 </p>
10885 <p>Server will start sending the following notification messages:
10886 </p>
10887 <p>
10888 </p>
10889 <blockquote class="text">
10890 <p>"NOTIFY:MIDI_INSTRUMENT_COUNT:&lt;map-id&gt; &lt;instruments&gt;"
10891 </p>
10892 </blockquote><p>
10893
10894 </p>
10895 <p>where &lt;map-id&gt; is the numerical ID of the MIDI instrument map, in which
10896 the nuber of instruments has changed and &lt;instruments&gt; will be replaced by
10897 the new number of MIDI instruments in the specified map.
10898 </p>
10899 <a name="SUBSCRIBE MIDI_INSTRUMENT_INFO"></a><br /><hr />
10900 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10901 <a name="rfc.section.8.16"></a><h3>8.16.&nbsp;
10902 MIDI instrument information changed</h3>
10903
10904 <p>Client may want to be notified when changes were made to MIDI instruments on the
10905 back-end by issuing the following command:
10906 </p>
10907 <p>
10908 </p>
10909 <blockquote class="text">
10910 <p>SUBSCRIBE MIDI_INSTRUMENT_INFO
10911 </p>
10912 </blockquote><p>
10913
10914 </p>
10915 <p>Server will start sending the following notification messages:
10916 </p>
10917 <p>
10918 </p>
10919 <blockquote class="text">
10920 <p>"NOTIFY:MIDI_INSTRUMENT_INFO:&lt;map-id&gt; &lt;bank&gt; &lt;program&gt;"
10921 </p>
10922 </blockquote><p>
10923
10924 </p>
10925 <p>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
10926 in which a MIDI instrument is changed. &lt;bank&gt; and &lt;program&gt; specifies
10927 the location of the changed MIDI instrument in the map. The front-end will have to send
10928 the respective command to actually get the MIDI instrument info. Because these messages
10929 will be triggered by LSCP commands issued by other clients rather than real
10930 time events happening on the server, it is believed that an empty notification
10931 message is sufficient here.
10932 </p>
10933 <a name="SUBSCRIBE GLOBAL_INFO"></a><br /><hr />
10934 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10935 <a name="rfc.section.8.17"></a><h3>8.17.&nbsp;
10936 Global settings changed</h3>
10937
10938 <p>Client may want to be notified when changes to the global settings
10939 of the sampler were made by issuing the following command:
10940 </p>
10941 <p>
10942 </p>
10943 <blockquote class="text">
10944 <p>SUBSCRIBE GLOBAL_INFO
10945 </p>
10946 </blockquote><p>
10947
10948 </p>
10949 <p>Server will start sending the following types of notification messages:
10950 </p>
10951 <p>
10952 </p>
10953 <blockquote class="text">
10954 <p>"NOTIFY:GLOBAL_INFO:VOLUME &lt;volume&gt;" - Notifies that the
10955 golbal volume of the sampler is changed, where &lt;volume&gt; will be
10956 replaced by the optional dotted floating point value, reflecting the
10957 new global volume parameter.
10958 </p>
10959 </blockquote><p>
10960
10961 </p>
10962 <a name="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT"></a><br /><hr />
10963 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10964 <a name="rfc.section.8.18"></a><h3>8.18.&nbsp;
10965 Number of database instrument directories changed</h3>
10966
10967 <p>Client may want to be notified when the number of instrument
10968 directories in a particular directory in the instruments database
10969 is changed by issuing the following command:
10970 </p>
10971 <p>
10972 </p>
10973 <blockquote class="text">
10974 <p>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT
10975 </p>
10976 </blockquote><p>
10977
10978 </p>
10979 <p>Server will start sending the following notification messages:
10980 </p>
10981 <p>
10982 </p>
10983 <blockquote class="text">
10984 <p>"NOTIFY:DB_INSTRUMENT_DIRECTORY_COUNT:&lt;dir-path&gt;"
10985 </p>
10986 </blockquote><p>
10987
10988 </p>
10989 <p>where &lt;dir-path&gt; will be replaced by the absolute path
10990 name of the directory in the instruments database,
10991 in which the number of directories is changed.
10992 </p>
10993 <p>Note that when a non-empty directory is removed, this event
10994 is not sent for the subdirectories in that directory.
10995 </p>
10996 <a name="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO"></a><br /><hr />
10997 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10998 <a name="rfc.section.8.19"></a><h3>8.19.&nbsp;
10999 Database instrument directory information changed</h3>
11000
11001 <p>Client may want to be notified when changes were made to directories
11002 in the instruments database by issuing the following command:
11003 </p>
11004 <p>
11005 </p>
11006 <blockquote class="text">
11007 <p>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO
11008 </p>
11009 </blockquote><p>
11010
11011 </p>
11012 <p>Server will start sending the following notification messages:
11013 </p>
11014 <p>
11015 </p>
11016 <blockquote class="text">
11017 <p>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:&lt;dir-path&gt;"
11018 </p>
11019 </blockquote><p>
11020
11021 </p>
11022 <p>where &lt;dir-path&gt; will be replaced by the absolute path name
11023 of the directory, for which information changes occurred. The front-end will have to send
11024 the respective command to actually get the updated directory info. Because these messages
11025 will be triggered by LSCP commands issued by other clients rather than real
11026 time events happening on the server, it is believed that an empty notification
11027 message is sufficient here.
11028 </p>
11029 <p>
11030 </p>
11031 <blockquote class="text">
11032 <p>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:NAME &lt;old-dir-path&gt; &lt;new-name&gt;"
11033 </p>
11034 </blockquote><p>
11035
11036 </p>
11037 <p>where &lt;old-dir-path&gt; is the old absolute path name of the directory
11038 (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
11039 the new name of the directory, encapsulated into apostrophes.
11040 </p>
11041 <a name="SUBSCRIBE DB_INSTRUMENT_COUNT"></a><br /><hr />
11042 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11043 <a name="rfc.section.8.20"></a><h3>8.20.&nbsp;
11044 Number of database instruments changed</h3>
11045
11046 <p>Client may want to be notified when the number of instruments
11047 in a particular directory in the instruments database
11048 is changed by issuing the following command:
11049 </p>
11050 <p>
11051 </p>
11052 <blockquote class="text">
11053 <p>SUBSCRIBE DB_INSTRUMENT_COUNT
11054 </p>
11055 </blockquote><p>
11056
11057 </p>
11058 <p>Server will start sending the following notification messages:
11059 </p>
11060 <p>
11061 </p>
11062 <blockquote class="text">
11063 <p>"NOTIFY:DB_INSTRUMENT_COUNT:&lt;dir-path&gt;"
11064 </p>
11065 </blockquote><p>
11066
11067 </p>
11068 <p>where &lt;dir-path&gt; will be replaced by the absolute path
11069 name of the directory in the instruments database,
11070 in which the number of instruments is changed.
11071 </p>
11072 <p>Note that when a non-empty directory is removed, this event
11073 is not sent for the instruments in that directory.
11074 </p>
11075 <a name="SUBSCRIBE DB_INSTRUMENT_INFO"></a><br /><hr />
11076 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11077 <a name="rfc.section.8.21"></a><h3>8.21.&nbsp;
11078 Database instrument information changed</h3>
11079
11080 <p>Client may want to be notified when changes were made to instruments
11081 in the instruments database by issuing the following command:
11082 </p>
11083 <p>
11084 </p>
11085 <blockquote class="text">
11086 <p>SUBSCRIBE DB_INSTRUMENT_INFO
11087 </p>
11088 </blockquote><p>
11089
11090 </p>
11091 <p>Server will start sending the following notification messages:
11092 </p>
11093 <p>
11094 </p>
11095 <blockquote class="text">
11096 <p>"NOTIFY:DB_INSTRUMENT_INFO:&lt;instr-path&gt;"
11097 </p>
11098 </blockquote><p>
11099
11100 </p>
11101 <p>where &lt;instr-path&gt; will be replaced by the absolute path name
11102 of the instrument, which settings are changed. The front-end will have to send
11103 the respective command to actually get the updated directory info. Because these messages
11104 will be triggered by LSCP commands issued by other clients rather than real
11105 time events happening on the server, it is believed that an empty notification
11106 message is sufficient here.
11107 </p>
11108 <p>
11109 </p>
11110 <blockquote class="text">
11111 <p>"NOTIFY:DB_INSTRUMENT_INFO:NAME &lt;old-instr-path&gt; &lt;new-name&gt;"
11112 </p>
11113 </blockquote><p>
11114
11115 </p>
11116 <p>where &lt;old-instr-path&gt; is the old absolute path name of the instrument
11117 (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
11118 the new name of the instrument, encapsulated into apostrophes.
11119 </p>
11120 <a name="SUBSCRIBE DB_INSTRUMENTS_JOB_INFO"></a><br /><hr />
11121 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11122 <a name="rfc.section.8.22"></a><h3>8.22.&nbsp;
11123 Database job status information changed</h3>
11124
11125 <p>Client may want to be notified when the status of particular database
11126 instruments job is changed by issuing the following command:
11127 </p>
11128 <p>
11129 </p>
11130 <blockquote class="text">
11131 <p>SUBSCRIBE DB_INSTRUMENTS_JOB_INFO
11132 </p>
11133 </blockquote><p>
11134
11135 </p>
11136 <p>Server will start sending the following notification messages:
11137 </p>
11138 <p>
11139 </p>
11140 <blockquote class="text">
11141 <p>"NOTIFY:DB_INSTRUMENTS_JOB_INFO:&lt;job-id&gt;"
11142 </p>
11143 </blockquote><p>
11144
11145 </p>
11146 <p>where &lt;job-id&gt; will be replaced by the numerical ID of the job,
11147 which status is changed. The front-end will have to send the respective
11148 command to actually get the status info. Because these messages
11149 will be triggered by LSCP commands issued by other clients rather than real
11150 time events happening on the server, it is believed that an empty notification
11151 message is sufficient here.
11152 </p>
11153 <a name="SUBSCRIBE MISCELLANEOUS"></a><br /><hr />
11154 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11155 <a name="rfc.section.8.23"></a><h3>8.23.&nbsp;
11156 Miscellaneous and debugging events</h3>
11157
11158 <p>Client may want to be notified of miscellaneous and debugging events occurring at
11159 the server by issuing the following command:
11160 </p>
11161 <p>
11162 </p>
11163 <blockquote class="text">
11164 <p>SUBSCRIBE MISCELLANEOUS
11165 </p>
11166 </blockquote><p>
11167
11168 </p>
11169 <p>Server will start sending the following notification messages:
11170 </p>
11171 <p>
11172 </p>
11173 <blockquote class="text">
11174 <p>"NOTIFY:MISCELLANEOUS:&lt;string&gt;"
11175 </p>
11176 </blockquote><p>
11177
11178 </p>
11179 <p>where &lt;string&gt; will be replaced by whatever data server
11180 wants to send to the client. Client MAY display this data to the
11181 user AS IS to facilitate debugging.
11182 </p>
11183 <a name="anchor14"></a><br /><hr />
11184 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11185 <a name="rfc.section.9"></a><h3>9.&nbsp;
11186 Security Considerations</h3>
11187
11188 <p>As there is so far no method of authentication and authorization
11189 defined and so not required for a client applications to succeed to
11190 connect, running LinuxSampler might be a security risk for the host
11191 system the LinuxSampler instance is running on.
11192 </p>
11193 <a name="anchor15"></a><br /><hr />
11194 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11195 <a name="rfc.section.10"></a><h3>10.&nbsp;
11196 Acknowledgments</h3>
11197
11198 <p>This document has benefited greatly from the comments of the
11199 following people, discussed on the LinuxSampler developer's mailing
11200 list:
11201 </p>
11202 <p>
11203 </p>
11204 <blockquote class="text">
11205 <p>Rui Nuno Capela
11206 </p>
11207 <p>Vladimir Senkov
11208 </p>
11209 <p>Mark Knecht
11210 </p>
11211 <p>Grigor Iliev
11212 </p>
11213 </blockquote><p>
11214
11215 </p>
11216 <a name="rfc.references1"></a><br /><hr />
11217 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11218 <h3>11.&nbsp;References</h3>
11219 <table width="99%" border="0">
11220 <tr><td class="author-text" valign="top"><a name="RFC20">[RFC20]</a></td>
11221 <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>
11222 <tr><td class="author-text" valign="top"><a name="RFC2119">[RFC2119]</a></td>
11223 <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>
11224 <tr><td class="author-text" valign="top"><a name="RFC2234">[RFC2234]</a></td>
11225 <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>
11226 <tr><td class="author-text" valign="top"><a name="RFC793">[RFC793]</a></td>
11227 <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>
11228 </table>
11229
11230 <a name="rfc.authors"></a><br /><hr />
11231 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11232 <h3>Author's Address</h3>
11233 <table width="99%" border="0" cellpadding="0" cellspacing="0">
11234 <tr><td class="author-text">&nbsp;</td>
11235 <td class="author-text">C.
11236 Schoenebeck</td></tr>
11237 <tr><td class="author-text">&nbsp;</td>
11238 <td class="author-text">Interessengemeinschaft Software Engineering e. V.</td></tr>
11239 <tr><td class="author-text">&nbsp;</td>
11240 <td class="author-text">Max-Planck-Str. 39</td></tr>
11241 <tr><td class="author-text">&nbsp;</td>
11242 <td class="author-text">74081 Heilbronn</td></tr>
11243 <tr><td class="author-text">&nbsp;</td>
11244 <td class="author-text">Germany</td></tr>
11245 <tr><td class="author" align="right">Email:&nbsp;</td>
11246 <td class="author-text"><a href="mailto:schoenebeck at software minus engineering dot org">schoenebeck at software minus engineering dot org</a></td></tr>
11247 </table>
11248 <a name="rfc.copyright"></a><br /><hr />
11249 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11250 <h3>Full Copyright Statement</h3>
11251 <p class='copyright'>
11252 Copyright &copy; The IETF Trust (2007).</p>
11253 <p class='copyright'>
11254 This document is subject to the rights,
11255 licenses and restrictions contained in BCP&nbsp;78,
11256 and except as set forth therein,
11257 the authors retain all their rights.</p>
11258 <p class='copyright'>
11259 This document and the information contained herein are provided
11260 on an &ldquo;AS IS&rdquo; basis and THE CONTRIBUTOR,
11261 THE ORGANIZATION HE/SHE REPRESENTS
11262 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST
11263 AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES,
11264 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT
11265 THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY
11266 IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
11267 PURPOSE.</p>
11268 <h3>Intellectual Property</h3>
11269 <p class='copyright'>
11270 The IETF takes no position regarding the validity or scope of any
11271 Intellectual Property Rights or other rights that might be claimed
11272 to pertain to the implementation or use of the technology
11273 described in this document or the extent to which any license
11274 under such rights might or might not be available; nor does it
11275 represent that it has made any independent effort to identify any
11276 such rights.
11277 Information on the procedures with respect to
11278 rights in RFC documents can be found in BCP&nbsp;78 and BCP&nbsp;79.</p>
11279 <p class='copyright'>
11280 Copies of IPR disclosures made to the IETF Secretariat and any
11281 assurances of licenses to be made available,
11282 or the result of an attempt made to obtain a general license or
11283 permission for the use of such proprietary rights by implementers or
11284 users of this specification can be obtained from the IETF on-line IPR
11285 repository at <a href='http://www.ietf.org/ipr'>http://www.ietf.org/ipr</a>.</p>
11286 <p class='copyright'>
11287 The IETF invites any interested party to bring to its attention
11288 any copyrights,
11289 patents or patent applications,
11290 or other
11291 proprietary rights that may cover technology that may be required
11292 to implement this standard.
11293 Please address the information to the IETF at <a href='mailto:ietf-ipr@ietf.org'>ietf-ipr@ietf.org</a>.</p>
11294 <h3>Acknowledgment</h3>
11295 <p class='copyright'>
11296 Funding for the RFC Editor function is provided by
11297 the IETF Administrative Support Activity (IASA).</p>
11298 </body></html>
11299

  ViewVC Help
Powered by ViewVC