/[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 1805 - (hide annotations) (download) (as text)
Wed Dec 10 22:10:17 2008 UTC (15 years, 3 months ago) by schoenebeck
File MIME type: text/html
File size: 431097 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 1805 <tr><td class="header">Expires: June 13, 2009</td><td class="header">December 10, 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 1805 This Internet-Draft will expire on June 13, 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 schoenebeck 1805 the audio signal, "-1" if there's no device
4000 senoner 542 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 schoenebeck 1805 <p>the instrument index number of the loaded instrument,
4043     "-1" if there's no instrument loaded for this sampler
4044     channel
4045 senoner 542 </p>
4046 schoenebeck 940 </blockquote>
4047    
4048 senoner 542
4049     <p>INSTRUMENT_NAME -
4050     </p>
4051     <blockquote class="text">
4052     <p>the instrument name of the loaded instrument
4053 schoenebeck 1400 (note: since LSCP 1.2 this character string may contain
4054     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>)
4055 senoner 542 </p>
4056 schoenebeck 940 </blockquote>
4057    
4058 senoner 542
4059     <p>INSTRUMENT_STATUS -
4060     </p>
4061     <blockquote class="text">
4062 schoenebeck 1805 <p>Integer values 0 to 100 indicating loading progress
4063     percentage for the instrument. Negative
4064     value indicates a loading exception (also returns "-1" in case no
4065     instrument was yet to be loaded on the sampler channel).
4066     Value of 100 indicates that the instrument is fully
4067 senoner 542 loaded.
4068     </p>
4069 schoenebeck 940 </blockquote>
4070    
4071 senoner 542
4072     <p>MIDI_INPUT_DEVICE -
4073     </p>
4074     <blockquote class="text">
4075     <p>numerical ID of the MIDI input device which is
4076     currently connected to this sampler channel to deliver
4077 schoenebeck 1805 MIDI input commands, "-1" if there's no device
4078 senoner 542 connected to this sampler channel
4079     </p>
4080 schoenebeck 940 </blockquote>
4081    
4082 senoner 542
4083     <p>MIDI_INPUT_PORT -
4084     </p>
4085     <blockquote class="text">
4086 schoenebeck 1805 <p>port number of the MIDI input device (in case a
4087     MIDI device was already assigned to the sampler
4088     channel)
4089 senoner 542 </p>
4090 schoenebeck 940 </blockquote>
4091    
4092 senoner 542
4093     <p>MIDI_INPUT_CHANNEL -
4094     </p>
4095     <blockquote class="text">
4096     <p>the MIDI input channel number this sampler channel
4097     should listen to or "ALL" to listen on all MIDI channels
4098     </p>
4099 schoenebeck 940 </blockquote>
4100    
4101 senoner 542
4102     <p>VOLUME -
4103     </p>
4104     <blockquote class="text">
4105     <p>optionally dotted number for the channel volume factor
4106 schoenebeck 1028 (where a value &lt; 1.0 means attenuation and a value >
4107 senoner 542 1.0 means amplification)
4108     </p>
4109 schoenebeck 940 </blockquote>
4110    
4111 senoner 542
4112 schoenebeck 708 <p>MUTE -
4113     </p>
4114     <blockquote class="text">
4115     <p>Determines whether the channel is muted, "true" if the
4116     channel is muted, "false" if the channel is not muted, and
4117     "MUTED_BY_SOLO" if the channel is muted because of the
4118     presence of a solo channel and will be unmuted when
4119     there are no solo channels left
4120     </p>
4121 schoenebeck 940 </blockquote>
4122    
4123 senoner 542
4124 schoenebeck 708 <p>SOLO -
4125     </p>
4126     <blockquote class="text">
4127     <p>Determines whether this is a solo channel, "true" if
4128     the channel is a solo channel; "false" otherwise
4129     </p>
4130 schoenebeck 940 </blockquote>
4131    
4132 senoner 542
4133 schoenebeck 974 <p>MIDI_INSTRUMENT_MAP -
4134     </p>
4135     <blockquote class="text">
4136     <p>Determines to which MIDI instrument map this sampler
4137     channel is assigned to. Read chapter
4138     <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>
4139     for a list of possible values.
4140     </p>
4141 schoenebeck 940 </blockquote>
4142 schoenebeck 974
4143    
4144     </blockquote>
4145 schoenebeck 940
4146 schoenebeck 708
4147     </blockquote><p>
4148 schoenebeck 940
4149 schoenebeck 708 </p>
4150 senoner 542 <p>The mentioned fields above don't have to be in particular order.
4151     </p>
4152     <p>Example:
4153     </p>
4154 schoenebeck 708 <p>
4155     </p>
4156 senoner 542 <blockquote class="text">
4157     <p>C: "GET CHANNEL INFO 34"
4158     </p>
4159     <p>S: "ENGINE_NAME: GigEngine"
4160     </p>
4161     <p>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"
4162     </p>
4163     <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_DEVICE: 0"
4164     </p>
4165     <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_CHANNELS: 2"
4166     </p>
4167     <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 0,1"
4168     </p>
4169     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"
4170     </p>
4171     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"
4172     </p>
4173     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NAME: Fazioli Piano"
4174     </p>
4175     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_STATUS: 100"
4176     </p>
4177     <p>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_DEVICE: 0"
4178     </p>
4179     <p>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_PORT: 0"
4180     </p>
4181     <p>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_CHANNEL: 5"
4182     </p>
4183 schoenebeck 974 <p>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"
4184     </p>
4185     <p>&nbsp;&nbsp;&nbsp;"MUTE: false"
4186     </p>
4187     <p>&nbsp;&nbsp;&nbsp;"SOLO: false"
4188     </p>
4189     <p>&nbsp;&nbsp;&nbsp;"MIDI_INSTRUMENT_MAP: NONE"
4190     </p>
4191 senoner 542 <p>&nbsp;&nbsp;&nbsp;"."
4192     </p>
4193 schoenebeck 708 </blockquote><p>
4194 schoenebeck 940
4195 schoenebeck 708 </p>
4196 schoenebeck 940 <a name="GET CHANNEL VOICE_COUNT"></a><br /><hr />
4197 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>
4198     <a name="rfc.section.6.4.11"></a><h3>6.4.11.&nbsp;
4199     Current number of active voices</h3>
4200 senoner 542
4201     <p>The front-end can ask for the current number of active voices on a
4202     sampler channel by sending the following command:
4203     </p>
4204 schoenebeck 708 <p>
4205     </p>
4206 senoner 542 <blockquote class="text">
4207     <p>GET CHANNEL VOICE_COUNT &lt;sampler-channel&gt;
4208     </p>
4209 schoenebeck 708 </blockquote><p>
4210 schoenebeck 940
4211 schoenebeck 708 </p>
4212 schoenebeck 575 <p>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
4213 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>
4214     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.
4215 senoner 542 </p>
4216     <p>Possible Answers:
4217     </p>
4218 schoenebeck 708 <p>
4219     </p>
4220 senoner 542 <blockquote class="text">
4221     <p>LinuxSampler will answer by returning the number of active
4222     voices on that channel.
4223     </p>
4224 schoenebeck 708 </blockquote><p>
4225 schoenebeck 940
4226 schoenebeck 708 </p>
4227 senoner 542 <p>Example:
4228     </p>
4229 schoenebeck 708 <p>
4230     </p>
4231 senoner 542 <blockquote class="text">
4232     <p>
4233     </p>
4234 schoenebeck 708 </blockquote><p>
4235 schoenebeck 940
4236 schoenebeck 708 </p>
4237 schoenebeck 940 <a name="GET CHANNEL STREAM_COUNT"></a><br /><hr />
4238 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>
4239     <a name="rfc.section.6.4.12"></a><h3>6.4.12.&nbsp;
4240     Current number of active disk streams</h3>
4241 senoner 542
4242     <p>The front-end can ask for the current number of active disk streams
4243     on a sampler channel by sending the following command:
4244     </p>
4245 schoenebeck 708 <p>
4246     </p>
4247 senoner 542 <blockquote class="text">
4248     <p>GET CHANNEL STREAM_COUNT &lt;sampler-channel&gt;
4249     </p>
4250 schoenebeck 708 </blockquote><p>
4251 schoenebeck 940
4252 schoenebeck 708 </p>
4253 schoenebeck 575 <p>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
4254 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>
4255     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.
4256 senoner 542 </p>
4257     <p>Possible Answers:
4258     </p>
4259 schoenebeck 708 <p>
4260     </p>
4261 senoner 542 <blockquote class="text">
4262     <p>LinuxSampler will answer by returning the number of active
4263     disk streams on that channel in case the engine supports disk
4264     streaming, if the engine doesn't support disk streaming it will
4265     return "NA" for not available.
4266     </p>
4267 schoenebeck 708 </blockquote><p>
4268 schoenebeck 940
4269 schoenebeck 708 </p>
4270 senoner 542 <p>Example:
4271     </p>
4272 schoenebeck 708 <p>
4273     </p>
4274 senoner 542 <blockquote class="text">
4275     <p>
4276     </p>
4277 schoenebeck 708 </blockquote><p>
4278 schoenebeck 940
4279 schoenebeck 708 </p>
4280 schoenebeck 940 <a name="GET CHANNEL BUFFER_FILL"></a><br /><hr />
4281 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>
4282     <a name="rfc.section.6.4.13"></a><h3>6.4.13.&nbsp;
4283     Current fill state of disk stream buffers</h3>
4284 senoner 542
4285     <p>The front-end can ask for the current fill state of all disk streams
4286     on a sampler channel by sending the following command:
4287     </p>
4288 schoenebeck 708 <p>
4289     </p>
4290 senoner 542 <blockquote class="text">
4291     <p>GET CHANNEL BUFFER_FILL BYTES &lt;sampler-channel&gt;
4292     </p>
4293 schoenebeck 708 </blockquote><p>
4294 schoenebeck 940
4295 schoenebeck 708 </p>
4296 senoner 542 <p>to get the fill state in bytes or
4297     </p>
4298 schoenebeck 708 <p>
4299     </p>
4300 senoner 542 <blockquote class="text">
4301     <p>GET CHANNEL BUFFER_FILL PERCENTAGE &lt;sampler-channel&gt;
4302     </p>
4303 schoenebeck 708 </blockquote><p>
4304 schoenebeck 940
4305 schoenebeck 708 </p>
4306 senoner 542 <p>to get the fill state in percent, where &lt;sampler-channel&gt; is the
4307 schoenebeck 575 sampler channel number the front-end is interested in
4308 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>
4309     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.
4310 senoner 542 </p>
4311     <p>Possible Answers:
4312     </p>
4313 schoenebeck 708 <p>
4314     </p>
4315 senoner 542 <blockquote class="text">
4316     <p>LinuxSampler will either answer by returning a comma separated
4317     string with the fill state of all disk stream buffers on that
4318     channel or an empty line if there are no active disk streams or
4319     "NA" for *not available* in case the engine which is deployed
4320     doesn't support disk streaming. Each entry in the answer list
4321     will begin with the stream's ID in brackets followed by the
4322     numerical representation of the fill size (either in bytes or
4323     percentage). Note: due to efficiency reasons the fill states in
4324     the response are not in particular order, thus the front-end has
4325     to sort them by itself if necessary.
4326     </p>
4327 schoenebeck 708 </blockquote><p>
4328 schoenebeck 940
4329 schoenebeck 708 </p>
4330 senoner 542 <p>Examples:
4331     </p>
4332 schoenebeck 708 <p>
4333     </p>
4334 senoner 542 <blockquote class="text">
4335     <p>C: "GET CHANNEL BUFFER_FILL BYTES 4"
4336     </p>
4337     <p>S: "[115]420500,[116]510300,[75]110000,[120]230700"
4338     </p>
4339 schoenebeck 708 </blockquote><p>
4340    
4341     </p>
4342 senoner 542 <blockquote class="text">
4343 schoenebeck 708 <p>C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
4344 senoner 542 </p>
4345     <p>S: "[115]90%,[116]98%,[75]40%,[120]62%"
4346     </p>
4347 schoenebeck 708 </blockquote><p>
4348    
4349     </p>
4350 senoner 542 <blockquote class="text">
4351 schoenebeck 708 <p>C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
4352 senoner 542 </p>
4353     <p>S: ""
4354     </p>
4355 schoenebeck 708 </blockquote><p>
4356 schoenebeck 940
4357 schoenebeck 708 </p>
4358 schoenebeck 940 <a name="SET CHANNEL AUDIO_OUTPUT_DEVICE"></a><br /><hr />
4359 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>
4360     <a name="rfc.section.6.4.14"></a><h3>6.4.14.&nbsp;
4361     Setting audio output device</h3>
4362 senoner 542
4363     <p>The front-end can set the audio output device on a specific sampler
4364     channel by sending the following command:
4365     </p>
4366 schoenebeck 708 <p>
4367     </p>
4368 senoner 542 <blockquote class="text">
4369     <p>SET CHANNEL AUDIO_OUTPUT_DEVICE &lt;sampler-channel&gt; &lt;audio-device-id&gt;
4370     </p>
4371 schoenebeck 708 </blockquote><p>
4372 schoenebeck 940
4373 schoenebeck 708 </p>
4374 schoenebeck 575 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4375 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>
4376     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
4377 schoenebeck 575 &lt;audio-device-id&gt; is the numerical ID of the audio output device as given by the
4378 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>
4379     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>
4380 schoenebeck 575 command.
4381 senoner 542 </p>
4382     <p>Possible Answers:
4383     </p>
4384 schoenebeck 708 <p>
4385     </p>
4386 senoner 542 <blockquote class="text">
4387     <p>"OK" -
4388     </p>
4389     <blockquote class="text">
4390     <p>on success
4391     </p>
4392 schoenebeck 940 </blockquote>
4393    
4394 senoner 542
4395     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4396     </p>
4397     <blockquote class="text">
4398     <p>if audio output device was set, but there are noteworthy
4399     issue(s) related, providing an appropriate warning code and
4400     warning message
4401     </p>
4402 schoenebeck 940 </blockquote>
4403    
4404 senoner 542
4405     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4406     </p>
4407     <blockquote class="text">
4408     <p>in case it failed, providing an appropriate error code and error message
4409     </p>
4410 schoenebeck 940 </blockquote>
4411    
4412 senoner 542
4413 schoenebeck 708 </blockquote><p>
4414 schoenebeck 940
4415 schoenebeck 708 </p>
4416 senoner 542 <p>Examples:
4417     </p>
4418 schoenebeck 708 <p>
4419     </p>
4420 senoner 542 <blockquote class="text">
4421     <p>
4422     </p>
4423 schoenebeck 708 </blockquote><p>
4424 schoenebeck 940
4425 schoenebeck 708 </p>
4426 schoenebeck 974 <a name="SET CHANNEL AUDIO_OUTPUT_TYPE"></a><br /><hr />
4427     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4428     <a name="rfc.section.6.4.15"></a><h3>6.4.15.&nbsp;
4429     Setting audio output type</h3>
4430 senoner 542
4431     <p>DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
4432     </p>
4433     <p>The front-end can alter the audio output type on a specific sampler
4434     channel by sending the following command:
4435     </p>
4436 schoenebeck 708 <p>
4437     </p>
4438 senoner 542 <blockquote class="text">
4439     <p>SET CHANNEL AUDIO_OUTPUT_TYPE &lt;sampler-channel&gt; &lt;audio-output-type&gt;
4440     </p>
4441 schoenebeck 708 </blockquote><p>
4442 schoenebeck 940
4443 schoenebeck 708 </p>
4444 senoner 542 <p>Where &lt;audio-output-type&gt; is currently either "ALSA" or "JACK" and
4445     &lt;sampler-channel&gt; is the respective sampler channel number.
4446     </p>
4447     <p>Possible Answers:
4448     </p>
4449 schoenebeck 708 <p>
4450     </p>
4451 senoner 542 <blockquote class="text">
4452     <p>"OK" -
4453     </p>
4454     <blockquote class="text">
4455     <p>on success
4456     </p>
4457 schoenebeck 940 </blockquote>
4458    
4459 senoner 542
4460     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4461     </p>
4462     <blockquote class="text">
4463     <p>if audio output type was set, but there are noteworthy
4464     issue(s) related, providing an appropriate warning code and
4465     warning message
4466     </p>
4467 schoenebeck 940 </blockquote>
4468    
4469 senoner 542
4470     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4471     </p>
4472     <blockquote class="text">
4473     <p>in case it failed, providing an appropriate error code and error message
4474     </p>
4475 schoenebeck 940 </blockquote>
4476    
4477 senoner 542
4478 schoenebeck 708 </blockquote><p>
4479 schoenebeck 940
4480 schoenebeck 708 </p>
4481 senoner 542 <p>Examples:
4482     </p>
4483 schoenebeck 708 <p>
4484     </p>
4485 senoner 542 <blockquote class="text">
4486     <p>
4487     </p>
4488 schoenebeck 708 </blockquote><p>
4489 schoenebeck 940
4490 schoenebeck 708 </p>
4491 schoenebeck 940 <a name="SET CHANNEL AUDIO_OUTPUT_CHANNEL"></a><br /><hr />
4492 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>
4493     <a name="rfc.section.6.4.16"></a><h3>6.4.16.&nbsp;
4494     Setting audio output channel</h3>
4495 senoner 542
4496     <p>The front-end can alter the audio output channel on a specific
4497     sampler channel by sending the following command:
4498     </p>
4499 schoenebeck 708 <p>
4500     </p>
4501 senoner 542 <blockquote class="text">
4502     <p>SET CHANNEL AUDIO_OUTPUT_CHANNEL &lt;sampler-chan&gt; &lt;audio-out&gt; &lt;audio-in&gt;
4503     </p>
4504 schoenebeck 708 </blockquote><p>
4505 schoenebeck 940
4506 schoenebeck 708 </p>
4507 schoenebeck 575 <p>Where &lt;sampler-chan&gt; is the sampler channel number
4508 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>
4509     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
4510 senoner 542 numerical ID of the sampler channel's audio output channel which should be
4511     rerouted and &lt;audio-in&gt; is the numerical ID of the audio channel of the selected audio
4512     output device where &lt;audio-out&gt; should be routed to.
4513     </p>
4514     <p>Possible Answers:
4515     </p>
4516 schoenebeck 708 <p>
4517     </p>
4518 senoner 542 <blockquote class="text">
4519     <p>"OK" -
4520     </p>
4521     <blockquote class="text">
4522     <p>on success
4523     </p>
4524 schoenebeck 940 </blockquote>
4525    
4526 senoner 542
4527     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4528     </p>
4529     <blockquote class="text">
4530     <p>if audio output channel was set, but there are noteworthy
4531     issue(s) related, providing an appropriate warning code and
4532     warning message
4533     </p>
4534 schoenebeck 940 </blockquote>
4535    
4536 senoner 542
4537     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4538     </p>
4539     <blockquote class="text">
4540     <p>in case it failed, providing an appropriate error code and error message
4541     </p>
4542 schoenebeck 940 </blockquote>
4543    
4544 senoner 542
4545 schoenebeck 708 </blockquote><p>
4546 schoenebeck 940
4547 schoenebeck 708 </p>
4548 senoner 542 <p>Examples:
4549     </p>
4550 schoenebeck 708 <p>
4551     </p>
4552 senoner 542 <blockquote class="text">
4553     <p>
4554     </p>
4555 schoenebeck 708 </blockquote><p>
4556 schoenebeck 940
4557 schoenebeck 708 </p>
4558 schoenebeck 940 <a name="SET CHANNEL MIDI_INPUT_DEVICE"></a><br /><hr />
4559 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>
4560     <a name="rfc.section.6.4.17"></a><h3>6.4.17.&nbsp;
4561     Setting MIDI input device</h3>
4562 senoner 542
4563     <p>The front-end can set the MIDI input device on a specific sampler
4564     channel by sending the following command:
4565     </p>
4566 schoenebeck 708 <p>
4567     </p>
4568 senoner 542 <blockquote class="text">
4569     <p>SET CHANNEL MIDI_INPUT_DEVICE &lt;sampler-channel&gt; &lt;midi-device-id&gt;
4570     </p>
4571 schoenebeck 708 </blockquote><p>
4572 schoenebeck 940
4573 schoenebeck 708 </p>
4574 schoenebeck 575 <p>Where &lt;sampler-channel&gt; is the sampler channel number
4575 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>
4576     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
4577 schoenebeck 575 and &lt;midi-device-id&gt; is the numerical ID of the MIDI input device as returned by the
4578 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>
4579     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.
4580 senoner 542 </p>
4581     <p>Possible Answers:
4582     </p>
4583 schoenebeck 708 <p>
4584     </p>
4585 senoner 542 <blockquote class="text">
4586     <p>"OK" -
4587     </p>
4588     <blockquote class="text">
4589     <p>on success
4590     </p>
4591 schoenebeck 940 </blockquote>
4592    
4593 senoner 542
4594     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4595     </p>
4596     <blockquote class="text">
4597     <p>if MIDI input device was set, but there are noteworthy
4598     issue(s) related, providing an appropriate warning code and
4599     warning message
4600     </p>
4601 schoenebeck 940 </blockquote>
4602    
4603 senoner 542
4604     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4605     </p>
4606     <blockquote class="text">
4607     <p>in case it failed, providing an appropriate error code and error message
4608     </p>
4609 schoenebeck 940 </blockquote>
4610    
4611 senoner 542
4612 schoenebeck 708 </blockquote><p>
4613 schoenebeck 940
4614 schoenebeck 708 </p>
4615 senoner 542 <p>Examples:
4616     </p>
4617 schoenebeck 708 <p>
4618     </p>
4619 senoner 542 <blockquote class="text">
4620     <p>
4621     </p>
4622 schoenebeck 708 </blockquote><p>
4623 schoenebeck 940
4624 schoenebeck 708 </p>
4625 schoenebeck 940 <a name="SET CHANNEL MIDI_INPUT_TYPE"></a><br /><hr />
4626 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>
4627     <a name="rfc.section.6.4.18"></a><h3>6.4.18.&nbsp;
4628     Setting MIDI input type</h3>
4629 senoner 542
4630     <p>DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
4631     </p>
4632     <p>The front-end can alter the MIDI input type on a specific sampler
4633     channel by sending the following command:
4634     </p>
4635 schoenebeck 708 <p>
4636     </p>
4637 senoner 542 <blockquote class="text">
4638     <p>SET CHANNEL MIDI_INPUT_TYPE &lt;sampler-channel&gt; &lt;midi-input-type&gt;
4639     </p>
4640 schoenebeck 708 </blockquote><p>
4641 schoenebeck 940
4642 schoenebeck 708 </p>
4643 senoner 542 <p>Where &lt;midi-input-type&gt; is currently only "ALSA" and
4644     &lt;sampler-channel&gt; is the respective sampler channel number.
4645     </p>
4646     <p>Possible Answers:
4647     </p>
4648 schoenebeck 708 <p>
4649     </p>
4650 senoner 542 <blockquote class="text">
4651     <p>"OK" -
4652     </p>
4653     <blockquote class="text">
4654     <p>on success
4655     </p>
4656 schoenebeck 940 </blockquote>
4657    
4658 senoner 542
4659     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4660     </p>
4661     <blockquote class="text">
4662     <p>if MIDI input type was set, but there are noteworthy
4663     issue(s) related, providing an appropriate warning code and
4664     warning message
4665     </p>
4666 schoenebeck 940 </blockquote>
4667    
4668 senoner 542
4669     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4670     </p>
4671     <blockquote class="text">
4672     <p>in case it failed, providing an appropriate error code and error message
4673     </p>
4674 schoenebeck 940 </blockquote>
4675    
4676 senoner 542
4677 schoenebeck 708 </blockquote><p>
4678 schoenebeck 940
4679 schoenebeck 708 </p>
4680 senoner 542 <p>Examples:
4681     </p>
4682 schoenebeck 708 <p>
4683     </p>
4684 senoner 542 <blockquote class="text">
4685     <p>
4686     </p>
4687 schoenebeck 708 </blockquote><p>
4688 schoenebeck 940
4689 schoenebeck 708 </p>
4690 schoenebeck 940 <a name="SET CHANNEL MIDI_INPUT_PORT"></a><br /><hr />
4691 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>
4692     <a name="rfc.section.6.4.19"></a><h3>6.4.19.&nbsp;
4693     Setting MIDI input port</h3>
4694 senoner 542
4695     <p>The front-end can alter the MIDI input port on a specific sampler
4696     channel by sending the following command:
4697     </p>
4698 schoenebeck 708 <p>
4699     </p>
4700 senoner 542 <blockquote class="text">
4701     <p>SET CHANNEL MIDI_INPUT_PORT &lt;sampler-channel&gt; &lt;midi-input-port&gt;
4702     </p>
4703 schoenebeck 708 </blockquote><p>
4704 schoenebeck 940
4705 schoenebeck 708 </p>
4706 senoner 542 <p>Where &lt;midi-input-port&gt; is a MIDI input port number of the
4707     MIDI input device connected to the sampler channel given by
4708     &lt;sampler-channel&gt;.
4709     </p>
4710     <p>Possible Answers:
4711     </p>
4712 schoenebeck 708 <p>
4713     </p>
4714 senoner 542 <blockquote class="text">
4715     <p>"OK" -
4716     </p>
4717     <blockquote class="text">
4718     <p>on success
4719     </p>
4720 schoenebeck 940 </blockquote>
4721    
4722 senoner 542
4723     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4724     </p>
4725     <blockquote class="text">
4726     <p>if MIDI input port was set, but there are noteworthy
4727     issue(s) related, providing an appropriate warning code and
4728     warning message
4729     </p>
4730 schoenebeck 940 </blockquote>
4731    
4732 senoner 542
4733     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4734     </p>
4735     <blockquote class="text">
4736 schoenebeck 561 <p>in case it failed, providing an appropriate error code and error message
4737 senoner 542 </p>
4738 schoenebeck 940 </blockquote>
4739    
4740 senoner 542
4741 schoenebeck 708 </blockquote><p>
4742 schoenebeck 940
4743 schoenebeck 708 </p>
4744 senoner 542 <p>Examples:
4745     </p>
4746 schoenebeck 708 <p>
4747     </p>
4748 senoner 542 <blockquote class="text">
4749     <p>
4750     </p>
4751 schoenebeck 708 </blockquote><p>
4752 schoenebeck 940
4753 schoenebeck 708 </p>
4754 schoenebeck 940 <a name="SET CHANNEL MIDI_INPUT_CHANNEL"></a><br /><hr />
4755 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>
4756     <a name="rfc.section.6.4.20"></a><h3>6.4.20.&nbsp;
4757     Setting MIDI input channel</h3>
4758 senoner 542
4759     <p>The front-end can alter the MIDI channel a sampler channel should
4760     listen to by sending the following command:
4761     </p>
4762 schoenebeck 708 <p>
4763     </p>
4764 senoner 542 <blockquote class="text">
4765     <p>SET CHANNEL MIDI_INPUT_CHANNEL &lt;sampler-channel&gt; &lt;midi-input-chan&gt;
4766     </p>
4767 schoenebeck 708 </blockquote><p>
4768 schoenebeck 940
4769 schoenebeck 708 </p>
4770 senoner 542 <p>Where &lt;midi-input-chan&gt; is the number of the new MIDI input channel where
4771     &lt;sampler-channel&gt; should listen to or "ALL" to listen on all 16 MIDI
4772     channels.
4773     </p>
4774     <p>Possible Answers:
4775     </p>
4776 schoenebeck 708 <p>
4777     </p>
4778 senoner 542 <blockquote class="text">
4779     <p>"OK" -
4780     </p>
4781     <blockquote class="text">
4782     <p>on success
4783     </p>
4784 schoenebeck 940 </blockquote>
4785    
4786 senoner 542
4787     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4788     </p>
4789     <blockquote class="text">
4790     <p>if MIDI input channel was set, but there are noteworthy
4791     issue(s) related, providing an appropriate warning code and
4792     warning message
4793     </p>
4794 schoenebeck 940 </blockquote>
4795    
4796 senoner 542
4797     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4798     </p>
4799     <blockquote class="text">
4800     <p>in case it failed, providing an appropriate error code and error message
4801     </p>
4802 schoenebeck 940 </blockquote>
4803    
4804 senoner 542
4805 schoenebeck 708 </blockquote><p>
4806 schoenebeck 940
4807 schoenebeck 708 </p>
4808 senoner 542 <p>Examples:
4809     </p>
4810 schoenebeck 708 <p>
4811     </p>
4812 senoner 542 <blockquote class="text">
4813     <p>
4814     </p>
4815 schoenebeck 708 </blockquote><p>
4816 schoenebeck 940
4817 schoenebeck 708 </p>
4818 schoenebeck 940 <a name="SET CHANNEL VOLUME"></a><br /><hr />
4819 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>
4820     <a name="rfc.section.6.4.21"></a><h3>6.4.21.&nbsp;
4821     Setting channel volume</h3>
4822 senoner 542
4823     <p>The front-end can alter the volume of a sampler channel by sending
4824     the following command:
4825     </p>
4826 schoenebeck 708 <p>
4827     </p>
4828 senoner 542 <blockquote class="text">
4829     <p>SET CHANNEL VOLUME &lt;sampler-channel&gt; &lt;volume&gt;
4830     </p>
4831 schoenebeck 708 </blockquote><p>
4832 schoenebeck 940
4833 schoenebeck 708 </p>
4834 senoner 542 <p>Where &lt;volume&gt; is an optionally dotted positive number (a value
4835     smaller than 1.0 means attenuation, whereas a value greater than
4836     1.0 means amplification) and &lt;sampler-channel&gt; defines the sampler
4837     channel where this volume factor should be set.
4838     </p>
4839     <p>Possible Answers:
4840     </p>
4841 schoenebeck 708 <p>
4842     </p>
4843 senoner 542 <blockquote class="text">
4844     <p>"OK" -
4845     </p>
4846     <blockquote class="text">
4847     <p>on success
4848     </p>
4849 schoenebeck 940 </blockquote>
4850    
4851 senoner 542
4852     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4853     </p>
4854     <blockquote class="text">
4855     <p>if channel volume was set, but there are noteworthy
4856     issue(s) related, providing an appropriate warning code and
4857     warning message
4858     </p>
4859 schoenebeck 940 </blockquote>
4860    
4861 senoner 542
4862     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4863     </p>
4864     <blockquote class="text">
4865     <p>in case it failed, providing an appropriate error code and error message
4866     </p>
4867 schoenebeck 940 </blockquote>
4868    
4869 senoner 542
4870 schoenebeck 708 </blockquote><p>
4871 schoenebeck 940
4872 schoenebeck 708 </p>
4873 senoner 542 <p>Examples:
4874     </p>
4875 schoenebeck 708 <p>
4876     </p>
4877 senoner 542 <blockquote class="text">
4878     <p>
4879     </p>
4880 schoenebeck 708 </blockquote><p>
4881 schoenebeck 940
4882 schoenebeck 708 </p>
4883 schoenebeck 940 <a name="SET CHANNEL MUTE"></a><br /><hr />
4884 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>
4885     <a name="rfc.section.6.4.22"></a><h3>6.4.22.&nbsp;
4886     Muting a sampler channel</h3>
4887 senoner 542
4888 schoenebeck 708 <p>The front-end can mute/unmute a specific sampler
4889     channel by sending the following command:
4890     </p>
4891     <p>
4892     </p>
4893     <blockquote class="text">
4894     <p>SET CHANNEL MUTE &lt;sampler-channel&gt; &lt;mute&gt;
4895     </p>
4896     </blockquote><p>
4897 schoenebeck 940
4898 schoenebeck 708 </p>
4899     <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4900 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>
4901     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
4902 schoenebeck 708 &lt;mute&gt; should be replaced either by "1" to mute the channel or "0"
4903     to unmute the channel.
4904     </p>
4905     <p>Possible Answers:
4906     </p>
4907     <p>
4908     </p>
4909     <blockquote class="text">
4910     <p>"OK" -
4911     </p>
4912     <blockquote class="text">
4913     <p>on success
4914     </p>
4915 schoenebeck 940 </blockquote>
4916    
4917 schoenebeck 708
4918     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4919     </p>
4920     <blockquote class="text">
4921     <p>if the channel was muted/unmuted, but there are noteworthy
4922     issue(s) related, providing an appropriate warning code and
4923     warning message
4924     </p>
4925 schoenebeck 940 </blockquote>
4926    
4927 schoenebeck 708
4928     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4929     </p>
4930     <blockquote class="text">
4931     <p>in case it failed, providing an appropriate error code and error message
4932     </p>
4933 schoenebeck 940 </blockquote>
4934    
4935 schoenebeck 708
4936     </blockquote><p>
4937 schoenebeck 940
4938 schoenebeck 708 </p>
4939     <p>Examples:
4940     </p>
4941     <p>
4942     </p>
4943     <blockquote class="text">
4944     <p>
4945     </p>
4946     </blockquote><p>
4947 schoenebeck 940
4948 schoenebeck 708 </p>
4949 schoenebeck 940 <a name="SET CHANNEL SOLO"></a><br /><hr />
4950 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>
4951     <a name="rfc.section.6.4.23"></a><h3>6.4.23.&nbsp;
4952     Soloing a sampler channel</h3>
4953 schoenebeck 708
4954     <p>The front-end can solo/unsolo a specific sampler channel
4955     by sending the following command:
4956     </p>
4957     <p>
4958     </p>
4959     <blockquote class="text">
4960     <p>SET CHANNEL SOLO &lt;sampler-channel&gt; &lt;solo&gt;
4961     </p>
4962     </blockquote><p>
4963 schoenebeck 940
4964 schoenebeck 708 </p>
4965     <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4966 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>
4967     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
4968 schoenebeck 708 &lt;solo&gt; should be replaced either by "1" to solo the channel or "0"
4969     to unsolo the channel.
4970     </p>
4971     <p>Possible Answers:
4972     </p>
4973     <p>
4974     </p>
4975     <blockquote class="text">
4976     <p>"OK" -
4977     </p>
4978     <blockquote class="text">
4979     <p>on success
4980     </p>
4981 schoenebeck 940 </blockquote>
4982    
4983 schoenebeck 708
4984     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4985     </p>
4986     <blockquote class="text">
4987     <p>if the channel was soloed/unsoloed, but there are noteworthy
4988     issue(s) related, providing an appropriate warning code and
4989     warning message
4990     </p>
4991 schoenebeck 940 </blockquote>
4992    
4993 schoenebeck 708
4994     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4995     </p>
4996     <blockquote class="text">
4997     <p>in case it failed, providing an appropriate error code and error message
4998     </p>
4999 schoenebeck 940 </blockquote>
5000    
5001 schoenebeck 708
5002     </blockquote><p>
5003 schoenebeck 940
5004 schoenebeck 708 </p>
5005     <p>Examples:
5006     </p>
5007     <p>
5008     </p>
5009     <blockquote class="text">
5010     <p>
5011     </p>
5012     </blockquote><p>
5013 schoenebeck 940
5014 schoenebeck 708 </p>
5015 schoenebeck 974 <a name="SET CHANNEL MIDI_INSTRUMENT_MAP"></a><br /><hr />
5016     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5017     <a name="rfc.section.6.4.24"></a><h3>6.4.24.&nbsp;
5018     Assigning a MIDI instrument map to a sampler channel</h3>
5019    
5020     <p>The front-end can assign a MIDI instrument map to a specific sampler channel
5021     by sending the following command:
5022     </p>
5023     <p>
5024     </p>
5025     <blockquote class="text">
5026     <p>SET CHANNEL MIDI_INSTRUMENT_MAP &lt;sampler-channel&gt; &lt;map&gt;
5027     </p>
5028     </blockquote><p>
5029    
5030     </p>
5031     <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5032     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>
5033     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
5034     &lt;map&gt; can have the following possibilites:
5035     </p>
5036     <p>
5037     </p>
5038     <blockquote class="text">
5039     <p>"NONE" -
5040     </p>
5041     <blockquote class="text">
5042     <p>This is the default setting. In this case
5043     the sampler channel is not assigned any MIDI
5044     instrument map and thus will ignore all MIDI
5045     program change messages.
5046     </p>
5047     </blockquote>
5048    
5049    
5050     <p>"DEFAULT" -
5051     </p>
5052     <blockquote class="text">
5053     <p>The sampler channel will always use the
5054     default MIDI instrument map to handle MIDI
5055     program change messages.
5056     </p>
5057     </blockquote>
5058    
5059    
5060     <p>numeric ID -
5061     </p>
5062     <blockquote class="text">
5063     <p>You can assign a specific MIDI instrument map
5064     by replacing &lt;map&gt; with the respective numeric
5065     ID of the MIDI instrument map as returned by the
5066     <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>
5067     command. Once that map will be deleted, the sampler
5068     channel would fall back to "NONE".
5069     </p>
5070     </blockquote>
5071    
5072    
5073     </blockquote><p>
5074    
5075     </p>
5076     <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>
5077     for details regarding MIDI instrument mapping.
5078     </p>
5079     <p>Possible Answers:
5080     </p>
5081     <p>
5082     </p>
5083     <blockquote class="text">
5084     <p>"OK" -
5085     </p>
5086     <blockquote class="text">
5087     <p>on success
5088     </p>
5089     </blockquote>
5090    
5091    
5092     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5093     </p>
5094     <blockquote class="text">
5095     <p>in case it failed, providing an appropriate error code and error message
5096     </p>
5097     </blockquote>
5098    
5099    
5100     </blockquote><p>
5101    
5102     </p>
5103     <p>Examples:
5104     </p>
5105     <p>
5106     </p>
5107     <blockquote class="text">
5108     <p>
5109     </p>
5110     </blockquote><p>
5111    
5112     </p>
5113 schoenebeck 1002 <a name="CREATE FX_SEND"></a><br /><hr />
5114     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5115     <a name="rfc.section.6.4.25"></a><h3>6.4.25.&nbsp;
5116     Adding an effect send to a sampler channel</h3>
5117    
5118     <p>The front-end can create an additional effect send on a specific sampler channel
5119     by sending the following command:
5120     </p>
5121     <p>
5122     </p>
5123     <blockquote class="text">
5124     <p>CREATE FX_SEND &lt;sampler-channel&gt; &lt;midi-ctrl&gt; [&lt;name&gt;]
5125     </p>
5126     </blockquote><p>
5127    
5128     </p>
5129     <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5130     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>
5131     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
5132     sampler channel on which the effect send should be created on, &lt;midi-ctrl&gt;
5133     is a number between 0..127 defining the MIDI controller which can alter the
5134     effect send level and &lt;name&gt; is an optional argument defining a name
5135 schoenebeck 1390 for the effect send entity. The name does not have to be unique, but MUST be
5136     encapsulated into apostrophes and supports escape sequences as described in chapter
5137     "<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>".
5138 schoenebeck 1002 </p>
5139     <p>By default, that is as initial routing, the effect send's audio channels
5140     are automatically routed to the last audio channels of the sampler channel's
5141     audio output device, that way you can i.e. first increase the amount of audio
5142     channels on the audio output device for having dedicated effect send output
5143     channels and when "CREATE FX_SEND" is called, those channels will automatically
5144     be picked. You can alter the destination channels however with
5145     <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>.
5146    
5147     </p>
5148     <p>Note: Create effect sends on a sampler channel only when needed, because having effect
5149     sends on a sampler channel will decrease runtime performance, because for implementing channel
5150     effect sends, separate (sampler channel local) audio buffers are needed to render and mix
5151     the voices and route the audio signal afterwards to the master outputs and effect send
5152     outputs (along with their respective effect send levels). A sampler channel without effect
5153     sends however can mix its voices directly into the audio output devices's audio buffers
5154     and is thus faster.
5155    
5156     </p>
5157     <p>Possible Answers:
5158     </p>
5159     <p>
5160     </p>
5161     <blockquote class="text">
5162     <p>"OK[&lt;fx-send-id&gt;]" -
5163     </p>
5164     <blockquote class="text">
5165     <p>in case a new effect send could be added to the
5166     sampler channel, where &lt;fx-send-id&gt; reflects the
5167     unique ID of the newly created effect send entity
5168     </p>
5169     </blockquote>
5170    
5171    
5172     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5173     </p>
5174     <blockquote class="text">
5175     <p>when a new effect send could not be added, i.e.
5176     due to invalid parameters
5177     </p>
5178     </blockquote>
5179    
5180    
5181     </blockquote><p>
5182    
5183     </p>
5184     <p>Examples:
5185     </p>
5186     <p>
5187     </p>
5188     <blockquote class="text">
5189     <p>C: "CREATE FX_SEND 0 91 'Reverb Send'"
5190     </p>
5191     <p>S: "OK[0]"
5192     </p>
5193     </blockquote><p>
5194    
5195     </p>
5196     <p>
5197     </p>
5198     <blockquote class="text">
5199     <p>C: "CREATE FX_SEND 0 93"
5200     </p>
5201     <p>S: "OK[1]"
5202     </p>
5203     </blockquote><p>
5204    
5205     </p>
5206     <a name="DESTROY FX_SEND"></a><br /><hr />
5207     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5208     <a name="rfc.section.6.4.26"></a><h3>6.4.26.&nbsp;
5209     Removing an effect send from a sampler channel</h3>
5210    
5211     <p>The front-end can remove an existing effect send on a specific sampler channel
5212     by sending the following command:
5213     </p>
5214     <p>
5215     </p>
5216     <blockquote class="text">
5217     <p>DESTROY FX_SEND &lt;sampler-channel&gt; &lt;fx-send-id&gt;
5218     </p>
5219     </blockquote><p>
5220    
5221     </p>
5222     <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5223     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>
5224     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
5225     sampler channel from which the effect send should be removed from and
5226     &lt;fx-send-id&gt; is the respective effect send number as returned by the
5227     <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>
5228     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.
5229     </p>
5230     <p>Possible Answers:
5231     </p>
5232     <p>
5233     </p>
5234     <blockquote class="text">
5235     <p>"OK" -
5236     </p>
5237     <blockquote class="text">
5238     <p>on success
5239     </p>
5240     </blockquote>
5241    
5242    
5243     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5244     </p>
5245     <blockquote class="text">
5246     <p>in case it failed, providing an appropriate error code and
5247     error message
5248     </p>
5249     </blockquote>
5250    
5251    
5252     </blockquote><p>
5253    
5254     </p>
5255     <p>Example:
5256     </p>
5257     <p>
5258     </p>
5259     <blockquote class="text">
5260     <p>C: "DESTROY FX_SEND 0 0"
5261     </p>
5262     <p>S: "OK"
5263     </p>
5264     </blockquote><p>
5265    
5266     </p>
5267     <a name="GET FX_SENDS"></a><br /><hr />
5268     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5269     <a name="rfc.section.6.4.27"></a><h3>6.4.27.&nbsp;
5270     Getting amount of effect sends on a sampler channel</h3>
5271    
5272     <p>The front-end can ask for the amount of effect sends on a specific sampler channel
5273     by sending the following command:
5274     </p>
5275     <p>
5276     </p>
5277     <blockquote class="text">
5278     <p>GET FX_SENDS &lt;sampler-channel&gt;
5279     </p>
5280     </blockquote><p>
5281    
5282     </p>
5283     <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5284     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>
5285     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.
5286     </p>
5287     <p>Possible Answers:
5288     </p>
5289     <p>
5290     </p>
5291     <blockquote class="text">
5292     <p>The sampler will answer by returning the number of effect
5293     sends on the given sampler channel.
5294     </p>
5295     </blockquote><p>
5296    
5297     </p>
5298     <p>Example:
5299     </p>
5300     <p>
5301     </p>
5302     <blockquote class="text">
5303     <p>C: "GET FX_SENDS 0"
5304     </p>
5305     <p>S: "2"
5306     </p>
5307     </blockquote><p>
5308    
5309     </p>
5310     <a name="LIST FX_SENDS"></a><br /><hr />
5311     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5312     <a name="rfc.section.6.4.28"></a><h3>6.4.28.&nbsp;
5313     Listing all effect sends on a sampler channel</h3>
5314    
5315     <p>The front-end can ask for a list of effect sends on a specific sampler channel
5316     by sending the following command:
5317     </p>
5318     <p>
5319     </p>
5320     <blockquote class="text">
5321     <p>LIST FX_SENDS &lt;sampler-channel&gt;
5322     </p>
5323     </blockquote><p>
5324    
5325     </p>
5326     <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5327     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>
5328     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.
5329     </p>
5330     <p>Possible Answers:
5331     </p>
5332     <p>
5333     </p>
5334     <blockquote class="text">
5335     <p>The sampler will answer by returning a comma separated list
5336     with all effect sends' numerical IDs on the given sampler
5337     channel.
5338     </p>
5339     </blockquote><p>
5340    
5341     </p>
5342     <p>Examples:
5343     </p>
5344     <p>
5345     </p>
5346     <blockquote class="text">
5347     <p>C: "LIST FX_SENDS 0"
5348     </p>
5349     <p>S: "0,1"
5350     </p>
5351     </blockquote><p>
5352    
5353     </p>
5354     <p>
5355     </p>
5356     <blockquote class="text">
5357     <p>C: "LIST FX_SENDS 1"
5358     </p>
5359     <p>S: ""
5360     </p>
5361     </blockquote><p>
5362    
5363     </p>
5364     <a name="GET FX_SEND INFO"></a><br /><hr />
5365     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5366     <a name="rfc.section.6.4.29"></a><h3>6.4.29.&nbsp;
5367     Getting effect send information</h3>
5368    
5369     <p>The front-end can ask for the current settings of an effect send entity
5370     by sending the following command:
5371     </p>
5372     <p>
5373     </p>
5374     <blockquote class="text">
5375     <p>GET FX_SEND INFO &lt;sampler-channel&gt; &lt;fx-send-id&gt;
5376     </p>
5377     </blockquote><p>
5378    
5379     </p>
5380     <p>Where &lt;sampler-channel&gt; is the sampler channel number
5381     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>
5382     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
5383     &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5384     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>
5385     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.
5386    
5387     </p>
5388     <p>Possible Answers:
5389     </p>
5390     <p>
5391     </p>
5392     <blockquote class="text">
5393     <p>The sampler will answer by sending a &lt;CRLF&gt; separated list.
5394     Each answer line begins with the settings category name
5395     followed by a colon and then a space character &lt;SP&gt; and finally
5396     the info character string to that setting category. At the
5397     moment the following categories are defined:
5398     </p>
5399     <p>
5400     </p>
5401     <blockquote class="text">
5402     <p>NAME -
5403     </p>
5404     <blockquote class="text">
5405     <p>name of the effect send entity
5406 schoenebeck 1400 (note that this character string may contain
5407     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>)
5408 schoenebeck 1002 </p>
5409     </blockquote>
5410    
5411    
5412 schoenebeck 1028 <p>MIDI_CONTROLLER -
5413     </p>
5414     <blockquote class="text">
5415     <p>a value between 0 and 127 reflecting the MIDI controller
5416     which is able to modify the effect send's send level
5417     </p>
5418     </blockquote>
5419    
5420    
5421     <p>LEVEL -
5422     </p>
5423     <blockquote class="text">
5424     <p>optionally dotted number reflecting the effect send's
5425     current send level (where a value &lt; 1.0 means attenuation
5426     and a value > 1.0 means amplification)
5427     </p>
5428     </blockquote>
5429    
5430    
5431 schoenebeck 1002 <p>AUDIO_OUTPUT_ROUTING -
5432     </p>
5433     <blockquote class="text">
5434     <p>comma separated list which reflects to which audio
5435     channel of the selected audio output device each
5436     effect send output channel is routed to, e.g. "0,3" would
5437     mean the effect send's output channel 0 is routed to channel
5438     0 of the audio output device and the effect send's output
5439     channel 1 is routed to the channel 3 of the audio
5440     output device (see
5441     <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>
5442     for details)
5443     </p>
5444     </blockquote>
5445    
5446    
5447     </blockquote>
5448    
5449    
5450     </blockquote><p>
5451    
5452     </p>
5453     <p>The mentioned fields above don't have to be in particular order.
5454     </p>
5455     <p>Example:
5456     </p>
5457     <p>
5458     </p>
5459     <blockquote class="text">
5460     <p>C: "GET FX_SEND INFO 0 0"
5461     </p>
5462     <p>S: "NAME: Reverb Send"
5463     </p>
5464 schoenebeck 1028 <p>&nbsp;&nbsp;&nbsp;"MIDI_CONTROLLER: 91"
5465     </p>
5466     <p>&nbsp;&nbsp;&nbsp;"LEVEL: 0.3"
5467     </p>
5468 schoenebeck 1002 <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 2,3"
5469     </p>
5470     <p>&nbsp;&nbsp;&nbsp;"."
5471     </p>
5472     </blockquote><p>
5473    
5474     </p>
5475 iliev 1137 <a name="SET FX_SEND NAME"></a><br /><hr />
5476     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5477     <a name="rfc.section.6.4.30"></a><h3>6.4.30.&nbsp;
5478     Changing effect send's name</h3>
5479    
5480     <p>The front-end can alter the current name of an effect
5481     send entity by sending the following command:
5482     </p>
5483     <p>
5484     </p>
5485     <blockquote class="text">
5486     <p>SET FX_SEND NAME &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;name&gt;
5487     </p>
5488     </blockquote><p>
5489    
5490     </p>
5491     <p>Where &lt;sampler-chan&gt; is the sampler channel number
5492     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>
5493     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,
5494     &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5495     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>
5496     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
5497     &lt;name&gt; is the new name of the effect send entity, which
5498 schoenebeck 1390 does not have to be unique (name MUST be encapsulated into apostrophes
5499     and supports escape sequences as described in chapter
5500     "<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>").
5501    
5502 iliev 1137 </p>
5503     <p>Possible Answers:
5504     </p>
5505     <p>
5506     </p>
5507     <blockquote class="text">
5508     <p>"OK" -
5509     </p>
5510     <blockquote class="text">
5511     <p>on success
5512     </p>
5513     </blockquote>
5514    
5515    
5516     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5517     </p>
5518     <blockquote class="text">
5519     <p>in case it failed, providing an appropriate error code and error message
5520     </p>
5521     </blockquote>
5522    
5523    
5524     </blockquote><p>
5525    
5526     </p>
5527     <p>Example:
5528     </p>
5529     <p>
5530     </p>
5531     <blockquote class="text">
5532     <p>C: "SET FX_SEND NAME 0 0 'Fx Send 1'"
5533     </p>
5534     <p>S: "OK"
5535     </p>
5536     </blockquote><p>
5537    
5538     </p>
5539 schoenebeck 1002 <a name="SET FX_SEND AUDIO_OUTPUT_CHANNEL"></a><br /><hr />
5540     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5541 iliev 1137 <a name="rfc.section.6.4.31"></a><h3>6.4.31.&nbsp;
5542 schoenebeck 1002 Altering effect send's audio routing</h3>
5543    
5544     <p>The front-end can alter the destination of an effect send's audio channel on a specific
5545     sampler channel by sending the following command:
5546     </p>
5547     <p>
5548     </p>
5549     <blockquote class="text">
5550     <p>SET FX_SEND AUDIO_OUTPUT_CHANNEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;audio-src&gt; &lt;audio-dst&gt;
5551     </p>
5552     </blockquote><p>
5553    
5554     </p>
5555     <p>Where &lt;sampler-chan&gt; is the sampler channel number
5556     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>
5557     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,
5558     &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5559     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>
5560     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,
5561     &lt;audio-src&gt; is the numerical ID of the effect send's audio channel
5562     which should be rerouted and &lt;audio-dst&gt; is the numerical ID of
5563     the audio channel of the selected audio output device where &lt;audio-src&gt;
5564     should be routed to.
5565     </p>
5566     <p>Note that effect sends can only route audio to the same audio output
5567     device as assigned to the effect send's sampler channel. Also note that an
5568     effect send entity does always have exactly as much audio channels as its
5569     sampler channel. So if the sampler channel is stereo, the effect send does
5570     have two audio channels as well. Also keep in mind that the amount of audio
5571     channels on a sampler channel might be dependant not only to the deployed
5572     sampler engine on the sampler channel, but also dependant to the instrument
5573     currently loaded. However you can (effectively) turn an i.e. stereo effect
5574     send into a mono one by simply altering its audio routing appropriately.
5575     </p>
5576     <p>Possible Answers:
5577     </p>
5578     <p>
5579     </p>
5580     <blockquote class="text">
5581     <p>"OK" -
5582     </p>
5583     <blockquote class="text">
5584     <p>on success
5585     </p>
5586     </blockquote>
5587    
5588    
5589     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5590     </p>
5591     <blockquote class="text">
5592     <p>if audio output channel was set, but there are noteworthy
5593     issue(s) related, providing an appropriate warning code and
5594     warning message
5595     </p>
5596     </blockquote>
5597    
5598    
5599     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5600     </p>
5601     <blockquote class="text">
5602     <p>in case it failed, providing an appropriate error code and error message
5603     </p>
5604     </blockquote>
5605    
5606    
5607     </blockquote><p>
5608    
5609     </p>
5610     <p>Example:
5611     </p>
5612     <p>
5613     </p>
5614     <blockquote class="text">
5615     <p>C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2"
5616     </p>
5617     <p>S: "OK"
5618     </p>
5619     </blockquote><p>
5620    
5621     </p>
5622 schoenebeck 1028 <a name="SET FX_SEND MIDI_CONTROLLER"></a><br /><hr />
5623     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5624 iliev 1137 <a name="rfc.section.6.4.32"></a><h3>6.4.32.&nbsp;
5625 schoenebeck 1028 Altering effect send's MIDI controller</h3>
5626    
5627     <p>The front-end can alter the MIDI controller of an effect
5628     send entity by sending the following command:
5629     </p>
5630     <p>
5631     </p>
5632     <blockquote class="text">
5633     <p>SET FX_SEND MIDI_CONTROLLER &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;midi-ctrl&gt;
5634     </p>
5635     </blockquote><p>
5636    
5637     </p>
5638     <p>Where &lt;sampler-chan&gt; is the sampler channel number
5639     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>
5640     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,
5641     &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5642     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>
5643     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
5644     &lt;midi-ctrl&gt; reflects the MIDI controller which shall be
5645     able to modify the effect send's send level.
5646     </p>
5647     <p>Possible Answers:
5648     </p>
5649     <p>
5650     </p>
5651     <blockquote class="text">
5652     <p>"OK" -
5653     </p>
5654     <blockquote class="text">
5655     <p>on success
5656     </p>
5657     </blockquote>
5658    
5659    
5660     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5661     </p>
5662     <blockquote class="text">
5663     <p>if MIDI controller was set, but there are noteworthy
5664     issue(s) related, providing an appropriate warning code and
5665     warning message
5666     </p>
5667     </blockquote>
5668    
5669    
5670     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5671     </p>
5672     <blockquote class="text">
5673     <p>in case it failed, providing an appropriate error code and error message
5674     </p>
5675     </blockquote>
5676    
5677    
5678     </blockquote><p>
5679    
5680     </p>
5681     <p>Example:
5682     </p>
5683     <p>
5684     </p>
5685     <blockquote class="text">
5686     <p>C: "SET FX_SEND MIDI_CONTROLLER 0 0 91"
5687     </p>
5688     <p>S: "OK"
5689     </p>
5690     </blockquote><p>
5691    
5692     </p>
5693     <a name="SET FX_SEND LEVEL"></a><br /><hr />
5694     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5695 iliev 1137 <a name="rfc.section.6.4.33"></a><h3>6.4.33.&nbsp;
5696 schoenebeck 1028 Altering effect send's send level</h3>
5697    
5698     <p>The front-end can alter the current send level of an effect
5699     send entity by sending the following command:
5700     </p>
5701     <p>
5702     </p>
5703     <blockquote class="text">
5704     <p>SET FX_SEND LEVEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;volume&gt;
5705     </p>
5706     </blockquote><p>
5707    
5708     </p>
5709     <p>Where &lt;sampler-chan&gt; is the sampler channel number
5710     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>
5711     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,
5712     &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5713     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>
5714     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
5715     &lt;volume&gt; is an optionally dotted positive number (a value
5716     smaller than 1.0 means attenuation, whereas a value greater than
5717     1.0 means amplification) reflecting the new send level.
5718     </p>
5719     <p>Possible Answers:
5720     </p>
5721     <p>
5722     </p>
5723     <blockquote class="text">
5724     <p>"OK" -
5725     </p>
5726     <blockquote class="text">
5727     <p>on success
5728     </p>
5729     </blockquote>
5730    
5731    
5732     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5733     </p>
5734     <blockquote class="text">
5735     <p>if new send level was set, but there are noteworthy
5736     issue(s) related, providing an appropriate warning code and
5737     warning message
5738     </p>
5739     </blockquote>
5740    
5741    
5742     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5743     </p>
5744     <blockquote class="text">
5745     <p>in case it failed, providing an appropriate error code and error message
5746     </p>
5747     </blockquote>
5748    
5749    
5750     </blockquote><p>
5751    
5752     </p>
5753     <p>Example:
5754     </p>
5755     <p>
5756     </p>
5757     <blockquote class="text">
5758     <p>C: "SET FX_SEND LEVEL 0 0 0.15"
5759     </p>
5760     <p>S: "OK"
5761     </p>
5762     </blockquote><p>
5763    
5764     </p>
5765 iliev 1773 <a name="SEND CHANNEL MIDI_DATA"></a><br /><hr />
5766     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5767     <a name="rfc.section.6.4.34"></a><h3>6.4.34.&nbsp;
5768     Sending MIDI messages to sampler channel</h3>
5769    
5770     <p>The front-end can send MIDI events to specific sampler channel
5771     by sending the following command:
5772     </p>
5773     <p>
5774     </p>
5775     <blockquote class="text">
5776     <p>SEND CHANNEL MIDI_DATA &lt;midi-msg&gt; &lt;sampler-chan&gt; &lt;arg1&gt; &lt;arg2&gt;
5777     </p>
5778     </blockquote><p>
5779    
5780     </p>
5781     <p>Where &lt;sampler-chan&gt; is the sampler channel number
5782     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>
5783     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,
5784     &lt;arg1&gt; and &lt;arg2&gt; arguments depend on the &lt;midi-msg&gt; argument, which
5785     specifies the MIDI message type. Currently, the following MIDI messages are supported:
5786     </p>
5787     <p>
5788     </p>
5789     <blockquote class="text">
5790     <p>"NOTE_ON" -
5791     </p>
5792     <blockquote class="text">
5793     <p>For turning on MIDI notes, where &lt;arg1&gt;
5794     specifies the key number and &lt;arg2&gt; the velocity
5795     as described in the MIDI specification.
5796     </p>
5797     </blockquote>
5798    
5799    
5800     <p>"NOTE_OFF" -
5801     </p>
5802     <blockquote class="text">
5803     <p>For turning a currently playing MIDI note off, where &lt;arg1&gt;
5804     specifies the key number and &lt;arg2&gt; the velocity
5805     as described in the MIDI specification.
5806     </p>
5807     </blockquote>
5808    
5809    
5810     </blockquote><p>
5811    
5812     </p>
5813     <p>CAUTION: This command is provided for implementations of virtual MIDI keyboards
5814     and no realtime guarantee whatsoever will be made!
5815     </p>
5816     <p>Possible Answers:
5817     </p>
5818     <p>
5819     </p>
5820     <blockquote class="text">
5821     <p>"OK" -
5822     </p>
5823     <blockquote class="text">
5824     <p>on success
5825     </p>
5826     </blockquote>
5827    
5828    
5829     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5830     </p>
5831     <blockquote class="text">
5832     <p>in case it failed, providing an appropriate error code and error message
5833     </p>
5834     </blockquote>
5835    
5836    
5837     </blockquote><p>
5838    
5839     </p>
5840     <p>Example:
5841     </p>
5842     <p>
5843     </p>
5844     <blockquote class="text">
5845     <p>C: "SEND CHANNEL MIDI_DATA NOTE_ON 0 56 112"
5846     </p>
5847     <p>S: "OK"
5848     </p>
5849     </blockquote><p>
5850    
5851     </p>
5852 schoenebeck 940 <a name="RESET CHANNEL"></a><br /><hr />
5853 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>
5854 iliev 1773 <a name="rfc.section.6.4.35"></a><h3>6.4.35.&nbsp;
5855 schoenebeck 974 Resetting a sampler channel</h3>
5856 schoenebeck 708
5857 senoner 542 <p>The front-end can reset a particular sampler channel by sending the following command:
5858     </p>
5859 schoenebeck 708 <p>
5860     </p>
5861 senoner 542 <blockquote class="text">
5862     <p>RESET CHANNEL &lt;sampler-channel&gt;
5863     </p>
5864 schoenebeck 708 </blockquote><p>
5865 schoenebeck 940
5866 schoenebeck 708 </p>
5867 senoner 542 <p>
5868     Where &lt;sampler-channel&gt; defines the sampler channel to be reset.
5869     This will cause the engine on that sampler channel, its voices and
5870     eventually disk streams and all control and status variables to be
5871     reset.
5872     </p>
5873     <p>Possible Answers:
5874     </p>
5875 schoenebeck 708 <p>
5876     </p>
5877 senoner 542 <blockquote class="text">
5878     <p>"OK" -
5879     </p>
5880     <blockquote class="text">
5881     <p>on success
5882     </p>
5883 schoenebeck 940 </blockquote>
5884    
5885 senoner 542
5886     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5887     </p>
5888     <blockquote class="text">
5889     <p>if channel was reset, but there are noteworthy issue(s)
5890     related, providing an appropriate warning code and warning
5891     message
5892     </p>
5893 schoenebeck 940 </blockquote>
5894    
5895 senoner 542
5896     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5897     </p>
5898     <blockquote class="text">
5899     <p>in case it failed, providing an appropriate error code and
5900     error message
5901     </p>
5902 schoenebeck 940 </blockquote>
5903    
5904 senoner 542
5905 schoenebeck 708 </blockquote><p>
5906 schoenebeck 940
5907 schoenebeck 708 </p>
5908 senoner 542 <p>Examples:
5909     </p>
5910 schoenebeck 708 <p>
5911     </p>
5912 senoner 542 <blockquote class="text">
5913     <p>
5914     </p>
5915 schoenebeck 708 </blockquote><p>
5916 schoenebeck 940
5917 schoenebeck 708 </p>
5918 schoenebeck 940 <a name="anchor12"></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"></a><h3>6.5.&nbsp;
5921     Controlling connection</h3>
5922 senoner 542
5923     <p>The following commands are used to control the connection to LinuxSampler.
5924     </p>
5925 schoenebeck 940 <a name="SUBSCRIBE"></a><br /><hr />
5926 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>
5927     <a name="rfc.section.6.5.1"></a><h3>6.5.1.&nbsp;
5928     Register front-end for receiving event messages</h3>
5929 senoner 542
5930     <p>The front-end can register itself to the LinuxSampler application to
5931     be informed about noteworthy events by sending this command:
5932     </p>
5933 schoenebeck 708 <p>
5934     </p>
5935 senoner 542 <blockquote class="text">
5936     <p>SUBSCRIBE &lt;event-id&gt;
5937     </p>
5938 schoenebeck 708 </blockquote><p>
5939 schoenebeck 940
5940 schoenebeck 708 </p>
5941 senoner 542 <p>where &lt;event-id&gt; will be replaced by the respective event that
5942     client wants to subscribe to.
5943     </p>
5944     <p>Possible Answers:
5945     </p>
5946 schoenebeck 708 <p>
5947     </p>
5948 senoner 542 <blockquote class="text">
5949     <p>"OK" -
5950     </p>
5951     <blockquote class="text">
5952     <p>on success
5953     </p>
5954 schoenebeck 940 </blockquote>
5955    
5956 senoner 542
5957     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5958     </p>
5959     <blockquote class="text">
5960     <p>if registration succeeded, but there are noteworthy
5961     issue(s) related, providing an appropriate warning code and
5962     warning message
5963     </p>
5964 schoenebeck 940 </blockquote>
5965    
5966 senoner 542
5967     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5968     </p>
5969     <blockquote class="text">
5970     <p>in case it failed, providing an appropriate error code and
5971     error message
5972     </p>
5973 schoenebeck 940 </blockquote>
5974    
5975 senoner 542
5976 schoenebeck 708 </blockquote><p>
5977 schoenebeck 940
5978 schoenebeck 708 </p>
5979 senoner 542 <p>Examples:
5980     </p>
5981 schoenebeck 708 <p>
5982     </p>
5983 senoner 542 <blockquote class="text">
5984     <p>
5985     </p>
5986 schoenebeck 708 </blockquote><p>
5987 schoenebeck 940
5988 schoenebeck 708 </p>
5989 schoenebeck 940 <a name="UNSUBSCRIBE"></a><br /><hr />
5990 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>
5991     <a name="rfc.section.6.5.2"></a><h3>6.5.2.&nbsp;
5992     Unregister front-end for not receiving event messages</h3>
5993 senoner 542
5994     <p>The front-end can unregister itself if it doesn't want to receive event
5995     messages anymore by sending the following command:
5996     </p>
5997 schoenebeck 708 <p>
5998     </p>
5999 senoner 542 <blockquote class="text">
6000     <p>UNSUBSCRIBE &lt;event-id&gt;
6001     </p>
6002 schoenebeck 708 </blockquote><p>
6003 schoenebeck 940
6004 schoenebeck 708 </p>
6005 senoner 542 <p>Where &lt;event-id&gt; will be replaced by the respective event that
6006     client doesn't want to receive anymore.
6007     </p>
6008     <p>Possible Answers:
6009     </p>
6010 schoenebeck 708 <p>
6011     </p>
6012 senoner 542 <blockquote class="text">
6013     <p>"OK" -
6014     </p>
6015     <blockquote class="text">
6016     <p>on success
6017     </p>
6018 schoenebeck 940 </blockquote>
6019    
6020 senoner 542
6021     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6022     </p>
6023     <blockquote class="text">
6024     <p>if unregistration succeeded, but there are noteworthy
6025     issue(s) related, providing an appropriate warning code and
6026     warning message
6027     </p>
6028 schoenebeck 940 </blockquote>
6029    
6030 senoner 542
6031     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6032     </p>
6033     <blockquote class="text">
6034     <p>in case it failed, providing an appropriate error code and
6035     error message
6036     </p>
6037 schoenebeck 940 </blockquote>
6038    
6039 senoner 542
6040 schoenebeck 708 </blockquote><p>
6041 schoenebeck 940
6042 schoenebeck 708 </p>
6043 senoner 542 <p>Examples:
6044     </p>
6045 schoenebeck 708 <p>
6046     </p>
6047 senoner 542 <blockquote class="text">
6048     <p>
6049     </p>
6050 schoenebeck 708 </blockquote><p>
6051 schoenebeck 940
6052 schoenebeck 708 </p>
6053 schoenebeck 940 <a name="SET ECHO"></a><br /><hr />
6054 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>
6055     <a name="rfc.section.6.5.3"></a><h3>6.5.3.&nbsp;
6056     Enable or disable echo of commands</h3>
6057 senoner 542
6058     <p>To enable or disable back sending of commands to the client the following command can be used:
6059     </p>
6060 schoenebeck 708 <p>
6061     </p>
6062 senoner 542 <blockquote class="text">
6063     <p>SET ECHO &lt;value&gt;
6064     </p>
6065 schoenebeck 708 </blockquote><p>
6066 schoenebeck 940
6067 schoenebeck 708 </p>
6068 senoner 542 <p>Where &lt;value&gt; should be replaced either by "1" to enable echo mode
6069     or "0" to disable echo mode. When echo mode is enabled, all
6070     commands send to LinuxSampler will be immediately send back and
6071     after this echo the actual response to the command will be
6072     returned. Echo mode will only be altered for the client connection
6073     that issued the "SET ECHO" command, not globally for all client
6074     connections.
6075     </p>
6076     <p>Possible Answers:
6077     </p>
6078 schoenebeck 708 <p>
6079     </p>
6080 senoner 542 <blockquote class="text">
6081     <p>"OK" -
6082     </p>
6083     <blockquote class="text">
6084     <p>usually
6085     </p>
6086 schoenebeck 940 </blockquote>
6087    
6088 senoner 542
6089     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6090     </p>
6091     <blockquote class="text">
6092     <p>on syntax error, e.g. non boolean value
6093     </p>
6094 schoenebeck 940 </blockquote>
6095    
6096 senoner 542
6097 schoenebeck 708 </blockquote><p>
6098 schoenebeck 940
6099 schoenebeck 708 </p>
6100 senoner 542 <p>Examples:
6101     </p>
6102 schoenebeck 708 <p>
6103     </p>
6104 senoner 542 <blockquote class="text">
6105     <p>
6106     </p>
6107 schoenebeck 708 </blockquote><p>
6108 schoenebeck 940
6109 schoenebeck 708 </p>
6110 schoenebeck 940 <a name="QUIT"></a><br /><hr />
6111 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>
6112     <a name="rfc.section.6.5.4"></a><h3>6.5.4.&nbsp;
6113     Close client connection</h3>
6114 senoner 542
6115     <p>The client can close its network connection to LinuxSampler by sending the following command:
6116     </p>
6117 schoenebeck 708 <p>
6118     </p>
6119 senoner 542 <blockquote class="text">
6120     <p>QUIT
6121     </p>
6122 schoenebeck 708 </blockquote><p>
6123 schoenebeck 940
6124 schoenebeck 708 </p>
6125 senoner 542 <p>This is probably more interesting for manual telnet connections to
6126     LinuxSampler than really useful for a front-end implementation.
6127     </p>
6128 schoenebeck 940 <a name="anchor13"></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"></a><h3>6.6.&nbsp;
6131     Global commands</h3>
6132 senoner 542
6133     <p>The following commands have global impact on the sampler.
6134     </p>
6135 schoenebeck 940 <a name="GET TOTAL_VOICE_COUNT"></a><br /><hr />
6136 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>
6137     <a name="rfc.section.6.6.1"></a><h3>6.6.1.&nbsp;
6138     Current number of active voices</h3>
6139 senoner 542
6140 schoenebeck 940 <p>The front-end can ask for the current number of active voices on
6141     the sampler by sending the following command:
6142     </p>
6143     <p>
6144     </p>
6145     <blockquote class="text">
6146     <p>GET TOTAL_VOICE_COUNT
6147     </p>
6148     </blockquote><p>
6149    
6150     </p>
6151     <p>Possible Answers:
6152     </p>
6153     <p>
6154     </p>
6155     <blockquote class="text">
6156     <p>LinuxSampler will answer by returning the number of all active
6157     voices on the sampler.
6158     </p>
6159     </blockquote><p>
6160    
6161     </p>
6162     <a name="GET TOTAL_VOICE_COUNT_MAX"></a><br /><hr />
6163 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>
6164     <a name="rfc.section.6.6.2"></a><h3>6.6.2.&nbsp;
6165     Maximum amount of active voices</h3>
6166 schoenebeck 940
6167     <p>The front-end can ask for the maximum number of active voices
6168     by sending the following command:
6169     </p>
6170     <p>
6171     </p>
6172     <blockquote class="text">
6173     <p>GET TOTAL_VOICE_COUNT_MAX
6174     </p>
6175     </blockquote><p>
6176    
6177     </p>
6178     <p>Possible Answers:
6179     </p>
6180     <p>
6181     </p>
6182     <blockquote class="text">
6183     <p>LinuxSampler will answer by returning the maximum number
6184     of active voices.
6185     </p>
6186     </blockquote><p>
6187    
6188     </p>
6189 schoenebeck 1572 <a name="GET TOTAL_STREAM_COUNT"></a><br /><hr />
6190     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6191     <a name="rfc.section.6.6.3"></a><h3>6.6.3.&nbsp;
6192     Current number of active disk streams</h3>
6193    
6194     <p>The front-end can ask for the current number of active disk streams on
6195     the sampler by sending the following command:
6196     </p>
6197     <p>
6198     </p>
6199     <blockquote class="text">
6200     <p>GET TOTAL_STREAM_COUNT
6201     </p>
6202     </blockquote><p>
6203    
6204     </p>
6205     <p>Possible Answers:
6206     </p>
6207     <p>
6208     </p>
6209     <blockquote class="text">
6210     <p>LinuxSampler will answer by returning the number of all active
6211     disk streams on the sampler.
6212     </p>
6213     </blockquote><p>
6214    
6215     </p>
6216 schoenebeck 940 <a name="RESET"></a><br /><hr />
6217 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>
6218 schoenebeck 1572 <a name="rfc.section.6.6.4"></a><h3>6.6.4.&nbsp;
6219 schoenebeck 974 Reset sampler</h3>
6220 schoenebeck 940
6221 senoner 542 <p>The front-end can reset the whole sampler by sending the following command:
6222     </p>
6223 schoenebeck 708 <p>
6224     </p>
6225 senoner 542 <blockquote class="text">
6226     <p>RESET
6227     </p>
6228 schoenebeck 708 </blockquote><p>
6229 schoenebeck 940
6230 schoenebeck 708 </p>
6231 senoner 542 <p>Possible Answers:
6232     </p>
6233 schoenebeck 708 <p>
6234     </p>
6235 senoner 542 <blockquote class="text">
6236     <p>"OK" -
6237     </p>
6238     <blockquote class="text">
6239     <p>always
6240     </p>
6241 schoenebeck 940 </blockquote>
6242    
6243 senoner 542
6244 schoenebeck 708 </blockquote><p>
6245 schoenebeck 940
6246 schoenebeck 708 </p>
6247 senoner 542 <p>Examples:
6248     </p>
6249 schoenebeck 708 <p>
6250     </p>
6251 senoner 542 <blockquote class="text">
6252     <p>
6253     </p>
6254 schoenebeck 708 </blockquote><p>
6255 schoenebeck 940
6256 schoenebeck 708 </p>
6257 schoenebeck 940 <a name="GET SERVER INFO"></a><br /><hr />
6258 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>
6259 schoenebeck 1572 <a name="rfc.section.6.6.5"></a><h3>6.6.5.&nbsp;
6260 schoenebeck 974 General sampler informations</h3>
6261 schoenebeck 575
6262     <p>The client can ask for general informations about the LinuxSampler
6263     instance by sending the following command:
6264     </p>
6265 schoenebeck 708 <p>
6266     </p>
6267 schoenebeck 575 <blockquote class="text">
6268     <p>GET SERVER INFO
6269     </p>
6270 schoenebeck 708 </blockquote><p>
6271 schoenebeck 940
6272 schoenebeck 708 </p>
6273 schoenebeck 575 <p>Possible Answers:
6274     </p>
6275 schoenebeck 708 <p>
6276     </p>
6277 schoenebeck 575 <blockquote class="text">
6278     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6279     Each answer line begins with the information category name
6280     followed by a colon and then a space character &lt;SP&gt; and finally
6281     the info character string to that information category. At the
6282     moment the following categories are defined:
6283 schoenebeck 940
6284 schoenebeck 575 </p>
6285 schoenebeck 708 <p>
6286     </p>
6287 schoenebeck 575 <blockquote class="text">
6288     <p>DESCRIPTION -
6289     </p>
6290     <blockquote class="text">
6291     <p>arbitrary textual description about the sampler
6292 schoenebeck 1390 (note that the character string may contain
6293     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>)
6294 schoenebeck 575 </p>
6295 schoenebeck 940 </blockquote>
6296    
6297 schoenebeck 575
6298     <p>VERSION -
6299     </p>
6300     <blockquote class="text">
6301     <p>version of the sampler
6302     </p>
6303 schoenebeck 940 </blockquote>
6304    
6305 schoenebeck 575
6306     <p>PROTOCOL_VERSION -
6307     </p>
6308     <blockquote class="text">
6309     <p>version of the LSCP specification the sampler
6310 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)
6311 schoenebeck 575 </p>
6312 schoenebeck 940 </blockquote>
6313    
6314 schoenebeck 575
6315 iliev 1162 <p>INSTRUMENTS_DB_SUPPORT -
6316     </p>
6317     <blockquote class="text">
6318     <p>either yes or no, specifies whether the
6319     sampler is build with instruments database support.
6320     </p>
6321 schoenebeck 940 </blockquote>
6322 iliev 1162
6323    
6324     </blockquote>
6325 schoenebeck 940
6326 schoenebeck 575
6327 schoenebeck 708 </blockquote><p>
6328 schoenebeck 940
6329 schoenebeck 708 </p>
6330 schoenebeck 575 <p>The mentioned fields above don't have to be in particular order.
6331     Other fields might be added in future.
6332     </p>
6333 schoenebeck 1006 <a name="GET VOLUME"></a><br /><hr />
6334     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6335 schoenebeck 1572 <a name="rfc.section.6.6.6"></a><h3>6.6.6.&nbsp;
6336 schoenebeck 1006 Getting global volume attenuation</h3>
6337    
6338     <p>The client can ask for the current global sampler-wide volume
6339     attenuation by sending the following command:
6340     </p>
6341     <p>
6342     </p>
6343     <blockquote class="text">
6344     <p>GET VOLUME
6345     </p>
6346     </blockquote><p>
6347    
6348     </p>
6349     <p>Possible Answers:
6350     </p>
6351     <p>
6352     </p>
6353     <blockquote class="text">
6354     <p>The sampler will always answer by returning the optional
6355     dotted floating point coefficient, reflecting the current
6356     global volume attenuation.
6357    
6358     </p>
6359     </blockquote><p>
6360    
6361     </p>
6362     <p>Note: it is up to the respective sampler engine whether to obey
6363     that global volume parameter or not, but in general all engines SHOULD
6364     use this parameter.
6365     </p>
6366     <a name="SET VOLUME"></a><br /><hr />
6367     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6368 schoenebeck 1572 <a name="rfc.section.6.6.7"></a><h3>6.6.7.&nbsp;
6369 schoenebeck 1006 Setting global volume attenuation</h3>
6370    
6371     <p>The client can alter the current global sampler-wide volume
6372     attenuation by sending the following command:
6373     </p>
6374     <p>
6375     </p>
6376     <blockquote class="text">
6377     <p>SET VOLUME &lt;volume&gt;
6378     </p>
6379     </blockquote><p>
6380    
6381     </p>
6382     <p>Where &lt;volume&gt; should be replaced by the optional dotted
6383     floating point value, reflecting the new global volume parameter.
6384     This value might usually be in the range between 0.0 and 1.0, that
6385     is for attenuating the overall volume.
6386     </p>
6387     <p>Possible Answers:
6388     </p>
6389     <p>
6390     </p>
6391     <blockquote class="text">
6392     <p>"OK" -
6393     </p>
6394     <blockquote class="text">
6395     <p>on success
6396     </p>
6397     </blockquote>
6398    
6399    
6400     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6401     </p>
6402     <blockquote class="text">
6403     <p>if the global volume was set, but there are noteworthy
6404     issue(s) related, providing an appropriate warning code and
6405     warning message
6406     </p>
6407     </blockquote>
6408    
6409    
6410     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6411     </p>
6412     <blockquote class="text">
6413     <p>in case it failed, providing an appropriate error code and error message
6414     </p>
6415     </blockquote>
6416    
6417    
6418     </blockquote><p>
6419    
6420     </p>
6421 schoenebeck 1801 <a name="GET VOICES"></a><br /><hr />
6422     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6423     <a name="rfc.section.6.6.8"></a><h3>6.6.8.&nbsp;
6424     Getting global voice limit</h3>
6425    
6426     <p>The client can ask for the current global sampler-wide limit
6427     for maximum voices by sending the following command:
6428     </p>
6429     <p>
6430     </p>
6431     <blockquote class="text">
6432     <p>GET VOICES
6433     </p>
6434     </blockquote><p>
6435    
6436     </p>
6437     <p>Possible Answers:
6438     </p>
6439     <p>
6440     </p>
6441     <blockquote class="text">
6442     <p>LinuxSampler will answer by returning the number for
6443     the current limit of maximum voices.
6444     </p>
6445     </blockquote><p>
6446    
6447     </p>
6448     <p>The voice limit setting defines how many voices should maximum
6449     be processed by the sampler at the same time. If the user
6450     triggers new notes which would exceed that voice limit, the
6451     sampler engine will react by stealing old voices for those
6452     newly triggered notes. Note that the amount of voices triggered
6453     by a new note can be larger than one and is dependent to the
6454     respective instrument and probably further criterias.
6455     </p>
6456     <a name="SET VOICES"></a><br /><hr />
6457     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6458     <a name="rfc.section.6.6.9"></a><h3>6.6.9.&nbsp;
6459     Setting global voice limit</h3>
6460    
6461     <p>The client can alter the current global sampler-wide limit
6462     for maximum voices by sending the following command:
6463     </p>
6464     <p>
6465     </p>
6466     <blockquote class="text">
6467     <p>SET VOICES &lt;max-voices&gt;
6468     </p>
6469     </blockquote><p>
6470    
6471     </p>
6472     <p>Where &lt;max-voices&gt; should be replaced by the integer
6473     value, reflecting the new global amount limit of maximum voices.
6474     This value has to be larger than 0.
6475     </p>
6476     <p>Possible Answers:
6477     </p>
6478     <p>
6479     </p>
6480     <blockquote class="text">
6481     <p>"OK" -
6482     </p>
6483     <blockquote class="text">
6484     <p>on success
6485     </p>
6486     </blockquote>
6487    
6488    
6489     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6490     </p>
6491     <blockquote class="text">
6492     <p>if the voice limit was set, but there are noteworthy
6493     issue(s) related, providing an appropriate warning code and
6494     warning message
6495     </p>
6496     </blockquote>
6497    
6498    
6499     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6500     </p>
6501     <blockquote class="text">
6502     <p>in case it failed, providing an appropriate error code and error message
6503     </p>
6504     </blockquote>
6505    
6506    
6507     </blockquote><p>
6508    
6509     </p>
6510     <p>Note: the given value will be passed to all sampler engine instances.
6511     The total amount of maximum voices on the running system might thus
6512     be as big as the given value multiplied by the current amount of engine
6513     instances.
6514     </p>
6515     <p>Caution: when adjusting the voice limit, you SHOULD also
6516     adjust the disk stream limit respectively and vice versa.
6517     </p>
6518     <a name="GET STREAMS"></a><br /><hr />
6519     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6520     <a name="rfc.section.6.6.10"></a><h3>6.6.10.&nbsp;
6521     Getting global disk stream limit</h3>
6522    
6523     <p>The client can ask for the current global sampler-wide limit
6524     for maximum disk streams by sending the following command:
6525     </p>
6526     <p>
6527     </p>
6528     <blockquote class="text">
6529     <p>GET STREAMS
6530     </p>
6531     </blockquote><p>
6532    
6533     </p>
6534     <p>Possible Answers:
6535     </p>
6536     <p>
6537     </p>
6538     <blockquote class="text">
6539     <p>LinuxSampler will answer by returning the number for
6540     the current limit of maximum disk streams.
6541     </p>
6542     </blockquote><p>
6543    
6544     </p>
6545     <p>The disk stream limit setting defines how many disk streams should
6546     maximum be processed by a sampler engine at the same time. The
6547     higher this value, the more memory (RAM) will be occupied, since
6548     every disk streams allocates a certain buffer size for being able
6549     to perform its streaming operations.
6550     </p>
6551     <a name="SET STREAMS"></a><br /><hr />
6552     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6553     <a name="rfc.section.6.6.11"></a><h3>6.6.11.&nbsp;
6554     Setting global disk stream limit</h3>
6555    
6556     <p>The client can alter the current global sampler-wide limit
6557     for maximum disk streams by sending the following command:
6558     </p>
6559     <p>
6560     </p>
6561     <blockquote class="text">
6562     <p>SET STREAMS &lt;max-streams&gt;
6563     </p>
6564     </blockquote><p>
6565    
6566     </p>
6567     <p>Where &lt;max-streams&gt; should be replaced by the integer
6568     value, reflecting the new global amount limit of maximum disk streams.
6569     This value has to be positive.
6570     </p>
6571     <p>Possible Answers:
6572     </p>
6573     <p>
6574     </p>
6575     <blockquote class="text">
6576     <p>"OK" -
6577     </p>
6578     <blockquote class="text">
6579     <p>on success
6580     </p>
6581     </blockquote>
6582    
6583    
6584     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6585     </p>
6586     <blockquote class="text">
6587     <p>if the disk stream limit was set, but there are noteworthy
6588     issue(s) related, providing an appropriate warning code and
6589     warning message
6590     </p>
6591     </blockquote>
6592    
6593    
6594     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6595     </p>
6596     <blockquote class="text">
6597     <p>in case it failed, providing an appropriate error code and error message
6598     </p>
6599     </blockquote>
6600    
6601    
6602     </blockquote><p>
6603    
6604     </p>
6605     <p>Note: the given value will be passed to all sampler engine instances.
6606     The total amount of maximum disk streams on the running system might
6607     thus be as big as the given value multiplied by the current amount of
6608     engine instances.
6609     </p>
6610     <p>Caution: when adjusting the disk stream limit, you SHOULD also
6611     adjust the voice limit respectively and vice versa.
6612     </p>
6613 schoenebeck 974 <a name="MIDI Instrument Mapping"></a><br /><hr />
6614     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6615     <a name="rfc.section.6.7"></a><h3>6.7.&nbsp;
6616     MIDI Instrument Mapping</h3>
6617 schoenebeck 945
6618     <p>The MIDI protocol provides a way to switch between instruments
6619     by sending so called MIDI bank select and MIDI program change
6620     messages which are essentially just numbers. The following commands
6621     allow to actually map arbitrary MIDI bank select / program change
6622     numbers with real instruments.
6623     </p>
6624 schoenebeck 974 <p>The sampler allows to manage an arbitrary amount of MIDI
6625     instrument maps which define which instrument to load on
6626     which MIDI program change message.
6627 schoenebeck 945 </p>
6628 schoenebeck 974 <p>By default, that is when the sampler is launched, there is no
6629     map, thus the sampler will simply ignore all program change
6630     messages. The front-end has to explicitly create at least one
6631     map, add entries to the map and tell the respective sampler
6632     channel(s) which MIDI instrument map to use, so the sampler
6633     knows how to react on a given program change message on the
6634     respective sampler channel, that is by switching to the
6635     respectively defined engine type and loading the respective
6636     instrument. See command
6637     <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>
6638     for how to assign a MIDI instrument map to a sampler channel.
6639     </p>
6640 schoenebeck 945 <p>Also note per MIDI specification a bank select message does not
6641     cause to switch to another instrument. Instead when receiving a
6642     bank select message the bank value will be stored and a subsequent
6643     program change message (which may occur at any time) will finally
6644     cause the sampler to switch to the respective instrument as
6645     reflected by the current MIDI instrument map.
6646     </p>
6647 schoenebeck 1390 <a name="ADD MIDI_INSTRUMENT_MAP"></a><br /><hr />
6648 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>
6649     <a name="rfc.section.6.7.1"></a><h3>6.7.1.&nbsp;
6650     Create a new MIDI instrument map</h3>
6651    
6652     <p>The front-end can add a new MIDI instrument map by sending
6653     the following command:
6654     </p>
6655     <p>
6656     </p>
6657     <blockquote class="text">
6658     <p>ADD MIDI_INSTRUMENT_MAP [&lt;name&gt;]
6659     </p>
6660     </blockquote><p>
6661    
6662     </p>
6663     <p>Where &lt;name&gt; is an optional argument allowing to
6664     assign a custom name to the new map. MIDI instrument Map
6665 schoenebeck 1390 names do not have to be unique, but MUST be encapsulated
6666     into apostrophes and support escape sequences as described
6667     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>".
6668    
6669 schoenebeck 974 </p>
6670     <p>Possible Answers:
6671     </p>
6672     <p>
6673     </p>
6674     <blockquote class="text">
6675     <p>"OK[&lt;map&gt;]" -
6676     </p>
6677     <blockquote class="text">
6678     <p>in case a new MIDI instrument map could
6679     be added, where &lt;map&gt; reflects the
6680     unique ID of the newly created MIDI
6681     instrument map
6682     </p>
6683     </blockquote>
6684    
6685    
6686     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6687     </p>
6688     <blockquote class="text">
6689     <p>when a new map could not be created, which
6690     might never occur in practice
6691     </p>
6692     </blockquote>
6693    
6694    
6695     </blockquote><p>
6696    
6697     </p>
6698     <p>Examples:
6699     </p>
6700     <p>
6701     </p>
6702     <blockquote class="text">
6703     <p>C: "ADD MIDI_INSTRUMENT_MAP 'Standard Map'"
6704     </p>
6705     <p>S: "OK[0]"
6706     </p>
6707     </blockquote><p>
6708    
6709     </p>
6710     <p>
6711     </p>
6712     <blockquote class="text">
6713     <p>C: "ADD MIDI_INSTRUMENT_MAP 'Standard Drumkit'"
6714     </p>
6715     <p>S: "OK[1]"
6716     </p>
6717     </blockquote><p>
6718    
6719     </p>
6720     <p>
6721     </p>
6722     <blockquote class="text">
6723     <p>C: "ADD MIDI_INSTRUMENT_MAP"
6724     </p>
6725     <p>S: "OK[5]"
6726     </p>
6727     </blockquote><p>
6728    
6729     </p>
6730     <a name="REMOVE MIDI_INSTRUMENT_MAP"></a><br /><hr />
6731     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6732     <a name="rfc.section.6.7.2"></a><h3>6.7.2.&nbsp;
6733     Delete one particular or all MIDI instrument maps</h3>
6734    
6735     <p>The front-end can delete a particular MIDI instrument map
6736     by sending the following command:
6737     </p>
6738     <p>
6739     </p>
6740     <blockquote class="text">
6741     <p>REMOVE MIDI_INSTRUMENT_MAP &lt;map&gt;
6742     </p>
6743     </blockquote><p>
6744    
6745     </p>
6746     <p>Where &lt;map&gt; reflects the unique ID of the map to delete
6747     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>
6748     command.
6749     </p>
6750     <p>The front-end can delete all MIDI instrument maps by
6751     sending the following command:
6752     </p>
6753     <p>
6754     </p>
6755     <blockquote class="text">
6756     <p>REMOVE MIDI_INSTRUMENT_MAP ALL
6757     </p>
6758     </blockquote><p>
6759    
6760     </p>
6761     <p>Possible Answers:
6762     </p>
6763     <p>
6764     </p>
6765     <blockquote class="text">
6766     <p>"OK" -
6767     </p>
6768     <blockquote class="text">
6769     <p>in case the map(s) could be deleted
6770     </p>
6771     </blockquote>
6772    
6773    
6774     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6775     </p>
6776     <blockquote class="text">
6777     <p>when the given map does not exist
6778     </p>
6779     </blockquote>
6780    
6781    
6782     </blockquote><p>
6783    
6784     </p>
6785     <p>Examples:
6786     </p>
6787     <p>
6788     </p>
6789     <blockquote class="text">
6790     <p>C: "REMOVE MIDI_INSTRUMENT_MAP 0"
6791     </p>
6792     <p>S: "OK"
6793     </p>
6794     </blockquote><p>
6795    
6796     </p>
6797     <p>
6798     </p>
6799     <blockquote class="text">
6800     <p>C: "REMOVE MIDI_INSTRUMENT_MAP ALL"
6801     </p>
6802     <p>S: "OK"
6803     </p>
6804     </blockquote><p>
6805    
6806     </p>
6807     <a name="GET MIDI_INSTRUMENT_MAPS"></a><br /><hr />
6808     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6809     <a name="rfc.section.6.7.3"></a><h3>6.7.3.&nbsp;
6810     Get amount of existing MIDI instrument maps</h3>
6811    
6812     <p>The front-end can retrieve the current amount of MIDI
6813     instrument maps by sending the following command:
6814     </p>
6815     <p>
6816     </p>
6817     <blockquote class="text">
6818     <p>GET MIDI_INSTRUMENT_MAPS
6819     </p>
6820     </blockquote><p>
6821    
6822     </p>
6823     <p>Possible Answers:
6824     </p>
6825     <p>
6826     </p>
6827     <blockquote class="text">
6828     <p>The sampler will answer by returning the current
6829     number of MIDI instrument maps.
6830     </p>
6831     </blockquote><p>
6832    
6833     </p>
6834     <p>Example:
6835     </p>
6836     <p>
6837     </p>
6838     <blockquote class="text">
6839     <p>C: "GET MIDI_INSTRUMENT_MAPS"
6840     </p>
6841     <p>S: "2"
6842     </p>
6843     </blockquote><p>
6844    
6845     </p>
6846     <a name="LIST MIDI_INSTRUMENT_MAPS"></a><br /><hr />
6847     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6848     <a name="rfc.section.6.7.4"></a><h3>6.7.4.&nbsp;
6849     Getting all created MIDI instrument maps</h3>
6850    
6851     <p>The number of MIDI instrument maps can change on runtime. To get the
6852     current list of MIDI instrument maps, the front-end can send the
6853     following command:
6854     </p>
6855     <p>
6856     </p>
6857     <blockquote class="text">
6858     <p>LIST MIDI_INSTRUMENT_MAPS
6859     </p>
6860     </blockquote><p>
6861    
6862     </p>
6863     <p>Possible Answers:
6864     </p>
6865     <p>
6866     </p>
6867     <blockquote class="text">
6868     <p>The sampler will answer by returning a comma separated list
6869     with all MIDI instrument maps' numerical IDs.
6870     </p>
6871     </blockquote><p>
6872    
6873     </p>
6874     <p>Example:
6875     </p>
6876     <p>
6877     </p>
6878     <blockquote class="text">
6879     <p>C: "LIST MIDI_INSTRUMENT_MAPS"
6880     </p>
6881     <p>S: "0,1,5,12"
6882     </p>
6883     </blockquote><p>
6884    
6885     </p>
6886     <a name="GET MIDI_INSTRUMENT_MAP INFO"></a><br /><hr />
6887     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6888     <a name="rfc.section.6.7.5"></a><h3>6.7.5.&nbsp;
6889     Getting MIDI instrument map information</h3>
6890    
6891     <p>The front-end can ask for the current settings of a MIDI
6892     instrument map by sending the following command:
6893     </p>
6894     <p>
6895     </p>
6896     <blockquote class="text">
6897     <p>GET MIDI_INSTRUMENT_MAP INFO &lt;map&gt;
6898     </p>
6899     </blockquote><p>
6900    
6901     </p>
6902     <p>Where &lt;map&gt; is the numerical ID of the map the
6903     front-end is interested in as returned by the
6904     <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>
6905     command.
6906     </p>
6907     <p>Possible Answers:
6908     </p>
6909     <p>
6910     </p>
6911     <blockquote class="text">
6912     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6913     Each answer line begins with the settings category name
6914     followed by a colon and then a space character &lt;SP&gt; and finally
6915     the info character string to that setting category. At the
6916     moment the following categories are defined:
6917     </p>
6918     <p>
6919     </p>
6920     <blockquote class="text">
6921     <p>NAME -
6922     </p>
6923     <blockquote class="text">
6924     <p>custom name of the given map,
6925     which does not have to be unique
6926 schoenebeck 1400 (note that this character string may contain
6927     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>)
6928 schoenebeck 974 </p>
6929     </blockquote>
6930    
6931    
6932 iliev 1137 <p>DEFAULT -
6933     </p>
6934     <blockquote class="text">
6935     <p>either true or false,
6936     defines whether this map is the default map
6937     </p>
6938 schoenebeck 974 </blockquote>
6939 iliev 1137
6940    
6941     </blockquote>
6942 schoenebeck 974
6943    
6944     </blockquote><p>
6945    
6946     </p>
6947     <p>The mentioned fields above don't have to be in particular order.
6948     </p>
6949     <p>Example:
6950     </p>
6951     <p>
6952     </p>
6953     <blockquote class="text">
6954     <p>C: "GET MIDI_INSTRUMENT_MAP INFO 0"
6955     </p>
6956     <p>S: "NAME: Standard Map"
6957     </p>
6958 iliev 1137 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: true"
6959     </p>
6960 schoenebeck 974 <p>&nbsp;&nbsp;&nbsp;"."
6961     </p>
6962     </blockquote><p>
6963    
6964     </p>
6965     <a name="SET MIDI_INSTRUMENT_MAP NAME"></a><br /><hr />
6966     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6967     <a name="rfc.section.6.7.6"></a><h3>6.7.6.&nbsp;
6968     Renaming a MIDI instrument map</h3>
6969    
6970     <p>The front-end can alter the custom name of a MIDI
6971     instrument map by sending the following command:
6972     </p>
6973     <p>
6974     </p>
6975     <blockquote class="text">
6976     <p>SET MIDI_INSTRUMENT_MAP NAME &lt;map&gt; &lt;name&gt;
6977     </p>
6978     </blockquote><p>
6979    
6980     </p>
6981     <p>Where &lt;map&gt; is the numerical ID of the map and
6982     &lt;name&gt; the new custom name of the map, which does not
6983 schoenebeck 1390 have to be unique (name MUST be encapsulated into apostrophes
6984     and supports escape sequences as described in chapter
6985     "<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>").
6986    
6987 schoenebeck 974 </p>
6988     <p>Possible Answers:
6989     </p>
6990     <p>
6991     </p>
6992     <blockquote class="text">
6993     <p>"OK" -
6994     </p>
6995     <blockquote class="text">
6996     <p>on success
6997     </p>
6998     </blockquote>
6999    
7000    
7001     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7002     </p>
7003     <blockquote class="text">
7004     <p>in case the given map does not exist
7005     </p>
7006     </blockquote>
7007    
7008    
7009     </blockquote><p>
7010    
7011     </p>
7012     <p>Example:
7013     </p>
7014     <p>
7015     </p>
7016     <blockquote class="text">
7017     <p>C: "SET MIDI_INSTRUMENT_MAP NAME 0 'Foo instruments'"
7018     </p>
7019     <p>S: "OK"
7020     </p>
7021     </blockquote><p>
7022    
7023     </p>
7024 schoenebeck 945 <a name="MAP MIDI_INSTRUMENT"></a><br /><hr />
7025 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>
7026     <a name="rfc.section.6.7.7"></a><h3>6.7.7.&nbsp;
7027     Create or replace a MIDI instrument map entry</h3>
7028 schoenebeck 945
7029     <p>The front-end can create a new or replace an existing entry
7030 schoenebeck 974 in a sampler's MIDI instrument map by sending the following
7031 schoenebeck 945 command:
7032     </p>
7033     <p>
7034     </p>
7035     <blockquote class="text">
7036 schoenebeck 1048 <p>MAP MIDI_INSTRUMENT [NON_MODAL] &lt;map&gt;
7037 schoenebeck 974 &lt;midi_bank&gt; &lt;midi_prog&gt; &lt;engine_name&gt;
7038 schoenebeck 945 &lt;filename&gt; &lt;instrument_index&gt; &lt;volume_value&gt;
7039     [&lt;instr_load_mode&gt;] [&lt;name&gt;]
7040     </p>
7041     </blockquote><p>
7042    
7043     </p>
7044 schoenebeck 974 <p>Where &lt;map&gt; is the numeric ID of the map to alter,
7045     &lt;midi_bank&gt; is an integer value between
7046     0..16383 reflecting the MIDI bank select index,
7047     &lt;midi_prog&gt; an
7048 schoenebeck 945 integer value between 0..127 reflecting the MIDI program change
7049     index, &lt;engine_name&gt; a sampler engine name as returned by
7050 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>
7051 schoenebeck 945 command (not encapsulated into apostrophes), &lt;filename&gt; the name
7052 schoenebeck 1251 of the instrument's file to be deployed (encapsulated into apostrophes,
7053     supporting escape sequences as described in chapter
7054     "<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>"),
7055 schoenebeck 974 &lt;instrument_index&gt; the index (integer value) of the instrument
7056 schoenebeck 945 within the given file, &lt;volume_value&gt; reflects the master
7057     volume of the instrument as optionally dotted number (where a
7058 schoenebeck 1028 value &lt; 1.0 means attenuation and a value > 1.0 means
7059 schoenebeck 945 amplification). This parameter easily allows to adjust the
7060     volume of all intruments within a custom instrument map
7061     without having to adjust their instrument files. The
7062     OPTIONAL &lt;instr_load_mode&gt; argument defines the life
7063     time of the instrument, that is when the instrument should
7064     be loaded, when freed and has exactly the following
7065     possibilities:
7066     </p>
7067     <p>
7068     </p>
7069     <blockquote class="text">
7070     <p>"ON_DEMAND" -
7071     </p>
7072     <blockquote class="text">
7073     <p>The instrument will be loaded when needed,
7074     that is when demanded by at least one sampler
7075     channel. It will immediately be freed from memory
7076     when not needed by any sampler channel anymore.
7077     </p>
7078     </blockquote>
7079    
7080    
7081     <p>"ON_DEMAND_HOLD" -
7082     </p>
7083     <blockquote class="text">
7084     <p>The instrument will be loaded when needed,
7085     that is when demanded by at least one sampler
7086     channel. It will be kept in memory even when
7087     not needed by any sampler channel anymore.
7088     Instruments with this mode are only freed
7089     when the sampler is reset or all mapping
7090     entries with this mode (and respective
7091     instrument) are explicitly changed to
7092     "ON_DEMAND" and no sampler channel is using
7093     the instrument anymore.
7094     </p>
7095     </blockquote>
7096    
7097    
7098     <p>"PERSISTENT" -
7099     </p>
7100     <blockquote class="text">
7101     <p>The instrument will immediately be loaded
7102 schoenebeck 1048 into memory when this mapping
7103 schoenebeck 945 command is sent and the instrument is kept all
7104     the time. Instruments with this mode are
7105     only freed when the sampler is reset or all
7106     mapping entries with this mode (and
7107     respective instrument) are explicitly
7108     changed to "ON_DEMAND" and no sampler
7109     channel is using the instrument anymore.
7110     </p>
7111     </blockquote>
7112    
7113    
7114     <p>not supplied -
7115     </p>
7116     <blockquote class="text">
7117     <p>In case there is no &lt;instr_load_mode&gt;
7118     argument given, it will be up to the
7119     InstrumentManager to decide which mode to use.
7120     Usually it will use "ON_DEMAND" if an entry
7121     for the given instrument does not exist in
7122     the InstrumentManager's list yet, otherwise
7123     if an entry already exists, it will simply
7124     stick with the mode currently reflected by
7125     the already existing entry, that is it will
7126     not change the mode.
7127     </p>
7128     </blockquote>
7129    
7130    
7131     </blockquote><p>
7132    
7133     </p>
7134     <p>
7135     The &lt;instr_load_mode&gt; argument thus allows to define an
7136     appropriate strategy (low memory consumption vs. fast
7137     instrument switching) for each instrument individually. Note, the
7138     following restrictions apply to this argument: "ON_DEMAND_HOLD" and
7139     "PERSISTENT" have to be supported by the respective sampler engine
7140     (which is technically the case when the engine provides an
7141     InstrumentManager for its format). If this is not the case the
7142     argument will automatically fall back to the default value
7143     "ON_DEMAND". Also the load mode of one instrument may
7144     automatically change the laod mode of other instrument(s), i.e.
7145     because the instruments are part of the same file and the
7146     engine does not allow a way to manage load modes for them
7147     individually. Due to this, in case the frontend shows the
7148     load modes of entries, the frontend should retrieve the actual
7149     mode by i.e. sending
7150 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>
7151 schoenebeck 1390 command(s). Finally the OPTIONAL &lt;name&gt; argument allows to set a custom name
7152     (encapsulated into apostrophes, supporting escape sequences as described in chapter
7153     "<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
7154     mapping entry, useful for frontends for displaying an appropriate name for
7155 schoenebeck 945 mapped instruments (using
7156 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>).
7157 schoenebeck 945
7158     </p>
7159     <p>
7160 schoenebeck 1048 By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is
7161     completely established in the sampler. The OPTIONAL "NON_MODAL" argument
7162     however causes the respective "MAP MIDI_INSTRUMENT" command to return
7163     immediately, that is to let the sampler establish the mapping in the
7164     background. So this argument might be especially useful for mappings with
7165     a "PERSISTENT" type, because these have to load the respective instruments
7166     immediately and might thus block for a very long time. It is recommended
7167     however to use the OPTIONAL "NON_MODAL" argument only if really necessary,
7168     because it has the following drawbacks: as "NON_MODAL" instructions return
7169     immediately, they may not necessarily return an error i.e. when the given
7170     instrument file turns out to be corrupt, beside that subsequent commands
7171     in a LSCP instruction sequence might fail, because mandatory mappings are
7172     not yet completed.
7173 schoenebeck 945
7174     </p>
7175     <p>Possible Answers:
7176     </p>
7177     <p>
7178     </p>
7179     <blockquote class="text">
7180     <p>"OK" -
7181     </p>
7182     <blockquote class="text">
7183     <p>usually
7184     </p>
7185     </blockquote>
7186    
7187    
7188     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7189     </p>
7190     <blockquote class="text">
7191 schoenebeck 974 <p>when the given map or engine does not exist or a value
7192 schoenebeck 945 is out of range
7193     </p>
7194     </blockquote>
7195    
7196    
7197     </blockquote><p>
7198    
7199     </p>
7200     <p>Examples:
7201     </p>
7202     <p>
7203     </p>
7204     <blockquote class="text">
7205 schoenebeck 974 <p>C: "MAP MIDI_INSTRUMENT 0 3 0 gig '/usr/share/Steinway D.gig' 0 0.8 PERSISTENT"
7206 schoenebeck 945 </p>
7207     <p>S: "OK"
7208     </p>
7209     </blockquote><p>
7210    
7211     </p>
7212     <p>
7213     </p>
7214     <blockquote class="text">
7215 schoenebeck 974 <p>C: "MAP MIDI_INSTRUMENT 0 4 50 gig '/home/john/foostrings.gig' 7 1.0"
7216 schoenebeck 945 </p>
7217     <p>S: "OK"
7218     </p>
7219     </blockquote><p>
7220    
7221     </p>
7222     <p>
7223     </p>
7224     <blockquote class="text">
7225     <p>C: "MAP MIDI_INSTRUMENT 0 0 0 gig '/usr/share/piano.gig' 0 1.0 'Normal Piano'"
7226     </p>
7227     <p>S: "OK"
7228     </p>
7229 schoenebeck 974 <p>C: "MAP MIDI_INSTRUMENT 0 1 0 gig '/usr/share/piano.gig' 0 0.25 'Silent Piano'"
7230 schoenebeck 945 </p>
7231     <p>S: "OK"
7232     </p>
7233     </blockquote><p>
7234    
7235     </p>
7236     <p>
7237     </p>
7238     <blockquote class="text">
7239 schoenebeck 1048 <p>C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"
7240 schoenebeck 945 </p>
7241     <p>S: "OK"
7242     </p>
7243     </blockquote><p>
7244    
7245     </p>
7246     <a name="GET MIDI_INSTRUMENTS"></a><br /><hr />
7247 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>
7248     <a name="rfc.section.6.7.8"></a><h3>6.7.8.&nbsp;
7249     Getting ammount of MIDI instrument map entries</h3>
7250 schoenebeck 945
7251 schoenebeck 974 <p>The front-end can query the amount of currently existing
7252     entries in a MIDI instrument map by sending the following
7253 schoenebeck 945 command:
7254     </p>
7255     <p>
7256     </p>
7257     <blockquote class="text">
7258 schoenebeck 974 <p>GET MIDI_INSTRUMENTS &lt;map&gt;
7259 schoenebeck 945 </p>
7260     </blockquote><p>
7261    
7262     </p>
7263 schoenebeck 974 <p>The front-end can query the amount of currently existing
7264     entries in all MIDI instrument maps by sending the following
7265     command:
7266     </p>
7267     <p>
7268     </p>
7269     <blockquote class="text">
7270     <p>GET MIDI_INSTRUMENTS ALL
7271     </p>
7272     </blockquote><p>
7273    
7274     </p>
7275 schoenebeck 945 <p>Possible Answers:
7276     </p>
7277     <p>
7278     </p>
7279     <blockquote class="text">
7280 schoenebeck 974 <p>The sampler will answer by sending the current number of
7281     entries in the MIDI instrument map(s).
7282 schoenebeck 945 </p>
7283     </blockquote><p>
7284    
7285     </p>
7286     <p>Example:
7287     </p>
7288     <p>
7289     </p>
7290     <blockquote class="text">
7291 schoenebeck 974 <p>C: "GET MIDI_INSTRUMENTS 0"
7292 schoenebeck 945 </p>
7293 schoenebeck 974 <p>S: "234"
7294 schoenebeck 945 </p>
7295     </blockquote><p>
7296    
7297     </p>
7298 schoenebeck 974 <p>
7299     </p>
7300     <blockquote class="text">
7301     <p>C: "GET MIDI_INSTRUMENTS ALL"
7302     </p>
7303     <p>S: "954"
7304     </p>
7305     </blockquote><p>
7306    
7307     </p>
7308 schoenebeck 945 <a name="LIST MIDI_INSTRUMENTS"></a><br /><hr />
7309 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>
7310     <a name="rfc.section.6.7.9"></a><h3>6.7.9.&nbsp;
7311     Getting indeces of all entries of a MIDI instrument map</h3>
7312 schoenebeck 945
7313 schoenebeck 974 <p>The front-end can query a list of all currently existing
7314     entries in a certain MIDI instrument map by sending the following
7315     command:
7316 schoenebeck 945 </p>
7317     <p>
7318     </p>
7319     <blockquote class="text">
7320 schoenebeck 974 <p>LIST MIDI_INSTRUMENTS &lt;map&gt;
7321 schoenebeck 945 </p>
7322     </blockquote><p>
7323    
7324     </p>
7325 schoenebeck 974 <p>Where &lt;map&gt; is the numeric ID of the MIDI instrument map.
7326     </p>
7327     <p>The front-end can query a list of all currently existing
7328     entries of all MIDI instrument maps by sending the following
7329     command:
7330     </p>
7331     <p>
7332     </p>
7333     <blockquote class="text">
7334     <p>LIST MIDI_INSTRUMENTS ALL
7335     </p>
7336     </blockquote><p>
7337    
7338     </p>
7339 schoenebeck 945 <p>Possible Answers:
7340     </p>
7341     <p>
7342     </p>
7343     <blockquote class="text">
7344 schoenebeck 974 <p>The sampler will answer by sending a comma separated
7345     list of map ID - MIDI bank - MIDI program triples, where
7346     each triple is encapsulated into curly braces. The
7347     list is returned in one single line. Each triple
7348     just reflects the key of the respective map entry,
7349     thus subsequent
7350     <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>
7351 schoenebeck 945 command(s) are necessary to retrieve detailed informations
7352     about each entry.
7353     </p>
7354     </blockquote><p>
7355    
7356     </p>
7357     <p>Example:
7358     </p>
7359     <p>
7360     </p>
7361     <blockquote class="text">
7362 schoenebeck 974 <p>C: "LIST MIDI_INSTRUMENTS 0"
7363 schoenebeck 945 </p>
7364 schoenebeck 974 <p>S: "{0,0,0},{0,0,1},{0,0,3},{0,1,4},{1,127,127}"
7365 schoenebeck 945 </p>
7366     </blockquote><p>
7367    
7368     </p>
7369     <a name="UNMAP MIDI_INSTRUMENT"></a><br /><hr />
7370 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>
7371     <a name="rfc.section.6.7.10"></a><h3>6.7.10.&nbsp;
7372     Remove an entry from the MIDI instrument map</h3>
7373 schoenebeck 945
7374 schoenebeck 974 <p>The front-end can delete an entry from a MIDI instrument
7375 schoenebeck 945 map by sending the following command:
7376     </p>
7377     <p>
7378     </p>
7379     <blockquote class="text">
7380 schoenebeck 974 <p>UNMAP MIDI_INSTRUMENT &lt;map&gt; &lt;midi_bank&gt; &lt;midi_prog&gt;
7381 schoenebeck 945 </p>
7382     </blockquote><p>
7383    
7384     </p>
7385     <p>
7386 schoenebeck 974 Where &lt;map&gt; is the numeric ID of the MIDI instrument map,
7387     &lt;midi_bank&gt; is an integer value between 0..16383
7388     reflecting the MIDI bank value and
7389     &lt;midi_prog&gt; an integer value between
7390     0..127 reflecting the MIDI program value of the map's entrie's key
7391 schoenebeck 945 index triple.
7392    
7393     </p>
7394     <p>Possible Answers:
7395     </p>
7396     <p>
7397     </p>
7398     <blockquote class="text">
7399     <p>"OK" -
7400     </p>
7401     <blockquote class="text">
7402     <p>usually
7403     </p>
7404     </blockquote>
7405    
7406    
7407     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7408     </p>
7409     <blockquote class="text">
7410     <p>when index out of bounds
7411     </p>
7412     </blockquote>
7413    
7414    
7415     </blockquote><p>
7416    
7417     </p>
7418     <p>Example:
7419     </p>
7420     <p>
7421     </p>
7422     <blockquote class="text">
7423 schoenebeck 974 <p>C: "UNMAP MIDI_INSTRUMENT 0 2 127"
7424 schoenebeck 945 </p>
7425     <p>S: "OK"
7426     </p>
7427     </blockquote><p>
7428    
7429     </p>
7430     <a name="GET MIDI_INSTRUMENT INFO"></a><br /><hr />
7431 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>
7432     <a name="rfc.section.6.7.11"></a><h3>6.7.11.&nbsp;
7433     Get current settings of MIDI instrument map entry</h3>
7434 schoenebeck 945
7435     <p>The front-end can retrieve the current settings of a certain
7436     instrument map entry by sending the following command:
7437     </p>
7438     <p>
7439     </p>
7440     <blockquote class="text">
7441 schoenebeck 974 <p>GET MIDI_INSTRUMENT INFO &lt;map&gt; &lt;midi_bank&gt; &lt;midi_prog&gt;
7442 schoenebeck 945 </p>
7443     </blockquote><p>
7444    
7445     </p>
7446     <p>
7447 schoenebeck 974 Where &lt;map&gt; is the numeric ID of the MIDI instrument map,
7448     &lt;midi_bank&gt; is an integer value between 0..16383
7449     reflecting the MIDI bank value, &lt;midi_bank&gt;
7450     and &lt;midi_prog&gt; an integer value between
7451     0..127 reflecting the MIDI program value of the map's entrie's key
7452 schoenebeck 945 index triple.
7453    
7454     </p>
7455     <p>Possible Answers:
7456     </p>
7457     <p>
7458     </p>
7459     <blockquote class="text">
7460     <p>LinuxSampler will answer by sending a &lt;CRLF&gt;
7461     separated list. Each answer line begins with the
7462     information category name followed by a colon and then
7463     a space character &lt;SP&gt; and finally the info
7464     character string to that info category. At the moment
7465     the following categories are defined:
7466     </p>
7467     <p>"NAME" -
7468     </p>
7469     <blockquote class="text">
7470     <p>Name for this MIDI instrument map entry (if defined).
7471     This name shall be used by frontends for displaying a
7472     name for this mapped instrument. It can be set and
7473     changed with the
7474 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>
7475 schoenebeck 945 command and does not have to be unique.
7476 schoenebeck 1400 (note that this character string may contain
7477     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>)
7478 schoenebeck 945 </p>
7479     </blockquote>
7480    
7481    
7482     <p>"ENGINE_NAME" -
7483     </p>
7484     <blockquote class="text">
7485     <p>Name of the engine to be deployed for this
7486     instrument.
7487     </p>
7488     </blockquote>
7489    
7490    
7491     <p>"INSTRUMENT_FILE" -
7492     </p>
7493     <blockquote class="text">
7494 schoenebeck 1400 <p>File name of the instrument
7495     (note that this path may contain
7496     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>).
7497 schoenebeck 945 </p>
7498     </blockquote>
7499    
7500    
7501     <p>"INSTRUMENT_NR" -
7502     </p>
7503     <blockquote class="text">
7504     <p>Index of the instrument within the file.
7505     </p>
7506     </blockquote>
7507    
7508    
7509     <p>"INSTRUMENT_NAME" -
7510     </p>
7511     <blockquote class="text">
7512     <p>Name of the loaded instrument as reflected by its file.
7513     In contrast to the "NAME" field, the "INSTRUMENT_NAME" field
7514 schoenebeck 1400 cannot be changed (note that this character string may contain
7515     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>).
7516 schoenebeck 945 </p>
7517     </blockquote>
7518    
7519    
7520     <p>"LOAD_MODE" -
7521     </p>
7522     <blockquote class="text">
7523     <p>Life time of instrument
7524 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).
7525 schoenebeck 945 </p>
7526     </blockquote>
7527    
7528    
7529     <p>"VOLUME" -
7530     </p>
7531     <blockquote class="text">
7532     <p>master volume of the instrument as optionally
7533 schoenebeck 1028 dotted number (where a value &lt; 1.0 means attenuation
7534 schoenebeck 945 and a value > 1.0 means amplification)
7535     </p>
7536     </blockquote>
7537    
7538    
7539     <p>The mentioned fields above don't have to be in particular order.
7540     </p>
7541     </blockquote><p>
7542    
7543     </p>
7544     <p>Example:
7545     </p>
7546     <p>
7547     </p>
7548     <blockquote class="text">
7549 schoenebeck 974 <p>C: "GET MIDI_INSTRUMENT INFO 1 45 120"
7550 schoenebeck 945 </p>
7551     <p>S: "NAME: Drums for Foo Song"
7552     </p>
7553     <p>&nbsp;&nbsp;&nbsp;"ENGINE_NAME: GigEngine"
7554     </p>
7555     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_FILE: /usr/share/joesdrumkit.gig"
7556     </p>
7557     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"
7558     </p>
7559     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NAME: Joe's Drumkit"
7560     </p>
7561     <p>&nbsp;&nbsp;&nbsp;"LOAD_MODE: PERSISTENT"
7562     </p>
7563     <p>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"
7564     </p>
7565     <p>&nbsp;&nbsp;&nbsp;"."
7566     </p>
7567     </blockquote><p>
7568    
7569     </p>
7570     <a name="CLEAR MIDI_INSTRUMENTS"></a><br /><hr />
7571 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>
7572     <a name="rfc.section.6.7.12"></a><h3>6.7.12.&nbsp;
7573     Clear MIDI instrument map</h3>
7574 schoenebeck 945
7575 schoenebeck 974 <p>The front-end can clear a whole MIDI instrument map, that
7576     is delete all its entries by sending the following command:
7577 schoenebeck 945 </p>
7578     <p>
7579     </p>
7580     <blockquote class="text">
7581 schoenebeck 974 <p>CLEAR MIDI_INSTRUMENTS &lt;map&gt;
7582 schoenebeck 945 </p>
7583     </blockquote><p>
7584    
7585     </p>
7586 schoenebeck 974 <p>Where &lt;map&gt; is the numeric ID of the map to clear.
7587     </p>
7588     <p>The front-end can clear all MIDI instrument maps, that
7589     is delete all entries of all maps by sending the following
7590     command:
7591     </p>
7592     <p>
7593     </p>
7594     <blockquote class="text">
7595     <p>CLEAR MIDI_INSTRUMENTS ALL
7596     </p>
7597     </blockquote><p>
7598    
7599     </p>
7600     <p>The command "CLEAR MIDI_INSTRUMENTS ALL" does not delete the
7601     maps, only their entries, thus the map's settings like
7602     custom name will be preservevd.
7603     </p>
7604 schoenebeck 945 <p>Possible Answers:
7605     </p>
7606     <p>
7607     </p>
7608     <blockquote class="text">
7609     <p>"OK" -
7610     </p>
7611     <blockquote class="text">
7612     <p>always
7613     </p>
7614     </blockquote>
7615    
7616    
7617     </blockquote><p>
7618    
7619     </p>
7620 schoenebeck 974 <p>Examples:
7621 schoenebeck 945 </p>
7622     <p>
7623     </p>
7624     <blockquote class="text">
7625 schoenebeck 974 <p>C: "CLEAR MIDI_INSTRUMENTS 0"
7626 schoenebeck 945 </p>
7627     <p>S: "OK"
7628     </p>
7629     </blockquote><p>
7630    
7631     </p>
7632 schoenebeck 974 <p>
7633     </p>
7634     <blockquote class="text">
7635     <p>C: "CLEAR MIDI_INSTRUMENTS ALL"
7636     </p>
7637     <p>S: "OK"
7638     </p>
7639     </blockquote><p>
7640    
7641     </p>
7642 iliev 1162 <a name="Managing Instruments Database"></a><br /><hr />
7643     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7644     <a name="rfc.section.6.8"></a><h3>6.8.&nbsp;
7645     Managing Instruments Database</h3>
7646    
7647     <p>The following commands describe how to use and manage
7648     the instruments database.
7649     </p>
7650 schoenebeck 1363 <p>Notice:
7651     </p>
7652     <p>
7653     </p>
7654     <blockquote class="text">
7655     <p>All command arguments representing a path or
7656     instrument/directory name support escape sequences as described in chapter
7657     "<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>".
7658    
7659     </p>
7660     <p>All occurrences of a forward slash in instrument and directory
7661     names are escaped with its hex (\x2f) or octal (\057) escape sequence.
7662    
7663     </p>
7664     </blockquote><p>
7665    
7666     </p>
7667 iliev 1162 <a name="ADD DB_INSTRUMENT_DIRECTORY"></a><br /><hr />
7668     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7669     <a name="rfc.section.6.8.1"></a><h3>6.8.1.&nbsp;
7670     Creating a new instrument directory</h3>
7671    
7672     <p>The front-end can add a new instrument directory to the
7673     instruments database by sending the following command:
7674     </p>
7675     <p>
7676     </p>
7677     <blockquote class="text">
7678     <p>ADD DB_INSTRUMENT_DIRECTORY &lt;dir&gt;
7679     </p>
7680     </blockquote><p>
7681    
7682     </p>
7683     <p>Where &lt;dir&gt; is the absolute path name of the directory
7684     to be created (encapsulated into apostrophes).
7685     </p>
7686     <p>Possible Answers:
7687     </p>
7688     <p>
7689     </p>
7690     <blockquote class="text">
7691     <p>"OK" -
7692     </p>
7693     <blockquote class="text">
7694     <p>on success
7695     </p>
7696     </blockquote>
7697    
7698    
7699     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7700     </p>
7701     <blockquote class="text">
7702     <p>when the directory could not be created, which
7703     can happen if the directory already exists or the
7704     name contains not allowed symbols
7705     </p>
7706     </blockquote>
7707    
7708    
7709     </blockquote><p>
7710    
7711     </p>
7712     <p>Examples:
7713     </p>
7714     <p>
7715     </p>
7716     <blockquote class="text">
7717     <p>C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'"
7718     </p>
7719     <p>S: "OK"
7720     </p>
7721     </blockquote><p>
7722    
7723     </p>
7724     <a name="REMOVE DB_INSTRUMENT_DIRECTORY"></a><br /><hr />
7725     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7726     <a name="rfc.section.6.8.2"></a><h3>6.8.2.&nbsp;
7727     Deleting an instrument directory</h3>
7728    
7729     <p>The front-end can delete a particular instrument directory
7730     from the instruments database by sending the following command:
7731     </p>
7732     <p>
7733     </p>
7734     <blockquote class="text">
7735     <p>REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] &lt;dir&gt;
7736     </p>
7737     </blockquote><p>
7738    
7739     </p>
7740     <p>Where &lt;dir&gt; is the absolute path name of the directory
7741     to delete. The optional FORCE argument can be used to
7742     force the deletion of a non-empty directory and all its content.
7743     </p>
7744     <p>Possible Answers:
7745     </p>
7746     <p>
7747     </p>
7748     <blockquote class="text">
7749     <p>"OK" -
7750     </p>
7751     <blockquote class="text">
7752     <p>if the directory is deleted successfully
7753     </p>
7754     </blockquote>
7755    
7756    
7757     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7758     </p>
7759     <blockquote class="text">
7760     <p>if the given directory does not exist, or
7761     if trying to delete a non-empty directory,
7762     without using the FORCE argument.
7763     </p>
7764     </blockquote>
7765    
7766    
7767     </blockquote><p>
7768    
7769     </p>
7770     <p>Examples:
7771     </p>
7772     <p>
7773     </p>
7774     <blockquote class="text">
7775     <p>C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'"
7776     </p>
7777     <p>S: "OK"
7778     </p>
7779     </blockquote><p>
7780    
7781     </p>
7782     <a name="GET DB_INSTRUMENT_DIRECTORIES"></a><br /><hr />
7783     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7784     <a name="rfc.section.6.8.3"></a><h3>6.8.3.&nbsp;
7785     Getting amount of instrument directories</h3>
7786    
7787     <p>The front-end can retrieve the current amount of
7788     directories in a specific directory by sending the following command:
7789     </p>
7790     <p>
7791     </p>
7792     <blockquote class="text">
7793 iliev 1189 <p>GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;
7794 iliev 1162 </p>
7795     </blockquote><p>
7796    
7797     </p>
7798     <p>Where &lt;dir&gt; should be replaced by the absolute path
7799 iliev 1189 name of the directory. If RECURSIVE is specified, the number of
7800     all directories, including those located in subdirectories of the
7801     specified directory, will be returned.
7802 iliev 1162 </p>
7803     <p>Possible Answers:
7804     </p>
7805     <p>
7806     </p>
7807     <blockquote class="text">
7808     <p>The current number of instrument directories
7809     in the specified directory.
7810     </p>
7811     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7812     </p>
7813     <blockquote class="text">
7814     <p>if the given directory does not exist.
7815     </p>
7816     </blockquote>
7817    
7818    
7819     </blockquote><p>
7820    
7821     </p>
7822     <p>Example:
7823     </p>
7824     <p>
7825     </p>
7826     <blockquote class="text">
7827     <p>C: "GET DB_INSTRUMENT_DIRECTORIES '/'"
7828     </p>
7829     <p>S: "2"
7830     </p>
7831     </blockquote><p>
7832    
7833     </p>
7834     <a name="LIST DB_INSTRUMENT_DIRECTORIES"></a><br /><hr />
7835     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7836     <a name="rfc.section.6.8.4"></a><h3>6.8.4.&nbsp;
7837     Listing all directories in specific directory</h3>
7838    
7839     <p>The front-end can retrieve the current list of directories
7840     in specific directory by sending the following command:
7841     </p>
7842     <p>
7843     </p>
7844     <blockquote class="text">
7845 iliev 1189 <p>LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;
7846 iliev 1162 </p>
7847     </blockquote><p>
7848    
7849     </p>
7850     <p>Where &lt;dir&gt; should be replaced by the absolute path
7851 iliev 1189 name of the directory. If RECURSIVE is specified, the absolute path names
7852     of all directories, including those located in subdirectories of the
7853     specified directory, will be returned.
7854 iliev 1162 </p>
7855     <p>Possible Answers:
7856     </p>
7857     <p>
7858     </p>
7859     <blockquote class="text">
7860     <p>A comma separated list of all instrument directories
7861     (encapsulated into apostrophes) in the specified directory.
7862     </p>
7863     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7864     </p>
7865     <blockquote class="text">
7866     <p>if the given directory does not exist.
7867     </p>
7868     </blockquote>
7869    
7870    
7871     </blockquote><p>
7872    
7873     </p>
7874     <p>Example:
7875     </p>
7876     <p>
7877     </p>
7878     <blockquote class="text">
7879     <p>C: "LIST DB_INSTRUMENT_DIRECTORIES '/'"
7880     </p>
7881     <p>S: "'Piano Collection','Percussion Collection'"
7882     </p>
7883     </blockquote><p>
7884    
7885     </p>
7886 iliev 1189 <p>
7887     </p>
7888     <blockquote class="text">
7889     <p>C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'"
7890     </p>
7891     <p>S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano Collection/Acoustic/New','/Percussion Collection'"
7892     </p>
7893     </blockquote><p>
7894    
7895     </p>
7896 iliev 1162 <a name="GET DB_INSTRUMENT_DIRECTORY INFO"></a><br /><hr />
7897     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7898     <a name="rfc.section.6.8.5"></a><h3>6.8.5.&nbsp;
7899     Getting instrument directory information</h3>
7900    
7901     <p>The front-end can ask for the current settings of an
7902     instrument directory by sending the following command:
7903     </p>
7904     <p>
7905     </p>
7906     <blockquote class="text">
7907     <p>GET DB_INSTRUMENT_DIRECTORY INFO &lt;dir&gt;
7908     </p>
7909     </blockquote><p>
7910    
7911     </p>
7912     <p>Where &lt;dir&gt; should be replaced by the absolute path
7913     name of the directory the front-end is interested in.
7914     </p>
7915     <p>Possible Answers:
7916     </p>
7917     <p>
7918     </p>
7919     <blockquote class="text">
7920     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
7921     Each answer line begins with the settings category name
7922     followed by a colon and then a space character &lt;SP&gt; and finally
7923     the info character string to that setting category. At the
7924     moment the following categories are defined:
7925     </p>
7926     <p>
7927     </p>
7928     <blockquote class="text">
7929     <p>DESCRIPTION -
7930     </p>
7931     <blockquote class="text">
7932 schoenebeck 1363 <p>A brief description of the directory content.
7933     Note that the character string may contain
7934     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
7935 iliev 1162 </p>
7936     </blockquote>
7937    
7938    
7939     <p>CREATED -
7940     </p>
7941     <blockquote class="text">
7942     <p>The creation date and time of the directory,
7943     represented in "YYYY-MM-DD HH:MM:SS" format
7944     </p>
7945     </blockquote>
7946    
7947    
7948     <p>MODIFIED -
7949     </p>
7950     <blockquote class="text">
7951     <p>The date and time of the last modification of the
7952     directory, represented in "YYYY-MM-DD HH:MM:SS" format
7953     </p>
7954     </blockquote>
7955    
7956    
7957     </blockquote>
7958    
7959    
7960     </blockquote><p>
7961    
7962     </p>
7963     <p>The mentioned fields above don't have to be in particular order.
7964     </p>
7965     <p>Example:
7966     </p>
7967     <p>
7968     </p>
7969     <blockquote class="text">
7970     <p>C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'"
7971     </p>
7972     <p>S: "DESCRIPTION: Piano collection of instruments in GigaSampler format."
7973     </p>
7974     <p>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"
7975     </p>
7976     <p>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"
7977     </p>
7978     <p>&nbsp;&nbsp;&nbsp;"."
7979     </p>
7980     </blockquote><p>
7981    
7982     </p>
7983     <a name="SET DB_INSTRUMENT_DIRECTORY NAME"></a><br /><hr />
7984     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7985     <a name="rfc.section.6.8.6"></a><h3>6.8.6.&nbsp;
7986     Renaming an instrument directory</h3>
7987    
7988     <p>The front-end can alter the name of a specific
7989     instrument directory by sending the following command:
7990     </p>
7991     <p>
7992     </p>
7993     <blockquote class="text">
7994     <p>SET DB_INSTRUMENT_DIRECTORY NAME &lt;dir&gt; &lt;name&gt;
7995     </p>
7996     </blockquote><p>
7997    
7998     </p>
7999     <p>Where &lt;dir&gt; is the absolute path name of the directory and
8000     &lt;name&gt; is the new name for that directory.
8001     </p>
8002     <p>Possible Answers:
8003     </p>
8004     <p>
8005     </p>
8006     <blockquote class="text">
8007     <p>"OK" -
8008     </p>
8009     <blockquote class="text">
8010     <p>on success
8011     </p>
8012     </blockquote>
8013    
8014    
8015     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8016     </p>
8017     <blockquote class="text">
8018     <p>in case the given directory does not exists,
8019     or if a directory with name equal to the new
8020     name already exists.
8021     </p>
8022     </blockquote>
8023    
8024    
8025     </blockquote><p>
8026    
8027     </p>
8028     <p>Example:
8029     </p>
8030     <p>
8031     </p>
8032     <blockquote class="text">
8033     <p>C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic' 'Acoustic'"
8034     </p>
8035     <p>S: "OK"
8036     </p>
8037     </blockquote><p>
8038    
8039     </p>
8040     <a name="MOVE DB_INSTRUMENT_DIRECTORY"></a><br /><hr />
8041     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8042     <a name="rfc.section.6.8.7"></a><h3>6.8.7.&nbsp;
8043     Moving an instrument directory</h3>
8044    
8045     <p>The front-end can move a specific
8046     instrument directory by sending the following command:
8047     </p>
8048     <p>
8049     </p>
8050     <blockquote class="text">
8051     <p>MOVE DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;
8052     </p>
8053     </blockquote><p>
8054    
8055     </p>
8056     <p>Where &lt;dir&gt; is the absolute path name of the directory
8057     to move and &lt;dst&gt; is the location where the directory will
8058     be moved to.
8059     </p>
8060     <p>Possible Answers:
8061     </p>
8062     <p>
8063     </p>
8064     <blockquote class="text">
8065     <p>"OK" -
8066     </p>
8067     <blockquote class="text">
8068     <p>on success
8069     </p>
8070     </blockquote>
8071    
8072    
8073     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8074     </p>
8075     <blockquote class="text">
8076     <p>in case a given directory does not exists,
8077     or if a directory with name equal to the name
8078     of the specified directory already exists in
8079     the destination directory. Error is also thrown
8080     when trying to move a directory to a subdirectory
8081     of itself.
8082     </p>
8083     </blockquote>
8084    
8085    
8086     </blockquote><p>
8087    
8088     </p>
8089     <p>Example:
8090     </p>
8091     <p>
8092     </p>
8093     <blockquote class="text">
8094     <p>C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/Acoustic'"
8095     </p>
8096     <p>S: "OK"
8097     </p>
8098     </blockquote><p>
8099    
8100     </p>
8101 iliev 1189 <a name="COPY DB_INSTRUMENT_DIRECTORY"></a><br /><hr />
8102     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8103     <a name="rfc.section.6.8.8"></a><h3>6.8.8.&nbsp;
8104     Copying instrument directories</h3>
8105    
8106     <p>The front-end can copy a specific
8107     instrument directory by sending the following command:
8108     </p>
8109     <p>
8110     </p>
8111     <blockquote class="text">
8112     <p>COPY DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;
8113     </p>
8114     </blockquote><p>
8115    
8116     </p>
8117     <p>Where &lt;dir&gt; is the absolute path name of the directory
8118     to copy and &lt;dst&gt; is the location where the directory will
8119     be copied to.
8120     </p>
8121     <p>Possible Answers:
8122     </p>
8123     <p>
8124     </p>
8125     <blockquote class="text">
8126     <p>"OK" -
8127     </p>
8128     <blockquote class="text">
8129     <p>on success
8130     </p>
8131     </blockquote>
8132    
8133    
8134     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8135     </p>
8136     <blockquote class="text">
8137     <p>in case a given directory does not exists,
8138     or if a directory with name equal to the name
8139     of the specified directory already exists in
8140     the destination directory. Error is also thrown
8141     when trying to copy a directory to a subdirectory
8142     of itself.
8143     </p>
8144     </blockquote>
8145    
8146    
8147     </blockquote><p>
8148    
8149     </p>
8150     <p>Example:
8151     </p>
8152     <p>
8153     </p>
8154     <blockquote class="text">
8155     <p>C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic' '/Acoustic/Pianos'"
8156     </p>
8157     <p>S: "OK"
8158     </p>
8159     </blockquote><p>
8160    
8161     </p>
8162 iliev 1162 <a name="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"></a><br /><hr />
8163     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8164 iliev 1189 <a name="rfc.section.6.8.9"></a><h3>6.8.9.&nbsp;
8165 iliev 1162 Changing the description of directory</h3>
8166    
8167     <p>The front-end can alter the description of a specific
8168     instrument directory by sending the following command:
8169     </p>
8170     <p>
8171     </p>
8172     <blockquote class="text">
8173     <p>SET DB_INSTRUMENT_DIRECTORY DESCRIPTION &lt;dir&gt; &lt;desc&gt;
8174     </p>
8175     </blockquote><p>
8176    
8177     </p>
8178     <p>Where &lt;dir&gt; is the absolute path name of the directory and
8179 schoenebeck 1363 &lt;desc&gt; is the new description for the directory
8180     (encapsulated into apostrophes, supporting escape sequences as described in chapter
8181     "<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>").
8182 iliev 1162 </p>
8183     <p>Possible Answers:
8184     </p>
8185     <p>
8186     </p>
8187     <blockquote class="text">
8188     <p>"OK" -
8189     </p>
8190     <blockquote class="text">
8191     <p>on success
8192     </p>
8193     </blockquote>
8194    
8195    
8196     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8197     </p>
8198     <blockquote class="text">
8199     <p>in case the given directory does not exists.
8200     </p>
8201     </blockquote>
8202    
8203    
8204     </blockquote><p>
8205    
8206     </p>
8207     <p>Example:
8208     </p>
8209     <p>
8210     </p>
8211     <blockquote class="text">
8212     <p>C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A collection of piano instruments in various format.'"
8213     </p>
8214     <p>S: "OK"
8215     </p>
8216     </blockquote><p>
8217    
8218     </p>
8219 iliev 1189 <a name="FIND DB_INSTRUMENT_DIRECTORIES"></a><br /><hr />
8220     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8221     <a name="rfc.section.6.8.10"></a><h3>6.8.10.&nbsp;
8222     Finding directories</h3>
8223    
8224     <p>The front-end can search for directories
8225     in specific directory by sending the following command:
8226     </p>
8227     <p>
8228     </p>
8229     <blockquote class="text">
8230     <p>FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;
8231     </p>
8232     </blockquote><p>
8233    
8234     </p>
8235     <p>Where &lt;dir&gt; should be replaced by the absolute path
8236     name of the directory to search in. If NON_RECURSIVE is specified, the
8237     directories located in subdirectories of the specified directory will not
8238     be searched. &lt;criteria-list&gt; is a list of search criterias
8239     in form of "key1=val1 key2=val2 ...". The following criterias are
8240     allowed:
8241     </p>
8242     <p>
8243    
8244     <p>NAME='&lt;search-string&gt;'
8245     </p>
8246     <blockquote class="text">
8247     <p>Restricts the search to directories, which names
8248 schoenebeck 1363 satisfy the supplied search string (encapsulated into apostrophes,
8249     supporting escape sequences as described in chapter
8250     "<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>").
8251 iliev 1189 </p>
8252     </blockquote><p>
8253    
8254     </p>
8255    
8256    
8257     <p>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
8258     </p>
8259     <blockquote class="text">
8260     <p>Restricts the search to directories, which creation
8261     date satisfies the specified period, where &lt;date-after&gt;
8262     and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
8263     If &lt;date-after&gt; is omitted the search is restricted to
8264     directories created before &lt;date-before&gt;. If
8265     &lt;date-before&gt; is omitted, the search is restricted
8266     to directories created after &lt;date-after&gt;.
8267     </p>
8268     </blockquote><p>
8269    
8270     </p>
8271    
8272    
8273     <p>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
8274     </p>
8275     <blockquote class="text">
8276     <p>Restricts the search to directories, which
8277     date of last modification satisfies the specified period, where
8278     &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
8279     format. If &lt;date-after&gt; is omitted the search is restricted to
8280     directories, which are last modified before &lt;date-before&gt;. If
8281     &lt;date-before&gt; is omitted, the search is restricted to directories,
8282     which are last modified after &lt;date-after&gt;.
8283     </p>
8284     </blockquote><p>
8285    
8286     </p>
8287    
8288    
8289     <p>DESCRIPTION='&lt;search-string&gt;'
8290     </p>
8291     <blockquote class="text">
8292     <p>Restricts the search to directories with description
8293 schoenebeck 1363 that satisfies the supplied search string
8294     (encapsulated into apostrophes, supporting escape
8295     sequences as described in chapter
8296     "<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>").
8297 iliev 1189 </p>
8298     </blockquote><p>
8299    
8300     </p>
8301    
8302    
8303     <p>Where &lt;search-string&gt; is either a regular expression, or a
8304     word list separated with spaces for OR search and with '+' for AND search.
8305     </p>
8306     <p>Possible Answers:
8307     </p>
8308     <p>
8309     </p>
8310     <blockquote class="text">
8311     <p>A comma separated list with the absolute path names (encapsulated into
8312     apostrophes) of all directories in the specified directory that satisfy
8313     the supplied search criterias.
8314     </p>
8315     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8316     </p>
8317     <blockquote class="text">
8318     <p>if the given directory does not exist.
8319     </p>
8320     </blockquote>
8321    
8322    
8323     </blockquote><p>
8324    
8325     </p>
8326     <p>Example:
8327     </p>
8328     <p>
8329     </p>
8330     <blockquote class="text">
8331     <p>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'"
8332     </p>
8333     <p>S: "'/Piano Collection'"
8334     </p>
8335     </blockquote><p>
8336    
8337     </p>
8338     <p>
8339     </p>
8340     <blockquote class="text">
8341     <p>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:30:13'"
8342     </p>
8343     <p>S: "'/Piano Collection','/Percussions'"
8344     </p>
8345     </blockquote><p>
8346    
8347     </p>
8348 iliev 1162 <a name="ADD DB_INSTRUMENTS"></a><br /><hr />
8349     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8350 iliev 1189 <a name="rfc.section.6.8.11"></a><h3>6.8.11.&nbsp;
8351 iliev 1162 Adding instruments to the instruments database</h3>
8352    
8353     <p>The front-end can add one or more instruments
8354     to the instruments database by sending the following command:
8355     </p>
8356     <p>
8357     </p>
8358     <blockquote class="text">
8359 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;]
8360 iliev 1162 </p>
8361     </blockquote><p>
8362    
8363     </p>
8364     <p>Where &lt;db_dir&gt; is the absolute path name of a directory
8365     (encapsulated into apostrophes) in the instruments database in which
8366     only the new instruments (that are not already in the database) will
8367     be added, &lt;file_path&gt; is the absolute path name of a file or
8368     directory in the file system (encapsulated into apostrophes). In case
8369     an instrument file is supplied, only the instruments in the specified
8370     file will be added to the instruments database. If the optional
8371     &lt;instr_index&gt; (the index of the instrument within the given file)
8372     is supplied too, then only the specified instrument will be added.
8373     In case a directory is supplied, the instruments in that directory
8374     will be added. The OPTIONAL &lt;mode&gt; argument is only applied
8375     when a directory is provided as &lt;file_path&gt; and specifies how the
8376     scanning will be done and has exactly the following possibilities:
8377     </p>
8378     <p>
8379     </p>
8380     <blockquote class="text">
8381 iliev 1201 <p>"RECURSIVE" -
8382     </p>
8383     <blockquote class="text">
8384     <p>All instruments will be processed, including those
8385     in the subdirectories, and the respective subdirectory
8386     tree structure will be recreated in the instruments
8387     database
8388     </p>
8389     </blockquote>
8390    
8391    
8392 iliev 1162 <p>"NON_RECURSIVE" -
8393     </p>
8394     <blockquote class="text">
8395     <p>Only the instruments in the specified directory
8396     will be added, the instruments in the subdirectories
8397     will not be processed.
8398     </p>
8399     </blockquote>
8400    
8401    
8402     <p>"FLAT" -
8403     </p>
8404     <blockquote class="text">
8405     <p>All instruments will be processed, including those
8406     in the subdirectories, but the respective subdirectory
8407     structure will not be recreated in the instruments
8408     database. All instruments will be added directly in
8409     the specified database directory.
8410     </p>
8411     </blockquote>
8412    
8413    
8414     </blockquote><p>
8415    
8416     </p>
8417 schoenebeck 1801 <p> If FILE_AS_DIR argument is supplied, all instruments in an instrument
8418     file will be added to a separate directory in the instruments database, which
8419     name will be the name of the instrument file with the file extension stripped off.
8420    
8421     </p>
8422 iliev 1201 <p>The difference between regular and NON_MODAL versions of the command
8423     is that the regular command returns when the scanning is finished
8424     while NON_MODAL version returns immediately and a background process is launched.
8425     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>
8426     command can be used to monitor the scanning progress.
8427     </p>
8428 iliev 1162 <p>Possible Answers:
8429     </p>
8430     <p>
8431     </p>
8432     <blockquote class="text">
8433     <p>"OK" -
8434     </p>
8435     <blockquote class="text">
8436 iliev 1201 <p>on success when NON_MODAL is not supplied
8437 iliev 1162 </p>
8438     </blockquote>
8439    
8440    
8441 iliev 1201 <p>"OK[&lt;job-id&gt;]" -
8442     </p>
8443     <blockquote class="text">
8444     <p>on success when NON_MODAL is supplied, where &lt;job-id&gt;
8445     is a numerical ID used to obtain status information about the job progress.
8446     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>
8447    
8448     </p>
8449     </blockquote>
8450    
8451    
8452 iliev 1162 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8453     </p>
8454     <blockquote class="text">
8455     <p>if an invalid path is specified.
8456     </p>
8457     </blockquote>
8458    
8459    
8460     </blockquote><p>
8461    
8462     </p>
8463     <p>Examples:
8464     </p>
8465     <p>
8466     </p>
8467     <blockquote class="text">
8468     <p>C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI Bosendorfer 290.gig' 0"
8469     </p>
8470     <p>S: "OK"
8471     </p>
8472     </blockquote><p>
8473    
8474     </p>
8475     <a name="REMOVE DB_INSTRUMENT"></a><br /><hr />
8476     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8477 iliev 1189 <a name="rfc.section.6.8.12"></a><h3>6.8.12.&nbsp;
8478 iliev 1162 Removing an instrument</h3>
8479    
8480     <p>The front-end can remove a particular instrument
8481     from the instruments database by sending the following command:
8482     </p>
8483     <p>
8484     </p>
8485     <blockquote class="text">
8486     <p>REMOVE DB_INSTRUMENT &lt;instr_path&gt;
8487     </p>
8488     </blockquote><p>
8489    
8490     </p>
8491     <p>Where &lt;instr_path&gt; is the absolute path name
8492     (in the instruments database) of the instrument to remove.
8493     </p>
8494     <p>Possible Answers:
8495     </p>
8496     <p>
8497     </p>
8498     <blockquote class="text">
8499     <p>"OK" -
8500     </p>
8501     <blockquote class="text">
8502     <p>if the instrument is removed successfully
8503     </p>
8504     </blockquote>
8505    
8506    
8507     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8508     </p>
8509     <blockquote class="text">
8510     <p>if the given path does not exist or
8511     is a directory.
8512     </p>
8513     </blockquote>
8514    
8515    
8516     </blockquote><p>
8517    
8518     </p>
8519     <p>Examples:
8520     </p>
8521     <p>
8522     </p>
8523     <blockquote class="text">
8524     <p>C: "REMOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'"
8525     </p>
8526     <p>S: "OK"
8527     </p>
8528     </blockquote><p>
8529    
8530     </p>
8531     <a name="GET DB_INSTRUMENTS"></a><br /><hr />
8532     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8533 iliev 1189 <a name="rfc.section.6.8.13"></a><h3>6.8.13.&nbsp;
8534 iliev 1162 Getting amount of instruments</h3>
8535    
8536     <p>The front-end can retrieve the current amount of
8537     instruments in a specific directory by sending the following command:
8538     </p>
8539     <p>
8540     </p>
8541     <blockquote class="text">
8542 iliev 1189 <p>GET DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;
8543 iliev 1162 </p>
8544     </blockquote><p>
8545    
8546     </p>
8547     <p>Where &lt;dir&gt; should be replaced by the absolute path name
8548 iliev 1189 of the directory. If RECURSIVE is specified, the number of all
8549     instruments, including those located in subdirectories of the
8550     specified directory, will be returned.
8551 iliev 1162 </p>
8552     <p>Possible Answers:
8553     </p>
8554     <p>
8555     </p>
8556     <blockquote class="text">
8557     <p>The current number of instruments
8558     in the specified directory.
8559     </p>
8560     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8561     </p>
8562     <blockquote class="text">
8563     <p>if the given directory does not exist.
8564     </p>
8565     </blockquote>
8566    
8567    
8568     </blockquote><p>
8569    
8570     </p>
8571     <p>Example:
8572     </p>
8573     <p>
8574     </p>
8575     <blockquote class="text">
8576     <p>C: "GET DB_INSTRUMENTS '/Piano Collection'"
8577     </p>
8578     <p>S: "2"
8579     </p>
8580     </blockquote><p>
8581    
8582     </p>
8583     <a name="LIST DB_INSTRUMENTS"></a><br /><hr />
8584     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8585 iliev 1189 <a name="rfc.section.6.8.14"></a><h3>6.8.14.&nbsp;
8586 iliev 1162 Listing all instruments in specific directory</h3>
8587    
8588     <p>The front-end can retrieve the current list of instruments
8589     in specific directory by sending the following command:
8590     </p>
8591     <p>
8592     </p>
8593     <blockquote class="text">
8594 iliev 1189 <p>LIST DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;
8595 iliev 1162 </p>
8596     </blockquote><p>
8597    
8598     </p>
8599     <p>Where &lt;dir&gt; should be replaced by the absolute path
8600 iliev 1189 name of the directory. If RECURSIVE is specified, the absolute path
8601     names of all instruments, including those located in subdirectories
8602     of the specified directory, will be returned.
8603 iliev 1162 </p>
8604     <p>Possible Answers:
8605     </p>
8606     <p>
8607     </p>
8608     <blockquote class="text">
8609     <p>A comma separated list of all instruments
8610     (encapsulated into apostrophes) in the specified directory.
8611     </p>
8612     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8613     </p>
8614     <blockquote class="text">
8615     <p>if the given directory does not exist.
8616     </p>
8617     </blockquote>
8618    
8619    
8620     </blockquote><p>
8621    
8622     </p>
8623     <p>Example:
8624     </p>
8625     <p>
8626     </p>
8627     <blockquote class="text">
8628     <p>C: "LIST DB_INSTRUMENTS '/Piano Collection'"
8629     </p>
8630     <p>S: "'Bosendorfer 290','Steinway D'"
8631     </p>
8632     </blockquote><p>
8633    
8634     </p>
8635 iliev 1189 <p>
8636     </p>
8637     <blockquote class="text">
8638     <p>C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'"
8639     </p>
8640     <p>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D','/Piano Collection/Lite/Free Piano'"
8641     </p>
8642     </blockquote><p>
8643    
8644     </p>
8645 iliev 1162 <a name="GET DB_INSTRUMENT INFO"></a><br /><hr />
8646     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8647 iliev 1189 <a name="rfc.section.6.8.15"></a><h3>6.8.15.&nbsp;
8648 iliev 1162 Getting instrument information</h3>
8649    
8650     <p>The front-end can ask for the current settings of an
8651     instrument by sending the following command:
8652     </p>
8653     <p>
8654     </p>
8655     <blockquote class="text">
8656     <p>GET DB_INSTRUMENT INFO &lt;instr_path&gt;
8657     </p>
8658     </blockquote><p>
8659    
8660     </p>
8661     <p>Where &lt;instr_path&gt; should be replaced by the absolute path
8662     name of the instrument the front-end is interested in.
8663     </p>
8664     <p>Possible Answers:
8665     </p>
8666     <p>
8667     </p>
8668     <blockquote class="text">
8669     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
8670     Each answer line begins with the settings category name
8671     followed by a colon and then a space character &lt;SP&gt; and finally
8672     the info character string to that setting category. At the
8673     moment the following categories are defined:
8674     </p>
8675     <p>
8676     </p>
8677     <blockquote class="text">
8678     <p>INSTRUMENT_FILE -
8679     </p>
8680     <blockquote class="text">
8681     <p>File name of the instrument.
8682 schoenebeck 1363 Note that the character string may contain
8683     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
8684 iliev 1162 </p>
8685     </blockquote>
8686    
8687    
8688     <p>INSTRUMENT_NR -
8689     </p>
8690     <blockquote class="text">
8691     <p>Index of the instrument within the file.
8692     </p>
8693     </blockquote>
8694    
8695    
8696     <p>FORMAT_FAMILY -
8697     </p>
8698     <blockquote class="text">
8699     <p>The format family of the instrument.
8700     </p>
8701     </blockquote>
8702    
8703    
8704     <p>FORMAT_VERSION -
8705     </p>
8706     <blockquote class="text">
8707     <p>The format version of the instrument.
8708     </p>
8709     </blockquote>
8710    
8711    
8712     <p>SIZE -
8713     </p>
8714     <blockquote class="text">
8715     <p>The size of the instrument in bytes.
8716     </p>
8717     </blockquote>
8718    
8719    
8720     <p>CREATED -
8721     </p>
8722     <blockquote class="text">
8723     <p>The date and time when the instrument is added
8724     in the instruments database, represented in
8725     "YYYY-MM-DD HH:MM:SS" format
8726     </p>
8727     </blockquote>
8728    
8729    
8730     <p>MODIFIED -
8731     </p>
8732     <blockquote class="text">
8733     <p>The date and time of the last modification of the
8734     instrument's database settings, represented in
8735     "YYYY-MM-DD HH:MM:SS" format
8736     </p>
8737     </blockquote>
8738    
8739    
8740     <p>DESCRIPTION -
8741     </p>
8742     <blockquote class="text">
8743 schoenebeck 1363 <p>A brief description of the instrument.
8744     Note that the character string may contain
8745     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
8746 iliev 1162 </p>
8747     </blockquote>
8748    
8749    
8750     <p>IS_DRUM -
8751     </p>
8752     <blockquote class="text">
8753     <p>either true or false, determines whether the
8754     instrument is a drumkit or a chromatic instrument
8755     </p>
8756     </blockquote>
8757    
8758    
8759     <p>PRODUCT -
8760     </p>
8761     <blockquote class="text">
8762 schoenebeck 1363 <p>The product title of the instrument.
8763     Note that the character string may contain
8764     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
8765 iliev 1162 </p>
8766     </blockquote>
8767    
8768    
8769     <p>ARTISTS -
8770     </p>
8771     <blockquote class="text">
8772 schoenebeck 1363 <p>Lists the artist names.
8773     Note that the character string may contain
8774     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
8775 iliev 1162 </p>
8776     </blockquote>
8777    
8778    
8779     <p>KEYWORDS -
8780     </p>
8781     <blockquote class="text">
8782     <p>Provides a list of keywords that refer to the instrument.
8783     Keywords are separated with semicolon and blank.
8784 schoenebeck 1363 Note that the character string may contain
8785     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
8786 iliev 1162 </p>
8787     </blockquote>
8788    
8789    
8790     </blockquote>
8791    
8792    
8793     </blockquote><p>
8794    
8795     </p>
8796     <p>The mentioned fields above don't have to be in particular order.
8797     </p>
8798     <p>Example:
8799     </p>
8800     <p>
8801     </p>
8802     <blockquote class="text">
8803     <p>C: "GET DB_INSTRUMENT INFO '/Piano Collection/Bosendorfer 290'"
8804     </p>
8805     <p>S: "INSTRUMENT_FILE: /home/me/gigs/Bosendorfer 290.gig"
8806     </p>
8807     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"
8808     </p>
8809     <p>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"
8810     </p>
8811     <p>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 2"
8812     </p>
8813     <p>&nbsp;&nbsp;&nbsp;"SIZE: 2050871870"
8814     </p>
8815     <p>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"
8816     </p>
8817     <p>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"
8818     </p>
8819     <p>&nbsp;&nbsp;&nbsp;"DESCRIPTION: "
8820     </p>
8821     <p>&nbsp;&nbsp;&nbsp;"IS_DRUM: false"
8822     </p>
8823     <p>&nbsp;&nbsp;&nbsp;"PRODUCT: GRANDIOSO Bosendorfer 290"
8824     </p>
8825     <p>&nbsp;&nbsp;&nbsp;"ARTISTS: Post Musical Instruments"
8826     </p>
8827     <p>&nbsp;&nbsp;&nbsp;"KEYWORDS: Bosendorfer"
8828     </p>
8829     <p>&nbsp;&nbsp;&nbsp;"."
8830     </p>
8831     </blockquote><p>
8832    
8833     </p>
8834     <a name="SET DB_INSTRUMENT NAME"></a><br /><hr />
8835     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8836 iliev 1189 <a name="rfc.section.6.8.16"></a><h3>6.8.16.&nbsp;
8837 iliev 1162 Renaming an instrument</h3>
8838    
8839     <p>The front-end can alter the name of a specific
8840     instrument by sending the following command:
8841     </p>
8842     <p>
8843     </p>
8844     <blockquote class="text">
8845     <p>SET DB_INSTRUMENT NAME &lt;instr&gt; &lt;name&gt;
8846     </p>
8847     </blockquote><p>
8848    
8849     </p>
8850     <p>Where &lt;instr&gt; is the absolute path name of the instrument and
8851     &lt;name&gt; is the new name for that instrument.
8852     </p>
8853     <p>Possible Answers:
8854     </p>
8855     <p>
8856     </p>
8857     <blockquote class="text">
8858     <p>"OK" -
8859     </p>
8860     <blockquote class="text">
8861     <p>on success
8862     </p>
8863     </blockquote>
8864    
8865    
8866     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8867     </p>
8868     <blockquote class="text">
8869     <p>in case the given instrument does not exists,
8870     or if an instrument with name equal to the new
8871     name already exists.
8872     </p>
8873     </blockquote>
8874    
8875    
8876     </blockquote><p>
8877    
8878     </p>
8879     <p>Example:
8880     </p>
8881     <p>
8882     </p>
8883     <blockquote class="text">
8884     <p>C: "SET DB_INSTRUMENT NAME '/Piano Collection/Bosendorfer' 'Bosendorfer 290'"
8885     </p>
8886     <p>S: "OK"
8887     </p>
8888     </blockquote><p>
8889    
8890     </p>
8891     <a name="MOVE DB_INSTRUMENT"></a><br /><hr />
8892     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8893 iliev 1189 <a name="rfc.section.6.8.17"></a><h3>6.8.17.&nbsp;
8894 iliev 1162 Moving an instrument</h3>
8895    
8896     <p>The front-end can move a specific instrument to another directory by
8897     sending the following command:
8898     </p>
8899     <p>
8900     </p>
8901     <blockquote class="text">
8902     <p>MOVE DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;
8903     </p>
8904     </blockquote><p>
8905    
8906     </p>
8907     <p>Where &lt;instr&gt; is the absolute path name of the instrument
8908     to move and &lt;dst&gt; is the directory where the instrument will
8909     be moved to.
8910     </p>
8911     <p>Possible Answers:
8912     </p>
8913     <p>
8914     </p>
8915     <blockquote class="text">
8916     <p>"OK" -
8917     </p>
8918     <blockquote class="text">
8919     <p>on success
8920     </p>
8921     </blockquote>
8922    
8923    
8924     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8925     </p>
8926     <blockquote class="text">
8927     <p>in case the given instrument does not exists,
8928     or if an instrument with name equal to the name of the
8929     specified instrument already exists in the destination
8930     directory.
8931     </p>
8932     </blockquote>
8933    
8934    
8935     </blockquote><p>
8936    
8937     </p>
8938     <p>Example:
8939     </p>
8940     <p>
8941     </p>
8942     <blockquote class="text">
8943     <p>C: "MOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Piano Collection/Acoustic'"
8944     </p>
8945     <p>S: "OK"
8946     </p>
8947     </blockquote><p>
8948    
8949     </p>
8950 iliev 1189 <a name="COPY DB_INSTRUMENT"></a><br /><hr />
8951     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8952     <a name="rfc.section.6.8.18"></a><h3>6.8.18.&nbsp;
8953     Copying instruments</h3>
8954    
8955     <p>The front-end can copy a specific instrument to another directory by
8956     sending the following command:
8957     </p>
8958     <p>
8959     </p>
8960     <blockquote class="text">
8961     <p>COPY DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;
8962     </p>
8963     </blockquote><p>
8964    
8965     </p>
8966     <p>Where &lt;instr&gt; is the absolute path name of the instrument
8967     to copy and &lt;dst&gt; is the directory where the instrument will
8968     be copied to.
8969     </p>
8970     <p>Possible Answers:
8971     </p>
8972     <p>
8973     </p>
8974     <blockquote class="text">
8975     <p>"OK" -
8976     </p>
8977     <blockquote class="text">
8978     <p>on success
8979     </p>
8980     </blockquote>
8981    
8982    
8983     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8984     </p>
8985     <blockquote class="text">
8986     <p>in case the given instrument does not exists,
8987     or if an instrument with name equal to the name of the
8988     specified instrument already exists in the destination
8989     directory.
8990     </p>
8991     </blockquote>
8992    
8993    
8994     </blockquote><p>
8995    
8996     </p>
8997     <p>Example:
8998     </p>
8999     <p>
9000     </p>
9001     <blockquote class="text">
9002     <p>C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Acoustic/Pianos/'"
9003     </p>
9004     <p>S: "OK"
9005     </p>
9006     </blockquote><p>
9007    
9008     </p>
9009 iliev 1162 <a name="SET DB_INSTRUMENT DESCRIPTION"></a><br /><hr />
9010     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9011 iliev 1189 <a name="rfc.section.6.8.19"></a><h3>6.8.19.&nbsp;
9012 iliev 1162 Changing the description of instrument</h3>
9013    
9014     <p>The front-end can alter the description of a specific
9015     instrument by sending the following command:
9016     </p>
9017     <p>
9018     </p>
9019     <blockquote class="text">
9020     <p>SET DB_INSTRUMENT DESCRIPTION &lt;instr&gt; &lt;desc&gt;
9021     </p>
9022     </blockquote><p>
9023    
9024     </p>
9025     <p>Where &lt;instr&gt; is the absolute path name of the instrument and
9026 schoenebeck 1572 &lt;desc&gt; is the new description for the instrument
9027 schoenebeck 1363 (encapsulated into apostrophes, supporting escape sequences as described in chapter
9028     "<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>").
9029 iliev 1162 </p>
9030     <p>Possible Answers:
9031     </p>
9032     <p>
9033     </p>
9034     <blockquote class="text">
9035     <p>"OK" -
9036     </p>
9037     <blockquote class="text">
9038     <p>on success
9039     </p>
9040     </blockquote>
9041    
9042    
9043     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
9044     </p>
9045     <blockquote class="text">
9046     <p>in case the given instrument does not exists.
9047     </p>
9048     </blockquote>
9049    
9050    
9051     </blockquote><p>
9052    
9053     </p>
9054     <p>Example:
9055     </p>
9056     <p>
9057     </p>
9058     <blockquote class="text">
9059     <p>C: "SET DB_INSTRUMENT DESCRIPTION '/Piano Collection/Acoustic/Bosendorfer 290' 'No comment :)'"
9060     </p>
9061     <p>S: "OK"
9062     </p>
9063     </blockquote><p>
9064    
9065     </p>
9066 iliev 1189 <a name="FIND DB_INSTRUMENTS"></a><br /><hr />
9067     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9068     <a name="rfc.section.6.8.20"></a><h3>6.8.20.&nbsp;
9069     Finding instruments</h3>
9070    
9071     <p>The front-end can search for instruments
9072     in specific directory by sending the following command:
9073     </p>
9074     <p>
9075     </p>
9076     <blockquote class="text">
9077     <p>FIND DB_INSTRUMENTS [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;
9078     </p>
9079     </blockquote><p>
9080    
9081     </p>
9082     <p>Where &lt;dir&gt; should be replaced by the absolute path
9083     name of the directory to search in. If NON_RECURSIVE is specified, the
9084     directories located in subdirectories of the specified directory will not
9085     be searched. &lt;criteria-list&gt; is a list of search criterias
9086     in form of "key1=val1 key2=val2 ...". The following criterias are
9087     allowed:
9088     </p>
9089     <p>
9090    
9091     <p>NAME='&lt;search-string&gt;'
9092     </p>
9093     <blockquote class="text">
9094     <p>Restricts the search to instruments, which names
9095 schoenebeck 1363 satisfy the supplied search string (encapsulated into apostrophes,
9096     supporting escape sequences as described in chapter
9097     "<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>").
9098 iliev 1189 </p>
9099     </blockquote><p>
9100    
9101     </p>
9102    
9103    
9104     <p>SIZE=[&lt;min&gt;]..[&lt;max&gt;]
9105     </p>
9106     <blockquote class="text">
9107 schoenebeck 1251 <p>Restricts the search to instruments, which
9108 iliev 1189 size is in the specified range. If &lt;min&gt; is omitted,
9109     the search results are restricted to instruments with size less then
9110     or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the
9111     search is restricted to instruments with size greater then
9112     or equal to &lt;min&gt;.
9113     </p>
9114     </blockquote><p>
9115    
9116     </p>
9117    
9118    
9119     <p>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
9120     </p>
9121     <blockquote class="text">
9122     <p>Restricts the search to instruments, which creation
9123     date satisfies the specified period, where &lt;date-after&gt;
9124     and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
9125     If &lt;date-after&gt; is omitted the search is restricted to
9126     instruments created before &lt;date-before&gt;. If
9127     &lt;date-before&gt; is omitted, the search is restricted
9128     to instruments created after &lt;date-after&gt;.
9129     </p>
9130     </blockquote><p>
9131    
9132     </p>
9133    
9134    
9135     <p>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
9136     </p>
9137     <blockquote class="text">
9138     <p>Restricts the search to instruments, which
9139     date of last modification satisfies the specified period, where
9140     &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
9141     format. If &lt;date-after&gt; is omitted the search is restricted to
9142     instruments, which are last modified before &lt;date-before&gt;. If
9143     &lt;date-before&gt; is omitted, the search is restricted to instruments,
9144     which are last modified after &lt;date-after&gt;.
9145     </p>
9146     </blockquote><p>
9147    
9148     </p>
9149    
9150    
9151     <p>DESCRIPTION='&lt;search-string&gt;'
9152     </p>
9153     <blockquote class="text">
9154     <p>Restricts the search to instruments with description
9155 schoenebeck 1363 that satisfies the supplied search string (encapsulated into apostrophes,
9156     supporting escape sequences as described in chapter
9157     "<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>").
9158 iliev 1189 </p>
9159     </blockquote><p>
9160    
9161     </p>
9162    
9163    
9164     <p>PRODUCT='&lt;search-string&gt;'
9165     </p>
9166     <blockquote class="text">
9167     <p>Restricts the search to instruments with product info
9168 schoenebeck 1363 that satisfies the supplied search string (encapsulated into apostrophes,
9169     supporting escape sequences as described in chapter
9170     "<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>").
9171 iliev 1189 </p>
9172     </blockquote><p>
9173    
9174     </p>
9175    
9176    
9177     <p>ARTISTS='&lt;search-string&gt;'
9178     </p>
9179     <blockquote class="text">
9180     <p>Restricts the search to instruments with artists info
9181 schoenebeck 1363 that satisfies the supplied search string (encapsulated into apostrophes,
9182     supporting escape sequences as described in chapter
9183     "<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>").
9184 iliev 1189 </p>
9185     </blockquote><p>
9186    
9187     </p>
9188    
9189    
9190     <p>KEYWORDS='&lt;search-string&gt;'
9191     </p>
9192     <blockquote class="text">
9193     <p>Restricts the search to instruments with keyword list
9194 schoenebeck 1363 that satisfies the supplied search string (encapsulated into apostrophes,
9195     supporting escape sequences as described in chapter
9196     "<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>").
9197 iliev 1189 </p>
9198     </blockquote><p>
9199    
9200     </p>
9201    
9202    
9203     <p>IS_DRUM=true | false
9204     </p>
9205     <blockquote class="text">
9206 schoenebeck 1251 <p>Either true or false. Restricts the search to
9207 iliev 1189 drum kits or chromatic instruments.
9208     </p>
9209     </blockquote><p>
9210    
9211     </p>
9212    
9213    
9214     <p>FORMAT_FAMILIES='&lt;format-list&gt;'
9215     </p>
9216     <blockquote class="text">
9217     <p>Restricts the search to instruments of the supplied format families,
9218     where &lt;format-list&gt; is a comma separated list of format families.
9219     </p>
9220     </blockquote><p>
9221    
9222     </p>
9223    
9224    
9225     <p>Where &lt;search-string&gt; is either a regular expression, or a
9226     word list separated with spaces for OR search and with '+' for AND search.
9227     </p>
9228     <p>Possible Answers:
9229     </p>
9230     <p>
9231     </p>
9232     <blockquote class="text">
9233     <p>A comma separated list with the absolute path names (encapsulated into
9234     apostrophes) of all instruments in the specified directory that satisfy
9235     the supplied search criterias.
9236     </p>
9237     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
9238     </p>
9239     <blockquote class="text">
9240     <p>if the given directory does not exist.
9241     </p>
9242     </blockquote>
9243    
9244    
9245     </blockquote><p>
9246    
9247     </p>
9248     <p>Example:
9249     </p>
9250     <p>
9251     </p>
9252     <blockquote class="text">
9253     <p>C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+290'"
9254     </p>
9255     <p>S: "'/Piano Collection/Bosendorfer 290'"
9256     </p>
9257     </blockquote><p>
9258    
9259     </p>
9260     <p>
9261     </p>
9262     <blockquote class="text">
9263     <p>C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01 09:30:13..'"
9264     </p>
9265     <p>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D'"
9266     </p>
9267     </blockquote><p>
9268    
9269     </p>
9270 iliev 1201 <a name="GET DB_INSTRUMENTS_JOB INFO"></a><br /><hr />
9271     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9272     <a name="rfc.section.6.8.21"></a><h3>6.8.21.&nbsp;
9273     Getting job status information</h3>
9274    
9275     <p>The front-end can ask for the current status of a
9276     particular database instruments job by sending the following command:
9277     </p>
9278     <p>
9279     </p>
9280     <blockquote class="text">
9281     <p>GET DB_INSTRUMENTS_JOB INFO &lt;job-id&gt;
9282     </p>
9283     </blockquote><p>
9284    
9285     </p>
9286     <p>Where &lt;job-id&gt; should be replaced by the numerical ID
9287     of the job the front-end is interested in.
9288     </p>
9289     <p>Possible Answers:
9290     </p>
9291     <p>
9292     </p>
9293     <blockquote class="text">
9294     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
9295     Each answer line begins with the settings category name
9296     followed by a colon and then a space character &lt;SP&gt; and finally
9297     the info character string to that setting category. At the
9298     moment the following categories are defined:
9299     </p>
9300     <p>
9301     </p>
9302     <blockquote class="text">
9303     <p>FILES_TOTAL -
9304     </p>
9305     <blockquote class="text">
9306     <p>The total number of files scheduled for scanning
9307     </p>
9308     </blockquote>
9309    
9310    
9311     <p>FILES_SCANNED -
9312     </p>
9313     <blockquote class="text">
9314     <p>The current number of scanned files
9315     </p>
9316     </blockquote>
9317    
9318    
9319     <p>SCANNING -
9320     </p>
9321     <blockquote class="text">
9322     <p>The absolute path name of the file which is currently
9323     being scanned
9324     </p>
9325     </blockquote>
9326    
9327    
9328     <p>STATUS -
9329     </p>
9330     <blockquote class="text">
9331     <p>An integer value between 0 and 100 indicating the
9332     scanning progress percentage of the file which is
9333     currently being scanned
9334     </p>
9335     </blockquote>
9336    
9337    
9338     </blockquote>
9339    
9340    
9341     </blockquote><p>
9342    
9343     </p>
9344     <p>The mentioned fields above don't have to be in particular order.
9345     </p>
9346     <p>Example:
9347     </p>
9348     <p>
9349     </p>
9350     <blockquote class="text">
9351     <p>C: "GET DB_INSTRUMENTS_JOB INFO 2"
9352     </p>
9353     <p>S: "FILES_TOTAL: 12"
9354     </p>
9355     <p>&nbsp;&nbsp;&nbsp;"FILES_SCANNED: 7"
9356     </p>
9357     <p>&nbsp;&nbsp;&nbsp;"SCANNING: /home/me/gigs/Bosendorfer 290.gig"
9358     </p>
9359     <p>&nbsp;&nbsp;&nbsp;"STATUS: 42"
9360     </p>
9361     <p>&nbsp;&nbsp;&nbsp;"."
9362     </p>
9363     </blockquote><p>
9364    
9365     </p>
9366 schoenebeck 1363 <a name="FORMAT INSTRUMENTS_DB"></a><br /><hr />
9367     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9368     <a name="rfc.section.6.8.22"></a><h3>6.8.22.&nbsp;
9369     Formatting the instruments database</h3>
9370    
9371     <p>The front-end can remove all instruments and directories and re-create
9372     the instruments database structure (e.g., in case of a database corruption)
9373     by sending the following command:
9374     </p>
9375     <p>
9376     </p>
9377     <blockquote class="text">
9378     <p>FORMAT INSTRUMENTS_DB
9379     </p>
9380     </blockquote><p>
9381    
9382     </p>
9383     <p>Possible Answers:
9384     </p>
9385     <p>
9386     </p>
9387     <blockquote class="text">
9388     <p>"OK" -
9389     </p>
9390     <blockquote class="text">
9391     <p>on success
9392     </p>
9393     </blockquote>
9394    
9395    
9396     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
9397     </p>
9398     <blockquote class="text">
9399     <p>If the formatting of the instruments database
9400     failed.
9401     </p>
9402     </blockquote>
9403    
9404    
9405     </blockquote><p>
9406    
9407     </p>
9408 iliev 1731 <a name="FIND LOST DB_INSTRUMENT_FILES"></a><br /><hr />
9409     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9410     <a name="rfc.section.6.8.23"></a><h3>6.8.23.&nbsp;
9411     Checking for lost instrument files</h3>
9412    
9413     <p>The front-end can retrieve the list of all instrument files in the instruments database
9414     that don't exist in the filesystem by sending the following command:
9415     </p>
9416     <p>
9417     </p>
9418     <blockquote class="text">
9419     <p>FIND LOST DB_INSTRUMENT_FILES
9420     </p>
9421     </blockquote><p>
9422    
9423     </p>
9424     <p>Possible Answers:
9425     </p>
9426     <p>
9427     </p>
9428     <blockquote class="text">
9429     <p>A comma separated list with the absolute path names
9430     (encapsulated into apostrophes) of all lost instrument files.
9431     </p>
9432     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
9433     </p>
9434     <blockquote class="text">
9435     <p>in case it failed, providing an appropriate error code and error message.
9436     </p>
9437     </blockquote>
9438    
9439    
9440     </blockquote><p>
9441    
9442     </p>
9443     <p>Example:
9444     </p>
9445     <p>
9446     </p>
9447     <blockquote class="text">
9448     <p>C: "FIND LOST DB_INSTRUMENT_FILES"
9449     </p>
9450     <p>S: "'/gigs/Bosendorfer 290.gig','/gigs/Steinway D.gig','/gigs/Free Piano.gig'"
9451     </p>
9452     </blockquote><p>
9453    
9454     </p>
9455     <a name="SET DB_INSTRUMENT FILE_PATH"></a><br /><hr />
9456     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9457     <a name="rfc.section.6.8.24"></a><h3>6.8.24.&nbsp;
9458     Replacing an instrument file</h3>
9459    
9460     <p>The front-end can substitute all occurrences of an instrument file
9461     in the instruments database with a new one by sending the following command:
9462     </p>
9463     <p>
9464     </p>
9465     <blockquote class="text">
9466     <p>SET DB_INSTRUMENT FILE_PATH &lt;old_path&gt; &lt;new_path&gt;
9467     </p>
9468     </blockquote><p>
9469    
9470     </p>
9471     <p>Where &lt;old_path&gt; is the absolute path name of the instrument file
9472     to substitute with &lt;new_path&gt;.
9473     </p>
9474     <p>Possible Answers:
9475     </p>
9476     <p>
9477     </p>
9478     <blockquote class="text">
9479     <p>"OK" -
9480     </p>
9481     <blockquote class="text">
9482     <p>on success
9483     </p>
9484     </blockquote>
9485    
9486    
9487     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
9488     </p>
9489     <blockquote class="text">
9490     <p>in case it failed, providing an appropriate error code and error message.
9491     </p>
9492     </blockquote>
9493    
9494    
9495     </blockquote><p>
9496    
9497     </p>
9498     <p>Example:
9499     </p>
9500     <p>
9501     </p>
9502     <blockquote class="text">
9503     <p>C: "SET DB_INSTRUMENT FILE_PATH '/gigs/Bosendorfer 290.gig' '/gigs/pianos/Bosendorfer 290.gig'"
9504     </p>
9505     <p>S: "OK"
9506     </p>
9507     </blockquote><p>
9508    
9509     </p>
9510 schoenebeck 1363 <a name="editing_instruments"></a><br /><hr />
9511     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9512     <a name="rfc.section.6.9"></a><h3>6.9.&nbsp;
9513     Editing Instruments</h3>
9514    
9515     <p>The sampler allows to edit instruments while playing with the
9516     sampler by spawning an external (3rd party) instrument editor
9517     application for a given instrument. The 3rd party instrument
9518     editor applications have to place a respective plugin DLL file
9519     into the sampler's plugins directory. The sampler will
9520     automatically try to load all plugin DLLs in that directory on
9521     startup and only on startup!
9522     </p>
9523     <p>At the moment there is only one command for this feature set,
9524     but this will most probably change in future.
9525     </p>
9526     <a name="EDIT INSTRUMENT"></a><br /><hr />
9527     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9528     <a name="rfc.section.6.9.1"></a><h3>6.9.1.&nbsp;
9529     Opening an appropriate instrument editor application</h3>
9530    
9531     <p>The front-end can request to open an appropriate instrument
9532     editor application by sending the following command:
9533     </p>
9534     <p>
9535     </p>
9536     <blockquote class="text">
9537 schoenebeck 1430 <p>EDIT CHANNEL INSTRUMENT &lt;sampler-channel&gt;
9538 schoenebeck 1363 </p>
9539     </blockquote><p>
9540    
9541     </p>
9542     <p>Where &lt;sampler-channel&gt; should be replaced by the
9543     number of the sampler channel as given by the
9544     <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
9545     or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a>
9546     command.
9547     </p>
9548     <p>The sampler will try to ask all registered instrument
9549     editors (or to be more specific: their sampler plugins)
9550     whether they are capable to handle the instrument on the
9551     given sampler channel. The sampler will simply use the first
9552     instrument editor application which replied with a positive
9553     answer and spawn that instrument editor application within
9554     the sampler's process and provide that application access
9555     to the instrument's data structures, so both applications
9556     can share and access the same instruments data at the same
9557     time, thus allowing to immediately hear changes with the
9558     sampler made by the instrument editor.
9559     </p>
9560     <p>Note: consequently instrument editors are always spawned
9561     locally on the same machine where the sampler is running
9562     on!
9563     </p>
9564     <p>Possible Answers:
9565     </p>
9566     <p>
9567     </p>
9568     <blockquote class="text">
9569     <p>"OK" -
9570     </p>
9571     <blockquote class="text">
9572     <p>when an appropriate instrument editor was
9573     launched
9574     </p>
9575     </blockquote>
9576    
9577    
9578     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
9579     </p>
9580     <blockquote class="text">
9581     <p>when an appropriate instrument editor was
9582     launched, but there are noteworthy issues
9583     </p>
9584     </blockquote>
9585    
9586    
9587     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
9588     </p>
9589     <blockquote class="text">
9590     <p>when an appropriate instrument editor
9591     could not be launched
9592     </p>
9593     </blockquote>
9594    
9595    
9596     </blockquote><p>
9597    
9598     </p>
9599     <p>Examples:
9600     </p>
9601     <p>
9602     </p>
9603     <blockquote class="text">
9604 schoenebeck 1430 <p>C: "EDIT CHANNEL INSTRUMENT 0"
9605 schoenebeck 1363 </p>
9606     <p>S: "OK"
9607     </p>
9608     </blockquote><p>
9609    
9610     </p>
9611 schoenebeck 1572 <a name="file_management"></a><br /><hr />
9612     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9613     <a name="rfc.section.6.10"></a><h3>6.10.&nbsp;
9614     Managing Files</h3>
9615    
9616     <p>You can query detailed informations about files located
9617     at the same system where the sampler instance is running on.
9618     Using this command set allows to retrieve file informations
9619     even remotely from another machine.
9620     </p>
9621     <a name="GET FILE INSTRUMENTS"></a><br /><hr />
9622     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9623     <a name="rfc.section.6.10.1"></a><h3>6.10.1.&nbsp;
9624     Retrieving amount of instruments of a file</h3>
9625    
9626     <p>The front-end can retrieve the amount of instruments
9627     within a given instrument file by sending the
9628     following command:
9629     </p>
9630     <p>
9631     </p>
9632     <blockquote class="text">
9633     <p>GET FILE INSTRUMENTS &lt;filename&gt;
9634     </p>
9635     </blockquote><p>
9636    
9637     </p>
9638     <p>Where &lt;filename&gt; is the name of the instrument
9639     file (encapsulated into apostrophes, supporting escape
9640     sequences as described in chapter
9641     "<a class='info' href='#character_set'>Character Set and Escape
9642     Sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>").
9643     </p>
9644     <p>The sampler will try to ask all sampler engines,
9645     whether they support the given file and ask the first
9646     engine with a positive answer for the amount of
9647     instruments.
9648     </p>
9649     <p>Possible Answers:
9650     </p>
9651     <p>
9652     </p>
9653     <blockquote class="text">
9654     <p>On success, the sampler will answer by
9655     returning the amount of instruments.
9656    
9657     </p>
9658     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
9659     </p>
9660     <blockquote class="text">
9661     <p>if the file could not be handled
9662     </p>
9663     </blockquote>
9664    
9665    
9666     </blockquote><p>
9667    
9668     </p>
9669     <p>Examples:
9670     </p>
9671     <p>
9672     </p>
9673     <blockquote class="text">
9674     <p>C: "GET FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"
9675     </p>
9676     <p>S: "10"
9677     </p>
9678     </blockquote><p>
9679    
9680     </p>
9681     <a name="LIST FILE INSTRUMENTS"></a><br /><hr />
9682     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9683     <a name="rfc.section.6.10.2"></a><h3>6.10.2.&nbsp;
9684     Retrieving all instruments of a file</h3>
9685    
9686     <p>The front-end can retrieve a list of all instruments
9687     within a given instrument file by sending the
9688     following command:
9689     </p>
9690     <p>
9691     </p>
9692     <blockquote class="text">
9693     <p>LIST FILE INSTRUMENTS &lt;filename&gt;
9694     </p>
9695     </blockquote><p>
9696    
9697     </p>
9698     <p>Where &lt;filename&gt; is the name of the instrument
9699     file (encapsulated into apostrophes, supporting escape
9700     sequences as described in chapter
9701     "<a class='info' href='#character_set'>Character Set and Escape
9702     Sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>").
9703     </p>
9704     <p>The sampler will try to ask all sampler engines,
9705     whether they support the given file and ask the first
9706     engine with a positive answer for a list of IDs for the
9707     instruments in the given file.
9708     </p>
9709     <p>Possible Answers:
9710     </p>
9711     <p>
9712     </p>
9713     <blockquote class="text">
9714     <p>On success, the sampler will answer by
9715     returning a comma separated list of
9716     instrument IDs.
9717    
9718     </p>
9719     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
9720     </p>
9721     <blockquote class="text">
9722     <p>if the file could not be handled
9723     </p>
9724     </blockquote>
9725    
9726    
9727     </blockquote><p>
9728    
9729     </p>
9730     <p>Examples:
9731     </p>
9732     <p>
9733     </p>
9734     <blockquote class="text">
9735     <p>C: "LIST FILE INSTRUMENTS 'D:/Sounds/Foo.gig'"
9736     </p>
9737     <p>S: "0,1,2,3,4,5,6,7,8,9"
9738     </p>
9739     </blockquote><p>
9740    
9741     </p>
9742     <a name="GET FILE INSTRUMENT INFO"></a><br /><hr />
9743     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9744     <a name="rfc.section.6.10.3"></a><h3>6.10.3.&nbsp;
9745     Retrieving informations about one instrument in a file</h3>
9746    
9747     <p>The front-end can retrieve detailed informations
9748     about a specific instrument within a given instrument
9749     file by sending the following command:
9750     </p>
9751     <p>
9752     </p>
9753     <blockquote class="text">
9754     <p>GET FILE INSTRUMENT INFO &lt;filename&gt;
9755     &lt;instr-id&gt;
9756     </p>
9757     </blockquote><p>
9758    
9759     </p>
9760     <p>Where &lt;filename&gt; is the name of the instrument
9761     file (encapsulated into apostrophes, supporting escape
9762     sequences as described in chapter
9763     "<a class='info' href='#character_set'>Character Set and Escape
9764     Sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>") and &lt;instr-id&gt; is the numeric
9765     instrument ID as returned by the
9766     <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.
9767     </p>
9768     <p>The sampler will try to ask all sampler engines,
9769     whether they support the given file and ask the first
9770     engine with a positive answer for informations about the
9771     specific instrument in the given file.
9772     </p>
9773     <p>Possible Answers:
9774     </p>
9775     <p>
9776     </p>
9777     <blockquote class="text">
9778     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
9779     Each answer line begins with the settings category name
9780     followed by a colon and then a space character &lt;SP&gt; and finally
9781     the info character string to that setting category. At the
9782     moment the following categories are defined:
9783     </p>
9784     <p>
9785     </p>
9786     <blockquote class="text">
9787     <p>NAME -
9788     </p>
9789     <blockquote class="text">
9790     <p>name of the instrument as
9791     stored in the instrument file
9792     </p>
9793     </blockquote>
9794    
9795    
9796     <p>FORMAT_FAMILY -
9797     </p>
9798     <blockquote class="text">
9799     <p>name of the sampler format
9800     of the given instrument
9801     </p>
9802     </blockquote>
9803    
9804    
9805     <p>FORMAT_VERSION -
9806     </p>
9807     <blockquote class="text">
9808     <p>version of the sampler format
9809     the instrumen is stored as
9810     </p>
9811     </blockquote>
9812    
9813    
9814     <p>PRODUCT -
9815     </p>
9816     <blockquote class="text">
9817     <p>official product name of the
9818     instrument as stored in the file
9819    
9820     </p>
9821     </blockquote>
9822    
9823    
9824     <p>ARTISTS -
9825     </p>
9826     <blockquote class="text">
9827     <p>artists / sample library
9828     vendor of the instrument
9829     </p>
9830     </blockquote>
9831    
9832    
9833 iliev 1773 <p>KEY_BINDINGS -
9834     </p>
9835     <blockquote class="text">
9836     <p>comma separated list of integer values representing
9837     the instrument's key mapping in the range between 0 .. 127,
9838     reflecting the analog meaning of the MIDI specification.
9839     </p>
9840 schoenebeck 1572 </blockquote>
9841 iliev 1773
9842    
9843     <p>KEYSWITCH_BINDINGS -
9844     </p>
9845     <blockquote class="text">
9846     <p>comma separated list of integer values representing
9847     the instrument's keyswitch mapping in the range between 0 .. 127,
9848     reflecting the analog meaning of the MIDI specification.
9849     </p>
9850     </blockquote>
9851    
9852    
9853     </blockquote>
9854 schoenebeck 1572
9855    
9856     </blockquote><p>
9857    
9858     </p>
9859     <p>The mentioned fields above don't have to be in particular order.
9860     </p>
9861     <p>Example:
9862     </p>
9863     <p>
9864     </p>
9865     <blockquote class="text">
9866     <p>C: "GET FILE INSTRUMENT INFO 'D:/Sounds/Foo.gig' 0"
9867     </p>
9868     <p>S: "NAME: Lunatic Loops"
9869     </p>
9870     <p>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"
9871     </p>
9872     <p>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 3"
9873     </p>
9874     <p>&nbsp;&nbsp;&nbsp;"PRODUCT: The Backbone Bongo Beats"
9875     </p>
9876     <p>&nbsp;&nbsp;&nbsp;"ARTISTS: Jimmy the Fish"
9877     </p>
9878     <p>&nbsp;&nbsp;&nbsp;"."
9879     </p>
9880     </blockquote><p>
9881    
9882     </p>
9883 senoner 542 <a name="command_syntax"></a><br /><hr />
9884 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>
9885     <a name="rfc.section.7"></a><h3>7.&nbsp;
9886     Command Syntax</h3>
9887 senoner 542
9888 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>
9889     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>)
9890 schoenebeck 575 where applicable.
9891 schoenebeck 940
9892 senoner 542 </p>
9893 schoenebeck 575 <p>input =
9894     </p>
9895     <blockquote class="text">
9896     <p>line LF
9897 schoenebeck 940
9898 schoenebeck 575 </p>
9899     <p>/ line CR LF
9900 schoenebeck 940
9901 schoenebeck 575 </p>
9902 schoenebeck 708 </blockquote><p>
9903 schoenebeck 575
9904 schoenebeck 708 </p>
9905 schoenebeck 575 <p>line =
9906     </p>
9907     <blockquote class="text">
9908     <p>/* epsilon (empty line ignored) */
9909 schoenebeck 940
9910 schoenebeck 575 </p>
9911     <p>/ comment
9912 schoenebeck 940
9913 schoenebeck 575 </p>
9914     <p>/ command
9915 schoenebeck 940
9916 schoenebeck 575 </p>
9917     <p>/ error
9918 schoenebeck 940
9919 schoenebeck 575 </p>
9920 schoenebeck 708 </blockquote><p>
9921 schoenebeck 575
9922 schoenebeck 708 </p>
9923 schoenebeck 575 <p>comment =
9924     </p>
9925     <blockquote class="text">
9926     <p>'#'
9927 schoenebeck 940
9928 schoenebeck 575 </p>
9929     <p>/ comment '#'
9930 schoenebeck 940
9931 schoenebeck 575 </p>
9932     <p>/ comment SP
9933 schoenebeck 940
9934 schoenebeck 575 </p>
9935     <p>/ comment number
9936 schoenebeck 940
9937 schoenebeck 575 </p>
9938     <p>/ comment string
9939 schoenebeck 940
9940 schoenebeck 575 </p>
9941 schoenebeck 708 </blockquote><p>
9942 schoenebeck 575
9943 schoenebeck 708 </p>
9944 schoenebeck 575 <p>command =
9945     </p>
9946     <blockquote class="text">
9947 schoenebeck 974 <p>ADD SP add_instruction
9948 schoenebeck 940
9949 schoenebeck 575 </p>
9950 schoenebeck 945 <p>/ MAP SP map_instruction
9951    
9952     </p>
9953     <p>/ UNMAP SP unmap_instruction
9954    
9955     </p>
9956 schoenebeck 575 <p>/ GET SP get_instruction
9957 schoenebeck 940
9958 schoenebeck 575 </p>
9959     <p>/ CREATE SP create_instruction
9960 schoenebeck 940
9961 schoenebeck 575 </p>
9962     <p>/ DESTROY SP destroy_instruction
9963 schoenebeck 940
9964 schoenebeck 575 </p>
9965     <p>/ LIST SP list_instruction
9966 schoenebeck 940
9967 schoenebeck 575 </p>
9968     <p>/ LOAD SP load_instruction
9969 schoenebeck 940
9970 schoenebeck 575 </p>
9971 schoenebeck 945 <p>/ REMOVE SP remove_instruction
9972 schoenebeck 940
9973 schoenebeck 575 </p>
9974     <p>/ SET SP set_instruction
9975 schoenebeck 940
9976 schoenebeck 575 </p>
9977     <p>/ SUBSCRIBE SP subscribe_event
9978 schoenebeck 940
9979 schoenebeck 575 </p>
9980     <p>/ UNSUBSCRIBE SP unsubscribe_event
9981 schoenebeck 940
9982 schoenebeck 575 </p>
9983 schoenebeck 945 <p>/ RESET SP reset_instruction
9984 schoenebeck 940
9985 schoenebeck 575 </p>
9986 schoenebeck 945 <p>/ CLEAR SP clear_instruction
9987    
9988     </p>
9989 iliev 1189 <p>/ FIND SP find_instruction
9990    
9991     </p>
9992 iliev 1162 <p>/ MOVE SP move_instruction
9993    
9994     </p>
9995 iliev 1189 <p>/ COPY SP copy_instruction
9996    
9997     </p>
9998 schoenebeck 1251 <p>/ EDIT SP edit_instruction
9999    
10000     </p>
10001 schoenebeck 1363 <p>/ FORMAT SP format_instruction
10002 schoenebeck 1801
10003 iliev 1773 </p>
10004 schoenebeck 1801 <p>/ SEND SP send_instruction
10005 schoenebeck 1363
10006     </p>
10007 schoenebeck 575 <p>/ RESET
10008 schoenebeck 940
10009 schoenebeck 575 </p>
10010     <p>/ QUIT
10011 schoenebeck 940
10012 schoenebeck 575 </p>
10013 schoenebeck 708 </blockquote><p>
10014 schoenebeck 575
10015 schoenebeck 708 </p>
10016 schoenebeck 974 <p>add_instruction =
10017     </p>
10018     <blockquote class="text">
10019     <p>CHANNEL
10020    
10021     </p>
10022 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORY SP db_path
10023 iliev 1162
10024     </p>
10025 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename
10026 iliev 1162
10027     </p>
10028 schoenebeck 1801 <p>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP FILE_AS_DIR SP db_path SP filename
10029    
10030     </p>
10031 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename
10032 iliev 1162
10033     </p>
10034 schoenebeck 1801 <p>/ DB_INSTRUMENTS SP scan_mode SP FILE_AS_DIR SP db_path SP filename
10035    
10036     </p>
10037 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
10038 iliev 1201
10039     </p>
10040 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index
10041 iliev 1201
10042     </p>
10043 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP db_path SP filename
10044 iliev 1162
10045     </p>
10046 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP db_path SP filename SP instrument_index
10047 iliev 1162
10048     </p>
10049 schoenebeck 974 <p>/ MIDI_INSTRUMENT_MAP
10050    
10051     </p>
10052     <p>/ MIDI_INSTRUMENT_MAP SP map_name
10053    
10054     </p>
10055     </blockquote><p>
10056    
10057     </p>
10058 schoenebeck 575 <p>subscribe_event =
10059     </p>
10060     <blockquote class="text">
10061 iliev 992 <p>AUDIO_OUTPUT_DEVICE_COUNT
10062 schoenebeck 940
10063 schoenebeck 575 </p>
10064 iliev 992 <p>/ AUDIO_OUTPUT_DEVICE_INFO
10065    
10066     </p>
10067     <p>/ MIDI_INPUT_DEVICE_COUNT
10068    
10069     </p>
10070     <p>/ MIDI_INPUT_DEVICE_INFO
10071    
10072     </p>
10073     <p>/ CHANNEL_COUNT
10074    
10075     </p>
10076 schoenebeck 1685 <p>/ CHANNEL_MIDI
10077    
10078     </p>
10079 schoenebeck 1696 <p>/ DEVICE_MIDI
10080    
10081     </p>
10082 schoenebeck 575 <p>/ VOICE_COUNT
10083 schoenebeck 940
10084 schoenebeck 575 </p>
10085     <p>/ STREAM_COUNT
10086 schoenebeck 940
10087 schoenebeck 575 </p>
10088     <p>/ BUFFER_FILL
10089 schoenebeck 940
10090 schoenebeck 575 </p>
10091     <p>/ CHANNEL_INFO
10092 schoenebeck 940
10093 schoenebeck 575 </p>
10094 iliev 1110 <p>/ FX_SEND_COUNT
10095    
10096     </p>
10097     <p>/ FX_SEND_INFO
10098    
10099     </p>
10100 iliev 992 <p>/ MIDI_INSTRUMENT_MAP_COUNT
10101    
10102     </p>
10103     <p>/ MIDI_INSTRUMENT_MAP_INFO
10104    
10105     </p>
10106     <p>/ MIDI_INSTRUMENT_COUNT
10107    
10108     </p>
10109     <p>/ MIDI_INSTRUMENT_INFO
10110    
10111     </p>
10112 iliev 1162 <p>/ DB_INSTRUMENT_DIRECTORY_COUNT
10113    
10114     </p>
10115     <p>/ DB_INSTRUMENT_DIRECTORY_INFO
10116    
10117     </p>
10118     <p>/ DB_INSTRUMENT_COUNT
10119    
10120     </p>
10121     <p>/ DB_INSTRUMENT_INFO
10122    
10123     </p>
10124 iliev 1201 <p>/ DB_INSTRUMENTS_JOB_INFO
10125    
10126     </p>
10127 schoenebeck 575 <p>/ MISCELLANEOUS
10128 schoenebeck 940
10129 schoenebeck 575 </p>
10130 schoenebeck 1572 <p>/ TOTAL_STREAM_COUNT
10131    
10132     </p>
10133 schoenebeck 940 <p>/ TOTAL_VOICE_COUNT
10134    
10135     </p>
10136 iliev 1110 <p>/ GLOBAL_INFO
10137    
10138     </p>
10139 schoenebeck 708 </blockquote><p>
10140 schoenebeck 575
10141 schoenebeck 708 </p>
10142 schoenebeck 575 <p>unsubscribe_event =
10143     </p>
10144     <blockquote class="text">
10145 iliev 992 <p>AUDIO_OUTPUT_DEVICE_COUNT
10146 schoenebeck 940
10147 schoenebeck 575 </p>
10148 iliev 992 <p>/ AUDIO_OUTPUT_DEVICE_INFO
10149    
10150     </p>
10151     <p>/ MIDI_INPUT_DEVICE_COUNT
10152    
10153     </p>
10154     <p>/ MIDI_INPUT_DEVICE_INFO
10155    
10156     </p>
10157     <p>/ CHANNEL_COUNT
10158    
10159     </p>
10160 schoenebeck 1685 <p>/ CHANNEL_MIDI
10161    
10162     </p>
10163 schoenebeck 1696 <p>/ DEVICE_MIDI
10164    
10165     </p>
10166 schoenebeck 575 <p>/ VOICE_COUNT
10167 schoenebeck 940
10168 schoenebeck 575 </p>
10169     <p>/ STREAM_COUNT
10170 schoenebeck 940
10171 schoenebeck 575 </p>
10172     <p>/ BUFFER_FILL
10173 schoenebeck 940
10174 schoenebeck 575 </p>
10175     <p>/ CHANNEL_INFO
10176 schoenebeck 940
10177 schoenebeck 575 </p>
10178 iliev 1110 <p>/ FX_SEND_COUNT
10179    
10180     </p>
10181     <p>/ FX_SEND_INFO
10182    
10183     </p>
10184 iliev 992 <p>/ MIDI_INSTRUMENT_MAP_COUNT
10185    
10186     </p>
10187     <p>/ MIDI_INSTRUMENT_MAP_INFO
10188    
10189     </p>
10190     <p>/ MIDI_INSTRUMENT_COUNT
10191    
10192     </p>
10193     <p>/ MIDI_INSTRUMENT_INFO
10194    
10195     </p>
10196 iliev 1162 <p>/ DB_INSTRUMENT_DIRECTORY_COUNT
10197    
10198     </p>
10199     <p>/ DB_INSTRUMENT_DIRECTORY_INFO
10200    
10201     </p>
10202     <p>/ DB_INSTRUMENT_COUNT
10203    
10204     </p>
10205     <p>/ DB_INSTRUMENT_INFO
10206    
10207     </p>
10208 iliev 1201 <p>/ DB_INSTRUMENTS_JOB_INFO
10209    
10210     </p>
10211 schoenebeck 575 <p>/ MISCELLANEOUS
10212 schoenebeck 940
10213 schoenebeck 575 </p>
10214 schoenebeck 1572 <p>/ TOTAL_STREAM_COUNT
10215    
10216     </p>
10217 schoenebeck 940 <p>/ TOTAL_VOICE_COUNT
10218    
10219     </p>
10220 iliev 1110 <p>/ GLOBAL_INFO
10221    
10222     </p>
10223 schoenebeck 708 </blockquote><p>
10224 schoenebeck 575
10225 schoenebeck 708 </p>
10226 schoenebeck 945 <p>map_instruction =
10227     </p>
10228     <blockquote class="text">
10229 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
10230 schoenebeck 945
10231     </p>
10232 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
10233 schoenebeck 945
10234     </p>
10235 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
10236 schoenebeck 945
10237     </p>
10238 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
10239 schoenebeck 945
10240     </p>
10241     </blockquote><p>
10242    
10243     </p>
10244     <p>unmap_instruction =
10245     </p>
10246     <blockquote class="text">
10247 schoenebeck 974 <p>MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog
10248 schoenebeck 945
10249     </p>
10250     </blockquote><p>
10251    
10252     </p>
10253     <p>remove_instruction =
10254     </p>
10255     <blockquote class="text">
10256     <p>CHANNEL SP sampler_channel
10257    
10258     </p>
10259 schoenebeck 974 <p>/ MIDI_INSTRUMENT_MAP SP midi_map
10260    
10261     </p>
10262     <p>/ MIDI_INSTRUMENT_MAP SP ALL
10263    
10264     </p>
10265 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path
10266 iliev 1162
10267     </p>
10268 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORY SP db_path
10269 iliev 1162
10270     </p>
10271 schoenebeck 1363 <p>/ DB_INSTRUMENT SP db_path
10272 iliev 1162
10273     </p>
10274 schoenebeck 945 </blockquote><p>
10275    
10276     </p>
10277 schoenebeck 575 <p>get_instruction =
10278     </p>
10279     <blockquote class="text">
10280     <p>AVAILABLE_ENGINES
10281 schoenebeck 940
10282 schoenebeck 575 </p>
10283     <p>/ AVAILABLE_MIDI_INPUT_DRIVERS
10284 schoenebeck 940
10285 schoenebeck 575 </p>
10286     <p>/ MIDI_INPUT_DRIVER SP INFO SP string
10287 schoenebeck 940
10288 schoenebeck 575 </p>
10289     <p>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
10290 schoenebeck 940
10291 schoenebeck 575 </p>
10292     <p>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
10293 schoenebeck 940
10294 schoenebeck 575 </p>
10295     <p>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
10296 schoenebeck 940
10297 schoenebeck 575 </p>
10298     <p>/ AUDIO_OUTPUT_DRIVER SP INFO SP string
10299 schoenebeck 940
10300 schoenebeck 575 </p>
10301     <p>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
10302 schoenebeck 940
10303 schoenebeck 575 </p>
10304     <p>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
10305 schoenebeck 940
10306 schoenebeck 575 </p>
10307     <p>/ AUDIO_OUTPUT_DEVICES
10308 schoenebeck 940
10309 schoenebeck 575 </p>
10310     <p>/ MIDI_INPUT_DEVICES
10311 schoenebeck 940
10312 schoenebeck 575 </p>
10313     <p>/ AUDIO_OUTPUT_DEVICE SP INFO SP number
10314 schoenebeck 940
10315 schoenebeck 575 </p>
10316     <p>/ MIDI_INPUT_DEVICE SP INFO SP number
10317 schoenebeck 940
10318 schoenebeck 575 </p>
10319     <p>/ MIDI_INPUT_PORT SP INFO SP number SP number
10320 schoenebeck 940
10321 schoenebeck 575 </p>
10322     <p>/ MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
10323 schoenebeck 940
10324 schoenebeck 575 </p>
10325     <p>/ AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
10326 schoenebeck 940
10327 schoenebeck 575 </p>
10328     <p>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP string
10329 schoenebeck 940
10330 schoenebeck 575 </p>
10331     <p>/ CHANNELS
10332 schoenebeck 940
10333 schoenebeck 575 </p>
10334     <p>/ CHANNEL SP INFO SP sampler_channel
10335 schoenebeck 940
10336 schoenebeck 575 </p>
10337     <p>/ CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
10338 schoenebeck 940
10339 schoenebeck 575 </p>
10340     <p>/ CHANNEL SP STREAM_COUNT SP sampler_channel
10341 schoenebeck 940
10342 schoenebeck 575 </p>
10343     <p>/ CHANNEL SP VOICE_COUNT SP sampler_channel
10344 schoenebeck 940
10345 schoenebeck 575 </p>
10346     <p>/ ENGINE SP INFO SP engine_name
10347 schoenebeck 940
10348 schoenebeck 575 </p>
10349     <p>/ SERVER SP INFO
10350 schoenebeck 940
10351 schoenebeck 575 </p>
10352 schoenebeck 1572 <p>/ TOTAL_STREAM_COUNT
10353    
10354     </p>
10355 schoenebeck 940 <p>/ TOTAL_VOICE_COUNT
10356    
10357     </p>
10358     <p>/ TOTAL_VOICE_COUNT_MAX
10359    
10360     </p>
10361 schoenebeck 974 <p>/ MIDI_INSTRUMENTS SP midi_map
10362 schoenebeck 945
10363     </p>
10364 schoenebeck 974 <p>/ MIDI_INSTRUMENTS SP ALL
10365 schoenebeck 945
10366     </p>
10367 schoenebeck 974 <p>/ MIDI_INSTRUMENT SP INFO SP midi_map SP midi_bank SP midi_prog
10368    
10369     </p>
10370     <p>/ MIDI_INSTRUMENT_MAPS
10371    
10372     </p>
10373     <p>/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map
10374    
10375     </p>
10376 schoenebeck 1002 <p>/ FX_SENDS SP sampler_channel
10377    
10378     </p>
10379     <p>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
10380    
10381     </p>
10382 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
10383 iliev 1189
10384     </p>
10385 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORIES SP db_path
10386 iliev 1162
10387     </p>
10388 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORY SP INFO SP db_path
10389 iliev 1162
10390     </p>
10391 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
10392 iliev 1189
10393     </p>
10394 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP db_path
10395 iliev 1162
10396     </p>
10397 schoenebeck 1363 <p>/ DB_INSTRUMENT SP INFO SP db_path
10398 iliev 1162
10399     </p>
10400 iliev 1201 <p>/ DB_INSTRUMENTS_JOB SP INFO SP number
10401    
10402     </p>
10403 schoenebeck 1006 <p>/ VOLUME
10404    
10405     </p>
10406 schoenebeck 1801 <p>/ VOICES
10407    
10408     </p>
10409     <p>/ STREAMS
10410    
10411     </p>
10412 schoenebeck 1572 <p>/ FILE SP INSTRUMENTS SP filename
10413    
10414     </p>
10415     <p>/ FILE SP INSTRUMENT SP INFO SP filename SP instrument_index
10416    
10417     </p>
10418 schoenebeck 708 </blockquote><p>
10419 schoenebeck 575
10420 schoenebeck 708 </p>
10421 schoenebeck 575 <p>set_instruction =
10422     </p>
10423     <blockquote class="text">
10424     <p>AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
10425 schoenebeck 940
10426 schoenebeck 575 </p>
10427     <p>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '=' param_val_list
10428 schoenebeck 940
10429 schoenebeck 575 </p>
10430     <p>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
10431 schoenebeck 940
10432 schoenebeck 575 </p>
10433 schoenebeck 1363 <p>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE
10434    
10435     </p>
10436 schoenebeck 575 <p>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list
10437 schoenebeck 940
10438 schoenebeck 575 </p>
10439     <p>/ CHANNEL SP set_chan_instruction
10440 schoenebeck 940
10441 schoenebeck 575 </p>
10442 schoenebeck 974 <p>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
10443    
10444     </p>
10445 iliev 1137 <p>/ FX_SEND SP NAME SP sampler_channel SP fx_send_id SP fx_send_name
10446    
10447     </p>
10448 schoenebeck 1002 <p>/ FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id SP audio_channel_index SP audio_channel_index
10449    
10450     </p>
10451 schoenebeck 1028 <p>/ FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP midi_ctrl
10452    
10453     </p>
10454     <p>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
10455    
10456     </p>
10457 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped
10458 iliev 1162
10459     </p>
10460 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped
10461 iliev 1162
10462     </p>
10463 schoenebeck 1363 <p>/ DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped
10464 iliev 1162
10465     </p>
10466 schoenebeck 1363 <p>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
10467 iliev 1162
10468     </p>
10469 iliev 1731 <p>/ DB_INSTRUMENT SP FILE_PATH SP filename SP filename
10470    
10471     </p>
10472 schoenebeck 575 <p>/ ECHO SP boolean
10473 schoenebeck 940
10474 schoenebeck 575 </p>
10475 schoenebeck 1006 <p>/ VOLUME SP volume_value
10476    
10477     </p>
10478 schoenebeck 1801 <p>/ VOICES SP number
10479    
10480     </p>
10481     <p>/ STREAMS SP number
10482    
10483     </p>
10484 schoenebeck 708 </blockquote><p>
10485 schoenebeck 575
10486 schoenebeck 708 </p>
10487 schoenebeck 575 <p>create_instruction =
10488     </p>
10489     <blockquote class="text">
10490     <p>AUDIO_OUTPUT_DEVICE SP string SP key_val_list
10491 schoenebeck 940
10492 schoenebeck 575 </p>
10493     <p>/ AUDIO_OUTPUT_DEVICE SP string
10494 schoenebeck 940
10495 schoenebeck 575 </p>
10496     <p>/ MIDI_INPUT_DEVICE SP string SP key_val_list
10497 schoenebeck 940
10498 schoenebeck 575 </p>
10499     <p>/ MIDI_INPUT_DEVICE SP string
10500 schoenebeck 940
10501 schoenebeck 575 </p>
10502 schoenebeck 1002 <p>/ FX_SEND SP sampler_channel SP midi_ctrl
10503    
10504     </p>
10505     <p>/ FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name
10506    
10507     </p>
10508 schoenebeck 708 </blockquote><p>
10509 schoenebeck 575
10510 schoenebeck 708 </p>
10511 schoenebeck 945 <p>reset_instruction =
10512     </p>
10513     <blockquote class="text">
10514     <p>CHANNEL SP sampler_channel
10515    
10516     </p>
10517     </blockquote><p>
10518    
10519     </p>
10520     <p>clear_instruction =
10521     </p>
10522     <blockquote class="text">
10523 schoenebeck 974 <p>MIDI_INSTRUMENTS SP midi_map
10524 schoenebeck 945
10525     </p>
10526 schoenebeck 974 <p>/ MIDI_INSTRUMENTS SP ALL
10527    
10528     </p>
10529 schoenebeck 945 </blockquote><p>
10530    
10531     </p>
10532 iliev 1189 <p>find_instruction =
10533     </p>
10534     <blockquote class="text">
10535 schoenebeck 1363 <p>DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list
10536 iliev 1189
10537     </p>
10538 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP db_path SP query_val_list
10539 iliev 1189
10540     </p>
10541 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP query_val_list
10542 iliev 1189
10543     </p>
10544 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
10545 iliev 1189
10546     </p>
10547 iliev 1731 <p>/ LOST SP DB_INSTRUMENT_FILES
10548    
10549     </p>
10550 iliev 1189 </blockquote><p>
10551    
10552     </p>
10553 iliev 1162 <p>move_instruction =
10554     </p>
10555     <blockquote class="text">
10556 schoenebeck 1363 <p>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
10557 iliev 1162
10558     </p>
10559 schoenebeck 1363 <p>/ DB_INSTRUMENT SP db_path SP db_path
10560 iliev 1162
10561     </p>
10562     </blockquote><p>
10563    
10564     </p>
10565 iliev 1189 <p>copy_instruction =
10566     </p>
10567     <blockquote class="text">
10568 schoenebeck 1363 <p>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
10569 iliev 1189
10570     </p>
10571 schoenebeck 1363 <p>/ DB_INSTRUMENT SP db_path SP db_path
10572 iliev 1189
10573     </p>
10574     </blockquote><p>
10575    
10576     </p>
10577 schoenebeck 575 <p>destroy_instruction =
10578     </p>
10579     <blockquote class="text">
10580     <p>AUDIO_OUTPUT_DEVICE SP number
10581 schoenebeck 940
10582 schoenebeck 575 </p>
10583     <p>/ MIDI_INPUT_DEVICE SP number
10584 schoenebeck 940
10585 schoenebeck 575 </p>
10586 schoenebeck 1002 <p>/ FX_SEND SP sampler_channel SP fx_send_id
10587    
10588     </p>
10589 schoenebeck 708 </blockquote><p>
10590 schoenebeck 575
10591 schoenebeck 708 </p>
10592 schoenebeck 575 <p>load_instruction =
10593     </p>
10594     <blockquote class="text">
10595     <p>INSTRUMENT SP load_instr_args
10596 schoenebeck 940
10597 schoenebeck 575 </p>
10598     <p>/ ENGINE SP load_engine_args
10599 schoenebeck 940
10600 schoenebeck 575 </p>
10601 schoenebeck 708 </blockquote><p>
10602 schoenebeck 575
10603 schoenebeck 708 </p>
10604 schoenebeck 575 <p>set_chan_instruction =
10605     </p>
10606     <blockquote class="text">
10607     <p>AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
10608 schoenebeck 940
10609 schoenebeck 575 </p>
10610     <p>/ AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index SP audio_channel_index
10611 schoenebeck 940
10612 schoenebeck 575 </p>
10613     <p>/ AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
10614 schoenebeck 940
10615 schoenebeck 575 </p>
10616     <p>/ MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index SP midi_input_channel_index
10617 schoenebeck 940
10618 schoenebeck 575 </p>
10619     <p>/ MIDI_INPUT_DEVICE SP sampler_channel SP device_index
10620 schoenebeck 940
10621 schoenebeck 575 </p>
10622     <p>/ MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
10623 schoenebeck 940
10624 schoenebeck 575 </p>
10625     <p>/ MIDI_INPUT_CHANNEL SP sampler_channel SP midi_input_channel_index
10626 schoenebeck 940
10627 schoenebeck 575 </p>
10628     <p>/ MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
10629 schoenebeck 940
10630 schoenebeck 575 </p>
10631     <p>/ VOLUME SP sampler_channel SP volume_value
10632 schoenebeck 940
10633 schoenebeck 575 </p>
10634 schoenebeck 708 <p>/ MUTE SP sampler_channel SP boolean
10635 schoenebeck 940
10636 schoenebeck 708 </p>
10637     <p>/ SOLO SP sampler_channel SP boolean
10638 schoenebeck 940
10639 schoenebeck 708 </p>
10640 schoenebeck 974 <p>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP midi_map
10641    
10642     </p>
10643     <p>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP NONE
10644    
10645     </p>
10646     <p>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP DEFAULT
10647    
10648     </p>
10649 schoenebeck 708 </blockquote><p>
10650    
10651     </p>
10652 schoenebeck 1251 <p>edit_instruction =
10653     </p>
10654     <blockquote class="text">
10655 schoenebeck 1430 <p>CHANNEL SP INSTRUMENT SP sampler_channel
10656 schoenebeck 1251
10657     </p>
10658     </blockquote><p>
10659    
10660     </p>
10661 schoenebeck 1363 <p>format_instruction =
10662     </p>
10663     <blockquote class="text">
10664     <p>INSTRUMENTS_DB
10665    
10666     </p>
10667     </blockquote><p>
10668    
10669     </p>
10670 schoenebeck 1048 <p>modal_arg =
10671     </p>
10672     <blockquote class="text">
10673     <p>/* epsilon (empty argument) */
10674    
10675     </p>
10676     <p>/ NON_MODAL SP
10677    
10678     </p>
10679     </blockquote><p>
10680    
10681     </p>
10682 schoenebeck 575 <p>key_val_list =
10683     </p>
10684     <blockquote class="text">
10685     <p>string '=' param_val_list
10686 schoenebeck 940
10687 schoenebeck 575 </p>
10688     <p>/ key_val_list SP string '=' param_val_list
10689 schoenebeck 940
10690 schoenebeck 575 </p>
10691 schoenebeck 708 </blockquote><p>
10692 schoenebeck 575
10693 schoenebeck 708 </p>
10694 schoenebeck 575 <p>buffer_size_type =
10695     </p>
10696     <blockquote class="text">
10697     <p>BYTES
10698 schoenebeck 940
10699 schoenebeck 575 </p>
10700     <p>/ PERCENTAGE
10701 schoenebeck 940
10702 schoenebeck 575 </p>
10703 schoenebeck 708 </blockquote><p>
10704 schoenebeck 575
10705 schoenebeck 708 </p>
10706 schoenebeck 575 <p>list_instruction =
10707     </p>
10708     <blockquote class="text">
10709     <p>AUDIO_OUTPUT_DEVICES
10710 schoenebeck 940
10711 schoenebeck 575 </p>
10712     <p>/ MIDI_INPUT_DEVICES
10713 schoenebeck 940
10714 schoenebeck 575 </p>
10715     <p>/ CHANNELS
10716 schoenebeck 940
10717 schoenebeck 575 </p>
10718     <p>/ AVAILABLE_ENGINES
10719 schoenebeck 940
10720 schoenebeck 575 </p>
10721     <p>/ AVAILABLE_MIDI_INPUT_DRIVERS
10722 schoenebeck 940
10723 schoenebeck 575 </p>
10724     <p>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
10725 schoenebeck 940
10726 schoenebeck 575 </p>
10727 schoenebeck 974 <p>/ MIDI_INSTRUMENTS SP midi_map
10728 schoenebeck 945
10729     </p>
10730 schoenebeck 974 <p>/ MIDI_INSTRUMENTS SP ALL
10731    
10732     </p>
10733     <p>/ MIDI_INSTRUMENT_MAPS
10734    
10735     </p>
10736 schoenebeck 1002 <p>/ FX_SENDS SP sampler_channel
10737    
10738     </p>
10739 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
10740 iliev 1189
10741     </p>
10742 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORIES SP db_path
10743 iliev 1162
10744     </p>
10745 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
10746 iliev 1189
10747     </p>
10748 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP db_path
10749 iliev 1162
10750     </p>
10751 schoenebeck 1572 <p>/ FILE SP INSTRUMENTS SP filename
10752    
10753     </p>
10754 schoenebeck 708 </blockquote><p>
10755 schoenebeck 575
10756 schoenebeck 708 </p>
10757 iliev 1773 <p>send_instruction =
10758     </p>
10759     <blockquote class="text">
10760     <p>CHANNEL SP MIDI_DATA SP string SP sampler_channel SP number SP number
10761    
10762     </p>
10763     </blockquote><p>
10764    
10765     </p>
10766 schoenebeck 575 <p>load_instr_args =
10767     </p>
10768     <blockquote class="text">
10769     <p>filename SP instrument_index SP sampler_channel
10770 schoenebeck 940
10771 schoenebeck 575 </p>
10772     <p>/ NON_MODAL SP filename SP instrument_index SP sampler_channel
10773 schoenebeck 940
10774 schoenebeck 575 </p>
10775 schoenebeck 708 </blockquote><p>
10776 schoenebeck 575
10777 schoenebeck 708 </p>
10778 schoenebeck 575 <p>load_engine_args =
10779     </p>
10780     <blockquote class="text">
10781     <p>engine_name SP sampler_channel
10782 schoenebeck 940
10783 schoenebeck 575 </p>
10784 schoenebeck 708 </blockquote><p>
10785 schoenebeck 575
10786 schoenebeck 708 </p>
10787 schoenebeck 945 <p>instr_load_mode =
10788     </p>
10789     <blockquote class="text">
10790     <p>ON_DEMAND
10791    
10792     </p>
10793     <p>/ ON_DEMAND_HOLD
10794    
10795     </p>
10796     <p>/ PERSISTENT
10797    
10798     </p>
10799     </blockquote><p>
10800    
10801     </p>
10802 schoenebeck 575 <p>device_index =
10803     </p>
10804     <blockquote class="text">
10805     <p>number
10806 schoenebeck 940
10807 schoenebeck 575 </p>
10808 schoenebeck 708 </blockquote><p>
10809 schoenebeck 575
10810 schoenebeck 708 </p>
10811 schoenebeck 575 <p>audio_channel_index =
10812     </p>
10813     <blockquote class="text">
10814     <p>number
10815 schoenebeck 940
10816 schoenebeck 575 </p>
10817 schoenebeck 708 </blockquote><p>
10818 schoenebeck 575
10819 schoenebeck 708 </p>
10820 schoenebeck 575 <p>audio_output_type_name =
10821     </p>
10822     <blockquote class="text">
10823     <p>string
10824 schoenebeck 940
10825 schoenebeck 575 </p>
10826 schoenebeck 708 </blockquote><p>
10827 schoenebeck 575
10828 schoenebeck 708 </p>
10829 schoenebeck 575 <p>midi_input_port_index =
10830     </p>
10831     <blockquote class="text">
10832     <p>number
10833 schoenebeck 940
10834 schoenebeck 575 </p>
10835 schoenebeck 708 </blockquote><p>
10836 schoenebeck 575
10837 schoenebeck 708 </p>
10838 schoenebeck 575 <p>midi_input_channel_index =
10839     </p>
10840     <blockquote class="text">
10841     <p>number
10842 schoenebeck 940
10843 schoenebeck 575 </p>
10844     <p>/ ALL
10845 schoenebeck 940
10846 schoenebeck 575 </p>
10847 schoenebeck 708 </blockquote><p>
10848 schoenebeck 575
10849 schoenebeck 708 </p>
10850 schoenebeck 575 <p>midi_input_type_name =
10851     </p>
10852     <blockquote class="text">
10853     <p>string
10854 schoenebeck 940
10855 schoenebeck 575 </p>
10856 schoenebeck 708 </blockquote><p>
10857 schoenebeck 575
10858 schoenebeck 708 </p>
10859 schoenebeck 974 <p>midi_map =
10860 schoenebeck 945 </p>
10861     <blockquote class="text">
10862     <p>number
10863    
10864     </p>
10865     </blockquote><p>
10866    
10867     </p>
10868 schoenebeck 974 <p>midi_bank =
10869 schoenebeck 945 </p>
10870     <blockquote class="text">
10871     <p>number
10872    
10873     </p>
10874     </blockquote><p>
10875    
10876     </p>
10877     <p>midi_prog =
10878     </p>
10879     <blockquote class="text">
10880     <p>number
10881    
10882     </p>
10883     </blockquote><p>
10884    
10885     </p>
10886 schoenebeck 1002 <p>midi_ctrl =
10887     </p>
10888     <blockquote class="text">
10889     <p>number
10890    
10891     </p>
10892     </blockquote><p>
10893    
10894     </p>
10895 schoenebeck 575 <p>volume_value =
10896     </p>
10897     <blockquote class="text">
10898     <p>dotnum
10899 schoenebeck 940
10900 schoenebeck 575 </p>
10901     <p>/ number
10902 schoenebeck 940
10903 schoenebeck 575 </p>
10904 schoenebeck 708 </blockquote><p>
10905 schoenebeck 575
10906 schoenebeck 708 </p>
10907 schoenebeck 575 <p>sampler_channel =
10908     </p>
10909     <blockquote class="text">
10910     <p>number
10911 schoenebeck 940
10912 schoenebeck 575 </p>
10913 schoenebeck 708 </blockquote><p>
10914 schoenebeck 575
10915 schoenebeck 708 </p>
10916 schoenebeck 575 <p>instrument_index =
10917     </p>
10918     <blockquote class="text">
10919     <p>number
10920 schoenebeck 940
10921 schoenebeck 575 </p>
10922 schoenebeck 708 </blockquote><p>
10923 schoenebeck 575
10924 schoenebeck 708 </p>
10925 schoenebeck 1002 <p>fx_send_id =
10926     </p>
10927     <blockquote class="text">
10928     <p>number
10929    
10930     </p>
10931     </blockquote><p>
10932    
10933     </p>
10934 schoenebeck 575 <p>engine_name =
10935     </p>
10936     <blockquote class="text">
10937     <p>string
10938 schoenebeck 940
10939 schoenebeck 575 </p>
10940 schoenebeck 708 </blockquote><p>
10941 schoenebeck 575
10942 schoenebeck 708 </p>
10943 schoenebeck 1363 <p>filename =
10944 iliev 1162 </p>
10945     <blockquote class="text">
10946 schoenebeck 1363 <p>path
10947 iliev 1162
10948     </p>
10949     </blockquote><p>
10950    
10951     </p>
10952 schoenebeck 1363 <p>db_path =
10953 iliev 1162 </p>
10954     <blockquote class="text">
10955 schoenebeck 1363 <p>path
10956 iliev 1162
10957     </p>
10958     </blockquote><p>
10959    
10960     </p>
10961 schoenebeck 974 <p>map_name =
10962     </p>
10963     <blockquote class="text">
10964 schoenebeck 1390 <p>stringval_escaped
10965 schoenebeck 974
10966     </p>
10967     </blockquote><p>
10968    
10969     </p>
10970 schoenebeck 945 <p>entry_name =
10971     </p>
10972     <blockquote class="text">
10973 schoenebeck 1390 <p>stringval_escaped
10974 schoenebeck 945
10975     </p>
10976     </blockquote><p>
10977    
10978     </p>
10979 schoenebeck 1002 <p>fx_send_name =
10980     </p>
10981     <blockquote class="text">
10982 schoenebeck 1390 <p>stringval_escaped
10983 schoenebeck 1002
10984     </p>
10985     </blockquote><p>
10986    
10987     </p>
10988 schoenebeck 575 <p>param_val_list =
10989     </p>
10990     <blockquote class="text">
10991     <p>param_val
10992 schoenebeck 940
10993 schoenebeck 575 </p>
10994     <p>/ param_val_list','param_val
10995 schoenebeck 940
10996 schoenebeck 575 </p>
10997 schoenebeck 708 </blockquote><p>
10998 schoenebeck 575
10999 schoenebeck 708 </p>
11000 schoenebeck 575 <p>param_val =
11001     </p>
11002     <blockquote class="text">
11003     <p>string
11004 schoenebeck 940
11005 schoenebeck 575 </p>
11006 schoenebeck 940 <p>/ stringval
11007    
11008 schoenebeck 575 </p>
11009     <p>/ number
11010 schoenebeck 940
11011 schoenebeck 575 </p>
11012     <p>/ dotnum
11013 schoenebeck 940
11014 schoenebeck 575 </p>
11015 schoenebeck 708 </blockquote><p>
11016 schoenebeck 575
11017 schoenebeck 708 </p>
11018 iliev 1189 <p>query_val_list =
11019     </p>
11020     <blockquote class="text">
11021     <p>string '=' query_val
11022    
11023     </p>
11024     <p>/ query_val_list SP string '=' query_val
11025    
11026     </p>
11027     </blockquote><p>
11028    
11029     </p>
11030     <p>query_val =
11031     </p>
11032     <blockquote class="text">
11033 schoenebeck 1390 <p>text_escaped
11034 iliev 1189
11035     </p>
11036 schoenebeck 1363 <p>/ stringval_escaped
11037 iliev 1189
11038     </p>
11039     </blockquote><p>
11040    
11041     </p>
11042 iliev 1201 <p>scan_mode =
11043     </p>
11044     <blockquote class="text">
11045     <p>RECURSIVE
11046    
11047     </p>
11048     <p>/ NON_RECURSIVE
11049    
11050     </p>
11051     <p>/ FLAT
11052    
11053     </p>
11054     </blockquote><p>
11055    
11056     </p>
11057 schoenebeck 1251 <a name="character_set"></a><br /><hr />
11058     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11059     <a name="rfc.section.7.1"></a><h3>7.1.&nbsp;
11060     Character Set and Escape Sequences</h3>
11061    
11062     <p>Older versions of this protocol up to and including v1.1 only
11063     supported the standard ASCII character set (ASCII code 0 - 127)
11064     <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
11065     however support the Extended ASCII character set (ASCII code
11066     0 - 255). The same group of younger protocols also support
11067     escape sequences, but only for certain, explicitly declared
11068     parts of the protocol. The supported escape sequences are
11069     defined as follows:
11070     </p><table class="full" align="center" border="0" cellpadding="2" cellspacing="2">
11071     <col align="left"><col align="left">
11072     <tr><th align="left">ASCII Character Sequence</th><th align="left">Translated into (Name)</th></tr>
11073     <tr>
11074     <td align="left">\n</td>
11075     <td align="left">new line</td>
11076     </tr>
11077     <tr>
11078     <td align="left">\r</td>
11079     <td align="left">carriage return</td>
11080     </tr>
11081     <tr>
11082     <td align="left">\f</td>
11083     <td align="left">form feed</td>
11084     </tr>
11085     <tr>
11086     <td align="left">\t</td>
11087     <td align="left">horizontal tab</td>
11088     </tr>
11089     <tr>
11090     <td align="left">\v</td>
11091     <td align="left">vertical tab</td>
11092     </tr>
11093     <tr>
11094     <td align="left">\'</td>
11095     <td align="left">apostrophe</td>
11096     </tr>
11097     <tr>
11098     <td align="left">\"</td>
11099     <td align="left">quotation mark</td>
11100     </tr>
11101     <tr>
11102     <td align="left">\\</td>
11103     <td align="left">backslash</td>
11104     </tr>
11105     <tr>
11106     <td align="left">\OOO</td>
11107     <td align="left">three digit octal ASCII code of the character</td>
11108     </tr>
11109     <tr>
11110     <td align="left">\xHH</td>
11111     <td align="left">two digit hex ASCII code of the character</td>
11112     </tr>
11113     </table>
11114 schoenebeck 1801 <br clear="all" />
11115 schoenebeck 1251
11116     <p>Notice: due to the transition of certain parts of the
11117     protocol which now support escape sequences, a slight backward
11118     incompatibility to protocols version v1.1 and younger has been
11119     introduced. The only difference is that in parts of the protocol
11120     where escape characters are now supported, a backslash characters
11121     MUST be escaped as well (that is as double backslash), whereas
11122     in the old versions a single backslash was sufficient.
11123     </p>
11124 schoenebeck 1390 <p>The following LSCP commands support escape sequences as part
11125 schoenebeck 1400 of their filename / path based arguments and / or may contain
11126     a filename / path with escape sequences in their response:
11127 schoenebeck 1390 </p>
11128     <blockquote class="text">
11129     <p><a class='info' href='#LOAD INSTRUMENT'>"LOAD INSTRUMENT"<span> (</span><span class='info'>Loading an instrument</span><span>)</span></a>
11130     </p>
11131 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>
11132     </p>
11133 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>
11134     </p>
11135 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>
11136     </p>
11137 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>
11138     </p>
11139     <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>
11140     </p>
11141     <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>
11142     </p>
11143     <p><a class='info' href='#REMOVE DB_INSTRUMENT'>"REMOVE DB_INSTRUMENT"<span> (</span><span class='info'>Removing an instrument</span><span>)</span></a>
11144     </p>
11145     <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>
11146     </p>
11147     <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>
11148     </p>
11149     <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>
11150     </p>
11151     <p><a class='info' href='#GET DB_INSTRUMENTS'>"GET DB_INSTRUMENTS"<span> (</span><span class='info'>Getting amount of instruments</span><span>)</span></a>
11152     </p>
11153     <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>
11154     </p>
11155     <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>
11156     </p>
11157     <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>
11158     </p>
11159     <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>
11160     </p>
11161     <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>
11162     </p>
11163     <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>
11164     </p>
11165     <p><a class='info' href='#FIND DB_INSTRUMENTS'>"FIND DB_INSTRUMENTS"<span> (</span><span class='info'>Finding instruments</span><span>)</span></a>
11166     </p>
11167     <p><a class='info' href='#FIND DB_INSTRUMENT_DIRECTORIES'>"FIND DB_INSTRUMENT_DIRECTORIES"<span> (</span><span class='info'>Finding directories</span><span>)</span></a>
11168     </p>
11169     <p><a class='info' href='#MOVE DB_INSTRUMENT'>"MOVE DB_INSTRUMENT"<span> (</span><span class='info'>Moving an instrument</span><span>)</span></a>
11170     </p>
11171     <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>
11172     </p>
11173     <p><a class='info' href='#COPY DB_INSTRUMENT'>"COPY DB_INSTRUMENT"<span> (</span><span class='info'>Copying instruments</span><span>)</span></a>
11174     </p>
11175     <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>
11176     </p>
11177 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>
11178     </p>
11179     <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>
11180     </p>
11181 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>
11182     </p>
11183     <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>
11184     </p>
11185     <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>
11186     </p>
11187 schoenebeck 1390 </blockquote><p>
11188     Note that the forward slash character ('/') has a special meaning in
11189     filename / path based arguments: it acts as separator of the nodes in
11190     the path, thus if a directory- or filename includes a forward slash
11191     (not intended as path node separator), you MUST escape that slash
11192     either with the respective hex escape sequence ("\x2f") or with the
11193     respective octal escape sequence ("\057").
11194    
11195     </p>
11196     <p>
11197 schoenebeck 1572 Note for Windows: file path arguments in LSCP are expected
11198     to use forward slashes as directory node separator similar
11199     to Unix based operating systems. In contrast to Unix however
11200     a Windows typical drive character is expected to be
11201     prefixed to the path. That is an original Windows file path
11202     like "D:\Sounds\My.gig" would become in LSCP:
11203     "D:/Sounds/My.gig".
11204    
11205     </p>
11206     <p>
11207 schoenebeck 1390 The following LSCP commands even support escape sequences as
11208     part of at least one of their text-based arguments (i.e. entity name,
11209 schoenebeck 1400 description) and / or may contain escape sequences in at least one of
11210     their text-based fields in their response:
11211 schoenebeck 1390 </p>
11212     <blockquote class="text">
11213 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>
11214     </p>
11215     <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>
11216     </p>
11217     <p><a class='info' href='#GET CHANNEL INFO'>"GET CHANNEL INFO"<span> (</span><span class='info'>Getting sampler channel information</span><span>)</span></a>
11218     </p>
11219     <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>
11220     </p>
11221     <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>
11222     </p>
11223     <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>
11224     </p>
11225     <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>
11226     </p>
11227     <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>
11228     </p>
11229 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>
11230     </p>
11231     <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>
11232     </p>
11233     <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>
11234     </p>
11235 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>
11236     </p>
11237 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>
11238     </p>
11239     <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>
11240     </p>
11241 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>
11242     </p>
11243 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>
11244     </p>
11245 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>
11246     </p>
11247     <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>
11248     </p>
11249 schoenebeck 1400 <p><a class='info' href='#FIND DB_INSTRUMENTS'>"FIND DB_INSTRUMENTS"<span> (</span><span class='info'>Finding instruments</span><span>)</span></a>
11250 schoenebeck 1390 </p>
11251     </blockquote><p>
11252     Please note that these lists are manually maintained. If you
11253     find a command that also supports escape sequences we forgot to
11254     mention here, please report it!
11255    
11256     </p>
11257 senoner 542 <a name="events"></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"></a><h3>8.&nbsp;
11260     Events</h3>
11261 senoner 542
11262     <p>This chapter will describe all currently defined events supported by LinuxSampler.
11263     </p>
11264 iliev 992 <a name="SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT"></a><br /><hr />
11265 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>
11266     <a name="rfc.section.8.1"></a><h3>8.1.&nbsp;
11267 iliev 992 Number of audio output devices changed</h3>
11268    
11269     <p>Client may want to be notified when the total number of audio output devices on the
11270     back-end changes by issuing the following command:
11271     </p>
11272     <p>
11273     </p>
11274     <blockquote class="text">
11275     <p>SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT
11276     </p>
11277     </blockquote><p>
11278    
11279     </p>
11280     <p>Server will start sending the following notification messages:
11281     </p>
11282     <p>
11283     </p>
11284     <blockquote class="text">
11285     <p>"NOTIFY:AUDIO_OUTPUT_DEVICE_COUNT:&lt;devices&gt;"
11286     </p>
11287     </blockquote><p>
11288    
11289     </p>
11290     <p>where &lt;devices&gt; will be replaced by the new number
11291     of audio output devices.
11292     </p>
11293     <a name="SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO"></a><br /><hr />
11294     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11295     <a name="rfc.section.8.2"></a><h3>8.2.&nbsp;
11296     Audio output device's settings changed</h3>
11297    
11298     <p>Client may want to be notified when changes were made to audio output devices on the
11299     back-end by issuing the following command:
11300     </p>
11301     <p>
11302     </p>
11303     <blockquote class="text">
11304     <p>SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO
11305     </p>
11306     </blockquote><p>
11307    
11308     </p>
11309     <p>Server will start sending the following notification messages:
11310     </p>
11311     <p>
11312     </p>
11313     <blockquote class="text">
11314     <p>"NOTIFY:AUDIO_OUTPUT_DEVICE_INFO:&lt;device-id&gt;"
11315     </p>
11316     </blockquote><p>
11317    
11318     </p>
11319     <p>where &lt;device-id&gt; will be replaced by the numerical ID of the audio output device,
11320     which settings has been changed. The front-end will have to send
11321     the respective command to actually get the audio output device info. Because these messages
11322     will be triggered by LSCP commands issued by other clients rather than real
11323     time events happening on the server, it is believed that an empty notification
11324     message is sufficient here.
11325     </p>
11326     <a name="SUBSCRIBE MIDI_INPUT_DEVICE_COUNT"></a><br /><hr />
11327     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11328     <a name="rfc.section.8.3"></a><h3>8.3.&nbsp;
11329     Number of MIDI input devices changed</h3>
11330    
11331     <p>Client may want to be notified when the total number of MIDI input devices on the
11332     back-end changes by issuing the following command:
11333     </p>
11334     <p>
11335     </p>
11336     <blockquote class="text">
11337     <p>SUBSCRIBE MIDI_INPUT_DEVICE_COUNT
11338     </p>
11339     </blockquote><p>
11340    
11341     </p>
11342     <p>Server will start sending the following notification messages:
11343     </p>
11344     <p>
11345     </p>
11346     <blockquote class="text">
11347     <p>"NOTIFY:MIDI_INPUT_DEVICE_COUNT:&lt;devices&gt;"
11348     </p>
11349     </blockquote><p>
11350    
11351     </p>
11352     <p>where &lt;devices&gt; will be replaced by the new number
11353     of MIDI input devices.
11354     </p>
11355     <a name="SUBSCRIBE MIDI_INPUT_DEVICE_INFO"></a><br /><hr />
11356     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11357     <a name="rfc.section.8.4"></a><h3>8.4.&nbsp;
11358     MIDI input device's settings changed</h3>
11359    
11360     <p>Client may want to be notified when changes were made to MIDI input devices on the
11361     back-end by issuing the following command:
11362     </p>
11363     <p>
11364     </p>
11365     <blockquote class="text">
11366     <p>SUBSCRIBE MIDI_INPUT_DEVICE_INFO
11367     </p>
11368     </blockquote><p>
11369    
11370     </p>
11371     <p>Server will start sending the following notification messages:
11372     </p>
11373     <p>
11374     </p>
11375     <blockquote class="text">
11376     <p>"NOTIFY:MIDI_INPUT_DEVICE_INFO:&lt;device-id&gt;"
11377     </p>
11378     </blockquote><p>
11379    
11380     </p>
11381     <p>where &lt;device-id&gt; will be replaced by the numerical ID of the MIDI input device,
11382     which settings has been changed. The front-end will have to send
11383     the respective command to actually get the MIDI input device info. Because these messages
11384     will be triggered by LSCP commands issued by other clients rather than real
11385     time events happening on the server, it is believed that an empty notification
11386     message is sufficient here.
11387     </p>
11388     <a name="SUBSCRIBE CHANNEL_COUNT"></a><br /><hr />
11389     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11390     <a name="rfc.section.8.5"></a><h3>8.5.&nbsp;
11391 schoenebeck 974 Number of sampler channels changed</h3>
11392 senoner 542
11393     <p>Client may want to be notified when the total number of channels on the
11394     back-end changes by issuing the following command:
11395     </p>
11396 schoenebeck 708 <p>
11397     </p>
11398 senoner 542 <blockquote class="text">
11399 schoenebeck 558 <p>SUBSCRIBE CHANNEL_COUNT
11400 senoner 542 </p>
11401 schoenebeck 708 </blockquote><p>
11402 schoenebeck 940
11403 schoenebeck 708 </p>
11404 senoner 542 <p>Server will start sending the following notification messages:
11405     </p>
11406 schoenebeck 708 <p>
11407     </p>
11408 senoner 542 <blockquote class="text">
11409 schoenebeck 558 <p>"NOTIFY:CHANNEL_COUNT:&lt;channels&gt;"
11410 senoner 542 </p>
11411 schoenebeck 708 </blockquote><p>
11412 schoenebeck 940
11413 schoenebeck 708 </p>
11414 senoner 542 <p>where &lt;channels&gt; will be replaced by the new number
11415     of sampler channels.
11416     </p>
11417 schoenebeck 1685 <a name="SUBSCRIBE CHANNEL_MIDI"></a><br /><hr />
11418     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11419     <a name="rfc.section.8.6"></a><h3>8.6.&nbsp;
11420     MIDI data on a sampler channel arrived</h3>
11421    
11422     <p>Client may want to be notified when MIDI data arrive on sampler channels on
11423     back-end side, by issuing the following command:
11424     </p>
11425     <p>
11426     </p>
11427     <blockquote class="text">
11428     <p>SUBSCRIBE CHANNEL_MIDI
11429     </p>
11430     </blockquote><p>
11431    
11432     </p>
11433     <p>Server will start sending one of the the following notification messages:
11434     </p>
11435     <p>
11436     </p>
11437     <blockquote class="text">
11438     <p>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_ON &lt;note&gt; &lt;velocity&gt;"
11439     </p>
11440     <p>"NOTIFY:CHANNEL_MIDI:&lt;channel-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"
11441     </p>
11442     </blockquote><p>
11443    
11444     </p>
11445     <p>where &lt;channel-id&gt; will be replaced by the ID of the sampler channel where the MIDI
11446     data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
11447     0 .. 127, reflecting the analog meaning of the MIDI specification.
11448    
11449     </p>
11450     <p>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
11451     delivered by this mechanism! With other words: events could be lost at any time!
11452     This restriction was made to keep the RT-safeness of the backend's MIDI and audio
11453     thread unaffected by this feature.
11454     </p>
11455 schoenebeck 1696 <a name="SUBSCRIBE DEVICE_MIDI"></a><br /><hr />
11456     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11457     <a name="rfc.section.8.7"></a><h3>8.7.&nbsp;
11458     MIDI data on a MIDI input device arrived</h3>
11459    
11460     <p>Client may want to be notified when MIDI data arrive on MIDI input devices by issuing the following command:
11461     </p>
11462     <p>
11463     </p>
11464     <blockquote class="text">
11465     <p>SUBSCRIBE DEVICE_MIDI
11466     </p>
11467     </blockquote><p>
11468    
11469     </p>
11470     <p>Server will start sending one of the the following notification messages:
11471     </p>
11472     <p>
11473     </p>
11474     <blockquote class="text">
11475 iliev 1731 <p>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_ON &lt;note&gt; &lt;velocity&gt;"
11476 schoenebeck 1696 </p>
11477 iliev 1731 <p>"NOTIFY:DEVICE_MIDI:&lt;device-id&gt; &lt;port-id&gt; NOTE_OFF &lt;note&gt; &lt;velocity&gt;"
11478 schoenebeck 1696 </p>
11479     </blockquote><p>
11480    
11481     </p>
11482     <p>where &lt;device-id&gt; &lt;port-id&gt; will be replaced
11483     by the IDs of the respective MIDI input device and the device's MIDI port where the MIDI
11484     data arrived. &lt;note&gt; and &lt;velocity&gt; are integer values in the range between
11485     0 .. 127, reflecting the analog meaning of the MIDI specification.
11486    
11487     </p>
11488     <p>CAUTION: no guarantee whatsoever will be made that MIDI events are actually all
11489     delivered by this mechanism! With other words: events could be lost at any time!
11490     This restriction was made to keep the RT-safeness of the backend's MIDI and audio
11491     thread unaffected by this feature.
11492     </p>
11493 schoenebeck 940 <a name="SUBSCRIBE VOICE_COUNT"></a><br /><hr />
11494 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>
11495 schoenebeck 1696 <a name="rfc.section.8.8"></a><h3>8.8.&nbsp;
11496 schoenebeck 974 Number of active voices changed</h3>
11497 senoner 542
11498     <p>Client may want to be notified when the number of voices on the
11499     back-end changes by issuing the following command:
11500     </p>
11501 schoenebeck 708 <p>
11502     </p>
11503 senoner 542 <blockquote class="text">
11504     <p>SUBSCRIBE VOICE_COUNT
11505     </p>
11506 schoenebeck 708 </blockquote><p>
11507 schoenebeck 940
11508 schoenebeck 708 </p>
11509 senoner 542 <p>Server will start sending the following notification messages:
11510     </p>
11511 schoenebeck 708 <p>
11512     </p>
11513 senoner 542 <blockquote class="text">
11514 iliev 1110 <p>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;"
11515 senoner 542 </p>
11516 schoenebeck 708 </blockquote><p>
11517 schoenebeck 940
11518 schoenebeck 708 </p>
11519 senoner 542 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
11520     voice count change occurred and &lt;voices&gt; by the new number of
11521     active voices on that channel.
11522     </p>
11523 schoenebeck 940 <a name="SUBSCRIBE STREAM_COUNT"></a><br /><hr />
11524 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>
11525 schoenebeck 1696 <a name="rfc.section.8.9"></a><h3>8.9.&nbsp;
11526 schoenebeck 974 Number of active disk streams changed</h3>
11527 senoner 542
11528     <p>Client may want to be notified when the number of streams on the back-end
11529     changes by issuing the following command: SUBSCRIBE STREAM_COUNT
11530     </p>
11531 schoenebeck 708 <p>
11532     </p>
11533 senoner 542 <blockquote class="text">
11534     <p>SUBSCRIBE STREAM_COUNT
11535     </p>
11536 schoenebeck 708 </blockquote><p>
11537 schoenebeck 940
11538 schoenebeck 708 </p>
11539 senoner 542 <p>Server will start sending the following notification messages:
11540     </p>
11541 schoenebeck 708 <p>
11542     </p>
11543 senoner 542 <blockquote class="text">
11544     <p>"NOTIFY:STREAM_COUNT:&lt;sampler-channel&gt; &lt;streams&gt;"
11545     </p>
11546 schoenebeck 708 </blockquote><p>
11547 schoenebeck 940
11548 schoenebeck 708 </p>
11549 senoner 542 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
11550     stream count change occurred and &lt;streams&gt; by the new number of
11551     active disk streams on that channel.
11552     </p>
11553 schoenebeck 940 <a name="SUBSCRIBE BUFFER_FILL"></a><br /><hr />
11554 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>
11555 schoenebeck 1696 <a name="rfc.section.8.10"></a><h3>8.10.&nbsp;
11556 schoenebeck 974 Disk stream buffer fill state changed</h3>
11557 senoner 542
11558     <p>Client may want to be notified when the buffer fill state of a disk stream
11559     on the back-end changes by issuing the following command:
11560     </p>
11561 schoenebeck 708 <p>
11562     </p>
11563 senoner 542 <blockquote class="text">
11564     <p>SUBSCRIBE BUFFER_FILL
11565     </p>
11566 schoenebeck 708 </blockquote><p>
11567 schoenebeck 940
11568 schoenebeck 708 </p>
11569 senoner 542 <p>Server will start sending the following notification messages:
11570     </p>
11571 schoenebeck 708 <p>
11572     </p>
11573 senoner 542 <blockquote class="text">
11574     <p>"NOTIFY:BUFFER_FILL:&lt;sampler-channel&gt; &lt;fill-data&gt;"
11575     </p>
11576 schoenebeck 708 </blockquote><p>
11577 schoenebeck 940
11578 schoenebeck 708 </p>
11579 senoner 542 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
11580     buffer fill state change occurred on and &lt;fill-data&gt; will be replaced by the
11581 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>
11582     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.
11583 senoner 542 </p>
11584 iliev 992 <a name="SUBSCRIBE CHANNEL_INFO"></a><br /><hr />
11585 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>
11586 schoenebeck 1696 <a name="rfc.section.8.11"></a><h3>8.11.&nbsp;
11587 schoenebeck 974 Channel information changed</h3>
11588 senoner 542
11589     <p>Client may want to be notified when changes were made to sampler channels on the
11590 schoenebeck 561 back-end by issuing the following command:
11591 senoner 542 </p>
11592 schoenebeck 708 <p>
11593     </p>
11594 senoner 542 <blockquote class="text">
11595 schoenebeck 558 <p>SUBSCRIBE CHANNEL_INFO
11596 senoner 542 </p>
11597 schoenebeck 708 </blockquote><p>
11598 schoenebeck 940
11599 schoenebeck 708 </p>
11600 senoner 542 <p>Server will start sending the following notification messages:
11601     </p>
11602 schoenebeck 708 <p>
11603     </p>
11604 senoner 542 <blockquote class="text">
11605 schoenebeck 558 <p>"NOTIFY:CHANNEL_INFO:&lt;sampler-channel&gt;"
11606 senoner 542 </p>
11607 schoenebeck 708 </blockquote><p>
11608 schoenebeck 940
11609 schoenebeck 708 </p>
11610 senoner 542 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
11611     channel info change occurred. The front-end will have to send
11612     the respective command to actually get the channel info. Because these messages
11613     will be triggered by LSCP commands issued by other clients rather than real
11614     time events happening on the server, it is believed that an empty notification
11615     message is sufficient here.
11616     </p>
11617 iliev 1110 <a name="SUBSCRIBE FX_SEND_COUNT"></a><br /><hr />
11618     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11619 schoenebeck 1696 <a name="rfc.section.8.12"></a><h3>8.12.&nbsp;
11620 iliev 1110 Number of effect sends changed</h3>
11621    
11622 schoenebeck 1251 <p>Client may want to be notified when the number of effect sends on
11623 iliev 1110 a particular sampler channel is changed by issuing the following command:
11624     </p>
11625     <p>
11626     </p>
11627     <blockquote class="text">
11628     <p>SUBSCRIBE FX_SEND_COUNT
11629     </p>
11630     </blockquote><p>
11631    
11632     </p>
11633     <p>Server will start sending the following notification messages:
11634     </p>
11635     <p>
11636     </p>
11637     <blockquote class="text">
11638     <p>"NOTIFY:FX_SEND_COUNT:&lt;channel-id&gt; &lt;fx-sends&gt;"
11639     </p>
11640     </blockquote><p>
11641    
11642     </p>
11643     <p>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
11644     channel, on which the effect sends number is changed and &lt;fx-sends&gt; will
11645     be replaced by the new number of effect sends on that channel.
11646     </p>
11647     <a name="SUBSCRIBE FX_SEND_INFO"></a><br /><hr />
11648     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11649 schoenebeck 1696 <a name="rfc.section.8.13"></a><h3>8.13.&nbsp;
11650 iliev 1110 Effect send information changed</h3>
11651    
11652     <p>Client may want to be notified when changes were made to effect sends on a
11653     a particular sampler channel by issuing the following command:
11654     </p>
11655     <p>
11656     </p>
11657     <blockquote class="text">
11658     <p>SUBSCRIBE FX_SEND_INFO
11659     </p>
11660     </blockquote><p>
11661    
11662     </p>
11663     <p>Server will start sending the following notification messages:
11664     </p>
11665     <p>
11666     </p>
11667     <blockquote class="text">
11668     <p>"NOTIFY:FX_SEND_INFO:&lt;channel-id&gt; &lt;fx-send-id&gt;"
11669     </p>
11670     </blockquote><p>
11671    
11672     </p>
11673     <p>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
11674     channel, on which an effect send entity is changed and &lt;fx-send-id&gt; will
11675     be replaced by the numerical ID of the changed effect send.
11676     </p>
11677 schoenebeck 940 <a name="SUBSCRIBE TOTAL_VOICE_COUNT"></a><br /><hr />
11678 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>
11679 schoenebeck 1696 <a name="rfc.section.8.14"></a><h3>8.14.&nbsp;
11680 schoenebeck 974 Total number of active voices changed</h3>
11681 senoner 542
11682 schoenebeck 940 <p>Client may want to be notified when the total number of voices on the
11683     back-end changes by issuing the following command:
11684     </p>
11685     <p>
11686     </p>
11687     <blockquote class="text">
11688     <p>SUBSCRIBE TOTAL_VOICE_COUNT
11689     </p>
11690     </blockquote><p>
11691    
11692     </p>
11693     <p>Server will start sending the following notification messages:
11694     </p>
11695     <p>
11696     </p>
11697     <blockquote class="text">
11698 iliev 1110 <p>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;"
11699 schoenebeck 940 </p>
11700     </blockquote><p>
11701    
11702     </p>
11703     <p>where &lt;voices&gt; will be replaced by the new number of
11704     all currently active voices.
11705     </p>
11706 schoenebeck 1572 <a name="SUBSCRIBE TOTAL_STREAM_COUNT"></a><br /><hr />
11707     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11708 schoenebeck 1696 <a name="rfc.section.8.15"></a><h3>8.15.&nbsp;
11709 schoenebeck 1572 Total number of active disk streams changed</h3>
11710    
11711     <p>Client may want to be notified when the total number of disk streams on the
11712     back-end changes by issuing the following command:
11713     </p>
11714     <p>
11715     </p>
11716     <blockquote class="text">
11717     <p>SUBSCRIBE TOTAL_STREAM_COUNT
11718     </p>
11719     </blockquote><p>
11720    
11721     </p>
11722     <p>Server will start sending the following notification messages:
11723     </p>
11724     <p>
11725     </p>
11726     <blockquote class="text">
11727     <p>"NOTIFY:TOTAL_STREAM_COUNT:&lt;streams&gt;"
11728     </p>
11729     </blockquote><p>
11730    
11731     </p>
11732     <p>where &lt;streams&gt; will be replaced by the new number of
11733     all currently active disk streams.
11734     </p>
11735 iliev 992 <a name="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT"></a><br /><hr />
11736     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11737 schoenebeck 1696 <a name="rfc.section.8.16"></a><h3>8.16.&nbsp;
11738 iliev 992 Number of MIDI instrument maps changed</h3>
11739    
11740     <p>Client may want to be notified when the number of MIDI instrument maps on the
11741     back-end changes by issuing the following command:
11742     </p>
11743     <p>
11744     </p>
11745     <blockquote class="text">
11746     <p>SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT
11747     </p>
11748     </blockquote><p>
11749    
11750     </p>
11751     <p>Server will start sending the following notification messages:
11752     </p>
11753     <p>
11754     </p>
11755     <blockquote class="text">
11756     <p>"NOTIFY:MIDI_INSTRUMENT_MAP_COUNT:&lt;maps&gt;"
11757     </p>
11758     </blockquote><p>
11759    
11760     </p>
11761     <p>where &lt;maps&gt; will be replaced by the new number
11762     of MIDI instrument maps.
11763     </p>
11764     <a name="SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO"></a><br /><hr />
11765     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11766 schoenebeck 1696 <a name="rfc.section.8.17"></a><h3>8.17.&nbsp;
11767 iliev 992 MIDI instrument map information changed</h3>
11768    
11769     <p>Client may want to be notified when changes were made to MIDI instrument maps on the
11770     back-end by issuing the following command:
11771     </p>
11772     <p>
11773     </p>
11774     <blockquote class="text">
11775     <p>SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO
11776     </p>
11777     </blockquote><p>
11778    
11779     </p>
11780     <p>Server will start sending the following notification messages:
11781     </p>
11782     <p>
11783     </p>
11784     <blockquote class="text">
11785     <p>"NOTIFY:MIDI_INSTRUMENT_MAP_INFO:&lt;map-id&gt;"
11786     </p>
11787     </blockquote><p>
11788    
11789     </p>
11790     <p>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
11791     for which information changes occurred. The front-end will have to send
11792     the respective command to actually get the MIDI instrument map info. Because these messages
11793     will be triggered by LSCP commands issued by other clients rather than real
11794     time events happening on the server, it is believed that an empty notification
11795     message is sufficient here.
11796     </p>
11797     <a name="SUBSCRIBE MIDI_INSTRUMENT_COUNT"></a><br /><hr />
11798     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11799 schoenebeck 1696 <a name="rfc.section.8.18"></a><h3>8.18.&nbsp;
11800 iliev 992 Number of MIDI instruments changed</h3>
11801    
11802     <p>Client may want to be notified when the number of MIDI instrument maps on the
11803     back-end changes by issuing the following command:
11804     </p>
11805     <p>
11806     </p>
11807     <blockquote class="text">
11808     <p>SUBSCRIBE MIDI_INSTRUMENT_COUNT
11809     </p>
11810     </blockquote><p>
11811    
11812     </p>
11813     <p>Server will start sending the following notification messages:
11814     </p>
11815     <p>
11816     </p>
11817     <blockquote class="text">
11818     <p>"NOTIFY:MIDI_INSTRUMENT_COUNT:&lt;map-id&gt; &lt;instruments&gt;"
11819     </p>
11820     </blockquote><p>
11821    
11822     </p>
11823     <p>where &lt;map-id&gt; is the numerical ID of the MIDI instrument map, in which
11824     the nuber of instruments has changed and &lt;instruments&gt; will be replaced by
11825     the new number of MIDI instruments in the specified map.
11826     </p>
11827     <a name="SUBSCRIBE MIDI_INSTRUMENT_INFO"></a><br /><hr />
11828     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11829 schoenebeck 1696 <a name="rfc.section.8.19"></a><h3>8.19.&nbsp;
11830 iliev 992 MIDI instrument information changed</h3>
11831    
11832     <p>Client may want to be notified when changes were made to MIDI instruments on the
11833     back-end by issuing the following command:
11834     </p>
11835     <p>
11836     </p>
11837     <blockquote class="text">
11838     <p>SUBSCRIBE MIDI_INSTRUMENT_INFO
11839     </p>
11840     </blockquote><p>
11841    
11842     </p>
11843     <p>Server will start sending the following notification messages:
11844     </p>
11845     <p>
11846     </p>
11847     <blockquote class="text">
11848     <p>"NOTIFY:MIDI_INSTRUMENT_INFO:&lt;map-id&gt; &lt;bank&gt; &lt;program&gt;"
11849     </p>
11850     </blockquote><p>
11851    
11852     </p>
11853     <p>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
11854     in which a MIDI instrument is changed. &lt;bank&gt; and &lt;program&gt; specifies
11855     the location of the changed MIDI instrument in the map. The front-end will have to send
11856     the respective command to actually get the MIDI instrument info. Because these messages
11857     will be triggered by LSCP commands issued by other clients rather than real
11858     time events happening on the server, it is believed that an empty notification
11859     message is sufficient here.
11860     </p>
11861 iliev 1110 <a name="SUBSCRIBE GLOBAL_INFO"></a><br /><hr />
11862     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11863 schoenebeck 1696 <a name="rfc.section.8.20"></a><h3>8.20.&nbsp;
11864 iliev 1110 Global settings changed</h3>
11865    
11866     <p>Client may want to be notified when changes to the global settings
11867     of the sampler were made by issuing the following command:
11868     </p>
11869     <p>
11870     </p>
11871     <blockquote class="text">
11872     <p>SUBSCRIBE GLOBAL_INFO
11873     </p>
11874     </blockquote><p>
11875    
11876     </p>
11877     <p>Server will start sending the following types of notification messages:
11878     </p>
11879     <p>
11880     </p>
11881     <blockquote class="text">
11882     <p>"NOTIFY:GLOBAL_INFO:VOLUME &lt;volume&gt;" - Notifies that the
11883     golbal volume of the sampler is changed, where &lt;volume&gt; will be
11884     replaced by the optional dotted floating point value, reflecting the
11885     new global volume parameter.
11886     </p>
11887     </blockquote><p>
11888 schoenebeck 1801 </p>
11889     <blockquote class="text">
11890     <p>"NOTIFY:GLOBAL_INFO:VOICES &lt;max-voices&gt;" - Notifies that the
11891     golbal limit of the sampler for maximum voices is changed, where
11892     &lt;max-voices&gt; will be an integer value, reflecting the
11893     new global voice limit parameter.
11894     </p>
11895     </blockquote><p>
11896     </p>
11897     <blockquote class="text">
11898     <p>"NOTIFY:GLOBAL_INFO:STREAMS &lt;max-streams&gt;" - Notifies that the
11899     golbal limit of the sampler for maximum disk streams is changed, where
11900     &lt;max-streams&gt; will be an integer value, reflecting the
11901     new global disk streams limit parameter.
11902     </p>
11903     </blockquote><p>
11904 iliev 1110
11905     </p>
11906 iliev 1162 <a name="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT"></a><br /><hr />
11907     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11908 schoenebeck 1696 <a name="rfc.section.8.21"></a><h3>8.21.&nbsp;
11909 iliev 1162 Number of database instrument directories changed</h3>
11910    
11911     <p>Client may want to be notified when the number of instrument
11912     directories in a particular directory in the instruments database
11913     is changed by issuing the following command:
11914     </p>
11915     <p>
11916     </p>
11917     <blockquote class="text">
11918     <p>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT
11919     </p>
11920     </blockquote><p>
11921    
11922     </p>
11923     <p>Server will start sending the following notification messages:
11924     </p>
11925     <p>
11926     </p>
11927     <blockquote class="text">
11928     <p>"NOTIFY:DB_INSTRUMENT_DIRECTORY_COUNT:&lt;dir-path&gt;"
11929     </p>
11930     </blockquote><p>
11931    
11932     </p>
11933     <p>where &lt;dir-path&gt; will be replaced by the absolute path
11934     name of the directory in the instruments database,
11935     in which the number of directories is changed.
11936     </p>
11937     <p>Note that when a non-empty directory is removed, this event
11938     is not sent for the subdirectories in that directory.
11939     </p>
11940     <a name="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO"></a><br /><hr />
11941     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11942 schoenebeck 1696 <a name="rfc.section.8.22"></a><h3>8.22.&nbsp;
11943 iliev 1162 Database instrument directory information changed</h3>
11944    
11945     <p>Client may want to be notified when changes were made to directories
11946     in the instruments database by issuing the following command:
11947     </p>
11948     <p>
11949     </p>
11950     <blockquote class="text">
11951     <p>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO
11952     </p>
11953     </blockquote><p>
11954    
11955     </p>
11956     <p>Server will start sending the following notification messages:
11957     </p>
11958     <p>
11959     </p>
11960     <blockquote class="text">
11961     <p>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:&lt;dir-path&gt;"
11962     </p>
11963     </blockquote><p>
11964    
11965     </p>
11966     <p>where &lt;dir-path&gt; will be replaced by the absolute path name
11967     of the directory, for which information changes occurred. The front-end will have to send
11968     the respective command to actually get the updated directory info. Because these messages
11969     will be triggered by LSCP commands issued by other clients rather than real
11970     time events happening on the server, it is believed that an empty notification
11971     message is sufficient here.
11972     </p>
11973     <p>
11974     </p>
11975     <blockquote class="text">
11976     <p>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:NAME &lt;old-dir-path&gt; &lt;new-name&gt;"
11977     </p>
11978     </blockquote><p>
11979    
11980     </p>
11981     <p>where &lt;old-dir-path&gt; is the old absolute path name of the directory
11982     (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
11983     the new name of the directory, encapsulated into apostrophes.
11984     </p>
11985     <a name="SUBSCRIBE DB_INSTRUMENT_COUNT"></a><br /><hr />
11986     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11987 schoenebeck 1696 <a name="rfc.section.8.23"></a><h3>8.23.&nbsp;
11988 iliev 1162 Number of database instruments changed</h3>
11989    
11990     <p>Client may want to be notified when the number of instruments
11991     in a particular directory in the instruments database
11992     is changed by issuing the following command:
11993     </p>
11994     <p>
11995     </p>
11996     <blockquote class="text">
11997     <p>SUBSCRIBE DB_INSTRUMENT_COUNT
11998     </p>
11999     </blockquote><p>
12000    
12001     </p>
12002     <p>Server will start sending the following notification messages:
12003     </p>
12004     <p>
12005     </p>
12006     <blockquote class="text">
12007     <p>"NOTIFY:DB_INSTRUMENT_COUNT:&lt;dir-path&gt;"
12008     </p>
12009     </blockquote><p>
12010    
12011     </p>
12012     <p>where &lt;dir-path&gt; will be replaced by the absolute path
12013     name of the directory in the instruments database,
12014     in which the number of instruments is changed.
12015     </p>
12016     <p>Note that when a non-empty directory is removed, this event
12017     is not sent for the instruments in that directory.
12018     </p>
12019     <a name="SUBSCRIBE DB_INSTRUMENT_INFO"></a><br /><hr />
12020     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
12021 schoenebeck 1696 <a name="rfc.section.8.24"></a><h3>8.24.&nbsp;
12022 iliev 1162 Database instrument information changed</h3>
12023    
12024     <p>Client may want to be notified when changes were made to instruments
12025     in the instruments database by issuing the following command:
12026     </p>
12027     <p>
12028     </p>
12029     <blockquote class="text">
12030     <p>SUBSCRIBE DB_INSTRUMENT_INFO
12031     </p>
12032     </blockquote><p>
12033    
12034     </p>
12035     <p>Server will start sending the following notification messages:
12036     </p>
12037     <p>
12038     </p>
12039     <blockquote class="text">
12040     <p>"NOTIFY:DB_INSTRUMENT_INFO:&lt;instr-path&gt;"
12041     </p>
12042     </blockquote><p>
12043    
12044     </p>
12045     <p>where &lt;instr-path&gt; will be replaced by the absolute path name
12046     of the instrument, which settings are changed. The front-end will have to send
12047     the respective command to actually get the updated directory info. Because these messages
12048     will be triggered by LSCP commands issued by other clients rather than real
12049     time events happening on the server, it is believed that an empty notification
12050     message is sufficient here.
12051     </p>
12052     <p>
12053     </p>
12054     <blockquote class="text">
12055     <p>"NOTIFY:DB_INSTRUMENT_INFO:NAME &lt;old-instr-path&gt; &lt;new-name&gt;"
12056     </p>
12057     </blockquote><p>
12058    
12059     </p>
12060     <p>where &lt;old-instr-path&gt; is the old absolute path name of the instrument
12061     (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
12062     the new name of the instrument, encapsulated into apostrophes.
12063     </p>
12064 iliev 1201 <a name="SUBSCRIBE DB_INSTRUMENTS_JOB_INFO"></a><br /><hr />
12065     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
12066 schoenebeck 1696 <a name="rfc.section.8.25"></a><h3>8.25.&nbsp;
12067 iliev 1201 Database job status information changed</h3>
12068    
12069     <p>Client may want to be notified when the status of particular database
12070     instruments job is changed by issuing the following command:
12071     </p>
12072     <p>
12073     </p>
12074     <blockquote class="text">
12075     <p>SUBSCRIBE DB_INSTRUMENTS_JOB_INFO
12076     </p>
12077     </blockquote><p>
12078    
12079     </p>
12080     <p>Server will start sending the following notification messages:
12081     </p>
12082     <p>
12083     </p>
12084     <blockquote class="text">
12085     <p>"NOTIFY:DB_INSTRUMENTS_JOB_INFO:&lt;job-id&gt;"
12086     </p>
12087     </blockquote><p>
12088    
12089     </p>
12090     <p>where &lt;job-id&gt; will be replaced by the numerical ID of the job,
12091     which status is changed. The front-end will have to send the respective
12092     command to actually get the status info. Because these messages
12093     will be triggered by LSCP commands issued by other clients rather than real
12094     time events happening on the server, it is believed that an empty notification
12095     message is sufficient here.
12096     </p>
12097 schoenebeck 940 <a name="SUBSCRIBE MISCELLANEOUS"></a><br /><hr />
12098 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>
12099 schoenebeck 1696 <a name="rfc.section.8.26"></a><h3>8.26.&nbsp;
12100 schoenebeck 974 Miscellaneous and debugging events</h3>
12101 schoenebeck 940
12102 senoner 542 <p>Client may want to be notified of miscellaneous and debugging events occurring at
12103     the server by issuing the following command:
12104     </p>
12105 schoenebeck 708 <p>
12106     </p>
12107 senoner 542 <blockquote class="text">
12108     <p>SUBSCRIBE MISCELLANEOUS
12109     </p>
12110 schoenebeck 708 </blockquote><p>
12111 schoenebeck 940
12112 schoenebeck 708 </p>
12113 senoner 542 <p>Server will start sending the following notification messages:
12114     </p>
12115 schoenebeck 708 <p>
12116     </p>
12117 senoner 542 <blockquote class="text">
12118     <p>"NOTIFY:MISCELLANEOUS:&lt;string&gt;"
12119     </p>
12120 schoenebeck 708 </blockquote><p>
12121 schoenebeck 940
12122 schoenebeck 708 </p>
12123 senoner 542 <p>where &lt;string&gt; will be replaced by whatever data server
12124     wants to send to the client. Client MAY display this data to the
12125     user AS IS to facilitate debugging.
12126     </p>
12127 schoenebeck 974 <a name="anchor14"></a><br /><hr />
12128     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
12129     <a name="rfc.section.9"></a><h3>9.&nbsp;
12130     Security Considerations</h3>
12131 senoner 542
12132     <p>As there is so far no method of authentication and authorization
12133     defined and so not required for a client applications to succeed to
12134     connect, running LinuxSampler might be a security risk for the host
12135     system the LinuxSampler instance is running on.
12136     </p>
12137 schoenebeck 974 <a name="anchor15"></a><br /><hr />
12138     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
12139     <a name="rfc.section.10"></a><h3>10.&nbsp;
12140     Acknowledgments</h3>
12141 senoner 542
12142     <p>This document has benefited greatly from the comments of the
12143     following people, discussed on the LinuxSampler developer's mailing
12144     list:
12145     </p>
12146 schoenebeck 708 <p>
12147     </p>
12148 senoner 542 <blockquote class="text">
12149     <p>Rui Nuno Capela
12150     </p>
12151     <p>Vladimir Senkov
12152     </p>
12153     <p>Mark Knecht
12154     </p>
12155 schoenebeck 561 <p>Grigor Iliev
12156     </p>
12157 schoenebeck 708 </blockquote><p>
12158 schoenebeck 940
12159 schoenebeck 708 </p>
12160 senoner 542 <a name="rfc.references1"></a><br /><hr />
12161 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>
12162 schoenebeck 708 <h3>11.&nbsp;References</h3>
12163 senoner 542 <table width="99%" border="0">
12164 schoenebeck 1251 <tr><td class="author-text" valign="top"><a name="RFC20">[RFC20]</a></td>
12165 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>
12166 senoner 542 <tr><td class="author-text" valign="top"><a name="RFC2119">[RFC2119]</a></td>
12167 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>
12168 schoenebeck 575 <tr><td class="author-text" valign="top"><a name="RFC2234">[RFC2234]</a></td>
12169 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>
12170 schoenebeck 575 <tr><td class="author-text" valign="top"><a name="RFC793">[RFC793]</a></td>
12171 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>
12172 senoner 542 </table>
12173    
12174     <a name="rfc.authors"></a><br /><hr />
12175 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>
12176 senoner 542 <h3>Author's Address</h3>
12177     <table width="99%" border="0" cellpadding="0" cellspacing="0">
12178     <tr><td class="author-text">&nbsp;</td>
12179     <td class="author-text">C.
12180     Schoenebeck</td></tr>
12181     <tr><td class="author-text">&nbsp;</td>
12182     <td class="author-text">Interessengemeinschaft Software Engineering e. V.</td></tr>
12183     <tr><td class="author-text">&nbsp;</td>
12184     <td class="author-text">Max-Planck-Str. 39</td></tr>
12185     <tr><td class="author-text">&nbsp;</td>
12186     <td class="author-text">74081 Heilbronn</td></tr>
12187     <tr><td class="author-text">&nbsp;</td>
12188     <td class="author-text">Germany</td></tr>
12189 schoenebeck 708 <tr><td class="author" align="right">Email:&nbsp;</td>
12190 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>
12191     </table>
12192     <a name="rfc.copyright"></a><br /><hr />
12193 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>
12194     <h3>Full Copyright Statement</h3>
12195 senoner 542 <p class='copyright'>
12196 schoenebeck 1685 Copyright &copy; The IETF Trust (2008).</p>
12197 senoner 542 <p class='copyright'>
12198 schoenebeck 974 This document is subject to the rights,
12199     licenses and restrictions contained in BCP&nbsp;78,
12200     and except as set forth therein,
12201     the authors retain all their rights.</p>
12202 senoner 542 <p class='copyright'>
12203 schoenebeck 974 This document and the information contained herein are provided
12204     on an &ldquo;AS IS&rdquo; basis and THE CONTRIBUTOR,
12205 iliev 1110 THE ORGANIZATION HE/SHE REPRESENTS
12206     OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST
12207     AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES,
12208     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT
12209     THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY
12210     IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
12211     PURPOSE.</p>
12212 schoenebeck 974 <h3>Intellectual Property</h3>
12213 senoner 542 <p class='copyright'>
12214 schoenebeck 974 The IETF takes no position regarding the validity or scope of any
12215     Intellectual Property Rights or other rights that might be claimed
12216     to pertain to the implementation or use of the technology
12217     described in this document or the extent to which any license
12218     under such rights might or might not be available; nor does it
12219     represent that it has made any independent effort to identify any
12220     such rights.
12221     Information on the procedures with respect to
12222     rights in RFC documents can be found in BCP&nbsp;78 and BCP&nbsp;79.</p>
12223 senoner 542 <p class='copyright'>
12224 schoenebeck 974 Copies of IPR disclosures made to the IETF Secretariat and any
12225     assurances of licenses to be made available,
12226     or the result of an attempt made to obtain a general license or
12227     permission for the use of such proprietary rights by implementers or
12228     users of this specification can be obtained from the IETF on-line IPR
12229     repository at <a href='http://www.ietf.org/ipr'>http://www.ietf.org/ipr</a>.</p>
12230 senoner 542 <p class='copyright'>
12231 schoenebeck 974 The IETF invites any interested party to bring to its attention
12232     any copyrights,
12233     patents or patent applications,
12234     or other
12235     proprietary rights that may cover technology that may be required
12236     to implement this standard.
12237     Please address the information to the IETF at <a href='mailto:ietf-ipr@ietf.org'>ietf-ipr@ietf.org</a>.</p>
12238 senoner 542 </body></html>
12239 schoenebeck 1801

  ViewVC Help
Powered by ViewVC