/[svn]/web/trunk/www.linuxsampler.org/api/lscp-1.2.html
ViewVC logotype

Annotation of /web/trunk/www.linuxsampler.org/api/lscp-1.2.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1430 - (hide annotations) (download) (as text)
Sun Oct 14 23:39:14 2007 UTC (16 years, 6 months ago) by schoenebeck
File MIME type: text/html
File size: 398239 byte(s) 
* new LSCP "release" (v1.2) along to the new LS release (0.5.0)
1 schoenebeck 1430 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2     <html lang="en"><head><title>LinuxSampler Control Protocol</title>
3     <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
4     <meta name="description" content="LinuxSampler Control Protocol">
5     <meta name="keywords" content="LSCP">
6     <meta name="generator" content="xml2rfc v1.32 (http://xml.resource.org/)">
7     <style type='text/css'><!--
8     body {
9     font-family: verdana, charcoal, helvetica, arial, sans-serif;
10     font-size: small; color: #000; background-color: #FFF;
11     margin: 2em;
12     }
13     h1, h2, h3, h4, h5, h6 {
14     font-family: helvetica, monaco, "MS Sans Serif", arial, sans-serif;
15     font-weight: bold; font-style: normal;
16     }
17     h1 { color: #900; background-color: transparent; text-align: right; }
18     h3 { color: #333; background-color: transparent; }
19    
20     td.RFCbug {
21     font-size: x-small; text-decoration: none;
22     width: 30px; height: 30px; padding-top: 2px;
23     text-align: justify; vertical-align: middle;
24     background-color: #000;
25     }
26     td.RFCbug span.RFC {
27     font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
28     font-weight: bold; color: #666;
29     }
30     td.RFCbug span.hotText {
31     font-family: charcoal, monaco, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
32     font-weight: normal; text-align: center; color: #FFF;
33     }
34    
35     table.TOCbug { width: 30px; height: 15px; }
36     td.TOCbug {
37     text-align: center; width: 30px; height: 15px;
38     color: #FFF; background-color: #900;
39     }
40     td.TOCbug a {
41     font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, sans-serif;
42     font-weight: bold; font-size: x-small; text-decoration: none;
43     color: #FFF; background-color: transparent;
44     }
45    
46     td.header {
47     font-family: arial, helvetica, sans-serif; font-size: x-small;
48     vertical-align: top; width: 33%;
49     color: #FFF; background-color: #666;
50     }
51     td.author { font-weight: bold; font-size: x-small; margin-left: 4em; }
52     td.author-text { font-size: x-small; }
53    
54     /* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */
55     a.info {
56     /* This is the key. */
57     position: relative;
58     z-index: 24;
59     text-decoration: none;
60     }
61     a.info:hover {
62     z-index: 25;
63     color: #FFF; background-color: #900;
64     }
65     a.info span { display: none; }
66     a.info:hover span.info {
67     /* The span will display just on :hover state. */
68     display: block;
69     position: absolute;
70     font-size: smaller;
71     top: 2em; left: -5em; width: 15em;
72     padding: 2px; border: 1px solid #333;
73     color: #900; background-color: #EEE;
74     text-align: left;
75     }
76    
77     a { font-weight: bold; }
78     a:link { color: #900; background-color: transparent; }
79     a:visited { color: #633; background-color: transparent; }
80     a:active { color: #633; background-color: transparent; }
81    
82     p { margin-left: 2em; margin-right: 2em; }
83     p.copyright { font-size: x-small; }
84     p.toc { font-size: small; font-weight: bold; margin-left: 3em; }
85     table.toc { margin: 0 0 0 3em; padding: 0; border: 0; vertical-align: text-top; }
86     td.toc { font-size: small; font-weight: bold; vertical-align: text-top; }
87    
88     ol.text { margin-left: 2em; margin-right: 2em; }
89     ul.text { margin-left: 2em; margin-right: 2em; }
90     li { margin-left: 3em; }
91    
92     /* RFC-2629 <spanx>s and <artwork>s. */
93     em { font-style: italic; }
94     strong { font-weight: bold; }
95     dfn { font-weight: bold; font-style: normal; }
96     cite { font-weight: normal; font-style: normal; }
97     tt { color: #036; }
98     tt, pre, pre dfn, pre em, pre cite, pre span {
99     font-family: "Courier New", Courier, monospace; font-size: small;
100     }
101     pre {
102     text-align: left; padding: 4px;
103     color: #000; background-color: #CCC;
104     }
105     pre dfn { color: #900; }
106     pre em { color: #66F; background-color: #FFC; font-weight: normal; }
107     pre .key { color: #33C; font-weight: bold; }
108     pre .id { color: #900; }
109     pre .str { color: #000; background-color: #CFF; }
110     pre .val { color: #066; }
111     pre .rep { color: #909; }
112     pre .oth { color: #000; background-color: #FCF; }
113     pre .err { background-color: #FCC; }
114    
115     /* RFC-2629 <texttable>s. */
116     table.all, table.full, table.headers, table.none {
117     font-size: small; text-align: center; border-width: 2px;
118     vertical-align: top; border-collapse: collapse;
119     }
120     table.all, table.full { border-style: solid; border-color: black; }
121     table.headers, table.none { border-style: none; }
122     th {
123     font-weight: bold; border-color: black;
124     border-width: 2px 2px 3px 2px;
125     }
126     table.all th, table.full th { border-style: solid; }
127     table.headers th { border-style: none none solid none; }
128     table.none th { border-style: none; }
129     table.all td {
130     border-style: solid; border-color: #333;
131     border-width: 1px 2px;
132     }
133     table.full td, table.headers td, table.none td { border-style: none; }
134    
135     hr { height: 1px; }
136     hr.insert {
137     width: 80%; border-style: none; border-width: 0;
138     color: #CCC; background-color: #CCC;
139     }
140     --></style>
141     </head>
142     <body>
143     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
144     <table summary="layout" width="66%" border="0" cellpadding="0" cellspacing="0"><tr><td><table summary="layout" width="100%" border="0" cellpadding="2" cellspacing="1">
145     <tr><td class="header">LinuxSampler Developers</td><td class="header">C. Schoenebeck</td></tr>
146     <tr><td class="header">Internet-Draft</td><td class="header">Interessengemeinschaft Software</td></tr>
147     <tr><td class="header">Intended status: Standards Track</td><td class="header">Engineering e. V.</td></tr>
148     <tr><td class="header">Expires: April 17, 2008</td><td class="header">October 15, 2007</td></tr>
149     </table></td></tr></table>
150     <h1><br />LinuxSampler Control Protocol<br />LSCP 1.2</h1>
151    
152     <h3>Status of this Memo</h3>
153     <p>
154     By submitting this Internet-Draft,
155     each author represents that any applicable patent or other IPR claims of which
156     he or she is aware have been or will be disclosed,
157     and any of which he or she becomes aware will be disclosed,
158     in accordance with Section&nbsp;6 of BCP&nbsp;79.</p>
159     <p>
160     Internet-Drafts are working documents of the Internet Engineering
161     Task Force (IETF), its areas, and its working groups.
162     Note that other groups may also distribute working documents as
163     Internet-Drafts.</p>
164     <p>
165     Internet-Drafts are draft documents valid for a maximum of six months
166     and may be updated, replaced, or obsoleted by other documents at any time.
167     It is inappropriate to use Internet-Drafts as reference material or to cite
168     them other than as &ldquo;work in progress.&rdquo;</p>
169     <p>
170     The list of current Internet-Drafts can be accessed at
171     <a href='http://www.ietf.org/ietf/1id-abstracts.txt'>http://www.ietf.org/ietf/1id-abstracts.txt</a>.</p>
172     <p>
173     The list of Internet-Draft Shadow Directories can be accessed at
174     <a href='http://www.ietf.org/shadow.html'>http://www.ietf.org/shadow.html</a>.</p>
175     <p>
176     This Internet-Draft will expire on April 17, 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 CHANNEL 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 CHANNEL 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>CHANNEL SP 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='#GET DB_INSTRUMENT_DIRECTORY INFO'>"GET DB_INSTRUMENT_DIRECTORY INFO"<span> (</span><span class='info'>Getting instrument directory information</span><span>)</span></a>
10417     </p>
10418     <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>
10419     </p>
10420     <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>
10421     </p>
10422     <p><a class='info' href='#FIND DB_INSTRUMENT_DIRECTORIES'>"FIND DB_INSTRUMENT_DIRECTORIES"<span> (</span><span class='info'>Finding directories</span><span>)</span></a>
10423     </p>
10424     <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>
10425     </p>
10426     <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>
10427     </p>
10428     <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>
10429     </p>
10430     <p><a class='info' href='#FIND DB_INSTRUMENTS'>"FIND DB_INSTRUMENTS"<span> (</span><span class='info'>Finding instruments</span><span>)</span></a>
10431     </p>
10432     </blockquote><p>
10433     Please note that these lists are manually maintained. If you
10434     find a command that also supports escape sequences we forgot to
10435     mention here, please report it!
10436    
10437     </p>
10438     <a name="events"></a><br /><hr />
10439     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10440     <a name="rfc.section.8"></a><h3>8.&nbsp;
10441     Events</h3>
10442    
10443     <p>This chapter will describe all currently defined events supported by LinuxSampler.
10444     </p>
10445     <a name="SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT"></a><br /><hr />
10446     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10447     <a name="rfc.section.8.1"></a><h3>8.1.&nbsp;
10448     Number of audio output devices changed</h3>
10449    
10450     <p>Client may want to be notified when the total number of audio output devices on the
10451     back-end changes by issuing the following command:
10452     </p>
10453     <p>
10454     </p>
10455     <blockquote class="text">
10456     <p>SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT
10457     </p>
10458     </blockquote><p>
10459    
10460     </p>
10461     <p>Server will start sending the following notification messages:
10462     </p>
10463     <p>
10464     </p>
10465     <blockquote class="text">
10466     <p>"NOTIFY:AUDIO_OUTPUT_DEVICE_COUNT:&lt;devices&gt;"
10467     </p>
10468     </blockquote><p>
10469    
10470     </p>
10471     <p>where &lt;devices&gt; will be replaced by the new number
10472     of audio output devices.
10473     </p>
10474     <a name="SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO"></a><br /><hr />
10475     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10476     <a name="rfc.section.8.2"></a><h3>8.2.&nbsp;
10477     Audio output device's settings changed</h3>
10478    
10479     <p>Client may want to be notified when changes were made to audio output devices on the
10480     back-end by issuing the following command:
10481     </p>
10482     <p>
10483     </p>
10484     <blockquote class="text">
10485     <p>SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO
10486     </p>
10487     </blockquote><p>
10488    
10489     </p>
10490     <p>Server will start sending the following notification messages:
10491     </p>
10492     <p>
10493     </p>
10494     <blockquote class="text">
10495     <p>"NOTIFY:AUDIO_OUTPUT_DEVICE_INFO:&lt;device-id&gt;"
10496     </p>
10497     </blockquote><p>
10498    
10499     </p>
10500     <p>where &lt;device-id&gt; will be replaced by the numerical ID of the audio output device,
10501     which settings has been changed. The front-end will have to send
10502     the respective command to actually get the audio output device info. Because these messages
10503     will be triggered by LSCP commands issued by other clients rather than real
10504     time events happening on the server, it is believed that an empty notification
10505     message is sufficient here.
10506     </p>
10507     <a name="SUBSCRIBE MIDI_INPUT_DEVICE_COUNT"></a><br /><hr />
10508     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10509     <a name="rfc.section.8.3"></a><h3>8.3.&nbsp;
10510     Number of MIDI input devices changed</h3>
10511    
10512     <p>Client may want to be notified when the total number of MIDI input devices on the
10513     back-end changes by issuing the following command:
10514     </p>
10515     <p>
10516     </p>
10517     <blockquote class="text">
10518     <p>SUBSCRIBE MIDI_INPUT_DEVICE_COUNT
10519     </p>
10520     </blockquote><p>
10521    
10522     </p>
10523     <p>Server will start sending the following notification messages:
10524     </p>
10525     <p>
10526     </p>
10527     <blockquote class="text">
10528     <p>"NOTIFY:MIDI_INPUT_DEVICE_COUNT:&lt;devices&gt;"
10529     </p>
10530     </blockquote><p>
10531    
10532     </p>
10533     <p>where &lt;devices&gt; will be replaced by the new number
10534     of MIDI input devices.
10535     </p>
10536     <a name="SUBSCRIBE MIDI_INPUT_DEVICE_INFO"></a><br /><hr />
10537     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10538     <a name="rfc.section.8.4"></a><h3>8.4.&nbsp;
10539     MIDI input device's settings changed</h3>
10540    
10541     <p>Client may want to be notified when changes were made to MIDI input devices on the
10542     back-end by issuing the following command:
10543     </p>
10544     <p>
10545     </p>
10546     <blockquote class="text">
10547     <p>SUBSCRIBE MIDI_INPUT_DEVICE_INFO
10548     </p>
10549     </blockquote><p>
10550    
10551     </p>
10552     <p>Server will start sending the following notification messages:
10553     </p>
10554     <p>
10555     </p>
10556     <blockquote class="text">
10557     <p>"NOTIFY:MIDI_INPUT_DEVICE_INFO:&lt;device-id&gt;"
10558     </p>
10559     </blockquote><p>
10560    
10561     </p>
10562     <p>where &lt;device-id&gt; will be replaced by the numerical ID of the MIDI input device,
10563     which settings has been changed. The front-end will have to send
10564     the respective command to actually get the MIDI input device info. Because these messages
10565     will be triggered by LSCP commands issued by other clients rather than real
10566     time events happening on the server, it is believed that an empty notification
10567     message is sufficient here.
10568     </p>
10569     <a name="SUBSCRIBE CHANNEL_COUNT"></a><br /><hr />
10570     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10571     <a name="rfc.section.8.5"></a><h3>8.5.&nbsp;
10572     Number of sampler channels changed</h3>
10573    
10574     <p>Client may want to be notified when the total number of channels on the
10575     back-end changes by issuing the following command:
10576     </p>
10577     <p>
10578     </p>
10579     <blockquote class="text">
10580     <p>SUBSCRIBE CHANNEL_COUNT
10581     </p>
10582     </blockquote><p>
10583    
10584     </p>
10585     <p>Server will start sending the following notification messages:
10586     </p>
10587     <p>
10588     </p>
10589     <blockquote class="text">
10590     <p>"NOTIFY:CHANNEL_COUNT:&lt;channels&gt;"
10591     </p>
10592     </blockquote><p>
10593    
10594     </p>
10595     <p>where &lt;channels&gt; will be replaced by the new number
10596     of sampler channels.
10597     </p>
10598     <a name="SUBSCRIBE VOICE_COUNT"></a><br /><hr />
10599     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10600     <a name="rfc.section.8.6"></a><h3>8.6.&nbsp;
10601     Number of active voices changed</h3>
10602    
10603     <p>Client may want to be notified when the number of voices on the
10604     back-end changes by issuing the following command:
10605     </p>
10606     <p>
10607     </p>
10608     <blockquote class="text">
10609     <p>SUBSCRIBE VOICE_COUNT
10610     </p>
10611     </blockquote><p>
10612    
10613     </p>
10614     <p>Server will start sending the following notification messages:
10615     </p>
10616     <p>
10617     </p>
10618     <blockquote class="text">
10619     <p>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;"
10620     </p>
10621     </blockquote><p>
10622    
10623     </p>
10624     <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
10625     voice count change occurred and &lt;voices&gt; by the new number of
10626     active voices on that channel.
10627     </p>
10628     <a name="SUBSCRIBE STREAM_COUNT"></a><br /><hr />
10629     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10630     <a name="rfc.section.8.7"></a><h3>8.7.&nbsp;
10631     Number of active disk streams changed</h3>
10632    
10633     <p>Client may want to be notified when the number of streams on the back-end
10634     changes by issuing the following command: SUBSCRIBE STREAM_COUNT
10635     </p>
10636     <p>
10637     </p>
10638     <blockquote class="text">
10639     <p>SUBSCRIBE STREAM_COUNT
10640     </p>
10641     </blockquote><p>
10642    
10643     </p>
10644     <p>Server will start sending the following notification messages:
10645     </p>
10646     <p>
10647     </p>
10648     <blockquote class="text">
10649     <p>"NOTIFY:STREAM_COUNT:&lt;sampler-channel&gt; &lt;streams&gt;"
10650     </p>
10651     </blockquote><p>
10652    
10653     </p>
10654     <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
10655     stream count change occurred and &lt;streams&gt; by the new number of
10656     active disk streams on that channel.
10657     </p>
10658     <a name="SUBSCRIBE BUFFER_FILL"></a><br /><hr />
10659     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10660     <a name="rfc.section.8.8"></a><h3>8.8.&nbsp;
10661     Disk stream buffer fill state changed</h3>
10662    
10663     <p>Client may want to be notified when the buffer fill state of a disk stream
10664     on the back-end changes by issuing the following command:
10665     </p>
10666     <p>
10667     </p>
10668     <blockquote class="text">
10669     <p>SUBSCRIBE BUFFER_FILL
10670     </p>
10671     </blockquote><p>
10672    
10673     </p>
10674     <p>Server will start sending the following notification messages:
10675     </p>
10676     <p>
10677     </p>
10678     <blockquote class="text">
10679     <p>"NOTIFY:BUFFER_FILL:&lt;sampler-channel&gt; &lt;fill-data&gt;"
10680     </p>
10681     </blockquote><p>
10682    
10683     </p>
10684     <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
10685     buffer fill state change occurred on and &lt;fill-data&gt; will be replaced by the
10686     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>
10687     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.
10688     </p>
10689     <a name="SUBSCRIBE CHANNEL_INFO"></a><br /><hr />
10690     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10691     <a name="rfc.section.8.9"></a><h3>8.9.&nbsp;
10692     Channel information changed</h3>
10693    
10694     <p>Client may want to be notified when changes were made to sampler channels on the
10695     back-end by issuing the following command:
10696     </p>
10697     <p>
10698     </p>
10699     <blockquote class="text">
10700     <p>SUBSCRIBE CHANNEL_INFO
10701     </p>
10702     </blockquote><p>
10703    
10704     </p>
10705     <p>Server will start sending the following notification messages:
10706     </p>
10707     <p>
10708     </p>
10709     <blockquote class="text">
10710     <p>"NOTIFY:CHANNEL_INFO:&lt;sampler-channel&gt;"
10711     </p>
10712     </blockquote><p>
10713    
10714     </p>
10715     <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
10716     channel info change occurred. The front-end will have to send
10717     the respective command to actually get the channel info. Because these messages
10718     will be triggered by LSCP commands issued by other clients rather than real
10719     time events happening on the server, it is believed that an empty notification
10720     message is sufficient here.
10721     </p>
10722     <a name="SUBSCRIBE FX_SEND_COUNT"></a><br /><hr />
10723     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10724     <a name="rfc.section.8.10"></a><h3>8.10.&nbsp;
10725     Number of effect sends changed</h3>
10726    
10727     <p>Client may want to be notified when the number of effect sends on
10728     a particular sampler channel is changed by issuing the following command:
10729     </p>
10730     <p>
10731     </p>
10732     <blockquote class="text">
10733     <p>SUBSCRIBE FX_SEND_COUNT
10734     </p>
10735     </blockquote><p>
10736    
10737     </p>
10738     <p>Server will start sending the following notification messages:
10739     </p>
10740     <p>
10741     </p>
10742     <blockquote class="text">
10743     <p>"NOTIFY:FX_SEND_COUNT:&lt;channel-id&gt; &lt;fx-sends&gt;"
10744     </p>
10745     </blockquote><p>
10746    
10747     </p>
10748     <p>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
10749     channel, on which the effect sends number is changed and &lt;fx-sends&gt; will
10750     be replaced by the new number of effect sends on that channel.
10751     </p>
10752     <a name="SUBSCRIBE FX_SEND_INFO"></a><br /><hr />
10753     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10754     <a name="rfc.section.8.11"></a><h3>8.11.&nbsp;
10755     Effect send information changed</h3>
10756    
10757     <p>Client may want to be notified when changes were made to effect sends on a
10758     a particular sampler channel by issuing the following command:
10759     </p>
10760     <p>
10761     </p>
10762     <blockquote class="text">
10763     <p>SUBSCRIBE FX_SEND_INFO
10764     </p>
10765     </blockquote><p>
10766    
10767     </p>
10768     <p>Server will start sending the following notification messages:
10769     </p>
10770     <p>
10771     </p>
10772     <blockquote class="text">
10773     <p>"NOTIFY:FX_SEND_INFO:&lt;channel-id&gt; &lt;fx-send-id&gt;"
10774     </p>
10775     </blockquote><p>
10776    
10777     </p>
10778     <p>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
10779     channel, on which an effect send entity is changed and &lt;fx-send-id&gt; will
10780     be replaced by the numerical ID of the changed effect send.
10781     </p>
10782     <a name="SUBSCRIBE TOTAL_VOICE_COUNT"></a><br /><hr />
10783     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10784     <a name="rfc.section.8.12"></a><h3>8.12.&nbsp;
10785     Total number of active voices changed</h3>
10786    
10787     <p>Client may want to be notified when the total number of voices on the
10788     back-end changes by issuing the following command:
10789     </p>
10790     <p>
10791     </p>
10792     <blockquote class="text">
10793     <p>SUBSCRIBE TOTAL_VOICE_COUNT
10794     </p>
10795     </blockquote><p>
10796    
10797     </p>
10798     <p>Server will start sending the following notification messages:
10799     </p>
10800     <p>
10801     </p>
10802     <blockquote class="text">
10803     <p>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;"
10804     </p>
10805     </blockquote><p>
10806    
10807     </p>
10808     <p>where &lt;voices&gt; will be replaced by the new number of
10809     all currently active voices.
10810     </p>
10811     <a name="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT"></a><br /><hr />
10812     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10813     <a name="rfc.section.8.13"></a><h3>8.13.&nbsp;
10814     Number of MIDI instrument maps changed</h3>
10815    
10816     <p>Client may want to be notified when the number of MIDI instrument maps on the
10817     back-end changes by issuing the following command:
10818     </p>
10819     <p>
10820     </p>
10821     <blockquote class="text">
10822     <p>SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT
10823     </p>
10824     </blockquote><p>
10825    
10826     </p>
10827     <p>Server will start sending the following notification messages:
10828     </p>
10829     <p>
10830     </p>
10831     <blockquote class="text">
10832     <p>"NOTIFY:MIDI_INSTRUMENT_MAP_COUNT:&lt;maps&gt;"
10833     </p>
10834     </blockquote><p>
10835    
10836     </p>
10837     <p>where &lt;maps&gt; will be replaced by the new number
10838     of MIDI instrument maps.
10839     </p>
10840     <a name="SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO"></a><br /><hr />
10841     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10842     <a name="rfc.section.8.14"></a><h3>8.14.&nbsp;
10843     MIDI instrument map information changed</h3>
10844    
10845     <p>Client may want to be notified when changes were made to MIDI instrument maps on the
10846     back-end by issuing the following command:
10847     </p>
10848     <p>
10849     </p>
10850     <blockquote class="text">
10851     <p>SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO
10852     </p>
10853     </blockquote><p>
10854    
10855     </p>
10856     <p>Server will start sending the following notification messages:
10857     </p>
10858     <p>
10859     </p>
10860     <blockquote class="text">
10861     <p>"NOTIFY:MIDI_INSTRUMENT_MAP_INFO:&lt;map-id&gt;"
10862     </p>
10863     </blockquote><p>
10864    
10865     </p>
10866     <p>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
10867     for which information changes occurred. The front-end will have to send
10868     the respective command to actually get the MIDI instrument map info. Because these messages
10869     will be triggered by LSCP commands issued by other clients rather than real
10870     time events happening on the server, it is believed that an empty notification
10871     message is sufficient here.
10872     </p>
10873     <a name="SUBSCRIBE MIDI_INSTRUMENT_COUNT"></a><br /><hr />
10874     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10875     <a name="rfc.section.8.15"></a><h3>8.15.&nbsp;
10876     Number of MIDI instruments changed</h3>
10877    
10878     <p>Client may want to be notified when the number of MIDI instrument maps on the
10879     back-end changes by issuing the following command:
10880     </p>
10881     <p>
10882     </p>
10883     <blockquote class="text">
10884     <p>SUBSCRIBE MIDI_INSTRUMENT_COUNT
10885     </p>
10886     </blockquote><p>
10887    
10888     </p>
10889     <p>Server will start sending the following notification messages:
10890     </p>
10891     <p>
10892     </p>
10893     <blockquote class="text">
10894     <p>"NOTIFY:MIDI_INSTRUMENT_COUNT:&lt;map-id&gt; &lt;instruments&gt;"
10895     </p>
10896     </blockquote><p>
10897    
10898     </p>
10899     <p>where &lt;map-id&gt; is the numerical ID of the MIDI instrument map, in which
10900     the nuber of instruments has changed and &lt;instruments&gt; will be replaced by
10901     the new number of MIDI instruments in the specified map.
10902     </p>
10903     <a name="SUBSCRIBE MIDI_INSTRUMENT_INFO"></a><br /><hr />
10904     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10905     <a name="rfc.section.8.16"></a><h3>8.16.&nbsp;
10906     MIDI instrument information changed</h3>
10907    
10908     <p>Client may want to be notified when changes were made to MIDI instruments on the
10909     back-end by issuing the following command:
10910     </p>
10911     <p>
10912     </p>
10913     <blockquote class="text">
10914     <p>SUBSCRIBE MIDI_INSTRUMENT_INFO
10915     </p>
10916     </blockquote><p>
10917    
10918     </p>
10919     <p>Server will start sending the following notification messages:
10920     </p>
10921     <p>
10922     </p>
10923     <blockquote class="text">
10924     <p>"NOTIFY:MIDI_INSTRUMENT_INFO:&lt;map-id&gt; &lt;bank&gt; &lt;program&gt;"
10925     </p>
10926     </blockquote><p>
10927    
10928     </p>
10929     <p>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
10930     in which a MIDI instrument is changed. &lt;bank&gt; and &lt;program&gt; specifies
10931     the location of the changed MIDI instrument in the map. The front-end will have to send
10932     the respective command to actually get the MIDI instrument info. Because these messages
10933     will be triggered by LSCP commands issued by other clients rather than real
10934     time events happening on the server, it is believed that an empty notification
10935     message is sufficient here.
10936     </p>
10937     <a name="SUBSCRIBE GLOBAL_INFO"></a><br /><hr />
10938     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10939     <a name="rfc.section.8.17"></a><h3>8.17.&nbsp;
10940     Global settings changed</h3>
10941    
10942     <p>Client may want to be notified when changes to the global settings
10943     of the sampler were made by issuing the following command:
10944     </p>
10945     <p>
10946     </p>
10947     <blockquote class="text">
10948     <p>SUBSCRIBE GLOBAL_INFO
10949     </p>
10950     </blockquote><p>
10951    
10952     </p>
10953     <p>Server will start sending the following types of notification messages:
10954     </p>
10955     <p>
10956     </p>
10957     <blockquote class="text">
10958     <p>"NOTIFY:GLOBAL_INFO:VOLUME &lt;volume&gt;" - Notifies that the
10959     golbal volume of the sampler is changed, where &lt;volume&gt; will be
10960     replaced by the optional dotted floating point value, reflecting the
10961     new global volume parameter.
10962     </p>
10963     </blockquote><p>
10964    
10965     </p>
10966     <a name="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT"></a><br /><hr />
10967     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10968     <a name="rfc.section.8.18"></a><h3>8.18.&nbsp;
10969     Number of database instrument directories changed</h3>
10970    
10971     <p>Client may want to be notified when the number of instrument
10972     directories in a particular directory in the instruments database
10973     is changed by issuing the following command:
10974     </p>
10975     <p>
10976     </p>
10977     <blockquote class="text">
10978     <p>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT
10979     </p>
10980     </blockquote><p>
10981    
10982     </p>
10983     <p>Server will start sending the following notification messages:
10984     </p>
10985     <p>
10986     </p>
10987     <blockquote class="text">
10988     <p>"NOTIFY:DB_INSTRUMENT_DIRECTORY_COUNT:&lt;dir-path&gt;"
10989     </p>
10990     </blockquote><p>
10991    
10992     </p>
10993     <p>where &lt;dir-path&gt; will be replaced by the absolute path
10994     name of the directory in the instruments database,
10995     in which the number of directories is changed.
10996     </p>
10997     <p>Note that when a non-empty directory is removed, this event
10998     is not sent for the subdirectories in that directory.
10999     </p>
11000     <a name="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO"></a><br /><hr />
11001     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11002     <a name="rfc.section.8.19"></a><h3>8.19.&nbsp;
11003     Database instrument directory information changed</h3>
11004    
11005     <p>Client may want to be notified when changes were made to directories
11006     in the instruments database by issuing the following command:
11007     </p>
11008     <p>
11009     </p>
11010     <blockquote class="text">
11011     <p>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO
11012     </p>
11013     </blockquote><p>
11014    
11015     </p>
11016     <p>Server will start sending the following notification messages:
11017     </p>
11018     <p>
11019     </p>
11020     <blockquote class="text">
11021     <p>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:&lt;dir-path&gt;"
11022     </p>
11023     </blockquote><p>
11024    
11025     </p>
11026     <p>where &lt;dir-path&gt; will be replaced by the absolute path name
11027     of the directory, for which information changes occurred. The front-end will have to send
11028     the respective command to actually get the updated directory info. Because these messages
11029     will be triggered by LSCP commands issued by other clients rather than real
11030     time events happening on the server, it is believed that an empty notification
11031     message is sufficient here.
11032     </p>
11033     <p>
11034     </p>
11035     <blockquote class="text">
11036     <p>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:NAME &lt;old-dir-path&gt; &lt;new-name&gt;"
11037     </p>
11038     </blockquote><p>
11039    
11040     </p>
11041     <p>where &lt;old-dir-path&gt; is the old absolute path name of the directory
11042     (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
11043     the new name of the directory, encapsulated into apostrophes.
11044     </p>
11045     <a name="SUBSCRIBE DB_INSTRUMENT_COUNT"></a><br /><hr />
11046     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11047     <a name="rfc.section.8.20"></a><h3>8.20.&nbsp;
11048     Number of database instruments changed</h3>
11049    
11050     <p>Client may want to be notified when the number of instruments
11051     in a particular directory in the instruments database
11052     is changed by issuing the following command:
11053     </p>
11054     <p>
11055     </p>
11056     <blockquote class="text">
11057     <p>SUBSCRIBE DB_INSTRUMENT_COUNT
11058     </p>
11059     </blockquote><p>
11060    
11061     </p>
11062     <p>Server will start sending the following notification messages:
11063     </p>
11064     <p>
11065     </p>
11066     <blockquote class="text">
11067     <p>"NOTIFY:DB_INSTRUMENT_COUNT:&lt;dir-path&gt;"
11068     </p>
11069     </blockquote><p>
11070    
11071     </p>
11072     <p>where &lt;dir-path&gt; will be replaced by the absolute path
11073     name of the directory in the instruments database,
11074     in which the number of instruments is changed.
11075     </p>
11076     <p>Note that when a non-empty directory is removed, this event
11077     is not sent for the instruments in that directory.
11078     </p>
11079     <a name="SUBSCRIBE DB_INSTRUMENT_INFO"></a><br /><hr />
11080     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11081     <a name="rfc.section.8.21"></a><h3>8.21.&nbsp;
11082     Database instrument information changed</h3>
11083    
11084     <p>Client may want to be notified when changes were made to instruments
11085     in the instruments database by issuing the following command:
11086     </p>
11087     <p>
11088     </p>
11089     <blockquote class="text">
11090     <p>SUBSCRIBE DB_INSTRUMENT_INFO
11091     </p>
11092     </blockquote><p>
11093    
11094     </p>
11095     <p>Server will start sending the following notification messages:
11096     </p>
11097     <p>
11098     </p>
11099     <blockquote class="text">
11100     <p>"NOTIFY:DB_INSTRUMENT_INFO:&lt;instr-path&gt;"
11101     </p>
11102     </blockquote><p>
11103    
11104     </p>
11105     <p>where &lt;instr-path&gt; will be replaced by the absolute path name
11106     of the instrument, which settings are changed. The front-end will have to send
11107     the respective command to actually get the updated directory info. Because these messages
11108     will be triggered by LSCP commands issued by other clients rather than real
11109     time events happening on the server, it is believed that an empty notification
11110     message is sufficient here.
11111     </p>
11112     <p>
11113     </p>
11114     <blockquote class="text">
11115     <p>"NOTIFY:DB_INSTRUMENT_INFO:NAME &lt;old-instr-path&gt; &lt;new-name&gt;"
11116     </p>
11117     </blockquote><p>
11118    
11119     </p>
11120     <p>where &lt;old-instr-path&gt; is the old absolute path name of the instrument
11121     (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
11122     the new name of the instrument, encapsulated into apostrophes.
11123     </p>
11124     <a name="SUBSCRIBE DB_INSTRUMENTS_JOB_INFO"></a><br /><hr />
11125     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11126     <a name="rfc.section.8.22"></a><h3>8.22.&nbsp;
11127     Database job status information changed</h3>
11128    
11129     <p>Client may want to be notified when the status of particular database
11130     instruments job is changed by issuing the following command:
11131     </p>
11132     <p>
11133     </p>
11134     <blockquote class="text">
11135     <p>SUBSCRIBE DB_INSTRUMENTS_JOB_INFO
11136     </p>
11137     </blockquote><p>
11138    
11139     </p>
11140     <p>Server will start sending the following notification messages:
11141     </p>
11142     <p>
11143     </p>
11144     <blockquote class="text">
11145     <p>"NOTIFY:DB_INSTRUMENTS_JOB_INFO:&lt;job-id&gt;"
11146     </p>
11147     </blockquote><p>
11148    
11149     </p>
11150     <p>where &lt;job-id&gt; will be replaced by the numerical ID of the job,
11151     which status is changed. The front-end will have to send the respective
11152     command to actually get the status info. Because these messages
11153     will be triggered by LSCP commands issued by other clients rather than real
11154     time events happening on the server, it is believed that an empty notification
11155     message is sufficient here.
11156     </p>
11157     <a name="SUBSCRIBE MISCELLANEOUS"></a><br /><hr />
11158     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11159     <a name="rfc.section.8.23"></a><h3>8.23.&nbsp;
11160     Miscellaneous and debugging events</h3>
11161    
11162     <p>Client may want to be notified of miscellaneous and debugging events occurring at
11163     the server by issuing the following command:
11164     </p>
11165     <p>
11166     </p>
11167     <blockquote class="text">
11168     <p>SUBSCRIBE MISCELLANEOUS
11169     </p>
11170     </blockquote><p>
11171    
11172     </p>
11173     <p>Server will start sending the following notification messages:
11174     </p>
11175     <p>
11176     </p>
11177     <blockquote class="text">
11178     <p>"NOTIFY:MISCELLANEOUS:&lt;string&gt;"
11179     </p>
11180     </blockquote><p>
11181    
11182     </p>
11183     <p>where &lt;string&gt; will be replaced by whatever data server
11184     wants to send to the client. Client MAY display this data to the
11185     user AS IS to facilitate debugging.
11186     </p>
11187     <a name="anchor14"></a><br /><hr />
11188     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11189     <a name="rfc.section.9"></a><h3>9.&nbsp;
11190     Security Considerations</h3>
11191    
11192     <p>As there is so far no method of authentication and authorization
11193     defined and so not required for a client applications to succeed to
11194     connect, running LinuxSampler might be a security risk for the host
11195     system the LinuxSampler instance is running on.
11196     </p>
11197     <a name="anchor15"></a><br /><hr />
11198     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11199     <a name="rfc.section.10"></a><h3>10.&nbsp;
11200     Acknowledgments</h3>
11201    
11202     <p>This document has benefited greatly from the comments of the
11203     following people, discussed on the LinuxSampler developer's mailing
11204     list:
11205     </p>
11206     <p>
11207     </p>
11208     <blockquote class="text">
11209     <p>Rui Nuno Capela
11210     </p>
11211     <p>Vladimir Senkov
11212     </p>
11213     <p>Mark Knecht
11214     </p>
11215     <p>Grigor Iliev
11216     </p>
11217     </blockquote><p>
11218    
11219     </p>
11220     <a name="rfc.references1"></a><br /><hr />
11221     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11222     <h3>11.&nbsp;References</h3>
11223     <table width="99%" border="0">
11224     <tr><td class="author-text" valign="top"><a name="RFC20">[RFC20]</a></td>
11225     <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>
11226     <tr><td class="author-text" valign="top"><a name="RFC2119">[RFC2119]</a></td>
11227     <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>
11228     <tr><td class="author-text" valign="top"><a name="RFC2234">[RFC2234]</a></td>
11229     <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>
11230     <tr><td class="author-text" valign="top"><a name="RFC793">[RFC793]</a></td>
11231     <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>
11232     </table>
11233    
11234     <a name="rfc.authors"></a><br /><hr />
11235     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11236     <h3>Author's Address</h3>
11237     <table width="99%" border="0" cellpadding="0" cellspacing="0">
11238     <tr><td class="author-text">&nbsp;</td>
11239     <td class="author-text">C.
11240     Schoenebeck</td></tr>
11241     <tr><td class="author-text">&nbsp;</td>
11242     <td class="author-text">Interessengemeinschaft Software Engineering e. V.</td></tr>
11243     <tr><td class="author-text">&nbsp;</td>
11244     <td class="author-text">Max-Planck-Str. 39</td></tr>
11245     <tr><td class="author-text">&nbsp;</td>
11246     <td class="author-text">74081 Heilbronn</td></tr>
11247     <tr><td class="author-text">&nbsp;</td>
11248     <td class="author-text">Germany</td></tr>
11249     <tr><td class="author" align="right">Email:&nbsp;</td>
11250     <td class="author-text"><a href="mailto:schoenebeck at software minus engineering dot org">schoenebeck at software minus engineering dot org</a></td></tr>
11251     </table>
11252     <a name="rfc.copyright"></a><br /><hr />
11253     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11254     <h3>Full Copyright Statement</h3>
11255     <p class='copyright'>
11256     Copyright &copy; The IETF Trust (2007).</p>
11257     <p class='copyright'>
11258     This document is subject to the rights,
11259     licenses and restrictions contained in BCP&nbsp;78,
11260     and except as set forth therein,
11261     the authors retain all their rights.</p>
11262     <p class='copyright'>
11263     This document and the information contained herein are provided
11264     on an &ldquo;AS IS&rdquo; basis and THE CONTRIBUTOR,
11265     THE ORGANIZATION HE/SHE REPRESENTS
11266     OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST
11267     AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES,
11268     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT
11269     THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY
11270     IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
11271     PURPOSE.</p>
11272     <h3>Intellectual Property</h3>
11273     <p class='copyright'>
11274     The IETF takes no position regarding the validity or scope of any
11275     Intellectual Property Rights or other rights that might be claimed
11276     to pertain to the implementation or use of the technology
11277     described in this document or the extent to which any license
11278     under such rights might or might not be available; nor does it
11279     represent that it has made any independent effort to identify any
11280     such rights.
11281     Information on the procedures with respect to
11282     rights in RFC documents can be found in BCP&nbsp;78 and BCP&nbsp;79.</p>
11283     <p class='copyright'>
11284     Copies of IPR disclosures made to the IETF Secretariat and any
11285     assurances of licenses to be made available,
11286     or the result of an attempt made to obtain a general license or
11287     permission for the use of such proprietary rights by implementers or
11288     users of this specification can be obtained from the IETF on-line IPR
11289     repository at <a href='http://www.ietf.org/ipr'>http://www.ietf.org/ipr</a>.</p>
11290     <p class='copyright'>
11291     The IETF invites any interested party to bring to its attention
11292     any copyrights,
11293     patents or patent applications,
11294     or other
11295     proprietary rights that may cover technology that may be required
11296     to implement this standard.
11297     Please address the information to the IETF at <a href='mailto:ietf-ipr@ietf.org'>ietf-ipr@ietf.org</a>.</p>
11298     <h3>Acknowledgment</h3>
11299     <p class='copyright'>
11300     Funding for the RFC Editor function is provided by
11301     the IETF Administrative Support Activity (IASA).</p>
11302     </body></html>
11303    
  ViewVC Help
Powered by ViewVC