/[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 575 - (hide annotations) (download) (as text)
Tue May 24 03:26:22 2005 UTC (18 years, 10 months ago) by schoenebeck
File MIME type: text/html
File size: 173632 byte(s)
- LSCP syntax (BNF) is now auto generated
- tagged LSCP specification as version 1.0
- minor cleanup

1 senoner 542 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2     <html lang="en"><head><title>LinuxSampler Control Protocol</title>
3     <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
4     <meta name="description" content="LinuxSampler Control Protocol">
5     <meta name="keywords" content="LSCP">
6     <meta name="generator" content="xml2rfc v1.25 (http://xml.resource.org/)">
7     <style type='text/css'>
8     <!--
9     body {
10     font-family: verdana, charcoal, helvetica, arial, sans-serif;
11     margin: 2em;
12     font-size: small ; color: #000000 ; background-color: #ffffff ; }
13     .title { color: #990000; font-size: x-large ;
14     font-weight: bold; text-align: right;
15     font-family: helvetica, monaco, "MS Sans Serif", arial, sans-serif;
16     background-color: transparent; }
17     .filename { color: #666666; font-size: 18px; line-height: 28px;
18     font-weight: bold; text-align: right;
19     font-family: helvetica, arial, sans-serif;
20     background-color: transparent; }
21     td.rfcbug { background-color: #000000 ; width: 30px ; height: 30px ;
22     text-align: justify; vertical-align: middle ; padding-top: 2px ; }
23     td.rfcbug span.RFC { color: #666666; font-weight: bold; text-decoration: none;
24     background-color: #000000 ;
25     font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
26     font-size: x-small ; }
27     td.rfcbug span.hotText { color: #ffffff; font-weight: normal; text-decoration: none;
28     text-align: center ;
29     font-family: charcoal, monaco, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
30     font-size: x-small ; background-color: #000000; }
31     /* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */
32     div#counter{margin-top: 100px}
33    
34     a.info{
35     position:relative; /*this is the key*/
36     z-index:24;
37     text-decoration:none}
38    
39     a.info:hover{z-index:25; background-color:#990000 ; color: #ffffff ;}
40    
41     a.info span{display: none}
42    
43     a.info:hover span{ /*the span will display just on :hover state*/
44     display:block;
45     position:absolute;
46     font-size: smaller ;
47     top:2em; left:2em; width:15em;
48     padding: 2px ;
49     border:1px solid #333333;
50     background-color:#eeeeee; color:#990000;
51     text-align: left ;}
52    
53     A { font-weight: bold; }
54     A:link { color: #990000; background-color: transparent ; }
55     A:visited { color: #333333; background-color: transparent ; }
56     A:active { color: #333333; background-color: transparent ; }
57    
58     p { margin-left: 2em; margin-right: 2em; }
59     p.copyright { font-size: x-small ; }
60     p.toc { font-size: small ; font-weight: bold ; margin-left: 3em ;}
61    
62     span.emph { font-style: italic; }
63     span.strong { font-weight: bold; }
64     span.verb { font-family: "Courier New", Courier, monospace ; }
65    
66     ol.text { margin-left: 2em; margin-right: 2em; }
67     ul.text { margin-left: 2em; margin-right: 2em; }
68     li { margin-left: 3em; }
69    
70     pre { margin-left: 3em; color: #333333; background-color: transparent;
71     font-family: "Courier New", Courier, monospace ; font-size: small ;
72     }
73    
74     h3 { color: #333333; font-size: medium ;
75     font-family: helvetica, arial, sans-serif ;
76     background-color: transparent; }
77     h4 { font-size: small; font-family: helvetica, arial, sans-serif ; }
78    
79     table.bug { width: 30px ; height: 15px ; }
80     td.bug { color: #ffffff ; background-color: #990000 ;
81     text-align: center ; width: 30px ; height: 15px ;
82     }
83     td.bug A.link2 { color: #ffffff ; font-weight: bold;
84     text-decoration: none;
85     font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, sans-serif;
86     font-size: x-small ; background-color: transparent }
87    
88     td.header { color: #ffffff; font-size: x-small ;
89     font-family: arial, helvetica, sans-serif; vertical-align: top;
90     background-color: #666666 ; width: 33% ; }
91     td.author { font-weight: bold; margin-left: 4em; font-size: x-small ; }
92     td.author-text { font-size: x-small; }
93     table.data { vertical-align: top ; border-collapse: collapse ;
94     border-style: solid solid solid solid ;
95     border-color: black black black black ;
96     font-size: small ; text-align: center ; }
97     table.data th { font-weight: bold ;
98     border-style: solid solid solid solid ;
99     border-color: black black black black ; }
100     table.data td {
101     border-style: solid solid solid solid ;
102     border-color: #333333 #333333 #333333 #333333 ; }
103    
104     hr { height: 1px }
105     -->
106     </style>
107     </head>
108     <body>
109     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
110     <table summary="layout" width="66%" border="0" cellpadding="0" cellspacing="0"><tr><td><table summary="layout" width="100%" border="0" cellpadding="2" cellspacing="1">
111     <tr><td class="header">LinuxSampler Developers</td><td class="header">C. Schoenebeck</td></tr>
112     <tr><td class="header">Internet-Draft</td><td class="header">Interessengemeinschaft Software</td></tr>
113 schoenebeck 575 <tr><td class="header">Expires: November 22, 2005</td><td class="header">Engineering e. V.</td></tr>
114     <tr><td class="header">&nbsp;</td><td class="header">May 24, 2005</td></tr>
115 senoner 542 </table></td></tr></table>
116     <div align="right"><span class="title"><br />LinuxSampler Control Protocol</span></div>
117 schoenebeck 575 <div align="right"><span class="title"><br />LSCP 1.0</span></div>
118 senoner 542
119     <h3>Status of this Memo</h3>
120     <p>
121     This document is an Internet-Draft and is
122     in full conformance with all provisions of Section 10 of RFC2026.</p>
123     <p>
124     Internet-Drafts are working documents of the Internet Engineering
125     Task Force (IETF), its areas, and its working groups.
126     Note that other groups may also distribute working documents as
127     Internet-Drafts.</p>
128     <p>
129     Internet-Drafts are draft documents valid for a maximum of six months
130     and may be updated, replaced, or obsoleted by other documents at any time.
131     It is inappropriate to use Internet-Drafts as reference material or to cite
132     them other than as "work in progress."</p>
133     <p>
134     The list of current Internet-Drafts can be accessed at
135     <a href='http://www.ietf.org/ietf/1id-abstracts.txt'>http://www.ietf.org/ietf/1id-abstracts.txt</a>.</p>
136     <p>
137     The list of Internet-Draft Shadow Directories can be accessed at
138     <a href='http://www.ietf.org/shadow.html'>http://www.ietf.org/shadow.html</a>.</p>
139     <p>
140 schoenebeck 575 This Internet-Draft will expire on November 22, 2005.</p>
141 senoner 542
142     <h3>Copyright Notice</h3>
143     <p>
144     Copyright (C) The Internet Society (2005). All Rights Reserved.</p>
145    
146     <h3>Abstract</h3>
147    
148     <p>The LinuxSampler Control Protocol (LSCP) is an
149     application-level protocol primarily intended for local and
150 schoenebeck 575 remote controlling the LinuxSampler backend application, which is a
151     sophisticated server-like console application essentially playing
152     back audio samples and manipulating the samples in real time to
153     certain extent.
154 senoner 542 </p><a name="toc"></a><br /><hr />
155     <h3>Table of Contents</h3>
156     <p class="toc">
157     <a href="#anchor1">1.</a>&nbsp;
158     Requirements notation<br />
159 schoenebeck 575 <a href="#LSCP versioning">2.</a>&nbsp;
160     Versioning of this specification<br />
161     <a href="#anchor2">3.</a>&nbsp;
162 senoner 542 Introduction<br />
163 schoenebeck 575 <a href="#anchor3">4.</a>&nbsp;
164 senoner 542 Focus of this protocol<br />
165 schoenebeck 575 <a href="#anchor4">5.</a>&nbsp;
166 senoner 542 Communication Overview<br />
167 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor5">5.1</a>&nbsp;
168 senoner 542 Request/response communication method<br />
169 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor6">5.1.1</a>&nbsp;
170 senoner 542 Result format<br />
171 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor7">5.2</a>&nbsp;
172 senoner 542 Subscribe/notify communication method<br />
173 schoenebeck 575 <a href="#control_commands">6.</a>&nbsp;
174 senoner 542 Description for control commands<br />
175 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor8">6.1</a>&nbsp;
176 senoner 542 Ignored lines and comments<br />
177 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor9">6.2</a>&nbsp;
178 senoner 542 Configuring audio drivers<br />
179 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_AUDIO_OUTPUT_DRIVERS">6.2.1</a>&nbsp;
180 senoner 542 Getting amount of available audio output drivers<br />
181 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">6.2.2</a>&nbsp;
182 senoner 542 Getting all available audio output drivers<br />
183 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DRIVER INFO">6.2.3</a>&nbsp;
184 senoner 542 Getting information about a specific audio
185     output driver<br />
186 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO">6.2.4</a>&nbsp;
187 senoner 542 Getting information about specific audio
188     output driver parameter<br />
189 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CREATE AUDIO_OUTPUT_DEVICE">6.2.5</a>&nbsp;
190 senoner 542 Creating an audio output device<br />
191 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DESTROY AUDIO_OUTPUT_DEVICE">6.2.6</a>&nbsp;
192 senoner 542 Destroying an audio output device<br />
193 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DEVICES">6.2.7</a>&nbsp;
194 senoner 542 Getting all created audio output device count<br />
195 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AUDIO_OUTPUT_DEVICES">6.2.8</a>&nbsp;
196 senoner 542 Getting all created audio output device list<br />
197 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_DEVICE INFO">6.2.9</a>&nbsp;
198 senoner 542 Getting current settings of an audio output device<br />
199 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET AUDIO_OUTPUT_DEVICE_PARAMETER">6.2.10</a>&nbsp;
200 senoner 542 Changing settings of audio output devices<br />
201 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_CHANNEL INFO">6.2.11</a>&nbsp;
202 senoner 542 Getting information about an audio channel<br />
203 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO">6.2.12</a>&nbsp;
204 senoner 542 Getting information about specific audio channel parameter<br />
205 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET AUDIO_OUTPUT_CHANNEL_PARAMETER">6.2.13</a>&nbsp;
206 senoner 542 Changing settings of audio output channels<br />
207 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor10">6.3</a>&nbsp;
208 senoner 542 Configuring MIDI input drivers<br />
209 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_MIDI_INPUT_DRIVERS">6.3.1</a>&nbsp;
210 senoner 542 Getting amount of available MIDI input drivers<br />
211 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_MIDI_INPUT_DRIVERS">6.3.2</a>&nbsp;
212 senoner 542 Getting all available MIDI input drivers<br />
213 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DRIVER INFO">6.3.3</a>&nbsp;
214 senoner 542 Getting information about a specific MIDI input driver<br />
215 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DRIVER_PARAMETER INFO">6.3.4</a>&nbsp;
216 senoner 542 Getting information about specific MIDI input driver parameter<br />
217 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#CREATE MIDI_INPUT_DEVICE">6.3.5</a>&nbsp;
218 senoner 542 Creating a MIDI input device<br />
219 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DESTROY MIDI_INPUT_DEVICE">6.3.6</a>&nbsp;
220 senoner 542 Destroying a MIDI input device<br />
221 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DEVICES">6.3.7</a>&nbsp;
222 senoner 542 Getting all created MIDI input device count<br />
223 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST MIDI_INPUT_DEVICES">6.3.8</a>&nbsp;
224 senoner 542 Getting all created MIDI input device list<br />
225 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_DEVICE INFO">6.3.9</a>&nbsp;
226 senoner 542 Getting current settings of a MIDI input device<br />
227 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET MIDI_INPUT_DEVICE_PARAMETER">6.3.10</a>&nbsp;
228 senoner 542 Changing settings of MIDI input devices<br />
229 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_PORT INFO">6.3.11</a>&nbsp;
230 senoner 542 Getting information about a MIDI port<br />
231 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET MIDI_INPUT_PORT_PARAMETER INFO">6.3.12</a>&nbsp;
232 senoner 542 Getting information about specific MIDI port parameter<br />
233 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET MIDI_INPUT_PORT_PARAMETER">6.3.13</a>&nbsp;
234 senoner 542 Changing settings of MIDI input ports<br />
235 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor11">6.4</a>&nbsp;
236 senoner 542 Configuring sampler channels<br />
237 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LOAD INSTRUMENT">6.4.1</a>&nbsp;
238 senoner 542 Loading an instrument<br />
239 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LOAD ENGINE">6.4.2</a>&nbsp;
240 senoner 542 Loading a sampler engine<br />
241 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNELS">6.4.3</a>&nbsp;
242 senoner 542 Getting all created sampler channel count<br />
243 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST CHANNELS">6.4.4</a>&nbsp;
244 senoner 542 Getting all created sampler channel list<br />
245 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ADD CHANNEL">6.4.5</a>&nbsp;
246 senoner 542 Adding a new sampler channel<br />
247 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#REMOVE CHANNEL">6.4.6</a>&nbsp;
248 senoner 542 Removing a sampler channel<br />
249 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET AVAILABLE_ENGINES">6.4.7</a>&nbsp;
250 senoner 542 Getting amount of available engines<br />
251 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#LIST AVAILABLE_ENGINES">6.4.8</a>&nbsp;
252 senoner 542 Getting all available engines<br />
253 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET ENGINE INFO">6.4.9</a>&nbsp;
254 senoner 542 Getting information about an engine<br />
255 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL INFO">6.4.10</a>&nbsp;
256 senoner 542 Getting sampler channel information<br />
257 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL VOICE_COUNT">6.4.11</a>&nbsp;
258 senoner 542 Current number of active voices<br />
259 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL STREAM_COUNT">6.4.12</a>&nbsp;
260 senoner 542 Current number of active disk streams<br />
261 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET CHANNEL BUFFER_FILL">6.4.13</a>&nbsp;
262 senoner 542 Current fill state of disk stream buffers<br />
263 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_DEVICE">6.4.14</a>&nbsp;
264 senoner 542 Setting audio output device<br />
265 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_TYP">6.4.15</a>&nbsp;
266 senoner 542 Setting audio output type<br />
267 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL AUDIO_OUTPUT_CHANNEL">6.4.16</a>&nbsp;
268 senoner 542 Setting audio output channel<br />
269 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_DEVICE">6.4.17</a>&nbsp;
270 senoner 542 Setting MIDI input device<br />
271 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_TYPE">6.4.18</a>&nbsp;
272 senoner 542 Setting MIDI input type<br />
273 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_PORT">6.4.19</a>&nbsp;
274 senoner 542 Setting MIDI input port<br />
275 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL MIDI_INPUT_CHANNEL">6.4.20</a>&nbsp;
276 senoner 542 Setting MIDI input channel<br />
277 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET CHANNEL VOLUME">6.4.21</a>&nbsp;
278 senoner 542 Setting channel volume<br />
279 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#RESET CHANNEL">6.4.22</a>&nbsp;
280 senoner 542 Resetting a sampler channel<br />
281 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor12">6.5</a>&nbsp;
282 senoner 542 Controlling connection<br />
283 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE">6.5.1</a>&nbsp;
284 senoner 542 Register front-end for receiving event messages<br />
285 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#UNSUBSCRIBE">6.5.2</a>&nbsp;
286 senoner 542 Unregister front-end for not receiving event messages<br />
287 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SET ECHO">6.5.3</a>&nbsp;
288 senoner 542 Enable or disable echo of commands<br />
289 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#QUIT">6.5.4</a>&nbsp;
290 senoner 542 Close client connection<br />
291 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor13">6.6</a>&nbsp;
292 senoner 542 Global commands<br />
293 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#RESET">6.6.1</a>&nbsp;
294 senoner 542 Reset sampler<br />
295 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET SERVER INFO">6.6.2</a>&nbsp;
296     General sampler informations<br />
297     <a href="#command_syntax">7.</a>&nbsp;
298 senoner 542 Command Syntax<br />
299 schoenebeck 575 <a href="#events">8.</a>&nbsp;
300 senoner 542 Events<br />
301 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE CHANNEL">8.1</a>&nbsp;
302 senoner 542 Number of sampler channels changed<br />
303 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE VOICE_COUNT">8.2</a>&nbsp;
304 senoner 542 Number of active voices changed<br />
305 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE STREAM_COUNT">8.3</a>&nbsp;
306 senoner 542 Number of active disk streams changed<br />
307 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE BUFFER_FILL">8.4</a>&nbsp;
308 senoner 542 Disk stream buffer fill state changed<br />
309 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE INFO">8.5</a>&nbsp;
310 senoner 542 Channel information changed<br />
311 schoenebeck 575 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MISCELLANEOUS">8.6</a>&nbsp;
312 senoner 542 Miscellaneous and debugging events<br />
313 schoenebeck 575 <a href="#anchor14">9.</a>&nbsp;
314 senoner 542 Security Considerations<br />
315 schoenebeck 575 <a href="#anchor15">10.</a>&nbsp;
316 senoner 542 Acknowledgments<br />
317 schoenebeck 575 <a href="#rfc.references1">11.</a>&nbsp;
318 senoner 542 References<br />
319     <a href="#rfc.authors">&#167;</a>&nbsp;
320     Author's Address<br />
321     <a href="#rfc.copyright">&#167;</a>&nbsp;
322     Intellectual Property and Copyright Statements<br />
323     </p>
324     <br clear="all" />
325    
326     <a name="anchor1"></a><br /><hr />
327     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
328     <a name="rfc.section.1"></a><h3>1.&nbsp;Requirements notation</h3>
329    
330     <p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
331     "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
332     and "OPTIONAL" in this document are to be interpreted as
333 schoenebeck 575 described in <a class="info" href="#RFC2119">[RFC2119]<span>Bradner, S., Key words for use in RFCs to Indicate Requirement Levels, 1997.</span></a>.
334 senoner 542 </p>
335     <p>This protocol is always case-sensitive if not explicitly
336     claimed the opposite.
337     </p>
338     <p>In examples, "C:" and "S:" indicate lines sent by the client
339     (front-end) and server (LinuxSampler) respectively. Lines in
340     examples must be interpreted as every line being CRLF
341     terminated (carriage return character followed by line feed
342     character as defined in the ASCII standard), thus the following
343     example:
344     </p>
345     <p></p>
346     <blockquote class="text">
347     <p>C: "some line"
348     </p>
349     <p>&nbsp;&nbsp;&nbsp;"another line"
350     </p>
351     </blockquote>
352    
353     <p>must actually be interpreted as client sending the following
354     message:
355     </p>
356     <p></p>
357     <blockquote class="text">
358     <p>"some line&lt;CR&gt;&lt;LF&gt;another
359     line&lt;CR&gt;&lt;LF&gt;"
360     </p>
361     </blockquote>
362    
363     <p>where &lt;CR&gt; symbolizes the carriage return character and
364     &lt;LF&gt; the line feed character as defined in the ASCII
365     standard.
366     </p>
367     <p>Due to technical reasons, messages can arbitrary be
368     fragmented, means the following example:
369     </p>
370     <p></p>
371     <blockquote class="text">
372     <p>S: "abcd"
373     </p>
374     </blockquote>
375    
376     <p>could also happen to be sent in three messages like in the
377     following sequence scenario:
378     </p>
379     <p></p>
380     <ul class="text">
381     <li>server sending message "a"
382     </li>
383     <li>followed by a delay (pause) with
384     arbitrary duration
385     </li>
386     <li>followed by server sending message
387     "bcd&lt;CR&gt;"
388     </li>
389     <li>again followed by a delay (pause) with arbitrary
390     duration
391     </li>
392     <li>followed by server sending the message
393     "&lt;LF&gt;"
394     </li>
395     </ul>
396    
397     <p>where again &lt;CR&gt; and &lt;LF&gt; symbolize the carriage
398     return and line feed characters respectively.
399     </p>
400 schoenebeck 575 <a name="LSCP versioning"></a><br /><hr />
401     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
402     <a name="rfc.section.2"></a><h3>2.&nbsp;Versioning of this specification</h3>
403    
404     <p>LSCP will certainly be extended and enhanced by-and-by. Each official
405     release of the LSCP specification will be tagged with a unique version
406     tuple. The version tuple consists at least of a major and minor version
407     number like:
408    
409     </p>
410     <p></p>
411     <blockquote class="text">
412     <p>"1.2"
413     </p>
414     </blockquote>
415    
416     <p>
417     In this example the major version number would be "1" and the minor
418     version number would be "2". Note that the version tuple might also
419     have more than two elements. The major version number defines a
420     group of backward compatible versions. That means a frontend is
421     compatible to the connected sampler if and only if the LSCP versions
422     to which each of the two parties complies to, match both of the
423     following rules:
424    
425     </p>
426     <p>Compatibility:
427     </p>
428     <p></p>
429     <ol class="text">
430     <li>The frontend's LSCP major version and the sampler's LSCP
431     major version are exactly equal.
432     </li>
433     <li>The frontend's LSCP minor version is less or equal than
434     the sampler's LSCP minor version.
435     </li>
436     </ol>
437    
438     <p>
439     Compatibility can only be claimed if both rules are true.
440     The frontend can use the
441     <a class="info" href="#GET SERVER INFO">"GET SERVER INFO"<span>General sampler informations</span></a> command to
442     get the version of the LSCP specification the sampler complies with.
443    
444     </p>
445 senoner 542 <a name="anchor2"></a><br /><hr />
446     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
447 schoenebeck 575 <a name="rfc.section.3"></a><h3>3.&nbsp;Introduction</h3>
448 senoner 542
449     <p>LinuxSampler is a so called software sampler application
450     capable to playback audio samples from a computer's Random
451     Access Memory (RAM) as well as directly streaming it from disk.
452     LinuxSampler is designed to be modular. It provides several so
453     called "sampler engines" where each engine is specialized for a
454     certain purpose. LinuxSampler has virtual channels which will be
455     referred in this document as "sampler channels". The channels
456     are in such way virtual as they can be connected to an
457     arbitrary MIDI input method and arbitrary MIDI channel (e.g.
458     sampler channel 17 could be connected to an ALSA sequencer
459     device 64:0 and listening to MIDI channel 1 there). Each sampler
460 schoenebeck 575 channel will be associated with an instance of one of the available
461 senoner 542 sampler engines (e.g. GigEngine, DLSEngine). The audio output of
462     each sampler channel can be routed to an arbitrary audio output
463     method (ALSA / JACK) and an arbitrary audio output channel
464     there.
465     </p>
466     <a name="anchor3"></a><br /><hr />
467     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
468 schoenebeck 575 <a name="rfc.section.4"></a><h3>4.&nbsp;Focus of this protocol</h3>
469 senoner 542
470     <p>Main focus of this protocol is to provide a way to configure
471     a running LinuxSampler instance and to retrieve information
472     about it. The focus of this protocol is not to provide a way to
473     control synthesis parameters or even to trigger or release
474     notes. Or in other words; the focus are those functionalities
475     which are not covered by MIDI or which may at most be handled
476     via MIDI System Exclusive Messages.
477     </p>
478     <a name="anchor4"></a><br /><hr />
479     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
480 schoenebeck 575 <a name="rfc.section.5"></a><h3>5.&nbsp;Communication Overview</h3>
481 senoner 542
482     <p>There are two distinct methods of communication between a
483     running instance of LinuxSampler and one or more control
484     applications, so called "front-ends": a simple request/response
485     communication method used by the clients to give commands to the
486     server as well as to inquire about server's status and a
487     subscribe/notify communication method used by the client to
488     subscribe to and receive notifications of certain events as they
489     happen on the server. The latter needs more effort to be
490     implemented in the front-end application. The two communication
491     methods will be described next.
492     </p>
493 schoenebeck 575 <a name="rfc.section.5.1"></a><h4><a name="anchor5">5.1</a>&nbsp;Request/response communication method</h4>
494 senoner 542
495 schoenebeck 575 <p>This simple communication method is based on
496     <a class="info" href="#RFC793">TCP<span>Defense Advanced Research Projects Agency, TRANSMISSION CONTROL PROTOCOL, 1981.</span></a>[RFC793]. The
497 senoner 542 front-end application establishes a TCP connection to the
498     LinuxSampler instance on a certain host system. Then the
499     front-end application will send certain ASCII based commands
500     as defined in this document (every command line must be CRLF
501     terminated - see "Conventions used in this document" at the
502     beginning of this document) and the LinuxSampler application
503     will response after a certain process time with an
504     appropriate ASCII based answer, also as defined in this
505     document. So this TCP communication is simply based on query
506     and answer paradigm. That way LinuxSampler is only able to
507     answer on queries from front-ends, but not able to
508     automatically send messages to the client if it's not asked
509     to. The fronted should not reconnect to LinuxSampler for
510     every single command, instead it should keep the connection
511     established and simply resend message(s) for subsequent
512     commands. To keep information in the front-end up-to-date
513     the front-end has to periodically send new requests to get
514     the current information from the LinuxSampler instance. This
515     is often referred to as "polling". While polling is simple
516     to implement and may be OK to use in some cases, there may
517     be disadvantages to polling such as network traffic overhead
518     and information being out of date.
519     It is possible for a client or several clients to open more
520     than one connection to the server at the same time. It is
521     also possible to send more than one request to the server
522     at the same time but if those requests are sent over the
523     same connection server MUST execute them sequentially. Upon
524     executing a request server will produce a result set and
525     send it to the client. Each and every request made by the
526     client MUST result in a result set being sent back to the
527     client. No other data other than a result set may be sent by
528     a server to a client. No result set may be sent to a client
529     without the client sending request to the server first. On
530     any particular connection, result sets MUST be sent in their
531     entirety without being interrupted by other result sets. If
532     several requests got queued up at the server they MUST be
533     processed in the order they were received and result sets
534     MUST be sent back in the same order.
535     </p>
536 schoenebeck 575 <a name="rfc.section.5.1.1"></a><h4><a name="anchor6">5.1.1</a>&nbsp;Result format</h4>
537 senoner 542
538     <p>Result set could be one of the following types:
539     </p>
540     <p></p>
541     <ol class="text">
542     <li>Normal
543     </li>
544     <li>Warning
545     </li>
546     <li>Error
547     </li>
548     </ol>
549    
550     <p>Warning and Error result sets MUST be single line and
551     have the following format:
552     </p>
553     <p></p>
554     <ul class="text">
555     <li>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;"
556     </li>
557     <li>"ERR:&lt;error-code&gt;:&lt;error-message&gt;"
558     </li>
559     </ul>
560    
561     <p>Where &lt;warning-code&gt; and &lt;error-code&gt; are
562     numeric unique identifiers of the warning or error and
563     &lt;warning-message&gt; and &lt;error-message&gt; are
564     human readable descriptions of the warning or error
565     respectively.
566     </p>
567     <p>Examples:
568     </p>
569     <p></p>
570     <blockquote class="text">
571     <p>C: "LOAD INSTRUMENT '/home/me/Boesendorfer24bit.gig" 0 0
572     </p>
573     <p>S: "WRN:32:This is a 24 bit patch which is not supported natively yet."
574     </p>
575     </blockquote>
576    
577     <p></p>
578     <blockquote class="text">
579     <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA EAR"
580     </p>
581     <p>S: "ERR:3456:Audio output driver 'ALSA' does not have a parameter 'EAR'."
582     </p>
583     </blockquote>
584    
585     <p></p>
586     <blockquote class="text">
587     <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 123456"
588     </p>
589     <p>S: "ERR:9:There is no audio output device with index 123456."
590     </p>
591     </blockquote>
592    
593     <p>Normal result sets could be:
594     </p>
595     <p></p>
596     <ol class="text">
597     <li>Empty
598     </li>
599     <li>Single line
600     </li>
601     <li>Multi-line
602     </li>
603     </ol>
604    
605     <p> Empty result set is issued when the server only
606     needed to acknowledge the fact that the request was
607     received and it was processed successfully and no
608     additional information is available. This result set has
609     the following format:
610     </p>
611     <p></p>
612     <blockquote class="text">
613     <p>"OK"
614     </p>
615     </blockquote>
616    
617     <p>Example:
618     </p>
619     <p></p>
620     <blockquote class="text">
621     <p>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 CHANNELS=4"
622     </p>
623     <p>S: "OK"
624     </p>
625     </blockquote>
626    
627     <p>Single line result sets are command specific. One
628     example of a single line result set is an empty line.
629     Multi-line result sets are command specific and may
630     include one or more lines of information. They MUST
631     always end with the following line:
632     </p>
633     <p></p>
634     <blockquote class="text">
635     <p>"."
636     </p>
637     </blockquote>
638    
639     <p>Example:
640     </p>
641     <p></p>
642     <blockquote class="text">
643     <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
644     </p>
645     <p>S: "DRIVER: ALSA"
646     </p>
647     <p>&nbsp;&nbsp;&nbsp;"CHANNELS: 2"
648     </p>
649     <p>&nbsp;&nbsp;&nbsp;"SAMPLERATE: 44100"
650     </p>
651     <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
652     </p>
653     <p>&nbsp;&nbsp;&nbsp;"FRAGMENTS: 2"
654     </p>
655     <p>&nbsp;&nbsp;&nbsp;"FRAGMENTSIZE: 128"
656     </p>
657     <p>&nbsp;&nbsp;&nbsp;"CARD: '0,0'"
658     </p>
659     <p>&nbsp;&nbsp;&nbsp;"."
660     </p>
661     </blockquote>
662    
663     <p>In addition to above mentioned formats, warnings and
664     empty result sets MAY be indexed. In this case, they
665     have the following formats respectively:
666     </p>
667     <p></p>
668     <ul class="text">
669     <li>"WRN[&lt;index&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;"
670     </li>
671     <li>"OK[&lt;index&gt;]"
672     </li>
673     </ul>
674    
675     <p>where &lt;index&gt; is command specific and is used
676     to indicate channel number that the result set was
677     related to or other integer value.
678     </p>
679     <p>Each line of the result set MUST end with
680     &lt;CRLF&gt;.
681     </p>
682     <p>Examples:
683     </p>
684     <p></p>
685     <blockquote class="text">
686     <p>C: "ADD CHANNEL"
687     </p>
688     <p>S: "OK[12]"
689     </p>
690     </blockquote>
691    
692     <p></p>
693     <blockquote class="text">
694     <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"
695     </p>
696     <p>S: "WRN[0]:32:Sample rate not supported, using 44100 instead."
697     </p>
698     </blockquote>
699    
700 schoenebeck 575 <a name="rfc.section.5.2"></a><h4><a name="anchor7">5.2</a>&nbsp;Subscribe/notify communication method</h4>
701 senoner 542
702     <p>This more sophisticated communication method is actually
703     only an extension of the simple request/response
704     communication method. The front-end still uses a TCP
705     connection and sends the same commands on the TCP
706     connection. Two extra commands are SUBSCRIBE and UNSUBSCRIBE
707     commands that allow a client to tell the server that it is
708     interested in receiving notifications about certain events
709     as they happen on the server. The SUBSCRIBE command has the
710     following syntax:
711     </p>
712     <p></p>
713     <blockquote class="text">
714     <p>SUBSCRIBE &lt;event-id&gt;
715     </p>
716     </blockquote>
717    
718     <p>where &lt;event-id&gt; will be replaced by the respective
719     event that client wants to subscribe to. Upon receiving such
720     request, server SHOULD respond with OK and start sending
721     EVENT notifications when a given even has occurred to the
722     front-end when an event has occurred. It MAY be possible
723     certain events may be sent before OK response during real
724     time nature of their generation. Event messages have the
725     following format:
726     </p>
727     <p></p>
728     <blockquote class="text">
729     <p>NOTIFY:&lt;event-id&gt;:&lt;custom-event-data&gt;
730     </p>
731     </blockquote>
732    
733     <p>where &lt;event-id&gt; uniquely identifies the event that
734     has occurred and &lt;custom-event-data&gt; is event
735     specific.
736     </p>
737     <p>Several rules must be followed by the server when
738     generating events:
739     </p>
740     <p></p>
741     <ol class="text">
742     <li>Events MUST NOT be sent to any client who has not
743     issued an appropriate SUBSCRIBE command.
744     </li>
745     <li>Events MUST only be sent using the same
746     connection that was used to subscribe to them.
747     </li>
748     <li>When response is being sent to the client, event
749     MUST be inserted in the stream before or after the
750     response, but NOT in the middle. Same is true about
751     the response. It should never be inserted in the
752     middle of the event message as well as any other
753     response.
754     </li>
755     </ol>
756    
757     <p>If the client is not interested in a particular event
758     anymore it MAY issue UNSUBSCRIBE command using the following
759     syntax:
760     </p>
761     <p></p>
762     <blockquote class="text">
763     <p>UNSUBSCRIBE &lt;event-id&gt;
764     </p>
765     </blockquote>
766    
767     <p>where &lt;event-id&gt; will be replace by the respective
768     event that client is no longer interested in receiving. For
769 schoenebeck 575 a list of supported events see <a class="info" href="#events">Section 8<span>Events</span></a>.
770 senoner 542 </p>
771     <p>Example: the fill states of disk stream buffers have
772     changed on sampler channel 4 and the LinuxSampler instance
773     will react by sending the following message to all clients
774     who subscribed to this event:
775     </p>
776     <p></p>
777     <blockquote class="text">
778     <p>NOTIFY:CHANNEL_BUFFER_FILL:4 [35]62%,[33]80%,[37]98%
779     </p>
780     </blockquote>
781    
782     <p>Which means there are currently three active streams on
783     sampler channel 4, where the stream with ID "35" is filled
784     by 62%, stream with ID 33 is filled by 80% and stream with
785     ID 37 is filled by 98%.
786     </p>
787     <p>Clients may choose to open more than one connection to
788     the server and use some connections to receive notifications
789     while using other connections to issue commands to the
790     back-end. This is entirely legal and up to the
791     implementation. This does not change the protocol in any way
792     and no special restrictions exist on the server to allow or
793     disallow this or to track what connections belong to what
794     front-ends. Server will listen on a single port, accept
795     multiple connections and support protocol described in this
796     specification in it's entirety on this single port on each
797     connection that it accepted.
798     </p>
799     <p>Due to the fact that TCP is used for this communication,
800     dead peers will be detected automatically by the OS TCP
801     stack. While it may take a while to detect dead peers if no
802     traffic is being sent from server to client (TCP keep-alive
803     timer is set to 2 hours on many OSes) it will not be an
804     issue here as when notifications are sent by the server,
805     dead client will be detected quickly.
806     </p>
807     <p>When connection is closed for any reason server MUST
808     forget all subscriptions that were made on this connection.
809     If client reconnects it MUST resubscribe to all events that
810     it wants to receive.
811     </p>
812 schoenebeck 575 <a name="control_commands"></a><br /><hr />
813 senoner 542 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
814 schoenebeck 575 <a name="rfc.section.6"></a><h3>6.&nbsp;Description for control commands</h3>
815 senoner 542
816     <p>This chapter will describe the available control commands
817     that can be sent on the TCP connection in detail. Some certain
818     commands (e.g. <a class="info" href="#GET CHANNEL INFO">"GET CHANNEL INFO"<span>Getting sampler channel information</span></a>
819     or <a class="info" href="#GET ENGINE INFO">"GET ENGINE INFO"<span>Getting information about an engine</span></a>) lead to
820     multiple-line responses. In this case LinuxSampler signals the
821     end of the response by a "." (single dot) line.
822     </p>
823 schoenebeck 575 <a name="rfc.section.6.1"></a><h4><a name="anchor8">6.1</a>&nbsp;Ignored lines and comments</h4>
824 senoner 542
825     <p>White lines, that is lines which only contain space and
826     tabulator characters, and lines that start with a "#"
827     character are ignored, thus it's possible for example to
828     group commands and to place comments in a LSCP script
829     file.
830     </p>
831 schoenebeck 575 <a name="rfc.section.6.2"></a><h4><a name="anchor9">6.2</a>&nbsp;Configuring audio drivers</h4>
832 senoner 542
833     <p>Instances of drivers in LinuxSampler are called devices.
834     You can use multiple audio devices simultaneously, e.g. to
835     output the sound of one sampler channel using the ALSA audio
836     output driver, and on another sampler channel you might want
837     to use the JACK audio output driver. For particular audio
838     output systems it's also possible to create several devices
839     of the same audio output driver, e.g. two separate ALSA
840     audio output devices for using two different sound cards at
841     the same time. This chapter describes all commands to
842     configure LinuxSampler's audio output devices and their
843     parameters.
844     </p>
845     <p>Instead of defining commands and parameters for each
846     driver individually, all possible parameters, their meanings
847     and possible values have to be obtained at runtime. This
848     makes the protocol a bit abstract, but has the advantage,
849     that front-ends can be written independently of what drivers
850     are currently implemented and what parameters these drivers
851     are actually offering. This means front-ends can even handle
852     drivers which are implemented somewhere in future without
853     modifying the front-end at all.
854     </p>
855     <p>Note: examples in this chapter showing particular
856     parameters of drivers are not meant as specification of the
857     drivers' parameters. Driver implementations in LinuxSampler
858     might have complete different parameter names and meanings
859     than shown in these examples or might change in future, so
860     these examples are only meant for showing how to retrieve
861     what parameters drivers are offering, how to retrieve their
862     possible values, etc.
863     </p>
864 schoenebeck 575 <a name="rfc.section.6.2.1"></a><h4><a name="GET AVAILABLE_AUDIO_OUTPUT_DRIVERS">6.2.1</a>&nbsp;Getting amount of available audio output drivers</h4>
865 senoner 542
866     <p>Use the following command to get the number of
867     audio output drivers currently available for the
868     LinuxSampler instance:
869     </p>
870     <p></p>
871     <blockquote class="text">
872     <p>GET AVAILABLE_AUDIO_OUTPUT_DRIVERS
873     </p>
874     </blockquote>
875    
876     <p>Possible Answers:
877     </p>
878     <p></p>
879     <blockquote class="text">
880     <p>LinuxSampler will answer by sending the
881     number of audio output drivers.
882     </p>
883     </blockquote>
884    
885     <p>Example:
886     </p>
887     <p></p>
888     <blockquote class="text">
889     <p>C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
890     </p>
891     <p>S: "2"
892     </p>
893     </blockquote>
894    
895 schoenebeck 575 <a name="rfc.section.6.2.2"></a><h4><a name="LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">6.2.2</a>&nbsp;Getting all available audio output drivers</h4>
896 senoner 542
897     <p>Use the following command to list all audio output
898     drivers currently available for the LinuxSampler
899     instance:
900     </p>
901     <p></p>
902     <blockquote class="text">
903     <p>LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS
904     </p>
905     </blockquote>
906    
907     <p>Possible Answers:
908     </p>
909     <p></p>
910     <blockquote class="text">
911     <p>LinuxSampler will answer by sending comma
912     separated character strings, each symbolizing an
913     audio output driver.
914     </p>
915     </blockquote>
916    
917     <p>Example:
918     </p>
919     <p></p>
920     <blockquote class="text">
921     <p>C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"
922     </p>
923     <p>S: "ALSA,JACK"
924     </p>
925     </blockquote>
926    
927 schoenebeck 575 <a name="rfc.section.6.2.3"></a><h4><a name="GET AUDIO_OUTPUT_DRIVER INFO">6.2.3</a>&nbsp;Getting information about a specific audio
928 senoner 542 output driver</h4>
929    
930     <p>Use the following command to get detailed information
931     about a specific audio output driver:
932     </p>
933     <p></p>
934     <blockquote class="text">
935     <p>GET AUDIO_OUTPUT_DRIVER INFO
936     &lt;audio-output-driver&gt;
937     </p>
938     </blockquote>
939    
940     <p>Where &lt;audio-output-driver&gt; is the name of the
941     audio output driver, returned by the
942     <a class="info" href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"<span>Getting all available audio output drivers</span></a> command.
943     </p>
944     <p>Possible Answers:
945     </p>
946     <p></p>
947     <blockquote class="text">
948     <p>LinuxSampler will answer by sending a
949     &lt;CRLF&gt; separated list. Each answer line
950     begins with the information category name
951     followed by a colon and then a space character
952     &lt;SP&gt; and finally the info character string
953     to that info category. At the moment the
954     following information categories are
955     defined:
956     </p>
957     <p></p>
958     <blockquote class="text">
959     <p>DESCRIPTION -
960     </p>
961     <blockquote class="text">
962     <p> character string describing the
963     audio output driver
964     </p>
965     </blockquote>
966    
967     <p>VERSION -
968     </p>
969     <blockquote class="text">
970     <p>character string reflecting the
971     driver's version
972     </p>
973     </blockquote>
974    
975     <p>PARAMETERS -
976     </p>
977     <blockquote class="text">
978     <p>comma separated list of all
979     parameters available for the given
980     audio output driver, at least
981     parameters 'channels', 'samplerate'
982     and 'active' are offered by all audio
983     output drivers
984     </p>
985     </blockquote>
986    
987     </blockquote>
988    
989     <p>The mentioned fields above don't have to be
990     in particular order.
991     </p>
992     </blockquote>
993    
994     <p>Example:
995     </p>
996     <p></p>
997     <blockquote class="text">
998     <p>C: "GET AUDIO_OUTPUT_DRIVER INFO ALSA"
999     </p>
1000     <p>S: "DESCRIPTION: Advanced Linux Sound
1001     Architecture"
1002     </p>
1003     <p>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"
1004     </p>
1005     <p>&nbsp;&nbsp;&nbsp;"PARAMETERS:
1006     DRIVER,CHANNELS,SAMPLERATE,ACTIVE,FRAGMENTS,
1007     FRAGMENTSIZE,CARD"
1008     </p>
1009     <p>&nbsp;&nbsp;&nbsp;"."
1010     </p>
1011     </blockquote>
1012    
1013 schoenebeck 575 <a name="rfc.section.6.2.4"></a><h4><a name="GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO">6.2.4</a>&nbsp;Getting information about specific audio
1014 senoner 542 output driver parameter</h4>
1015    
1016     <p>Use the following command to get detailed information
1017     about a specific audio output driver parameter:
1018     </p>
1019     <p></p>
1020     <blockquote class="text">
1021     <p>GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO &lt;audio&gt; &lt;prm&gt; [&lt;deplist&gt;]
1022     </p>
1023     </blockquote>
1024    
1025     <p>Where &lt;audio&gt; is the name of the audio output
1026     driver as returned by the <a class="info" href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"<span>Getting all available audio output drivers</span></a> command,
1027     &lt;prm&gt; a specific parameter name for which information should be
1028     obtained (as returned by the
1029     <a class="info" href="#GET AUDIO_OUTPUT_DRIVER INFO">"GET AUDIO_OUTPUT_DRIVER INFO"<span>Getting information about a specific audio output driver</span></a> command) and
1030     &lt;deplist&gt; is an optional list of parameters on which the sought
1031     parameter &lt;prm&gt; depends on, &lt;deplist&gt; is a list of key-value
1032     pairs in form of "key1=val1 key2=val2 ...", where character string values
1033     are encapsulated into apostrophes ('). Arguments given with &lt;deplist&gt;
1034     which are not dependency parameters of &lt;prm&gt; will be ignored, means
1035     the front-end application can simply put all parameters into &lt;deplist&gt;
1036     with the values already selected by the user.
1037     </p>
1038     <p>Possible Answers:
1039     </p>
1040     <p></p>
1041     <blockquote class="text">
1042     <p>LinuxSampler will answer by sending a
1043     &lt;CRLF&gt; separated list.
1044     Each answer line begins with the information category name
1045     followed by a colon and then a space character &lt;SP&gt; and
1046     finally
1047     the info character string to that info category. There are
1048     information which is always returned, independently of the
1049     given driver parameter and there are optional information
1050     which is only shown dependently to given driver parameter. At
1051     the moment the following information categories are defined:
1052     </p>
1053     </blockquote>
1054    
1055     <p></p>
1056     <blockquote class="text">
1057     <p>TYPE -
1058     </p>
1059     <blockquote class="text">
1060     <p>either "BOOL" for boolean value(s) or
1061     "INT" for integer
1062     value(s) or "FLOAT" for dotted number(s) or "STRING" for
1063     character string(s)
1064     (always returned, no matter which driver parameter)
1065     </p>
1066     </blockquote>
1067    
1068     <p>DESCRIPTION -
1069     </p>
1070     <blockquote class="text">
1071     <p>arbitrary text describing the purpose of the parameter
1072     (always returned, no matter which driver parameter)
1073     </p>
1074     </blockquote>
1075    
1076     <p>MANDATORY -
1077     </p>
1078     <blockquote class="text">
1079     <p>either true or false, defines if this parameter must be
1080     given when the device is to be created with the
1081     <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">'CREATE AUDIO_OUTPUT_DEVICE'<span>Creating an audio output device</span></a>
1082     command (always returned, no matter which driver parameter)
1083     </p>
1084     </blockquote>
1085    
1086     <p>FIX -
1087     </p>
1088     <blockquote class="text">
1089     <p>either true or false, if false then this parameter can
1090     be changed at any time, once the device is created by
1091     the <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">'CREATE AUDIO_OUTPUT_DEVICE'<span>Creating an audio output device</span></a>
1092     command (always returned, no matter which driver parameter)
1093     </p>
1094     </blockquote>
1095    
1096     <p>MULTIPLICITY -
1097     </p>
1098     <blockquote class="text">
1099     <p>either true or false, defines if this parameter allows
1100     only one value or a list of values, where true means
1101     multiple values and false only a single value allowed
1102     (always returned, no matter which driver parameter)
1103     </p>
1104     </blockquote>
1105    
1106     <p>DEPENDS -
1107     </p>
1108     <blockquote class="text">
1109 schoenebeck 561 <p>comma separated list of parameters this parameter depends
1110 senoner 542 on, means the values for fields 'DEFAULT', 'RANGE_MIN',
1111     'RANGE_MAX' and 'POSSIBILITIES' might depend on these
1112     listed parameters, for example assuming that an audio
1113     driver (like the ALSA driver) offers parameters 'card'
1114     and 'samplerate' then parameter 'samplerate' would
1115     depend on 'card' because the possible values for
1116     'samplerate' depends on the sound card which can be
1117     chosen by the 'card' parameter
1118     (optionally returned, dependent to driver parameter)
1119     </p>
1120     </blockquote>
1121    
1122     <p>DEFAULT -
1123     </p>
1124     <blockquote class="text">
1125     <p>reflects the default value for this parameter which is
1126     used when the device is created and not explicitly
1127     given with the <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">'CREATE AUDIO_OUTPUT_DEVICE'<span>Creating an audio output device</span></a> command,
1128     in case of MULTIPLCITY=true, this is a comma separated
1129     list, that's why character strings are encapsulated into
1130     apostrophes (')
1131     (optionally returned, dependent to driver parameter)
1132     </p>
1133     </blockquote>
1134    
1135     <p>RANGE_MIN -
1136     </p>
1137     <blockquote class="text">
1138     <p>defines lower limit of the allowed value range for this
1139     parameter, can be an integer value as well as a dotted
1140     number, this parameter is often used in conjunction
1141     with RANGE_MAX, but may also appear without
1142     (optionally returned, dependent to driver parameter)
1143     </p>
1144     </blockquote>
1145    
1146     <p>RANGE_MAX -
1147     </p>
1148     <blockquote class="text">
1149     <p>defines upper limit of the allowed value range for this
1150     parameter, can be an integer value as well as a dotted
1151     number, this parameter is often used in conjunction with
1152     RANGE_MIN, but may also appear without
1153     (optionally returned, dependent to driver parameter)
1154     </p>
1155     </blockquote>
1156    
1157     <p>POSSIBILITIES -
1158     </p>
1159     <blockquote class="text">
1160     <p>comma separated list of possible values for this
1161     parameter, character strings are encapsulated into
1162     apostrophes
1163     (optionally returned, dependent to driver parameter)
1164     </p>
1165     </blockquote>
1166    
1167     </blockquote>
1168    
1169     <p>The mentioned fields above don't have to be in particular order.
1170     </p>
1171     <p>Examples:
1172     </p>
1173     <p></p>
1174     <blockquote class="text">
1175     <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA CARD"
1176     </p>
1177     <p>S: "DESCRIPTION: sound card to be used"
1178     </p>
1179     <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
1180     </p>
1181     <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1182     </p>
1183     <p>&nbsp;&nbsp;&nbsp;"FIX: true"
1184     </p>
1185     <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1186     </p>
1187     <p>&nbsp;&nbsp;&nbsp;"DEFAULT: '0,0'"
1188     </p>
1189     <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: '0,0','1,0','2,0'"
1190     </p>
1191     <p>&nbsp;&nbsp;&nbsp;"."
1192     </p>
1193     </blockquote>
1194    
1195     <p></p>
1196     <blockquote class="text">
1197     <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE"
1198     </p>
1199     <p>S: "DESCRIPTION: output sample rate in Hz"
1200     </p>
1201     <p>&nbsp;&nbsp;&nbsp;"TYPE: INT"
1202     </p>
1203     <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1204     </p>
1205     <p>&nbsp;&nbsp;&nbsp;"FIX: false"
1206     </p>
1207     <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1208     </p>
1209     <p>&nbsp;&nbsp;&nbsp;"DEPENDS: card"
1210     </p>
1211     <p>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"
1212     </p>
1213     <p>&nbsp;&nbsp;&nbsp;"."
1214     </p>
1215     </blockquote>
1216    
1217     <p></p>
1218     <blockquote class="text">
1219     <p>C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE CARD='0,0'"
1220     </p>
1221     <p>S: "DESCRIPTION: output sample rate in Hz"
1222     </p>
1223     <p>&nbsp;&nbsp;&nbsp;"TYPE: INT"
1224     </p>
1225     <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
1226     </p>
1227     <p>&nbsp;&nbsp;&nbsp;"FIX: false"
1228     </p>
1229     <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
1230     </p>
1231     <p>&nbsp;&nbsp;&nbsp;"DEPENDS: card"
1232     </p>
1233     <p>&nbsp;&nbsp;&nbsp;"DEFAULT: 44100"
1234     </p>
1235     <p>&nbsp;&nbsp;&nbsp;"RANGE_MIN: 22050"
1236     </p>
1237     <p>&nbsp;&nbsp;&nbsp;"RANGE_MAX: 96000"
1238     </p>
1239     <p>&nbsp;&nbsp;&nbsp;"."
1240     </p>
1241     </blockquote>
1242    
1243 schoenebeck 575 <a name="rfc.section.6.2.5"></a><h4><a name="CREATE AUDIO_OUTPUT_DEVICE">6.2.5</a>&nbsp;Creating an audio output device</h4>
1244 senoner 542
1245     <p>Use the following command to create a new audio output device for the desired audio output system:
1246     </p>
1247     <p></p>
1248     <blockquote class="text">
1249     <p>CREATE AUDIO_OUTPUT_DEVICE &lt;audio-output-driver&gt; [&lt;param-list&gt;]
1250     </p>
1251     </blockquote>
1252    
1253     <p>Where &lt;audio-output-driver&gt; should be replaced by the desired audio
1254 schoenebeck 575 output system as returned by the
1255     <a class="info" href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"<span>Getting all available audio output drivers</span></a>
1256     command and &lt;param-list&gt; by an optional list of driver
1257 senoner 542 specific parameters in form of "key1=val1 key2=val2 ...", where
1258     character string values should be encapsulated into apostrophes (').
1259     Note that there might be drivers which require parameter(s) to be
1260     given with this command. Use the previously described commands in
1261     this chapter to get this information.
1262     </p>
1263     <p>Possible Answers:
1264     </p>
1265     <p></p>
1266     <blockquote class="text">
1267     <p>"OK[&lt;device-id&gt;]" -
1268     </p>
1269     <blockquote class="text">
1270     <p>in case the device was successfully created, where
1271     &lt;device-id&gt; is the numerical ID of the new device
1272     </p>
1273     </blockquote>
1274    
1275     <p>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1276     </p>
1277     <blockquote class="text">
1278     <p>in case the device was created successfully, where
1279     &lt;device-id&gt; is the numerical ID of the new device, but there
1280     are noteworthy issue(s) related (e.g. sound card doesn't
1281     support given hardware parameters and the driver is using
1282     fall-back values), providing an appropriate warning code and
1283     warning message
1284     </p>
1285     </blockquote>
1286    
1287     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1288     </p>
1289     <blockquote class="text">
1290     <p>in case it failed, providing an appropriate error code and error message
1291     </p>
1292     </blockquote>
1293    
1294     </blockquote>
1295    
1296     <p>Examples:
1297     </p>
1298     <p></p>
1299     <blockquote class="text">
1300     <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA"
1301     </p>
1302     <p>S: "OK[0]"
1303     </p>
1304     </blockquote>
1305    
1306     <p></p>
1307     <blockquote class="text">
1308     <p>C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"
1309     </p>
1310     <p>S: "OK[1]"
1311     </p>
1312     </blockquote>
1313    
1314 schoenebeck 575 <a name="rfc.section.6.2.6"></a><h4><a name="DESTROY AUDIO_OUTPUT_DEVICE">6.2.6</a>&nbsp;Destroying an audio output device</h4>
1315 senoner 542
1316     <p>Use the following command to destroy a created output device:
1317     </p>
1318     <p></p>
1319     <blockquote class="text">
1320     <p>DESTROY AUDIO_OUTPUT_DEVICE &lt;device-id&gt;
1321     </p>
1322     </blockquote>
1323    
1324     <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1325     audio output device as given by the
1326     <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"<span>Creating an audio output device</span></a>
1327     or <a class="info" href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"<span>Getting all created audio output device list</span></a>
1328     command.
1329     </p>
1330     <p>Possible Answers:
1331     </p>
1332     <p></p>
1333     <blockquote class="text">
1334     <p>"OK" -
1335     </p>
1336     <blockquote class="text">
1337     <p>in case the device was successfully destroyed
1338     </p>
1339     </blockquote>
1340    
1341     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1342     </p>
1343     <blockquote class="text">
1344     <p>in case the device was destroyed successfully, but there are
1345     noteworthy issue(s) related (e.g. an audio over ethernet
1346     driver was unloaded but the other host might not be
1347     informed about this situation), providing an appropriate
1348     warning code and warning message
1349     </p>
1350     </blockquote>
1351    
1352     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1353     </p>
1354     <blockquote class="text">
1355     <p>in case it failed, providing an appropriate error code and
1356     error message
1357     </p>
1358     </blockquote>
1359    
1360     </blockquote>
1361    
1362     <p>Example:
1363     </p>
1364     <p></p>
1365     <blockquote class="text">
1366     <p>C: "DESTROY AUDIO_OUTPUT_DEVICE 0"
1367     </p>
1368     <p>S: "OK"
1369     </p>
1370     </blockquote>
1371    
1372 schoenebeck 575 <a name="rfc.section.6.2.7"></a><h4><a name="GET AUDIO_OUTPUT_DEVICES">6.2.7</a>&nbsp;Getting all created audio output device count</h4>
1373 senoner 542
1374     <p>Use the following command to count all created audio output devices:
1375     </p>
1376     <p></p>
1377     <blockquote class="text">
1378     <p>GET AUDIO_OUTPUT_DEVICES
1379     </p>
1380     </blockquote>
1381    
1382     <p>Possible Answers:
1383     </p>
1384     <p></p>
1385     <blockquote class="text">
1386     <p>LinuxSampler will answer by sending the current number of all
1387     audio output devices.
1388     </p>
1389     </blockquote>
1390    
1391     <p>Example:
1392     </p>
1393     <p></p>
1394     <blockquote class="text">
1395     <p>C: "GET AUDIO_OUTPUT_DEVICES"
1396     </p>
1397     <p>S: "4"
1398     </p>
1399     </blockquote>
1400    
1401 schoenebeck 575 <a name="rfc.section.6.2.8"></a><h4><a name="LIST AUDIO_OUTPUT_DEVICES">6.2.8</a>&nbsp;Getting all created audio output device list</h4>
1402 senoner 542
1403     <p>Use the following command to list all created audio output devices:
1404     </p>
1405     <p></p>
1406     <blockquote class="text">
1407     <p>LIST AUDIO_OUTPUT_DEVICES
1408     </p>
1409     </blockquote>
1410    
1411     <p>Possible Answers:
1412     </p>
1413     <p></p>
1414     <blockquote class="text">
1415     <p>LinuxSampler will answer by sending a comma separated list with
1416     the numerical IDs of all audio output devices.
1417     </p>
1418     </blockquote>
1419    
1420     <p>Example:
1421     </p>
1422     <p></p>
1423     <blockquote class="text">
1424     <p>C: "LIST AUDIO_OUTPUT_DEVICES"
1425     </p>
1426     <p>S: "0,1,4,5"
1427     </p>
1428     </blockquote>
1429    
1430 schoenebeck 575 <a name="rfc.section.6.2.9"></a><h4><a name="GET AUDIO_OUTPUT_DEVICE INFO">6.2.9</a>&nbsp;Getting current settings of an audio output device</h4>
1431 senoner 542
1432     <p>Use the following command to get current settings of a specific, created audio output device:
1433     </p>
1434     <p></p>
1435     <blockquote class="text">
1436     <p>GET AUDIO_OUTPUT_DEVICE INFO &lt;device-id&gt;
1437     </p>
1438     </blockquote>
1439    
1440     <p>Where &lt;device-id&gt; should be replaced by numerical ID
1441     of the audio output device as e.g. returned by the
1442     <a class="info" href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"<span>Getting all created audio output device list</span></a> command.
1443     </p>
1444     <p>Possible Answers:
1445     </p>
1446     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1447     Each answer line begins with the information category name
1448     followed by a colon and then a space character &lt;SP&gt; and finally
1449     the info character string to that info category. As some
1450     parameters might allow multiple values, character strings are
1451     encapsulated into apostrophes ('). At the moment the following
1452     information categories are defined (independently of device):
1453     </p>
1454     <p></p>
1455     <blockquote class="text">
1456     <p>DRIVER -
1457     </p>
1458     <blockquote class="text">
1459     <p>identifier of the used audio output driver, as also
1460     returned by the
1461     <a class="info" href="#LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS">"LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"<span>Getting all available audio output drivers</span></a>
1462     command
1463     </p>
1464     </blockquote>
1465    
1466     <p>CHANNELS -
1467     </p>
1468     <blockquote class="text">
1469     <p>amount of audio output channels this device currently
1470     offers
1471     </p>
1472     </blockquote>
1473    
1474     <p>SAMPLERATE -
1475     </p>
1476     <blockquote class="text">
1477     <p>playback sample rate the device uses
1478     </p>
1479     </blockquote>
1480    
1481     <p>ACTIVE -
1482     </p>
1483     <blockquote class="text">
1484     <p>either true or false, if false then the audio device is
1485     inactive and doesn't output any sound, nor do the
1486     sampler channels connected to this audio device render
1487     any audio
1488     </p>
1489     </blockquote>
1490    
1491     </blockquote>
1492    
1493     <p>The mentioned fields above don't have to be in particular
1494     order. The fields above are only those fields which are
1495     returned by all audio output devices. Every audio output driver
1496     might have its own, additional driver specific parameters (see
1497 schoenebeck 575 <a class="info" href="#GET AUDIO_OUTPUT_DRIVER INFO">Section 6.2.3<span>Getting information about a specific audio output driver</span></a>)
1498 senoner 542 which are also returned by this command.
1499     </p>
1500     <p>Example:
1501     </p>
1502     <p></p>
1503     <blockquote class="text">
1504     <p>C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
1505     </p>
1506     <p>S: "DRIVER: ALSA"
1507     </p>
1508     <p>&nbsp;&nbsp;&nbsp;"CHANNELS: 2"
1509     </p>
1510     <p>&nbsp;&nbsp;&nbsp;"SAMPLERATE: 44100"
1511     </p>
1512     <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
1513     </p>
1514     <p>&nbsp;&nbsp;&nbsp;"FRAGMENTS: 2"
1515     </p>
1516     <p>&nbsp;&nbsp;&nbsp;"FRAGMENTSIZE: 128"
1517     </p>
1518     <p>&nbsp;&nbsp;&nbsp;"CARD: '0,0'"
1519     </p>
1520     <p>&nbsp;&nbsp;&nbsp;"."
1521     </p>
1522     </blockquote>
1523    
1524 schoenebeck 575 <a name="rfc.section.6.2.10"></a><h4><a name="SET AUDIO_OUTPUT_DEVICE_PARAMETER">6.2.10</a>&nbsp;Changing settings of audio output devices</h4>
1525 senoner 542
1526     <p>Use the following command to alter a specific setting of a created audio output device:
1527     </p>
1528     <p></p>
1529     <blockquote class="text">
1530     <p>SET AUDIO_OUTPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;
1531     </p>
1532     </blockquote>
1533    
1534     <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
1535 schoenebeck 575 audio output device as given by the
1536     <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"<span>Creating an audio output device</span></a>
1537     or <a class="info" href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"<span>Getting all created audio output device list</span></a>
1538     command, &lt;key&gt; by the name of the parameter to change
1539 senoner 542 and &lt;value&gt; by the new value for this parameter.
1540     </p>
1541     <p>Possible Answers:
1542     </p>
1543     <p></p>
1544     <blockquote class="text">
1545     <p>"OK" -
1546     </p>
1547     <blockquote class="text">
1548     <p>in case setting was successfully changed
1549     </p>
1550     </blockquote>
1551    
1552     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1553     </p>
1554     <blockquote class="text">
1555     <p>in case setting was changed successfully, but there are
1556     noteworthy issue(s) related, providing an appropriate
1557     warning code and warning message
1558     </p>
1559     </blockquote>
1560    
1561     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1562     </p>
1563     <blockquote class="text">
1564     <p>in case it failed, providing an appropriate error code and
1565     error message
1566     </p>
1567     </blockquote>
1568    
1569     </blockquote>
1570    
1571     <p>Example:
1572     </p>
1573     <p></p>
1574     <blockquote class="text">
1575     <p>C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"
1576     </p>
1577     <p>S: "OK"
1578     </p>
1579     </blockquote>
1580    
1581 schoenebeck 575 <a name="rfc.section.6.2.11"></a><h4><a name="GET AUDIO_OUTPUT_CHANNEL INFO">6.2.11</a>&nbsp;Getting information about an audio channel</h4>
1582 senoner 542
1583     <p>Use the following command to get information about an audio channel:
1584     </p>
1585     <p></p>
1586     <blockquote class="text">
1587     <p>GET AUDIO_OUTPUT_CHANNEL INFO &lt;device-id&gt; &lt;audio-chan&gt;
1588     </p>
1589     </blockquote>
1590    
1591 schoenebeck 575 <p>Where &lt;device-id&gt; is the numerical ID of the audio output device as given by the
1592     <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"<span>Creating an audio output device</span></a>
1593     or <a class="info" href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"<span>Getting all created audio output device list</span></a>
1594     command and &lt;audio-chan&gt; the audio channel number.
1595 senoner 542 </p>
1596     <p>Possible Answers:
1597     </p>
1598     <p></p>
1599     <blockquote class="text">
1600     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1601     Each answer line begins with the information category name
1602     followed by a colon and then a space character &lt;SP&gt; and finally
1603     the info character string to that info category. At the moment
1604     the following information categories are defined:
1605     </p>
1606     <p></p>
1607     <blockquote class="text">
1608     <p>NAME -
1609     </p>
1610     <blockquote class="text">
1611     <p>arbitrary character string naming the channel, which
1612     doesn't have to be unique (always returned by all audio channels)
1613     </p>
1614     </blockquote>
1615    
1616     <p>IS_MIX_CHANNEL -
1617     </p>
1618     <blockquote class="text">
1619     <p>either true or false, a mix-channel is not a real,
1620     independent audio channel, but a virtual channel which
1621     is mixed to another real channel, this mechanism is
1622     needed for sampler engines which need more audio
1623     channels than the used audio system might be able to offer
1624     (always returned by all audio channels)
1625     </p>
1626     </blockquote>
1627    
1628     <p>MIX_CHANNEL_DESTINATION -
1629     </p>
1630     <blockquote class="text">
1631     <p>numerical ID (positive integer including 0)
1632     which reflects the real audio channel (of the same audio
1633     output device) this mix channel refers to, means where
1634     the audio signal actually will be routed / added to
1635     (only returned in case the audio channel is mix channel)
1636     </p>
1637     </blockquote>
1638    
1639     </blockquote>
1640    
1641     </blockquote>
1642    
1643     <p>The mentioned fields above don't have to be in particular
1644     order. The fields above are only those fields which are
1645     generally returned for the described cases by all audio
1646     channels regardless of the audio driver. Every audio channel
1647     might have its own, additional driver and channel specific
1648     parameters.
1649     </p>
1650     <p>Examples:
1651     </p>
1652     <p></p>
1653     <blockquote class="text">
1654     <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 0"
1655     </p>
1656     <p>S: "NAME: studio monitor left"
1657     </p>
1658     <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
1659     </p>
1660     <p>&nbsp;&nbsp;&nbsp;"."
1661     </p>
1662     </blockquote>
1663    
1664     <p></p>
1665     <blockquote class="text">
1666     <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 1"
1667     </p>
1668     <p>S: "NAME: studio monitor right"
1669     </p>
1670     <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
1671     </p>
1672     <p>&nbsp;&nbsp;&nbsp;"."
1673     </p>
1674     </blockquote>
1675    
1676     <p></p>
1677     <blockquote class="text">
1678     <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"
1679     </p>
1680     <p>S: "NAME: studio monitor left"
1681     </p>
1682     <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: true"
1683     </p>
1684     <p>&nbsp;&nbsp;&nbsp;"MIX_CHANNEL_DESTINATION: 1"
1685     </p>
1686     <p>&nbsp;&nbsp;&nbsp;"."
1687     </p>
1688     </blockquote>
1689    
1690     <p></p>
1691     <blockquote class="text">
1692     <p>C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"
1693     </p>
1694     <p>S: "NAME: 'ardour (left)'"
1695     </p>
1696     <p>&nbsp;&nbsp;&nbsp;"IS_MIX_CHANNEL: false"
1697     </p>
1698     <p>&nbsp;&nbsp;&nbsp;"JACK_BINDINGS: 'ardour:0'"
1699     </p>
1700     <p>&nbsp;&nbsp;&nbsp;"."
1701     </p>
1702     </blockquote>
1703    
1704 schoenebeck 575 <a name="rfc.section.6.2.12"></a><h4><a name="GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO">6.2.12</a>&nbsp;Getting information about specific audio channel parameter</h4>
1705 senoner 542
1706     <p>Use the following command to get detailed information about specific audio channel parameter:
1707     </p>
1708     <p></p>
1709     <blockquote class="text">
1710     <p>GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO &lt;dev-id&gt; &lt;chan&gt; &lt;param&gt;
1711     </p>
1712     </blockquote>
1713    
1714 schoenebeck 575 <p>Where &lt;dev-id&gt; is the numerical ID of the audio output device as returned by the
1715     <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"<span>Creating an audio output device</span></a>
1716     or <a class="info" href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"<span>Getting all created audio output device list</span></a>
1717 senoner 542 command, &lt;chan&gt; the audio channel number
1718     and &lt;param&gt; a specific channel parameter name for which information should
1719     be obtained (as returned by the <a class="info" href="#GET AUDIO_OUTPUT_CHANNEL INFO">"GET AUDIO_OUTPUT_CHANNEL INFO"<span>Getting information about an audio channel</span></a> command).
1720     </p>
1721     <p>Possible Answers:
1722     </p>
1723     <p></p>
1724     <blockquote class="text">
1725     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
1726     Each answer line begins with the information category name
1727     followed by a colon and then a space character &lt;SP&gt; and finally
1728     the info character string to that info category. There are
1729     information which is always returned, independently of the
1730     given channel parameter and there is optional information
1731     which is only shown dependently to the given audio channel. At
1732     the moment the following information categories are defined:
1733     </p>
1734     <p></p>
1735     <blockquote class="text">
1736     <p>TYPE -
1737     </p>
1738     <blockquote class="text">
1739     <p>either "BOOL" for boolean value(s) or "INT" for integer
1740     value(s) or "FLOAT" for dotted number(s) or "STRING" for
1741     character string(s)
1742     (always returned)
1743     </p>
1744     </blockquote>
1745    
1746     <p>DESCRIPTION -
1747     </p>
1748     <blockquote class="text">
1749     <p>arbitrary text describing the purpose of the parameter (always returned)
1750     </p>
1751     </blockquote>
1752    
1753     <p>FIX -
1754     </p>
1755     <blockquote class="text">
1756     <p>either true or false, if true then this parameter is
1757     read only, thus cannot be altered
1758     (always returned)
1759     </p>
1760     </blockquote>
1761    
1762     <p>MULTIPLICITY -
1763     </p>
1764     <blockquote class="text">
1765     <p>either true or false, defines if this parameter allows
1766     only one value or a list of values, where true means
1767     multiple values and false only a single value allowed
1768     (always returned)
1769     </p>
1770     </blockquote>
1771    
1772     <p>RANGE_MIN -
1773     </p>
1774     <blockquote class="text">
1775     <p>defines lower limit of the allowed value range for this
1776     parameter, can be an integer value as well as a dotted
1777     number, usually used in conjunction with 'RANGE_MAX',
1778     but may also appear without
1779     (optionally returned, dependent to driver and channel
1780     parameter)
1781     </p>
1782     </blockquote>
1783    
1784     <p>RANGE_MAX -
1785     </p>
1786     <blockquote class="text">
1787     <p>defines upper limit of the allowed value range for this
1788     parameter, can be an integer value as well as a dotted
1789     number, usually used in conjunction with 'RANGE_MIN',
1790     but may also appear without
1791     (optionally returned, dependent to driver and channel
1792     parameter)
1793     </p>
1794     </blockquote>
1795    
1796     <p>POSSIBILITIES -
1797     </p>
1798     <blockquote class="text">
1799     <p>comma separated list of possible values for this
1800     parameter, character strings are encapsulated into
1801     apostrophes
1802     (optionally returned, dependent to driver and channel
1803     parameter)
1804     </p>
1805     </blockquote>
1806    
1807     </blockquote>
1808    
1809     <p>The mentioned fields above don't have to be in particular order.
1810     </p>
1811     </blockquote>
1812    
1813     <p>Example:
1814     </p>
1815     <p></p>
1816     <blockquote class="text">
1817     <p>C: "GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO 1 0 JACK_BINDINGS"
1818     </p>
1819     <p>S: "DESCRIPTION: bindings to other JACK clients"
1820     </p>
1821     <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
1822     </p>
1823     <p>&nbsp;&nbsp;&nbsp;"FIX: false"
1824     </p>
1825     <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"
1826     </p>
1827     <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"
1828     </p>
1829     <p>&nbsp;&nbsp;&nbsp;"."
1830     </p>
1831     </blockquote>
1832    
1833 schoenebeck 575 <a name="rfc.section.6.2.13"></a><h4><a name="SET AUDIO_OUTPUT_CHANNEL_PARAMETER">6.2.13</a>&nbsp;Changing settings of audio output channels</h4>
1834 senoner 542
1835     <p>Use the following command to alter a specific setting of an audio output channel:
1836     </p>
1837     <p></p>
1838     <blockquote class="text">
1839     <p>SET AUDIO_OUTPUT_CHANNEL_PARAMETER &lt;dev-id&gt; &lt;chn&gt; &lt;key&gt;=&lt;value&gt;
1840     </p>
1841     </blockquote>
1842    
1843 schoenebeck 575 <p>Where &lt;dev-id&gt; should be replaced by the numerical ID of the audio output device as returned by the
1844     <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"<span>Creating an audio output device</span></a>
1845     or <a class="info" href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"<span>Getting all created audio output device list</span></a>
1846     command, &lt;chn&gt; by the audio channel number, &lt;key&gt; by the name of the
1847 senoner 542 parameter to change and &lt;value&gt; by the new value for this parameter.
1848     </p>
1849     <p>Possible Answers:
1850     </p>
1851     <p></p>
1852     <blockquote class="text">
1853     <p>"OK" -
1854     </p>
1855     <blockquote class="text">
1856     <p>in case setting was successfully changed
1857     </p>
1858     </blockquote>
1859    
1860     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
1861     </p>
1862     <blockquote class="text">
1863     <p>in case setting was changed successfully, but there are
1864     noteworthy issue(s) related, providing an appropriate
1865     warning code and warning message
1866     </p>
1867     </blockquote>
1868    
1869     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
1870     </p>
1871     <blockquote class="text">
1872     <p>in case it failed, providing an appropriate error code and
1873     error message
1874     </p>
1875     </blockquote>
1876    
1877     </blockquote>
1878    
1879     <p>Example:
1880     </p>
1881     <p></p>
1882     <blockquote class="text">
1883     <p>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"
1884     </p>
1885     <p>S: "OK"
1886     </p>
1887     </blockquote>
1888    
1889     <p></p>
1890     <blockquote class="text">
1891     <p>C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"
1892     </p>
1893     <p>S: "OK"
1894     </p>
1895     </blockquote>
1896    
1897 schoenebeck 575 <a name="rfc.section.6.3"></a><h4><a name="anchor10">6.3</a>&nbsp;Configuring MIDI input drivers</h4>
1898 senoner 542
1899     <p>Instances of drivers in LinuxSampler are called devices. You can use
1900     multiple MIDI devices simultaneously, e.g. to use MIDI over ethernet as
1901     MIDI input on one sampler channel and ALSA as MIDI input on another sampler
1902     channel. For particular MIDI input systems it's also possible to create
1903     several devices of the same MIDI input type. This chapter describes all
1904     commands to configure LinuxSampler's MIDI input devices and their parameters.
1905     </p>
1906     <p>Instead of defining commands and parameters for each driver individually,
1907     all possible parameters, their meanings and possible values have to be obtained
1908     at runtime. This makes the protocol a bit abstract, but has the advantage, that
1909     front-ends can be written independently of what drivers are currently implemented
1910     and what parameters these drivers are actually offering. This means front-ends can
1911     even handle drivers which are implemented somewhere in future without modifying
1912     the front-end at all.
1913     </p>
1914     <p>Commands for configuring MIDI input devices are pretty much the same as the
1915     commands for configuring audio output drivers, already described in the last
1916     chapter.
1917     </p>
1918     <p>Note: examples in this chapter showing particular parameters of drivers are
1919     not meant as specification of the drivers' parameters. Driver implementations in
1920     LinuxSampler might have complete different parameter names and meanings than shown
1921     in these examples or might change in future, so these examples are only meant for
1922     showing how to retrieve what parameters drivers are offering, how to retrieve their
1923     possible values, etc.
1924     </p>
1925 schoenebeck 575 <a name="rfc.section.6.3.1"></a><h4><a name="GET AVAILABLE_MIDI_INPUT_DRIVERS">6.3.1</a>&nbsp;Getting amount of available MIDI input drivers</h4>
1926 senoner 542
1927     <p>Use the following command to get the number of
1928     MIDI input drivers currently available for the
1929     LinuxSampler instance:
1930     </p>
1931     <p></p>
1932     <blockquote class="text">
1933     <p>GET AVAILABLE_MIDI_INPUT_DRIVERS
1934     </p>
1935     </blockquote>
1936    
1937     <p>Possible Answers:
1938     </p>
1939     <p></p>
1940     <blockquote class="text">
1941     <p>LinuxSampler will answer by sending the
1942     number of available MIDI input drivers.
1943     </p>
1944     </blockquote>
1945    
1946     <p>Example:
1947     </p>
1948     <p></p>
1949     <blockquote class="text">
1950     <p>C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"
1951     </p>
1952     <p>S: "2"
1953     </p>
1954     </blockquote>
1955    
1956 schoenebeck 575 <a name="rfc.section.6.3.2"></a><h4><a name="LIST AVAILABLE_MIDI_INPUT_DRIVERS">6.3.2</a>&nbsp;Getting all available MIDI input drivers</h4>
1957 senoner 542
1958     <p>Use the following command to list all MIDI input drivers currently available
1959     for the LinuxSampler instance:
1960     </p>
1961     <p></p>
1962     <blockquote class="text">
1963     <p>LIST AVAILABLE_MIDI_INPUT_DRIVERS
1964     </p>
1965     </blockquote>
1966    
1967     <p>Possible Answers:
1968     </p>
1969     <p></p>
1970     <blockquote class="text">
1971     <p>LinuxSampler will answer by sending comma separated character
1972     strings, each symbolizing a MIDI input driver.
1973     </p>
1974     </blockquote>
1975    
1976     <p>Example:
1977     </p>
1978     <p></p>
1979     <blockquote class="text">
1980     <p>C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
1981     </p>
1982     <p>S: "ALSA,JACK"
1983     </p>
1984     </blockquote>
1985    
1986 schoenebeck 575 <a name="rfc.section.6.3.3"></a><h4><a name="GET MIDI_INPUT_DRIVER INFO">6.3.3</a>&nbsp;Getting information about a specific MIDI input driver</h4>
1987 senoner 542
1988     <p>Use the following command to get detailed information about a specific MIDI input driver:
1989     </p>
1990     <p></p>
1991     <blockquote class="text">
1992     <p>GET MIDI_INPUT_DRIVER INFO &lt;midi-input-driver&gt;
1993     </p>
1994     </blockquote>
1995    
1996 schoenebeck 575 <p>Where &lt;midi-input-driver&gt; is the name of the MIDI input driver as returned
1997     by the <a class="info" href="#LIST AVAILABLE_MIDI_INPUT_DRIVERS">"LIST AVAILABLE_MIDI_INPUT_DRIVERS"<span>Getting all available MIDI input drivers</span></a> command.
1998 senoner 542 </p>
1999     <p>Possible Answers:
2000     </p>
2001     <p></p>
2002     <blockquote class="text">
2003     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2004     Each answer line begins with the information category name
2005     followed by a colon and then a space character &lt;SP&gt; and finally
2006     the info character string to that info category. At the moment
2007     the following information categories are defined:
2008     </p>
2009     <p></p>
2010     <blockquote class="text">
2011     <p>DESCRIPTION -
2012     </p>
2013     <blockquote class="text">
2014     <p>arbitrary description text about the MIDI input driver
2015     </p>
2016     </blockquote>
2017    
2018     <p>VERSION -
2019     </p>
2020     <blockquote class="text">
2021     <p>arbitrary character string regarding the driver's version
2022     </p>
2023     </blockquote>
2024    
2025     <p>PARAMETERS -
2026     </p>
2027     <blockquote class="text">
2028     <p>comma separated list of all parameters available for the given MIDI input driver
2029     </p>
2030     </blockquote>
2031    
2032     </blockquote>
2033    
2034     <p>The mentioned fields above don't have to be in particular order.
2035     </p>
2036     </blockquote>
2037    
2038     <p>Example:
2039     </p>
2040     <p></p>
2041     <blockquote class="text">
2042     <p>C: "GET MIDI_INPUT_DRIVER INFO ALSA"
2043     </p>
2044     <p>S: "DESCRIPTION: Advanced Linux Sound Architecture"
2045     </p>
2046     <p>&nbsp;&nbsp;&nbsp;"VERSION: 1.0"
2047     </p>
2048     <p>&nbsp;&nbsp;&nbsp;"PARAMETERS: DRIVER,ACTIVE"
2049     </p>
2050     <p>&nbsp;&nbsp;&nbsp;"."
2051     </p>
2052     </blockquote>
2053    
2054 schoenebeck 575 <a name="rfc.section.6.3.4"></a><h4><a name="GET MIDI_INPUT_DRIVER_PARAMETER INFO">6.3.4</a>&nbsp;Getting information about specific MIDI input driver parameter</h4>
2055 senoner 542
2056     <p>Use the following command to get detailed information about a specific parameter of a specific MIDI input driver:
2057     </p>
2058     <p></p>
2059     <blockquote class="text">
2060     <p>GET MIDI_INPUT_DRIVER_PARAMETER INFO &lt;midit&gt; &lt;param&gt; [&lt;deplist&gt;]
2061     </p>
2062     </blockquote>
2063    
2064 schoenebeck 561 <p>Where &lt;midit&gt; is the name of the MIDI input driver as returned
2065 senoner 542 by the <a class="info" href="#LIST AVAILABLE_MIDI_INPUT_DRIVERS">"LIST AVAILABLE_MIDI_INPUT_DRIVERS"<span>Getting all available MIDI input drivers</span></a> command, &lt;param&gt; a specific
2066     parameter name for which information should be obtained (as returned by the
2067     <a class="info" href="#GET MIDI_INPUT_DRIVER INFO">"GET MIDI_INPUT_DRIVER INFO"<span>Getting information about a specific MIDI input driver</span></a> command) and &lt;deplist&gt; is an optional list
2068     of parameters on which the sought parameter &lt;param&gt; depends on,
2069     &lt;deplist&gt; is a key-value pair list in form of "key1=val1 key2=val2 ...",
2070     where character string values are encapsulated into apostrophes ('). Arguments
2071     given with &lt;deplist&gt; which are not dependency parameters of &lt;param&gt;
2072     will be ignored, means the front-end application can simply put all parameters
2073     in &lt;deplist&gt; with the values selected by the user.
2074     </p>
2075     <p>Possible Answers:
2076     </p>
2077     <p>LinuxSampler will answer by sending a &lt;CRLF> separated list.
2078     Each answer line begins with the information category name
2079     followed by a colon and then a space character &lt;SP> and finally
2080     the info character string to that info category. There is
2081     information which is always returned, independent of the
2082     given driver parameter and there is optional information
2083     which is only shown dependent to given driver parameter. At
2084     the moment the following information categories are defined:
2085     </p>
2086     <p></p>
2087     <blockquote class="text">
2088     <p>TYPE -
2089     </p>
2090     <blockquote class="text">
2091     <p>either "BOOL" for boolean value(s) or "INT" for integer
2092     value(s) or "FLOAT" for dotted number(s) or "STRING" for
2093     character string(s)
2094     (always returned, no matter which driver parameter)
2095     </p>
2096     </blockquote>
2097    
2098     <p>DESCRIPTION -
2099     </p>
2100     <blockquote class="text">
2101     <p>arbitrary text describing the purpose of the parameter
2102     (always returned, no matter which driver parameter)
2103     </p>
2104     </blockquote>
2105    
2106     <p>MANDATORY -
2107     </p>
2108     <blockquote class="text">
2109     <p>either true or false, defines if this parameter must be
2110     given when the device is to be created with the
2111     <a class="info" href="#CREATE MIDI_INPUT_DEVICE">'CREATE MIDI_INPUT_DEVICE'<span>Creating a MIDI input device</span></a> command
2112     (always returned, no matter which driver parameter)
2113     </p>
2114     </blockquote>
2115    
2116     <p>FIX -
2117     </p>
2118     <blockquote class="text">
2119     <p>either true or false, if false then this parameter can
2120     be changed at any time, once the device is created by
2121     the <a class="info" href="#CREATE MIDI_INPUT_DEVICE">'CREATE MIDI_INPUT_DEVICE'<span>Creating a MIDI input device</span></a> command
2122     (always returned, no matter which driver parameter)
2123     </p>
2124     </blockquote>
2125    
2126     <p>MULTIPLICITY -
2127     </p>
2128     <blockquote class="text">
2129     <p>either true or false, defines if this parameter allows
2130     only one value or a list of values, where true means
2131     multiple values and false only a single value allowed
2132     (always returned, no matter which driver parameter)
2133     </p>
2134     </blockquote>
2135    
2136     <p>DEPENDS -
2137     </p>
2138     <blockquote class="text">
2139 schoenebeck 561 <p>comma separated list of parameters this parameter depends
2140 senoner 542 on, means the values for fields 'DEFAULT', 'RANGE_MIN',
2141     'RANGE_MAX' and 'POSSIBILITIES' might depend on these
2142     listed parameters, for example assuming that an audio
2143     driver (like the ALSA driver) offers parameters 'card'
2144     and 'samplerate' then parameter 'samplerate' would
2145     depend on 'card' because the possible values for
2146     'samplerate' depends on the sound card which can be
2147     chosen by the 'card' parameter
2148     (optionally returned, dependent to driver parameter)
2149     </p>
2150     </blockquote>
2151    
2152     <p>DEFAULT -
2153     </p>
2154     <blockquote class="text">
2155     <p>reflects the default value for this parameter which is
2156     used when the device is created and not explicitly
2157     given with the <a class="info" href="#CREATE MIDI_INPUT_DEVICE">'CREATE MIDI_INPUT_DEVICE'<span>Creating a MIDI input device</span></a> command,
2158     in case of MULTIPLCITY=true, this is a comma separated
2159     list, that's why character strings are encapsulated into
2160     apostrophes (')
2161     (optionally returned, dependent to driver parameter)
2162     </p>
2163     </blockquote>
2164    
2165     <p>RANGE_MIN -
2166     </p>
2167     <blockquote class="text">
2168     <p>defines lower limit of the allowed value range for this
2169     parameter, can be an integer value as well as a dotted
2170     number, this parameter is often used in conjunction
2171     with RANGE_MAX, but may also appear without
2172     (optionally returned, dependent to driver parameter)
2173     </p>
2174     </blockquote>
2175    
2176     <p>RANGE_MAX -
2177     </p>
2178     <blockquote class="text">
2179     <p>defines upper limit of the allowed value range for this
2180     parameter, can be an integer value as well as a dotted
2181     number, this parameter is often used in conjunction with
2182     RANGE_MIN, but may also appear without
2183     (optionally returned, dependent to driver parameter)
2184     </p>
2185     </blockquote>
2186    
2187     <p>POSSIBILITIES -
2188     </p>
2189     <blockquote class="text">
2190     <p>comma separated list of possible values for this
2191     parameter, character strings are encapsulated into
2192     apostrophes
2193     (optionally returned, dependent to driver parameter)
2194     </p>
2195     </blockquote>
2196    
2197     </blockquote>
2198    
2199     <p>The mentioned fields above don't have to be in particular order.
2200     </p>
2201     <p>Example:
2202     </p>
2203     <p></p>
2204     <blockquote class="text">
2205     <p>C: "GET MIDI_INPUT_DRIVER_PARAMETER INFO ALSA ACTIVE"
2206     </p>
2207     <p>S: "DESCRIPTION: Whether device is enabled"
2208     </p>
2209     <p>&nbsp;&nbsp;&nbsp;"TYPE: BOOL"
2210     </p>
2211     <p>&nbsp;&nbsp;&nbsp;"MANDATORY: false"
2212     </p>
2213     <p>&nbsp;&nbsp;&nbsp;"FIX: false"
2214     </p>
2215     <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: false"
2216     </p>
2217     <p>&nbsp;&nbsp;&nbsp;"DEFAULT: true"
2218     </p>
2219     <p>&nbsp;&nbsp;&nbsp;"."
2220     </p>
2221     </blockquote>
2222    
2223 schoenebeck 575 <a name="rfc.section.6.3.5"></a><h4><a name="CREATE MIDI_INPUT_DEVICE">6.3.5</a>&nbsp;Creating a MIDI input device</h4>
2224 senoner 542
2225     <p>Use the following command to create a new MIDI input device for the desired MIDI input system:
2226     </p>
2227     <p></p>
2228     <blockquote class="text">
2229     <p>CREATE MIDI_INPUT_DEVICE &lt;midi-input-driver&gt; [&lt;param-list&gt;]
2230     </p>
2231     </blockquote>
2232    
2233 schoenebeck 575 <p>Where &lt;midi-input-driver&gt; should be replaced by the desired MIDI input system as returned
2234     by the <a class="info" href="#LIST AVAILABLE_MIDI_INPUT_DRIVERS">"LIST AVAILABLE_MIDI_INPUT_DRIVERS"<span>Getting all available MIDI input drivers</span></a> command and &lt;param-list&gt; by an
2235 senoner 542 optional list of driver specific parameters in form of "key1=val1 key2=val2 ...", where
2236     character string values should be encapsulated into apostrophes (').
2237     Note that there might be drivers which require parameter(s) to be
2238     given with this command. Use the previously described commands in
2239     this chapter to get that information.
2240     </p>
2241     <p>Possible Answers:
2242     </p>
2243     <p></p>
2244     <blockquote class="text">
2245     <p>"OK[&lt;device-id&gt;]" -
2246     </p>
2247     <blockquote class="text">
2248     <p>in case the device was successfully created, where
2249     &lt;device-id&gt; is the numerical ID of the new device
2250     </p>
2251     </blockquote>
2252    
2253     <p>"WRN[&lt;device-id&gt;]:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2254     </p>
2255     <blockquote class="text">
2256     <p>in case the driver was loaded successfully, where
2257     &lt;device-id&gt; is the numerical ID of the new device, but
2258     there are noteworthy issue(s) related, providing an
2259     appropriate warning code and warning message
2260     </p>
2261     </blockquote>
2262    
2263     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2264     </p>
2265     <blockquote class="text">
2266     <p>in case it failed, providing an appropriate error code and error message
2267     </p>
2268     </blockquote>
2269    
2270     </blockquote>
2271    
2272     <p>Example:
2273     </p>
2274     <p></p>
2275     <blockquote class="text">
2276     <p>C: "CREATE MIDI_INPUT_DEVICE ALSA"
2277     </p>
2278     <p>S: "OK[0]"
2279     </p>
2280     </blockquote>
2281    
2282 schoenebeck 575 <a name="rfc.section.6.3.6"></a><h4><a name="DESTROY MIDI_INPUT_DEVICE">6.3.6</a>&nbsp;Destroying a MIDI input device</h4>
2283 senoner 542
2284     <p>Use the following command to destroy a created MIDI input device:
2285     </p>
2286     <p></p>
2287     <blockquote class="text">
2288     <p>DESTROY MIDI_INPUT_DEVICE &lt;device-id&gt;
2289     </p>
2290     </blockquote>
2291    
2292 schoenebeck 575 <p>Where &lt;device-id&gt; should be replaced by the device's numerical ID as returned by the
2293     <a class="info" href="#CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"<span>Creating a MIDI input device</span></a>
2294     or <a class="info" href="#LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"<span>Getting all created MIDI input device list</span></a>
2295     command.
2296 senoner 542 </p>
2297     <p>Possible Answers:
2298     </p>
2299     <p></p>
2300     <blockquote class="text">
2301     <p>"OK" -
2302     </p>
2303     <blockquote class="text">
2304     <p>in case the device was successfully destroyed
2305     </p>
2306     </blockquote>
2307    
2308     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2309     </p>
2310     <blockquote class="text">
2311     <p>in case the device was destroyed, but there are noteworthy
2312     issue(s) related, providing an appropriate warning code and
2313     warning message
2314     </p>
2315     </blockquote>
2316    
2317     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2318     </p>
2319     <blockquote class="text">
2320     <p>in case it failed, providing an appropriate error code and error message
2321     </p>
2322     </blockquote>
2323    
2324     </blockquote>
2325    
2326     <p>Example:
2327     </p>
2328     <p></p>
2329     <blockquote class="text">
2330     <p>C: "DESTROY MIDI_INPUT_DEVICE 0"
2331     </p>
2332     <p>S: "OK"
2333     </p>
2334     </blockquote>
2335    
2336 schoenebeck 575 <a name="rfc.section.6.3.7"></a><h4><a name="GET MIDI_INPUT_DEVICES">6.3.7</a>&nbsp;Getting all created MIDI input device count</h4>
2337 senoner 542
2338     <p>Use the following command to count all created MIDI input devices:
2339     </p>
2340     <p></p>
2341     <blockquote class="text">
2342     <p>GET MIDI_INPUT_DEVICES
2343     </p>
2344     </blockquote>
2345    
2346     <p>Possible Answers:
2347     </p>
2348     <p></p>
2349     <blockquote class="text">
2350     <p>LinuxSampler will answer by sending the current number of all
2351     MIDI input devices.
2352     </p>
2353     </blockquote>
2354    
2355     <p>Example:
2356     </p>
2357     <p></p>
2358     <blockquote class="text">
2359     <p>C: "GET MIDI_INPUT_DEVICES"
2360     </p>
2361     <p>S: "3"
2362     </p>
2363     </blockquote>
2364    
2365 schoenebeck 575 <a name="rfc.section.6.3.8"></a><h4><a name="LIST MIDI_INPUT_DEVICES">6.3.8</a>&nbsp;Getting all created MIDI input device list</h4>
2366 senoner 542
2367     <p>Use the following command to list all created MIDI input devices:
2368     </p>
2369     <p></p>
2370     <blockquote class="text">
2371     <p>LIST MIDI_INPUT_DEVICES
2372     </p>
2373     </blockquote>
2374    
2375     <p>Possible Answers:
2376     </p>
2377     <p></p>
2378     <blockquote class="text">
2379     <p>LinuxSampler will answer by sending a comma separated list
2380     with the numerical Ids of all created MIDI input devices.
2381     </p>
2382     </blockquote>
2383    
2384     <p>Examples:
2385     </p>
2386     <p></p>
2387     <blockquote class="text">
2388     <p>C: "LIST MIDI_INPUT_DEVICES"
2389     </p>
2390     <p>S: "0,1,2"
2391     </p>
2392     </blockquote>
2393    
2394     <p></p>
2395     <blockquote class="text">
2396     <p>C: "LIST MIDI_INPUT_DEVICES"
2397     </p>
2398     <p>S: "1,3"
2399     </p>
2400     </blockquote>
2401    
2402 schoenebeck 575 <a name="rfc.section.6.3.9"></a><h4><a name="GET MIDI_INPUT_DEVICE INFO">6.3.9</a>&nbsp;Getting current settings of a MIDI input device</h4>
2403 senoner 542
2404     <p>Use the following command to get current settings of a specific, created MIDI input device:
2405     </p>
2406     <p></p>
2407     <blockquote class="text">
2408     <p>GET MIDI_INPUT_DEVICE INFO &lt;device-id&gt;
2409     </p>
2410     </blockquote>
2411    
2412 schoenebeck 575 <p>Where &lt;device-id&gt; is the numerical ID of the MIDI input device as returned by the
2413     <a class="info" href="#CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"<span>Creating a MIDI input device</span></a>
2414     or <a class="info" href="#LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"<span>Getting all created MIDI input device list</span></a>
2415     command.
2416 senoner 542 </p>
2417     <p>Possible Answers:
2418     </p>
2419     <p></p>
2420     <blockquote class="text">
2421     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2422     Each answer line begins with the information category name
2423     followed by a colon and then a space character &lt;SP&gt; and finally
2424     the info character string to that info category. As some
2425     parameters might allow multiple values, character strings are
2426     encapsulated into apostrophes ('). At the moment the following
2427     information categories are defined (independent of driver):
2428     </p>
2429     <p></p>
2430     <blockquote class="text">
2431     <p>DRIVER -
2432     </p>
2433     <blockquote class="text">
2434     <p>identifier of the used MIDI input driver, as e.g.
2435     returned by the <a class="info" href="#LIST AVAILABLE_MIDI_INPUT_DRIVERS">"LIST AVAILABLE_MIDI_INPUT_DRIVERS"<span>Getting all available MIDI input drivers</span></a>
2436     command
2437     </p>
2438     </blockquote>
2439    
2440     </blockquote>
2441     <blockquote class="text">
2442     <p><p>ACTIVE -
2443     </p>
2444     <blockquote class="text">
2445     <p>either true or false, if false then the MIDI device is
2446     inactive and doesn't listen to any incoming MIDI events
2447     and thus doesn't forward them to connected sampler
2448     channels
2449     </p>
2450     </blockquote>
2451    
2452     </blockquote>
2453    
2454     </blockquote>
2455    
2456     <p>The mentioned fields above don't have to be in particular
2457     order. The fields above are only those fields which are
2458     returned by all MIDI input devices. Every MIDI input driver
2459     might have its own, additional driver specific parameters (see
2460     <a class="info" href="#GET MIDI_INPUT_DRIVER INFO">"GET MIDI_INPUT_DRIVER INFO"<span>Getting information about a specific MIDI input driver</span></a> command) which are also returned
2461     by this command.
2462     </p>
2463     <p>Example:
2464     </p>
2465     <p></p>
2466     <blockquote class="text">
2467     <p>C: "GET MIDI_INPUT_DEVICE INFO 0"
2468     </p>
2469     <p>S: "DRIVER: ALSA"
2470     </p>
2471     <p>&nbsp;&nbsp;&nbsp;"ACTIVE: true"
2472     </p>
2473     <p>&nbsp;&nbsp;&nbsp;"."
2474     </p>
2475     </blockquote>
2476    
2477 schoenebeck 575 <a name="rfc.section.6.3.10"></a><h4><a name="SET MIDI_INPUT_DEVICE_PARAMETER">6.3.10</a>&nbsp;Changing settings of MIDI input devices</h4>
2478 senoner 542
2479     <p>Use the following command to alter a specific setting of a created MIDI input device:
2480     </p>
2481     <p></p>
2482     <blockquote class="text">
2483     <p>SET MIDI_INPUT_DEVICE_PARAMETER &lt;device-id&gt; &lt;key&gt;=&lt;value&gt;
2484     </p>
2485     </blockquote>
2486    
2487     <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
2488 schoenebeck 575 MIDI input device as returned by the
2489     <a class="info" href="#CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"<span>Creating a MIDI input device</span></a>
2490     or <a class="info" href="#LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"<span>Getting all created MIDI input device list</span></a>
2491     command, &lt;key&gt; by the name of the parameter to change and
2492 senoner 542 &lt;value&gt; by the new value for this parameter.
2493     </p>
2494     <p>Possible Answers:
2495     </p>
2496     <p></p>
2497     <blockquote class="text">
2498     <p>"OK" -
2499     </p>
2500     <blockquote class="text">
2501     <p>in case setting was successfully changed
2502     </p>
2503     </blockquote>
2504    
2505     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2506     </p>
2507     <blockquote class="text">
2508     <p>in case setting was changed successfully, but there are
2509     noteworthy issue(s) related, providing an appropriate
2510     warning code and warning message
2511     </p>
2512     </blockquote>
2513    
2514     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2515     </p>
2516     <blockquote class="text">
2517     <p>in case it failed, providing an appropriate error code and error message
2518     </p>
2519     </blockquote>
2520    
2521     </blockquote>
2522    
2523     <p>Example:
2524     </p>
2525     <p></p>
2526     <blockquote class="text">
2527     <p>C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"
2528     </p>
2529     <p>S: "OK"
2530     </p>
2531     </blockquote>
2532    
2533 schoenebeck 575 <a name="rfc.section.6.3.11"></a><h4><a name="GET MIDI_INPUT_PORT INFO">6.3.11</a>&nbsp;Getting information about a MIDI port</h4>
2534 senoner 542
2535     <p>Use the following command to get information about a MIDI port:
2536     </p>
2537     <p></p>
2538     <blockquote class="text">
2539     <p>GET MIDI_INPUT_PORT INFO &lt;device-id&gt; &lt;midi-port&gt;
2540     </p>
2541     </blockquote>
2542    
2543 schoenebeck 575 <p>Where &lt;device-id&gt; is the numerical ID of the MIDI input device as returned by the
2544     <a class="info" href="#CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"<span>Creating a MIDI input device</span></a>
2545     or <a class="info" href="#LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"<span>Getting all created MIDI input device list</span></a>
2546     command and &lt;midi-port&gt; the MIDI input port number.
2547 senoner 542 </p>
2548     <p>Possible Answers:
2549     </p>
2550     <p></p>
2551     <blockquote class="text">
2552     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2553     Each answer line begins with the information category name
2554     followed by a colon and then a space character &lt;SP&gt; and finally
2555     the info character string to that info category. At the moment
2556     the following information categories are defined:
2557     </p>
2558     <p>NAME -
2559     </p>
2560     <blockquote class="text">
2561     <p>arbitrary character string naming the port
2562     </p>
2563     </blockquote>
2564    
2565     </blockquote>
2566    
2567     <p>The field above is only the one which is returned by all MIDI
2568     ports regardless of the MIDI driver and port. Every MIDI port
2569     might have its own, additional driver and port specific
2570     parameters.
2571     </p>
2572     <p>Example:
2573     </p>
2574     <p></p>
2575     <blockquote class="text">
2576     <p>C: "GET MIDI_INPUT_PORT INFO 0 0"
2577     </p>
2578     <p>S: "NAME: 'Masterkeyboard'"
2579     </p>
2580     <p>&nbsp;&nbsp;&nbsp;"ALSA_SEQ_BINDINGS: '64:0'"
2581     </p>
2582     <p>&nbsp;&nbsp;&nbsp;"."
2583     </p>
2584     </blockquote>
2585    
2586 schoenebeck 575 <a name="rfc.section.6.3.12"></a><h4><a name="GET MIDI_INPUT_PORT_PARAMETER INFO">6.3.12</a>&nbsp;Getting information about specific MIDI port parameter</h4>
2587 senoner 542
2588     <p>Use the following command to get detailed information about specific MIDI port parameter:
2589     </p>
2590     <p></p>
2591     <blockquote class="text">
2592     <p>GET MIDI_INPUT_PORT_PARAMETER INFO &lt;dev-id&gt; &lt;port&gt; &lt;param&gt;
2593     </p>
2594     </blockquote>
2595    
2596 schoenebeck 575 <p>Where &lt;dev-id&gt; is the numerical ID of the MIDI input device as returned by the
2597     <a class="info" href="#CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"<span>Creating a MIDI input device</span></a>
2598     or <a class="info" href="#LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"<span>Getting all created MIDI input device list</span></a>
2599     command, &lt;port&gt; the MIDI port number and
2600 senoner 542 &lt;param&gt; a specific port parameter name for which information should be
2601     obtained (as returned by the <a class="info" href="#GET MIDI_INPUT_PORT INFO">"GET MIDI_INPUT_PORT INFO"<span>Getting information about a MIDI port</span></a> command).
2602     </p>
2603     <p>Possible Answers:
2604     </p>
2605     <p></p>
2606     <blockquote class="text">
2607     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
2608     Each answer line begins with the information category name
2609     followed by a colon and then a space character &lt;SP&gt; and finally
2610     the info character string to that info category. There is
2611     information which is always returned, independently of the
2612     given channel parameter and there is optional information
2613     which are only shown dependently to the given MIDI port. At the
2614     moment the following information categories are defined:
2615     </p>
2616     <p>TYPE -
2617     </p>
2618     <blockquote class="text">
2619     <p>either "BOOL" for boolean value(s) or "INT" for integer
2620     value(s) or "FLOAT" for dotted number(s) or "STRING" for
2621     character string(s)
2622     (always returned)
2623     </p>
2624     </blockquote>
2625    
2626     <p>DESCRIPTION -
2627     </p>
2628     <blockquote class="text">
2629     <p>arbitrary text describing the purpose of the parameter
2630     (always returned)
2631     </p>
2632     </blockquote>
2633    
2634     <p>FIX -
2635     </p>
2636     <blockquote class="text">
2637     <p>either true or false, if true then this parameter is
2638     read only, thus cannot be altered
2639     (always returned)
2640     </p>
2641     </blockquote>
2642    
2643     <p>MULTIPLICITY -
2644     </p>
2645     <blockquote class="text">
2646     <p>either true or false, defines if this parameter allows
2647     only one value or a list of values, where true means
2648     multiple values and false only a single value allowed
2649     (always returned)
2650     </p>
2651     </blockquote>
2652    
2653     <p>RANGE_MIN -
2654     </p>
2655     <blockquote class="text">
2656     <p>defines lower limit of the allowed value range for this
2657     parameter, can be an integer value as well as a dotted
2658     number, this parameter is usually used in conjunction
2659     with 'RANGE_MAX' but may also appear without
2660     (optionally returned, dependent to driver and port
2661     parameter)
2662     </p>
2663     </blockquote>
2664    
2665     <p>RANGE_MAX -
2666     </p>
2667     <blockquote class="text">
2668     <p>defines upper limit of the allowed value range for this
2669     parameter, can be an integer value as well as a dotted
2670     number, this parameter is usually used in conjunction
2671     with 'RANGE_MIN' but may also appear without
2672     (optionally returned, dependent to driver and port
2673     parameter)
2674     </p>
2675     </blockquote>
2676    
2677     <p>POSSIBILITIES -
2678     </p>
2679     <blockquote class="text">
2680     <p>comma separated list of possible values for this
2681     parameter, character strings are encapsulated into
2682     apostrophes
2683     (optionally returned, dependent to device and port
2684     parameter)
2685     </p>
2686     </blockquote>
2687    
2688     </blockquote>
2689    
2690     <p>The mentioned fields above don't have to be in particular order.
2691     </p>
2692     <p>Example:
2693     </p>
2694     <p></p>
2695     <blockquote class="text">
2696     <p>C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"
2697     </p>
2698     <p>S: "DESCRIPTION: bindings to other ALSA sequencer clients"
2699     </p>
2700     <p>&nbsp;&nbsp;&nbsp;"TYPE: STRING"
2701     </p>
2702     <p>&nbsp;&nbsp;&nbsp;"FIX: false"
2703     </p>
2704     <p>&nbsp;&nbsp;&nbsp;"MULTIPLICITY: true"
2705     </p>
2706     <p>&nbsp;&nbsp;&nbsp;"POSSIBILITIES: '64:0','68:0','68:1'"
2707     </p>
2708     <p>&nbsp;&nbsp;&nbsp;"."
2709     </p>
2710     </blockquote>
2711    
2712 schoenebeck 575 <a name="rfc.section.6.3.13"></a><h4><a name="SET MIDI_INPUT_PORT_PARAMETER">6.3.13</a>&nbsp;Changing settings of MIDI input ports</h4>
2713 senoner 542
2714     <p>Use the following command to alter a specific setting of a MIDI input port:
2715     </p>
2716     <p></p>
2717     <blockquote class="text">
2718     <p>SET MIDI_INPUT_PORT_PARAMETER &lt;device-id&gt; &lt;port&gt; &lt;key&gt;=&lt;value&gt;
2719     </p>
2720     </blockquote>
2721    
2722     <p>Where &lt;device-id&gt; should be replaced by the numerical ID of the
2723 schoenebeck 575 MIDI device as returned by the
2724     <a class="info" href="#CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"<span>Creating a MIDI input device</span></a>
2725     or <a class="info" href="#LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"<span>Getting all created MIDI input device list</span></a>
2726     command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of
2727 senoner 542 the parameter to change and &lt;value&gt; by the new value for this
2728     parameter.
2729     </p>
2730     <p>Possible Answers:
2731     </p>
2732     <p></p>
2733     <blockquote class="text">
2734     <p>"OK" -
2735     </p>
2736     <blockquote class="text">
2737     <p>in case setting was successfully changed
2738     </p>
2739     </blockquote>
2740    
2741     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2742     </p>
2743     <blockquote class="text">
2744     <p>in case setting was changed successfully, but there are
2745     noteworthy issue(s) related, providing an appropriate
2746     warning code and warning message
2747     </p>
2748     </blockquote>
2749    
2750     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2751     </p>
2752     <blockquote class="text">
2753     <p>in case it failed, providing an appropriate error code and error message
2754     </p>
2755     </blockquote>
2756    
2757     </blockquote>
2758    
2759     <p>Example:
2760     </p>
2761     <p></p>
2762     <blockquote class="text">
2763     <p>
2764     </p>
2765     </blockquote>
2766    
2767 schoenebeck 575 <a name="rfc.section.6.4"></a><h4><a name="anchor11">6.4</a>&nbsp;Configuring sampler channels</h4>
2768 senoner 542
2769 schoenebeck 575 <p>The following commands describe how to add and remove sampler channels, associate a
2770     sampler channel with a sampler engine, load instruments and connect sampler channels to
2771     MIDI and audio devices.
2772 senoner 542 </p>
2773 schoenebeck 575 <a name="rfc.section.6.4.1"></a><h4><a name="LOAD INSTRUMENT">6.4.1</a>&nbsp;Loading an instrument</h4>
2774 senoner 542
2775     <p>An instrument file can be loaded and assigned to a sampler channel by one of the following commands:
2776     </p>
2777     <p></p>
2778     <blockquote class="text">
2779     <p>LOAD INSTRUMENT [NON_MODAL] '&lt;filename&gt;' &lt;instr-index&gt; &lt;sampler-channel&gt;
2780     </p>
2781     </blockquote>
2782    
2783     <p>Where &lt;filename&gt; is the name of the instrument file on the
2784     LinuxSampler instance's host system, &lt;instr-index&gt; the index of the
2785     instrument in the instrument file and &lt;sampler-channel> is the
2786     number of the sampler channel the instrument should be assigned to.
2787     Each sampler channel can only have one instrument.
2788     </p>
2789     <p>The difference between regular and NON_MODAL versions of the command
2790     is that the regular command returns OK only after the instrument has been
2791     fully loaded and the channel is ready to be used while NON_MODAL version
2792     returns immediately and a background process is launched to load the instrument
2793     on the channel. The <a class="info" href="#GET CHANNEL INFO">GET CHANNEL INFO<span>Getting sampler channel information</span></a>
2794     command can be used to obtain loading
2795     progress from INSTRUMENT_STATUS field. LOAD command will perform sanity checks
2796     such as making sure that the file could be read and it is of a proper format
2797     and SHOULD return ERR and SHOULD not launch the background process should any
2798     errors be detected at that point.
2799     </p>
2800     <p>Possible Answers:
2801     </p>
2802     <p></p>
2803     <blockquote class="text">
2804     <p>"OK" -
2805     </p>
2806     <blockquote class="text">
2807     <p>in case the instrument was successfully loaded
2808     </p>
2809     </blockquote>
2810    
2811     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2812     </p>
2813     <blockquote class="text">
2814     <p>in case the instrument was loaded successfully, but there
2815     are noteworthy issue(s) related (e.g. Engine doesn't support
2816     one or more patch parameters provided by the loaded
2817     instrument file), providing an appropriate warning code and
2818     warning message
2819     </p>
2820     </blockquote>
2821    
2822     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2823     </p>
2824     <blockquote class="text">
2825     <p>in case it failed, providing an appropriate error code and error message
2826     </p>
2827     </blockquote>
2828    
2829     </blockquote>
2830    
2831     <p>Example:
2832     </p>
2833     <p></p>
2834     <blockquote class="text">
2835     <p>
2836     </p>
2837     </blockquote>
2838    
2839 schoenebeck 575 <a name="rfc.section.6.4.2"></a><h4><a name="LOAD ENGINE">6.4.2</a>&nbsp;Loading a sampler engine</h4>
2840 senoner 542
2841 schoenebeck 575 <p>A sampler engine type can be associated to a specific sampler
2842 senoner 542 channel by the following command:
2843     </p>
2844     <p></p>
2845     <blockquote class="text">
2846     <p>LOAD ENGINE &lt;engine-name&gt; &lt;sampler-channel&gt;
2847     </p>
2848     </blockquote>
2849    
2850     <p>Where &lt;engine-name&gt; is an engine name as obtained by the
2851 schoenebeck 575 <a class="info" href="#LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"<span>Getting all available engines</span></a> command and &lt;sampler-channel&gt;
2852     the sampler channel as returned by the
2853     <a class="info" href="#ADD CHANNEL">"ADD CHANNEL"<span>Adding a new sampler channel</span></a> or
2854     <a class="info" href="#LIST CHANNELS">"LIST CHANNELS"<span>Getting all created sampler channel list</span></a> command where
2855     the engine type should be assigned to. This command should be issued
2856     after adding a new sampler channel and before any other control
2857     commands on the new sampler channel. It can also be used to change
2858     the engine type of a sampler channel. This command has (currently) no
2859     way to define or force if a new engine instance should be created and
2860     assigned to the given sampler channel or if an already existing
2861     instance of that engine type, shared with other sampler channels,
2862     should be used.
2863 senoner 542 </p>
2864     <p>Possible Answers:
2865     </p>
2866     <p></p>
2867     <blockquote class="text">
2868     <p>"OK" -
2869     </p>
2870     <blockquote class="text">
2871     <p>in case the engine was successfully deployed
2872     </p>
2873     </blockquote>
2874    
2875     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
2876     </p>
2877     <blockquote class="text">
2878     <p>in case the engine was deployed successfully, but there
2879     are noteworthy issue(s) related, providing an appropriate
2880     warning code and warning message
2881     </p>
2882     </blockquote>
2883    
2884     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
2885     </p>
2886     <blockquote class="text">
2887     <p>in case it failed, providing an appropriate error code and
2888     error message
2889     </p>
2890     </blockquote>
2891    
2892     </blockquote>
2893    
2894     <p>Example:
2895     </p>
2896     <p></p>
2897     <blockquote class="text">
2898     <p>
2899     </p>
2900     </blockquote>
2901    
2902 schoenebeck 575 <a name="rfc.section.6.4.3"></a><h4><a name="GET CHANNELS">6.4.3</a>&nbsp;Getting all created sampler channel count</h4>
2903 senoner 542
2904     <p>The number of sampler channels can change on runtime. To get the
2905     current amount of sampler channels, the front-end can send the
2906     following command:
2907     </p>
2908     <p></p>
2909     <blockquote class="text">
2910     <p>GET CHANNELS
2911     </p>
2912     </blockquote>
2913    
2914     <p>Possible Answers:
2915     </p>
2916     <p></p>
2917     <blockquote class="text">
2918     <p>LinuxSampler will answer by returning the current number of sampler channels.
2919     </p>
2920     </blockquote>
2921    
2922     <p>Example:
2923     </p>
2924     <p></p>
2925     <blockquote class="text">
2926     <p>C: "GET CHANNELS"
2927     </p>
2928     <p>S: "12"
2929     </p>
2930     </blockquote>
2931    
2932 schoenebeck 575 <a name="rfc.section.6.4.4"></a><h4><a name="LIST CHANNELS">6.4.4</a>&nbsp;Getting all created sampler channel list</h4>
2933 senoner 542
2934     <p>The number of sampler channels can change on runtime. To get the
2935     current list of sampler channels, the front-end can send the
2936     following command:
2937     </p>
2938     <p></p>
2939     <blockquote class="text">
2940     <p>LIST CHANNELS
2941     </p>
2942     </blockquote>
2943    
2944     <p>Possible Answers:
2945     </p>
2946     <p></p>
2947     <blockquote class="text">
2948     <p>LinuxSampler will answer by returning a comma separated list
2949     with all sampler channels numerical IDs.
2950     </p>
2951     </blockquote>
2952    
2953     <p>Example:
2954     </p>
2955     <p></p>
2956     <blockquote class="text">
2957     <p>C: "LIST CHANNELS"
2958     </p>
2959     <p>S: "0,1,2,3,4,5,6,9,10,11,15,20"
2960     </p>
2961     </blockquote>
2962    
2963 schoenebeck 575 <a name="rfc.section.6.4.5"></a><h4><a name="ADD CHANNEL">6.4.5</a>&nbsp;Adding a new sampler channel</h4>
2964 senoner 542
2965     <p>A new sampler channel can be added to the end of the sampler
2966     channel list by sending the following command:
2967     </p>
2968     <p></p>
2969     <blockquote class="text">
2970     <p>ADD CHANNEL
2971     </p>
2972     </blockquote>
2973    
2974     <p>This will increment the sampler channel count by one and the new
2975     sampler channel will be appended to the end of the sampler channel
2976     list. The front-end should send the respective, related commands
2977     right after to e.g. load an engine, load an instrument and setting
2978     input, output method and eventually other commands to initialize
2979     the new channel. The front-end should use the sampler channel
2980     returned by the answer of this command to perform the previously
2981     recommended commands, to avoid race conditions e.g. with other
2982     front-ends that might also have sent an "ADD CHANNEL" command.
2983     </p>
2984     <p>Possible Answers:
2985     </p>
2986     <p></p>
2987     <blockquote class="text">
2988     <p>"OK[&lt;sampler-channel&gt;]" -
2989     </p>
2990     <blockquote class="text">
2991     <p>in case a new sampler channel could be added, where
2992     &lt;sampler-channel&gt; reflects the channel number of the new
2993 schoenebeck 561 created sampler channel which should be used to set up
2994     the sampler channel by sending subsequent initialization
2995 senoner 542 commands
2996     </p>
2997     </blockquote>
2998    
2999     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3000     </p>
3001     <blockquote class="text">
3002     <p>in case a new channel was added successfully, but there are
3003     noteworthy issue(s) related, providing an appropriate
3004     warning code and warning message
3005     </p>
3006     </blockquote>
3007    
3008     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3009     </p>
3010     <blockquote class="text">
3011     <p>in case it failed, providing an appropriate error code and
3012     error message
3013     </p>
3014     </blockquote>
3015    
3016     </blockquote>
3017    
3018     <p>Example:
3019     </p>
3020     <p></p>
3021     <blockquote class="text">
3022     <p>
3023     </p>
3024     </blockquote>
3025    
3026 schoenebeck 575 <a name="rfc.section.6.4.6"></a><h4><a name="REMOVE CHANNEL">6.4.6</a>&nbsp;Removing a sampler channel</h4>
3027 senoner 542
3028     <p>A sampler channel can be removed by sending the following command:
3029     </p>
3030     <p></p>
3031     <blockquote class="text">
3032     <p>REMOVE CHANNEL &lt;sampler-channel&gt;
3033     </p>
3034     </blockquote>
3035    
3036 schoenebeck 561 <p>Where &lt;sampler-channel&gt; should be replaced by the
3037     number of the sampler channel as given by the
3038     <a class="info" href="#ADD CHANNEL">"ADD CHANNEL"<span>Adding a new sampler channel</span></a>
3039     or <a class="info" href="#LIST CHANNELS">"LIST CHANNELS"<span>Getting all created sampler channel list</span></a>
3040     command. The channel numbers of all subsequent sampler channels
3041     remain the same.
3042 senoner 542 </p>
3043     <p>Possible Answers:
3044     </p>
3045     <p></p>
3046     <blockquote class="text">
3047     <p>"OK" -
3048     </p>
3049     <blockquote class="text">
3050     <p>in case the given sampler channel could be removed
3051     </p>
3052     </blockquote>
3053    
3054     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3055     </p>
3056     <blockquote class="text">
3057     <p>in case the given channel was removed, but there are
3058     noteworthy issue(s) related, providing an appropriate
3059     warning code and warning message
3060     </p>
3061     </blockquote>
3062    
3063     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3064     </p>
3065     <blockquote class="text">
3066     <p>in case it failed, providing an appropriate error code and
3067     error message
3068     </p>
3069     </blockquote>
3070    
3071     </blockquote>
3072    
3073     <p>Example:
3074     </p>
3075     <p></p>
3076     <blockquote class="text">
3077     <p>
3078     </p>
3079     </blockquote>
3080    
3081 schoenebeck 575 <a name="rfc.section.6.4.7"></a><h4><a name="GET AVAILABLE_ENGINES">6.4.7</a>&nbsp;Getting amount of available engines</h4>
3082 senoner 542
3083     <p>The front-end can ask for the number of available engines by sending the following command:
3084     </p>
3085     <p></p>
3086     <blockquote class="text">
3087     <p>GET AVAILABLE_ENGINES
3088     </p>
3089     </blockquote>
3090    
3091     <p>Possible Answers:
3092     </p>
3093     <p></p>
3094     <blockquote class="text">
3095     <p>LinuxSampler will answer by sending the number of available engines.
3096     </p>
3097     </blockquote>
3098    
3099     <p>Example:
3100     </p>
3101     <p></p>
3102     <blockquote class="text">
3103     <p>C: "GET AVAILABLE_ENGINES"
3104     </p>
3105     <p>S: "4"
3106     </p>
3107     </blockquote>
3108    
3109 schoenebeck 575 <a name="rfc.section.6.4.8"></a><h4><a name="LIST AVAILABLE_ENGINES">6.4.8</a>&nbsp;Getting all available engines</h4>
3110 senoner 542
3111     <p>The front-end can ask for a list of all available engines by sending the following command:
3112     </p>
3113     <p></p>
3114     <blockquote class="text">
3115     <p>LIST AVAILABLE_ENGINES
3116     </p>
3117     </blockquote>
3118    
3119     <p>Possible Answers:
3120     </p>
3121     <p></p>
3122     <blockquote class="text">
3123 schoenebeck 561 <p>LinuxSampler will answer by sending a comma separated list
3124     of the engines' names encapsulated into apostrophes (').
3125     Engine names can consist of lower and upper cases,
3126     digits and underlines ("_" character).
3127 senoner 542 </p>
3128     </blockquote>
3129    
3130     <p>Example:
3131     </p>
3132     <p></p>
3133     <blockquote class="text">
3134     <p>C: "LIST AVAILABLE_ENGINES"
3135     </p>
3136 schoenebeck 561 <p>S: "'GigEngine','AkaiEngine','DLSEngine','JoesCustomEngine'"
3137 senoner 542 </p>
3138     </blockquote>
3139    
3140 schoenebeck 575 <a name="rfc.section.6.4.9"></a><h4><a name="GET ENGINE INFO">6.4.9</a>&nbsp;Getting information about an engine</h4>
3141 senoner 542
3142     <p>The front-end can ask for information about a specific engine by
3143     sending the following command:
3144     </p>
3145     <p></p>
3146     <blockquote class="text">
3147     <p>GET ENGINE INFO &lt;engine-name&gt;
3148     </p>
3149     </blockquote>
3150    
3151     <p>Where &lt;engine-name&gt; is an engine name as obtained by the
3152     <a class="info" href="#LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"<span>Getting all available engines</span></a> command.
3153     </p>
3154     <p>Possible Answers:
3155     </p>
3156     <p></p>
3157     <blockquote class="text">
3158     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3159     Each answer line begins with the information category name
3160     followed by a colon and then a space character &lt;SP&gt; and finally
3161     the info character string to that info category. At the moment
3162     the following categories are defined:
3163     </p>
3164     <p></p>
3165     <blockquote class="text">
3166     <p>DESCRIPTION -
3167     </p>
3168     <blockquote class="text">
3169     <p>arbitrary description text about the engine
3170     </p>
3171     </blockquote>
3172    
3173     <p>VERSION -
3174     </p>
3175     <blockquote class="text">
3176     <p>arbitrary character string regarding the engine's version
3177     </p>
3178     </blockquote>
3179    
3180     </blockquote>
3181    
3182     </blockquote>
3183    
3184     <p>The mentioned fields above don't have to be in particular order.
3185     </p>
3186     <p>Example:
3187     </p>
3188     <p></p>
3189     <blockquote class="text">
3190     <p>C: "GET ENGINE INFO JoesCustomEngine"
3191     </p>
3192     <p>S: "DESCRIPTION: this is Joe's custom sampler engine"
3193     </p>
3194     <p>&nbsp;&nbsp;&nbsp;"VERSION: testing-1.0"
3195     </p>
3196     <p>&nbsp;&nbsp;&nbsp;"."
3197     </p>
3198     </blockquote>
3199    
3200 schoenebeck 575 <a name="rfc.section.6.4.10"></a><h4><a name="GET CHANNEL INFO">6.4.10</a>&nbsp;Getting sampler channel information</h4>
3201 senoner 542
3202     <p>The front-end can ask for the current settings of a sampler channel
3203     by sending the following command:
3204     </p>
3205     <p></p>
3206     <blockquote class="text">
3207     <p>GET CHANNEL INFO &lt;sampler-channel&gt;
3208     </p>
3209     </blockquote>
3210    
3211 schoenebeck 575 <p>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
3212     as returned by the <a class="info" href="#ADD CHANNEL">"ADD CHANNEL"<span>Adding a new sampler channel</span></a>
3213     or <a class="info" href="#LIST CHANNELS">"LIST CHANNELS"<span>Getting all created sampler channel list</span></a> command.
3214 senoner 542 </p>
3215     <p>Possible Answers:
3216     </p>
3217     <p></p>
3218     <blockquote class="text">
3219     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
3220     Each answer line begins with the settings category name
3221     followed by a colon and then a space character &lt;SP&gt; and finally
3222     the info character string to that setting category. At the
3223     moment the following categories are defined:
3224     </p>
3225     <p></p>
3226     <blockquote class="text">
3227     <p>ENGINE_NAME -
3228     </p>
3229     <blockquote class="text">
3230 schoenebeck 575 <p>name of the engine that is associated with the sampler
3231     channel, "NONE" if there's no engine associated yet for
3232 senoner 542 this sampler channel
3233     </p>
3234     </blockquote>
3235    
3236     <p>AUDIO_OUTPUT_DEVICE -
3237     </p>
3238     <blockquote class="text">
3239     <p>numerical ID of the audio output device which is
3240     currently connected to this sampler channel to output
3241     the audio signal, "NONE" if there's no device
3242     connected to this sampler channel
3243     </p>
3244     </blockquote>
3245    
3246     <p>AUDIO_OUTPUT_CHANNELS -
3247     </p>
3248     <blockquote class="text">
3249     <p>number of output channels the sampler channel offers
3250     (dependent to used sampler engine and loaded instrument)
3251     </p>
3252     </blockquote>
3253    
3254     <p>AUDIO_OUTPUT_ROUTING -
3255     </p>
3256     <blockquote class="text">
3257     <p>comma separated list which reflects to which audio
3258     channel of the selected audio output device each
3259     sampler output channel is routed to, e.g. "0,3" would
3260     mean the engine's output channel 0 is routed to channel
3261     0 of the audio output device and the engine's output
3262     channel 1 is routed to the channel 3 of the audio
3263     output device
3264     </p>
3265     </blockquote>
3266    
3267     <p>INSTRUMENT_FILE -
3268     </p>
3269     <blockquote class="text">
3270     <p>the file name of the loaded instrument, "NONE" if
3271     there's no instrument yet loaded for this sampler
3272     channel
3273     </p>
3274     </blockquote>
3275    
3276     <p>INSTRUMENT_NR -
3277     </p>
3278     <blockquote class="text">
3279     <p>the instrument index number of the loaded instrument
3280     </p>
3281     </blockquote>
3282    
3283     <p>INSTRUMENT_NAME -
3284     </p>
3285     <blockquote class="text">
3286     <p>the instrument name of the loaded instrument
3287     </p>
3288     </blockquote>
3289    
3290     <p>INSTRUMENT_STATUS -
3291     </p>
3292     <blockquote class="text">
3293     <p>integer values 0 to 100 indicating loading progress percentage for the instrument. Negative
3294     value indicates a loading exception. Value of 100 indicates that the instrument is fully
3295     loaded.
3296     </p>
3297     </blockquote>
3298    
3299     <p>MIDI_INPUT_DEVICE -
3300     </p>
3301     <blockquote class="text">
3302     <p>numerical ID of the MIDI input device which is
3303     currently connected to this sampler channel to deliver
3304     MIDI input commands, "NONE" if there's no device
3305     connected to this sampler channel
3306     </p>
3307     </blockquote>
3308    
3309     <p>MIDI_INPUT_PORT -
3310     </p>
3311     <blockquote class="text">
3312     <p>port number of the MIDI input device
3313     </p>
3314     </blockquote>
3315    
3316     <p>MIDI_INPUT_CHANNEL -
3317     </p>
3318     <blockquote class="text">
3319     <p>the MIDI input channel number this sampler channel
3320     should listen to or "ALL" to listen on all MIDI channels
3321     </p>
3322     </blockquote>
3323    
3324     <p>VOLUME -
3325     </p>
3326     <blockquote class="text">
3327     <p>optionally dotted number for the channel volume factor
3328     (where a value < 1.0 means attenuation and a value >
3329     1.0 means amplification)
3330     </p>
3331     </blockquote>
3332    
3333     </blockquote>
3334    
3335     </blockquote>
3336    
3337     <p>The mentioned fields above don't have to be in particular order.
3338     </p>
3339     <p>Example:
3340     </p>
3341     <p></p>
3342     <blockquote class="text">
3343     <p>C: "GET CHANNEL INFO 34"
3344     </p>
3345     <p>S: "ENGINE_NAME: GigEngine"
3346     </p>
3347     <p>&nbsp;&nbsp;&nbsp;"VOLUME: 1.0"
3348     </p>
3349     <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_DEVICE: 0"
3350     </p>
3351     <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_CHANNELS: 2"
3352     </p>
3353     <p>&nbsp;&nbsp;&nbsp;"AUDIO_OUTPUT_ROUTING: 0,1"
3354     </p>
3355     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"
3356     </p>
3357     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NR: 0"
3358     </p>
3359     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_NAME: Fazioli Piano"
3360     </p>
3361     <p>&nbsp;&nbsp;&nbsp;"INSTRUMENT_STATUS: 100"
3362     </p>
3363     <p>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_DEVICE: 0"
3364     </p>
3365     <p>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_PORT: 0"
3366     </p>
3367     <p>&nbsp;&nbsp;&nbsp;"MIDI_INPUT_CHANNEL: 5"
3368     </p>
3369     <p>&nbsp;&nbsp;&nbsp;"."
3370     </p>
3371     </blockquote>
3372    
3373 schoenebeck 575 <a name="rfc.section.6.4.11"></a><h4><a name="GET CHANNEL VOICE_COUNT">6.4.11</a>&nbsp;Current number of active voices</h4>
3374 senoner 542
3375     <p>The front-end can ask for the current number of active voices on a
3376     sampler channel by sending the following command:
3377     </p>
3378     <p></p>
3379     <blockquote class="text">
3380     <p>GET CHANNEL VOICE_COUNT &lt;sampler-channel&gt;
3381     </p>
3382     </blockquote>
3383    
3384 schoenebeck 575 <p>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
3385     as returned by the <a class="info" href="#ADD CHANNEL">"ADD CHANNEL"<span>Adding a new sampler channel</span></a>
3386     or <a class="info" href="#LIST CHANNELS">"LIST CHANNELS"<span>Getting all created sampler channel list</span></a> command.
3387 senoner 542 </p>
3388     <p>Possible Answers:
3389     </p>
3390     <p></p>
3391     <blockquote class="text">
3392     <p>LinuxSampler will answer by returning the number of active
3393     voices on that channel.
3394     </p>
3395     </blockquote>
3396    
3397     <p>Example:
3398     </p>
3399     <p></p>
3400     <blockquote class="text">
3401     <p>
3402     </p>
3403     </blockquote>
3404    
3405 schoenebeck 575 <a name="rfc.section.6.4.12"></a><h4><a name="GET CHANNEL STREAM_COUNT">6.4.12</a>&nbsp;Current number of active disk streams</h4>
3406 senoner 542
3407     <p>The front-end can ask for the current number of active disk streams
3408     on a sampler channel by sending the following command:
3409     </p>
3410     <p></p>
3411     <blockquote class="text">
3412     <p>GET CHANNEL STREAM_COUNT &lt;sampler-channel&gt;
3413     </p>
3414     </blockquote>
3415    
3416 schoenebeck 575 <p>Where &lt;sampler-channel&gt; is the sampler channel number the front-end is interested in
3417     as returned by the <a class="info" href="#ADD CHANNEL">"ADD CHANNEL"<span>Adding a new sampler channel</span></a>
3418     or <a class="info" href="#LIST CHANNELS">"LIST CHANNELS"<span>Getting all created sampler channel list</span></a> command.
3419 senoner 542 </p>
3420     <p>Possible Answers:
3421     </p>
3422     <p></p>
3423     <blockquote class="text">
3424     <p>LinuxSampler will answer by returning the number of active
3425     disk streams on that channel in case the engine supports disk
3426     streaming, if the engine doesn't support disk streaming it will
3427     return "NA" for not available.
3428     </p>
3429     </blockquote>
3430    
3431     <p>Example:
3432     </p>
3433     <p></p>
3434     <blockquote class="text">
3435     <p>
3436     </p>
3437     </blockquote>
3438    
3439 schoenebeck 575 <a name="rfc.section.6.4.13"></a><h4><a name="GET CHANNEL BUFFER_FILL">6.4.13</a>&nbsp;Current fill state of disk stream buffers</h4>
3440 senoner 542
3441     <p>The front-end can ask for the current fill state of all disk streams
3442     on a sampler channel by sending the following command:
3443     </p>
3444     <p></p>
3445     <blockquote class="text">
3446     <p>GET CHANNEL BUFFER_FILL BYTES &lt;sampler-channel&gt;
3447     </p>
3448     </blockquote>
3449    
3450     <p>to get the fill state in bytes or
3451     </p>
3452     <p></p>
3453     <blockquote class="text">
3454     <p>GET CHANNEL BUFFER_FILL PERCENTAGE &lt;sampler-channel&gt;
3455     </p>
3456     </blockquote>
3457    
3458     <p>to get the fill state in percent, where &lt;sampler-channel&gt; is the
3459 schoenebeck 575 sampler channel number the front-end is interested in
3460     as returned by the <a class="info" href="#ADD CHANNEL">"ADD CHANNEL"<span>Adding a new sampler channel</span></a>
3461     or <a class="info" href="#LIST CHANNELS">"LIST CHANNELS"<span>Getting all created sampler channel list</span></a> command.
3462 senoner 542 </p>
3463     <p>Possible Answers:
3464     </p>
3465     <p></p>
3466     <blockquote class="text">
3467     <p>LinuxSampler will either answer by returning a comma separated
3468     string with the fill state of all disk stream buffers on that
3469     channel or an empty line if there are no active disk streams or
3470     "NA" for *not available* in case the engine which is deployed
3471     doesn't support disk streaming. Each entry in the answer list
3472     will begin with the stream's ID in brackets followed by the
3473     numerical representation of the fill size (either in bytes or
3474     percentage). Note: due to efficiency reasons the fill states in
3475     the response are not in particular order, thus the front-end has
3476     to sort them by itself if necessary.
3477     </p>
3478     </blockquote>
3479    
3480     <p>Examples:
3481     </p>
3482     <p></p>
3483     <blockquote class="text">
3484     <p>C: "GET CHANNEL BUFFER_FILL BYTES 4"
3485     </p>
3486     <p>S: "[115]420500,[116]510300,[75]110000,[120]230700"
3487     </p>
3488     </blockquote>
3489     <blockquote class="text">
3490     <p><p>C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
3491     </p>
3492     <p>S: "[115]90%,[116]98%,[75]40%,[120]62%"
3493     </p>
3494     </blockquote>
3495     <blockquote class="text">
3496     <p><p>C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
3497     </p>
3498     <p>S: ""
3499     </p>
3500     </blockquote>
3501    
3502 schoenebeck 575 <a name="rfc.section.6.4.14"></a><h4><a name="SET CHANNEL AUDIO_OUTPUT_DEVICE">6.4.14</a>&nbsp;Setting audio output device</h4>
3503 senoner 542
3504     <p>The front-end can set the audio output device on a specific sampler
3505     channel by sending the following command:
3506     </p>
3507     <p></p>
3508     <blockquote class="text">
3509     <p>SET CHANNEL AUDIO_OUTPUT_DEVICE &lt;sampler-channel&gt; &lt;audio-device-id&gt;
3510     </p>
3511     </blockquote>
3512    
3513 schoenebeck 575 <p>Where &lt;sampler-channel&gt; is the respective sampler channel
3514     number as returned by the <a class="info" href="#ADD CHANNEL">"ADD CHANNEL"<span>Adding a new sampler channel</span></a>
3515     or <a class="info" href="#LIST CHANNELS">"LIST CHANNELS"<span>Getting all created sampler channel list</span></a> command and
3516     &lt;audio-device-id&gt; is the numerical ID of the audio output device as given by the
3517     <a class="info" href="#CREATE AUDIO_OUTPUT_DEVICE">"CREATE AUDIO_OUTPUT_DEVICE"<span>Creating an audio output device</span></a>
3518     or <a class="info" href="#LIST AUDIO_OUTPUT_DEVICES">"LIST AUDIO_OUTPUT_DEVICES"<span>Getting all created audio output device list</span></a>
3519     command.
3520 senoner 542 </p>
3521     <p>Possible Answers:
3522     </p>
3523     <p></p>
3524     <blockquote class="text">
3525     <p>"OK" -
3526     </p>
3527     <blockquote class="text">
3528     <p>on success
3529     </p>
3530     </blockquote>
3531    
3532     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3533     </p>
3534     <blockquote class="text">
3535     <p>if audio output device was set, but there are noteworthy
3536     issue(s) related, providing an appropriate warning code and
3537     warning message
3538     </p>
3539     </blockquote>
3540    
3541     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3542     </p>
3543     <blockquote class="text">
3544     <p>in case it failed, providing an appropriate error code and error message
3545     </p>
3546     </blockquote>
3547    
3548     </blockquote>
3549    
3550     <p>Examples:
3551     </p>
3552     <p></p>
3553     <blockquote class="text">
3554     <p>
3555     </p>
3556     </blockquote>
3557    
3558 schoenebeck 575 <a name="rfc.section.6.4.15"></a><h4><a name="SET CHANNEL AUDIO_OUTPUT_TYP">6.4.15</a>&nbsp;Setting audio output type</h4>
3559 senoner 542
3560     <p>DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
3561     </p>
3562     <p>The front-end can alter the audio output type on a specific sampler
3563     channel by sending the following command:
3564     </p>
3565     <p></p>
3566     <blockquote class="text">
3567     <p>SET CHANNEL AUDIO_OUTPUT_TYPE &lt;sampler-channel&gt; &lt;audio-output-type&gt;
3568     </p>
3569     </blockquote>
3570    
3571     <p>Where &lt;audio-output-type&gt; is currently either "ALSA" or "JACK" and
3572     &lt;sampler-channel&gt; is the respective sampler channel number.
3573     </p>
3574     <p>Possible Answers:
3575     </p>
3576     <p></p>
3577     <blockquote class="text">
3578     <p>"OK" -
3579     </p>
3580     <blockquote class="text">
3581     <p>on success
3582     </p>
3583     </blockquote>
3584    
3585     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3586     </p>
3587     <blockquote class="text">
3588     <p>if audio output type was set, but there are noteworthy
3589     issue(s) related, providing an appropriate warning code and
3590     warning message
3591     </p>
3592     </blockquote>
3593    
3594     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3595     </p>
3596     <blockquote class="text">
3597     <p>in case it failed, providing an appropriate error code and error message
3598     </p>
3599     </blockquote>
3600    
3601     </blockquote>
3602    
3603     <p>Examples:
3604     </p>
3605     <p></p>
3606     <blockquote class="text">
3607     <p>
3608     </p>
3609     </blockquote>
3610    
3611 schoenebeck 575 <a name="rfc.section.6.4.16"></a><h4><a name="SET CHANNEL AUDIO_OUTPUT_CHANNEL">6.4.16</a>&nbsp;Setting audio output channel</h4>
3612 senoner 542
3613     <p>The front-end can alter the audio output channel on a specific
3614     sampler channel by sending the following command:
3615     </p>
3616     <p></p>
3617     <blockquote class="text">
3618     <p>SET CHANNEL AUDIO_OUTPUT_CHANNEL &lt;sampler-chan&gt; &lt;audio-out&gt; &lt;audio-in&gt;
3619     </p>
3620     </blockquote>
3621    
3622 schoenebeck 575 <p>Where &lt;sampler-chan&gt; is the sampler channel number
3623     as returned by the <a class="info" href="#ADD CHANNEL">"ADD CHANNEL"<span>Adding a new sampler channel</span></a>
3624     or <a class="info" href="#LIST CHANNELS">"LIST CHANNELS"<span>Getting all created sampler channel list</span></a> command, &lt;audio-out&gt; is the
3625 senoner 542 numerical ID of the sampler channel's audio output channel which should be
3626     rerouted and &lt;audio-in&gt; is the numerical ID of the audio channel of the selected audio
3627     output device where &lt;audio-out&gt; should be routed to.
3628     </p>
3629     <p>Possible Answers:
3630     </p>
3631     <p></p>
3632     <blockquote class="text">
3633     <p>"OK" -
3634     </p>
3635     <blockquote class="text">
3636     <p>on success
3637     </p>
3638     </blockquote>
3639    
3640     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3641     </p>
3642     <blockquote class="text">
3643     <p>if audio output channel was set, but there are noteworthy
3644     issue(s) related, providing an appropriate warning code and
3645     warning message
3646     </p>
3647     </blockquote>
3648    
3649     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3650     </p>
3651     <blockquote class="text">
3652     <p>in case it failed, providing an appropriate error code and error message
3653     </p>
3654     </blockquote>
3655    
3656     </blockquote>
3657    
3658     <p>Examples:
3659     </p>
3660     <p></p>
3661     <blockquote class="text">
3662     <p>
3663     </p>
3664     </blockquote>
3665    
3666 schoenebeck 575 <a name="rfc.section.6.4.17"></a><h4><a name="SET CHANNEL MIDI_INPUT_DEVICE">6.4.17</a>&nbsp;Setting MIDI input device</h4>
3667 senoner 542
3668     <p>The front-end can set the MIDI input device on a specific sampler
3669     channel by sending the following command:
3670     </p>
3671     <p></p>
3672     <blockquote class="text">
3673     <p>SET CHANNEL MIDI_INPUT_DEVICE &lt;sampler-channel&gt; &lt;midi-device-id&gt;
3674     </p>
3675     </blockquote>
3676    
3677 schoenebeck 575 <p>Where &lt;sampler-channel&gt; is the sampler channel number
3678     as returned by the <a class="info" href="#ADD CHANNEL">"ADD CHANNEL"<span>Adding a new sampler channel</span></a>
3679     or <a class="info" href="#LIST CHANNELS">"LIST CHANNELS"<span>Getting all created sampler channel list</span></a> command
3680     and &lt;midi-device-id&gt; is the numerical ID of the MIDI input device as returned by the
3681     <a class="info" href="#CREATE MIDI_INPUT_DEVICE">"CREATE MIDI_INPUT_DEVICE"<span>Creating a MIDI input device</span></a>
3682     or <a class="info" href="#LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"<span>Getting all created MIDI input device list</span></a> command.
3683 senoner 542 </p>
3684     <p>Possible Answers:
3685     </p>
3686     <p></p>
3687     <blockquote class="text">
3688     <p>"OK" -
3689     </p>
3690     <blockquote class="text">
3691     <p>on success
3692     </p>
3693     </blockquote>
3694    
3695     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3696     </p>
3697     <blockquote class="text">
3698     <p>if MIDI input device was set, but there are noteworthy
3699     issue(s) related, providing an appropriate warning code and
3700     warning message
3701     </p>
3702     </blockquote>
3703    
3704     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3705     </p>
3706     <blockquote class="text">
3707     <p>in case it failed, providing an appropriate error code and error message
3708     </p>
3709     </blockquote>
3710    
3711     </blockquote>
3712    
3713     <p>Examples:
3714     </p>
3715     <p></p>
3716     <blockquote class="text">
3717     <p>
3718     </p>
3719     </blockquote>
3720    
3721 schoenebeck 575 <a name="rfc.section.6.4.18"></a><h4><a name="SET CHANNEL MIDI_INPUT_TYPE">6.4.18</a>&nbsp;Setting MIDI input type</h4>
3722 senoner 542
3723     <p>DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
3724     </p>
3725     <p>The front-end can alter the MIDI input type on a specific sampler
3726     channel by sending the following command:
3727     </p>
3728     <p></p>
3729     <blockquote class="text">
3730     <p>SET CHANNEL MIDI_INPUT_TYPE &lt;sampler-channel&gt; &lt;midi-input-type&gt;
3731     </p>
3732     </blockquote>
3733    
3734     <p>Where &lt;midi-input-type&gt; is currently only "ALSA" and
3735     &lt;sampler-channel&gt; is the respective sampler channel number.
3736     </p>
3737     <p>Possible Answers:
3738     </p>
3739     <p></p>
3740     <blockquote class="text">
3741     <p>"OK" -
3742     </p>
3743     <blockquote class="text">
3744     <p>on success
3745     </p>
3746     </blockquote>
3747    
3748     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3749     </p>
3750     <blockquote class="text">
3751     <p>if MIDI input type was set, but there are noteworthy
3752     issue(s) related, providing an appropriate warning code and
3753     warning message
3754     </p>
3755     </blockquote>
3756    
3757     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3758     </p>
3759     <blockquote class="text">
3760     <p>in case it failed, providing an appropriate error code and error message
3761     </p>
3762     </blockquote>
3763    
3764     </blockquote>
3765    
3766     <p>Examples:
3767     </p>
3768     <p></p>
3769     <blockquote class="text">
3770     <p>
3771     </p>
3772     </blockquote>
3773    
3774 schoenebeck 575 <a name="rfc.section.6.4.19"></a><h4><a name="SET CHANNEL MIDI_INPUT_PORT">6.4.19</a>&nbsp;Setting MIDI input port</h4>
3775 senoner 542
3776     <p>The front-end can alter the MIDI input port on a specific sampler
3777     channel by sending the following command:
3778     </p>
3779     <p></p>
3780     <blockquote class="text">
3781     <p>SET CHANNEL MIDI_INPUT_PORT &lt;sampler-channel&gt; &lt;midi-input-port&gt;
3782     </p>
3783     </blockquote>
3784    
3785     <p>Where &lt;midi-input-port&gt; is a MIDI input port number of the
3786     MIDI input device connected to the sampler channel given by
3787     &lt;sampler-channel&gt;.
3788     </p>
3789     <p>Possible Answers:
3790     </p>
3791     <p></p>
3792     <blockquote class="text">
3793     <p>"OK" -
3794     </p>
3795     <blockquote class="text">
3796     <p>on success
3797     </p>
3798     </blockquote>
3799    
3800     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3801     </p>
3802     <blockquote class="text">
3803     <p>if MIDI input port was set, but there are noteworthy
3804     issue(s) related, providing an appropriate warning code and
3805     warning message
3806     </p>
3807     </blockquote>
3808    
3809     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3810     </p>
3811     <blockquote class="text">
3812 schoenebeck 561 <p>in case it failed, providing an appropriate error code and error message
3813 senoner 542 </p>
3814     </blockquote>
3815    
3816     </blockquote>
3817    
3818     <p>Examples:
3819     </p>
3820     <p></p>
3821     <blockquote class="text">
3822     <p>
3823     </p>
3824     </blockquote>
3825    
3826 schoenebeck 575 <a name="rfc.section.6.4.20"></a><h4><a name="SET CHANNEL MIDI_INPUT_CHANNEL">6.4.20</a>&nbsp;Setting MIDI input channel</h4>
3827 senoner 542
3828     <p>The front-end can alter the MIDI channel a sampler channel should
3829     listen to by sending the following command:
3830     </p>
3831     <p></p>
3832     <blockquote class="text">
3833     <p>SET CHANNEL MIDI_INPUT_CHANNEL &lt;sampler-channel&gt; &lt;midi-input-chan&gt;
3834     </p>
3835     </blockquote>
3836    
3837     <p>Where &lt;midi-input-chan&gt; is the number of the new MIDI input channel where
3838     &lt;sampler-channel&gt; should listen to or "ALL" to listen on all 16 MIDI
3839     channels.
3840     </p>
3841     <p>Possible Answers:
3842     </p>
3843     <p></p>
3844     <blockquote class="text">
3845     <p>"OK" -
3846     </p>
3847     <blockquote class="text">
3848     <p>on success
3849     </p>
3850     </blockquote>
3851    
3852     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3853     </p>
3854     <blockquote class="text">
3855     <p>if MIDI input channel was set, but there are noteworthy
3856     issue(s) related, providing an appropriate warning code and
3857     warning message
3858     </p>
3859     </blockquote>
3860    
3861     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3862     </p>
3863     <blockquote class="text">
3864     <p>in case it failed, providing an appropriate error code and error message
3865     </p>
3866     </blockquote>
3867    
3868     </blockquote>
3869    
3870     <p>Examples:
3871     </p>
3872     <p></p>
3873     <blockquote class="text">
3874     <p>
3875     </p>
3876     </blockquote>
3877    
3878 schoenebeck 575 <a name="rfc.section.6.4.21"></a><h4><a name="SET CHANNEL VOLUME">6.4.21</a>&nbsp;Setting channel volume</h4>
3879 senoner 542
3880     <p>The front-end can alter the volume of a sampler channel by sending
3881     the following command:
3882     </p>
3883     <p></p>
3884     <blockquote class="text">
3885     <p>SET CHANNEL VOLUME &lt;sampler-channel&gt; &lt;volume&gt;
3886     </p>
3887     </blockquote>
3888    
3889     <p>Where &lt;volume&gt; is an optionally dotted positive number (a value
3890     smaller than 1.0 means attenuation, whereas a value greater than
3891     1.0 means amplification) and &lt;sampler-channel&gt; defines the sampler
3892     channel where this volume factor should be set.
3893     </p>
3894     <p>Possible Answers:
3895     </p>
3896     <p></p>
3897     <blockquote class="text">
3898     <p>"OK" -
3899     </p>
3900     <blockquote class="text">
3901     <p>on success
3902     </p>
3903     </blockquote>
3904    
3905     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3906     </p>
3907     <blockquote class="text">
3908     <p>if channel volume was set, but there are noteworthy
3909     issue(s) related, providing an appropriate warning code and
3910     warning message
3911     </p>
3912     </blockquote>
3913    
3914     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3915     </p>
3916     <blockquote class="text">
3917     <p>in case it failed, providing an appropriate error code and error message
3918     </p>
3919     </blockquote>
3920    
3921     </blockquote>
3922    
3923     <p>Examples:
3924     </p>
3925     <p></p>
3926     <blockquote class="text">
3927     <p>
3928     </p>
3929     </blockquote>
3930    
3931 schoenebeck 575 <a name="rfc.section.6.4.22"></a><h4><a name="RESET CHANNEL">6.4.22</a>&nbsp;Resetting a sampler channel</h4>
3932 senoner 542
3933     <p>The front-end can reset a particular sampler channel by sending the following command:
3934     </p>
3935     <p></p>
3936     <blockquote class="text">
3937     <p>RESET CHANNEL &lt;sampler-channel&gt;
3938     </p>
3939     </blockquote>
3940    
3941     <p>
3942     Where &lt;sampler-channel&gt; defines the sampler channel to be reset.
3943     This will cause the engine on that sampler channel, its voices and
3944     eventually disk streams and all control and status variables to be
3945     reset.
3946     </p>
3947     <p>Possible Answers:
3948     </p>
3949     <p></p>
3950     <blockquote class="text">
3951     <p>"OK" -
3952     </p>
3953     <blockquote class="text">
3954     <p>on success
3955     </p>
3956     </blockquote>
3957    
3958     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
3959     </p>
3960     <blockquote class="text">
3961     <p>if channel was reset, but there are noteworthy issue(s)
3962     related, providing an appropriate warning code and warning
3963     message
3964     </p>
3965     </blockquote>
3966    
3967     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
3968     </p>
3969     <blockquote class="text">
3970     <p>in case it failed, providing an appropriate error code and
3971     error message
3972     </p>
3973     </blockquote>
3974    
3975     </blockquote>
3976    
3977     <p>Examples:
3978     </p>
3979     <p></p>
3980     <blockquote class="text">
3981     <p>
3982     </p>
3983     </blockquote>
3984    
3985 schoenebeck 575 <a name="rfc.section.6.5"></a><h4><a name="anchor12">6.5</a>&nbsp;Controlling connection</h4>
3986 senoner 542
3987     <p>The following commands are used to control the connection to LinuxSampler.
3988     </p>
3989 schoenebeck 575 <a name="rfc.section.6.5.1"></a><h4><a name="SUBSCRIBE">6.5.1</a>&nbsp;Register front-end for receiving event messages</h4>
3990 senoner 542
3991     <p>The front-end can register itself to the LinuxSampler application to
3992     be informed about noteworthy events by sending this command:
3993     </p>
3994     <p></p>
3995     <blockquote class="text">
3996     <p>SUBSCRIBE &lt;event-id&gt;
3997     </p>
3998     </blockquote>
3999    
4000     <p>where &lt;event-id&gt; will be replaced by the respective event that
4001     client wants to subscribe to.
4002     </p>
4003     <p>Possible Answers:
4004     </p>
4005     <p></p>
4006     <blockquote class="text">
4007     <p>"OK" -
4008     </p>
4009     <blockquote class="text">
4010     <p>on success
4011     </p>
4012     </blockquote>
4013    
4014     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4015     </p>
4016     <blockquote class="text">
4017     <p>if registration succeeded, but there are noteworthy
4018     issue(s) related, providing an appropriate warning code and
4019     warning message
4020     </p>
4021     </blockquote>
4022    
4023     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4024     </p>
4025     <blockquote class="text">
4026     <p>in case it failed, providing an appropriate error code and
4027     error message
4028     </p>
4029     </blockquote>
4030    
4031     </blockquote>
4032    
4033     <p>Examples:
4034     </p>
4035     <p></p>
4036     <blockquote class="text">
4037     <p>
4038     </p>
4039     </blockquote>
4040    
4041 schoenebeck 575 <a name="rfc.section.6.5.2"></a><h4><a name="UNSUBSCRIBE">6.5.2</a>&nbsp;Unregister front-end for not receiving event messages</h4>
4042 senoner 542
4043     <p>The front-end can unregister itself if it doesn't want to receive event
4044     messages anymore by sending the following command:
4045     </p>
4046     <p></p>
4047     <blockquote class="text">
4048     <p>UNSUBSCRIBE &lt;event-id&gt;
4049     </p>
4050     </blockquote>
4051    
4052     <p>Where &lt;event-id&gt; will be replaced by the respective event that
4053     client doesn't want to receive anymore.
4054     </p>
4055     <p>Possible Answers:
4056     </p>
4057     <p></p>
4058     <blockquote class="text">
4059     <p>"OK" -
4060     </p>
4061     <blockquote class="text">
4062     <p>on success
4063     </p>
4064     </blockquote>
4065    
4066     <p>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
4067     </p>
4068     <blockquote class="text">
4069     <p>if unregistration succeeded, but there are noteworthy
4070     issue(s) related, providing an appropriate warning code and
4071     warning message
4072     </p>
4073     </blockquote>
4074    
4075     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4076     </p>
4077     <blockquote class="text">
4078     <p>in case it failed, providing an appropriate error code and
4079     error message
4080     </p>
4081     </blockquote>
4082    
4083     </blockquote>
4084    
4085     <p>Examples:
4086     </p>
4087     <p></p>
4088     <blockquote class="text">
4089     <p>
4090     </p>
4091     </blockquote>
4092    
4093 schoenebeck 575 <a name="rfc.section.6.5.3"></a><h4><a name="SET ECHO">6.5.3</a>&nbsp;Enable or disable echo of commands</h4>
4094 senoner 542
4095     <p>To enable or disable back sending of commands to the client the following command can be used:
4096     </p>
4097     <p></p>
4098     <blockquote class="text">
4099     <p>SET ECHO &lt;value&gt;
4100     </p>
4101     </blockquote>
4102    
4103     <p>Where &lt;value&gt; should be replaced either by "1" to enable echo mode
4104     or "0" to disable echo mode. When echo mode is enabled, all
4105     commands send to LinuxSampler will be immediately send back and
4106     after this echo the actual response to the command will be
4107     returned. Echo mode will only be altered for the client connection
4108     that issued the "SET ECHO" command, not globally for all client
4109     connections.
4110     </p>
4111     <p>Possible Answers:
4112     </p>
4113     <p></p>
4114     <blockquote class="text">
4115     <p>"OK" -
4116     </p>
4117     <blockquote class="text">
4118     <p>usually
4119     </p>
4120     </blockquote>
4121    
4122     <p>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
4123     </p>
4124     <blockquote class="text">
4125     <p>on syntax error, e.g. non boolean value
4126     </p>
4127     </blockquote>
4128    
4129     </blockquote>
4130    
4131     <p>Examples:
4132     </p>
4133     <p></p>
4134     <blockquote class="text">
4135     <p>
4136     </p>
4137     </blockquote>
4138    
4139 schoenebeck 575 <a name="rfc.section.6.5.4"></a><h4><a name="QUIT">6.5.4</a>&nbsp;Close client connection</h4>
4140 senoner 542
4141     <p>The client can close its network connection to LinuxSampler by sending the following command:
4142     </p>
4143     <p></p>
4144     <blockquote class="text">
4145     <p>QUIT
4146     </p>
4147     </blockquote>
4148    
4149     <p>This is probably more interesting for manual telnet connections to
4150     LinuxSampler than really useful for a front-end implementation.
4151     </p>
4152 schoenebeck 575 <a name="rfc.section.6.6"></a><h4><a name="anchor13">6.6</a>&nbsp;Global commands</h4>
4153 senoner 542
4154     <p>The following commands have global impact on the sampler.
4155     </p>
4156 schoenebeck 575 <a name="rfc.section.6.6.1"></a><h4><a name="RESET">6.6.1</a>&nbsp;Reset sampler</h4>
4157 senoner 542
4158     <p>The front-end can reset the whole sampler by sending the following command:
4159     </p>
4160     <p></p>
4161     <blockquote class="text">
4162     <p>RESET
4163     </p>
4164     </blockquote>
4165    
4166     <p>Possible Answers:
4167     </p>
4168     <p></p>
4169     <blockquote class="text">
4170     <p>"OK" -
4171     </p>
4172     <blockquote class="text">
4173     <p>always
4174     </p>
4175     </blockquote>
4176    
4177     </blockquote>
4178    
4179     <p>Examples:
4180     </p>
4181     <p></p>
4182     <blockquote class="text">
4183     <p>
4184     </p>
4185     </blockquote>
4186    
4187 schoenebeck 575 <a name="rfc.section.6.6.2"></a><h4><a name="GET SERVER INFO">6.6.2</a>&nbsp;General sampler informations</h4>
4188    
4189     <p>The client can ask for general informations about the LinuxSampler
4190     instance by sending the following command:
4191     </p>
4192     <p></p>
4193     <blockquote class="text">
4194     <p>GET SERVER INFO
4195     </p>
4196     </blockquote>
4197    
4198     <p>Possible Answers:
4199     </p>
4200     <p></p>
4201     <blockquote class="text">
4202     <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
4203     Each answer line begins with the information category name
4204     followed by a colon and then a space character &lt;SP&gt; and finally
4205     the info character string to that information category. At the
4206     moment the following categories are defined:
4207    
4208     </p>
4209     <p></p>
4210     <blockquote class="text">
4211     <p>DESCRIPTION -
4212     </p>
4213     <blockquote class="text">
4214     <p>arbitrary textual description about the sampler
4215     </p>
4216     </blockquote>
4217    
4218     <p>VERSION -
4219     </p>
4220     <blockquote class="text">
4221     <p>version of the sampler
4222     </p>
4223     </blockquote>
4224    
4225     <p>PROTOCOL_VERSION -
4226     </p>
4227     <blockquote class="text">
4228     <p>version of the LSCP specification the sampler
4229     complies with (see <a class="info" href="#LSCP versioning">Section 2<span>Versioning of this specification</span></a> for details)
4230     </p>
4231     </blockquote>
4232    
4233     </blockquote>
4234    
4235     </blockquote>
4236    
4237     <p>The mentioned fields above don't have to be in particular order.
4238     Other fields might be added in future.
4239     </p>
4240 senoner 542 <a name="command_syntax"></a><br /><hr />
4241     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
4242 schoenebeck 575 <a name="rfc.section.7"></a><h3>7.&nbsp;Command Syntax</h3>
4243 senoner 542
4244 schoenebeck 575 <p>The grammar of the control protocol as descibed in <a class="info" href="#control_commands">Section 6<span>Description for control commands</span></a>
4245     is defined below using Backus-Naur Form (BNF as described in <a class="info" href="#RFC2234">[RFC2234]<span>Crocker, D. and P. Overell, Augmented BNF for Syntax Specifications, 1997.</span></a>)
4246     where applicable.
4247    
4248 senoner 542 </p>
4249 schoenebeck 575 <p>input =
4250     </p>
4251     <blockquote class="text">
4252     <p>line LF
4253    
4254     </p>
4255     <p>/ line CR LF
4256    
4257     </p>
4258     </blockquote>
4259    
4260     <p>line =
4261     </p>
4262     <blockquote class="text">
4263     <p>/* epsilon (empty line ignored) */
4264    
4265     </p>
4266     <p>/ comment
4267    
4268     </p>
4269     <p>/ command
4270    
4271     </p>
4272     <p>/ error
4273    
4274     </p>
4275     </blockquote>
4276    
4277     <p>comment =
4278     </p>
4279     <blockquote class="text">
4280     <p>'#'
4281    
4282     </p>
4283     <p>/ comment '#'
4284    
4285     </p>
4286     <p>/ comment SP
4287    
4288     </p>
4289     <p>/ comment number
4290    
4291     </p>
4292     <p>/ comment string
4293    
4294     </p>
4295     </blockquote>
4296    
4297     <p>command =
4298     </p>
4299     <blockquote class="text">
4300     <p>ADD SP CHANNEL
4301    
4302     </p>
4303     <p>/ GET SP get_instruction
4304    
4305     </p>
4306     <p>/ CREATE SP create_instruction
4307    
4308     </p>
4309     <p>/ DESTROY SP destroy_instruction
4310    
4311     </p>
4312     <p>/ LIST SP list_instruction
4313    
4314     </p>
4315     <p>/ LOAD SP load_instruction
4316    
4317     </p>
4318     <p>/ REMOVE SP CHANNEL SP sampler_channel
4319    
4320     </p>
4321     <p>/ SET SP set_instruction
4322    
4323     </p>
4324     <p>/ SUBSCRIBE SP subscribe_event
4325    
4326     </p>
4327     <p>/ UNSUBSCRIBE SP unsubscribe_event
4328    
4329     </p>
4330     <p>/ SELECT SP text
4331    
4332     </p>
4333     <p>/ RESET SP CHANNEL SP sampler_channel
4334    
4335     </p>
4336     <p>/ RESET
4337    
4338     </p>
4339     <p>/ QUIT
4340    
4341     </p>
4342     </blockquote>
4343    
4344     <p>subscribe_event =
4345     </p>
4346     <blockquote class="text">
4347     <p>CHANNEL_COUNT
4348    
4349     </p>
4350     <p>/ VOICE_COUNT
4351    
4352     </p>
4353     <p>/ STREAM_COUNT
4354    
4355     </p>
4356     <p>/ BUFFER_FILL
4357    
4358     </p>
4359     <p>/ CHANNEL_INFO
4360    
4361     </p>
4362     <p>/ MISCELLANEOUS
4363    
4364     </p>
4365     </blockquote>
4366    
4367     <p>unsubscribe_event =
4368     </p>
4369     <blockquote class="text">
4370     <p>CHANNEL_COUNT
4371    
4372     </p>
4373     <p>/ VOICE_COUNT
4374    
4375     </p>
4376     <p>/ STREAM_COUNT
4377    
4378     </p>
4379     <p>/ BUFFER_FILL
4380    
4381     </p>
4382     <p>/ CHANNEL_INFO
4383    
4384     </p>
4385     <p>/ MISCELLANEOUS
4386    
4387     </p>
4388     </blockquote>
4389    
4390     <p>get_instruction =
4391     </p>
4392     <blockquote class="text">
4393     <p>AVAILABLE_ENGINES
4394    
4395     </p>
4396     <p>/ AVAILABLE_MIDI_INPUT_DRIVERS
4397    
4398     </p>
4399     <p>/ MIDI_INPUT_DRIVER SP INFO SP string
4400    
4401     </p>
4402     <p>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
4403    
4404     </p>
4405     <p>/ MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
4406    
4407     </p>
4408     <p>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
4409    
4410     </p>
4411     <p>/ AUDIO_OUTPUT_DRIVER SP INFO SP string
4412    
4413     </p>
4414     <p>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
4415    
4416     </p>
4417     <p>/ AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list
4418    
4419     </p>
4420     <p>/ AUDIO_OUTPUT_DEVICES
4421    
4422     </p>
4423     <p>/ MIDI_INPUT_DEVICES
4424    
4425     </p>
4426     <p>/ AUDIO_OUTPUT_DEVICE SP INFO SP number
4427    
4428     </p>
4429     <p>/ MIDI_INPUT_DEVICE SP INFO SP number
4430    
4431     </p>
4432     <p>/ MIDI_INPUT_PORT SP INFO SP number SP number
4433    
4434     </p>
4435     <p>/ MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
4436    
4437     </p>
4438     <p>/ AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
4439    
4440     </p>
4441     <p>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP string
4442    
4443     </p>
4444     <p>/ CHANNELS
4445    
4446     </p>
4447     <p>/ CHANNEL SP INFO SP sampler_channel
4448    
4449     </p>
4450     <p>/ CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
4451    
4452     </p>
4453     <p>/ CHANNEL SP STREAM_COUNT SP sampler_channel
4454    
4455     </p>
4456     <p>/ CHANNEL SP VOICE_COUNT SP sampler_channel
4457    
4458     </p>
4459     <p>/ ENGINE SP INFO SP engine_name
4460    
4461     </p>
4462     <p>/ SERVER SP INFO
4463    
4464     </p>
4465     </blockquote>
4466    
4467     <p>set_instruction =
4468     </p>
4469     <blockquote class="text">
4470     <p>AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
4471    
4472     </p>
4473     <p>/ AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '=' param_val_list
4474    
4475     </p>
4476     <p>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
4477    
4478     </p>
4479     <p>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list
4480    
4481     </p>
4482     <p>/ CHANNEL SP set_chan_instruction
4483    
4484     </p>
4485     <p>/ ECHO SP boolean
4486    
4487     </p>
4488     </blockquote>
4489    
4490     <p>create_instruction =
4491     </p>
4492     <blockquote class="text">
4493     <p>AUDIO_OUTPUT_DEVICE SP string SP key_val_list
4494    
4495     </p>
4496     <p>/ AUDIO_OUTPUT_DEVICE SP string
4497    
4498     </p>
4499     <p>/ MIDI_INPUT_DEVICE SP string SP key_val_list
4500    
4501     </p>
4502     <p>/ MIDI_INPUT_DEVICE SP string
4503    
4504     </p>
4505     </blockquote>
4506    
4507     <p>destroy_instruction =
4508     </p>
4509     <blockquote class="text">
4510     <p>AUDIO_OUTPUT_DEVICE SP number
4511    
4512     </p>
4513     <p>/ MIDI_INPUT_DEVICE SP number
4514    
4515     </p>
4516     </blockquote>
4517    
4518     <p>load_instruction =
4519     </p>
4520     <blockquote class="text">
4521     <p>INSTRUMENT SP load_instr_args
4522    
4523     </p>
4524     <p>/ ENGINE SP load_engine_args
4525    
4526     </p>
4527     </blockquote>
4528    
4529     <p>set_chan_instruction =
4530     </p>
4531     <blockquote class="text">
4532     <p>AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
4533    
4534     </p>
4535     <p>/ AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index SP audio_channel_index
4536    
4537     </p>
4538     <p>/ AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
4539    
4540     </p>
4541     <p>/ MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index SP midi_input_channel_index
4542    
4543     </p>
4544     <p>/ MIDI_INPUT_DEVICE SP sampler_channel SP device_index
4545    
4546     </p>
4547     <p>/ MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
4548    
4549     </p>
4550     <p>/ MIDI_INPUT_CHANNEL SP sampler_channel SP midi_input_channel_index
4551    
4552     </p>
4553     <p>/ MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
4554    
4555     </p>
4556     <p>/ VOLUME SP sampler_channel SP volume_value
4557    
4558     </p>
4559     </blockquote>
4560    
4561     <p>key_val_list =
4562     </p>
4563     <blockquote class="text">
4564     <p>string '=' param_val_list
4565    
4566     </p>
4567     <p>/ key_val_list SP string '=' param_val_list
4568    
4569     </p>
4570     </blockquote>
4571    
4572     <p>buffer_size_type =
4573     </p>
4574     <blockquote class="text">
4575     <p>BYTES
4576    
4577     </p>
4578     <p>/ PERCENTAGE
4579    
4580     </p>
4581     </blockquote>
4582    
4583     <p>list_instruction =
4584     </p>
4585     <blockquote class="text">
4586     <p>AUDIO_OUTPUT_DEVICES
4587    
4588     </p>
4589     <p>/ MIDI_INPUT_DEVICES
4590    
4591     </p>
4592     <p>/ CHANNELS
4593    
4594     </p>
4595     <p>/ AVAILABLE_ENGINES
4596    
4597     </p>
4598     <p>/ AVAILABLE_MIDI_INPUT_DRIVERS
4599    
4600     </p>
4601     <p>/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
4602    
4603     </p>
4604     </blockquote>
4605    
4606     <p>load_instr_args =
4607     </p>
4608     <blockquote class="text">
4609     <p>filename SP instrument_index SP sampler_channel
4610    
4611     </p>
4612     <p>/ NON_MODAL SP filename SP instrument_index SP sampler_channel
4613    
4614     </p>
4615     </blockquote>
4616    
4617     <p>load_engine_args =
4618     </p>
4619     <blockquote class="text">
4620     <p>engine_name SP sampler_channel
4621    
4622     </p>
4623     </blockquote>
4624    
4625     <p>device_index =
4626     </p>
4627     <blockquote class="text">
4628     <p>number
4629    
4630     </p>
4631     </blockquote>
4632    
4633     <p>audio_channel_index =
4634     </p>
4635     <blockquote class="text">
4636     <p>number
4637    
4638     </p>
4639     </blockquote>
4640    
4641     <p>audio_output_type_name =
4642     </p>
4643     <blockquote class="text">
4644     <p>string
4645    
4646     </p>
4647     </blockquote>
4648    
4649     <p>midi_input_port_index =
4650     </p>
4651     <blockquote class="text">
4652     <p>number
4653    
4654     </p>
4655     </blockquote>
4656    
4657     <p>midi_input_channel_index =
4658     </p>
4659     <blockquote class="text">
4660     <p>number
4661    
4662     </p>
4663     <p>/ ALL
4664    
4665     </p>
4666     </blockquote>
4667    
4668     <p>midi_input_type_name =
4669     </p>
4670     <blockquote class="text">
4671     <p>string
4672    
4673     </p>
4674     </blockquote>
4675    
4676     <p>volume_value =
4677     </p>
4678     <blockquote class="text">
4679     <p>dotnum
4680    
4681     </p>
4682     <p>/ number
4683    
4684     </p>
4685     </blockquote>
4686    
4687     <p>sampler_channel =
4688     </p>
4689     <blockquote class="text">
4690     <p>number
4691    
4692     </p>
4693     </blockquote>
4694    
4695     <p>instrument_index =
4696     </p>
4697     <blockquote class="text">
4698     <p>number
4699    
4700     </p>
4701     </blockquote>
4702    
4703     <p>engine_name =
4704     </p>
4705     <blockquote class="text">
4706     <p>string
4707    
4708     </p>
4709     </blockquote>
4710    
4711     <p>filename =
4712     </p>
4713     <blockquote class="text">
4714     <p>stringval
4715    
4716     </p>
4717     </blockquote>
4718    
4719     <p>param_val_list =
4720     </p>
4721     <blockquote class="text">
4722     <p>param_val
4723    
4724     </p>
4725     <p>/ param_val_list','param_val
4726    
4727     </p>
4728     </blockquote>
4729    
4730     <p>param_val =
4731     </p>
4732     <blockquote class="text">
4733     <p>string
4734    
4735     </p>
4736     <p>/ '\'' string '\''
4737    
4738     </p>
4739     <p>/ '\"' string '\"'
4740    
4741     </p>
4742     <p>/ number
4743    
4744     </p>
4745     <p>/ dotnum
4746    
4747     </p>
4748     </blockquote>
4749    
4750 senoner 542 <a name="events"></a><br /><hr />
4751     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
4752 schoenebeck 575 <a name="rfc.section.8"></a><h3>8.&nbsp;Events</h3>
4753 senoner 542
4754     <p>This chapter will describe all currently defined events supported by LinuxSampler.
4755     </p>
4756 schoenebeck 575 <a name="rfc.section.8.1"></a><h4><a name="SUBSCRIBE CHANNEL">8.1</a>&nbsp;Number of sampler channels changed</h4>
4757 senoner 542
4758     <p>Client may want to be notified when the total number of channels on the
4759     back-end changes by issuing the following command:
4760     </p>
4761     <p></p>
4762     <blockquote class="text">
4763 schoenebeck 558 <p>SUBSCRIBE CHANNEL_COUNT
4764 senoner 542 </p>
4765     </blockquote>
4766    
4767     <p>Server will start sending the following notification messages:
4768     </p>
4769     <p></p>
4770     <blockquote class="text">
4771 schoenebeck 558 <p>"NOTIFY:CHANNEL_COUNT:&lt;channels&gt;"
4772 senoner 542 </p>
4773     </blockquote>
4774    
4775     <p>where &lt;channels&gt; will be replaced by the new number
4776     of sampler channels.
4777     </p>
4778 schoenebeck 575 <a name="rfc.section.8.2"></a><h4><a name="SUBSCRIBE VOICE_COUNT">8.2</a>&nbsp;Number of active voices changed</h4>
4779 senoner 542
4780     <p>Client may want to be notified when the number of voices on the
4781     back-end changes by issuing the following command:
4782     </p>
4783     <p></p>
4784     <blockquote class="text">
4785     <p>SUBSCRIBE VOICE_COUNT
4786     </p>
4787     </blockquote>
4788    
4789     <p>Server will start sending the following notification messages:
4790     </p>
4791     <p></p>
4792     <blockquote class="text">
4793     <p>"NOTIFY:VOICE_COUNT:&lt;sampler-channel&gt; &lt;voices&gt;
4794     </p>
4795     </blockquote>
4796    
4797     <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
4798     voice count change occurred and &lt;voices&gt; by the new number of
4799     active voices on that channel.
4800     </p>
4801 schoenebeck 575 <a name="rfc.section.8.3"></a><h4><a name="SUBSCRIBE STREAM_COUNT">8.3</a>&nbsp;Number of active disk streams changed</h4>
4802 senoner 542
4803     <p>Client may want to be notified when the number of streams on the back-end
4804     changes by issuing the following command: SUBSCRIBE STREAM_COUNT
4805     </p>
4806     <p></p>
4807     <blockquote class="text">
4808     <p>SUBSCRIBE STREAM_COUNT
4809     </p>
4810     </blockquote>
4811    
4812     <p>Server will start sending the following notification messages:
4813     </p>
4814     <p></p>
4815     <blockquote class="text">
4816     <p>"NOTIFY:STREAM_COUNT:&lt;sampler-channel&gt; &lt;streams&gt;"
4817     </p>
4818     </blockquote>
4819    
4820     <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
4821     stream count change occurred and &lt;streams&gt; by the new number of
4822     active disk streams on that channel.
4823     </p>
4824 schoenebeck 575 <a name="rfc.section.8.4"></a><h4><a name="SUBSCRIBE BUFFER_FILL">8.4</a>&nbsp;Disk stream buffer fill state changed</h4>
4825 senoner 542
4826     <p>Client may want to be notified when the buffer fill state of a disk stream
4827     on the back-end changes by issuing the following command:
4828     </p>
4829     <p></p>
4830     <blockquote class="text">
4831     <p>SUBSCRIBE BUFFER_FILL
4832     </p>
4833     </blockquote>
4834    
4835     <p>Server will start sending the following notification messages:
4836     </p>
4837     <p></p>
4838     <blockquote class="text">
4839     <p>"NOTIFY:BUFFER_FILL:&lt;sampler-channel&gt; &lt;fill-data&gt;"
4840     </p>
4841     </blockquote>
4842    
4843     <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
4844     buffer fill state change occurred on and &lt;fill-data&gt; will be replaced by the
4845 schoenebeck 575 buffer fill data for this channel as described in <a class="info" href="#GET CHANNEL BUFFER_FILL">Section 6.4.13<span>Current fill state of disk stream buffers</span></a>
4846 senoner 542 as if the <a class="info" href="#GET CHANNEL BUFFER_FILL">"GET CHANNEL BUFFER_FILL PERCENTAGE"<span>Current fill state of disk stream buffers</span></a> command was issued on this channel.
4847     </p>
4848 schoenebeck 575 <a name="rfc.section.8.5"></a><h4><a name="SUBSCRIBE INFO">8.5</a>&nbsp;Channel information changed</h4>
4849 senoner 542
4850     <p>Client may want to be notified when changes were made to sampler channels on the
4851 schoenebeck 561 back-end by issuing the following command:
4852 senoner 542 </p>
4853     <p></p>
4854     <blockquote class="text">
4855 schoenebeck 558 <p>SUBSCRIBE CHANNEL_INFO
4856 senoner 542 </p>
4857     </blockquote>
4858    
4859     <p>Server will start sending the following notification messages:
4860     </p>
4861     <p></p>
4862     <blockquote class="text">
4863 schoenebeck 558 <p>"NOTIFY:CHANNEL_INFO:&lt;sampler-channel&gt;"
4864 senoner 542 </p>
4865     </blockquote>
4866    
4867     <p>where &lt;sampler-channel&gt; will be replaced by the sampler channel the
4868     channel info change occurred. The front-end will have to send
4869     the respective command to actually get the channel info. Because these messages
4870     will be triggered by LSCP commands issued by other clients rather than real
4871     time events happening on the server, it is believed that an empty notification
4872     message is sufficient here.
4873     </p>
4874 schoenebeck 575 <a name="rfc.section.8.6"></a><h4><a name="SUBSCRIBE MISCELLANEOUS">8.6</a>&nbsp;Miscellaneous and debugging events</h4>
4875 senoner 542
4876     <p>Client may want to be notified of miscellaneous and debugging events occurring at
4877     the server by issuing the following command:
4878     </p>
4879     <p></p>
4880     <blockquote class="text">
4881     <p>SUBSCRIBE MISCELLANEOUS
4882     </p>
4883     </blockquote>
4884    
4885     <p>Server will start sending the following notification messages:
4886     </p>
4887     <p></p>
4888     <blockquote class="text">
4889     <p>"NOTIFY:MISCELLANEOUS:&lt;string&gt;"
4890     </p>
4891     </blockquote>
4892    
4893     <p>where &lt;string&gt; will be replaced by whatever data server
4894     wants to send to the client. Client MAY display this data to the
4895     user AS IS to facilitate debugging.
4896     </p>
4897 schoenebeck 575 <a name="anchor14"></a><br /><hr />
4898 senoner 542 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
4899 schoenebeck 575 <a name="rfc.section.9"></a><h3>9.&nbsp;Security Considerations</h3>
4900 senoner 542
4901     <p>As there is so far no method of authentication and authorization
4902     defined and so not required for a client applications to succeed to
4903     connect, running LinuxSampler might be a security risk for the host
4904     system the LinuxSampler instance is running on.
4905     </p>
4906 schoenebeck 575 <a name="anchor15"></a><br /><hr />
4907 senoner 542 <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
4908 schoenebeck 575 <a name="rfc.section.10"></a><h3>10.&nbsp;Acknowledgments</h3>
4909 senoner 542
4910     <p>This document has benefited greatly from the comments of the
4911     following people, discussed on the LinuxSampler developer's mailing
4912     list:
4913     </p>
4914     <p></p>
4915     <blockquote class="text">
4916     <p>Rui Nuno Capela
4917     </p>
4918     <p>Vladimir Senkov
4919     </p>
4920     <p>Mark Knecht
4921     </p>
4922 schoenebeck 561 <p>Grigor Iliev
4923     </p>
4924 senoner 542 </blockquote>
4925    
4926     <a name="rfc.references1"></a><br /><hr />
4927     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
4928 schoenebeck 575 <h3>11&nbsp;References</h3>
4929 senoner 542 <table width="99%" border="0">
4930     <tr><td class="author-text" valign="top"><a name="RFC2119">[RFC2119]</a></td>
4931 schoenebeck 575 <td class="author-text">Bradner, S., "<a href="ftp://ftp.isi.edu/in-notes/rfc2119.txt">Key words for use in RFCs to Indicate Requirement Levels</a>", RFC 2119, 1997.</td></tr>
4932     <tr><td class="author-text" valign="top"><a name="RFC2234">[RFC2234]</a></td>
4933     <td class="author-text">Crocker, D. and P. Overell, "<a href="ftp://ftp.isi.edu/in-notes/rfc2234.txt">Augmented BNF for Syntax Specifications</a>", RFC 2234, 1997.</td></tr>
4934     <tr><td class="author-text" valign="top"><a name="RFC793">[RFC793]</a></td>
4935     <td class="author-text">Defense Advanced Research Projects Agency, "<a href="ftp://ftp.isi.edu/in-notes/rfc793.txt">TRANSMISSION CONTROL PROTOCOL</a>", RFC 793, 1981.</td></tr>
4936 senoner 542 </table>
4937    
4938     <a name="rfc.authors"></a><br /><hr />
4939     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
4940     <h3>Author's Address</h3>
4941     <table width="99%" border="0" cellpadding="0" cellspacing="0">
4942     <tr><td class="author-text">&nbsp;</td>
4943     <td class="author-text">C.
4944     Schoenebeck</td></tr>
4945     <tr><td class="author-text">&nbsp;</td>
4946     <td class="author-text">Interessengemeinschaft Software Engineering e. V.</td></tr>
4947     <tr><td class="author-text">&nbsp;</td>
4948     <td class="author-text">Max-Planck-Str. 39</td></tr>
4949     <tr><td class="author-text">&nbsp;</td>
4950     <td class="author-text">74081 Heilbronn</td></tr>
4951     <tr><td class="author-text">&nbsp;</td>
4952     <td class="author-text">Germany</td></tr>
4953     <tr><td class="author" align="right">EMail:&nbsp;</td>
4954     <td class="author-text"><a href="mailto:schoenebeck at software minus engineering dot org">schoenebeck at software minus engineering dot org</a></td></tr>
4955     </table>
4956     <a name="rfc.copyright"></a><br /><hr />
4957     <table summary="layout" cellpadding="0" cellspacing="2" class="bug" align="right"><tr><td class="bug"><a href="#toc" class="link2">&nbsp;TOC&nbsp;</a></td></tr></table>
4958     <h3>Intellectual Property Statement</h3>
4959     <p class='copyright'>
4960     The IETF takes no position regarding the validity or scope of
4961     any intellectual property or other rights that might be claimed
4962     to pertain to the implementation or use of the technology
4963     described in this document or the extent to which any license
4964     under such rights might or might not be available; neither does
4965     it represent that it has made any effort to identify any such
4966     rights. Information on the IETF's procedures with respect to
4967     rights in standards-track and standards-related documentation
4968     can be found in BCP-11. Copies of claims of rights made
4969     available for publication and any assurances of licenses to
4970     be made available, or the result of an attempt made
4971     to obtain a general license or permission for the use of such
4972     proprietary rights by implementors or users of this
4973     specification can be obtained from the IETF Secretariat.</p>
4974     <p class='copyright'>
4975     The IETF invites any interested party to bring to its
4976     attention any copyrights, patents or patent applications, or
4977     other proprietary rights which may cover technology that may be
4978     required to practice this standard. Please address the
4979     information to the IETF Executive Director.</p>
4980     <h3>Full Copyright Statement</h3>
4981     <p class='copyright'>
4982     Copyright (C) The Internet Society (2005). All Rights Reserved.</p>
4983     <p class='copyright'>
4984     This document and translations of it may be copied and furnished to
4985     others, and derivative works that comment on or otherwise explain it
4986     or assist in its implementation may be prepared, copied, published and
4987     distributed, in whole or in part, without restriction of any kind,
4988     provided that the above copyright notice and this paragraph are
4989     included on all such copies and derivative works. However, this
4990     document itself may not be modified in any way, such as by removing
4991     the copyright notice or references to the Internet Society or other
4992     Internet organizations, except as needed for the purpose of
4993     developing Internet standards in which case the procedures for
4994     copyrights defined in the Internet Standards process must be
4995     followed, or as required to translate it into languages other than
4996     English.</p>
4997     <p class='copyright'>
4998     The limited permissions granted above are perpetual and will not be
4999     revoked by the Internet Society or its successors or assignees.</p>
5000     <p class='copyright'>
5001     This document and the information contained herein is provided on an
5002     &quot;AS IS&quot; basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
5003     TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
5004     BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
5005     HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
5006     MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.</p>
5007     <h3>Acknowledgment</h3>
5008     <p class='copyright'>
5009     Funding for the RFC Editor function is currently provided by the
5010     Internet Society.</p>
5011     </body></html>

  ViewVC Help
Powered by ViewVC