/[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 1363 - (hide annotations) (download) (as text)
Sun Sep 30 21:51:14 2007 UTC (16 years, 6 months ago) by schoenebeck
File MIME type: text/html
File size: 385356 byte(s)
* updated LSCP draft specs ... it's been a while

1 senoner 542 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 schoenebeck 1251 <html lang="en"><head><title>LinuxSampler Control Protocol (draft)</title>
3 senoner 542 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
4 schoenebeck 1251 <meta name="description" content="LinuxSampler Control Protocol (draft)">
5 senoner 542 <meta name="keywords" content="LSCP">
6 iliev 1110 <meta name="generator" content="xml2rfc v1.32 (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 1363 <tr><td class="header">Expires: March 4, 2008</td><td class="header">September 2007</td></tr>
149 senoner 542 </table></td></tr></table>
150 schoenebeck 1251 <h1><br />LinuxSampler Control Protocol (draft)<br />LSCP 1.2cvs</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 1363 This Internet-Draft will expire on March 4, 2008.</p>
177 senoner 542
178     <h3>Copyright Notice</h3>
179     <p>
180 iliev 1110 Copyright &copy; The IETF Trust (2007).</p>
181 senoner 542
182     <h3>Abstract</h3>
183    
184     <p>The LinuxSampler Control Protocol (LSCP) is an
185     application-level protocol primarily intended for local and
186 schoenebeck 575 remote controlling the LinuxSampler backend application, which is a
187     sophisticated server-like console application essentially playing
188     back audio samples and manipulating the samples in real time to
189     certain extent.
190 senoner 542 </p><a name="toc"></a><br /><hr />
191     <h3>Table of Contents</h3>
192     <p class="toc">
193     <a href="#anchor1">1.</a>&nbsp;
194     Requirements notation<br />
195 schoenebeck 575 <a href="#LSCP versioning">2.</a>&nbsp;
196     Versioning of this specification<br />
197     <a href="#anchor2">3.</a>&nbsp;
198 senoner 542 Introduction<br />
199 schoenebeck 575 <a href="#anchor3">4.</a>&nbsp;
200 senoner 542 Focus of this protocol<br />
201 schoenebeck 575 <a href="#anchor4">5.</a>&nbsp;
202 senoner 542 Communication Overview<br />
203 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor5">5.1.</a>&nbsp;
204 senoner 542 Request/response communication method<br />
205 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor6">5.1.1.</a>&nbsp;
206 senoner 542 Result format<br />
207 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor7">5.2.</a>&nbsp;
208 senoner 542 Subscribe/notify communication method<br />
209 schoenebeck 575 <a href="#control_commands">6.</a>&nbsp;
210 senoner 542 Description for control commands<br />
211 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor8">6.1.</a>&nbsp;
212 senoner 542 Ignored lines and comments<br />
213 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor9">6.2.</a>&nbsp;
214 senoner 542 Configuring audio drivers<br />
215 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_AUDIO_OUTPUT_DRIVERS">6.2.1.</a>&nbsp;
216 senoner 542 Getting amount of available audio output drivers<br />
217 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">6.2.2.</a>&nbsp;
218 senoner 542 Getting all available audio output drivers<br />
219 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DRIVER INFO">6.2.3.</a>&nbsp;
220 senoner 542 Getting information about a specific audio
221     output driver<br />
222 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO">6.2.4.</a>&nbsp;
223 senoner 542 Getting information about specific audio
224     output driver parameter<br />
225 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CREATE AUDIO_OUTPUT_DEVICE">6.2.5.</a>&nbsp;
226 senoner 542 Creating an audio output device<br />
227 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DESTROY AUDIO_OUTPUT_DEVICE">6.2.6.</a>&nbsp;
228 senoner 542 Destroying an audio output device<br />
229 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DEVICES">6.2.7.</a>&nbsp;
230 senoner 542 Getting all created audio output device count<br />
231 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AUDIO_OUTPUT_DEVICES">6.2.8.</a>&nbsp;
232 senoner 542 Getting all created audio output device list<br />
233 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DEVICE INFO">6.2.9.</a>&nbsp;
234 senoner 542 Getting current settings of an audio output device<br />
235 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET AUDIO_OUTPUT_DEVICE_PARAMETER">6.2.10.</a>&nbsp;
236 senoner 542 Changing settings of audio output devices<br />
237 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_CHANNEL INFO">6.2.11.</a>&nbsp;
238 senoner 542 Getting information about an audio channel<br />
239 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO">6.2.12.</a>&nbsp;
240 senoner 542 Getting information about specific audio channel parameter<br />
241 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET AUDIO_OUTPUT_CHANNEL_PARAMETER">6.2.13.</a>&nbsp;
242 senoner 542 Changing settings of audio output channels<br />
243 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor10">6.3.</a>&nbsp;
244 senoner 542 Configuring MIDI input drivers<br />
245 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_MIDI_INPUT_DRIVERS">6.3.1.</a>&nbsp;
246 senoner 542 Getting amount of available MIDI input drivers<br />
247 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_MIDI_INPUT_DRIVERS">6.3.2.</a>&nbsp;
248 senoner 542 Getting all available MIDI input drivers<br />
249 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DRIVER INFO">6.3.3.</a>&nbsp;
250 senoner 542 Getting information about a specific MIDI input driver<br />
251 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DRIVER_PARAMETER INFO">6.3.4.</a>&nbsp;
252 senoner 542 Getting information about specific MIDI input driver parameter<br />
253 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CREATE MIDI_INPUT_DEVICE">6.3.5.</a>&nbsp;
254 senoner 542 Creating a MIDI input device<br />
255 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DESTROY MIDI_INPUT_DEVICE">6.3.6.</a>&nbsp;
256 senoner 542 Destroying a MIDI input device<br />
257 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DEVICES">6.3.7.</a>&nbsp;
258 senoner 542 Getting all created MIDI input device count<br />
259 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST MIDI_INPUT_DEVICES">6.3.8.</a>&nbsp;
260 senoner 542 Getting all created MIDI input device list<br />
261 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DEVICE INFO">6.3.9.</a>&nbsp;
262 senoner 542 Getting current settings of a MIDI input device<br />
263 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET MIDI_INPUT_DEVICE_PARAMETER">6.3.10.</a>&nbsp;
264 senoner 542 Changing settings of MIDI input devices<br />
265 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_PORT INFO">6.3.11.</a>&nbsp;
266 senoner 542 Getting information about a MIDI port<br />
267 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_PORT_PARAMETER INFO">6.3.12.</a>&nbsp;
268 senoner 542 Getting information about specific MIDI port parameter<br />
269 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET MIDI_INPUT_PORT_PARAMETER">6.3.13.</a>&nbsp;
270 senoner 542 Changing settings of MIDI input ports<br />
271 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor11">6.4.</a>&nbsp;
272 senoner 542 Configuring sampler channels<br />
273 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LOAD INSTRUMENT">6.4.1.</a>&nbsp;
274 senoner 542 Loading an instrument<br />
275 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LOAD ENGINE">6.4.2.</a>&nbsp;
276 senoner 542 Loading a sampler engine<br />
277 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNELS">6.4.3.</a>&nbsp;
278 senoner 542 Getting all created sampler channel count<br />
279 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST CHANNELS">6.4.4.</a>&nbsp;
280 senoner 542 Getting all created sampler channel list<br />
281 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD CHANNEL">6.4.5.</a>&nbsp;
282 senoner 542 Adding a new sampler channel<br />
283 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE CHANNEL">6.4.6.</a>&nbsp;
284 senoner 542 Removing a sampler channel<br />
285 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_ENGINES">6.4.7.</a>&nbsp;
286 senoner 542 Getting amount of available engines<br />
287 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_ENGINES">6.4.8.</a>&nbsp;
288 senoner 542 Getting all available engines<br />
289 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET ENGINE INFO">6.4.9.</a>&nbsp;
290 senoner 542 Getting information about an engine<br />
291 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL INFO">6.4.10.</a>&nbsp;
292 senoner 542 Getting sampler channel information<br />
293 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL VOICE_COUNT">6.4.11.</a>&nbsp;
294 senoner 542 Current number of active voices<br />
295 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL STREAM_COUNT">6.4.12.</a>&nbsp;
296 senoner 542 Current number of active disk streams<br />
297 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL BUFFER_FILL">6.4.13.</a>&nbsp;
298 senoner 542 Current fill state of disk stream buffers<br />
299 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_DEVICE">6.4.14.</a>&nbsp;
300 senoner 542 Setting audio output device<br />
301 schoenebeck 974 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_TYPE">6.4.15.</a>&nbsp;
302 senoner 542 Setting audio output type<br />
303 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_CHANNEL">6.4.16.</a>&nbsp;
304 senoner 542 Setting audio output channel<br />
305 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_DEVICE">6.4.17.</a>&nbsp;
306 senoner 542 Setting MIDI input device<br />
307 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_TYPE">6.4.18.</a>&nbsp;
308 senoner 542 Setting MIDI input type<br />
309 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_PORT">6.4.19.</a>&nbsp;
310 senoner 542 Setting MIDI input port<br />
311 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_CHANNEL">6.4.20.</a>&nbsp;
312 senoner 542 Setting MIDI input channel<br />
313 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL VOLUME">6.4.21.</a>&nbsp;
314 senoner 542 Setting channel volume<br />
315 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MUTE">6.4.22.</a>&nbsp;
316 schoenebeck 708 Muting a sampler channel<br />
317 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL SOLO">6.4.23.</a>&nbsp;
318 schoenebeck 708 Soloing a sampler channel<br />
319 schoenebeck 974 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INSTRUMENT_MAP">6.4.24.</a>&nbsp;
320     Assigning a MIDI instrument map to a sampler channel<br />
321 schoenebeck 1002 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CREATE FX_SEND">6.4.25.</a>&nbsp;
322     Adding an effect send to a sampler channel<br />
323     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DESTROY FX_SEND">6.4.26.</a>&nbsp;
324     Removing an effect send from a sampler channel<br />
325     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET FX_SENDS">6.4.27.</a>&nbsp;
326     Getting amount of effect sends on a sampler channel<br />
327     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST FX_SENDS">6.4.28.</a>&nbsp;
328     Listing all effect sends on a sampler channel<br />
329     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET FX_SEND INFO">6.4.29.</a>&nbsp;
330     Getting effect send information<br />
331 iliev 1137 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET FX_SEND NAME">6.4.30.</a>&nbsp;
332     Changing effect send's name<br />
333     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET FX_SEND AUDIO_OUTPUT_CHANNEL">6.4.31.</a>&nbsp;
334 schoenebeck 1002 Altering effect send's audio routing<br />
335 iliev 1137 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET FX_SEND MIDI_CONTROLLER">6.4.32.</a>&nbsp;
336 schoenebeck 1028 Altering effect send's MIDI controller<br />
337 iliev 1137 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET FX_SEND LEVEL">6.4.33.</a>&nbsp;
338 schoenebeck 1028 Altering effect send's send level<br />
339 iliev 1137 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#RESET CHANNEL">6.4.34.</a>&nbsp;
340 senoner 542 Resetting a sampler channel<br />
341 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor12">6.5.</a>&nbsp;
342 senoner 542 Controlling connection<br />
343 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE">6.5.1.</a>&nbsp;
344 senoner 542 Register front-end for receiving event messages<br />
345 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#UNSUBSCRIBE">6.5.2.</a>&nbsp;
346 senoner 542 Unregister front-end for not receiving event messages<br />
347 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET ECHO">6.5.3.</a>&nbsp;
348 senoner 542 Enable or disable echo of commands<br />
349 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#QUIT">6.5.4.</a>&nbsp;
350 senoner 542 Close client connection<br />
351 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor13">6.6.</a>&nbsp;
352 senoner 542 Global commands<br />
353 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET TOTAL_VOICE_COUNT">6.6.1.</a>&nbsp;
354     Current number of active voices<br />
355     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET TOTAL_VOICE_COUNT_MAX">6.6.2.</a>&nbsp;
356     Maximum amount of active voices<br />
357     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#RESET">6.6.3.</a>&nbsp;
358 senoner 542 Reset sampler<br />
359 schoenebeck 940 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET SERVER INFO">6.6.4.</a>&nbsp;
360 schoenebeck 575 General sampler informations<br />
361 schoenebeck 1006 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET VOLUME">6.6.5.</a>&nbsp;
362     Getting global volume attenuation<br />
363     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET VOLUME">6.6.6.</a>&nbsp;
364     Setting global volume attenuation<br />
365 schoenebeck 974 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#MIDI Instrument Mapping">6.7.</a>&nbsp;
366 schoenebeck 945 MIDI Instrument Mapping<br />
367 schoenebeck 974 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD MIDI_INSTRUMENT MAP">6.7.1.</a>&nbsp;
368     Create a new MIDI instrument map<br />
369     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE MIDI_INSTRUMENT_MAP">6.7.2.</a>&nbsp;
370     Delete one particular or all MIDI instrument maps<br />
371     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENT_MAPS">6.7.3.</a>&nbsp;
372     Get amount of existing MIDI instrument maps<br />
373     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST MIDI_INSTRUMENT_MAPS">6.7.4.</a>&nbsp;
374     Getting all created MIDI instrument maps<br />
375     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENT_MAP INFO">6.7.5.</a>&nbsp;
376     Getting MIDI instrument map information<br />
377     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET MIDI_INSTRUMENT_MAP NAME">6.7.6.</a>&nbsp;
378     Renaming a MIDI instrument map<br />
379     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#MAP MIDI_INSTRUMENT">6.7.7.</a>&nbsp;
380 schoenebeck 945 Create or replace a MIDI instrument map entry<br />
381 schoenebeck 974 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENTS">6.7.8.</a>&nbsp;
382 schoenebeck 945 Getting ammount of MIDI instrument map entries<br />
383 schoenebeck 974 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST MIDI_INSTRUMENTS">6.7.9.</a>&nbsp;
384     Getting indeces of all entries of a MIDI instrument map<br />
385     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#UNMAP MIDI_INSTRUMENT">6.7.10.</a>&nbsp;
386 schoenebeck 945 Remove an entry from the MIDI instrument map<br />
387 schoenebeck 974 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INSTRUMENT INFO">6.7.11.</a>&nbsp;
388 schoenebeck 945 Get current settings of MIDI instrument map entry<br />
389 schoenebeck 974 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CLEAR MIDI_INSTRUMENTS">6.7.12.</a>&nbsp;
390 schoenebeck 945 Clear MIDI instrument map<br />
391 iliev 1162 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#Managing Instruments Database">6.8.</a>&nbsp;
392     Managing Instruments Database<br />
393     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD DB_INSTRUMENT_DIRECTORY">6.8.1.</a>&nbsp;
394     Creating a new instrument directory<br />
395     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE DB_INSTRUMENT_DIRECTORY">6.8.2.</a>&nbsp;
396     Deleting an instrument directory<br />
397     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENT_DIRECTORIES">6.8.3.</a>&nbsp;
398     Getting amount of instrument directories<br />
399     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST DB_INSTRUMENT_DIRECTORIES">6.8.4.</a>&nbsp;
400     Listing all directories in specific directory<br />
401     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENT_DIRECTORY INFO">6.8.5.</a>&nbsp;
402     Getting instrument directory information<br />
403     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET DB_INSTRUMENT_DIRECTORY NAME">6.8.6.</a>&nbsp;
404     Renaming an instrument directory<br />
405     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#MOVE DB_INSTRUMENT_DIRECTORY">6.8.7.</a>&nbsp;
406     Moving an instrument directory<br />
407 iliev 1189 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#COPY DB_INSTRUMENT_DIRECTORY">6.8.8.</a>&nbsp;
408     Copying instrument directories<br />
409     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">6.8.9.</a>&nbsp;
410 iliev 1162 Changing the description of directory<br />
411 iliev 1189 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#FIND DB_INSTRUMENT_DIRECTORIES">6.8.10.</a>&nbsp;
412     Finding directories<br />
413     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD DB_INSTRUMENTS">6.8.11.</a>&nbsp;
414 iliev 1162 Adding instruments to the instruments database<br />
415 iliev 1189 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE DB_INSTRUMENT">6.8.12.</a>&nbsp;
416 iliev 1162 Removing an instrument<br />
417 iliev 1189 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENTS">6.8.13.</a>&nbsp;
418 iliev 1162 Getting amount of instruments<br />
419 iliev 1189 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST DB_INSTRUMENTS">6.8.14.</a>&nbsp;
420 iliev 1162 Listing all instruments in specific directory<br />
421 iliev 1189 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENT INFO">6.8.15.</a>&nbsp;
422 iliev 1162 Getting instrument information<br />
423 iliev 1189 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET DB_INSTRUMENT NAME">6.8.16.</a>&nbsp;
424 iliev 1162 Renaming an instrument<br />
425 iliev 1189 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#MOVE DB_INSTRUMENT">6.8.17.</a>&nbsp;
426 iliev 1162 Moving an instrument<br />
427 iliev 1189 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#COPY DB_INSTRUMENT">6.8.18.</a>&nbsp;
428     Copying instruments<br />
429     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET DB_INSTRUMENT DESCRIPTION">6.8.19.</a>&nbsp;
430 iliev 1162 Changing the description of instrument<br />
431 iliev 1189 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#FIND DB_INSTRUMENTS">6.8.20.</a>&nbsp;
432     Finding instruments<br />
433 iliev 1201 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENTS_JOB INFO">6.8.21.</a>&nbsp;
434     Getting job status information<br />
435 schoenebeck 1363 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#FORMAT INSTRUMENTS_DB">6.8.22.</a>&nbsp;
436     Formatting the instruments database<br />
437     &nbsp;&nbsp;&nbsp;&nbsp;<a href="#editing_instruments">6.9.</a>&nbsp;
438     Editing Instruments<br />
439     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#EDIT INSTRUMENT">6.9.1.</a>&nbsp;
440     Opening an appropriate instrument editor application<br />
441 schoenebeck 575 <a href="#command_syntax">7.</a>&nbsp;
442 senoner 542 Command Syntax<br />
443 schoenebeck 1251 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#character_set">7.1.</a>&nbsp;
444     Character Set and Escape Sequences<br />
445 schoenebeck 575 <a href="#events">8.</a>&nbsp;
446 senoner 542 Events<br />
447 iliev 992 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT">8.1.</a>&nbsp;
448     Number of audio output devices changed<br />
449     &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO">8.2.</a>&nbsp;
450     Audio output device's settings changed<br />
451     &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INPUT_DEVICE_COUNT">8.3.</a>&nbsp;
452     Number of MIDI input devices changed<br />
453     &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INPUT_DEVICE_INFO">8.4.</a>&nbsp;
454     MIDI input device's settings changed<br />
455     &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE CHANNEL_COUNT">8.5.</a>&nbsp;
456 senoner 542 Number of sampler channels changed<br />
457 iliev 992 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE VOICE_COUNT">8.6.</a>&nbsp;
458 senoner 542 Number of active voices changed<br />
459 iliev 992 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE STREAM_COUNT">8.7.</a>&nbsp;
460 senoner 542 Number of active disk streams changed<br />
461 iliev 992 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE BUFFER_FILL">8.8.</a>&nbsp;
462 senoner 542 Disk stream buffer fill state changed<br />
463 iliev 992 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE CHANNEL_INFO">8.9.</a>&nbsp;
464 senoner 542 Channel information changed<br />
465 iliev 1110 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE FX_SEND_COUNT">8.10.</a>&nbsp;
466     Number of effect sends changed<br />
467     &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE FX_SEND_INFO">8.11.</a>&nbsp;
468     Effect send information changed<br />
469     &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE TOTAL_VOICE_COUNT">8.12.</a>&nbsp;
470 schoenebeck 940 Total number of active voices changed<br />
471 iliev 1110 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT">8.13.</a>&nbsp;
472 iliev 992 Number of MIDI instrument maps changed<br />
473 iliev 1110 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO">8.14.</a>&nbsp;
474 iliev 992 MIDI instrument map information changed<br />
475 iliev 1110 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_COUNT">8.15.</a>&nbsp;
476 iliev 992 Number of MIDI instruments changed<br />
477 iliev 1110 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MIDI_INSTRUMENT_INFO">8.16.</a>&nbsp;
478 iliev 992 MIDI instrument information changed<br />
479 iliev 1110 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE GLOBAL_INFO">8.17.</a>&nbsp;
480     Global settings changed<br />
481 iliev 1162 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT">8.18.</a>&nbsp;
482     Number of database instrument directories changed<br />
483     &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO">8.19.</a>&nbsp;
484     Database instrument directory information changed<br />
485     &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENT_COUNT">8.20.</a>&nbsp;
486     Number of database instruments changed<br />
487     &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENT_INFO">8.21.</a>&nbsp;
488     Database instrument information changed<br />
489 iliev 1201 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENTS_JOB_INFO">8.22.</a>&nbsp;
490     Database job status information changed<br />
491     &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MISCELLANEOUS">8.23.</a>&nbsp;
492 senoner 542 Miscellaneous and debugging events<br />
493 schoenebeck 974 <a href="#anchor14">9.</a>&nbsp;
494 senoner 542 Security Considerations<br />
495 schoenebeck 974 <a href="#anchor15">10.</a>&nbsp;
496 senoner 542 Acknowledgments<br />
497 schoenebeck 575 <a href="#rfc.references1">11.</a>&nbsp;
498 senoner 542 References<br />
499     <a href="#rfc.authors">&#167;</a>&nbsp;
500     Author's Address<br />
501     <a href="#rfc.copyright">&#167;</a>&nbsp;
502     Intellectual Property and Copyright Statements<br />
503     </p>
504     <br clear="all" />
505    
506     <a name="anchor1"></a><br /><hr />
507 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>
508     <a name="rfc.section.1"></a><h3>1.&nbsp;
509     Requirements notation</h3>
510 senoner 542
511     <p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
512     "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
513     and "OPTIONAL" in this document are to be interpreted as
514 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>.
515 senoner 542 </p>
516     <p>This protocol is always case-sensitive if not explicitly
517     claimed the opposite.
518     </p>
519     <p>In examples, "C:" and "S:" indicate lines sent by the client
520     (front-end) and server (LinuxSampler) respectively. Lines in
521     examples must be interpreted as every line being CRLF
522     terminated (carriage return character followed by line feed
523 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>),
524     thus the following example:
525 senoner 542 </p>
526 schoenebeck 708 <p>
527     </p>
528 senoner 542 <blockquote class="text">
529     <p>C: "some line"
530     </p>
531     <p>&nbsp;&nbsp;&nbsp;"another line"
532     </p>
533 schoenebeck 708 </blockquote><p>
534 schoenebeck 940
535 schoenebeck 708 </p>
536 senoner 542 <p>must actually be interpreted as client sending the following
537     message:
538     </p>
539 schoenebeck 708 <p>
540     </p>
541 senoner 542 <blockquote class="text">
542     <p>"some line&lt;CR&gt;&lt;LF&gt;another
543     line&lt;CR&gt;&lt;LF&gt;"
544     </p>
545 schoenebeck 708 </blockquote><p>
546 schoenebeck 940
547 schoenebeck 708 </p>
548 senoner 542 <p>where &lt;CR&gt; symbolizes the carriage return character and
549     &lt;LF&gt; the line feed character as defined in the ASCII
550     standard.
551     </p>
552     <p>Due to technical reasons, messages can arbitrary be
553     fragmented, means the following example:
554     </p>
555 schoenebeck 708 <p>
556     </p>
557 senoner 542 <blockquote class="text">
558     <p>S: "abcd"
559     </p>
560 schoenebeck 708 </blockquote><p>
561 schoenebeck 940
562 schoenebeck 708 </p>
563 senoner 542 <p>could also happen to be sent in three messages like in the
564     following sequence scenario:
565     </p>
566 schoenebeck 708 <p>
567     </p>
568 senoner 542 <ul class="text">
569     <li>server sending message "a"
570     </li>
571     <li>followed by a delay (pause) with
572     arbitrary duration
573     </li>
574     <li>followed by server sending message
575     "bcd&lt;CR&gt;"
576     </li>
577     <li>again followed by a delay (pause) with arbitrary
578     duration
579     </li>
580     <li>followed by server sending the message
581     "&lt;LF&gt;"
582     </li>
583 schoenebeck 708 </ul><p>
584 schoenebeck 940
585 schoenebeck 708 </p>
586 senoner 542 <p>where again &lt;CR&gt; and &lt;LF&gt; symbolize the carriage
587     return and line feed characters respectively.
588     </p>
589 schoenebeck 575 <a name="LSCP versioning"></a><br /><hr />
590 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>
591     <a name="rfc.section.2"></a><h3>2.&nbsp;
592     Versioning of this specification</h3>
593 schoenebeck 575
594     <p>LSCP will certainly be extended and enhanced by-and-by. Each official
595     release of the LSCP specification will be tagged with a unique version
596     tuple. The version tuple consists at least of a major and minor version
597     number like:
598 schoenebeck 940
599 schoenebeck 575 </p>
600 schoenebeck 708 <p>
601     </p>
602 schoenebeck 575 <blockquote class="text">
603     <p>"1.2"
604     </p>
605 schoenebeck 708 </blockquote><p>
606 schoenebeck 940
607 schoenebeck 708 </p>
608 schoenebeck 575 <p>
609     In this example the major version number would be "1" and the minor
610     version number would be "2". Note that the version tuple might also
611     have more than two elements. The major version number defines a
612     group of backward compatible versions. That means a frontend is
613     compatible to the connected sampler if and only if the LSCP versions
614     to which each of the two parties complies to, match both of the
615     following rules:
616 schoenebeck 940
617 schoenebeck 575 </p>
618     <p>Compatibility:
619     </p>
620 schoenebeck 708 <p>
621     </p>
622 schoenebeck 575 <ol class="text">
623     <li>The frontend's LSCP major version and the sampler's LSCP
624     major version are exactly equal.
625     </li>
626     <li>The frontend's LSCP minor version is less or equal than
627     the sampler's LSCP minor version.
628     </li>
629 schoenebeck 708 </ol><p>
630 schoenebeck 940
631 schoenebeck 708 </p>
632 schoenebeck 575 <p>
633     Compatibility can only be claimed if both rules are true.
634     The frontend can use the
635 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
636 schoenebeck 575 get the version of the LSCP specification the sampler complies with.
637 schoenebeck 940
638 schoenebeck 575 </p>
639 senoner 542 <a name="anchor2"></a><br /><hr />
640 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>
641     <a name="rfc.section.3"></a><h3>3.&nbsp;
642     Introduction</h3>
643 senoner 542
644     <p>LinuxSampler is a so called software sampler application
645     capable to playback audio samples from a computer's Random
646     Access Memory (RAM) as well as directly streaming it from disk.
647     LinuxSampler is designed to be modular. It provides several so
648     called "sampler engines" where each engine is specialized for a
649     certain purpose. LinuxSampler has virtual channels which will be
650     referred in this document as "sampler channels". The channels
651     are in such way virtual as they can be connected to an
652     arbitrary MIDI input method and arbitrary MIDI channel (e.g.
653     sampler channel 17 could be connected to an ALSA sequencer
654     device 64:0 and listening to MIDI channel 1 there). Each sampler
655 schoenebeck 575 channel will be associated with an instance of one of the available
656 senoner 542 sampler engines (e.g. GigEngine, DLSEngine). The audio output of
657     each sampler channel can be routed to an arbitrary audio output
658     method (ALSA / JACK) and an arbitrary audio output channel
659     there.
660     </p>
661     <a name="anchor3"></a><br /><hr />
662 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>
663     <a name="rfc.section.4"></a><h3>4.&nbsp;
664     Focus of this protocol</h3>
665 senoner 542
666     <p>Main focus of this protocol is to provide a way to configure
667     a running LinuxSampler instance and to retrieve information
668     about it. The focus of this protocol is not to provide a way to
669     control synthesis parameters or even to trigger or release
670     notes. Or in other words; the focus are those functionalities
671     which are not covered by MIDI or which may at most be handled
672     via MIDI System Exclusive Messages.
673     </p>
674     <a name="anchor4"></a><br /><hr />
675 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>
676     <a name="rfc.section.5"></a><h3>5.&nbsp;
677     Communication Overview</h3>
678 senoner 542
679     <p>There are two distinct methods of communication between a
680     running instance of LinuxSampler and one or more control
681     applications, so called "front-ends": a simple request/response
682     communication method used by the clients to give commands to the
683     server as well as to inquire about server's status and a
684     subscribe/notify communication method used by the client to
685     subscribe to and receive notifications of certain events as they
686     happen on the server. The latter needs more effort to be
687     implemented in the front-end application. The two communication
688     methods will be described next.
689     </p>
690 schoenebeck 940 <a name="anchor5"></a><br /><hr />
691 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>
692     <a name="rfc.section.5.1"></a><h3>5.1.&nbsp;
693     Request/response communication method</h3>
694 senoner 542
695 schoenebeck 575 <p>This simple communication method is based on
696 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
697 senoner 542 front-end application establishes a TCP connection to the
698     LinuxSampler instance on a certain host system. Then the
699     front-end application will send certain ASCII based commands
700     as defined in this document (every command line must be CRLF
701     terminated - see "Conventions used in this document" at the
702     beginning of this document) and the LinuxSampler application
703     will response after a certain process time with an
704     appropriate ASCII based answer, also as defined in this
705     document. So this TCP communication is simply based on query
706     and answer paradigm. That way LinuxSampler is only able to
707     answer on queries from front-ends, but not able to
708     automatically send messages to the client if it's not asked
709     to. The fronted should not reconnect to LinuxSampler for
710     every single command, instead it should keep the connection
711     established and simply resend message(s) for subsequent
712     commands. To keep information in the front-end up-to-date
713     the front-end has to periodically send new requests to get
714     the current information from the LinuxSampler instance. This
715     is often referred to as "polling". While polling is simple
716     to implement and may be OK to use in some cases, there may
717     be disadvantages to polling such as network traffic overhead
718     and information being out of date.
719     It is possible for a client or several clients to open more
720     than one connection to the server at the same time. It is
721     also possible to send more than one request to the server
722     at the same time but if those requests are sent over the
723     same connection server MUST execute them sequentially. Upon
724     executing a request server will produce a result set and
725     send it to the client. Each and every request made by the
726     client MUST result in a result set being sent back to the
727     client. No other data other than a result set may be sent by
728     a server to a client. No result set may be sent to a client
729     without the client sending request to the server first. On
730     any particular connection, result sets MUST be sent in their
731     entirety without being interrupted by other result sets. If
732     several requests got queued up at the server they MUST be
733     processed in the order they were received and result sets
734     MUST be sent back in the same order.
735     </p>
736 schoenebeck 940 <a name="anchor6"></a><br /><hr />
737 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>
738     <a name="rfc.section.5.1.1"></a><h3>5.1.1.&nbsp;
739     Result format</h3>
740 senoner 542
741     <p>Result set could be one of the following types:
742     </p>
743 schoenebeck 708 <p>
744     </p>
745 senoner 542 <ol class="text">
746     <li>Normal
747     </li>
748     <li>Warning
749     </li>
750     <li>Error
751     </li>
752 schoenebeck 708 </ol><p>
753 schoenebeck 940
754 schoenebeck 708 </p>
755 senoner 542 <p>Warning and Error result sets MUST be single line and
756     have the following format:
757     </p>
758 schoenebeck 708 <p>
759     </p>
760 senoner 542 <ul class="text">
761     <li>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;"
762     </li>
763     <li>"ERR:&lt;error-code&gt;:&lt;error-message&gt;"
764     </li>
765 schoenebeck 708 </ul><p>
766 schoenebeck 940
767 schoenebeck 708 </p>
768 senoner 542 <p>Where &lt;warning-code&gt; and &lt;error-code&gt; are
769     numeric unique identifiers of the warning or error and
770     &lt;warning-message&gt; and &lt;error-message&gt; are
771     human readable descriptions of the warning or error
772     respectively.
773     </p>
774     <p>Examples:
775     </p>
776 schoenebeck 708 <p>
777     </p>
778 senoner 542 <blockquote class="text">
779     <p>C: "LOAD INSTRUMENT '/home/me/Boesendorfer24bit.gig" 0 0
780     </p>
781     <p>S: "WRN:32:This is a 24 bit patch which is not supported natively yet."
782     </p>
783 schoenebeck 708 </blockquote><p>
784 schoenebeck 940
785 schoenebeck 708 </p>
786     <p>
787     </p>
788 senoner 542 <blockquote class="text">
789     <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA EAR"
790     </p>
791     <p>S: "ERR:3456:Audio output driver 'ALSA' does not have a parameter 'EAR'."
792     </p>
793 schoenebeck 708 </blockquote><p>
794 schoenebeck 940
795 schoenebeck 708 </p>
796     <p>
797     </p>
798 senoner 542 <blockquote class="text">
799     <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 123456"
800     </p>
801     <p>S: "ERR:9:There is no audio output device with index 123456."
802     </p>
803 schoenebeck 708 </blockquote><p>
804 schoenebeck 940
805 schoenebeck 708 </p>
806 senoner 542 <p>Normal result sets could be:
807     </p>
808 schoenebeck 708 <p>
809     </p>
810 senoner 542 <ol class="text">
811     <li>Empty
812     </li>
813     <li>Single line
814     </li>
815     <li>Multi-line
816     </li>
817 schoenebeck 708 </ol><p>
818 schoenebeck 940
819 schoenebeck 708 </p>
820 senoner 542 <p> Empty result set is issued when the server only
821     needed to acknowledge the fact that the request was
822     received and it was processed successfully and no
823     additional information is available. This result set has
824     the following format:
825     </p>
826 schoenebeck 708 <p>
827     </p>
828 senoner 542 <blockquote class="text">
829     <p>"OK"
830     </p>
831 schoenebeck 708 </blockquote><p>
832 schoenebeck 940
833 schoenebeck 708 </p>
834 senoner 542 <p>Example:
835     </p>
836 schoenebeck 708 <p>
837     </p>
838 senoner 542 <blockquote class="text">
839     <p>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 CHANNELS=4"
840     </p>
841     <p>S: "OK"
842     </p>
843 schoenebeck 708 </blockquote><p>
844 schoenebeck 940
845 schoenebeck 708 </p>
846 senoner 542 <p>Single line result sets are command specific. One
847     example of a single line result set is an empty line.
848     Multi-line result sets are command specific and may
849     include one or more lines of information. They MUST
850     always end with the following line:
851     </p>
852 schoenebeck 708 <p>
853     </p>
854 senoner 542 <blockquote class="text">
855     <p>"."
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: "GET AUDIO_OUTPUT_DEVICE INFO 0"
866     </p>
867     <p>S: "DRIVER: ALSA"
868     </p>
869     <p>&nbsp;&nbsp;&nbsp;"CHANNELS: 2"
870     </p>
871     <p>&nbsp;&nbsp;&nbsp;"SAMPLERATE: 44100"
872     </p>
873     <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
874     </p>
875     <p>&nbsp;&nbsp;&nbsp;"FRAGMENTS: 2"
876     </p>
877     <p>&nbsp;&nbsp;&nbsp;"FRAGMENTSIZE: 128"
878     </p>
879     <p>&nbsp;&nbsp;&nbsp;"CARD: '0,0'"
880     </p>
881     <p>&nbsp;&nbsp;&nbsp;"."
882     </p>
883 schoenebeck 708 </blockquote><p>
884 schoenebeck 940
885 schoenebeck 708 </p>
886 senoner 542 <p>In addition to above mentioned formats, warnings and
887     empty result sets MAY be indexed. In this case, they
888     have the following formats respectively:
889     </p>
890 schoenebeck 708 <p>
891     </p>
892 senoner 542 <ul class="text">
893     <li>"WRN[&lt;index&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;"
894     </li>
895     <li>"OK[&lt;index&gt;]"
896     </li>
897 schoenebeck 708 </ul><p>
898 schoenebeck 940
899 schoenebeck 708 </p>
900 senoner 542 <p>where &lt;index&gt; is command specific and is used
901     to indicate channel number that the result set was
902     related to or other integer value.
903     </p>
904     <p>Each line of the result set MUST end with
905     &lt;CRLF&gt;.
906     </p>
907     <p>Examples:
908     </p>
909 schoenebeck 708 <p>
910     </p>
911 senoner 542 <blockquote class="text">
912     <p>C: "ADD CHANNEL"
913     </p>
914     <p>S: "OK[12]"
915     </p>
916 schoenebeck 708 </blockquote><p>
917 schoenebeck 940
918 schoenebeck 708 </p>
919     <p>
920     </p>
921 senoner 542 <blockquote class="text">
922     <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"
923     </p>
924     <p>S: "WRN[0]:32:Sample rate not supported, using 44100 instead."
925     </p>
926 schoenebeck 708 </blockquote><p>
927 schoenebeck 940
928 schoenebeck 708 </p>
929 schoenebeck 940 <a name="anchor7"></a><br /><hr />
930 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>
931     <a name="rfc.section.5.2"></a><h3>5.2.&nbsp;
932     Subscribe/notify communication method</h3>
933 senoner 542
934     <p>This more sophisticated communication method is actually
935     only an extension of the simple request/response
936     communication method. The front-end still uses a TCP
937     connection and sends the same commands on the TCP
938     connection. Two extra commands are SUBSCRIBE and UNSUBSCRIBE
939     commands that allow a client to tell the server that it is
940     interested in receiving notifications about certain events
941     as they happen on the server. The SUBSCRIBE command has the
942     following syntax:
943     </p>
944 schoenebeck 708 <p>
945     </p>
946 senoner 542 <blockquote class="text">
947     <p>SUBSCRIBE &lt;event-id&gt;
948     </p>
949 schoenebeck 708 </blockquote><p>
950 schoenebeck 940
951 schoenebeck 708 </p>
952 senoner 542 <p>where &lt;event-id&gt; will be replaced by the respective
953     event that client wants to subscribe to. Upon receiving such
954     request, server SHOULD respond with OK and start sending
955     EVENT notifications when a given even has occurred to the
956     front-end when an event has occurred. It MAY be possible
957     certain events may be sent before OK response during real
958     time nature of their generation. Event messages have the
959     following format:
960     </p>
961 schoenebeck 708 <p>
962     </p>
963 senoner 542 <blockquote class="text">
964     <p>NOTIFY:&lt;event-id&gt;:&lt;custom-event-data&gt;
965     </p>
966 schoenebeck 708 </blockquote><p>
967 schoenebeck 940
968 schoenebeck 708 </p>
969 senoner 542 <p>where &lt;event-id&gt; uniquely identifies the event that
970     has occurred and &lt;custom-event-data&gt; is event
971     specific.
972     </p>
973     <p>Several rules must be followed by the server when
974     generating events:
975     </p>
976 schoenebeck 708 <p>
977     </p>
978 senoner 542 <ol class="text">
979     <li>Events MUST NOT be sent to any client who has not
980     issued an appropriate SUBSCRIBE command.
981     </li>
982     <li>Events MUST only be sent using the same
983     connection that was used to subscribe to them.
984     </li>
985     <li>When response is being sent to the client, event
986     MUST be inserted in the stream before or after the
987     response, but NOT in the middle. Same is true about
988     the response. It should never be inserted in the
989     middle of the event message as well as any other
990     response.
991     </li>
992 schoenebeck 708 </ol><p>
993 schoenebeck 940
994 schoenebeck 708 </p>
995 senoner 542 <p>If the client is not interested in a particular event
996     anymore it MAY issue UNSUBSCRIBE command using the following
997     syntax:
998     </p>
999 schoenebeck 708 <p>
1000     </p>
1001 senoner 542 <blockquote class="text">
1002     <p>UNSUBSCRIBE &lt;event-id&gt;
1003     </p>
1004 schoenebeck 708 </blockquote><p>
1005 schoenebeck 940
1006 schoenebeck 708 </p>
1007 senoner 542 <p>where &lt;event-id&gt; will be replace by the respective
1008     event that client is no longer interested in receiving. For
1009 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>.
1010 senoner 542 </p>
1011     <p>Example: the fill states of disk stream buffers have
1012     changed on sampler channel 4 and the LinuxSampler instance
1013     will react by sending the following message to all clients
1014     who subscribed to this event:
1015     </p>
1016 schoenebeck 708 <p>
1017     </p>
1018 senoner 542 <blockquote class="text">
1019     <p>NOTIFY:CHANNEL_BUFFER_FILL:4 [35]62%,[33]80%,[37]98%
1020     </p>
1021 schoenebeck 708 </blockquote><p>
1022 schoenebeck 940
1023 schoenebeck 708 </p>
1024 senoner 542 <p>Which means there are currently three active streams on
1025     sampler channel 4, where the stream with ID "35" is filled
1026     by 62%, stream with ID 33 is filled by 80% and stream with
1027     ID 37 is filled by 98%.
1028     </p>
1029     <p>Clients may choose to open more than one connection to
1030     the server and use some connections to receive notifications
1031     while using other connections to issue commands to the
1032     back-end. This is entirely legal and up to the
1033     implementation. This does not change the protocol in any way
1034     and no special restrictions exist on the server to allow or
1035     disallow this or to track what connections belong to what
1036     front-ends. Server will listen on a single port, accept
1037     multiple connections and support protocol described in this
1038     specification in it's entirety on this single port on each
1039     connection that it accepted.
1040     </p>
1041     <p>Due to the fact that TCP is used for this communication,
1042     dead peers will be detected automatically by the OS TCP
1043     stack. While it may take a while to detect dead peers if no
1044     traffic is being sent from server to client (TCP keep-alive
1045     timer is set to 2 hours on many OSes) it will not be an
1046     issue here as when notifications are sent by the server,
1047     dead client will be detected quickly.
1048     </p>
1049     <p>When connection is closed for any reason server MUST
1050     forget all subscriptions that were made on this connection.
1051     If client reconnects it MUST resubscribe to all events that
1052     it wants to receive.
1053     </p>
1054 schoenebeck 575 <a name="control_commands"></a><br /><hr />
1055 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>
1056     <a name="rfc.section.6"></a><h3>6.&nbsp;
1057     Description for control commands</h3>
1058 senoner 542
1059     <p>This chapter will describe the available control commands
1060     that can be sent on the TCP connection in detail. Some certain
1061 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>
1062     or <a class='info' href='#GET ENGINE INFO'>"GET ENGINE INFO"<span> (</span><span class='info'>Getting information about an engine</span><span>)</span></a>) lead to
1063 senoner 542 multiple-line responses. In this case LinuxSampler signals the
1064     end of the response by a "." (single dot) line.
1065     </p>
1066 schoenebeck 940 <a name="anchor8"></a><br /><hr />
1067 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>
1068     <a name="rfc.section.6.1"></a><h3>6.1.&nbsp;
1069     Ignored lines and comments</h3>
1070 senoner 542
1071     <p>White lines, that is lines which only contain space and
1072     tabulator characters, and lines that start with a "#"
1073     character are ignored, thus it's possible for example to
1074     group commands and to place comments in a LSCP script
1075     file.
1076     </p>
1077 schoenebeck 940 <a name="anchor9"></a><br /><hr />
1078 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>
1079     <a name="rfc.section.6.2"></a><h3>6.2.&nbsp;
1080     Configuring audio drivers</h3>
1081 senoner 542
1082     <p>Instances of drivers in LinuxSampler are called devices.
1083     You can use multiple audio devices simultaneously, e.g. to
1084     output the sound of one sampler channel using the ALSA audio
1085     output driver, and on another sampler channel you might want
1086     to use the JACK audio output driver. For particular audio
1087     output systems it's also possible to create several devices
1088     of the same audio output driver, e.g. two separate ALSA
1089     audio output devices for using two different sound cards at
1090     the same time. This chapter describes all commands to
1091     configure LinuxSampler's audio output devices and their
1092     parameters.
1093     </p>
1094     <p>Instead of defining commands and parameters for each
1095     driver individually, all possible parameters, their meanings
1096     and possible values have to be obtained at runtime. This
1097     makes the protocol a bit abstract, but has the advantage,
1098     that front-ends can be written independently of what drivers
1099     are currently implemented and what parameters these drivers
1100     are actually offering. This means front-ends can even handle
1101     drivers which are implemented somewhere in future without
1102     modifying the front-end at all.
1103     </p>
1104     <p>Note: examples in this chapter showing particular
1105     parameters of drivers are not meant as specification of the
1106     drivers' parameters. Driver implementations in LinuxSampler
1107     might have complete different parameter names and meanings
1108     than shown in these examples or might change in future, so
1109     these examples are only meant for showing how to retrieve
1110     what parameters drivers are offering, how to retrieve their
1111     possible values, etc.
1112     </p>
1113 schoenebeck 940 <a name="GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"></a><br /><hr />
1114 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>
1115     <a name="rfc.section.6.2.1"></a><h3>6.2.1.&nbsp;
1116     Getting amount of available audio output drivers</h3>
1117 senoner 542
1118     <p>Use the following command to get the number of
1119     audio output drivers currently available for the
1120     LinuxSampler instance:
1121     </p>
1122 schoenebeck 708 <p>
1123     </p>
1124 senoner 542 <blockquote class="text">
1125     <p>GET AVAILABLE_AUDIO_OUTPUT_DRIVERS
1126     </p>
1127 schoenebeck 708 </blockquote><p>
1128 schoenebeck 940
1129 schoenebeck 708 </p>
1130 senoner 542 <p>Possible Answers:
1131     </p>
1132 schoenebeck 708 <p>
1133     </p>
1134 senoner 542 <blockquote class="text">
1135     <p>LinuxSampler will answer by sending the
1136     number of audio output drivers.
1137     </p>
1138 schoenebeck 708 </blockquote><p>
1139 schoenebeck 940
1140 schoenebeck 708 </p>
1141 senoner 542 <p>Example:
1142     </p>
1143 schoenebeck 708 <p>
1144     </p>
1145 senoner 542 <blockquote class="text">
1146     <p>C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
1147     </p>
1148     <p>S: "2"
1149     </p>
1150 schoenebeck 708 </blockquote><p>
1151 schoenebeck 940
1152 schoenebeck 708 </p>
1153 schoenebeck 940 <a name="LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"></a><br /><hr />
1154 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>
1155     <a name="rfc.section.6.2.2"></a><h3>6.2.2.&nbsp;
1156     Getting all available audio output drivers</h3>
1157 senoner 542
1158     <p>Use the following command to list all audio output
1159     drivers currently available for the LinuxSampler
1160     instance:
1161     </p>
1162 schoenebeck 708 <p>
1163     </p>
1164 senoner 542 <blockquote class="text">
1165     <p>LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS
1166     </p>
1167 schoenebeck 708 </blockquote><p>
1168 schoenebeck 940
1169 schoenebeck 708 </p>
1170 senoner 542 <p>Possible Answers:
1171     </p>
1172 schoenebeck 708 <p>
1173     </p>
1174 senoner 542 <blockquote class="text">
1175     <p>LinuxSampler will answer by sending comma
1176     separated character strings, each symbolizing an
1177     audio output driver.
1178     </p>
1179 schoenebeck 708 </blockquote><p>
1180 schoenebeck 940
1181 schoenebeck 708 </p>
1182 senoner 542 <p>Example:
1183     </p>
1184 schoenebeck 708 <p>
1185     </p>
1186 senoner 542 <blockquote class="text">
1187     <p>C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"
1188     </p>
1189     <p>S: "ALSA,JACK"
1190     </p>
1191 schoenebeck 708 </blockquote><p>
1192 schoenebeck 940
1193 schoenebeck 708 </p>
1194 schoenebeck 940 <a name="GET AUDIO_OUTPUT_DRIVER INFO"></a><br /><hr />
1195 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>
1196     <a name="rfc.section.6.2.3"></a><h3>6.2.3.&nbsp;
1197     Getting information about a specific audio
1198 schoenebeck 940 output driver</h3>
1199 senoner 542
1200     <p>Use the following command to get detailed information
1201     about a specific audio output driver:
1202     </p>
1203 schoenebeck 708 <p>
1204     </p>
1205 senoner 542 <blockquote class="text">
1206     <p>GET AUDIO_OUTPUT_DRIVER INFO
1207     &lt;audio-output-driver&gt;
1208     </p>
1209 schoenebeck 708 </blockquote><p>
1210 schoenebeck 940
1211 schoenebeck 708 </p>
1212 senoner 542 <p>Where &lt;audio-output-driver&gt; is the name of the
1213     audio output driver, returned by the
1214 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.
1215 senoner 542 </p>
1216     <p>Possible Answers:
1217     </p>
1218 schoenebeck 708 <p>
1219     </p>
1220 senoner 542 <blockquote class="text">
1221     <p>LinuxSampler will answer by sending a
1222     &lt;CRLF&gt; separated list. Each answer line
1223     begins with the information category name
1224     followed by a colon and then a space character
1225     &lt;SP&gt; and finally the info character string
1226     to that info category. At the moment the
1227     following information categories are
1228     defined:
1229     </p>
1230 schoenebeck 708 <p>
1231     </p>
1232 senoner 542 <blockquote class="text">
1233     <p>DESCRIPTION -
1234     </p>
1235     <blockquote class="text">
1236     <p> character string describing the
1237     audio output driver
1238     </p>
1239 schoenebeck 940 </blockquote>
1240    
1241 senoner 542
1242     <p>VERSION -
1243     </p>
1244     <blockquote class="text">
1245     <p>character string reflecting the
1246     driver's version
1247     </p>
1248 schoenebeck 940 </blockquote>
1249    
1250 senoner 542
1251     <p>PARAMETERS -
1252     </p>
1253     <blockquote class="text">
1254     <p>comma separated list of all
1255     parameters available for the given
1256     audio output driver, at least
1257     parameters 'channels', 'samplerate'
1258     and 'active' are offered by all audio
1259     output drivers
1260     </p>
1261 schoenebeck 940 </blockquote>
1262    
1263 senoner 542
1264 schoenebeck 940 </blockquote>
1265    
1266 senoner 542
1267     <p>The mentioned fields above don't have to be
1268     in particular order.
1269     </p>
1270 schoenebeck 708 </blockquote><p>
1271 schoenebeck 940
1272 schoenebeck 708 </p>
1273 senoner 542 <p>Example:
1274     </p>
1275 schoenebeck 708 <p>
1276     </p>
1277 senoner 542 <blockquote class="text">
1278     <p>C: "GET AUDIO_OUTPUT_DRIVER INFO ALSA"
1279     </p>
1280     <p>S: "DESCRIPTION: Advanced Linux Sound
1281     Architecture"
1282     </p>
1283     <p>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"
1284     </p>
1285     <p>&nbsp;&nbsp;&nbsp;"PARAMETERS:
1286     DRIVER,CHANNELS,SAMPLERATE,ACTIVE,FRAGMENTS,
1287     FRAGMENTSIZE,CARD"
1288     </p>
1289     <p>&nbsp;&nbsp;&nbsp;"."
1290     </p>
1291 schoenebeck 708 </blockquote><p>
1292 schoenebeck 940
1293 schoenebeck 708 </p>
1294 schoenebeck 940 <a name="GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO"></a><br /><hr />
1295 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>
1296     <a name="rfc.section.6.2.4"></a><h3>6.2.4.&nbsp;
1297     Getting information about specific audio
1298 schoenebeck 940 output driver parameter</h3>
1299 senoner 542
1300     <p>Use the following command to get detailed information
1301     about a specific audio output driver parameter:
1302     </p>
1303 schoenebeck 708 <p>
1304     </p>
1305 senoner 542 <blockquote class="text">
1306     <p>GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO &lt;audio&gt; &lt;prm&gt; [&lt;deplist&gt;]
1307     </p>
1308 schoenebeck 708 </blockquote><p>
1309 schoenebeck 940
1310 schoenebeck 708 </p>
1311 senoner 542 <p>Where &lt;audio&gt; is the name of the audio output
1312 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,
1313 senoner 542 &lt;prm&gt; a specific parameter name for which information should be
1314     obtained (as returned by the
1315 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
1316 senoner 542 &lt;deplist&gt; is an optional list of parameters on which the sought
1317     parameter &lt;prm&gt; depends on, &lt;deplist&gt; is a list of key-value
1318     pairs in form of "key1=val1 key2=val2 ...", where character string values
1319     are encapsulated into apostrophes ('). Arguments given with &lt;deplist&gt;
1320     which are not dependency parameters of &lt;prm&gt; will be ignored, means
1321     the front-end application can simply put all parameters into &lt;deplist&gt;
1322     with the values already selected by the user.
1323     </p>
1324     <p>Possible Answers:
1325     </p>
1326 schoenebeck 708 <p>
1327     </p>
1328 senoner 542 <blockquote class="text">
1329     <p>LinuxSampler will answer by sending a
1330     &lt;CRLF&gt; separated list.
1331     Each answer line begins with the information category name
1332     followed by a colon and then a space character &lt;SP&gt; and
1333     finally
1334     the info character string to that info category. There are
1335     information which is always returned, independently of the
1336     given driver parameter and there are optional information
1337     which is only shown dependently to given driver parameter. At
1338     the moment the following information categories are defined:
1339     </p>
1340 schoenebeck 708 </blockquote><p>
1341 schoenebeck 940
1342 schoenebeck 708 </p>
1343     <p>
1344     </p>
1345 senoner 542 <blockquote class="text">
1346     <p>TYPE -
1347     </p>
1348     <blockquote class="text">
1349     <p>either "BOOL" for boolean value(s) or
1350     "INT" for integer
1351     value(s) or "FLOAT" for dotted number(s) or "STRING" for
1352     character string(s)
1353     (always returned, no matter which driver parameter)
1354     </p>
1355 schoenebeck 940 </blockquote>
1356    
1357 senoner 542
1358     <p>DESCRIPTION -
1359     </p>
1360     <blockquote class="text">
1361     <p>arbitrary text describing the purpose of the parameter
1362     (always returned, no matter which driver parameter)
1363     </p>
1364 schoenebeck 940 </blockquote>
1365    
1366 senoner 542
1367     <p>MANDATORY -
1368     </p>
1369     <blockquote class="text">
1370     <p>either true or false, defines if this parameter must be
1371     given when the device is to be created with the
1372 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>
1373 senoner 542 command (always returned, no matter which driver parameter)
1374     </p>
1375 schoenebeck 940 </blockquote>
1376    
1377 senoner 542
1378     <p>FIX -
1379     </p>
1380     <blockquote class="text">
1381     <p>either true or false, if false then this parameter can
1382     be changed at any time, once the device is created by
1383 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>
1384 senoner 542 command (always returned, no matter which driver parameter)
1385     </p>
1386 schoenebeck 940 </blockquote>
1387    
1388 senoner 542
1389     <p>MULTIPLICITY -
1390     </p>
1391     <blockquote class="text">
1392     <p>either true or false, defines if this parameter allows
1393     only one value or a list of values, where true means
1394     multiple values and false only a single value allowed
1395     (always returned, no matter which driver parameter)
1396     </p>
1397 schoenebeck 940 </blockquote>
1398    
1399 senoner 542
1400     <p>DEPENDS -
1401     </p>
1402     <blockquote class="text">
1403 schoenebeck 561 <p>comma separated list of parameters this parameter depends
1404 senoner 542 on, means the values for fields 'DEFAULT', 'RANGE_MIN',
1405     'RANGE_MAX' and 'POSSIBILITIES' might depend on these
1406     listed parameters, for example assuming that an audio
1407     driver (like the ALSA driver) offers parameters 'card'
1408     and 'samplerate' then parameter 'samplerate' would
1409     depend on 'card' because the possible values for
1410     'samplerate' depends on the sound card which can be
1411     chosen by the 'card' parameter
1412     (optionally returned, dependent to driver parameter)
1413     </p>
1414 schoenebeck 940 </blockquote>
1415    
1416 senoner 542
1417     <p>DEFAULT -
1418     </p>
1419     <blockquote class="text">
1420     <p>reflects the default value for this parameter which is
1421     used when the device is created and not explicitly
1422 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,
1423 senoner 542 in case of MULTIPLCITY=true, this is a comma separated
1424     list, that's why character strings are encapsulated into
1425     apostrophes (')
1426     (optionally returned, dependent to driver parameter)
1427     </p>
1428 schoenebeck 940 </blockquote>
1429    
1430 senoner 542
1431     <p>RANGE_MIN -
1432     </p>
1433     <blockquote class="text">
1434     <p>defines lower limit of the allowed value range for this
1435     parameter, can be an integer value as well as a dotted
1436     number, this parameter is often used in conjunction
1437     with RANGE_MAX, but may also appear without
1438     (optionally returned, dependent to driver parameter)
1439     </p>
1440 schoenebeck 940 </blockquote>
1441    
1442 senoner 542
1443     <p>RANGE_MAX -
1444     </p>
1445     <blockquote class="text">
1446     <p>defines upper limit of the allowed value range for this
1447     parameter, can be an integer value as well as a dotted
1448     number, this parameter is often used in conjunction with
1449     RANGE_MIN, but may also appear without
1450     (optionally returned, dependent to driver parameter)
1451     </p>
1452 schoenebeck 940 </blockquote>
1453    
1454 senoner 542
1455     <p>POSSIBILITIES -
1456     </p>
1457     <blockquote class="text">
1458     <p>comma separated list of possible values for this
1459     parameter, character strings are encapsulated into
1460     apostrophes
1461     (optionally returned, dependent to driver parameter)
1462     </p>
1463 schoenebeck 940 </blockquote>
1464    
1465 senoner 542
1466 schoenebeck 708 </blockquote><p>
1467 schoenebeck 940
1468 schoenebeck 708 </p>
1469 senoner 542 <p>The mentioned fields above don't have to be in particular order.
1470     </p>
1471     <p>Examples:
1472     </p>
1473 schoenebeck 708 <p>
1474     </p>
1475 senoner 542 <blockquote class="text">
1476     <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA CARD"
1477     </p>
1478     <p>S: "DESCRIPTION: sound card to be used"
1479     </p>
1480     <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
1481     </p>
1482     <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1483     </p>
1484     <p>&nbsp;&nbsp;&nbsp;"FIX: true"
1485     </p>
1486     <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1487     </p>
1488     <p>&nbsp;&nbsp;&nbsp;"DEFAULT: '0,0'"
1489     </p>
1490     <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: '0,0','1,0','2,0'"
1491     </p>
1492     <p>&nbsp;&nbsp;&nbsp;"."
1493     </p>
1494 schoenebeck 708 </blockquote><p>
1495 schoenebeck 940
1496 schoenebeck 708 </p>
1497     <p>
1498     </p>
1499 senoner 542 <blockquote class="text">
1500     <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE"
1501     </p>
1502     <p>S: "DESCRIPTION: output sample rate in Hz"
1503     </p>
1504     <p>&nbsp;&nbsp;&nbsp;"TYPE: INT"
1505     </p>
1506     <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1507     </p>
1508     <p>&nbsp;&nbsp;&nbsp;"FIX: false"
1509     </p>
1510     <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1511     </p>
1512     <p>&nbsp;&nbsp;&nbsp;"DEPENDS: card"
1513     </p>
1514     <p>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"
1515     </p>
1516     <p>&nbsp;&nbsp;&nbsp;"."
1517     </p>
1518 schoenebeck 708 </blockquote><p>
1519 schoenebeck 940
1520 schoenebeck 708 </p>
1521     <p>
1522     </p>
1523 senoner 542 <blockquote class="text">
1524     <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE CARD='0,0'"
1525     </p>
1526     <p>S: "DESCRIPTION: output sample rate in Hz"
1527     </p>
1528     <p>&nbsp;&nbsp;&nbsp;"TYPE: INT"
1529     </p>
1530     <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1531     </p>
1532     <p>&nbsp;&nbsp;&nbsp;"FIX: false"
1533     </p>
1534     <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1535     </p>
1536     <p>&nbsp;&nbsp;&nbsp;"DEPENDS: card"
1537     </p>
1538     <p>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"
1539     </p>
1540     <p>&nbsp;&nbsp;&nbsp;"RANGE_MIN: 22050"
1541     </p>
1542     <p>&nbsp;&nbsp;&nbsp;"RANGE_MAX: 96000"
1543     </p>
1544     <p>&nbsp;&nbsp;&nbsp;"."
1545     </p>
1546 schoenebeck 708 </blockquote><p>
1547 schoenebeck 940
1548 schoenebeck 708 </p>
1549 schoenebeck 940 <a name="CREATE AUDIO_OUTPUT_DEVICE"></a><br /><hr />
1550 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>
1551     <a name="rfc.section.6.2.5"></a><h3>6.2.5.&nbsp;
1552     Creating an audio output device</h3>
1553 senoner 542
1554     <p>Use the following command to create a new audio output device for the desired audio output system:
1555     </p>
1556 schoenebeck 708 <p>
1557     </p>
1558 senoner 542 <blockquote class="text">
1559     <p>CREATE AUDIO_OUTPUT_DEVICE &lt;audio-output-driver&gt; [&lt;param-list&gt;]
1560     </p>
1561 schoenebeck 708 </blockquote><p>
1562 schoenebeck 940
1563 schoenebeck 708 </p>
1564 senoner 542 <p>Where &lt;audio-output-driver&gt; should be replaced by the desired audio
1565 schoenebeck 575 output system as returned by the
1566 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>
1567 schoenebeck 575 command and &lt;param-list&gt; by an optional list of driver
1568 senoner 542 specific parameters in form of "key1=val1 key2=val2 ...", where
1569     character string values should be encapsulated into apostrophes (').
1570     Note that there might be drivers which require parameter(s) to be
1571     given with this command. Use the previously described commands in
1572     this chapter to get this information.
1573     </p>
1574     <p>Possible Answers:
1575     </p>
1576 schoenebeck 708 <p>
1577     </p>
1578 senoner 542 <blockquote class="text">
1579     <p>"OK[&lt;device-id&gt;]" -
1580     </p>
1581     <blockquote class="text">
1582     <p>in case the device was successfully created, where
1583     &lt;device-id&gt; is the numerical ID of the new device
1584     </p>
1585 schoenebeck 940 </blockquote>
1586    
1587 senoner 542
1588     <p>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1589     </p>
1590     <blockquote class="text">
1591     <p>in case the device was created successfully, where
1592     &lt;device-id&gt; is the numerical ID of the new device, but there
1593     are noteworthy issue(s) related (e.g. sound card doesn't
1594     support given hardware parameters and the driver is using
1595     fall-back values), providing an appropriate warning code and
1596     warning message
1597     </p>
1598 schoenebeck 940 </blockquote>
1599    
1600 senoner 542
1601     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1602     </p>
1603     <blockquote class="text">
1604     <p>in case it failed, providing an appropriate error code and error message
1605     </p>
1606 schoenebeck 940 </blockquote>
1607    
1608 senoner 542
1609 schoenebeck 708 </blockquote><p>
1610 schoenebeck 940
1611 schoenebeck 708 </p>
1612 senoner 542 <p>Examples:
1613     </p>
1614 schoenebeck 708 <p>
1615     </p>
1616 senoner 542 <blockquote class="text">
1617     <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA"
1618     </p>
1619     <p>S: "OK[0]"
1620     </p>
1621 schoenebeck 708 </blockquote><p>
1622 schoenebeck 940
1623 schoenebeck 708 </p>
1624     <p>
1625     </p>
1626 senoner 542 <blockquote class="text">
1627     <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"
1628     </p>
1629     <p>S: "OK[1]"
1630     </p>
1631 schoenebeck 708 </blockquote><p>
1632 schoenebeck 940
1633 schoenebeck 708 </p>
1634 schoenebeck 940 <a name="DESTROY AUDIO_OUTPUT_DEVICE"></a><br /><hr />
1635 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>
1636     <a name="rfc.section.6.2.6"></a><h3>6.2.6.&nbsp;
1637     Destroying an audio output device</h3>
1638 senoner 542
1639     <p>Use the following command to destroy a created output device:
1640     </p>
1641 schoenebeck 708 <p>
1642     </p>
1643 senoner 542 <blockquote class="text">
1644     <p>DESTROY AUDIO_OUTPUT_DEVICE &lt;device-id&gt;
1645     </p>
1646 schoenebeck 708 </blockquote><p>
1647 schoenebeck 940
1648 schoenebeck 708 </p>
1649 senoner 542 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1650     audio output device as given by the
1651 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>
1652     or <a class='info' href='#LIST AUDIO_OUTPUT_DEVICES'>"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class='info'>Getting all created audio output device list</span><span>)</span></a>
1653 senoner 542 command.
1654     </p>
1655     <p>Possible Answers:
1656     </p>
1657 schoenebeck 708 <p>
1658     </p>
1659 senoner 542 <blockquote class="text">
1660     <p>"OK" -
1661     </p>
1662     <blockquote class="text">
1663     <p>in case the device was successfully destroyed
1664     </p>
1665 schoenebeck 940 </blockquote>
1666    
1667 senoner 542
1668     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1669     </p>
1670     <blockquote class="text">
1671     <p>in case the device was destroyed successfully, but there are
1672     noteworthy issue(s) related (e.g. an audio over ethernet
1673     driver was unloaded but the other host might not be
1674     informed about this situation), providing an appropriate
1675     warning code and warning message
1676     </p>
1677 schoenebeck 940 </blockquote>
1678    
1679 senoner 542
1680     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1681     </p>
1682     <blockquote class="text">
1683     <p>in case it failed, providing an appropriate error code and
1684     error message
1685     </p>
1686 schoenebeck 940 </blockquote>
1687    
1688 senoner 542
1689 schoenebeck 708 </blockquote><p>
1690 schoenebeck 940
1691 schoenebeck 708 </p>
1692 senoner 542 <p>Example:
1693     </p>
1694 schoenebeck 708 <p>
1695     </p>
1696 senoner 542 <blockquote class="text">
1697     <p>C: "DESTROY AUDIO_OUTPUT_DEVICE 0"
1698     </p>
1699     <p>S: "OK"
1700     </p>
1701 schoenebeck 708 </blockquote><p>
1702 schoenebeck 940
1703 schoenebeck 708 </p>
1704 schoenebeck 940 <a name="GET AUDIO_OUTPUT_DEVICES"></a><br /><hr />
1705 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>
1706     <a name="rfc.section.6.2.7"></a><h3>6.2.7.&nbsp;
1707     Getting all created audio output device count</h3>
1708 senoner 542
1709     <p>Use the following command to count all created audio output devices:
1710     </p>
1711 schoenebeck 708 <p>
1712     </p>
1713 senoner 542 <blockquote class="text">
1714     <p>GET AUDIO_OUTPUT_DEVICES
1715     </p>
1716 schoenebeck 708 </blockquote><p>
1717 schoenebeck 940
1718 schoenebeck 708 </p>
1719 senoner 542 <p>Possible Answers:
1720     </p>
1721 schoenebeck 708 <p>
1722     </p>
1723 senoner 542 <blockquote class="text">
1724     <p>LinuxSampler will answer by sending the current number of all
1725     audio output devices.
1726     </p>
1727 schoenebeck 708 </blockquote><p>
1728 schoenebeck 940
1729 schoenebeck 708 </p>
1730 senoner 542 <p>Example:
1731     </p>
1732 schoenebeck 708 <p>
1733     </p>
1734 senoner 542 <blockquote class="text">
1735     <p>C: "GET AUDIO_OUTPUT_DEVICES"
1736     </p>
1737     <p>S: "4"
1738     </p>
1739 schoenebeck 708 </blockquote><p>
1740 schoenebeck 940
1741 schoenebeck 708 </p>
1742 schoenebeck 940 <a name="LIST AUDIO_OUTPUT_DEVICES"></a><br /><hr />
1743 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>
1744     <a name="rfc.section.6.2.8"></a><h3>6.2.8.&nbsp;
1745     Getting all created audio output device list</h3>
1746 senoner 542
1747     <p>Use the following command to list all created audio output devices:
1748     </p>
1749 schoenebeck 708 <p>
1750     </p>
1751 senoner 542 <blockquote class="text">
1752     <p>LIST AUDIO_OUTPUT_DEVICES
1753     </p>
1754 schoenebeck 708 </blockquote><p>
1755 schoenebeck 940
1756 schoenebeck 708 </p>
1757 senoner 542 <p>Possible Answers:
1758     </p>
1759 schoenebeck 708 <p>
1760     </p>
1761 senoner 542 <blockquote class="text">
1762     <p>LinuxSampler will answer by sending a comma separated list with
1763     the numerical IDs of all audio output devices.
1764     </p>
1765 schoenebeck 708 </blockquote><p>
1766 schoenebeck 940
1767 schoenebeck 708 </p>
1768 senoner 542 <p>Example:
1769     </p>
1770 schoenebeck 708 <p>
1771     </p>
1772 senoner 542 <blockquote class="text">
1773     <p>C: "LIST AUDIO_OUTPUT_DEVICES"
1774     </p>
1775     <p>S: "0,1,4,5"
1776     </p>
1777 schoenebeck 708 </blockquote><p>
1778 schoenebeck 940
1779 schoenebeck 708 </p>
1780 schoenebeck 940 <a name="GET AUDIO_OUTPUT_DEVICE INFO"></a><br /><hr />
1781 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>
1782     <a name="rfc.section.6.2.9"></a><h3>6.2.9.&nbsp;
1783     Getting current settings of an audio output device</h3>
1784 senoner 542
1785     <p>Use the following command to get current settings of a specific, created audio output device:
1786     </p>
1787 schoenebeck 708 <p>
1788     </p>
1789 senoner 542 <blockquote class="text">
1790     <p>GET AUDIO_OUTPUT_DEVICE INFO &lt;device-id&gt;
1791     </p>
1792 schoenebeck 708 </blockquote><p>
1793 schoenebeck 940
1794 schoenebeck 708 </p>
1795 senoner 542 <p>Where &lt;device-id&gt; should be replaced by numerical ID
1796     of the audio output device as e.g. returned by the
1797 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.
1798 senoner 542 </p>
1799     <p>Possible Answers:
1800     </p>
1801     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1802     Each answer line begins with the information category name
1803     followed by a colon and then a space character &lt;SP&gt; and finally
1804     the info character string to that info category. As some
1805     parameters might allow multiple values, character strings are
1806     encapsulated into apostrophes ('). At the moment the following
1807     information categories are defined (independently of device):
1808     </p>
1809 schoenebeck 708 <p>
1810     </p>
1811 senoner 542 <blockquote class="text">
1812     <p>DRIVER -
1813     </p>
1814     <blockquote class="text">
1815     <p>identifier of the used audio output driver, as also
1816     returned by the
1817 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>
1818 senoner 542 command
1819     </p>
1820 schoenebeck 940 </blockquote>
1821    
1822 senoner 542
1823     <p>CHANNELS -
1824     </p>
1825     <blockquote class="text">
1826     <p>amount of audio output channels this device currently
1827     offers
1828     </p>
1829 schoenebeck 940 </blockquote>
1830    
1831 senoner 542
1832     <p>SAMPLERATE -
1833     </p>
1834     <blockquote class="text">
1835     <p>playback sample rate the device uses
1836     </p>
1837 schoenebeck 940 </blockquote>
1838    
1839 senoner 542
1840     <p>ACTIVE -
1841     </p>
1842     <blockquote class="text">
1843     <p>either true or false, if false then the audio device is
1844     inactive and doesn't output any sound, nor do the
1845     sampler channels connected to this audio device render
1846     any audio
1847     </p>
1848 schoenebeck 940 </blockquote>
1849    
1850 senoner 542
1851 schoenebeck 708 </blockquote><p>
1852 schoenebeck 940
1853 schoenebeck 708 </p>
1854 senoner 542 <p>The mentioned fields above don't have to be in particular
1855     order. The fields above are only those fields which are
1856     returned by all audio output devices. Every audio output driver
1857     might have its own, additional driver specific parameters (see
1858 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>)
1859 senoner 542 which are also returned by this command.
1860     </p>
1861     <p>Example:
1862     </p>
1863 schoenebeck 708 <p>
1864     </p>
1865 senoner 542 <blockquote class="text">
1866     <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
1867     </p>
1868     <p>S: "DRIVER: ALSA"
1869     </p>
1870     <p>&nbsp;&nbsp;&nbsp;"CHANNELS: 2"
1871     </p>
1872     <p>&nbsp;&nbsp;&nbsp;"SAMPLERATE: 44100"
1873     </p>
1874     <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
1875     </p>
1876     <p>&nbsp;&nbsp;&nbsp;"FRAGMENTS: 2"
1877     </p>
1878     <p>&nbsp;&nbsp;&nbsp;"FRAGMENTSIZE: 128"
1879     </p>
1880     <p>&nbsp;&nbsp;&nbsp;"CARD: '0,0'"
1881     </p>
1882     <p>&nbsp;&nbsp;&nbsp;"."
1883     </p>
1884 schoenebeck 708 </blockquote><p>
1885 schoenebeck 940
1886 schoenebeck 708 </p>
1887 schoenebeck 940 <a name="SET AUDIO_OUTPUT_DEVICE_PARAMETER"></a><br /><hr />
1888 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>
1889     <a name="rfc.section.6.2.10"></a><h3>6.2.10.&nbsp;
1890     Changing settings of audio output devices</h3>
1891 senoner 542
1892     <p>Use the following command to alter a specific setting of a created audio output device:
1893     </p>
1894 schoenebeck 708 <p>
1895     </p>
1896 senoner 542 <blockquote class="text">
1897     <p>SET AUDIO_OUTPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;
1898     </p>
1899 schoenebeck 708 </blockquote><p>
1900 schoenebeck 940
1901 schoenebeck 708 </p>
1902 senoner 542 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1903 schoenebeck 575 audio output device as given by the
1904 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>
1905     or <a class='info' href='#LIST AUDIO_OUTPUT_DEVICES'>"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class='info'>Getting all created audio output device list</span><span>)</span></a>
1906 schoenebeck 575 command, &lt;key&gt; by the name of the parameter to change
1907 senoner 542 and &lt;value&gt; by the new value for this parameter.
1908     </p>
1909     <p>Possible Answers:
1910     </p>
1911 schoenebeck 708 <p>
1912     </p>
1913 senoner 542 <blockquote class="text">
1914     <p>"OK" -
1915     </p>
1916     <blockquote class="text">
1917     <p>in case setting was successfully changed
1918     </p>
1919 schoenebeck 940 </blockquote>
1920    
1921 senoner 542
1922     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1923     </p>
1924     <blockquote class="text">
1925     <p>in case setting was changed successfully, but there are
1926     noteworthy issue(s) related, providing an appropriate
1927     warning code and warning message
1928     </p>
1929 schoenebeck 940 </blockquote>
1930    
1931 senoner 542
1932     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1933     </p>
1934     <blockquote class="text">
1935     <p>in case it failed, providing an appropriate error code and
1936     error message
1937     </p>
1938 schoenebeck 940 </blockquote>
1939    
1940 senoner 542
1941 schoenebeck 708 </blockquote><p>
1942 schoenebeck 940
1943 schoenebeck 708 </p>
1944 senoner 542 <p>Example:
1945     </p>
1946 schoenebeck 708 <p>
1947     </p>
1948 senoner 542 <blockquote class="text">
1949     <p>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"
1950     </p>
1951     <p>S: "OK"
1952     </p>
1953 schoenebeck 708 </blockquote><p>
1954 schoenebeck 940
1955 schoenebeck 708 </p>
1956 schoenebeck 940 <a name="GET AUDIO_OUTPUT_CHANNEL INFO"></a><br /><hr />
1957 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>
1958     <a name="rfc.section.6.2.11"></a><h3>6.2.11.&nbsp;
1959     Getting information about an audio channel</h3>
1960 senoner 542
1961     <p>Use the following command to get information about an audio channel:
1962     </p>
1963 schoenebeck 708 <p>
1964     </p>
1965 senoner 542 <blockquote class="text">
1966     <p>GET AUDIO_OUTPUT_CHANNEL INFO &lt;device-id&gt; &lt;audio-chan&gt;
1967     </p>
1968 schoenebeck 708 </blockquote><p>
1969 schoenebeck 940
1970 schoenebeck 708 </p>
1971 schoenebeck 575 <p>Where &lt;device-id&gt; is the numerical ID of the audio output device as given by the
1972 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>
1973     or <a class='info' href='#LIST AUDIO_OUTPUT_DEVICES'>"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class='info'>Getting all created audio output device list</span><span>)</span></a>
1974 schoenebeck 575 command and &lt;audio-chan&gt; the audio channel number.
1975 senoner 542 </p>
1976     <p>Possible Answers:
1977     </p>
1978 schoenebeck 708 <p>
1979     </p>
1980 senoner 542 <blockquote class="text">
1981     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1982     Each answer line begins with the information category name
1983     followed by a colon and then a space character &lt;SP&gt; and finally
1984     the info character string to that info category. At the moment
1985     the following information categories are defined:
1986     </p>
1987 schoenebeck 708 <p>
1988     </p>
1989 senoner 542 <blockquote class="text">
1990     <p>NAME -
1991     </p>
1992     <blockquote class="text">
1993     <p>arbitrary character string naming the channel, which
1994     doesn't have to be unique (always returned by all audio channels)
1995     </p>
1996 schoenebeck 940 </blockquote>
1997    
1998 senoner 542
1999     <p>IS_MIX_CHANNEL -
2000     </p>
2001     <blockquote class="text">
2002     <p>either true or false, a mix-channel is not a real,
2003     independent audio channel, but a virtual channel which
2004     is mixed to another real channel, this mechanism is
2005     needed for sampler engines which need more audio
2006     channels than the used audio system might be able to offer
2007     (always returned by all audio channels)
2008     </p>
2009 schoenebeck 940 </blockquote>
2010    
2011 senoner 542
2012     <p>MIX_CHANNEL_DESTINATION -
2013     </p>
2014     <blockquote class="text">
2015     <p>numerical ID (positive integer including 0)
2016     which reflects the real audio channel (of the same audio
2017     output device) this mix channel refers to, means where
2018     the audio signal actually will be routed / added to
2019     (only returned in case the audio channel is mix channel)
2020     </p>
2021 schoenebeck 940 </blockquote>
2022    
2023 senoner 542
2024 schoenebeck 940 </blockquote>
2025    
2026 senoner 542
2027 schoenebeck 708 </blockquote><p>
2028 schoenebeck 940
2029 schoenebeck 708 </p>
2030 senoner 542 <p>The mentioned fields above don't have to be in particular
2031     order. The fields above are only those fields which are
2032     generally returned for the described cases by all audio
2033     channels regardless of the audio driver. Every audio channel
2034     might have its own, additional driver and channel specific
2035     parameters.
2036     </p>
2037     <p>Examples:
2038     </p>
2039 schoenebeck 708 <p>
2040     </p>
2041 senoner 542 <blockquote class="text">
2042     <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 0"
2043     </p>
2044     <p>S: "NAME: studio monitor left"
2045     </p>
2046     <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
2047     </p>
2048     <p>&nbsp;&nbsp;&nbsp;"."
2049     </p>
2050 schoenebeck 708 </blockquote><p>
2051 schoenebeck 940
2052 schoenebeck 708 </p>
2053     <p>
2054     </p>
2055 senoner 542 <blockquote class="text">
2056     <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 1"
2057     </p>
2058     <p>S: "NAME: studio monitor right"
2059     </p>
2060     <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
2061     </p>
2062     <p>&nbsp;&nbsp;&nbsp;"."
2063     </p>
2064 schoenebeck 708 </blockquote><p>
2065 schoenebeck 940
2066 schoenebeck 708 </p>
2067     <p>
2068     </p>
2069 senoner 542 <blockquote class="text">
2070     <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"
2071     </p>
2072     <p>S: "NAME: studio monitor left"
2073     </p>
2074     <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: true"
2075     </p>
2076     <p>&nbsp;&nbsp;&nbsp;"MIX_CHANNEL_DESTINATION: 1"
2077     </p>
2078     <p>&nbsp;&nbsp;&nbsp;"."
2079     </p>
2080 schoenebeck 708 </blockquote><p>
2081 schoenebeck 940
2082 schoenebeck 708 </p>
2083     <p>
2084     </p>
2085 senoner 542 <blockquote class="text">
2086     <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"
2087     </p>
2088     <p>S: "NAME: 'ardour (left)'"
2089     </p>
2090     <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
2091     </p>
2092     <p>&nbsp;&nbsp;&nbsp;"JACK_BINDINGS: 'ardour:0'"
2093     </p>
2094     <p>&nbsp;&nbsp;&nbsp;"."
2095     </p>
2096 schoenebeck 708 </blockquote><p>
2097 schoenebeck 940
2098 schoenebeck 708 </p>
2099 schoenebeck 940 <a name="GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO"></a><br /><hr />
2100 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>
2101     <a name="rfc.section.6.2.12"></a><h3>6.2.12.&nbsp;
2102     Getting information about specific audio channel parameter</h3>
2103 senoner 542
2104     <p>Use the following command to get detailed information about specific audio channel parameter:
2105     </p>
2106 schoenebeck 708 <p>
2107     </p>
2108 senoner 542 <blockquote class="text">
2109     <p>GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO &lt;dev-id&gt; &lt;chan&gt; &lt;param&gt;
2110     </p>
2111 schoenebeck 708 </blockquote><p>
2112 schoenebeck 940
2113 schoenebeck 708 </p>
2114 schoenebeck 575 <p>Where &lt;dev-id&gt; is the numerical ID of the audio output device as returned by the
2115 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>
2116     or <a class='info' href='#LIST AUDIO_OUTPUT_DEVICES'>"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class='info'>Getting all created audio output device list</span><span>)</span></a>
2117 senoner 542 command, &lt;chan&gt; the audio channel number
2118     and &lt;param&gt; a specific channel parameter name for which information should
2119 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).
2120 senoner 542 </p>
2121     <p>Possible Answers:
2122     </p>
2123 schoenebeck 708 <p>
2124     </p>
2125 senoner 542 <blockquote class="text">
2126     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2127     Each answer line begins with the information category name
2128     followed by a colon and then a space character &lt;SP&gt; and finally
2129     the info character string to that info category. There are
2130     information which is always returned, independently of the
2131     given channel parameter and there is optional information
2132     which is only shown dependently to the given audio channel. At
2133     the moment the following information categories are defined:
2134     </p>
2135 schoenebeck 708 <p>
2136     </p>
2137 senoner 542 <blockquote class="text">
2138     <p>TYPE -
2139     </p>
2140     <blockquote class="text">
2141     <p>either "BOOL" for boolean value(s) or "INT" for integer
2142     value(s) or "FLOAT" for dotted number(s) or "STRING" for
2143     character string(s)
2144     (always returned)
2145     </p>
2146 schoenebeck 940 </blockquote>
2147    
2148 senoner 542
2149     <p>DESCRIPTION -
2150     </p>
2151     <blockquote class="text">
2152     <p>arbitrary text describing the purpose of the parameter (always returned)
2153     </p>
2154 schoenebeck 940 </blockquote>
2155    
2156 senoner 542
2157     <p>FIX -
2158     </p>
2159     <blockquote class="text">
2160     <p>either true or false, if true then this parameter is
2161     read only, thus cannot be altered
2162     (always returned)
2163     </p>
2164 schoenebeck 940 </blockquote>
2165    
2166 senoner 542
2167     <p>MULTIPLICITY -
2168     </p>
2169     <blockquote class="text">
2170     <p>either true or false, defines if this parameter allows
2171     only one value or a list of values, where true means
2172     multiple values and false only a single value allowed
2173     (always returned)
2174     </p>
2175 schoenebeck 940 </blockquote>
2176    
2177 senoner 542
2178     <p>RANGE_MIN -
2179     </p>
2180     <blockquote class="text">
2181     <p>defines lower limit of the allowed value range for this
2182     parameter, can be an integer value as well as a dotted
2183     number, usually used in conjunction with 'RANGE_MAX',
2184     but may also appear without
2185     (optionally returned, dependent to driver and channel
2186     parameter)
2187     </p>
2188 schoenebeck 940 </blockquote>
2189    
2190 senoner 542
2191     <p>RANGE_MAX -
2192     </p>
2193     <blockquote class="text">
2194     <p>defines upper limit of the allowed value range for this
2195     parameter, can be an integer value as well as a dotted
2196     number, usually used in conjunction with 'RANGE_MIN',
2197     but may also appear without
2198     (optionally returned, dependent to driver and channel
2199     parameter)
2200     </p>
2201 schoenebeck 940 </blockquote>
2202    
2203 senoner 542
2204     <p>POSSIBILITIES -
2205     </p>
2206     <blockquote class="text">
2207     <p>comma separated list of possible values for this
2208     parameter, character strings are encapsulated into
2209     apostrophes
2210     (optionally returned, dependent to driver and channel
2211     parameter)
2212     </p>
2213 schoenebeck 940 </blockquote>
2214    
2215 senoner 542
2216 schoenebeck 940 </blockquote>
2217    
2218 senoner 542
2219     <p>The mentioned fields above don't have to be in particular order.
2220     </p>
2221 schoenebeck 708 </blockquote><p>
2222 schoenebeck 940
2223 schoenebeck 708 </p>
2224 senoner 542 <p>Example:
2225     </p>
2226 schoenebeck 708 <p>
2227     </p>
2228 senoner 542 <blockquote class="text">
2229     <p>C: "GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO 1 0 JACK_BINDINGS"
2230     </p>
2231     <p>S: "DESCRIPTION: bindings to other JACK clients"
2232     </p>
2233     <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
2234     </p>
2235     <p>&nbsp;&nbsp;&nbsp;"FIX: false"
2236     </p>
2237     <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"
2238     </p>
2239     <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"
2240     </p>
2241     <p>&nbsp;&nbsp;&nbsp;"."
2242     </p>
2243 schoenebeck 708 </blockquote><p>
2244 schoenebeck 940
2245 schoenebeck 708 </p>
2246 schoenebeck 940 <a name="SET AUDIO_OUTPUT_CHANNEL_PARAMETER"></a><br /><hr />
2247 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>
2248     <a name="rfc.section.6.2.13"></a><h3>6.2.13.&nbsp;
2249     Changing settings of audio output channels</h3>
2250 senoner 542
2251     <p>Use the following command to alter a specific setting of an audio output channel:
2252     </p>
2253 schoenebeck 708 <p>
2254     </p>
2255 senoner 542 <blockquote class="text">
2256     <p>SET AUDIO_OUTPUT_CHANNEL_PARAMETER &lt;dev-id&gt; &lt;chn&gt; &lt;key&gt;=&lt;value&gt;
2257     </p>
2258 schoenebeck 708 </blockquote><p>
2259 schoenebeck 940
2260 schoenebeck 708 </p>
2261 schoenebeck 575 <p>Where &lt;dev-id&gt; should be replaced by the numerical ID of the audio output device as returned by the
2262 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>
2263     or <a class='info' href='#LIST AUDIO_OUTPUT_DEVICES'>"LIST AUDIO_OUTPUT_DEVICES"<span> (</span><span class='info'>Getting all created audio output device list</span><span>)</span></a>
2264 schoenebeck 575 command, &lt;chn&gt; by the audio channel number, &lt;key&gt; by the name of the
2265 senoner 542 parameter to change and &lt;value&gt; by the new value for this parameter.
2266     </p>
2267     <p>Possible Answers:
2268     </p>
2269 schoenebeck 708 <p>
2270     </p>
2271 senoner 542 <blockquote class="text">
2272     <p>"OK" -
2273     </p>
2274     <blockquote class="text">
2275     <p>in case setting was successfully changed
2276     </p>
2277 schoenebeck 940 </blockquote>
2278    
2279 senoner 542
2280     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2281     </p>
2282     <blockquote class="text">
2283     <p>in case setting was changed successfully, but there are
2284     noteworthy issue(s) related, providing an appropriate
2285     warning code and warning message
2286     </p>
2287 schoenebeck 940 </blockquote>
2288    
2289 senoner 542
2290     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2291     </p>
2292     <blockquote class="text">
2293     <p>in case it failed, providing an appropriate error code and
2294     error message
2295     </p>
2296 schoenebeck 940 </blockquote>
2297    
2298 senoner 542
2299 schoenebeck 708 </blockquote><p>
2300 schoenebeck 940
2301 schoenebeck 708 </p>
2302 senoner 542 <p>Example:
2303     </p>
2304 schoenebeck 708 <p>
2305     </p>
2306 senoner 542 <blockquote class="text">
2307     <p>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"
2308     </p>
2309     <p>S: "OK"
2310     </p>
2311 schoenebeck 708 </blockquote><p>
2312 schoenebeck 940
2313 schoenebeck 708 </p>
2314     <p>
2315     </p>
2316 senoner 542 <blockquote class="text">
2317     <p>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"
2318     </p>
2319     <p>S: "OK"
2320     </p>
2321 schoenebeck 708 </blockquote><p>
2322 schoenebeck 940
2323 schoenebeck 708 </p>
2324 schoenebeck 940 <a name="anchor10"></a><br /><hr />
2325 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>
2326     <a name="rfc.section.6.3"></a><h3>6.3.&nbsp;
2327     Configuring MIDI input drivers</h3>
2328 senoner 542
2329     <p>Instances of drivers in LinuxSampler are called devices. You can use
2330     multiple MIDI devices simultaneously, e.g. to use MIDI over ethernet as
2331     MIDI input on one sampler channel and ALSA as MIDI input on another sampler
2332     channel. For particular MIDI input systems it's also possible to create
2333     several devices of the same MIDI input type. This chapter describes all
2334     commands to configure LinuxSampler's MIDI input devices and their parameters.
2335     </p>
2336     <p>Instead of defining commands and parameters for each driver individually,
2337     all possible parameters, their meanings and possible values have to be obtained
2338     at runtime. This makes the protocol a bit abstract, but has the advantage, that
2339     front-ends can be written independently of what drivers are currently implemented
2340     and what parameters these drivers are actually offering. This means front-ends can
2341     even handle drivers which are implemented somewhere in future without modifying
2342     the front-end at all.
2343     </p>
2344     <p>Commands for configuring MIDI input devices are pretty much the same as the
2345     commands for configuring audio output drivers, already described in the last
2346     chapter.
2347     </p>
2348     <p>Note: examples in this chapter showing particular parameters of drivers are
2349     not meant as specification of the drivers' parameters. Driver implementations in
2350     LinuxSampler might have complete different parameter names and meanings than shown
2351     in these examples or might change in future, so these examples are only meant for
2352     showing how to retrieve what parameters drivers are offering, how to retrieve their
2353     possible values, etc.
2354     </p>
2355 schoenebeck 940 <a name="GET AVAILABLE_MIDI_INPUT_DRIVERS"></a><br /><hr />
2356 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>
2357     <a name="rfc.section.6.3.1"></a><h3>6.3.1.&nbsp;
2358     Getting amount of available MIDI input drivers</h3>
2359 senoner 542
2360     <p>Use the following command to get the number of
2361     MIDI input drivers currently available for the
2362     LinuxSampler instance:
2363     </p>
2364 schoenebeck 708 <p>
2365     </p>
2366 senoner 542 <blockquote class="text">
2367     <p>GET AVAILABLE_MIDI_INPUT_DRIVERS
2368     </p>
2369 schoenebeck 708 </blockquote><p>
2370 schoenebeck 940
2371 schoenebeck 708 </p>
2372 senoner 542 <p>Possible Answers:
2373     </p>
2374 schoenebeck 708 <p>
2375     </p>
2376 senoner 542 <blockquote class="text">
2377     <p>LinuxSampler will answer by sending the
2378     number of available MIDI input drivers.
2379     </p>
2380 schoenebeck 708 </blockquote><p>
2381 schoenebeck 940
2382 schoenebeck 708 </p>
2383 senoner 542 <p>Example:
2384     </p>
2385 schoenebeck 708 <p>
2386     </p>
2387 senoner 542 <blockquote class="text">
2388     <p>C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"
2389     </p>
2390     <p>S: "2"
2391     </p>
2392 schoenebeck 708 </blockquote><p>
2393 schoenebeck 940
2394 schoenebeck 708 </p>
2395 schoenebeck 940 <a name="LIST AVAILABLE_MIDI_INPUT_DRIVERS"></a><br /><hr />
2396 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>
2397     <a name="rfc.section.6.3.2"></a><h3>6.3.2.&nbsp;
2398     Getting all available MIDI input drivers</h3>
2399 senoner 542
2400     <p>Use the following command to list all MIDI input drivers currently available
2401     for the LinuxSampler instance:
2402     </p>
2403 schoenebeck 708 <p>
2404     </p>
2405 senoner 542 <blockquote class="text">
2406     <p>LIST AVAILABLE_MIDI_INPUT_DRIVERS
2407     </p>
2408 schoenebeck 708 </blockquote><p>
2409 schoenebeck 940
2410 schoenebeck 708 </p>
2411 senoner 542 <p>Possible Answers:
2412     </p>
2413 schoenebeck 708 <p>
2414     </p>
2415 senoner 542 <blockquote class="text">
2416     <p>LinuxSampler will answer by sending comma separated character
2417     strings, each symbolizing a MIDI input driver.
2418     </p>
2419 schoenebeck 708 </blockquote><p>
2420 schoenebeck 940
2421 schoenebeck 708 </p>
2422 senoner 542 <p>Example:
2423     </p>
2424 schoenebeck 708 <p>
2425     </p>
2426 senoner 542 <blockquote class="text">
2427     <p>C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
2428     </p>
2429     <p>S: "ALSA,JACK"
2430     </p>
2431 schoenebeck 708 </blockquote><p>
2432 schoenebeck 940
2433 schoenebeck 708 </p>
2434 schoenebeck 940 <a name="GET MIDI_INPUT_DRIVER INFO"></a><br /><hr />
2435 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>
2436     <a name="rfc.section.6.3.3"></a><h3>6.3.3.&nbsp;
2437     Getting information about a specific MIDI input driver</h3>
2438 senoner 542
2439     <p>Use the following command to get detailed information about a specific MIDI input driver:
2440     </p>
2441 schoenebeck 708 <p>
2442     </p>
2443 senoner 542 <blockquote class="text">
2444     <p>GET MIDI_INPUT_DRIVER INFO &lt;midi-input-driver&gt;
2445     </p>
2446 schoenebeck 708 </blockquote><p>
2447 schoenebeck 940
2448 schoenebeck 708 </p>
2449 schoenebeck 575 <p>Where &lt;midi-input-driver&gt; is the name of the MIDI input driver as returned
2450 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.
2451 senoner 542 </p>
2452     <p>Possible Answers:
2453     </p>
2454 schoenebeck 708 <p>
2455     </p>
2456 senoner 542 <blockquote class="text">
2457     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2458     Each answer line begins with the information category name
2459     followed by a colon and then a space character &lt;SP&gt; and finally
2460     the info character string to that info category. At the moment
2461     the following information categories are defined:
2462     </p>
2463 schoenebeck 708 <p>
2464     </p>
2465 senoner 542 <blockquote class="text">
2466     <p>DESCRIPTION -
2467     </p>
2468     <blockquote class="text">
2469     <p>arbitrary description text about the MIDI input driver
2470     </p>
2471 schoenebeck 940 </blockquote>
2472    
2473 senoner 542
2474     <p>VERSION -
2475     </p>
2476     <blockquote class="text">
2477     <p>arbitrary character string regarding the driver's version
2478     </p>
2479 schoenebeck 940 </blockquote>
2480    
2481 senoner 542
2482     <p>PARAMETERS -
2483     </p>
2484     <blockquote class="text">
2485     <p>comma separated list of all parameters available for the given MIDI input driver
2486     </p>
2487 schoenebeck 940 </blockquote>
2488    
2489 senoner 542
2490 schoenebeck 940 </blockquote>
2491    
2492 senoner 542
2493     <p>The mentioned fields above don't have to be in particular order.
2494     </p>
2495 schoenebeck 708 </blockquote><p>
2496 schoenebeck 940
2497 schoenebeck 708 </p>
2498 senoner 542 <p>Example:
2499     </p>
2500 schoenebeck 708 <p>
2501     </p>
2502 senoner 542 <blockquote class="text">
2503     <p>C: "GET MIDI_INPUT_DRIVER INFO ALSA"
2504     </p>
2505     <p>S: "DESCRIPTION: Advanced Linux Sound Architecture"
2506     </p>
2507     <p>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"
2508     </p>
2509     <p>&nbsp;&nbsp;&nbsp;"PARAMETERS: DRIVER,ACTIVE"
2510     </p>
2511     <p>&nbsp;&nbsp;&nbsp;"."
2512     </p>
2513 schoenebeck 708 </blockquote><p>
2514 schoenebeck 940
2515 schoenebeck 708 </p>
2516 schoenebeck 940 <a name="GET MIDI_INPUT_DRIVER_PARAMETER INFO"></a><br /><hr />
2517 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>
2518     <a name="rfc.section.6.3.4"></a><h3>6.3.4.&nbsp;
2519     Getting information about specific MIDI input driver parameter</h3>
2520 senoner 542
2521     <p>Use the following command to get detailed information about a specific parameter of a specific MIDI input driver:
2522     </p>
2523 schoenebeck 708 <p>
2524     </p>
2525 senoner 542 <blockquote class="text">
2526     <p>GET MIDI_INPUT_DRIVER_PARAMETER INFO &lt;midit&gt; &lt;param&gt; [&lt;deplist&gt;]
2527     </p>
2528 schoenebeck 708 </blockquote><p>
2529 schoenebeck 940
2530 schoenebeck 708 </p>
2531 schoenebeck 561 <p>Where &lt;midit&gt; is the name of the MIDI input driver as returned
2532 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
2533 senoner 542 parameter name for which information should be obtained (as returned by the
2534 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
2535 senoner 542 of parameters on which the sought parameter &lt;param&gt; depends on,
2536     &lt;deplist&gt; is a key-value pair list in form of "key1=val1 key2=val2 ...",
2537     where character string values are encapsulated into apostrophes ('). Arguments
2538     given with &lt;deplist&gt; which are not dependency parameters of &lt;param&gt;
2539     will be ignored, means the front-end application can simply put all parameters
2540     in &lt;deplist&gt; with the values selected by the user.
2541     </p>
2542     <p>Possible Answers:
2543     </p>
2544     <p>LinuxSampler will answer by sending a &lt;CRLF> separated list.
2545     Each answer line begins with the information category name
2546     followed by a colon and then a space character &lt;SP> and finally
2547     the info character string to that info category. There is
2548     information which is always returned, independent of the
2549     given driver parameter and there is optional information
2550     which is only shown dependent to given driver parameter. At
2551     the moment the following information categories are defined:
2552     </p>
2553 schoenebeck 708 <p>
2554     </p>
2555 senoner 542 <blockquote class="text">
2556     <p>TYPE -
2557     </p>
2558     <blockquote class="text">
2559     <p>either "BOOL" for boolean value(s) or "INT" for integer
2560     value(s) or "FLOAT" for dotted number(s) or "STRING" for
2561     character string(s)
2562     (always returned, no matter which driver parameter)
2563     </p>
2564 schoenebeck 940 </blockquote>
2565    
2566 senoner 542
2567     <p>DESCRIPTION -
2568     </p>
2569     <blockquote class="text">
2570     <p>arbitrary text describing the purpose of the parameter
2571     (always returned, no matter which driver parameter)
2572     </p>
2573 schoenebeck 940 </blockquote>
2574    
2575 senoner 542
2576     <p>MANDATORY -
2577     </p>
2578     <blockquote class="text">
2579     <p>either true or false, defines if this parameter must be
2580     given when the device is to be created with the
2581 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
2582 senoner 542 (always returned, no matter which driver parameter)
2583     </p>
2584 schoenebeck 940 </blockquote>
2585    
2586 senoner 542
2587     <p>FIX -
2588     </p>
2589     <blockquote class="text">
2590     <p>either true or false, if false then this parameter can
2591     be changed at any time, once the device is created by
2592 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
2593 senoner 542 (always returned, no matter which driver parameter)
2594     </p>
2595 schoenebeck 940 </blockquote>
2596    
2597 senoner 542
2598     <p>MULTIPLICITY -
2599     </p>
2600     <blockquote class="text">
2601     <p>either true or false, defines if this parameter allows
2602     only one value or a list of values, where true means
2603     multiple values and false only a single value allowed
2604     (always returned, no matter which driver parameter)
2605     </p>
2606 schoenebeck 940 </blockquote>
2607    
2608 senoner 542
2609     <p>DEPENDS -
2610     </p>
2611     <blockquote class="text">
2612 schoenebeck 561 <p>comma separated list of parameters this parameter depends
2613 senoner 542 on, means the values for fields 'DEFAULT', 'RANGE_MIN',
2614     'RANGE_MAX' and 'POSSIBILITIES' might depend on these
2615     listed parameters, for example assuming that an audio
2616     driver (like the ALSA driver) offers parameters 'card'
2617     and 'samplerate' then parameter 'samplerate' would
2618     depend on 'card' because the possible values for
2619     'samplerate' depends on the sound card which can be
2620     chosen by the 'card' parameter
2621     (optionally returned, dependent to driver parameter)
2622     </p>
2623 schoenebeck 940 </blockquote>
2624    
2625 senoner 542
2626     <p>DEFAULT -
2627     </p>
2628     <blockquote class="text">
2629     <p>reflects the default value for this parameter which is
2630     used when the device is created and not explicitly
2631 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,
2632 senoner 542 in case of MULTIPLCITY=true, this is a comma separated
2633     list, that's why character strings are encapsulated into
2634     apostrophes (')
2635     (optionally returned, dependent to driver parameter)
2636     </p>
2637 schoenebeck 940 </blockquote>
2638    
2639 senoner 542
2640     <p>RANGE_MIN -
2641     </p>
2642     <blockquote class="text">
2643     <p>defines lower limit of the allowed value range for this
2644     parameter, can be an integer value as well as a dotted
2645     number, this parameter is often used in conjunction
2646     with RANGE_MAX, but may also appear without
2647     (optionally returned, dependent to driver parameter)
2648     </p>
2649 schoenebeck 940 </blockquote>
2650    
2651 senoner 542
2652     <p>RANGE_MAX -
2653     </p>
2654     <blockquote class="text">
2655     <p>defines upper limit of the allowed value range for this
2656     parameter, can be an integer value as well as a dotted
2657     number, this parameter is often used in conjunction with
2658     RANGE_MIN, but may also appear without
2659     (optionally returned, dependent to driver parameter)
2660     </p>
2661 schoenebeck 940 </blockquote>
2662    
2663 senoner 542
2664     <p>POSSIBILITIES -
2665     </p>
2666     <blockquote class="text">
2667     <p>comma separated list of possible values for this
2668     parameter, character strings are encapsulated into
2669     apostrophes
2670     (optionally returned, dependent to driver parameter)
2671     </p>
2672 schoenebeck 940 </blockquote>
2673    
2674 senoner 542
2675 schoenebeck 708 </blockquote><p>
2676 schoenebeck 940
2677 schoenebeck 708 </p>
2678 senoner 542 <p>The mentioned fields above don't have to be in particular order.
2679     </p>
2680     <p>Example:
2681     </p>
2682 schoenebeck 708 <p>
2683     </p>
2684 senoner 542 <blockquote class="text">
2685     <p>C: "GET MIDI_INPUT_DRIVER_PARAMETER INFO ALSA ACTIVE"
2686     </p>
2687     <p>S: "DESCRIPTION: Whether device is enabled"
2688     </p>
2689     <p>&nbsp;&nbsp;&nbsp;"TYPE: BOOL"
2690     </p>
2691     <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
2692     </p>
2693     <p>&nbsp;&nbsp;&nbsp;"FIX: false"
2694     </p>
2695     <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
2696     </p>
2697     <p>&nbsp;&nbsp;&nbsp;"DEFAULT: true"
2698     </p>
2699     <p>&nbsp;&nbsp;&nbsp;"."
2700     </p>
2701 schoenebeck 708 </blockquote><p>
2702 schoenebeck 940
2703 schoenebeck 708 </p>
2704 schoenebeck 940 <a name="CREATE MIDI_INPUT_DEVICE"></a><br /><hr />
2705 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>
2706     <a name="rfc.section.6.3.5"></a><h3>6.3.5.&nbsp;
2707     Creating a MIDI input device</h3>
2708 senoner 542
2709     <p>Use the following command to create a new MIDI input device for the desired MIDI input system:
2710     </p>
2711 schoenebeck 708 <p>
2712     </p>
2713 senoner 542 <blockquote class="text">
2714     <p>CREATE MIDI_INPUT_DEVICE &lt;midi-input-driver&gt; [&lt;param-list&gt;]
2715     </p>
2716 schoenebeck 708 </blockquote><p>
2717 schoenebeck 940
2718 schoenebeck 708 </p>
2719 schoenebeck 575 <p>Where &lt;midi-input-driver&gt; should be replaced by the desired MIDI input system as returned
2720 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
2721 senoner 542 optional list of driver specific parameters in form of "key1=val1 key2=val2 ...", where
2722     character string values should be encapsulated into apostrophes (').
2723     Note that there might be drivers which require parameter(s) to be
2724     given with this command. Use the previously described commands in
2725     this chapter to get that information.
2726     </p>
2727     <p>Possible Answers:
2728     </p>
2729 schoenebeck 708 <p>
2730     </p>
2731 senoner 542 <blockquote class="text">
2732     <p>"OK[&lt;device-id&gt;]" -
2733     </p>
2734     <blockquote class="text">
2735     <p>in case the device was successfully created, where
2736     &lt;device-id&gt; is the numerical ID of the new device
2737     </p>
2738 schoenebeck 940 </blockquote>
2739    
2740 senoner 542
2741     <p>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2742     </p>
2743     <blockquote class="text">
2744     <p>in case the driver was loaded successfully, where
2745     &lt;device-id&gt; is the numerical ID of the new device, but
2746     there are noteworthy issue(s) related, providing an
2747     appropriate warning code and warning message
2748     </p>
2749 schoenebeck 940 </blockquote>
2750    
2751 senoner 542
2752     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2753     </p>
2754     <blockquote class="text">
2755     <p>in case it failed, providing an appropriate error code and error message
2756     </p>
2757 schoenebeck 940 </blockquote>
2758    
2759 senoner 542
2760 schoenebeck 708 </blockquote><p>
2761 schoenebeck 940
2762 schoenebeck 708 </p>
2763 senoner 542 <p>Example:
2764     </p>
2765 schoenebeck 708 <p>
2766     </p>
2767 senoner 542 <blockquote class="text">
2768     <p>C: "CREATE MIDI_INPUT_DEVICE ALSA"
2769     </p>
2770     <p>S: "OK[0]"
2771     </p>
2772 schoenebeck 708 </blockquote><p>
2773 schoenebeck 940
2774 schoenebeck 708 </p>
2775 schoenebeck 940 <a name="DESTROY MIDI_INPUT_DEVICE"></a><br /><hr />
2776 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>
2777     <a name="rfc.section.6.3.6"></a><h3>6.3.6.&nbsp;
2778     Destroying a MIDI input device</h3>
2779 senoner 542
2780     <p>Use the following command to destroy a created MIDI input device:
2781     </p>
2782 schoenebeck 708 <p>
2783     </p>
2784 senoner 542 <blockquote class="text">
2785     <p>DESTROY MIDI_INPUT_DEVICE &lt;device-id&gt;
2786     </p>
2787 schoenebeck 708 </blockquote><p>
2788 schoenebeck 940
2789 schoenebeck 708 </p>
2790 schoenebeck 575 <p>Where &lt;device-id&gt; should be replaced by the device's numerical ID as returned by the
2791 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>
2792     or <a class='info' href='#LIST MIDI_INPUT_DEVICES'>"LIST MIDI_INPUT_DEVICES"<span> (</span><span class='info'>Getting all created MIDI input device list</span><span>)</span></a>
2793 schoenebeck 575 command.
2794 senoner 542 </p>
2795     <p>Possible Answers:
2796     </p>
2797 schoenebeck 708 <p>
2798     </p>
2799 senoner 542 <blockquote class="text">
2800     <p>"OK" -
2801     </p>
2802     <blockquote class="text">
2803     <p>in case the device was successfully destroyed
2804     </p>
2805 schoenebeck 940 </blockquote>
2806    
2807 senoner 542
2808     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2809     </p>
2810     <blockquote class="text">
2811     <p>in case the device was destroyed, but there are noteworthy
2812     issue(s) related, providing an appropriate warning code and
2813     warning message
2814     </p>
2815 schoenebeck 940 </blockquote>
2816    
2817 senoner 542
2818     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2819     </p>
2820     <blockquote class="text">
2821     <p>in case it failed, providing an appropriate error code and error message
2822     </p>
2823 schoenebeck 940 </blockquote>
2824    
2825 senoner 542
2826 schoenebeck 708 </blockquote><p>
2827 schoenebeck 940
2828 schoenebeck 708 </p>
2829 senoner 542 <p>Example:
2830     </p>
2831 schoenebeck 708 <p>
2832     </p>
2833 senoner 542 <blockquote class="text">
2834     <p>C: "DESTROY MIDI_INPUT_DEVICE 0"
2835     </p>
2836     <p>S: "OK"
2837     </p>
2838 schoenebeck 708 </blockquote><p>
2839 schoenebeck 940
2840 schoenebeck 708 </p>
2841 schoenebeck 940 <a name="GET MIDI_INPUT_DEVICES"></a><br /><hr />
2842 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>
2843     <a name="rfc.section.6.3.7"></a><h3>6.3.7.&nbsp;
2844     Getting all created MIDI input device count</h3>
2845 senoner 542
2846     <p>Use the following command to count all created MIDI input devices:
2847     </p>
2848 schoenebeck 708 <p>
2849     </p>
2850 senoner 542 <blockquote class="text">
2851     <p>GET MIDI_INPUT_DEVICES
2852     </p>
2853 schoenebeck 708 </blockquote><p>
2854 schoenebeck 940
2855 schoenebeck 708 </p>
2856 senoner 542 <p>Possible Answers:
2857     </p>
2858 schoenebeck 708 <p>
2859     </p>
2860 senoner 542 <blockquote class="text">
2861     <p>LinuxSampler will answer by sending the current number of all
2862     MIDI input devices.
2863     </p>
2864 schoenebeck 708 </blockquote><p>
2865 schoenebeck 940
2866 schoenebeck 708 </p>
2867 senoner 542 <p>Example:
2868     </p>
2869 schoenebeck 708 <p>
2870     </p>
2871 senoner 542 <blockquote class="text">
2872     <p>C: "GET MIDI_INPUT_DEVICES"
2873     </p>
2874     <p>S: "3"
2875     </p>
2876 schoenebeck 708 </blockquote><p>
2877 schoenebeck 940
2878 schoenebeck 708 </p>
2879 schoenebeck 940 <a name="LIST MIDI_INPUT_DEVICES"></a><br /><hr />
2880 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>
2881     <a name="rfc.section.6.3.8"></a><h3>6.3.8.&nbsp;
2882     Getting all created MIDI input device list</h3>
2883 senoner 542
2884     <p>Use the following command to list all created MIDI input devices:
2885     </p>
2886 schoenebeck 708 <p>
2887     </p>
2888 senoner 542 <blockquote class="text">
2889     <p>LIST MIDI_INPUT_DEVICES
2890     </p>
2891 schoenebeck 708 </blockquote><p>
2892 schoenebeck 940
2893 schoenebeck 708 </p>
2894 senoner 542 <p>Possible Answers:
2895     </p>
2896 schoenebeck 708 <p>
2897     </p>
2898 senoner 542 <blockquote class="text">
2899     <p>LinuxSampler will answer by sending a comma separated list
2900     with the numerical Ids of all created MIDI input devices.
2901     </p>
2902 schoenebeck 708 </blockquote><p>
2903 schoenebeck 940
2904 schoenebeck 708 </p>
2905 senoner 542 <p>Examples:
2906     </p>
2907 schoenebeck 708 <p>
2908     </p>
2909 senoner 542 <blockquote class="text">
2910     <p>C: "LIST MIDI_INPUT_DEVICES"
2911     </p>
2912     <p>S: "0,1,2"
2913     </p>
2914 schoenebeck 708 </blockquote><p>
2915 schoenebeck 940
2916 schoenebeck 708 </p>
2917     <p>
2918     </p>
2919 senoner 542 <blockquote class="text">
2920     <p>C: "LIST MIDI_INPUT_DEVICES"
2921     </p>
2922     <p>S: "1,3"
2923     </p>
2924 schoenebeck 708 </blockquote><p>
2925 schoenebeck 940
2926 schoenebeck 708 </p>
2927 schoenebeck 940 <a name="GET MIDI_INPUT_DEVICE INFO"></a><br /><hr />
2928 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>
2929     <a name="rfc.section.6.3.9"></a><h3>6.3.9.&nbsp;
2930     Getting current settings of a MIDI input device</h3>
2931 senoner 542
2932     <p>Use the following command to get current settings of a specific, created MIDI input device:
2933     </p>
2934 schoenebeck 708 <p>
2935     </p>
2936 senoner 542 <blockquote class="text">
2937     <p>GET MIDI_INPUT_DEVICE INFO &lt;device-id&gt;
2938     </p>
2939 schoenebeck 708 </blockquote><p>
2940 schoenebeck 940
2941 schoenebeck 708 </p>
2942 schoenebeck 575 <p>Where &lt;device-id&gt; is the numerical ID of the MIDI input device as returned by the
2943 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>
2944     or <a class='info' href='#LIST MIDI_INPUT_DEVICES'>"LIST MIDI_INPUT_DEVICES"<span> (</span><span class='info'>Getting all created MIDI input device list</span><span>)</span></a>
2945 schoenebeck 575 command.
2946 senoner 542 </p>
2947     <p>Possible Answers:
2948     </p>
2949 schoenebeck 708 <p>
2950     </p>
2951 senoner 542 <blockquote class="text">
2952     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2953     Each answer line begins with the information category name
2954     followed by a colon and then a space character &lt;SP&gt; and finally
2955     the info character string to that info category. As some
2956     parameters might allow multiple values, character strings are
2957     encapsulated into apostrophes ('). At the moment the following
2958     information categories are defined (independent of driver):
2959     </p>
2960 schoenebeck 708 <p>
2961     </p>
2962 senoner 542 <blockquote class="text">
2963     <p>DRIVER -
2964     </p>
2965     <blockquote class="text">
2966     <p>identifier of the used MIDI input driver, as e.g.
2967 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>
2968 senoner 542 command
2969     </p>
2970 schoenebeck 940 </blockquote>
2971    
2972 senoner 542
2973 schoenebeck 940 </blockquote>
2974    
2975 senoner 542 <blockquote class="text">
2976 schoenebeck 708 <p>ACTIVE -
2977 senoner 542 </p>
2978     <blockquote class="text">
2979     <p>either true or false, if false then the MIDI device is
2980     inactive and doesn't listen to any incoming MIDI events
2981     and thus doesn't forward them to connected sampler
2982     channels
2983     </p>
2984 schoenebeck 940 </blockquote>
2985    
2986 senoner 542
2987 schoenebeck 940 </blockquote>
2988    
2989 senoner 542
2990 schoenebeck 708 </blockquote><p>
2991 schoenebeck 940
2992 schoenebeck 708 </p>
2993 senoner 542 <p>The mentioned fields above don't have to be in particular
2994     order. The fields above are only those fields which are
2995     returned by all MIDI input devices. Every MIDI input driver
2996     might have its own, additional driver specific parameters (see
2997 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
2998 senoner 542 by this command.
2999     </p>
3000     <p>Example:
3001     </p>
3002 schoenebeck 708 <p>
3003     </p>
3004 senoner 542 <blockquote class="text">
3005     <p>C: "GET MIDI_INPUT_DEVICE INFO 0"
3006     </p>
3007     <p>S: "DRIVER: ALSA"
3008     </p>
3009     <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
3010     </p>
3011     <p>&nbsp;&nbsp;&nbsp;"."
3012     </p>
3013 schoenebeck 708 </blockquote><p>
3014 schoenebeck 940
3015 schoenebeck 708 </p>
3016 schoenebeck 940 <a name="SET MIDI_INPUT_DEVICE_PARAMETER"></a><br /><hr />
3017 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>
3018     <a name="rfc.section.6.3.10"></a><h3>6.3.10.&nbsp;
3019     Changing settings of MIDI input devices</h3>
3020 senoner 542
3021     <p>Use the following command to alter a specific setting of a created MIDI input device:
3022     </p>
3023 schoenebeck 708 <p>
3024     </p>
3025 senoner 542 <blockquote class="text">
3026     <p>SET MIDI_INPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;
3027     </p>
3028 schoenebeck 708 </blockquote><p>
3029 schoenebeck 940
3030 schoenebeck 708 </p>
3031 senoner 542 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
3032 schoenebeck 575 MIDI input device as returned by the
3033 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>
3034     or <a class='info' href='#LIST MIDI_INPUT_DEVICES'>"LIST MIDI_INPUT_DEVICES"<span> (</span><span class='info'>Getting all created MIDI input device list</span><span>)</span></a>
3035 schoenebeck 575 command, &lt;key&gt; by the name of the parameter to change and
3036 senoner 542 &lt;value&gt; by the new value for this parameter.
3037     </p>
3038     <p>Possible Answers:
3039     </p>
3040 schoenebeck 708 <p>
3041     </p>
3042 senoner 542 <blockquote class="text">
3043     <p>"OK" -
3044     </p>
3045     <blockquote class="text">
3046     <p>in case setting was successfully changed
3047     </p>
3048 schoenebeck 940 </blockquote>
3049    
3050 senoner 542
3051     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3052     </p>
3053     <blockquote class="text">
3054     <p>in case setting was changed successfully, but there are
3055     noteworthy issue(s) related, providing an appropriate
3056     warning code and warning message
3057     </p>
3058 schoenebeck 940 </blockquote>
3059    
3060 senoner 542
3061     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3062     </p>
3063     <blockquote class="text">
3064     <p>in case it failed, providing an appropriate error code and error message
3065     </p>
3066 schoenebeck 940 </blockquote>
3067    
3068 senoner 542
3069 schoenebeck 708 </blockquote><p>
3070 schoenebeck 940
3071 schoenebeck 708 </p>
3072 senoner 542 <p>Example:
3073     </p>
3074 schoenebeck 708 <p>
3075     </p>
3076 senoner 542 <blockquote class="text">
3077     <p>C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"
3078     </p>
3079     <p>S: "OK"
3080     </p>
3081 schoenebeck 708 </blockquote><p>
3082 schoenebeck 940
3083 schoenebeck 708 </p>
3084 schoenebeck 940 <a name="GET MIDI_INPUT_PORT INFO"></a><br /><hr />
3085 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>
3086     <a name="rfc.section.6.3.11"></a><h3>6.3.11.&nbsp;
3087     Getting information about a MIDI port</h3>
3088 senoner 542
3089     <p>Use the following command to get information about a MIDI port:
3090     </p>
3091 schoenebeck 708 <p>
3092     </p>
3093 senoner 542 <blockquote class="text">
3094     <p>GET MIDI_INPUT_PORT INFO &lt;device-id&gt; &lt;midi-port&gt;
3095     </p>
3096 schoenebeck 708 </blockquote><p>
3097 schoenebeck 940
3098 schoenebeck 708 </p>
3099 schoenebeck 575 <p>Where &lt;device-id&gt; is the numerical ID of the MIDI input device as returned by the
3100 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>
3101     or <a class='info' href='#LIST MIDI_INPUT_DEVICES'>"LIST MIDI_INPUT_DEVICES"<span> (</span><span class='info'>Getting all created MIDI input device list</span><span>)</span></a>
3102 schoenebeck 575 command and &lt;midi-port&gt; the MIDI input port number.
3103 senoner 542 </p>
3104     <p>Possible Answers:
3105     </p>
3106 schoenebeck 708 <p>
3107     </p>
3108 senoner 542 <blockquote class="text">
3109     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3110     Each answer line begins with the information category name
3111     followed by a colon and then a space character &lt;SP&gt; and finally
3112     the info character string to that info category. At the moment
3113     the following information categories are defined:
3114     </p>
3115     <p>NAME -
3116     </p>
3117     <blockquote class="text">
3118     <p>arbitrary character string naming the port
3119     </p>
3120 schoenebeck 940 </blockquote>
3121    
3122 senoner 542
3123 schoenebeck 708 </blockquote><p>
3124 schoenebeck 940
3125 schoenebeck 708 </p>
3126 senoner 542 <p>The field above is only the one which is returned by all MIDI
3127     ports regardless of the MIDI driver and port. Every MIDI port
3128     might have its own, additional driver and port specific
3129     parameters.
3130     </p>
3131     <p>Example:
3132     </p>
3133 schoenebeck 708 <p>
3134     </p>
3135 senoner 542 <blockquote class="text">
3136     <p>C: "GET MIDI_INPUT_PORT INFO 0 0"
3137     </p>
3138     <p>S: "NAME: 'Masterkeyboard'"
3139     </p>
3140     <p>&nbsp;&nbsp;&nbsp;"ALSA_SEQ_BINDINGS: '64:0'"
3141     </p>
3142     <p>&nbsp;&nbsp;&nbsp;"."
3143     </p>
3144 schoenebeck 708 </blockquote><p>
3145 schoenebeck 940
3146 schoenebeck 708 </p>
3147 schoenebeck 940 <a name="GET MIDI_INPUT_PORT_PARAMETER INFO"></a><br /><hr />
3148 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>
3149     <a name="rfc.section.6.3.12"></a><h3>6.3.12.&nbsp;
3150     Getting information about specific MIDI port parameter</h3>
3151 senoner 542
3152     <p>Use the following command to get detailed information about specific MIDI port parameter:
3153     </p>
3154 schoenebeck 708 <p>
3155     </p>
3156 senoner 542 <blockquote class="text">
3157     <p>GET MIDI_INPUT_PORT_PARAMETER INFO &lt;dev-id&gt; &lt;port&gt; &lt;param&gt;
3158     </p>
3159 schoenebeck 708 </blockquote><p>
3160 schoenebeck 940
3161 schoenebeck 708 </p>
3162 schoenebeck 575 <p>Where &lt;dev-id&gt; is the numerical ID of the MIDI input device as returned by the
3163 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>
3164     or <a class='info' href='#LIST MIDI_INPUT_DEVICES'>"LIST MIDI_INPUT_DEVICES"<span> (</span><span class='info'>Getting all created MIDI input device list</span><span>)</span></a>
3165 schoenebeck 575 command, &lt;port&gt; the MIDI port number and
3166 senoner 542 &lt;param&gt; a specific port parameter name for which information should be
3167 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).
3168 senoner 542 </p>
3169     <p>Possible Answers:
3170     </p>
3171 schoenebeck 708 <p>
3172     </p>
3173 senoner 542 <blockquote class="text">
3174     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3175     Each answer line begins with the information category name
3176     followed by a colon and then a space character &lt;SP&gt; and finally
3177     the info character string to that info category. There is
3178     information which is always returned, independently of the
3179     given channel parameter and there is optional information
3180     which are only shown dependently to the given MIDI port. At the
3181     moment the following information categories are defined:
3182     </p>
3183     <p>TYPE -
3184     </p>
3185     <blockquote class="text">
3186     <p>either "BOOL" for boolean value(s) or "INT" for integer
3187     value(s) or "FLOAT" for dotted number(s) or "STRING" for
3188     character string(s)
3189     (always returned)
3190     </p>
3191 schoenebeck 940 </blockquote>
3192    
3193 senoner 542
3194     <p>DESCRIPTION -
3195     </p>
3196     <blockquote class="text">
3197     <p>arbitrary text describing the purpose of the parameter
3198     (always returned)
3199     </p>
3200 schoenebeck 940 </blockquote>
3201    
3202 senoner 542
3203     <p>FIX -
3204     </p>
3205     <blockquote class="text">
3206     <p>either true or false, if true then this parameter is
3207     read only, thus cannot be altered
3208     (always returned)
3209     </p>
3210 schoenebeck 940 </blockquote>
3211    
3212 senoner 542
3213     <p>MULTIPLICITY -
3214     </p>
3215     <blockquote class="text">
3216     <p>either true or false, defines if this parameter allows
3217     only one value or a list of values, where true means
3218     multiple values and false only a single value allowed
3219     (always returned)
3220     </p>
3221 schoenebeck 940 </blockquote>
3222    
3223 senoner 542
3224     <p>RANGE_MIN -
3225     </p>
3226     <blockquote class="text">
3227     <p>defines lower limit of the allowed value range for this
3228     parameter, can be an integer value as well as a dotted
3229     number, this parameter is usually used in conjunction
3230     with 'RANGE_MAX' but may also appear without
3231     (optionally returned, dependent to driver and port
3232     parameter)
3233     </p>
3234 schoenebeck 940 </blockquote>
3235    
3236 senoner 542
3237     <p>RANGE_MAX -
3238     </p>
3239     <blockquote class="text">
3240     <p>defines upper limit of the allowed value range for this
3241     parameter, can be an integer value as well as a dotted
3242     number, this parameter is usually used in conjunction
3243     with 'RANGE_MIN' but may also appear without
3244     (optionally returned, dependent to driver and port
3245     parameter)
3246     </p>
3247 schoenebeck 940 </blockquote>
3248    
3249 senoner 542
3250     <p>POSSIBILITIES -
3251     </p>
3252     <blockquote class="text">
3253     <p>comma separated list of possible values for this
3254     parameter, character strings are encapsulated into
3255     apostrophes
3256     (optionally returned, dependent to device and port
3257     parameter)
3258     </p>
3259 schoenebeck 940 </blockquote>
3260    
3261 senoner 542
3262 schoenebeck 708 </blockquote><p>
3263 schoenebeck 940
3264 schoenebeck 708 </p>
3265 senoner 542 <p>The mentioned fields above don't have to be in particular order.
3266     </p>
3267     <p>Example:
3268     </p>
3269 schoenebeck 708 <p>
3270     </p>
3271 senoner 542 <blockquote class="text">
3272     <p>C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"
3273     </p>
3274     <p>S: "DESCRIPTION: bindings to other ALSA sequencer clients"
3275     </p>
3276     <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
3277     </p>
3278     <p>&nbsp;&nbsp;&nbsp;"FIX: false"
3279     </p>
3280     <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"
3281     </p>
3282     <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: '64:0','68:0','68:1'"
3283     </p>
3284     <p>&nbsp;&nbsp;&nbsp;"."
3285     </p>
3286 schoenebeck 708 </blockquote><p>
3287 schoenebeck 940
3288 schoenebeck 708 </p>
3289 schoenebeck 940 <a name="SET MIDI_INPUT_PORT_PARAMETER"></a><br /><hr />
3290 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>
3291     <a name="rfc.section.6.3.13"></a><h3>6.3.13.&nbsp;
3292     Changing settings of MIDI input ports</h3>
3293 senoner 542
3294     <p>Use the following command to alter a specific setting of a MIDI input port:
3295     </p>
3296 schoenebeck 708 <p>
3297     </p>
3298 senoner 542 <blockquote class="text">
3299     <p>SET MIDI_INPUT_PORT_PARAMETER &lt;device-id&gt; &lt;port&gt; &lt;key&gt;=&lt;value&gt;
3300     </p>
3301 schoenebeck 708 </blockquote><p>
3302 schoenebeck 940
3303 schoenebeck 708 </p>
3304 senoner 542 <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
3305 schoenebeck 575 MIDI device as returned by the
3306 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>
3307     or <a class='info' href='#LIST MIDI_INPUT_DEVICES'>"LIST MIDI_INPUT_DEVICES"<span> (</span><span class='info'>Getting all created MIDI input device list</span><span>)</span></a>
3308 schoenebeck 575 command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of
3309 senoner 542 the parameter to change and &lt;value&gt; by the new value for this
3310 schoenebeck 1363 parameter (encapsulated into apostrophes) or NONE (not encapsulated into apostrophes)
3311     for specifying no value for parameters allowing a list of values.
3312 senoner 542 </p>
3313     <p>Possible Answers:
3314     </p>
3315 schoenebeck 708 <p>
3316     </p>
3317 senoner 542 <blockquote class="text">
3318     <p>"OK" -
3319     </p>
3320     <blockquote class="text">
3321     <p>in case setting was successfully changed
3322     </p>
3323 schoenebeck 940 </blockquote>
3324    
3325 senoner 542
3326     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3327     </p>
3328     <blockquote class="text">
3329     <p>in case setting was changed successfully, but there are
3330     noteworthy issue(s) related, providing an appropriate
3331     warning code and warning message
3332     </p>
3333 schoenebeck 940 </blockquote>
3334    
3335 senoner 542
3336     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3337     </p>
3338     <blockquote class="text">
3339     <p>in case it failed, providing an appropriate error code and error message
3340     </p>
3341 schoenebeck 940 </blockquote>
3342    
3343 senoner 542
3344 schoenebeck 708 </blockquote><p>
3345 schoenebeck 940
3346 schoenebeck 708 </p>
3347 senoner 542 <p>Example:
3348     </p>
3349 schoenebeck 708 <p>
3350     </p>
3351 senoner 542 <blockquote class="text">
3352 schoenebeck 1363 <p>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='20:0'"
3353     </p>
3354     <p>S: "OK"
3355     </p>
3356     </blockquote><p>
3357    
3358     </p>
3359 senoner 542 <p>
3360 schoenebeck 1363 </p>
3361     <blockquote class="text">
3362     <p>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE"
3363 senoner 542 </p>
3364 schoenebeck 1363 <p>S: "OK"
3365     </p>
3366 schoenebeck 708 </blockquote><p>
3367 schoenebeck 940
3368 schoenebeck 708 </p>
3369 schoenebeck 940 <a name="anchor11"></a><br /><hr />
3370 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>
3371     <a name="rfc.section.6.4"></a><h3>6.4.&nbsp;
3372     Configuring sampler channels</h3>
3373 senoner 542
3374 schoenebeck 575 <p>The following commands describe how to add and remove sampler channels, associate a
3375     sampler channel with a sampler engine, load instruments and connect sampler channels to
3376     MIDI and audio devices.
3377 senoner 542 </p>
3378 schoenebeck 940 <a name="LOAD INSTRUMENT"></a><br /><hr />
3379 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>
3380     <a name="rfc.section.6.4.1"></a><h3>6.4.1.&nbsp;
3381     Loading an instrument</h3>
3382 senoner 542
3383     <p>An instrument file can be loaded and assigned to a sampler channel by one of the following commands:
3384     </p>
3385 schoenebeck 708 <p>
3386     </p>
3387 senoner 542 <blockquote class="text">
3388     <p>LOAD INSTRUMENT [NON_MODAL] '&lt;filename&gt;' &lt;instr-index&gt; &lt;sampler-channel&gt;
3389     </p>
3390 schoenebeck 708 </blockquote><p>
3391 schoenebeck 940
3392 schoenebeck 708 </p>
3393 senoner 542 <p>Where &lt;filename&gt; is the name of the instrument file on the
3394     LinuxSampler instance's host system, &lt;instr-index&gt; the index of the
3395     instrument in the instrument file and &lt;sampler-channel> is the
3396     number of the sampler channel the instrument should be assigned to.
3397     Each sampler channel can only have one instrument.
3398     </p>
3399 schoenebeck 1251 <p>Notice: since LSCP 1.2 the &lt;filename&gt; argument supports
3400     escape characters for special characters (see chapter
3401     "<a class='info' href='#character_set'>Character Set and Escape Sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>"
3402     for details) and accordingly backslash characters in the filename
3403     MUST now be escaped as well!
3404     </p>
3405 senoner 542 <p>The difference between regular and NON_MODAL versions of the command
3406     is that the regular command returns OK only after the instrument has been
3407     fully loaded and the channel is ready to be used while NON_MODAL version
3408     returns immediately and a background process is launched to load the instrument
3409 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>
3410 senoner 542 command can be used to obtain loading
3411     progress from INSTRUMENT_STATUS field. LOAD command will perform sanity checks
3412     such as making sure that the file could be read and it is of a proper format
3413     and SHOULD return ERR and SHOULD not launch the background process should any
3414     errors be detected at that point.
3415     </p>
3416     <p>Possible Answers:
3417     </p>
3418 schoenebeck 708 <p>
3419     </p>
3420 senoner 542 <blockquote class="text">
3421     <p>"OK" -
3422     </p>
3423     <blockquote class="text">
3424     <p>in case the instrument was successfully loaded
3425     </p>
3426 schoenebeck 940 </blockquote>
3427    
3428 senoner 542
3429     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3430     </p>
3431     <blockquote class="text">
3432     <p>in case the instrument was loaded successfully, but there
3433     are noteworthy issue(s) related (e.g. Engine doesn't support
3434     one or more patch parameters provided by the loaded
3435     instrument file), providing an appropriate warning code and
3436     warning message
3437     </p>
3438 schoenebeck 940 </blockquote>
3439    
3440 senoner 542
3441     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3442     </p>
3443     <blockquote class="text">
3444     <p>in case it failed, providing an appropriate error code and error message
3445     </p>
3446 schoenebeck 940 </blockquote>
3447    
3448 senoner 542
3449 schoenebeck 708 </blockquote><p>
3450 schoenebeck 940
3451 schoenebeck 708 </p>
3452 senoner 542 <p>Example:
3453     </p>
3454 schoenebeck 708 <p>
3455     </p>
3456 senoner 542 <blockquote class="text">
3457     <p>
3458     </p>
3459 schoenebeck 708 </blockquote><p>
3460 schoenebeck 940
3461 schoenebeck 708 </p>
3462 schoenebeck 940 <a name="LOAD ENGINE"></a><br /><hr />
3463 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>
3464     <a name="rfc.section.6.4.2"></a><h3>6.4.2.&nbsp;
3465     Loading a sampler engine</h3>
3466 senoner 542
3467 schoenebeck 575 <p>A sampler engine type can be associated to a specific sampler
3468 senoner 542 channel by the following command:
3469     </p>
3470 schoenebeck 708 <p>
3471     </p>
3472 senoner 542 <blockquote class="text">
3473     <p>LOAD ENGINE &lt;engine-name&gt; &lt;sampler-channel&gt;
3474     </p>
3475 schoenebeck 708 </blockquote><p>
3476 schoenebeck 940
3477 schoenebeck 708 </p>
3478 senoner 542 <p>Where &lt;engine-name&gt; is an engine name as obtained by the
3479 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;
3480 schoenebeck 575 the sampler channel as returned by the
3481 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
3482     <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a> command where
3483 schoenebeck 575 the engine type should be assigned to. This command should be issued
3484     after adding a new sampler channel and before any other control
3485     commands on the new sampler channel. It can also be used to change
3486     the engine type of a sampler channel. This command has (currently) no
3487     way to define or force if a new engine instance should be created and
3488     assigned to the given sampler channel or if an already existing
3489     instance of that engine type, shared with other sampler channels,
3490     should be used.
3491 senoner 542 </p>
3492     <p>Possible Answers:
3493     </p>
3494 schoenebeck 708 <p>
3495     </p>
3496 senoner 542 <blockquote class="text">
3497     <p>"OK" -
3498     </p>
3499     <blockquote class="text">
3500     <p>in case the engine was successfully deployed
3501     </p>
3502 schoenebeck 940 </blockquote>
3503    
3504 senoner 542
3505     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3506     </p>
3507     <blockquote class="text">
3508     <p>in case the engine was deployed successfully, but there
3509     are noteworthy issue(s) related, providing an appropriate
3510     warning code and warning message
3511     </p>
3512 schoenebeck 940 </blockquote>
3513    
3514 senoner 542
3515     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3516     </p>
3517     <blockquote class="text">
3518     <p>in case it failed, providing an appropriate error code and
3519     error message
3520     </p>
3521 schoenebeck 940 </blockquote>
3522    
3523 senoner 542
3524 schoenebeck 708 </blockquote><p>
3525 schoenebeck 940
3526 schoenebeck 708 </p>
3527 senoner 542 <p>Example:
3528     </p>
3529 schoenebeck 708 <p>
3530     </p>
3531 senoner 542 <blockquote class="text">
3532     <p>
3533     </p>
3534 schoenebeck 708 </blockquote><p>
3535 schoenebeck 940
3536 schoenebeck 708 </p>
3537 schoenebeck 940 <a name="GET CHANNELS"></a><br /><hr />
3538 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>
3539     <a name="rfc.section.6.4.3"></a><h3>6.4.3.&nbsp;
3540     Getting all created sampler channel count</h3>
3541 senoner 542
3542     <p>The number of sampler channels can change on runtime. To get the
3543     current amount of sampler channels, the front-end can send the
3544     following command:
3545     </p>
3546 schoenebeck 708 <p>
3547     </p>
3548 senoner 542 <blockquote class="text">
3549     <p>GET CHANNELS
3550     </p>
3551 schoenebeck 708 </blockquote><p>
3552 schoenebeck 940
3553 schoenebeck 708 </p>
3554 senoner 542 <p>Possible Answers:
3555     </p>
3556 schoenebeck 708 <p>
3557     </p>
3558 senoner 542 <blockquote class="text">
3559     <p>LinuxSampler will answer by returning the current number of sampler channels.
3560     </p>
3561 schoenebeck 708 </blockquote><p>
3562 schoenebeck 940
3563 schoenebeck 708 </p>
3564 senoner 542 <p>Example:
3565     </p>
3566 schoenebeck 708 <p>
3567     </p>
3568 senoner 542 <blockquote class="text">
3569     <p>C: "GET CHANNELS"
3570     </p>
3571     <p>S: "12"
3572     </p>
3573 schoenebeck 708 </blockquote><p>
3574 schoenebeck 940
3575 schoenebeck 708 </p>
3576 schoenebeck 940 <a name="LIST CHANNELS"></a><br /><hr />
3577 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>
3578     <a name="rfc.section.6.4.4"></a><h3>6.4.4.&nbsp;
3579     Getting all created sampler channel list</h3>
3580 senoner 542
3581     <p>The number of sampler channels can change on runtime. To get the
3582     current list of sampler channels, the front-end can send the
3583     following command:
3584     </p>
3585 schoenebeck 708 <p>
3586     </p>
3587 senoner 542 <blockquote class="text">
3588     <p>LIST CHANNELS
3589     </p>
3590 schoenebeck 708 </blockquote><p>
3591 schoenebeck 940
3592 schoenebeck 708 </p>
3593 senoner 542 <p>Possible Answers:
3594     </p>
3595 schoenebeck 708 <p>
3596     </p>
3597 senoner 542 <blockquote class="text">
3598     <p>LinuxSampler will answer by returning a comma separated list
3599     with all sampler channels numerical IDs.
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: "LIST CHANNELS"
3610     </p>
3611     <p>S: "0,1,2,3,4,5,6,9,10,11,15,20"
3612     </p>
3613 schoenebeck 708 </blockquote><p>
3614 schoenebeck 940
3615 schoenebeck 708 </p>
3616 schoenebeck 940 <a name="ADD CHANNEL"></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.5"></a><h3>6.4.5.&nbsp;
3619     Adding a new sampler channel</h3>
3620 senoner 542
3621     <p>A new sampler channel can be added to the end of the sampler
3622     channel list by sending the following command:
3623     </p>
3624 schoenebeck 708 <p>
3625     </p>
3626 senoner 542 <blockquote class="text">
3627     <p>ADD CHANNEL
3628     </p>
3629 schoenebeck 708 </blockquote><p>
3630 schoenebeck 940
3631 schoenebeck 708 </p>
3632 senoner 542 <p>This will increment the sampler channel count by one and the new
3633     sampler channel will be appended to the end of the sampler channel
3634     list. The front-end should send the respective, related commands
3635     right after to e.g. load an engine, load an instrument and setting
3636     input, output method and eventually other commands to initialize
3637     the new channel. The front-end should use the sampler channel
3638     returned by the answer of this command to perform the previously
3639     recommended commands, to avoid race conditions e.g. with other
3640     front-ends that might also have sent an "ADD CHANNEL" command.
3641     </p>
3642     <p>Possible Answers:
3643     </p>
3644 schoenebeck 708 <p>
3645     </p>
3646 senoner 542 <blockquote class="text">
3647     <p>"OK[&lt;sampler-channel&gt;]" -
3648     </p>
3649     <blockquote class="text">
3650     <p>in case a new sampler channel could be added, where
3651     &lt;sampler-channel&gt; reflects the channel number of the new
3652 schoenebeck 561 created sampler channel which should be used to set up
3653     the sampler channel by sending subsequent initialization
3654 senoner 542 commands
3655     </p>
3656 schoenebeck 940 </blockquote>
3657    
3658 senoner 542
3659     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3660     </p>
3661     <blockquote class="text">
3662     <p>in case a new channel was added successfully, but there are
3663     noteworthy issue(s) related, providing an appropriate
3664     warning code and warning message
3665     </p>
3666 schoenebeck 940 </blockquote>
3667    
3668 senoner 542
3669     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3670     </p>
3671     <blockquote class="text">
3672     <p>in case it failed, providing an appropriate error code and
3673     error message
3674     </p>
3675 schoenebeck 940 </blockquote>
3676    
3677 senoner 542
3678 schoenebeck 708 </blockquote><p>
3679 schoenebeck 940
3680 schoenebeck 708 </p>
3681 senoner 542 <p>Example:
3682     </p>
3683 schoenebeck 708 <p>
3684     </p>
3685 senoner 542 <blockquote class="text">
3686     <p>
3687     </p>
3688 schoenebeck 708 </blockquote><p>
3689 schoenebeck 940
3690 schoenebeck 708 </p>
3691 schoenebeck 940 <a name="REMOVE CHANNEL"></a><br /><hr />
3692 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>
3693     <a name="rfc.section.6.4.6"></a><h3>6.4.6.&nbsp;
3694     Removing a sampler channel</h3>
3695 senoner 542
3696     <p>A sampler channel can be removed by sending the following command:
3697     </p>
3698 schoenebeck 708 <p>
3699     </p>
3700 senoner 542 <blockquote class="text">
3701     <p>REMOVE CHANNEL &lt;sampler-channel&gt;
3702     </p>
3703 schoenebeck 708 </blockquote><p>
3704 schoenebeck 940
3705 schoenebeck 708 </p>
3706 schoenebeck 561 <p>Where &lt;sampler-channel&gt; should be replaced by the
3707     number of the sampler channel as given by the
3708 schoenebeck 974 <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
3709     or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a>
3710 schoenebeck 561 command. The channel numbers of all subsequent sampler channels
3711     remain the same.
3712 senoner 542 </p>
3713     <p>Possible Answers:
3714     </p>
3715 schoenebeck 708 <p>
3716     </p>
3717 senoner 542 <blockquote class="text">
3718     <p>"OK" -
3719     </p>
3720     <blockquote class="text">
3721     <p>in case the given sampler channel could be removed
3722     </p>
3723 schoenebeck 940 </blockquote>
3724    
3725 senoner 542
3726     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3727     </p>
3728     <blockquote class="text">
3729     <p>in case the given channel was removed, but there are
3730     noteworthy issue(s) related, providing an appropriate
3731     warning code and warning message
3732     </p>
3733 schoenebeck 940 </blockquote>
3734    
3735 senoner 542
3736     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3737     </p>
3738     <blockquote class="text">
3739     <p>in case it failed, providing an appropriate error code and
3740     error message
3741     </p>
3742 schoenebeck 940 </blockquote>
3743    
3744 senoner 542
3745 schoenebeck 708 </blockquote><p>
3746 schoenebeck 940
3747 schoenebeck 708 </p>
3748 senoner 542 <p>Example:
3749     </p>
3750 schoenebeck 708 <p>
3751     </p>
3752 senoner 542 <blockquote class="text">
3753     <p>
3754     </p>
3755 schoenebeck 708 </blockquote><p>
3756 schoenebeck 940
3757 schoenebeck 708 </p>
3758 schoenebeck 940 <a name="GET AVAILABLE_ENGINES"></a><br /><hr />
3759 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>
3760     <a name="rfc.section.6.4.7"></a><h3>6.4.7.&nbsp;
3761     Getting amount of available engines</h3>
3762 senoner 542
3763     <p>The front-end can ask for the number of available engines by sending the following command:
3764     </p>
3765 schoenebeck 708 <p>
3766     </p>
3767 senoner 542 <blockquote class="text">
3768     <p>GET AVAILABLE_ENGINES
3769     </p>
3770 schoenebeck 708 </blockquote><p>
3771 schoenebeck 940
3772 schoenebeck 708 </p>
3773 senoner 542 <p>Possible Answers:
3774     </p>
3775 schoenebeck 708 <p>
3776     </p>
3777 senoner 542 <blockquote class="text">
3778     <p>LinuxSampler will answer by sending the number of available engines.
3779     </p>
3780 schoenebeck 708 </blockquote><p>
3781 schoenebeck 940
3782 schoenebeck 708 </p>
3783 senoner 542 <p>Example:
3784     </p>
3785 schoenebeck 708 <p>
3786     </p>
3787 senoner 542 <blockquote class="text">
3788     <p>C: "GET AVAILABLE_ENGINES"
3789     </p>
3790     <p>S: "4"
3791     </p>
3792 schoenebeck 708 </blockquote><p>
3793 schoenebeck 940
3794 schoenebeck 708 </p>
3795 schoenebeck 940 <a name="LIST AVAILABLE_ENGINES"></a><br /><hr />
3796 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>
3797     <a name="rfc.section.6.4.8"></a><h3>6.4.8.&nbsp;
3798     Getting all available engines</h3>
3799 senoner 542
3800     <p>The front-end can ask for a list of all available engines by sending the following command:
3801     </p>
3802 schoenebeck 708 <p>
3803     </p>
3804 senoner 542 <blockquote class="text">
3805     <p>LIST AVAILABLE_ENGINES
3806     </p>
3807 schoenebeck 708 </blockquote><p>
3808 schoenebeck 940
3809 schoenebeck 708 </p>
3810 senoner 542 <p>Possible Answers:
3811     </p>
3812 schoenebeck 708 <p>
3813     </p>
3814 senoner 542 <blockquote class="text">
3815 schoenebeck 561 <p>LinuxSampler will answer by sending a comma separated list
3816     of the engines' names encapsulated into apostrophes (').
3817     Engine names can consist of lower and upper cases,
3818     digits and underlines ("_" character).
3819 senoner 542 </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: "LIST AVAILABLE_ENGINES"
3829     </p>
3830 schoenebeck 561 <p>S: "'GigEngine','AkaiEngine','DLSEngine','JoesCustomEngine'"
3831 senoner 542 </p>
3832 schoenebeck 708 </blockquote><p>
3833 schoenebeck 940
3834 schoenebeck 708 </p>
3835 schoenebeck 940 <a name="GET ENGINE INFO"></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.9"></a><h3>6.4.9.&nbsp;
3838     Getting information about an engine</h3>
3839 senoner 542
3840     <p>The front-end can ask for information about a specific engine by
3841     sending the following command:
3842     </p>
3843 schoenebeck 708 <p>
3844     </p>
3845 senoner 542 <blockquote class="text">
3846     <p>GET ENGINE INFO &lt;engine-name&gt;
3847     </p>
3848 schoenebeck 708 </blockquote><p>
3849 schoenebeck 940
3850 schoenebeck 708 </p>
3851 senoner 542 <p>Where &lt;engine-name&gt; is an engine name as obtained by the
3852 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.
3853 senoner 542 </p>
3854     <p>Possible Answers:
3855     </p>
3856 schoenebeck 708 <p>
3857     </p>
3858 senoner 542 <blockquote class="text">
3859     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3860     Each answer line begins with the information category name
3861     followed by a colon and then a space character &lt;SP&gt; and finally
3862     the info character string to that info category. At the moment
3863     the following categories are defined:
3864     </p>
3865 schoenebeck 708 <p>
3866     </p>
3867 senoner 542 <blockquote class="text">
3868     <p>DESCRIPTION -
3869     </p>
3870     <blockquote class="text">
3871     <p>arbitrary description text about the engine
3872     </p>
3873 schoenebeck 940 </blockquote>
3874    
3875 senoner 542
3876     <p>VERSION -
3877     </p>
3878     <blockquote class="text">
3879     <p>arbitrary character string regarding the engine's version
3880     </p>
3881 schoenebeck 940 </blockquote>
3882    
3883 senoner 542
3884 schoenebeck 940 </blockquote>
3885    
3886 senoner 542
3887 schoenebeck 708 </blockquote><p>
3888 schoenebeck 940
3889 schoenebeck 708 </p>
3890 senoner 542 <p>The mentioned fields above don't have to be in particular order.
3891     </p>
3892     <p>Example:
3893     </p>
3894 schoenebeck 708 <p>
3895     </p>
3896 senoner 542 <blockquote class="text">
3897     <p>C: "GET ENGINE INFO JoesCustomEngine"
3898     </p>
3899     <p>S: "DESCRIPTION: this is Joe's custom sampler engine"
3900     </p>
3901     <p>&nbsp;&nbsp;&nbsp;"VERSION: testing-1.0"
3902     </p>
3903     <p>&nbsp;&nbsp;&nbsp;"."
3904     </p>
3905 schoenebeck 708 </blockquote><p>
3906 schoenebeck 940
3907 schoenebeck 708 </p>
3908 schoenebeck 940 <a name="GET CHANNEL INFO"></a><br /><hr />
3909 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>
3910     <a name="rfc.section.6.4.10"></a><h3>6.4.10.&nbsp;
3911     Getting sampler channel information</h3>
3912 senoner 542
3913     <p>The front-end can ask for the current settings of a sampler channel
3914     by sending the following command:
3915     </p>
3916 schoenebeck 708 <p>
3917     </p>
3918 senoner 542 <blockquote class="text">
3919     <p>GET CHANNEL INFO &lt;sampler-channel&gt;
3920     </p>
3921 schoenebeck 708 </blockquote><p>
3922 schoenebeck 940
3923 schoenebeck 708 </p>
3924 schoenebeck 575 <p>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
3925 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>
3926     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.
3927 senoner 542 </p>
3928     <p>Possible Answers:
3929     </p>
3930 schoenebeck 708 <p>
3931     </p>
3932 senoner 542 <blockquote class="text">
3933     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3934     Each answer line begins with the settings category name
3935     followed by a colon and then a space character &lt;SP&gt; and finally
3936     the info character string to that setting category. At the
3937     moment the following categories are defined:
3938     </p>
3939 schoenebeck 708 <p>
3940     </p>
3941 senoner 542 <blockquote class="text">
3942     <p>ENGINE_NAME -
3943     </p>
3944     <blockquote class="text">
3945 schoenebeck 575 <p>name of the engine that is associated with the sampler
3946     channel, "NONE" if there's no engine associated yet for
3947 senoner 542 this sampler channel
3948     </p>
3949 schoenebeck 940 </blockquote>
3950    
3951 senoner 542
3952     <p>AUDIO_OUTPUT_DEVICE -
3953     </p>
3954     <blockquote class="text">
3955     <p>numerical ID of the audio output device which is
3956     currently connected to this sampler channel to output
3957     the audio signal, "NONE" if there's no device
3958     connected to this sampler channel
3959     </p>
3960 schoenebeck 940 </blockquote>
3961    
3962 senoner 542
3963     <p>AUDIO_OUTPUT_CHANNELS -
3964     </p>
3965     <blockquote class="text">
3966     <p>number of output channels the sampler channel offers
3967     (dependent to used sampler engine and loaded instrument)
3968     </p>
3969 schoenebeck 940 </blockquote>
3970    
3971 senoner 542
3972     <p>AUDIO_OUTPUT_ROUTING -
3973     </p>
3974     <blockquote class="text">
3975     <p>comma separated list which reflects to which audio
3976     channel of the selected audio output device each
3977     sampler output channel is routed to, e.g. "0,3" would
3978     mean the engine's output channel 0 is routed to channel
3979     0 of the audio output device and the engine's output
3980     channel 1 is routed to the channel 3 of the audio
3981     output device
3982     </p>
3983 schoenebeck 940 </blockquote>
3984    
3985 senoner 542
3986     <p>INSTRUMENT_FILE -
3987     </p>
3988     <blockquote class="text">
3989     <p>the file name of the loaded instrument, "NONE" if
3990     there's no instrument yet loaded for this sampler
3991     channel
3992     </p>
3993 schoenebeck 940 </blockquote>
3994    
3995 senoner 542
3996     <p>INSTRUMENT_NR -
3997     </p>
3998     <blockquote class="text">
3999     <p>the instrument index number of the loaded instrument
4000     </p>
4001 schoenebeck 940 </blockquote>
4002    
4003 senoner 542
4004     <p>INSTRUMENT_NAME -
4005     </p>
4006     <blockquote class="text">
4007     <p>the instrument name of the loaded instrument
4008     </p>
4009 schoenebeck 940 </blockquote>
4010    
4011 senoner 542
4012     <p>INSTRUMENT_STATUS -
4013     </p>
4014     <blockquote class="text">
4015     <p>integer values 0 to 100 indicating loading progress percentage for the instrument. Negative
4016     value indicates a loading exception. Value of 100 indicates that the instrument is fully
4017     loaded.
4018     </p>
4019 schoenebeck 940 </blockquote>
4020    
4021 senoner 542
4022     <p>MIDI_INPUT_DEVICE -
4023     </p>
4024     <blockquote class="text">
4025     <p>numerical ID of the MIDI input device which is
4026     currently connected to this sampler channel to deliver
4027     MIDI input commands, "NONE" if there's no device
4028     connected to this sampler channel
4029     </p>
4030 schoenebeck 940 </blockquote>
4031    
4032 senoner 542
4033     <p>MIDI_INPUT_PORT -
4034     </p>
4035     <blockquote class="text">
4036     <p>port number of the MIDI input device
4037     </p>
4038 schoenebeck 940 </blockquote>
4039    
4040 senoner 542
4041     <p>MIDI_INPUT_CHANNEL -
4042     </p>
4043     <blockquote class="text">
4044     <p>the MIDI input channel number this sampler channel
4045     should listen to or "ALL" to listen on all MIDI channels
4046     </p>
4047 schoenebeck 940 </blockquote>
4048    
4049 senoner 542
4050     <p>VOLUME -
4051     </p>
4052     <blockquote class="text">
4053     <p>optionally dotted number for the channel volume factor
4054 schoenebeck 1028 (where a value &lt; 1.0 means attenuation and a value >
4055 senoner 542 1.0 means amplification)
4056     </p>
4057 schoenebeck 940 </blockquote>
4058    
4059 senoner 542
4060 schoenebeck 708 <p>MUTE -
4061     </p>
4062     <blockquote class="text">
4063     <p>Determines whether the channel is muted, "true" if the
4064     channel is muted, "false" if the channel is not muted, and
4065     "MUTED_BY_SOLO" if the channel is muted because of the
4066     presence of a solo channel and will be unmuted when
4067     there are no solo channels left
4068     </p>
4069 schoenebeck 940 </blockquote>
4070    
4071 senoner 542
4072 schoenebeck 708 <p>SOLO -
4073     </p>
4074     <blockquote class="text">
4075     <p>Determines whether this is a solo channel, "true" if
4076     the channel is a solo channel; "false" otherwise
4077     </p>
4078 schoenebeck 940 </blockquote>
4079    
4080 senoner 542
4081 schoenebeck 974 <p>MIDI_INSTRUMENT_MAP -
4082     </p>
4083     <blockquote class="text">
4084     <p>Determines to which MIDI instrument map this sampler
4085     channel is assigned to. Read chapter
4086     <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>
4087     for a list of possible values.
4088     </p>
4089 schoenebeck 940 </blockquote>
4090 schoenebeck 974
4091    
4092     </blockquote>
4093 schoenebeck 940
4094 schoenebeck 708
4095     </blockquote><p>
4096 schoenebeck 940
4097 schoenebeck 708 </p>
4098 senoner 542 <p>The mentioned fields above don't have to be in particular order.
4099     </p>
4100     <p>Example:
4101     </p>
4102 schoenebeck 708 <p>
4103     </p>
4104 senoner 542 <blockquote class="text">
4105     <p>C: "GET CHANNEL INFO 34"
4106     </p>
4107     <p>S: "ENGINE_NAME: GigEngine"
4108     </p>
4109     <p>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"
4110     </p>
4111     <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_DEVICE: 0"
4112     </p>
4113     <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_CHANNELS: 2"
4114     </p>
4115     <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 0,1"
4116     </p>
4117     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"
4118     </p>
4119     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"
4120     </p>
4121     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NAME: Fazioli Piano"
4122     </p>
4123     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_STATUS: 100"
4124     </p>
4125     <p>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_DEVICE: 0"
4126     </p>
4127     <p>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_PORT: 0"
4128     </p>
4129     <p>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_CHANNEL: 5"
4130     </p>
4131 schoenebeck 974 <p>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"
4132     </p>
4133     <p>&nbsp;&nbsp;&nbsp;"MUTE: false"
4134     </p>
4135     <p>&nbsp;&nbsp;&nbsp;"SOLO: false"
4136     </p>
4137     <p>&nbsp;&nbsp;&nbsp;"MIDI_INSTRUMENT_MAP: NONE"
4138     </p>
4139 senoner 542 <p>&nbsp;&nbsp;&nbsp;"."
4140     </p>
4141 schoenebeck 708 </blockquote><p>
4142 schoenebeck 940
4143 schoenebeck 708 </p>
4144 schoenebeck 940 <a name="GET CHANNEL VOICE_COUNT"></a><br /><hr />
4145 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>
4146     <a name="rfc.section.6.4.11"></a><h3>6.4.11.&nbsp;
4147     Current number of active voices</h3>
4148 senoner 542
4149     <p>The front-end can ask for the current number of active voices on a
4150     sampler channel by sending the following command:
4151     </p>
4152 schoenebeck 708 <p>
4153     </p>
4154 senoner 542 <blockquote class="text">
4155     <p>GET CHANNEL VOICE_COUNT &lt;sampler-channel&gt;
4156     </p>
4157 schoenebeck 708 </blockquote><p>
4158 schoenebeck 940
4159 schoenebeck 708 </p>
4160 schoenebeck 575 <p>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
4161 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>
4162     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.
4163 senoner 542 </p>
4164     <p>Possible Answers:
4165     </p>
4166 schoenebeck 708 <p>
4167     </p>
4168 senoner 542 <blockquote class="text">
4169     <p>LinuxSampler will answer by returning the number of active
4170     voices on that channel.
4171     </p>
4172 schoenebeck 708 </blockquote><p>
4173 schoenebeck 940
4174 schoenebeck 708 </p>
4175 senoner 542 <p>Example:
4176     </p>
4177 schoenebeck 708 <p>
4178     </p>
4179 senoner 542 <blockquote class="text">
4180     <p>
4181     </p>
4182 schoenebeck 708 </blockquote><p>
4183 schoenebeck 940
4184 schoenebeck 708 </p>
4185 schoenebeck 940 <a name="GET CHANNEL STREAM_COUNT"></a><br /><hr />
4186 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>
4187     <a name="rfc.section.6.4.12"></a><h3>6.4.12.&nbsp;
4188     Current number of active disk streams</h3>
4189 senoner 542
4190     <p>The front-end can ask for the current number of active disk streams
4191     on a sampler channel by sending the following command:
4192     </p>
4193 schoenebeck 708 <p>
4194     </p>
4195 senoner 542 <blockquote class="text">
4196     <p>GET CHANNEL STREAM_COUNT &lt;sampler-channel&gt;
4197     </p>
4198 schoenebeck 708 </blockquote><p>
4199 schoenebeck 940
4200 schoenebeck 708 </p>
4201 schoenebeck 575 <p>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
4202 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>
4203     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.
4204 senoner 542 </p>
4205     <p>Possible Answers:
4206     </p>
4207 schoenebeck 708 <p>
4208     </p>
4209 senoner 542 <blockquote class="text">
4210     <p>LinuxSampler will answer by returning the number of active
4211     disk streams on that channel in case the engine supports disk
4212     streaming, if the engine doesn't support disk streaming it will
4213     return "NA" for not available.
4214     </p>
4215 schoenebeck 708 </blockquote><p>
4216 schoenebeck 940
4217 schoenebeck 708 </p>
4218 senoner 542 <p>Example:
4219     </p>
4220 schoenebeck 708 <p>
4221     </p>
4222 senoner 542 <blockquote class="text">
4223     <p>
4224     </p>
4225 schoenebeck 708 </blockquote><p>
4226 schoenebeck 940
4227 schoenebeck 708 </p>
4228 schoenebeck 940 <a name="GET CHANNEL BUFFER_FILL"></a><br /><hr />
4229 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>
4230     <a name="rfc.section.6.4.13"></a><h3>6.4.13.&nbsp;
4231     Current fill state of disk stream buffers</h3>
4232 senoner 542
4233     <p>The front-end can ask for the current fill state of all disk streams
4234     on a sampler channel by sending the following command:
4235     </p>
4236 schoenebeck 708 <p>
4237     </p>
4238 senoner 542 <blockquote class="text">
4239     <p>GET CHANNEL BUFFER_FILL BYTES &lt;sampler-channel&gt;
4240     </p>
4241 schoenebeck 708 </blockquote><p>
4242 schoenebeck 940
4243 schoenebeck 708 </p>
4244 senoner 542 <p>to get the fill state in bytes or
4245     </p>
4246 schoenebeck 708 <p>
4247     </p>
4248 senoner 542 <blockquote class="text">
4249     <p>GET CHANNEL BUFFER_FILL PERCENTAGE &lt;sampler-channel&gt;
4250     </p>
4251 schoenebeck 708 </blockquote><p>
4252 schoenebeck 940
4253 schoenebeck 708 </p>
4254 senoner 542 <p>to get the fill state in percent, where &lt;sampler-channel&gt; is the
4255 schoenebeck 575 sampler channel number the front-end is interested in
4256 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>
4257     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.
4258 senoner 542 </p>
4259     <p>Possible Answers:
4260     </p>
4261 schoenebeck 708 <p>
4262     </p>
4263 senoner 542 <blockquote class="text">
4264     <p>LinuxSampler will either answer by returning a comma separated
4265     string with the fill state of all disk stream buffers on that
4266     channel or an empty line if there are no active disk streams or
4267     "NA" for *not available* in case the engine which is deployed
4268     doesn't support disk streaming. Each entry in the answer list
4269     will begin with the stream's ID in brackets followed by the
4270     numerical representation of the fill size (either in bytes or
4271     percentage). Note: due to efficiency reasons the fill states in
4272     the response are not in particular order, thus the front-end has
4273     to sort them by itself if necessary.
4274     </p>
4275 schoenebeck 708 </blockquote><p>
4276 schoenebeck 940
4277 schoenebeck 708 </p>
4278 senoner 542 <p>Examples:
4279     </p>
4280 schoenebeck 708 <p>
4281     </p>
4282 senoner 542 <blockquote class="text">
4283     <p>C: "GET CHANNEL BUFFER_FILL BYTES 4"
4284     </p>
4285     <p>S: "[115]420500,[116]510300,[75]110000,[120]230700"
4286     </p>
4287 schoenebeck 708 </blockquote><p>
4288    
4289     </p>
4290 senoner 542 <blockquote class="text">
4291 schoenebeck 708 <p>C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
4292 senoner 542 </p>
4293     <p>S: "[115]90%,[116]98%,[75]40%,[120]62%"
4294     </p>
4295 schoenebeck 708 </blockquote><p>
4296    
4297     </p>
4298 senoner 542 <blockquote class="text">
4299 schoenebeck 708 <p>C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
4300 senoner 542 </p>
4301     <p>S: ""
4302     </p>
4303 schoenebeck 708 </blockquote><p>
4304 schoenebeck 940
4305 schoenebeck 708 </p>
4306 schoenebeck 940 <a name="SET CHANNEL AUDIO_OUTPUT_DEVICE"></a><br /><hr />
4307 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>
4308     <a name="rfc.section.6.4.14"></a><h3>6.4.14.&nbsp;
4309     Setting audio output device</h3>
4310 senoner 542
4311     <p>The front-end can set the audio output device on a specific sampler
4312     channel by sending the following command:
4313     </p>
4314 schoenebeck 708 <p>
4315     </p>
4316 senoner 542 <blockquote class="text">
4317     <p>SET CHANNEL AUDIO_OUTPUT_DEVICE &lt;sampler-channel&gt; &lt;audio-device-id&gt;
4318     </p>
4319 schoenebeck 708 </blockquote><p>
4320 schoenebeck 940
4321 schoenebeck 708 </p>
4322 schoenebeck 575 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4323 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>
4324     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
4325 schoenebeck 575 &lt;audio-device-id&gt; is the numerical ID of the audio output device as given by the
4326 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>
4327     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>
4328 schoenebeck 575 command.
4329 senoner 542 </p>
4330     <p>Possible Answers:
4331     </p>
4332 schoenebeck 708 <p>
4333     </p>
4334 senoner 542 <blockquote class="text">
4335     <p>"OK" -
4336     </p>
4337     <blockquote class="text">
4338     <p>on success
4339     </p>
4340 schoenebeck 940 </blockquote>
4341    
4342 senoner 542
4343     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4344     </p>
4345     <blockquote class="text">
4346     <p>if audio output device was set, but there are noteworthy
4347     issue(s) related, providing an appropriate warning code and
4348     warning message
4349     </p>
4350 schoenebeck 940 </blockquote>
4351    
4352 senoner 542
4353     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4354     </p>
4355     <blockquote class="text">
4356     <p>in case it failed, providing an appropriate error code and error message
4357     </p>
4358 schoenebeck 940 </blockquote>
4359    
4360 senoner 542
4361 schoenebeck 708 </blockquote><p>
4362 schoenebeck 940
4363 schoenebeck 708 </p>
4364 senoner 542 <p>Examples:
4365     </p>
4366 schoenebeck 708 <p>
4367     </p>
4368 senoner 542 <blockquote class="text">
4369     <p>
4370     </p>
4371 schoenebeck 708 </blockquote><p>
4372 schoenebeck 940
4373 schoenebeck 708 </p>
4374 schoenebeck 974 <a name="SET CHANNEL AUDIO_OUTPUT_TYPE"></a><br /><hr />
4375     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4376     <a name="rfc.section.6.4.15"></a><h3>6.4.15.&nbsp;
4377     Setting audio output type</h3>
4378 senoner 542
4379     <p>DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
4380     </p>
4381     <p>The front-end can alter the audio output type on a specific sampler
4382     channel by sending the following command:
4383     </p>
4384 schoenebeck 708 <p>
4385     </p>
4386 senoner 542 <blockquote class="text">
4387     <p>SET CHANNEL AUDIO_OUTPUT_TYPE &lt;sampler-channel&gt; &lt;audio-output-type&gt;
4388     </p>
4389 schoenebeck 708 </blockquote><p>
4390 schoenebeck 940
4391 schoenebeck 708 </p>
4392 senoner 542 <p>Where &lt;audio-output-type&gt; is currently either "ALSA" or "JACK" and
4393     &lt;sampler-channel&gt; is the respective sampler channel number.
4394     </p>
4395     <p>Possible Answers:
4396     </p>
4397 schoenebeck 708 <p>
4398     </p>
4399 senoner 542 <blockquote class="text">
4400     <p>"OK" -
4401     </p>
4402     <blockquote class="text">
4403     <p>on success
4404     </p>
4405 schoenebeck 940 </blockquote>
4406    
4407 senoner 542
4408     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4409     </p>
4410     <blockquote class="text">
4411     <p>if audio output type was set, but there are noteworthy
4412     issue(s) related, providing an appropriate warning code and
4413     warning message
4414     </p>
4415 schoenebeck 940 </blockquote>
4416    
4417 senoner 542
4418     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4419     </p>
4420     <blockquote class="text">
4421     <p>in case it failed, providing an appropriate error code and error message
4422     </p>
4423 schoenebeck 940 </blockquote>
4424    
4425 senoner 542
4426 schoenebeck 708 </blockquote><p>
4427 schoenebeck 940
4428 schoenebeck 708 </p>
4429 senoner 542 <p>Examples:
4430     </p>
4431 schoenebeck 708 <p>
4432     </p>
4433 senoner 542 <blockquote class="text">
4434     <p>
4435     </p>
4436 schoenebeck 708 </blockquote><p>
4437 schoenebeck 940
4438 schoenebeck 708 </p>
4439 schoenebeck 940 <a name="SET CHANNEL AUDIO_OUTPUT_CHANNEL"></a><br /><hr />
4440 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>
4441     <a name="rfc.section.6.4.16"></a><h3>6.4.16.&nbsp;
4442     Setting audio output channel</h3>
4443 senoner 542
4444     <p>The front-end can alter the audio output channel on a specific
4445     sampler channel by sending the following command:
4446     </p>
4447 schoenebeck 708 <p>
4448     </p>
4449 senoner 542 <blockquote class="text">
4450     <p>SET CHANNEL AUDIO_OUTPUT_CHANNEL &lt;sampler-chan&gt; &lt;audio-out&gt; &lt;audio-in&gt;
4451     </p>
4452 schoenebeck 708 </blockquote><p>
4453 schoenebeck 940
4454 schoenebeck 708 </p>
4455 schoenebeck 575 <p>Where &lt;sampler-chan&gt; is the sampler channel number
4456 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>
4457     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
4458 senoner 542 numerical ID of the sampler channel's audio output channel which should be
4459     rerouted and &lt;audio-in&gt; is the numerical ID of the audio channel of the selected audio
4460     output device where &lt;audio-out&gt; should be routed to.
4461     </p>
4462     <p>Possible Answers:
4463     </p>
4464 schoenebeck 708 <p>
4465     </p>
4466 senoner 542 <blockquote class="text">
4467     <p>"OK" -
4468     </p>
4469     <blockquote class="text">
4470     <p>on success
4471     </p>
4472 schoenebeck 940 </blockquote>
4473    
4474 senoner 542
4475     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4476     </p>
4477     <blockquote class="text">
4478     <p>if audio output channel was set, but there are noteworthy
4479     issue(s) related, providing an appropriate warning code and
4480     warning message
4481     </p>
4482 schoenebeck 940 </blockquote>
4483    
4484 senoner 542
4485     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4486     </p>
4487     <blockquote class="text">
4488     <p>in case it failed, providing an appropriate error code and error message
4489     </p>
4490 schoenebeck 940 </blockquote>
4491    
4492 senoner 542
4493 schoenebeck 708 </blockquote><p>
4494 schoenebeck 940
4495 schoenebeck 708 </p>
4496 senoner 542 <p>Examples:
4497     </p>
4498 schoenebeck 708 <p>
4499     </p>
4500 senoner 542 <blockquote class="text">
4501     <p>
4502     </p>
4503 schoenebeck 708 </blockquote><p>
4504 schoenebeck 940
4505 schoenebeck 708 </p>
4506 schoenebeck 940 <a name="SET CHANNEL MIDI_INPUT_DEVICE"></a><br /><hr />
4507 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>
4508     <a name="rfc.section.6.4.17"></a><h3>6.4.17.&nbsp;
4509     Setting MIDI input device</h3>
4510 senoner 542
4511     <p>The front-end can set the MIDI input device on a specific sampler
4512     channel by sending the following command:
4513     </p>
4514 schoenebeck 708 <p>
4515     </p>
4516 senoner 542 <blockquote class="text">
4517     <p>SET CHANNEL MIDI_INPUT_DEVICE &lt;sampler-channel&gt; &lt;midi-device-id&gt;
4518     </p>
4519 schoenebeck 708 </blockquote><p>
4520 schoenebeck 940
4521 schoenebeck 708 </p>
4522 schoenebeck 575 <p>Where &lt;sampler-channel&gt; is the sampler channel number
4523 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>
4524     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
4525 schoenebeck 575 and &lt;midi-device-id&gt; is the numerical ID of the MIDI input device as returned by the
4526 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>
4527     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.
4528 senoner 542 </p>
4529     <p>Possible Answers:
4530     </p>
4531 schoenebeck 708 <p>
4532     </p>
4533 senoner 542 <blockquote class="text">
4534     <p>"OK" -
4535     </p>
4536     <blockquote class="text">
4537     <p>on success
4538     </p>
4539 schoenebeck 940 </blockquote>
4540    
4541 senoner 542
4542     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4543     </p>
4544     <blockquote class="text">
4545     <p>if MIDI input device was set, but there are noteworthy
4546     issue(s) related, providing an appropriate warning code and
4547     warning message
4548     </p>
4549 schoenebeck 940 </blockquote>
4550    
4551 senoner 542
4552     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4553     </p>
4554     <blockquote class="text">
4555     <p>in case it failed, providing an appropriate error code and error message
4556     </p>
4557 schoenebeck 940 </blockquote>
4558    
4559 senoner 542
4560 schoenebeck 708 </blockquote><p>
4561 schoenebeck 940
4562 schoenebeck 708 </p>
4563 senoner 542 <p>Examples:
4564     </p>
4565 schoenebeck 708 <p>
4566     </p>
4567 senoner 542 <blockquote class="text">
4568     <p>
4569     </p>
4570 schoenebeck 708 </blockquote><p>
4571 schoenebeck 940
4572 schoenebeck 708 </p>
4573 schoenebeck 940 <a name="SET CHANNEL MIDI_INPUT_TYPE"></a><br /><hr />
4574 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>
4575     <a name="rfc.section.6.4.18"></a><h3>6.4.18.&nbsp;
4576     Setting MIDI input type</h3>
4577 senoner 542
4578     <p>DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
4579     </p>
4580     <p>The front-end can alter the MIDI input type on a specific sampler
4581     channel by sending the following command:
4582     </p>
4583 schoenebeck 708 <p>
4584     </p>
4585 senoner 542 <blockquote class="text">
4586     <p>SET CHANNEL MIDI_INPUT_TYPE &lt;sampler-channel&gt; &lt;midi-input-type&gt;
4587     </p>
4588 schoenebeck 708 </blockquote><p>
4589 schoenebeck 940
4590 schoenebeck 708 </p>
4591 senoner 542 <p>Where &lt;midi-input-type&gt; is currently only "ALSA" and
4592     &lt;sampler-channel&gt; is the respective sampler channel number.
4593     </p>
4594     <p>Possible Answers:
4595     </p>
4596 schoenebeck 708 <p>
4597     </p>
4598 senoner 542 <blockquote class="text">
4599     <p>"OK" -
4600     </p>
4601     <blockquote class="text">
4602     <p>on success
4603     </p>
4604 schoenebeck 940 </blockquote>
4605    
4606 senoner 542
4607     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4608     </p>
4609     <blockquote class="text">
4610     <p>if MIDI input type was set, but there are noteworthy
4611     issue(s) related, providing an appropriate warning code and
4612     warning message
4613     </p>
4614 schoenebeck 940 </blockquote>
4615    
4616 senoner 542
4617     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4618     </p>
4619     <blockquote class="text">
4620     <p>in case it failed, providing an appropriate error code and error message
4621     </p>
4622 schoenebeck 940 </blockquote>
4623    
4624 senoner 542
4625 schoenebeck 708 </blockquote><p>
4626 schoenebeck 940
4627 schoenebeck 708 </p>
4628 senoner 542 <p>Examples:
4629     </p>
4630 schoenebeck 708 <p>
4631     </p>
4632 senoner 542 <blockquote class="text">
4633     <p>
4634     </p>
4635 schoenebeck 708 </blockquote><p>
4636 schoenebeck 940
4637 schoenebeck 708 </p>
4638 schoenebeck 940 <a name="SET CHANNEL MIDI_INPUT_PORT"></a><br /><hr />
4639 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>
4640     <a name="rfc.section.6.4.19"></a><h3>6.4.19.&nbsp;
4641     Setting MIDI input port</h3>
4642 senoner 542
4643     <p>The front-end can alter the MIDI input port on a specific sampler
4644     channel by sending the following command:
4645     </p>
4646 schoenebeck 708 <p>
4647     </p>
4648 senoner 542 <blockquote class="text">
4649     <p>SET CHANNEL MIDI_INPUT_PORT &lt;sampler-channel&gt; &lt;midi-input-port&gt;
4650     </p>
4651 schoenebeck 708 </blockquote><p>
4652 schoenebeck 940
4653 schoenebeck 708 </p>
4654 senoner 542 <p>Where &lt;midi-input-port&gt; is a MIDI input port number of the
4655     MIDI input device connected to the sampler channel given by
4656     &lt;sampler-channel&gt;.
4657     </p>
4658     <p>Possible Answers:
4659     </p>
4660 schoenebeck 708 <p>
4661     </p>
4662 senoner 542 <blockquote class="text">
4663     <p>"OK" -
4664     </p>
4665     <blockquote class="text">
4666     <p>on success
4667     </p>
4668 schoenebeck 940 </blockquote>
4669    
4670 senoner 542
4671     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4672     </p>
4673     <blockquote class="text">
4674     <p>if MIDI input port was set, but there are noteworthy
4675     issue(s) related, providing an appropriate warning code and
4676     warning message
4677     </p>
4678 schoenebeck 940 </blockquote>
4679    
4680 senoner 542
4681     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4682     </p>
4683     <blockquote class="text">
4684 schoenebeck 561 <p>in case it failed, providing an appropriate error code and error message
4685 senoner 542 </p>
4686 schoenebeck 940 </blockquote>
4687    
4688 senoner 542
4689 schoenebeck 708 </blockquote><p>
4690 schoenebeck 940
4691 schoenebeck 708 </p>
4692 senoner 542 <p>Examples:
4693     </p>
4694 schoenebeck 708 <p>
4695     </p>
4696 senoner 542 <blockquote class="text">
4697     <p>
4698     </p>
4699 schoenebeck 708 </blockquote><p>
4700 schoenebeck 940
4701 schoenebeck 708 </p>
4702 schoenebeck 940 <a name="SET CHANNEL MIDI_INPUT_CHANNEL"></a><br /><hr />
4703 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>
4704     <a name="rfc.section.6.4.20"></a><h3>6.4.20.&nbsp;
4705     Setting MIDI input channel</h3>
4706 senoner 542
4707     <p>The front-end can alter the MIDI channel a sampler channel should
4708     listen to by sending the following command:
4709     </p>
4710 schoenebeck 708 <p>
4711     </p>
4712 senoner 542 <blockquote class="text">
4713     <p>SET CHANNEL MIDI_INPUT_CHANNEL &lt;sampler-channel&gt; &lt;midi-input-chan&gt;
4714     </p>
4715 schoenebeck 708 </blockquote><p>
4716 schoenebeck 940
4717 schoenebeck 708 </p>
4718 senoner 542 <p>Where &lt;midi-input-chan&gt; is the number of the new MIDI input channel where
4719     &lt;sampler-channel&gt; should listen to or "ALL" to listen on all 16 MIDI
4720     channels.
4721     </p>
4722     <p>Possible Answers:
4723     </p>
4724 schoenebeck 708 <p>
4725     </p>
4726 senoner 542 <blockquote class="text">
4727     <p>"OK" -
4728     </p>
4729     <blockquote class="text">
4730     <p>on success
4731     </p>
4732 schoenebeck 940 </blockquote>
4733    
4734 senoner 542
4735     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4736     </p>
4737     <blockquote class="text">
4738     <p>if MIDI input channel was set, but there are noteworthy
4739     issue(s) related, providing an appropriate warning code and
4740     warning message
4741     </p>
4742 schoenebeck 940 </blockquote>
4743    
4744 senoner 542
4745     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4746     </p>
4747     <blockquote class="text">
4748     <p>in case it failed, providing an appropriate error code and error message
4749     </p>
4750 schoenebeck 940 </blockquote>
4751    
4752 senoner 542
4753 schoenebeck 708 </blockquote><p>
4754 schoenebeck 940
4755 schoenebeck 708 </p>
4756 senoner 542 <p>Examples:
4757     </p>
4758 schoenebeck 708 <p>
4759     </p>
4760 senoner 542 <blockquote class="text">
4761     <p>
4762     </p>
4763 schoenebeck 708 </blockquote><p>
4764 schoenebeck 940
4765 schoenebeck 708 </p>
4766 schoenebeck 940 <a name="SET CHANNEL VOLUME"></a><br /><hr />
4767 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>
4768     <a name="rfc.section.6.4.21"></a><h3>6.4.21.&nbsp;
4769     Setting channel volume</h3>
4770 senoner 542
4771     <p>The front-end can alter the volume of a sampler channel by sending
4772     the following command:
4773     </p>
4774 schoenebeck 708 <p>
4775     </p>
4776 senoner 542 <blockquote class="text">
4777     <p>SET CHANNEL VOLUME &lt;sampler-channel&gt; &lt;volume&gt;
4778     </p>
4779 schoenebeck 708 </blockquote><p>
4780 schoenebeck 940
4781 schoenebeck 708 </p>
4782 senoner 542 <p>Where &lt;volume&gt; is an optionally dotted positive number (a value
4783     smaller than 1.0 means attenuation, whereas a value greater than
4784     1.0 means amplification) and &lt;sampler-channel&gt; defines the sampler
4785     channel where this volume factor should be set.
4786     </p>
4787     <p>Possible Answers:
4788     </p>
4789 schoenebeck 708 <p>
4790     </p>
4791 senoner 542 <blockquote class="text">
4792     <p>"OK" -
4793     </p>
4794     <blockquote class="text">
4795     <p>on success
4796     </p>
4797 schoenebeck 940 </blockquote>
4798    
4799 senoner 542
4800     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4801     </p>
4802     <blockquote class="text">
4803     <p>if channel volume was set, but there are noteworthy
4804     issue(s) related, providing an appropriate warning code and
4805     warning message
4806     </p>
4807 schoenebeck 940 </blockquote>
4808    
4809 senoner 542
4810     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4811     </p>
4812     <blockquote class="text">
4813     <p>in case it failed, providing an appropriate error code and error message
4814     </p>
4815 schoenebeck 940 </blockquote>
4816    
4817 senoner 542
4818 schoenebeck 708 </blockquote><p>
4819 schoenebeck 940
4820 schoenebeck 708 </p>
4821 senoner 542 <p>Examples:
4822     </p>
4823 schoenebeck 708 <p>
4824     </p>
4825 senoner 542 <blockquote class="text">
4826     <p>
4827     </p>
4828 schoenebeck 708 </blockquote><p>
4829 schoenebeck 940
4830 schoenebeck 708 </p>
4831 schoenebeck 940 <a name="SET CHANNEL MUTE"></a><br /><hr />
4832 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>
4833     <a name="rfc.section.6.4.22"></a><h3>6.4.22.&nbsp;
4834     Muting a sampler channel</h3>
4835 senoner 542
4836 schoenebeck 708 <p>The front-end can mute/unmute a specific sampler
4837     channel by sending the following command:
4838     </p>
4839     <p>
4840     </p>
4841     <blockquote class="text">
4842     <p>SET CHANNEL MUTE &lt;sampler-channel&gt; &lt;mute&gt;
4843     </p>
4844     </blockquote><p>
4845 schoenebeck 940
4846 schoenebeck 708 </p>
4847     <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4848 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>
4849     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
4850 schoenebeck 708 &lt;mute&gt; should be replaced either by "1" to mute the channel or "0"
4851     to unmute the channel.
4852     </p>
4853     <p>Possible Answers:
4854     </p>
4855     <p>
4856     </p>
4857     <blockquote class="text">
4858     <p>"OK" -
4859     </p>
4860     <blockquote class="text">
4861     <p>on success
4862     </p>
4863 schoenebeck 940 </blockquote>
4864    
4865 schoenebeck 708
4866     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4867     </p>
4868     <blockquote class="text">
4869     <p>if the channel was muted/unmuted, but there are noteworthy
4870     issue(s) related, providing an appropriate warning code and
4871     warning message
4872     </p>
4873 schoenebeck 940 </blockquote>
4874    
4875 schoenebeck 708
4876     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4877     </p>
4878     <blockquote class="text">
4879     <p>in case it failed, providing an appropriate error code and error message
4880     </p>
4881 schoenebeck 940 </blockquote>
4882    
4883 schoenebeck 708
4884     </blockquote><p>
4885 schoenebeck 940
4886 schoenebeck 708 </p>
4887     <p>Examples:
4888     </p>
4889     <p>
4890     </p>
4891     <blockquote class="text">
4892     <p>
4893     </p>
4894     </blockquote><p>
4895 schoenebeck 940
4896 schoenebeck 708 </p>
4897 schoenebeck 940 <a name="SET CHANNEL SOLO"></a><br /><hr />
4898 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>
4899     <a name="rfc.section.6.4.23"></a><h3>6.4.23.&nbsp;
4900     Soloing a sampler channel</h3>
4901 schoenebeck 708
4902     <p>The front-end can solo/unsolo a specific sampler channel
4903     by sending the following command:
4904     </p>
4905     <p>
4906     </p>
4907     <blockquote class="text">
4908     <p>SET CHANNEL SOLO &lt;sampler-channel&gt; &lt;solo&gt;
4909     </p>
4910     </blockquote><p>
4911 schoenebeck 940
4912 schoenebeck 708 </p>
4913     <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4914 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>
4915     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
4916 schoenebeck 708 &lt;solo&gt; should be replaced either by "1" to solo the channel or "0"
4917     to unsolo the channel.
4918     </p>
4919     <p>Possible Answers:
4920     </p>
4921     <p>
4922     </p>
4923     <blockquote class="text">
4924     <p>"OK" -
4925     </p>
4926     <blockquote class="text">
4927     <p>on success
4928     </p>
4929 schoenebeck 940 </blockquote>
4930    
4931 schoenebeck 708
4932     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4933     </p>
4934     <blockquote class="text">
4935     <p>if the channel was soloed/unsoloed, but there are noteworthy
4936     issue(s) related, providing an appropriate warning code and
4937     warning message
4938     </p>
4939 schoenebeck 940 </blockquote>
4940    
4941 schoenebeck 708
4942     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4943     </p>
4944     <blockquote class="text">
4945     <p>in case it failed, providing an appropriate error code and error message
4946     </p>
4947 schoenebeck 940 </blockquote>
4948    
4949 schoenebeck 708
4950     </blockquote><p>
4951 schoenebeck 940
4952 schoenebeck 708 </p>
4953     <p>Examples:
4954     </p>
4955     <p>
4956     </p>
4957     <blockquote class="text">
4958     <p>
4959     </p>
4960     </blockquote><p>
4961 schoenebeck 940
4962 schoenebeck 708 </p>
4963 schoenebeck 974 <a name="SET CHANNEL MIDI_INSTRUMENT_MAP"></a><br /><hr />
4964     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
4965     <a name="rfc.section.6.4.24"></a><h3>6.4.24.&nbsp;
4966     Assigning a MIDI instrument map to a sampler channel</h3>
4967    
4968     <p>The front-end can assign a MIDI instrument map to a specific sampler channel
4969     by sending the following command:
4970     </p>
4971     <p>
4972     </p>
4973     <blockquote class="text">
4974     <p>SET CHANNEL MIDI_INSTRUMENT_MAP &lt;sampler-channel&gt; &lt;map&gt;
4975     </p>
4976     </blockquote><p>
4977    
4978     </p>
4979     <p>Where &lt;sampler-channel&gt; is the respective sampler channel
4980     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>
4981     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
4982     &lt;map&gt; can have the following possibilites:
4983     </p>
4984     <p>
4985     </p>
4986     <blockquote class="text">
4987     <p>"NONE" -
4988     </p>
4989     <blockquote class="text">
4990     <p>This is the default setting. In this case
4991     the sampler channel is not assigned any MIDI
4992     instrument map and thus will ignore all MIDI
4993     program change messages.
4994     </p>
4995     </blockquote>
4996    
4997    
4998     <p>"DEFAULT" -
4999     </p>
5000     <blockquote class="text">
5001     <p>The sampler channel will always use the
5002     default MIDI instrument map to handle MIDI
5003     program change messages.
5004     </p>
5005     </blockquote>
5006    
5007    
5008     <p>numeric ID -
5009     </p>
5010     <blockquote class="text">
5011     <p>You can assign a specific MIDI instrument map
5012     by replacing &lt;map&gt; with the respective numeric
5013     ID of the MIDI instrument map as returned by the
5014     <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>
5015     command. Once that map will be deleted, the sampler
5016     channel would fall back to "NONE".
5017     </p>
5018     </blockquote>
5019    
5020    
5021     </blockquote><p>
5022    
5023     </p>
5024     <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>
5025     for details regarding MIDI instrument mapping.
5026     </p>
5027     <p>Possible Answers:
5028     </p>
5029     <p>
5030     </p>
5031     <blockquote class="text">
5032     <p>"OK" -
5033     </p>
5034     <blockquote class="text">
5035     <p>on success
5036     </p>
5037     </blockquote>
5038    
5039    
5040     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5041     </p>
5042     <blockquote class="text">
5043     <p>in case it failed, providing an appropriate error code and error message
5044     </p>
5045     </blockquote>
5046    
5047    
5048     </blockquote><p>
5049    
5050     </p>
5051     <p>Examples:
5052     </p>
5053     <p>
5054     </p>
5055     <blockquote class="text">
5056     <p>
5057     </p>
5058     </blockquote><p>
5059    
5060     </p>
5061 schoenebeck 1002 <a name="CREATE FX_SEND"></a><br /><hr />
5062     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5063     <a name="rfc.section.6.4.25"></a><h3>6.4.25.&nbsp;
5064     Adding an effect send to a sampler channel</h3>
5065    
5066     <p>The front-end can create an additional effect send on a specific sampler channel
5067     by sending the following command:
5068     </p>
5069     <p>
5070     </p>
5071     <blockquote class="text">
5072     <p>CREATE FX_SEND &lt;sampler-channel&gt; &lt;midi-ctrl&gt; [&lt;name&gt;]
5073     </p>
5074     </blockquote><p>
5075    
5076     </p>
5077     <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5078     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>
5079     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
5080     sampler channel on which the effect send should be created on, &lt;midi-ctrl&gt;
5081     is a number between 0..127 defining the MIDI controller which can alter the
5082     effect send level and &lt;name&gt; is an optional argument defining a name
5083     for the effect send entity. The name does not have to be unique.
5084     </p>
5085     <p>By default, that is as initial routing, the effect send's audio channels
5086     are automatically routed to the last audio channels of the sampler channel's
5087     audio output device, that way you can i.e. first increase the amount of audio
5088     channels on the audio output device for having dedicated effect send output
5089     channels and when "CREATE FX_SEND" is called, those channels will automatically
5090     be picked. You can alter the destination channels however with
5091     <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>.
5092    
5093     </p>
5094     <p>Note: Create effect sends on a sampler channel only when needed, because having effect
5095     sends on a sampler channel will decrease runtime performance, because for implementing channel
5096     effect sends, separate (sampler channel local) audio buffers are needed to render and mix
5097     the voices and route the audio signal afterwards to the master outputs and effect send
5098     outputs (along with their respective effect send levels). A sampler channel without effect
5099     sends however can mix its voices directly into the audio output devices's audio buffers
5100     and is thus faster.
5101    
5102     </p>
5103     <p>Possible Answers:
5104     </p>
5105     <p>
5106     </p>
5107     <blockquote class="text">
5108     <p>"OK[&lt;fx-send-id&gt;]" -
5109     </p>
5110     <blockquote class="text">
5111     <p>in case a new effect send could be added to the
5112     sampler channel, where &lt;fx-send-id&gt; reflects the
5113     unique ID of the newly created effect send entity
5114     </p>
5115     </blockquote>
5116    
5117    
5118     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5119     </p>
5120     <blockquote class="text">
5121     <p>when a new effect send could not be added, i.e.
5122     due to invalid parameters
5123     </p>
5124     </blockquote>
5125    
5126    
5127     </blockquote><p>
5128    
5129     </p>
5130     <p>Examples:
5131     </p>
5132     <p>
5133     </p>
5134     <blockquote class="text">
5135     <p>C: "CREATE FX_SEND 0 91 'Reverb Send'"
5136     </p>
5137     <p>S: "OK[0]"
5138     </p>
5139     </blockquote><p>
5140    
5141     </p>
5142     <p>
5143     </p>
5144     <blockquote class="text">
5145     <p>C: "CREATE FX_SEND 0 93"
5146     </p>
5147     <p>S: "OK[1]"
5148     </p>
5149     </blockquote><p>
5150    
5151     </p>
5152     <a name="DESTROY FX_SEND"></a><br /><hr />
5153     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5154     <a name="rfc.section.6.4.26"></a><h3>6.4.26.&nbsp;
5155     Removing an effect send from a sampler channel</h3>
5156    
5157     <p>The front-end can remove an existing effect send on a specific sampler channel
5158     by sending the following command:
5159     </p>
5160     <p>
5161     </p>
5162     <blockquote class="text">
5163     <p>DESTROY FX_SEND &lt;sampler-channel&gt; &lt;fx-send-id&gt;
5164     </p>
5165     </blockquote><p>
5166    
5167     </p>
5168     <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5169     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>
5170     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
5171     sampler channel from which the effect send should be removed from and
5172     &lt;fx-send-id&gt; is the respective effect send number as returned by the
5173     <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>
5174     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.
5175     </p>
5176     <p>Possible Answers:
5177     </p>
5178     <p>
5179     </p>
5180     <blockquote class="text">
5181     <p>"OK" -
5182     </p>
5183     <blockquote class="text">
5184     <p>on success
5185     </p>
5186     </blockquote>
5187    
5188    
5189     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5190     </p>
5191     <blockquote class="text">
5192     <p>in case it failed, providing an appropriate error code and
5193     error message
5194     </p>
5195     </blockquote>
5196    
5197    
5198     </blockquote><p>
5199    
5200     </p>
5201     <p>Example:
5202     </p>
5203     <p>
5204     </p>
5205     <blockquote class="text">
5206     <p>C: "DESTROY FX_SEND 0 0"
5207     </p>
5208     <p>S: "OK"
5209     </p>
5210     </blockquote><p>
5211    
5212     </p>
5213     <a name="GET FX_SENDS"></a><br /><hr />
5214     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5215     <a name="rfc.section.6.4.27"></a><h3>6.4.27.&nbsp;
5216     Getting amount of effect sends on a sampler channel</h3>
5217    
5218     <p>The front-end can ask for the amount of effect sends on a specific sampler channel
5219     by sending the following command:
5220     </p>
5221     <p>
5222     </p>
5223     <blockquote class="text">
5224     <p>GET FX_SENDS &lt;sampler-channel&gt;
5225     </p>
5226     </blockquote><p>
5227    
5228     </p>
5229     <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5230     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>
5231     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.
5232     </p>
5233     <p>Possible Answers:
5234     </p>
5235     <p>
5236     </p>
5237     <blockquote class="text">
5238     <p>The sampler will answer by returning the number of effect
5239     sends on the given sampler channel.
5240     </p>
5241     </blockquote><p>
5242    
5243     </p>
5244     <p>Example:
5245     </p>
5246     <p>
5247     </p>
5248     <blockquote class="text">
5249     <p>C: "GET FX_SENDS 0"
5250     </p>
5251     <p>S: "2"
5252     </p>
5253     </blockquote><p>
5254    
5255     </p>
5256     <a name="LIST FX_SENDS"></a><br /><hr />
5257     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5258     <a name="rfc.section.6.4.28"></a><h3>6.4.28.&nbsp;
5259     Listing all effect sends on a sampler channel</h3>
5260    
5261     <p>The front-end can ask for a list of effect sends on a specific sampler channel
5262     by sending the following command:
5263     </p>
5264     <p>
5265     </p>
5266     <blockquote class="text">
5267     <p>LIST FX_SENDS &lt;sampler-channel&gt;
5268     </p>
5269     </blockquote><p>
5270    
5271     </p>
5272     <p>Where &lt;sampler-channel&gt; is the respective sampler channel
5273     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>
5274     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.
5275     </p>
5276     <p>Possible Answers:
5277     </p>
5278     <p>
5279     </p>
5280     <blockquote class="text">
5281     <p>The sampler will answer by returning a comma separated list
5282     with all effect sends' numerical IDs on the given sampler
5283     channel.
5284     </p>
5285     </blockquote><p>
5286    
5287     </p>
5288     <p>Examples:
5289     </p>
5290     <p>
5291     </p>
5292     <blockquote class="text">
5293     <p>C: "LIST FX_SENDS 0"
5294     </p>
5295     <p>S: "0,1"
5296     </p>
5297     </blockquote><p>
5298    
5299     </p>
5300     <p>
5301     </p>
5302     <blockquote class="text">
5303     <p>C: "LIST FX_SENDS 1"
5304     </p>
5305     <p>S: ""
5306     </p>
5307     </blockquote><p>
5308    
5309     </p>
5310     <a name="GET FX_SEND INFO"></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.29"></a><h3>6.4.29.&nbsp;
5313     Getting effect send information</h3>
5314    
5315     <p>The front-end can ask for the current settings of an effect send entity
5316     by sending the following command:
5317     </p>
5318     <p>
5319     </p>
5320     <blockquote class="text">
5321     <p>GET FX_SEND INFO &lt;sampler-channel&gt; &lt;fx-send-id&gt;
5322     </p>
5323     </blockquote><p>
5324    
5325     </p>
5326     <p>Where &lt;sampler-channel&gt; is the sampler channel number
5327     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 and
5329     &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5330     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>
5331     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.
5332    
5333     </p>
5334     <p>Possible Answers:
5335     </p>
5336     <p>
5337     </p>
5338     <blockquote class="text">
5339     <p>The sampler will answer by sending a &lt;CRLF&gt; separated list.
5340     Each answer line begins with the settings category name
5341     followed by a colon and then a space character &lt;SP&gt; and finally
5342     the info character string to that setting category. At the
5343     moment the following categories are defined:
5344     </p>
5345     <p>
5346     </p>
5347     <blockquote class="text">
5348     <p>NAME -
5349     </p>
5350     <blockquote class="text">
5351     <p>name of the effect send entity
5352     </p>
5353     </blockquote>
5354    
5355    
5356 schoenebeck 1028 <p>MIDI_CONTROLLER -
5357     </p>
5358     <blockquote class="text">
5359     <p>a value between 0 and 127 reflecting the MIDI controller
5360     which is able to modify the effect send's send level
5361     </p>
5362     </blockquote>
5363    
5364    
5365     <p>LEVEL -
5366     </p>
5367     <blockquote class="text">
5368     <p>optionally dotted number reflecting the effect send's
5369     current send level (where a value &lt; 1.0 means attenuation
5370     and a value > 1.0 means amplification)
5371     </p>
5372     </blockquote>
5373    
5374    
5375 schoenebeck 1002 <p>AUDIO_OUTPUT_ROUTING -
5376     </p>
5377     <blockquote class="text">
5378     <p>comma separated list which reflects to which audio
5379     channel of the selected audio output device each
5380     effect send output channel is routed to, e.g. "0,3" would
5381     mean the effect send's output channel 0 is routed to channel
5382     0 of the audio output device and the effect send's output
5383     channel 1 is routed to the channel 3 of the audio
5384     output device (see
5385     <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>
5386     for details)
5387     </p>
5388     </blockquote>
5389    
5390    
5391     </blockquote>
5392    
5393    
5394     </blockquote><p>
5395    
5396     </p>
5397     <p>The mentioned fields above don't have to be in particular order.
5398     </p>
5399     <p>Example:
5400     </p>
5401     <p>
5402     </p>
5403     <blockquote class="text">
5404     <p>C: "GET FX_SEND INFO 0 0"
5405     </p>
5406     <p>S: "NAME: Reverb Send"
5407     </p>
5408 schoenebeck 1028 <p>&nbsp;&nbsp;&nbsp;"MIDI_CONTROLLER: 91"
5409     </p>
5410     <p>&nbsp;&nbsp;&nbsp;"LEVEL: 0.3"
5411     </p>
5412 schoenebeck 1002 <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 2,3"
5413     </p>
5414     <p>&nbsp;&nbsp;&nbsp;"."
5415     </p>
5416     </blockquote><p>
5417    
5418     </p>
5419 iliev 1137 <a name="SET FX_SEND NAME"></a><br /><hr />
5420     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5421     <a name="rfc.section.6.4.30"></a><h3>6.4.30.&nbsp;
5422     Changing effect send's name</h3>
5423    
5424     <p>The front-end can alter the current name of an effect
5425     send entity by sending the following command:
5426     </p>
5427     <p>
5428     </p>
5429     <blockquote class="text">
5430     <p>SET FX_SEND NAME &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;name&gt;
5431     </p>
5432     </blockquote><p>
5433    
5434     </p>
5435     <p>Where &lt;sampler-chan&gt; is the sampler channel number
5436     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>
5437     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,
5438     &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5439     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>
5440     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
5441     &lt;name&gt; is the new name of the effect send entity, which
5442     does not have to be unique.
5443     </p>
5444     <p>Possible Answers:
5445     </p>
5446     <p>
5447     </p>
5448     <blockquote class="text">
5449     <p>"OK" -
5450     </p>
5451     <blockquote class="text">
5452     <p>on success
5453     </p>
5454     </blockquote>
5455    
5456    
5457     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5458     </p>
5459     <blockquote class="text">
5460     <p>in case it failed, providing an appropriate error code and error message
5461     </p>
5462     </blockquote>
5463    
5464    
5465     </blockquote><p>
5466    
5467     </p>
5468     <p>Example:
5469     </p>
5470     <p>
5471     </p>
5472     <blockquote class="text">
5473     <p>C: "SET FX_SEND NAME 0 0 'Fx Send 1'"
5474     </p>
5475     <p>S: "OK"
5476     </p>
5477     </blockquote><p>
5478    
5479     </p>
5480 schoenebeck 1002 <a name="SET FX_SEND AUDIO_OUTPUT_CHANNEL"></a><br /><hr />
5481     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5482 iliev 1137 <a name="rfc.section.6.4.31"></a><h3>6.4.31.&nbsp;
5483 schoenebeck 1002 Altering effect send's audio routing</h3>
5484    
5485     <p>The front-end can alter the destination of an effect send's audio channel on a specific
5486     sampler channel by sending the following command:
5487     </p>
5488     <p>
5489     </p>
5490     <blockquote class="text">
5491     <p>SET FX_SEND AUDIO_OUTPUT_CHANNEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;audio-src&gt; &lt;audio-dst&gt;
5492     </p>
5493     </blockquote><p>
5494    
5495     </p>
5496     <p>Where &lt;sampler-chan&gt; is the sampler channel number
5497     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>
5498     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,
5499     &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5500     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>
5501     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,
5502     &lt;audio-src&gt; is the numerical ID of the effect send's audio channel
5503     which should be rerouted and &lt;audio-dst&gt; is the numerical ID of
5504     the audio channel of the selected audio output device where &lt;audio-src&gt;
5505     should be routed to.
5506     </p>
5507     <p>Note that effect sends can only route audio to the same audio output
5508     device as assigned to the effect send's sampler channel. Also note that an
5509     effect send entity does always have exactly as much audio channels as its
5510     sampler channel. So if the sampler channel is stereo, the effect send does
5511     have two audio channels as well. Also keep in mind that the amount of audio
5512     channels on a sampler channel might be dependant not only to the deployed
5513     sampler engine on the sampler channel, but also dependant to the instrument
5514     currently loaded. However you can (effectively) turn an i.e. stereo effect
5515     send into a mono one by simply altering its audio routing appropriately.
5516     </p>
5517     <p>Possible Answers:
5518     </p>
5519     <p>
5520     </p>
5521     <blockquote class="text">
5522     <p>"OK" -
5523     </p>
5524     <blockquote class="text">
5525     <p>on success
5526     </p>
5527     </blockquote>
5528    
5529    
5530     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5531     </p>
5532     <blockquote class="text">
5533     <p>if audio output channel was set, but there are noteworthy
5534     issue(s) related, providing an appropriate warning code and
5535     warning message
5536     </p>
5537     </blockquote>
5538    
5539    
5540     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5541     </p>
5542     <blockquote class="text">
5543     <p>in case it failed, providing an appropriate error code and error message
5544     </p>
5545     </blockquote>
5546    
5547    
5548     </blockquote><p>
5549    
5550     </p>
5551     <p>Example:
5552     </p>
5553     <p>
5554     </p>
5555     <blockquote class="text">
5556     <p>C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2"
5557     </p>
5558     <p>S: "OK"
5559     </p>
5560     </blockquote><p>
5561    
5562     </p>
5563 schoenebeck 1028 <a name="SET FX_SEND MIDI_CONTROLLER"></a><br /><hr />
5564     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5565 iliev 1137 <a name="rfc.section.6.4.32"></a><h3>6.4.32.&nbsp;
5566 schoenebeck 1028 Altering effect send's MIDI controller</h3>
5567    
5568     <p>The front-end can alter the MIDI controller of an effect
5569     send entity by sending the following command:
5570     </p>
5571     <p>
5572     </p>
5573     <blockquote class="text">
5574     <p>SET FX_SEND MIDI_CONTROLLER &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;midi-ctrl&gt;
5575     </p>
5576     </blockquote><p>
5577    
5578     </p>
5579     <p>Where &lt;sampler-chan&gt; is the sampler channel number
5580     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>
5581     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,
5582     &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5583     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>
5584     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
5585     &lt;midi-ctrl&gt; reflects the MIDI controller which shall be
5586     able to modify the effect send's send level.
5587     </p>
5588     <p>Possible Answers:
5589     </p>
5590     <p>
5591     </p>
5592     <blockquote class="text">
5593     <p>"OK" -
5594     </p>
5595     <blockquote class="text">
5596     <p>on success
5597     </p>
5598     </blockquote>
5599    
5600    
5601     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5602     </p>
5603     <blockquote class="text">
5604     <p>if MIDI controller was set, but there are noteworthy
5605     issue(s) related, providing an appropriate warning code and
5606     warning message
5607     </p>
5608     </blockquote>
5609    
5610    
5611     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5612     </p>
5613     <blockquote class="text">
5614     <p>in case it failed, providing an appropriate error code and error message
5615     </p>
5616     </blockquote>
5617    
5618    
5619     </blockquote><p>
5620    
5621     </p>
5622     <p>Example:
5623     </p>
5624     <p>
5625     </p>
5626     <blockquote class="text">
5627     <p>C: "SET FX_SEND MIDI_CONTROLLER 0 0 91"
5628     </p>
5629     <p>S: "OK"
5630     </p>
5631     </blockquote><p>
5632    
5633     </p>
5634     <a name="SET FX_SEND LEVEL"></a><br /><hr />
5635     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5636 iliev 1137 <a name="rfc.section.6.4.33"></a><h3>6.4.33.&nbsp;
5637 schoenebeck 1028 Altering effect send's send level</h3>
5638    
5639     <p>The front-end can alter the current send level of an effect
5640     send entity by sending the following command:
5641     </p>
5642     <p>
5643     </p>
5644     <blockquote class="text">
5645     <p>SET FX_SEND LEVEL &lt;sampler-chan&gt; &lt;fx-send-id&gt; &lt;volume&gt;
5646     </p>
5647     </blockquote><p>
5648    
5649     </p>
5650     <p>Where &lt;sampler-chan&gt; is the sampler channel number
5651     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>
5652     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,
5653     &lt;fx-send-id&gt; reflects the numerical ID of the effect send entity
5654     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>
5655     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
5656     &lt;volume&gt; is an optionally dotted positive number (a value
5657     smaller than 1.0 means attenuation, whereas a value greater than
5658     1.0 means amplification) reflecting the new send level.
5659     </p>
5660     <p>Possible Answers:
5661     </p>
5662     <p>
5663     </p>
5664     <blockquote class="text">
5665     <p>"OK" -
5666     </p>
5667     <blockquote class="text">
5668     <p>on success
5669     </p>
5670     </blockquote>
5671    
5672    
5673     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5674     </p>
5675     <blockquote class="text">
5676     <p>if new send level was set, but there are noteworthy
5677     issue(s) related, providing an appropriate warning code and
5678     warning message
5679     </p>
5680     </blockquote>
5681    
5682    
5683     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5684     </p>
5685     <blockquote class="text">
5686     <p>in case it failed, providing an appropriate error code and error message
5687     </p>
5688     </blockquote>
5689    
5690    
5691     </blockquote><p>
5692    
5693     </p>
5694     <p>Example:
5695     </p>
5696     <p>
5697     </p>
5698     <blockquote class="text">
5699     <p>C: "SET FX_SEND LEVEL 0 0 0.15"
5700     </p>
5701     <p>S: "OK"
5702     </p>
5703     </blockquote><p>
5704    
5705     </p>
5706 schoenebeck 940 <a name="RESET CHANNEL"></a><br /><hr />
5707 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>
5708 iliev 1137 <a name="rfc.section.6.4.34"></a><h3>6.4.34.&nbsp;
5709 schoenebeck 974 Resetting a sampler channel</h3>
5710 schoenebeck 708
5711 senoner 542 <p>The front-end can reset a particular sampler channel by sending the following command:
5712     </p>
5713 schoenebeck 708 <p>
5714     </p>
5715 senoner 542 <blockquote class="text">
5716     <p>RESET CHANNEL &lt;sampler-channel&gt;
5717     </p>
5718 schoenebeck 708 </blockquote><p>
5719 schoenebeck 940
5720 schoenebeck 708 </p>
5721 senoner 542 <p>
5722     Where &lt;sampler-channel&gt; defines the sampler channel to be reset.
5723     This will cause the engine on that sampler channel, its voices and
5724     eventually disk streams and all control and status variables to be
5725     reset.
5726     </p>
5727     <p>Possible Answers:
5728     </p>
5729 schoenebeck 708 <p>
5730     </p>
5731 senoner 542 <blockquote class="text">
5732     <p>"OK" -
5733     </p>
5734     <blockquote class="text">
5735     <p>on success
5736     </p>
5737 schoenebeck 940 </blockquote>
5738    
5739 senoner 542
5740     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5741     </p>
5742     <blockquote class="text">
5743     <p>if channel was reset, but there are noteworthy issue(s)
5744     related, providing an appropriate warning code and warning
5745     message
5746     </p>
5747 schoenebeck 940 </blockquote>
5748    
5749 senoner 542
5750     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5751     </p>
5752     <blockquote class="text">
5753     <p>in case it failed, providing an appropriate error code and
5754     error message
5755     </p>
5756 schoenebeck 940 </blockquote>
5757    
5758 senoner 542
5759 schoenebeck 708 </blockquote><p>
5760 schoenebeck 940
5761 schoenebeck 708 </p>
5762 senoner 542 <p>Examples:
5763     </p>
5764 schoenebeck 708 <p>
5765     </p>
5766 senoner 542 <blockquote class="text">
5767     <p>
5768     </p>
5769 schoenebeck 708 </blockquote><p>
5770 schoenebeck 940
5771 schoenebeck 708 </p>
5772 schoenebeck 940 <a name="anchor12"></a><br /><hr />
5773 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>
5774     <a name="rfc.section.6.5"></a><h3>6.5.&nbsp;
5775     Controlling connection</h3>
5776 senoner 542
5777     <p>The following commands are used to control the connection to LinuxSampler.
5778     </p>
5779 schoenebeck 940 <a name="SUBSCRIBE"></a><br /><hr />
5780 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>
5781     <a name="rfc.section.6.5.1"></a><h3>6.5.1.&nbsp;
5782     Register front-end for receiving event messages</h3>
5783 senoner 542
5784     <p>The front-end can register itself to the LinuxSampler application to
5785     be informed about noteworthy events by sending this command:
5786     </p>
5787 schoenebeck 708 <p>
5788     </p>
5789 senoner 542 <blockquote class="text">
5790     <p>SUBSCRIBE &lt;event-id&gt;
5791     </p>
5792 schoenebeck 708 </blockquote><p>
5793 schoenebeck 940
5794 schoenebeck 708 </p>
5795 senoner 542 <p>where &lt;event-id&gt; will be replaced by the respective event that
5796     client wants to subscribe to.
5797     </p>
5798     <p>Possible Answers:
5799     </p>
5800 schoenebeck 708 <p>
5801     </p>
5802 senoner 542 <blockquote class="text">
5803     <p>"OK" -
5804     </p>
5805     <blockquote class="text">
5806     <p>on success
5807     </p>
5808 schoenebeck 940 </blockquote>
5809    
5810 senoner 542
5811     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5812     </p>
5813     <blockquote class="text">
5814     <p>if registration succeeded, but there are noteworthy
5815     issue(s) related, providing an appropriate warning code and
5816     warning message
5817     </p>
5818 schoenebeck 940 </blockquote>
5819    
5820 senoner 542
5821     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5822     </p>
5823     <blockquote class="text">
5824     <p>in case it failed, providing an appropriate error code and
5825     error message
5826     </p>
5827 schoenebeck 940 </blockquote>
5828    
5829 senoner 542
5830 schoenebeck 708 </blockquote><p>
5831 schoenebeck 940
5832 schoenebeck 708 </p>
5833 senoner 542 <p>Examples:
5834     </p>
5835 schoenebeck 708 <p>
5836     </p>
5837 senoner 542 <blockquote class="text">
5838     <p>
5839     </p>
5840 schoenebeck 708 </blockquote><p>
5841 schoenebeck 940
5842 schoenebeck 708 </p>
5843 schoenebeck 940 <a name="UNSUBSCRIBE"></a><br /><hr />
5844 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>
5845     <a name="rfc.section.6.5.2"></a><h3>6.5.2.&nbsp;
5846     Unregister front-end for not receiving event messages</h3>
5847 senoner 542
5848     <p>The front-end can unregister itself if it doesn't want to receive event
5849     messages anymore by sending the following command:
5850     </p>
5851 schoenebeck 708 <p>
5852     </p>
5853 senoner 542 <blockquote class="text">
5854     <p>UNSUBSCRIBE &lt;event-id&gt;
5855     </p>
5856 schoenebeck 708 </blockquote><p>
5857 schoenebeck 940
5858 schoenebeck 708 </p>
5859 senoner 542 <p>Where &lt;event-id&gt; will be replaced by the respective event that
5860     client doesn't want to receive anymore.
5861     </p>
5862     <p>Possible Answers:
5863     </p>
5864 schoenebeck 708 <p>
5865     </p>
5866 senoner 542 <blockquote class="text">
5867     <p>"OK" -
5868     </p>
5869     <blockquote class="text">
5870     <p>on success
5871     </p>
5872 schoenebeck 940 </blockquote>
5873    
5874 senoner 542
5875     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
5876     </p>
5877     <blockquote class="text">
5878     <p>if unregistration succeeded, but there are noteworthy
5879     issue(s) related, providing an appropriate warning code and
5880     warning message
5881     </p>
5882 schoenebeck 940 </blockquote>
5883    
5884 senoner 542
5885     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5886     </p>
5887     <blockquote class="text">
5888     <p>in case it failed, providing an appropriate error code and
5889     error message
5890     </p>
5891 schoenebeck 940 </blockquote>
5892    
5893 senoner 542
5894 schoenebeck 708 </blockquote><p>
5895 schoenebeck 940
5896 schoenebeck 708 </p>
5897 senoner 542 <p>Examples:
5898     </p>
5899 schoenebeck 708 <p>
5900     </p>
5901 senoner 542 <blockquote class="text">
5902     <p>
5903     </p>
5904 schoenebeck 708 </blockquote><p>
5905 schoenebeck 940
5906 schoenebeck 708 </p>
5907 schoenebeck 940 <a name="SET ECHO"></a><br /><hr />
5908 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>
5909     <a name="rfc.section.6.5.3"></a><h3>6.5.3.&nbsp;
5910     Enable or disable echo of commands</h3>
5911 senoner 542
5912     <p>To enable or disable back sending of commands to the client the following command can be used:
5913     </p>
5914 schoenebeck 708 <p>
5915     </p>
5916 senoner 542 <blockquote class="text">
5917     <p>SET ECHO &lt;value&gt;
5918     </p>
5919 schoenebeck 708 </blockquote><p>
5920 schoenebeck 940
5921 schoenebeck 708 </p>
5922 senoner 542 <p>Where &lt;value&gt; should be replaced either by "1" to enable echo mode
5923     or "0" to disable echo mode. When echo mode is enabled, all
5924     commands send to LinuxSampler will be immediately send back and
5925     after this echo the actual response to the command will be
5926     returned. Echo mode will only be altered for the client connection
5927     that issued the "SET ECHO" command, not globally for all client
5928     connections.
5929     </p>
5930     <p>Possible Answers:
5931     </p>
5932 schoenebeck 708 <p>
5933     </p>
5934 senoner 542 <blockquote class="text">
5935     <p>"OK" -
5936     </p>
5937     <blockquote class="text">
5938     <p>usually
5939     </p>
5940 schoenebeck 940 </blockquote>
5941    
5942 senoner 542
5943     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5944     </p>
5945     <blockquote class="text">
5946     <p>on syntax error, e.g. non boolean value
5947     </p>
5948 schoenebeck 940 </blockquote>
5949    
5950 senoner 542
5951 schoenebeck 708 </blockquote><p>
5952 schoenebeck 940
5953 schoenebeck 708 </p>
5954 senoner 542 <p>Examples:
5955     </p>
5956 schoenebeck 708 <p>
5957     </p>
5958 senoner 542 <blockquote class="text">
5959     <p>
5960     </p>
5961 schoenebeck 708 </blockquote><p>
5962 schoenebeck 940
5963 schoenebeck 708 </p>
5964 schoenebeck 940 <a name="QUIT"></a><br /><hr />
5965 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>
5966     <a name="rfc.section.6.5.4"></a><h3>6.5.4.&nbsp;
5967     Close client connection</h3>
5968 senoner 542
5969     <p>The client can close its network connection to LinuxSampler by sending the following command:
5970     </p>
5971 schoenebeck 708 <p>
5972     </p>
5973 senoner 542 <blockquote class="text">
5974     <p>QUIT
5975     </p>
5976 schoenebeck 708 </blockquote><p>
5977 schoenebeck 940
5978 schoenebeck 708 </p>
5979 senoner 542 <p>This is probably more interesting for manual telnet connections to
5980     LinuxSampler than really useful for a front-end implementation.
5981     </p>
5982 schoenebeck 940 <a name="anchor13"></a><br /><hr />
5983 schoenebeck 974 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
5984     <a name="rfc.section.6.6"></a><h3>6.6.&nbsp;
5985     Global commands</h3>
5986 senoner 542
5987     <p>The following commands have global impact on the sampler.
5988     </p>
5989 schoenebeck 940 <a name="GET TOTAL_VOICE_COUNT"></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.6.1"></a><h3>6.6.1.&nbsp;
5992     Current number of active voices</h3>
5993 senoner 542
5994 schoenebeck 940 <p>The front-end can ask for the current number of active voices on
5995     the sampler by sending the following command:
5996     </p>
5997     <p>
5998     </p>
5999     <blockquote class="text">
6000     <p>GET TOTAL_VOICE_COUNT
6001     </p>
6002     </blockquote><p>
6003    
6004     </p>
6005     <p>Possible Answers:
6006     </p>
6007     <p>
6008     </p>
6009     <blockquote class="text">
6010     <p>LinuxSampler will answer by returning the number of all active
6011     voices on the sampler.
6012     </p>
6013     </blockquote><p>
6014    
6015     </p>
6016     <a name="GET TOTAL_VOICE_COUNT_MAX"></a><br /><hr />
6017 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>
6018     <a name="rfc.section.6.6.2"></a><h3>6.6.2.&nbsp;
6019     Maximum amount of active voices</h3>
6020 schoenebeck 940
6021     <p>The front-end can ask for the maximum number of active voices
6022     by sending the following command:
6023     </p>
6024     <p>
6025     </p>
6026     <blockquote class="text">
6027     <p>GET TOTAL_VOICE_COUNT_MAX
6028     </p>
6029     </blockquote><p>
6030    
6031     </p>
6032     <p>Possible Answers:
6033     </p>
6034     <p>
6035     </p>
6036     <blockquote class="text">
6037     <p>LinuxSampler will answer by returning the maximum number
6038     of active voices.
6039     </p>
6040     </blockquote><p>
6041    
6042     </p>
6043     <a name="RESET"></a><br /><hr />
6044 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>
6045     <a name="rfc.section.6.6.3"></a><h3>6.6.3.&nbsp;
6046     Reset sampler</h3>
6047 schoenebeck 940
6048 senoner 542 <p>The front-end can reset the whole sampler by sending the following command:
6049     </p>
6050 schoenebeck 708 <p>
6051     </p>
6052 senoner 542 <blockquote class="text">
6053     <p>RESET
6054     </p>
6055 schoenebeck 708 </blockquote><p>
6056 schoenebeck 940
6057 schoenebeck 708 </p>
6058 senoner 542 <p>Possible Answers:
6059     </p>
6060 schoenebeck 708 <p>
6061     </p>
6062 senoner 542 <blockquote class="text">
6063     <p>"OK" -
6064     </p>
6065     <blockquote class="text">
6066     <p>always
6067     </p>
6068 schoenebeck 940 </blockquote>
6069    
6070 senoner 542
6071 schoenebeck 708 </blockquote><p>
6072 schoenebeck 940
6073 schoenebeck 708 </p>
6074 senoner 542 <p>Examples:
6075     </p>
6076 schoenebeck 708 <p>
6077     </p>
6078 senoner 542 <blockquote class="text">
6079     <p>
6080     </p>
6081 schoenebeck 708 </blockquote><p>
6082 schoenebeck 940
6083 schoenebeck 708 </p>
6084 schoenebeck 940 <a name="GET SERVER INFO"></a><br /><hr />
6085 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>
6086     <a name="rfc.section.6.6.4"></a><h3>6.6.4.&nbsp;
6087     General sampler informations</h3>
6088 schoenebeck 575
6089     <p>The client can ask for general informations about the LinuxSampler
6090     instance by sending the following command:
6091     </p>
6092 schoenebeck 708 <p>
6093     </p>
6094 schoenebeck 575 <blockquote class="text">
6095     <p>GET SERVER INFO
6096     </p>
6097 schoenebeck 708 </blockquote><p>
6098 schoenebeck 940
6099 schoenebeck 708 </p>
6100 schoenebeck 575 <p>Possible Answers:
6101     </p>
6102 schoenebeck 708 <p>
6103     </p>
6104 schoenebeck 575 <blockquote class="text">
6105     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6106     Each answer line begins with the information category name
6107     followed by a colon and then a space character &lt;SP&gt; and finally
6108     the info character string to that information category. At the
6109     moment the following categories are defined:
6110 schoenebeck 940
6111 schoenebeck 575 </p>
6112 schoenebeck 708 <p>
6113     </p>
6114 schoenebeck 575 <blockquote class="text">
6115     <p>DESCRIPTION -
6116     </p>
6117     <blockquote class="text">
6118     <p>arbitrary textual description about the sampler
6119     </p>
6120 schoenebeck 940 </blockquote>
6121    
6122 schoenebeck 575
6123     <p>VERSION -
6124     </p>
6125     <blockquote class="text">
6126     <p>version of the sampler
6127     </p>
6128 schoenebeck 940 </blockquote>
6129    
6130 schoenebeck 575
6131     <p>PROTOCOL_VERSION -
6132     </p>
6133     <blockquote class="text">
6134     <p>version of the LSCP specification the sampler
6135 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)
6136 schoenebeck 575 </p>
6137 schoenebeck 940 </blockquote>
6138    
6139 schoenebeck 575
6140 iliev 1162 <p>INSTRUMENTS_DB_SUPPORT -
6141     </p>
6142     <blockquote class="text">
6143     <p>either yes or no, specifies whether the
6144     sampler is build with instruments database support.
6145     </p>
6146 schoenebeck 940 </blockquote>
6147 iliev 1162
6148    
6149     </blockquote>
6150 schoenebeck 940
6151 schoenebeck 575
6152 schoenebeck 708 </blockquote><p>
6153 schoenebeck 940
6154 schoenebeck 708 </p>
6155 schoenebeck 575 <p>The mentioned fields above don't have to be in particular order.
6156     Other fields might be added in future.
6157     </p>
6158 schoenebeck 1006 <a name="GET VOLUME"></a><br /><hr />
6159     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6160     <a name="rfc.section.6.6.5"></a><h3>6.6.5.&nbsp;
6161     Getting global volume attenuation</h3>
6162    
6163     <p>The client can ask for the current global sampler-wide volume
6164     attenuation by sending the following command:
6165     </p>
6166     <p>
6167     </p>
6168     <blockquote class="text">
6169     <p>GET VOLUME
6170     </p>
6171     </blockquote><p>
6172    
6173     </p>
6174     <p>Possible Answers:
6175     </p>
6176     <p>
6177     </p>
6178     <blockquote class="text">
6179     <p>The sampler will always answer by returning the optional
6180     dotted floating point coefficient, reflecting the current
6181     global volume attenuation.
6182    
6183     </p>
6184     </blockquote><p>
6185    
6186     </p>
6187     <p>Note: it is up to the respective sampler engine whether to obey
6188     that global volume parameter or not, but in general all engines SHOULD
6189     use this parameter.
6190     </p>
6191     <a name="SET VOLUME"></a><br /><hr />
6192     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6193     <a name="rfc.section.6.6.6"></a><h3>6.6.6.&nbsp;
6194     Setting global volume attenuation</h3>
6195    
6196     <p>The client can alter the current global sampler-wide volume
6197     attenuation by sending the following command:
6198     </p>
6199     <p>
6200     </p>
6201     <blockquote class="text">
6202     <p>SET VOLUME &lt;volume&gt;
6203     </p>
6204     </blockquote><p>
6205    
6206     </p>
6207     <p>Where &lt;volume&gt; should be replaced by the optional dotted
6208     floating point value, reflecting the new global volume parameter.
6209     This value might usually be in the range between 0.0 and 1.0, that
6210     is for attenuating the overall volume.
6211     </p>
6212     <p>Possible Answers:
6213     </p>
6214     <p>
6215     </p>
6216     <blockquote class="text">
6217     <p>"OK" -
6218     </p>
6219     <blockquote class="text">
6220     <p>on success
6221     </p>
6222     </blockquote>
6223    
6224    
6225     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6226     </p>
6227     <blockquote class="text">
6228     <p>if the global volume was set, but there are noteworthy
6229     issue(s) related, providing an appropriate warning code and
6230     warning message
6231     </p>
6232     </blockquote>
6233    
6234    
6235     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6236     </p>
6237     <blockquote class="text">
6238     <p>in case it failed, providing an appropriate error code and error message
6239     </p>
6240     </blockquote>
6241    
6242    
6243     </blockquote><p>
6244    
6245     </p>
6246 schoenebeck 974 <a name="MIDI Instrument Mapping"></a><br /><hr />
6247     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6248     <a name="rfc.section.6.7"></a><h3>6.7.&nbsp;
6249     MIDI Instrument Mapping</h3>
6250 schoenebeck 945
6251     <p>The MIDI protocol provides a way to switch between instruments
6252     by sending so called MIDI bank select and MIDI program change
6253     messages which are essentially just numbers. The following commands
6254     allow to actually map arbitrary MIDI bank select / program change
6255     numbers with real instruments.
6256     </p>
6257 schoenebeck 974 <p>The sampler allows to manage an arbitrary amount of MIDI
6258     instrument maps which define which instrument to load on
6259     which MIDI program change message.
6260 schoenebeck 945 </p>
6261 schoenebeck 974 <p>By default, that is when the sampler is launched, there is no
6262     map, thus the sampler will simply ignore all program change
6263     messages. The front-end has to explicitly create at least one
6264     map, add entries to the map and tell the respective sampler
6265     channel(s) which MIDI instrument map to use, so the sampler
6266     knows how to react on a given program change message on the
6267     respective sampler channel, that is by switching to the
6268     respectively defined engine type and loading the respective
6269     instrument. See command
6270     <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>
6271     for how to assign a MIDI instrument map to a sampler channel.
6272     </p>
6273 schoenebeck 945 <p>Also note per MIDI specification a bank select message does not
6274     cause to switch to another instrument. Instead when receiving a
6275     bank select message the bank value will be stored and a subsequent
6276     program change message (which may occur at any time) will finally
6277     cause the sampler to switch to the respective instrument as
6278     reflected by the current MIDI instrument map.
6279     </p>
6280 schoenebeck 974 <a name="ADD MIDI_INSTRUMENT MAP"></a><br /><hr />
6281     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6282     <a name="rfc.section.6.7.1"></a><h3>6.7.1.&nbsp;
6283     Create a new MIDI instrument map</h3>
6284    
6285     <p>The front-end can add a new MIDI instrument map by sending
6286     the following command:
6287     </p>
6288     <p>
6289     </p>
6290     <blockquote class="text">
6291     <p>ADD MIDI_INSTRUMENT_MAP [&lt;name&gt;]
6292     </p>
6293     </blockquote><p>
6294    
6295     </p>
6296     <p>Where &lt;name&gt; is an optional argument allowing to
6297     assign a custom name to the new map. MIDI instrument Map
6298     names do not have to be unique.
6299     </p>
6300     <p>Possible Answers:
6301     </p>
6302     <p>
6303     </p>
6304     <blockquote class="text">
6305     <p>"OK[&lt;map&gt;]" -
6306     </p>
6307     <blockquote class="text">
6308     <p>in case a new MIDI instrument map could
6309     be added, where &lt;map&gt; reflects the
6310     unique ID of the newly created MIDI
6311     instrument map
6312     </p>
6313     </blockquote>
6314    
6315    
6316     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6317     </p>
6318     <blockquote class="text">
6319     <p>when a new map could not be created, which
6320     might never occur in practice
6321     </p>
6322     </blockquote>
6323    
6324    
6325     </blockquote><p>
6326    
6327     </p>
6328     <p>Examples:
6329     </p>
6330     <p>
6331     </p>
6332     <blockquote class="text">
6333     <p>C: "ADD MIDI_INSTRUMENT_MAP 'Standard Map'"
6334     </p>
6335     <p>S: "OK[0]"
6336     </p>
6337     </blockquote><p>
6338    
6339     </p>
6340     <p>
6341     </p>
6342     <blockquote class="text">
6343     <p>C: "ADD MIDI_INSTRUMENT_MAP 'Standard Drumkit'"
6344     </p>
6345     <p>S: "OK[1]"
6346     </p>
6347     </blockquote><p>
6348    
6349     </p>
6350     <p>
6351     </p>
6352     <blockquote class="text">
6353     <p>C: "ADD MIDI_INSTRUMENT_MAP"
6354     </p>
6355     <p>S: "OK[5]"
6356     </p>
6357     </blockquote><p>
6358    
6359     </p>
6360     <a name="REMOVE MIDI_INSTRUMENT_MAP"></a><br /><hr />
6361     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6362     <a name="rfc.section.6.7.2"></a><h3>6.7.2.&nbsp;
6363     Delete one particular or all MIDI instrument maps</h3>
6364    
6365     <p>The front-end can delete a particular MIDI instrument map
6366     by sending the following command:
6367     </p>
6368     <p>
6369     </p>
6370     <blockquote class="text">
6371     <p>REMOVE MIDI_INSTRUMENT_MAP &lt;map&gt;
6372     </p>
6373     </blockquote><p>
6374    
6375     </p>
6376     <p>Where &lt;map&gt; reflects the unique ID of the map to delete
6377     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>
6378     command.
6379     </p>
6380     <p>The front-end can delete all MIDI instrument maps by
6381     sending the following command:
6382     </p>
6383     <p>
6384     </p>
6385     <blockquote class="text">
6386     <p>REMOVE MIDI_INSTRUMENT_MAP ALL
6387     </p>
6388     </blockquote><p>
6389    
6390     </p>
6391     <p>Possible Answers:
6392     </p>
6393     <p>
6394     </p>
6395     <blockquote class="text">
6396     <p>"OK" -
6397     </p>
6398     <blockquote class="text">
6399     <p>in case the map(s) could be deleted
6400     </p>
6401     </blockquote>
6402    
6403    
6404     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6405     </p>
6406     <blockquote class="text">
6407     <p>when the given map does not exist
6408     </p>
6409     </blockquote>
6410    
6411    
6412     </blockquote><p>
6413    
6414     </p>
6415     <p>Examples:
6416     </p>
6417     <p>
6418     </p>
6419     <blockquote class="text">
6420     <p>C: "REMOVE MIDI_INSTRUMENT_MAP 0"
6421     </p>
6422     <p>S: "OK"
6423     </p>
6424     </blockquote><p>
6425    
6426     </p>
6427     <p>
6428     </p>
6429     <blockquote class="text">
6430     <p>C: "REMOVE MIDI_INSTRUMENT_MAP ALL"
6431     </p>
6432     <p>S: "OK"
6433     </p>
6434     </blockquote><p>
6435    
6436     </p>
6437     <a name="GET MIDI_INSTRUMENT_MAPS"></a><br /><hr />
6438     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6439     <a name="rfc.section.6.7.3"></a><h3>6.7.3.&nbsp;
6440     Get amount of existing MIDI instrument maps</h3>
6441    
6442     <p>The front-end can retrieve the current amount of MIDI
6443     instrument maps by sending the following command:
6444     </p>
6445     <p>
6446     </p>
6447     <blockquote class="text">
6448     <p>GET MIDI_INSTRUMENT_MAPS
6449     </p>
6450     </blockquote><p>
6451    
6452     </p>
6453     <p>Possible Answers:
6454     </p>
6455     <p>
6456     </p>
6457     <blockquote class="text">
6458     <p>The sampler will answer by returning the current
6459     number of MIDI instrument maps.
6460     </p>
6461     </blockquote><p>
6462    
6463     </p>
6464     <p>Example:
6465     </p>
6466     <p>
6467     </p>
6468     <blockquote class="text">
6469     <p>C: "GET MIDI_INSTRUMENT_MAPS"
6470     </p>
6471     <p>S: "2"
6472     </p>
6473     </blockquote><p>
6474    
6475     </p>
6476     <a name="LIST MIDI_INSTRUMENT_MAPS"></a><br /><hr />
6477     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6478     <a name="rfc.section.6.7.4"></a><h3>6.7.4.&nbsp;
6479     Getting all created MIDI instrument maps</h3>
6480    
6481     <p>The number of MIDI instrument maps can change on runtime. To get the
6482     current list of MIDI instrument maps, the front-end can send the
6483     following command:
6484     </p>
6485     <p>
6486     </p>
6487     <blockquote class="text">
6488     <p>LIST MIDI_INSTRUMENT_MAPS
6489     </p>
6490     </blockquote><p>
6491    
6492     </p>
6493     <p>Possible Answers:
6494     </p>
6495     <p>
6496     </p>
6497     <blockquote class="text">
6498     <p>The sampler will answer by returning a comma separated list
6499     with all MIDI instrument maps' numerical IDs.
6500     </p>
6501     </blockquote><p>
6502    
6503     </p>
6504     <p>Example:
6505     </p>
6506     <p>
6507     </p>
6508     <blockquote class="text">
6509     <p>C: "LIST MIDI_INSTRUMENT_MAPS"
6510     </p>
6511     <p>S: "0,1,5,12"
6512     </p>
6513     </blockquote><p>
6514    
6515     </p>
6516     <a name="GET MIDI_INSTRUMENT_MAP INFO"></a><br /><hr />
6517     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6518     <a name="rfc.section.6.7.5"></a><h3>6.7.5.&nbsp;
6519     Getting MIDI instrument map information</h3>
6520    
6521     <p>The front-end can ask for the current settings of a MIDI
6522     instrument map by sending the following command:
6523     </p>
6524     <p>
6525     </p>
6526     <blockquote class="text">
6527     <p>GET MIDI_INSTRUMENT_MAP INFO &lt;map&gt;
6528     </p>
6529     </blockquote><p>
6530    
6531     </p>
6532     <p>Where &lt;map&gt; is the numerical ID of the map the
6533     front-end is interested in as returned by the
6534     <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>
6535     command.
6536     </p>
6537     <p>Possible Answers:
6538     </p>
6539     <p>
6540     </p>
6541     <blockquote class="text">
6542     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
6543     Each answer line begins with the settings category name
6544     followed by a colon and then a space character &lt;SP&gt; and finally
6545     the info character string to that setting category. At the
6546     moment the following categories are defined:
6547     </p>
6548     <p>
6549     </p>
6550     <blockquote class="text">
6551     <p>NAME -
6552     </p>
6553     <blockquote class="text">
6554     <p>custom name of the given map,
6555     which does not have to be unique
6556     </p>
6557     </blockquote>
6558    
6559    
6560 iliev 1137 <p>DEFAULT -
6561     </p>
6562     <blockquote class="text">
6563     <p>either true or false,
6564     defines whether this map is the default map
6565     </p>
6566 schoenebeck 974 </blockquote>
6567 iliev 1137
6568    
6569     </blockquote>
6570 schoenebeck 974
6571    
6572     </blockquote><p>
6573    
6574     </p>
6575     <p>The mentioned fields above don't have to be in particular order.
6576     </p>
6577     <p>Example:
6578     </p>
6579     <p>
6580     </p>
6581     <blockquote class="text">
6582     <p>C: "GET MIDI_INSTRUMENT_MAP INFO 0"
6583     </p>
6584     <p>S: "NAME: Standard Map"
6585     </p>
6586 iliev 1137 <p>&nbsp;&nbsp;&nbsp;"DEFAULT: true"
6587     </p>
6588 schoenebeck 974 <p>&nbsp;&nbsp;&nbsp;"."
6589     </p>
6590     </blockquote><p>
6591    
6592     </p>
6593     <a name="SET MIDI_INSTRUMENT_MAP NAME"></a><br /><hr />
6594     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
6595     <a name="rfc.section.6.7.6"></a><h3>6.7.6.&nbsp;
6596     Renaming a MIDI instrument map</h3>
6597    
6598     <p>The front-end can alter the custom name of a MIDI
6599     instrument map by sending the following command:
6600     </p>
6601     <p>
6602     </p>
6603     <blockquote class="text">
6604     <p>SET MIDI_INSTRUMENT_MAP NAME &lt;map&gt; &lt;name&gt;
6605     </p>
6606     </blockquote><p>
6607    
6608     </p>
6609     <p>Where &lt;map&gt; is the numerical ID of the map and
6610     &lt;name&gt; the new custom name of the map, which does not
6611     have to be unique.
6612     </p>
6613     <p>Possible Answers:
6614     </p>
6615     <p>
6616     </p>
6617     <blockquote class="text">
6618     <p>"OK" -
6619     </p>
6620     <blockquote class="text">
6621     <p>on success
6622     </p>
6623     </blockquote>
6624    
6625    
6626     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6627     </p>
6628     <blockquote class="text">
6629     <p>in case the given map does not exist
6630     </p>
6631     </blockquote>
6632    
6633    
6634     </blockquote><p>
6635    
6636     </p>
6637     <p>Example:
6638     </p>
6639     <p>
6640     </p>
6641     <blockquote class="text">
6642     <p>C: "SET MIDI_INSTRUMENT_MAP NAME 0 'Foo instruments'"
6643     </p>
6644     <p>S: "OK"
6645     </p>
6646     </blockquote><p>
6647    
6648     </p>
6649 schoenebeck 945 <a name="MAP MIDI_INSTRUMENT"></a><br /><hr />
6650 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>
6651     <a name="rfc.section.6.7.7"></a><h3>6.7.7.&nbsp;
6652     Create or replace a MIDI instrument map entry</h3>
6653 schoenebeck 945
6654     <p>The front-end can create a new or replace an existing entry
6655 schoenebeck 974 in a sampler's MIDI instrument map by sending the following
6656 schoenebeck 945 command:
6657     </p>
6658     <p>
6659     </p>
6660     <blockquote class="text">
6661 schoenebeck 1048 <p>MAP MIDI_INSTRUMENT [NON_MODAL] &lt;map&gt;
6662 schoenebeck 974 &lt;midi_bank&gt; &lt;midi_prog&gt; &lt;engine_name&gt;
6663 schoenebeck 945 &lt;filename&gt; &lt;instrument_index&gt; &lt;volume_value&gt;
6664     [&lt;instr_load_mode&gt;] [&lt;name&gt;]
6665     </p>
6666     </blockquote><p>
6667    
6668     </p>
6669 schoenebeck 974 <p>Where &lt;map&gt; is the numeric ID of the map to alter,
6670     &lt;midi_bank&gt; is an integer value between
6671     0..16383 reflecting the MIDI bank select index,
6672     &lt;midi_prog&gt; an
6673 schoenebeck 945 integer value between 0..127 reflecting the MIDI program change
6674     index, &lt;engine_name&gt; a sampler engine name as returned by
6675 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>
6676 schoenebeck 945 command (not encapsulated into apostrophes), &lt;filename&gt; the name
6677 schoenebeck 1251 of the instrument's file to be deployed (encapsulated into apostrophes,
6678     supporting escape sequences as described in chapter
6679     "<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>"),
6680 schoenebeck 974 &lt;instrument_index&gt; the index (integer value) of the instrument
6681 schoenebeck 945 within the given file, &lt;volume_value&gt; reflects the master
6682     volume of the instrument as optionally dotted number (where a
6683 schoenebeck 1028 value &lt; 1.0 means attenuation and a value > 1.0 means
6684 schoenebeck 945 amplification). This parameter easily allows to adjust the
6685     volume of all intruments within a custom instrument map
6686     without having to adjust their instrument files. The
6687     OPTIONAL &lt;instr_load_mode&gt; argument defines the life
6688     time of the instrument, that is when the instrument should
6689     be loaded, when freed and has exactly the following
6690     possibilities:
6691     </p>
6692     <p>
6693     </p>
6694     <blockquote class="text">
6695     <p>"ON_DEMAND" -
6696     </p>
6697     <blockquote class="text">
6698     <p>The instrument will be loaded when needed,
6699     that is when demanded by at least one sampler
6700     channel. It will immediately be freed from memory
6701     when not needed by any sampler channel anymore.
6702     </p>
6703     </blockquote>
6704    
6705    
6706     <p>"ON_DEMAND_HOLD" -
6707     </p>
6708     <blockquote class="text">
6709     <p>The instrument will be loaded when needed,
6710     that is when demanded by at least one sampler
6711     channel. It will be kept in memory even when
6712     not needed by any sampler channel anymore.
6713     Instruments with this mode are only freed
6714     when the sampler is reset or all mapping
6715     entries with this mode (and respective
6716     instrument) are explicitly changed to
6717     "ON_DEMAND" and no sampler channel is using
6718     the instrument anymore.
6719     </p>
6720     </blockquote>
6721    
6722    
6723     <p>"PERSISTENT" -
6724     </p>
6725     <blockquote class="text">
6726     <p>The instrument will immediately be loaded
6727 schoenebeck 1048 into memory when this mapping
6728 schoenebeck 945 command is sent and the instrument is kept all
6729     the time. Instruments with this mode are
6730     only freed when the sampler is reset or all
6731     mapping entries with this mode (and
6732     respective instrument) are explicitly
6733     changed to "ON_DEMAND" and no sampler
6734     channel is using the instrument anymore.
6735     </p>
6736     </blockquote>
6737    
6738    
6739     <p>not supplied -
6740     </p>
6741     <blockquote class="text">
6742     <p>In case there is no &lt;instr_load_mode&gt;
6743     argument given, it will be up to the
6744     InstrumentManager to decide which mode to use.
6745     Usually it will use "ON_DEMAND" if an entry
6746     for the given instrument does not exist in
6747     the InstrumentManager's list yet, otherwise
6748     if an entry already exists, it will simply
6749     stick with the mode currently reflected by
6750     the already existing entry, that is it will
6751     not change the mode.
6752     </p>
6753     </blockquote>
6754    
6755    
6756     </blockquote><p>
6757    
6758     </p>
6759     <p>
6760     The &lt;instr_load_mode&gt; argument thus allows to define an
6761     appropriate strategy (low memory consumption vs. fast
6762     instrument switching) for each instrument individually. Note, the
6763     following restrictions apply to this argument: "ON_DEMAND_HOLD" and
6764     "PERSISTENT" have to be supported by the respective sampler engine
6765     (which is technically the case when the engine provides an
6766     InstrumentManager for its format). If this is not the case the
6767     argument will automatically fall back to the default value
6768     "ON_DEMAND". Also the load mode of one instrument may
6769     automatically change the laod mode of other instrument(s), i.e.
6770     because the instruments are part of the same file and the
6771     engine does not allow a way to manage load modes for them
6772     individually. Due to this, in case the frontend shows the
6773     load modes of entries, the frontend should retrieve the actual
6774     mode by i.e. sending
6775 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>
6776 schoenebeck 945 command(s). Finally the OPTIONAL &lt;name&gt; argument allows to
6777     set a custom name (encapsulated into apostrophes) for the mapping
6778     entry, useful for frontends for displaying an appropriate name for
6779     mapped instruments (using
6780 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>).
6781 schoenebeck 945
6782     </p>
6783     <p>
6784 schoenebeck 1048 By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is
6785     completely established in the sampler. The OPTIONAL "NON_MODAL" argument
6786     however causes the respective "MAP MIDI_INSTRUMENT" command to return
6787     immediately, that is to let the sampler establish the mapping in the
6788     background. So this argument might be especially useful for mappings with
6789     a "PERSISTENT" type, because these have to load the respective instruments
6790     immediately and might thus block for a very long time. It is recommended
6791     however to use the OPTIONAL "NON_MODAL" argument only if really necessary,
6792     because it has the following drawbacks: as "NON_MODAL" instructions return
6793     immediately, they may not necessarily return an error i.e. when the given
6794     instrument file turns out to be corrupt, beside that subsequent commands
6795     in a LSCP instruction sequence might fail, because mandatory mappings are
6796     not yet completed.
6797 schoenebeck 945
6798     </p>
6799     <p>Possible Answers:
6800     </p>
6801     <p>
6802     </p>
6803     <blockquote class="text">
6804     <p>"OK" -
6805     </p>
6806     <blockquote class="text">
6807     <p>usually
6808     </p>
6809     </blockquote>
6810    
6811    
6812     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6813     </p>
6814     <blockquote class="text">
6815 schoenebeck 974 <p>when the given map or engine does not exist or a value
6816 schoenebeck 945 is out of range
6817     </p>
6818     </blockquote>
6819    
6820    
6821     </blockquote><p>
6822    
6823     </p>
6824     <p>Examples:
6825     </p>
6826     <p>
6827     </p>
6828     <blockquote class="text">
6829 schoenebeck 974 <p>C: "MAP MIDI_INSTRUMENT 0 3 0 gig '/usr/share/Steinway D.gig' 0 0.8 PERSISTENT"
6830 schoenebeck 945 </p>
6831     <p>S: "OK"
6832     </p>
6833     </blockquote><p>
6834    
6835     </p>
6836     <p>
6837     </p>
6838     <blockquote class="text">
6839 schoenebeck 974 <p>C: "MAP MIDI_INSTRUMENT 0 4 50 gig '/home/john/foostrings.gig' 7 1.0"
6840 schoenebeck 945 </p>
6841     <p>S: "OK"
6842     </p>
6843     </blockquote><p>
6844    
6845     </p>
6846     <p>
6847     </p>
6848     <blockquote class="text">
6849     <p>C: "MAP MIDI_INSTRUMENT 0 0 0 gig '/usr/share/piano.gig' 0 1.0 'Normal Piano'"
6850     </p>
6851     <p>S: "OK"
6852     </p>
6853 schoenebeck 974 <p>C: "MAP MIDI_INSTRUMENT 0 1 0 gig '/usr/share/piano.gig' 0 0.25 'Silent Piano'"
6854 schoenebeck 945 </p>
6855     <p>S: "OK"
6856     </p>
6857     </blockquote><p>
6858    
6859     </p>
6860     <p>
6861     </p>
6862     <blockquote class="text">
6863 schoenebeck 1048 <p>C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"
6864 schoenebeck 945 </p>
6865     <p>S: "OK"
6866     </p>
6867     </blockquote><p>
6868    
6869     </p>
6870     <a name="GET MIDI_INSTRUMENTS"></a><br /><hr />
6871 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>
6872     <a name="rfc.section.6.7.8"></a><h3>6.7.8.&nbsp;
6873     Getting ammount of MIDI instrument map entries</h3>
6874 schoenebeck 945
6875 schoenebeck 974 <p>The front-end can query the amount of currently existing
6876     entries in a MIDI instrument map by sending the following
6877 schoenebeck 945 command:
6878     </p>
6879     <p>
6880     </p>
6881     <blockquote class="text">
6882 schoenebeck 974 <p>GET MIDI_INSTRUMENTS &lt;map&gt;
6883 schoenebeck 945 </p>
6884     </blockquote><p>
6885    
6886     </p>
6887 schoenebeck 974 <p>The front-end can query the amount of currently existing
6888     entries in all MIDI instrument maps by sending the following
6889     command:
6890     </p>
6891     <p>
6892     </p>
6893     <blockquote class="text">
6894     <p>GET MIDI_INSTRUMENTS ALL
6895     </p>
6896     </blockquote><p>
6897    
6898     </p>
6899 schoenebeck 945 <p>Possible Answers:
6900     </p>
6901     <p>
6902     </p>
6903     <blockquote class="text">
6904 schoenebeck 974 <p>The sampler will answer by sending the current number of
6905     entries in the MIDI instrument map(s).
6906 schoenebeck 945 </p>
6907     </blockquote><p>
6908    
6909     </p>
6910     <p>Example:
6911     </p>
6912     <p>
6913     </p>
6914     <blockquote class="text">
6915 schoenebeck 974 <p>C: "GET MIDI_INSTRUMENTS 0"
6916 schoenebeck 945 </p>
6917 schoenebeck 974 <p>S: "234"
6918 schoenebeck 945 </p>
6919     </blockquote><p>
6920    
6921     </p>
6922 schoenebeck 974 <p>
6923     </p>
6924     <blockquote class="text">
6925     <p>C: "GET MIDI_INSTRUMENTS ALL"
6926     </p>
6927     <p>S: "954"
6928     </p>
6929     </blockquote><p>
6930    
6931     </p>
6932 schoenebeck 945 <a name="LIST MIDI_INSTRUMENTS"></a><br /><hr />
6933 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>
6934     <a name="rfc.section.6.7.9"></a><h3>6.7.9.&nbsp;
6935     Getting indeces of all entries of a MIDI instrument map</h3>
6936 schoenebeck 945
6937 schoenebeck 974 <p>The front-end can query a list of all currently existing
6938     entries in a certain MIDI instrument map by sending the following
6939     command:
6940 schoenebeck 945 </p>
6941     <p>
6942     </p>
6943     <blockquote class="text">
6944 schoenebeck 974 <p>LIST MIDI_INSTRUMENTS &lt;map&gt;
6945 schoenebeck 945 </p>
6946     </blockquote><p>
6947    
6948     </p>
6949 schoenebeck 974 <p>Where &lt;map&gt; is the numeric ID of the MIDI instrument map.
6950     </p>
6951     <p>The front-end can query a list of all currently existing
6952     entries of all MIDI instrument maps by sending the following
6953     command:
6954     </p>
6955     <p>
6956     </p>
6957     <blockquote class="text">
6958     <p>LIST MIDI_INSTRUMENTS ALL
6959     </p>
6960     </blockquote><p>
6961    
6962     </p>
6963 schoenebeck 945 <p>Possible Answers:
6964     </p>
6965     <p>
6966     </p>
6967     <blockquote class="text">
6968 schoenebeck 974 <p>The sampler will answer by sending a comma separated
6969     list of map ID - MIDI bank - MIDI program triples, where
6970     each triple is encapsulated into curly braces. The
6971     list is returned in one single line. Each triple
6972     just reflects the key of the respective map entry,
6973     thus subsequent
6974     <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>
6975 schoenebeck 945 command(s) are necessary to retrieve detailed informations
6976     about each entry.
6977     </p>
6978     </blockquote><p>
6979    
6980     </p>
6981     <p>Example:
6982     </p>
6983     <p>
6984     </p>
6985     <blockquote class="text">
6986 schoenebeck 974 <p>C: "LIST MIDI_INSTRUMENTS 0"
6987 schoenebeck 945 </p>
6988 schoenebeck 974 <p>S: "{0,0,0},{0,0,1},{0,0,3},{0,1,4},{1,127,127}"
6989 schoenebeck 945 </p>
6990     </blockquote><p>
6991    
6992     </p>
6993     <a name="UNMAP MIDI_INSTRUMENT"></a><br /><hr />
6994 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>
6995     <a name="rfc.section.6.7.10"></a><h3>6.7.10.&nbsp;
6996     Remove an entry from the MIDI instrument map</h3>
6997 schoenebeck 945
6998 schoenebeck 974 <p>The front-end can delete an entry from a MIDI instrument
6999 schoenebeck 945 map by sending the following command:
7000     </p>
7001     <p>
7002     </p>
7003     <blockquote class="text">
7004 schoenebeck 974 <p>UNMAP MIDI_INSTRUMENT &lt;map&gt; &lt;midi_bank&gt; &lt;midi_prog&gt;
7005 schoenebeck 945 </p>
7006     </blockquote><p>
7007    
7008     </p>
7009     <p>
7010 schoenebeck 974 Where &lt;map&gt; is the numeric ID of the MIDI instrument map,
7011     &lt;midi_bank&gt; is an integer value between 0..16383
7012     reflecting the MIDI bank value and
7013     &lt;midi_prog&gt; an integer value between
7014     0..127 reflecting the MIDI program value of the map's entrie's key
7015 schoenebeck 945 index triple.
7016    
7017     </p>
7018     <p>Possible Answers:
7019     </p>
7020     <p>
7021     </p>
7022     <blockquote class="text">
7023     <p>"OK" -
7024     </p>
7025     <blockquote class="text">
7026     <p>usually
7027     </p>
7028     </blockquote>
7029    
7030    
7031     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7032     </p>
7033     <blockquote class="text">
7034     <p>when index out of bounds
7035     </p>
7036     </blockquote>
7037    
7038    
7039     </blockquote><p>
7040    
7041     </p>
7042     <p>Example:
7043     </p>
7044     <p>
7045     </p>
7046     <blockquote class="text">
7047 schoenebeck 974 <p>C: "UNMAP MIDI_INSTRUMENT 0 2 127"
7048 schoenebeck 945 </p>
7049     <p>S: "OK"
7050     </p>
7051     </blockquote><p>
7052    
7053     </p>
7054     <a name="GET MIDI_INSTRUMENT INFO"></a><br /><hr />
7055 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>
7056     <a name="rfc.section.6.7.11"></a><h3>6.7.11.&nbsp;
7057     Get current settings of MIDI instrument map entry</h3>
7058 schoenebeck 945
7059     <p>The front-end can retrieve the current settings of a certain
7060     instrument map entry by sending the following command:
7061     </p>
7062     <p>
7063     </p>
7064     <blockquote class="text">
7065 schoenebeck 974 <p>GET MIDI_INSTRUMENT INFO &lt;map&gt; &lt;midi_bank&gt; &lt;midi_prog&gt;
7066 schoenebeck 945 </p>
7067     </blockquote><p>
7068    
7069     </p>
7070     <p>
7071 schoenebeck 974 Where &lt;map&gt; is the numeric ID of the MIDI instrument map,
7072     &lt;midi_bank&gt; is an integer value between 0..16383
7073     reflecting the MIDI bank value, &lt;midi_bank&gt;
7074     and &lt;midi_prog&gt; an integer value between
7075     0..127 reflecting the MIDI program value of the map's entrie's key
7076 schoenebeck 945 index triple.
7077    
7078     </p>
7079     <p>Possible Answers:
7080     </p>
7081     <p>
7082     </p>
7083     <blockquote class="text">
7084     <p>LinuxSampler will answer by sending a &lt;CRLF&gt;
7085     separated list. Each answer line begins with the
7086     information category name followed by a colon and then
7087     a space character &lt;SP&gt; and finally the info
7088     character string to that info category. At the moment
7089     the following categories are defined:
7090     </p>
7091     <p>"NAME" -
7092     </p>
7093     <blockquote class="text">
7094     <p>Name for this MIDI instrument map entry (if defined).
7095     This name shall be used by frontends for displaying a
7096     name for this mapped instrument. It can be set and
7097     changed with the
7098 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>
7099 schoenebeck 945 command and does not have to be unique.
7100     </p>
7101     </blockquote>
7102    
7103    
7104     <p>"ENGINE_NAME" -
7105     </p>
7106     <blockquote class="text">
7107     <p>Name of the engine to be deployed for this
7108     instrument.
7109     </p>
7110     </blockquote>
7111    
7112    
7113     <p>"INSTRUMENT_FILE" -
7114     </p>
7115     <blockquote class="text">
7116     <p>File name of the instrument.
7117     </p>
7118     </blockquote>
7119    
7120    
7121     <p>"INSTRUMENT_NR" -
7122     </p>
7123     <blockquote class="text">
7124     <p>Index of the instrument within the file.
7125     </p>
7126     </blockquote>
7127    
7128    
7129     <p>"INSTRUMENT_NAME" -
7130     </p>
7131     <blockquote class="text">
7132     <p>Name of the loaded instrument as reflected by its file.
7133     In contrast to the "NAME" field, the "INSTRUMENT_NAME" field
7134     cannot be changed.
7135     </p>
7136     </blockquote>
7137    
7138    
7139     <p>"LOAD_MODE" -
7140     </p>
7141     <blockquote class="text">
7142     <p>Life time of instrument
7143 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).
7144 schoenebeck 945 </p>
7145     </blockquote>
7146    
7147    
7148     <p>"VOLUME" -
7149     </p>
7150     <blockquote class="text">
7151     <p>master volume of the instrument as optionally
7152 schoenebeck 1028 dotted number (where a value &lt; 1.0 means attenuation
7153 schoenebeck 945 and a value > 1.0 means amplification)
7154     </p>
7155     </blockquote>
7156    
7157    
7158     <p>The mentioned fields above don't have to be in particular order.
7159     </p>
7160     </blockquote><p>
7161    
7162     </p>
7163     <p>Example:
7164     </p>
7165     <p>
7166     </p>
7167     <blockquote class="text">
7168 schoenebeck 974 <p>C: "GET MIDI_INSTRUMENT INFO 1 45 120"
7169 schoenebeck 945 </p>
7170     <p>S: "NAME: Drums for Foo Song"
7171     </p>
7172     <p>&nbsp;&nbsp;&nbsp;"ENGINE_NAME: GigEngine"
7173     </p>
7174     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_FILE: /usr/share/joesdrumkit.gig"
7175     </p>
7176     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"
7177     </p>
7178     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NAME: Joe's Drumkit"
7179     </p>
7180     <p>&nbsp;&nbsp;&nbsp;"LOAD_MODE: PERSISTENT"
7181     </p>
7182     <p>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"
7183     </p>
7184     <p>&nbsp;&nbsp;&nbsp;"."
7185     </p>
7186     </blockquote><p>
7187    
7188     </p>
7189     <a name="CLEAR MIDI_INSTRUMENTS"></a><br /><hr />
7190 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>
7191     <a name="rfc.section.6.7.12"></a><h3>6.7.12.&nbsp;
7192     Clear MIDI instrument map</h3>
7193 schoenebeck 945
7194 schoenebeck 974 <p>The front-end can clear a whole MIDI instrument map, that
7195     is delete all its entries by sending the following command:
7196 schoenebeck 945 </p>
7197     <p>
7198     </p>
7199     <blockquote class="text">
7200 schoenebeck 974 <p>CLEAR MIDI_INSTRUMENTS &lt;map&gt;
7201 schoenebeck 945 </p>
7202     </blockquote><p>
7203    
7204     </p>
7205 schoenebeck 974 <p>Where &lt;map&gt; is the numeric ID of the map to clear.
7206     </p>
7207     <p>The front-end can clear all MIDI instrument maps, that
7208     is delete all entries of all maps by sending the following
7209     command:
7210     </p>
7211     <p>
7212     </p>
7213     <blockquote class="text">
7214     <p>CLEAR MIDI_INSTRUMENTS ALL
7215     </p>
7216     </blockquote><p>
7217    
7218     </p>
7219     <p>The command "CLEAR MIDI_INSTRUMENTS ALL" does not delete the
7220     maps, only their entries, thus the map's settings like
7221     custom name will be preservevd.
7222     </p>
7223 schoenebeck 945 <p>Possible Answers:
7224     </p>
7225     <p>
7226     </p>
7227     <blockquote class="text">
7228     <p>"OK" -
7229     </p>
7230     <blockquote class="text">
7231     <p>always
7232     </p>
7233     </blockquote>
7234    
7235    
7236     </blockquote><p>
7237    
7238     </p>
7239 schoenebeck 974 <p>Examples:
7240 schoenebeck 945 </p>
7241     <p>
7242     </p>
7243     <blockquote class="text">
7244 schoenebeck 974 <p>C: "CLEAR MIDI_INSTRUMENTS 0"
7245 schoenebeck 945 </p>
7246     <p>S: "OK"
7247     </p>
7248     </blockquote><p>
7249    
7250     </p>
7251 schoenebeck 974 <p>
7252     </p>
7253     <blockquote class="text">
7254     <p>C: "CLEAR MIDI_INSTRUMENTS ALL"
7255     </p>
7256     <p>S: "OK"
7257     </p>
7258     </blockquote><p>
7259    
7260     </p>
7261 iliev 1162 <a name="Managing Instruments Database"></a><br /><hr />
7262     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7263     <a name="rfc.section.6.8"></a><h3>6.8.&nbsp;
7264     Managing Instruments Database</h3>
7265    
7266     <p>The following commands describe how to use and manage
7267     the instruments database.
7268     </p>
7269 schoenebeck 1363 <p>Notice:
7270     </p>
7271     <p>
7272     </p>
7273     <blockquote class="text">
7274     <p>All command arguments representing a path or
7275     instrument/directory name support escape sequences as described in chapter
7276     "<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>".
7277    
7278     </p>
7279     <p>All occurrences of a forward slash in instrument and directory
7280     names are escaped with its hex (\x2f) or octal (\057) escape sequence.
7281    
7282     </p>
7283     </blockquote><p>
7284    
7285     </p>
7286 iliev 1162 <a name="ADD DB_INSTRUMENT_DIRECTORY"></a><br /><hr />
7287     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7288     <a name="rfc.section.6.8.1"></a><h3>6.8.1.&nbsp;
7289     Creating a new instrument directory</h3>
7290    
7291     <p>The front-end can add a new instrument directory to the
7292     instruments database by sending the following command:
7293     </p>
7294     <p>
7295     </p>
7296     <blockquote class="text">
7297     <p>ADD DB_INSTRUMENT_DIRECTORY &lt;dir&gt;
7298     </p>
7299     </blockquote><p>
7300    
7301     </p>
7302     <p>Where &lt;dir&gt; is the absolute path name of the directory
7303     to be created (encapsulated into apostrophes).
7304     </p>
7305     <p>Possible Answers:
7306     </p>
7307     <p>
7308     </p>
7309     <blockquote class="text">
7310     <p>"OK" -
7311     </p>
7312     <blockquote class="text">
7313     <p>on success
7314     </p>
7315     </blockquote>
7316    
7317    
7318     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7319     </p>
7320     <blockquote class="text">
7321     <p>when the directory could not be created, which
7322     can happen if the directory already exists or the
7323     name contains not allowed symbols
7324     </p>
7325     </blockquote>
7326    
7327    
7328     </blockquote><p>
7329    
7330     </p>
7331     <p>Examples:
7332     </p>
7333     <p>
7334     </p>
7335     <blockquote class="text">
7336     <p>C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'"
7337     </p>
7338     <p>S: "OK"
7339     </p>
7340     </blockquote><p>
7341    
7342     </p>
7343     <a name="REMOVE DB_INSTRUMENT_DIRECTORY"></a><br /><hr />
7344     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7345     <a name="rfc.section.6.8.2"></a><h3>6.8.2.&nbsp;
7346     Deleting an instrument directory</h3>
7347    
7348     <p>The front-end can delete a particular instrument directory
7349     from the instruments database by sending the following command:
7350     </p>
7351     <p>
7352     </p>
7353     <blockquote class="text">
7354     <p>REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] &lt;dir&gt;
7355     </p>
7356     </blockquote><p>
7357    
7358     </p>
7359     <p>Where &lt;dir&gt; is the absolute path name of the directory
7360     to delete. The optional FORCE argument can be used to
7361     force the deletion of a non-empty directory and all its content.
7362     </p>
7363     <p>Possible Answers:
7364     </p>
7365     <p>
7366     </p>
7367     <blockquote class="text">
7368     <p>"OK" -
7369     </p>
7370     <blockquote class="text">
7371     <p>if the directory is deleted successfully
7372     </p>
7373     </blockquote>
7374    
7375    
7376     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7377     </p>
7378     <blockquote class="text">
7379     <p>if the given directory does not exist, or
7380     if trying to delete a non-empty directory,
7381     without using the FORCE argument.
7382     </p>
7383     </blockquote>
7384    
7385    
7386     </blockquote><p>
7387    
7388     </p>
7389     <p>Examples:
7390     </p>
7391     <p>
7392     </p>
7393     <blockquote class="text">
7394     <p>C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'"
7395     </p>
7396     <p>S: "OK"
7397     </p>
7398     </blockquote><p>
7399    
7400     </p>
7401     <a name="GET DB_INSTRUMENT_DIRECTORIES"></a><br /><hr />
7402     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7403     <a name="rfc.section.6.8.3"></a><h3>6.8.3.&nbsp;
7404     Getting amount of instrument directories</h3>
7405    
7406     <p>The front-end can retrieve the current amount of
7407     directories in a specific directory by sending the following command:
7408     </p>
7409     <p>
7410     </p>
7411     <blockquote class="text">
7412 iliev 1189 <p>GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;
7413 iliev 1162 </p>
7414     </blockquote><p>
7415    
7416     </p>
7417     <p>Where &lt;dir&gt; should be replaced by the absolute path
7418 iliev 1189 name of the directory. If RECURSIVE is specified, the number of
7419     all directories, including those located in subdirectories of the
7420     specified directory, will be returned.
7421 iliev 1162 </p>
7422     <p>Possible Answers:
7423     </p>
7424     <p>
7425     </p>
7426     <blockquote class="text">
7427     <p>The current number of instrument directories
7428     in the specified directory.
7429     </p>
7430     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7431     </p>
7432     <blockquote class="text">
7433     <p>if the given directory does not exist.
7434     </p>
7435     </blockquote>
7436    
7437    
7438     </blockquote><p>
7439    
7440     </p>
7441     <p>Example:
7442     </p>
7443     <p>
7444     </p>
7445     <blockquote class="text">
7446     <p>C: "GET DB_INSTRUMENT_DIRECTORIES '/'"
7447     </p>
7448     <p>S: "2"
7449     </p>
7450     </blockquote><p>
7451    
7452     </p>
7453     <a name="LIST DB_INSTRUMENT_DIRECTORIES"></a><br /><hr />
7454     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7455     <a name="rfc.section.6.8.4"></a><h3>6.8.4.&nbsp;
7456     Listing all directories in specific directory</h3>
7457    
7458     <p>The front-end can retrieve the current list of directories
7459     in specific directory by sending the following command:
7460     </p>
7461     <p>
7462     </p>
7463     <blockquote class="text">
7464 iliev 1189 <p>LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] &lt;dir&gt;
7465 iliev 1162 </p>
7466     </blockquote><p>
7467    
7468     </p>
7469     <p>Where &lt;dir&gt; should be replaced by the absolute path
7470 iliev 1189 name of the directory. If RECURSIVE is specified, the absolute path names
7471     of all directories, including those located in subdirectories of the
7472     specified directory, will be returned.
7473 iliev 1162 </p>
7474     <p>Possible Answers:
7475     </p>
7476     <p>
7477     </p>
7478     <blockquote class="text">
7479     <p>A comma separated list of all instrument directories
7480     (encapsulated into apostrophes) in the specified directory.
7481     </p>
7482     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7483     </p>
7484     <blockquote class="text">
7485     <p>if the given directory does not exist.
7486     </p>
7487     </blockquote>
7488    
7489    
7490     </blockquote><p>
7491    
7492     </p>
7493     <p>Example:
7494     </p>
7495     <p>
7496     </p>
7497     <blockquote class="text">
7498     <p>C: "LIST DB_INSTRUMENT_DIRECTORIES '/'"
7499     </p>
7500     <p>S: "'Piano Collection','Percussion Collection'"
7501     </p>
7502     </blockquote><p>
7503    
7504     </p>
7505 iliev 1189 <p>
7506     </p>
7507     <blockquote class="text">
7508     <p>C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'"
7509     </p>
7510     <p>S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano Collection/Acoustic/New','/Percussion Collection'"
7511     </p>
7512     </blockquote><p>
7513    
7514     </p>
7515 iliev 1162 <a name="GET DB_INSTRUMENT_DIRECTORY INFO"></a><br /><hr />
7516     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7517     <a name="rfc.section.6.8.5"></a><h3>6.8.5.&nbsp;
7518     Getting instrument directory information</h3>
7519    
7520     <p>The front-end can ask for the current settings of an
7521     instrument directory by sending the following command:
7522     </p>
7523     <p>
7524     </p>
7525     <blockquote class="text">
7526     <p>GET DB_INSTRUMENT_DIRECTORY INFO &lt;dir&gt;
7527     </p>
7528     </blockquote><p>
7529    
7530     </p>
7531     <p>Where &lt;dir&gt; should be replaced by the absolute path
7532     name of the directory the front-end is interested in.
7533     </p>
7534     <p>Possible Answers:
7535     </p>
7536     <p>
7537     </p>
7538     <blockquote class="text">
7539     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
7540     Each answer line begins with the settings category name
7541     followed by a colon and then a space character &lt;SP&gt; and finally
7542     the info character string to that setting category. At the
7543     moment the following categories are defined:
7544     </p>
7545     <p>
7546     </p>
7547     <blockquote class="text">
7548     <p>DESCRIPTION -
7549     </p>
7550     <blockquote class="text">
7551 schoenebeck 1363 <p>A brief description of the directory content.
7552     Note that the character string may contain
7553     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
7554 iliev 1162 </p>
7555     </blockquote>
7556    
7557    
7558     <p>CREATED -
7559     </p>
7560     <blockquote class="text">
7561     <p>The creation date and time of the directory,
7562     represented in "YYYY-MM-DD HH:MM:SS" format
7563     </p>
7564     </blockquote>
7565    
7566    
7567     <p>MODIFIED -
7568     </p>
7569     <blockquote class="text">
7570     <p>The date and time of the last modification of the
7571     directory, represented in "YYYY-MM-DD HH:MM:SS" format
7572     </p>
7573     </blockquote>
7574    
7575    
7576     </blockquote>
7577    
7578    
7579     </blockquote><p>
7580    
7581     </p>
7582     <p>The mentioned fields above don't have to be in particular order.
7583     </p>
7584     <p>Example:
7585     </p>
7586     <p>
7587     </p>
7588     <blockquote class="text">
7589     <p>C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'"
7590     </p>
7591     <p>S: "DESCRIPTION: Piano collection of instruments in GigaSampler format."
7592     </p>
7593     <p>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"
7594     </p>
7595     <p>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"
7596     </p>
7597     <p>&nbsp;&nbsp;&nbsp;"."
7598     </p>
7599     </blockquote><p>
7600    
7601     </p>
7602     <a name="SET DB_INSTRUMENT_DIRECTORY NAME"></a><br /><hr />
7603     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7604     <a name="rfc.section.6.8.6"></a><h3>6.8.6.&nbsp;
7605     Renaming an instrument directory</h3>
7606    
7607     <p>The front-end can alter the name of a specific
7608     instrument directory by sending the following command:
7609     </p>
7610     <p>
7611     </p>
7612     <blockquote class="text">
7613     <p>SET DB_INSTRUMENT_DIRECTORY NAME &lt;dir&gt; &lt;name&gt;
7614     </p>
7615     </blockquote><p>
7616    
7617     </p>
7618     <p>Where &lt;dir&gt; is the absolute path name of the directory and
7619     &lt;name&gt; is the new name for that directory.
7620     </p>
7621     <p>Possible Answers:
7622     </p>
7623     <p>
7624     </p>
7625     <blockquote class="text">
7626     <p>"OK" -
7627     </p>
7628     <blockquote class="text">
7629     <p>on success
7630     </p>
7631     </blockquote>
7632    
7633    
7634     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7635     </p>
7636     <blockquote class="text">
7637     <p>in case the given directory does not exists,
7638     or if a directory with name equal to the new
7639     name already exists.
7640     </p>
7641     </blockquote>
7642    
7643    
7644     </blockquote><p>
7645    
7646     </p>
7647     <p>Example:
7648     </p>
7649     <p>
7650     </p>
7651     <blockquote class="text">
7652     <p>C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic' 'Acoustic'"
7653     </p>
7654     <p>S: "OK"
7655     </p>
7656     </blockquote><p>
7657    
7658     </p>
7659     <a name="MOVE DB_INSTRUMENT_DIRECTORY"></a><br /><hr />
7660     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7661     <a name="rfc.section.6.8.7"></a><h3>6.8.7.&nbsp;
7662     Moving an instrument directory</h3>
7663    
7664     <p>The front-end can move a specific
7665     instrument directory by sending the following command:
7666     </p>
7667     <p>
7668     </p>
7669     <blockquote class="text">
7670     <p>MOVE DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;
7671     </p>
7672     </blockquote><p>
7673    
7674     </p>
7675     <p>Where &lt;dir&gt; is the absolute path name of the directory
7676     to move and &lt;dst&gt; is the location where the directory will
7677     be moved to.
7678     </p>
7679     <p>Possible Answers:
7680     </p>
7681     <p>
7682     </p>
7683     <blockquote class="text">
7684     <p>"OK" -
7685     </p>
7686     <blockquote class="text">
7687     <p>on success
7688     </p>
7689     </blockquote>
7690    
7691    
7692     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7693     </p>
7694     <blockquote class="text">
7695     <p>in case a given directory does not exists,
7696     or if a directory with name equal to the name
7697     of the specified directory already exists in
7698     the destination directory. Error is also thrown
7699     when trying to move a directory to a subdirectory
7700     of itself.
7701     </p>
7702     </blockquote>
7703    
7704    
7705     </blockquote><p>
7706    
7707     </p>
7708     <p>Example:
7709     </p>
7710     <p>
7711     </p>
7712     <blockquote class="text">
7713     <p>C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/Acoustic'"
7714     </p>
7715     <p>S: "OK"
7716     </p>
7717     </blockquote><p>
7718    
7719     </p>
7720 iliev 1189 <a name="COPY DB_INSTRUMENT_DIRECTORY"></a><br /><hr />
7721     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7722     <a name="rfc.section.6.8.8"></a><h3>6.8.8.&nbsp;
7723     Copying instrument directories</h3>
7724    
7725     <p>The front-end can copy a specific
7726     instrument directory by sending the following command:
7727     </p>
7728     <p>
7729     </p>
7730     <blockquote class="text">
7731     <p>COPY DB_INSTRUMENT_DIRECTORY &lt;dir&gt; &lt;dst&gt;
7732     </p>
7733     </blockquote><p>
7734    
7735     </p>
7736     <p>Where &lt;dir&gt; is the absolute path name of the directory
7737     to copy and &lt;dst&gt; is the location where the directory will
7738     be copied to.
7739     </p>
7740     <p>Possible Answers:
7741     </p>
7742     <p>
7743     </p>
7744     <blockquote class="text">
7745     <p>"OK" -
7746     </p>
7747     <blockquote class="text">
7748     <p>on success
7749     </p>
7750     </blockquote>
7751    
7752    
7753     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7754     </p>
7755     <blockquote class="text">
7756     <p>in case a given directory does not exists,
7757     or if a directory with name equal to the name
7758     of the specified directory already exists in
7759     the destination directory. Error is also thrown
7760     when trying to copy a directory to a subdirectory
7761     of itself.
7762     </p>
7763     </blockquote>
7764    
7765    
7766     </blockquote><p>
7767    
7768     </p>
7769     <p>Example:
7770     </p>
7771     <p>
7772     </p>
7773     <blockquote class="text">
7774     <p>C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic' '/Acoustic/Pianos'"
7775     </p>
7776     <p>S: "OK"
7777     </p>
7778     </blockquote><p>
7779    
7780     </p>
7781 iliev 1162 <a name="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"></a><br /><hr />
7782     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7783 iliev 1189 <a name="rfc.section.6.8.9"></a><h3>6.8.9.&nbsp;
7784 iliev 1162 Changing the description of directory</h3>
7785    
7786     <p>The front-end can alter the description of a specific
7787     instrument directory by sending the following command:
7788     </p>
7789     <p>
7790     </p>
7791     <blockquote class="text">
7792     <p>SET DB_INSTRUMENT_DIRECTORY DESCRIPTION &lt;dir&gt; &lt;desc&gt;
7793     </p>
7794     </blockquote><p>
7795    
7796     </p>
7797     <p>Where &lt;dir&gt; is the absolute path name of the directory and
7798 schoenebeck 1363 &lt;desc&gt; is the new description for the directory
7799     (encapsulated into apostrophes, supporting escape sequences as described in chapter
7800     "<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>").
7801 iliev 1162 </p>
7802     <p>Possible Answers:
7803     </p>
7804     <p>
7805     </p>
7806     <blockquote class="text">
7807     <p>"OK" -
7808     </p>
7809     <blockquote class="text">
7810     <p>on success
7811     </p>
7812     </blockquote>
7813    
7814    
7815     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7816     </p>
7817     <blockquote class="text">
7818     <p>in case the given directory does not exists.
7819     </p>
7820     </blockquote>
7821    
7822    
7823     </blockquote><p>
7824    
7825     </p>
7826     <p>Example:
7827     </p>
7828     <p>
7829     </p>
7830     <blockquote class="text">
7831     <p>C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A collection of piano instruments in various format.'"
7832     </p>
7833     <p>S: "OK"
7834     </p>
7835     </blockquote><p>
7836    
7837     </p>
7838 iliev 1189 <a name="FIND DB_INSTRUMENT_DIRECTORIES"></a><br /><hr />
7839     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7840     <a name="rfc.section.6.8.10"></a><h3>6.8.10.&nbsp;
7841     Finding directories</h3>
7842    
7843     <p>The front-end can search for directories
7844     in specific directory by sending the following command:
7845     </p>
7846     <p>
7847     </p>
7848     <blockquote class="text">
7849     <p>FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;
7850     </p>
7851     </blockquote><p>
7852    
7853     </p>
7854     <p>Where &lt;dir&gt; should be replaced by the absolute path
7855     name of the directory to search in. If NON_RECURSIVE is specified, the
7856     directories located in subdirectories of the specified directory will not
7857     be searched. &lt;criteria-list&gt; is a list of search criterias
7858     in form of "key1=val1 key2=val2 ...". The following criterias are
7859     allowed:
7860     </p>
7861     <p>
7862    
7863     <p>NAME='&lt;search-string&gt;'
7864     </p>
7865     <blockquote class="text">
7866     <p>Restricts the search to directories, which names
7867 schoenebeck 1363 satisfy the supplied search string (encapsulated into apostrophes,
7868     supporting escape sequences as described in chapter
7869     "<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>").
7870 iliev 1189 </p>
7871     </blockquote><p>
7872    
7873     </p>
7874    
7875    
7876     <p>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
7877     </p>
7878     <blockquote class="text">
7879     <p>Restricts the search to directories, which creation
7880     date satisfies the specified period, where &lt;date-after&gt;
7881     and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
7882     If &lt;date-after&gt; is omitted the search is restricted to
7883     directories created before &lt;date-before&gt;. If
7884     &lt;date-before&gt; is omitted, the search is restricted
7885     to directories created after &lt;date-after&gt;.
7886     </p>
7887     </blockquote><p>
7888    
7889     </p>
7890    
7891    
7892     <p>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
7893     </p>
7894     <blockquote class="text">
7895     <p>Restricts the search to directories, which
7896     date of last modification satisfies the specified period, where
7897     &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
7898     format. If &lt;date-after&gt; is omitted the search is restricted to
7899     directories, which are last modified before &lt;date-before&gt;. If
7900     &lt;date-before&gt; is omitted, the search is restricted to directories,
7901     which are last modified after &lt;date-after&gt;.
7902     </p>
7903     </blockquote><p>
7904    
7905     </p>
7906    
7907    
7908     <p>DESCRIPTION='&lt;search-string&gt;'
7909     </p>
7910     <blockquote class="text">
7911     <p>Restricts the search to directories with description
7912 schoenebeck 1363 that satisfies the supplied search string
7913     (encapsulated into apostrophes, supporting escape
7914     sequences as described in chapter
7915     "<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>").
7916 iliev 1189 </p>
7917     </blockquote><p>
7918    
7919     </p>
7920    
7921    
7922     <p>Where &lt;search-string&gt; is either a regular expression, or a
7923     word list separated with spaces for OR search and with '+' for AND search.
7924     </p>
7925     <p>Possible Answers:
7926     </p>
7927     <p>
7928     </p>
7929     <blockquote class="text">
7930     <p>A comma separated list with the absolute path names (encapsulated into
7931     apostrophes) of all directories in the specified directory that satisfy
7932     the supplied search criterias.
7933     </p>
7934     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
7935     </p>
7936     <blockquote class="text">
7937     <p>if the given directory does not exist.
7938     </p>
7939     </blockquote>
7940    
7941    
7942     </blockquote><p>
7943    
7944     </p>
7945     <p>Example:
7946     </p>
7947     <p>
7948     </p>
7949     <blockquote class="text">
7950     <p>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'"
7951     </p>
7952     <p>S: "'/Piano Collection'"
7953     </p>
7954     </blockquote><p>
7955    
7956     </p>
7957     <p>
7958     </p>
7959     <blockquote class="text">
7960     <p>C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:30:13'"
7961     </p>
7962     <p>S: "'/Piano Collection','/Percussions'"
7963     </p>
7964     </blockquote><p>
7965    
7966     </p>
7967 iliev 1162 <a name="ADD DB_INSTRUMENTS"></a><br /><hr />
7968     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
7969 iliev 1189 <a name="rfc.section.6.8.11"></a><h3>6.8.11.&nbsp;
7970 iliev 1162 Adding instruments to the instruments database</h3>
7971    
7972     <p>The front-end can add one or more instruments
7973     to the instruments database by sending the following command:
7974     </p>
7975     <p>
7976     </p>
7977     <blockquote class="text">
7978 iliev 1201 <p>ADD DB_INSTRUMENTS [NON_MODAL] [&lt;mode&gt;] &lt;db_dir&gt; &lt;file_path&gt; [&lt;instr_index&gt;]
7979 iliev 1162 </p>
7980     </blockquote><p>
7981    
7982     </p>
7983     <p>Where &lt;db_dir&gt; is the absolute path name of a directory
7984     (encapsulated into apostrophes) in the instruments database in which
7985     only the new instruments (that are not already in the database) will
7986     be added, &lt;file_path&gt; is the absolute path name of a file or
7987     directory in the file system (encapsulated into apostrophes). In case
7988     an instrument file is supplied, only the instruments in the specified
7989     file will be added to the instruments database. If the optional
7990     &lt;instr_index&gt; (the index of the instrument within the given file)
7991     is supplied too, then only the specified instrument will be added.
7992     In case a directory is supplied, the instruments in that directory
7993     will be added. The OPTIONAL &lt;mode&gt; argument is only applied
7994     when a directory is provided as &lt;file_path&gt; and specifies how the
7995     scanning will be done and has exactly the following possibilities:
7996     </p>
7997     <p>
7998     </p>
7999     <blockquote class="text">
8000 iliev 1201 <p>"RECURSIVE" -
8001     </p>
8002     <blockquote class="text">
8003     <p>All instruments will be processed, including those
8004     in the subdirectories, and the respective subdirectory
8005     tree structure will be recreated in the instruments
8006     database
8007     </p>
8008     </blockquote>
8009    
8010    
8011 iliev 1162 <p>"NON_RECURSIVE" -
8012     </p>
8013     <blockquote class="text">
8014     <p>Only the instruments in the specified directory
8015     will be added, the instruments in the subdirectories
8016     will not be processed.
8017     </p>
8018     </blockquote>
8019    
8020    
8021     <p>"FLAT" -
8022     </p>
8023     <blockquote class="text">
8024     <p>All instruments will be processed, including those
8025     in the subdirectories, but the respective subdirectory
8026     structure will not be recreated in the instruments
8027     database. All instruments will be added directly in
8028     the specified database directory.
8029     </p>
8030     </blockquote>
8031    
8032    
8033     </blockquote><p>
8034    
8035     </p>
8036 iliev 1201 <p>The difference between regular and NON_MODAL versions of the command
8037     is that the regular command returns when the scanning is finished
8038     while NON_MODAL version returns immediately and a background process is launched.
8039     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>
8040     command can be used to monitor the scanning progress.
8041     </p>
8042 iliev 1162 <p>Possible Answers:
8043     </p>
8044     <p>
8045     </p>
8046     <blockquote class="text">
8047     <p>"OK" -
8048     </p>
8049     <blockquote class="text">
8050 iliev 1201 <p>on success when NON_MODAL is not supplied
8051 iliev 1162 </p>
8052     </blockquote>
8053    
8054    
8055 iliev 1201 <p>"OK[&lt;job-id&gt;]" -
8056     </p>
8057     <blockquote class="text">
8058     <p>on success when NON_MODAL is supplied, where &lt;job-id&gt;
8059     is a numerical ID used to obtain status information about the job progress.
8060     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>
8061    
8062     </p>
8063     </blockquote>
8064    
8065    
8066 iliev 1162 <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8067     </p>
8068     <blockquote class="text">
8069     <p>if an invalid path is specified.
8070     </p>
8071     </blockquote>
8072    
8073    
8074     </blockquote><p>
8075    
8076     </p>
8077     <p>Examples:
8078     </p>
8079     <p>
8080     </p>
8081     <blockquote class="text">
8082     <p>C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI Bosendorfer 290.gig' 0"
8083     </p>
8084     <p>S: "OK"
8085     </p>
8086     </blockquote><p>
8087    
8088     </p>
8089     <a name="REMOVE DB_INSTRUMENT"></a><br /><hr />
8090     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8091 iliev 1189 <a name="rfc.section.6.8.12"></a><h3>6.8.12.&nbsp;
8092 iliev 1162 Removing an instrument</h3>
8093    
8094     <p>The front-end can remove a particular instrument
8095     from the instruments database by sending the following command:
8096     </p>
8097     <p>
8098     </p>
8099     <blockquote class="text">
8100     <p>REMOVE DB_INSTRUMENT &lt;instr_path&gt;
8101     </p>
8102     </blockquote><p>
8103    
8104     </p>
8105     <p>Where &lt;instr_path&gt; is the absolute path name
8106     (in the instruments database) of the instrument to remove.
8107     </p>
8108     <p>Possible Answers:
8109     </p>
8110     <p>
8111     </p>
8112     <blockquote class="text">
8113     <p>"OK" -
8114     </p>
8115     <blockquote class="text">
8116     <p>if the instrument is removed successfully
8117     </p>
8118     </blockquote>
8119    
8120    
8121     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8122     </p>
8123     <blockquote class="text">
8124     <p>if the given path does not exist or
8125     is a directory.
8126     </p>
8127     </blockquote>
8128    
8129    
8130     </blockquote><p>
8131    
8132     </p>
8133     <p>Examples:
8134     </p>
8135     <p>
8136     </p>
8137     <blockquote class="text">
8138     <p>C: "REMOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'"
8139     </p>
8140     <p>S: "OK"
8141     </p>
8142     </blockquote><p>
8143    
8144     </p>
8145     <a name="GET DB_INSTRUMENTS"></a><br /><hr />
8146     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8147 iliev 1189 <a name="rfc.section.6.8.13"></a><h3>6.8.13.&nbsp;
8148 iliev 1162 Getting amount of instruments</h3>
8149    
8150     <p>The front-end can retrieve the current amount of
8151     instruments in a specific directory by sending the following command:
8152     </p>
8153     <p>
8154     </p>
8155     <blockquote class="text">
8156 iliev 1189 <p>GET DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;
8157 iliev 1162 </p>
8158     </blockquote><p>
8159    
8160     </p>
8161     <p>Where &lt;dir&gt; should be replaced by the absolute path name
8162 iliev 1189 of the directory. If RECURSIVE is specified, the number of all
8163     instruments, including those located in subdirectories of the
8164     specified directory, will be returned.
8165 iliev 1162 </p>
8166     <p>Possible Answers:
8167     </p>
8168     <p>
8169     </p>
8170     <blockquote class="text">
8171     <p>The current number of instruments
8172     in the specified directory.
8173     </p>
8174     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8175     </p>
8176     <blockquote class="text">
8177     <p>if the given directory does not exist.
8178     </p>
8179     </blockquote>
8180    
8181    
8182     </blockquote><p>
8183    
8184     </p>
8185     <p>Example:
8186     </p>
8187     <p>
8188     </p>
8189     <blockquote class="text">
8190     <p>C: "GET DB_INSTRUMENTS '/Piano Collection'"
8191     </p>
8192     <p>S: "2"
8193     </p>
8194     </blockquote><p>
8195    
8196     </p>
8197     <a name="LIST DB_INSTRUMENTS"></a><br /><hr />
8198     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8199 iliev 1189 <a name="rfc.section.6.8.14"></a><h3>6.8.14.&nbsp;
8200 iliev 1162 Listing all instruments in specific directory</h3>
8201    
8202     <p>The front-end can retrieve the current list of instruments
8203     in specific directory by sending the following command:
8204     </p>
8205     <p>
8206     </p>
8207     <blockquote class="text">
8208 iliev 1189 <p>LIST DB_INSTRUMENTS [RECURSIVE] &lt;dir&gt;
8209 iliev 1162 </p>
8210     </blockquote><p>
8211    
8212     </p>
8213     <p>Where &lt;dir&gt; should be replaced by the absolute path
8214 iliev 1189 name of the directory. If RECURSIVE is specified, the absolute path
8215     names of all instruments, including those located in subdirectories
8216     of the specified directory, will be returned.
8217 iliev 1162 </p>
8218     <p>Possible Answers:
8219     </p>
8220     <p>
8221     </p>
8222     <blockquote class="text">
8223     <p>A comma separated list of all instruments
8224     (encapsulated into apostrophes) in the specified directory.
8225     </p>
8226     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8227     </p>
8228     <blockquote class="text">
8229     <p>if the given directory does not exist.
8230     </p>
8231     </blockquote>
8232    
8233    
8234     </blockquote><p>
8235    
8236     </p>
8237     <p>Example:
8238     </p>
8239     <p>
8240     </p>
8241     <blockquote class="text">
8242     <p>C: "LIST DB_INSTRUMENTS '/Piano Collection'"
8243     </p>
8244     <p>S: "'Bosendorfer 290','Steinway D'"
8245     </p>
8246     </blockquote><p>
8247    
8248     </p>
8249 iliev 1189 <p>
8250     </p>
8251     <blockquote class="text">
8252     <p>C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'"
8253     </p>
8254     <p>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D','/Piano Collection/Lite/Free Piano'"
8255     </p>
8256     </blockquote><p>
8257    
8258     </p>
8259 iliev 1162 <a name="GET DB_INSTRUMENT INFO"></a><br /><hr />
8260     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8261 iliev 1189 <a name="rfc.section.6.8.15"></a><h3>6.8.15.&nbsp;
8262 iliev 1162 Getting instrument information</h3>
8263    
8264     <p>The front-end can ask for the current settings of an
8265     instrument by sending the following command:
8266     </p>
8267     <p>
8268     </p>
8269     <blockquote class="text">
8270     <p>GET DB_INSTRUMENT INFO &lt;instr_path&gt;
8271     </p>
8272     </blockquote><p>
8273    
8274     </p>
8275     <p>Where &lt;instr_path&gt; should be replaced by the absolute path
8276     name of the instrument the front-end is interested in.
8277     </p>
8278     <p>Possible Answers:
8279     </p>
8280     <p>
8281     </p>
8282     <blockquote class="text">
8283     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
8284     Each answer line begins with the settings category name
8285     followed by a colon and then a space character &lt;SP&gt; and finally
8286     the info character string to that setting category. At the
8287     moment the following categories are defined:
8288     </p>
8289     <p>
8290     </p>
8291     <blockquote class="text">
8292     <p>INSTRUMENT_FILE -
8293     </p>
8294     <blockquote class="text">
8295     <p>File name of the instrument.
8296 schoenebeck 1363 Note that the character string may contain
8297     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
8298 iliev 1162 </p>
8299     </blockquote>
8300    
8301    
8302     <p>INSTRUMENT_NR -
8303     </p>
8304     <blockquote class="text">
8305     <p>Index of the instrument within the file.
8306     </p>
8307     </blockquote>
8308    
8309    
8310     <p>FORMAT_FAMILY -
8311     </p>
8312     <blockquote class="text">
8313     <p>The format family of the instrument.
8314     </p>
8315     </blockquote>
8316    
8317    
8318     <p>FORMAT_VERSION -
8319     </p>
8320     <blockquote class="text">
8321     <p>The format version of the instrument.
8322     </p>
8323     </blockquote>
8324    
8325    
8326     <p>SIZE -
8327     </p>
8328     <blockquote class="text">
8329     <p>The size of the instrument in bytes.
8330     </p>
8331     </blockquote>
8332    
8333    
8334     <p>CREATED -
8335     </p>
8336     <blockquote class="text">
8337     <p>The date and time when the instrument is added
8338     in the instruments database, represented in
8339     "YYYY-MM-DD HH:MM:SS" format
8340     </p>
8341     </blockquote>
8342    
8343    
8344     <p>MODIFIED -
8345     </p>
8346     <blockquote class="text">
8347     <p>The date and time of the last modification of the
8348     instrument's database settings, represented in
8349     "YYYY-MM-DD HH:MM:SS" format
8350     </p>
8351     </blockquote>
8352    
8353    
8354     <p>DESCRIPTION -
8355     </p>
8356     <blockquote class="text">
8357 schoenebeck 1363 <p>A brief description of the instrument.
8358     Note that the character string may contain
8359     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
8360 iliev 1162 </p>
8361     </blockquote>
8362    
8363    
8364     <p>IS_DRUM -
8365     </p>
8366     <blockquote class="text">
8367     <p>either true or false, determines whether the
8368     instrument is a drumkit or a chromatic instrument
8369     </p>
8370     </blockquote>
8371    
8372    
8373     <p>PRODUCT -
8374     </p>
8375     <blockquote class="text">
8376 schoenebeck 1363 <p>The product title of the instrument.
8377     Note that the character string may contain
8378     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
8379 iliev 1162 </p>
8380     </blockquote>
8381    
8382    
8383     <p>ARTISTS -
8384     </p>
8385     <blockquote class="text">
8386 schoenebeck 1363 <p>Lists the artist names.
8387     Note that the character string may contain
8388     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
8389 iliev 1162 </p>
8390     </blockquote>
8391    
8392    
8393     <p>KEYWORDS -
8394     </p>
8395     <blockquote class="text">
8396     <p>Provides a list of keywords that refer to the instrument.
8397     Keywords are separated with semicolon and blank.
8398 schoenebeck 1363 Note that the character string may contain
8399     <a class='info' href='#character_set'>escape sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>.
8400 iliev 1162 </p>
8401     </blockquote>
8402    
8403    
8404     </blockquote>
8405    
8406    
8407     </blockquote><p>
8408    
8409     </p>
8410     <p>The mentioned fields above don't have to be in particular order.
8411     </p>
8412     <p>Example:
8413     </p>
8414     <p>
8415     </p>
8416     <blockquote class="text">
8417     <p>C: "GET DB_INSTRUMENT INFO '/Piano Collection/Bosendorfer 290'"
8418     </p>
8419     <p>S: "INSTRUMENT_FILE: /home/me/gigs/Bosendorfer 290.gig"
8420     </p>
8421     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"
8422     </p>
8423     <p>&nbsp;&nbsp;&nbsp;"FORMAT_FAMILY: GIG"
8424     </p>
8425     <p>&nbsp;&nbsp;&nbsp;"FORMAT_VERSION: 2"
8426     </p>
8427     <p>&nbsp;&nbsp;&nbsp;"SIZE: 2050871870"
8428     </p>
8429     <p>&nbsp;&nbsp;&nbsp;"CREATED: 2007-02-05 10:23:12"
8430     </p>
8431     <p>&nbsp;&nbsp;&nbsp;"MODIFIED: 2007-04-07 12:50:21"
8432     </p>
8433     <p>&nbsp;&nbsp;&nbsp;"DESCRIPTION: "
8434     </p>
8435     <p>&nbsp;&nbsp;&nbsp;"IS_DRUM: false"
8436     </p>
8437     <p>&nbsp;&nbsp;&nbsp;"PRODUCT: GRANDIOSO Bosendorfer 290"
8438     </p>
8439     <p>&nbsp;&nbsp;&nbsp;"ARTISTS: Post Musical Instruments"
8440     </p>
8441     <p>&nbsp;&nbsp;&nbsp;"KEYWORDS: Bosendorfer"
8442     </p>
8443     <p>&nbsp;&nbsp;&nbsp;"."
8444     </p>
8445     </blockquote><p>
8446    
8447     </p>
8448     <a name="SET DB_INSTRUMENT NAME"></a><br /><hr />
8449     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8450 iliev 1189 <a name="rfc.section.6.8.16"></a><h3>6.8.16.&nbsp;
8451 iliev 1162 Renaming an instrument</h3>
8452    
8453     <p>The front-end can alter the name of a specific
8454     instrument by sending the following command:
8455     </p>
8456     <p>
8457     </p>
8458     <blockquote class="text">
8459     <p>SET DB_INSTRUMENT NAME &lt;instr&gt; &lt;name&gt;
8460     </p>
8461     </blockquote><p>
8462    
8463     </p>
8464     <p>Where &lt;instr&gt; is the absolute path name of the instrument and
8465     &lt;name&gt; is the new name for that instrument.
8466     </p>
8467     <p>Possible Answers:
8468     </p>
8469     <p>
8470     </p>
8471     <blockquote class="text">
8472     <p>"OK" -
8473     </p>
8474     <blockquote class="text">
8475     <p>on success
8476     </p>
8477     </blockquote>
8478    
8479    
8480     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8481     </p>
8482     <blockquote class="text">
8483     <p>in case the given instrument does not exists,
8484     or if an instrument with name equal to the new
8485     name already exists.
8486     </p>
8487     </blockquote>
8488    
8489    
8490     </blockquote><p>
8491    
8492     </p>
8493     <p>Example:
8494     </p>
8495     <p>
8496     </p>
8497     <blockquote class="text">
8498     <p>C: "SET DB_INSTRUMENT NAME '/Piano Collection/Bosendorfer' 'Bosendorfer 290'"
8499     </p>
8500     <p>S: "OK"
8501     </p>
8502     </blockquote><p>
8503    
8504     </p>
8505     <a name="MOVE DB_INSTRUMENT"></a><br /><hr />
8506     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8507 iliev 1189 <a name="rfc.section.6.8.17"></a><h3>6.8.17.&nbsp;
8508 iliev 1162 Moving an instrument</h3>
8509    
8510     <p>The front-end can move a specific instrument to another directory by
8511     sending the following command:
8512     </p>
8513     <p>
8514     </p>
8515     <blockquote class="text">
8516     <p>MOVE DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;
8517     </p>
8518     </blockquote><p>
8519    
8520     </p>
8521     <p>Where &lt;instr&gt; is the absolute path name of the instrument
8522     to move and &lt;dst&gt; is the directory where the instrument will
8523     be moved to.
8524     </p>
8525     <p>Possible Answers:
8526     </p>
8527     <p>
8528     </p>
8529     <blockquote class="text">
8530     <p>"OK" -
8531     </p>
8532     <blockquote class="text">
8533     <p>on success
8534     </p>
8535     </blockquote>
8536    
8537    
8538     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8539     </p>
8540     <blockquote class="text">
8541     <p>in case the given instrument does not exists,
8542     or if an instrument with name equal to the name of the
8543     specified instrument already exists in the destination
8544     directory.
8545     </p>
8546     </blockquote>
8547    
8548    
8549     </blockquote><p>
8550    
8551     </p>
8552     <p>Example:
8553     </p>
8554     <p>
8555     </p>
8556     <blockquote class="text">
8557     <p>C: "MOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Piano Collection/Acoustic'"
8558     </p>
8559     <p>S: "OK"
8560     </p>
8561     </blockquote><p>
8562    
8563     </p>
8564 iliev 1189 <a name="COPY DB_INSTRUMENT"></a><br /><hr />
8565     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8566     <a name="rfc.section.6.8.18"></a><h3>6.8.18.&nbsp;
8567     Copying instruments</h3>
8568    
8569     <p>The front-end can copy a specific instrument to another directory by
8570     sending the following command:
8571     </p>
8572     <p>
8573     </p>
8574     <blockquote class="text">
8575     <p>COPY DB_INSTRUMENT &lt;instr&gt; &lt;dst&gt;
8576     </p>
8577     </blockquote><p>
8578    
8579     </p>
8580     <p>Where &lt;instr&gt; is the absolute path name of the instrument
8581     to copy and &lt;dst&gt; is the directory where the instrument will
8582     be copied to.
8583     </p>
8584     <p>Possible Answers:
8585     </p>
8586     <p>
8587     </p>
8588     <blockquote class="text">
8589     <p>"OK" -
8590     </p>
8591     <blockquote class="text">
8592     <p>on success
8593     </p>
8594     </blockquote>
8595    
8596    
8597     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8598     </p>
8599     <blockquote class="text">
8600     <p>in case the given instrument does not exists,
8601     or if an instrument with name equal to the name of the
8602     specified instrument already exists in the destination
8603     directory.
8604     </p>
8605     </blockquote>
8606    
8607    
8608     </blockquote><p>
8609    
8610     </p>
8611     <p>Example:
8612     </p>
8613     <p>
8614     </p>
8615     <blockquote class="text">
8616     <p>C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Acoustic/Pianos/'"
8617     </p>
8618     <p>S: "OK"
8619     </p>
8620     </blockquote><p>
8621    
8622     </p>
8623 iliev 1162 <a name="SET DB_INSTRUMENT DESCRIPTION"></a><br /><hr />
8624     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8625 iliev 1189 <a name="rfc.section.6.8.19"></a><h3>6.8.19.&nbsp;
8626 iliev 1162 Changing the description of instrument</h3>
8627    
8628     <p>The front-end can alter the description of a specific
8629     instrument by sending the following command:
8630     </p>
8631     <p>
8632     </p>
8633     <blockquote class="text">
8634     <p>SET DB_INSTRUMENT DESCRIPTION &lt;instr&gt; &lt;desc&gt;
8635     </p>
8636     </blockquote><p>
8637    
8638     </p>
8639     <p>Where &lt;instr&gt; is the absolute path name of the instrument and
8640 schoenebeck 1363 &lt;desc&gt; is the new description for the instrument
8641     (encapsulated into apostrophes, supporting escape sequences as described in chapter
8642     "<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>").
8643 iliev 1162 </p>
8644     <p>Possible Answers:
8645     </p>
8646     <p>
8647     </p>
8648     <blockquote class="text">
8649     <p>"OK" -
8650     </p>
8651     <blockquote class="text">
8652     <p>on success
8653     </p>
8654     </blockquote>
8655    
8656    
8657     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8658     </p>
8659     <blockquote class="text">
8660     <p>in case the given instrument does not exists.
8661     </p>
8662     </blockquote>
8663    
8664    
8665     </blockquote><p>
8666    
8667     </p>
8668     <p>Example:
8669     </p>
8670     <p>
8671     </p>
8672     <blockquote class="text">
8673     <p>C: "SET DB_INSTRUMENT DESCRIPTION '/Piano Collection/Acoustic/Bosendorfer 290' 'No comment :)'"
8674     </p>
8675     <p>S: "OK"
8676     </p>
8677     </blockquote><p>
8678    
8679     </p>
8680 iliev 1189 <a name="FIND DB_INSTRUMENTS"></a><br /><hr />
8681     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8682     <a name="rfc.section.6.8.20"></a><h3>6.8.20.&nbsp;
8683     Finding instruments</h3>
8684    
8685     <p>The front-end can search for instruments
8686     in specific directory by sending the following command:
8687     </p>
8688     <p>
8689     </p>
8690     <blockquote class="text">
8691     <p>FIND DB_INSTRUMENTS [NON_RECURSIVE] &lt;dir&gt; &lt;criteria-list&gt;
8692     </p>
8693     </blockquote><p>
8694    
8695     </p>
8696     <p>Where &lt;dir&gt; should be replaced by the absolute path
8697     name of the directory to search in. If NON_RECURSIVE is specified, the
8698     directories located in subdirectories of the specified directory will not
8699     be searched. &lt;criteria-list&gt; is a list of search criterias
8700     in form of "key1=val1 key2=val2 ...". The following criterias are
8701     allowed:
8702     </p>
8703     <p>
8704    
8705     <p>NAME='&lt;search-string&gt;'
8706     </p>
8707     <blockquote class="text">
8708     <p>Restricts the search to instruments, which names
8709 schoenebeck 1363 satisfy the supplied search string (encapsulated into apostrophes,
8710     supporting escape sequences as described in chapter
8711     "<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>").
8712 iliev 1189 </p>
8713     </blockquote><p>
8714    
8715     </p>
8716    
8717    
8718     <p>SIZE=[&lt;min&gt;]..[&lt;max&gt;]
8719     </p>
8720     <blockquote class="text">
8721 schoenebeck 1251 <p>Restricts the search to instruments, which
8722 iliev 1189 size is in the specified range. If &lt;min&gt; is omitted,
8723     the search results are restricted to instruments with size less then
8724     or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the
8725     search is restricted to instruments with size greater then
8726     or equal to &lt;min&gt;.
8727     </p>
8728     </blockquote><p>
8729    
8730     </p>
8731    
8732    
8733     <p>CREATED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
8734     </p>
8735     <blockquote class="text">
8736     <p>Restricts the search to instruments, which creation
8737     date satisfies the specified period, where &lt;date-after&gt;
8738     and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS" format.
8739     If &lt;date-after&gt; is omitted the search is restricted to
8740     instruments created before &lt;date-before&gt;. If
8741     &lt;date-before&gt; is omitted, the search is restricted
8742     to instruments created after &lt;date-after&gt;.
8743     </p>
8744     </blockquote><p>
8745    
8746     </p>
8747    
8748    
8749     <p>MODIFIED='[&lt;date-after&gt;]..[&lt;date-before&gt;]'
8750     </p>
8751     <blockquote class="text">
8752     <p>Restricts the search to instruments, which
8753     date of last modification satisfies the specified period, where
8754     &lt;date-after&gt; and &lt;date-before&gt; are in "YYYY-MM-DD HH:MM:SS"
8755     format. If &lt;date-after&gt; is omitted the search is restricted to
8756     instruments, which are last modified before &lt;date-before&gt;. If
8757     &lt;date-before&gt; is omitted, the search is restricted to instruments,
8758     which are last modified after &lt;date-after&gt;.
8759     </p>
8760     </blockquote><p>
8761    
8762     </p>
8763    
8764    
8765     <p>DESCRIPTION='&lt;search-string&gt;'
8766     </p>
8767     <blockquote class="text">
8768     <p>Restricts the search to instruments with description
8769 schoenebeck 1363 that satisfies the supplied search string (encapsulated into apostrophes,
8770     supporting escape sequences as described in chapter
8771     "<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>").
8772 iliev 1189 </p>
8773     </blockquote><p>
8774    
8775     </p>
8776    
8777    
8778     <p>PRODUCT='&lt;search-string&gt;'
8779     </p>
8780     <blockquote class="text">
8781     <p>Restricts the search to instruments with product info
8782 schoenebeck 1363 that satisfies the supplied search string (encapsulated into apostrophes,
8783     supporting escape sequences as described in chapter
8784     "<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>").
8785 iliev 1189 </p>
8786     </blockquote><p>
8787    
8788     </p>
8789    
8790    
8791     <p>ARTISTS='&lt;search-string&gt;'
8792     </p>
8793     <blockquote class="text">
8794     <p>Restricts the search to instruments with artists info
8795 schoenebeck 1363 that satisfies the supplied search string (encapsulated into apostrophes,
8796     supporting escape sequences as described in chapter
8797     "<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>").
8798 iliev 1189 </p>
8799     </blockquote><p>
8800    
8801     </p>
8802    
8803    
8804     <p>KEYWORDS='&lt;search-string&gt;'
8805     </p>
8806     <blockquote class="text">
8807     <p>Restricts the search to instruments with keyword list
8808 schoenebeck 1363 that satisfies the supplied search string (encapsulated into apostrophes,
8809     supporting escape sequences as described in chapter
8810     "<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>").
8811 iliev 1189 </p>
8812     </blockquote><p>
8813    
8814     </p>
8815    
8816    
8817     <p>IS_DRUM=true | false
8818     </p>
8819     <blockquote class="text">
8820 schoenebeck 1251 <p>Either true or false. Restricts the search to
8821 iliev 1189 drum kits or chromatic instruments.
8822     </p>
8823     </blockquote><p>
8824    
8825     </p>
8826    
8827    
8828     <p>FORMAT_FAMILIES='&lt;format-list&gt;'
8829     </p>
8830     <blockquote class="text">
8831     <p>Restricts the search to instruments of the supplied format families,
8832     where &lt;format-list&gt; is a comma separated list of format families.
8833     </p>
8834     </blockquote><p>
8835    
8836     </p>
8837    
8838    
8839     <p>Where &lt;search-string&gt; is either a regular expression, or a
8840     word list separated with spaces for OR search and with '+' for AND search.
8841     </p>
8842     <p>Possible Answers:
8843     </p>
8844     <p>
8845     </p>
8846     <blockquote class="text">
8847     <p>A comma separated list with the absolute path names (encapsulated into
8848     apostrophes) of all instruments in the specified directory that satisfy
8849     the supplied search criterias.
8850     </p>
8851     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
8852     </p>
8853     <blockquote class="text">
8854     <p>if the given directory does not exist.
8855     </p>
8856     </blockquote>
8857    
8858    
8859     </blockquote><p>
8860    
8861     </p>
8862     <p>Example:
8863     </p>
8864     <p>
8865     </p>
8866     <blockquote class="text">
8867     <p>C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+290'"
8868     </p>
8869     <p>S: "'/Piano Collection/Bosendorfer 290'"
8870     </p>
8871     </blockquote><p>
8872    
8873     </p>
8874     <p>
8875     </p>
8876     <blockquote class="text">
8877     <p>C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01 09:30:13..'"
8878     </p>
8879     <p>S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D'"
8880     </p>
8881     </blockquote><p>
8882    
8883     </p>
8884 iliev 1201 <a name="GET DB_INSTRUMENTS_JOB INFO"></a><br /><hr />
8885     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8886     <a name="rfc.section.6.8.21"></a><h3>6.8.21.&nbsp;
8887     Getting job status information</h3>
8888    
8889     <p>The front-end can ask for the current status of a
8890     particular database instruments job by sending the following command:
8891     </p>
8892     <p>
8893     </p>
8894     <blockquote class="text">
8895     <p>GET DB_INSTRUMENTS_JOB INFO &lt;job-id&gt;
8896     </p>
8897     </blockquote><p>
8898    
8899     </p>
8900     <p>Where &lt;job-id&gt; should be replaced by the numerical ID
8901     of the job the front-end is interested in.
8902     </p>
8903     <p>Possible Answers:
8904     </p>
8905     <p>
8906     </p>
8907     <blockquote class="text">
8908     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
8909     Each answer line begins with the settings category name
8910     followed by a colon and then a space character &lt;SP&gt; and finally
8911     the info character string to that setting category. At the
8912     moment the following categories are defined:
8913     </p>
8914     <p>
8915     </p>
8916     <blockquote class="text">
8917     <p>FILES_TOTAL -
8918     </p>
8919     <blockquote class="text">
8920     <p>The total number of files scheduled for scanning
8921     </p>
8922     </blockquote>
8923    
8924    
8925     <p>FILES_SCANNED -
8926     </p>
8927     <blockquote class="text">
8928     <p>The current number of scanned files
8929     </p>
8930     </blockquote>
8931    
8932    
8933     <p>SCANNING -
8934     </p>
8935     <blockquote class="text">
8936     <p>The absolute path name of the file which is currently
8937     being scanned
8938     </p>
8939     </blockquote>
8940    
8941    
8942     <p>STATUS -
8943     </p>
8944     <blockquote class="text">
8945     <p>An integer value between 0 and 100 indicating the
8946     scanning progress percentage of the file which is
8947     currently being scanned
8948     </p>
8949     </blockquote>
8950    
8951    
8952     </blockquote>
8953    
8954    
8955     </blockquote><p>
8956    
8957     </p>
8958     <p>The mentioned fields above don't have to be in particular order.
8959     </p>
8960     <p>Example:
8961     </p>
8962     <p>
8963     </p>
8964     <blockquote class="text">
8965     <p>C: "GET DB_INSTRUMENTS_JOB INFO 2"
8966     </p>
8967     <p>S: "FILES_TOTAL: 12"
8968     </p>
8969     <p>&nbsp;&nbsp;&nbsp;"FILES_SCANNED: 7"
8970     </p>
8971     <p>&nbsp;&nbsp;&nbsp;"SCANNING: /home/me/gigs/Bosendorfer 290.gig"
8972     </p>
8973     <p>&nbsp;&nbsp;&nbsp;"STATUS: 42"
8974     </p>
8975     <p>&nbsp;&nbsp;&nbsp;"."
8976     </p>
8977     </blockquote><p>
8978    
8979     </p>
8980 schoenebeck 1363 <a name="FORMAT INSTRUMENTS_DB"></a><br /><hr />
8981     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
8982     <a name="rfc.section.6.8.22"></a><h3>6.8.22.&nbsp;
8983     Formatting the instruments database</h3>
8984    
8985     <p>The front-end can remove all instruments and directories and re-create
8986     the instruments database structure (e.g., in case of a database corruption)
8987     by sending the following command:
8988     </p>
8989     <p>
8990     </p>
8991     <blockquote class="text">
8992     <p>FORMAT INSTRUMENTS_DB
8993     </p>
8994     </blockquote><p>
8995    
8996     </p>
8997     <p>Possible Answers:
8998     </p>
8999     <p>
9000     </p>
9001     <blockquote class="text">
9002     <p>"OK" -
9003     </p>
9004     <blockquote class="text">
9005     <p>on success
9006     </p>
9007     </blockquote>
9008    
9009    
9010     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
9011     </p>
9012     <blockquote class="text">
9013     <p>If the formatting of the instruments database
9014     failed.
9015     </p>
9016     </blockquote>
9017    
9018    
9019     </blockquote><p>
9020    
9021     </p>
9022     <a name="editing_instruments"></a><br /><hr />
9023     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9024     <a name="rfc.section.6.9"></a><h3>6.9.&nbsp;
9025     Editing Instruments</h3>
9026    
9027     <p>The sampler allows to edit instruments while playing with the
9028     sampler by spawning an external (3rd party) instrument editor
9029     application for a given instrument. The 3rd party instrument
9030     editor applications have to place a respective plugin DLL file
9031     into the sampler's plugins directory. The sampler will
9032     automatically try to load all plugin DLLs in that directory on
9033     startup and only on startup!
9034     </p>
9035     <p>At the moment there is only one command for this feature set,
9036     but this will most probably change in future.
9037     </p>
9038     <a name="EDIT INSTRUMENT"></a><br /><hr />
9039     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
9040     <a name="rfc.section.6.9.1"></a><h3>6.9.1.&nbsp;
9041     Opening an appropriate instrument editor application</h3>
9042    
9043     <p>The front-end can request to open an appropriate instrument
9044     editor application by sending the following command:
9045     </p>
9046     <p>
9047     </p>
9048     <blockquote class="text">
9049     <p>EDIT INSTRUMENT &lt;sampler-channel&gt;
9050     </p>
9051     </blockquote><p>
9052    
9053     </p>
9054     <p>Where &lt;sampler-channel&gt; should be replaced by the
9055     number of the sampler channel as given by the
9056     <a class='info' href='#ADD CHANNEL'>"ADD CHANNEL"<span> (</span><span class='info'>Adding a new sampler channel</span><span>)</span></a>
9057     or <a class='info' href='#LIST CHANNELS'>"LIST CHANNELS"<span> (</span><span class='info'>Getting all created sampler channel list</span><span>)</span></a>
9058     command.
9059     </p>
9060     <p>The sampler will try to ask all registered instrument
9061     editors (or to be more specific: their sampler plugins)
9062     whether they are capable to handle the instrument on the
9063     given sampler channel. The sampler will simply use the first
9064     instrument editor application which replied with a positive
9065     answer and spawn that instrument editor application within
9066     the sampler's process and provide that application access
9067     to the instrument's data structures, so both applications
9068     can share and access the same instruments data at the same
9069     time, thus allowing to immediately hear changes with the
9070     sampler made by the instrument editor.
9071     </p>
9072     <p>Note: consequently instrument editors are always spawned
9073     locally on the same machine where the sampler is running
9074     on!
9075     </p>
9076     <p>Possible Answers:
9077     </p>
9078     <p>
9079     </p>
9080     <blockquote class="text">
9081     <p>"OK" -
9082     </p>
9083     <blockquote class="text">
9084     <p>when an appropriate instrument editor was
9085     launched
9086     </p>
9087     </blockquote>
9088    
9089    
9090     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
9091     </p>
9092     <blockquote class="text">
9093     <p>when an appropriate instrument editor was
9094     launched, but there are noteworthy issues
9095     </p>
9096     </blockquote>
9097    
9098    
9099     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
9100     </p>
9101     <blockquote class="text">
9102     <p>when an appropriate instrument editor
9103     could not be launched
9104     </p>
9105     </blockquote>
9106    
9107    
9108     </blockquote><p>
9109    
9110     </p>
9111     <p>Examples:
9112     </p>
9113     <p>
9114     </p>
9115     <blockquote class="text">
9116     <p>C: "EDIT INSTRUMENT 0"
9117     </p>
9118     <p>S: "OK"
9119     </p>
9120     </blockquote><p>
9121    
9122     </p>
9123 senoner 542 <a name="command_syntax"></a><br /><hr />
9124 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>
9125     <a name="rfc.section.7"></a><h3>7.&nbsp;
9126     Command Syntax</h3>
9127 senoner 542
9128 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>
9129     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>)
9130 schoenebeck 575 where applicable.
9131 schoenebeck 940
9132 senoner 542 </p>
9133 schoenebeck 575 <p>input =
9134     </p>
9135     <blockquote class="text">
9136     <p>line LF
9137 schoenebeck 940
9138 schoenebeck 575 </p>
9139     <p>/ line CR LF
9140 schoenebeck 940
9141 schoenebeck 575 </p>
9142 schoenebeck 708 </blockquote><p>
9143 schoenebeck 575
9144 schoenebeck 708 </p>
9145 schoenebeck 575 <p>line =
9146     </p>
9147     <blockquote class="text">
9148     <p>/* epsilon (empty line ignored) */
9149 schoenebeck 940
9150 schoenebeck 575 </p>
9151     <p>/ comment
9152 schoenebeck 940
9153 schoenebeck 575 </p>
9154     <p>/ command
9155 schoenebeck 940
9156 schoenebeck 575 </p>
9157     <p>/ error
9158 schoenebeck 940
9159 schoenebeck 575 </p>
9160 schoenebeck 708 </blockquote><p>
9161 schoenebeck 575
9162 schoenebeck 708 </p>
9163 schoenebeck 575 <p>comment =
9164     </p>
9165     <blockquote class="text">
9166     <p>'#'
9167 schoenebeck 940
9168 schoenebeck 575 </p>
9169     <p>/ comment '#'
9170 schoenebeck 940
9171 schoenebeck 575 </p>
9172     <p>/ comment SP
9173 schoenebeck 940
9174 schoenebeck 575 </p>
9175     <p>/ comment number
9176 schoenebeck 940
9177 schoenebeck 575 </p>
9178     <p>/ comment string
9179 schoenebeck 940
9180 schoenebeck 575 </p>
9181 schoenebeck 708 </blockquote><p>
9182 schoenebeck 575
9183 schoenebeck 708 </p>
9184 schoenebeck 575 <p>command =
9185     </p>
9186     <blockquote class="text">
9187 schoenebeck 974 <p>ADD SP add_instruction
9188 schoenebeck 940
9189 schoenebeck 575 </p>
9190 schoenebeck 945 <p>/ MAP SP map_instruction
9191    
9192     </p>
9193     <p>/ UNMAP SP unmap_instruction
9194    
9195     </p>
9196 schoenebeck 575 <p>/ GET SP get_instruction
9197 schoenebeck 940
9198 schoenebeck 575 </p>
9199     <p>/ CREATE SP create_instruction
9200 schoenebeck 940
9201 schoenebeck 575 </p>
9202     <p>/ DESTROY SP destroy_instruction
9203 schoenebeck 940
9204 schoenebeck 575 </p>
9205     <p>/ LIST SP list_instruction
9206 schoenebeck 940
9207 schoenebeck 575 </p>
9208     <p>/ LOAD SP load_instruction
9209 schoenebeck 940
9210 schoenebeck 575 </p>
9211 schoenebeck 945 <p>/ REMOVE SP remove_instruction
9212 schoenebeck 940
9213 schoenebeck 575 </p>
9214     <p>/ SET SP set_instruction
9215 schoenebeck 940
9216 schoenebeck 575 </p>
9217     <p>/ SUBSCRIBE SP subscribe_event
9218 schoenebeck 940
9219 schoenebeck 575 </p>
9220     <p>/ UNSUBSCRIBE SP unsubscribe_event
9221 schoenebeck 940
9222 schoenebeck 575 </p>
9223 schoenebeck 945 <p>/ RESET SP reset_instruction
9224 schoenebeck 940
9225 schoenebeck 575 </p>
9226 schoenebeck 945 <p>/ CLEAR SP clear_instruction
9227    
9228     </p>
9229 iliev 1189 <p>/ FIND SP find_instruction
9230    
9231     </p>
9232 iliev 1162 <p>/ MOVE SP move_instruction
9233    
9234     </p>
9235 iliev 1189 <p>/ COPY SP copy_instruction
9236    
9237     </p>
9238 schoenebeck 1251 <p>/ EDIT SP edit_instruction
9239    
9240     </p>
9241 schoenebeck 1363 <p>/ FORMAT SP format_instruction
9242    
9243     </p>
9244 schoenebeck 575 <p>/ RESET
9245 schoenebeck 940
9246 schoenebeck 575 </p>
9247     <p>/ QUIT
9248 schoenebeck 940
9249 schoenebeck 575 </p>
9250 schoenebeck 708 </blockquote><p>
9251 schoenebeck 575
9252 schoenebeck 708 </p>
9253 schoenebeck 974 <p>add_instruction =
9254     </p>
9255     <blockquote class="text">
9256     <p>CHANNEL
9257    
9258     </p>
9259 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORY SP db_path
9260 iliev 1162
9261     </p>
9262 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename
9263 iliev 1162
9264     </p>
9265 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename
9266 iliev 1162
9267     </p>
9268 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
9269 iliev 1201
9270     </p>
9271 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index
9272 iliev 1201
9273     </p>
9274 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP db_path SP filename
9275 iliev 1162
9276     </p>
9277 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP db_path SP filename SP instrument_index
9278 iliev 1162
9279     </p>
9280 schoenebeck 974 <p>/ MIDI_INSTRUMENT_MAP
9281    
9282     </p>
9283     <p>/ MIDI_INSTRUMENT_MAP SP map_name
9284    
9285     </p>
9286     </blockquote><p>
9287    
9288     </p>
9289 schoenebeck 575 <p>subscribe_event =
9290     </p>
9291     <blockquote class="text">
9292 iliev 992 <p>AUDIO_OUTPUT_DEVICE_COUNT
9293 schoenebeck 940
9294 schoenebeck 575 </p>
9295 iliev 992 <p>/ AUDIO_OUTPUT_DEVICE_INFO
9296    
9297     </p>
9298     <p>/ MIDI_INPUT_DEVICE_COUNT
9299    
9300     </p>
9301     <p>/ MIDI_INPUT_DEVICE_INFO
9302    
9303     </p>
9304     <p>/ CHANNEL_COUNT
9305    
9306     </p>
9307 schoenebeck 575 <p>/ VOICE_COUNT
9308 schoenebeck 940
9309 schoenebeck 575 </p>
9310     <p>/ STREAM_COUNT
9311 schoenebeck 940
9312 schoenebeck 575 </p>
9313     <p>/ BUFFER_FILL
9314 schoenebeck 940
9315 schoenebeck 575 </p>
9316     <p>/ CHANNEL_INFO
9317 schoenebeck 940
9318 schoenebeck 575 </p>
9319 iliev 1110 <p>/ FX_SEND_COUNT
9320    
9321     </p>
9322     <p>/ FX_SEND_INFO
9323    
9324     </p>
9325 iliev 992 <p>/ MIDI_INSTRUMENT_MAP_COUNT
9326    
9327     </p>
9328     <p>/ MIDI_INSTRUMENT_MAP_INFO
9329    
9330     </p>
9331     <p>/ MIDI_INSTRUMENT_COUNT
9332    
9333     </p>
9334     <p>/ MIDI_INSTRUMENT_INFO
9335    
9336     </p>
9337 iliev 1162 <p>/ DB_INSTRUMENT_DIRECTORY_COUNT
9338    
9339     </p>
9340     <p>/ DB_INSTRUMENT_DIRECTORY_INFO
9341    
9342     </p>
9343     <p>/ DB_INSTRUMENT_COUNT
9344    
9345     </p>
9346     <p>/ DB_INSTRUMENT_INFO
9347    
9348     </p>
9349 iliev 1201 <p>/ DB_INSTRUMENTS_JOB_INFO
9350    
9351     </p>
9352 schoenebeck 575 <p>/ MISCELLANEOUS
9353 schoenebeck 940
9354 schoenebeck 575 </p>
9355 schoenebeck 940 <p>/ TOTAL_VOICE_COUNT
9356    
9357     </p>
9358 iliev 1110 <p>/ GLOBAL_INFO
9359    
9360     </p>
9361 schoenebeck 708 </blockquote><p>
9362 schoenebeck 575
9363 schoenebeck 708 </p>
9364 schoenebeck 575 <p>unsubscribe_event =
9365     </p>
9366     <blockquote class="text">
9367 iliev 992 <p>AUDIO_OUTPUT_DEVICE_COUNT
9368 schoenebeck 940
9369 schoenebeck 575 </p>
9370 iliev 992 <p>/ AUDIO_OUTPUT_DEVICE_INFO
9371    
9372     </p>
9373     <p>/ MIDI_INPUT_DEVICE_COUNT
9374    
9375     </p>
9376     <p>/ MIDI_INPUT_DEVICE_INFO
9377    
9378     </p>
9379     <p>/ CHANNEL_COUNT
9380    
9381     </p>
9382 schoenebeck 575 <p>/ VOICE_COUNT
9383 schoenebeck 940
9384 schoenebeck 575 </p>
9385     <p>/ STREAM_COUNT
9386 schoenebeck 940
9387 schoenebeck 575 </p>
9388     <p>/ BUFFER_FILL
9389 schoenebeck 940
9390 schoenebeck 575 </p>
9391     <p>/ CHANNEL_INFO
9392 schoenebeck 940
9393 schoenebeck 575 </p>
9394 iliev 1110 <p>/ FX_SEND_COUNT
9395    
9396     </p>
9397     <p>/ FX_SEND_INFO
9398    
9399     </p>
9400 iliev 992 <p>/ MIDI_INSTRUMENT_MAP_COUNT
9401    
9402     </p>
9403     <p>/ MIDI_INSTRUMENT_MAP_INFO
9404    
9405     </p>
9406     <p>/ MIDI_INSTRUMENT_COUNT
9407    
9408     </p>
9409     <p>/ MIDI_INSTRUMENT_INFO
9410    
9411     </p>
9412 iliev 1162 <p>/ DB_INSTRUMENT_DIRECTORY_COUNT
9413    
9414     </p>
9415     <p>/ DB_INSTRUMENT_DIRECTORY_INFO
9416    
9417     </p>
9418     <p>/ DB_INSTRUMENT_COUNT
9419    
9420     </p>
9421     <p>/ DB_INSTRUMENT_INFO
9422    
9423     </p>
9424 iliev 1201 <p>/ DB_INSTRUMENTS_JOB_INFO
9425    
9426     </p>
9427 schoenebeck 575 <p>/ MISCELLANEOUS
9428 schoenebeck 940
9429 schoenebeck 575 </p>
9430 schoenebeck 940 <p>/ TOTAL_VOICE_COUNT
9431    
9432     </p>
9433 iliev 1110 <p>/ GLOBAL_INFO
9434    
9435     </p>
9436 schoenebeck 708 </blockquote><p>
9437 schoenebeck 575
9438 schoenebeck 708 </p>
9439 schoenebeck 945 <p>map_instruction =
9440     </p>
9441     <blockquote class="text">
9442 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
9443 schoenebeck 945
9444     </p>
9445 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
9446 schoenebeck 945
9447     </p>
9448 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
9449 schoenebeck 945
9450     </p>
9451 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
9452 schoenebeck 945
9453     </p>
9454     </blockquote><p>
9455    
9456     </p>
9457     <p>unmap_instruction =
9458     </p>
9459     <blockquote class="text">
9460 schoenebeck 974 <p>MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog
9461 schoenebeck 945
9462     </p>
9463     </blockquote><p>
9464    
9465     </p>
9466     <p>remove_instruction =
9467     </p>
9468     <blockquote class="text">
9469     <p>CHANNEL SP sampler_channel
9470    
9471     </p>
9472 schoenebeck 974 <p>/ MIDI_INSTRUMENT_MAP SP midi_map
9473    
9474     </p>
9475     <p>/ MIDI_INSTRUMENT_MAP SP ALL
9476    
9477     </p>
9478 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path
9479 iliev 1162
9480     </p>
9481 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORY SP db_path
9482 iliev 1162
9483     </p>
9484 schoenebeck 1363 <p>/ DB_INSTRUMENT SP db_path
9485 iliev 1162
9486     </p>
9487 schoenebeck 945 </blockquote><p>
9488    
9489     </p>
9490 schoenebeck 575 <p>get_instruction =
9491     </p>
9492     <blockquote class="text">
9493     <p>AVAILABLE_ENGINES
9494 schoenebeck 940
9495 schoenebeck 575 </p>
9496     <p>/ AVAILABLE_MIDI_INPUT_DRIVERS
9497 schoenebeck 940
9498 schoenebeck 575 </p>
9499     <p>/ MIDI_INPUT_DRIVER SP INFO SP string
9500 schoenebeck 940
9501 schoenebeck 575 </p>
9502     <p>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
9503 schoenebeck 940
9504 schoenebeck 575 </p>
9505     <p>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
9506 schoenebeck 940
9507 schoenebeck 575 </p>
9508     <p>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
9509 schoenebeck 940
9510 schoenebeck 575 </p>
9511     <p>/ AUDIO_OUTPUT_DRIVER SP INFO SP string
9512 schoenebeck 940
9513 schoenebeck 575 </p>
9514     <p>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
9515 schoenebeck 940
9516 schoenebeck 575 </p>
9517     <p>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
9518 schoenebeck 940
9519 schoenebeck 575 </p>
9520     <p>/ AUDIO_OUTPUT_DEVICES
9521 schoenebeck 940
9522 schoenebeck 575 </p>
9523     <p>/ MIDI_INPUT_DEVICES
9524 schoenebeck 940
9525 schoenebeck 575 </p>
9526     <p>/ AUDIO_OUTPUT_DEVICE SP INFO SP number
9527 schoenebeck 940
9528 schoenebeck 575 </p>
9529     <p>/ MIDI_INPUT_DEVICE SP INFO SP number
9530 schoenebeck 940
9531 schoenebeck 575 </p>
9532     <p>/ MIDI_INPUT_PORT SP INFO SP number SP number
9533 schoenebeck 940
9534 schoenebeck 575 </p>
9535     <p>/ MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
9536 schoenebeck 940
9537 schoenebeck 575 </p>
9538     <p>/ AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
9539 schoenebeck 940
9540 schoenebeck 575 </p>
9541     <p>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP string
9542 schoenebeck 940
9543 schoenebeck 575 </p>
9544     <p>/ CHANNELS
9545 schoenebeck 940
9546 schoenebeck 575 </p>
9547     <p>/ CHANNEL SP INFO SP sampler_channel
9548 schoenebeck 940
9549 schoenebeck 575 </p>
9550     <p>/ CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
9551 schoenebeck 940
9552 schoenebeck 575 </p>
9553     <p>/ CHANNEL SP STREAM_COUNT SP sampler_channel
9554 schoenebeck 940
9555 schoenebeck 575 </p>
9556     <p>/ CHANNEL SP VOICE_COUNT SP sampler_channel
9557 schoenebeck 940
9558 schoenebeck 575 </p>
9559     <p>/ ENGINE SP INFO SP engine_name
9560 schoenebeck 940
9561 schoenebeck 575 </p>
9562     <p>/ SERVER SP INFO
9563 schoenebeck 940
9564 schoenebeck 575 </p>
9565 schoenebeck 940 <p>/ TOTAL_VOICE_COUNT
9566    
9567     </p>
9568     <p>/ TOTAL_VOICE_COUNT_MAX
9569    
9570     </p>
9571 schoenebeck 974 <p>/ MIDI_INSTRUMENTS SP midi_map
9572 schoenebeck 945
9573     </p>
9574 schoenebeck 974 <p>/ MIDI_INSTRUMENTS SP ALL
9575 schoenebeck 945
9576     </p>
9577 schoenebeck 974 <p>/ MIDI_INSTRUMENT SP INFO SP midi_map SP midi_bank SP midi_prog
9578    
9579     </p>
9580     <p>/ MIDI_INSTRUMENT_MAPS
9581    
9582     </p>
9583     <p>/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map
9584    
9585     </p>
9586 schoenebeck 1002 <p>/ FX_SENDS SP sampler_channel
9587    
9588     </p>
9589     <p>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
9590    
9591     </p>
9592 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
9593 iliev 1189
9594     </p>
9595 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORIES SP db_path
9596 iliev 1162
9597     </p>
9598 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORY SP INFO SP db_path
9599 iliev 1162
9600     </p>
9601 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
9602 iliev 1189
9603     </p>
9604 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP db_path
9605 iliev 1162
9606     </p>
9607 schoenebeck 1363 <p>/ DB_INSTRUMENT SP INFO SP db_path
9608 iliev 1162
9609     </p>
9610 iliev 1201 <p>/ DB_INSTRUMENTS_JOB SP INFO SP number
9611    
9612     </p>
9613 schoenebeck 1006 <p>/ VOLUME
9614    
9615     </p>
9616 schoenebeck 708 </blockquote><p>
9617 schoenebeck 575
9618 schoenebeck 708 </p>
9619 schoenebeck 575 <p>set_instruction =
9620     </p>
9621     <blockquote class="text">
9622     <p>AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
9623 schoenebeck 940
9624 schoenebeck 575 </p>
9625     <p>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '=' param_val_list
9626 schoenebeck 940
9627 schoenebeck 575 </p>
9628     <p>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
9629 schoenebeck 940
9630 schoenebeck 575 </p>
9631 schoenebeck 1363 <p>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE
9632    
9633     </p>
9634 schoenebeck 575 <p>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list
9635 schoenebeck 940
9636 schoenebeck 575 </p>
9637     <p>/ CHANNEL SP set_chan_instruction
9638 schoenebeck 940
9639 schoenebeck 575 </p>
9640 schoenebeck 974 <p>/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
9641    
9642     </p>
9643 iliev 1137 <p>/ FX_SEND SP NAME SP sampler_channel SP fx_send_id SP fx_send_name
9644    
9645     </p>
9646 schoenebeck 1002 <p>/ FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id SP audio_channel_index SP audio_channel_index
9647    
9648     </p>
9649 schoenebeck 1028 <p>/ FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP midi_ctrl
9650    
9651     </p>
9652     <p>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
9653    
9654     </p>
9655 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped
9656 iliev 1162
9657     </p>
9658 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped
9659 iliev 1162
9660     </p>
9661 schoenebeck 1363 <p>/ DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped
9662 iliev 1162
9663     </p>
9664 schoenebeck 1363 <p>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
9665 iliev 1162
9666     </p>
9667 schoenebeck 575 <p>/ ECHO SP boolean
9668 schoenebeck 940
9669 schoenebeck 575 </p>
9670 schoenebeck 1006 <p>/ VOLUME SP volume_value
9671    
9672     </p>
9673 schoenebeck 708 </blockquote><p>
9674 schoenebeck 575
9675 schoenebeck 708 </p>
9676 schoenebeck 575 <p>create_instruction =
9677     </p>
9678     <blockquote class="text">
9679     <p>AUDIO_OUTPUT_DEVICE SP string SP key_val_list
9680 schoenebeck 940
9681 schoenebeck 575 </p>
9682     <p>/ AUDIO_OUTPUT_DEVICE SP string
9683 schoenebeck 940
9684 schoenebeck 575 </p>
9685     <p>/ MIDI_INPUT_DEVICE SP string SP key_val_list
9686 schoenebeck 940
9687 schoenebeck 575 </p>
9688     <p>/ MIDI_INPUT_DEVICE SP string
9689 schoenebeck 940
9690 schoenebeck 575 </p>
9691 schoenebeck 1002 <p>/ FX_SEND SP sampler_channel SP midi_ctrl
9692    
9693     </p>
9694     <p>/ FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name
9695    
9696     </p>
9697 schoenebeck 708 </blockquote><p>
9698 schoenebeck 575
9699 schoenebeck 708 </p>
9700 schoenebeck 945 <p>reset_instruction =
9701     </p>
9702     <blockquote class="text">
9703     <p>CHANNEL SP sampler_channel
9704    
9705     </p>
9706     </blockquote><p>
9707    
9708     </p>
9709     <p>clear_instruction =
9710     </p>
9711     <blockquote class="text">
9712 schoenebeck 974 <p>MIDI_INSTRUMENTS SP midi_map
9713 schoenebeck 945
9714     </p>
9715 schoenebeck 974 <p>/ MIDI_INSTRUMENTS SP ALL
9716    
9717     </p>
9718 schoenebeck 945 </blockquote><p>
9719    
9720     </p>
9721 iliev 1189 <p>find_instruction =
9722     </p>
9723     <blockquote class="text">
9724 schoenebeck 1363 <p>DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list
9725 iliev 1189
9726     </p>
9727 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP db_path SP query_val_list
9728 iliev 1189
9729     </p>
9730 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP query_val_list
9731 iliev 1189
9732     </p>
9733 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
9734 iliev 1189
9735     </p>
9736     </blockquote><p>
9737    
9738     </p>
9739 iliev 1162 <p>move_instruction =
9740     </p>
9741     <blockquote class="text">
9742 schoenebeck 1363 <p>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
9743 iliev 1162
9744     </p>
9745 schoenebeck 1363 <p>/ DB_INSTRUMENT SP db_path SP db_path
9746 iliev 1162
9747     </p>
9748     </blockquote><p>
9749    
9750     </p>
9751 iliev 1189 <p>copy_instruction =
9752     </p>
9753     <blockquote class="text">
9754 schoenebeck 1363 <p>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
9755 iliev 1189
9756     </p>
9757 schoenebeck 1363 <p>/ DB_INSTRUMENT SP db_path SP db_path
9758 iliev 1189
9759     </p>
9760     </blockquote><p>
9761    
9762     </p>
9763 schoenebeck 575 <p>destroy_instruction =
9764     </p>
9765     <blockquote class="text">
9766     <p>AUDIO_OUTPUT_DEVICE SP number
9767 schoenebeck 940
9768 schoenebeck 575 </p>
9769     <p>/ MIDI_INPUT_DEVICE SP number
9770 schoenebeck 940
9771 schoenebeck 575 </p>
9772 schoenebeck 1002 <p>/ FX_SEND SP sampler_channel SP fx_send_id
9773    
9774     </p>
9775 schoenebeck 708 </blockquote><p>
9776 schoenebeck 575
9777 schoenebeck 708 </p>
9778 schoenebeck 575 <p>load_instruction =
9779     </p>
9780     <blockquote class="text">
9781     <p>INSTRUMENT SP load_instr_args
9782 schoenebeck 940
9783 schoenebeck 575 </p>
9784     <p>/ ENGINE SP load_engine_args
9785 schoenebeck 940
9786 schoenebeck 575 </p>
9787 schoenebeck 708 </blockquote><p>
9788 schoenebeck 575
9789 schoenebeck 708 </p>
9790 schoenebeck 575 <p>set_chan_instruction =
9791     </p>
9792     <blockquote class="text">
9793     <p>AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
9794 schoenebeck 940
9795 schoenebeck 575 </p>
9796     <p>/ AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index SP audio_channel_index
9797 schoenebeck 940
9798 schoenebeck 575 </p>
9799     <p>/ AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
9800 schoenebeck 940
9801 schoenebeck 575 </p>
9802     <p>/ MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index SP midi_input_channel_index
9803 schoenebeck 940
9804 schoenebeck 575 </p>
9805     <p>/ MIDI_INPUT_DEVICE SP sampler_channel SP device_index
9806 schoenebeck 940
9807 schoenebeck 575 </p>
9808     <p>/ MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
9809 schoenebeck 940
9810 schoenebeck 575 </p>
9811     <p>/ MIDI_INPUT_CHANNEL SP sampler_channel SP midi_input_channel_index
9812 schoenebeck 940
9813 schoenebeck 575 </p>
9814     <p>/ MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
9815 schoenebeck 940
9816 schoenebeck 575 </p>
9817     <p>/ VOLUME SP sampler_channel SP volume_value
9818 schoenebeck 940
9819 schoenebeck 575 </p>
9820 schoenebeck 708 <p>/ MUTE SP sampler_channel SP boolean
9821 schoenebeck 940
9822 schoenebeck 708 </p>
9823     <p>/ SOLO SP sampler_channel SP boolean
9824 schoenebeck 940
9825 schoenebeck 708 </p>
9826 schoenebeck 974 <p>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP midi_map
9827    
9828     </p>
9829     <p>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP NONE
9830    
9831     </p>
9832     <p>/ MIDI_INSTRUMENT_MAP SP sampler_channel SP DEFAULT
9833    
9834     </p>
9835 schoenebeck 708 </blockquote><p>
9836    
9837     </p>
9838 schoenebeck 1251 <p>edit_instruction =
9839     </p>
9840     <blockquote class="text">
9841     <p>INSTRUMENT SP sampler_channel
9842    
9843     </p>
9844     </blockquote><p>
9845    
9846     </p>
9847 schoenebeck 1363 <p>format_instruction =
9848     </p>
9849     <blockquote class="text">
9850     <p>INSTRUMENTS_DB
9851    
9852     </p>
9853     </blockquote><p>
9854    
9855     </p>
9856 schoenebeck 1048 <p>modal_arg =
9857     </p>
9858     <blockquote class="text">
9859     <p>/* epsilon (empty argument) */
9860    
9861     </p>
9862     <p>/ NON_MODAL SP
9863    
9864     </p>
9865     </blockquote><p>
9866    
9867     </p>
9868 schoenebeck 575 <p>key_val_list =
9869     </p>
9870     <blockquote class="text">
9871     <p>string '=' param_val_list
9872 schoenebeck 940
9873 schoenebeck 575 </p>
9874     <p>/ key_val_list SP string '=' param_val_list
9875 schoenebeck 940
9876 schoenebeck 575 </p>
9877 schoenebeck 708 </blockquote><p>
9878 schoenebeck 575
9879 schoenebeck 708 </p>
9880 schoenebeck 575 <p>buffer_size_type =
9881     </p>
9882     <blockquote class="text">
9883     <p>BYTES
9884 schoenebeck 940
9885 schoenebeck 575 </p>
9886     <p>/ PERCENTAGE
9887 schoenebeck 940
9888 schoenebeck 575 </p>
9889 schoenebeck 708 </blockquote><p>
9890 schoenebeck 575
9891 schoenebeck 708 </p>
9892 schoenebeck 575 <p>list_instruction =
9893     </p>
9894     <blockquote class="text">
9895     <p>AUDIO_OUTPUT_DEVICES
9896 schoenebeck 940
9897 schoenebeck 575 </p>
9898     <p>/ MIDI_INPUT_DEVICES
9899 schoenebeck 940
9900 schoenebeck 575 </p>
9901     <p>/ CHANNELS
9902 schoenebeck 940
9903 schoenebeck 575 </p>
9904     <p>/ AVAILABLE_ENGINES
9905 schoenebeck 940
9906 schoenebeck 575 </p>
9907     <p>/ AVAILABLE_MIDI_INPUT_DRIVERS
9908 schoenebeck 940
9909 schoenebeck 575 </p>
9910     <p>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
9911 schoenebeck 940
9912 schoenebeck 575 </p>
9913 schoenebeck 974 <p>/ MIDI_INSTRUMENTS SP midi_map
9914 schoenebeck 945
9915     </p>
9916 schoenebeck 974 <p>/ MIDI_INSTRUMENTS SP ALL
9917    
9918     </p>
9919     <p>/ MIDI_INSTRUMENT_MAPS
9920    
9921     </p>
9922 schoenebeck 1002 <p>/ FX_SENDS SP sampler_channel
9923    
9924     </p>
9925 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
9926 iliev 1189
9927     </p>
9928 schoenebeck 1363 <p>/ DB_INSTRUMENT_DIRECTORIES SP db_path
9929 iliev 1162
9930     </p>
9931 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
9932 iliev 1189
9933     </p>
9934 schoenebeck 1363 <p>/ DB_INSTRUMENTS SP db_path
9935 iliev 1162
9936     </p>
9937 schoenebeck 708 </blockquote><p>
9938 schoenebeck 575
9939 schoenebeck 708 </p>
9940 schoenebeck 575 <p>load_instr_args =
9941     </p>
9942     <blockquote class="text">
9943     <p>filename SP instrument_index SP sampler_channel
9944 schoenebeck 940
9945 schoenebeck 575 </p>
9946     <p>/ NON_MODAL SP filename SP instrument_index SP sampler_channel
9947 schoenebeck 940
9948 schoenebeck 575 </p>
9949 schoenebeck 708 </blockquote><p>
9950 schoenebeck 575
9951 schoenebeck 708 </p>
9952 schoenebeck 575 <p>load_engine_args =
9953     </p>
9954     <blockquote class="text">
9955     <p>engine_name SP sampler_channel
9956 schoenebeck 940
9957 schoenebeck 575 </p>
9958 schoenebeck 708 </blockquote><p>
9959 schoenebeck 575
9960 schoenebeck 708 </p>
9961 schoenebeck 945 <p>instr_load_mode =
9962     </p>
9963     <blockquote class="text">
9964     <p>ON_DEMAND
9965    
9966     </p>
9967     <p>/ ON_DEMAND_HOLD
9968    
9969     </p>
9970     <p>/ PERSISTENT
9971    
9972     </p>
9973     </blockquote><p>
9974    
9975     </p>
9976 schoenebeck 575 <p>device_index =
9977     </p>
9978     <blockquote class="text">
9979     <p>number
9980 schoenebeck 940
9981 schoenebeck 575 </p>
9982 schoenebeck 708 </blockquote><p>
9983 schoenebeck 575
9984 schoenebeck 708 </p>
9985 schoenebeck 575 <p>audio_channel_index =
9986     </p>
9987     <blockquote class="text">
9988     <p>number
9989 schoenebeck 940
9990 schoenebeck 575 </p>
9991 schoenebeck 708 </blockquote><p>
9992 schoenebeck 575
9993 schoenebeck 708 </p>
9994 schoenebeck 575 <p>audio_output_type_name =
9995     </p>
9996     <blockquote class="text">
9997     <p>string
9998 schoenebeck 940
9999 schoenebeck 575 </p>
10000 schoenebeck 708 </blockquote><p>
10001 schoenebeck 575
10002 schoenebeck 708 </p>
10003 schoenebeck 575 <p>midi_input_port_index =
10004     </p>
10005     <blockquote class="text">
10006     <p>number
10007 schoenebeck 940
10008 schoenebeck 575 </p>
10009 schoenebeck 708 </blockquote><p>
10010 schoenebeck 575
10011 schoenebeck 708 </p>
10012 schoenebeck 575 <p>midi_input_channel_index =
10013     </p>
10014     <blockquote class="text">
10015     <p>number
10016 schoenebeck 940
10017 schoenebeck 575 </p>
10018     <p>/ ALL
10019 schoenebeck 940
10020 schoenebeck 575 </p>
10021 schoenebeck 708 </blockquote><p>
10022 schoenebeck 575
10023 schoenebeck 708 </p>
10024 schoenebeck 575 <p>midi_input_type_name =
10025     </p>
10026     <blockquote class="text">
10027     <p>string
10028 schoenebeck 940
10029 schoenebeck 575 </p>
10030 schoenebeck 708 </blockquote><p>
10031 schoenebeck 575
10032 schoenebeck 708 </p>
10033 schoenebeck 974 <p>midi_map =
10034 schoenebeck 945 </p>
10035     <blockquote class="text">
10036     <p>number
10037    
10038     </p>
10039     </blockquote><p>
10040    
10041     </p>
10042 schoenebeck 974 <p>midi_bank =
10043 schoenebeck 945 </p>
10044     <blockquote class="text">
10045     <p>number
10046    
10047     </p>
10048     </blockquote><p>
10049    
10050     </p>
10051     <p>midi_prog =
10052     </p>
10053     <blockquote class="text">
10054     <p>number
10055    
10056     </p>
10057     </blockquote><p>
10058    
10059     </p>
10060 schoenebeck 1002 <p>midi_ctrl =
10061     </p>
10062     <blockquote class="text">
10063     <p>number
10064    
10065     </p>
10066     </blockquote><p>
10067    
10068     </p>
10069 schoenebeck 575 <p>volume_value =
10070     </p>
10071     <blockquote class="text">
10072     <p>dotnum
10073 schoenebeck 940
10074 schoenebeck 575 </p>
10075     <p>/ number
10076 schoenebeck 940
10077 schoenebeck 575 </p>
10078 schoenebeck 708 </blockquote><p>
10079 schoenebeck 575
10080 schoenebeck 708 </p>
10081 schoenebeck 575 <p>sampler_channel =
10082     </p>
10083     <blockquote class="text">
10084     <p>number
10085 schoenebeck 940
10086 schoenebeck 575 </p>
10087 schoenebeck 708 </blockquote><p>
10088 schoenebeck 575
10089 schoenebeck 708 </p>
10090 schoenebeck 575 <p>instrument_index =
10091     </p>
10092     <blockquote class="text">
10093     <p>number
10094 schoenebeck 940
10095 schoenebeck 575 </p>
10096 schoenebeck 708 </blockquote><p>
10097 schoenebeck 575
10098 schoenebeck 708 </p>
10099 schoenebeck 1002 <p>fx_send_id =
10100     </p>
10101     <blockquote class="text">
10102     <p>number
10103    
10104     </p>
10105     </blockquote><p>
10106    
10107     </p>
10108 schoenebeck 575 <p>engine_name =
10109     </p>
10110     <blockquote class="text">
10111     <p>string
10112 schoenebeck 940
10113 schoenebeck 575 </p>
10114 schoenebeck 708 </blockquote><p>
10115 schoenebeck 575
10116 schoenebeck 708 </p>
10117 schoenebeck 1363 <p>filename =
10118 iliev 1162 </p>
10119     <blockquote class="text">
10120 schoenebeck 1363 <p>path
10121 iliev 1162
10122     </p>
10123     </blockquote><p>
10124    
10125     </p>
10126 schoenebeck 1363 <p>db_path =
10127 iliev 1162 </p>
10128     <blockquote class="text">
10129 schoenebeck 1363 <p>path
10130 iliev 1162
10131     </p>
10132     </blockquote><p>
10133    
10134     </p>
10135 schoenebeck 974 <p>map_name =
10136     </p>
10137     <blockquote class="text">
10138     <p>stringval
10139    
10140     </p>
10141     </blockquote><p>
10142    
10143     </p>
10144 schoenebeck 945 <p>entry_name =
10145     </p>
10146     <blockquote class="text">
10147     <p>stringval
10148    
10149     </p>
10150     </blockquote><p>
10151    
10152     </p>
10153 schoenebeck 1002 <p>fx_send_name =
10154     </p>
10155     <blockquote class="text">
10156     <p>stringval
10157    
10158     </p>
10159     </blockquote><p>
10160    
10161     </p>
10162 schoenebeck 575 <p>param_val_list =
10163     </p>
10164     <blockquote class="text">
10165     <p>param_val
10166 schoenebeck 940
10167 schoenebeck 575 </p>
10168     <p>/ param_val_list','param_val
10169 schoenebeck 940
10170 schoenebeck 575 </p>
10171 schoenebeck 708 </blockquote><p>
10172 schoenebeck 575
10173 schoenebeck 708 </p>
10174 schoenebeck 575 <p>param_val =
10175     </p>
10176     <blockquote class="text">
10177     <p>string
10178 schoenebeck 940
10179 schoenebeck 575 </p>
10180 schoenebeck 940 <p>/ stringval
10181    
10182 schoenebeck 575 </p>
10183     <p>/ number
10184 schoenebeck 940
10185 schoenebeck 575 </p>
10186     <p>/ dotnum
10187 schoenebeck 940
10188 schoenebeck 575 </p>
10189 schoenebeck 708 </blockquote><p>
10190 schoenebeck 575
10191 schoenebeck 708 </p>
10192 iliev 1189 <p>query_val_list =
10193     </p>
10194     <blockquote class="text">
10195     <p>string '=' query_val
10196    
10197     </p>
10198     <p>/ query_val_list SP string '=' query_val
10199    
10200     </p>
10201     </blockquote><p>
10202    
10203     </p>
10204     <p>query_val =
10205     </p>
10206     <blockquote class="text">
10207 schoenebeck 1363 <p>textval_escaped
10208 iliev 1189
10209     </p>
10210 schoenebeck 1363 <p>/ stringval_escaped
10211 iliev 1189
10212     </p>
10213     </blockquote><p>
10214    
10215     </p>
10216 iliev 1201 <p>scan_mode =
10217     </p>
10218     <blockquote class="text">
10219     <p>RECURSIVE
10220    
10221     </p>
10222     <p>/ NON_RECURSIVE
10223    
10224     </p>
10225     <p>/ FLAT
10226    
10227     </p>
10228     </blockquote><p>
10229    
10230     </p>
10231 schoenebeck 1251 <a name="character_set"></a><br /><hr />
10232     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10233     <a name="rfc.section.7.1"></a><h3>7.1.&nbsp;
10234     Character Set and Escape Sequences</h3>
10235    
10236     <p>Older versions of this protocol up to and including v1.1 only
10237     supported the standard ASCII character set (ASCII code 0 - 127)
10238     <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
10239     however support the Extended ASCII character set (ASCII code
10240     0 - 255). The same group of younger protocols also support
10241     escape sequences, but only for certain, explicitly declared
10242     parts of the protocol. The supported escape sequences are
10243     defined as follows:
10244     </p><table class="full" align="center" border="0" cellpadding="2" cellspacing="2">
10245     <col align="left"><col align="left">
10246     <tr><th align="left">ASCII Character Sequence</th><th align="left">Translated into (Name)</th></tr>
10247     <tr>
10248     <td align="left">\n</td>
10249     <td align="left">new line</td>
10250     </tr>
10251     <tr>
10252     <td align="left">\r</td>
10253     <td align="left">carriage return</td>
10254     </tr>
10255     <tr>
10256     <td align="left">\f</td>
10257     <td align="left">form feed</td>
10258     </tr>
10259     <tr>
10260     <td align="left">\t</td>
10261     <td align="left">horizontal tab</td>
10262     </tr>
10263     <tr>
10264     <td align="left">\v</td>
10265     <td align="left">vertical tab</td>
10266     </tr>
10267     <tr>
10268     <td align="left">\'</td>
10269     <td align="left">apostrophe</td>
10270     </tr>
10271     <tr>
10272     <td align="left">\"</td>
10273     <td align="left">quotation mark</td>
10274     </tr>
10275     <tr>
10276     <td align="left">\\</td>
10277     <td align="left">backslash</td>
10278     </tr>
10279     <tr>
10280     <td align="left">\OOO</td>
10281     <td align="left">three digit octal ASCII code of the character</td>
10282     </tr>
10283     <tr>
10284     <td align="left">\xHH</td>
10285     <td align="left">two digit hex ASCII code of the character</td>
10286     </tr>
10287     </table>
10288    
10289     <p>Notice: due to the transition of certain parts of the
10290     protocol which now support escape sequences, a slight backward
10291     incompatibility to protocols version v1.1 and younger has been
10292     introduced. The only difference is that in parts of the protocol
10293     where escape characters are now supported, a backslash characters
10294     MUST be escaped as well (that is as double backslash), whereas
10295     in the old versions a single backslash was sufficient.
10296     </p>
10297 senoner 542 <a name="events"></a><br /><hr />
10298 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>
10299     <a name="rfc.section.8"></a><h3>8.&nbsp;
10300     Events</h3>
10301 senoner 542
10302     <p>This chapter will describe all currently defined events supported by LinuxSampler.
10303     </p>
10304 iliev 992 <a name="SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT"></a><br /><hr />
10305 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>
10306     <a name="rfc.section.8.1"></a><h3>8.1.&nbsp;
10307 iliev 992 Number of audio output devices changed</h3>
10308    
10309     <p>Client may want to be notified when the total number of audio output devices on the
10310     back-end changes by issuing the following command:
10311     </p>
10312     <p>
10313     </p>
10314     <blockquote class="text">
10315     <p>SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT
10316     </p>
10317     </blockquote><p>
10318    
10319     </p>
10320     <p>Server will start sending the following notification messages:
10321     </p>
10322     <p>
10323     </p>
10324     <blockquote class="text">
10325     <p>"NOTIFY:AUDIO_OUTPUT_DEVICE_COUNT:&lt;devices&gt;"
10326     </p>
10327     </blockquote><p>
10328    
10329     </p>
10330     <p>where &lt;devices&gt; will be replaced by the new number
10331     of audio output devices.
10332     </p>
10333     <a name="SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO"></a><br /><hr />
10334     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10335     <a name="rfc.section.8.2"></a><h3>8.2.&nbsp;
10336     Audio output device's settings changed</h3>
10337    
10338     <p>Client may want to be notified when changes were made to audio output devices on the
10339     back-end by issuing the following command:
10340     </p>
10341     <p>
10342     </p>
10343     <blockquote class="text">
10344     <p>SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO
10345     </p>
10346     </blockquote><p>
10347    
10348     </p>
10349     <p>Server will start sending the following notification messages:
10350     </p>
10351     <p>
10352     </p>
10353     <blockquote class="text">
10354     <p>"NOTIFY:AUDIO_OUTPUT_DEVICE_INFO:&lt;device-id&gt;"
10355     </p>
10356     </blockquote><p>
10357    
10358     </p>
10359     <p>where &lt;device-id&gt; will be replaced by the numerical ID of the audio output device,
10360     which settings has been changed. The front-end will have to send
10361     the respective command to actually get the audio output device info. Because these messages
10362     will be triggered by LSCP commands issued by other clients rather than real
10363     time events happening on the server, it is believed that an empty notification
10364     message is sufficient here.
10365     </p>
10366     <a name="SUBSCRIBE MIDI_INPUT_DEVICE_COUNT"></a><br /><hr />
10367     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10368     <a name="rfc.section.8.3"></a><h3>8.3.&nbsp;
10369     Number of MIDI input devices changed</h3>
10370    
10371     <p>Client may want to be notified when the total number of MIDI input devices on the
10372     back-end changes by issuing the following command:
10373     </p>
10374     <p>
10375     </p>
10376     <blockquote class="text">
10377     <p>SUBSCRIBE MIDI_INPUT_DEVICE_COUNT
10378     </p>
10379     </blockquote><p>
10380    
10381     </p>
10382     <p>Server will start sending the following notification messages:
10383     </p>
10384     <p>
10385     </p>
10386     <blockquote class="text">
10387     <p>"NOTIFY:MIDI_INPUT_DEVICE_COUNT:&lt;devices&gt;"
10388     </p>
10389     </blockquote><p>
10390    
10391     </p>
10392     <p>where &lt;devices&gt; will be replaced by the new number
10393     of MIDI input devices.
10394     </p>
10395     <a name="SUBSCRIBE MIDI_INPUT_DEVICE_INFO"></a><br /><hr />
10396     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10397     <a name="rfc.section.8.4"></a><h3>8.4.&nbsp;
10398     MIDI input device's settings changed</h3>
10399    
10400     <p>Client may want to be notified when changes were made to MIDI input devices on the
10401     back-end by issuing the following command:
10402     </p>
10403     <p>
10404     </p>
10405     <blockquote class="text">
10406     <p>SUBSCRIBE MIDI_INPUT_DEVICE_INFO
10407     </p>
10408     </blockquote><p>
10409    
10410     </p>
10411     <p>Server will start sending the following notification messages:
10412     </p>
10413     <p>
10414     </p>
10415     <blockquote class="text">
10416     <p>"NOTIFY:MIDI_INPUT_DEVICE_INFO:&lt;device-id&gt;"
10417     </p>
10418     </blockquote><p>
10419    
10420     </p>
10421     <p>where &lt;device-id&gt; will be replaced by the numerical ID of the MIDI input device,
10422     which settings has been changed. The front-end will have to send
10423     the respective command to actually get the MIDI input device info. Because these messages
10424     will be triggered by LSCP commands issued by other clients rather than real
10425     time events happening on the server, it is believed that an empty notification
10426     message is sufficient here.
10427     </p>
10428     <a name="SUBSCRIBE CHANNEL_COUNT"></a><br /><hr />
10429     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10430     <a name="rfc.section.8.5"></a><h3>8.5.&nbsp;
10431 schoenebeck 974 Number of sampler channels changed</h3>
10432 senoner 542
10433     <p>Client may want to be notified when the total number of channels on the
10434     back-end changes by issuing the following command:
10435     </p>
10436 schoenebeck 708 <p>
10437     </p>
10438 senoner 542 <blockquote class="text">
10439 schoenebeck 558 <p>SUBSCRIBE CHANNEL_COUNT
10440 senoner 542 </p>
10441 schoenebeck 708 </blockquote><p>
10442 schoenebeck 940
10443 schoenebeck 708 </p>
10444 senoner 542 <p>Server will start sending the following notification messages:
10445     </p>
10446 schoenebeck 708 <p>
10447     </p>
10448 senoner 542 <blockquote class="text">
10449 schoenebeck 558 <p>"NOTIFY:CHANNEL_COUNT:&lt;channels&gt;"
10450 senoner 542 </p>
10451 schoenebeck 708 </blockquote><p>
10452 schoenebeck 940
10453 schoenebeck 708 </p>
10454 senoner 542 <p>where &lt;channels&gt; will be replaced by the new number
10455     of sampler channels.
10456     </p>
10457 schoenebeck 940 <a name="SUBSCRIBE VOICE_COUNT"></a><br /><hr />
10458 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>
10459 iliev 992 <a name="rfc.section.8.6"></a><h3>8.6.&nbsp;
10460 schoenebeck 974 Number of active voices changed</h3>
10461 senoner 542
10462     <p>Client may want to be notified when the number of voices on the
10463     back-end changes by issuing the following command:
10464     </p>
10465 schoenebeck 708 <p>
10466     </p>
10467 senoner 542 <blockquote class="text">
10468     <p>SUBSCRIBE VOICE_COUNT
10469     </p>
10470 schoenebeck 708 </blockquote><p>
10471 schoenebeck 940
10472 schoenebeck 708 </p>
10473 senoner 542 <p>Server will start sending the following notification messages:
10474     </p>
10475 schoenebeck 708 <p>
10476     </p>
10477 senoner 542 <blockquote class="text">
10478 iliev 1110 <p>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;"
10479 senoner 542 </p>
10480 schoenebeck 708 </blockquote><p>
10481 schoenebeck 940
10482 schoenebeck 708 </p>
10483 senoner 542 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
10484     voice count change occurred and &lt;voices&gt; by the new number of
10485     active voices on that channel.
10486     </p>
10487 schoenebeck 940 <a name="SUBSCRIBE STREAM_COUNT"></a><br /><hr />
10488 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>
10489 iliev 992 <a name="rfc.section.8.7"></a><h3>8.7.&nbsp;
10490 schoenebeck 974 Number of active disk streams changed</h3>
10491 senoner 542
10492     <p>Client may want to be notified when the number of streams on the back-end
10493     changes by issuing the following command: SUBSCRIBE STREAM_COUNT
10494     </p>
10495 schoenebeck 708 <p>
10496     </p>
10497 senoner 542 <blockquote class="text">
10498     <p>SUBSCRIBE STREAM_COUNT
10499     </p>
10500 schoenebeck 708 </blockquote><p>
10501 schoenebeck 940
10502 schoenebeck 708 </p>
10503 senoner 542 <p>Server will start sending the following notification messages:
10504     </p>
10505 schoenebeck 708 <p>
10506     </p>
10507 senoner 542 <blockquote class="text">
10508     <p>"NOTIFY:STREAM_COUNT:&lt;sampler-channel&gt; &lt;streams&gt;"
10509     </p>
10510 schoenebeck 708 </blockquote><p>
10511 schoenebeck 940
10512 schoenebeck 708 </p>
10513 senoner 542 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
10514     stream count change occurred and &lt;streams&gt; by the new number of
10515     active disk streams on that channel.
10516     </p>
10517 schoenebeck 940 <a name="SUBSCRIBE BUFFER_FILL"></a><br /><hr />
10518 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>
10519 iliev 992 <a name="rfc.section.8.8"></a><h3>8.8.&nbsp;
10520 schoenebeck 974 Disk stream buffer fill state changed</h3>
10521 senoner 542
10522     <p>Client may want to be notified when the buffer fill state of a disk stream
10523     on the back-end changes by issuing the following command:
10524     </p>
10525 schoenebeck 708 <p>
10526     </p>
10527 senoner 542 <blockquote class="text">
10528     <p>SUBSCRIBE BUFFER_FILL
10529     </p>
10530 schoenebeck 708 </blockquote><p>
10531 schoenebeck 940
10532 schoenebeck 708 </p>
10533 senoner 542 <p>Server will start sending the following notification messages:
10534     </p>
10535 schoenebeck 708 <p>
10536     </p>
10537 senoner 542 <blockquote class="text">
10538     <p>"NOTIFY:BUFFER_FILL:&lt;sampler-channel&gt; &lt;fill-data&gt;"
10539     </p>
10540 schoenebeck 708 </blockquote><p>
10541 schoenebeck 940
10542 schoenebeck 708 </p>
10543 senoner 542 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
10544     buffer fill state change occurred on and &lt;fill-data&gt; will be replaced by the
10545 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>
10546     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.
10547 senoner 542 </p>
10548 iliev 992 <a name="SUBSCRIBE CHANNEL_INFO"></a><br /><hr />
10549 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>
10550 iliev 992 <a name="rfc.section.8.9"></a><h3>8.9.&nbsp;
10551 schoenebeck 974 Channel information changed</h3>
10552 senoner 542
10553     <p>Client may want to be notified when changes were made to sampler channels on the
10554 schoenebeck 561 back-end by issuing the following command:
10555 senoner 542 </p>
10556 schoenebeck 708 <p>
10557     </p>
10558 senoner 542 <blockquote class="text">
10559 schoenebeck 558 <p>SUBSCRIBE CHANNEL_INFO
10560 senoner 542 </p>
10561 schoenebeck 708 </blockquote><p>
10562 schoenebeck 940
10563 schoenebeck 708 </p>
10564 senoner 542 <p>Server will start sending the following notification messages:
10565     </p>
10566 schoenebeck 708 <p>
10567     </p>
10568 senoner 542 <blockquote class="text">
10569 schoenebeck 558 <p>"NOTIFY:CHANNEL_INFO:&lt;sampler-channel&gt;"
10570 senoner 542 </p>
10571 schoenebeck 708 </blockquote><p>
10572 schoenebeck 940
10573 schoenebeck 708 </p>
10574 senoner 542 <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
10575     channel info change occurred. The front-end will have to send
10576     the respective command to actually get the channel info. Because these messages
10577     will be triggered by LSCP commands issued by other clients rather than real
10578     time events happening on the server, it is believed that an empty notification
10579     message is sufficient here.
10580     </p>
10581 iliev 1110 <a name="SUBSCRIBE FX_SEND_COUNT"></a><br /><hr />
10582     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10583     <a name="rfc.section.8.10"></a><h3>8.10.&nbsp;
10584     Number of effect sends changed</h3>
10585    
10586 schoenebeck 1251 <p>Client may want to be notified when the number of effect sends on
10587 iliev 1110 a particular sampler channel is changed by issuing the following command:
10588     </p>
10589     <p>
10590     </p>
10591     <blockquote class="text">
10592     <p>SUBSCRIBE FX_SEND_COUNT
10593     </p>
10594     </blockquote><p>
10595    
10596     </p>
10597     <p>Server will start sending the following notification messages:
10598     </p>
10599     <p>
10600     </p>
10601     <blockquote class="text">
10602     <p>"NOTIFY:FX_SEND_COUNT:&lt;channel-id&gt; &lt;fx-sends&gt;"
10603     </p>
10604     </blockquote><p>
10605    
10606     </p>
10607     <p>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
10608     channel, on which the effect sends number is changed and &lt;fx-sends&gt; will
10609     be replaced by the new number of effect sends on that channel.
10610     </p>
10611     <a name="SUBSCRIBE FX_SEND_INFO"></a><br /><hr />
10612     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10613     <a name="rfc.section.8.11"></a><h3>8.11.&nbsp;
10614     Effect send information changed</h3>
10615    
10616     <p>Client may want to be notified when changes were made to effect sends on a
10617     a particular sampler channel by issuing the following command:
10618     </p>
10619     <p>
10620     </p>
10621     <blockquote class="text">
10622     <p>SUBSCRIBE FX_SEND_INFO
10623     </p>
10624     </blockquote><p>
10625    
10626     </p>
10627     <p>Server will start sending the following notification messages:
10628     </p>
10629     <p>
10630     </p>
10631     <blockquote class="text">
10632     <p>"NOTIFY:FX_SEND_INFO:&lt;channel-id&gt; &lt;fx-send-id&gt;"
10633     </p>
10634     </blockquote><p>
10635    
10636     </p>
10637     <p>where &lt;channel-id&gt; will be replaced by the numerical ID of the sampler
10638     channel, on which an effect send entity is changed and &lt;fx-send-id&gt; will
10639     be replaced by the numerical ID of the changed effect send.
10640     </p>
10641 schoenebeck 940 <a name="SUBSCRIBE TOTAL_VOICE_COUNT"></a><br /><hr />
10642 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>
10643 iliev 1110 <a name="rfc.section.8.12"></a><h3>8.12.&nbsp;
10644 schoenebeck 974 Total number of active voices changed</h3>
10645 senoner 542
10646 schoenebeck 940 <p>Client may want to be notified when the total number of voices on the
10647     back-end changes by issuing the following command:
10648     </p>
10649     <p>
10650     </p>
10651     <blockquote class="text">
10652     <p>SUBSCRIBE TOTAL_VOICE_COUNT
10653     </p>
10654     </blockquote><p>
10655    
10656     </p>
10657     <p>Server will start sending the following notification messages:
10658     </p>
10659     <p>
10660     </p>
10661     <blockquote class="text">
10662 iliev 1110 <p>"NOTIFY:TOTAL_VOICE_COUNT:&lt;voices&gt;"
10663 schoenebeck 940 </p>
10664     </blockquote><p>
10665    
10666     </p>
10667     <p>where &lt;voices&gt; will be replaced by the new number of
10668     all currently active voices.
10669     </p>
10670 iliev 992 <a name="SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT"></a><br /><hr />
10671     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10672 iliev 1110 <a name="rfc.section.8.13"></a><h3>8.13.&nbsp;
10673 iliev 992 Number of MIDI instrument maps changed</h3>
10674    
10675     <p>Client may want to be notified when the number of MIDI instrument maps on the
10676     back-end changes by issuing the following command:
10677     </p>
10678     <p>
10679     </p>
10680     <blockquote class="text">
10681     <p>SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT
10682     </p>
10683     </blockquote><p>
10684    
10685     </p>
10686     <p>Server will start sending the following notification messages:
10687     </p>
10688     <p>
10689     </p>
10690     <blockquote class="text">
10691     <p>"NOTIFY:MIDI_INSTRUMENT_MAP_COUNT:&lt;maps&gt;"
10692     </p>
10693     </blockquote><p>
10694    
10695     </p>
10696     <p>where &lt;maps&gt; will be replaced by the new number
10697     of MIDI instrument maps.
10698     </p>
10699     <a name="SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO"></a><br /><hr />
10700     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10701 iliev 1110 <a name="rfc.section.8.14"></a><h3>8.14.&nbsp;
10702 iliev 992 MIDI instrument map information changed</h3>
10703    
10704     <p>Client may want to be notified when changes were made to MIDI instrument maps on the
10705     back-end by issuing the following command:
10706     </p>
10707     <p>
10708     </p>
10709     <blockquote class="text">
10710     <p>SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO
10711     </p>
10712     </blockquote><p>
10713    
10714     </p>
10715     <p>Server will start sending the following notification messages:
10716     </p>
10717     <p>
10718     </p>
10719     <blockquote class="text">
10720     <p>"NOTIFY:MIDI_INSTRUMENT_MAP_INFO:&lt;map-id&gt;"
10721     </p>
10722     </blockquote><p>
10723    
10724     </p>
10725     <p>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
10726     for which information changes occurred. The front-end will have to send
10727     the respective command to actually get the MIDI instrument map info. Because these messages
10728     will be triggered by LSCP commands issued by other clients rather than real
10729     time events happening on the server, it is believed that an empty notification
10730     message is sufficient here.
10731     </p>
10732     <a name="SUBSCRIBE MIDI_INSTRUMENT_COUNT"></a><br /><hr />
10733     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10734 iliev 1110 <a name="rfc.section.8.15"></a><h3>8.15.&nbsp;
10735 iliev 992 Number of MIDI instruments changed</h3>
10736    
10737     <p>Client may want to be notified when the number of MIDI instrument maps on the
10738     back-end changes by issuing the following command:
10739     </p>
10740     <p>
10741     </p>
10742     <blockquote class="text">
10743     <p>SUBSCRIBE MIDI_INSTRUMENT_COUNT
10744     </p>
10745     </blockquote><p>
10746    
10747     </p>
10748     <p>Server will start sending the following notification messages:
10749     </p>
10750     <p>
10751     </p>
10752     <blockquote class="text">
10753     <p>"NOTIFY:MIDI_INSTRUMENT_COUNT:&lt;map-id&gt; &lt;instruments&gt;"
10754     </p>
10755     </blockquote><p>
10756    
10757     </p>
10758     <p>where &lt;map-id&gt; is the numerical ID of the MIDI instrument map, in which
10759     the nuber of instruments has changed and &lt;instruments&gt; will be replaced by
10760     the new number of MIDI instruments in the specified map.
10761     </p>
10762     <a name="SUBSCRIBE MIDI_INSTRUMENT_INFO"></a><br /><hr />
10763     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10764 iliev 1110 <a name="rfc.section.8.16"></a><h3>8.16.&nbsp;
10765 iliev 992 MIDI instrument information changed</h3>
10766    
10767     <p>Client may want to be notified when changes were made to MIDI instruments on the
10768     back-end by issuing the following command:
10769     </p>
10770     <p>
10771     </p>
10772     <blockquote class="text">
10773     <p>SUBSCRIBE MIDI_INSTRUMENT_INFO
10774     </p>
10775     </blockquote><p>
10776    
10777     </p>
10778     <p>Server will start sending the following notification messages:
10779     </p>
10780     <p>
10781     </p>
10782     <blockquote class="text">
10783     <p>"NOTIFY:MIDI_INSTRUMENT_INFO:&lt;map-id&gt; &lt;bank&gt; &lt;program&gt;"
10784     </p>
10785     </blockquote><p>
10786    
10787     </p>
10788     <p>where &lt;map-id&gt; will be replaced by the numerical ID of the MIDI instrument map,
10789     in which a MIDI instrument is changed. &lt;bank&gt; and &lt;program&gt; specifies
10790     the location of the changed MIDI instrument in the map. The front-end will have to send
10791     the respective command to actually get the MIDI instrument info. Because these messages
10792     will be triggered by LSCP commands issued by other clients rather than real
10793     time events happening on the server, it is believed that an empty notification
10794     message is sufficient here.
10795     </p>
10796 iliev 1110 <a name="SUBSCRIBE GLOBAL_INFO"></a><br /><hr />
10797     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10798     <a name="rfc.section.8.17"></a><h3>8.17.&nbsp;
10799     Global settings changed</h3>
10800    
10801     <p>Client may want to be notified when changes to the global settings
10802     of the sampler were made by issuing the following command:
10803     </p>
10804     <p>
10805     </p>
10806     <blockquote class="text">
10807     <p>SUBSCRIBE GLOBAL_INFO
10808     </p>
10809     </blockquote><p>
10810    
10811     </p>
10812     <p>Server will start sending the following types of notification messages:
10813     </p>
10814     <p>
10815     </p>
10816     <blockquote class="text">
10817     <p>"NOTIFY:GLOBAL_INFO:VOLUME &lt;volume&gt;" - Notifies that the
10818     golbal volume of the sampler is changed, where &lt;volume&gt; will be
10819     replaced by the optional dotted floating point value, reflecting the
10820     new global volume parameter.
10821     </p>
10822     </blockquote><p>
10823    
10824     </p>
10825 iliev 1162 <a name="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT"></a><br /><hr />
10826     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10827     <a name="rfc.section.8.18"></a><h3>8.18.&nbsp;
10828     Number of database instrument directories changed</h3>
10829    
10830     <p>Client may want to be notified when the number of instrument
10831     directories in a particular directory in the instruments database
10832     is changed by issuing the following command:
10833     </p>
10834     <p>
10835     </p>
10836     <blockquote class="text">
10837     <p>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT
10838     </p>
10839     </blockquote><p>
10840    
10841     </p>
10842     <p>Server will start sending the following notification messages:
10843     </p>
10844     <p>
10845     </p>
10846     <blockquote class="text">
10847     <p>"NOTIFY:DB_INSTRUMENT_DIRECTORY_COUNT:&lt;dir-path&gt;"
10848     </p>
10849     </blockquote><p>
10850    
10851     </p>
10852     <p>where &lt;dir-path&gt; will be replaced by the absolute path
10853     name of the directory in the instruments database,
10854     in which the number of directories is changed.
10855     </p>
10856     <p>Note that when a non-empty directory is removed, this event
10857     is not sent for the subdirectories in that directory.
10858     </p>
10859     <a name="SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO"></a><br /><hr />
10860     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10861     <a name="rfc.section.8.19"></a><h3>8.19.&nbsp;
10862     Database instrument directory information changed</h3>
10863    
10864     <p>Client may want to be notified when changes were made to directories
10865     in the instruments database by issuing the following command:
10866     </p>
10867     <p>
10868     </p>
10869     <blockquote class="text">
10870     <p>SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO
10871     </p>
10872     </blockquote><p>
10873    
10874     </p>
10875     <p>Server will start sending the following notification messages:
10876     </p>
10877     <p>
10878     </p>
10879     <blockquote class="text">
10880     <p>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:&lt;dir-path&gt;"
10881     </p>
10882     </blockquote><p>
10883    
10884     </p>
10885     <p>where &lt;dir-path&gt; will be replaced by the absolute path name
10886     of the directory, for which information changes occurred. The front-end will have to send
10887     the respective command to actually get the updated directory info. Because these messages
10888     will be triggered by LSCP commands issued by other clients rather than real
10889     time events happening on the server, it is believed that an empty notification
10890     message is sufficient here.
10891     </p>
10892     <p>
10893     </p>
10894     <blockquote class="text">
10895     <p>"NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:NAME &lt;old-dir-path&gt; &lt;new-name&gt;"
10896     </p>
10897     </blockquote><p>
10898    
10899     </p>
10900     <p>where &lt;old-dir-path&gt; is the old absolute path name of the directory
10901     (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
10902     the new name of the directory, encapsulated into apostrophes.
10903     </p>
10904     <a name="SUBSCRIBE DB_INSTRUMENT_COUNT"></a><br /><hr />
10905     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10906     <a name="rfc.section.8.20"></a><h3>8.20.&nbsp;
10907     Number of database instruments changed</h3>
10908    
10909     <p>Client may want to be notified when the number of instruments
10910     in a particular directory in the instruments database
10911     is changed by issuing the following command:
10912     </p>
10913     <p>
10914     </p>
10915     <blockquote class="text">
10916     <p>SUBSCRIBE DB_INSTRUMENT_COUNT
10917     </p>
10918     </blockquote><p>
10919    
10920     </p>
10921     <p>Server will start sending the following notification messages:
10922     </p>
10923     <p>
10924     </p>
10925     <blockquote class="text">
10926     <p>"NOTIFY:DB_INSTRUMENT_COUNT:&lt;dir-path&gt;"
10927     </p>
10928     </blockquote><p>
10929    
10930     </p>
10931     <p>where &lt;dir-path&gt; will be replaced by the absolute path
10932     name of the directory in the instruments database,
10933     in which the number of instruments is changed.
10934     </p>
10935     <p>Note that when a non-empty directory is removed, this event
10936     is not sent for the instruments in that directory.
10937     </p>
10938     <a name="SUBSCRIBE DB_INSTRUMENT_INFO"></a><br /><hr />
10939     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10940     <a name="rfc.section.8.21"></a><h3>8.21.&nbsp;
10941     Database instrument information changed</h3>
10942    
10943     <p>Client may want to be notified when changes were made to instruments
10944     in the instruments database by issuing the following command:
10945     </p>
10946     <p>
10947     </p>
10948     <blockquote class="text">
10949     <p>SUBSCRIBE DB_INSTRUMENT_INFO
10950     </p>
10951     </blockquote><p>
10952    
10953     </p>
10954     <p>Server will start sending the following notification messages:
10955     </p>
10956     <p>
10957     </p>
10958     <blockquote class="text">
10959     <p>"NOTIFY:DB_INSTRUMENT_INFO:&lt;instr-path&gt;"
10960     </p>
10961     </blockquote><p>
10962    
10963     </p>
10964     <p>where &lt;instr-path&gt; will be replaced by the absolute path name
10965     of the instrument, which settings are changed. The front-end will have to send
10966     the respective command to actually get the updated directory info. Because these messages
10967     will be triggered by LSCP commands issued by other clients rather than real
10968     time events happening on the server, it is believed that an empty notification
10969     message is sufficient here.
10970     </p>
10971     <p>
10972     </p>
10973     <blockquote class="text">
10974     <p>"NOTIFY:DB_INSTRUMENT_INFO:NAME &lt;old-instr-path&gt; &lt;new-name&gt;"
10975     </p>
10976     </blockquote><p>
10977    
10978     </p>
10979     <p>where &lt;old-instr-path&gt; is the old absolute path name of the instrument
10980     (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
10981     the new name of the instrument, encapsulated into apostrophes.
10982     </p>
10983 iliev 1201 <a name="SUBSCRIBE DB_INSTRUMENTS_JOB_INFO"></a><br /><hr />
10984     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
10985     <a name="rfc.section.8.22"></a><h3>8.22.&nbsp;
10986     Database job status information changed</h3>
10987    
10988     <p>Client may want to be notified when the status of particular database
10989     instruments job is changed by issuing the following command:
10990     </p>
10991     <p>
10992     </p>
10993     <blockquote class="text">
10994     <p>SUBSCRIBE DB_INSTRUMENTS_JOB_INFO
10995     </p>
10996     </blockquote><p>
10997    
10998     </p>
10999     <p>Server will start sending the following notification messages:
11000     </p>
11001     <p>
11002     </p>
11003     <blockquote class="text">
11004     <p>"NOTIFY:DB_INSTRUMENTS_JOB_INFO:&lt;job-id&gt;"
11005     </p>
11006     </blockquote><p>
11007    
11008     </p>
11009     <p>where &lt;job-id&gt; will be replaced by the numerical ID of the job,
11010     which status is changed. The front-end will have to send the respective
11011     command to actually get the status info. Because these messages
11012     will be triggered by LSCP commands issued by other clients rather than real
11013     time events happening on the server, it is believed that an empty notification
11014     message is sufficient here.
11015     </p>
11016 schoenebeck 940 <a name="SUBSCRIBE MISCELLANEOUS"></a><br /><hr />
11017 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>
11018 iliev 1201 <a name="rfc.section.8.23"></a><h3>8.23.&nbsp;
11019 schoenebeck 974 Miscellaneous and debugging events</h3>
11020 schoenebeck 940
11021 senoner 542 <p>Client may want to be notified of miscellaneous and debugging events occurring at
11022     the server by issuing the following command:
11023     </p>
11024 schoenebeck 708 <p>
11025     </p>
11026 senoner 542 <blockquote class="text">
11027     <p>SUBSCRIBE MISCELLANEOUS
11028     </p>
11029 schoenebeck 708 </blockquote><p>
11030 schoenebeck 940
11031 schoenebeck 708 </p>
11032 senoner 542 <p>Server will start sending the following notification messages:
11033     </p>
11034 schoenebeck 708 <p>
11035     </p>
11036 senoner 542 <blockquote class="text">
11037     <p>"NOTIFY:MISCELLANEOUS:&lt;string&gt;"
11038     </p>
11039 schoenebeck 708 </blockquote><p>
11040 schoenebeck 940
11041 schoenebeck 708 </p>
11042 senoner 542 <p>where &lt;string&gt; will be replaced by whatever data server
11043     wants to send to the client. Client MAY display this data to the
11044     user AS IS to facilitate debugging.
11045     </p>
11046 schoenebeck 974 <a name="anchor14"></a><br /><hr />
11047     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11048     <a name="rfc.section.9"></a><h3>9.&nbsp;
11049     Security Considerations</h3>
11050 senoner 542
11051     <p>As there is so far no method of authentication and authorization
11052     defined and so not required for a client applications to succeed to
11053     connect, running LinuxSampler might be a security risk for the host
11054     system the LinuxSampler instance is running on.
11055     </p>
11056 schoenebeck 974 <a name="anchor15"></a><br /><hr />
11057     <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
11058     <a name="rfc.section.10"></a><h3>10.&nbsp;
11059     Acknowledgments</h3>
11060 senoner 542
11061     <p>This document has benefited greatly from the comments of the
11062     following people, discussed on the LinuxSampler developer's mailing
11063     list:
11064     </p>
11065 schoenebeck 708 <p>
11066     </p>
11067 senoner 542 <blockquote class="text">
11068     <p>Rui Nuno Capela
11069     </p>
11070     <p>Vladimir Senkov
11071     </p>
11072     <p>Mark Knecht
11073     </p>
11074 schoenebeck 561 <p>Grigor Iliev
11075     </p>
11076 schoenebeck 708 </blockquote><p>
11077 schoenebeck 940
11078 schoenebeck 708 </p>
11079 senoner 542 <a name="rfc.references1"></a><br /><hr />
11080 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>
11081 schoenebeck 708 <h3>11.&nbsp;References</h3>
11082 senoner 542 <table width="99%" border="0">
11083 schoenebeck 1251 <tr><td class="author-text" valign="top"><a name="RFC20">[RFC20]</a></td>
11084     <td class="author-text">UCLA, &ldquo;<a href="ftp://ftp.isi.edu/in-notes/rfc20.txt">ASCII format for Network Interchange</a>,&rdquo; RFC&nbsp;20, 1969.</td></tr>
11085 senoner 542 <tr><td class="author-text" valign="top"><a name="RFC2119">[RFC2119]</a></td>
11086 schoenebeck 708 <td class="author-text">Bradner, S., &ldquo;<a href="ftp://ftp.isi.edu/in-notes/rfc2119.txt">Key words for use in RFCs to Indicate Requirement Levels</a>,&rdquo; RFC&nbsp;2119, 1997.</td></tr>
11087 schoenebeck 575 <tr><td class="author-text" valign="top"><a name="RFC2234">[RFC2234]</a></td>
11088 schoenebeck 708 <td class="author-text">Crocker, D. and P. Overell, &ldquo;<a href="ftp://ftp.isi.edu/in-notes/rfc2234.txt">Augmented BNF for Syntax Specifications</a>,&rdquo; RFC&nbsp;2234, 1997.</td></tr>
11089 schoenebeck 575 <tr><td class="author-text" valign="top"><a name="RFC793">[RFC793]</a></td>
11090 schoenebeck 708 <td class="author-text">Defense Advanced Research Projects Agency, &ldquo;<a href="ftp://ftp.isi.edu/in-notes/rfc793.txt">TRANSMISSION CONTROL PROTOCOL</a>,&rdquo; RFC&nbsp;793, 1981.</td></tr>
11091 senoner 542 </table>
11092    
11093     <a name="rfc.authors"></a><br /><hr />
11094 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>
11095 senoner 542 <h3>Author's Address</h3>
11096     <table width="99%" border="0" cellpadding="0" cellspacing="0">
11097     <tr><td class="author-text">&nbsp;</td>
11098     <td class="author-text">C.
11099     Schoenebeck</td></tr>
11100     <tr><td class="author-text">&nbsp;</td>
11101     <td class="author-text">Interessengemeinschaft Software Engineering e. V.</td></tr>
11102     <tr><td class="author-text">&nbsp;</td>
11103     <td class="author-text">Max-Planck-Str. 39</td></tr>
11104     <tr><td class="author-text">&nbsp;</td>
11105     <td class="author-text">74081 Heilbronn</td></tr>
11106     <tr><td class="author-text">&nbsp;</td>
11107     <td class="author-text">Germany</td></tr>
11108 schoenebeck 708 <tr><td class="author" align="right">Email:&nbsp;</td>
11109 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>
11110     </table>
11111     <a name="rfc.copyright"></a><br /><hr />
11112 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>
11113     <h3>Full Copyright Statement</h3>
11114 senoner 542 <p class='copyright'>
11115 iliev 1110 Copyright &copy; The IETF Trust (2007).</p>
11116 senoner 542 <p class='copyright'>
11117 schoenebeck 974 This document is subject to the rights,
11118     licenses and restrictions contained in BCP&nbsp;78,
11119     and except as set forth therein,
11120     the authors retain all their rights.</p>
11121 senoner 542 <p class='copyright'>
11122 schoenebeck 974 This document and the information contained herein are provided
11123     on an &ldquo;AS IS&rdquo; basis and THE CONTRIBUTOR,
11124 iliev 1110 THE ORGANIZATION HE/SHE REPRESENTS
11125     OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST
11126     AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES,
11127     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT
11128     THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY
11129     IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
11130     PURPOSE.</p>
11131 schoenebeck 974 <h3>Intellectual Property</h3>
11132 senoner 542 <p class='copyright'>
11133 schoenebeck 974 The IETF takes no position regarding the validity or scope of any
11134     Intellectual Property Rights or other rights that might be claimed
11135     to pertain to the implementation or use of the technology
11136     described in this document or the extent to which any license
11137     under such rights might or might not be available; nor does it
11138     represent that it has made any independent effort to identify any
11139     such rights.
11140     Information on the procedures with respect to
11141     rights in RFC documents can be found in BCP&nbsp;78 and BCP&nbsp;79.</p>
11142 senoner 542 <p class='copyright'>
11143 schoenebeck 974 Copies of IPR disclosures made to the IETF Secretariat and any
11144     assurances of licenses to be made available,
11145     or the result of an attempt made to obtain a general license or
11146     permission for the use of such proprietary rights by implementers or
11147     users of this specification can be obtained from the IETF on-line IPR
11148     repository at <a href='http://www.ietf.org/ipr'>http://www.ietf.org/ipr</a>.</p>
11149 senoner 542 <p class='copyright'>
11150 schoenebeck 974 The IETF invites any interested party to bring to its attention
11151     any copyrights,
11152     patents or patent applications,
11153     or other
11154     proprietary rights that may cover technology that may be required
11155     to implement this standard.
11156     Please address the information to the IETF at <a href='mailto:ietf-ipr@ietf.org'>ietf-ipr@ietf.org</a>.</p>
11157 senoner 542 <h3>Acknowledgment</h3>
11158     <p class='copyright'>
11159 schoenebeck 974 Funding for the RFC Editor function is provided by
11160     the IETF Administrative Support Activity (IASA).</p>
11161 senoner 542 </body></html>
11162 schoenebeck 1363

  ViewVC Help
Powered by ViewVC