/[svn]/web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.html
ViewVC logotype

Annotation of /web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1801 - (hide annotations) (download) (as text)
Sun Dec 7 01:31:29 2008 UTC (15 years, 3 months ago) by schoenebeck
File MIME type: text/html
File size: 430573 byte(s)
* updated LSCP specs

1 senoner 542 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 schoenebeck 1430 <html lang="en"><head><title>LinuxSampler Control Protocol</title>
3 senoner 542 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
4 schoenebeck 1430 <meta name="description" content="LinuxSampler Control Protocol">
5 senoner 542 <meta name="keywords" content="LSCP">
6 schoenebeck 1801 <meta name="generator" content="xml2rfc v1.33 (http://xml.resource.org/)">
7 schoenebeck 974 <style type='text/css'><!--
8 iliev 1110 body {
9     font-family: verdana, charcoal, helvetica, arial, sans-serif;
10     font-size: small; color: #000; background-color: #FFF;
11     margin: 2em;
12     }
13 schoenebeck 974 h1, h2, h3, h4, h5, h6 {
14 iliev 1110 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 senoner 542
20 iliev 1110 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 senoner 542
35 iliev 1110 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 senoner 542
46 iliev 1110 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 senoner 542
54 iliev 1110 /* 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 senoner 542
77 iliev 1110 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 senoner 542
82 iliev 1110 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 senoner 542
88 iliev 1110 ol.text { margin-left: 2em; margin-right: 2em; }
89     ul.text { margin-left: 2em; margin-right: 2em; }
90     li { margin-left: 3em; }
91 senoner 542
92 iliev 1110 /* 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 schoenebeck 974 tt, pre, pre dfn, pre em, pre cite, pre span {
99 iliev 1110 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 schoenebeck 708
115 iliev 1110 /* 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 senoner 542
135 iliev 1110 hr { height: 1px; }
136     hr.insert {
137     width: 80%; border-style: none; border-width: 0;
138     color: #CCC; background-color: #CCC;
139     }
140 schoenebeck 974 --></style>
141 senoner 542 </head>
142     <body>
143 schoenebeck 974 <table 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 senoner 542 <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 schoenebeck 974 <tr><td class="header">Intended status: Standards Track</td><td class="header">Engineering e. V.</td></tr>
148 schoenebeck 1801 <tr><td class="header">Expires: June 9, 2009</td><td class="header">December 6, 2008</td></tr>
149 senoner 542 </table></td></tr></table>
150 schoenebeck 1685 <h1><br />LinuxSampler Control Protocol<br />LSCP 1.4</h1>
151 senoner 542
152     <h3>Status of this Memo</h3>
153     <p>
154 schoenebeck 974 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 senoner 542 <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 schoenebeck 708 them other than as &ldquo;work in progress.&rdquo;</p>
169 senoner 542 <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 schoenebeck 1801 This Internet-Draft will expire on June 9, 2009.</p>
177 senoner 542
178     <h3>Abstract</h3>
179    
180     <p>The LinuxSampler Control Protocol (LSCP) is an
181     application-level protocol primarily intended for local and
182 schoenebeck 575 remote controlling the LinuxSampler backend application, which is a
183     sophisticated server-like console application essentially playing
184     back audio samples and manipulating the samples in real time to
185     certain extent.
186 senoner 542 </p><a name="toc"></a><br /><hr />
187     <h3>Table of Contents</h3>
188     <p class="toc">
189     <a href="#anchor1">1.</a>&nbsp;
190     Requirements notation<br />
191 schoenebeck 575 <a href="#LSCP versioning">2.</a>&nbsp;
192     Versioning of this specification<br />
193     <a href="#anchor2">3.</a>&nbsp;
194 senoner 542 Introduction<br />
195 schoenebeck 575 <a href="#anchor3">4.</a>&nbsp;
196 senoner 542 Focus of this protocol<br />
197 schoenebeck 575 <a href="#anchor4">5.</a>&nbsp;
198 senoner 542 Communication Overview<br />
199 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor5">5.1.</a>&nbsp;
200 senoner 542 Request/response communication method<br />
201 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor6">5.1.1.</a>&nbsp;
202 senoner 542 Result format<br />
203 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor7">5.2.</a>&nbsp;
204 senoner 542 Subscribe/notify communication method<br />
205 schoenebeck 575 <a href="#control_commands">6.</a>&nbsp;
206 senoner 542 Description for control commands<br />
207 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor8">6.1.</a>&nbsp;
208 senoner 542 Ignored lines and comments<br />
209 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor9">6.2.</a>&nbsp;
210 senoner 542 Configuring audio drivers<br />
211 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_AUDIO_OUTPUT_DRIVERS">6.2.1.</a>&nbsp;
212 senoner 542 Getting amount of available audio output drivers<br />
213 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">6.2.2.</a>&nbsp;
214 senoner 542 Getting all available audio output drivers<br />
215 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DRIVER INFO">6.2.3.</a>&nbsp;
216 senoner 542 Getting information about a specific audio
217     output driver<br />
218 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO">6.2.4.</a>&nbsp;
219 senoner 542 Getting information about specific audio
220     output driver parameter<br />
221 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CREATE AUDIO_OUTPUT_DEVICE">6.2.5.</a>&nbsp;
222 senoner 542 Creating an audio output device<br />
223 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DESTROY AUDIO_OUTPUT_DEVICE">6.2.6.</a>&nbsp;
224 senoner 542 Destroying an audio output device<br />
225 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DEVICES">6.2.7.</a>&nbsp;
226 senoner 542 Getting all created audio output device count<br />
227 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AUDIO_OUTPUT_DEVICES">6.2.8.</a>&nbsp;
228 senoner 542 Getting all created audio output device list<br />
229 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DEVICE INFO">6.2.9.</a>&nbsp;
230 senoner 542 Getting current settings of an audio output device<br />
231 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET AUDIO_OUTPUT_DEVICE_PARAMETER">6.2.10.</a>&nbsp;
232 senoner 542 Changing settings of audio output devices<br />
233 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_CHANNEL INFO">6.2.11.</a>&nbsp;
234 senoner 542 Getting information about an audio channel<br />
235 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO">6.2.12.</a>&nbsp;
236 senoner 542 Getting information about specific audio channel parameter<br />
237 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET AUDIO_OUTPUT_CHANNEL_PARAMETER">6.2.13.</a>&nbsp;
238 senoner 542 Changing settings of audio output channels<br />
239 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor10">6.3.</a>&nbsp;
240 senoner 542 Configuring MIDI input drivers<br />
241 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_MIDI_INPUT_DRIVERS">6.3.1.</a>&nbsp;
242 senoner 542 Getting amount of available MIDI input drivers<br />
243 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_MIDI_INPUT_DRIVERS">6.3.2.</a>&nbsp;
244 senoner 542 Getting all available MIDI input drivers<br />
245 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DRIVER INFO">6.3.3.</a>&nbsp;
246 senoner 542 Getting information about a specific MIDI input driver<br />
247 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DRIVER_PARAMETER INFO">6.3.4.</a>&nbsp;
248 senoner 542 Getting information about specific MIDI input driver parameter<br />
249 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CREATE MIDI_INPUT_DEVICE">6.3.5.</a>&nbsp;
250 senoner 542 Creating a MIDI input device<br />
251 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DESTROY MIDI_INPUT_DEVICE">6.3.6.</a>&nbsp;
252 senoner 542 Destroying a MIDI input device<br />
253 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DEVICES">6.3.7.</a>&nbsp;
254 senoner 542 Getting all created MIDI input device count<br />
255 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST MIDI_INPUT_DEVICES">6.3.8.</a>&nbsp;
256 senoner 542 Getting all created MIDI input device list<br />
257 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DEVICE INFO">6.3.9.</a>&nbsp;
258 senoner 542 Getting current settings of a MIDI input device<br />
259 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET MIDI_INPUT_DEVICE_PARAMETER">6.3.10.</a>&nbsp;
260 senoner 542 Changing settings of MIDI input devices<br />
261 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_PORT INFO">6.3.11.</a>&nbsp;
262 senoner 542 Getting information about a MIDI port<br />
263 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_PORT_PARAMETER INFO">6.3.12.</a>&nbsp;
264 senoner 542 Getting information about specific MIDI port parameter<br />
265 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET MIDI_INPUT_PORT_PARAMETER">6.3.13.</a>&nbsp;
266 senoner 542 Changing settings of MIDI input ports<br />
267 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor11">6.4.</a>&nbsp;
268 senoner 542 Configuring sampler channels<br />
269 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LOAD INSTRUMENT">6.4.1.</a>&nbsp;
270 senoner 542 Loading an instrument<br />
271 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LOAD ENGINE">6.4.2.</a>&nbsp;
272 senoner 542 Loading a sampler engine<br />
273 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNELS">6.4.3.</a>&nbsp;
274 senoner 542 Getting all created sampler channel count<br />
275 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST CHANNELS">6.4.4.</a>&nbsp;
276 senoner 542 Getting all created sampler channel list<br />
277 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD CHANNEL">6.4.5.</a>&nbsp;
278 senoner 542 Adding a new sampler channel<br />
279 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE CHANNEL">6.4.6.</a>&nbsp;
280 senoner 542 Removing a sampler channel<br />
281 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_ENGINES">6.4.7.</a>&nbsp;
282 senoner 542 Getting amount of available engines<br />
283 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_ENGINES">6.4.8.</a>&nbsp;
284 senoner 542 Getting all available engines<br />
285 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET ENGINE INFO">6.4.9.</a>&nbsp;
286 senoner 542 Getting information about an engine<br />
287 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL INFO">6.4.10.</a>&nbsp;
288 senoner 542 Getting sampler channel information<br />
289 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL VOICE_COUNT">6.4.11.</a>&nbsp;
290 senoner 542 Current number of active voices<br />
291 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL STREAM_COUNT">6.4.12.</a>&nbsp;
292 senoner 542 Current number of active disk streams<br />
293 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL BUFFER_FILL">6.4.13.</a>&nbsp;
294 senoner 542 Current fill state of disk stream buffers<br />
295 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_DEVICE">6.4.14.</a>&nbsp;
296 senoner 542 Setting audio output device<br />
297 schoenebeck 974 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_TYPE">6.4.15.</a>&nbsp;
298 senoner 542 Setting audio output type<br />
299 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_CHANNEL">6.4.16.</a>&nbsp;
300 senoner 542 Setting audio output channel<br />
301 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_DEVICE">6.4.17.</a>&nbsp;
302 senoner 542 Setting MIDI input device<br />
303 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_TYPE">6.4.18.</a>&nbsp;
304 senoner 542 Setting MIDI input type<br />
305 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_PORT">6.4.19.</a>&nbsp;
306 senoner 542 Setting MIDI input port<br />
307 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_CHANNEL">6.4.20.</a>&nbsp;
308 senoner 542 Setting MIDI input channel<br />
309 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL VOLUME">6.4.21.</a>&nbsp;
310 senoner 542 Setting channel volume<br />
311 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MUTE">6.4.22.</a>&nbsp;
312 schoenebeck 708 Muting a sampler channel<br />
313 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL SOLO">6.4.23.</a>&nbsp;
314 schoenebeck 708 Soloing a sampler channel<br />
315 schoenebeck 974 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INSTRUMENT_MAP">6.4.24.</a>&nbsp;
316     Assigning a MIDI instrument map to a sampler channel<br />
317 schoenebeck 1002 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CREATE FX_SEND">6.4.25.</a>&nbsp;
318     Adding an effect send to a sampler channel<br />
319     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DESTROY FX_SEND">6.4.26.</a>&nbsp;
320     Removing an effect send from a sampler channel<br />
321     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET FX_SENDS">6.4.27.</a>&nbsp;
322     Getting amount of effect sends on a sampler channel<br />
323     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST FX_SENDS">6.4.28.</a>&nbsp;
324     Listing all effect sends on a sampler channel<br />
325     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET FX_SEND INFO">6.4.29.</a>&nbsp;
326     Getting effect send information<br />
327 iliev 1137 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET FX_SEND NAME">6.4.30.</a>&nbsp;
328     Changing effect send's name<br />
329     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET FX_SEND AUDIO_OUTPUT_CHANNEL">6.4.31.</a>&nbsp;
330 schoenebeck 1002 Altering effect send's audio routing<br />
331 iliev 1137 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET FX_SEND MIDI_CONTROLLER">6.4.32.</a>&nbsp;
332 schoenebeck 1028 Altering effect send's MIDI controller<br />
333 iliev 1137 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET FX_SEND LEVEL">6.4.33.</a>&nbsp;
334 schoenebeck 1028 Altering effect send's send level<br />
335 iliev 1773 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SEND CHANNEL MIDI_DATA">6.4.34.</a>&nbsp;
336     Sending MIDI messages to sampler channel<br />
337     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#RESET CHANNEL">6.4.35.</a>&nbsp;
338 senoner 542 Resetting a sampler channel<br />
339 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor12">6.5.</a>&nbsp;
340 senoner 542 Controlling connection<br />
341 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE">6.5.1.</a>&nbsp;
342 senoner 542 Register front-end for receiving event messages<br />
343 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#UNSUBSCRIBE">6.5.2.</a>&nbsp;
344 senoner 542 Unregister front-end for not receiving event messages<br />
345 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET ECHO">6.5.3.</a>&nbsp;
346 senoner 542 Enable or disable echo of commands<br />
347 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#QUIT">6.5.4.</a>&nbsp;
348 senoner 542 Close client connection<br />
349 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor13">6.6.</a>&nbsp;
350 senoner 542 Global commands<br />
351 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET TOTAL_VOICE_COUNT">6.6.1.</a>&nbsp;
352     Current number of active voices<br />
353     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET TOTAL_VOICE_COUNT_MAX">6.6.2.</a>&nbsp;
354     Maximum amount of active voices<br />
355 schoenebeck 1572 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET TOTAL_STREAM_COUNT">6.6.3.</a>&nbsp;
356     Current number of active disk streams<br />
357     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#RESET">6.6.4.</a>&nbsp;
358 senoner 542 Reset sampler<br />
359 schoenebeck 1572 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET SERVER INFO">6.6.5.</a>&nbsp;
360 schoenebeck 575 General sampler informations<br />
361 schoenebeck 1572 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET VOLUME">6.6.6.</a>&nbsp;
362 schoenebeck 1006 Getting global volume attenuation<br />
363 schoenebeck 1572 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET VOLUME">6.6.7.</a>&nbsp;
364 schoenebeck 1006 Setting global volume attenuation<br />
365 schoenebeck 1801 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET VOICES">6.6.8.</a>&nbsp;
366     Getting global voice limit<br />
367     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET VOICES">6.6.9.</a>&nbsp;
368     Setting global voice limit<br />
369     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET STREAMS">6.6.10.</a>&nbsp;
370     Getting global disk stream limit<br />
371     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET STREAMS">6.6.11.</a>&nbsp;
372     Setting global disk stream limit<br />
373 schoenebeck 974 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#MIDI Instrument Mapping">6.7.</a>&nbsp;
374 schoenebeck 945 MIDI Instrument Mapping<br />
375 schoenebeck 1390 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD MIDI_INSTRUMENT_MAP">6.7.1.</a>&nbsp;
376 schoenebeck 974 Create a new MIDI instrument map<br />
377     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE MIDI_INSTRUMENT_MAP">6.7.2.</a>&nbsp;
378     Delete one particular or all MIDI instrument maps<br />
379     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENT_MAPS">6.7.3.</a>&nbsp;
380     Get amount of existing MIDI instrument maps<br />
381     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST MIDI_INSTRUMENT_MAPS">6.7.4.</a>&nbsp;
382     Getting all created MIDI instrument maps<br />
383     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENT_MAP INFO">6.7.5.</a>&nbsp;
384     Getting MIDI instrument map information<br />
385     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET MIDI_INSTRUMENT_MAP NAME">6.7.6.</a>&nbsp;
386     Renaming a MIDI instrument map<br />
387     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#MAP MIDI_INSTRUMENT">6.7.7.</a>&nbsp;
388 schoenebeck 945 Create or replace a MIDI instrument map entry<br />
389 schoenebeck 974 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENTS">6.7.8.</a>&nbsp;
390 schoenebeck 945 Getting ammount of MIDI instrument map entries<br />
391 schoenebeck 974 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST MIDI_INSTRUMENTS">6.7.9.</a>&nbsp;
392     Getting indeces of all entries of a MIDI instrument map<br />
393     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#UNMAP MIDI_INSTRUMENT">6.7.10.</a>&nbsp;
394 schoenebeck 945 Remove an entry from the MIDI instrument map<br />
395 schoenebeck 974 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENT INFO">6.7.11.</a>&nbsp;
396 schoenebeck 945 Get current settings of MIDI instrument map entry<br />
397 schoenebeck 974 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CLEAR MIDI_INSTRUMENTS">6.7.12.</a>&nbsp;
398 schoenebeck 945 Clear MIDI instrument map<br />
399 iliev 1162 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#Managing Instruments Database">6.8.</a>&nbsp;
400     Managing Instruments Database<br />
401     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD DB_INSTRUMENT_DIRECTORY">6.8.1.</a>&nbsp;
402     Creating a new instrument directory<br />
403     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE DB_INSTRUMENT_DIRECTORY">6.8.2.</a>&nbsp;
404     Deleting an instrument directory<br />
405     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENT_DIRECTORIES">6.8.3.</a>&nbsp;
406     Getting amount of instrument directories<br />
407     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST DB_INSTRUMENT_DIRECTORIES">6.8.4.</a>&nbsp;
408     Listing all directories in specific directory<br />
409     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENT_DIRECTORY INFO">6.8.5.</a>&nbsp;
410     Getting instrument directory information<br />
411     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET DB_INSTRUMENT_DIRECTORY NAME">6.8.6.</a>&nbsp;
412     Renaming an instrument directory<br />
413     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#MOVE DB_INSTRUMENT_DIRECTORY">6.8.7.</a>&nbsp;
414     Moving an instrument directory<br />
415 iliev 1189 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#COPY DB_INSTRUMENT_DIRECTORY">6.8.8.</a>&nbsp;
416     Copying instrument directories<br />
417     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">6.8.9.</a>&nbsp;
418 iliev 1162 Changing the description of directory<br />
419 iliev 1189 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#FIND DB_INSTRUMENT_DIRECTORIES">6.8.10.</a>&nbsp;
420     Finding directories<br />
421     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD DB_INSTRUMENTS">6.8.11.</a>&nbsp;
422 iliev 1162 Adding instruments to the instruments database<br />
423 iliev 1189 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE DB_INSTRUMENT">6.8.12.</a>&nbsp;
424 iliev 1162 Removing an instrument<br />
425 iliev 1189 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENTS">6.8.13.</a>&nbsp;
426 iliev 1162 Getting amount of instruments<br />
427 iliev 1189 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST DB_INSTRUMENTS">6.8.14.</a>&nbsp;
428 iliev 1162 Listing all instruments in specific directory<br />
429 iliev 1189 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENT INFO">6.8.15.</a>&nbsp;
430 iliev 1162 Getting instrument information<br />
431 iliev 1189 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET DB_INSTRUMENT NAME">6.8.16.</a>&nbsp;
432 iliev 1162 Renaming an instrument<br />
433 iliev 1189 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#MOVE DB_INSTRUMENT">6.8.17.</a>&nbsp;
434 iliev 1162 Moving an instrument<br />
435 iliev 1189 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#COPY DB_INSTRUMENT">6.8.18.</a>&nbsp;
436     Copying instruments<br />
437     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET DB_INSTRUMENT DESCRIPTION">6.8.19.</a>&nbsp;
438 iliev 1162 Changing the description of instrument<br />
439 iliev 1189 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#FIND DB_INSTRUMENTS">6.8.20.</a>&nbsp;
440     Finding instruments<br />
441 iliev 1201 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENTS_JOB INFO">6.8.21.</a>&nbsp;
442     Getting job status information<br />
443 schoenebeck 1363 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#FORMAT INSTRUMENTS_DB">6.8.22.</a>&nbsp;
444     Formatting the instruments database<br />
445 iliev 1731 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#FIND LOST DB_INSTRUMENT_FILES">6.8.23.</a>&nbsp;
446     Checking for lost instrument files<br />
447     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET DB_INSTRUMENT FILE_PATH">6.8.24.</a>&nbsp;
448     Replacing an instrument file<br />
449 schoenebeck 1363 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#editing_instruments">6.9.</a>&nbsp;
450     Editing Instruments<br />
451     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#EDIT INSTRUMENT">6.9.1.</a>&nbsp;
452     Opening an appropriate instrument editor application<br />
453 schoenebeck 1572 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#file_management">6.10.</a>&nbsp;
454     Managing Files<br />
455     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET FILE INSTRUMENTS">6.10.1.</a>&nbsp;
456     Retrieving amount of instruments of a file<br />
457     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST FILE INSTRUMENTS">6.10.2.</a>&nbsp;
458     Retrieving all instruments of a file<br />
459     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET FILE INSTRUMENT INFO">6.10.3.</a>&nbsp;
460     Retrieving informations about one instrument in a file<br />
461 schoenebeck 575 <a href="#command_syntax">7.</a>&nbsp;
462 senoner 542 Command Syntax<br />
463 schoenebeck 1251 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#character_set">7.1.</a>&nbsp;
464     Character Set and Escape Sequences<br />
465 schoenebeck 575 <a href="#events">8.</a>&nbsp;
466 senoner 542 Events<br />
467 iliev 992 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT">8.1.</a>&nbsp;
468     Number of audio output devices changed<br />
469     &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO">8.2.</a>&nbsp;
470     Audio output device's settings changed<br />
471     &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INPUT_DEVICE_COUNT">8.3.</a>&nbsp;
472     Number of MIDI input devices changed<br />
473     &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INPUT_DEVICE_INFO">8.4.</a>&nbsp;
474     MIDI input device's settings changed<br />
475     &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE CHANNEL_COUNT">8.5.</a>&nbsp;
476 senoner 542 Number of sampler channels changed<br />
477 schoenebeck 1685 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE CHANNEL_MIDI">8.6.</a>&nbsp;
478     MIDI data on a sampler channel arrived<br />
479 schoenebeck 1696 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DEVICE_MIDI">8.7.</a>&nbsp;
480     MIDI data on a MIDI input device arrived<br />
481     &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE VOICE_COUNT">8.8.</a>&nbsp;
482 senoner 542 Number of active voices changed<br />
483 schoenebeck 1696 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE STREAM_COUNT">8.9.</a>&nbsp;
484 senoner 542 Number of active disk streams changed<br />
485 schoenebeck 1696 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE BUFFER_FILL">8.10.</a>&nbsp;
486 senoner 542 Disk stream buffer fill state changed<br />
487 schoenebeck 1696 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE CHANNEL_INFO">8.11.</a>&nbsp;
488 senoner 542 Channel information changed<br />
489 schoenebeck 1696 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE FX_SEND_COUNT">8.12.</a>&nbsp;
490 iliev 1110 Number of effect sends changed<br />
491 schoenebeck 1696 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE FX_SEND_INFO">8.13.</a>&nbsp;
492 iliev 1110 Effect send information changed<br />
493 schoenebeck 1696 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE TOTAL_VOICE_COUNT">8.14.</a>&nbsp;
494 schoenebeck 940 Total number of active voices changed<br />
495 schoenebeck 1696 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE TOTAL_STREAM_COUNT">8.15.</a>&nbsp;
496 schoenebeck 1572 Total number of active disk streams changed<br />
497 schoenebeck 1696 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT">8.16.</a>&nbsp;
498 iliev 992 Number of MIDI instrument maps changed<br />
499 schoenebeck 1696 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO">8.17.</a>&nbsp;
500 iliev 992 MIDI instrument map information changed<br />
501 schoenebeck 1696 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_COUNT">8.18.</a>&nbsp;
502 iliev 992 Number of MIDI instruments changed<br />
503 schoenebeck 1696 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_INFO">8.19.</a>&nbsp;
504 iliev 992 MIDI instrument information changed<br />
505 schoenebeck 1696 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE GLOBAL_INFO">8.20.</a>&nbsp;
506 iliev 1110 Global settings changed<br />
507 schoenebeck 1696 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT">8.21.</a>&nbsp;
508 iliev 1162 Number of database instrument directories changed<br />
509 schoenebeck 1696 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO">8.22.</a>&nbsp;
510 iliev 1162 Database instrument directory information changed<br />
511 schoenebeck 1696 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENT_COUNT">8.23.</a>&nbsp;
512 iliev 1162 Number of database instruments changed<br />
513 schoenebeck 1696 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENT_INFO">8.24.</a>&nbsp;
514 iliev 1162 Database instrument information changed<br />
515 schoenebeck 1696 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENTS_JOB_INFO">8.25.</a>&nbsp;
516 iliev 1201 Database job status information changed<br />
517 schoenebeck 1696 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MISCELLANEOUS">8.26.</a>&nbsp;
518 senoner 542 Miscellaneous and debugging events<br />
519 schoenebeck 974 <a href="#anchor14">9.</a>&nbsp;
520 senoner 542 Security Considerations<br />
521 schoenebeck 974 <a href="#anchor15">10.</a>&nbsp;
522 senoner 542 Acknowledgments<br />
523 schoenebeck 575 <a href="#rfc.references1">11.</a>&nbsp;
524 senoner 542 References<br />
525     <a href="#rfc.authors">&#167;</a>&nbsp;
526     Author's Address<br />
527     <a href="#rfc.copyright">&#167;</a>&nbsp;
528     Intellectual Property and Copyright Statements<br />
529     </p>
530     <br clear="all" />
531    
532     <a name="anchor1"></a><br /><hr />
533 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
534     <a name="rfc.section.1"></a><h3>1.&nbsp;
535     Requirements notation</h3>
536 senoner 542
537     <p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
538     "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
539     and "OPTIONAL" in this document are to be interpreted as
540 schoenebeck 974 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>.
541 senoner 542 </p>
542     <p>This protocol is always case-sensitive if not explicitly
543     claimed the opposite.
544     </p>
545     <p>In examples, "C:" and "S:" indicate lines sent by the client
546     (front-end) and server (LinuxSampler) respectively. Lines in
547     examples must be interpreted as every line being CRLF
548     terminated (carriage return character followed by line feed
549 schoenebeck 1251 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>),
550     thus the following example:
551 senoner 542 </p>
552 schoenebeck 708 <p>
553     </p>
554 senoner 542 <blockquote class="text">
555     <p>C: "some line"
556     </p>
557     <p>&nbsp;&nbsp;&nbsp;"another line"
558     </p>
559 schoenebeck 708 </blockquote><p>
560 schoenebeck 940
561 schoenebeck 708 </p>
562 senoner 542 <p>must actually be interpreted as client sending the following
563     message:
564     </p>
565 schoenebeck 708 <p>
566     </p>
567 senoner 542 <blockquote class="text">
568     <p>"some line&lt;CR&gt;&lt;LF&gt;another
569     line&lt;CR&gt;&lt;LF&gt;"
570     </p>
571 schoenebeck 708 </blockquote><p>
572 schoenebeck 940
573 schoenebeck 708 </p>
574 senoner 542 <p>where &lt;CR&gt; symbolizes the carriage return character and
575     &lt;LF&gt; the line feed character as defined in the ASCII
576     standard.
577     </p>
578     <p>Due to technical reasons, messages can arbitrary be
579     fragmented, means the following example:
580     </p>
581 schoenebeck 708 <p>
582     </p>
583 senoner 542 <blockquote class="text">
584     <p>S: "abcd"
585     </p>
586 schoenebeck 708 </blockquote><p>
587 schoenebeck 940
588 schoenebeck 708 </p>
589 senoner 542 <p>could also happen to be sent in three messages like in the
590     following sequence scenario:
591     </p>
592 schoenebeck 708 <p>
593     </p>
594 senoner 542 <ul class="text">
595     <li>server sending message "a"
596     </li>
597     <li>followed by a delay (pause) with
598     arbitrary duration
599     </li>
600     <li>followed by server sending message
601     "bcd&lt;CR&gt;"
602     </li>
603     <li>again followed by a delay (pause) with arbitrary
604     duration
605     </li>
606     <li>followed by server sending the message
607     "&lt;LF&gt;"
608     </li>
609 schoenebeck 708 </ul><p>
610 schoenebeck 940
611 schoenebeck 708 </p>
612 senoner 542 <p>where again &lt;CR&gt; and &lt;LF&gt; symbolize the carriage
613     return and line feed characters respectively.
614     </p>
615 schoenebeck 575 <a name="LSCP versioning"></a><br /><hr />
616 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
617     <a name="rfc.section.2"></a><h3>2.&nbsp;
618     Versioning of this specification</h3>
619 schoenebeck 575
620     <p>LSCP will certainly be extended and enhanced by-and-by. Each official
621     release of the LSCP specification will be tagged with a unique version
622     tuple. The version tuple consists at least of a major and minor version
623     number like:
624 schoenebeck 940
625 schoenebeck 575 </p>
626 schoenebeck 708 <p>
627     </p>
628 schoenebeck 575 <blockquote class="text">
629     <p>"1.2"
630     </p>
631 schoenebeck 708 </blockquote><p>
632 schoenebeck 940
633 schoenebeck 708 </p>
634 schoenebeck 575 <p>
635     In this example the major version number would be "1" and the minor
636     version number would be "2". Note that the version tuple might also
637     have more than two elements. The major version number defines a
638     group of backward compatible versions. That means a frontend is
639     compatible to the connected sampler if and only if the LSCP versions
640     to which each of the two parties complies to, match both of the
641     following rules:
642 schoenebeck 940
643 schoenebeck 575 </p>
644     <p>Compatibility:
645     </p>
646 schoenebeck 708 <p>
647     </p>
648 schoenebeck 575 <ol class="text">
649     <li>The frontend's LSCP major version and the sampler's LSCP
650     major version are exactly equal.
651     </li>
652     <li>The frontend's LSCP minor version is less or equal than
653     the sampler's LSCP minor version.
654     </li>
655 schoenebeck 708 </ol><p>
656 schoenebeck 940
657 schoenebeck 708 </p>
658 schoenebeck 575 <p>
659     Compatibility can only be claimed if both rules are true.
660     The frontend can use the
661 schoenebeck 974 <a class='info' href='#GET SERVER INFO'>"GET SERVER INFO"<span> (</span><span class='info'>General sampler informations</span><span>)</span></a> command to
662 schoenebeck 575 get the version of the LSCP specification the sampler complies with.
663 schoenebeck 940
664 schoenebeck 575 </p>
665 senoner 542 <a name="anchor2"></a><br /><hr />
666 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
667     <a name="rfc.section.3"></a><h3>3.&nbsp;
668     Introduction</h3>
669 senoner 542
670     <p>LinuxSampler is a so called software sampler application
671     capable to playback audio samples from a computer's Random
672     Access Memory (RAM) as well as directly streaming it from disk.
673     LinuxSampler is designed to be modular. It provides several so
674     called "sampler engines" where each engine is specialized for a
675     certain purpose. LinuxSampler has virtual channels which will be
676     referred in this document as "sampler channels". The channels
677     are in such way virtual as they can be connected to an
678     arbitrary MIDI input method and arbitrary MIDI channel (e.g.
679     sampler channel 17 could be connected to an ALSA sequencer
680     device 64:0 and listening to MIDI channel 1 there). Each sampler
681 schoenebeck 575 channel will be associated with an instance of one of the available
682 senoner 542 sampler engines (e.g. GigEngine, DLSEngine). The audio output of
683     each sampler channel can be routed to an arbitrary audio output
684     method (ALSA / JACK) and an arbitrary audio output channel
685     there.
686     </p>
687     <a name="anchor3"></a><br /><hr />
688 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
689     <a name="rfc.section.4"></a><h3>4.&nbsp;
690     Focus of this protocol</h3>
691 senoner 542
692     <p>Main focus of this protocol is to provide a way to configure
693     a running LinuxSampler instance and to retrieve information
694     about it. The focus of this protocol is not to provide a way to
695     control synthesis parameters or even to trigger or release
696     notes. Or in other words; the focus are those functionalities
697     which are not covered by MIDI or which may at most be handled
698     via MIDI System Exclusive Messages.
699     </p>
700     <a name="anchor4"></a><br /><hr />
701 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
702     <a name="rfc.section.5"></a><h3>5.&nbsp;
703     Communication Overview</h3>
704 senoner 542
705     <p>There are two distinct methods of communication between a
706     running instance of LinuxSampler and one or more control
707     applications, so called "front-ends": a simple request/response
708     communication method used by the clients to give commands to the
709     server as well as to inquire about server's status and a
710     subscribe/notify communication method used by the client to
711     subscribe to and receive notifications of certain events as they
712     happen on the server. The latter needs more effort to be
713     implemented in the front-end application. The two communication
714     methods will be described next.
715     </p>
716 schoenebeck 940 <a name="anchor5"></a><br /><hr />
717 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
718     <a name="rfc.section.5.1"></a><h3>5.1.&nbsp;
719     Request/response communication method</h3>
720 senoner 542
721 schoenebeck 575 <p>This simple communication method is based on
722 schoenebeck 974 <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
723 senoner 542 front-end application establishes a TCP connection to the
724     LinuxSampler instance on a certain host system. Then the
725     front-end application will send certain ASCII based commands
726     as defined in this document (every command line must be CRLF
727     terminated - see "Conventions used in this document" at the
728     beginning of this document) and the LinuxSampler application
729     will response after a certain process time with an
730     appropriate ASCII based answer, also as defined in this
731     document. So this TCP communication is simply based on query
732     and answer paradigm. That way LinuxSampler is only able to
733     answer on queries from front-ends, but not able to
734     automatically send messages to the client if it's not asked
735     to. The fronted should not reconnect to LinuxSampler for
736     every single command, instead it should keep the connection
737     established and simply resend message(s) for subsequent
738     commands. To keep information in the front-end up-to-date
739     the front-end has to periodically send new requests to get
740     the current information from the LinuxSampler instance. This
741     is often referred to as "polling". While polling is simple
742     to implement and may be OK to use in some cases, there may
743     be disadvantages to polling such as network traffic overhead
744     and information being out of date.
745     It is possible for a client or several clients to open more
746     than one connection to the server at the same time. It is
747     also possible to send more than one request to the server
748     at the same time but if those requests are sent over the
749     same connection server MUST execute them sequentially. Upon
750     executing a request server will produce a result set and
751     send it to the client. Each and every request made by the
752     client MUST result in a result set being sent back to the
753     client. No other data other than a result set may be sent by
754     a server to a client. No result set may be sent to a client
755     without the client sending request to the server first. On
756     any particular connection, result sets MUST be sent in their
757     entirety without being interrupted by other result sets. If
758     several requests got queued up at the server they MUST be
759     processed in the order they were received and result sets
760     MUST be sent back in the same order.
761     </p>
762 schoenebeck 940 <a name="anchor6"></a><br /><hr />
763 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
764     <a name="rfc.section.5.1.1"></a><h3>5.1.1.&nbsp;
765     Result format</h3>
766 senoner 542
767     <p>Result set could be one of the following types:
768     </p>
769 schoenebeck 708 <p>
770     </p>
771 senoner 542 <ol class="text">
772     <li>Normal
773     </li>
774     <li>Warning
775     </li>
776     <li>Error
777     </li>
778 schoenebeck 708 </ol><p>
779 schoenebeck 940
780 schoenebeck 708 </p>
781 senoner 542 <p>Warning and Error result sets MUST be single line and
782     have the following format:
783     </p>
784 schoenebeck 708 <p>
785     </p>
786 senoner 542 <ul class="text">
787     <li>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;"
788     </li>
789     <li>"ERR:&lt;error-code&gt;:&lt;error-message&gt;"
790     </li>
791 schoenebeck 708 </ul><p>
792 schoenebeck 940
793 schoenebeck 708 </p>
794 senoner 542 <p>Where &lt;warning-code&gt; and &lt;error-code&gt; are
795     numeric unique identifiers of the warning or error and
796     &lt;warning-message&gt; and &lt;error-message&gt; are
797     human readable descriptions of the warning or error
798     respectively.
799     </p>
800     <p>Examples:
801     </p>
802 schoenebeck 708 <p>
803     </p>
804 senoner 542 <blockquote class="text">
805     <p>C: "LOAD INSTRUMENT '/home/me/Boesendorfer24bit.gig" 0 0
806     </p>
807     <p>S: "WRN:32:This is a 24 bit patch which is not supported natively yet."
808     </p>
809 schoenebeck 708 </blockquote><p>
810 schoenebeck 940
811 schoenebeck 708 </p>
812     <p>
813     </p>
814 senoner 542 <blockquote class="text">
815     <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA EAR"
816     </p>
817     <p>S: "ERR:3456:Audio output driver 'ALSA' does not have a parameter 'EAR'."
818     </p>
819 schoenebeck 708 </blockquote><p>
820 schoenebeck 940
821 schoenebeck 708 </p>
822     <p>
823     </p>
824 senoner 542 <blockquote class="text">
825     <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 123456"
826     </p>
827     <p>S: "ERR:9:There is no audio output device with index 123456."
828     </p>
829 schoenebeck 708 </blockquote><p>
830 schoenebeck 940
831 schoenebeck 708 </p>
832 senoner 542 <p>Normal result sets could be:
833     </p>
834 schoenebeck 708 <p>
835     </p>
836 senoner 542 <ol class="text">
837     <li>Empty
838     </li>
839     <li>Single line
840     </li>
841     <li>Multi-line
842     </li>
843 schoenebeck 708 </ol><p>
844 schoenebeck 940
845 schoenebeck 708 </p>
846 senoner 542 <p> Empty result set is issued when the server only
847     needed to acknowledge the fact that the request was
848     received and it was processed successfully and no
849     additional information is available. This result set has
850     the following format:
851     </p>
852 schoenebeck 708 <p>
853     </p>
854 senoner 542 <blockquote class="text">
855     <p>"OK"
856     </p>
857 schoenebeck 708 </blockquote><p>
858 schoenebeck 940
859 schoenebeck 708 </p>
860 senoner 542 <p>Example:
861     </p>
862 schoenebeck 708 <p>
863     </p>
864 senoner 542 <blockquote class="text">
865     <p>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 CHANNELS=4"
866     </p>
867     <p>S: "OK"
868     </p>
869 schoenebeck 708 </blockquote><p>
870 schoenebeck 940
871 schoenebeck 708 </p>
872 senoner 542 <p>Single line result sets are command specific. One
873     example of a single line result set is an empty line.
874     Multi-line result sets are command specific and may
875     include one or more lines of information. They MUST
876     always end with the following line:
877     </p>
878 schoenebeck 708 <p>
879     </p>
880 senoner 542 <blockquote class="text">
881     <p>"."
882     </p>
883 schoenebeck 708 </blockquote><p>
884 schoenebeck 940
885 schoenebeck 708 </p>
886 senoner 542 <p>Example:
887     </p>
888 schoenebeck 708 <p>
889     </p>
890 senoner 542 <blockquote class="text">
891     <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
892     </p>
893     <p>S: "DRIVER: ALSA"
894     </p>
895     <p>&nbsp;&nbsp;&nbsp;"CHANNELS: 2"
896     </p>
897     <p>&nbsp;&nbsp;&nbsp;"SAMPLERATE: 44100"
898     </p>
899     <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
900     </p>
901     <p>&nbsp;&nbsp;&nbsp;"FRAGMENTS: 2"
902     </p>
903     <p>&nbsp;&nbsp;&nbsp;"FRAGMENTSIZE: 128"
904     </p>
905     <p>&nbsp;&nbsp;&nbsp;"CARD: '0,0'"
906     </p>
907     <p>&nbsp;&nbsp;&nbsp;"."
908     </p>
909 schoenebeck 708 </blockquote><p>
910 schoenebeck 940
911 schoenebeck 708 </p>
912 senoner 542 <p>In addition to above mentioned formats, warnings and
913     empty result sets MAY be indexed. In this case, they
914     have the following formats respectively:
915     </p>
916 schoenebeck 708 <p>
917     </p>
918 senoner 542 <ul class="text">
919     <li>"WRN[&lt;index&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;"
920     </li>
921     <li>"OK[&lt;index&gt;]"
922     </li>
923 schoenebeck 708 </ul><p>
924 schoenebeck 940
925 schoenebeck 708 </p>
926 senoner 542 <p>where &lt;index&gt; is command specific and is used
927     to indicate channel number that the result set was
928     related to or other integer value.
929     </p>
930     <p>Each line of the result set MUST end with
931     &lt;CRLF&gt;.
932     </p>
933     <p>Examples:
934     </p>
935 schoenebeck 708 <p>
936     </p>
937 senoner 542 <blockquote class="text">
938     <p>C: "ADD CHANNEL"
939     </p>
940     <p>S: "OK[12]"
941     </p>
942 schoenebeck 708 </blockquote><p>
943 schoenebeck 940
944 schoenebeck 708 </p>
945     <p>
946     </p>
947 senoner 542 <blockquote class="text">
948     <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"
949     </p>
950     <p>S: "WRN[0]:32:Sample rate not supported, using 44100 instead."
951     </p>
952 schoenebeck 708 </blockquote><p>
953 schoenebeck 940
954 schoenebeck 708 </p>
955 schoenebeck 940 <a name="anchor7"></a><br /><hr />
956 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
957     <a name="rfc.section.5.2"></a><h3>5.2.&nbsp;
958     Subscribe/notify communication method</h3>
959 senoner 542
960     <p>This more sophisticated communication method is actually
961     only an extension of the simple request/response
962     communication method. The front-end still uses a TCP
963     connection and sends the same commands on the TCP
964     connection. Two extra commands are SUBSCRIBE and UNSUBSCRIBE
965     commands that allow a client to tell the server that it is
966     interested in receiving notifications about certain events
967     as they happen on the server. The SUBSCRIBE command has the
968     following syntax:
969     </p>
970 schoenebeck 708 <p>
971     </p>
972 senoner 542 <blockquote class="text">
973     <p>SUBSCRIBE &lt;event-id&gt;
974     </p>
975 schoenebeck 708 </blockquote><p>
976 schoenebeck 940
977 schoenebeck 708 </p>
978 senoner 542 <p>where &lt;event-id&gt; will be replaced by the respective
979     event that client wants to subscribe to. Upon receiving such
980     request, server SHOULD respond with OK and start sending
981     EVENT notifications when a given even has occurred to the
982     front-end when an event has occurred. It MAY be possible
983     certain events may be sent before OK response during real
984     time nature of their generation. Event messages have the
985     following format:
986     </p>
987 schoenebeck 708 <p>
988     </p>
989 senoner 542 <blockquote class="text">
990     <p>NOTIFY:&lt;event-id&gt;:&lt;custom-event-data&gt;
991     </p>
992 schoenebeck 708 </blockquote><p>
993 schoenebeck 940
994 schoenebeck 708 </p>
995 senoner 542 <p>where &lt;event-id&gt; uniquely identifies the event that
996     has occurred and &lt;custom-event-data&gt; is event
997     specific.
998     </p>
999     <p>Several rules must be followed by the server when
1000     generating events:
1001     </p>
1002 schoenebeck 708 <p>
1003     </p>
1004 senoner 542 <ol class="text">
1005     <li>Events MUST NOT be sent to any client who has not
1006     issued an appropriate SUBSCRIBE command.
1007     </li>
1008     <li>Events MUST only be sent using the same
1009     connection that was used to subscribe to them.
1010     </li>
1011     <li>When response is being sent to the client, event
1012     MUST be inserted in the stream before or after the
1013     response, but NOT in the middle. Same is true about
1014     the response. It should never be inserted in the
1015     middle of the event message as well as any other
1016     response.
1017     </li>
1018 schoenebeck 708 </ol><p>
1019 schoenebeck 940
1020 schoenebeck 708 </p>
1021 senoner 542 <p>If the client is not interested in a particular event
1022     anymore it MAY issue UNSUBSCRIBE command using the following
1023     syntax:
1024     </p>
1025 schoenebeck 708 <p>
1026     </p>
1027 senoner 542 <blockquote class="text">
1028     <p>UNSUBSCRIBE &lt;event-id&gt;
1029     </p>
1030 schoenebeck 708 </blockquote><p>
1031 schoenebeck 940
1032 schoenebeck 708 </p>
1033 senoner 542 <p>where &lt;event-id&gt; will be replace by the respective
1034     event that client is no longer interested in receiving. For
1035 schoenebeck 974 a list of supported events see <a class='info' href='#events'>Section&nbsp;8<span> (</span><span class='info'>Events</span><span>)</span></a>.
1036 senoner 542 </p>
1037     <p>Example: the fill states of disk stream buffers have
1038     changed on sampler channel 4 and the LinuxSampler instance
1039     will react by sending the following message to all clients
1040     who subscribed to this event:
1041     </p>
1042 schoenebeck 708 <p>
1043     </p>
1044 senoner 542 <blockquote class="text">
1045     <p>NOTIFY:CHANNEL_BUFFER_FILL:4 [35]62%,[33]80%,[37]98%
1046     </p>
1047 schoenebeck 708 </blockquote><p>
1048 schoenebeck 940
1049 schoenebeck 708 </p>
1050 senoner 542 <p>Which means there are currently three active streams on
1051     sampler channel 4, where the stream with ID "35" is filled
1052     by 62%, stream with ID 33 is filled by 80% and stream with
1053     ID 37 is filled by 98%.
1054     </p>
1055     <p>Clients may choose to open more than one connection to
1056     the server and use some connections to receive notifications
1057     while using other connections to issue commands to the
1058     back-end. This is entirely legal and up to the
1059     implementation. This does not change the protocol in any way
1060     and no special restrictions exist on the server to allow or
1061     disallow this or to track what connections belong to what
1062     front-ends. Server will listen on a single port, accept
1063     multiple connections and support protocol described in this
1064     specification in it's entirety on this single port on each
1065     connection that it accepted.
1066     </p>
1067     <p>Due to the fact that TCP is used for this communication,
1068     dead peers will be detected automatically by the OS TCP
1069     stack. While it may take a while to detect dead peers if no
1070     traffic is being sent from server to client (TCP keep-alive
1071     timer is set to 2 hours on many OSes) it will not be an
1072     issue here as when notifications are sent by the server,
1073     dead client will be detected quickly.
1074     </p>
1075     <p>When connection is closed for any reason server MUST
1076     forget all subscriptions that were made on this connection.
1077     If client reconnects it MUST resubscribe to all events that
1078     it wants to receive.
1079     </p>
1080 schoenebeck 575 <a name="control_commands"></a><br /><hr />
1081 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1082     <a name="rfc.section.6"></a><h3>6.&nbsp;
1083     Description for control commands</h3>
1084 senoner 542
1085     <p>This chapter will describe the available control commands
1086     that can be sent on the TCP connection in detail. Some certain
1087 schoenebeck 974 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>
1088     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
1089 senoner 542 multiple-line responses. In this case LinuxSampler signals the
1090     end of the response by a "." (single dot) line.
1091     </p>
1092 schoenebeck 940 <a name="anchor8"></a><br /><hr />
1093 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1094     <a name="rfc.section.6.1"></a><h3>6.1.&nbsp;
1095     Ignored lines and comments</h3>
1096 senoner 542
1097     <p>White lines, that is lines which only contain space and
1098     tabulator characters, and lines that start with a "#"
1099     character are ignored, thus it's possible for example to
1100     group commands and to place comments in a LSCP script
1101     file.
1102     </p>
1103 schoenebeck 940 <a name="anchor9"></a><br /><hr />
1104 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1105     <a name="rfc.section.6.2"></a><h3>6.2.&nbsp;
1106     Configuring audio drivers</h3>
1107 senoner 542
1108     <p>Instances of drivers in LinuxSampler are called devices.
1109     You can use multiple audio devices simultaneously, e.g. to
1110     output the sound of one sampler channel using the ALSA audio
1111     output driver, and on another sampler channel you might want
1112     to use the JACK audio output driver. For particular audio
1113     output systems it's also possible to create several devices
1114     of the same audio output driver, e.g. two separate ALSA
1115     audio output devices for using two different sound cards at
1116     the same time. This chapter describes all commands to
1117     configure LinuxSampler's audio output devices and their
1118     parameters.
1119     </p>
1120     <p>Instead of defining commands and parameters for each
1121     driver individually, all possible parameters, their meanings
1122     and possible values have to be obtained at runtime. This
1123     makes the protocol a bit abstract, but has the advantage,
1124     that front-ends can be written independently of what drivers
1125     are currently implemented and what parameters these drivers
1126     are actually offering. This means front-ends can even handle
1127     drivers which are implemented somewhere in future without
1128     modifying the front-end at all.
1129     </p>
1130     <p>Note: examples in this chapter showing particular
1131     parameters of drivers are not meant as specification of the
1132     drivers' parameters. Driver implementations in LinuxSampler
1133     might have complete different parameter names and meanings
1134     than shown in these examples or might change in future, so
1135     these examples are only meant for showing how to retrieve
1136     what parameters drivers are offering, how to retrieve their
1137     possible values, etc.
1138     </p>
1139 schoenebeck 940 <a name="GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"></a><br /><hr />
1140 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1141     <a name="rfc.section.6.2.1"></a><h3>6.2.1.&nbsp;
1142     Getting amount of available audio output drivers</h3>
1143 senoner 542
1144     <p>Use the following command to get the number of
1145     audio output drivers currently available for the
1146     LinuxSampler instance:
1147     </p>
1148 schoenebeck 708 <p>
1149     </p>
1150 senoner 542 <blockquote class="text">
1151     <p>GET AVAILABLE_AUDIO_OUTPUT_DRIVERS
1152     </p>
1153 schoenebeck 708 </blockquote><p>
1154 schoenebeck 940
1155 schoenebeck 708 </p>
1156 senoner 542 <p>Possible Answers:
1157     </p>
1158 schoenebeck 708 <p>
1159     </p>
1160 senoner 542 <blockquote class="text">
1161     <p>LinuxSampler will answer by sending the
1162     number of audio output drivers.
1163     </p>
1164 schoenebeck 708 </blockquote><p>
1165 schoenebeck 940
1166 schoenebeck 708 </p>
1167 senoner 542 <p>Example:
1168     </p>
1169 schoenebeck 708 <p>
1170     </p>
1171 senoner 542 <blockquote class="text">
1172     <p>C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
1173     </p>
1174     <p>S: "2"
1175     </p>
1176 schoenebeck 708 </blockquote><p>
1177 schoenebeck 940
1178 schoenebeck 708 </p>
1179 schoenebeck 940 <a name="LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"></a><br /><hr />
1180 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1181     <a name="rfc.section.6.2.2"></a><h3>6.2.2.&nbsp;
1182     Getting all available audio output drivers</h3>
1183 senoner 542
1184     <p>Use the following command to list all audio output
1185     drivers currently available for the LinuxSampler
1186     instance:
1187     </p>
1188 schoenebeck 708 <p>
1189     </p>
1190 senoner 542 <blockquote class="text">
1191     <p>LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS
1192     </p>
1193 schoenebeck 708 </blockquote><p>
1194 schoenebeck 940
1195 schoenebeck 708 </p>
1196 senoner 542 <p>Possible Answers:
1197     </p>
1198 schoenebeck 708 <p>
1199     </p>
1200 senoner 542 <blockquote class="text">
1201     <p>LinuxSampler will answer by sending comma
1202     separated character strings, each symbolizing an
1203     audio output driver.
1204     </p>
1205 schoenebeck 708 </blockquote><p>
1206 schoenebeck 940
1207 schoenebeck 708 </p>
1208 senoner 542 <p>Example:
1209     </p>
1210 schoenebeck 708 <p>
1211     </p>
1212 senoner 542 <blockquote class="text">
1213     <p>C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"
1214     </p>
1215     <p>S: "ALSA,JACK"
1216     </p>
1217 schoenebeck 708 </blockquote><p>
1218 schoenebeck 940
1219 schoenebeck 708 </p>
1220 schoenebeck 940 <a name="GET AUDIO_OUTPUT_DRIVER INFO"></a><br /><hr />
1221 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1222     <a name="rfc.section.6.2.3"></a><h3>6.2.3.&nbsp;
1223     Getting information about a specific audio
1224 schoenebeck 940 output driver</h3>
1225 senoner 542
1226     <p>Use the following command to get detailed information
1227     about a specific audio output driver:
1228     </p>
1229 schoenebeck 708 <p>
1230     </p>
1231 senoner 542 <blockquote class="text">
1232     <p>GET AUDIO_OUTPUT_DRIVER INFO
1233     &lt;audio-output-driver&gt;
1234     </p>
1235 schoenebeck 708 </blockquote><p>
1236 schoenebeck 940
1237 schoenebeck 708 </p>
1238 senoner 542 <p>Where &lt;audio-output-driver&gt; is the name of the
1239     audio output driver, returned by the
1240 schoenebeck 974 <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.
1241 senoner 542 </p>
1242     <p>Possible Answers:
1243     </p>
1244 schoenebeck 708 <p>
1245     </p>
1246 senoner 542 <blockquote class="text">
1247     <p>LinuxSampler will answer by sending a
1248     &lt;CRLF&gt; separated list. Each answer line
1249     begins with the information category name
1250     followed by a colon and then a space character
1251     &lt;SP&gt; and finally the info character string
1252     to that info category. At the moment the
1253     following information categories are
1254     defined:
1255     </p>
1256 schoenebeck 708 <p>
1257     </p>
1258 senoner 542 <blockquote class="text">
1259     <p>DESCRIPTION -
1260     </p>
1261     <blockquote class="text">
1262     <p> character string describing the
1263     audio output driver
1264     </p>
1265 schoenebeck 940 </blockquote>
1266    
1267 senoner 542
1268     <p>VERSION -
1269     </p>
1270     <blockquote class="text">
1271     <p>character string reflecting the
1272     driver's version
1273     </p>
1274 schoenebeck 940 </blockquote>
1275    
1276 senoner 542
1277     <p>PARAMETERS -
1278     </p>
1279     <blockquote class="text">
1280     <p>comma separated list of all
1281     parameters available for the given
1282     audio output driver, at least
1283     parameters 'channels', 'samplerate'
1284     and 'active' are offered by all audio
1285     output drivers
1286     </p>
1287 schoenebeck 940 </blockquote>
1288    
1289 senoner 542
1290 schoenebeck 940 </blockquote>
1291    
1292 senoner 542
1293     <p>The mentioned fields above don't have to be
1294     in particular order.
1295     </p>
1296 schoenebeck 708 </blockquote><p>
1297 schoenebeck 940
1298 schoenebeck 708 </p>
1299 senoner 542 <p>Example:
1300     </p>
1301 schoenebeck 708 <p>
1302     </p>
1303 senoner 542 <blockquote class="text">
1304     <p>C: "GET AUDIO_OUTPUT_DRIVER INFO ALSA"
1305     </p>
1306     <p>S: "DESCRIPTION: Advanced Linux Sound
1307     Architecture"
1308     </p>
1309     <p>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"
1310     </p>
1311     <p>&nbsp;&nbsp;&nbsp;"PARAMETERS:
1312     DRIVER,CHANNELS,SAMPLERATE,ACTIVE,FRAGMENTS,
1313     FRAGMENTSIZE,CARD"
1314     </p>
1315     <p>&nbsp;&nbsp;&nbsp;"."
1316     </p>
1317 schoenebeck 708 </blockquote><p>
1318 schoenebeck 940
1319 schoenebeck 708 </p>
1320 schoenebeck 940 <a name="GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO"></a><br /><hr />
1321 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1322     <a name="rfc.section.6.2.4"></a><h3>6.2.4.&nbsp;
1323     Getting information about specific audio
1324 schoenebeck 940 output driver parameter</h3>
1325 senoner 542
1326     <p>Use the following command to get detailed information
1327     about a specific audio output driver parameter:
1328     </p>
1329 schoenebeck 708 <p>
1330     </p>
1331 senoner 542 <blockquote class="text">
1332     <p>GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO &lt;audio&gt; &lt;prm&gt; [&lt;deplist&gt;]
1333     </p>
1334 schoenebeck 708 </blockquote><p>
1335 schoenebeck 940
1336 schoenebeck 708 </p>
1337 senoner 542 <p>Where &lt;audio&gt; is the name of the audio output
1338 schoenebeck 974 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,
1339 senoner 542 &lt;prm&gt; a specific parameter name for which information should be
1340     obtained (as returned by the
1341 schoenebeck 974 <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
1342 senoner 542 &lt;deplist&gt; is an optional list of parameters on which the sought
1343     parameter &lt;prm&gt; depends on, &lt;deplist&gt; is a list of key-value
1344     pairs in form of "key1=val1 key2=val2 ...", where character string values
1345     are encapsulated into apostrophes ('). Arguments given with &lt;deplist&gt;
1346     which are not dependency parameters of &lt;prm&gt; will be ignored, means
1347     the front-end application can simply put all parameters into &lt;deplist&gt;
1348     with the values already selected by the user.
1349     </p>
1350     <p>Possible Answers:
1351     </p>
1352 schoenebeck 708 <p>
1353     </p>
1354 senoner 542 <blockquote class="text">
1355     <p>LinuxSampler will answer by sending a
1356     &lt;CRLF&gt; separated list.
1357     Each answer line begins with the information category name
1358     followed by a colon and then a space character &lt;SP&gt; and
1359     finally
1360     the info character string to that info category. There are
1361     information which is always returned, independently of the
1362     given driver parameter and there are optional information
1363     which is only shown dependently to given driver parameter. At
1364     the moment the following information categories are defined:
1365     </p>
1366 schoenebeck 708 </blockquote><p>
1367 schoenebeck 940
1368 schoenebeck 708 </p>
1369     <p>
1370     </p>
1371 senoner 542 <blockquote class="text">
1372     <p>TYPE -
1373     </p>
1374     <blockquote class="text">
1375     <p>either "BOOL" for boolean value(s) or
1376     "INT" for integer
1377     value(s) or "FLOAT" for dotted number(s) or "STRING" for
1378     character string(s)
1379     (always returned, no matter which driver parameter)
1380     </p>
1381 schoenebeck 940 </blockquote>
1382    
1383 senoner 542
1384     <p>DESCRIPTION -
1385     </p>
1386     <blockquote class="text">
1387     <p>arbitrary text describing the purpose of the parameter
1388     (always returned, no matter which driver parameter)
1389     </p>
1390 schoenebeck 940 </blockquote>
1391    
1392 senoner 542
1393     <p>MANDATORY -
1394     </p>
1395     <blockquote class="text">
1396     <p>either true or false, defines if this parameter must be
1397     given when the device is to be created with the
1398 schoenebeck 974 <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>
1399 senoner 542 command (always returned, no matter which driver parameter)
1400     </p>
1401 schoenebeck 940 </blockquote>
1402    
1403 senoner 542
1404     <p>FIX -
1405     </p>
1406     <blockquote class="text">
1407     <p>either true or false, if false then this parameter can
1408     be changed at any time, once the device is created by
1409 schoenebeck 974 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>
1410 senoner 542 command (always returned, no matter which driver parameter)
1411     </p>
1412 schoenebeck 940 </blockquote>
1413    
1414 senoner 542
1415     <p>MULTIPLICITY -
1416     </p>
1417     <blockquote class="text">
1418     <p>either true or false, defines if this parameter allows
1419     only one value or a list of values, where true means
1420     multiple values and false only a single value allowed
1421     (always returned, no matter which driver parameter)
1422     </p>
1423 schoenebeck 940 </blockquote>
1424    
1425 senoner 542
1426     <p>DEPENDS -
1427     </p>
1428     <blockquote class="text">
1429 schoenebeck 561 <p>comma separated list of parameters this parameter depends
1430 senoner 542 on, means the values for fields 'DEFAULT', 'RANGE_MIN',
1431     'RANGE_MAX' and 'POSSIBILITIES' might depend on these
1432     listed parameters, for example assuming that an audio
1433     driver (like the ALSA driver) offers parameters 'card'
1434     and 'samplerate' then parameter 'samplerate' would
1435     depend on 'card' because the possible values for
1436     'samplerate' depends on the sound card which can be
1437     chosen by the 'card' parameter
1438     (optionally returned, dependent to driver parameter)
1439     </p>
1440 schoenebeck 940 </blockquote>
1441    
1442 senoner 542
1443     <p>DEFAULT -
1444     </p>
1445     <blockquote class="text">
1446     <p>reflects the default value for this parameter which is
1447     used when the device is created and not explicitly
1448 schoenebeck 974 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,
1449 senoner 542 in case of MULTIPLCITY=true, this is a comma separated
1450     list, that's why character strings are encapsulated into
1451     apostrophes (')
1452     (optionally returned, dependent to driver parameter)
1453     </p>
1454 schoenebeck 940 </blockquote>
1455    
1456 senoner 542
1457     <p>RANGE_MIN -
1458     </p>
1459     <blockquote class="text">
1460     <p>defines lower limit of the allowed value range for this
1461     parameter, can be an integer value as well as a dotted
1462     number, this parameter is often used in conjunction
1463     with RANGE_MAX, but may also appear without
1464     (optionally returned, dependent to driver parameter)
1465     </p>
1466 schoenebeck 940 </blockquote>
1467    
1468 senoner 542
1469     <p>RANGE_MAX -
1470     </p>
1471     <blockquote class="text">
1472     <p>defines upper limit of the allowed value range for this
1473     parameter, can be an integer value as well as a dotted
1474     number, this parameter is often used in conjunction with
1475     RANGE_MIN, but may also appear without
1476     (optionally returned, dependent to driver parameter)
1477     </p>
1478 schoenebeck 940 </blockquote>
1479    
1480 senoner 542
1481     <p>POSSIBILITIES -
1482     </p>
1483     <blockquote class="text">
1484     <p>comma separated list of possible values for this
1485     parameter, character strings are encapsulated into
1486     apostrophes
1487     (optionally returned, dependent to driver parameter)
1488     </p>
1489 schoenebeck 940 </blockquote>
1490    
1491 senoner 542
1492 schoenebeck 708 </blockquote><p>
1493 schoenebeck 940
1494 schoenebeck 708 </p>
1495 senoner 542 <p>The mentioned fields above don't have to be in particular order.
1496     </p>
1497     <p>Examples:
1498     </p>
1499 schoenebeck 708 <p>
1500     </p>
1501 senoner 542 <blockquote class="text">
1502     <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA CARD"
1503     </p>
1504     <p>S: "DESCRIPTION: sound card to be used"
1505     </p>
1506     <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
1507     </p>
1508     <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1509     </p>
1510     <p>&nbsp;&nbsp;&nbsp;"FIX: true"
1511     </p>
1512     <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1513     </p>
1514     <p>&nbsp;&nbsp;&nbsp;"DEFAULT: '0,0'"
1515     </p>
1516     <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: '0,0','1,0','2,0'"
1517     </p>
1518     <p>&nbsp;&nbsp;&nbsp;"."
1519     </p>
1520 schoenebeck 708 </blockquote><p>
1521 schoenebeck 940
1522 schoenebeck 708 </p>
1523     <p>
1524     </p>
1525 senoner 542 <blockquote class="text">
1526     <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE"
1527     </p>
1528     <p>S: "DESCRIPTION: output sample rate in Hz"
1529     </p>
1530     <p>&nbsp;&nbsp;&nbsp;"TYPE: INT"
1531     </p>
1532     <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1533     </p>
1534     <p>&nbsp;&nbsp;&nbsp;"FIX: false"
1535     </p>
1536     <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1537     </p>
1538     <p>&nbsp;&nbsp;&nbsp;"DEPENDS: card"
1539     </p>
1540     <p>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"
1541     </p>
1542     <p>&nbsp;&nbsp;&nbsp;"."
1543     </p>
1544 schoenebeck 708 </blockquote><p>
1545 schoenebeck 940
1546 schoenebeck 708 </p>
1547     <p>
1548     </p>
1549 senoner 542 <blockquote class="text">
1550     <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE CARD='0,0'"
1551     </p>
1552     <p>S: "DESCRIPTION: output sample rate in Hz"
1553     </p>
1554     <p>&nbsp;&nbsp;&nbsp;"TYPE: INT"
1555     </p>
1556     <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1557     </p>
1558     <p>&nbsp;&nbsp;&nbsp;"FIX: false"
1559     </p>
1560     <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1561     </p>
1562     <p>&nbsp;&nbsp;&nbsp;"DEPENDS: card"
1563     </p>
1564     <p>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"
1565     </p>
1566     <p>&nbsp;&nbsp;&nbsp;"RANGE_MIN: 22050"
1567     </p>
1568     <p>&nbsp;&nbsp;&nbsp;"RANGE_MAX: 96000"
1569     </p>
1570     <p>&nbsp;&nbsp;&nbsp;"."
1571     </p>
1572 schoenebeck 708 </blockquote><p>
1573 schoenebeck 940
1574 schoenebeck 708 </p>
1575 schoenebeck 940 <a name="CREATE AUDIO_OUTPUT_DEVICE"></a><br /><hr />
1576 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1577     <a name="rfc.section.6.2.5"></a><h3>6.2.5.&nbsp;
1578     Creating an audio output device</h3>
1579 senoner 542
1580     <p>Use the following command to create a new audio output device for the desired audio output system:
1581     </p>
1582 schoenebeck 708 <p>
1583     </p>
1584 senoner 542 <blockquote class="text">
1585     <p>CREATE AUDIO_OUTPUT_DEVICE &lt;audio-output-driver&gt; [&lt;param-list&gt;]
1586     </p>
1587 schoenebeck 708 </blockquote><p>
1588 schoenebeck 940
1589 schoenebeck 708 </p>
1590 senoner 542 <p>Where &lt;audio-output-driver&gt; should be replaced by the desired audio
1591 schoenebeck 575 output system as returned by the
1592 schoenebeck 974 <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>
1593 schoenebeck 575 command and &lt;param-list&gt; by an optional list of driver
1594 senoner 542 specific parameters in form of "key1=val1 key2=val2 ...", where
1595     character string values should be encapsulated into apostrophes (').
1596     Note that there might be drivers which require parameter(s) to be
1597     given with this command. Use the previously described commands in
1598     this chapter to get this information.
1599     </p>
1600     <p>Possible Answers:
1601     </p>
1602 schoenebeck 708 <p>
1603     </p>
1604 senoner 542 <blockquote class="text">
1605     <p>"OK[&lt;device-id&gt;]" -
1606     </p>
1607     <blockquote class="text">
1608     <p>in case the device was successfully created, where
1609     &lt;device-id&gt; is the numerical ID of the new device
1610     </p>
1611 schoenebeck 940 </blockquote>
1612    
1613 senoner 542
1614     <p>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1615     </p>
1616     <blockquote class="text">
1617     <p>in case the device was created successfully, where
1618     &lt;device-id&gt; is the numerical ID of the new device, but there
1619     are noteworthy issue(s) related (e.g. sound card doesn't
1620     support given hardware parameters and the driver is using
1621     fall-back values), providing an appropriate warning code and
1622     warning message
1623     </p>
1624 schoenebeck 940 </blockquote>
1625    
1626 senoner 542
1627     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1628     </p>
1629     <blockquote class="text">
1630     <p>in case it failed, providing an appropriate error code and error message
1631     </p>
1632 schoenebeck 940 </blockquote>
1633    
1634 senoner 542
1635 schoenebeck 708 </blockquote><p>
1636 schoenebeck 940
1637 schoenebeck 708 </p>
1638 senoner 542 <p>Examples:
1639     </p>
1640 schoenebeck 708 <p>
1641     </p>
1642 senoner 542 <blockquote class="text">
1643     <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA"
1644     </p>
1645     <p>S: "OK[0]"
1646     </p>
1647 schoenebeck 708 </blockquote><p>
1648 schoenebeck 940
1649 schoenebeck 708 </p>
1650     <p>
1651     </p>
1652 senoner 542 <blockquote class="text">
1653     <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"
1654     </p>
1655     <p>S: "OK[1]"
1656     </p>
1657 schoenebeck 708 </blockquote><p>
1658 schoenebeck 940
1659 schoenebeck 708 </p>
1660 schoenebeck 940 <a name="DESTROY AUDIO_OUTPUT_DEVICE"></a><br /><hr />
1661 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1662     <a name="rfc.section.6.2.6"></a><h3>6.2.6.&nbsp;
1663     Destroying an audio output device</h3>
1664 senoner 542
1665     <p>Use the following command to destroy a created output device:
1666     </p>
1667 schoenebeck 708 <p>
1668     </p>
1669 senoner 542 <blockquote class="text">
1670     <p>DESTROY AUDIO_OUTPUT_DEVICE &lt;device-id&gt;
1671     </p>
1672 schoenebeck 708 </blockquote><p>
1673 schoenebeck 940
1674 schoenebeck 708 </p>
1675 senoner 542 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1676     audio output device as given by the
1677 schoenebeck 974 <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>
1678     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>
1679 senoner 542 command.
1680     </p>
1681     <p>Possible Answers:
1682     </p>
1683 schoenebeck 708 <p>
1684     </p>
1685 senoner 542 <blockquote class="text">
1686     <p>"OK" -
1687     </p>
1688     <blockquote class="text">
1689     <p>in case the device was successfully destroyed
1690     </p>
1691 schoenebeck 940 </blockquote>
1692    
1693 senoner 542
1694     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1695     </p>
1696     <blockquote class="text">
1697     <p>in case the device was destroyed successfully, but there are
1698     noteworthy issue(s) related (e.g. an audio over ethernet
1699     driver was unloaded but the other host might not be
1700     informed about this situation), providing an appropriate
1701     warning code and warning message
1702     </p>
1703 schoenebeck 940 </blockquote>
1704    
1705 senoner 542
1706     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1707     </p>
1708     <blockquote class="text">
1709     <p>in case it failed, providing an appropriate error code and
1710     error message
1711     </p>
1712 schoenebeck 940 </blockquote>
1713    
1714 senoner 542
1715 schoenebeck 708 </blockquote><p>
1716 schoenebeck 940
1717 schoenebeck 708 </p>
1718 senoner 542 <p>Example:
1719     </p>
1720 schoenebeck 708 <p>
1721     </p>
1722 senoner 542 <blockquote class="text">
1723     <p>C: "DESTROY AUDIO_OUTPUT_DEVICE 0"
1724     </p>
1725     <p>S: "OK"
1726     </p>
1727 schoenebeck 708 </blockquote><p>
1728 schoenebeck 940
1729 schoenebeck 708 </p>
1730 schoenebeck 940 <a name="GET AUDIO_OUTPUT_DEVICES"></a><br /><hr />
1731 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1732     <a name="rfc.section.6.2.7"></a><h3>6.2.7.&nbsp;
1733     Getting all created audio output device count</h3>
1734 senoner 542
1735     <p>Use the following command to count all created audio output devices:
1736     </p>
1737 schoenebeck 708 <p>
1738     </p>
1739 senoner 542 <blockquote class="text">
1740     <p>GET AUDIO_OUTPUT_DEVICES
1741     </p>
1742 schoenebeck 708 </blockquote><p>
1743 schoenebeck 940
1744 schoenebeck 708 </p>
1745 senoner 542 <p>Possible Answers:
1746     </p>
1747 schoenebeck 708 <p>
1748     </p>
1749 senoner 542 <blockquote class="text">
1750     <p>LinuxSampler will answer by sending the current number of all
1751     audio output devices.
1752     </p>
1753 schoenebeck 708 </blockquote><p>
1754 schoenebeck 940
1755 schoenebeck 708 </p>
1756 senoner 542 <p>Example:
1757     </p>
1758 schoenebeck 708 <p>
1759     </p>
1760 senoner 542 <blockquote class="text">
1761     <p>C: "GET AUDIO_OUTPUT_DEVICES"
1762     </p>
1763     <p>S: "4"
1764     </p>
1765 schoenebeck 708 </blockquote><p>
1766 schoenebeck 940
1767 schoenebeck 708 </p>
1768 schoenebeck 940 <a name="LIST AUDIO_OUTPUT_DEVICES"></a><br /><hr />
1769 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1770     <a name="rfc.section.6.2.8"></a><h3>6.2.8.&nbsp;
1771     Getting all created audio output device list</h3>
1772 senoner 542
1773     <p>Use the following command to list all created audio output devices:
1774     </p>
1775 schoenebeck 708 <p>
1776     </p>
1777 senoner 542 <blockquote class="text">
1778     <p>LIST AUDIO_OUTPUT_DEVICES
1779     </p>
1780 schoenebeck 708 </blockquote><p>
1781 schoenebeck 940
1782 schoenebeck 708 </p>
1783 senoner 542 <p>Possible Answers:
1784     </p>
1785 schoenebeck 708 <p>
1786     </p>
1787 senoner 542 <blockquote class="text">
1788     <p>LinuxSampler will answer by sending a comma separated list with
1789     the numerical IDs of all audio output devices.
1790     </p>
1791 schoenebeck 708 </blockquote><p>
1792 schoenebeck 940
1793 schoenebeck 708 </p>
1794 senoner 542 <p>Example:
1795     </p>
1796 schoenebeck 708 <p>
1797     </p>
1798 senoner 542 <blockquote class="text">
1799     <p>C: "LIST AUDIO_OUTPUT_DEVICES"
1800     </p>
1801     <p>S: "0,1,4,5"
1802     </p>
1803 schoenebeck 708 </blockquote><p>
1804 schoenebeck 940
1805 schoenebeck 708 </p>
1806 schoenebeck 940 <a name="GET AUDIO_OUTPUT_DEVICE INFO"></a><br /><hr />
1807 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1808     <a name="rfc.section.6.2.9"></a><h3>6.2.9.&nbsp;
1809     Getting current settings of an audio output device</h3>
1810 senoner 542
1811     <p>Use the following command to get current settings of a specific, created audio output device:
1812     </p>
1813 schoenebeck 708 <p>
1814     </p>
1815 senoner 542 <blockquote class="text">
1816     <p>GET AUDIO_OUTPUT_DEVICE INFO &lt;device-id&gt;
1817     </p>
1818 schoenebeck 708 </blockquote><p>
1819 schoenebeck 940
1820 schoenebeck 708 </p>
1821 senoner 542 <p>Where &lt;device-id&gt; should be replaced by numerical ID
1822     of the audio output device as e.g. returned by the
1823 schoenebeck 974 <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.
1824 senoner 542 </p>
1825     <p>Possible Answers:
1826     </p>
1827     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1828     Each answer line begins with the information category name
1829     followed by a colon and then a space character &lt;SP&gt; and finally
1830     the info character string to that info category. As some
1831     parameters might allow multiple values, character strings are
1832     encapsulated into apostrophes ('). At the moment the following
1833     information categories are defined (independently of device):
1834     </p>
1835 schoenebeck 708 <p>
1836     </p>
1837 senoner 542 <blockquote class="text">
1838     <p>DRIVER -
1839     </p>
1840     <blockquote class="text">
1841     <p>identifier of the used audio output driver, as also
1842     returned by the
1843 schoenebeck 974 <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>
1844 senoner 542 command
1845     </p>
1846 schoenebeck 940 </blockquote>
1847    
1848 senoner 542
1849     <p>CHANNELS -
1850     </p>
1851     <blockquote class="text">
1852     <p>amount of audio output channels this device currently
1853     offers
1854     </p>
1855 schoenebeck 940 </blockquote>
1856    
1857 senoner 542
1858     <p>SAMPLERATE -
1859     </p>
1860     <blockquote class="text">
1861     <p>playback sample rate the device uses
1862     </p>
1863 schoenebeck 940 </blockquote>
1864    
1865 senoner 542
1866     <p>ACTIVE -
1867     </p>
1868     <blockquote class="text">
1869     <p>either true or false, if false then the audio device is
1870     inactive and doesn't output any sound, nor do the
1871     sampler channels connected to this audio device render
1872     any audio
1873     </p>
1874 schoenebeck 940 </blockquote>
1875    
1876 senoner 542
1877 schoenebeck 708 </blockquote><p>
1878 schoenebeck 940
1879 schoenebeck 708 </p>
1880 senoner 542 <p>The mentioned fields above don't have to be in particular
1881     order. The fields above are only those fields which are
1882     returned by all audio output devices. Every audio output driver
1883     might have its own, additional driver specific parameters (see
1884 schoenebeck 974 <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>)
1885 senoner 542 which are also returned by this command.
1886     </p>
1887     <p>Example:
1888     </p>
1889 schoenebeck 708 <p>
1890     </p>
1891 senoner 542 <blockquote class="text">
1892     <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
1893     </p>
1894     <p>S: "DRIVER: ALSA"
1895     </p>
1896     <p>&nbsp;&nbsp;&nbsp;"CHANNELS: 2"
1897     </p>
1898     <p>&nbsp;&nbsp;&nbsp;"SAMPLERATE: 44100"
1899     </p>
1900     <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
1901     </p>
1902     <p>&nbsp;&nbsp;&nbsp;"FRAGMENTS: 2"
1903     </p>
1904     <p>&nbsp;&nbsp;&nbsp;"FRAGMENTSIZE: 128"
1905     </p>
1906     <p>&nbsp;&nbsp;&nbsp;"CARD: '0,0'"
1907     </p>
1908     <p>&nbsp;&nbsp;&nbsp;"."
1909     </p>
1910 schoenebeck 708 </blockquote><p>
1911 schoenebeck 940
1912 schoenebeck 708 </p>
1913 schoenebeck 940 <a name="SET AUDIO_OUTPUT_DEVICE_PARAMETER"></a><br /><hr />
1914 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1915     <a name="rfc.section.6.2.10"></a><h3>6.2.10.&nbsp;
1916     Changing settings of audio output devices</h3>
1917 senoner 542
1918     <p>Use the following command to alter a specific setting of a created audio output device:
1919     </p>
1920 schoenebeck 708 <p>
1921     </p>
1922 senoner 542 <blockquote class="text">
1923     <p>SET AUDIO_OUTPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;
1924     </p>
1925 schoenebeck 708 </blockquote><p>
1926 schoenebeck 940
1927 schoenebeck 708 </p>
1928 senoner 542 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1929 schoenebeck 575 audio output device as given by the
1930 schoenebeck 974 <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>
1931     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>
1932 schoenebeck 575 command, &lt;key&gt; by the name of the parameter to change
1933 senoner 542 and &lt;value&gt; by the new value for this parameter.
1934     </p>
1935     <p>Possible Answers:
1936     </p>
1937 schoenebeck 708 <p>
1938     </p>
1939 senoner 542 <blockquote class="text">
1940     <p>"OK" -
1941     </p>
1942     <blockquote class="text">
1943     <p>in case setting was successfully changed
1944     </p>
1945 schoenebeck 940 </blockquote>
1946    
1947 senoner 542
1948     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1949     </p>
1950     <blockquote class="text">
1951     <p>in case setting was changed successfully, but there are
1952     noteworthy issue(s) related, providing an appropriate
1953     warning code and warning message
1954     </p>
1955 schoenebeck 940 </blockquote>
1956    
1957 senoner 542
1958     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1959     </p>
1960     <blockquote class="text">
1961     <p>in case it failed, providing an appropriate error code and
1962     error message
1963     </p>
1964 schoenebeck 940 </blockquote>
1965    
1966 senoner 542
1967 schoenebeck 708 </blockquote><p>
1968 schoenebeck 940
1969 schoenebeck 708 </p>
1970 senoner 542 <p>Example:
1971     </p>
1972 schoenebeck 708 <p>
1973     </p>
1974 senoner 542 <blockquote class="text">
1975     <p>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"
1976     </p>
1977     <p>S: "OK"
1978     </p>
1979 schoenebeck 708 </blockquote><p>
1980 schoenebeck 940
1981 schoenebeck 708 </p>
1982 schoenebeck 940 <a name="GET AUDIO_OUTPUT_CHANNEL INFO"></a><br /><hr />
1983 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
1984     <a name="rfc.section.6.2.11"></a><h3>6.2.11.&nbsp;
1985     Getting information about an audio channel</h3>
1986 senoner 542
1987     <p>Use the following command to get information about an audio channel:
1988     </p>
1989 schoenebeck 708 <p>
1990     </p>
1991 senoner 542 <blockquote class="text">
1992     <p>GET AUDIO_OUTPUT_CHANNEL INFO &lt;device-id&gt; &lt;audio-chan&gt;
1993     </p>
1994 schoenebeck 708 </blockquote><p>
1995 schoenebeck 940
1996 schoenebeck 708 </p>
1997 schoenebeck 575 <p>Where &lt;device-id&gt; is the numerical ID of the audio output device as given by the
1998 schoenebeck 974 <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>
1999     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>
2000 schoenebeck 575 command and &lt;audio-chan&gt; the audio channel number.
2001 senoner 542 </p>
2002     <p>Possible Answers:
2003     </p>
2004 schoenebeck 708 <p>
2005     </p>
2006 senoner 542 <blockquote class="text">
2007     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2008     Each answer line begins with the information category name
2009     followed by a colon and then a space character &lt;SP&gt; and finally
2010     the info character string to that info category. At the moment
2011     the following information categories are defined:
2012     </p>
2013 schoenebeck 708 <p>
2014     </p>
2015 senoner 542 <blockquote class="text">
2016     <p>NAME -
2017     </p>
2018     <blockquote class="text">
2019     <p>arbitrary character string naming the channel, which
2020     doesn't have to be unique (always returned by all audio channels)
2021     </p>
2022 schoenebeck 940 </blockquote>
2023    
2024 senoner 542
2025     <p>IS_MIX_CHANNEL -
2026     </p>
2027     <blockquote class="text">
2028     <p>either true or false, a mix-channel is not a real,
2029     independent audio channel, but a virtual channel which
2030     is mixed to another real channel, this mechanism is
2031     needed for sampler engines which need more audio
2032     channels than the used audio system might be able to offer
2033     (always returned by all audio channels)
2034     </p>
2035 schoenebeck 940 </blockquote>
2036    
2037 senoner 542
2038     <p>MIX_CHANNEL_DESTINATION -
2039     </p>
2040     <blockquote class="text">
2041     <p>numerical ID (positive integer including 0)
2042     which reflects the real audio channel (of the same audio
2043     output device) this mix channel refers to, means where
2044     the audio signal actually will be routed / added to
2045     (only returned in case the audio channel is mix channel)
2046     </p>
2047 schoenebeck 940 </blockquote>
2048    
2049 senoner 542
2050 schoenebeck 940 </blockquote>
2051    
2052 senoner 542
2053 schoenebeck 708 </blockquote><p>
2054 schoenebeck 940
2055 schoenebeck 708 </p>
2056 senoner 542 <p>The mentioned fields above don't have to be in particular
2057     order. The fields above are only those fields which are
2058     generally returned for the described cases by all audio
2059     channels regardless of the audio driver. Every audio channel
2060     might have its own, additional driver and channel specific
2061     parameters.
2062     </p>
2063     <p>Examples:
2064     </p>
2065 schoenebeck 708 <p>
2066     </p>
2067 senoner 542 <blockquote class="text">
2068     <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 0"
2069     </p>
2070     <p>S: "NAME: studio monitor left"
2071     </p>
2072     <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
2073     </p>
2074     <p>&nbsp;&nbsp;&nbsp;"."
2075     </p>
2076 schoenebeck 708 </blockquote><p>
2077 schoenebeck 940
2078 schoenebeck 708 </p>
2079     <p>
2080     </p>
2081 senoner 542 <blockquote class="text">
2082     <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 1"
2083     </p>
2084     <p>S: "NAME: studio monitor right"
2085     </p>
2086     <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
2087     </p>
2088     <p>&nbsp;&nbsp;&nbsp;"."
2089     </p>
2090 schoenebeck 708 </blockquote><p>
2091 schoenebeck 940
2092 schoenebeck 708 </p>
2093     <p>
2094     </p>
2095 senoner 542 <blockquote class="text">
2096     <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"
2097     </p>
2098     <p>S: "NAME: studio monitor left"
2099     </p>
2100     <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: true"
2101     </p>
2102     <p>&nbsp;&nbsp;&nbsp;"MIX_CHANNEL_DESTINATION: 1"
2103     </p>
2104     <p>&nbsp;&nbsp;&nbsp;"."
2105     </p>
2106 schoenebeck 708 </blockquote><p>
2107 schoenebeck 940
2108 schoenebeck 708 </p>
2109     <p>
2110     </p>
2111 senoner 542 <blockquote class="text">
2112     <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"
2113     </p>
2114     <p>S: "NAME: 'ardour (left)'"
2115     </p>
2116     <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
2117     </p>
2118     <p>&nbsp;&nbsp;&nbsp;"JACK_BINDINGS: 'ardour:0'"
2119     </p>
2120     <p>&nbsp;&nbsp;&nbsp;"."
2121     </p>
2122 schoenebeck 708 </blockquote><p>
2123 schoenebeck 940
2124 schoenebeck 708 </p>
2125 schoenebeck 940 <a name="GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO"></a><br /><hr />
2126 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2127     <a name="rfc.section.6.2.12"></a><h3>6.2.12.&nbsp;
2128     Getting information about specific audio channel parameter</h3>
2129 senoner 542
2130     <p>Use the following command to get detailed information about specific audio channel parameter:
2131     </p>
2132 schoenebeck 708 <p>
2133     </p>
2134 senoner 542 <blockquote class="text">
2135     <p>GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO &lt;dev-id&gt; &lt;chan&gt; &lt;param&gt;
2136     </p>
2137 schoenebeck 708 </blockquote><p>
2138 schoenebeck 940
2139 schoenebeck 708 </p>
2140 schoenebeck 575 <p>Where &lt;dev-id&gt; is the numerical ID of the audio output device as returned by the
2141 schoenebeck 974 <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>
2142     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>
2143 senoner 542 command, &lt;chan&gt; the audio channel number
2144     and &lt;param&gt; a specific channel parameter name for which information should
2145 schoenebeck 974 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).
2146 senoner 542 </p>
2147     <p>Possible Answers:
2148     </p>
2149 schoenebeck 708 <p>
2150     </p>
2151 senoner 542 <blockquote class="text">
2152     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2153     Each answer line begins with the information category name
2154     followed by a colon and then a space character &lt;SP&gt; and finally
2155     the info character string to that info category. There are
2156     information which is always returned, independently of the
2157     given channel parameter and there is optional information
2158     which is only shown dependently to the given audio channel. At
2159     the moment the following information categories are defined:
2160     </p>
2161 schoenebeck 708 <p>
2162     </p>
2163 senoner 542 <blockquote class="text">
2164     <p>TYPE -
2165     </p>
2166     <blockquote class="text">
2167     <p>either "BOOL" for boolean value(s) or "INT" for integer
2168     value(s) or "FLOAT" for dotted number(s) or "STRING" for
2169     character string(s)
2170     (always returned)
2171     </p>
2172 schoenebeck 940 </blockquote>
2173    
2174 senoner 542
2175     <p>DESCRIPTION -
2176     </p>
2177     <blockquote class="text">
2178     <p>arbitrary text describing the purpose of the parameter (always returned)
2179     </p>
2180 schoenebeck 940 </blockquote>
2181    
2182 senoner 542
2183     <p>FIX -
2184     </p>
2185     <blockquote class="text">
2186     <p>either true or false, if true then this parameter is
2187     read only, thus cannot be altered
2188     (always returned)
2189     </p>
2190 schoenebeck 940 </blockquote>
2191    
2192 senoner 542
2193     <p>MULTIPLICITY -
2194     </p>
2195     <blockquote class="text">
2196     <p>either true or false, defines if this parameter allows
2197     only one value or a list of values, where true means
2198     multiple values and false only a single value allowed
2199     (always returned)
2200     </p>
2201 schoenebeck 940 </blockquote>
2202    
2203 senoner 542
2204     <p>RANGE_MIN -
2205     </p>
2206     <blockquote class="text">
2207     <p>defines lower limit of the allowed value range for this
2208     parameter, can be an integer value as well as a dotted
2209     number, usually used in conjunction with 'RANGE_MAX',
2210     but may also appear without
2211     (optionally returned, dependent to driver and channel
2212     parameter)
2213     </p>
2214 schoenebeck 940 </blockquote>
2215    
2216 senoner 542
2217     <p>RANGE_MAX -
2218     </p>
2219     <blockquote class="text">
2220     <p>defines upper limit of the allowed value range for this
2221     parameter, can be an integer value as well as a dotted
2222     number, usually used in conjunction with 'RANGE_MIN',
2223     but may also appear without
2224     (optionally returned, dependent to driver and channel
2225     parameter)
2226     </p>
2227 schoenebeck 940 </blockquote>
2228    
2229 senoner 542
2230     <p>POSSIBILITIES -
2231     </p>
2232     <blockquote class="text">
2233     <p>comma separated list of possible values for this
2234     parameter, character strings are encapsulated into
2235     apostrophes
2236     (optionally returned, dependent to driver and channel
2237     parameter)
2238     </p>
2239 schoenebeck 940 </blockquote>
2240    
2241 senoner 542
2242 schoenebeck 940 </blockquote>
2243    
2244 senoner 542
2245     <p>The mentioned fields above don't have to be in particular order.
2246     </p>
2247 schoenebeck 708 </blockquote><p>
2248 schoenebeck 940
2249 schoenebeck 708 </p>
2250 senoner 542 <p>Example:
2251     </p>
2252 schoenebeck 708 <p>
2253     </p>
2254 senoner 542 <blockquote class="text">
2255     <p>C: "GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO 1 0 JACK_BINDINGS"
2256     </p>
2257     <p>S: "DESCRIPTION: bindings to other JACK clients"
2258     </p>
2259     <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
2260     </p>
2261     <p>&nbsp;&nbsp;&nbsp;"FIX: false"
2262     </p>
2263     <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"
2264     </p>
2265     <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"
2266     </p>
2267     <p>&nbsp;&nbsp;&nbsp;"."
2268     </p>
2269 schoenebeck 708 </blockquote><p>
2270 schoenebeck 940
2271 schoenebeck 708 </p>
2272 schoenebeck 940 <a name="SET AUDIO_OUTPUT_CHANNEL_PARAMETER"></a><br /><hr />
2273 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2274     <a name="rfc.section.6.2.13"></a><h3>6.2.13.&nbsp;
2275     Changing settings of audio output channels</h3>
2276 senoner 542
2277     <p>Use the following command to alter a specific setting of an audio output channel:
2278     </p>
2279 schoenebeck 708 <p>
2280     </p>
2281 senoner 542 <blockquote class="text">
2282     <p>SET AUDIO_OUTPUT_CHANNEL_PARAMETER &lt;dev-id&gt; &lt;chn&gt; &lt;key&gt;=&lt;value&gt;
2283     </p>
2284 schoenebeck 708 </blockquote><p>
2285 schoenebeck 940
2286 schoenebeck 708 </p>
2287 schoenebeck 575 <p>Where &lt;dev-id&gt; should be replaced by the numerical ID of the audio output device as returned by the
2288 schoenebeck 974 <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>
2289     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>
2290 schoenebeck 575 command, &lt;chn&gt; by the audio channel number, &lt;key&gt; by the name of the
2291 senoner 542 parameter to change and &lt;value&gt; by the new value for this parameter.
2292     </p>
2293     <p>Possible Answers:
2294     </p>
2295 schoenebeck 708 <p>
2296     </p>
2297 senoner 542 <blockquote class="text">
2298     <p>"OK" -
2299     </p>
2300     <blockquote class="text">
2301     <p>in case setting was successfully changed
2302     </p>
2303 schoenebeck 940 </blockquote>
2304    
2305 senoner 542
2306     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2307     </p>
2308     <blockquote class="text">
2309     <p>in case setting was changed successfully, but there are
2310     noteworthy issue(s) related, providing an appropriate
2311     warning code and warning message
2312     </p>
2313 schoenebeck 940 </blockquote>
2314    
2315 senoner 542
2316     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2317     </p>
2318     <blockquote class="text">
2319     <p>in case it failed, providing an appropriate error code and
2320     error message
2321     </p>
2322 schoenebeck 940 </blockquote>
2323    
2324 senoner 542
2325 schoenebeck 708 </blockquote><p>
2326 schoenebeck 940
2327 schoenebeck 708 </p>
2328 senoner 542 <p>Example:
2329     </p>
2330 schoenebeck 708 <p>
2331     </p>
2332 senoner 542 <blockquote class="text">
2333     <p>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"
2334     </p>
2335     <p>S: "OK"
2336     </p>
2337 schoenebeck 708 </blockquote><p>
2338 schoenebeck 940
2339 schoenebeck 708 </p>
2340     <p>
2341     </p>
2342 senoner 542 <blockquote class="text">
2343     <p>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"
2344     </p>
2345     <p>S: "OK"
2346     </p>
2347 schoenebeck 708 </blockquote><p>
2348 schoenebeck 940
2349 schoenebeck 708 </p>
2350 schoenebeck 940 <a name="anchor10"></a><br /><hr />
2351 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2352     <a name="rfc.section.6.3"></a><h3>6.3.&nbsp;
2353     Configuring MIDI input drivers</h3>
2354 senoner 542
2355     <p>Instances of drivers in LinuxSampler are called devices. You can use
2356     multiple MIDI devices simultaneously, e.g. to use MIDI over ethernet as
2357     MIDI input on one sampler channel and ALSA as MIDI input on another sampler
2358     channel. For particular MIDI input systems it's also possible to create
2359     several devices of the same MIDI input type. This chapter describes all
2360     commands to configure LinuxSampler's MIDI input devices and their parameters.
2361     </p>
2362     <p>Instead of defining commands and parameters for each driver individually,
2363     all possible parameters, their meanings and possible values have to be obtained
2364     at runtime. This makes the protocol a bit abstract, but has the advantage, that
2365     front-ends can be written independently of what drivers are currently implemented
2366     and what parameters these drivers are actually offering. This means front-ends can
2367     even handle drivers which are implemented somewhere in future without modifying
2368     the front-end at all.
2369     </p>
2370     <p>Commands for configuring MIDI input devices are pretty much the same as the
2371     commands for configuring audio output drivers, already described in the last
2372     chapter.
2373     </p>
2374     <p>Note: examples in this chapter showing particular parameters of drivers are
2375     not meant as specification of the drivers' parameters. Driver implementations in
2376     LinuxSampler might have complete different parameter names and meanings than shown
2377     in these examples or might change in future, so these examples are only meant for
2378     showing how to retrieve what parameters drivers are offering, how to retrieve their
2379     possible values, etc.
2380     </p>
2381 schoenebeck 940 <a name="GET AVAILABLE_MIDI_INPUT_DRIVERS"></a><br /><hr />
2382 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2383     <a name="rfc.section.6.3.1"></a><h3>6.3.1.&nbsp;
2384     Getting amount of available MIDI input drivers</h3>
2385 senoner 542
2386     <p>Use the following command to get the number of
2387     MIDI input drivers currently available for the
2388     LinuxSampler instance:
2389     </p>
2390 schoenebeck 708 <p>
2391     </p>
2392 senoner 542 <blockquote class="text">
2393     <p>GET AVAILABLE_MIDI_INPUT_DRIVERS
2394     </p>
2395 schoenebeck 708 </blockquote><p>
2396 schoenebeck 940
2397 schoenebeck 708 </p>
2398 senoner 542 <p>Possible Answers:
2399     </p>
2400 schoenebeck 708 <p>
2401     </p>
2402 senoner 542 <blockquote class="text">
2403     <p>LinuxSampler will answer by sending the
2404     number of available MIDI input drivers.
2405     </p>
2406 schoenebeck 708 </blockquote><p>
2407 schoenebeck 940
2408 schoenebeck 708 </p>
2409 senoner 542 <p>Example:
2410     </p>
2411 schoenebeck 708 <p>
2412     </p>
2413 senoner 542 <blockquote class="text">
2414     <p>C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"
2415     </p>
2416     <p>S: "2"
2417     </p>
2418 schoenebeck 708 </blockquote><p>
2419 schoenebeck 940
2420 schoenebeck 708 </p>
2421 schoenebeck 940 <a name="LIST AVAILABLE_MIDI_INPUT_DRIVERS"></a><br /><hr />
2422 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2423     <a name="rfc.section.6.3.2"></a><h3>6.3.2.&nbsp;
2424     Getting all available MIDI input drivers</h3>
2425 senoner 542
2426     <p>Use the following command to list all MIDI input drivers currently available
2427     for the LinuxSampler instance:
2428     </p>
2429 schoenebeck 708 <p>
2430     </p>
2431 senoner 542 <blockquote class="text">
2432     <p>LIST AVAILABLE_MIDI_INPUT_DRIVERS
2433     </p>
2434 schoenebeck 708 </blockquote><p>
2435 schoenebeck 940
2436 schoenebeck 708 </p>
2437 senoner 542 <p>Possible Answers:
2438     </p>
2439 schoenebeck 708 <p>
2440     </p>
2441 senoner 542 <blockquote class="text">
2442     <p>LinuxSampler will answer by sending comma separated character
2443     strings, each symbolizing a MIDI input driver.
2444     </p>
2445 schoenebeck 708 </blockquote><p>
2446 schoenebeck 940
2447 schoenebeck 708 </p>
2448 senoner 542 <p>Example:
2449     </p>
2450 schoenebeck 708 <p>
2451     </p>
2452 senoner 542 <blockquote class="text">
2453     <p>C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
2454     </p>
2455     <p>S: "ALSA,JACK"
2456     </p>
2457 schoenebeck 708 </blockquote><p>
2458 schoenebeck 940
2459 schoenebeck 708 </p>
2460 schoenebeck 940 <a name="GET MIDI_INPUT_DRIVER INFO"></a><br /><hr />
2461 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2462     <a name="rfc.section.6.3.3"></a><h3>6.3.3.&nbsp;
2463     Getting information about a specific MIDI input driver</h3>
2464 senoner 542
2465     <p>Use the following command to get detailed information about a specific MIDI input driver:
2466     </p>
2467 schoenebeck 708 <p>
2468     </p>
2469 senoner 542 <blockquote class="text">
2470     <p>GET MIDI_INPUT_DRIVER INFO &lt;midi-input-driver&gt;
2471     </p>
2472 schoenebeck 708 </blockquote><p>
2473 schoenebeck 940
2474 schoenebeck 708 </p>
2475 schoenebeck 575 <p>Where &lt;midi-input-driver&gt; is the name of the MIDI input driver as returned
2476 schoenebeck 974 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.
2477 senoner 542 </p>
2478     <p>Possible Answers:
2479     </p>
2480 schoenebeck 708 <p>
2481     </p>
2482 senoner 542 <blockquote class="text">
2483     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2484     Each answer line begins with the information category name
2485     followed by a colon and then a space character &lt;SP&gt; and finally
2486     the info character string to that info category. At the moment
2487     the following information categories are defined:
2488     </p>
2489 schoenebeck 708 <p>
2490     </p>
2491 senoner 542 <blockquote class="text">
2492     <p>DESCRIPTION -
2493     </p>
2494     <blockquote class="text">
2495     <p>arbitrary description text about the MIDI input driver
2496     </p>
2497 schoenebeck 940 </blockquote>
2498    
2499 senoner 542
2500     <p>VERSION -
2501     </p>
2502     <blockquote class="text">
2503     <p>arbitrary character string regarding the driver's version
2504     </p>
2505 schoenebeck 940 </blockquote>
2506    
2507 senoner 542
2508     <p>PARAMETERS -
2509     </p>
2510     <blockquote class="text">
2511     <p>comma separated list of all parameters available for the given MIDI input driver
2512     </p>
2513 schoenebeck 940 </blockquote>
2514    
2515 senoner 542
2516 schoenebeck 940 </blockquote>
2517    
2518 senoner 542
2519     <p>The mentioned fields above don't have to be in particular order.
2520     </p>
2521 schoenebeck 708 </blockquote><p>
2522 schoenebeck 940
2523 schoenebeck 708 </p>
2524 senoner 542 <p>Example:
2525     </p>
2526 schoenebeck 708 <p>
2527     </p>
2528 senoner 542 <blockquote class="text">
2529     <p>C: "GET MIDI_INPUT_DRIVER INFO ALSA"
2530     </p>
2531     <p>S: "DESCRIPTION: Advanced Linux Sound Architecture"
2532     </p>
2533     <p>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"
2534     </p>
2535     <p>&nbsp;&nbsp;&nbsp;"PARAMETERS: DRIVER,ACTIVE"
2536     </p>
2537     <p>&nbsp;&nbsp;&nbsp;"."
2538     </p>
2539 schoenebeck 708 </blockquote><p>
2540 schoenebeck 940
2541 schoenebeck 708 </p>
2542 schoenebeck 940 <a name="GET MIDI_INPUT_DRIVER_PARAMETER INFO"></a><br /><hr />
2543 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2544     <a name="rfc.section.6.3.4"></a><h3>6.3.4.&nbsp;
2545     Getting information about specific MIDI input driver parameter</h3>
2546 senoner 542
2547     <p>Use the following command to get detailed information about a specific parameter of a specific MIDI input driver:
2548     </p>
2549 schoenebeck 708 <p>
2550     </p>
2551 senoner 542 <blockquote class="text">
2552     <p>GET MIDI_INPUT_DRIVER_PARAMETER INFO &lt;midit&gt; &lt;param&gt; [&lt;deplist&gt;]
2553     </p>
2554 schoenebeck 708 </blockquote><p>
2555 schoenebeck 940
2556 schoenebeck 708 </p>
2557 schoenebeck 561 <p>Where &lt;midit&gt; is the name of the MIDI input driver as returned
2558 schoenebeck 974 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
2559 senoner 542 parameter name for which information should be obtained (as returned by the
2560 schoenebeck 974 <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
2561 senoner 542 of parameters on which the sought parameter &lt;param&gt; depends on,
2562     &lt;deplist&gt; is a key-value pair list in form of "key1=val1 key2=val2 ...",
2563     where character string values are encapsulated into apostrophes ('). Arguments
2564     given with &lt;deplist&gt; which are not dependency parameters of &lt;param&gt;
2565     will be ignored, means the front-end application can simply put all parameters
2566     in &lt;deplist&gt; with the values selected by the user.
2567     </p>
2568     <p>Possible Answers:
2569     </p>
2570     <p>LinuxSampler will answer by sending a &lt;CRLF> separated list.
2571     Each answer line begins with the information category name
2572     followed by a colon and then a space character &lt;SP> and finally
2573     the info character string to that info category. There is
2574     information which is always returned, independent of the
2575     given driver parameter and there is optional information
2576     which is only shown dependent to given driver parameter. At
2577     the moment the following information categories are defined:
2578     </p>
2579 schoenebeck 708 <p>
2580     </p>
2581 senoner 542 <blockquote class="text">
2582     <p>TYPE -
2583     </p>
2584     <blockquote class="text">
2585     <p>either "BOOL" for boolean value(s) or "INT" for integer
2586     value(s) or "FLOAT" for dotted number(s) or "STRING" for
2587     character string(s)
2588     (always returned, no matter which driver parameter)
2589     </p>
2590 schoenebeck 940 </blockquote>
2591    
2592 senoner 542
2593     <p>DESCRIPTION -
2594     </p>
2595     <blockquote class="text">
2596     <p>arbitrary text describing the purpose of the parameter
2597     (always returned, no matter which driver parameter)
2598     </p>
2599 schoenebeck 940 </blockquote>
2600    
2601 senoner 542
2602     <p>MANDATORY -
2603     </p>
2604     <blockquote class="text">
2605     <p>either true or false, defines if this parameter must be
2606     given when the device is to be created with the
2607 schoenebeck 974 <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
2608 senoner 542 (always returned, no matter which driver parameter)
2609     </p>
2610 schoenebeck 940 </blockquote>
2611    
2612 senoner 542
2613     <p>FIX -
2614     </p>
2615     <blockquote class="text">
2616     <p>either true or false, if false then this parameter can
2617     be changed at any time, once the device is created by
2618 schoenebeck 974 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
2619 senoner 542 (always returned, no matter which driver parameter)
2620     </p>
2621 schoenebeck 940 </blockquote>
2622    
2623 senoner 542
2624     <p>MULTIPLICITY -
2625     </p>
2626     <blockquote class="text">
2627     <p>either true or false, defines if this parameter allows
2628     only one value or a list of values, where true means
2629     multiple values and false only a single value allowed
2630     (always returned, no matter which driver parameter)
2631     </p>
2632 schoenebeck 940 </blockquote>
2633    
2634 senoner 542
2635     <p>DEPENDS -
2636     </p>
2637     <blockquote class="text">
2638 schoenebeck 561 <p>comma separated list of parameters this parameter depends
2639 senoner 542 on, means the values for fields 'DEFAULT', 'RANGE_MIN',
2640     'RANGE_MAX' and 'POSSIBILITIES' might depend on these
2641     listed parameters, for example assuming that an audio
2642     driver (like the ALSA driver) offers parameters 'card'
2643     and 'samplerate' then parameter 'samplerate' would
2644     depend on 'card' because the possible values for
2645     'samplerate' depends on the sound card which can be
2646     chosen by the 'card' parameter
2647     (optionally returned, dependent to driver parameter)
2648     </p>
2649 schoenebeck 940 </blockquote>
2650    
2651 senoner 542
2652     <p>DEFAULT -
2653     </p>
2654     <blockquote class="text">
2655     <p>reflects the default value for this parameter which is
2656     used when the device is created and not explicitly
2657 schoenebeck 974 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,
2658 senoner 542 in case of MULTIPLCITY=true, this is a comma separated
2659     list, that's why character strings are encapsulated into
2660     apostrophes (')
2661     (optionally returned, dependent to driver parameter)
2662     </p>
2663 schoenebeck 940 </blockquote>
2664    
2665 senoner 542
2666     <p>RANGE_MIN -
2667     </p>
2668     <blockquote class="text">
2669     <p>defines lower limit of the allowed value range for this
2670     parameter, can be an integer value as well as a dotted
2671     number, this parameter is often used in conjunction
2672     with RANGE_MAX, but may also appear without
2673     (optionally returned, dependent to driver parameter)
2674     </p>
2675 schoenebeck 940 </blockquote>
2676    
2677 senoner 542
2678     <p>RANGE_MAX -
2679     </p>
2680     <blockquote class="text">
2681     <p>defines upper limit of the allowed value range for this
2682     parameter, can be an integer value as well as a dotted
2683     number, this parameter is often used in conjunction with
2684     RANGE_MIN, but may also appear without
2685     (optionally returned, dependent to driver parameter)
2686     </p>
2687 schoenebeck 940 </blockquote>
2688    
2689 senoner 542
2690     <p>POSSIBILITIES -
2691     </p>
2692     <blockquote class="text">
2693     <p>comma separated list of possible values for this
2694     parameter, character strings are encapsulated into
2695     apostrophes
2696     (optionally returned, dependent to driver parameter)
2697     </p>
2698 schoenebeck 940 </blockquote>
2699    
2700 senoner 542
2701 schoenebeck 708 </blockquote><p>
2702 schoenebeck 940
2703 schoenebeck 708 </p>
2704 senoner 542 <p>The mentioned fields above don't have to be in particular order.
2705     </p>
2706     <p>Example:
2707     </p>
2708 schoenebeck 708 <p>
2709     </p>
2710 senoner 542 <blockquote class="text">
2711     <p>C: "GET MIDI_INPUT_DRIVER_PARAMETER INFO ALSA ACTIVE"
2712     </p>
2713     <p>S: "DESCRIPTION: Whether device is enabled"
2714     </p>
2715     <p>&nbsp;&nbsp;&nbsp;"TYPE: BOOL"
2716     </p>
2717     <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
2718     </p>
2719     <p>&nbsp;&nbsp;&nbsp;"FIX: false"
2720     </p>
2721     <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
2722     </p>
2723     <p>&nbsp;&nbsp;&nbsp;"DEFAULT: true"
2724     </p>
2725     <p>&nbsp;&nbsp;&nbsp;"."
2726     </p>
2727 schoenebeck 708 </blockquote><p>
2728 schoenebeck 940
2729 schoenebeck 708 </p>
2730 schoenebeck 940 <a name="CREATE MIDI_INPUT_DEVICE"></a><br /><hr />
2731 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2732     <a name="rfc.section.6.3.5"></a><h3>6.3.5.&nbsp;
2733     Creating a MIDI input device</h3>
2734 senoner 542
2735     <p>Use the following command to create a new MIDI input device for the desired MIDI input system:
2736     </p>
2737 schoenebeck 708 <p>
2738     </p>
2739 senoner 542 <blockquote class="text">
2740     <p>CREATE MIDI_INPUT_DEVICE &lt;midi-input-driver&gt; [&lt;param-list&gt;]
2741     </p>
2742 schoenebeck 708 </blockquote><p>
2743 schoenebeck 940
2744 schoenebeck 708 </p>
2745 schoenebeck 575 <p>Where &lt;midi-input-driver&gt; should be replaced by the desired MIDI input system as returned
2746 schoenebeck 974 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
2747 senoner 542 optional list of driver specific parameters in form of "key1=val1 key2=val2 ...", where
2748     character string values should be encapsulated into apostrophes (').
2749     Note that there might be drivers which require parameter(s) to be
2750     given with this command. Use the previously described commands in
2751     this chapter to get that information.
2752     </p>
2753     <p>Possible Answers:
2754     </p>
2755 schoenebeck 708 <p>
2756     </p>
2757 senoner 542 <blockquote class="text">
2758     <p>"OK[&lt;device-id&gt;]" -
2759     </p>
2760     <blockquote class="text">
2761     <p>in case the device was successfully created, where
2762     &lt;device-id&gt; is the numerical ID of the new device
2763     </p>
2764 schoenebeck 940 </blockquote>
2765    
2766 senoner 542
2767     <p>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2768     </p>
2769     <blockquote class="text">
2770     <p>in case the driver was loaded successfully, where
2771     &lt;device-id&gt; is the numerical ID of the new device, but
2772     there are noteworthy issue(s) related, providing an
2773     appropriate warning code and warning message
2774     </p>
2775 schoenebeck 940 </blockquote>
2776    
2777 senoner 542
2778     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2779     </p>
2780     <blockquote class="text">
2781     <p>in case it failed, providing an appropriate error code and error message
2782     </p>
2783 schoenebeck 940 </blockquote>
2784    
2785 senoner 542
2786 schoenebeck 708 </blockquote><p>
2787 schoenebeck 940
2788 schoenebeck 708 </p>
2789 senoner 542 <p>Example:
2790     </p>
2791 schoenebeck 708 <p>
2792     </p>
2793 senoner 542 <blockquote class="text">
2794     <p>C: "CREATE MIDI_INPUT_DEVICE ALSA"
2795     </p>
2796     <p>S: "OK[0]"
2797     </p>
2798 schoenebeck 708 </blockquote><p>
2799 schoenebeck 940
2800 schoenebeck 708 </p>
2801 schoenebeck 940 <a name="DESTROY MIDI_INPUT_DEVICE"></a><br /><hr />
2802 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2803     <a name="rfc.section.6.3.6"></a><h3>6.3.6.&nbsp;
2804     Destroying a MIDI input device</h3>
2805 senoner 542
2806     <p>Use the following command to destroy a created MIDI input device:
2807     </p>
2808 schoenebeck 708 <p>
2809     </p>
2810 senoner 542 <blockquote class="text">
2811     <p>DESTROY MIDI_INPUT_DEVICE &lt;device-id&gt;
2812     </p>
2813 schoenebeck 708 </blockquote><p>
2814 schoenebeck 940
2815 schoenebeck 708 </p>
2816 schoenebeck 575 <p>Where &lt;device-id&gt; should be replaced by the device's numerical ID as returned by the
2817 schoenebeck 974 <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>
2818     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>
2819 schoenebeck 575 command.
2820 senoner 542 </p>
2821     <p>Possible Answers:
2822     </p>
2823 schoenebeck 708 <p>
2824     </p>
2825 senoner 542 <blockquote class="text">
2826     <p>"OK" -
2827     </p>
2828     <blockquote class="text">
2829     <p>in case the device was successfully destroyed
2830     </p>
2831 schoenebeck 940 </blockquote>
2832    
2833 senoner 542
2834     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2835     </p>
2836     <blockquote class="text">
2837     <p>in case the device was destroyed, but there are noteworthy
2838     issue(s) related, providing an appropriate warning code and
2839     warning message
2840     </p>
2841 schoenebeck 940 </blockquote>
2842    
2843 senoner 542
2844     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2845     </p>
2846     <blockquote class="text">
2847     <p>in case it failed, providing an appropriate error code and error message
2848     </p>
2849 schoenebeck 940 </blockquote>
2850    
2851 senoner 542
2852 schoenebeck 708 </blockquote><p>
2853 schoenebeck 940
2854 schoenebeck 708 </p>
2855 senoner 542 <p>Example:
2856     </p>
2857 schoenebeck 708 <p>
2858     </p>
2859 senoner 542 <blockquote class="text">
2860     <p>C: "DESTROY MIDI_INPUT_DEVICE 0"
2861     </p>
2862     <p>S: "OK"
2863     </p>
2864 schoenebeck 708 </blockquote><p>
2865 schoenebeck 940
2866 schoenebeck 708 </p>
2867 schoenebeck 940 <a name="GET MIDI_INPUT_DEVICES"></a><br /><hr />
2868 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2869     <a name="rfc.section.6.3.7"></a><h3>6.3.7.&nbsp;
2870     Getting all created MIDI input device count</h3>
2871 senoner 542
2872     <p>Use the following command to count all created MIDI input devices:
2873     </p>
2874 schoenebeck 708 <p>
2875     </p>
2876 senoner 542 <blockquote class="text">
2877     <p>GET MIDI_INPUT_DEVICES
2878     </p>
2879 schoenebeck 708 </blockquote><p>
2880 schoenebeck 940
2881 schoenebeck 708 </p>
2882 senoner 542 <p>Possible Answers:
2883     </p>
2884 schoenebeck 708 <p>
2885     </p>
2886 senoner 542 <blockquote class="text">
2887     <p>LinuxSampler will answer by sending the current number of all
2888     MIDI input devices.
2889     </p>
2890 schoenebeck 708 </blockquote><p>
2891 schoenebeck 940
2892 schoenebeck 708 </p>
2893 senoner 542 <p>Example:
2894     </p>
2895 schoenebeck 708 <p>
2896     </p>
2897 senoner 542 <blockquote class="text">
2898     <p>C: "GET MIDI_INPUT_DEVICES"
2899     </p>
2900     <p>S: "3"
2901     </p>
2902 schoenebeck 708 </blockquote><p>
2903 schoenebeck 940
2904 schoenebeck 708 </p>
2905 schoenebeck 940 <a name="LIST MIDI_INPUT_DEVICES"></a><br /><hr />
2906 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2907     <a name="rfc.section.6.3.8"></a><h3>6.3.8.&nbsp;
2908     Getting all created MIDI input device list</h3>
2909 senoner 542
2910     <p>Use the following command to list all created MIDI input devices:
2911     </p>
2912 schoenebeck 708 <p>
2913     </p>
2914 senoner 542 <blockquote class="text">
2915     <p>LIST MIDI_INPUT_DEVICES
2916     </p>
2917 schoenebeck 708 </blockquote><p>
2918 schoenebeck 940
2919 schoenebeck 708 </p>
2920 senoner 542 <p>Possible Answers:
2921     </p>
2922 schoenebeck 708 <p>
2923     </p>
2924 senoner 542 <blockquote class="text">
2925     <p>LinuxSampler will answer by sending a comma separated list
2926     with the numerical Ids of all created MIDI input devices.
2927     </p>
2928 schoenebeck 708 </blockquote><p>
2929 schoenebeck 940
2930 schoenebeck 708 </p>
2931 senoner 542 <p>Examples:
2932     </p>
2933 schoenebeck 708 <p>
2934     </p>
2935 senoner 542 <blockquote class="text">
2936     <p>C: "LIST MIDI_INPUT_DEVICES"
2937     </p>
2938     <p>S: "0,1,2"
2939     </p>
2940 schoenebeck 708 </blockquote><p>
2941 schoenebeck 940
2942 schoenebeck 708 </p>
2943     <p>
2944     </p>
2945 senoner 542 <blockquote class="text">
2946     <p>C: "LIST MIDI_INPUT_DEVICES"
2947     </p>
2948     <p>S: "1,3"
2949     </p>
2950 schoenebeck 708 </blockquote><p>
2951 schoenebeck 940
2952 schoenebeck 708 </p>
2953 schoenebeck 940 <a name="GET MIDI_INPUT_DEVICE INFO"></a><br /><hr />
2954 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
2955     <a name="rfc.section.6.3.9"></a><h3>6.3.9.&nbsp;
2956     Getting current settings of a MIDI input device</h3>
2957 senoner 542
2958     <p>Use the following command to get current settings of a specific, created MIDI input device:
2959     </p>
2960 schoenebeck 708 <p>
2961     </p>
2962 senoner 542 <blockquote class="text">
2963     <p>GET MIDI_INPUT_DEVICE INFO &lt;device-id&gt;
2964     </p>
2965 schoenebeck 708 </blockquote><p>
2966 schoenebeck 940
2967 schoenebeck 708 </p>
2968 schoenebeck 575 <p>Where &lt;device-id&gt; is the numerical ID of the MIDI input device as returned by the
2969 schoenebeck 974 <a class='info' href='#CREATE MIDI_INPUT_DEVICE'>"CREATE MIDI_INPUT_DEVICE"<span> (</span><span class='info'>Creating a MIDI input device</span><span>)</span></a>
2970     or <a class='info' href='#LIST MIDI_INPUT_DEVICES'>"LIST MIDI_INPUT_DEVICES"<span> (</span><span class='info'>Getting all created MIDI input device list</span><span>)</span></a>
2971 schoenebeck 575 command.
2972 senoner 542 </p>
2973     <p>Possible Answers:
2974     </p>
2975 schoenebeck 708 <p>
2976     </p>
2977 senoner 542 <blockquote class="text">
2978     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2979     Each answer line begins with the information category name
2980     followed by a colon and then a space character &lt;SP&gt; and finally
2981     the info character string to that info category. As some
2982     parameters might allow multiple values, character strings are
2983     encapsulated into apostrophes ('). At the moment the following
2984     information categories are defined (independent of driver):
2985     </p>
2986 schoenebeck 708 <p>
2987     </p>
2988 senoner 542 <blockquote class="text">
2989     <p>DRIVER -
2990     </p>
2991     <blockquote class="text">
2992     <p>identifier of the used MIDI input driver, as e.g.
2993 schoenebeck 974 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>
2994 senoner 542 command
2995     </p>
2996 schoenebeck 940 </blockquote>
2997    
2998 senoner 542
2999 schoenebeck 940 </blockquote>
3000    
3001 senoner 542 <blockquote class="text">
3002 schoenebeck 708 <p>ACTIVE -
3003 senoner 542 </p>
3004     <blockquote class="text">
3005     <p>either true or false, if false then the MIDI device is
3006     inactive and doesn't listen to any incoming MIDI events
3007     and thus doesn't forward them to connected sampler
3008     channels
3009     </p>
3010 schoenebeck 940 </blockquote>
3011    
3012 senoner 542
3013 schoenebeck 940 </blockquote>
3014    
3015 senoner 542
3016 schoenebeck 708 </blockquote><p>
3017 schoenebeck 940
3018 schoenebeck 708 </p>
3019 senoner 542 <p>The mentioned fields above don't have to be in particular
3020     order. The fields above are only those fields which are
3021     returned by all MIDI input devices. Every MIDI input driver
3022     might have its own, additional driver specific parameters (see
3023 schoenebeck 974 <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
3024 senoner 542 by this command.
3025     </p>
3026     <p>Example:
3027     </p>
3028 schoenebeck 708 <p>
3029     </p>
3030 senoner 542 <blockquote class="text">
3031     <p>C: "GET MIDI_INPUT_DEVICE INFO 0"
3032     </p>
3033     <p>S: "DRIVER: ALSA"
3034     </p>
3035     <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
3036     </p>
3037     <p>&nbsp;&nbsp;&nbsp;"."
3038     </p>
3039 schoenebeck 708 </blockquote><p>
3040 schoenebeck 940
3041 schoenebeck 708 </p>
3042 schoenebeck 940 <a name="SET MIDI_INPUT_DEVICE_PARAMETER"></a><br /><hr />
3043 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3044     <a name="rfc.section.6.3.10"></a><h3>6.3.10.&nbsp;
3045     Changing settings of MIDI input devices</h3>
3046 senoner 542
3047     <p>Use the following command to alter a specific setting of a created MIDI input device:
3048     </p>
3049 schoenebeck 708 <p>
3050     </p>
3051 senoner 542 <blockquote class="text">
3052     <p>SET MIDI_INPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;
3053     </p>
3054 schoenebeck 708 </blockquote><p>
3055 schoenebeck 940
3056 schoenebeck 708 </p>
3057 senoner 542 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
3058 schoenebeck 575 MIDI input device as returned by the
3059 schoenebeck 974 <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>
3060     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>
3061 schoenebeck 575 command, &lt;key&gt; by the name of the parameter to change and
3062 senoner 542 &lt;value&gt; by the new value for this parameter.
3063     </p>
3064     <p>Possible Answers:
3065     </p>
3066 schoenebeck 708 <p>
3067     </p>
3068 senoner 542 <blockquote class="text">
3069     <p>"OK" -
3070     </p>
3071     <blockquote class="text">
3072     <p>in case setting was successfully changed
3073     </p>
3074 schoenebeck 940 </blockquote>
3075    
3076 senoner 542
3077     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3078     </p>
3079     <blockquote class="text">
3080     <p>in case setting was changed successfully, but there are
3081     noteworthy issue(s) related, providing an appropriate
3082     warning code and warning message
3083     </p>
3084 schoenebeck 940 </blockquote>
3085    
3086 senoner 542
3087     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3088     </p>
3089     <blockquote class="text">
3090     <p>in case it failed, providing an appropriate error code and error message
3091     </p>
3092 schoenebeck 940 </blockquote>
3093    
3094 senoner 542
3095 schoenebeck 708 </blockquote><p>
3096 schoenebeck 940
3097 schoenebeck 708 </p>
3098 senoner 542 <p>Example:
3099     </p>
3100 schoenebeck 708 <p>
3101     </p>
3102 senoner 542 <blockquote class="text">
3103     <p>C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"
3104     </p>
3105     <p>S: "OK"
3106     </p>
3107 schoenebeck 708 </blockquote><p>
3108 schoenebeck 940
3109 schoenebeck 708 </p>
3110 schoenebeck 940 <a name="GET MIDI_INPUT_PORT INFO"></a><br /><hr />
3111 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3112     <a name="rfc.section.6.3.11"></a><h3>6.3.11.&nbsp;
3113     Getting information about a MIDI port</h3>
3114 senoner 542
3115     <p>Use the following command to get information about a MIDI port:
3116     </p>
3117 schoenebeck 708 <p>
3118     </p>
3119 senoner 542 <blockquote class="text">
3120     <p>GET MIDI_INPUT_PORT INFO &lt;device-id&gt; &lt;midi-port&gt;
3121     </p>
3122 schoenebeck 708 </blockquote><p>
3123 schoenebeck 940
3124 schoenebeck 708 </p>
3125 schoenebeck 575 <p>Where &lt;device-id&gt; is the numerical ID of the MIDI input device as returned by the
3126 schoenebeck 974 <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>
3127     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>
3128 schoenebeck 575 command and &lt;midi-port&gt; the MIDI input port number.
3129 senoner 542 </p>
3130     <p>Possible Answers:
3131     </p>
3132 schoenebeck 708 <p>
3133     </p>
3134 senoner 542 <blockquote class="text">
3135     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3136     Each answer line begins with the information category name
3137     followed by a colon and then a space character &lt;SP&gt; and finally
3138     the info character string to that info category. At the moment
3139     the following information categories are defined:
3140     </p>
3141     <p>NAME -
3142     </p>
3143     <blockquote class="text">
3144     <p>arbitrary character string naming the port
3145     </p>
3146 schoenebeck 940 </blockquote>
3147    
3148 senoner 542
3149 schoenebeck 708 </blockquote><p>
3150 schoenebeck 940
3151 schoenebeck 708 </p>
3152 senoner 542 <p>The field above is only the one which is returned by all MIDI
3153     ports regardless of the MIDI driver and port. Every MIDI port
3154     might have its own, additional driver and port specific
3155     parameters.
3156     </p>
3157     <p>Example:
3158     </p>
3159 schoenebeck 708 <p>
3160     </p>
3161 senoner 542 <blockquote class="text">
3162     <p>C: "GET MIDI_INPUT_PORT INFO 0 0"
3163     </p>
3164     <p>S: "NAME: 'Masterkeyboard'"
3165     </p>
3166     <p>&nbsp;&nbsp;&nbsp;"ALSA_SEQ_BINDINGS: '64:0'"
3167     </p>
3168     <p>&nbsp;&nbsp;&nbsp;"."
3169     </p>
3170 schoenebeck 708 </blockquote><p>
3171 schoenebeck 940
3172 schoenebeck 708 </p>
3173 schoenebeck 940 <a name="GET MIDI_INPUT_PORT_PARAMETER INFO"></a><br /><hr />
3174 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3175     <a name="rfc.section.6.3.12"></a><h3>6.3.12.&nbsp;
3176     Getting information about specific MIDI port parameter</h3>
3177 senoner 542
3178     <p>Use the following command to get detailed information about specific MIDI port parameter:
3179     </p>
3180 schoenebeck 708 <p>
3181     </p>
3182 senoner 542 <blockquote class="text">
3183     <p>GET MIDI_INPUT_PORT_PARAMETER INFO &lt;dev-id&gt; &lt;port&gt; &lt;param&gt;
3184     </p>
3185 schoenebeck 708 </blockquote><p>
3186 schoenebeck 940
3187 schoenebeck 708 </p>
3188 schoenebeck 575 <p>Where &lt;dev-id&gt; is the numerical ID of the MIDI input device as returned by the
3189 schoenebeck 974 <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>
3190     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>
3191 schoenebeck 575 command, &lt;port&gt; the MIDI port number and
3192 senoner 542 &lt;param&gt; a specific port parameter name for which information should be
3193 schoenebeck 974 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).
3194 senoner 542 </p>
3195     <p>Possible Answers:
3196     </p>
3197 schoenebeck 708 <p>
3198     </p>
3199 senoner 542 <blockquote class="text">
3200     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3201     Each answer line begins with the information category name
3202     followed by a colon and then a space character &lt;SP&gt; and finally
3203     the info character string to that info category. There is
3204     information which is always returned, independently of the
3205     given channel parameter and there is optional information
3206     which are only shown dependently to the given MIDI port. At the
3207     moment the following information categories are defined:
3208     </p>
3209     <p>TYPE -
3210     </p>
3211     <blockquote class="text">
3212     <p>either "BOOL" for boolean value(s) or "INT" for integer
3213     value(s) or "FLOAT" for dotted number(s) or "STRING" for
3214     character string(s)
3215     (always returned)
3216     </p>
3217 schoenebeck 940 </blockquote>
3218    
3219 senoner 542
3220     <p>DESCRIPTION -
3221     </p>
3222     <blockquote class="text">
3223     <p>arbitrary text describing the purpose of the parameter
3224     (always returned)
3225     </p>
3226 schoenebeck 940 </blockquote>
3227    
3228 senoner 542
3229     <p>FIX -
3230     </p>
3231     <blockquote class="text">
3232     <p>either true or false, if true then this parameter is
3233     read only, thus cannot be altered
3234     (always returned)
3235     </p>
3236 schoenebeck 940 </blockquote>
3237    
3238 senoner 542
3239     <p>MULTIPLICITY -
3240     </p>
3241     <blockquote class="text">
3242     <p>either true or false, defines if this parameter allows
3243     only one value or a list of values, where true means
3244     multiple values and false only a single value allowed
3245     (always returned)
3246     </p>
3247 schoenebeck 940 </blockquote>
3248    
3249 senoner 542
3250     <p>RANGE_MIN -
3251     </p>
3252     <blockquote class="text">
3253     <p>defines lower limit of the allowed value range for this
3254     parameter, can be an integer value as well as a dotted
3255     number, this parameter is usually used in conjunction
3256     with 'RANGE_MAX' but may also appear without
3257     (optionally returned, dependent to driver and port
3258     parameter)
3259     </p>
3260 schoenebeck 940 </blockquote>
3261    
3262 senoner 542
3263     <p>RANGE_MAX -
3264     </p>
3265     <blockquote class="text">
3266     <p>defines upper limit of the allowed value range for this
3267     parameter, can be an integer value as well as a dotted
3268     number, this parameter is usually used in conjunction
3269     with 'RANGE_MIN' but may also appear without
3270     (optionally returned, dependent to driver and port
3271     parameter)
3272     </p>
3273 schoenebeck 940 </blockquote>
3274    
3275 senoner 542
3276     <p>POSSIBILITIES -
3277     </p>
3278     <blockquote class="text">
3279     <p>comma separated list of possible values for this
3280     parameter, character strings are encapsulated into
3281     apostrophes
3282     (optionally returned, dependent to device and port
3283     parameter)
3284     </p>
3285 schoenebeck 940 </blockquote>
3286    
3287 senoner 542
3288 schoenebeck 708 </blockquote><p>
3289 schoenebeck 940
3290 schoenebeck 708 </p>
3291 senoner 542 <p>The mentioned fields above don't have to be in particular order.
3292     </p>
3293     <p>Example:
3294     </p>
3295 schoenebeck 708 <p>
3296     </p>
3297 senoner 542 <blockquote class="text">
3298     <p>C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"
3299     </p>
3300     <p>S: "DESCRIPTION: bindings to other ALSA sequencer clients"
3301     </p>
3302     <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
3303     </p>
3304     <p>&nbsp;&nbsp;&nbsp;"FIX: false"
3305     </p>
3306     <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"
3307     </p>
3308     <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: '64:0','68:0','68:1'"
3309     </p>
3310     <p>&nbsp;&nbsp;&nbsp;"."
3311     </p>
3312 schoenebeck 708 </blockquote><p>
3313 schoenebeck 940
3314 schoenebeck 708 </p>
3315 schoenebeck 940 <a name="SET MIDI_INPUT_PORT_PARAMETER"></a><br /><hr />
3316 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3317     <a name="rfc.section.6.3.13"></a><h3>6.3.13.&nbsp;
3318     Changing settings of MIDI input ports</h3>
3319 senoner 542
3320     <p>Use the following command to alter a specific setting of a MIDI input port:
3321     </p>
3322 schoenebeck 708 <p>
3323     </p>
3324 senoner 542 <blockquote class="text">
3325     <p>SET MIDI_INPUT_PORT_PARAMETER &lt;device-id&gt; &lt;port&gt; &lt;key&gt;=&lt;value&gt;
3326     </p>
3327 schoenebeck 708 </blockquote><p>
3328 schoenebeck 940
3329 schoenebeck 708 </p>
3330 senoner 542 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
3331 schoenebeck 575 MIDI device as returned by the
3332 schoenebeck 974 <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>
3333     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>
3334 schoenebeck 575 command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of
3335 senoner 542 the parameter to change and &lt;value&gt; by the new value for this
3336 schoenebeck 1363 parameter (encapsulated into apostrophes) or NONE (not encapsulated into apostrophes)
3337     for specifying no value for parameters allowing a list of values.
3338 senoner 542 </p>
3339     <p>Possible Answers:
3340     </p>
3341 schoenebeck 708 <p>
3342     </p>
3343 senoner 542 <blockquote class="text">
3344     <p>"OK" -
3345     </p>
3346     <blockquote class="text">
3347     <p>in case setting was successfully changed
3348     </p>
3349 schoenebeck 940 </blockquote>
3350    
3351 senoner 542
3352     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3353     </p>
3354     <blockquote class="text">
3355     <p>in case setting was changed successfully, but there are
3356     noteworthy issue(s) related, providing an appropriate
3357     warning code and warning message
3358     </p>
3359 schoenebeck 940 </blockquote>
3360    
3361 senoner 542
3362     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3363     </p>
3364     <blockquote class="text">
3365     <p>in case it failed, providing an appropriate error code and error message
3366     </p>
3367 schoenebeck 940 </blockquote>
3368    
3369 senoner 542
3370 schoenebeck 708 </blockquote><p>
3371 schoenebeck 940
3372 schoenebeck 708 </p>
3373 senoner 542 <p>Example:
3374     </p>
3375 schoenebeck 708 <p>
3376     </p>
3377 senoner 542 <blockquote class="text">
3378 schoenebeck 1363 <p>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='20:0'"
3379     </p>
3380     <p>S: "OK"
3381     </p>
3382     </blockquote><p>
3383    
3384     </p>
3385 senoner 542 <p>
3386 schoenebeck 1363 </p>
3387     <blockquote class="text">
3388     <p>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE"
3389 senoner 542 </p>
3390 schoenebeck 1363 <p>S: "OK"
3391     </p>
3392 schoenebeck 708 </blockquote><p>
3393 schoenebeck 940
3394 schoenebeck 708 </p>
3395 schoenebeck 940 <a name="anchor11"></a><br /><hr />
3396 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3397     <a name="rfc.section.6.4"></a><h3>6.4.&nbsp;
3398     Configuring sampler channels</h3>
3399 senoner 542
3400 schoenebeck 575 <p>The following commands describe how to add and remove sampler channels, associate a
3401     sampler channel with a sampler engine, load instruments and connect sampler channels to
3402     MIDI and audio devices.
3403 senoner 542 </p>
3404 schoenebeck 940 <a name="LOAD INSTRUMENT"></a><br /><hr />
3405 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3406     <a name="rfc.section.6.4.1"></a><h3>6.4.1.&nbsp;
3407     Loading an instrument</h3>
3408 senoner 542
3409     <p>An instrument file can be loaded and assigned to a sampler channel by one of the following commands:
3410     </p>
3411 schoenebeck 708 <p>
3412     </p>
3413 senoner 542 <blockquote class="text">
3414     <p>LOAD INSTRUMENT [NON_MODAL] '&lt;filename&gt;' &lt;instr-index&gt; &lt;sampler-channel&gt;
3415     </p>
3416 schoenebeck 708 </blockquote><p>
3417 schoenebeck 940
3418 schoenebeck 708 </p>
3419 senoner 542 <p>Where &lt;filename&gt; is the name of the instrument file on the
3420     LinuxSampler instance's host system, &lt;instr-index&gt; the index of the
3421     instrument in the instrument file and &lt;sampler-channel> is the
3422     number of the sampler channel the instrument should be assigned to.
3423     Each sampler channel can only have one instrument.
3424     </p>
3425 schoenebeck 1251 <p>Notice: since LSCP 1.2 the &lt;filename&gt; argument supports
3426     escape characters for special characters (see chapter
3427     "<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>"
3428     for details) and accordingly backslash characters in the filename
3429     MUST now be escaped as well!
3430     </p>
3431 senoner 542 <p>The difference between regular and NON_MODAL versions of the command
3432     is that the regular command returns OK only after the instrument has been
3433     fully loaded and the channel is ready to be used while NON_MODAL version
3434     returns immediately and a background process is launched to load the instrument
3435 schoenebeck 974 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>
3436 senoner 542 command can be used to obtain loading
3437     progress from INSTRUMENT_STATUS field. LOAD command will perform sanity checks
3438     such as making sure that the file could be read and it is of a proper format
3439     and SHOULD return ERR and SHOULD not launch the background process should any
3440     errors be detected at that point.
3441     </p>
3442     <p>Possible Answers:
3443     </p>
3444 schoenebeck 708 <p>
3445     </p>
3446 senoner 542 <blockquote class="text">
3447     <p>"OK" -
3448     </p>
3449     <blockquote class="text">
3450     <p>in case the instrument was successfully loaded
3451     </p>
3452 schoenebeck 940 </blockquote>
3453    
3454 senoner 542
3455     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3456     </p>
3457     <blockquote class="text">
3458     <p>in case the instrument was loaded successfully, but there
3459     are noteworthy issue(s) related (e.g. Engine doesn't support
3460     one or more patch parameters provided by the loaded
3461     instrument file), providing an appropriate warning code and
3462     warning message
3463     </p>
3464 schoenebeck 940 </blockquote>
3465    
3466 senoner 542
3467     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3468     </p>
3469     <blockquote class="text">
3470     <p>in case it failed, providing an appropriate error code and error message
3471     </p>
3472 schoenebeck 940 </blockquote>
3473    
3474 senoner 542
3475 schoenebeck 708 </blockquote><p>
3476 schoenebeck 940
3477 schoenebeck 708 </p>
3478 schoenebeck 1572 <p>Example (Unix):
3479 senoner 542 </p>
3480 schoenebeck 708 <p>
3481     </p>
3482 senoner 542 <blockquote class="text">
3483 schoenebeck 1572 <p>C: LOAD INSTRUMENT '/home/joe/gigs/cello.gig' 0 0
3484     </p>
3485     <p>S: OK
3486     </p>
3487     </blockquote><p>
3488    
3489     </p>
3490     <p>Example (Windows):
3491     </p>
3492 senoner 542 <p>
3493 schoenebeck 1572 </p>
3494     <blockquote class="text">
3495     <p>C: LOAD INSTRUMENT 'D:/MySounds/cello.gig' 0 0
3496 senoner 542 </p>
3497 schoenebeck 1572 <p>S: OK
3498     </p>
3499 schoenebeck 708 </blockquote><p>
3500 schoenebeck 940
3501 schoenebeck 708 </p>
3502 schoenebeck 940 <a name="LOAD ENGINE"></a><br /><hr />
3503 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3504     <a name="rfc.section.6.4.2"></a><h3>6.4.2.&nbsp;
3505     Loading a sampler engine</h3>
3506 senoner 542
3507 schoenebeck 575 <p>A sampler engine type can be associated to a specific sampler
3508 senoner 542 channel by the following command:
3509     </p>
3510 schoenebeck 708 <p>
3511     </p>
3512 senoner 542 <blockquote class="text">
3513     <p>LOAD ENGINE &lt;engine-name&gt; &lt;sampler-channel&gt;
3514     </p>
3515 schoenebeck 708 </blockquote><p>
3516 schoenebeck 940
3517 schoenebeck 708 </p>
3518 senoner 542 <p>Where &lt;engine-name&gt; is an engine name as obtained by the
3519 schoenebeck 974 <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;
3520 schoenebeck 575 the sampler channel as returned by the
3521 schoenebeck 974 <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a> or
3522     <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
3523 schoenebeck 575 the engine type should be assigned to. This command should be issued
3524     after adding a new sampler channel and before any other control
3525     commands on the new sampler channel. It can also be used to change
3526     the engine type of a sampler channel. This command has (currently) no
3527     way to define or force if a new engine instance should be created and
3528     assigned to the given sampler channel or if an already existing
3529     instance of that engine type, shared with other sampler channels,
3530     should be used.
3531 senoner 542 </p>
3532     <p>Possible Answers:
3533     </p>
3534 schoenebeck 708 <p>
3535     </p>
3536 senoner 542 <blockquote class="text">
3537     <p>"OK" -
3538     </p>
3539     <blockquote class="text">
3540     <p>in case the engine was successfully deployed
3541     </p>
3542 schoenebeck 940 </blockquote>
3543    
3544 senoner 542
3545     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3546     </p>
3547     <blockquote class="text">
3548     <p>in case the engine was deployed successfully, but there
3549     are noteworthy issue(s) related, providing an appropriate
3550     warning code and warning message
3551     </p>
3552 schoenebeck 940 </blockquote>
3553    
3554 senoner 542
3555     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3556     </p>
3557     <blockquote class="text">
3558     <p>in case it failed, providing an appropriate error code and
3559     error message
3560     </p>
3561 schoenebeck 940 </blockquote>
3562    
3563 senoner 542
3564 schoenebeck 708 </blockquote><p>
3565 schoenebeck 940
3566 schoenebeck 708 </p>
3567 senoner 542 <p>Example:
3568     </p>
3569 schoenebeck 708 <p>
3570     </p>
3571 senoner 542 <blockquote class="text">
3572     <p>
3573     </p>
3574 schoenebeck 708 </blockquote><p>
3575 schoenebeck 940
3576 schoenebeck 708 </p>
3577 schoenebeck 940 <a name="GET CHANNELS"></a><br /><hr />
3578 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3579     <a name="rfc.section.6.4.3"></a><h3>6.4.3.&nbsp;
3580     Getting all created sampler channel count</h3>
3581 senoner 542
3582     <p>The number of sampler channels can change on runtime. To get the
3583     current amount of sampler channels, the front-end can send the
3584     following command:
3585     </p>
3586 schoenebeck 708 <p>
3587     </p>
3588 senoner 542 <blockquote class="text">
3589     <p>GET CHANNELS
3590     </p>
3591 schoenebeck 708 </blockquote><p>
3592 schoenebeck 940
3593 schoenebeck 708 </p>
3594 senoner 542 <p>Possible Answers:
3595     </p>
3596 schoenebeck 708 <p>
3597     </p>
3598 senoner 542 <blockquote class="text">
3599     <p>LinuxSampler will answer by returning the current number of sampler channels.
3600     </p>
3601 schoenebeck 708 </blockquote><p>
3602 schoenebeck 940
3603 schoenebeck 708 </p>
3604 senoner 542 <p>Example:
3605     </p>
3606 schoenebeck 708 <p>
3607     </p>
3608 senoner 542 <blockquote class="text">
3609     <p>C: "GET CHANNELS"
3610     </p>
3611     <p>S: "12"
3612     </p>
3613 schoenebeck 708 </blockquote><p>
3614 schoenebeck 940
3615 schoenebeck 708 </p>
3616 schoenebeck 940 <a name="LIST CHANNELS"></a><br /><hr />
3617 schoenebeck 974 <table 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.4"></a><h3>6.4.4.&nbsp;
3619     Getting all created sampler channel list</h3>
3620 senoner 542
3621     <p>The number of sampler channels can change on runtime. To get the
3622     current list of sampler channels, the front-end can send the
3623     following command:
3624     </p>
3625 schoenebeck 708 <p>
3626     </p>
3627 senoner 542 <blockquote class="text">
3628     <p>LIST CHANNELS
3629     </p>
3630 schoenebeck 708 </blockquote><p>
3631 schoenebeck 940
3632 schoenebeck 708 </p>
3633 senoner 542 <p>Possible Answers:
3634     </p>
3635 schoenebeck 708 <p>
3636     </p>
3637 senoner 542 <blockquote class="text">
3638     <p>LinuxSampler will answer by returning a comma separated list
3639     with all sampler channels numerical IDs.
3640     </p>
3641 schoenebeck 708 </blockquote><p>
3642 schoenebeck 940
3643 schoenebeck 708 </p>
3644 senoner 542 <p>Example:
3645     </p>
3646 schoenebeck 708 <p>
3647     </p>
3648 senoner 542 <blockquote class="text">
3649     <p>C: "LIST CHANNELS"
3650     </p>
3651     <p>S: "0,1,2,3,4,5,6,9,10,11,15,20"
3652     </p>
3653 schoenebeck 708 </blockquote><p>
3654 schoenebeck 940
3655 schoenebeck 708 </p>
3656 schoenebeck 940 <a name="ADD CHANNEL"></a><br /><hr />
3657 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3658     <a name="rfc.section.6.4.5"></a><h3>6.4.5.&nbsp;
3659     Adding a new sampler channel</h3>
3660 senoner 542
3661     <p>A new sampler channel can be added to the end of the sampler
3662     channel list by sending the following command:
3663     </p>
3664 schoenebeck 708 <p>
3665     </p>
3666 senoner 542 <blockquote class="text">
3667     <p>ADD CHANNEL
3668     </p>
3669 schoenebeck 708 </blockquote><p>
3670 schoenebeck 940
3671 schoenebeck 708 </p>
3672 senoner 542 <p>This will increment the sampler channel count by one and the new
3673     sampler channel will be appended to the end of the sampler channel
3674     list. The front-end should send the respective, related commands
3675     right after to e.g. load an engine, load an instrument and setting
3676     input, output method and eventually other commands to initialize
3677     the new channel. The front-end should use the sampler channel
3678     returned by the answer of this command to perform the previously
3679     recommended commands, to avoid race conditions e.g. with other
3680     front-ends that might also have sent an "ADD CHANNEL" command.
3681     </p>
3682     <p>Possible Answers:
3683     </p>
3684 schoenebeck 708 <p>
3685     </p>
3686 senoner 542 <blockquote class="text">
3687     <p>"OK[&lt;sampler-channel&gt;]" -
3688     </p>
3689     <blockquote class="text">
3690     <p>in case a new sampler channel could be added, where
3691     &lt;sampler-channel&gt; reflects the channel number of the new
3692 schoenebeck 561 created sampler channel which should be used to set up
3693     the sampler channel by sending subsequent initialization
3694 senoner 542 commands
3695     </p>
3696 schoenebeck 940 </blockquote>
3697    
3698 senoner 542
3699     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3700     </p>
3701     <blockquote class="text">
3702     <p>in case a new channel was added successfully, but there are
3703     noteworthy issue(s) related, providing an appropriate
3704     warning code and warning message
3705     </p>
3706 schoenebeck 940 </blockquote>
3707    
3708 senoner 542
3709     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3710     </p>
3711     <blockquote class="text">
3712     <p>in case it failed, providing an appropriate error code and
3713     error message
3714     </p>
3715 schoenebeck 940 </blockquote>
3716    
3717 senoner 542
3718 schoenebeck 708 </blockquote><p>
3719 schoenebeck 940
3720 schoenebeck 708 </p>
3721 senoner 542 <p>Example:
3722     </p>
3723 schoenebeck 708 <p>
3724     </p>
3725 senoner 542 <blockquote class="text">
3726     <p>
3727     </p>
3728 schoenebeck 708 </blockquote><p>
3729 schoenebeck 940
3730 schoenebeck 708 </p>
3731 schoenebeck 940 <a name="REMOVE CHANNEL"></a><br /><hr />
3732 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3733     <a name="rfc.section.6.4.6"></a><h3>6.4.6.&nbsp;
3734     Removing a sampler channel</h3>
3735 senoner 542
3736     <p>A sampler channel can be removed by sending the following command:
3737     </p>
3738 schoenebeck 708 <p>
3739     </p>
3740 senoner 542 <blockquote class="text">
3741     <p>REMOVE CHANNEL &lt;sampler-channel&gt;
3742     </p>
3743 schoenebeck 708 </blockquote><p>
3744 schoenebeck 940
3745 schoenebeck 708 </p>
3746 schoenebeck 561 <p>Where &lt;sampler-channel&gt; should be replaced by the
3747     number of the sampler channel as given by the
3748 schoenebeck 974 <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
3749     or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a>
3750 schoenebeck 561 command. The channel numbers of all subsequent sampler channels
3751     remain the same.
3752 senoner 542 </p>
3753     <p>Possible Answers:
3754     </p>
3755 schoenebeck 708 <p>
3756     </p>
3757 senoner 542 <blockquote class="text">
3758     <p>"OK" -
3759     </p>
3760     <blockquote class="text">
3761     <p>in case the given sampler channel could be removed
3762     </p>
3763 schoenebeck 940 </blockquote>
3764    
3765 senoner 542
3766     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3767     </p>
3768     <blockquote class="text">
3769     <p>in case the given channel was removed, but there are
3770     noteworthy issue(s) related, providing an appropriate
3771     warning code and warning message
3772     </p>
3773 schoenebeck 940 </blockquote>
3774    
3775 senoner 542
3776     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3777     </p>
3778     <blockquote class="text">
3779     <p>in case it failed, providing an appropriate error code and
3780     error message
3781     </p>
3782 schoenebeck 940 </blockquote>
3783    
3784 senoner 542
3785 schoenebeck 708 </blockquote><p>
3786 schoenebeck 940
3787 schoenebeck 708 </p>
3788 senoner 542 <p>Example:
3789     </p>
3790 schoenebeck 708 <p>
3791     </p>
3792 senoner 542 <blockquote class="text">
3793     <p>
3794     </p>
3795 schoenebeck 708 </blockquote><p>
3796 schoenebeck 940
3797 schoenebeck 708 </p>
3798 schoenebeck 940 <a name="GET AVAILABLE_ENGINES"></a><br /><hr />
3799 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3800     <a name="rfc.section.6.4.7"></a><h3>6.4.7.&nbsp;
3801     Getting amount of available engines</h3>
3802 senoner 542
3803     <p>The front-end can ask for the number of available engines by sending the following command:
3804     </p>
3805 schoenebeck 708 <p>
3806     </p>
3807 senoner 542 <blockquote class="text">
3808     <p>GET AVAILABLE_ENGINES
3809     </p>
3810 schoenebeck 708 </blockquote><p>
3811 schoenebeck 940
3812 schoenebeck 708 </p>
3813 senoner 542 <p>Possible Answers:
3814     </p>
3815 schoenebeck 708 <p>
3816     </p>
3817 senoner 542 <blockquote class="text">
3818     <p>LinuxSampler will answer by sending the number of available engines.
3819     </p>
3820 schoenebeck 708 </blockquote><p>
3821 schoenebeck 940
3822 schoenebeck 708 </p>
3823 senoner 542 <p>Example:
3824     </p>
3825 schoenebeck 708 <p>
3826     </p>
3827 senoner 542 <blockquote class="text">
3828     <p>C: "GET AVAILABLE_ENGINES"
3829     </p>
3830     <p>S: "4"
3831     </p>
3832 schoenebeck 708 </blockquote><p>
3833 schoenebeck 940
3834 schoenebeck 708 </p>
3835 schoenebeck 940 <a name="LIST AVAILABLE_ENGINES"></a><br /><hr />
3836 schoenebeck 974 <table 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.8"></a><h3>6.4.8.&nbsp;
3838     Getting all available engines</h3>
3839 senoner 542
3840     <p>The front-end can ask for a list of all available engines by sending the following command:
3841     </p>
3842 schoenebeck 708 <p>
3843     </p>
3844 senoner 542 <blockquote class="text">
3845     <p>LIST AVAILABLE_ENGINES
3846     </p>
3847 schoenebeck 708 </blockquote><p>
3848 schoenebeck 940
3849 schoenebeck 708 </p>
3850 senoner 542 <p>Possible Answers:
3851     </p>
3852 schoenebeck 708 <p>
3853     </p>
3854 senoner 542 <blockquote class="text">
3855 schoenebeck 561 <p>LinuxSampler will answer by sending a comma separated list
3856     of the engines' names encapsulated into apostrophes (').
3857     Engine names can consist of lower and upper cases,
3858     digits and underlines ("_" character).
3859 senoner 542 </p>
3860 schoenebeck 708 </blockquote><p>
3861 schoenebeck 940
3862 schoenebeck 708 </p>
3863 senoner 542 <p>Example:
3864     </p>
3865 schoenebeck 708 <p>
3866     </p>
3867 senoner 542 <blockquote class="text">
3868     <p>C: "LIST AVAILABLE_ENGINES"
3869     </p>
3870 schoenebeck 561 <p>S: "'GigEngine','AkaiEngine','DLSEngine','JoesCustomEngine'"
3871 senoner 542 </p>
3872 schoenebeck 708 </blockquote><p>
3873 schoenebeck 940
3874 schoenebeck 708 </p>
3875 schoenebeck 940 <a name="GET ENGINE INFO"></a><br /><hr />
3876 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3877     <a name="rfc.section.6.4.9"></a><h3>6.4.9.&nbsp;
3878     Getting information about an engine</h3>
3879 senoner 542
3880     <p>The front-end can ask for information about a specific engine by
3881     sending the following command:
3882     </p>
3883 schoenebeck 708 <p>
3884     </p>
3885 senoner 542 <blockquote class="text">
3886     <p>GET ENGINE INFO &lt;engine-name&gt;
3887     </p>
3888 schoenebeck 708 </blockquote><p>
3889 schoenebeck 940
3890 schoenebeck 708 </p>
3891 senoner 542 <p>Where &lt;engine-name&gt; is an engine name as obtained by the
3892 schoenebeck 974 <a class='info' href='#LIST AVAILABLE_ENGINES'>"LIST AVAILABLE_ENGINES"<span> (</span><span class='info'>Getting all available engines</span><span>)</span></a> command.
3893 senoner 542 </p>
3894     <p>Possible Answers:
3895     </p>
3896 schoenebeck 708 <p>
3897     </p>
3898 senoner 542 <blockquote class="text">
3899     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3900     Each answer line begins with the information category name
3901     followed by a colon and then a space character &lt;SP&gt; and finally
3902     the info character string to that info category. At the moment
3903     the following categories are defined:
3904     </p>
3905 schoenebeck 708 <p>
3906     </p>
3907 senoner 542 <blockquote class="text">
3908     <p>DESCRIPTION -
3909     </p>
3910     <blockquote class="text">
3911     <p>arbitrary description text about the engine
3912 schoenebeck 1400 (note that the character string may contain
3913     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>)
3914 senoner 542 </p>
3915 schoenebeck 940 </blockquote>
3916    
3917 senoner 542
3918     <p>VERSION -
3919     </p>
3920     <blockquote class="text">
3921     <p>arbitrary character string regarding the engine's version
3922     </p>
3923 schoenebeck 940 </blockquote>
3924    
3925 senoner 542
3926 schoenebeck 940 </blockquote>
3927    
3928 senoner 542
3929 schoenebeck 708 </blockquote><p>
3930 schoenebeck 940
3931 schoenebeck 708 </p>
3932 senoner 542 <p>The mentioned fields above don't have to be in particular order.
3933     </p>
3934     <p>Example:
3935     </p>
3936 schoenebeck 708 <p>
3937     </p>
3938 senoner 542 <blockquote class="text">
3939     <p>C: "GET ENGINE INFO JoesCustomEngine"
3940     </p>
3941     <p>S: "DESCRIPTION: this is Joe's custom sampler engine"
3942     </p>
3943     <p>&nbsp;&nbsp;&nbsp;"VERSION: testing-1.0"
3944     </p>
3945     <p>&nbsp;&nbsp;&nbsp;"."
3946     </p>
3947 schoenebeck 708 </blockquote><p>
3948 schoenebeck 940
3949 schoenebeck 708 </p>
3950 schoenebeck 940 <a name="GET CHANNEL INFO"></a><br /><hr />
3951 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
3952     <a name="rfc.section.6.4.10"></a><h3>6.4.10.&nbsp;
3953     Getting sampler channel information</h3>
3954 senoner 542
3955     <p>The front-end can ask for the current settings of a sampler channel
3956     by sending the following command:
3957     </p>
3958 schoenebeck 708 <p>
3959     </p>
3960 senoner 542 <blockquote class="text">
3961     <p>GET CHANNEL INFO &lt;sampler-channel&gt;
3962     </p>
3963 schoenebeck 708 </blockquote><p>
3964 schoenebeck 940
3965 schoenebeck 708 </p>
3966 schoenebeck 575 <p>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
3967 schoenebeck 974 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>
3968     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.
3969 senoner 542 </p>
3970     <p>Possible Answers:
3971     </p>
3972 schoenebeck 708 <p>
3973     </p>
3974 senoner 542 <blockquote class="text">
3975     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3976     Each answer line begins with the settings category name
3977     followed by a colon and then a space character &lt;SP&gt; and finally
3978     the info character string to that setting category. At the
3979     moment the following categories are defined:
3980     </p>
3981 schoenebeck 708 <p>
3982     </p>
3983 senoner 542 <blockquote class="text">
3984     <p>ENGINE_NAME -
3985     </p>
3986     <blockquote class="text">
3987 schoenebeck 575 <p>name of the engine that is associated with the sampler
3988     channel, "NONE" if there's no engine associated yet for
3989 senoner 542 this sampler channel
3990     </p>
3991 schoenebeck 940 </blockquote>
3992    
3993 senoner 542
3994     <p>AUDIO_OUTPUT_DEVICE -
3995     </p>
3996     <blockquote class="text">
3997     <p>numerical ID of the audio output device which is
3998     currently connected to this sampler channel to output
3999     the audio signal, "NONE" if there's no device
4000     connected to this sampler channel
4001     </p>
4002 schoenebeck 940 </blockquote>
4003    
4004 senoner 542
4005     <p>AUDIO_OUTPUT_CHANNELS -
4006     </p>
4007     <blockquote class="text">
4008     <p>number of output channels the sampler channel offers
4009     (dependent to used sampler engine and loaded instrument)
4010     </p>
4011 schoenebeck 940 </blockquote>
4012    
4013 senoner 542
4014     <p>AUDIO_OUTPUT_ROUTING -
4015     </p>
4016     <blockquote class="text">
4017     <p>comma separated list which reflects to which audio
4018     channel of the selected audio output device each
4019     sampler output channel is routed to, e.g. "0,3" would
4020     mean the engine's output channel 0 is routed to channel
4021     0 of the audio output device and the engine's output
4022     channel 1 is routed to the channel 3 of the audio
4023     output device
4024     </p>
4025 schoenebeck 940 </blockquote>
4026    
4027 senoner 542
4028     <p>INSTRUMENT_FILE -
4029     </p>
4030     <blockquote class="text">
4031     <p>the file name of the loaded instrument, "NONE" if
4032     there's no instrument yet loaded for this sampler
4033 schoenebeck 1400 channel (note: since LSCP 1.2 this path may contain
4034     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>)
4035 senoner 542 </p>
4036 schoenebeck 940 </blockquote>
4037    
4038 senoner 542
4039     <p>INSTRUMENT_NR -
4040     </p>
4041     <blockquote class="text">
4042     <p>the instrument index number of the loaded instrument
4043     </p>
4044 schoenebeck 940 </blockquote>
4045    
4046 senoner 542
4047     <p>INSTRUMENT_NAME -
4048     </p>
4049     <blockquote class="text">
4050     <p>the instrument name of the loaded instrument
4051 schoenebeck 1400 (note: since LSCP 1.2 this character string may contain
4052     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>)
4053 senoner 542 </p>
4054 schoenebeck 940 </blockquote>
4055    
4056 senoner 542
4057     <p>INSTRUMENT_STATUS -
4058     </p>
4059     <blockquote class="text">
4060     <p>integer values 0 to 100 indicating loading progress percentage for the instrument. Negative
4061     value indicates a loading exception. Value of 100 indicates that the instrument is fully
4062     loaded.
4063     </p>
4064 schoenebeck 940 </blockquote>
4065    
4066 senoner 542
4067     <p>MIDI_INPUT_DEVICE -
4068     </p>
4069     <blockquote class="text">
4070     <p>numerical ID of the MIDI input device which is
4071     currently connected to this sampler channel to deliver
4072     MIDI input commands, "NONE" if there's no device
4073     connected to this sampler channel
4074     </p>
4075 schoenebeck 940 </blockquote>
4076    
4077 senoner 542
4078     <p>MIDI_INPUT_PORT -
4079     </p>
4080     <blockquote class="text">
4081     <p>port number of the MIDI input device
4082     </p>
4083 schoenebeck 940 </blockquote>
4084    
4085 senoner 542
4086     <p>MIDI_INPUT_CHANNEL -
4087     </p>
4088     <blockquote class="text">
4089     <p>the MIDI input channel number this sampler channel
4090     should listen to or "ALL" to listen on all MIDI channels
4091     </p>
4092 schoenebeck 940 </blockquote>
4093    
4094 senoner 542
4095     <p>VOLUME -
4096     </p>
4097     <blockquote class="text">
4098     <p>optionally dotted number for the channel volume factor
4099 schoenebeck 1028 (where a value &lt; 1.0 means attenuation and a value >
4100 senoner 542 1.0 means amplification)
4101     </p>
4102 schoenebeck 940 </blockquote>
4103    
4104 senoner 542
4105 schoenebeck 708 <p>MUTE -
4106     </p>
4107     <blockquote class="text">
4108     <p>Determines whether the channel is muted, "true" if the
4109     channel is muted, "false" if the channel is not muted, and
4110     "MUTED_BY_SOLO" if the channel is muted because of the
4111     presence of a solo channel and will be unmuted when
4112     there are no solo channels left
4113     </p>
4114 schoenebeck 940 </blockquote>
4115    
4116 senoner 542
4117 schoenebeck 708 <p>SOLO -
4118     </p>
4119     <blockquote class="text">
4120     <p>Determines whether this is a solo channel, "true" if
4121     the channel is a solo channel; "false" otherwise
4122     </p>
4123 schoenebeck 940 </blockquote>
4124    
4125 senoner 542
4126 schoenebeck 974 <p>MIDI_INSTRUMENT_MAP -
4127     </p>
4128     <blockquote class="text">
4129     <p>Determines to which MIDI instrument map this sampler
4130     channel is assigned to. Read chapter
4131     <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>
4132     for a list of possible values.
4133     </p>
4134 schoenebeck 940 </blockquote>
4135 schoenebeck 974
4136    
4137     </blockquote>
4138 schoenebeck 940
4139 schoenebeck 708
4140     </blockquote><p>
4141 schoenebeck 940
4142 schoenebeck 708 </p>
4143 senoner 542 <p>The mentioned fields above don't have to be in particular order.
4144     </p>
4145     <p>Example:
4146     </p>
4147 schoenebeck 708 <p>
4148     </p>
4149 senoner 542 <blockquote class="text">
4150     <p>C: "GET CHANNEL INFO 34"
4151     </p>
4152     <p>S: "ENGINE_NAME: GigEngine"
4153     </p>
4154     <p>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"
4155     </p>
4156     <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_DEVICE: 0"
4157     </p>
4158     <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_CHANNELS: 2"
4159     </p>
4160     <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 0,1"
4161     </p>
4162     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"
4163     </p>
4164     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"
4165     </p>
4166     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NAME: Fazioli Piano"
4167     </p>
4168     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_STATUS: 100"
4169     </p>
4170     <p>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_DEVICE: 0"
4171     </p>
4172     <p>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_PORT: 0"
4173     </p>
4174     <p>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_CHANNEL: 5"
4175     </p>
4176 schoenebeck 974 <p>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"
4177     </p>
4178     <p>&nbsp;&nbsp;&nbsp;"MUTE: false"
4179     </p>
4180     <p>&nbsp;&nbsp;&nbsp;"SOLO: false"
4181     </p>
4182     <p>&nbsp;&nbsp;&nbsp;"MIDI_INSTRUMENT_MAP: NONE"
4183     </p>
4184 senoner 542 <p>&nbsp;&nbsp;&nbsp;"."
4185     </p>
4186 schoenebeck 708 </blockquote><p>
4187 schoenebeck 940
4188 schoenebeck 708 </p>
4189 schoenebeck 940 <a name="GET CHANNEL VOICE_COUNT"></a><br /><hr />
4190 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4191     <a name="rfc.section.6.4.11"></a><h3>6.4.11.&nbsp;
4192     Current number of active voices</h3>
4193 senoner 542
4194     <p>The front-end can ask for the current number of active voices on a
4195     sampler channel by sending the following command:
4196     </p>
4197 schoenebeck 708 <p>
4198     </p>
4199 senoner 542 <blockquote class="text">
4200     <p>GET CHANNEL VOICE_COUNT &lt;sampler-channel&gt;
4201     </p>
4202 schoenebeck 708 </blockquote><p>
4203 schoenebeck 940
4204 schoenebeck 708 </p>
4205 schoenebeck 575 <p>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
4206 schoenebeck 974 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>
4207     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.
4208 senoner 542 </p>
4209     <p>Possible Answers:
4210     </p>
4211 schoenebeck 708 <p>
4212     </p>
4213 senoner 542 <blockquote class="text">
4214     <p>LinuxSampler will answer by returning the number of active
4215     voices on that channel.
4216     </p>
4217 schoenebeck 708 </blockquote><p>
4218 schoenebeck 940
4219 schoenebeck 708 </p>
4220 senoner 542 <p>Example:
4221     </p>
4222 schoenebeck 708 <p>
4223     </p>
4224 senoner 542 <blockquote class="text">
4225     <p>
4226     </p>
4227 schoenebeck 708 </blockquote><p>
4228 schoenebeck 940
4229 schoenebeck 708 </p>
4230 schoenebeck 940 <a name="GET CHANNEL STREAM_COUNT"></a><br /><hr />
4231 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4232     <a name="rfc.section.6.4.12"></a><h3>6.4.12.&nbsp;
4233     Current number of active disk streams</h3>
4234 senoner 542
4235     <p>The front-end can ask for the current number of active disk streams
4236     on a sampler channel by sending the following command:
4237     </p>
4238 schoenebeck 708 <p>
4239     </p>
4240 senoner 542 <blockquote class="text">
4241     <p>GET CHANNEL STREAM_COUNT &lt;sampler-channel&gt;
4242     </p>
4243 schoenebeck 708 </blockquote><p>
4244 schoenebeck 940
4245 schoenebeck 708 </p>
4246 schoenebeck 575 <p>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
4247 schoenebeck 974 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>
4248     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.
4249 senoner 542 </p>
4250     <p>Possible Answers:
4251     </p>
4252 schoenebeck 708 <p>
4253     </p>
4254 senoner 542 <blockquote class="text">
4255     <p>LinuxSampler will answer by returning the number of active
4256     disk streams on that channel in case the engine supports disk
4257     streaming, if the engine doesn't support disk streaming it will
4258     return "NA" for not available.
4259     </p>
4260 schoenebeck 708 </blockquote><p>
4261 schoenebeck 940
4262 schoenebeck 708 </p>
4263 senoner 542 <p>Example:
4264     </p>
4265 schoenebeck 708 <p>
4266     </p>
4267 senoner 542 <blockquote class="text">
4268     <p>
4269     </p>
4270 schoenebeck 708 </blockquote><p>
4271 schoenebeck 940
4272 schoenebeck 708 </p>
4273 schoenebeck 940 <a name="GET CHANNEL BUFFER_FILL"></a><br /><hr />
4274 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4275     <a name="rfc.section.6.4.13"></a><h3>6.4.13.&nbsp;
4276     Current fill state of disk stream buffers</h3>
4277 senoner 542
4278     <p>The front-end can ask for the current fill state of all disk streams
4279     on a sampler channel by sending the following command:
4280     </p>
4281 schoenebeck 708 <p>
4282     </p>
4283 senoner 542 <blockquote class="text">
4284     <p>GET CHANNEL BUFFER_FILL BYTES &lt;sampler-channel&gt;
4285     </p>
4286 schoenebeck 708 </blockquote><p>
4287 schoenebeck 940
4288 schoenebeck 708 </p>
4289 senoner 542 <p>to get the fill state in bytes or
4290     </p>
4291 schoenebeck 708 <p>
4292     </p>
4293 senoner 542 <blockquote class="text">
4294     <p>GET CHANNEL BUFFER_FILL PERCENTAGE &lt;sampler-channel&gt;
4295     </p>
4296 schoenebeck 708 </blockquote><p>
4297 schoenebeck 940
4298 schoenebeck 708 </p>
4299 senoner 542 <p>to get the fill state in percent, where &lt;sampler-channel&gt; is the
4300 schoenebeck 575 sampler channel number the front-end is interested in
4301 schoenebeck 974 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>
4302     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.
4303 senoner 542 </p>
4304     <p>Possible Answers:
4305     </p>
4306 schoenebeck 708 <p>
4307     </p>
4308 senoner 542 <blockquote class="text">
4309     <p>LinuxSampler will either answer by returning a comma separated
4310     string with the fill state of all disk stream buffers on that
4311     channel or an empty line if there are no active disk streams or
4312     "NA" for *not available* in case the engine which is deployed
4313     doesn't support disk streaming. Each entry in the answer list
4314     will begin with the stream's ID in brackets followed by the
4315     numerical representation of the fill size (either in bytes or
4316     percentage). Note: due to efficiency reasons the fill states in
4317     the response are not in particular order, thus the front-end has
4318     to sort them by itself if necessary.
4319     </p>
4320 schoenebeck 708 </blockquote><p>
4321 schoenebeck 940
4322 schoenebeck 708 </p>
4323 senoner 542 <p>Examples:
4324     </p>
4325 schoenebeck 708 <p>
4326     </p>
4327 senoner 542 <blockquote class="text">
4328     <p>C: "GET CHANNEL BUFFER_FILL BYTES 4"
4329     </p>
4330     <p>S: "[115]420500,[116]510300,[75]110000,[120]230700"
4331     </p>
4332 schoenebeck 708 </blockquote><p>
4333    
4334     </p>
4335 senoner 542 <blockquote class="text">
4336 schoenebeck 708 <p>C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
4337 senoner 542 </p>
4338     <p>S: "[115]90%,[116]98%,[75]40%,[120]62%"
4339     </p>
4340 schoenebeck 708 </blockquote><p>
4341    
4342     </p>
4343 senoner 542 <blockquote class="text">
4344 schoenebeck 708 <p>C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
4345 senoner 542 </p>
4346     <p>S: ""
4347     </p>
4348 schoenebeck 708 </blockquote><p>
4349 schoenebeck 940
4350 schoenebeck 708 </p>
4351 schoenebeck 940 <a name="SET CHANNEL AUDIO_OUTPUT_DEVICE"></a><br /><hr />
4352 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4353     <a name="rfc.section.6.4.14"></a><h3>6.4.14.&nbsp;
4354     Setting audio output device</h3>
4355 senoner 542
4356     <p>The front-end can set the audio output device on a specific sampler
4357     channel by sending the following command:
4358     </p>
4359 schoenebeck 708 <p>
4360     </p>
4361 senoner 542 <blockquote class="text">
4362     <p>SET CHANNEL AUDIO_OUTPUT_DEVICE &lt;sampler-channel&gt; &lt;audio-device-id&gt;
4363     </p>
4364 schoenebeck 708 </blockquote><p>
4365 schoenebeck 940
4366 schoenebeck 708 </p>
4367 schoenebeck 575 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4368 schoenebeck 974 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>
4369     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
4370 schoenebeck 575 &lt;audio-device-id&gt; is the numerical ID of the audio output device as given by the
4371 schoenebeck 974 <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>
4372     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>
4373 schoenebeck 575 command.
4374 senoner 542 </p>
4375     <p>Possible Answers:
4376     </p>
4377 schoenebeck 708 <p>
4378     </p>
4379 senoner 542 <blockquote class="text">
4380     <p>"OK" -
4381     </p>
4382     <blockquote class="text">
4383     <p>on success
4384     </p>
4385 schoenebeck 940 </blockquote>
4386    
4387 senoner 542
4388     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4389     </p>
4390     <blockquote class="text">
4391     <p>if audio output device was set, but there are noteworthy
4392     issue(s) related, providing an appropriate warning code and
4393     warning message
4394     </p>
4395 schoenebeck 940 </blockquote>
4396    
4397 senoner 542
4398     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4399     </p>
4400     <blockquote class="text">
4401     <p>in case it failed, providing an appropriate error code and error message
4402     </p>
4403 schoenebeck 940 </blockquote>
4404    
4405 senoner 542
4406 schoenebeck 708 </blockquote><p>
4407 schoenebeck 940
4408 schoenebeck 708 </p>
4409 senoner 542 <p>Examples:
4410     </p>
4411 schoenebeck 708 <p>
4412     </p>
4413 senoner 542 <blockquote class="text">
4414     <p>
4415     </p>
4416 schoenebeck 708 </blockquote><p>
4417 schoenebeck 940
4418 schoenebeck 708 </p>
4419 schoenebeck 974 <a name="SET CHANNEL AUDIO_OUTPUT_TYPE"></a><br /><hr />
4420     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4421     <a name="rfc.section.6.4.15"></a><h3>6.4.15.&nbsp;
4422     Setting audio output type</h3>
4423 senoner 542
4424     <p>DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
4425     </p>
4426     <p>The front-end can alter the audio output type on a specific sampler
4427     channel by sending the following command:
4428     </p>
4429 schoenebeck 708 <p>
4430     </p>
4431 senoner 542 <blockquote class="text">
4432     <p>SET CHANNEL AUDIO_OUTPUT_TYPE &lt;sampler-channel&gt; &lt;audio-output-type&gt;
4433     </p>
4434 schoenebeck 708 </blockquote><p>
4435 schoenebeck 940
4436 schoenebeck 708 </p>
4437 senoner 542 <p>Where &lt;audio-output-type&gt; is currently either "ALSA" or "JACK" and
4438     &lt;sampler-channel&gt; is the respective sampler channel number.
4439     </p>
4440     <p>Possible Answers:
4441     </p>
4442 schoenebeck 708 <p>
4443     </p>
4444 senoner 542 <blockquote class="text">
4445     <p>"OK" -
4446     </p>
4447     <blockquote class="text">
4448     <p>on success
4449     </p>
4450 schoenebeck 940 </blockquote>
4451    
4452 senoner 542
4453     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4454     </p>
4455     <blockquote class="text">
4456     <p>if audio output type was set, but there are noteworthy
4457     issue(s) related, providing an appropriate warning code and
4458     warning message
4459     </p>
4460 schoenebeck 940 </blockquote>
4461    
4462 senoner 542
4463     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4464     </p>
4465     <blockquote class="text">
4466     <p>in case it failed, providing an appropriate error code and error message
4467     </p>
4468 schoenebeck 940 </blockquote>
4469    
4470 senoner 542
4471 schoenebeck 708 </blockquote><p>
4472 schoenebeck 940
4473 schoenebeck 708 </p>
4474 senoner 542 <p>Examples:
4475     </p>
4476 schoenebeck 708 <p>
4477     </p>
4478 senoner 542 <blockquote class="text">
4479     <p>
4480     </p>
4481 schoenebeck 708 </blockquote><p>
4482 schoenebeck 940
4483 schoenebeck 708 </p>
4484 schoenebeck 940 <a name="SET CHANNEL AUDIO_OUTPUT_CHANNEL"></a><br /><hr />
4485 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4486     <a name="rfc.section.6.4.16"></a><h3>6.4.16.&nbsp;
4487     Setting audio output channel</h3>
4488 senoner 542
4489     <p>The front-end can alter the audio output channel on a specific
4490     sampler channel by sending the following command:
4491     </p>
4492 schoenebeck 708 <p>
4493     </p>
4494 senoner 542 <blockquote class="text">
4495     <p>SET CHANNEL AUDIO_OUTPUT_CHANNEL &lt;sampler-chan&gt; &lt;audio-out&gt; &lt;audio-in&gt;
4496     </p>
4497 schoenebeck 708 </blockquote><p>
4498 schoenebeck 940
4499 schoenebeck 708 </p>
4500 schoenebeck 575 <p>Where &lt;sampler-chan&gt; is the sampler channel number
4501 schoenebeck 974 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>
4502     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
4503 senoner 542 numerical ID of the sampler channel's audio output channel which should be
4504     rerouted and &lt;audio-in&gt; is the numerical ID of the audio channel of the selected audio
4505     output device where &lt;audio-out&gt; should be routed to.
4506     </p>
4507     <p>Possible Answers:
4508     </p>
4509 schoenebeck 708 <p>
4510     </p>
4511 senoner 542 <blockquote class="text">
4512     <p>"OK" -
4513     </p>
4514     <blockquote class="text">
4515     <p>on success
4516     </p>
4517 schoenebeck 940 </blockquote>
4518    
4519 senoner 542
4520     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4521     </p>
4522     <blockquote class="text">
4523     <p>if audio output channel was set, but there are noteworthy
4524     issue(s) related, providing an appropriate warning code and
4525     warning message
4526     </p>
4527 schoenebeck 940 </blockquote>
4528    
4529 senoner 542
4530     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4531     </p>
4532     <blockquote class="text">
4533     <p>in case it failed, providing an appropriate error code and error message
4534     </p>
4535 schoenebeck 940 </blockquote>
4536    
4537 senoner 542
4538 schoenebeck 708 </blockquote><p>
4539 schoenebeck 940
4540 schoenebeck 708 </p>
4541 senoner 542 <p>Examples:
4542     </p>
4543 schoenebeck 708 <p>
4544     </p>
4545 senoner 542 <blockquote class="text">
4546     <p>
4547     </p>
4548 schoenebeck 708 </blockquote><p>
4549 schoenebeck 940
4550 schoenebeck 708 </p>
4551 schoenebeck 940 <a name="SET CHANNEL MIDI_INPUT_DEVICE"></a><br /><hr />
4552 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4553     <a name="rfc.section.6.4.17"></a><h3>6.4.17.&nbsp;
4554     Setting MIDI input device</h3>
4555 senoner 542
4556     <p>The front-end can set the MIDI input device on a specific sampler
4557     channel by sending the following command:
4558     </p>
4559 schoenebeck 708 <p>
4560     </p>
4561 senoner 542 <blockquote class="text">
4562     <p>SET CHANNEL MIDI_INPUT_DEVICE &lt;sampler-channel&gt; &lt;midi-device-id&gt;
4563     </p>
4564 schoenebeck 708 </blockquote><p>
4565 schoenebeck 940
4566 schoenebeck 708 </p>
4567 schoenebeck 575 <p>Where &lt;sampler-channel&gt; is the sampler channel number
4568 schoenebeck 974 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>
4569     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
4570 schoenebeck 575 and &lt;midi-device-id&gt; is the numerical ID of the MIDI input device as returned by the
4571 schoenebeck 974 <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>
4572     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.
4573 senoner 542 </p>
4574     <p>Possible Answers:
4575     </p>
4576 schoenebeck 708 <p>
4577     </p>
4578 senoner 542 <blockquote class="text">
4579     <p>"OK" -
4580     </p>
4581     <blockquote class="text">
4582     <p>on success
4583     </p>
4584 schoenebeck 940 </blockquote>
4585    
4586 senoner 542
4587     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4588     </p>
4589     <blockquote class="text">
4590     <p>if MIDI input device was set, but there are noteworthy
4591     issue(s) related, providing an appropriate warning code and
4592     warning message
4593     </p>
4594 schoenebeck 940 </blockquote>
4595    
4596 senoner 542
4597     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4598     </p>
4599     <blockquote class="text">
4600     <p>in case it failed, providing an appropriate error code and error message
4601     </p>
4602 schoenebeck 940 </blockquote>
4603    
4604 senoner 542
4605 schoenebeck 708 </blockquote><p>
4606 schoenebeck 940
4607 schoenebeck 708 </p>
4608 senoner 542 <p>Examples:
4609     </p>
4610 schoenebeck 708 <p>
4611     </p>
4612 senoner 542 <blockquote class="text">
4613     <p>
4614     </p>
4615 schoenebeck 708 </blockquote><p>
4616 schoenebeck 940
4617 schoenebeck 708 </p>
4618 schoenebeck 940 <a name="SET CHANNEL MIDI_INPUT_TYPE"></a><br /><hr />
4619 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4620     <a name="rfc.section.6.4.18"></a><h3>6.4.18.&nbsp;
4621     Setting MIDI input type</h3>
4622 senoner 542
4623     <p>DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
4624     </p>
4625     <p>The front-end can alter the MIDI input type on a specific sampler
4626     channel by sending the following command:
4627     </p>
4628 schoenebeck 708 <p>
4629     </p>
4630 senoner 542 <blockquote class="text">
4631     <p>SET CHANNEL MIDI_INPUT_TYPE &lt;sampler-channel&gt; &lt;midi-input-type&gt;
4632     </p>
4633 schoenebeck 708 </blockquote><p>
4634 schoenebeck 940
4635 schoenebeck 708 </p>
4636 senoner 542 <p>Where &lt;midi-input-type&gt; is currently only "ALSA" and
4637     &lt;sampler-channel&gt; is the respective sampler channel number.
4638     </p>
4639     <p>Possible Answers:
4640     </p>
4641 schoenebeck 708 <p>
4642     </p>
4643 senoner 542 <blockquote class="text">
4644     <p>"OK" -
4645     </p>
4646     <blockquote class="text">
4647     <p>on success
4648     </p>
4649 schoenebeck 940 </blockquote>
4650    
4651 senoner 542
4652     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4653     </p>
4654     <blockquote class="text">
4655     <p>if MIDI input type was set, but there are noteworthy
4656     issue(s) related, providing an appropriate warning code and
4657     warning message
4658     </p>
4659 schoenebeck 940 </blockquote>
4660    
4661 senoner 542
4662     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4663     </p>
4664     <blockquote class="text">
4665     <p>in case it failed, providing an appropriate error code and error message
4666     </p>
4667 schoenebeck 940 </blockquote>
4668    
4669 senoner 542
4670 schoenebeck 708 </blockquote><p>
4671 schoenebeck 940
4672 schoenebeck 708 </p>
4673 senoner 542 <p>Examples:
4674     </p>
4675 schoenebeck 708 <p>
4676     </p>
4677 senoner 542 <blockquote class="text">
4678     <p>
4679     </p>
4680 schoenebeck 708 </blockquote><p>
4681 schoenebeck 940
4682 schoenebeck 708 </p>
4683 schoenebeck 940 <a name="SET CHANNEL MIDI_INPUT_PORT"></a><br /><hr />
4684 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4685     <a name="rfc.section.6.4.19"></a><h3>6.4.19.&nbsp;
4686     Setting MIDI input port</h3>
4687 senoner 542
4688     <p>The front-end can alter the MIDI input port on a specific sampler
4689     channel by sending the following command:
4690     </p>
4691 schoenebeck 708 <p>
4692     </p>
4693 senoner 542 <blockquote class="text">
4694     <p>SET CHANNEL MIDI_INPUT_PORT &lt;sampler-channel&gt; &lt;midi-input-port&gt;
4695     </p>
4696 schoenebeck 708 </blockquote><p>
4697 schoenebeck 940
4698 schoenebeck 708 </p>
4699 senoner 542 <p>Where &lt;midi-input-port&gt; is a MIDI input port number of the
4700     MIDI input device connected to the sampler channel given by
4701     &lt;sampler-channel&gt;.
4702     </p>
4703     <p>Possible Answers:
4704     </p>
4705 schoenebeck 708 <p>
4706     </p>
4707 senoner 542 <blockquote class="text">
4708     <p>"OK" -
4709     </p>
4710     <blockquote class="text">
4711     <p>on success
4712     </p>
4713 schoenebeck 940 </blockquote>
4714    
4715 senoner 542
4716     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4717     </p>
4718     <blockquote class="text">
4719     <p>if MIDI input port was set, but there are noteworthy
4720     issue(s) related, providing an appropriate warning code and
4721     warning message
4722     </p>
4723 schoenebeck 940 </blockquote>
4724    
4725 senoner 542
4726     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4727     </p>
4728     <blockquote class="text">
4729 schoenebeck 561 <p>in case it failed, providing an appropriate error code and error message
4730 senoner 542 </p>
4731 schoenebeck 940 </blockquote>
4732    
4733 senoner 542
4734 schoenebeck 708 </blockquote><p>
4735 schoenebeck 940
4736 schoenebeck 708 </p>
4737 senoner 542 <p>Examples:
4738     </p>
4739 schoenebeck 708 <p>
4740     </p>
4741 senoner 542 <blockquote class="text">
4742     <p>
4743     </p>
4744 schoenebeck 708 </blockquote><p>
4745 schoenebeck 940
4746 schoenebeck 708 </p>
4747 schoenebeck 940 <a name="SET CHANNEL MIDI_INPUT_CHANNEL"></a><br /><hr />
4748 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4749     <a name="rfc.section.6.4.20"></a><h3>6.4.20.&nbsp;
4750     Setting MIDI input channel</h3>
4751 senoner 542
4752     <p>The front-end can alter the MIDI channel a sampler channel should
4753     listen to by sending the following command:
4754     </p>
4755 schoenebeck 708 <p>
4756     </p>
4757 senoner 542 <blockquote class="text">
4758     <p>SET CHANNEL MIDI_INPUT_CHANNEL &lt;sampler-channel&gt; &lt;midi-input-chan&gt;
4759     </p>
4760 schoenebeck 708 </blockquote><p>
4761 schoenebeck 940
4762 schoenebeck 708 </p>
4763 senoner 542 <p>Where &lt;midi-input-chan&gt; is the number of the new MIDI input channel where
4764     &lt;sampler-channel&gt; should listen to or "ALL" to listen on all 16 MIDI
4765     channels.
4766     </p>
4767     <p>Possible Answers:
4768     </p>
4769 schoenebeck 708 <p>
4770     </p>
4771 senoner 542 <blockquote class="text">
4772     <p>"OK" -
4773     </p>
4774     <blockquote class="text">
4775     <p>on success
4776     </p>
4777 schoenebeck 940 </blockquote>
4778    
4779 senoner 542
4780     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4781     </p>
4782     <blockquote class="text">
4783     <p>if MIDI input channel was set, but there are noteworthy
4784     issue(s) related, providing an appropriate warning code and
4785     warning message
4786     </p>
4787 schoenebeck 940 </blockquote>
4788    
4789 senoner 542
4790     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4791     </p>
4792     <blockquote class="text">
4793     <p>in case it failed, providing an appropriate error code and error message
4794     </p>
4795 schoenebeck 940 </blockquote>
4796    
4797 senoner 542
4798 schoenebeck 708 </blockquote><p>
4799 schoenebeck 940
4800 schoenebeck 708 </p>
4801 senoner 542 <p>Examples:
4802     </p>
4803 schoenebeck 708 <p>
4804     </p>
4805 senoner 542 <blockquote class="text">
4806     <p>
4807     </p>
4808 schoenebeck 708 </blockquote><p>
4809 schoenebeck 940
4810 schoenebeck 708 </p>
4811 schoenebeck 940 <a name="SET CHANNEL VOLUME"></a><br /><hr />
4812 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4813     <a name="rfc.section.6.4.21"></a><h3>6.4.21.&nbsp;
4814     Setting channel volume</h3>
4815 senoner 542
4816     <p>The front-end can alter the volume of a sampler channel by sending
4817     the following command:
4818     </p>
4819 schoenebeck 708 <p>
4820     </p>
4821 senoner 542 <blockquote class="text">
4822     <p>SET CHANNEL VOLUME &lt;sampler-channel&gt; &lt;volume&gt;
4823     </p>
4824 schoenebeck 708 </blockquote><p>
4825 schoenebeck 940
4826 schoenebeck 708 </p>
4827 senoner 542 <p>Where &lt;volume&gt; is an optionally dotted positive number (a value
4828     smaller than 1.0 means attenuation, whereas a value greater than
4829     1.0 means amplification) and &lt;sampler-channel&gt; defines the sampler
4830     channel where this volume factor should be set.
4831     </p>
4832     <p>Possible Answers:
4833     </p>
4834 schoenebeck 708 <p>
4835     </p>
4836 senoner 542 <blockquote class="text">
4837     <p>"OK" -
4838     </p>
4839     <blockquote class="text">
4840     <p>on success
4841     </p>
4842 schoenebeck 940 </blockquote>
4843    
4844 senoner 542
4845     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4846     </p>
4847     <blockquote class="text">
4848     <p>if channel volume was set, but there are noteworthy
4849     issue(s) related, providing an appropriate warning code and
4850     warning message
4851     </p>
4852 schoenebeck 940 </blockquote>
4853    
4854 senoner 542
4855     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4856     </p>
4857     <blockquote class="text">
4858     <p>in case it failed, providing an appropriate error code and error message
4859     </p>
4860 schoenebeck 940 </blockquote>
4861    
4862 senoner 542
4863 schoenebeck 708 </blockquote><p>
4864 schoenebeck 940
4865 schoenebeck 708 </p>
4866 senoner 542 <p>Examples:
4867     </p>
4868 schoenebeck 708 <p>
4869     </p>
4870 senoner 542 <blockquote class="text">
4871     <p>
4872     </p>
4873 schoenebeck 708 </blockquote><p>
4874 schoenebeck 940
4875 schoenebeck 708 </p>
4876 schoenebeck 940 <a name="SET CHANNEL MUTE"></a><br /><hr />
4877 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4878     <a name="rfc.section.6.4.22"></a><h3>6.4.22.&nbsp;
4879     Muting a sampler channel</h3>
4880 senoner 542
4881 schoenebeck 708 <p>The front-end can mute/unmute a specific sampler
4882     channel by sending the following command:
4883     </p>
4884     <p>
4885     </p>
4886     <blockquote class="text">
4887     <p>SET CHANNEL MUTE &lt;sampler-channel&gt; &lt;mute&gt;
4888     </p>
4889     </blockquote><p>
4890 schoenebeck 940
4891 schoenebeck 708 </p>
4892     <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4893 schoenebeck 974 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>
4894     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
4895 schoenebeck 708 &lt;mute&gt; should be replaced either by "1" to mute the channel or "0"
4896     to unmute the channel.
4897     </p>
4898     <p>Possible Answers:
4899     </p>
4900     <p>
4901     </p>
4902     <blockquote class="text">
4903     <p>"OK" -
4904     </p>
4905     <blockquote class="text">
4906     <p>on success
4907     </p>
4908 schoenebeck 940 </blockquote>
4909    
4910 schoenebeck 708
4911     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4912     </p>
4913     <blockquote class="text">
4914     <p>if the channel was muted/unmuted, but there are noteworthy
4915     issue(s) related, providing an appropriate warning code and
4916     warning message
4917     </p>
4918 schoenebeck 940 </blockquote>
4919    
4920 schoenebeck 708
4921     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4922     </p>
4923     <blockquote class="text">
4924     <p>in case it failed, providing an appropriate error code and error message
4925     </p>
4926 schoenebeck 940 </blockquote>
4927    
4928 schoenebeck 708
4929     </blockquote><p>
4930 schoenebeck 940
4931 schoenebeck 708 </p>
4932     <p>Examples:
4933     </p>
4934     <p>
4935     </p>
4936     <blockquote class="text">
4937     <p>
4938     </p>
4939     </blockquote><p>
4940 schoenebeck 940
4941 schoenebeck 708 </p>
4942 schoenebeck 940 <a name="SET CHANNEL SOLO"></a><br /><hr />
4943 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4944     <a name="rfc.section.6.4.23"></a><h3>6.4.23.&nbsp;
4945     Soloing a sampler channel</h3>
4946 schoenebeck 708
4947     <p>The front-end can solo/unsolo a specific sampler channel
4948     by sending the following command:
4949     </p>
4950     <p>
4951     </p>
4952     <blockquote class="text">
4953     <p>SET CHANNEL SOLO &lt;sampler-channel&gt; &lt;solo&gt;
4954     </p>
4955     </blockquote><p>
4956 schoenebeck 940
4957 schoenebeck 708 </p>
4958     <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4959 schoenebeck 974 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>
4960     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
4961 schoenebeck 708 &lt;solo&gt; should be replaced either by "1" to solo the channel or "0"
4962     to unsolo the channel.
4963     </p>
4964     <p>Possible Answers:
4965     </p>
4966     <p>
4967     </p>
4968     <blockquote class="text">
4969     <p>"OK" -
4970     </p>
4971     <blockquote class="text">
4972     <p>on success
4973     </p>
4974 schoenebeck 940 </blockquote>
4975    
4976 schoenebeck 708
4977     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4978     </p>
4979     <blockquote class="text">
4980     <p>if the channel was soloed/unsoloed, but there are noteworthy
4981     issue(s) related, providing an appropriate warning code and
4982     warning message
4983     </p>
4984 schoenebeck 940 </blockquote>
4985    
4986 schoenebeck 708
4987     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4988     </p>
4989     <blockquote class="text">
4990     <p>in case it failed, providing an appropriate error code and error message
4991     </p>
4992 schoenebeck 940 </blockquote>
4993    
4994 schoenebeck 708
4995     </blockquote><p>
4996 schoenebeck 940
4997 schoenebeck 708 </p>
4998     <p>Examples:
4999     </p>
5000     <p>
5001     </p>
5002     <blockquote class="text">
5003     <p>
5004     </p>
5005     </blockquote><p>
5006 schoenebeck 940
5007 schoenebeck 708 </p>
5008 schoenebeck 974 <a name="SET CHANNEL MIDI_INSTRUMENT_MAP"></a><br /><hr />
5009     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5010     <a name="rfc.section.6.4.24"></a><h3>6.4.24.&nbsp;
5011     Assigning a MIDI instrument map to a sampler channel</h3>
5012    
5013     <p>The front-end can assign a MIDI instrument map to a specific sampler channel
5014     by sending the following command:
5015     </p>
5016     <p>
5017     </p>
5018     <blockquote class="text">
5019     <p>SET CHANNEL MIDI_INSTRUMENT_MAP &lt;sampler-channel&gt; &lt;map&gt;
5020     </p>
5021     </blockquote><p>
5022    
5023     </p>
5024     <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5025     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>
5026     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
5027     &lt;map&gt; can have the following possibilites:
5028     </p>
5029     <p>
5030     </p>
5031     <blockquote class="text">
5032     <p>"NONE" -
5033     </p>
5034     <blockquote class="text">
5035     <p>This is the default setting. In this case
5036     the sampler channel is not assigned any MIDI
5037     instrument map and thus will ignore all MIDI
5038     program change messages.
5039     </p>
5040     </blockquote>
5041    
5042    
5043     <p>"DEFAULT" -
5044     </p>
5045     <blockquote class="text">
5046     <p>The sampler channel will always use the
5047     default MIDI instrument map to handle MIDI
5048     program change messages.
5049     </p>
5050     </blockquote>
5051    
5052    
5053     <p>numeric ID -
5054     </p>
5055     <blockquote class="text">
5056     <p>You can assign a specific MIDI instrument map
5057     by replacing &lt;map&gt; with the respective numeric
5058     ID of the MIDI instrument map as returned by the
5059     <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>
5060     command. Once that map will be deleted, the sampler
5061     channel would fall back to "NONE".
5062     </p>
5063     </blockquote>
5064    
5065    
5066     </blockquote><p>
5067    
5068     </p>
5069     <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>
5070     for details regarding MIDI instrument mapping.
5071     </p>
5072     <p>Possible Answers:
5073     </p>
5074     <p>
5075     </p>
5076     <blockquote class="text">
5077     <p>"OK" -
5078     </p>
5079     <blockquote class="text">
5080     <p>on success
5081     </p>
5082     </blockquote>
5083    
5084    
5085     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5086     </p>
5087     <blockquote class="text">
5088     <p>in case it failed, providing an appropriate error code and error message
5089     </p>
5090     </blockquote>
5091    
5092    
5093     </blockquote><p>
5094    
5095     </p>
5096     <p>Examples:
5097     </p>
5098     <p>
5099     </p>
5100     <blockquote class="text">
5101     <p>
5102     </p>
5103     </blockquote><p>
5104    
5105     </p>
5106 schoenebeck 1002 <a name="CREATE FX_SEND"></a><br /><hr />
5107     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5108     <a name="rfc.section.6.4.25"></a><h3>6.4.25.&nbsp;
5109     Adding an effect send to a sampler channel</h3>
5110    
5111     <p>The front-end can create an additional effect send on a specific sampler channel
5112     by sending the following command:
5113     </p>
5114     <p>
5115     </p>
5116     <blockquote class="text">
5117     <p>CREATE FX_SEND &lt;sampler-channel&gt; &lt;midi-ctrl&gt; [&lt;name&gt;]
5118     </p>
5119     </blockquote><p>
5120    
5121     </p>
5122     <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5123     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>
5124     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
5125     sampler channel on which the effect send should be created on, &lt;midi-ctrl&gt;
5126     is a number between 0..127 defining the MIDI controller which can alter the
5127     effect send level and &lt;name&gt; is an optional argument defining a name
5128 schoenebeck 1390 for the effect send entity. The name does not have to be unique, but MUST be
5129     encapsulated into apostrophes and supports escape sequences as described in chapter
5130     "<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>".
5131 schoenebeck 1002 </p>
5132     <p>By default, that is as initial routing, the effect send's audio channels
5133     are automatically routed to the last audio channels of the sampler channel's
5134     audio output device, that way you can i.e. first increase the amount of audio
5135     channels on the audio output device for having dedicated effect send output
5136     channels and when "CREATE FX_SEND" is called, those channels will automatically
5137     be picked. You can alter the destination channels however with
5138     <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>.
5139    
5140     </p>
5141     <p>Note: Create effect sends on a sampler channel only when needed, because having effect
5142     sends on a sampler channel will decrease runtime performance, because for implementing channel
5143     effect sends, separate (sampler channel local) audio buffers are needed to render and mix
5144     the voices and route the audio signal afterwards to the master outputs and effect send
5145     outputs (along with their respective effect send levels). A sampler channel without effect
5146     sends however can mix its voices directly into the audio output devices's audio buffers
5147     and is thus faster.
5148    
5149     </p>
5150     <p>Possible Answers:
5151     </p>
5152     <p>
5153     </p>
5154     <blockquote class="text">
5155     <p>"OK[&lt;fx-send-id&gt;]" -
5156     </p>
5157     <blockquote class="text">
5158     <p>in case a new effect send could be added to the
5159     sampler channel, where &lt;fx-send-id&gt; reflects the
5160     unique ID of the newly created effect send entity
5161     </p>
5162     </blockquote>
5163    
5164    
5165     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5166     </p>
5167     <blockquote class="text">
5168     <p>when a new effect send could not be added, i.e.
5169     due to invalid parameters
5170     </p>
5171     </blockquote>
5172    
5173    
5174     </blockquote><p>
5175    
5176     </p>
5177     <p>Examples:
5178     </p>
5179     <p>
5180     </p>
5181     <blockquote class="text">
5182     <p>C: "CREATE FX_SEND 0 91 'Reverb Send'"
5183     </p>
5184     <p>S: "OK[0]"
5185     </p>
5186     </blockquote><p>
5187    
5188     </p>
5189     <p>
5190     </p>
5191     <blockquote class="text">
5192     <p>C: "CREATE FX_SEND 0 93"
5193     </p>
5194     <p>S: "OK[1]"
5195     </p>
5196     </blockquote><p>
5197    
5198     </p>
5199     <a name="DESTROY FX_SEND"></a><br /><hr />
5200     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5201     <a name="rfc.section.6.4.26"></a><h3>6.4.26.&nbsp;
5202     Removing an effect send from a sampler channel</h3>
5203    
5204     <p>The front-end can remove an existing effect send on a specific sampler channel
5205     by sending the following command:
5206     </p>
5207     <p>
5208     </p>
5209     <blockquote class="text">
5210     <p>DESTROY FX_SEND &lt;sampler-channel&gt; &lt;fx-send-id&gt;
5211     </p>
5212     </blockquote><p>
5213    
5214     </p>
5215     <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5216     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>
5217     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
5218     sampler channel from which the effect send should be removed from and
5219     &lt;fx-send-id&gt; is the respective effect send number as returned by the
5220     <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>
5221     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.
5222     </p>
5223     <p>Possible Answers:
5224     </p>
5225     <p>
5226     </p>
5227     <blockquote class="text">
5228     <p>"OK" -
5229     </p>
5230     <blockquote class="text">
5231     <p>on success
5232     </p>
5233     </blockquote>
5234    
5235    
5236     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5237     </p>
5238     <blockquote class="text">
5239     <p>in case it failed, providing an appropriate error code and
5240     error message
5241     </p>
5242     </blockquote>
5243    
5244    
5245     </blockquote><p>
5246    
5247     </p>
5248     <p>Example:
5249     </p>
5250     <p>
5251     </p>
5252     <blockquote class="text">
5253     <p>C: "DESTROY FX_SEND 0 0"
5254     </p>
5255     <p>S: "OK"
5256     </p>
5257     </blockquote><p>
5258    
5259     </p>
5260     <a name="GET FX_SENDS"></a><br /><hr />
5261     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5262     <a name="rfc.section.6.4.27"></a><h3>6.4.27.&nbsp;
5263     Getting amount of effect sends on a sampler channel</h3>
5264    
5265     <p>The front-end can ask for the amount of effect sends on a specific sampler channel
5266     by sending the following command:
5267     </p>
5268     <p>
5269     </p>
5270     <blockquote class="text">
5271     <p>GET FX_SENDS &lt;sampler-channel&gt;
5272     </p>
5273     </blockquote><p>
5274    
5275     </p>
5276     <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5277     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>
5278     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.
5279     </p>
5280     <p>Possible Answers:
5281     </p>
5282     <p>
5283     </p>
5284     <blockquote class="text">
5285     <p>The sampler will answer by returning the number of effect
5286     sends on the given sampler channel.
5287     </p>
5288     </blockquote><p>
5289    
5290     </p>
5291     <p>Example:
5292     </p>
5293     <p>
5294     </p>
5295     <blockquote class="text">
5296     <p>C: "GET FX_SENDS 0"
5297     </p>
5298     <p>S: "2"
5299     </p>
5300     </blockquote><p>
5301    
5302     </p>
5303     <a name="LIST FX_SENDS"></a><br /><hr />
5304     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5305     <a name="rfc.section.6.4.28"></a><h3>6.4.28.&nbsp;
5306     Listing all effect sends on a sampler channel</h3>
5307    
5308     <p>The front-end can ask for a list of effect sends on a specific sampler channel
5309     by sending the following command:
5310     </p>
5311     <p>
5312     </p>
5313     <blockquote class="text">
5314     <p>LIST FX_SENDS &lt;sampler-channel&gt;
5315     </p>
5316     </blockquote><p>
5317    
5318     </p>
5319     <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5320     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>
5321     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.
5322     </p>
5323     <p>Possible Answers:
5324     </p>
5325     <p>
5326     </p>
5327     <blockquote class="text">
5328     <p>The sampler will answer by returning a comma separated list
5329     with all effect sends' numerical IDs on the given sampler
5330     channel.
5331     </p>
5332     </blockquote><p>
5333    
5334     </p>
5335     <p>Examples:
5336     </p>
5337     <p>
5338     </p>
5339     <blockquote class="text">
5340     <p>C: "LIST FX_SENDS 0"
5341     </p>
5342     <p>S: "0,1"
5343     </p>
5344     </blockquote><p>
5345    
5346     </p>
5347     <p>
5348     </p>
5349     <blockquote class="text">
5350     <p>C: "LIST FX_SENDS 1"
5351     </p>
5352     <p>S: ""
5353     </p>
5354     </blockquote><p>
5355    
5356     </p>
5357     <a name="GET FX_SEND INFO"></a><br /><hr />
5358     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5359     <a name="rfc.section.6.4.29"></a><h3>6.4.29.&nbsp;
5360     Getting effect send information</h3>
5361    
5362     <p>The front-end can ask for the current settings of an effect send entity
5363     by sending the following command:
5364     </p>
5365     <p>
5366     </p>
5367     <blockquote class="text">
5368     <p>GET FX_SEND INFO &lt;sampler-channel&gt; &lt;fx-send-id&gt;
5369     </p>
5370     </blockquote><p>
5371    
5372     </p>
5373     <p>Where &lt;sampler-channel&gt; is the sampler channel number
5374     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>
5375     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
5376     &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5377     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>
5378     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.
5379    
5380     </p>
5381     <p>Possible Answers:
5382     </p>
5383     <p>
5384     </p>
5385     <blockquote class="text">
5386     <p>The sampler will answer by sending a &lt;CRLF&gt; separated list.
5387     Each answer line begins with the settings category name
5388     followed by a colon and then a space character &lt;SP&gt; and finally
5389     the info character string to that setting category. At the
5390     moment the following categories are defined:
5391     </p>
5392     <p>
5393     </p>
5394     <blockquote class="text">
5395     <p>NAME -
5396     </p>
5397     <blockquote class="text">
5398     <p>name of the effect send entity
5399 schoenebeck 1400 (note that this character string may contain
5400     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>)
5401 schoenebeck 1002 </p>
5402     </blockquote>
5403    
5404    
5405 schoenebeck 1028 <p>MIDI_CONTROLLER -
5406     </p>
5407     <blockquote class="text">
5408     <p>a value between 0 and 127 reflecting the MIDI controller
5409     which is able to modify the effect send's send level
5410     </p>
5411     </blockquote>
5412    
5413    
5414     <p>LEVEL -
5415     </p>
5416     <blockquote class="text">
5417     <p>optionally dotted number reflecting the effect send's
5418     current send level (where a value &lt; 1.0 means attenuation
5419     and a value > 1.0 means amplification)
5420     </p>
5421     </blockquote>
5422    
5423    
5424 schoenebeck 1002 <p>AUDIO_OUTPUT_ROUTING -
5425     </p>
5426     <blockquote class="text">
5427     <p>comma separated list which reflects to which audio
5428     channel of the selected audio output device each
5429     effect send output channel is routed to, e.g. "0,3" would
5430     mean the effect send's output channel 0 is routed to channel
5431     0 of the audio output device and the effect send's output
5432     channel 1 is routed to the channel 3 of the audio
5433     output device (see
5434     <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>
5435     for details)
5436     </p>
5437     </blockquote>
5438    
5439    
5440     </blockquote>
5441    
5442    
5443     </blockquote><p>
5444    
5445     </p>
5446     <p>The mentioned fields above don't have to be in particular order.
5447     </p>
5448     <p>Example:
5449     </p>
5450     <p>
5451     </p>
5452     <blockquote class="text">
5453     <p>C: "GET FX_SEND INFO 0 0"
5454     </p>
5455     <p>S: "NAME: Reverb Send"
5456     </p>
5457 schoenebeck 1028 <p>&nbsp;&nbsp;&nbsp;"MIDI_CONTROLLER: 91"
5458     </p>
5459     <p>&nbsp;&nbsp;&nbsp;"LEVEL: 0.3"
5460     </p>
5461 schoenebeck 1002 <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 2,3"
5462     </p>
5463     <p>&nbsp;&nbsp;&nbsp;"."
5464     </p>
5465     </blockquote><p>
5466    
5467     </p>
5468 iliev 1137 <a name="SET FX_SEND NAME"></a><br /><hr />
5469     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5470     <a name="rfc.section.6.4.30"></a><h3>6.4.30.&nbsp;
5471     Changing effect send's name</h3>
5472    
5473     <p>The front-end can alter the current name of an effect
5474     send entity by sending the following command:
5475     </p>
5476     <p>
5477     </p>
5478     <blockquote class="text">
5479     <p>SET FX_SEND NAME &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;name&gt;
5480     </p>
5481     </blockquote><p>
5482    
5483     </p>
5484     <p>Where &lt;sampler-chan&gt; is the sampler channel number
5485     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>
5486     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,
5487     &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5488     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>
5489     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
5490     &lt;name&gt; is the new name of the effect send entity, which
5491 schoenebeck 1390 does not have to be unique (name MUST be encapsulated into apostrophes
5492     and supports escape sequences as described in chapter
5493     "<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>").
5494    
5495 iliev 1137 </p>
5496     <p>Possible Answers:
5497     </p>
5498     <p>
5499     </p>
5500     <blockquote class="text">
5501     <p>"OK" -
5502     </p>
5503     <blockquote class="text">
5504     <p>on success
5505     </p>
5506     </blockquote>
5507    
5508    
5509     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5510     </p>
5511     <blockquote class="text">
5512     <p>in case it failed, providing an appropriate error code and error message
5513     </p>
5514     </blockquote>
5515    
5516    
5517     </blockquote><p>
5518    
5519     </p>
5520     <p>Example:
5521     </p>
5522     <p>
5523     </p>
5524     <blockquote class="text">
5525     <p>C: "SET FX_SEND NAME 0 0 'Fx Send 1'"
5526     </p>
5527     <p>S: "OK"
5528     </p>
5529     </blockquote><p>
5530    
5531     </p>
5532 schoenebeck 1002 <a name="SET FX_SEND AUDIO_OUTPUT_CHANNEL"></a><br /><hr />
5533     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5534 iliev 1137 <a name="rfc.section.6.4.31"></a><h3>6.4.31.&nbsp;
5535 schoenebeck 1002 Altering effect send's audio routing</h3>
5536    
5537     <p>The front-end can alter the destination of an effect send's audio channel on a specific
5538     sampler channel by sending the following command:
5539     </p>
5540     <p>
5541     </p>
5542     <blockquote class="text">
5543     <p>SET FX_SEND AUDIO_OUTPUT_CHANNEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;audio-src&gt; &lt;audio-dst&gt;
5544     </p>
5545     </blockquote><p>
5546    
5547     </p>
5548     <p>Where &lt;sampler-chan&gt; is the sampler channel number
5549     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>
5550     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,
5551     &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5552     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>
5553     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,
5554     &lt;audio-src&gt; is the numerical ID of the effect send's audio channel
5555     which should be rerouted and &lt;audio-dst&gt; is the numerical ID of
5556     the audio channel of the selected audio output device where &lt;audio-src&gt;
5557     should be routed to.
5558     </p>
5559     <p>Note that effect sends can only route audio to the same audio output
5560     device as assigned to the effect send's sampler channel. Also note that an
5561     effect send entity does always have exactly as much audio channels as its
5562     sampler channel. So if the sampler channel is stereo, the effect send does
5563     have two audio channels as well. Also keep in mind that the amount of audio
5564     channels on a sampler channel might be dependant not only to the deployed
5565     sampler engine on the sampler channel, but also dependant to the instrument
5566     currently loaded. However you can (effectively) turn an i.e. stereo effect
5567     send into a mono one by simply altering its audio routing appropriately.
5568     </p>
5569     <p>Possible Answers:
5570     </p>
5571     <p>
5572     </p>
5573     <blockquote class="text">
5574     <p>"OK" -
5575     </p>
5576     <blockquote class="text">
5577     <p>on success
5578     </p>
5579     </blockquote>
5580    
5581    
5582     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5583     </p>
5584     <blockquote class="text">
5585     <p>if audio output channel was set, but there are noteworthy
5586     issue(s) related, providing an appropriate warning code and
5587     warning message
5588     </p>
5589     </blockquote>
5590    
5591    
5592     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5593     </p>
5594     <blockquote class="text">
5595     <p>in case it failed, providing an appropriate error code and error message
5596     </p>
5597     </blockquote>
5598    
5599    
5600     </blockquote><p>
5601    
5602     </p>
5603     <p>Example:
5604     </p>
5605     <p>
5606     </p>
5607     <blockquote class="text">
5608     <p>C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2"
5609     </p>
5610     <p>S: "OK"
5611     </p>
5612     </blockquote><p>
5613    
5614     </p>
5615 schoenebeck 1028 <a name="SET FX_SEND MIDI_CONTROLLER"></a><br /><hr />
5616     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5617 iliev 1137 <a name="rfc.section.6.4.32"></a><h3>6.4.32.&nbsp;
5618 schoenebeck 1028 Altering effect send's MIDI controller</h3>
5619    
5620     <p>The front-end can alter the MIDI controller of an effect
5621     send entity by sending the following command:
5622     </p>
5623     <p>
5624     </p>
5625     <blockquote class="text">
5626     <p>SET FX_SEND MIDI_CONTROLLER &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;midi-ctrl&gt;
5627     </p>
5628     </blockquote><p>
5629    
5630     </p>
5631     <p>Where &lt;sampler-chan&gt; is the sampler channel number
5632     as returned by the <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
5633     or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command,
5634     &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5635     as returned by the <a class='info' href='#CREATE FX_SEND'>"CREATE FX_SEND"<span> (</span><span class='info'>Adding an effect send to a sampler channel</span><span>)</span></a>
5636     or <a class='info' href='#LIST FX_SENDS'>"LIST FX_SENDS"<span> (</span><span class='info'>Listing all effect sends on a sampler channel</span><span>)</span></a> command and
5637     &lt;midi-ctrl&gt; reflects the MIDI controller which shall be
5638     able to modify the effect send's send level.
5639     </p>
5640     <p>Possible Answers:
5641     </p>
5642     <p>
5643     </p>
5644     <blockquote class="text">
5645     <p>"OK" -
5646     </p>
5647     <blockquote class="text">
5648     <p>on success
5649     </p>
5650     </blockquote>
5651    
5652    
5653     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5654     </p>
5655     <blockquote class="text">
5656     <p>if MIDI controller was set, but there are noteworthy
5657     issue(s) related, providing an appropriate warning code and
5658     warning message
5659     </p>
5660     </blockquote>
5661    
5662    
5663     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5664     </p>
5665     <blockquote class="text">
5666     <p>in case it failed, providing an appropriate error code and error message
5667     </p>
5668     </blockquote>
5669    
5670    
5671     </blockquote><p>
5672    
5673     </p>
5674     <p>Example:
5675     </p>
5676     <p>
5677     </p>
5678     <blockquote class="text">
5679     <p>C: "SET FX_SEND MIDI_CONTROLLER 0 0 91"
5680     </p>
5681     <p>S: "OK"
5682     </p>
5683     </blockquote><p>
5684    
5685     </p>
5686     <a name="SET FX_SEND LEVEL"></a><br /><hr />
5687     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5688 iliev 1137 <a name="rfc.section.6.4.33"></a><h3>6.4.33.&nbsp;
5689 schoenebeck 1028 Altering effect send's send level</h3>
5690    
5691     <p>The front-end can alter the current send level of an effect
5692     send entity by sending the following command:
5693     </p>
5694     <p>
5695     </p>
5696     <blockquote class="text">
5697     <p>SET FX_SEND LEVEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;volume&gt;
5698     </p>
5699     </blockquote><p>
5700    
5701     </p>
5702     <p>Where &lt;sampler-chan&gt; is the sampler channel number
5703     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>
5704     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,
5705     &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5706     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>
5707     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
5708     &lt;volume&gt; is an optionally dotted positive number (a value
5709     smaller than 1.0 means attenuation, whereas a value greater than
5710     1.0 means amplification) reflecting the new send level.
5711     </p>
5712     <p>Possible Answers:
5713     </p>
5714     <p>
5715     </p>
5716     <blockquote class="text">
5717     <p>"OK" -
5718     </p>
5719     <blockquote class="text">
5720     <p>on success
5721     </p>
5722     </blockquote>
5723    
5724    
5725     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5726     </p>
5727     <blockquote class="text">
5728     <p>if new send level was set, but there are noteworthy
5729     issue(s) related, providing an appropriate warning code and
5730     warning message
5731     </p>
5732     </blockquote>
5733    
5734    
5735     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5736     </p>
5737     <blockquote class="text">
5738     <p>in case it failed, providing an appropriate error code and error message
5739     </p>
5740     </blockquote>
5741    
5742    
5743     </blockquote><p>
5744    
5745     </p>
5746     <p>Example:
5747     </p>
5748     <p>
5749     </p>
5750     <blockquote class="text">
5751     <p>C: "SET FX_SEND LEVEL 0 0 0.15"
5752     </p>
5753     <p>S: "OK"
5754     </p>
5755     </blockquote><p>
5756    
5757     </p>
5758 iliev 1773 <a name="SEND CHANNEL MIDI_DATA"></a><br /><hr />
5759     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5760     <a name="rfc.section.6.4.34"></a><h3>6.4.34.&nbsp;
5761     Sending MIDI messages to sampler channel</h3>
5762    
5763     <p>The front-end can send MIDI events to specific sampler channel
5764     by sending the following command:
5765     </p>
5766     <p>
5767     </p>
5768     <blockquote class="text">
5769     <p>SEND CHANNEL MIDI_DATA &lt;midi-msg&gt; &lt;sampler-chan&gt; &lt;arg1&gt; &lt;arg2&gt;
5770     </p>
5771     </blockquote><p>
5772    
5773     </p>
5774     <p>Where &lt;sampler-chan&gt; is the sampler channel number
5775     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>
5776     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,
5777     &lt;arg1&gt; and &lt;arg2&gt; arguments depend on the &lt;midi-msg&gt; argument, which
5778     specifies the MIDI message type. Currently, the following MIDI messages are supported:
5779     </p>
5780     <p>
5781     </p>
5782     <blockquote class="text">
5783     <p>"NOTE_ON" -
5784     </p>
5785     <blockquote class="text">
5786     <p>For turning on MIDI notes, where &lt;arg1&gt;
5787     specifies the key number and &lt;arg2&gt; the velocity
5788     as described in the MIDI specification.
5789     </p>
5790     </blockquote>
5791    
5792    
5793     <p>"NOTE_OFF" -
5794     </p>
5795     <blockquote class="text">
5796     <p>For turning a currently playing MIDI note off, where &lt;arg1&gt;
5797     specifies the key number and &lt;arg2&gt; the velocity
5798     as described in the MIDI specification.
5799     </p>
5800     </blockquote>
5801    
5802    
5803     </blockquote><p>
5804    
5805     </p>
5806     <p>CAUTION: This command is provided for implementations of virtual MIDI keyboards
5807     and no realtime guarantee whatsoever will be made!
5808     </p>
5809     <p>Possible Answers:
5810     </p>
5811     <p>
5812     </p>
5813     <blockquote class="text">
5814     <p>"OK" -
5815     </p>
5816     <blockquote class="text">
5817     <p>on success
5818     </p>
5819     </blockquote>
5820    
5821    
5822     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5823     </p>
5824     <blockquote class="text">
5825     <p>in case it failed, providing an appropriate error code and error message
5826     </p>
5827     </blockquote>
5828    
5829    
5830     </blockquote><p>
5831    
5832     </p>
5833     <p>Example:
5834     </p>
5835     <p>
5836     </p>
5837     <blockquote class="text">
5838     <p>C: "SEND CHANNEL MIDI_DATA NOTE_ON 0 56 112"
5839     </p>
5840     <p>S: "OK"
5841     </p>
5842     </blockquote><p>
5843    
5844     </p>
5845 schoenebeck 940 <a name="RESET CHANNEL"></a><br /><hr />
5846 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5847 iliev 1773 <a name="rfc.section.6.4.35"></a><h3>6.4.35.&nbsp;
5848 schoenebeck 974 Resetting a sampler channel</h3>
5849 schoenebeck 708
5850 senoner 542 <p>The front-end can reset a particular sampler channel by sending the following command:
5851     </p>
5852 schoenebeck 708 <p>
5853     </p>
5854 senoner 542 <blockquote class="text">
5855     <p>RESET CHANNEL &lt;sampler-channel&gt;
5856     </p>
5857 schoenebeck 708 </blockquote><p>
5858 schoenebeck 940
5859 schoenebeck 708 </p>
5860 senoner 542 <p>
5861     Where &lt;sampler-channel&gt; defines the sampler channel to be reset.
5862     This will cause the engine on that sampler channel, its voices and
5863     eventually disk streams and all control and status variables to be
5864     reset.
5865     </p>
5866     <p>Possible Answers:
5867     </p>
5868 schoenebeck 708 <p>
5869     </p>
5870 senoner 542 <blockquote class="text">
5871     <p>"OK" -
5872     </p>
5873     <blockquote class="text">
5874     <p>on success
5875     </p>
5876 schoenebeck 940 </blockquote>
5877    
5878 senoner 542
5879     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5880     </p>
5881     <blockquote class="text">
5882     <p>if channel was reset, but there are noteworthy issue(s)
5883     related, providing an appropriate warning code and warning
5884     message
5885     </p>
5886 schoenebeck 940 </blockquote>
5887    
5888 senoner 542
5889     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5890     </p>
5891     <blockquote class="text">
5892     <p>in case it failed, providing an appropriate error code and
5893     error message
5894     </p>
5895 schoenebeck 940 </blockquote>
5896    
5897 senoner 542
5898 schoenebeck 708 </blockquote><p>
5899 schoenebeck 940
5900 schoenebeck 708 </p>
5901 senoner 542 <p>Examples:
5902     </p>
5903 schoenebeck 708 <p>
5904     </p>
5905 senoner 542 <blockquote class="text">
5906     <p>
5907     </p>
5908 schoenebeck 708 </blockquote><p>
5909 schoenebeck 940
5910 schoenebeck 708 </p>
5911 schoenebeck 940 <a name="anchor12"></a><br /><hr />
5912 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5913     <a name="rfc.section.6.5"></a><h3>6.5.&nbsp;
5914     Controlling connection</h3>
5915 senoner 542
5916     <p>The following commands are used to control the connection to LinuxSampler.
5917     </p>
5918 schoenebeck 940 <a name="SUBSCRIBE"></a><br /><hr />
5919 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5920     <a name="rfc.section.6.5.1"></a><h3>6.5.1.&nbsp;
5921     Register front-end for receiving event messages</h3>
5922 senoner 542
5923     <p>The front-end can register itself to the LinuxSampler application to
5924     be informed about noteworthy events by sending this command:
5925     </p>
5926 schoenebeck 708 <p>
5927     </p>
5928 senoner 542 <blockquote class="text">
5929     <p>SUBSCRIBE &lt;event-id&gt;
5930     </p>
5931 schoenebeck 708 </blockquote><p>
5932 schoenebeck 940
5933 schoenebeck 708 </p>
5934 senoner 542 <p>where &lt;event-id&gt; will be replaced by the respective event that
5935     client wants to subscribe to.
5936     </p>
5937     <p>Possible Answers:
5938     </p>
5939 schoenebeck 708 <p>
5940     </p>
5941 senoner 542 <blockquote class="text">
5942     <p>"OK" -
5943     </p>
5944     <blockquote class="text">
5945     <p>on success
5946     </p>
5947 schoenebeck 940 </blockquote>
5948    
5949 senoner 542
5950     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5951     </p>
5952     <blockquote class="text">
5953     <p>if registration succeeded, but there are noteworthy
5954     issue(s) related, providing an appropriate warning code and
5955     warning message
5956     </p>
5957 schoenebeck 940 </blockquote>
5958    
5959 senoner 542
5960     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5961     </p>
5962     <blockquote class="text">
5963     <p>in case it failed, providing an appropriate error code and
5964     error message
5965     </p>
5966 schoenebeck 940 </blockquote>
5967    
5968 senoner 542
5969 schoenebeck 708 </blockquote><p>
5970 schoenebeck 940
5971 schoenebeck 708 </p>
5972 senoner 542 <p>Examples:
5973     </p>
5974 schoenebeck 708 <p>
5975     </p>
5976 senoner 542 <blockquote class="text">
5977     <p>
5978     </p>
5979 schoenebeck 708 </blockquote><p>
5980 schoenebeck 940
5981 schoenebeck 708 </p>
5982 schoenebeck 940 <a name="UNSUBSCRIBE"></a><br /><hr />
5983 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5984     <a name="rfc.section.6.5.2"></a><h3>6.5.2.&nbsp;
5985     Unregister front-end for not receiving event messages</h3>
5986 senoner 542
5987     <p>The front-end can unregister itself if it doesn't want to receive event
5988     messages anymore by sending the following command:
5989     </p>
5990 schoenebeck 708 <p>
5991     </p>
5992 senoner 542 <blockquote class="text">
5993     <p>UNSUBSCRIBE &lt;event-id&gt;
5994     </p>
5995 schoenebeck 708 </blockquote><p>
5996 schoenebeck 940
5997 schoenebeck 708 </p>
5998 senoner 542 <p>Where &lt;event-id&gt; will be replaced by the respective event that
5999     client doesn't want to receive anymore.
6000     </p>
6001     <p>Possible Answers:
6002     </p>
6003 schoenebeck 708 <p>
6004     </p>
6005 senoner 542 <blockquote class="text">
6006     <p>"OK" -
6007     </p>
6008     <blockquote class="text">
6009     <p>on success
6010     </p>
6011 schoenebeck 940 </blockquote>
6012    
6013 senoner 542
6014     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6015     </p>
6016     <blockquote class="text">
6017     <p>if unregistration succeeded, but there are noteworthy
6018     issue(s) related, providing an appropriate warning code and
6019     warning message
6020     </p>
6021 schoenebeck 940 </blockquote>
6022    
6023 senoner 542
6024     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6025     </p>
6026     <blockquote class="text">
6027     <p>in case it failed, providing an appropriate error code and
6028     error message
6029     </p>
6030 schoenebeck 940 </blockquote>
6031    
6032 senoner 542
6033 schoenebeck 708 </blockquote><p>
6034 schoenebeck 940
6035 schoenebeck 708 </p>
6036 senoner 542 <p>Examples:
6037     </p>
6038 schoenebeck 708 <p>
6039     </p>
6040 senoner 542 <blockquote class="text">
6041     <p>
6042     </p>
6043 schoenebeck 708 </blockquote><p>
6044 schoenebeck 940
6045 schoenebeck 708 </p>
6046 schoenebeck 940 <a name="SET ECHO"></a><br /><hr />
6047 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6048     <a name="rfc.section.6.5.3"></a><h3>6.5.3.&nbsp;
6049     Enable or disable echo of commands</h3>
6050 senoner 542
6051     <p>To enable or disable back sending of commands to the client the following command can be used:
6052     </p>
6053 schoenebeck 708 <p>
6054     </p>
6055 senoner 542 <blockquote class="text">
6056     <p>SET ECHO &lt;value&gt;
6057     </p>
6058 schoenebeck 708 </blockquote><p>
6059 schoenebeck 940
6060 schoenebeck 708 </p>
6061 senoner 542 <p>Where &lt;value&gt; should be replaced either by "1" to enable echo mode
6062     or "0" to disable echo mode. When echo mode is enabled, all
6063     commands send to LinuxSampler will be immediately send back and
6064     after this echo the actual response to the command will be
6065     returned. Echo mode will only be altered for the client connection
6066     that issued the "SET ECHO" command, not globally for all client
6067     connections.
6068     </p>
6069     <p>Possible Answers:
6070     </p>
6071 schoenebeck 708 <p>
6072     </p>
6073 senoner 542 <blockquote class="text">
6074     <p>"OK" -
6075     </p>
6076     <blockquote class="text">
6077     <p>usually
6078     </p>
6079 schoenebeck 940 </blockquote>
6080    
6081 senoner 542
6082     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6083     </p>
6084     <blockquote class="text">
6085     <p>on syntax error, e.g. non boolean value
6086     </p>
6087 schoenebeck 940 </blockquote>
6088    
6089 senoner 542
6090 schoenebeck 708 </blockquote><p>
6091 schoenebeck 940
6092 schoenebeck 708 </p>
6093 senoner 542 <p>Examples:
6094     </p>
6095 schoenebeck 708 <p>
6096     </p>
6097 senoner 542 <blockquote class="text">
6098     <p>
6099     </p>
6100 schoenebeck 708 </blockquote><p>
6101 schoenebeck 940
6102 schoenebeck 708 </p>
6103 schoenebeck 940 <a name="QUIT"></a><br /><hr />
6104 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6105     <a name="rfc.section.6.5.4"></a><h3>6.5.4.&nbsp;
6106     Close client connection</h3>
6107 senoner 542
6108     <p>The client can close its network connection to LinuxSampler by sending the following command:
6109     </p>
6110 schoenebeck 708 <p>
6111     </p>
6112 senoner 542 <blockquote class="text">
6113     <p>QUIT
6114     </p>
6115 schoenebeck 708 </blockquote><p>
6116 schoenebeck 940
6117 schoenebeck 708 </p>
6118 senoner 542 <p>This is probably more interesting for manual telnet connections to
6119     LinuxSampler than really useful for a front-end implementation.
6120     </p>
6121 schoenebeck 940 <a name="anchor13"></a><br /><hr />
6122 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6123     <a name="rfc.section.6.6"></a><h3>6.6.&nbsp;
6124     Global commands</h3>
6125 senoner 542
6126     <p>The following commands have global impact on the sampler.
6127     </p>
6128 schoenebeck 940 <a name="GET TOTAL_VOICE_COUNT"></a><br /><hr />
6129 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6130     <a name="rfc.section.6.6.1"></a><h3>6.6.1.&nbsp;
6131     Current number of active voices</h3>
6132 senoner 542
6133 schoenebeck 940 <p>The front-end can ask for the current number of active voices on
6134     the sampler by sending the following command:
6135     </p>
6136     <p>
6137     </p>
6138     <blockquote class="text">
6139     <p>GET TOTAL_VOICE_COUNT
6140     </p>
6141     </blockquote><p>
6142    
6143     </p>
6144     <p>Possible Answers:
6145     </p>
6146     <p>
6147     </p>
6148     <blockquote class="text">
6149     <p>LinuxSampler will answer by returning the number of all active
6150     voices on the sampler.
6151     </p>
6152     </blockquote><p>
6153    
6154     </p>
6155     <a name="GET TOTAL_VOICE_COUNT_MAX"></a><br /><hr />
6156 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6157     <a name="rfc.section.6.6.2"></a><h3>6.6.2.&nbsp;
6158     Maximum amount of active voices</h3>
6159 schoenebeck 940
6160     <p>The front-end can ask for the maximum number of active voices
6161     by sending the following command:
6162     </p>
6163     <p>
6164     </p>
6165     <blockquote class="text">
6166     <p>GET TOTAL_VOICE_COUNT_MAX
6167     </p>
6168     </blockquote><p>
6169    
6170     </p>
6171     <p>Possible Answers:
6172     </p>
6173     <p>
6174     </p>
6175     <blockquote class="text">
6176     <p>LinuxSampler will answer by returning the maximum number
6177     of active voices.
6178     </p>
6179     </blockquote><p>
6180    
6181     </p>
6182 schoenebeck 1572 <a name="GET TOTAL_STREAM_COUNT"></a><br /><hr />
6183     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6184     <a name="rfc.section.6.6.3"></a><h3>6.6.3.&nbsp;
6185     Current number of active disk streams</h3>
6186    
6187     <p>The front-end can ask for the current number of active disk streams on
6188     the sampler by sending the following command:
6189     </p>
6190     <p>
6191     </p>
6192     <blockquote class="text">
6193     <p>GET TOTAL_STREAM_COUNT
6194     </p>
6195     </blockquote><p>
6196    
6197     </p>
6198     <p>Possible Answers:
6199     </p>
6200     <p>
6201     </p>
6202     <blockquote class="text">
6203     <p>LinuxSampler will answer by returning the number of all active
6204     disk streams on the sampler.
6205     </p>
6206     </blockquote><p>
6207    
6208     </p>
6209 schoenebeck 940 <a name="RESET"></a><br /><hr />
6210 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6211 schoenebeck 1572 <a name="rfc.section.6.6.4"></a><h3>6.6.4.&nbsp;
6212 schoenebeck 974 Reset sampler</h3>
6213 schoenebeck 940
6214 senoner 542 <p>The front-end can reset the whole sampler by sending the following command:
6215     </p>
6216 schoenebeck 708 <p>
6217     </p>
6218 senoner 542 <blockquote class="text">
6219     <p>RESET
6220     </p>
6221 schoenebeck 708 </blockquote><p>
6222 schoenebeck 940
6223 schoenebeck 708 </p>
6224 senoner 542 <p>Possible Answers:
6225     </p>
6226 schoenebeck 708 <p>
6227     </p>
6228 senoner 542 <blockquote class="text">
6229     <p>"OK" -
6230     </p>
6231     <blockquote class="text">
6232     <p>always
6233     </p>
6234 schoenebeck 940 </blockquote>
6235    
6236 senoner 542
6237 schoenebeck 708 </blockquote><p>
6238 schoenebeck 940
6239 schoenebeck 708 </p>
6240 senoner 542 <p>Examples:
6241     </p>
6242 schoenebeck 708 <p>
6243     </p>
6244 senoner 542 <blockquote class="text">
6245     <p>
6246     </p>
6247 schoenebeck 708 </blockquote><p>
6248 schoenebeck 940
6249 schoenebeck 708 </p>
6250 schoenebeck 940 <a name="GET SERVER INFO"></a><br /><hr />
6251 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6252 schoenebeck 1572 <a name="rfc.section.6.6.5"></a><h3>6.6.5.&nbsp;
6253 schoenebeck 974 General sampler informations</h3>
6254 schoenebeck 575
6255     <p>The client can ask for general informations about the LinuxSampler
6256     instance by sending the following command:
6257     </p>
6258 schoenebeck 708 <p>
6259     </p>
6260 schoenebeck 575 <blockquote class="text">
6261     <p>GET SERVER INFO
6262     </p>
6263 schoenebeck 708 </blockquote><p>
6264 schoenebeck 940
6265 schoenebeck 708 </p>
6266 schoenebeck 575 <p>Possible Answers:
6267     </p>
6268 schoenebeck 708 <p>
6269     </p>
6270 schoenebeck 575 <blockquote class="text">
6271     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6272     Each answer line begins with the information category name
6273     followed by a colon and then a space character &lt;SP&gt; and finally
6274     the info character string to that information category. At the
6275     moment the following categories are defined:
6276 schoenebeck 940
6277 schoenebeck 575 </p>
6278 schoenebeck 708 <p>
6279     </p>
6280 schoenebeck 575 <blockquote class="text">
6281     <p>DESCRIPTION -
6282     </p>
6283     <blockquote class="text">
6284     <p>arbitrary textual description about the sampler
6285 schoenebeck 1390 (note that the character string may contain
6286     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>)
6287 schoenebeck 575 </p>
6288 schoenebeck 940 </blockquote>
6289    
6290 schoenebeck 575
6291     <p>VERSION -
6292     </p>
6293     <blockquote class="text">
6294     <p>version of the sampler
6295     </p>
6296 schoenebeck 940 </blockquote>
6297    
6298 schoenebeck 575
6299     <p>PROTOCOL_VERSION -
6300     </p>
6301     <blockquote class="text">
6302     <p>version of the LSCP specification the sampler
6303 schoenebeck 974 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)
6304 schoenebeck 575 </p>
6305 schoenebeck 940 </blockquote>
6306    
6307 schoenebeck 575
6308 iliev 1162 <p>INSTRUMENTS_DB_SUPPORT -
6309     </p>
6310     <blockquote class="text">
6311     <p>either yes or no, specifies whether the
6312     sampler is build with instruments database support.
6313     </p>
6314 schoenebeck 940 </blockquote>
6315 iliev 1162
6316    
6317     </blockquote>
6318 schoenebeck 940
6319 schoenebeck 575
6320 schoenebeck 708 </blockquote><p>
6321 schoenebeck 940
6322 schoenebeck 708 </p>
6323 schoenebeck 575 <p>The mentioned fields above don't have to be in particular order.
6324     Other fields might be added in future.
6325     </p>
6326 schoenebeck 1006 <a name="GET VOLUME"></a><br /><hr />
6327     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6328 schoenebeck 1572 <a name="rfc.section.6.6.6"></a><h3>6.6.6.&nbsp;
6329 schoenebeck 1006 Getting global volume attenuation</h3>
6330    
6331     <p>The client can ask for the current global sampler-wide volume
6332     attenuation by sending the following command:
6333     </p>
6334     <p>
6335     </p>
6336     <blockquote class="text">
6337     <p>GET VOLUME
6338     </p>
6339     </blockquote><p>
6340    
6341     </p>
6342     <p>Possible Answers:
6343     </p>
6344     <p>
6345     </p>
6346     <blockquote class="text">
6347     <p>The sampler will always answer by returning the optional
6348     dotted floating point coefficient, reflecting the current
6349     global volume attenuation.
6350    
6351     </p>
6352     </blockquote><p>
6353    
6354     </p>
6355     <p>Note: it is up to the respective sampler engine whether to obey
6356     that global volume parameter or not, but in general all engines SHOULD
6357     use this parameter.
6358     </p>
6359     <a name="SET VOLUME"></a><br /><hr />
6360     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6361 schoenebeck 1572 <a name="rfc.section.6.6.7"></a><h3>6.6.7.&nbsp;
6362 schoenebeck 1006 Setting global volume attenuation</h3>
6363    
6364     <p>The client can alter the current global sampler-wide volume
6365     attenuation by sending the following command:
6366     </p>
6367     <p>
6368     </p>
6369     <blockquote class="text">
6370     <p>SET VOLUME &lt;volume&gt;
6371     </p>
6372     </blockquote><p>
6373    
6374     </p>
6375     <p>Where &lt;volume&gt; should be replaced by the optional dotted
6376     floating point value, reflecting the new global volume parameter.
6377     This value might usually be in the range between 0.0 and 1.0, that
6378     is for attenuating the overall volume.
6379     </p>
6380     <p>Possible Answers:
6381     </p>
6382     <p>
6383     </p>
6384     <blockquote class="text">
6385     <p>"OK" -
6386     </p>
6387     <blockquote class="text">
6388     <p>on success
6389     </p>
6390     </blockquote>
6391    
6392    
6393     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6394     </p>
6395     <blockquote class="text">
6396     <p>if the global volume was set, but there are noteworthy
6397     issue(s) related, providing an appropriate warning code and
6398     warning message
6399     </p>
6400     </blockquote>
6401    
6402    
6403     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6404     </p>
6405     <blockquote class="text">
6406     <p>in case it failed, providing an appropriate error code and error message
6407     </p>
6408     </blockquote>
6409    
6410    
6411     </blockquote><p>
6412    
6413     </p>
6414 schoenebeck 1801 <a name="GET VOICES"></a><br /><hr />
6415     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6416     <a name="rfc.section.6.6.8"></a><h3>6.6.8.&nbsp;
6417     Getting global voice limit</h3>
6418    
6419     <p>The client can ask for the current global sampler-wide limit
6420     for maximum voices by sending the following command:
6421     </p>
6422     <p>
6423     </p>
6424     <blockquote class="text">
6425     <p>GET VOICES
6426     </p>
6427     </blockquote><p>
6428    
6429     </p>
6430     <p>Possible Answers:
6431     </p>
6432     <p>
6433     </p>
6434     <blockquote class="text">
6435     <p>LinuxSampler will answer by returning the number for
6436     the current limit of maximum voices.
6437     </p>
6438     </blockquote><p>
6439    
6440     </p>
6441     <p>The voice limit setting defines how many voices should maximum
6442     be processed by the sampler at the same time. If the user
6443     triggers new notes which would exceed that voice limit, the
6444     sampler engine will react by stealing old voices for those
6445     newly triggered notes. Note that the amount of voices triggered
6446     by a new note can be larger than one and is dependent to the
6447     respective instrument and probably further criterias.
6448     </p>
6449     <a name="SET VOICES"></a><br /><hr />
6450     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6451     <a name="rfc.section.6.6.9"></a><h3>6.6.9.&nbsp;
6452     Setting global voice limit</h3>
6453    
6454     <p>The client can alter the current global sampler-wide limit
6455     for maximum voices by sending the following command:
6456     </p>
6457     <p>
6458     </p>
6459     <blockquote class="text">
6460     <p>SET VOICES &lt;max-voices&gt;
6461     </p>
6462     </blockquote><p>
6463    
6464     </p>
6465     <p>Where &lt;max-voices&gt; should be replaced by the integer
6466     value, reflecting the new global amount limit of maximum voices.
6467     This value has to be larger than 0.
6468     </p>
6469     <p>Possible Answers:
6470     </p>
6471     <p>
6472     </p>
6473     <blockquote class="text">
6474     <p>"OK" -
6475     </p>
6476     <blockquote class="text">
6477     <p>on success
6478     </p>
6479     </blockquote>
6480    
6481    
6482     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6483     </p>
6484     <blockquote class="text">
6485     <p>if the voice limit was set, but there are noteworthy
6486     issue(s) related, providing an appropriate warning code and
6487     warning message
6488     </p>
6489     </blockquote>
6490    
6491    
6492     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6493     </p>
6494     <blockquote class="text">
6495     <p>in case it failed, providing an appropriate error code and error message
6496     </p>
6497     </blockquote>
6498    
6499    
6500     </blockquote><p>
6501    
6502     </p>
6503     <p>Note: the given value will be passed to all sampler engine instances.
6504     The total amount of maximum voices on the running system might thus
6505     be as big as the given value multiplied by the current amount of engine
6506     instances.
6507     </p>
6508     <p>Caution: when adjusting the voice limit, you SHOULD also
6509     adjust the disk stream limit respectively and vice versa.
6510     </p>
6511     <a name="GET STREAMS"></a><br /><hr />
6512     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6513     <a name="rfc.section.6.6.10"></a><h3>6.6.10.&nbsp;
6514     Getting global disk stream limit</h3>
6515    
6516     <p>The client can ask for the current global sampler-wide limit
6517     for maximum disk streams by sending the following command:
6518     </p>
6519     <p>
6520     </p>
6521     <blockquote class="text">
6522     <p>GET STREAMS
6523     </p>
6524     </blockquote><p>
6525    
6526     </p>
6527     <p>Possible Answers:
6528     </p>
6529     <p>
6530     </p>
6531     <blockquote class="text">
6532     <p>LinuxSampler will answer by returning the number for
6533     the current limit of maximum disk streams.
6534     </p>
6535     </blockquote><p>
6536    
6537     </p>
6538     <p>The disk stream limit setting defines how many disk streams should
6539     maximum be processed by a sampler engine at the same time. The
6540     higher this value, the more memory (RAM) will be occupied, since
6541     every disk streams allocates a certain buffer size for being able
6542     to perform its streaming operations.
6543     </p>
6544     <a name="SET STREAMS"></a><br /><hr />
6545     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6546     <a name="rfc.section.6.6.11"></a><h3>6.6.11.&nbsp;
6547     Setting global disk stream limit</h3>
6548    
6549     <p>The client can alter the current global sampler-wide limit
6550     for maximum disk streams by sending the following command:
6551     </p>
6552     <p>
6553     </p>
6554     <blockquote class="text">
6555     <p>SET STREAMS &lt;max-streams&gt;
6556     </p>
6557     </blockquote><p>
6558    
6559     </p>
6560     <p>Where &lt;max-streams&gt; should be replaced by the integer
6561     value, reflecting the new global amount limit of maximum disk streams.
6562     This value has to be positive.
6563     </p>
6564     <p>Possible Answers:
6565     </p>
6566     <p>
6567     </p>
6568     <blockquote class="text">
6569     <p>"OK" -
6570     </p>
6571     <blockquote class="text">
6572     <p>on success
6573     </p>
6574     </blockquote>
6575    
6576    
6577     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6578     </p>
6579     <blockquote class="text">
6580     <p>if the disk stream limit was set, but there are noteworthy
6581     issue(s) related, providing an appropriate warning code and
6582     warning message
6583     </p>
6584     </blockquote>
6585    
6586    
6587     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6588     </p>
6589     <blockquote class="text">
6590     <p>in case it failed, providing an appropriate error code and error message
6591     </p>
6592     </blockquote>
6593    
6594    
6595     </blockquote><p>
6596    
6597     </p>
6598     <p>Note: the given value will be passed to all sampler engine instances.
6599     The total amount of maximum disk streams on the running system might
6600     thus be as big as the given value multiplied by the current amount of
6601     engine instances.
6602     </p>
6603     <p>Caution: when adjusting the disk stream limit, you SHOULD also
6604     adjust the voice limit respectively and vice versa.
6605     </p>
6606 schoenebeck 974 <a name="MIDI Instrument Mapping"></a><br /><hr />
6607     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6608     <a name="rfc.section.6.7"></a><h3>6.7.&nbsp;
6609     MIDI Instrument Mapping</h3>
6610 schoenebeck 945
6611     <p>The MIDI protocol provides a way to switch between instruments
6612     by sending so called MIDI bank select and MIDI program change
6613     messages which are essentially just numbers. The following commands
6614     allow to actually map arbitrary MIDI bank select / program change
6615     numbers with real instruments.
6616     </p>
6617 schoenebeck 974 <p>The sampler allows to manage an arbitrary amount of MIDI
6618     instrument maps which define which instrument to load on
6619     which MIDI program change message.
6620 schoenebeck 945 </p>
6621 schoenebeck 974 <p>By default, that is when the sampler is launched, there is no
6622     map, thus the sampler will simply ignore all program change
6623     messages. The front-end has to explicitly create at least one
6624     map, add entries to the map and tell the respective sampler
6625     channel(s) which MIDI instrument map to use, so the sampler
6626     knows how to react on a given program change message on the
6627     respective sampler channel, that is by switching to the
6628     respectively defined engine type and loading the respective
6629     instrument. See command
6630     <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>
6631     for how to assign a MIDI instrument map to a sampler channel.
6632     </p>
6633 schoenebeck 945 <p>Also note per MIDI specification a bank select message does not
6634     cause to switch to another instrument. Instead when receiving a
6635     bank select message the bank value will be stored and a subsequent
6636     program change message (which may occur at any time) will finally
6637     cause the sampler to switch to the respective instrument as
6638     reflected by the current MIDI instrument map.
6639     </p>
6640 schoenebeck 1390 <a name="ADD MIDI_INSTRUMENT_MAP"></a><br /><hr />
6641 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6642     <a name="rfc.section.6.7.1"></a><h3>6.7.1.&nbsp;
6643     Create a new MIDI instrument map</h3>
6644    
6645     <p>The front-end can add a new MIDI instrument map by sending
6646     the following command:
6647     </p>
6648     <p>
6649     </p>
6650     <blockquote class="text">
6651     <p>ADD MIDI_INSTRUMENT_MAP [&lt;name&gt;]
6652     </p>
6653     </blockquote><p>
6654    
6655     </p>
6656     <p>Where &lt;name&gt; is an optional argument allowing to
6657     assign a custom name to the new map. MIDI instrument Map
6658 schoenebeck 1390 names do not have to be unique, but MUST be encapsulated
6659     into apostrophes and support escape sequences as described
6660     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>".
6661    
6662 schoenebeck 974 </p>
6663     <p>Possible Answers:
6664     </p>
6665     <p>
6666     </p>
6667     <blockquote class="text">
6668     <p>"OK[&lt;map&gt;]" -
6669     </p>
6670     <blockquote class="text">
6671     <p>in case a new MIDI instrument map could
6672     be added, where &lt;map&gt; reflects the
6673     unique ID of the newly created MIDI
6674     instrument map
6675     </p>
6676     </blockquote>
6677    
6678    
6679     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6680     </p>
6681     <blockquote class="text">
6682     <p>when a new map could not be created, which
6683     might never occur in practice
6684     </p>
6685     </blockquote>
6686    
6687    
6688     </blockquote><p>
6689    
6690     </p>
6691     <p>Examples:
6692     </p>
6693     <p>
6694     </p>
6695     <blockquote class="text">
6696     <p>C: "ADD MIDI_INSTRUMENT_MAP 'Standard Map'"
6697     </p>
6698     <p>S: "OK[0]"
6699     </p>
6700     </blockquote><p>
6701    
6702     </p>
6703     <p>
6704     </p>
6705     <blockquote class="text">
6706     <p>C: "ADD MIDI_INSTRUMENT_MAP 'Standard Drumkit'"
6707     </p>
6708     <p>S: "OK[1]"
6709     </p>
6710     </blockquote><p>
6711    
6712     </p>
6713     <p>
6714     </p>
6715     <blockquote class="text">
6716     <p>C: "ADD MIDI_INSTRUMENT_MAP"
6717     </p>
6718     <p>S: "OK[5]"
6719     </p>
6720     </blockquote><p>
6721    
6722     </p>
6723     <a name="REMOVE MIDI_INSTRUMENT_MAP"></a><br /><hr />
6724     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6725     <a name="rfc.section.6.7.2"></a><h3>6.7.2.&nbsp;
6726     Delete one particular or all MIDI instrument maps</h3>
6727    
6728     <p>The front-end can delete a particular MIDI instrument map
6729     by sending the following command:
6730     </p>
6731     <p>
6732     </p>
6733     <blockquote class="text">
6734     <p>REMOVE MIDI_INSTRUMENT_MAP &lt;map&gt;
6735     </p>
6736     </blockquote><p>
6737    
6738     </p>
6739     <p>Where &lt;map&gt; reflects the unique ID of the map to delete
6740     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>
6741     command.
6742     </p>
6743     <p>The front-end can delete all MIDI instrument maps by
6744     sending the following command:
6745     </p>
6746     <p>
6747     </p>
6748     <blockquote class="text">
6749     <p>REMOVE MIDI_INSTRUMENT_MAP ALL
6750     </p>
6751     </blockquote><p>
6752    
6753     </p>
6754     <p>Possible Answers:
6755     </p>
6756     <p>
6757     </p>
6758     <blockquote class="text">
6759     <p>"OK" -
6760     </p>
6761     <blockquote class="text">
6762     <p>in case the map(s) could be deleted
6763     </p>
6764     </blockquote>
6765    
6766    
6767     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6768     </p>
6769     <blockquote class="text">
6770     <p>when the given map does not exist
6771     </p>
6772     </blockquote>
6773    
6774    
6775     </blockquote><p>
6776    
6777     </p>
6778     <p>Examples:
6779     </p>
6780     <p>
6781     </p>
6782     <blockquote class="text">
6783     <p>C: "REMOVE MIDI_INSTRUMENT_MAP 0"
6784     </p>
6785     <p>S: "OK"
6786     </p>
6787     </blockquote><p>
6788    
6789     </p>
6790     <p>
6791     </p>
6792     <blockquote class="text">
6793     <p>C: "REMOVE MIDI_INSTRUMENT_MAP ALL"
6794     </p>
6795     <p>S: "OK"
6796     </p>
6797     </blockquote><p>
6798    
6799     </p>
6800     <a name="GET MIDI_INSTRUMENT_MAPS"></a><br /><hr />
6801     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6802     <a name="rfc.section.6.7.3"></a><h3>6.7.3.&nbsp;
6803     Get amount of existing MIDI instrument maps</h3>
6804    
6805     <p>The front-end can retrieve the current amount of MIDI
6806     instrument maps by sending the following command:
6807     </p>
6808     <p>
6809     </p>
6810     <blockquote class="text">
6811     <p>GET MIDI_INSTRUMENT_MAPS
6812     </p>
6813     </blockquote><p>
6814    
6815     </p>
6816     <p>Possible Answers:
6817     </p>
6818     <p>
6819     </p>
6820     <blockquote class="text">
6821     <p>The sampler will answer by returning the current
6822     number of MIDI instrument maps.
6823     </p>
6824     </blockquote><p>
6825    
6826     </p>
6827     <p>Example:
6828     </p>
6829     <p>
6830     </p>
6831     <blockquote class="text">
6832     <p>C: "GET MIDI_INSTRUMENT_MAPS"
6833     </p>
6834     <p>S: "2"
6835     </p>
6836     </blockquote><p>
6837    
6838     </p>
6839     <a name="LIST MIDI_INSTRUMENT_MAPS"></a><br /><hr />
6840     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6841     <a name="rfc.section.6.7.4"></a><h3>6.7.4.&nbsp;
6842     Getting all created MIDI instrument maps</h3>
6843    
6844     <p>The number of MIDI instrument maps can change on runtime. To get the
6845     current list of MIDI instrument maps, the front-end can send the
6846     following command:
6847     </p>
6848     <p>
6849     </p>
6850     <blockquote class="text">
6851     <p>LIST MIDI_INSTRUMENT_MAPS
6852     </p>
6853     </blockquote><p>
6854    
6855     </p>
6856     <p>Possible Answers:
6857     </p>
6858     <p>
6859     </p>
6860     <blockquote class="text">
6861     <p>The sampler will answer by returning a comma separated list
6862     with all MIDI instrument maps' numerical IDs.
6863     </p>
6864     </blockquote><p>
6865    
6866     </p>
6867     <p>Example:
6868     </p>
6869     <p>
6870     </p>
6871     <blockquote class="text">
6872     <p>C: "LIST MIDI_INSTRUMENT_MAPS"
6873     </p>
6874     <p>S: "0,1,5,12"
6875     </p>
6876     </blockquote><p>
6877    
6878     </p>
6879     <a name="GET MIDI_INSTRUMENT_MAP INFO"></a><br /><hr />
6880     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6881     <a name="rfc.section.6.7.5"></a><h3>6.7.5.&nbsp;
6882     Getting MIDI instrument map information</h3>
6883    
6884     <p>The front-end can ask for the current settings of a MIDI
6885     instrument map by sending the following command:
6886     </p>
6887     <p>
6888     </p>
6889     <blockquote class="text">
6890     <p>GET MIDI_INSTRUMENT_MAP INFO &lt;map&gt;
6891     </p>
6892     </blockquote><p>
6893    
6894     </p>
6895     <p>Where &lt;map&gt; is the numerical ID of the map the
6896     front-end is interested in as returned by the
6897     <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>
6898     command.
6899     </p>
6900     <p>Possible Answers:
6901     </p>
6902     <p>
6903     </p>
6904     <blockquote class="text">
6905     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6906     Each answer line begins with the settings category name
6907     followed by a colon and then a space character &lt;SP&gt; and finally
6908     the info character string to that setting category. At the
6909     moment the following categories are defined:
6910     </p>
6911     <p>
6912     </p>
6913     <blockquote class="text">
6914     <p>NAME -
6915     </p>
6916     <blockquote class="text">
6917     <p>custom name of the given map,
6918     which does not have to be unique
6919 schoenebeck 1400 (note that this character string may contain
6920     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>)
6921 schoenebeck 974 </p>
6922     </blockquote>
6923    
6924    
6925 iliev 1137 <p>DEFAULT -
6926     </p>
6927     <blockquote class="text">
6928     <p>either true or false,
6929     defines whether this map is the default map
6930     </p>
6931 schoenebeck 974 </blockquote>
6932 iliev 1137
6933    
6934     </blockquote>
6935 schoenebeck 974
6936    
6937     </blockquote><p>
6938    
6939     </p>
6940     <p>The mentioned fields above don't have to be in particular order.
6941     </p>
6942     <p>Example:
6943     </p>
6944     <p>
6945     </p>
6946     <blockquote class="text">
6947     <p>C: "GET MIDI_INSTRUMENT_MAP INFO 0"
6948     </p>
6949     <p>S: "NAME: Standard Map"
6950     </p>
6951 iliev 1137 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: true"
6952     </p>
6953 schoenebeck 974 <p>&nbsp;&nbsp;&nbsp;"."
6954     </p>
6955     </blockquote><p>
6956    
6957     </p>
6958     <a name="SET MIDI_INSTRUMENT_MAP NAME"></a><br /><hr />
6959     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6960     <a name="rfc.section.6.7.6"></a><h3>6.7.6.&nbsp;
6961     Renaming a MIDI instrument map</h3>
6962    
6963     <p>The front-end can alter the custom name of a MIDI
6964     instrument map by sending the following command:
6965     </p>
6966     <p>
6967     </p>
6968     <blockquote class="text">
6969     <p>SET MIDI_INSTRUMENT_MAP NAME &lt;map&gt; &lt;name&gt;
6970     </p>
6971     </blockquote><p>
6972    
6973     </p>
6974     <p>Where &lt;map&gt; is the numerical ID of the map and
6975     &lt;name&gt; the new custom name of the map, which does not
6976 schoenebeck 1390 have to be unique (name MUST be encapsulated into apostrophes
6977     and supports escape sequences as described in chapter
6978     "<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>").
6979    
6980 schoenebeck 974 </p>
6981     <p>Possible Answers:
6982     </p>
6983     <p>
6984     </p>
6985     <blockquote class="text">
6986     <p>"OK" -
6987     </p>
6988     <blockquote class="text">
6989     <p>on success
6990     </p>
6991     </blockquote>
6992    
6993    
6994     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6995     </p>
6996     <blockquote class="text">
6997     <p>in case the given map does not exist
6998     </p>
6999     </blockquote>
7000    
7001    
7002     </blockquote><p>
7003    
7004     </p>
7005     <p>Example:
7006     </p>
7007     <p>
7008     </p>
7009     <blockquote class="text">
7010     <p>C: "SET MIDI_INSTRUMENT_MAP NAME 0 'Foo instruments'"
7011     </p>
7012     <p>S: "OK"
7013     </p>
7014     </blockquote><p>
7015    
7016     </p>
7017 schoenebeck 945 <a name="MAP MIDI_INSTRUMENT"></a><br /><hr />
7018 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7019     <a name="rfc.section.6.7.7"></a><h3>6.7.7.&nbsp;
7020     Create or replace a MIDI instrument map entry</h3>
7021 schoenebeck 945
7022     <p>The front-end can create a new or replace an existing entry
7023 schoenebeck 974 in a sampler's MIDI instrument map by sending the following
7024 schoenebeck 945 command:
7025     </p>
7026     <p>
7027     </p>
7028     <blockquote class="text">
7029 schoenebeck 1048 <p>MAP MIDI_INSTRUMENT [NON_MODAL] &lt;map&gt;
7030 schoenebeck 974 &lt;midi_bank&gt; &lt;midi_prog&gt; &lt;engine_name&gt;
7031 schoenebeck 945 &lt;filename&gt; &lt;instrument_index&gt; &lt;volume_value&gt;
7032     [&lt;instr_load_mode&gt;] [&lt;name&gt;]
7033     </p>
7034     </blockquote><p>
7035    
7036     </p>
7037 schoenebeck 974 <p>Where &lt;map&gt; is the numeric ID of the map to alter,
7038     &lt;midi_bank&gt; is an integer value between
7039     0..16383 reflecting the MIDI bank select index,
7040     &lt;midi_prog&gt; an
7041 schoenebeck 945 integer value between 0..127 reflecting the MIDI program change
7042     index, &lt;engine_name&gt; a sampler engine name as returned by
7043 schoenebeck 974 the <a class='info' href='#LIST AVAILABLE_ENGINES'>"LIST AVAILABLE_ENGINES"<span> (</span><span class='info'>Getting all available engines</span><span>)</span></a>
7044 schoenebeck 945 command (not encapsulated into apostrophes), &lt;filename&gt; the name
7045 schoenebeck 1251 of the instrument's file to be deployed (encapsulated into apostrophes,
7046     supporting escape sequences as described in chapter
7047     "<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>"),
7048 schoenebeck 974 &lt;instrument_index&gt; the index (integer value) of the instrument
7049 schoenebeck 945 within the given file, &lt;volume_value&gt; reflects the master
7050     volume of the instrument as optionally dotted number (where a
7051 schoenebeck 1028 value &lt; 1.0 means attenuation and a value > 1.0 means
7052 schoenebeck 945 amplification). This parameter easily allows to adjust the
7053     volume of all intruments within a custom instrument map
7054     without having to adjust their instrument files. The
7055     OPTIONAL &lt;instr_load_mode&gt; argument defines the life
7056     time of the instrument, that is when the instrument should
7057     be loaded, when freed and has exactly the following
7058     possibilities:
7059     </p>
7060     <p>
7061     </p>
7062     <blockquote class="text">
7063     <p>"ON_DEMAND" -
7064     </p>
7065     <blockquote class="text">
7066     <p>The instrument will be loaded when needed,
7067     that is when demanded by at least one sampler
7068     channel. It will immediately be freed from memory
7069     when not needed by any sampler channel anymore.
7070     </p>
7071     </blockquote>
7072    
7073    
7074     <p>"ON_DEMAND_HOLD" -
7075     </p>
7076     <blockquote class="text">
7077     <p>The instrument will be loaded when needed,
7078     that is when demanded by at least one sampler
7079     channel. It will be kept in memory even when
7080     not needed by any sampler channel anymore.
7081     Instruments with this mode are only freed
7082     when the sampler is reset or all mapping
7083     entries with this mode (and respective
7084     instrument) are explicitly changed to
7085     "ON_DEMAND" and no sampler channel is using
7086     the instrument anymore.
7087     </p>
7088     </blockquote>
7089    
7090    
7091     <p>"PERSISTENT" -
7092     </p>
7093     <blockquote class="text">
7094     <p>The instrument will immediately be loaded
7095 schoenebeck 1048 into memory when this mapping
7096 schoenebeck 945 command is sent and the instrument is kept all
7097     the time. Instruments with this mode are
7098     only freed when the sampler is reset or all
7099     mapping entries with this mode (and
7100     respective instrument) are explicitly
7101     changed to "ON_DEMAND" and no sampler
7102     channel is using the instrument anymore.
7103     </p>
7104     </blockquote>
7105    
7106    
7107     <p>not supplied -
7108     </p>
7109     <blockquote class="text">
7110     <p>In case there is no &lt;instr_load_mode&gt;
7111     argument given, it will be up to the
7112     InstrumentManager to decide which mode to use.
7113     Usually it will use "ON_DEMAND" if an entry
7114     for the given instrument does not exist in
7115     the InstrumentManager's list yet, otherwise
7116     if an entry already exists, it will simply
7117     stick with the mode currently reflected by
7118     the already existing entry, that is it will
7119     not change the mode.
7120     </p>
7121     </blockquote>
7122    
7123    
7124     </blockquote><p>
7125    
7126     </p>
7127     <p>
7128     The &lt;instr_load_mode&gt; argument thus allows to define an
7129     appropriate strategy (low memory consumption vs. fast
7130     instrument switching) for each instrument individually. Note, the
7131     following restrictions apply to this argument: "ON_DEMAND_HOLD" and
7132     "PERSISTENT" have to be supported by the respective sampler engine
7133     (which is technically the case when the engine provides an
7134     InstrumentManager for its format). If this is not the case the
7135     argument will automatically fall back to the default value
7136     "ON_DEMAND". Also the load mode of one instrument may
7137     automatically change the laod mode of other instrument(s), i.e.
7138     because the instruments are part of the same file and the
7139     engine does not allow a way to manage load modes for them
7140     individually. Due to this, in case the frontend shows the
7141     load modes of entries, the frontend should retrieve the actual
7142     mode by i.e. sending
7143 schoenebeck 974 <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>
7144 schoenebeck 1390 command(s). Finally the OPTIONAL &lt;name&gt; argument allows to set a custom name
7145     (encapsulated into apostrophes, supporting escape sequences as described in chapter
7146     "<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
7147     mapping entry, useful for frontends for displaying an appropriate name for
7148 schoenebeck 945 mapped instruments (using
7149 schoenebeck 974 <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>).
7150 schoenebeck 945
7151     </p>
7152     <p>
7153 schoenebeck 1048 By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is
7154     completely established in the sampler. The OPTIONAL "NON_MODAL" argument
7155     however causes the respective "MAP MIDI_INSTRUMENT" command to return
7156     immediately, that is to let the sampler establish the mapping in the
7157     background. So this argument might be especially useful for mappings with
7158     a "PERSISTENT" type, because these have to load the respective instruments
7159     immediately and might thus block for a very long time. It is recommended
7160     however to use the OPTIONAL "NON_MODAL" argument only if really necessary,
7161     because it has the following drawbacks: as "NON_MODAL" instructions return
7162     immediately, they may not necessarily return an error i.e. when the given
7163     instrument file turns out to be corrupt, beside that subsequent commands
7164     in a LSCP instruction sequence might fail, because mandatory mappings are
7165     not yet completed.
7166 schoenebeck 945
7167     </p>
7168     <p>Possible Answers:
7169     </p>
7170     <p>
7171     </p>
7172     <blockquote class="text">
7173     <p>"OK" -
7174     </p>
7175     <blockquote class="text">
7176     <p>usually
7177     </p>
7178     </blockquote>
7179    
7180    
7181     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7182     </p>
7183     <blockquote class="text">
7184 schoenebeck 974 <p>when the given map or engine does not exist or a value
7185 schoenebeck 945 is out of range
7186     </p>
7187     </blockquote>
7188    
7189    
7190     </blockquote><p>
7191    
7192     </p>
7193     <p>Examples:
7194     </p>
7195     <p>
7196     </p>
7197     <blockquote class="text">
7198 schoenebeck 974 <p>C: "MAP MIDI_INSTRUMENT 0 3 0 gig '/usr/share/Steinway D.gig' 0 0.8 PERSISTENT"
7199 schoenebeck 945 </p>
7200     <p>S: "OK"
7201     </p>
7202     </blockquote><p>
7203    
7204     </p>
7205     <p>
7206     </p>
7207     <blockquote class="text">
7208 schoenebeck 974 <p>C: "MAP MIDI_INSTRUMENT 0 4 50 gig '/home/john/foostrings.gig' 7 1.0"
7209 schoenebeck 945 </p>
7210     <p>S: "OK"
7211     </p>
7212     </blockquote><p>
7213    
7214     </p>
7215     <p>
7216     </p>
7217     <blockquote class="text">
7218     <p>C: "MAP MIDI_INSTRUMENT 0 0 0 gig '/usr/share/piano.gig' 0 1.0 'Normal Piano'"
7219     </p>
7220     <p>S: "OK"
7221     </p>
7222 schoenebeck 974 <p>C: "MAP MIDI_INSTRUMENT 0 1 0 gig '/usr/share/piano.gig' 0 0.25 'Silent Piano'"
7223 schoenebeck 945 </p>
7224     <p>S: "OK"
7225     </p>
7226     </blockquote><p>
7227    
7228     </p>
7229     <p>
7230     </p>
7231     <blockquote class="text">
7232 schoenebeck 1048 <p>C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"
7233 schoenebeck 945 </p>
7234     <p>S: "OK"
7235     </p>
7236     </blockquote><p>
7237    
7238     </p>
7239     <a name="GET MIDI_INSTRUMENTS"></a><br /><hr />
7240 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7241     <a name="rfc.section.6.7.8"></a><h3>6.7.8.&nbsp;
7242     Getting ammount of MIDI instrument map entries</h3>
7243 schoenebeck 945
7244 schoenebeck 974 <p>The front-end can query the amount of currently existing
7245     entries in a MIDI instrument map by sending the following
7246 schoenebeck 945 command:
7247     </p>
7248     <p>
7249     </p>
7250     <blockquote class="text">
7251 schoenebeck 974 <p>GET MIDI_INSTRUMENTS &lt;map&gt;
7252 schoenebeck 945 </p>
7253     </blockquote><p>
7254    
7255     </p>
7256 schoenebeck 974 <p>The front-end can query the amount of currently existing
7257     entries in all MIDI instrument maps by sending the following
7258     command:
7259     </p>
7260     <p>
7261     </p>
7262     <blockquote class="text">
7263     <p>GET MIDI_INSTRUMENTS ALL
7264     </p>
7265     </blockquote><p>
7266    
7267     </p>
7268 schoenebeck 945 <p>Possible Answers:
7269     </p>
7270     <p>
7271     </p>
7272     <blockquote class="text">
7273 schoenebeck 974 <p>The sampler will answer by sending the current number of
7274     entries in the MIDI instrument map(s).
7275 schoenebeck 945 </p>
7276     </blockquote><p>
7277    
7278     </p>
7279     <p>Example:
7280     </p>
7281     <p>
7282     </p>
7283     <blockquote class="text">
7284 schoenebeck 974 <p>C: "GET MIDI_INSTRUMENTS 0"
7285 schoenebeck 945 </p>
7286 schoenebeck 974 <p>S: "234"
7287 schoenebeck 945 </p>
7288     </blockquote><p>
7289    
7290     </p>
7291 schoenebeck 974 <p>
7292     </p>
7293     <blockquote class="text">
7294     <p>C: "GET MIDI_INSTRUMENTS ALL"
7295     </p>
7296     <p>S: "954"
7297     </p>
7298     </blockquote><p>
7299    
7300     </p>
7301 schoenebeck 945 <a name="LIST MIDI_INSTRUMENTS"></a><br /><hr />
7302 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7303     <a name="rfc.section.6.7.9"></a><h3>6.7.9.&nbsp;
7304     Getting indeces of all entries of a MIDI instrument map</h3>
7305 schoenebeck 945
7306 schoenebeck 974 <p>The front-end can query a list of all currently existing
7307     entries in a certain MIDI instrument map by sending the following
7308     command:
7309 schoenebeck 945 </p>
7310     <p>
7311     </p>
7312     <blockquote class="text">
7313 schoenebeck 974 <p>LIST MIDI_INSTRUMENTS &lt;map&gt;
7314 schoenebeck 945 </p>
7315     </blockquote><p>
7316    
7317     </p>
7318 schoenebeck 974 <p>Where &lt;map&gt; is the numeric ID of the MIDI instrument map.
7319     </p>
7320     <p>The front-end can query a list of all currently existing
7321     entries of all MIDI instrument maps by sending the following
7322     command:
7323     </p>
7324     <p>
7325     </p>
7326     <blockquote class="text">
7327     <p>LIST MIDI_INSTRUMENTS ALL
7328     </p>
7329     </blockquote><p>
7330    
7331     </p>
7332 schoenebeck 945 <p>Possible Answers:
7333     </p>
7334     <p>
7335     </p>
7336     <blockquote class="text">
7337 schoenebeck 974 <p>The sampler will answer by sending a comma separated
7338     list of map ID - MIDI bank - MIDI program triples, where
7339     each triple is encapsulated into curly braces. The
7340     list is returned in one single line. Each triple
7341     just reflects the key of the respective map entry,
7342     thus subsequent
7343     <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>
7344 schoenebeck 945 command(s) are necessary to retrieve detailed informations
7345     about each entry.
7346     </p>
7347     </blockquote><p>
7348    
7349     </p>
7350     <p>Example:
7351     </p>
7352     <p>
7353     </p>
7354     <blockquote class="text">
7355 schoenebeck 974 <p>C: "LIST MIDI_INSTRUMENTS 0"
7356 schoenebeck 945 </p>
7357 schoenebeck 974 <p>S: "{0,0,0},{0,0,1},{0,0,3},{0,1,4},{1,127,127}"
7358 schoenebeck 945 </p>
7359     </blockquote><p>
7360    
7361     </p>
7362     <a name="UNMAP MIDI_INSTRUMENT"></a><br /><hr />
7363 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7364     <a name="rfc.section.6.7.10"></a><h3>6.7.10.&nbsp;
7365     Remove an entry from the MIDI instrument map</h3>
7366 schoenebeck 945
7367 schoenebeck 974 <p>The front-end can delete an entry from a MIDI instrument
7368 schoenebeck 945 map by sending the following command:
7369     </p>
7370     <p>
7371     </p>
7372     <blockquote class="text">
7373 schoenebeck 974 <p>UNMAP MIDI_INSTRUMENT &lt;map&gt; &lt;midi_bank&gt; &lt;midi_prog&gt;
7374 schoenebeck 945 </p>
7375     </blockquote><p>
7376    
7377     </p>
7378     <p>
7379 schoenebeck 974 Where &lt;map&gt; is the numeric ID of the MIDI instrument map,
7380     &lt;midi_bank&gt; is an integer value between 0..16383
7381     reflecting the MIDI bank value and
7382     &lt;midi_prog&gt; an integer value between
7383     0..127 reflecting the MIDI program value of the map's entrie's key
7384 schoenebeck 945 index triple.
7385    
7386     </p>
7387     <p>Possible Answers:
7388     </p>
7389     <p>
7390     </p>
7391     <blockquote class="text">
7392     <p>"OK" -
7393     </p>
7394     <blockquote class="text">
7395     <p>usually
7396     </p>
7397     </blockquote>
7398    
7399    
7400     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7401     </p>
7402     <blockquote class="text">
7403     <p>when index out of bounds
7404     </p>
7405     </blockquote>
7406    
7407    
7408     </blockquote><p>
7409    
7410     </p>
7411     <p>Example:
7412     </p>
7413     <p>
7414     </p>
7415     <blockquote class="text">
7416 schoenebeck 974 <p>C: "UNMAP MIDI_INSTRUMENT 0 2 127"
7417 schoenebeck 945 </p>
7418     <p>S: "OK"
7419     </p>
7420     </blockquote><p>
7421    
7422     </p>
7423     <a name="GET MIDI_INSTRUMENT INFO"></a><br /><hr />
7424 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7425     <a name="rfc.section.6.7.11"></a><h3>6.7.11.&nbsp;
7426     Get current settings of MIDI instrument map entry</h3>
7427 schoenebeck 945
7428     <p>The front-end can retrieve the current settings of a certain
7429     instrument map entry by sending the following command:
7430     </p>
7431     <p>
7432     </p>
7433     <blockquote class="text">
7434 schoenebeck 974 <p>GET MIDI_INSTRUMENT INFO &lt;map&gt; &lt;midi_bank&gt; &lt;midi_prog&gt;
7435 schoenebeck 945 </p>
7436     </blockquote><p>
7437    
7438     </p>
7439     <p>
7440 schoenebeck 974 Where &lt;map&gt; is the numeric ID of the MIDI instrument map,
7441     &lt;midi_bank&gt; is an integer value between 0..16383
7442     reflecting the MIDI bank value, &lt;midi_bank&gt;
7443     and &lt;midi_prog&gt; an integer value between
7444     0..127 reflecting the MIDI program value of the map's entrie's key
7445 schoenebeck 945 index triple.
7446    
7447     </p>
7448     <p>Possible Answers:
7449     </p>
7450     <p>
7451     </p>
7452     <blockquote class="text">
7453     <p>LinuxSampler will answer by sending a &lt;CRLF&gt;
7454     separated list. Each answer line begins with the
7455     information category name followed by a colon and then
7456     a space character &lt;SP&gt; and finally the info
7457     character string to that info category. At the moment
7458     the following categories are defined:
7459     </p>
7460     <p>"NAME" -
7461     </p>
7462     <blockquote class="text">
7463     <p>Name for this MIDI instrument map entry (if defined).
7464     This name shall be used by frontends for displaying a
7465     name for this mapped instrument. It can be set and
7466     changed with the
7467 schoenebeck 974 <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>
7468 schoenebeck 945 command and does not have to be unique.
7469 schoenebeck 1400 (note that this character string may contain
7470     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>)
7471 schoenebeck 945 </p>
7472     </blockquote>
7473    
7474    
7475     <p>"ENGINE_NAME" -
7476     </p>
7477     <blockquote class="text">
7478     <p>Name of the engine to be deployed for this
7479     instrument.
7480     </p>
7481     </blockquote>
7482    
7483    
7484     <p>"INSTRUMENT_FILE" -
7485     </p>
7486     <blockquote class="text">
7487 schoenebeck 1400 <p>File name of the instrument
7488     (note that this path may contain
7489     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>).
7490 schoenebeck 945 </p>
7491     </blockquote>
7492    
7493    
7494     <p>"INSTRUMENT_NR" -
7495     </p>
7496     <blockquote class="text">
7497     <p>Index of the instrument within the file.
7498     </p>
7499     </blockquote>
7500    
7501    
7502     <p>"INSTRUMENT_NAME" -
7503     </p>
7504     <blockquote class="text">
7505     <p>Name of the loaded instrument as reflected by its file.
7506     In contrast to the "NAME" field, the "INSTRUMENT_NAME" field
7507 schoenebeck 1400 cannot be changed (note that this character string may contain
7508     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>).
7509 schoenebeck 945 </p>
7510     </blockquote>
7511    
7512    
7513     <p>"LOAD_MODE" -
7514     </p>
7515     <blockquote class="text">
7516     <p>Life time of instrument
7517 schoenebeck 974 (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).
7518 schoenebeck 945 </p>
7519     </blockquote>
7520    
7521    
7522     <p>"VOLUME" -
7523     </p>
7524     <blockquote class="text">
7525     <p>master volume of the instrument as optionally
7526 schoenebeck 1028 dotted number (where a value &lt; 1.0 means attenuation
7527 schoenebeck 945 and a value > 1.0 means amplification)
7528     </p>
7529     </blockquote>
7530    
7531    
7532     <p>The mentioned fields above don't have to be in particular order.
7533     </p>
7534     </blockquote><p>
7535    
7536     </p>
7537     <p>Example:
7538     </p>
7539     <p>
7540     </p>
7541     <blockquote class="text">
7542 schoenebeck 974 <p>C: "GET MIDI_INSTRUMENT INFO 1 45 120"
7543 schoenebeck 945 </p>
7544     <p>S: "NAME: Drums for Foo Song"
7545     </p>
7546     <p>&nbsp;&nbsp;&nbsp;"ENGINE_NAME: GigEngine"
7547     </p>
7548     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_FILE: /usr/share/joesdrumkit.gig"
7549     </p>
7550     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"
7551     </p>
7552     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NAME: Joe's Drumkit"
7553     </p>
7554     <p>&nbsp;&nbsp;&nbsp;"LOAD_MODE: PERSISTENT"
7555     </p>
7556     <p>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"
7557     </p>
7558     <p>&nbsp;&nbsp;&nbsp;"."
7559     </p>
7560     </blockquote><p>
7561    
7562     </p>
7563     <a name="CLEAR MIDI_INSTRUMENTS"></a><br /><hr />
7564 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7565     <a name="rfc.section.6.7.12"></a><h3>6.7.12.&nbsp;
7566     Clear MIDI instrument map</h3>
7567 schoenebeck 945
7568 schoenebeck 974 <p>The front-end can clear a whole MIDI instrument map, that
7569     is delete all its entries by sending the following command:
7570 schoenebeck 945 </p>
7571     <p>
7572     </p>
7573     <blockquote class="text">
7574 schoenebeck 974 <p>CLEAR MIDI_INSTRUMENTS &lt;map&gt;
7575 schoenebeck 945 </p>
7576     </blockquote><p>
7577    
7578     </p>
7579 schoenebeck 974 <p>Where &lt;map&gt; is the numeric ID of the map to clear.
7580     </p>
7581     <p>The front-end can clear all MIDI instrument maps, that
7582     is delete all entries of all maps by sending the following
7583     command:
7584     </p>
7585     <p>
7586     </p>
7587     <blockquote class="text">
7588     <p>CLEAR MIDI_INSTRUMENTS ALL
7589     </p>
7590     </blockquote><p>
7591    
7592     </p>
7593     <p>The command "CLEAR MIDI_INSTRUMENTS ALL" does not delete the
7594     maps, only their entries, thus the map's settings like
7595     custom name will be preservevd.
7596     </p>
7597 schoenebeck 945 <p>Possible Answers:
7598     </p>
7599     <p>
7600     </p>
7601     <blockquote class="text">
7602     <p>"OK" -
7603     </p>
7604     <blockquote class="text">
7605     <p>always
7606     </p>
7607     </blockquote>
7608    
7609    
7610     </blockquote><p>
7611    
7612     </p>
7613 schoenebeck 974 <p>Examples:
7614 schoenebeck 945 </p>
7615     <p>
7616     </p>
7617     <blockquote class="text">
7618 schoenebeck 974 <p>C: "CLEAR MIDI_INSTRUMENTS 0"
7619 schoenebeck 945 </p>
7620     <p>S: "OK"
7621     </p>
7622     </blockquote><p>
7623    
7624     </p>
7625 schoenebeck 974 <p>
7626     </p>
7627     <blockquote class="text">
7628     <p>C: "CLEAR MIDI_INSTRUMENTS ALL"
7629     </p>
7630     <p>S: "OK"
7631     </p>
7632     </blockquote><p>
7633    
7634     </p>
7635 iliev 1162 <a name="Managing Instruments Database"></a><br /><hr />
7636     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7637     <a name="rfc.section.6.8"></a><h3>6.8.&nbsp;
7638     Managing Instruments Database</h3>
7639    
7640     <p>The following commands describe how to use and manage
7641     the instruments database.
7642     </p>
7643 schoenebeck 1363 <p>Notice:
7644     </p>
7645     <p>
7646     </p>
7647     <blockquote class="text">
7648     <p>All command arguments representing a path or
7649     instrument/directory name support escape sequences as described in chapter
7650     "<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>".
7651    
7652     </p>
7653     <p>All occurrences of a forward slash in instrument and directory
7654     names are escaped with its hex (\x2f) or octal (\057) escape sequence.
7655    
7656     </p>
7657     </blockquote><p>
7658    
7659     </p>
7660 iliev 1162 <a name="ADD DB_INSTRUMENT_DIRECTORY"></a><br /><hr />
7661     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7662     <a name="rfc.section.6.8.1"></a><h3>6.8.1.&nbsp;
7663     Creating a new instrument directory</h3>
7664    
7665     <p>The front-end can add a new instrument directory to the
7666     instruments database by sending the following command:
7667     </p>
7668     <p>
7669     </p>
7670     <blockquote class="text">
7671     <p>ADD DB_INSTRUMENT_DIRECTORY &lt;dir&gt;
7672     </p>
7673     </blockquote><p>
7674    
7675     </p>
7676     <p>Where &lt;dir&gt; is the absolute path name of the directory
7677     to be created (encapsulated into apostrophes).
7678     </p>
7679     <p>Possible Answers:
7680     </p>
7681     <p>
7682     </p>
7683     <blockquote class="text">
7684     <p>"OK" -
7685     </p>
7686     <blockquote class="text">
7687     <p>on success
7688     </p>
7689     </blockquote>
7690    
7691    
7692     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7693     </p>
7694     <blockquote class="text">
7695     <p>when the directory could not be created, which
7696     can happen if the directory already exists or the
7697     name contains not allowed symbols
7698     </p>
7699     </blockquote>
7700    
7701    
7702     </blockquote><p>
7703    
7704     </p>
7705     <p>Examples:
7706     </p>
7707     <p>
7708     </p>
7709     <blockquote class="text">
7710     <p>C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'"
7711     </p>
7712     <p>S: "OK"
7713     </p>
7714     </blockquote><p>
7715    
7716     </p>
7717     <a name="REMOVE DB_INSTRUMENT_DIRECTORY"></a><br /><hr />
7718     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7719     <a name="rfc.section.6.8.2"></a><h3>6.8.2.&nbsp;
7720     Deleting an instrument directory</h3>
7721    
7722     <p>The front-end can delete a particular instrument directory
7723     from the instruments database by sending the following command:
7724     </p>
7725     <p>
7726     </p>
7727     <blockquote class="text">
7728     <p>REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] &lt;dir&gt;
7729     </p>
7730     </blockquote><p>
7731    
7732     </p>
7733     <p>Where &lt;dir&gt; is the absolute path name of the directory
7734     to delete. The optional FORCE argument can be used to
7735     force the deletion of a non-empty directory and all its content.
7736     </p>
7737     <p>Possible Answers:
7738     </p>
7739     <p>
7740     </p>
7741     <blockquote class="text">
7742     <p>"OK" -
7743     </p>
7744     <blockquote class="text">
7745     <p>if the directory is deleted successfully
7746     </p>
7747     </blockquote>
7748    
7749    
7750     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7751     </p>
7752     <blockquote class="text">
7753     <p>if the given directory does not exist, or
7754     if trying to delete a non-empty directory,
7755     without using the FORCE argument.
7756     </p>
7757     </blockquote>
7758    
7759    
7760     </blockquote><p>
7761    
7762     </p>
7763     <p>Examples:
7764     </p>
7765     <p>
7766     </p>
7767     <blockquote class="text">
7768     <p>C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'"
7769     </p>
7770     <p>S: "OK"
7771     </p>
7772     </blockquote><p>
7773    
7774     </p>
7775     <a name="GET DB_INSTRUMENT_DIRECTORIES"></a><br /><hr />
7776     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7777     <a name="rfc.section.6.8.3"></a><h3>6.8.3.&nbsp;
7778     Getting amount of instrument directories</h3>
7779    
7780     <p>The front-end can retrieve the current amount of
7781     directories in a specific directory by sending the following command:
7782     </p>
7783     <p>
7784     </p>
7785     <blockquote class="text">
7786 iliev 1189 <p>GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;
7787 iliev 1162 </p>
7788     </blockquote><p>
7789    
7790     </p>
7791     <p>Where &lt;dir&gt; should be replaced by the absolute path
7792 iliev 1189 name of the directory. If RECURSIVE is specified, the number of
7793     all directories, including those located in subdirectories of the
7794     specified directory, will be returned.
7795 iliev 1162 </p>
7796     <p>Possible Answers:
7797     </p>
7798     <p>
7799     </p>
7800     <blockquote class="text">
7801     <p>The current number of instrument directories
7802     in the specified directory.
7803     </p>
7804     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7805     </p>
7806     <blockquote class="text">
7807     <p>if the given directory does not exist.
7808     </p>
7809     </blockquote>
7810    
7811    
7812     </blockquote><p>
7813    
7814     </p>
7815     <p>Example:
7816     </p>
7817     <p>
7818     </p>
7819     <blockquote class="text">
7820     <p>C: "GET DB_INSTRUMENT_DIRECTORIES '/'"
7821     </p>
7822     <p>S: "2"
7823     </p>
7824     </blockquote><p>
7825    
7826     </p>
7827     <a name="LIST DB_INSTRUMENT_DIRECTORIES"></a><br /><hr />
7828     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7829     <a name="rfc.section.6.8.4"></a><h3>6.8.4.&nbsp;
7830     Listing all directories in specific directory</h3>
7831    
7832     <p>The front-end can retrieve the current list of directories
7833     in specific directory by sending the following command:
7834     </p>
7835     <p>
7836     </p>
7837     <blockquote class="text">
7838 iliev 1189 <p>LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;
7839 iliev 1162 </p>
7840     </blockquote><p>
7841    
7842     </p>
7843     <p>Where &lt;dir&gt; should be replaced by the absolute path
7844 iliev 1189 name of the directory. If RECURSIVE is specified, the absolute path names
7845     of all directories, including those located in subdirectories of the
7846     specified directory, will be returned.
7847 iliev 1162 </p>
7848     <p>Possible Answers:
7849     </p>
7850     <p>
7851     </p>
7852     <blockquote class="text">
7853     <p>A comma separated list of all instrument directories
7854     (encapsulated into apostrophes) in the specified directory.
7855     </p>
7856     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7857     </p>
7858     <blockquote class="text">
7859     <p>if the given directory does not exist.
7860     </p>
7861     </blockquote>
7862    
7863    
7864     </blockquote><p>
7865    
7866     </p>
7867     <p>Example:
7868     </p>
7869     <p>
7870     </p>
7871     <blockquote class="text">
7872     <p>C: "LIST DB_INSTRUMENT_DIRECTORIES '/'"
7873     </p>
7874     <p>S: "'Piano Collection','Percussion Collection'"
7875     </p>
7876     </blockquote><p>
7877    
7878     </p>
7879 iliev 1189 <p>
7880     </p>
7881     <blockquote class="text">
7882     <p>C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'"
7883     </p>
7884     <p>S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano Collection/Acoustic/New','/Percussion Collection'"
7885     </p>
7886     </blockquote><p>
7887    
7888     </p>
7889 iliev 1162 <a name="GET DB_INSTRUMENT_DIRECTORY INFO"></a><br /><hr />
7890     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7891     <a name="rfc.section.6.8.5"></a><h3>6.8.5.&nbsp;
7892     Getting instrument directory information</h3>
7893    
7894     <p>The front-end can ask for the current settings of an
7895     instrument directory by sending the following command:
7896     </p>
7897     <p>
7898     </p>
7899     <blockquote class="text">
7900     <p>GET DB_INSTRUMENT_DIRECTORY INFO &lt;dir&gt;
7901     </p>
7902     </blockquote><p>
7903    
7904     </p>
7905     <p>Where &lt;dir&gt; should be replaced by the absolute path
7906     name of the directory the front-end is interested in.
7907     </p>
7908     <p>Possible Answers:
7909     </p>
7910     <p>
7911     </p>
7912     <blockquote class="text">
7913     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
7914     Each answer line begins with the settings category name
7915     followed by a colon and then a space character &lt;SP&gt; and finally
7916     the info character string to that setting category. At the
7917     moment the following categories are defined:
7918     </p>
7919     <p>
7920     </p>
7921     <blockquote class="text">
7922     <p>DESCRIPTION -
7923     </p>
7924     <blockquote class="text">
7925 schoenebeck 1363 <p>A brief description of the directory content.
7926     Note that the character string may contain
7927     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
7928 iliev 1162 </p>
7929     </blockquote>
7930    
7931    
7932     <p>CREATED -
7933     </p>
7934     <blockquote class="text">
7935     <p>The creation date and time of the directory,
7936     represented in "YYYY-MM-DD HH:MM:SS" format
7937     </p>
7938     </blockquote>
7939    
7940    
7941     <p>MODIFIED -
7942     </p>
7943     <blockquote class="text">
7944     <p>The date and time of the last modification of the
7945     directory, represented in "YYYY-MM-DD HH:MM:SS" format
7946     </p>
7947     </blockquote>
7948    
7949    
7950     </blockquote>
7951    
7952    
7953     </blockquote><p>
7954    
7955     </p>
7956     <p>The mentioned fields above don't have to be in particular order.
7957     </p>
7958     <p>Example:
7959     </p>
7960     <p>
7961     </p>
7962     <blockquote class="text">
7963     <p>C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'"
7964     </p>
7965     <p>S: "DESCRIPTION: Piano collection of instruments in GigaSampler format."
7966     </p>
7967     <p>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"
7968     </p>
7969     <p>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"
7970     </p>
7971     <p>&nbsp;&nbsp;&nbsp;"."
7972     </p>
7973     </blockquote><p>
7974    
7975     </p>
7976     <a name="SET DB_INSTRUMENT_DIRECTORY NAME"></a><br /><hr />
7977     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7978     <a name="rfc.section.6.8.6"></a><h3>6.8.6.&nbsp;
7979     Renaming an instrument directory</h3>
7980    
7981     <p>The front-end can alter the name of a specific
7982     instrument directory by sending the following command:
7983     </p>
7984     <p>
7985     </p>
7986     <blockquote class="text">
7987     <p>SET DB_INSTRUMENT_DIRECTORY NAME &lt;dir&gt; &lt;name&gt;
7988     </p>
7989     </blockquote><p>
7990    
7991     </p>
7992     <p>Where &lt;dir&gt; is the absolute path name of the directory and
7993     &lt;name&gt; is the new name for that directory.
7994     </p>
7995     <p>Possible Answers:
7996     </p>
7997     <p>
7998     </p>
7999     <blockquote class="text">
8000     <p>"OK" -
8001     </p>
8002     <blockquote class="text">
8003     <p>on success
8004     </p>
8005     </blockquote>
8006    
8007    
8008     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8009     </p>
8010     <blockquote class="text">
8011     <p>in case the given directory does not exists,
8012     or if a directory with name equal to the new
8013     name already exists.
8014     </p>
8015     </blockquote>
8016    
8017    
8018     </blockquote><p>
8019    
8020     </p>
8021     <p>Example:
8022     </p>
8023     <p>
8024     </p>
8025     <blockquote class="text">
8026     <p>C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic' 'Acoustic'"
8027     </p>
8028     <p>S: "OK"
8029     </p>
8030     </blockquote><p>
8031    
8032     </p>
8033     <a name="MOVE DB_INSTRUMENT_DIRECTORY"></a><br /><hr />
8034     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8035     <a name="rfc.section.6.8.7"></a><h3>6.8.7.&nbsp;
8036     Moving an instrument directory</h3>
8037    
8038     <p>The front-end can move a specific
8039     instrument directory by sending the following command:
8040     </p>
8041     <p>
8042     </p>
8043     <blockquote class="text">
8044     <p>MOVE DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;
8045     </p>
8046     </blockquote><p>
8047    
8048     </p>
8049     <p>Where &lt;dir&gt; is the absolute path name of the directory
8050     to move and &lt;dst&gt; is the location where the directory will
8051     be moved to.
8052     </p>
8053     <p>Possible Answers:
8054     </p>
8055     <p>
8056     </p>
8057     <blockquote class="text">
8058     <p>"OK" -
8059     </p>
8060     <blockquote class="text">
8061     <p>on success
8062     </p>
8063     </blockquote>
8064    
8065    
8066     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8067     </p>
8068     <blockquote class="text">
8069     <p>in case a given directory does not exists,
8070     or if a directory with name equal to the name
8071     of the specified directory already exists in
8072     the destination directory. Error is also thrown
8073     when trying to move a directory to a subdirectory
8074     of itself.
8075     </p>
8076     </blockquote>
8077    
8078    
8079     </blockquote><p>
8080    
8081     </p>
8082     <p>Example:
8083     </p>
8084     <p>
8085     </p>
8086     <blockquote class="text">
8087     <p>C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/Acoustic'"
8088     </p>
8089     <p>S: "OK"
8090     </p>
8091     </blockquote><p>
8092    
8093     </p>
8094 iliev 1189 <a name="COPY DB_INSTRUMENT_DIRECTORY"></a><br /><hr />
8095     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8096     <a name="rfc.section.6.8.8"></a><h3>6.8.8.&nbsp;
8097     Copying instrument directories</h3>
8098    
8099     <p>The front-end can copy a specific
8100     instrument directory by sending the following command:
8101     </p>
8102     <p>
8103     </p>
8104     <blockquote class="text">
8105     <p>COPY DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;
8106     </p>
8107     </blockquote><p>
8108    
8109     </p>
8110     <p>Where &lt;dir&gt; is the absolute path name of the directory
8111     to copy and &lt;dst&gt; is the location where the directory will
8112     be copied to.
8113     </p>
8114     <p>Possible Answers:
8115     </p>
8116     <p>
8117     </p>
8118     <blockquote class="text">
8119     <p>"OK" -
8120     </p>
8121     <blockquote class="text">
8122     <p>on success
8123     </p>
8124     </blockquote>
8125    
8126    
8127     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8128     </p>
8129     <blockquote class="text">
8130     <p>in case a given directory does not exists,
8131     or if a directory with name equal to the name
8132     of the specified directory already exists in
8133     the destination directory. Error is also thrown
8134     when trying to copy a directory to a subdirectory
8135     of itself.
8136     </p>
8137     </blockquote>
8138    
8139    
8140     </blockquote><p>
8141    
8142     </p>
8143     <p>Example:
8144     </p>
8145     <p>
8146     </p>
8147     <blockquote class="text">
8148     <p>C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic' '/Acoustic/Pianos'"
8149     </p>
8150     <p>S: "OK"
8151     </p>
8152     </blockquote><p>
8153    
8154     </p>
8155 iliev 1162 <a name="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"></a><br /><hr />
8156     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8157 iliev 1189 <a name="rfc.section.6.8.9"></a><h3>6.8.9.&nbsp;
8158 iliev 1162 Changing the description of directory</h3>
8159    
8160     <p>The front-end can alter the description of a specific
8161     instrument directory by sending the following command:
8162     </p>
8163     <p>
8164     </p>
8165     <blockquote class="text">
8166     <p>SET DB_INSTRUMENT_DIRECTORY DESCRIPTION &lt;dir&gt; &lt;desc&gt;
8167     </p>
8168     </blockquote><p>
8169    
8170     </p>
8171     <p>Where &lt;dir&gt; is the absolute path name of the directory and
8172 schoenebeck 1363 &lt;desc&gt; is the new description for the directory
8173     (encapsulated into apostrophes, supporting escape sequences as described in chapter
8174     "<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>").
8175 iliev 1162 </p>
8176     <p>Possible Answers:
8177     </p>
8178     <p>
8179     </p>
8180     <blockquote class="text">
8181     <p>"OK" -
8182     </p>
8183     <blockquote class="text">
8184     <p>on success
8185     </p>
8186     </blockquote>
8187    
8188    
8189     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8190     </p>
8191     <blockquote class="text">
8192     <p>in case the given directory does not exists.
8193     </p>
8194     </blockquote>
8195    
8196    
8197     </blockquote><p>
8198    
8199     </p>
8200     <p>Example:
8201     </p>
8202     <p>
8203     </p>
8204     <blockquote class="text">
8205     <p>C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A collection of piano instruments in various format.'"
8206     </p>
8207     <p>S: "OK"
8208     </p>
8209     </blockquote><p>
8210    
8211     </p>
8212 iliev 1189 <a name="FIND DB_INSTRUMENT_DIRECTORIES"></a><br /><hr />
8213     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8214     <a name="rfc.section.6.8.10"></a><h3>6.8.10.&nbsp;
8215     Finding directories</h3>
8216    
8217     <p>The front-end can search for directories
8218     in specific directory by sending the following command:
8219     </p>
8220     <p>
8221     </p>
8222     <blockquote class="text">
8223     <p>FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;
8224     </p>
8225     </blockquote><p>
8226    
8227     </p>
8228     <p>Where &lt;dir&gt; should be replaced by the absolute path
8229     name of the directory to search in. If NON_RECURSIVE is specified, the
8230     directories located in subdirectories of the specified directory will not
8231     be searched. &lt;criteria-list&gt; is a list of search criterias
8232     in form of "key1=val1 key2=val2 ...". The following criterias are
8233     allowed:
8234     </p>
8235     <p>
8236    
8237     <p>NAME='&lt;search-string&gt;'
8238     </p>
8239     <blockquote class="text">
8240     <p>Restricts the search to directories, which names
8241 schoenebeck 1363 satisfy the supplied search string (encapsulated into apostrophes,
8242     supporting escape sequences as described in chapter
8243     "<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>").
8244 iliev 1189 </p>
8245     </blockquote><p>
8246    
8247     </p>
8248    
8249    
8250     <p>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
8251     </p>
8252     <blockquote class="text">
8253     <p>Restricts the search to directories, which creation
8254     date satisfies the specified period, where &lt;date-after&gt;
8255     and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
8256     If &lt;date-after&gt; is omitted the search is restricted to
8257     directories created before &lt;date-before&gt;. If
8258     &lt;date-before&gt; is omitted, the search is restricted
8259     to directories created after &lt;date-after&gt;.
8260     </p>
8261     </blockquote><p>
8262    
8263     </p>
8264    
8265    
8266     <p>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
8267     </p>
8268     <blockquote class="text">
8269     <p>Restricts the search to directories, which
8270     date of last modification satisfies the specified period, where
8271     &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
8272     format. If &lt;date-after&gt; is omitted the search is restricted to
8273     directories, which are last modified before &lt;date-before&gt;. If
8274     &lt;date-before&gt; is omitted, the search is restricted to directories,
8275     which are last modified after &lt;date-after&gt;.
8276     </p>
8277     </blockquote><p>
8278    
8279     </p>
8280    
8281    
8282     <p>DESCRIPTION='&lt;search-string&gt;'
8283     </p>
8284     <blockquote class="text">
8285     <p>Restricts the search to directories with description
8286 schoenebeck 1363 that satisfies the supplied search string
8287     (encapsulated into apostrophes, supporting escape
8288     sequences as described in chapter
8289     "<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>").
8290 iliev 1189 </p>
8291     </blockquote><p>
8292    
8293     </p>
8294    
8295    
8296     <p>Where &lt;search-string&gt; is either a regular expression, or a
8297     word list separated with spaces for OR search and with '+' for AND search.
8298     </p>
8299     <p>Possible Answers:
8300     </p>
8301     <p>
8302     </p>
8303     <blockquote class="text">
8304     <p>A comma separated list with the absolute path names (encapsulated into
8305     apostrophes) of all directories in the specified directory that satisfy
8306     the supplied search criterias.
8307     </p>
8308     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8309     </p>
8310     <blockquote class="text">
8311     <p>if the given directory does not exist.
8312     </p>
8313     </blockquote>
8314    
8315    
8316     </blockquote><p>
8317    
8318     </p>
8319     <p>Example:
8320     </p>
8321     <p>
8322     </p>
8323     <blockquote class="text">
8324     <p>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'"
8325     </p>
8326     <p>S: "'/Piano Collection'"
8327     </p>
8328     </blockquote><p>
8329    
8330     </p>
8331     <p>
8332     </p>
8333     <blockquote class="text">
8334     <p>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:30:13'"
8335     </p>
8336     <p>S: "'/Piano Collection','/Percussions'"
8337     </p>
8338     </blockquote><p>
8339    
8340     </p>
8341 iliev 1162 <a name="ADD DB_INSTRUMENTS"></a><br /><hr />
8342     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8343 iliev 1189 <a name="rfc.section.6.8.11"></a><h3>6.8.11.&nbsp;
8344 iliev 1162 Adding instruments to the instruments database</h3>
8345    
8346     <p>The front-end can add one or more instruments
8347     to the instruments database by sending the following command:
8348     </p>
8349     <p>
8350     </p>
8351     <blockquote class="text">
8352 schoenebeck 1801 <p>ADD DB_INSTRUMENTS [NON_MODAL] [&lt;mode&gt;[ FILE_AS_DIR]] &lt;db_dir&gt; &lt;file_path&gt; [&lt;instr_index&gt;]
8353 iliev 1162 </p>
8354     </blockquote><p>
8355    
8356     </p>
8357     <p>Where &lt;db_dir&gt; is the absolute path name of a directory
8358     (encapsulated into apostrophes) in the instruments database in which
8359     only the new instruments (that are not already in the database) will
8360     be added, &lt;file_path&gt; is the absolute path name of a file or
8361     directory in the file system (encapsulated into apostrophes). In case
8362     an instrument file is supplied, only the instruments in the specified
8363     file will be added to the instruments database. If the optional
8364     &lt;instr_index&gt; (the index of the instrument within the given file)
8365     is supplied too, then only the specified instrument will be added.
8366     In case a directory is supplied, the instruments in that directory
8367     will be added. The OPTIONAL &lt;mode&gt; argument is only applied
8368     when a directory is provided as &lt;file_path&gt; and specifies how the
8369     scanning will be done and has exactly the following possibilities:
8370     </p>
8371     <p>
8372     </p>
8373     <blockquote class="text">
8374 iliev 1201 <p>"RECURSIVE" -
8375     </p>
8376     <blockquote class="text">
8377     <p>All instruments will be processed, including those
8378     in the subdirectories, and the respective subdirectory
8379     tree structure will be recreated in the instruments
8380     database
8381     </p>
8382     </blockquote>
8383    
8384    
8385 iliev 1162 <p>"NON_RECURSIVE" -
8386     </p>
8387     <blockquote class="text">
8388     <p>Only the instruments in the specified directory
8389     will be added, the instruments in the subdirectories
8390     will not be processed.
8391     </p>
8392     </blockquote>
8393    
8394    
8395     <p>"FLAT" -
8396     </p>
8397     <blockquote class="text">
8398     <p>All instruments will be processed, including those
8399     in the subdirectories, but the respective subdirectory
8400     structure will not be recreated in the instruments
8401     database. All instruments will be added directly in
8402     the specified database directory.
8403     </p>
8404     </blockquote>
8405    
8406    
8407     </blockquote><p>
8408    
8409     </p>
8410 schoenebeck 1801 <p> If FILE_AS_DIR argument is supplied, all instruments in an instrument
8411     file will be added to a separate directory in the instruments database, which
8412     name will be the name of the instrument file with the file extension stripped off.
8413    
8414     </p>
8415 iliev 1201 <p>The difference between regular and NON_MODAL versions of the command
8416     is that the regular command returns when the scanning is finished
8417     while NON_MODAL version returns immediately and a background process is launched.
8418     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>
8419     command can be used to monitor the scanning progress.
8420     </p>
8421 iliev 1162 <p>Possible Answers:
8422     </p>
8423     <p>
8424     </p>
8425     <blockquote class="text">
8426     <p>"OK" -
8427     </p>
8428     <blockquote class="text">
8429 iliev 1201 <p>on success when NON_MODAL is not supplied
8430 iliev 1162 </p>
8431     </blockquote>
8432    
8433    
8434 iliev 1201 <p>"OK[&lt;job-id&gt;]" -
8435     </p>
8436     <blockquote class="text">
8437     <p>on success when NON_MODAL is supplied, where &lt;job-id&gt;
8438     is a numerical ID used to obtain status information about the job progress.
8439     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>
8440    
8441     </p>
8442     </blockquote>
8443    
8444    
8445 iliev 1162 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8446     </p>
8447     <blockquote class="text">
8448     <p>if an invalid path is specified.
8449     </p>
8450     </blockquote>
8451    
8452    
8453     </blockquote><p>
8454    
8455     </p>
8456     <p>Examples:
8457     </p>
8458     <p>
8459     </p>
8460     <blockquote class="text">
8461     <p>C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI Bosendorfer 290.gig' 0"
8462     </p>
8463     <p>S: "OK"
8464     </p>
8465     </blockquote><p>
8466    
8467     </p>
8468     <a name="REMOVE DB_INSTRUMENT"></a><br /><hr />
8469     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8470 iliev 1189 <a name="rfc.section.6.8.12"></a><h3>6.8.12.&nbsp;
8471 iliev 1162 Removing an instrument</h3>
8472    
8473     <p>The front-end can remove a particular instrument
8474     from the instruments database by sending the following command:
8475     </p>
8476     <p>
8477     </p>
8478     <blockquote class="text">
8479     <p>REMOVE DB_INSTRUMENT &lt;instr_path&gt;
8480     </p>
8481     </blockquote><p>
8482    
8483     </p>
8484     <p>Where &lt;instr_path&gt; is the absolute path name
8485     (in the instruments database) of the instrument to remove.
8486     </p>
8487     <p>Possible Answers:
8488     </p>
8489     <p>
8490     </p>
8491     <blockquote class="text">
8492     <p>"OK" -
8493     </p>
8494     <blockquote class="text">
8495     <p>if the instrument is removed successfully
8496     </p>
8497     </blockquote>
8498    
8499    
8500     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8501     </p>
8502     <blockquote class="text">
8503     <p>if the given path does not exist or
8504     is a directory.
8505     </p>
8506     </blockquote>
8507    
8508    
8509     </blockquote><p>
8510    
8511     </p>
8512     <p>Examples:
8513     </p>
8514     <p>
8515     </p>
8516     <blockquote class="text">
8517     <p>C: "REMOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'"
8518     </p>
8519     <p>S: "OK"
8520     </p>
8521     </blockquote><p>
8522    
8523     </p>
8524     <a name="GET DB_INSTRUMENTS"></a><br /><hr />
8525     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8526 iliev 1189 <a name="rfc.section.6.8.13"></a><h3>6.8.13.&nbsp;
8527 iliev 1162 Getting amount of instruments</h3>
8528    
8529     <p>The front-end can retrieve the current amount of
8530     instruments in a specific directory by sending the following command:
8531     </p>
8532     <p>
8533     </p>
8534     <blockquote class="text">
8535 iliev 1189 <p>GET DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;
8536 iliev 1162 </p>
8537     </blockquote><p>
8538    
8539     </p>
8540     <p>Where &lt;dir&gt; should be replaced by the absolute path name
8541 iliev 1189 of the directory. If RECURSIVE is specified, the number of all
8542     instruments, including those located in subdirectories of the
8543     specified directory, will be returned.
8544 iliev 1162 </p>
8545     <p>Possible Answers:
8546     </p>
8547     <p>
8548     </p>
8549     <blockquote class="text">
8550     <p>The current number of instruments
8551     in the specified directory.
8552     </p>
8553     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8554     </p>
8555     <blockquote class="text">
8556     <p>if the given directory does not exist.
8557     </p>
8558     </blockquote>
8559    
8560    
8561     </blockquote><p>
8562    
8563     </p>
8564     <p>Example:
8565     </p>
8566     <p>
8567     </p>
8568     <blockquote class="text">
8569     <p>C: "GET DB_INSTRUMENTS '/Piano Collection'"
8570     </p>
8571     <p>S: "2"
8572     </p>
8573     </blockquote><p>
8574    
8575     </p>
8576     <a name="LIST DB_INSTRUMENTS"></a><br /><hr />
8577     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8578 iliev 1189 <a name="rfc.section.6.8.14"></a><h3>6.8.14.&nbsp;
8579 iliev 1162 Listing all instruments in specific directory</h3>
8580    
8581     <p>The front-end can retrieve the current list of instruments
8582     in specific directory by sending the following command:
8583     </p>
8584     <p>
8585     </p>
8586     <blockquote class="text">
8587 iliev 1189 <p>LIST DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;
8588 iliev 1162 </p>
8589     </blockquote><p>
8590    
8591     </p>
8592     <p>Where &lt;dir&gt; should be replaced by the absolute path
8593 iliev 1189 name of the directory. If RECURSIVE is specified, the absolute path
8594     names of all instruments, including those located in subdirectories
8595     of the specified directory, will be returned.
8596 iliev 1162 </p>
8597     <p>Possible Answers:
8598     </p>
8599     <p>
8600     </p>
8601     <blockquote class="text">
8602     <p>A comma separated list of all instruments
8603     (encapsulated into apostrophes) in the specified directory.
8604     </p>
8605     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8606     </p>
8607     <blockquote class="text">
8608     <p>if the given directory does not exist.
8609     </p>
8610     </blockquote>
8611    
8612    
8613     </blockquote><p>
8614    
8615     </p>
8616     <p>Example:
8617     </p>
8618     <p>
8619     </p>
8620     <blockquote class="text">
8621     <p>C: "LIST DB_INSTRUMENTS '/Piano Collection'"
8622     </p>
8623     <p>S: "'Bosendorfer 290','Steinway D'"
8624     </p>
8625     </blockquote><p>
8626    
8627     </p>
8628 iliev 1189 <p>
8629     </p>
8630     <blockquote class="text">
8631     <p>C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'"
8632     </p>
8633     <p>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D','/Piano Collection/Lite/Free Piano'"
8634     </p>
8635     </blockquote><p>
8636    
8637     </p>
8638 iliev 1162 <a name="GET DB_INSTRUMENT INFO"></a><br /><hr />
8639     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8640 iliev 1189 <a name="rfc.section.6.8.15"></a><h3>6.8.15.&nbsp;
8641 iliev 1162 Getting instrument information</h3>
8642    
8643     <p>The front-end can ask for the current settings of an
8644     instrument by sending the following command:
8645     </p>
8646     <p>
8647     </p>
8648     <blockquote class="text">
8649     <p>GET DB_INSTRUMENT INFO &lt;instr_path&gt;
8650     </p>
8651     </blockquote><p>
8652    
8653     </p>
8654     <p>Where &lt;instr_path&gt; should be replaced by the absolute path
8655     name of the instrument the front-end is interested in.
8656     </p>
8657     <p>Possible Answers:
8658     </p>
8659     <p>
8660     </p>
8661     <blockquote class="text">
8662     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
8663     Each answer line begins with the settings category name
8664     followed by a colon and then a space character &lt;SP&gt; and finally
8665     the info character string to that setting category. At the
8666     moment the following categories are defined:
8667     </p>
8668     <p>
8669     </p>
8670     <blockquote class="text">
8671     <p>INSTRUMENT_FILE -
8672     </p>
8673     <blockquote class="text">
8674     <p>File name of the instrument.
8675 schoenebeck 1363 Note that the character string may contain
8676     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
8677 iliev 1162 </p>
8678     </blockquote>
8679    
8680    
8681     <p>INSTRUMENT_NR -
8682     </p>
8683     <blockquote class="text">
8684     <p>Index of the instrument within the file.
8685     </p>
8686     </blockquote>
8687    
8688    
8689     <p>FORMAT_FAMILY -
8690     </p>
8691     <blockquote class="text">
8692     <p>The format family of the instrument.
8693     </p>
8694     </blockquote>
8695    
8696    
8697     <p>FORMAT_VERSION -
8698     </p>
8699     <blockquote class="text">
8700     <p>The format version of the instrument.
8701     </p>
8702     </blockquote>
8703    
8704    
8705     <p>SIZE -
8706     </p>
8707     <blockquote class="text">
8708     <p>The size of the instrument in bytes.
8709     </p>
8710     </blockquote>
8711    
8712    
8713     <p>CREATED -
8714     </p>
8715     <blockquote class="text">
8716     <p>The date and time when the instrument is added
8717     in the instruments database, represented in
8718     "YYYY-MM-DD HH:MM:SS" format
8719     </p>
8720     </blockquote>
8721    
8722    
8723     <p>MODIFIED -
8724     </p>
8725     <blockquote class="text">
8726     <p>The date and time of the last modification of the
8727     instrument's database settings, represented in
8728     "YYYY-MM-DD HH:MM:SS" format
8729     </p>
8730     </blockquote>
8731    
8732    
8733     <p>DESCRIPTION -
8734     </p>
8735     <blockquote class="text">
8736 schoenebeck 1363 <p>A brief description of the instrument.
8737     Note that the character string may contain
8738     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
8739 iliev 1162 </p>
8740     </blockquote>
8741    
8742    
8743     <p>IS_DRUM -
8744     </p>
8745     <blockquote class="text">
8746     <p>either true or false, determines whether the
8747     instrument is a drumkit or a chromatic instrument
8748     </p>
8749     </blockquote>
8750    
8751    
8752     <p>PRODUCT -
8753     </p>
8754     <blockquote class="text">
8755 schoenebeck 1363 <p>The product title of the instrument.
8756     Note that the character string may contain
8757     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
8758 iliev 1162 </p>
8759     </blockquote>
8760    
8761    
8762     <p>ARTISTS -
8763     </p>
8764     <blockquote class="text">
8765 schoenebeck 1363 <p>Lists the artist names.
8766     Note that the character string may contain
8767     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
8768 iliev 1162 </p>
8769     </blockquote>
8770    
8771    
8772     <p>KEYWORDS -
8773     </p>
8774     <blockquote class="text">
8775     <p>Provides a list of keywords that refer to the instrument.
8776     Keywords are separated with semicolon and blank.
8777 schoenebeck 1363 Note that the character string may contain
8778     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
8779 iliev 1162 </p>
8780     </blockquote>
8781    
8782    
8783     </blockquote>
8784    
8785    
8786     </blockquote><p>
8787    
8788     </p>
8789     <p>The mentioned fields above don't have to be in particular order.
8790     </p>
8791     <p>Example:
8792     </p>
8793     <p>
8794     </p>
8795     <blockquote class="text">
8796     <p>C: "GET DB_INSTRUMENT INFO '/Piano Collection/Bosendorfer 290'"
8797     </p>
8798     <p>S: "INSTRUMENT_FILE: /home/me/gigs/Bosendorfer 290.gig"
8799     </p>
8800     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"
8801     </p>
8802     <p>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"
8803     </p>
8804     <p>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 2"
8805     </p>
8806     <p>&nbsp;&nbsp;&nbsp;"SIZE: 2050871870"
8807     </p>
8808     <p>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"
8809     </p>
8810     <p>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"
8811     </p>
8812     <p>&nbsp;&nbsp;&nbsp;"DESCRIPTION: "
8813     </p>
8814     <p>&nbsp;&nbsp;&nbsp;"IS_DRUM: false"
8815     </p>
8816     <p>&nbsp;&nbsp;&nbsp;"PRODUCT: GRANDIOSO Bosendorfer 290"
8817     </p>
8818     <p>&nbsp;&nbsp;&nbsp;"ARTISTS: Post Musical Instruments"
8819     </p>
8820     <p>&nbsp;&nbsp;&nbsp;"KEYWORDS: Bosendorfer"
8821     </p>
8822     <p>&nbsp;&nbsp;&nbsp;"."
8823     </p>
8824     </blockquote><p>
8825    
8826     </p>
8827     <a name="SET DB_INSTRUMENT NAME"></a><br /><hr />
8828     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8829 iliev 1189 <a name="rfc.section.6.8.16"></a><h3>6.8.16.&nbsp;
8830 iliev 1162 Renaming an instrument</h3>
8831    
8832     <p>The front-end can alter the name of a specific
8833     instrument by sending the following command:
8834     </p>
8835     <p>
8836     </p>
8837     <blockquote class="text">
8838     <p>SET DB_INSTRUMENT NAME &lt;instr&gt; &lt;name&gt;
8839     </p>
8840     </blockquote><p>
8841    
8842     </p>
8843     <p>Where &lt;instr&gt; is the absolute path name of the instrument and
8844     &lt;name&gt; is the new name for that instrument.
8845     </p>
8846     <p>Possible Answers:
8847     </p>
8848     <p>
8849     </p>
8850     <blockquote class="text">
8851     <p>"OK" -
8852     </p>
8853     <blockquote class="text">
8854     <p>on success
8855     </p>
8856     </blockquote>
8857    
8858    
8859     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8860     </p>
8861     <blockquote class="text">
8862     <p>in case the given instrument does not exists,
8863     or if an instrument with name equal to the new
8864     name already exists.
8865     </p>
8866     </blockquote>
8867    
8868    
8869     </blockquote><p>
8870    
8871     </p>
8872     <p>Example:
8873     </p>
8874     <p>
8875     </p>
8876     <blockquote class="text">
8877     <p>C: "SET DB_INSTRUMENT NAME '/Piano Collection/Bosendorfer' 'Bosendorfer 290'"
8878     </p>
8879     <p>S: "OK"
8880     </p>
8881     </blockquote><p>
8882    
8883     </p>
8884     <a name="MOVE DB_INSTRUMENT"></a><br /><hr />
8885     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8886 iliev 1189 <a name="rfc.section.6.8.17"></a><h3>6.8.17.&nbsp;
8887 iliev 1162 Moving an instrument</h3>
8888    
8889     <p>The front-end can move a specific instrument to another directory by
8890     sending the following command:
8891     </p>
8892     <p>
8893     </p>
8894     <blockquote class="text">
8895     <p>MOVE DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;
8896     </p>
8897     </blockquote><p>
8898    
8899     </p>
8900     <p>Where &lt;instr&gt; is the absolute path name of the instrument
8901     to move and &lt;dst&gt; is the directory where the instrument will
8902     be moved to.
8903     </p>
8904     <p>Possible Answers:
8905     </p>
8906     <p>
8907     </p>
8908     <blockquote class="text">
8909     <p>"OK" -
8910     </p>
8911     <blockquote class="text">
8912     <p>on success
8913     </p>
8914     </blockquote>
8915    
8916    
8917     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8918     </p>
8919     <blockquote class="text">
8920     <p>in case the given instrument does not exists,
8921     or if an instrument with name equal to the name of the
8922     specified instrument already exists in the destination
8923     directory.
8924     </p>
8925     </blockquote>
8926    
8927    
8928     </blockquote><p>
8929    
8930     </p>
8931     <p>Example:
8932     </p>
8933     <p>
8934     </p>
8935     <blockquote class="text">
8936     <p>C: "MOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Piano Collection/Acoustic'"
8937     </p>
8938     <p>S: "OK"
8939     </p>
8940     </blockquote><p>
8941    
8942     </p>
8943 iliev 1189 <a name="COPY DB_INSTRUMENT"></a><br /><hr />
8944     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8945     <a name="rfc.section.6.8.18"></a><h3>6.8.18.&nbsp;
8946     Copying instruments</h3>
8947    
8948     <p>The front-end can copy a specific instrument to another directory by
8949     sending the following command:
8950     </p>
8951     <p>
8952     </p>
8953     <blockquote class="text">
8954     <p>COPY DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;
8955     </p>
8956     </blockquote><p>
8957    
8958     </p>
8959     <p>Where &lt;instr&gt; is the absolute path name of the instrument
8960     to copy and &lt;dst&gt; is the directory where the instrument will
8961     be copied to.
8962     </p>
8963     <p>Possible Answers:
8964     </p>
8965     <p>
8966     </p>
8967     <blockquote class="text">
8968     <p>"OK" -
8969     </p>
8970     <blockquote class="text">
8971     <p>on success
8972     </p>
8973     </blockquote>
8974    
8975    
8976     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8977     </p>
8978     <blockquote class="text">
8979     <p>in case the given instrument does not exists,
8980     or if an instrument with name equal to the name of the
8981     specified instrument already exists in the destination
8982     directory.
8983     </p>
8984     </blockquote>
8985    
8986    
8987     </blockquote><p>
8988    
8989     </p>
8990     <p>Example:
8991     </p>
8992     <p>
8993     </p>
8994     <blockquote class="text">
8995     <p>C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Acoustic/Pianos/'"
8996     </p>
8997     <p>S: "OK"
8998     </p>
8999     </blockquote><p>
9000    
9001     </p>
9002 iliev 1162 <a name="SET DB_INSTRUMENT DESCRIPTION"></a><br /><hr />
9003     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9004 iliev 1189 <a name="rfc.section.6.8.19"></a><h3>6.8.19.&nbsp;
9005 iliev 1162 Changing the description of instrument</h3>
9006    
9007     <p>The front-end can alter the description of a specific
9008     instrument by sending the following command:
9009     </p>
9010     <p>
9011     </p>
9012     <blockquote class="text">
9013     <p>SET DB_INSTRUMENT DESCRIPTION &lt;instr&gt; &lt;desc&gt;
9014     </p>
9015     </blockquote><p>
9016    
9017     </p>
9018     <p>Where &lt;instr&gt; is the absolute path name of the instrument and
9019 schoenebeck 1572 &lt;desc&gt; is the new description for the instrument
9020 schoenebeck 1363 (encapsulated into apostrophes, supporting escape sequences as described in chapter
9021     "<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>").
9022 iliev 1162 </p>
9023     <p>Possible Answers:
9024     </p>
9025     <p>
9026     </p>
9027     <blockquote class="text">
9028     <p>"OK" -
9029     </p>
9030     <blockquote class="text">
9031     <p>on success
9032     </p>
9033     </blockquote>
9034    
9035    
9036     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
9037     </p>
9038     <blockquote class="text">
9039     <p>in case the given instrument does not exists.
9040     </p>
9041     </blockquote>
9042    
9043    
9044     </blockquote><p>
9045    
9046     </p>
9047     <p>Example:
9048     </p>
9049     <p>
9050     </p>
9051     <blockquote class="text">
9052     <p>C: "SET DB_INSTRUMENT DESCRIPTION '/Piano Collection/Acoustic/Bosendorfer 290' 'No comment :)'"
9053     </p>
9054     <p>S: "OK"
9055     </p>
9056     </blockquote><p>
9057    
9058     </p>
9059 iliev 1189 <a name="FIND DB_INSTRUMENTS"></a><br /><hr />
9060     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9061     <a name="rfc.section.6.8.20"></a><h3>6.8.20.&nbsp;
9062     Finding instruments</h3>
9063    
9064     <p>The front-end can search for instruments
9065     in specific directory by sending the following command:
9066     </p>
9067     <p>
9068     </p>
9069     <blockquote class="text">
9070     <p>FIND DB_INSTRUMENTS [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;
9071     </p>
9072     </blockquote><p>
9073    
9074     </p>
9075     <p>Where &lt;dir&gt; should be replaced by the absolute path
9076     name of the directory to search in. If NON_RECURSIVE is specified, the
9077     directories located in subdirectories of the specified directory will not
9078     be searched. &lt;criteria-list&gt; is a list of search criterias
9079     in form of "key1=val1 key2=val2 ...". The following criterias are
9080     allowed:
9081     </p>
9082     <p>
9083    
9084     <p>NAME='&lt;search-string&gt;'
9085     </p>
9086     <blockquote class="text">
9087     <p>Restricts the search to instruments, which names
9088 schoenebeck 1363 satisfy the supplied search string (encapsulated into apostrophes,
9089     supporting escape sequences as described in chapter
9090     "<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>").
9091 iliev 1189 </p>
9092     </blockquote><p>
9093    
9094     </p>
9095    
9096    
9097     <p>SIZE=[&lt;min&gt;]..[&lt;max&gt;]
9098     </p>
9099     <blockquote class="text">
9100 schoenebeck 1251 <p>Restricts the search to instruments, which
9101 iliev 1189 size is in the specified range. If &lt;min&gt; is omitted,
9102     the search results are restricted to instruments with size less then
9103     or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the
9104     search is restricted to instruments with size greater then
9105     or equal to &lt;min&gt;.
9106     </p>
9107     </blockquote><p>
9108    
9109     </p>
9110    
9111    
9112     <p>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
9113     </p>
9114     <blockquote class="text">
9115     <p>Restricts the search to instruments, which creation
9116     date satisfies the specified period, where &lt;date-after&gt;
9117     and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
9118     If &lt;date-after&gt; is omitted the search is restricted to
9119     instruments created before &lt;date-before&gt;. If
9120     &lt;date-before&gt; is omitted, the search is restricted
9121     to instruments created after &lt;date-after&gt;.
9122     </p>
9123     </blockquote><p>
9124    
9125     </p>
9126    
9127    
9128     <p>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
9129     </p>
9130     <blockquote class="text">
9131     <p>Restricts the search to instruments, which
9132     date of last modification satisfies the specified period, where
9133     &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
9134     format. If &lt;date-after&gt; is omitted the search is restricted to
9135     instruments, which are last modified before &lt;date-before&gt;. If
9136     &lt;date-before&gt; is omitted, the search is restricted to instruments,
9137     which are last modified after &lt;date-after&gt;.
9138     </p>
9139     </blockquote><p>
9140    
9141     </p>
9142    
9143    
9144     <p>DESCRIPTION='&lt;search-string&gt;'
9145     </p>
9146     <blockquote class="text">
9147     <p>Restricts the search to instruments with description
9148 schoenebeck 1363 that satisfies the supplied search string (encapsulated into apostrophes,
9149     supporting escape sequences as described in chapter
9150     "<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>").
9151 iliev 1189 </p>
9152     </blockquote><p>
9153    
9154     </p>
9155    
9156    
9157     <p>PRODUCT='&lt;search-string&gt;'
9158     </p>
9159     <blockquote class="text">
9160     <p>Restricts the search to instruments with product info
9161 schoenebeck 1363 that satisfies the supplied search string (encapsulated into apostrophes,
9162     supporting escape sequences as described in chapter
9163     "<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>").
9164 iliev 1189 </p>
9165     </blockquote><p>
9166    
9167     </p>
9168    
9169    
9170     <p>ARTISTS='&lt;search-string&gt;'
9171     </p>
9172     <blockquote class="text">
9173     <p>Restricts the search to instruments with artists info
9174 schoenebeck 1363 that satisfies the supplied search string (encapsulated into apostrophes,
9175     supporting escape sequences as described in chapter
9176     "<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>").
9177 iliev 1189 </p>
9178     </blockquote><p>
9179    
9180     </p>
9181    
9182    
9183     <p>KEYWORDS='&lt;search-string&gt;'
9184     </p>
9185     <blockquote class="text">
9186     <p>Restricts the search to instruments with keyword list
9187 schoenebeck 1363 that satisfies the supplied search string (encapsulated into apostrophes,
9188     supporting escape sequences as described in chapter
9189     "<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>").
9190 iliev 1189 </p>
9191     </blockquote><p>
9192    
9193     </p>
9194    
9195    
9196     <p>IS_DRUM=true | false
9197     </p>
9198     <blockquote class="text">
9199 schoenebeck 1251 <p>Either true or false. Restricts the search to
9200 iliev 1189 drum kits or chromatic instruments.
9201     </p>
9202     </blockquote><p>
9203    
9204     </p>
9205    
9206    
9207     <p>FORMAT_FAMILIES='&lt;format-list&gt;'
9208     </p>
9209     <blockquote class="text">
9210     <p>Restricts the search to instruments of the supplied format families,
9211     where &lt;format-list&gt; is a comma separated list of format families.
9212     </p>
9213     </blockquote><p>
9214    
9215     </p>
9216    
9217    
9218     <p>Where &lt;search-string&gt; is either a regular expression, or a
9219     word list separated with spaces for OR search and with '+' for AND search.
9220     </p>
9221     <p>Possible Answers:
9222     </p>
9223     <p>
9224     </p>
9225     <blockquote class="text">
9226     <p>A comma separated list with the absolute path names (encapsulated into
9227     apostrophes) of all instruments in the specified directory that satisfy
9228     the supplied search criterias.
9229     </p>
9230     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
9231     </p>
9232     <blockquote class="text">
9233     <p>if the given directory does not exist.
9234     </p>
9235     </blockquote>
9236    
9237    
9238     </blockquote><p>
9239    
9240     </p>
9241     <p>Example:
9242     </p>
9243     <p>
9244     </p>
9245     <blockquote class="text">
9246     <p>C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+290'"
9247     </p>
9248     <p>S: "'/Piano Collection/Bosendorfer 290'"
9249     </p>
9250     </blockquote><p>
9251    
9252     </p>
9253     <p>
9254     </p>
9255     <blockquote class="text">
9256     <p>C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01 09:30:13..'"
9257     </p>
9258     <p>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D'"
9259     </p>
9260     </blockquote><p>
9261    
9262     </p>
9263 iliev 1201 <a name="GET DB_INSTRUMENTS_JOB INFO"></a><br /><hr />
9264     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9265     <a name="rfc.section.6.8.21"></a><h3>6.8.21.&nbsp;
9266     Getting job status information</h3>
9267    
9268     <p>The front-end can ask for the current status of a
9269     particular database instruments job by sending the following command:
9270     </p>
9271     <p>
9272     </p>
9273     <blockquote class="text">
9274     <p>GET DB_INSTRUMENTS_JOB INFO &lt;job-id&gt;
9275     </p>
9276     </blockquote><p>
9277    
9278     </p>
9279     <p>Where &lt;job-id&gt; should be replaced by the numerical ID
9280     of the job the front-end is interested in.
9281     </p>
9282     <p>Possible Answers:
9283     </p>
9284     <p>
9285     </p>
9286     <blockquote class="text">
9287     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
9288     Each answer line begins with the settings category name
9289     followed by a colon and then a space character &lt;SP&gt; and finally
9290     the info character string to that setting category. At the
9291     moment the following categories are defined:
9292     </p>
9293     <p>
9294     </p>
9295     <blockquote class="text">
9296     <p>FILES_TOTAL -
9297     </p>
9298     <blockquote class="text">
9299     <p>The total number of files scheduled for scanning
9300     </p>
9301     </blockquote>
9302    
9303    
9304     <p>FILES_SCANNED -
9305     </p>
9306     <blockquote class="text">
9307     <p>The current number of scanned files
9308     </p>
9309     </blockquote>
9310    
9311    
9312     <p>SCANNING -
9313     </p>
9314     <blockquote class="text">
9315     <p>The absolute path name of the file which is currently
9316     being scanned
9317     </p>
9318     </blockquote>
9319    
9320    
9321     <p>STATUS -
9322     </p>
9323     <blockquote class="text">
9324     <p>An integer value between 0 and 100 indicating the
9325     scanning progress percentage of the file which is
9326     currently being scanned
9327     </p>
9328     </blockquote>
9329    
9330    
9331     </blockquote>
9332    
9333    
9334     </blockquote><p>
9335    
9336     </p>
9337     <p>The mentioned fields above don't have to be in particular order.
9338     </p>
9339     <p>Example:
9340     </p>
9341     <p>
9342     </p>
9343     <blockquote class="text">
9344     <p>C: "GET DB_INSTRUMENTS_JOB INFO 2"
9345     </p>
9346     <p>S: "FILES_TOTAL: 12"
9347     </p>
9348     <p>&nbsp;&nbsp;&nbsp;"FILES_SCANNED: 7"
9349     </p>
9350     <p>&nbsp;&nbsp;&nbsp;"SCANNING: /home/me/gigs/Bosendorfer 290.gig"
9351     </p>
9352     <p>&nbsp;&nbsp;&nbsp;"STATUS: 42"
9353     </p>
9354     <p>&nbsp;&nbsp;&nbsp;"."
9355     </p>
9356     </blockquote><p>
9357    
9358     </p>
9359 schoenebeck 1363 <a name="FORMAT INSTRUMENTS_DB"></a><br /><hr />
9360     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9361     <a name="rfc.section.6.8.22"></a><h3>6.8.22.&nbsp;
9362     Formatting the instruments database</h3>
9363    
9364     <p>The front-end can remove all instruments and directories and re-create
9365     the instruments database structure (e.g., in case of a database corruption)
9366     by sending the following command:
9367     </p>
9368     <p>
9369     </p>
9370     <blockquote class="text">
9371     <p>FORMAT INSTRUMENTS_DB
9372     </p>
9373     </blockquote><p>
9374    
9375     </p>
9376     <p>Possible Answers:
9377     </p>
9378     <p>
9379     </p>
9380     <blockquote class="text">
9381     <p>"OK" -
9382     </p>
9383     <blockquote class="text">
9384     <p>on success
9385     </p>
9386     </blockquote>
9387    
9388    
9389     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
9390     </p>
9391     <blockquote class="text">
9392     <p>If the formatting of the instruments database
9393     failed.
9394     </p>
9395     </blockquote>
9396    
9397    
9398     </blockquote><p>
9399    
9400     </p>
9401 iliev 1731 <a name="FIND LOST DB_INSTRUMENT_FILES"></a><br /><hr />
9402     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9403     <a name="rfc.section.6.8.23"></a><h3>6.8.23.&nbsp;
9404     Checking for lost instrument files</h3>
9405    
9406     <p>The front-end can retrieve the list of all instrument files in the instruments database
9407     that don't exist in the filesystem by sending the following command:
9408     </p>
9409     <p>
9410     </p>
9411     <blockquote class="text">
9412     <p>FIND LOST DB_INSTRUMENT_FILES
9413     </p>
9414     </blockquote><p>
9415    
9416     </p>
9417     <p>Possible Answers:
9418     </p>
9419     <p>
9420     </p>
9421     <blockquote class="text">
9422     <p>A comma separated list with the absolute path names
9423     (encapsulated into apostrophes) of all lost instrument files.
9424     </p>
9425     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
9426     </p>
9427     <blockquote class="text">
9428     <p>in case it failed, providing an appropriate error code and error message.
9429     </p>
9430     </blockquote>
9431    
9432    
9433     </blockquote><p>
9434    
9435     </p>
9436     <p>Example:
9437     </p>
9438     <p>
9439     </p>
9440     <blockquote class="text">
9441     <p>C: "FIND LOST DB_INSTRUMENT_FILES"
9442     </p>
9443     <p>S: "'/gigs/Bosendorfer 290.gig','/gigs/Steinway D.gig','/gigs/Free Piano.gig'"
9444     </p>
9445     </blockquote><p>
9446    
9447     </p>
9448     <a name="SET DB_INSTRUMENT FILE_PATH"></a><br /><hr />
9449     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9450     <a name="rfc.section.6.8.24"></a><h3>6.8.24.&nbsp;
9451     Replacing an instrument file</h3>
9452    
9453     <p>The front-end can substitute all occurrences of an instrument file
9454     in the instruments database with a new one by sending the following command:
9455     </p>
9456     <p>
9457     </p>
9458     <blockquote class="text">
9459     <p>SET DB_INSTRUMENT FILE_PATH &lt;old_path&gt; &lt;new_path&gt;
9460     </p>
9461     </blockquote><p>
9462    
9463     </p>
9464     <p>Where &lt;old_path&gt; is the absolute path name of the instrument file
9465     to substitute with &lt;new_path&gt;.
9466     </p>
9467     <p>Possible Answers:
9468     </p>
9469     <p>
9470     </p>
9471     <blockquote class="text">
9472     <p>"OK" -
9473     </p>
9474     <blockquote class="text">
9475     <p>on success
9476     </p>
9477     </blockquote>
9478    
9479    
9480     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
9481     </p>
9482     <blockquote class="text">
9483     <p>in case it failed, providing an appropriate error code and error message.
9484     </p>
9485     </blockquote>
9486    
9487    
9488     </blockquote><p>
9489    
9490     </p>
9491     <p>Example:
9492     </p>
9493     <p>
9494     </p>
9495     <blockquote class="text">
9496     <p>C: "SET DB_INSTRUMENT FILE_PATH '/gigs/Bosendorfer 290.gig' '/gigs/pianos/Bosendorfer 290.gig'"
9497     </p>
9498     <p>S: "OK"
9499     </p>
9500     </blockquote><p>
9501    
9502     </p>
9503 schoenebeck 1363 <a name="editing_instruments"></a><br /><hr />
9504     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9505     <a name="rfc.section.6.9"></a><h3>6.9.&nbsp;
9506     Editing Instruments</h3>
9507    
9508     <p>The sampler allows to edit instruments while playing with the
9509     sampler by spawning an external (3rd party) instrument editor
9510     application for a given instrument. The 3rd party instrument
9511     editor applications have to place a respective plugin DLL file
9512     into the sampler's plugins directory. The sampler will
9513     automatically try to load all plugin DLLs in that directory on
9514     startup and only on startup!
9515     </p>
9516     <p>At the moment there is only one command for this feature set,
9517     but this will most probably change in future.
9518     </p>
9519     <a name="EDIT INSTRUMENT"></a><br /><hr />
9520     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9521     <a name="rfc.section.6.9.1"></a><h3>6.9.1.&nbsp;
9522     Opening an appropriate instrument editor application</h3>
9523    
9524     <p>The front-end can request to open an appropriate instrument
9525     editor application by sending the following command:
9526     </p>
9527     <p>
9528     </p>
9529     <blockquote class="text">
9530 schoenebeck 1430 <p>EDIT CHANNEL INSTRUMENT &lt;sampler-channel&gt;
9531 schoenebeck 1363 </p>
9532     </blockquote><p>
9533    
9534     </p>
9535     <p>Where &lt;sampler-channel&gt; should be replaced by the
9536     number of the sampler channel as given by the
9537     <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
9538     or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a>
9539     command.
9540     </p>
9541     <p>The sampler will try to ask all registered instrument
9542     editors (or to be more specific: their sampler plugins)
9543     whether they are capable to handle the instrument on the
9544     given sampler channel. The sampler will simply use the first
9545     instrument editor application which replied with a positive
9546     answer and spawn that instrument editor application within
9547     the sampler's process and provide that application access
9548     to the instrument's data structures, so both applications
9549     can share and access the same instruments data at the same
9550     time, thus allowing to immediately hear changes with the
9551     sampler made by the instrument editor.
9552     </p>
9553     <p>Note: consequently instrument editors are always spawned
9554     locally on the same machine where the sampler is running
9555     on!
9556     </p>
9557     <p>Possible Answers:
9558     </p>
9559     <p>
9560     </p>
9561     <blockquote class="text">
9562     <p>"OK" -
9563     </p>
9564     <blockquote class="text">
9565     <p>when an appropriate instrument editor was
9566     launched
9567     </p>
9568     </blockquote>
9569    
9570    
9571     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
9572     </p>
9573     <blockquote class="text">
9574     <p>when an appropriate instrument editor was
9575     launched, but there are noteworthy issues
9576     </p>
9577     </blockquote>
9578    
9579    
9580     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
9581     </p>
9582     <blockquote class="text">
9583     <p>when an appropriate instrument editor
9584     could not be launched
9585     </p>
9586     </blockquote>
9587    
9588    
9589     </blockquote><p>
9590    
9591     </p>
9592     <p>Examples:
9593     </p>
9594     <p>
9595     </p>
9596     <blockquote class="text">
9597 schoenebeck 1430 <p>C: "EDIT CHANNEL INSTRUMENT 0"
9598 schoenebeck 1363 </p>
9599     <p>S: "OK"
9600     </p>
9601     </blockquote><p>
9602    
9603     </p>
9604 schoenebeck 1572 <a name="file_management"></a><br /><hr />
9605     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9606     <a name="rfc.section.6.10"></a><h3>6.10.&nbsp;
9607     Managing Files</h3>
9608    
9609     <p>You can query detailed informations about files located
9610     at the same system where the sampler instance is running on.
9611     Using this command set allows to retrieve file informations
9612     even remotely from another machine.
9613     </p>
9614     <a name="GET FILE INSTRUMENTS"></a><br /><hr />
9615     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9616     <a name="rfc.section.6.10.1"></a><h3>6.10.1.&nbsp;
9617     Retrieving amount of instruments of a file</h3>
9618    
9619     <p>The front-end can retrieve the amount of instruments
9620     within a given instrument file by sending the
9621     following command:
9622     </p>
9623     <p>
9624     </p>
9625     <blockquote class="text">
9626     <p>GET FILE INSTRUMENTS &lt;filename&gt;
9627     </p>
9628     </blockquote><p>
9629    
9630     </p>
9631     <p>Where &lt;filename&gt; is the name of the instrument
9632     file (encapsulated into apostrophes, supporting escape
9633     sequences as described in chapter
9634     "<a class='info' href='#character_set'>Character Set and Escape
9635     Sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>").
9636     </p>
9637     <p>The sampler will try to ask all sampler engines,
9638     whether they support the given file and ask the first
9639     engine with a positive answer for the amount of
9640     instruments.
9641     </p>
9642     <p>Possible Answers:
9643     </p>
9644     <p>
9645     </p>
9646     <blockquote class="text">
9647     <p>On success, the sampler will answer by
9648     returning the amount of instruments.
9649    
9650     </p>
9651     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
9652     </p>
9653     <blockquote class="text">
9654     <p>if the file could not be handled
9655     </p>
9656     </blockquote>
9657    
9658    
9659     </blockquote><p>
9660    
9661     </p>
9662     <p>Examples:
9663     </p>
9664     <p>
9665     </p>
9666     <blockquote class="text">
9667     <p>C: "GET FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"
9668     </p>
9669     <p>S: "10"
9670     </p>
9671     </blockquote><p>
9672    
9673     </p>
9674     <a name="LIST FILE INSTRUMENTS"></a><br /><hr />
9675     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9676     <a name="rfc.section.6.10.2"></a><h3>6.10.2.&nbsp;
9677     Retrieving all instruments of a file</h3>
9678    
9679     <p>The front-end can retrieve a list of all instruments
9680     within a given instrument file by sending the
9681     following command:
9682     </p>
9683     <p>
9684     </p>
9685     <blockquote class="text">
9686     <p>LIST FILE INSTRUMENTS &lt;filename&gt;
9687     </p>
9688     </blockquote><p>
9689    
9690     </p>
9691     <p>Where &lt;filename&gt; is the name of the instrument
9692     file (encapsulated into apostrophes, supporting escape
9693     sequences as described in chapter
9694     "<a class='info' href='#character_set'>Character Set and Escape
9695     Sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>").
9696     </p>
9697     <p>The sampler will try to ask all sampler engines,
9698     whether they support the given file and ask the first
9699     engine with a positive answer for a list of IDs for the
9700     instruments in the given file.
9701     </p>
9702     <p>Possible Answers:
9703     </p>
9704     <p>
9705     </p>
9706     <blockquote class="text">
9707     <p>On success, the sampler will answer by
9708     returning a comma separated list of
9709     instrument IDs.
9710    
9711     </p>
9712     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
9713     </p>
9714     <blockquote class="text">
9715     <p>if the file could not be handled
9716     </p>
9717     </blockquote>
9718    
9719    
9720     </blockquote><p>
9721    
9722     </p>
9723     <p>Examples:
9724     </p>
9725     <p>
9726     </p>
9727     <blockquote class="text">
9728     <p>C: "LIST FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"
9729     </p>
9730     <p>S: "0,1,2,3,4,5,6,7,8,9"
9731     </p>
9732     </blockquote><p>
9733    
9734     </p>
9735     <a name="GET FILE INSTRUMENT INFO"></a><br /><hr />
9736     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9737     <a name="rfc.section.6.10.3"></a><h3>6.10.3.&nbsp;
9738     Retrieving informations about one instrument in a file</h3>
9739    
9740     <p>The front-end can retrieve detailed informations
9741     about a specific instrument within a given instrument
9742     file by sending the following command:
9743     </p>
9744     <p>
9745     </p>
9746     <blockquote class="text">
9747     <p>GET FILE INSTRUMENT INFO &lt;filename&gt;
9748     &lt;instr-id&gt;
9749     </p>
9750     </blockquote><p>
9751    
9752     </p>
9753     <p>Where &lt;filename&gt; is the name of the instrument
9754     file (encapsulated into apostrophes, supporting escape
9755     sequences as described in chapter
9756     "<a class='info' href='#character_set'>Character Set and Escape
9757     Sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>") and &lt;instr-id&gt; is the numeric
9758     instrument ID as returned by the
9759     <a class='info' href='#LIST FILE INSTRUMENTS'>"LIST FILE INSTRUMENTS"<span> (</span><span class='info'>Retrieving all instruments of a file</span><span>)</span></a> command.
9760     </p>
9761     <p>The sampler will try to ask all sampler engines,
9762     whether they support the given file and ask the first
9763     engine with a positive answer for informations about the
9764     specific instrument in the given file.
9765     </p>
9766     <p>Possible Answers:
9767     </p>
9768     <p>
9769     </p>
9770     <blockquote class="text">
9771     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
9772     Each answer line begins with the settings category name
9773     followed by a colon and then a space character &lt;SP&gt; and finally
9774     the info character string to that setting category. At the
9775     moment the following categories are defined:
9776     </p>
9777     <p>
9778     </p>
9779     <blockquote class="text">
9780     <p>NAME -
9781     </p>
9782     <blockquote class="text">
9783     <p>name of the instrument as
9784     stored in the instrument file
9785     </p>
9786     </blockquote>
9787    
9788    
9789     <p>FORMAT_FAMILY -
9790     </p>
9791     <blockquote class="text">
9792     <p>name of the sampler format
9793     of the given instrument
9794     </p>
9795     </blockquote>
9796    
9797    
9798     <p>FORMAT_VERSION -
9799     </p>
9800     <blockquote class="text">
9801     <p>version of the sampler format
9802     the instrumen is stored as
9803     </p>
9804     </blockquote>
9805    
9806    
9807     <p>PRODUCT -
9808     </p>
9809     <blockquote class="text">
9810     <p>official product name of the
9811     instrument as stored in the file
9812    
9813     </p>
9814     </blockquote>
9815    
9816    
9817     <p>ARTISTS -
9818     </p>
9819     <blockquote class="text">
9820     <p>artists / sample library
9821     vendor of the instrument
9822     </p>
9823     </blockquote>
9824    
9825    
9826 iliev 1773 <p>KEY_BINDINGS -
9827     </p>
9828     <blockquote class="text">
9829     <p>comma separated list of integer values representing
9830     the instrument's key mapping in the range between 0 .. 127,
9831     reflecting the analog meaning of the MIDI specification.
9832     </p>
9833 schoenebeck 1572 </blockquote>
9834 iliev 1773
9835    
9836     <p>KEYSWITCH_BINDINGS -
9837     </p>
9838     <blockquote class="text">
9839     <p>comma separated list of integer values representing
9840     the instrument's keyswitch mapping in the range between 0 .. 127,
9841     reflecting the analog meaning of the MIDI specification.
9842     </p>
9843     </blockquote>
9844    
9845    
9846     </blockquote>
9847 schoenebeck 1572
9848    
9849     </blockquote><p>
9850    
9851     </p>
9852     <p>The mentioned fields above don't have to be in particular order.
9853     </p>
9854     <p>Example:
9855     </p>
9856     <p>
9857     </p>
9858     <blockquote class="text">
9859     <p>C: "GET FILE INSTRUMENT INFO 'D:/Sounds/Foo.gig' 0"
9860     </p>
9861     <p>S: "NAME: Lunatic Loops"
9862     </p>
9863     <p>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"
9864     </p>
9865     <p>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 3"
9866     </p>
9867     <p>&nbsp;&nbsp;&nbsp;"PRODUCT: The Backbone Bongo Beats"
9868     </p>
9869     <p>&nbsp;&nbsp;&nbsp;"ARTISTS: Jimmy the Fish"
9870     </p>
9871     <p>&nbsp;&nbsp;&nbsp;"."
9872     </p>
9873     </blockquote><p>
9874    
9875     </p>
9876 senoner 542 <a name="command_syntax"></a><br /><hr />
9877 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9878     <a name="rfc.section.7"></a><h3>7.&nbsp;
9879     Command Syntax</h3>
9880 senoner 542
9881 schoenebeck 974 <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>
9882     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>)
9883 schoenebeck 575 where applicable.
9884 schoenebeck 940
9885 senoner 542 </p>
9886 schoenebeck 575 <p>input =
9887     </p>
9888     <blockquote class="text">
9889     <p>line LF
9890 schoenebeck 940
9891 schoenebeck 575 </p>
9892     <p>/ line CR LF
9893 schoenebeck 940
9894 schoenebeck 575 </p>
9895 schoenebeck 708 </blockquote><p>
9896 schoenebeck 575
9897 schoenebeck 708 </p>
9898 schoenebeck 575 <p>line =
9899     </p>
9900     <blockquote class="text">
9901     <p>/* epsilon (empty line ignored) */
9902 schoenebeck 940
9903 schoenebeck 575 </p>
9904     <p>/ comment
9905 schoenebeck 940
9906 schoenebeck 575 </p>
9907     <p>/ command
9908 schoenebeck 940
9909 schoenebeck 575 </p>
9910     <p>/ error
9911 schoenebeck 940
9912 schoenebeck 575 </p>
9913 schoenebeck 708 </blockquote><p>
9914 schoenebeck 575
9915 schoenebeck 708 </p>
9916 schoenebeck 575 <p>comment =
9917     </p>
9918     <blockquote class="text">
9919     <p>'#'
9920 schoenebeck 940
9921 schoenebeck 575 </p>
9922     <p>/ comment '#'
9923 schoenebeck 940
9924 schoenebeck 575 </p>
9925     <p>/ comment SP
9926 schoenebeck 940
9927 schoenebeck 575 </p>
9928     <p>/ comment number
9929 schoenebeck 940
9930 schoenebeck 575 </p>
9931     <p>/ comment string
9932 schoenebeck 940
9933 schoenebeck 575 </p>
9934 schoenebeck 708 </blockquote><p>
9935 schoenebeck 575
9936 schoenebeck 708 </p>
9937 schoenebeck 575 <p>command =
9938     </p>
9939     <blockquote class="text">
9940 schoenebeck 974 <p>ADD SP add_instruction
9941 schoenebeck 940
9942 schoenebeck 575 </p>
9943 schoenebeck 945 <p>/ MAP SP map_instruction
9944    
9945     </p>
9946     <p>/ UNMAP SP unmap_instruction
9947    
9948     </p>
9949 schoenebeck 575 <p>/ GET SP get_instruction
9950 schoenebeck 940
9951 schoenebeck 575 </p>
9952     <p>/ CREATE SP create_instruction
9953 schoenebeck 940
9954 schoenebeck 575 </p>
9955     <p>/ DESTROY SP destroy_instruction
9956 schoenebeck 940
9957 schoenebeck 575 </p>
9958     <p>/ LIST SP list_instruction
9959 schoenebeck 940
9960 schoenebeck 575 </p>
9961     <p>/ LOAD SP load_instruction
9962 schoenebeck 940
9963 schoenebeck 575 </p>
9964 schoenebeck 945 <p>/ REMOVE SP remove_instruction
9965 schoenebeck 940
9966 schoenebeck 575 </p>
9967     <p>/ SET SP set_instruction
9968 schoenebeck 940
9969 schoenebeck 575 </p>
9970     <p>/ SUBSCRIBE SP subscribe_event
9971 schoenebeck 940
9972 schoenebeck 575 </p>
9973     <p>/ UNSUBSCRIBE SP unsubscribe_event
9974 schoenebeck 940
9975 schoenebeck 575 </p>
9976 schoenebeck 945 <p>/ RESET SP reset_instruction
9977 schoenebeck 940
9978 schoenebeck 575 </p>
9979 schoenebeck 945 <p>/ CLEAR SP clear_instruction
9980    
9981     </p>
9982 iliev 1189 <p>/ FIND SP find_instruction
9983    
9984     </p>
9985 iliev 1162 <p>/ MOVE SP move_instruction
9986    
9987     </p>
9988 iliev 1189 <p>/ COPY SP copy_instruction
9989    
9990     </p>
9991 schoenebeck 1251 <p>/ EDIT SP edit_instruction
9992    
9993     </p>
9994 schoenebeck 1363 <p>/ FORMAT SP format_instruction
9995 schoenebeck 1801
9996 iliev 1773 </p>
9997 schoenebeck 1801 <p>/ SEND SP send_instruction
9998 schoenebeck 1363
9999     </p>
10000 schoenebeck 575 <p>/ RESET
10001 schoenebeck 940
10002 schoenebeck 575 </p>
10003     <p>/ QUIT
10004 schoenebeck 940
10005 schoenebeck 575 </p>
10006 schoenebeck 708 </blockquote><p>
10007 schoenebeck 575
10008 schoenebeck 708 </p>
10009 schoenebeck 974 <p>add_instruction =
10010     </p>
10011     <blockquote class="text">
10012     <p>CHANNEL
10013    
10014     </p>
10015 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORY SP db_path
10016 iliev 1162
10017     </p>
10018 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename
10019 iliev 1162
10020     </p>
10021 schoenebeck 1801 <p>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP FILE_AS_DIR SP db_path SP filename
10022    
10023     </p>
10024 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename
10025 iliev 1162
10026     </p>
10027 schoenebeck 1801 <p>/ DB_INSTRUMENTS SP scan_mode SP FILE_AS_DIR SP db_path SP filename
10028    
10029     </p>
10030 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
10031 iliev 1201
10032     </p>
10033 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index
10034 iliev 1201
10035     </p>
10036 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP db_path SP filename
10037 iliev 1162
10038     </p>
10039 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP db_path SP filename SP instrument_index
10040 iliev 1162
10041     </p>
10042 schoenebeck 974 <p>/ MIDI_INSTRUMENT_MAP
10043    
10044     </p>
10045     <p>/ MIDI_INSTRUMENT_MAP SP map_name
10046    
10047     </p>
10048     </blockquote><p>
10049    
10050     </p>
10051 schoenebeck 575 <p>subscribe_event =
10052     </p>
10053     <blockquote class="text">
10054 iliev 992 <p>AUDIO_OUTPUT_DEVICE_COUNT
10055 schoenebeck 940
10056 schoenebeck 575 </p>
10057 iliev 992 <p>/ AUDIO_OUTPUT_DEVICE_INFO
10058    
10059     </p>
10060     <p>/ MIDI_INPUT_DEVICE_COUNT
10061    
10062     </p>
10063     <p>/ MIDI_INPUT_DEVICE_INFO
10064    
10065     </p>
10066     <p>/ CHANNEL_COUNT
10067    
10068     </p>
10069 schoenebeck 1685 <p>/ CHANNEL_MIDI
10070    
10071     </p>
10072 schoenebeck 1696 <p>/ DEVICE_MIDI
10073    
10074     </p>
10075 schoenebeck 575 <p>/ VOICE_COUNT
10076 schoenebeck 940
10077 schoenebeck 575 </p>
10078     <p>/ STREAM_COUNT
10079 schoenebeck 940
10080 schoenebeck 575 </p>
10081     <p>/ BUFFER_FILL
10082 schoenebeck 940
10083 schoenebeck 575 </p>
10084     <p>/ CHANNEL_INFO
10085 schoenebeck 940
10086 schoenebeck 575 </p>
10087 iliev 1110 <p>/ FX_SEND_COUNT
10088    
10089     </p>
10090     <p>/ FX_SEND_INFO
10091    
10092     </p>
10093 iliev 992 <p>/ MIDI_INSTRUMENT_MAP_COUNT
10094    
10095     </p>
10096     <p>/ MIDI_INSTRUMENT_MAP_INFO
10097    
10098     </p>
10099     <p>/ MIDI_INSTRUMENT_COUNT
10100    
10101     </p>
10102     <p>/ MIDI_INSTRUMENT_INFO
10103    
10104     </p>
10105 iliev 1162 <p>/ DB_INSTRUMENT_DIRECTORY_COUNT
10106    
10107     </p>
10108     <p>/ DB_INSTRUMENT_DIRECTORY_INFO
10109    
10110     </p>
10111     <p>/ DB_INSTRUMENT_COUNT
10112    
10113     </p>
10114     <p>/ DB_INSTRUMENT_INFO
10115    
10116     </p>
10117 iliev 1201 <p>/ DB_INSTRUMENTS_JOB_INFO
10118    
10119     </p>
10120 schoenebeck 575 <p>/ MISCELLANEOUS
10121 schoenebeck 940
10122 schoenebeck 575 </p>
10123 schoenebeck 1572 <p>/ TOTAL_STREAM_COUNT
10124    
10125     </p>
10126 schoenebeck 940 <p>/ TOTAL_VOICE_COUNT
10127    
10128     </p>
10129 iliev 1110 <p>/ GLOBAL_INFO
10130    
10131     </p>
10132 schoenebeck 708 </blockquote><p>
10133 schoenebeck 575
10134 schoenebeck 708 </p>
10135 schoenebeck 575 <p>unsubscribe_event =
10136     </p>
10137     <blockquote class="text">
10138 iliev 992 <p>AUDIO_OUTPUT_DEVICE_COUNT
10139 schoenebeck 940
10140 schoenebeck 575 </p>
10141 iliev 992 <p>/ AUDIO_OUTPUT_DEVICE_INFO
10142    
10143     </p>
10144     <p>/ MIDI_INPUT_DEVICE_COUNT
10145    
10146     </p>
10147     <p>/ MIDI_INPUT_DEVICE_INFO
10148    
10149     </p>
10150     <p>/ CHANNEL_COUNT
10151    
10152     </p>
10153 schoenebeck 1685 <p>/ CHANNEL_MIDI
10154    
10155     </p>
10156 schoenebeck 1696 <p>/ DEVICE_MIDI
10157    
10158     </p>
10159 schoenebeck 575 <p>/ VOICE_COUNT
10160 schoenebeck 940
10161 schoenebeck 575 </p>
10162     <p>/ STREAM_COUNT
10163 schoenebeck 940
10164 schoenebeck 575 </p>
10165     <p>/ BUFFER_FILL
10166 schoenebeck 940
10167 schoenebeck 575 </p>
10168     <p>/ CHANNEL_INFO
10169 schoenebeck 940
10170 schoenebeck 575 </p>
10171 iliev 1110 <p>/ FX_SEND_COUNT
10172    
10173     </p>
10174     <p>/ FX_SEND_INFO
10175    
10176     </p>
10177 iliev 992 <p>/ MIDI_INSTRUMENT_MAP_COUNT
10178    
10179     </p>
10180     <p>/ MIDI_INSTRUMENT_MAP_INFO
10181    
10182     </p>
10183     <p>/ MIDI_INSTRUMENT_COUNT
10184    
10185     </p>
10186     <p>/ MIDI_INSTRUMENT_INFO
10187    
10188     </p>
10189 iliev 1162 <p>/ DB_INSTRUMENT_DIRECTORY_COUNT
10190    
10191     </p>
10192     <p>/ DB_INSTRUMENT_DIRECTORY_INFO
10193    
10194     </p>
10195     <p>/ DB_INSTRUMENT_COUNT
10196    
10197     </p>
10198     <p>/ DB_INSTRUMENT_INFO
10199    
10200     </p>
10201 iliev 1201 <p>/ DB_INSTRUMENTS_JOB_INFO
10202    
10203     </p>
10204 schoenebeck 575 <p>/ MISCELLANEOUS
10205 schoenebeck 940
10206 schoenebeck 575 </p>
10207 schoenebeck 1572 <p>/ TOTAL_STREAM_COUNT
10208    
10209     </p>
10210 schoenebeck 940 <p>/ TOTAL_VOICE_COUNT
10211    
10212     </p>
10213 iliev 1110 <p>/ GLOBAL_INFO
10214    
10215     </p>
10216 schoenebeck 708 </blockquote><p>
10217 schoenebeck 575
10218 schoenebeck 708 </p>
10219 schoenebeck 945 <p>map_instruction =
10220     </p>
10221     <blockquote class="text">
10222 schoenebeck 1048 <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
10223 schoenebeck 945
10224     </p>
10225 schoenebeck 1048 <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
10226 schoenebeck 945
10227     </p>
10228 schoenebeck 1048 <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
10229 schoenebeck 945
10230     </p>
10231 schoenebeck 1048 <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
10232 schoenebeck 945
10233     </p>
10234     </blockquote><p>
10235    
10236     </p>
10237     <p>unmap_instruction =
10238     </p>
10239     <blockquote class="text">
10240 schoenebeck 974 <p>MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog
10241 schoenebeck 945
10242     </p>
10243     </blockquote><p>
10244    
10245     </p>
10246     <p>remove_instruction =
10247     </p>
10248     <blockquote class="text">
10249     <p>CHANNEL SP sampler_channel
10250    
10251     </p>
10252 schoenebeck 974 <p>/ MIDI_INSTRUMENT_MAP SP midi_map
10253    
10254     </p>
10255     <p>/ MIDI_INSTRUMENT_MAP SP ALL
10256    
10257     </p>
10258 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path
10259 iliev 1162
10260     </p>
10261 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORY SP db_path
10262 iliev 1162
10263     </p>
10264 schoenebeck 1363 <p>/ DB_INSTRUMENT SP db_path
10265 iliev 1162
10266     </p>
10267 schoenebeck 945 </blockquote><p>
10268    
10269     </p>
10270 schoenebeck 575 <p>get_instruction =
10271     </p>
10272     <blockquote class="text">
10273     <p>AVAILABLE_ENGINES
10274 schoenebeck 940
10275 schoenebeck 575 </p>
10276     <p>/ AVAILABLE_MIDI_INPUT_DRIVERS
10277 schoenebeck 940
10278 schoenebeck 575 </p>
10279     <p>/ MIDI_INPUT_DRIVER SP INFO SP string
10280 schoenebeck 940
10281 schoenebeck 575 </p>
10282     <p>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
10283 schoenebeck 940
10284 schoenebeck 575 </p>
10285     <p>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
10286 schoenebeck 940
10287 schoenebeck 575 </p>
10288     <p>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
10289 schoenebeck 940
10290 schoenebeck 575 </p>
10291     <p>/ AUDIO_OUTPUT_DRIVER SP INFO SP string
10292 schoenebeck 940
10293 schoenebeck 575 </p>
10294     <p>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
10295 schoenebeck 940
10296 schoenebeck 575 </p>
10297     <p>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
10298 schoenebeck 940
10299 schoenebeck 575 </p>
10300     <p>/ AUDIO_OUTPUT_DEVICES
10301 schoenebeck 940
10302 schoenebeck 575 </p>
10303     <p>/ MIDI_INPUT_DEVICES
10304 schoenebeck 940
10305 schoenebeck 575 </p>
10306     <p>/ AUDIO_OUTPUT_DEVICE SP INFO SP number
10307 schoenebeck 940
10308 schoenebeck 575 </p>
10309     <p>/ MIDI_INPUT_DEVICE SP INFO SP number
10310 schoenebeck 940
10311 schoenebeck 575 </p>
10312     <p>/ MIDI_INPUT_PORT SP INFO SP number SP number
10313 schoenebeck 940
10314 schoenebeck 575 </p>
10315     <p>/ MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
10316 schoenebeck 940
10317 schoenebeck 575 </p>
10318     <p>/ AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
10319 schoenebeck 940
10320 schoenebeck 575 </p>
10321     <p>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP string
10322 schoenebeck 940
10323 schoenebeck 575 </p>
10324     <p>/ CHANNELS
10325 schoenebeck 940
10326 schoenebeck 575 </p>
10327     <p>/ CHANNEL SP INFO SP sampler_channel
10328 schoenebeck 940
10329 schoenebeck 575 </p>
10330     <p>/ CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
10331 schoenebeck 940
10332 schoenebeck 575 </p>
10333     <p>/ CHANNEL SP STREAM_COUNT SP sampler_channel
10334 schoenebeck 940
10335 schoenebeck 575 </p>
10336     <p>/ CHANNEL SP VOICE_COUNT SP sampler_channel
10337 schoenebeck 940
10338 schoenebeck 575 </p>
10339     <p>/ ENGINE SP INFO SP engine_name
10340 schoenebeck 940
10341 schoenebeck 575 </p>
10342     <p>/ SERVER SP INFO
10343 schoenebeck 940
10344 schoenebeck 575 </p>
10345 schoenebeck 1572 <p>/ TOTAL_STREAM_COUNT
10346    
10347     </p>
10348 schoenebeck 940 <p>/ TOTAL_VOICE_COUNT
10349    
10350     </p>
10351     <p>/ TOTAL_VOICE_COUNT_MAX
10352    
10353     </p>
10354 schoenebeck 974 <p>/ MIDI_INSTRUMENTS SP midi_map
10355 schoenebeck 945
10356     </p>
10357 schoenebeck 974 <p>/ MIDI_INSTRUMENTS SP ALL
10358 schoenebeck 945
10359     </p>
10360 schoenebeck 974 <p>/ MIDI_INSTRUMENT SP INFO SP midi_map SP midi_bank SP midi_prog
10361    
10362     </p>
10363     <p>/ MIDI_INSTRUMENT_MAPS
10364    
10365     </p>
10366     <p>/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map
10367    
10368     </p>
10369 schoenebeck 1002 <p>/ FX_SENDS SP sampler_channel
10370    
10371     </p>
10372     <p>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
10373    
10374     </p>
10375 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
10376 iliev 1189
10377     </p>
10378 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORIES SP db_path
10379 iliev 1162
10380     </p>
10381 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORY SP INFO SP db_path
10382 iliev 1162
10383     </p>
10384 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
10385 iliev 1189
10386     </p>
10387 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP db_path
10388 iliev 1162
10389     </p>
10390 schoenebeck 1363 <p>/ DB_INSTRUMENT SP INFO SP db_path
10391 iliev 1162
10392     </p>
10393 iliev 1201 <p>/ DB_INSTRUMENTS_JOB SP INFO SP number
10394    
10395     </p>
10396 schoenebeck 1006 <p>/ VOLUME
10397    
10398     </p>
10399 schoenebeck 1801 <p>/ VOICES
10400    
10401     </p>
10402     <p>/ STREAMS
10403    
10404     </p>
10405 schoenebeck 1572 <p>/ FILE SP INSTRUMENTS SP filename
10406    
10407     </p>
10408     <p>/ FILE SP INSTRUMENT SP INFO SP filename SP instrument_index
10409    
10410     </p>
10411 schoenebeck 708 </blockquote><p>
10412 schoenebeck 575
10413 schoenebeck 708 </p>
10414 schoenebeck 575 <p>set_instruction =
10415     </p>
10416     <blockquote class="text">
10417     <p>AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
10418 schoenebeck 940
10419 schoenebeck 575 </p>
10420     <p>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '=' param_val_list
10421 schoenebeck 940
10422 schoenebeck 575 </p>
10423     <p>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
10424 schoenebeck 940
10425 schoenebeck 575 </p>
10426 schoenebeck 1363 <p>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE
10427    
10428     </p>
10429 schoenebeck 575 <p>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list
10430 schoenebeck 940
10431 schoenebeck 575 </p>
10432     <p>/ CHANNEL SP set_chan_instruction
10433 schoenebeck 940
10434 schoenebeck 575 </p>
10435 schoenebeck 974 <p>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
10436    
10437     </p>
10438 iliev 1137 <p>/ FX_SEND SP NAME SP sampler_channel SP fx_send_id SP fx_send_name
10439    
10440     </p>
10441 schoenebeck 1002 <p>/ FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id SP audio_channel_index SP audio_channel_index
10442    
10443     </p>
10444 schoenebeck 1028 <p>/ FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP midi_ctrl
10445    
10446     </p>
10447     <p>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
10448    
10449     </p>
10450 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped
10451 iliev 1162
10452     </p>
10453 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped
10454 iliev 1162
10455     </p>
10456 schoenebeck 1363 <p>/ DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped
10457 iliev 1162
10458     </p>
10459 schoenebeck 1363 <p>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
10460 iliev 1162
10461     </p>
10462 iliev 1731 <p>/ DB_INSTRUMENT SP FILE_PATH SP filename SP filename
10463    
10464     </p>
10465 schoenebeck 575 <p>/ ECHO SP boolean
10466 schoenebeck 940
10467 schoenebeck 575 </p>
10468 schoenebeck 1006 <p>/ VOLUME SP volume_value
10469    
10470     </p>
10471 schoenebeck 1801 <p>/ VOICES SP number
10472    
10473     </p>
10474     <p>/ STREAMS SP number
10475    
10476     </p>
10477 schoenebeck 708 </blockquote><p>
10478 schoenebeck 575
10479 schoenebeck 708 </p>
10480 schoenebeck 575 <p>create_instruction =
10481     </p>
10482     <blockquote class="text">
10483     <p>AUDIO_OUTPUT_DEVICE SP string SP key_val_list
10484 schoenebeck 940
10485 schoenebeck 575 </p>
10486     <p>/ AUDIO_OUTPUT_DEVICE SP string
10487 schoenebeck 940
10488 schoenebeck 575 </p>
10489     <p>/ MIDI_INPUT_DEVICE SP string SP key_val_list
10490 schoenebeck 940
10491 schoenebeck 575 </p>
10492     <p>/ MIDI_INPUT_DEVICE SP string
10493 schoenebeck 940
10494 schoenebeck 575 </p>
10495 schoenebeck 1002 <p>/ FX_SEND SP sampler_channel SP midi_ctrl
10496    
10497     </p>
10498     <p>/ FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name
10499    
10500     </p>
10501 schoenebeck 708 </blockquote><p>
10502 schoenebeck 575
10503 schoenebeck 708 </p>
10504 schoenebeck 945 <p>reset_instruction =
10505     </p>
10506     <blockquote class="text">
10507     <p>CHANNEL SP sampler_channel
10508    
10509     </p>
10510     </blockquote><p>
10511    
10512     </p>
10513     <p>clear_instruction =
10514     </p>
10515     <blockquote class="text">
10516 schoenebeck 974 <p>MIDI_INSTRUMENTS SP midi_map
10517 schoenebeck 945
10518     </p>
10519 schoenebeck 974 <p>/ MIDI_INSTRUMENTS SP ALL
10520    
10521     </p>
10522 schoenebeck 945 </blockquote><p>
10523    
10524     </p>
10525 iliev 1189 <p>find_instruction =
10526     </p>
10527     <blockquote class="text">
10528 schoenebeck 1363 <p>DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list
10529 iliev 1189
10530     </p>
10531 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP db_path SP query_val_list
10532 iliev 1189
10533     </p>
10534 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP query_val_list
10535 iliev 1189
10536     </p>
10537 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
10538 iliev 1189
10539     </p>
10540 iliev 1731 <p>/ LOST SP DB_INSTRUMENT_FILES
10541    
10542     </p>
10543 iliev 1189 </blockquote><p>
10544    
10545     </p>
10546 iliev 1162 <p>move_instruction =
10547     </p>
10548     <blockquote class="text">
10549 schoenebeck 1363 <p>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
10550 iliev 1162
10551     </p>
10552 schoenebeck 1363 <p>/ DB_INSTRUMENT SP db_path SP db_path
10553 iliev 1162
10554     </p>
10555     </blockquote><p>
10556    
10557     </p>
10558 iliev 1189 <p>copy_instruction =
10559     </p>
10560     <blockquote class="text">
10561 schoenebeck 1363 <p>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
10562 iliev 1189
10563     </p>
10564 schoenebeck 1363 <p>/ DB_INSTRUMENT SP db_path SP db_path
10565 iliev 1189
10566     </p>
10567     </blockquote><p>
10568    
10569     </p>
10570 schoenebeck 575 <p>destroy_instruction =
10571     </p>
10572     <blockquote class="text">
10573     <p>AUDIO_OUTPUT_DEVICE SP number
10574 schoenebeck 940
10575 schoenebeck 575 </p>
10576     <p>/ MIDI_INPUT_DEVICE SP number
10577 schoenebeck 940
10578 schoenebeck 575 </p>
10579 schoenebeck 1002 <p>/ FX_SEND SP sampler_channel SP fx_send_id
10580    
10581     </p>
10582 schoenebeck 708 </blockquote><p>
10583 schoenebeck 575
10584 schoenebeck 708 </p>
10585 schoenebeck 575 <p>load_instruction =
10586     </p>
10587     <blockquote class="text">
10588     <p>INSTRUMENT SP load_instr_args
10589 schoenebeck 940
10590 schoenebeck 575 </p>
10591     <p>/ ENGINE SP load_engine_args
10592 schoenebeck 940
10593 schoenebeck 575 </p>
10594 schoenebeck 708 </blockquote><p>
10595 schoenebeck 575
10596 schoenebeck 708 </p>
10597 schoenebeck 575 <p>set_chan_instruction =
10598     </p>
10599     <blockquote class="text">
10600     <p>AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
10601 schoenebeck 940
10602 schoenebeck 575 </p>
10603     <p>/ AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index SP audio_channel_index
10604 schoenebeck 940
10605 schoenebeck 575 </p>
10606     <p>/ AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
10607 schoenebeck 940
10608 schoenebeck 575 </p>
10609     <p>/ MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index SP midi_input_channel_index
10610 schoenebeck 940
10611 schoenebeck 575 </p>
10612     <p>/ MIDI_INPUT_DEVICE SP sampler_channel SP device_index
10613 schoenebeck 940
10614 schoenebeck 575 </p>
10615     <p>/ MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
10616 schoenebeck 940
10617 schoenebeck 575 </p>
10618     <p>/ MIDI_INPUT_CHANNEL SP sampler_channel SP midi_input_channel_index
10619 schoenebeck 940
10620 schoenebeck 575 </p>
10621     <p>/ MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
10622 schoenebeck 940
10623 schoenebeck 575 </p>
10624     <p>/ VOLUME SP sampler_channel SP volume_value
10625 schoenebeck 940
10626 schoenebeck 575 </p>
10627 schoenebeck 708 <p>/ MUTE SP sampler_channel SP boolean
10628 schoenebeck 940
10629 schoenebeck 708 </p>
10630     <p>/ SOLO SP sampler_channel SP boolean
10631 schoenebeck 940
10632 schoenebeck 708 </p>
10633 schoenebeck 974 <p>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP midi_map
10634    
10635     </p>
10636     <p>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP NONE
10637    
10638     </p>
10639     <p>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP DEFAULT
10640    
10641     </p>
10642 schoenebeck 708 </blockquote><p>
10643    
10644     </p>
10645 schoenebeck 1251 <p>edit_instruction =
10646     </p>
10647     <blockquote class="text">
10648 schoenebeck 1430 <p>CHANNEL SP INSTRUMENT SP sampler_channel
10649 schoenebeck 1251
10650     </p>
10651     </blockquote><p>
10652    
10653     </p>
10654 schoenebeck 1363 <p>format_instruction =
10655     </p>
10656     <blockquote class="text">
10657     <p>INSTRUMENTS_DB
10658    
10659     </p>
10660     </blockquote><p>
10661    
10662     </p>
10663 schoenebeck 1048 <p>modal_arg =
10664     </p>
10665     <blockquote class="text">
10666     <p>/* epsilon (empty argument) */
10667    
10668     </p>
10669     <p>/ NON_MODAL SP
10670    
10671     </p>
10672     </blockquote><p>
10673    
10674     </p>
10675 schoenebeck 575 <p>key_val_list =
10676     </p>
10677     <blockquote class="text">
10678     <p>string '=' param_val_list
10679 schoenebeck 940
10680 schoenebeck 575 </p>
10681     <p>/ key_val_list SP string '=' param_val_list
10682 schoenebeck 940
10683 schoenebeck 575 </p>
10684 schoenebeck 708 </blockquote><p>
10685 schoenebeck 575
10686 schoenebeck 708 </p>
10687 schoenebeck 575 <p>buffer_size_type =
10688     </p>
10689     <blockquote class="text">
10690     <p>BYTES
10691 schoenebeck 940
10692 schoenebeck 575 </p>
10693     <p>/ PERCENTAGE
10694 schoenebeck 940
10695 schoenebeck 575 </p>
10696 schoenebeck 708 </blockquote><p>
10697 schoenebeck 575
10698 schoenebeck 708 </p>
10699 schoenebeck 575 <p>list_instruction =
10700     </p>
10701     <blockquote class="text">
10702     <p>AUDIO_OUTPUT_DEVICES
10703 schoenebeck 940
10704 schoenebeck 575 </p>
10705     <p>/ MIDI_INPUT_DEVICES
10706 schoenebeck 940
10707 schoenebeck 575 </p>
10708     <p>/ CHANNELS
10709 schoenebeck 940
10710 schoenebeck 575 </p>
10711     <p>/ AVAILABLE_ENGINES
10712 schoenebeck 940
10713 schoenebeck 575 </p>
10714     <p>/ AVAILABLE_MIDI_INPUT_DRIVERS
10715 schoenebeck 940
10716 schoenebeck 575 </p>
10717     <p>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
10718 schoenebeck 940
10719 schoenebeck 575 </p>
10720 schoenebeck 974 <p>/ MIDI_INSTRUMENTS SP midi_map
10721 schoenebeck 945
10722     </p>
10723 schoenebeck 974 <p>/ MIDI_INSTRUMENTS SP ALL
10724    
10725     </p>
10726     <p>/ MIDI_INSTRUMENT_MAPS
10727    
10728     </p>
10729 schoenebeck 1002 <p>/ FX_SENDS SP sampler_channel
10730    
10731     </p>
10732 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
10733 iliev 1189
10734     </p>
10735 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORIES SP db_path
10736 iliev 1162
10737     </p>
10738 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
10739 iliev 1189
10740     </p>
10741 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP db_path
10742 iliev 1162
10743     </p>
10744 schoenebeck 1572 <p>/ FILE SP INSTRUMENTS SP filename
10745    
10746     </p>
10747 schoenebeck 708 </blockquote><p>
10748 schoenebeck 575
10749 schoenebeck 708 </p>
10750 iliev 1773 <p>send_instruction =
10751     </p>
10752     <blockquote class="text">
10753     <p>CHANNEL SP MIDI_DATA SP string SP sampler_channel SP number SP number
10754    
10755     </p>
10756     </blockquote><p>
10757    
10758     </p>
10759 schoenebeck 575 <p>load_instr_args =
10760     </p>
10761     <blockquote class="text">
10762     <p>filename SP instrument_index SP sampler_channel
10763 schoenebeck 940
10764 schoenebeck 575 </p>
10765     <p>/ NON_MODAL SP filename SP instrument_index SP sampler_channel
10766 schoenebeck 940
10767 schoenebeck 575 </p>
10768 schoenebeck 708 </blockquote><p>
10769 schoenebeck 575
10770 schoenebeck 708 </p>
10771 schoenebeck 575 <p>load_engine_args =
10772     </p>
10773     <blockquote class="text">
10774     <p>engine_name SP sampler_channel
10775 schoenebeck 940
10776 schoenebeck 575 </p>
10777 schoenebeck 708 </blockquote><p>
10778 schoenebeck 575
10779 schoenebeck 708 </p>
10780 schoenebeck 945 <p>instr_load_mode =
10781     </p>
10782     <blockquote class="text">
10783     <p>ON_DEMAND
10784    
10785     </p>
10786     <p>/ ON_DEMAND_HOLD
10787    
10788     </p>
10789     <p>/ PERSISTENT
10790    
10791     </p>
10792     </blockquote><p>
10793    
10794     </p>
10795 schoenebeck 575 <p>device_index =
10796     </p>
10797     <blockquote class="text">
10798     <p>number
10799 schoenebeck 940
10800 schoenebeck 575 </p>
10801 schoenebeck 708 </blockquote><p>
10802 schoenebeck 575
10803 schoenebeck 708 </p>
10804 schoenebeck 575 <p>audio_channel_index =
10805     </p>
10806     <blockquote class="text">
10807     <p>number
10808 schoenebeck 940
10809 schoenebeck 575 </p>
10810 schoenebeck 708 </blockquote><p>
10811 schoenebeck 575
10812 schoenebeck 708 </p>
10813 schoenebeck 575 <p>audio_output_type_name =
10814     </p>
10815     <blockquote class="text">
10816     <p>string
10817 schoenebeck 940
10818 schoenebeck 575 </p>
10819 schoenebeck 708 </blockquote><p>
10820 schoenebeck 575
10821 schoenebeck 708 </p>
10822 schoenebeck 575 <p>midi_input_port_index =
10823     </p>
10824     <blockquote class="text">
10825     <p>number
10826 schoenebeck 940
10827 schoenebeck 575 </p>
10828 schoenebeck 708 </blockquote><p>
10829 schoenebeck 575
10830 schoenebeck 708 </p>
10831 schoenebeck 575 <p>midi_input_channel_index =
10832     </p>
10833     <blockquote class="text">
10834     <p>number
10835 schoenebeck 940
10836 schoenebeck 575 </p>
10837     <p>/ ALL
10838 schoenebeck 940
10839 schoenebeck 575 </p>
10840 schoenebeck 708 </blockquote><p>
10841 schoenebeck 575
10842 schoenebeck 708 </p>
10843 schoenebeck 575 <p>midi_input_type_name =
10844     </p>
10845     <blockquote class="text">
10846     <p>string
10847 schoenebeck 940
10848 schoenebeck 575 </p>
10849 schoenebeck 708 </blockquote><p>
10850 schoenebeck 575
10851 schoenebeck 708 </p>
10852 schoenebeck 974 <p>midi_map =
10853 schoenebeck 945 </p>
10854     <blockquote class="text">
10855     <p>number
10856    
10857     </p>
10858     </blockquote><p>
10859    
10860     </p>
10861 schoenebeck 974 <p>midi_bank =
10862 schoenebeck 945 </p>
10863     <blockquote class="text">
10864     <p>number
10865    
10866     </p>
10867     </blockquote><p>
10868    
10869     </p>
10870     <p>midi_prog =
10871     </p>
10872     <blockquote class="text">
10873     <p>number
10874    
10875     </p>
10876     </blockquote><p>
10877    
10878     </p>
10879 schoenebeck 1002 <p>midi_ctrl =
10880     </p>
10881     <blockquote class="text">
10882     <p>number
10883    
10884     </p>
10885     </blockquote><p>
10886    
10887     </p>
10888 schoenebeck 575 <p>volume_value =
10889     </p>
10890     <blockquote class="text">
10891     <p>dotnum
10892 schoenebeck 940
10893 schoenebeck 575 </p>
10894     <p>/ number
10895 schoenebeck 940
10896 schoenebeck 575 </p>
10897 schoenebeck 708 </blockquote><p>
10898 schoenebeck 575
10899 schoenebeck 708 </p>
10900 schoenebeck 575 <p>sampler_channel =
10901     </p>
10902     <blockquote class="text">
10903     <p>number
10904 schoenebeck 940
10905 schoenebeck 575 </p>
10906 schoenebeck 708 </blockquote><p>
10907 schoenebeck 575
10908 schoenebeck 708 </p>
10909 schoenebeck 575 <p>instrument_index =
10910     </p>
10911     <blockquote class="text">
10912     <p>number
10913 schoenebeck 940
10914 schoenebeck 575 </p>
10915 schoenebeck 708 </blockquote><p>
10916 schoenebeck 575
10917 schoenebeck 708 </p>
10918 schoenebeck 1002 <p>fx_send_id =
10919     </p>
10920     <blockquote class="text">
10921     <p>number
10922    
10923     </p>
10924     </blockquote><p>
10925    
10926     </p>
10927 schoenebeck 575 <p>engine_name =
10928     </p>
10929     <blockquote class="text">
10930     <p>string
10931 schoenebeck 940
10932 schoenebeck 575 </p>
10933 schoenebeck 708 </blockquote><p>
10934 schoenebeck 575
10935 schoenebeck 708 </p>
10936 schoenebeck 1363 <p>filename =
10937 iliev 1162 </p>
10938     <blockquote class="text">
10939 schoenebeck 1363 <p>path
10940 iliev 1162
10941     </p>
10942     </blockquote><p>
10943    
10944     </p>
10945 schoenebeck 1363 <p>db_path =
10946 iliev 1162 </p>
10947     <blockquote class="text">
10948 schoenebeck 1363 <p>path
10949 iliev 1162
10950     </p>
10951     </blockquote><p>
10952    
10953     </p>
10954 schoenebeck 974 <p>map_name =
10955     </p>
10956     <blockquote class="text">
10957 schoenebeck 1390 <p>stringval_escaped
10958 schoenebeck 974
10959     </p>
10960     </blockquote><p>
10961    
10962     </p>
10963 schoenebeck 945 <p>entry_name =
10964     </p>
10965     <blockquote class="text">
10966 schoenebeck 1390 <p>stringval_escaped
10967 schoenebeck 945
10968     </p>
10969     </blockquote><p>
10970    
10971     </p>
10972 schoenebeck 1002 <p>fx_send_name =
10973     </p>
10974     <blockquote class="text">
10975 schoenebeck 1390 <p>stringval_escaped
10976 schoenebeck 1002
10977     </p>
10978     </blockquote><p>
10979    
10980     </p>
10981 schoenebeck 575 <p>param_val_list =
10982     </p>
10983     <blockquote class="text">
10984     <p>param_val
10985 schoenebeck 940
10986 schoenebeck 575 </p>
10987     <p>/ param_val_list','param_val
10988 schoenebeck 940
10989 schoenebeck 575 </p>
10990 schoenebeck 708 </blockquote><p>
10991 schoenebeck 575
10992 schoenebeck 708 </p>
10993 schoenebeck 575 <p>param_val =
10994     </p>
10995     <blockquote class="text">
10996     <p>string
10997 schoenebeck 940
10998 schoenebeck 575 </p>
10999 schoenebeck 940 <p>/ stringval
11000    
11001 schoenebeck 575 </p>
11002     <p>/ number
11003 schoenebeck 940
11004 schoenebeck 575 </p>
11005     <p>/ dotnum
11006 schoenebeck 940
11007 schoenebeck 575 </p>
11008 schoenebeck 708 </blockquote><p>
11009 schoenebeck 575
11010 schoenebeck 708 </p>
11011 iliev 1189 <p>query_val_list =
11012     </p>
11013     <blockquote class="text">
11014     <p>string '=' query_val
11015    
11016     </p>
11017     <p>/ query_val_list SP string '=' query_val
11018    
11019     </p>
11020     </blockquote><p>
11021    
11022     </p>
11023     <p>query_val =
11024     </p>
11025     <blockquote class="text">
11026 schoenebeck 1390 <p>text_escaped
11027 iliev 1189
11028     </p>
11029 schoenebeck 1363 <p>/ stringval_escaped
11030 iliev 1189
11031     </p>
11032     </blockquote><p>
11033    
11034     </p>
11035 iliev 1201 <p>scan_mode =
11036     </p>
11037     <blockquote class="text">
11038     <p>RECURSIVE
11039    
11040     </p>
11041     <p>/ NON_RECURSIVE
11042    
11043     </p>
11044     <p>/ FLAT
11045    
11046     </p>
11047     </blockquote><p>
11048    
11049     </p>
11050 schoenebeck 1251 <a name="character_set"></a><br /><hr />
11051     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11052     <a name="rfc.section.7.1"></a><h3>7.1.&nbsp;
11053     Character Set and Escape Sequences</h3>
11054    
11055     <p>Older versions of this protocol up to and including v1.1 only
11056     supported the standard ASCII character set (ASCII code 0 - 127)
11057     <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
11058     however support the Extended ASCII character set (ASCII code
11059     0 - 255). The same group of younger protocols also support
11060     escape sequences, but only for certain, explicitly declared
11061     parts of the protocol. The supported escape sequences are
11062     defined as follows:
11063     </p><table class="full" align="center" border="0" cellpadding="2" cellspacing="2">
11064     <col align="left"><col align="left">
11065     <tr><th align="left">ASCII Character Sequence</th><th align="left">Translated into (Name)</th></tr>
11066     <tr>
11067     <td align="left">\n</td>
11068     <td align="left">new line</td>
11069     </tr>
11070     <tr>
11071     <td align="left">\r</td>
11072     <td align="left">carriage return</td>
11073     </tr>
11074     <tr>
11075     <td align="left">\f</td>
11076     <td align="left">form feed</td>
11077     </tr>
11078     <tr>
11079     <td align="left">\t</td>
11080     <td align="left">horizontal tab</td>
11081     </tr>
11082     <tr>
11083     <td align="left">\v</td>
11084     <td align="left">vertical tab</td>
11085     </tr>
11086     <tr>
11087     <td align="left">\'</td>
11088     <td align="left">apostrophe</td>
11089     </tr>
11090     <tr>
11091     <td align="left">\"</td>
11092     <td align="left">quotation mark</td>
11093     </tr>
11094     <tr>
11095     <td align="left">\\</td>
11096     <td align="left">backslash</td>
11097     </tr>
11098     <tr>
11099     <td align="left">\OOO</td>
11100     <td align="left">three digit octal ASCII code of the character</td>
11101     </tr>
11102     <tr>
11103     <td align="left">\xHH</td>
11104     <td align="left">two digit hex ASCII code of the character</td>
11105     </tr>
11106     </table>
11107 schoenebeck 1801 <br clear="all" />
11108 schoenebeck 1251
11109     <p>Notice: due to the transition of certain parts of the
11110     protocol which now support escape sequences, a slight backward
11111     incompatibility to protocols version v1.1 and younger has been
11112     introduced. The only difference is that in parts of the protocol
11113     where escape characters are now supported, a backslash characters
11114     MUST be escaped as well (that is as double backslash), whereas
11115     in the old versions a single backslash was sufficient.
11116     </p>
11117 schoenebeck 1390 <p>The following LSCP commands support escape sequences as part
11118 schoenebeck 1400 of their filename / path based arguments and / or may contain
11119     a filename / path with escape sequences in their response:
11120 schoenebeck 1390 </p>
11121     <blockquote class="text">
11122     <p><a class='info' href='#LOAD INSTRUMENT'>"LOAD INSTRUMENT"<span> (</span><span class='info'>Loading an instrument</span><span>)</span></a>
11123     </p>
11124 schoenebeck 1400 <p><a class='info' href='#GET CHANNEL INFO'>"GET CHANNEL INFO"<span> (</span><span class='info'>Getting sampler channel information</span><span>)</span></a>
11125     </p>
11126 schoenebeck 1390 <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>
11127     </p>
11128 schoenebeck 1400 <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>
11129     </p>
11130 schoenebeck 1390 <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>
11131     </p>
11132     <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>
11133     </p>
11134     <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>
11135     </p>
11136     <p><a class='info' href='#REMOVE DB_INSTRUMENT'>"REMOVE DB_INSTRUMENT"<span> (</span><span class='info'>Removing an instrument</span><span>)</span></a>
11137     </p>
11138     <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>
11139     </p>
11140     <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>
11141     </p>
11142     <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>
11143     </p>
11144     <p><a class='info' href='#GET DB_INSTRUMENTS'>"GET DB_INSTRUMENTS"<span> (</span><span class='info'>Getting amount of instruments</span><span>)</span></a>
11145     </p>
11146     <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>
11147     </p>
11148     <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>
11149     </p>
11150     <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>
11151     </p>
11152     <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>
11153     </p>
11154     <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>
11155     </p>
11156     <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>
11157     </p>
11158     <p><a class='info' href='#FIND DB_INSTRUMENTS'>"FIND DB_INSTRUMENTS"<span> (</span><span class='info'>Finding instruments</span><span>)</span></a>
11159     </p>
11160     <p><a class='info' href='#FIND DB_INSTRUMENT_DIRECTORIES'>"FIND DB_INSTRUMENT_DIRECTORIES"<span> (</span><span class='info'>Finding directories</span><span>)</span></a>
11161     </p>
11162     <p><a class='info' href='#MOVE DB_INSTRUMENT'>"MOVE DB_INSTRUMENT"<span> (</span><span class='info'>Moving an instrument</span><span>)</span></a>
11163     </p>
11164     <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>
11165     </p>
11166     <p><a class='info' href='#COPY DB_INSTRUMENT'>"COPY DB_INSTRUMENT"<span> (</span><span class='info'>Copying instruments</span><span>)</span></a>
11167     </p>
11168     <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>
11169     </p>
11170 iliev 1731 <p><a class='info' href='#FIND LOST DB_INSTRUMENT_FILES'>"FIND LOST DB_INSTRUMENT_FILES"<span> (</span><span class='info'>Checking for lost instrument files</span><span>)</span></a>
11171     </p>
11172     <p><a class='info' href='#SET DB_INSTRUMENT FILE_PATH'>"SET DB_INSTRUMENT FILE_PATH"<span> (</span><span class='info'>Replacing an instrument file</span><span>)</span></a>
11173     </p>
11174 schoenebeck 1572 <p><a class='info' href='#GET FILE INSTRUMENTS'>"GET FILE INSTRUMENTS"<span> (</span><span class='info'>Retrieving amount of instruments of a file</span><span>)</span></a>
11175     </p>
11176     <p><a class='info' href='#LIST FILE INSTRUMENTS'>"LIST FILE INSTRUMENTS"<span> (</span><span class='info'>Retrieving all instruments of a file</span><span>)</span></a>
11177     </p>
11178     <p><a class='info' href='#GET FILE INSTRUMENT INFO'>"GET FILE INSTRUMENT INFO"<span> (</span><span class='info'>Retrieving informations about one instrument in a file</span><span>)</span></a>
11179     </p>
11180 schoenebeck 1390 </blockquote><p>
11181     Note that the forward slash character ('/') has a special meaning in
11182     filename / path based arguments: it acts as separator of the nodes in
11183     the path, thus if a directory- or filename includes a forward slash
11184     (not intended as path node separator), you MUST escape that slash
11185     either with the respective hex escape sequence ("\x2f") or with the
11186     respective octal escape sequence ("\057").
11187    
11188     </p>
11189     <p>
11190 schoenebeck 1572 Note for Windows: file path arguments in LSCP are expected
11191     to use forward slashes as directory node separator similar
11192     to Unix based operating systems. In contrast to Unix however
11193     a Windows typical drive character is expected to be
11194     prefixed to the path. That is an original Windows file path
11195     like "D:\Sounds\My.gig" would become in LSCP:
11196     "D:/Sounds/My.gig".
11197    
11198     </p>
11199     <p>
11200 schoenebeck 1390 The following LSCP commands even support escape sequences as
11201     part of at least one of their text-based arguments (i.e. entity name,
11202 schoenebeck 1400 description) and / or may contain escape sequences in at least one of
11203     their text-based fields in their response:
11204 schoenebeck 1390 </p>
11205     <blockquote class="text">
11206 schoenebeck 1400 <p><a class='info' href='#GET SERVER INFO'>"GET SERVER INFO"<span> (</span><span class='info'>General sampler informations</span><span>)</span></a>
11207     </p>
11208     <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>
11209     </p>
11210     <p><a class='info' href='#GET CHANNEL INFO'>"GET CHANNEL INFO"<span> (</span><span class='info'>Getting sampler channel information</span><span>)</span></a>
11211     </p>
11212     <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>
11213     </p>
11214     <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>
11215     </p>
11216     <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>
11217     </p>
11218     <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>
11219     </p>
11220     <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>
11221     </p>
11222 schoenebeck 1390 <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>
11223     </p>
11224     <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>
11225     </p>
11226     <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>
11227     </p>
11228 schoenebeck 1430 <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>
11229     </p>
11230 schoenebeck 1390 <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>
11231     </p>
11232     <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>
11233     </p>
11234 schoenebeck 1400 <p><a class='info' href='#FIND DB_INSTRUMENT_DIRECTORIES'>"FIND DB_INSTRUMENT_DIRECTORIES"<span> (</span><span class='info'>Finding directories</span><span>)</span></a>
11235     </p>
11236 schoenebeck 1430 <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>
11237     </p>
11238 schoenebeck 1390 <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>
11239     </p>
11240     <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>
11241     </p>
11242 schoenebeck 1400 <p><a class='info' href='#FIND DB_INSTRUMENTS'>"FIND DB_INSTRUMENTS"<span> (</span><span class='info'>Finding instruments</span><span>)</span></a>
11243 schoenebeck 1390 </p>
11244     </blockquote><p>
11245     Please note that these lists are manually maintained. If you
11246     find a command that also supports escape sequences we forgot to
11247     mention here, please report it!
11248    
11249     </p>
11250 senoner 542 <a name="events"></a><br /><hr />
11251 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11252     <a name="rfc.section.8"></a><h3>8.&nbsp;
11253     Events</h3>
11254 senoner 542
11255     <p>This chapter will describe all currently defined events supported by LinuxSampler.
11256     </p>
11257 iliev 992 <a name="SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT"></a><br /><hr />
11258 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11259     <a name="rfc.section.8.1"></a><h3>8.1.&nbsp;
11260 iliev 992 Number of audio output devices changed</h3>
11261    
11262     <p>Client may want to be notified when the total number of audio output devices on the
11263     back-end changes by issuing the following command:
11264     </p>
11265     <p>
11266     </p>
11267     <blockquote class="text">
11268     <p>SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT
11269     </p>
11270     </blockquote><p>
11271    
11272     </p>
11273     <p>Server will start sending the following notification messages:
11274     </p>
11275     <p>
11276     </p>
11277     <blockquote class="text">
11278     <p>"NOTIFY:AUDIO_OUTPUT_DEVICE_COUNT:&lt;devices&gt;"
11279     </p>
11280     </blockquote><p>
11281    
11282     </p>
11283     <p>where &lt;devices&gt; will be replaced by the new number
11284     of audio output devices.
11285     </p>
11286     <a name="SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO"></a><br /><hr />
11287     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11288     <a name="rfc.section.8.2"></a><h3>8.2.&nbsp;
11289     Audio output device's settings changed</h3>
11290    
11291     <p>Client may want to be notified when changes were made to audio output devices on the
11292     back-end by issuing the following command:
11293     </p>
11294     <p>
11295     </p>
11296     <blockquote class="text">
11297     <p>SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO
11298     </p>
11299     </blockquote><p>
11300    
11301     </p>
11302     <p>Server will start sending the following notification messages:
11303     </p>
11304     <p>
11305     </p>
11306     <blockquote class="text">
11307     <p>"NOTIFY:AUDIO_OUTPUT_DEVICE_INFO:&lt;device-id&gt;"
11308     </p>
11309     </blockquote><p>
11310    
11311     </p>
11312     <p>where &lt;device-id&gt; will be replaced by the numerical ID of the audio output device,
11313     which settings has been changed. The front-end will have to send
11314     the respective command to actually get the audio output device info. Because these messages
11315     will be triggered by LSCP commands issued by other clients rather than real
11316     time events happening on the server, it is believed that an empty notification
11317     message is sufficient here.
11318     </p>
11319     <a name="SUBSCRIBE MIDI_INPUT_DEVICE_COUNT"></a><br /><hr />
11320     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11321     <a name="rfc.section.8.3"></a><h3>8.3.&nbsp;
11322     Number of MIDI input devices changed</h3>
11323    
11324     <p>Client may want to be notified when the total number of MIDI input devices on the
11325     back-end changes by issuing the following command:
11326     </p>
11327     <p>
11328     </p>
11329     <blockquote class="text">
11330     <p>SUBSCRIBE MIDI_INPUT_DEVICE_COUNT
11331     </p>
11332     </blockquote><p>
11333    
11334     </p>
11335     <p>Server will start sending the following notification messages:
11336     </p>
11337     <p>
11338     </p>
11339     <blockquote class="text">
11340     <p>"NOTIFY:MIDI_INPUT_DEVICE_COUNT:&lt;devices&gt;"
11341     </p>
11342     </blockquote><p>
11343    
11344     </p>
11345     <p>where &lt;devices&gt; will be replaced by the new number
11346     of MIDI input devices.
11347     </p>
11348     <a name="SUBSCRIBE MIDI_INPUT_DEVICE_INFO"></a><br /><hr />
11349     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11350     <a name="rfc.section.8.4"></a><h3>8.4.&nbsp;
11351     MIDI input device's settings changed</h3>
11352    
11353     <p>Client may want to be notified when changes were made to MIDI input devices on the
11354     back-end by issuing the following command:
11355     </p>
11356     <p>
11357     </p>
11358     <blockquote class="text">
11359     <p>SUBSCRIBE MIDI_INPUT_DEVICE_INFO
11360     </p>
11361     </blockquote><p>
11362    
11363     </p>
11364     <p>Server will start sending the following notification messages:
11365     </p>
11366     <p>
11367     </p>
11368     <blockquote class="text">
11369     <p>"NOTIFY:MIDI_INPUT_DEVICE_INFO:&lt;device-id&gt;"
11370     </p>
11371     </blockquote><p>
11372    
11373     </p>
11374     <p>where &lt;device-id&gt; will be replaced by the numerical ID of the MIDI input device,
11375     which settings has been changed. The front-end will have to send
11376     the respective command to actually get the MIDI input device info. Because these messages
11377     will be triggered by LSCP commands issued by other clients rather than real
11378     time events happening on the server, it is believed that an empty notification
11379     message is sufficient here.
11380     </p>
11381     <a name="SUBSCRIBE CHANNEL_COUNT"></a><br /><hr />
11382     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11383     <a name="rfc.section.8.5"></a><h3>8.5.&nbsp;
11384 schoenebeck 974 Number of sampler channels changed</h3>
11385 senoner 542
11386     <p>Client may want to be notified when the total number of channels on the
11387     back-end changes by issuing the following command:
11388     </p>
11389 schoenebeck 708 <p>
11390     </p>
11391 senoner 542 <blockquote class="text">
11392 schoenebeck 558 <p>SUBSCRIBE CHANNEL_COUNT
11393 senoner 542 </p>
11394 schoenebeck 708 </blockquote><p>
11395 schoenebeck 940
11396 schoenebeck 708 </p>
11397 senoner 542 <p>Server will start sending the following notification messages:
11398     </p>
11399 schoenebeck 708 <p>
11400     </p>
11401 senoner 542 <blockquote class="text">
11402 schoenebeck 558 <p>"NOTIFY:CHANNEL_COUNT:&lt;channels&gt;"
11403 senoner 542 </p>
11404 schoenebeck 708 </blockquote><p>
11405 schoenebeck 940
11406 schoenebeck 708 </p>
11407 senoner 542 <p>where &lt;channels&gt; will be replaced by the new number
11408     of sampler channels.
11409     </p>
11410 schoenebeck 1685 <a name="SUBSCRIBE CHANNEL_MIDI"></a><br /><hr />
11411     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11412     <a name="rfc.section.8.6"></a><h3>8.6.&nbsp;
11413     MIDI data on a sampler channel arrived</h3>
11414    
11415     <p>Client may want to be notified when MIDI data arrive on sampler channels on
11416     back-end side, by issuing the following command:
11417     </p>
11418     <p>
11419     </p>
11420     <blockquote class="text">
11421     <p>SUBSCRIBE CHANNEL_MIDI
11422     </p>
11423     </blockquote><p>
11424    
11425     </p>
11426     <p>Server will start sending one of the the following notification messages:
11427     </p>
11428     <p>
11429     </p>
11430     <blockquote class="text">
11431     <p>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_ON &lt;note&gt; &lt;velocity&gt;"
11432     </p>
11433     <p>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"
11434     </p>
11435     </blockquote><p>
11436    
11437     </p>
11438     <p>where &lt;channel-id&gt; will be replaced by the ID of the sampler channel where the MIDI
11439     data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
11440     0 .. 127, reflecting the analog meaning of the MIDI specification.
11441    
11442     </p>
11443     <p>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
11444     delivered by this mechanism! With other words: events could be lost at any time!
11445     This restriction was made to keep the RT-safeness of the backend's MIDI and audio
11446     thread unaffected by this feature.
11447     </p>
11448 schoenebeck 1696 <a name="SUBSCRIBE DEVICE_MIDI"></a><br /><hr />
11449     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11450     <a name="rfc.section.8.7"></a><h3>8.7.&nbsp;
11451     MIDI data on a MIDI input device arrived</h3>
11452    
11453     <p>Client may want to be notified when MIDI data arrive on MIDI input devices by issuing the following command:
11454     </p>
11455     <p>
11456     </p>
11457     <blockquote class="text">
11458     <p>SUBSCRIBE DEVICE_MIDI
11459     </p>
11460     </blockquote><p>
11461    
11462     </p>
11463     <p>Server will start sending one of the the following notification messages:
11464     </p>
11465     <p>
11466     </p>
11467     <blockquote class="text">
11468 iliev 1731 <p>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_ON &lt;note&gt; &lt;velocity&gt;"
11469 schoenebeck 1696 </p>
11470 iliev 1731 <p>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"
11471 schoenebeck 1696 </p>
11472     </blockquote><p>
11473    
11474     </p>
11475     <p>where &lt;device-id&gt; &lt;port-id&gt; will be replaced
11476     by the IDs of the respective MIDI input device and the device's MIDI port where the MIDI
11477     data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
11478     0 .. 127, reflecting the analog meaning of the MIDI specification.
11479    
11480     </p>
11481     <p>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
11482     delivered by this mechanism! With other words: events could be lost at any time!
11483     This restriction was made to keep the RT-safeness of the backend's MIDI and audio
11484     thread unaffected by this feature.
11485     </p>
11486 schoenebeck 940 <a name="SUBSCRIBE VOICE_COUNT"></a><br /><hr />
11487 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11488 schoenebeck 1696 <a name="rfc.section.8.8"></a><h3>8.8.&nbsp;
11489 schoenebeck 974 Number of active voices changed</h3>
11490 senoner 542
11491     <p>Client may want to be notified when the number of voices on the
11492     back-end changes by issuing the following command:
11493     </p>
11494 schoenebeck 708 <p>
11495     </p>
11496 senoner 542 <blockquote class="text">
11497     <p>SUBSCRIBE VOICE_COUNT
11498     </p>
11499 schoenebeck 708 </blockquote><p>
11500 schoenebeck 940
11501 schoenebeck 708 </p>
11502 senoner 542 <p>Server will start sending the following notification messages:
11503     </p>
11504 schoenebeck 708 <p>
11505     </p>
11506 senoner 542 <blockquote class="text">
11507 iliev 1110 <p>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;"
11508 senoner 542 </p>
11509 schoenebeck 708 </blockquote><p>
11510 schoenebeck 940
11511 schoenebeck 708 </p>
11512 senoner 542 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
11513     voice count change occurred and &lt;voices&gt; by the new number of
11514     active voices on that channel.
11515     </p>
11516 schoenebeck 940 <a name="SUBSCRIBE STREAM_COUNT"></a><br /><hr />
11517 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11518 schoenebeck 1696 <a name="rfc.section.8.9"></a><h3>8.9.&nbsp;
11519 schoenebeck 974 Number of active disk streams changed</h3>
11520 senoner 542
11521     <p>Client may want to be notified when the number of streams on the back-end
11522     changes by issuing the following command: SUBSCRIBE STREAM_COUNT
11523     </p>
11524 schoenebeck 708 <p>
11525     </p>
11526 senoner 542 <blockquote class="text">
11527     <p>SUBSCRIBE STREAM_COUNT
11528     </p>
11529 schoenebeck 708 </blockquote><p>
11530 schoenebeck 940
11531 schoenebeck 708 </p>
11532 senoner 542 <p>Server will start sending the following notification messages:
11533     </p>
11534 schoenebeck 708 <p>
11535     </p>
11536 senoner 542 <blockquote class="text">
11537     <p>"NOTIFY:STREAM_COUNT:&lt;sampler-channel&gt; &lt;streams&gt;"
11538     </p>
11539 schoenebeck 708 </blockquote><p>
11540 schoenebeck 940
11541 schoenebeck 708 </p>
11542 senoner 542 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
11543     stream count change occurred and &lt;streams&gt; by the new number of
11544     active disk streams on that channel.
11545     </p>
11546 schoenebeck 940 <a name="SUBSCRIBE BUFFER_FILL"></a><br /><hr />
11547 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11548 schoenebeck 1696 <a name="rfc.section.8.10"></a><h3>8.10.&nbsp;
11549 schoenebeck 974 Disk stream buffer fill state changed</h3>
11550 senoner 542
11551     <p>Client may want to be notified when the buffer fill state of a disk stream
11552     on the back-end changes by issuing the following command:
11553     </p>
11554 schoenebeck 708 <p>
11555     </p>
11556 senoner 542 <blockquote class="text">
11557     <p>SUBSCRIBE BUFFER_FILL
11558     </p>
11559 schoenebeck 708 </blockquote><p>
11560 schoenebeck 940
11561 schoenebeck 708 </p>
11562 senoner 542 <p>Server will start sending the following notification messages:
11563     </p>
11564 schoenebeck 708 <p>
11565     </p>
11566 senoner 542 <blockquote class="text">
11567     <p>"NOTIFY:BUFFER_FILL:&lt;sampler-channel&gt; &lt;fill-data&gt;"
11568     </p>
11569 schoenebeck 708 </blockquote><p>
11570 schoenebeck 940
11571 schoenebeck 708 </p>
11572 senoner 542 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
11573     buffer fill state change occurred on and &lt;fill-data&gt; will be replaced by the
11574 schoenebeck 974 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>
11575     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.
11576 senoner 542 </p>
11577 iliev 992 <a name="SUBSCRIBE CHANNEL_INFO"></a><br /><hr />
11578 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11579 schoenebeck 1696 <a name="rfc.section.8.11"></a><h3>8.11.&nbsp;
11580 schoenebeck 974 Channel information changed</h3>
11581 senoner 542
11582     <p>Client may want to be notified when changes were made to sampler channels on the
11583 schoenebeck 561 back-end by issuing the following command:
11584 senoner 542 </p>
11585 schoenebeck 708 <p>
11586     </p>
11587 senoner 542 <blockquote class="text">
11588 schoenebeck 558 <p>SUBSCRIBE CHANNEL_INFO
11589 senoner 542 </p>
11590 schoenebeck 708 </blockquote><p>
11591 schoenebeck 940
11592 schoenebeck 708 </p>
11593 senoner 542 <p>Server will start sending the following notification messages:
11594     </p>
11595 schoenebeck 708 <p>
11596     </p>
11597 senoner 542 <blockquote class="text">
11598 schoenebeck 558 <p>"NOTIFY:CHANNEL_INFO:&lt;sampler-channel&gt;"
11599 senoner 542 </p>
11600 schoenebeck 708 </blockquote><p>
11601 schoenebeck 940
11602 schoenebeck 708 </p>
11603 senoner 542 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
11604     channel info change occurred. The front-end will have to send
11605     the respective command to actually get the channel info. Because these messages
11606     will be triggered by LSCP commands issued by other clients rather than real
11607     time events happening on the server, it is believed that an empty notification
11608     message is sufficient here.
11609     </p>
11610 iliev 1110 <a name="SUBSCRIBE FX_SEND_COUNT"></a><br /><hr />
11611     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11612 schoenebeck 1696 <a name="rfc.section.8.12"></a><h3>8.12.&nbsp;
11613 iliev 1110 Number of effect sends changed</h3>
11614    
11615 schoenebeck 1251 <p>Client may want to be notified when the number of effect sends on
11616 iliev 1110 a particular sampler channel is changed by issuing the following command:
11617     </p>
11618     <p>
11619     </p>
11620     <blockquote class="text">
11621     <p>SUBSCRIBE FX_SEND_COUNT
11622     </p>
11623     </blockquote><p>
11624    
11625     </p>
11626     <p>Server will start sending the following notification messages:
11627     </p>
11628     <p>
11629     </p>
11630     <blockquote class="text">
11631     <p>"NOTIFY:FX_SEND_COUNT:&lt;channel-id&gt; &lt;fx-sends&gt;"
11632     </p>
11633     </blockquote><p>
11634    
11635     </p>
11636     <p>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
11637     channel, on which the effect sends number is changed and &lt;fx-sends&gt; will
11638     be replaced by the new number of effect sends on that channel.
11639     </p>
11640     <a name="SUBSCRIBE FX_SEND_INFO"></a><br /><hr />
11641     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11642 schoenebeck 1696 <a name="rfc.section.8.13"></a><h3>8.13.&nbsp;
11643 iliev 1110 Effect send information changed</h3>
11644    
11645     <p>Client may want to be notified when changes were made to effect sends on a
11646     a particular sampler channel by issuing the following command:
11647     </p>
11648     <p>
11649     </p>
11650     <blockquote class="text">
11651     <p>SUBSCRIBE FX_SEND_INFO
11652     </p>
11653     </blockquote><p>
11654    
11655     </p>
11656     <p>Server will start sending the following notification messages:
11657     </p>
11658     <p>
11659     </p>
11660     <blockquote class="text">
11661     <p>"NOTIFY:FX_SEND_INFO:&lt;channel-id&gt; &lt;fx-send-id&gt;"
11662     </p>
11663     </blockquote><p>
11664    
11665     </p>
11666     <p>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
11667     channel, on which an effect send entity is changed and &lt;fx-send-id&gt; will
11668     be replaced by the numerical ID of the changed effect send.
11669     </p>
11670 schoenebeck 940 <a name="SUBSCRIBE TOTAL_VOICE_COUNT"></a><br /><hr />
11671 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11672 schoenebeck 1696 <a name="rfc.section.8.14"></a><h3>8.14.&nbsp;
11673 schoenebeck 974 Total number of active voices changed</h3>
11674 senoner 542
11675 schoenebeck 940 <p>Client may want to be notified when the total number of voices on the
11676     back-end changes by issuing the following command:
11677     </p>
11678     <p>
11679     </p>
11680     <blockquote class="text">
11681     <p>SUBSCRIBE TOTAL_VOICE_COUNT
11682     </p>
11683     </blockquote><p>
11684    
11685     </p>
11686     <p>Server will start sending the following notification messages:
11687     </p>
11688     <p>
11689     </p>
11690     <blockquote class="text">
11691 iliev 1110 <p>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;"
11692 schoenebeck 940 </p>
11693     </blockquote><p>
11694    
11695     </p>
11696     <p>where &lt;voices&gt; will be replaced by the new number of
11697     all currently active voices.
11698     </p>
11699 schoenebeck 1572 <a name="SUBSCRIBE TOTAL_STREAM_COUNT"></a><br /><hr />
11700     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11701 schoenebeck 1696 <a name="rfc.section.8.15"></a><h3>8.15.&nbsp;
11702 schoenebeck 1572 Total number of active disk streams changed</h3>
11703    
11704     <p>Client may want to be notified when the total number of disk streams on the
11705     back-end changes by issuing the following command:
11706     </p>
11707     <p>
11708     </p>
11709     <blockquote class="text">
11710     <p>SUBSCRIBE TOTAL_STREAM_COUNT
11711     </p>
11712     </blockquote><p>
11713    
11714     </p>
11715     <p>Server will start sending the following notification messages:
11716     </p>
11717     <p>
11718     </p>
11719     <blockquote class="text">
11720     <p>"NOTIFY:TOTAL_STREAM_COUNT:&lt;streams&gt;"
11721     </p>
11722     </blockquote><p>
11723    
11724     </p>
11725     <p>where &lt;streams&gt; will be replaced by the new number of
11726     all currently active disk streams.
11727     </p>
11728 iliev 992 <a name="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT"></a><br /><hr />
11729     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11730 schoenebeck 1696 <a name="rfc.section.8.16"></a><h3>8.16.&nbsp;
11731 iliev 992 Number of MIDI instrument maps changed</h3>
11732    
11733     <p>Client may want to be notified when the number of MIDI instrument maps on the
11734     back-end changes by issuing the following command:
11735     </p>
11736     <p>
11737     </p>
11738     <blockquote class="text">
11739     <p>SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT
11740     </p>
11741     </blockquote><p>
11742    
11743     </p>
11744     <p>Server will start sending the following notification messages:
11745     </p>
11746     <p>
11747     </p>
11748     <blockquote class="text">
11749     <p>"NOTIFY:MIDI_INSTRUMENT_MAP_COUNT:&lt;maps&gt;"
11750     </p>
11751     </blockquote><p>
11752    
11753     </p>
11754     <p>where &lt;maps&gt; will be replaced by the new number
11755     of MIDI instrument maps.
11756     </p>
11757     <a name="SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO"></a><br /><hr />
11758     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11759 schoenebeck 1696 <a name="rfc.section.8.17"></a><h3>8.17.&nbsp;
11760 iliev 992 MIDI instrument map information changed</h3>
11761    
11762     <p>Client may want to be notified when changes were made to MIDI instrument maps on the
11763     back-end by issuing the following command:
11764     </p>
11765     <p>
11766     </p>
11767     <blockquote class="text">
11768     <p>SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO
11769     </p>
11770     </blockquote><p>
11771    
11772     </p>
11773     <p>Server will start sending the following notification messages:
11774     </p>
11775     <p>
11776     </p>
11777     <blockquote class="text">
11778     <p>"NOTIFY:MIDI_INSTRUMENT_MAP_INFO:&lt;map-id&gt;"
11779     </p>
11780     </blockquote><p>
11781    
11782     </p>
11783     <p>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
11784     for which information changes occurred. The front-end will have to send
11785     the respective command to actually get the MIDI instrument map info. Because these messages
11786     will be triggered by LSCP commands issued by other clients rather than real
11787     time events happening on the server, it is believed that an empty notification
11788     message is sufficient here.
11789     </p>
11790     <a name="SUBSCRIBE MIDI_INSTRUMENT_COUNT"></a><br /><hr />
11791     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11792 schoenebeck 1696 <a name="rfc.section.8.18"></a><h3>8.18.&nbsp;
11793 iliev 992 Number of MIDI instruments changed</h3>
11794    
11795     <p>Client may want to be notified when the number of MIDI instrument maps on the
11796     back-end changes by issuing the following command:
11797     </p>
11798     <p>
11799     </p>
11800     <blockquote class="text">
11801     <p>SUBSCRIBE MIDI_INSTRUMENT_COUNT
11802     </p>
11803     </blockquote><p>
11804    
11805     </p>
11806     <p>Server will start sending the following notification messages:
11807     </p>
11808     <p>
11809     </p>
11810     <blockquote class="text">
11811     <p>"NOTIFY:MIDI_INSTRUMENT_COUNT:&lt;map-id&gt; &lt;instruments&gt;"
11812     </p>
11813     </blockquote><p>
11814    
11815     </p>
11816     <p>where &lt;map-id&gt; is the numerical ID of the MIDI instrument map, in which
11817     the nuber of instruments has changed and &lt;instruments&gt; will be replaced by
11818     the new number of MIDI instruments in the specified map.
11819     </p>
11820     <a name="SUBSCRIBE MIDI_INSTRUMENT_INFO"></a><br /><hr />
11821     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11822 schoenebeck 1696 <a name="rfc.section.8.19"></a><h3>8.19.&nbsp;
11823 iliev 992 MIDI instrument information changed</h3>
11824    
11825     <p>Client may want to be notified when changes were made to MIDI instruments on the
11826     back-end by issuing the following command:
11827     </p>
11828     <p>
11829     </p>
11830     <blockquote class="text">
11831     <p>SUBSCRIBE MIDI_INSTRUMENT_INFO
11832     </p>
11833     </blockquote><p>
11834    
11835     </p>
11836     <p>Server will start sending the following notification messages:
11837     </p>
11838     <p>
11839     </p>
11840     <blockquote class="text">
11841     <p>"NOTIFY:MIDI_INSTRUMENT_INFO:&lt;map-id&gt; &lt;bank&gt; &lt;program&gt;"
11842     </p>
11843     </blockquote><p>
11844    
11845     </p>
11846     <p>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
11847     in which a MIDI instrument is changed. &lt;bank&gt; and &lt;program&gt; specifies
11848     the location of the changed MIDI instrument in the map. The front-end will have to send
11849     the respective command to actually get the MIDI instrument info. Because these messages
11850     will be triggered by LSCP commands issued by other clients rather than real
11851     time events happening on the server, it is believed that an empty notification
11852     message is sufficient here.
11853     </p>
11854 iliev 1110 <a name="SUBSCRIBE GLOBAL_INFO"></a><br /><hr />
11855     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11856 schoenebeck 1696 <a name="rfc.section.8.20"></a><h3>8.20.&nbsp;
11857 iliev 1110 Global settings changed</h3>
11858    
11859     <p>Client may want to be notified when changes to the global settings
11860     of the sampler were made by issuing the following command:
11861     </p>
11862     <p>
11863     </p>
11864     <blockquote class="text">
11865     <p>SUBSCRIBE GLOBAL_INFO
11866     </p>
11867     </blockquote><p>
11868    
11869     </p>
11870     <p>Server will start sending the following types of notification messages:
11871     </p>
11872     <p>
11873     </p>
11874     <blockquote class="text">
11875     <p>"NOTIFY:GLOBAL_INFO:VOLUME &lt;volume&gt;" - Notifies that the
11876     golbal volume of the sampler is changed, where &lt;volume&gt; will be
11877     replaced by the optional dotted floating point value, reflecting the
11878     new global volume parameter.
11879     </p>
11880     </blockquote><p>
11881 schoenebeck 1801 </p>
11882     <blockquote class="text">
11883     <p>"NOTIFY:GLOBAL_INFO:VOICES &lt;max-voices&gt;" - Notifies that the
11884     golbal limit of the sampler for maximum voices is changed, where
11885     &lt;max-voices&gt; will be an integer value, reflecting the
11886     new global voice limit parameter.
11887     </p>
11888     </blockquote><p>
11889     </p>
11890     <blockquote class="text">
11891     <p>"NOTIFY:GLOBAL_INFO:STREAMS &lt;max-streams&gt;" - Notifies that the
11892     golbal limit of the sampler for maximum disk streams is changed, where
11893     &lt;max-streams&gt; will be an integer value, reflecting the
11894     new global disk streams limit parameter.
11895     </p>
11896     </blockquote><p>
11897 iliev 1110
11898     </p>
11899 iliev 1162 <a name="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT"></a><br /><hr />
11900     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11901 schoenebeck 1696 <a name="rfc.section.8.21"></a><h3>8.21.&nbsp;
11902 iliev 1162 Number of database instrument directories changed</h3>
11903    
11904     <p>Client may want to be notified when the number of instrument
11905     directories in a particular directory in the instruments database
11906     is changed by issuing the following command:
11907     </p>
11908     <p>
11909     </p>
11910     <blockquote class="text">
11911     <p>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT
11912     </p>
11913     </blockquote><p>
11914    
11915     </p>
11916     <p>Server will start sending the following notification messages:
11917     </p>
11918     <p>
11919     </p>
11920     <blockquote class="text">
11921     <p>"NOTIFY:DB_INSTRUMENT_DIRECTORY_COUNT:&lt;dir-path&gt;"
11922     </p>
11923     </blockquote><p>
11924    
11925     </p>
11926     <p>where &lt;dir-path&gt; will be replaced by the absolute path
11927     name of the directory in the instruments database,
11928     in which the number of directories is changed.
11929     </p>
11930     <p>Note that when a non-empty directory is removed, this event
11931     is not sent for the subdirectories in that directory.
11932     </p>
11933     <a name="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO"></a><br /><hr />
11934     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11935 schoenebeck 1696 <a name="rfc.section.8.22"></a><h3>8.22.&nbsp;
11936 iliev 1162 Database instrument directory information changed</h3>
11937    
11938     <p>Client may want to be notified when changes were made to directories
11939     in the instruments database by issuing the following command:
11940     </p>
11941     <p>
11942     </p>
11943     <blockquote class="text">
11944     <p>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO
11945     </p>
11946     </blockquote><p>
11947    
11948     </p>
11949     <p>Server will start sending the following notification messages:
11950     </p>
11951     <p>
11952     </p>
11953     <blockquote class="text">
11954     <p>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:&lt;dir-path&gt;"
11955     </p>
11956     </blockquote><p>
11957    
11958     </p>
11959     <p>where &lt;dir-path&gt; will be replaced by the absolute path name
11960     of the directory, for which information changes occurred. The front-end will have to send
11961     the respective command to actually get the updated directory info. Because these messages
11962     will be triggered by LSCP commands issued by other clients rather than real
11963     time events happening on the server, it is believed that an empty notification
11964     message is sufficient here.
11965     </p>
11966     <p>
11967     </p>
11968     <blockquote class="text">
11969     <p>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:NAME &lt;old-dir-path&gt; &lt;new-name&gt;"
11970     </p>
11971     </blockquote><p>
11972    
11973     </p>
11974     <p>where &lt;old-dir-path&gt; is the old absolute path name of the directory
11975     (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
11976     the new name of the directory, encapsulated into apostrophes.
11977     </p>
11978     <a name="SUBSCRIBE DB_INSTRUMENT_COUNT"></a><br /><hr />
11979     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11980 schoenebeck 1696 <a name="rfc.section.8.23"></a><h3>8.23.&nbsp;
11981 iliev 1162 Number of database instruments changed</h3>
11982    
11983     <p>Client may want to be notified when the number of instruments
11984     in a particular directory in the instruments database
11985     is changed by issuing the following command:
11986     </p>
11987     <p>
11988     </p>
11989     <blockquote class="text">
11990     <p>SUBSCRIBE DB_INSTRUMENT_COUNT
11991     </p>
11992     </blockquote><p>
11993    
11994     </p>
11995     <p>Server will start sending the following notification messages:
11996     </p>
11997     <p>
11998     </p>
11999     <blockquote class="text">
12000     <p>"NOTIFY:DB_INSTRUMENT_COUNT:&lt;dir-path&gt;"
12001     </p>
12002     </blockquote><p>
12003    
12004     </p>
12005     <p>where &lt;dir-path&gt; will be replaced by the absolute path
12006     name of the directory in the instruments database,
12007     in which the number of instruments is changed.
12008     </p>
12009     <p>Note that when a non-empty directory is removed, this event
12010     is not sent for the instruments in that directory.
12011     </p>
12012     <a name="SUBSCRIBE DB_INSTRUMENT_INFO"></a><br /><hr />
12013     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
12014 schoenebeck 1696 <a name="rfc.section.8.24"></a><h3>8.24.&nbsp;
12015 iliev 1162 Database instrument information changed</h3>
12016    
12017     <p>Client may want to be notified when changes were made to instruments
12018     in the instruments database by issuing the following command:
12019     </p>
12020     <p>
12021     </p>
12022     <blockquote class="text">
12023     <p>SUBSCRIBE DB_INSTRUMENT_INFO
12024     </p>
12025     </blockquote><p>
12026    
12027     </p>
12028     <p>Server will start sending the following notification messages:
12029     </p>
12030     <p>
12031     </p>
12032     <blockquote class="text">
12033     <p>"NOTIFY:DB_INSTRUMENT_INFO:&lt;instr-path&gt;"
12034     </p>
12035     </blockquote><p>
12036    
12037     </p>
12038     <p>where &lt;instr-path&gt; will be replaced by the absolute path name
12039     of the instrument, which settings are changed. The front-end will have to send
12040     the respective command to actually get the updated directory info. Because these messages
12041     will be triggered by LSCP commands issued by other clients rather than real
12042     time events happening on the server, it is believed that an empty notification
12043     message is sufficient here.
12044     </p>
12045     <p>
12046     </p>
12047     <blockquote class="text">
12048     <p>"NOTIFY:DB_INSTRUMENT_INFO:NAME &lt;old-instr-path&gt; &lt;new-name&gt;"
12049     </p>
12050     </blockquote><p>
12051    
12052     </p>
12053     <p>where &lt;old-instr-path&gt; is the old absolute path name of the instrument
12054     (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
12055     the new name of the instrument, encapsulated into apostrophes.
12056     </p>
12057 iliev 1201 <a name="SUBSCRIBE DB_INSTRUMENTS_JOB_INFO"></a><br /><hr />
12058     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
12059 schoenebeck 1696 <a name="rfc.section.8.25"></a><h3>8.25.&nbsp;
12060 iliev 1201 Database job status information changed</h3>
12061    
12062     <p>Client may want to be notified when the status of particular database
12063     instruments job is changed by issuing the following command:
12064     </p>
12065     <p>
12066     </p>
12067     <blockquote class="text">
12068     <p>SUBSCRIBE DB_INSTRUMENTS_JOB_INFO
12069     </p>
12070     </blockquote><p>
12071    
12072     </p>
12073     <p>Server will start sending the following notification messages:
12074     </p>
12075     <p>
12076     </p>
12077     <blockquote class="text">
12078     <p>"NOTIFY:DB_INSTRUMENTS_JOB_INFO:&lt;job-id&gt;"
12079     </p>
12080     </blockquote><p>
12081    
12082     </p>
12083     <p>where &lt;job-id&gt; will be replaced by the numerical ID of the job,
12084     which status is changed. The front-end will have to send the respective
12085     command to actually get the status info. Because these messages
12086     will be triggered by LSCP commands issued by other clients rather than real
12087     time events happening on the server, it is believed that an empty notification
12088     message is sufficient here.
12089     </p>
12090 schoenebeck 940 <a name="SUBSCRIBE MISCELLANEOUS"></a><br /><hr />
12091 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
12092 schoenebeck 1696 <a name="rfc.section.8.26"></a><h3>8.26.&nbsp;
12093 schoenebeck 974 Miscellaneous and debugging events</h3>
12094 schoenebeck 940
12095 senoner 542 <p>Client may want to be notified of miscellaneous and debugging events occurring at
12096     the server by issuing the following command:
12097     </p>
12098 schoenebeck 708 <p>
12099     </p>
12100 senoner 542 <blockquote class="text">
12101     <p>SUBSCRIBE MISCELLANEOUS
12102     </p>
12103 schoenebeck 708 </blockquote><p>
12104 schoenebeck 940
12105 schoenebeck 708 </p>
12106 senoner 542 <p>Server will start sending the following notification messages:
12107     </p>
12108 schoenebeck 708 <p>
12109     </p>
12110 senoner 542 <blockquote class="text">
12111     <p>"NOTIFY:MISCELLANEOUS:&lt;string&gt;"
12112     </p>
12113 schoenebeck 708 </blockquote><p>
12114 schoenebeck 940
12115 schoenebeck 708 </p>
12116 senoner 542 <p>where &lt;string&gt; will be replaced by whatever data server
12117     wants to send to the client. Client MAY display this data to the
12118     user AS IS to facilitate debugging.
12119     </p>
12120 schoenebeck 974 <a name="anchor14"></a><br /><hr />
12121     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
12122     <a name="rfc.section.9"></a><h3>9.&nbsp;
12123     Security Considerations</h3>
12124 senoner 542
12125     <p>As there is so far no method of authentication and authorization
12126     defined and so not required for a client applications to succeed to
12127     connect, running LinuxSampler might be a security risk for the host
12128     system the LinuxSampler instance is running on.
12129     </p>
12130 schoenebeck 974 <a name="anchor15"></a><br /><hr />
12131     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
12132     <a name="rfc.section.10"></a><h3>10.&nbsp;
12133     Acknowledgments</h3>
12134 senoner 542
12135     <p>This document has benefited greatly from the comments of the
12136     following people, discussed on the LinuxSampler developer's mailing
12137     list:
12138     </p>
12139 schoenebeck 708 <p>
12140     </p>
12141 senoner 542 <blockquote class="text">
12142     <p>Rui Nuno Capela
12143     </p>
12144     <p>Vladimir Senkov
12145     </p>
12146     <p>Mark Knecht
12147     </p>
12148 schoenebeck 561 <p>Grigor Iliev
12149     </p>
12150 schoenebeck 708 </blockquote><p>
12151 schoenebeck 940
12152 schoenebeck 708 </p>
12153 senoner 542 <a name="rfc.references1"></a><br /><hr />
12154 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
12155 schoenebeck 708 <h3>11.&nbsp;References</h3>
12156 senoner 542 <table width="99%" border="0">
12157 schoenebeck 1251 <tr><td class="author-text" valign="top"><a name="RFC20">[RFC20]</a></td>
12158 schoenebeck 1801 <td class="author-text">UCLA, &ldquo;<a href="http://tools.ietf.org/html/rfc20">ASCII format for Network Interchange</a>,&rdquo; RFC&nbsp;20, 1969.</td></tr>
12159 senoner 542 <tr><td class="author-text" valign="top"><a name="RFC2119">[RFC2119]</a></td>
12160 schoenebeck 1801 <td class="author-text">Bradner, S., &ldquo;<a href="http://tools.ietf.org/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a>,&rdquo; RFC&nbsp;2119, 1997.</td></tr>
12161 schoenebeck 575 <tr><td class="author-text" valign="top"><a name="RFC2234">[RFC2234]</a></td>
12162 schoenebeck 1801 <td class="author-text">Crocker, D. and P. Overell, &ldquo;<a href="http://tools.ietf.org/html/rfc2234">Augmented BNF for Syntax Specifications</a>,&rdquo; RFC&nbsp;2234, 1997.</td></tr>
12163 schoenebeck 575 <tr><td class="author-text" valign="top"><a name="RFC793">[RFC793]</a></td>
12164 schoenebeck 1801 <td class="author-text">Defense Advanced Research Projects Agency, &ldquo;<a href="http://tools.ietf.org/html/rfc793">TRANSMISSION CONTROL PROTOCOL</a>,&rdquo; RFC&nbsp;793, 1981.</td></tr>
12165 senoner 542 </table>
12166    
12167     <a name="rfc.authors"></a><br /><hr />
12168 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
12169 senoner 542 <h3>Author's Address</h3>
12170     <table width="99%" border="0" cellpadding="0" cellspacing="0">
12171     <tr><td class="author-text">&nbsp;</td>
12172     <td class="author-text">C.
12173     Schoenebeck</td></tr>
12174     <tr><td class="author-text">&nbsp;</td>
12175     <td class="author-text">Interessengemeinschaft Software Engineering e. V.</td></tr>
12176     <tr><td class="author-text">&nbsp;</td>
12177     <td class="author-text">Max-Planck-Str. 39</td></tr>
12178     <tr><td class="author-text">&nbsp;</td>
12179     <td class="author-text">74081 Heilbronn</td></tr>
12180     <tr><td class="author-text">&nbsp;</td>
12181     <td class="author-text">Germany</td></tr>
12182 schoenebeck 708 <tr><td class="author" align="right">Email:&nbsp;</td>
12183 senoner 542 <td class="author-text"><a href="mailto:schoenebeck at software minus engineering dot org">schoenebeck at software minus engineering dot org</a></td></tr>
12184     </table>
12185     <a name="rfc.copyright"></a><br /><hr />
12186 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
12187     <h3>Full Copyright Statement</h3>
12188 senoner 542 <p class='copyright'>
12189 schoenebeck 1685 Copyright &copy; The IETF Trust (2008).</p>
12190 senoner 542 <p class='copyright'>
12191 schoenebeck 974 This document is subject to the rights,
12192     licenses and restrictions contained in BCP&nbsp;78,
12193     and except as set forth therein,
12194     the authors retain all their rights.</p>
12195 senoner 542 <p class='copyright'>
12196 schoenebeck 974 This document and the information contained herein are provided
12197     on an &ldquo;AS IS&rdquo; basis and THE CONTRIBUTOR,
12198 iliev 1110 THE ORGANIZATION HE/SHE REPRESENTS
12199     OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST
12200     AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES,
12201     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT
12202     THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY
12203     IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
12204     PURPOSE.</p>
12205 schoenebeck 974 <h3>Intellectual Property</h3>
12206 senoner 542 <p class='copyright'>
12207 schoenebeck 974 The IETF takes no position regarding the validity or scope of any
12208     Intellectual Property Rights or other rights that might be claimed
12209     to pertain to the implementation or use of the technology
12210     described in this document or the extent to which any license
12211     under such rights might or might not be available; nor does it
12212     represent that it has made any independent effort to identify any
12213     such rights.
12214     Information on the procedures with respect to
12215     rights in RFC documents can be found in BCP&nbsp;78 and BCP&nbsp;79.</p>
12216 senoner 542 <p class='copyright'>
12217 schoenebeck 974 Copies of IPR disclosures made to the IETF Secretariat and any
12218     assurances of licenses to be made available,
12219     or the result of an attempt made to obtain a general license or
12220     permission for the use of such proprietary rights by implementers or
12221     users of this specification can be obtained from the IETF on-line IPR
12222     repository at <a href='http://www.ietf.org/ipr'>http://www.ietf.org/ipr</a>.</p>
12223 senoner 542 <p class='copyright'>
12224 schoenebeck 974 The IETF invites any interested party to bring to its attention
12225     any copyrights,
12226     patents or patent applications,
12227     or other
12228     proprietary rights that may cover technology that may be required
12229     to implement this standard.
12230     Please address the information to the IETF at <a href='mailto:ietf-ipr@ietf.org'>ietf-ipr@ietf.org</a>.</p>
12231 senoner 542 </body></html>
12232 schoenebeck 1801

  ViewVC Help
Powered by ViewVC