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

Contents of /web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3503 - (show annotations) (download)
Mon Mar 11 15:46:15 2019 UTC (11 months, 2 weeks ago) by schoenebeck
File MIME type: text/plain
File size: 281929 byte(s)
* Updated LSCP reference documentation.

1
2
3
4
5 LinuxSampler Developers C. Schoenebeck, Ed.
6 Internet-Draft LinuxSampler.org
7 Intended status: Informational March 11, 2019
8 Expires: September 12, 2019
9
10
11 LinuxSampler Control Protocol
12 LSCP 1.7
13
14 Abstract
15
16 The LinuxSampler Control Protocol (LSCP) is an application-level
17 protocol primarily intended for local and remote controlling the
18 LinuxSampler backend application, which is a sophisticated server-
19 like console application essentially playing back audio samples and
20 manipulating the samples in real time to certain extent.
21
22 Status of This Memo
23
24 This Internet-Draft is submitted in full conformance with the
25 provisions of BCP 78 and BCP 79.
26
27 Internet-Drafts are working documents of the Internet Engineering
28 Task Force (IETF). Note that other groups may also distribute
29 working documents as Internet-Drafts. The list of current Internet-
30 Drafts is at http://datatracker.ietf.org/drafts/current/.
31
32 Internet-Drafts are draft documents valid for a maximum of six months
33 and may be updated, replaced, or obsoleted by other documents at any
34 time. It is inappropriate to use Internet-Drafts as reference
35 material or to cite them other than as "work in progress."
36
37 This Internet-Draft will expire on September 12, 2019.
38
39 Copyright Notice
40
41 Copyright (c) 2019 IETF Trust and the persons identified as the
42 document authors. All rights reserved.
43
44 This document is subject to BCP 78 and the IETF Trust's Legal
45 Provisions Relating to IETF Documents
46 (http://trustee.ietf.org/license-info) in effect on the date of
47 publication of this document. Please review these documents
48 carefully, as they describe your rights and restrictions with respect
49 to this document. Code Components extracted from this document must
50 include Simplified BSD License text as described in Section 4.e of
51 the Trust Legal Provisions and are provided without warranty as
52 described in the Simplified BSD License.
53
54
55
56 Schoenebeck Expires September 12, 2019 [Page 1]
57
58 Internet-Draft LinuxSampler Control Protocol March 2019
59
60
61 This document may not be modified, and derivative works of it may not
62 be created, and it may not be published except as an Internet-Draft.
63
64 Table of Contents
65
66 1. Requirements notation . . . . . . . . . . . . . . . . . . . . 6
67 2. Versioning of this specification . . . . . . . . . . . . . . 7
68 3. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8
69 4. Focus of this protocol . . . . . . . . . . . . . . . . . . . 8
70 5. Communication Overview . . . . . . . . . . . . . . . . . . . 8
71 5.1. Request/response communication method . . . . . . . . . . 9
72 5.1.1. Result format . . . . . . . . . . . . . . . . . . . . 9
73 5.2. Subscribe/notify communication method . . . . . . . . . . 12
74 6. Description for control commands . . . . . . . . . . . . . . 13
75 6.1. Ignored lines and comments . . . . . . . . . . . . . . . 14
76 6.2. Configuring audio drivers . . . . . . . . . . . . . . . . 14
77 6.2.1. Getting amount of available audio output drivers . . 14
78 6.2.2. Getting all available audio output drivers . . . . . 15
79 6.2.3. Getting information about a specific audio
80 output driver . . . . . . . . . . . . . . . . . . . . 15
81 6.2.4. Getting information about specific audio
82 output driver parameter . . . . . . . . . . . . . . . 16
83 6.2.5. Creating an audio output device . . . . . . . . . . . 20
84 6.2.6. Destroying an audio output device . . . . . . . . . . 21
85 6.2.7. Getting all created audio output device count . . . . 21
86 6.2.8. Getting all created audio output device list . . . . 22
87 6.2.9. Getting current settings of an audio output device . 22
88 6.2.10. Changing settings of audio output devices . . . . . . 23
89 6.2.11. Getting information about an audio channel . . . . . 24
90 6.2.12. Getting information about specific audio channel
91 parameter . . . . . . . . . . . . . . . . . . . . . . 26
92 6.2.13. Changing settings of audio output channels . . . . . 28
93 6.3. Configuring MIDI input drivers . . . . . . . . . . . . . 29
94 6.3.1. Getting amount of available MIDI input drivers . . . 29
95 6.3.2. Getting all available MIDI input drivers . . . . . . 30
96 6.3.3. Getting information about a specific MIDI input
97 driver . . . . . . . . . . . . . . . . . . . . . . . 30
98 6.3.4. Getting information about specific MIDI input driver
99 parameter . . . . . . . . . . . . . . . . . . . . . . 31
100 6.3.5. Creating a MIDI input device . . . . . . . . . . . . 34
101 6.3.6. Destroying a MIDI input device . . . . . . . . . . . 35
102 6.3.7. Getting all created MIDI input device count . . . . . 35
103 6.3.8. Getting all created MIDI input device list . . . . . 36
104 6.3.9. Getting current settings of a MIDI input device . . . 36
105 6.3.10. Changing settings of MIDI input devices . . . . . . . 37
106 6.3.11. Getting information about a MIDI port . . . . . . . . 38
107 6.3.12. Getting information about specific MIDI port
108 parameter . . . . . . . . . . . . . . . . . . . . . . 39
109
110
111
112 Schoenebeck Expires September 12, 2019 [Page 2]
113
114 Internet-Draft LinuxSampler Control Protocol March 2019
115
116
117 6.3.13. Changing settings of MIDI input ports . . . . . . . . 41
118 6.4. Configuring sampler channels . . . . . . . . . . . . . . 41
119 6.4.1. Loading an instrument . . . . . . . . . . . . . . . . 42
120 6.4.2. Loading a sampler engine . . . . . . . . . . . . . . 43
121 6.4.3. Getting all created sampler channel count . . . . . . 44
122 6.4.4. Getting all created sampler channel list . . . . . . 44
123 6.4.5. Adding a new sampler channel . . . . . . . . . . . . 44
124 6.4.6. Removing a sampler channel . . . . . . . . . . . . . 45
125 6.4.7. Getting amount of available engines . . . . . . . . . 46
126 6.4.8. Getting all available engines . . . . . . . . . . . . 46
127 6.4.9. Getting information about an engine . . . . . . . . . 47
128 6.4.10. Getting sampler channel information . . . . . . . . . 48
129 6.4.11. Current number of active voices . . . . . . . . . . . 52
130 6.4.12. Current number of active disk streams . . . . . . . . 52
131 6.4.13. Current fill state of disk stream buffers . . . . . . 52
132 6.4.14. Setting audio output device . . . . . . . . . . . . . 53
133 6.4.15. Setting audio output type . . . . . . . . . . . . . . 54
134 6.4.16. Setting audio output channel . . . . . . . . . . . . 55
135 6.4.17. Add MIDI input to sampler channel . . . . . . . . . . 56
136 6.4.18. Remove MIDI input(s) from sampler channel . . . . . . 57
137 6.4.19. Getting all MIDI inputs of a sampler channel . . . . 58
138 6.4.20. Setting MIDI input device . . . . . . . . . . . . . . 59
139 6.4.21. Setting MIDI input type . . . . . . . . . . . . . . . 60
140 6.4.22. Setting MIDI input port . . . . . . . . . . . . . . . 61
141 6.4.23. Setting MIDI input channel . . . . . . . . . . . . . 62
142 6.4.24. Setting channel volume . . . . . . . . . . . . . . . 63
143 6.4.25. Muting a sampler channel . . . . . . . . . . . . . . 63
144 6.4.26. Soloing a sampler channel . . . . . . . . . . . . . . 64
145 6.4.27. Assigning a MIDI instrument map to a sampler channel 65
146 6.4.28. Adding an effect send to a sampler channel . . . . . 66
147 6.4.29. Removing an effect send from a sampler channel . . . 67
148 6.4.30. Getting amount of effect sends on a sampler channel . 68
149 6.4.31. Listing all effect sends on a sampler channel . . . . 68
150 6.4.32. Getting effect send information . . . . . . . . . . . 69
151 6.4.33. Changing effect send's name . . . . . . . . . . . . . 71
152 6.4.34. Altering effect send's audio routing . . . . . . . . 71
153 6.4.35. Assigning destination effect to an effect send . . . 73
154 6.4.36. Removing destination effect from an effect send . . . 74
155 6.4.37. Altering effect send's MIDI controller . . . . . . . 74
156 6.4.38. Altering effect send's send level . . . . . . . . . . 75
157 6.4.39. Sending MIDI messages to sampler channel . . . . . . 76
158 6.4.40. Resetting a sampler channel . . . . . . . . . . . . . 77
159 6.5. Controlling connection . . . . . . . . . . . . . . . . . 78
160 6.5.1. Register front-end for receiving event messages . . . 78
161 6.5.2. Unregister front-end for not receiving event messages 78
162 6.5.3. Enable or disable echo of commands . . . . . . . . . 79
163 6.5.4. Close client connection . . . . . . . . . . . . . . . 80
164 6.6. Global commands . . . . . . . . . . . . . . . . . . . . . 80
165
166
167
168 Schoenebeck Expires September 12, 2019 [Page 3]
169
170 Internet-Draft LinuxSampler Control Protocol March 2019
171
172
173 6.6.1. Current number of active voices . . . . . . . . . . . 80
174 6.6.2. Maximum amount of active voices . . . . . . . . . . . 80
175 6.6.3. Current number of active disk streams . . . . . . . . 80
176 6.6.4. Reset sampler . . . . . . . . . . . . . . . . . . . . 81
177 6.6.5. General sampler information . . . . . . . . . . . . . 81
178 6.6.6. Getting global volume attenuation . . . . . . . . . . 82
179 6.6.7. Setting global volume attenuation . . . . . . . . . . 83
180 6.6.8. Getting global voice limit . . . . . . . . . . . . . 83
181 6.6.9. Setting global voice limit . . . . . . . . . . . . . 84
182 6.6.10. Getting global disk stream limit . . . . . . . . . . 84
183 6.6.11. Setting global disk stream limit . . . . . . . . . . 85
184 6.7. MIDI Instrument Mapping . . . . . . . . . . . . . . . . . 85
185 6.7.1. Create a new MIDI instrument map . . . . . . . . . . 86
186 6.7.2. Delete one particular or all MIDI instrument maps . . 87
187 6.7.3. Get amount of existing MIDI instrument maps . . . . . 88
188 6.7.4. Getting all created MIDI instrument maps . . . . . . 88
189 6.7.5. Getting MIDI instrument map information . . . . . . . 88
190 6.7.6. Renaming a MIDI instrument map . . . . . . . . . . . 89
191 6.7.7. Create or replace a MIDI instrument map entry . . . . 90
192 6.7.8. Getting amount of MIDI instrument map entries . . . . 93
193 6.7.9. Getting indeces of all entries of a MIDI instrument
194 map . . . . . . . . . . . . . . . . . . . . . . . . . 93
195 6.7.10. Remove an entry from the MIDI instrument map . . . . 94
196 6.7.11. Get current settings of MIDI instrument map entry . . 95
197 6.7.12. Clear MIDI instrument map . . . . . . . . . . . . . . 96
198 6.8. Managing Instruments Database . . . . . . . . . . . . . . 97
199 6.8.1. Creating a new instrument directory . . . . . . . . . 97
200 6.8.2. Deleting an instrument directory . . . . . . . . . . 98
201 6.8.3. Getting amount of instrument directories . . . . . . 99
202 6.8.4. Listing all directories in specific directory . . . . 99
203 6.8.5. Getting instrument directory information . . . . . . 100
204 6.8.6. Renaming an instrument directory . . . . . . . . . . 101
205 6.8.7. Moving an instrument directory . . . . . . . . . . . 101
206 6.8.8. Copying instrument directories . . . . . . . . . . . 102
207 6.8.9. Changing the description of directory . . . . . . . . 103
208 6.8.10. Finding directories . . . . . . . . . . . . . . . . . 103
209 6.8.11. Adding instruments to the instruments database . . . 104
210 6.8.12. Removing an instrument . . . . . . . . . . . . . . . 106
211 6.8.13. Getting amount of instruments . . . . . . . . . . . . 106
212 6.8.14. Listing all instruments in specific directory . . . . 107
213 6.8.15. Getting instrument information . . . . . . . . . . . 107
214 6.8.16. Renaming an instrument . . . . . . . . . . . . . . . 110
215 6.8.17. Moving an instrument . . . . . . . . . . . . . . . . 110
216 6.8.18. Copying instruments . . . . . . . . . . . . . . . . . 111
217 6.8.19. Changing the description of instrument . . . . . . . 112
218 6.8.20. Finding instruments . . . . . . . . . . . . . . . . . 112
219 6.8.21. Getting job status information . . . . . . . . . . . 113
220 6.8.22. Formatting the instruments database . . . . . . . . . 114
221
222
223
224 Schoenebeck Expires September 12, 2019 [Page 4]
225
226 Internet-Draft LinuxSampler Control Protocol March 2019
227
228
229 6.8.23. Checking for lost instrument files . . . . . . . . . 115
230 6.8.24. Replacing an instrument file . . . . . . . . . . . . 115
231 6.9. Editing Instruments . . . . . . . . . . . . . . . . . . . 116
232 6.9.1. Opening an appropriate instrument editor application 116
233 6.10. Managing Files . . . . . . . . . . . . . . . . . . . . . 117
234 6.10.1. Retrieving amount of instruments of a file . . . . . 117
235 6.10.2. Retrieving all instruments of a file . . . . . . . . 118
236 6.10.3. Retrieving information about one instrument in a
237 file . . . . . . . . . . . . . . . . . . . . . . . . 118
238 6.11. Managing Effects . . . . . . . . . . . . . . . . . . . . 120
239 6.11.1. Retrieve amount of available effects . . . . . . . . 121
240 6.11.2. Get list of available effects . . . . . . . . . . . 121
241 6.11.3. Retrieving general information about an effect . . . 122
242 6.11.4. Creating an instance of an effect by its portable ID 123
243 6.11.5. Creating an instance of an effect by its numerical
244 ID . . . . . . . . . . . . . . . . . . . . . . . . . 124
245 6.11.6. Destroy an effect instance . . . . . . . . . . . . . 125
246 6.11.7. Retrieve amount of effect instances . . . . . . . . 126
247 6.11.8. Get list of effect instances . . . . . . . . . . . . 126
248 6.11.9. Retrieving current information about an effect
249 instance . . . . . . . . . . . . . . . . . . . . . . 126
250 6.11.10. Retrieving information about an effect parameter . . 128
251 6.11.11. Altering an effect parameter . . . . . . . . . . . . 130
252 6.11.12. Retrieve amount of send effect chains . . . . . . . 130
253 6.11.13. Retrieve list of send effect chains . . . . . . . . 131
254 6.11.14. Add send effect chain . . . . . . . . . . . . . . . 131
255 6.11.15. Remove send effect chain . . . . . . . . . . . . . . 132
256 6.11.16. Retrieving information about a send effect chain . . 132
257 6.11.17. Append effect instance to a send effect chain . . . 133
258 6.11.18. Insert effect instance to a send effect chain . . . 134
259 6.11.19. Remove effect instance from send effect chain . . . 135
260 7. Command Syntax . . . . . . . . . . . . . . . . . . . . . . . 136
261 7.1. Character Set and Escape Sequences . . . . . . . . . . . 153
262 8. Events . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
263 8.1. Number of audio output devices changed . . . . . . . . . 157
264 8.2. Audio output device's settings changed . . . . . . . . . 157
265 8.3. Number of MIDI input devices changed . . . . . . . . . . 157
266 8.4. MIDI input device's settings changed . . . . . . . . . . 158
267 8.5. Number of sampler channels changed . . . . . . . . . . . 158
268 8.6. MIDI data on a sampler channel arrived . . . . . . . . . 158
269 8.7. MIDI data on a MIDI input device arrived . . . . . . . . 159
270 8.8. Number of active voices changed . . . . . . . . . . . . . 159
271 8.9. Number of active disk streams changed . . . . . . . . . . 160
272 8.10. Disk stream buffer fill state changed . . . . . . . . . . 160
273 8.11. Channel information changed . . . . . . . . . . . . . . . 160
274 8.12. Number of effect sends changed . . . . . . . . . . . . . 161
275 8.13. Effect send information changed . . . . . . . . . . . . . 161
276 8.14. Total number of active voices changed . . . . . . . . . . 162
277
278
279
280 Schoenebeck Expires September 12, 2019 [Page 5]
281
282 Internet-Draft LinuxSampler Control Protocol March 2019
283
284
285 8.15. Total number of active disk streams changed . . . . . . . 162
286 8.16. Number of MIDI instrument maps changed . . . . . . . . . 162
287 8.17. MIDI instrument map information changed . . . . . . . . . 162
288 8.18. Number of MIDI instruments changed . . . . . . . . . . . 163
289 8.19. MIDI instrument information changed . . . . . . . . . . . 163
290 8.20. Global settings changed . . . . . . . . . . . . . . . . . 164
291 8.21. Number of database instrument directories changed . . . . 164
292 8.22. Database instrument directory information changed . . . . 165
293 8.23. Number of database instruments changed . . . . . . . . . 165
294 8.24. Database instrument information changed . . . . . . . . . 166
295 8.25. Database job status information changed . . . . . . . . . 166
296 8.26. Number of effect instances changed . . . . . . . . . . . 167
297 8.27. Effect instance information changed . . . . . . . . . . . 167
298 8.28. Number of send effect chains changed . . . . . . . . . . 167
299 8.29. Send effect chain information changed . . . . . . . . . . 168
300 8.30. Miscellaneous and debugging events . . . . . . . . . . . 168
301 9. Security Considerations . . . . . . . . . . . . . . . . . . . 168
302 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 168
303 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 169
304 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 169
305
306 1. Requirements notation
307
308 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
309 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
310 document are to be interpreted as described in [RFC2119].
311
312 This protocol is always case-sensitive if not explicitly claimed the
313 opposite.
314
315 In examples, "C:" and "S:" indicate lines sent by the client (front-
316 end) and server (LinuxSampler) respectively. Lines in examples must
317 be interpreted as every line being CRLF terminated (carriage return
318 character followed by line feed character as defined in the ASCII
319 standard [RFC20]), thus the following example:
320
321 C: "some line"
322
323 "another line"
324
325 must actually be interpreted as client sending the following message:
326
327 "some line<CR><LF>another line<CR><LF>"
328
329 where <CR> symbolizes the carriage return character and <LF> the line
330 feed character as defined in the ASCII standard.
331
332
333
334
335
336 Schoenebeck Expires September 12, 2019 [Page 6]
337
338 Internet-Draft LinuxSampler Control Protocol March 2019
339
340
341 Due to technical reasons, messages can arbitrary be fragmented, means
342 the following example:
343
344 S: "abcd"
345
346 could also happen to be sent in three messages like in the following
347 sequence scenario:
348
349 o server sending message "a"
350
351 o followed by a delay (pause) with arbitrary duration
352
353 o followed by server sending message "bcd<CR>"
354
355 o again followed by a delay (pause) with arbitrary duration
356
357 o followed by server sending the message "<LF>"
358
359 where again <CR> and <LF> symbolize the carriage return and line feed
360 characters respectively.
361
362 2. Versioning of this specification
363
364 LSCP will certainly be extended and enhanced by-and-by. Each
365 official release of the LSCP specification will be tagged with a
366 unique version tuple. The version tuple consists at least of a major
367 and minor version number like:
368
369 "1.2"
370
371 In this example the major version number would be "1" and the minor
372 version number would be "2". Note that the version tuple might also
373 have more than two elements. The major version number defines a
374 group of backward compatible versions. That means a frontend is
375 compatible to the connected sampler if and only if the LSCP versions
376 to which each of the two parties complies to, match both of the
377 following rules:
378
379 Compatibility:
380
381 1. The frontend's LSCP major version and the sampler's LSCP major
382 version are exactly equal.
383
384 2. The frontend's LSCP minor version is less or equal than the
385 sampler's LSCP minor version.
386
387
388
389
390
391
392 Schoenebeck Expires September 12, 2019 [Page 7]
393
394 Internet-Draft LinuxSampler Control Protocol March 2019
395
396
397 Compatibility can only be claimed if both rules are true. The
398 frontend can use the "GET SERVER INFO" (Section 6.6.5) command to get
399 the version of the LSCP specification the sampler complies with.
400
401 3. Introduction
402
403 LinuxSampler is a so called software sampler application capable to
404 playback audio samples from a computer's Random Access Memory (RAM)
405 as well as directly streaming it from disk. LinuxSampler is designed
406 to be modular. It provides several so called "sampler engines" where
407 each engine is specialized for a certain purpose. LinuxSampler has
408 virtual channels which will be referred in this document as "sampler
409 channels". The channels are in such way virtual as they can be
410 connected to an arbitrary MIDI input method and arbitrary MIDI
411 channel (e.g. sampler channel 17 could be connected to an ALSA
412 sequencer device 64:0 and listening to MIDI channel 1 there). Each
413 sampler channel will be associated with an instance of one of the
414 available sampler engines (e.g. GigEngine, DLSEngine). The audio
415 output of each sampler channel can be routed to an arbitrary audio
416 output method (ALSA / JACK) and an arbitrary audio output channel
417 there.
418
419 4. Focus of this protocol
420
421 Main focus of this protocol is to provide a way to configure a
422 running LinuxSampler instance and to retrieve information about it.
423 The focus of this protocol is not to provide a way to control
424 synthesis parameters or even to trigger or release notes. Or in
425 other words; the focus are those functionalities which are not
426 covered by MIDI or which may at most be handled via MIDI System
427 Exclusive Messages.
428
429 5. Communication Overview
430
431 There are two distinct methods of communication between a running
432 instance of LinuxSampler and one or more control applications, so
433 called "front-ends": a simple request/response communication method
434 used by the clients to give commands to the server as well as to
435 inquire about server's status and a subscribe/notify communication
436 method used by the client to subscribe to and receive notifications
437 of certain events as they happen on the server. The latter needs
438 more effort to be implemented in the front-end application. The two
439 communication methods will be described next.
440
441
442
443
444
445
446
447
448 Schoenebeck Expires September 12, 2019 [Page 8]
449
450 Internet-Draft LinuxSampler Control Protocol March 2019
451
452
453 5.1. Request/response communication method
454
455 This simple communication method is based on TCP [RFC793]. The
456 front-end application establishes a TCP connection to the
457 LinuxSampler instance on a certain host system. Then the front-end
458 application will send certain ASCII based commands as defined in this
459 document (every command line must be CRLF terminated - see
460 "Conventions used in this document" at the beginning of this
461 document) and the LinuxSampler application will response after a
462 certain process time with an appropriate ASCII based answer, also as
463 defined in this document. So this TCP communication is simply based
464 on query and answer paradigm. That way LinuxSampler is only able to
465 answer on queries from front-ends, but not able to automatically send
466 messages to the client if it's not asked to. The fronted should not
467 reconnect to LinuxSampler for every single command, instead it should
468 keep the connection established and simply resend message(s) for
469 subsequent commands. To keep information in the front-end up-to-date
470 the front-end has to periodically send new requests to get the
471 current information from the LinuxSampler instance. This is often
472 referred to as "polling". While polling is simple to implement and
473 may be OK to use in some cases, there may be disadvantages to polling
474 such as network traffic overhead and information being out of date.
475 It is possible for a client or several clients to open more than one
476 connection to the server at the same time. It is also possible to
477 send more than one request to the server at the same time but if
478 those requests are sent over the same connection server MUST execute
479 them sequentially. Upon executing a request server will produce a
480 result set and send it to the client. Each and every request made by
481 the client MUST result in a result set being sent back to the client.
482 No other data other than a result set may be sent by a server to a
483 client. No result set may be sent to a client without the client
484 sending request to the server first. On any particular connection,
485 result sets MUST be sent in their entirety without being interrupted
486 by other result sets. If several requests got queued up at the
487 server they MUST be processed in the order they were received and
488 result sets MUST be sent back in the same order.
489
490 5.1.1. Result format
491
492 Result set could be one of the following types:
493
494 1. Normal
495
496 2. Warning
497
498 3. Error
499
500
501
502
503
504 Schoenebeck Expires September 12, 2019 [Page 9]
505
506 Internet-Draft LinuxSampler Control Protocol March 2019
507
508
509 Warning and Error result sets MUST be single line and have the
510 following format:
511
512 o "WRN:<warning-code>:<warning-message>"
513
514 o "ERR:<error-code>:<error-message>"
515
516 Where <warning-code> and <error-code> are numeric unique identifiers
517 of the warning or error and <warning-message> and <error-message> are
518 human readable descriptions of the warning or error respectively.
519
520 Examples:
521
522 C: "LOAD INSTRUMENT '/home/me/Boesendorfer24bit.gig" 0 0
523
524 S: "WRN:32:This is a 24 bit patch which is not supported natively
525 yet."
526
527 C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA EAR"
528
529 S: "ERR:3456:Audio output driver 'ALSA' does not have a parameter
530 'EAR'."
531
532 C: "GET AUDIO_OUTPUT_DEVICE INFO 123456"
533
534 S: "ERR:9:There is no audio output device with index 123456."
535
536 Normal result sets could be:
537
538 1. Empty
539
540 2. Single line
541
542 3. Multi-line
543
544 Empty result set is issued when the server only needed to acknowledge
545 the fact that the request was received and it was processed
546 successfully and no additional information is available. This result
547 set has the following format:
548
549 "OK"
550
551 Example:
552
553 C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 CHANNELS=4"
554
555 S: "OK"
556
557
558
559
560 Schoenebeck Expires September 12, 2019 [Page 10]
561
562 Internet-Draft LinuxSampler Control Protocol March 2019
563
564
565 Single line result sets are command specific. One example of a
566 single line result set is an empty line. Multi-line result sets are
567 command specific and may include one or more lines of information.
568 They MUST always end with the following line:
569
570 "."
571
572 Example:
573
574 C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
575
576 S: "DRIVER: ALSA"
577
578 "CHANNELS: 2"
579
580 "SAMPLERATE: 44100"
581
582 "ACTIVE: true"
583
584 "FRAGMENTS: 2"
585
586 "FRAGMENTSIZE: 128"
587
588 "CARD: '0,0'"
589
590 "."
591
592 In addition to above mentioned formats, warnings and empty result
593 sets MAY be indexed. In this case, they have the following formats
594 respectively:
595
596 o "WRN[<index>]:<warning-code>:<warning-message>"
597
598 o "OK[<index>]"
599
600 where <index> is command specific and is used to indicate channel
601 number that the result set was related to or other integer value.
602
603 Each line of the result set MUST end with <CRLF>.
604
605 Examples:
606
607 C: "ADD CHANNEL"
608
609 S: "OK[12]"
610
611 C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"
612
613
614
615
616 Schoenebeck Expires September 12, 2019 [Page 11]
617
618 Internet-Draft LinuxSampler Control Protocol March 2019
619
620
621 S: "WRN[0]:32:Sample rate not supported, using 44100 instead."
622
623 5.2. Subscribe/notify communication method
624
625 This more sophisticated communication method is actually only an
626 extension of the simple request/response communication method. The
627 front-end still uses a TCP connection and sends the same commands on
628 the TCP connection. Two extra commands are SUBSCRIBE and UNSUBSCRIBE
629 commands that allow a client to tell the server that it is interested
630 in receiving notifications about certain events as they happen on the
631 server. The SUBSCRIBE command has the following syntax:
632
633 SUBSCRIBE <event-id>
634
635 where <event-id> will be replaced by the respective event that client
636 wants to subscribe to. Upon receiving such request, server SHOULD
637 respond with OK and start sending EVENT notifications when a given
638 even has occurred to the front-end when an event has occurred. It
639 MAY be possible certain events may be sent before OK response during
640 real time nature of their generation. Event messages have the
641 following format:
642
643 NOTIFY:<event-id>:<custom-event-data>
644
645 where <event-id> uniquely identifies the event that has occurred and
646 <custom-event-data> is event specific.
647
648 Several rules must be followed by the server when generating events:
649
650 1. Events MUST NOT be sent to any client who has not issued an
651 appropriate SUBSCRIBE command.
652
653 2. Events MUST only be sent using the same connection that was used
654 to subscribe to them.
655
656 3. When response is being sent to the client, event MUST be inserted
657 in the stream before or after the response, but NOT in the
658 middle. Same is true about the response. It should never be
659 inserted in the middle of the event message as well as any other
660 response.
661
662 If the client is not interested in a particular event anymore it MAY
663 issue UNSUBSCRIBE command using the following syntax:
664
665 UNSUBSCRIBE <event-id>
666
667
668
669
670
671
672 Schoenebeck Expires September 12, 2019 [Page 12]
673
674 Internet-Draft LinuxSampler Control Protocol March 2019
675
676
677 where <event-id> will be replace by the respective event that client
678 is no longer interested in receiving. For a list of supported events
679 see Section 8.
680
681 Example: the fill states of disk stream buffers have changed on
682 sampler channel 4 and the LinuxSampler instance will react by sending
683 the following message to all clients who subscribed to this event:
684
685 NOTIFY:CHANNEL_BUFFER_FILL:4 [35]62%,[33]80%,[37]98%
686
687 Which means there are currently three active streams on sampler
688 channel 4, where the stream with ID "35" is filled by 62%, stream
689 with ID 33 is filled by 80% and stream with ID 37 is filled by 98%.
690
691 Clients may choose to open more than one connection to the server and
692 use some connections to receive notifications while using other
693 connections to issue commands to the back-end. This is entirely
694 legal and up to the implementation. This does not change the
695 protocol in any way and no special restrictions exist on the server
696 to allow or disallow this or to track what connections belong to what
697 front-ends. Server will listen on a single port, accept multiple
698 connections and support protocol described in this specification in
699 it's entirety on this single port on each connection that it
700 accepted.
701
702 Due to the fact that TCP is used for this communication, dead peers
703 will be detected automatically by the OS TCP stack. While it may
704 take a while to detect dead peers if no traffic is being sent from
705 server to client (TCP keep-alive timer is set to 2 hours on many
706 OSes) it will not be an issue here as when notifications are sent by
707 the server, dead client will be detected quickly.
708
709 When connection is closed for any reason server MUST forget all
710 subscriptions that were made on this connection. If client
711 reconnects it MUST resubscribe to all events that it wants to
712 receive.
713
714 6. Description for control commands
715
716 This chapter will describe the available control commands that can be
717 sent on the TCP connection in detail. Some certain commands (e.g.
718 "GET CHANNEL INFO" (Section 6.4.10) or "GET ENGINE INFO"
719 (Section 6.4.9)) lead to multiple-line responses. In this case
720 LinuxSampler signals the end of the response by a "." (single dot)
721 line.
722
723
724
725
726
727
728 Schoenebeck Expires September 12, 2019 [Page 13]
729
730 Internet-Draft LinuxSampler Control Protocol March 2019
731
732
733 6.1. Ignored lines and comments
734
735 White lines, that is lines which only contain space and tabulator
736 characters, and lines that start with a "#" character are ignored,
737 thus it's possible for example to group commands and to place
738 comments in a LSCP script file.
739
740 6.2. Configuring audio drivers
741
742 Instances of drivers in LinuxSampler are called devices. You can use
743 multiple audio devices simultaneously, e.g. to output the sound of
744 one sampler channel using the ALSA audio output driver, and on
745 another sampler channel you might want to use the JACK audio output
746 driver. For particular audio output systems it's also possible to
747 create several devices of the same audio output driver, e.g. two
748 separate ALSA audio output devices for using two different sound
749 cards at the same time. This chapter describes all commands to
750 configure LinuxSampler's audio output devices and their parameters.
751
752 Instead of defining commands and parameters for each driver
753 individually, all possible parameters, their meanings and possible
754 values have to be obtained at runtime. This makes the protocol a bit
755 abstract, but has the advantage, that front-ends can be written
756 independently of what drivers are currently implemented and what
757 parameters these drivers are actually offering. This means front-
758 ends can even handle drivers which are implemented somewhere in
759 future without modifying the front-end at all.
760
761 Note: examples in this chapter showing particular parameters of
762 drivers are not meant as specification of the drivers' parameters.
763 Driver implementations in LinuxSampler might have complete different
764 parameter names and meanings than shown in these examples or might
765 change in future, so these examples are only meant for showing how to
766 retrieve what parameters drivers are offering, how to retrieve their
767 possible values, etc.
768
769 6.2.1. Getting amount of available audio output drivers
770
771 Use the following command to get the number of audio output drivers
772 currently available for the LinuxSampler instance:
773
774 GET AVAILABLE_AUDIO_OUTPUT_DRIVERS
775
776 Possible Answers:
777
778 LinuxSampler will answer by sending the number of audio output
779 drivers.
780
781
782
783
784 Schoenebeck Expires September 12, 2019 [Page 14]
785
786 Internet-Draft LinuxSampler Control Protocol March 2019
787
788
789 Example:
790
791 C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
792
793 S: "2"
794
795 6.2.2. Getting all available audio output drivers
796
797 Use the following command to list all audio output drivers currently
798 available for the LinuxSampler instance:
799
800 LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS
801
802 Possible Answers:
803
804 LinuxSampler will answer by sending comma separated character
805 strings, each symbolizing an audio output driver.
806
807 Example:
808
809 C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"
810
811 S: "ALSA,JACK"
812
813 6.2.3. Getting information about a specific audio output driver
814
815 Use the following command to get detailed information about a
816 specific audio output driver:
817
818 GET AUDIO_OUTPUT_DRIVER INFO <audio-output-driver>
819
820 Where <audio-output-driver> is the name of the audio output driver,
821 returned by the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2)
822 command.
823
824 Possible Answers:
825
826 LinuxSampler will answer by sending a <CRLF> separated list. Each
827 answer line begins with the information category name followed by
828 a colon and then a space character <SP> and finally the info
829 character string to that info category. At the moment the
830 following information categories are defined:
831
832
833
834 DESCRIPTION -
835
836 character string describing the audio output driver
837
838
839
840 Schoenebeck Expires September 12, 2019 [Page 15]
841
842 Internet-Draft LinuxSampler Control Protocol March 2019
843
844
845 VERSION -
846
847 character string reflecting the driver's version
848
849 PARAMETERS -
850
851 comma separated list of all parameters available for the
852 given audio output driver, at least parameters 'channels',
853 'samplerate' and 'active' are offered by all audio output
854 drivers
855
856 The mentioned fields above don't have to be in particular order.
857
858 Example:
859
860 C: "GET AUDIO_OUTPUT_DRIVER INFO ALSA"
861
862 S: "DESCRIPTION: Advanced Linux Sound Architecture"
863
864 "VERSION: 1.0"
865
866 "PARAMETERS: DRIVER,CHANNELS,SAMPLERATE,ACTIVE,FRAGMENTS,
867 FRAGMENTSIZE,CARD"
868
869 "."
870
871 6.2.4. Getting information about specific audio output driver parameter
872
873 Use the following command to get detailed information about a
874 specific audio output driver parameter:
875
876 GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO <audio> <prm> [<deplist>]
877
878 Where <audio> is the name of the audio output driver as returned by
879 the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2) command,
880 <prm> a specific parameter name for which information should be
881 obtained (as returned by the "GET AUDIO_OUTPUT_DRIVER INFO"
882 (Section 6.2.3) command) and <deplist> is an optional list of
883 parameters on which the sought parameter <prm> depends on, <deplist>
884 is a list of key-value pairs in form of "key1=val1 key2=val2 ...",
885 where character string values are encapsulated into apostrophes (').
886 Arguments given with <deplist> which are not dependency parameters of
887 <prm> will be ignored, means the front-end application can simply put
888 all parameters into <deplist> with the values already selected by the
889 user.
890
891 Possible Answers:
892
893
894
895
896 Schoenebeck Expires September 12, 2019 [Page 16]
897
898 Internet-Draft LinuxSampler Control Protocol March 2019
899
900
901 LinuxSampler will answer by sending a <CRLF> separated list. Each
902 answer line begins with the information category name followed by
903 a colon and then a space character <SP> and finally the info
904 character string to that info category. There are information
905 which is always returned, independently of the given driver
906 parameter and there are optional information which is only shown
907 dependently to given driver parameter. At the moment the
908 following information categories are defined:
909
910 TYPE -
911
912 either "BOOL" for boolean value(s) or "INT" for integer
913 value(s) or "FLOAT" for dotted number(s) or "STRING" for
914 character string(s) (always returned, no matter which driver
915 parameter)
916
917 DESCRIPTION -
918
919 arbitrary text describing the purpose of the parameter (always
920 returned, no matter which driver parameter)
921
922 MANDATORY -
923
924 either true or false, defines if this parameter must be given
925 when the device is to be created with the 'CREATE
926 AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command (always returned,
927 no matter which driver parameter)
928
929 FIX -
930
931 either true or false, if false then this parameter can be
932 changed at any time, once the device is created by the 'CREATE
933 AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command (always returned,
934 no matter which driver parameter)
935
936 MULTIPLICITY -
937
938 either true or false, defines if this parameter allows only one
939 value or a list of values, where true means multiple values and
940 false only a single value allowed (always returned, no matter
941 which driver parameter)
942
943 DEPENDS -
944
945 comma separated list of parameters this parameter depends on,
946 means the values for fields 'DEFAULT', 'RANGE_MIN', 'RANGE_MAX'
947 and 'POSSIBILITIES' might depend on these listed parameters,
948 for example assuming that an audio driver (like the ALSA
949
950
951
952 Schoenebeck Expires September 12, 2019 [Page 17]
953
954 Internet-Draft LinuxSampler Control Protocol March 2019
955
956
957 driver) offers parameters 'card' and 'samplerate' then
958 parameter 'samplerate' would depend on 'card' because the
959 possible values for 'samplerate' depends on the sound card
960 which can be chosen by the 'card' parameter (optionally
961 returned, dependent to driver parameter)
962
963 DEFAULT -
964
965 reflects the default value for this parameter which is used
966 when the device is created and not explicitly given with the
967 'CREATE AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command, in case
968 of MULTIPLCITY=true, this is a comma separated list, that's why
969 character strings are encapsulated into apostrophes (')
970 (optionally returned, dependent to driver parameter)
971
972 RANGE_MIN -
973
974 defines lower limit of the allowed value range for this
975 parameter, can be an integer value as well as a dotted number,
976 this parameter is often used in conjunction with RANGE_MAX, but
977 may also appear without (optionally returned, dependent to
978 driver parameter)
979
980 RANGE_MAX -
981
982 defines upper limit of the allowed value range for this
983 parameter, can be an integer value as well as a dotted number,
984 this parameter is often used in conjunction with RANGE_MIN, but
985 may also appear without (optionally returned, dependent to
986 driver parameter)
987
988 POSSIBILITIES -
989
990 comma separated list of possible values for this parameter,
991 character strings are encapsulated into apostrophes (optionally
992 returned, dependent to driver parameter)
993
994 The mentioned fields above don't have to be in particular order.
995
996 Examples:
997
998 C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA CARD"
999
1000 S: "DESCRIPTION: sound card to be used"
1001
1002 "TYPE: STRING"
1003
1004 "MANDATORY: false"
1005
1006
1007
1008 Schoenebeck Expires September 12, 2019 [Page 18]
1009
1010 Internet-Draft LinuxSampler Control Protocol March 2019
1011
1012
1013 "FIX: true"
1014
1015 "MULTIPLICITY: false"
1016
1017 "DEFAULT: '0,0'"
1018
1019 "POSSIBILITIES: '0,0','1,0','2,0'"
1020
1021 "."
1022
1023 C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE"
1024
1025 S: "DESCRIPTION: output sample rate in Hz"
1026
1027 "TYPE: INT"
1028
1029 "MANDATORY: false"
1030
1031 "FIX: false"
1032
1033 "MULTIPLICITY: false"
1034
1035 "DEPENDS: card"
1036
1037 "DEFAULT: 44100"
1038
1039 "."
1040
1041 C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE
1042 CARD='0,0'"
1043
1044 S: "DESCRIPTION: output sample rate in Hz"
1045
1046 "TYPE: INT"
1047
1048 "MANDATORY: false"
1049
1050 "FIX: false"
1051
1052 "MULTIPLICITY: false"
1053
1054 "DEPENDS: card"
1055
1056 "DEFAULT: 44100"
1057
1058 "RANGE_MIN: 22050"
1059
1060 "RANGE_MAX: 96000"
1061
1062
1063
1064 Schoenebeck Expires September 12, 2019 [Page 19]
1065
1066 Internet-Draft LinuxSampler Control Protocol March 2019
1067
1068
1069 "."
1070
1071 6.2.5. Creating an audio output device
1072
1073 Use the following command to create a new audio output device for the
1074 desired audio output system:
1075
1076 CREATE AUDIO_OUTPUT_DEVICE <audio-output-driver> [<param-list>]
1077
1078 Where <audio-output-driver> should be replaced by the desired audio
1079 output system as returned by the "LIST
1080 AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2) command and <param-
1081 list> by an optional list of driver specific parameters in form of
1082 "key1=val1 key2=val2 ...", where character string values should be
1083 encapsulated into apostrophes ('). Note that there might be drivers
1084 which require parameter(s) to be given with this command. Use the
1085 previously described commands in this chapter to get this
1086 information.
1087
1088 Possible Answers:
1089
1090 "OK[<device-id>]" -
1091
1092 in case the device was successfully created, where <device-id>
1093 is the numerical ID of the new device
1094
1095 "WRN[<device-id>]:<warning-code>:<warning-message>" -
1096
1097 in case the device was created successfully, where <device-id>
1098 is the numerical ID of the new device, but there are noteworthy
1099 issue(s) related (e.g. sound card doesn't support given
1100 hardware parameters and the driver is using fall-back values),
1101 providing an appropriate warning code and warning message
1102
1103 "ERR:<error-code>:<error-message>" -
1104
1105 in case it failed, providing an appropriate error code and
1106 error message
1107
1108 Examples:
1109
1110 C: "CREATE AUDIO_OUTPUT_DEVICE ALSA"
1111
1112 S: "OK[0]"
1113
1114 C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"
1115
1116 S: "OK[1]"
1117
1118
1119
1120 Schoenebeck Expires September 12, 2019 [Page 20]
1121
1122 Internet-Draft LinuxSampler Control Protocol March 2019
1123
1124
1125 6.2.6. Destroying an audio output device
1126
1127 Use the following command to destroy a created output device:
1128
1129 DESTROY AUDIO_OUTPUT_DEVICE <device-id>
1130
1131 Where <device-id> should be replaced by the numerical ID of the audio
1132 output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
1133 (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
1134 command.
1135
1136 Possible Answers:
1137
1138 "OK" -
1139
1140 in case the device was successfully destroyed
1141
1142 "WRN:<warning-code>:<warning-message>" -
1143
1144 in case the device was destroyed successfully, but there are
1145 noteworthy issue(s) related (e.g. an audio over ethernet driver
1146 was unloaded but the other host might not be informed about
1147 this situation), providing an appropriate warning code and
1148 warning message
1149
1150 "ERR:<error-code>:<error-message>" -
1151
1152 in case it failed, providing an appropriate error code and
1153 error message
1154
1155 Example:
1156
1157 C: "DESTROY AUDIO_OUTPUT_DEVICE 0"
1158
1159 S: "OK"
1160
1161 6.2.7. Getting all created audio output device count
1162
1163 Use the following command to count all created audio output devices:
1164
1165 GET AUDIO_OUTPUT_DEVICES
1166
1167 Possible Answers:
1168
1169 LinuxSampler will answer by sending the current number of all
1170 audio output devices.
1171
1172 Example:
1173
1174
1175
1176 Schoenebeck Expires September 12, 2019 [Page 21]
1177
1178 Internet-Draft LinuxSampler Control Protocol March 2019
1179
1180
1181 C: "GET AUDIO_OUTPUT_DEVICES"
1182
1183 S: "4"
1184
1185 6.2.8. Getting all created audio output device list
1186
1187 Use the following command to list all created audio output devices:
1188
1189 LIST AUDIO_OUTPUT_DEVICES
1190
1191 Possible Answers:
1192
1193 LinuxSampler will answer by sending a comma separated list with
1194 the numerical IDs of all audio output devices.
1195
1196 Example:
1197
1198 C: "LIST AUDIO_OUTPUT_DEVICES"
1199
1200 S: "0,1,4,5"
1201
1202 6.2.9. Getting current settings of an audio output device
1203
1204 Use the following command to get current settings of a specific,
1205 created audio output device:
1206
1207 GET AUDIO_OUTPUT_DEVICE INFO <device-id>
1208
1209 Where <device-id> should be replaced by numerical ID of the audio
1210 output device as e.g. returned by the "LIST AUDIO_OUTPUT_DEVICES"
1211 (Section 6.2.8) command.
1212
1213 Possible Answers:
1214
1215 LinuxSampler will answer by sending a <CRLF> separated list. Each
1216 answer line begins with the information category name followed by a
1217 colon and then a space character <SP> and finally the info character
1218 string to that info category. As some parameters might allow
1219 multiple values, character strings are encapsulated into apostrophes
1220 ('). At the moment the following information categories are defined
1221 (independently of device):
1222
1223 DRIVER -
1224
1225 identifier of the used audio output driver, as also returned by
1226 the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2)
1227 command
1228
1229
1230
1231
1232 Schoenebeck Expires September 12, 2019 [Page 22]
1233
1234 Internet-Draft LinuxSampler Control Protocol March 2019
1235
1236
1237 CHANNELS -
1238
1239 amount of audio output channels this device currently offers
1240
1241 SAMPLERATE -
1242
1243 playback sample rate the device uses
1244
1245 ACTIVE -
1246
1247 either true or false, if false then the audio device is
1248 inactive and doesn't output any sound, nor do the sampler
1249 channels connected to this audio device render any audio
1250
1251 The mentioned fields above don't have to be in particular order. The
1252 fields above are only those fields which are returned by all audio
1253 output devices. Every audio output driver might have its own,
1254 additional driver specific parameters (see Section 6.2.3) which are
1255 also returned by this command.
1256
1257 Example:
1258
1259 C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
1260
1261 S: "DRIVER: ALSA"
1262
1263 "CHANNELS: 2"
1264
1265 "SAMPLERATE: 44100"
1266
1267 "ACTIVE: true"
1268
1269 "FRAGMENTS: 2"
1270
1271 "FRAGMENTSIZE: 128"
1272
1273 "CARD: '0,0'"
1274
1275 "."
1276
1277 6.2.10. Changing settings of audio output devices
1278
1279 Use the following command to alter a specific setting of a created
1280 audio output device:
1281
1282 SET AUDIO_OUTPUT_DEVICE_PARAMETER <device-id> <key>=<value>
1283
1284
1285
1286
1287
1288 Schoenebeck Expires September 12, 2019 [Page 23]
1289
1290 Internet-Draft LinuxSampler Control Protocol March 2019
1291
1292
1293 Where <device-id> should be replaced by the numerical ID of the audio
1294 output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
1295 (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
1296 command, <key> by the name of the parameter to change and <value> by
1297 the new value for this parameter.
1298
1299 Possible Answers:
1300
1301 "OK" -
1302
1303 in case setting was successfully changed
1304
1305 "WRN:<warning-code>:<warning-message>" -
1306
1307 in case setting was changed successfully, but there are
1308 noteworthy issue(s) related, providing an appropriate warning
1309 code and warning message
1310
1311 "ERR:<error-code>:<error-message>" -
1312
1313 in case it failed, providing an appropriate error code and
1314 error message
1315
1316 Example:
1317
1318 C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"
1319
1320 S: "OK"
1321
1322 6.2.11. Getting information about an audio channel
1323
1324 Use the following command to get information about an audio channel:
1325
1326 GET AUDIO_OUTPUT_CHANNEL INFO <device-id> <audio-chan>
1327
1328 Where <device-id> is the numerical ID of the audio output device as
1329 given by the "CREATE AUDIO_OUTPUT_DEVICE" (Section 6.2.5) or "LIST
1330 AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command and <audio-chan> the
1331 audio channel number.
1332
1333 Possible Answers:
1334
1335 LinuxSampler will answer by sending a <CRLF> separated list. Each
1336 answer line begins with the information category name followed by
1337 a colon and then a space character <SP> and finally the info
1338 character string to that info category. At the moment the
1339 following information categories are defined:
1340
1341
1342
1343
1344 Schoenebeck Expires September 12, 2019 [Page 24]
1345
1346 Internet-Draft LinuxSampler Control Protocol March 2019
1347
1348
1349 NAME -
1350
1351 arbitrary character string naming the channel, which doesn't
1352 have to be unique (always returned by all audio channels)
1353
1354 IS_MIX_CHANNEL -
1355
1356 either true or false, a mix-channel is not a real,
1357 independent audio channel, but a virtual channel which is
1358 mixed to another real channel, this mechanism is needed for
1359 sampler engines which need more audio channels than the used
1360 audio system might be able to offer (always returned by all
1361 audio channels)
1362
1363 MIX_CHANNEL_DESTINATION -
1364
1365 numerical ID (positive integer including 0) which reflects
1366 the real audio channel (of the same audio output device)
1367 this mix channel refers to, means where the audio signal
1368 actually will be routed / added to (only returned in case
1369 the audio channel is mix channel)
1370
1371 The mentioned fields above don't have to be in particular order. The
1372 fields above are only those fields which are generally returned for
1373 the described cases by all audio channels regardless of the audio
1374 driver. Every audio channel might have its own, additional driver
1375 and channel specific parameters.
1376
1377 Examples:
1378
1379 C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 0"
1380
1381 S: "NAME: studio monitor left"
1382
1383 "IS_MIX_CHANNEL: false"
1384
1385 "."
1386
1387 C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 1"
1388
1389 S: "NAME: studio monitor right"
1390
1391 "IS_MIX_CHANNEL: false"
1392
1393 "."
1394
1395 C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"
1396
1397
1398
1399
1400 Schoenebeck Expires September 12, 2019 [Page 25]
1401
1402 Internet-Draft LinuxSampler Control Protocol March 2019
1403
1404
1405 S: "NAME: studio monitor left"
1406
1407 "IS_MIX_CHANNEL: true"
1408
1409 "MIX_CHANNEL_DESTINATION: 1"
1410
1411 "."
1412
1413 C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"
1414
1415 S: "NAME: 'ardour (left)'"
1416
1417 "IS_MIX_CHANNEL: false"
1418
1419 "JACK_BINDINGS: 'ardour:0'"
1420
1421 "."
1422
1423 6.2.12. Getting information about specific audio channel parameter
1424
1425 Use the following command to get detailed information about specific
1426 audio channel parameter:
1427
1428 GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO <dev-id> <chan> <param>
1429
1430 Where <dev-id> is the numerical ID of the audio output device as
1431 returned by the "CREATE AUDIO_OUTPUT_DEVICE" (Section 6.2.5) or "LIST
1432 AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command, <chan> the audio
1433 channel number and <param> a specific channel parameter name for
1434 which information should be obtained (as returned by the "GET
1435 AUDIO_OUTPUT_CHANNEL INFO" (Section 6.2.11) command).
1436
1437 Possible Answers:
1438
1439 LinuxSampler will answer by sending a <CRLF> separated list. Each
1440 answer line begins with the information category name followed by
1441 a colon and then a space character <SP> and finally the info
1442 character string to that info category. There are information
1443 which is always returned, independently of the given channel
1444 parameter and there is optional information which is only shown
1445 dependently to the given audio channel. At the moment the
1446 following information categories are defined:
1447
1448
1449
1450 TYPE -
1451
1452
1453
1454
1455
1456 Schoenebeck Expires September 12, 2019 [Page 26]
1457
1458 Internet-Draft LinuxSampler Control Protocol March 2019
1459
1460
1461 either "BOOL" for boolean value(s) or "INT" for integer
1462 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1463 character string(s) (always returned)
1464
1465 DESCRIPTION -
1466
1467 arbitrary text describing the purpose of the parameter
1468 (always returned)
1469
1470 FIX -
1471
1472 either true or false, if true then this parameter is read
1473 only, thus cannot be altered (always returned)
1474
1475 MULTIPLICITY -
1476
1477 either true or false, defines if this parameter allows only
1478 one value or a list of values, where true means multiple
1479 values and false only a single value allowed (always
1480 returned)
1481
1482 RANGE_MIN -
1483
1484 defines lower limit of the allowed value range for this
1485 parameter, can be an integer value as well as a dotted
1486 number, usually used in conjunction with 'RANGE_MAX', but
1487 may also appear without (optionally returned, dependent to
1488 driver and channel parameter)
1489
1490 RANGE_MAX -
1491
1492 defines upper limit of the allowed value range for this
1493 parameter, can be an integer value as well as a dotted
1494 number, usually used in conjunction with 'RANGE_MIN', but
1495 may also appear without (optionally returned, dependent to
1496 driver and channel parameter)
1497
1498 POSSIBILITIES -
1499
1500 comma separated list of possible values for this parameter,
1501 character strings are encapsulated into apostrophes
1502 (optionally returned, dependent to driver and channel
1503 parameter)
1504
1505 The mentioned fields above don't have to be in particular order.
1506
1507 Example:
1508
1509
1510
1511
1512 Schoenebeck Expires September 12, 2019 [Page 27]
1513
1514 Internet-Draft LinuxSampler Control Protocol March 2019
1515
1516
1517 C: "GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO 1 0 JACK_BINDINGS"
1518
1519 S: "DESCRIPTION: bindings to other JACK clients"
1520
1521 "TYPE: STRING"
1522
1523 "FIX: false"
1524
1525 "MULTIPLICITY: true"
1526
1527 "POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"
1528
1529 "."
1530
1531 6.2.13. Changing settings of audio output channels
1532
1533 Use the following command to alter a specific setting of an audio
1534 output channel:
1535
1536 SET AUDIO_OUTPUT_CHANNEL_PARAMETER <dev-id> <chn> <key>=<value>
1537
1538 Where <dev-id> should be replaced by the numerical ID of the audio
1539 output device as returned by the "CREATE AUDIO_OUTPUT_DEVICE"
1540 (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
1541 command, <chn> by the audio channel number, <key> by the name of the
1542 parameter to change and <value> by the new value for this parameter.
1543
1544 Possible Answers:
1545
1546 "OK" -
1547
1548 in case setting was successfully changed
1549
1550 "WRN:<warning-code>:<warning-message>" -
1551
1552 in case setting was changed successfully, but there are
1553 noteworthy issue(s) related, providing an appropriate warning
1554 code and warning message
1555
1556 "ERR:<error-code>:<error-message>" -
1557
1558 in case it failed, providing an appropriate error code and
1559 error message
1560
1561 Example:
1562
1563 C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"
1564
1565
1566
1567
1568 Schoenebeck Expires September 12, 2019 [Page 28]
1569
1570 Internet-Draft LinuxSampler Control Protocol March 2019
1571
1572
1573 S: "OK"
1574
1575 C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"
1576
1577 S: "OK"
1578
1579 6.3. Configuring MIDI input drivers
1580
1581 Instances of drivers in LinuxSampler are called devices. You can use
1582 multiple MIDI devices simultaneously, e.g. to use MIDI over ethernet
1583 as MIDI input on one sampler channel and ALSA as MIDI input on
1584 another sampler channel. For particular MIDI input systems it's also
1585 possible to create several devices of the same MIDI input type. This
1586 chapter describes all commands to configure LinuxSampler's MIDI input
1587 devices and their parameters.
1588
1589 Instead of defining commands and parameters for each driver
1590 individually, all possible parameters, their meanings and possible
1591 values have to be obtained at runtime. This makes the protocol a bit
1592 abstract, but has the advantage, that front-ends can be written
1593 independently of what drivers are currently implemented and what
1594 parameters these drivers are actually offering. This means front-
1595 ends can even handle drivers which are implemented somewhere in
1596 future without modifying the front-end at all.
1597
1598 Commands for configuring MIDI input devices are pretty much the same
1599 as the commands for configuring audio output drivers, already
1600 described in the last chapter.
1601
1602 Note: examples in this chapter showing particular parameters of
1603 drivers are not meant as specification of the drivers' parameters.
1604 Driver implementations in LinuxSampler might have complete different
1605 parameter names and meanings than shown in these examples or might
1606 change in future, so these examples are only meant for showing how to
1607 retrieve what parameters drivers are offering, how to retrieve their
1608 possible values, etc.
1609
1610 6.3.1. Getting amount of available MIDI input drivers
1611
1612 Use the following command to get the number of MIDI input drivers
1613 currently available for the LinuxSampler instance:
1614
1615 GET AVAILABLE_MIDI_INPUT_DRIVERS
1616
1617 Possible Answers:
1618
1619 LinuxSampler will answer by sending the number of available MIDI
1620 input drivers.
1621
1622
1623
1624 Schoenebeck Expires September 12, 2019 [Page 29]
1625
1626 Internet-Draft LinuxSampler Control Protocol March 2019
1627
1628
1629 Example:
1630
1631 C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"
1632
1633 S: "2"
1634
1635 6.3.2. Getting all available MIDI input drivers
1636
1637 Use the following command to list all MIDI input drivers currently
1638 available for the LinuxSampler instance:
1639
1640 LIST AVAILABLE_MIDI_INPUT_DRIVERS
1641
1642 Possible Answers:
1643
1644 LinuxSampler will answer by sending comma separated character
1645 strings, each symbolizing a MIDI input driver.
1646
1647 Example:
1648
1649 C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
1650
1651 S: "ALSA,JACK"
1652
1653 6.3.3. Getting information about a specific MIDI input driver
1654
1655 Use the following command to get detailed information about a
1656 specific MIDI input driver:
1657
1658 GET MIDI_INPUT_DRIVER INFO <midi-input-driver>
1659
1660 Where <midi-input-driver> is the name of the MIDI input driver as
1661 returned by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2)
1662 command.
1663
1664 Possible Answers:
1665
1666 LinuxSampler will answer by sending a <CRLF> separated list. Each
1667 answer line begins with the information category name followed by
1668 a colon and then a space character <SP> and finally the info
1669 character string to that info category. At the moment the
1670 following information categories are defined:
1671
1672
1673
1674 DESCRIPTION -
1675
1676 arbitrary description text about the MIDI input driver
1677
1678
1679
1680 Schoenebeck Expires September 12, 2019 [Page 30]
1681
1682 Internet-Draft LinuxSampler Control Protocol March 2019
1683
1684
1685 VERSION -
1686
1687 arbitrary character string regarding the driver's version
1688
1689 PARAMETERS -
1690
1691 comma separated list of all parameters available for the
1692 given MIDI input driver
1693
1694 The mentioned fields above don't have to be in particular order.
1695
1696 Example:
1697
1698 C: "GET MIDI_INPUT_DRIVER INFO ALSA"
1699
1700 S: "DESCRIPTION: Advanced Linux Sound Architecture"
1701
1702 "VERSION: 1.0"
1703
1704 "PARAMETERS: DRIVER,ACTIVE"
1705
1706 "."
1707
1708 6.3.4. Getting information about specific MIDI input driver parameter
1709
1710 Use the following command to get detailed information about a
1711 specific parameter of a specific MIDI input driver:
1712
1713 GET MIDI_INPUT_DRIVER_PARAMETER INFO <midit> <param> [<deplist>]
1714
1715 Where <midit> is the name of the MIDI input driver as returned by the
1716 "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2) command, <param>
1717 a specific parameter name for which information should be obtained
1718 (as returned by the "GET MIDI_INPUT_DRIVER INFO" (Section 6.3.3)
1719 command) and <deplist> is an optional list of parameters on which the
1720 sought parameter <param> depends on, <deplist> is a key-value pair
1721 list in form of "key1=val1 key2=val2 ...", where character string
1722 values are encapsulated into apostrophes ('). Arguments given with
1723 <deplist> which are not dependency parameters of <param> will be
1724 ignored, means the front-end application can simply put all
1725 parameters in <deplist> with the values selected by the user.
1726
1727 Possible Answers:
1728
1729 LinuxSampler will answer by sending a <CRLF> separated list. Each
1730 answer line begins with the information category name followed by a
1731 colon and then a space character <SP> and finally the info character
1732 string to that info category. There is information which is always
1733
1734
1735
1736 Schoenebeck Expires September 12, 2019 [Page 31]
1737
1738 Internet-Draft LinuxSampler Control Protocol March 2019
1739
1740
1741 returned, independent of the given driver parameter and there is
1742 optional information which is only shown dependent to given driver
1743 parameter. At the moment the following information categories are
1744 defined:
1745
1746 TYPE -
1747
1748 either "BOOL" for boolean value(s) or "INT" for integer
1749 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1750 character string(s) (always returned, no matter which driver
1751 parameter)
1752
1753 DESCRIPTION -
1754
1755 arbitrary text describing the purpose of the parameter (always
1756 returned, no matter which driver parameter)
1757
1758 MANDATORY -
1759
1760 either true or false, defines if this parameter must be given
1761 when the device is to be created with the 'CREATE
1762 MIDI_INPUT_DEVICE' (Section 6.3.5) command (always returned, no
1763 matter which driver parameter)
1764
1765 FIX -
1766
1767 either true or false, if false then this parameter can be
1768 changed at any time, once the device is created by the 'CREATE
1769 MIDI_INPUT_DEVICE' (Section 6.3.5) command (always returned, no
1770 matter which driver parameter)
1771
1772 MULTIPLICITY -
1773
1774 either true or false, defines if this parameter allows only one
1775 value or a list of values, where true means multiple values and
1776 false only a single value allowed (always returned, no matter
1777 which driver parameter)
1778
1779 DEPENDS -
1780
1781 comma separated list of parameters this parameter depends on,
1782 means the values for fields 'DEFAULT', 'RANGE_MIN', 'RANGE_MAX'
1783 and 'POSSIBILITIES' might depend on these listed parameters,
1784 for example assuming that an audio driver (like the ALSA
1785 driver) offers parameters 'card' and 'samplerate' then
1786 parameter 'samplerate' would depend on 'card' because the
1787 possible values for 'samplerate' depends on the sound card
1788
1789
1790
1791
1792 Schoenebeck Expires September 12, 2019 [Page 32]
1793
1794 Internet-Draft LinuxSampler Control Protocol March 2019
1795
1796
1797 which can be chosen by the 'card' parameter (optionally
1798 returned, dependent to driver parameter)
1799
1800 DEFAULT -
1801
1802 reflects the default value for this parameter which is used
1803 when the device is created and not explicitly given with the
1804 'CREATE MIDI_INPUT_DEVICE' (Section 6.3.5) command, in case of
1805 MULTIPLCITY=true, this is a comma separated list, that's why
1806 character strings are encapsulated into apostrophes (')
1807 (optionally returned, dependent to driver parameter)
1808
1809 RANGE_MIN -
1810
1811 defines lower limit of the allowed value range for this
1812 parameter, can be an integer value as well as a dotted number,
1813 this parameter is often used in conjunction with RANGE_MAX, but
1814 may also appear without (optionally returned, dependent to
1815 driver parameter)
1816
1817 RANGE_MAX -
1818
1819 defines upper limit of the allowed value range for this
1820 parameter, can be an integer value as well as a dotted number,
1821 this parameter is often used in conjunction with RANGE_MIN, but
1822 may also appear without (optionally returned, dependent to
1823 driver parameter)
1824
1825 POSSIBILITIES -
1826
1827 comma separated list of possible values for this parameter,
1828 character strings are encapsulated into apostrophes (optionally
1829 returned, dependent to driver parameter)
1830
1831 The mentioned fields above don't have to be in particular order.
1832
1833 Example:
1834
1835 C: "GET MIDI_INPUT_DRIVER_PARAMETER INFO ALSA ACTIVE"
1836
1837 S: "DESCRIPTION: Whether device is enabled"
1838
1839 "TYPE: BOOL"
1840
1841 "MANDATORY: false"
1842
1843 "FIX: false"
1844
1845
1846
1847
1848 Schoenebeck Expires September 12, 2019 [Page 33]
1849
1850 Internet-Draft LinuxSampler Control Protocol March 2019
1851
1852
1853 "MULTIPLICITY: false"
1854
1855 "DEFAULT: true"
1856
1857 "."
1858
1859 6.3.5. Creating a MIDI input device
1860
1861 Use the following command to create a new MIDI input device for the
1862 desired MIDI input system:
1863
1864 CREATE MIDI_INPUT_DEVICE <midi-input-driver> [<param-list>]
1865
1866 Where <midi-input-driver> should be replaced by the desired MIDI
1867 input system as returned by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
1868 (Section 6.3.2) command and <param-list> by an optional list of
1869 driver specific parameters in form of "key1=val1 key2=val2 ...",
1870 where character string values should be encapsulated into apostrophes
1871 ('). Note that there might be drivers which require parameter(s) to
1872 be given with this command. Use the previously described commands in
1873 this chapter to get that information.
1874
1875 Possible Answers:
1876
1877 "OK[<device-id>]" -
1878
1879 in case the device was successfully created, where <device-id>
1880 is the numerical ID of the new device
1881
1882 "WRN[<device-id>]:<warning-code>:<warning-message>" -
1883
1884 in case the driver was loaded successfully, where <device-id>
1885 is the numerical ID of the new device, but there are noteworthy
1886 issue(s) related, providing an appropriate warning code and
1887 warning message
1888
1889 "ERR:<error-code>:<error-message>" -
1890
1891 in case it failed, providing an appropriate error code and
1892 error message
1893
1894 Example:
1895
1896 C: "CREATE MIDI_INPUT_DEVICE ALSA"
1897
1898 S: "OK[0]"
1899
1900
1901
1902
1903
1904 Schoenebeck Expires September 12, 2019 [Page 34]
1905
1906 Internet-Draft LinuxSampler Control Protocol March 2019
1907
1908
1909 6.3.6. Destroying a MIDI input device
1910
1911 Use the following command to destroy a created MIDI input device:
1912
1913 DESTROY MIDI_INPUT_DEVICE <device-id>
1914
1915 Where <device-id> should be replaced by the device's numerical ID as
1916 returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
1917 MIDI_INPUT_DEVICES" (Section 6.3.8) command.
1918
1919 Possible Answers:
1920
1921 "OK" -
1922
1923 in case the device was successfully destroyed
1924
1925 "WRN:<warning-code>:<warning-message>" -
1926
1927 in case the device was destroyed, but there are noteworthy
1928 issue(s) related, providing an appropriate warning code and
1929 warning message
1930
1931 "ERR:<error-code>:<error-message>" -
1932
1933 in case it failed, providing an appropriate error code and
1934 error message
1935
1936 Example:
1937
1938 C: "DESTROY MIDI_INPUT_DEVICE 0"
1939
1940 S: "OK"
1941
1942 6.3.7. Getting all created MIDI input device count
1943
1944 Use the following command to count all created MIDI input devices:
1945
1946 GET MIDI_INPUT_DEVICES
1947
1948 Possible Answers:
1949
1950 LinuxSampler will answer by sending the current number of all MIDI
1951 input devices.
1952
1953 Example:
1954
1955 C: "GET MIDI_INPUT_DEVICES"
1956
1957
1958
1959
1960 Schoenebeck Expires September 12, 2019 [Page 35]
1961
1962 Internet-Draft LinuxSampler Control Protocol March 2019
1963
1964
1965 S: "3"
1966
1967 6.3.8. Getting all created MIDI input device list
1968
1969 Use the following command to list all created MIDI input devices:
1970
1971 LIST MIDI_INPUT_DEVICES
1972
1973 Possible Answers:
1974
1975 LinuxSampler will answer by sending a comma separated list with
1976 the numerical Ids of all created MIDI input devices.
1977
1978 Examples:
1979
1980 C: "LIST MIDI_INPUT_DEVICES"
1981
1982 S: "0,1,2"
1983
1984 C: "LIST MIDI_INPUT_DEVICES"
1985
1986 S: "1,3"
1987
1988 6.3.9. Getting current settings of a MIDI input device
1989
1990 Use the following command to get current settings of a specific,
1991 created MIDI input device:
1992
1993 GET MIDI_INPUT_DEVICE INFO <device-id>
1994
1995 Where <device-id> is the numerical ID of the MIDI input device as
1996 returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
1997 MIDI_INPUT_DEVICES" (Section 6.3.8) command.
1998
1999 Possible Answers:
2000
2001 LinuxSampler will answer by sending a <CRLF> separated list. Each
2002 answer line begins with the information category name followed by
2003 a colon and then a space character <SP> and finally the info
2004 character string to that info category. As some parameters might
2005 allow multiple values, character strings are encapsulated into
2006 apostrophes ('). At the moment the following information
2007 categories are defined (independent of driver):
2008
2009
2010
2011 DRIVER -
2012
2013
2014
2015
2016 Schoenebeck Expires September 12, 2019 [Page 36]
2017
2018 Internet-Draft LinuxSampler Control Protocol March 2019
2019
2020
2021 identifier of the used MIDI input driver, as e.g. returned
2022 by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2)
2023 command
2024
2025 ACTIVE -
2026
2027 either true or false, if false then the MIDI device is
2028 inactive and doesn't listen to any incoming MIDI events and
2029 thus doesn't forward them to connected sampler channels
2030
2031 The mentioned fields above don't have to be in particular order. The
2032 fields above are only those fields which are returned by all MIDI
2033 input devices. Every MIDI input driver might have its own,
2034 additional driver specific parameters (see "GET MIDI_INPUT_DRIVER
2035 INFO" (Section 6.3.3) command) which are also returned by this
2036 command.
2037
2038 Example:
2039
2040 C: "GET MIDI_INPUT_DEVICE INFO 0"
2041
2042 S: "DRIVER: ALSA"
2043
2044 "ACTIVE: true"
2045
2046 "."
2047
2048 6.3.10. Changing settings of MIDI input devices
2049
2050 Use the following command to alter a specific setting of a created
2051 MIDI input device:
2052
2053 SET MIDI_INPUT_DEVICE_PARAMETER <device-id> <key>=<value>
2054
2055 Where <device-id> should be replaced by the numerical ID of the MIDI
2056 input device as returned by the "CREATE MIDI_INPUT_DEVICE"
2057 (Section 6.3.5) or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command,
2058 <key> by the name of the parameter to change and <value> by the new
2059 value for this parameter.
2060
2061 Possible Answers:
2062
2063 "OK" -
2064
2065 in case setting was successfully changed
2066
2067 "WRN:<warning-code>:<warning-message>" -
2068
2069
2070
2071
2072 Schoenebeck Expires September 12, 2019 [Page 37]
2073
2074 Internet-Draft LinuxSampler Control Protocol March 2019
2075
2076
2077 in case setting was changed successfully, but there are
2078 noteworthy issue(s) related, providing an appropriate warning
2079 code and warning message
2080
2081 "ERR:<error-code>:<error-message>" -
2082
2083 in case it failed, providing an appropriate error code and
2084 error message
2085
2086 Example:
2087
2088 C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"
2089
2090 S: "OK"
2091
2092 6.3.11. Getting information about a MIDI port
2093
2094 Use the following command to get information about a MIDI port:
2095
2096 GET MIDI_INPUT_PORT INFO <device-id> <midi-port>
2097
2098 Where <device-id> is the numerical ID of the MIDI input device as
2099 returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
2100 MIDI_INPUT_DEVICES" (Section 6.3.8) command and <midi-port> the MIDI
2101 input port number.
2102
2103 Possible Answers:
2104
2105 LinuxSampler will answer by sending a <CRLF> separated list. Each
2106 answer line begins with the information category name followed by
2107 a colon and then a space character <SP> and finally the info
2108 character string to that info category. At the moment the
2109 following information categories are defined:
2110
2111 NAME -
2112
2113 arbitrary character string naming the port
2114
2115 The field above is only the one which is returned by all MIDI ports
2116 regardless of the MIDI driver and port. Every MIDI port might have
2117 its own, additional driver and port specific parameters.
2118
2119 Example:
2120
2121 C: "GET MIDI_INPUT_PORT INFO 0 0"
2122
2123 S: "NAME: 'Masterkeyboard'"
2124
2125
2126
2127
2128 Schoenebeck Expires September 12, 2019 [Page 38]
2129
2130 Internet-Draft LinuxSampler Control Protocol March 2019
2131
2132
2133 "ALSA_SEQ_BINDINGS: '64:0'"
2134
2135 "."
2136
2137 6.3.12. Getting information about specific MIDI port parameter
2138
2139 Use the following command to get detailed information about specific
2140 MIDI port parameter:
2141
2142 GET MIDI_INPUT_PORT_PARAMETER INFO <dev-id> <port> <param>
2143
2144 Where <dev-id> is the numerical ID of the MIDI input device as
2145 returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
2146 MIDI_INPUT_DEVICES" (Section 6.3.8) command, <port> the MIDI port
2147 number and <param> a specific port parameter name for which
2148 information should be obtained (as returned by the "GET
2149 MIDI_INPUT_PORT INFO" (Section 6.3.11) command).
2150
2151 Possible Answers:
2152
2153 LinuxSampler will answer by sending a <CRLF> separated list. Each
2154 answer line begins with the information category name followed by
2155 a colon and then a space character <SP> and finally the info
2156 character string to that info category. There is information
2157 which is always returned, independently of the given channel
2158 parameter and there is optional information which are only shown
2159 dependently to the given MIDI port. At the moment the following
2160 information categories are defined:
2161
2162 TYPE -
2163
2164 either "BOOL" for boolean value(s) or "INT" for integer
2165 value(s) or "FLOAT" for dotted number(s) or "STRING" for
2166 character string(s) (always returned)
2167
2168 DESCRIPTION -
2169
2170 arbitrary text describing the purpose of the parameter (always
2171 returned)
2172
2173 FIX -
2174
2175 either true or false, if true then this parameter is read only,
2176 thus cannot be altered (always returned)
2177
2178 MULTIPLICITY -
2179
2180
2181
2182
2183
2184 Schoenebeck Expires September 12, 2019 [Page 39]
2185
2186 Internet-Draft LinuxSampler Control Protocol March 2019
2187
2188
2189 either true or false, defines if this parameter allows only one
2190 value or a list of values, where true means multiple values and
2191 false only a single value allowed (always returned)
2192
2193 RANGE_MIN -
2194
2195 defines lower limit of the allowed value range for this
2196 parameter, can be an integer value as well as a dotted number,
2197 this parameter is usually used in conjunction with 'RANGE_MAX'
2198 but may also appear without (optionally returned, dependent to
2199 driver and port parameter)
2200
2201 RANGE_MAX -
2202
2203 defines upper limit of the allowed value range for this
2204 parameter, can be an integer value as well as a dotted number,
2205 this parameter is usually used in conjunction with 'RANGE_MIN'
2206 but may also appear without (optionally returned, dependent to
2207 driver and port parameter)
2208
2209 POSSIBILITIES -
2210
2211 comma separated list of possible values for this parameter,
2212 character strings are encapsulated into apostrophes (optionally
2213 returned, dependent to device and port parameter)
2214
2215 The mentioned fields above don't have to be in particular order.
2216
2217 Example:
2218
2219 C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"
2220
2221 S: "DESCRIPTION: bindings to other ALSA sequencer clients"
2222
2223 "TYPE: STRING"
2224
2225 "FIX: false"
2226
2227 "MULTIPLICITY: true"
2228
2229 "POSSIBILITIES: '64:0','68:0','68:1'"
2230
2231 "."
2232
2233
2234
2235
2236
2237
2238
2239
2240 Schoenebeck Expires September 12, 2019 [Page 40]
2241
2242 Internet-Draft LinuxSampler Control Protocol March 2019
2243
2244
2245 6.3.13. Changing settings of MIDI input ports
2246
2247 Use the following command to alter a specific setting of a MIDI input
2248 port:
2249
2250 SET MIDI_INPUT_PORT_PARAMETER <device-id> <port> <key>=<value>
2251
2252 Where <device-id> should be replaced by the numerical ID of the MIDI
2253 device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5)
2254 or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command, <port> by the
2255 MIDI port number, <key> by the name of the parameter to change and
2256 <value> by the new value for this parameter (encapsulated into
2257 apostrophes) or NONE (not encapsulated into apostrophes) for
2258 specifying no value for parameters allowing a list of values.
2259
2260 Possible Answers:
2261
2262 "OK" -
2263
2264 in case setting was successfully changed
2265
2266 "WRN:<warning-code>:<warning-message>" -
2267
2268 in case setting was changed successfully, but there are
2269 noteworthy issue(s) related, providing an appropriate warning
2270 code and warning message
2271
2272 "ERR:<error-code>:<error-message>" -
2273
2274 in case it failed, providing an appropriate error code and
2275 error message
2276
2277 Example:
2278
2279 C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='20:0'"
2280
2281 S: "OK"
2282
2283 C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE"
2284
2285 S: "OK"
2286
2287 6.4. Configuring sampler channels
2288
2289 The following commands describe how to add and remove sampler
2290 channels, associate a sampler channel with a sampler engine, load
2291 instruments and connect sampler channels to MIDI and audio devices.
2292
2293
2294
2295
2296 Schoenebeck Expires September 12, 2019 [Page 41]
2297
2298 Internet-Draft LinuxSampler Control Protocol March 2019
2299
2300
2301 6.4.1. Loading an instrument
2302
2303 An instrument file can be loaded and assigned to a sampler channel by
2304 one of the following commands:
2305
2306 LOAD INSTRUMENT [NON_MODAL] '<filename>' <instr-index> <sampler-
2307 channel>
2308
2309 Where <filename> is the name of the instrument file on the
2310 LinuxSampler instance's host system, <instr-index> the index of the
2311 instrument in the instrument file and <sampler-channel> is the number
2312 of the sampler channel the instrument should be assigned to. Each
2313 sampler channel can only have one instrument.
2314
2315 Notice: since LSCP 1.2 the <filename> argument supports escape
2316 characters for special characters (see chapter "Character Set and
2317 Escape Sequences (Section 7.1)" for details) and accordingly
2318 backslash characters in the filename MUST now be escaped as well!
2319
2320 The difference between regular and NON_MODAL versions of the command
2321 is that the regular command returns OK only after the instrument has
2322 been fully loaded and the channel is ready to be used while NON_MODAL
2323 version returns immediately and a background process is launched to
2324 load the instrument on the channel. The GET CHANNEL INFO
2325 (Section 6.4.10) command can be used to obtain loading progress from
2326 INSTRUMENT_STATUS field. LOAD command will perform sanity checks
2327 such as making sure that the file could be read and it is of a proper
2328 format and SHOULD return ERR and SHOULD not launch the background
2329 process should any errors be detected at that point.
2330
2331 Possible Answers:
2332
2333 "OK" -
2334
2335 in case the instrument was successfully loaded
2336
2337 "WRN:<warning-code>:<warning-message>" -
2338
2339 in case the instrument was loaded successfully, but there are
2340 noteworthy issue(s) related (e.g. Engine doesn't support one
2341 or more patch parameters provided by the loaded instrument
2342 file), providing an appropriate warning code and warning
2343 message
2344
2345 "ERR:<error-code>:<error-message>" -
2346
2347 in case it failed, providing an appropriate error code and
2348 error message
2349
2350
2351
2352 Schoenebeck Expires September 12, 2019 [Page 42]
2353
2354 Internet-Draft LinuxSampler Control Protocol March 2019
2355
2356
2357 Example (Unix):
2358
2359 C: LOAD INSTRUMENT '/home/joe/gigs/cello.gig' 0 0
2360
2361 S: OK
2362
2363 Example (Windows):
2364
2365 C: LOAD INSTRUMENT 'D:/MySounds/cello.gig' 0 0
2366
2367 S: OK
2368
2369 6.4.2. Loading a sampler engine
2370
2371 A sampler engine type can be associated to a specific sampler channel
2372 by the following command:
2373
2374 LOAD ENGINE <engine-name> <sampler-channel>
2375
2376 Where <engine-name> is an engine name as obtained by the "LIST
2377 AVAILABLE_ENGINES" (Section 6.4.8) command and <sampler-channel> the
2378 sampler channel as returned by the "ADD CHANNEL" (Section 6.4.5) or
2379 "LIST CHANNELS" (Section 6.4.4) command where the engine type should
2380 be assigned to. This command should be issued after adding a new
2381 sampler channel and before any other control commands on the new
2382 sampler channel. It can also be used to change the engine type of a
2383 sampler channel. This command has (currently) no way to define or
2384 force if a new engine instance should be created and assigned to the
2385 given sampler channel or if an already existing instance of that
2386 engine type, shared with other sampler channels, should be used.
2387
2388 Possible Answers:
2389
2390 "OK" -
2391
2392 in case the engine was successfully deployed
2393
2394 "WRN:<warning-code>:<warning-message>" -
2395
2396 in case the engine was deployed successfully, but there are
2397 noteworthy issue(s) related, providing an appropriate warning
2398 code and warning message
2399
2400 "ERR:<error-code>:<error-message>" -
2401
2402 in case it failed, providing an appropriate error code and
2403 error message
2404
2405
2406
2407
2408 Schoenebeck Expires September 12, 2019 [Page 43]
2409
2410 Internet-Draft LinuxSampler Control Protocol March 2019
2411
2412
2413 Example:
2414
2415
2416
2417 6.4.3. Getting all created sampler channel count
2418
2419 The number of sampler channels can change on runtime. To get the
2420 current amount of sampler channels, the front-end can send the
2421 following command:
2422
2423 GET CHANNELS
2424
2425 Possible Answers:
2426
2427 LinuxSampler will answer by returning the current number of
2428 sampler channels.
2429
2430 Example:
2431
2432 C: "GET CHANNELS"
2433
2434 S: "12"
2435
2436 6.4.4. Getting all created sampler channel list
2437
2438 The number of sampler channels can change on runtime. To get the
2439 current list of sampler channels, the front-end can send the
2440 following command:
2441
2442 LIST CHANNELS
2443
2444 Possible Answers:
2445
2446 LinuxSampler will answer by returning a comma separated list with
2447 all sampler channels numerical IDs.
2448
2449 Example:
2450
2451 C: "LIST CHANNELS"
2452
2453 S: "0,1,2,3,4,5,6,9,10,11,15,20"
2454
2455 6.4.5. Adding a new sampler channel
2456
2457 A new sampler channel can be added to the end of the sampler channel
2458 list by sending the following command:
2459
2460 ADD CHANNEL
2461
2462
2463
2464 Schoenebeck Expires September 12, 2019 [Page 44]
2465
2466 Internet-Draft LinuxSampler Control Protocol March 2019
2467
2468
2469 This will increment the sampler channel count by one and the new
2470 sampler channel will be appended to the end of the sampler channel
2471 list. The front-end should send the respective, related commands
2472 right after to e.g. load an engine, load an instrument and setting
2473 input, output method and eventually other commands to initialize the
2474 new channel. The front-end should use the sampler channel returned
2475 by the answer of this command to perform the previously recommended
2476 commands, to avoid race conditions e.g. with other front-ends that
2477 might also have sent an "ADD CHANNEL" command.
2478
2479 Possible Answers:
2480
2481 "OK[<sampler-channel>]" -
2482
2483 in case a new sampler channel could be added, where <sampler-
2484 channel> reflects the channel number of the new created sampler
2485 channel which should be used to set up the sampler channel by
2486 sending subsequent initialization commands
2487
2488 "WRN:<warning-code>:<warning-message>" -
2489
2490 in case a new channel was added successfully, but there are
2491 noteworthy issue(s) related, providing an appropriate warning
2492 code and warning message
2493
2494 "ERR:<error-code>:<error-message>" -
2495
2496 in case it failed, providing an appropriate error code and
2497 error message
2498
2499 Example:
2500
2501
2502
2503 6.4.6. Removing a sampler channel
2504
2505 A sampler channel can be removed by sending the following command:
2506
2507 REMOVE CHANNEL <sampler-channel>
2508
2509 Where <sampler-channel> should be replaced by the number of the
2510 sampler channel as given by the "ADD CHANNEL" (Section 6.4.5) or
2511 "LIST CHANNELS" (Section 6.4.4) command. The channel numbers of all
2512 subsequent sampler channels remain the same.
2513
2514 Possible Answers:
2515
2516 "OK" -
2517
2518
2519
2520 Schoenebeck Expires September 12, 2019 [Page 45]
2521
2522 Internet-Draft LinuxSampler Control Protocol March 2019
2523
2524
2525 in case the given sampler channel could be removed
2526
2527 "WRN:<warning-code>:<warning-message>" -
2528
2529 in case the given channel was removed, but there are noteworthy
2530 issue(s) related, providing an appropriate warning code and
2531 warning message
2532
2533 "ERR:<error-code>:<error-message>" -
2534
2535 in case it failed, providing an appropriate error code and
2536 error message
2537
2538 Example:
2539
2540
2541
2542 6.4.7. Getting amount of available engines
2543
2544 The front-end can ask for the number of available engines by sending
2545 the following command:
2546
2547 GET AVAILABLE_ENGINES
2548
2549 Possible Answers:
2550
2551 LinuxSampler will answer by sending the number of available
2552 engines.
2553
2554 Example:
2555
2556 C: "GET AVAILABLE_ENGINES"
2557
2558 S: "4"
2559
2560 6.4.8. Getting all available engines
2561
2562 The front-end can ask for a list of all available engines by sending
2563 the following command:
2564
2565 LIST AVAILABLE_ENGINES
2566
2567 Possible Answers:
2568
2569 LinuxSampler will answer by sending a comma separated list of the
2570 engines' names encapsulated into apostrophes ('). Engine names
2571 can consist of lower and upper cases, digits and underlines ("_"
2572 character).
2573
2574
2575
2576 Schoenebeck Expires September 12, 2019 [Page 46]
2577
2578 Internet-Draft LinuxSampler Control Protocol March 2019
2579
2580
2581 Example:
2582
2583 C: "LIST AVAILABLE_ENGINES"
2584
2585 S: "'gig','sfz','sf2'"
2586
2587 6.4.9. Getting information about an engine
2588
2589 The front-end can ask for information about a specific engine by
2590 sending the following command:
2591
2592 GET ENGINE INFO <engine-name>
2593
2594 Where <engine-name> is an engine name as obtained by the "LIST
2595 AVAILABLE_ENGINES" (Section 6.4.8) command.
2596
2597 Possible Answers:
2598
2599 LinuxSampler will answer by sending a <CRLF> separated list. Each
2600 answer line begins with the information category name followed by
2601 a colon and then a space character <SP> and finally the info
2602 character string to that info category. At the moment the
2603 following categories are defined:
2604
2605
2606
2607 DESCRIPTION -
2608
2609 arbitrary description text about the engine (note that the
2610 character string may contain escape sequences (Section 7.1))
2611
2612 VERSION -
2613
2614 arbitrary character string regarding the engine's version
2615
2616 The mentioned fields above don't have to be in particular order.
2617
2618 Examples:
2619
2620 C: "GET ENGINE INFO gig"
2621
2622 S: "DESCRIPTION: GigaSampler Format Engine"
2623
2624 "VERSION: 1.110"
2625
2626 "."
2627
2628 C: "GET ENGINE INFO sf2"
2629
2630
2631
2632 Schoenebeck Expires September 12, 2019 [Page 47]
2633
2634 Internet-Draft LinuxSampler Control Protocol March 2019
2635
2636
2637 S: "DESCRIPTION: SoundFont Format Engine"
2638
2639 "VERSION: 1.4"
2640
2641 "."
2642
2643 C: "GET ENGINE INFO sfz"
2644
2645 S: "DESCRIPTION: SFZ Format Engine"
2646
2647 "VERSION: 1.11"
2648
2649 "."
2650
2651 6.4.10. Getting sampler channel information
2652
2653 The front-end can ask for the current settings of a sampler channel
2654 by sending the following command:
2655
2656 GET CHANNEL INFO <sampler-channel>
2657
2658 Where <sampler-channel> is the sampler channel number the front-end
2659 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2660 "LIST CHANNELS" (Section 6.4.4) command.
2661
2662 Possible Answers:
2663
2664 LinuxSampler will answer by sending a <CRLF> separated list. Each
2665 answer line begins with the settings category name followed by a
2666 colon and then a space character <SP> and finally the info
2667 character string to that setting category. At the moment the
2668 following categories are defined:
2669
2670
2671
2672 ENGINE_NAME -
2673
2674 name of the engine that is associated with the sampler
2675 channel, "NONE" if there's no engine associated yet for this
2676 sampler channel
2677
2678 AUDIO_OUTPUT_DEVICE -
2679
2680 numerical ID of the audio output device which is currently
2681 connected to this sampler channel to output the audio
2682 signal, "-1" if there's no device connected to this sampler
2683 channel
2684
2685
2686
2687
2688 Schoenebeck Expires September 12, 2019 [Page 48]
2689
2690 Internet-Draft LinuxSampler Control Protocol March 2019
2691
2692
2693 AUDIO_OUTPUT_CHANNELS -
2694
2695 number of output channels the sampler channel offers
2696 (dependent to used sampler engine and loaded instrument)
2697
2698 AUDIO_OUTPUT_ROUTING -
2699
2700 comma separated list which reflects to which audio channel
2701 of the selected audio output device each sampler output
2702 channel is routed to, e.g. "0,3" would mean the engine's
2703 output channel 0 is routed to channel 0 of the audio output
2704 device and the engine's output channel 1 is routed to the
2705 channel 3 of the audio output device
2706
2707 INSTRUMENT_FILE -
2708
2709 the file name of the loaded instrument, "NONE" if there's no
2710 instrument yet loaded for this sampler channel (note: since
2711 LSCP 1.2 this path may contain escape sequences
2712 (Section 7.1))
2713
2714 INSTRUMENT_NR -
2715
2716 the instrument index number of the loaded instrument, "-1"
2717 if there's no instrument loaded for this sampler channel
2718
2719 INSTRUMENT_NAME -
2720
2721 the instrument name of the loaded instrument (note: since
2722 LSCP 1.2 this character string may contain escape sequences
2723 (Section 7.1))
2724
2725 INSTRUMENT_STATUS -
2726
2727 Integer values 0 to 100 indicating loading progress
2728 percentage for the instrument. Negative value indicates a
2729 loading exception (also returns "-1" in case no instrument
2730 was yet to be loaded on the sampler channel). Value of 100
2731 indicates that the instrument is fully loaded.
2732
2733 MIDI_INPUT_DEVICE -
2734
2735 DEPRECATED: THIS FIELD WILL DISAPPEAR!
2736
2737 numerical ID of the MIDI input device which is currently
2738 connected to this sampler channel to deliver MIDI input
2739 commands, "-1" if there's no device connected to this
2740 sampler channel
2741
2742
2743
2744 Schoenebeck Expires September 12, 2019 [Page 49]
2745
2746 Internet-Draft LinuxSampler Control Protocol March 2019
2747
2748
2749 Should not be used anymore as of LSCP v1.6 and younger.
2750 This field is currently only preserved for backward
2751 compatibility.
2752
2753 This field a relict from times where only one MIDI input per
2754 sampler channel was allowed. Use "GET CHANNEL MIDI_INPUTS"
2755 (Section 6.4.19) instead.
2756
2757 MIDI_INPUT_PORT -
2758
2759 DEPRECATED: THIS FIELD WILL DISAPPEAR!
2760
2761 port number of the MIDI input device (in case a MIDI device
2762 was already assigned to the sampler channel)
2763
2764 Should not be used anymore as of LSCP v1.6 and younger.
2765 This field is currently only preserved for backward
2766 compatibility.
2767
2768 This field a relict from times where only one MIDI input per
2769 sampler channel was allowed. Use "GET CHANNEL MIDI_INPUTS"
2770 (Section 6.4.19) instead.
2771
2772 MIDI_INPUT_CHANNEL -
2773
2774 the MIDI input channel number this sampler channel should
2775 listen to or "ALL" to listen on all MIDI channels
2776
2777 VOLUME -
2778
2779 optionally dotted number for the channel volume factor
2780 (where a value < 1.0 means attenuation and a value > 1.0
2781 means amplification)
2782
2783 MUTE -
2784
2785 Determines whether the channel is muted, "true" if the
2786 channel is muted, "false" if the channel is not muted, and
2787 "MUTED_BY_SOLO" if the channel is muted because of the
2788 presence of a solo channel and will be unmuted when there
2789 are no solo channels left
2790
2791 SOLO -
2792
2793 Determines whether this is a solo channel, "true" if the
2794 channel is a solo channel; "false" otherwise
2795
2796 MIDI_INSTRUMENT_MAP -
2797
2798
2799
2800 Schoenebeck Expires September 12, 2019 [Page 50]
2801
2802 Internet-Draft LinuxSampler Control Protocol March 2019
2803
2804
2805 Determines to which MIDI instrument map this sampler channel
2806 is assigned to. Read chapter "SET CHANNEL
2807 MIDI_INSTRUMENT_MAP" (Section 6.4.27) for a list of possible
2808 values.
2809
2810 The mentioned fields above don't have to be in particular order.
2811
2812 Example:
2813
2814 C: "GET CHANNEL INFO 34"
2815
2816 S: "ENGINE_NAME: gig"
2817
2818 "VOLUME: 1.0"
2819
2820 "AUDIO_OUTPUT_DEVICE: 0"
2821
2822 "AUDIO_OUTPUT_CHANNELS: 2"
2823
2824 "AUDIO_OUTPUT_ROUTING: 0,1"
2825
2826 "INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"
2827
2828 "INSTRUMENT_NR: 0"
2829
2830 "INSTRUMENT_NAME: Fazioli Piano"
2831
2832 "INSTRUMENT_STATUS: 100"
2833
2834 "MIDI_INPUT_DEVICE: 0"
2835
2836 "MIDI_INPUT_PORT: 0"
2837
2838 "MIDI_INPUT_CHANNEL: 5"
2839
2840 "VOLUME: 1.0"
2841
2842 "MUTE: false"
2843
2844 "SOLO: false"
2845
2846 "MIDI_INSTRUMENT_MAP: NONE"
2847
2848 "."
2849
2850
2851
2852
2853
2854
2855
2856 Schoenebeck Expires September 12, 2019 [Page 51]
2857
2858 Internet-Draft LinuxSampler Control Protocol March 2019
2859
2860
2861 6.4.11. Current number of active voices
2862
2863 The front-end can ask for the current number of active voices on a
2864 sampler channel by sending the following command:
2865
2866 GET CHANNEL VOICE_COUNT <sampler-channel>
2867
2868 Where <sampler-channel> is the sampler channel number the front-end
2869 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2870 "LIST CHANNELS" (Section 6.4.4) command.
2871
2872 Possible Answers:
2873
2874 LinuxSampler will answer by returning the number of active voices
2875 on that channel.
2876
2877 Example:
2878
2879
2880
2881 6.4.12. Current number of active disk streams
2882
2883 The front-end can ask for the current number of active disk streams
2884 on a sampler channel by sending the following command:
2885
2886 GET CHANNEL STREAM_COUNT <sampler-channel>
2887
2888 Where <sampler-channel> is the sampler channel number the front-end
2889 is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
2890 "LIST CHANNELS" (Section 6.4.4) command.
2891
2892 Possible Answers:
2893
2894 LinuxSampler will answer by returning the number of active disk
2895 streams on that channel in case the engine supports disk
2896 streaming, if the engine doesn't support disk streaming it will
2897 return "NA" for not available.
2898
2899 Example:
2900
2901
2902
2903 6.4.13. Current fill state of disk stream buffers
2904
2905 The front-end can ask for the current fill state of all disk streams
2906 on a sampler channel by sending the following command:
2907
2908 GET CHANNEL BUFFER_FILL BYTES <sampler-channel>
2909
2910
2911
2912 Schoenebeck Expires September 12, 2019 [Page 52]
2913
2914 Internet-Draft LinuxSampler Control Protocol March 2019
2915
2916
2917 to get the fill state in bytes or
2918
2919 GET CHANNEL BUFFER_FILL PERCENTAGE <sampler-channel>
2920
2921 to get the fill state in percent, where <sampler-channel> is the
2922 sampler channel number the front-end is interested in as returned by
2923 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
2924 command.
2925
2926 Possible Answers:
2927
2928 LinuxSampler will either answer by returning a comma separated
2929 string with the fill state of all disk stream buffers on that
2930 channel or an empty line if there are no active disk streams or
2931 "NA" for *not available* in case the engine which is deployed
2932 doesn't support disk streaming. Each entry in the answer list
2933 will begin with the stream's ID in brackets followed by the
2934 numerical representation of the fill size (either in bytes or
2935 percentage). Note: due to efficiency reasons the fill states in
2936 the response are not in particular order, thus the front-end has
2937 to sort them by itself if necessary.
2938
2939 Examples:
2940
2941 C: "GET CHANNEL BUFFER_FILL BYTES 4"
2942
2943 S: "[115]420500,[116]510300,[75]110000,[120]230700"
2944
2945 C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
2946
2947 S: "[115]90%,[116]98%,[75]40%,[120]62%"
2948
2949 C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
2950
2951 S: ""
2952
2953 6.4.14. Setting audio output device
2954
2955 The front-end can set the audio output device on a specific sampler
2956 channel by sending the following command:
2957
2958 SET CHANNEL AUDIO_OUTPUT_DEVICE <sampler-channel> <audio-device-
2959 id>
2960
2961 Where <sampler-channel> is the respective sampler channel number as
2962 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
2963 (Section 6.4.4) command and <audio-device-id> is the numerical ID of
2964 the audio output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
2965
2966
2967
2968 Schoenebeck Expires September 12, 2019 [Page 53]
2969
2970 Internet-Draft LinuxSampler Control Protocol March 2019
2971
2972
2973 (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
2974 command.
2975
2976 Possible Answers:
2977
2978 "OK" -
2979
2980 on success
2981
2982 "WRN:<warning-code>:<warning-message>" -
2983
2984 if audio output device was set, but there are noteworthy
2985 issue(s) related, providing an appropriate warning code and
2986 warning message
2987
2988 "ERR:<error-code>:<error-message>" -
2989
2990 in case it failed, providing an appropriate error code and
2991 error message
2992
2993 Examples:
2994
2995
2996
2997 6.4.15. Setting audio output type
2998
2999 DEPRECATED: THIS COMMAND WILL DISAPPEAR!
3000
3001 The front-end can alter the audio output type on a specific sampler
3002 channel by sending the following command:
3003
3004 SET CHANNEL AUDIO_OUTPUT_TYPE <sampler-channel> <audio-output-
3005 type>
3006
3007 Where <audio-output-type> is currently either "ALSA" or "JACK" and
3008 <sampler-channel> is the respective sampler channel number.
3009
3010 Possible Answers:
3011
3012 "OK" -
3013
3014 on success
3015
3016 "WRN:<warning-code>:<warning-message>" -
3017
3018 if audio output type was set, but there are noteworthy issue(s)
3019 related, providing an appropriate warning code and warning
3020 message
3021
3022
3023
3024 Schoenebeck Expires September 12, 2019 [Page 54]
3025
3026 Internet-Draft LinuxSampler Control Protocol March 2019
3027
3028
3029 "ERR:<error-code>:<error-message>" -
3030
3031 in case it failed, providing an appropriate error code and
3032 error message
3033
3034 Examples:
3035
3036
3037
3038 Deprecated:
3039
3040 Should not be used anymore. This command is currently only
3041 preserved for backward compatibility.
3042
3043 This command is a relict from times where there was no
3044 sophisticated driver management yet. Use "CREATE
3045 AUDIO_OUTPUT_DEVICE" (Section 6.2.5) and "SET CHANNEL
3046 AUDIO_OUTPUT_DEVICE" (Section 6.4.14) instead.
3047
3048 6.4.16. Setting audio output channel
3049
3050 The front-end can alter the audio output channel on a specific
3051 sampler channel by sending the following command:
3052
3053 SET CHANNEL AUDIO_OUTPUT_CHANNEL <sampler-chan> <audio-out>
3054 <audio-in>
3055
3056 Where <sampler-chan> is the sampler channel number as returned by the
3057 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3058 command, <audio-out> is the numerical ID of the sampler channel's
3059 audio output channel which should be rerouted and <audio-in> is the
3060 numerical ID of the audio channel of the selected audio output device
3061 where <audio-out> should be routed to.
3062
3063 Possible Answers:
3064
3065 "OK" -
3066
3067 on success
3068
3069 "WRN:<warning-code>:<warning-message>" -
3070
3071 if audio output channel was set, but there are noteworthy
3072 issue(s) related, providing an appropriate warning code and
3073 warning message
3074
3075 "ERR:<error-code>:<error-message>" -
3076
3077
3078
3079
3080 Schoenebeck Expires September 12, 2019 [Page 55]
3081
3082 Internet-Draft LinuxSampler Control Protocol March 2019
3083
3084
3085 in case it failed, providing an appropriate error code and
3086 error message
3087
3088 Examples:
3089
3090
3091
3092 6.4.17. Add MIDI input to sampler channel
3093
3094 The front-end can add a MIDI input on a specific sampler channel by
3095 sending the following command:
3096
3097 ADD CHANNEL MIDI_INPUT <sampler-channel> <midi-device-id> [<midi-
3098 input-port>]
3099
3100 Where <sampler-channel> is the sampler channel number as returned by
3101 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3102 command and <midi-device-id> is the numerical ID of the MIDI input
3103 device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5)
3104 or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command, and <midi-
3105 input-port> is an optional MIDI input port number of that MIDI input
3106 device. If <midi-input-port> is omitted, then the MIDI input
3107 device's first port (port number 0) is used.
3108
3109 Possible Answers:
3110
3111 "OK" -
3112
3113 on success
3114
3115 "WRN:<warning-code>:<warning-message>" -
3116
3117 if MIDI input port was connected, but there are noteworthy
3118 issue(s) related, providing an appropriate warning code and
3119 warning message
3120
3121 "ERR:<error-code>:<error-message>" -
3122
3123 in case it failed, providing an appropriate error code and
3124 error message
3125
3126 Examples:
3127
3128 C: "ADD CHANNEL MIDI_INPUT 0 0"
3129
3130 S: "OK"
3131
3132 C: "ADD CHANNEL MIDI_INPUT 1 0"
3133
3134
3135
3136 Schoenebeck Expires September 12, 2019 [Page 56]
3137
3138 Internet-Draft LinuxSampler Control Protocol March 2019
3139
3140
3141 S: "OK"
3142
3143 C: "ADD CHANNEL MIDI_INPUT 1 1 1"
3144
3145 S: "OK"
3146
3147 C: "ADD CHANNEL MIDI_INPUT 1 2 0"
3148
3149 S: "OK"
3150
3151 Since:
3152
3153 Introduced with LSCP v1.6
3154
3155 6.4.18. Remove MIDI input(s) from sampler channel
3156
3157 The front-end can remove one ore more MIDI input(s) on a specific
3158 sampler channel by sending the following command:
3159
3160 REMOVE CHANNEL MIDI_INPUT <sampler-channel> [<midi-device-id>
3161 [<midi-input-port>]]
3162
3163 Where <sampler-channel> is the sampler channel number as returned by
3164 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3165 command and <midi-device-id> and <midi-input-port> are optional
3166 numerical IDs defining the MIDI input device and one of its MIDI
3167 ports as returned by the "LIST CHANNEL MIDI_INPUTS" (Section 6.4.19)
3168 command.
3169
3170 If <midi-input-port> is omitted, then all MIDI input ports of <midi-
3171 device-id> are disconnected from this sampler channel.
3172
3173 If both, <midi-device-id> and <midi-input-port> are omitted, then all
3174 MIDI input ports currently connected to this sampler channel are
3175 disconnected from this sampler channel.
3176
3177 Possible Answers:
3178
3179 "OK" -
3180
3181 on success
3182
3183 "WRN:<warning-code>:<warning-message>" -
3184
3185 if MIDI input porst were disconnected, but there are noteworthy
3186 issue(s) related, providing an appropriate warning code and
3187 warning message
3188
3189
3190
3191
3192 Schoenebeck Expires September 12, 2019 [Page 57]
3193
3194 Internet-Draft LinuxSampler Control Protocol March 2019
3195
3196
3197 "ERR:<error-code>:<error-message>" -
3198
3199 in case it failed, providing an appropriate error code and
3200 error message
3201
3202 Examples:
3203
3204 C: "REMOVE CHANNEL MIDI_INPUT 0"
3205
3206 S: "OK"
3207
3208 C: "REMOVE CHANNEL MIDI_INPUT 1"
3209
3210 S: "OK"
3211
3212 C: "REMOVE CHANNEL MIDI_INPUT 1 2 0"
3213
3214 S: "OK"
3215
3216 Since:
3217
3218 Introduced with LSCP v1.6
3219
3220 6.4.19. Getting all MIDI inputs of a sampler channel
3221
3222 The front-end can query a list of all currently connected MIDI inputs
3223 of a certain sampler channel by sending the following command:
3224
3225 LIST CHANNEL MIDI_INPUTS <sampler-channel>
3226
3227 Where <sampler-channel> is the sampler channel number as returned by
3228 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3229 command.
3230
3231 Possible Answers:
3232
3233 The sampler will answer by sending a comma separated list of MIDI
3234 input device ID - MIDI input port number pairs, where each pair is
3235 encapsulated into curly braces. The list is returned in one
3236 single line. The MIDI input device ID corresponds to the number
3237 returned by "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) and the port
3238 number is the index of the respective MIDI port of that MIDI input
3239 device.
3240
3241 Example:
3242
3243 C: "LIST CHANNEL MIDI_INPUTS 0"
3244
3245
3246
3247
3248 Schoenebeck Expires September 12, 2019 [Page 58]
3249
3250 Internet-Draft LinuxSampler Control Protocol March 2019
3251
3252
3253 S: "{0,0},{1,3},{2,0}"
3254
3255 Since:
3256
3257 Introduced with LSCP v1.6
3258
3259 6.4.20. Setting MIDI input device
3260
3261 DEPRECATED: THIS COMMAND WILL DISAPPEAR!
3262
3263 The front-end can set the MIDI input device on a specific sampler
3264 channel by sending the following command:
3265
3266 SET CHANNEL MIDI_INPUT_DEVICE <sampler-channel> <midi-device-id>
3267
3268 Where <sampler-channel> is the sampler channel number as returned by
3269 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3270 command and <midi-device-id> is the numerical ID of the MIDI input
3271 device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5)
3272 or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command.
3273
3274 If more than 1 MIDI inputs are currently connected to this sampler
3275 channel: Sending this command will disconnect ALL currently connected
3276 MIDI input ports connected to this sampler channel before
3277 establishing the new MIDI input connection. So this command does NOT
3278 add the connection, it replaces all existing ones instead. This
3279 behavior is due to preserving full behavior backward compatibility.
3280
3281 Possible Answers:
3282
3283 "OK" -
3284
3285 on success
3286
3287 "WRN:<warning-code>:<warning-message>" -
3288
3289 if MIDI input device was set, but there are noteworthy issue(s)
3290 related, providing an appropriate warning code and warning
3291 message
3292
3293 "ERR:<error-code>:<error-message>" -
3294
3295 in case it failed, providing an appropriate error code and
3296 error message
3297
3298 Examples:
3299
3300
3301
3302
3303
3304 Schoenebeck Expires September 12, 2019 [Page 59]
3305
3306 Internet-Draft LinuxSampler Control Protocol March 2019
3307
3308
3309 Deprecated:
3310
3311 Should not be used anymore as of LSCP v1.6 and younger. This
3312 command is currently only preserved for backward compatibility.
3313
3314 This command is a relict from times where only one MIDI input per
3315 sampler channel was allowed. Use "ADD CHANNEL MIDI_INPUT"
3316 (Section 6.4.17) and "REMOVE CHANNEL MIDI_INPUT" (Section 6.4.18)
3317 instead.
3318
3319 6.4.21. Setting MIDI input type
3320
3321 DEPRECATED: THIS COMMAND WILL DISAPPEAR!
3322
3323 The front-end can alter the MIDI input type on a specific sampler
3324 channel by sending the following command:
3325
3326 SET CHANNEL MIDI_INPUT_TYPE <sampler-channel> <midi-input-type>
3327
3328 Where <midi-input-type> is currently only "ALSA" and <sampler-
3329 channel> is the respective sampler channel number.
3330
3331 If more than 1 MIDI inputs are currently connected to this sampler
3332 channel: Sending this command will disconnect ALL currently connected
3333 MIDI input ports connected to this sampler channel before
3334 establishing the new MIDI input connection. So this command does NOT
3335 add the connection, it replaces all existing ones instead. This
3336 behavior is due to preserving full behavior backward compatibility.
3337
3338 Possible Answers:
3339
3340 "OK" -
3341
3342 on success
3343
3344 "WRN:<warning-code>:<warning-message>" -
3345
3346 if MIDI input type was set, but there are noteworthy issue(s)
3347 related, providing an appropriate warning code and warning
3348 message
3349
3350 "ERR:<error-code>:<error-message>" -
3351
3352 in case it failed, providing an appropriate error code and
3353 error message
3354
3355 Examples:
3356
3357
3358
3359
3360 Schoenebeck Expires September 12, 2019 [Page 60]
3361
3362 Internet-Draft LinuxSampler Control Protocol March 2019
3363
3364
3365 Deprecated:
3366
3367 Should not be used anymore. This command is currently only
3368 preserved for backward compatibility.
3369
3370 This command is a relict from times where only 1 MIDI input per
3371 sampler channels was allowed and where no sophisticated driver
3372 management existed yet. Use "ADD CHANNEL MIDI_INPUT"
3373 (Section 6.4.17) and "REMOVE CHANNEL MIDI_INPUT" (Section 6.4.18)
3374 instead.
3375
3376 6.4.22. Setting MIDI input port
3377
3378 DEPRECATED: THIS COMMAND WILL DISAPPEAR!
3379
3380 The front-end can alter the MIDI input port on a specific sampler
3381 channel by sending the following command:
3382
3383 SET CHANNEL MIDI_INPUT_PORT <sampler-channel> <midi-input-port>
3384
3385 Where <midi-input-port> is a MIDI input port number of the MIDI input
3386 device connected to the sampler channel given by <sampler-channel>.
3387
3388 If more than 1 MIDI inputs are currently connected to this sampler
3389 channel: Sending this command will switch the connection of the first
3390 (and only the first) MIDI input port currently being connected to
3391 this sampler channel, to another port of the same MIDI input device.
3392 Or in other words: the first MIDI input port currently connected to
3393 this sampler channel will be disconnected, and the requested other
3394 port of its MIDI input device will be connected to this sampler
3395 channel instead. This behavior is due to preserving full behavior
3396 backward compatibility.
3397
3398 Possible Answers:
3399
3400 "OK" -
3401
3402 on success
3403
3404 "WRN:<warning-code>:<warning-message>" -
3405
3406 if MIDI input port was set, but there are noteworthy issue(s)
3407 related, providing an appropriate warning code and warning
3408 message
3409
3410 "ERR:<error-code>:<error-message>" -
3411
3412
3413
3414
3415
3416 Schoenebeck Expires September 12, 2019 [Page 61]
3417
3418 Internet-Draft LinuxSampler Control Protocol March 2019
3419
3420
3421 in case it failed, providing an appropriate error code and
3422 error message
3423
3424 Examples:
3425
3426
3427
3428 Deprecated:
3429
3430 Should not be used anymore. This command is currently only
3431 preserved for backward compatibility.
3432
3433 This command is a relict from times where only one MIDI input per
3434 sampler channel was allowed. Use "ADD CHANNEL MIDI_INPUT"
3435 (Section 6.4.17) and "REMOVE CHANNEL MIDI_INPUT" (Section 6.4.18)
3436 instead.
3437
3438 6.4.23. Setting MIDI input channel
3439
3440 The front-end can alter the MIDI channel a sampler channel should
3441 listen to by sending the following command:
3442
3443 SET CHANNEL MIDI_INPUT_CHANNEL <sampler-channel> <midi-input-chan>
3444
3445 Where <midi-input-chan> is the number of the new MIDI input channel
3446 (zero indexed!) where <sampler-channel> should listen to, or "ALL" to
3447 listen on all 16 MIDI channels.
3448
3449 Possible Answers:
3450
3451 "OK" -
3452
3453 on success
3454
3455 "WRN:<warning-code>:<warning-message>" -
3456
3457 if MIDI input channel was set, but there are noteworthy
3458 issue(s) related, providing an appropriate warning code and
3459 warning message
3460
3461 "ERR:<error-code>:<error-message>" -
3462
3463 in case it failed, providing an appropriate error code and
3464 error message
3465
3466 Examples:
3467
3468 C: "SET CHANNEL MIDI_INPUT_CHANNEL 0 0"
3469
3470
3471
3472 Schoenebeck Expires September 12, 2019 [Page 62]
3473
3474 Internet-Draft LinuxSampler Control Protocol March 2019
3475
3476
3477 S: "OK"
3478
3479 C: "SET CHANNEL MIDI_INPUT_CHANNEL 1 ALL"
3480
3481 S: "OK"
3482
3483 6.4.24. Setting channel volume
3484
3485 The front-end can alter the volume of a sampler channel by sending
3486 the following command:
3487
3488 SET CHANNEL VOLUME <sampler-channel> <volume>
3489
3490 Where <volume> is an optionally dotted positive number (a value
3491 smaller than 1.0 means attenuation, whereas a value greater than 1.0
3492 means amplification) and <sampler-channel> defines the sampler
3493 channel where this volume factor should be set.
3494
3495 Possible Answers:
3496
3497 "OK" -
3498
3499 on success
3500
3501 "WRN:<warning-code>:<warning-message>" -
3502
3503 if channel volume was set, but there are noteworthy issue(s)
3504 related, providing an appropriate warning code and warning
3505 message
3506
3507 "ERR:<error-code>:<error-message>" -
3508
3509 in case it failed, providing an appropriate error code and
3510 error message
3511
3512 Examples:
3513
3514
3515
3516 6.4.25. Muting a sampler channel
3517
3518 The front-end can mute/unmute a specific sampler channel by sending
3519 the following command:
3520
3521 SET CHANNEL MUTE <sampler-channel> <mute>
3522
3523 Where <sampler-channel> is the respective sampler channel number as
3524 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3525
3526
3527
3528 Schoenebeck Expires September 12, 2019 [Page 63]
3529
3530 Internet-Draft LinuxSampler Control Protocol March 2019
3531
3532
3533 (Section 6.4.4) command and <mute> should be replaced either by "1"
3534 to mute the channel or "0" to unmute the channel.
3535
3536 Possible Answers:
3537
3538 "OK" -
3539
3540 on success
3541
3542 "WRN:<warning-code>:<warning-message>" -
3543
3544 if the channel was muted/unmuted, but there are noteworthy
3545 issue(s) related, providing an appropriate warning code and
3546 warning message
3547
3548 "ERR:<error-code>:<error-message>" -
3549
3550 in case it failed, providing an appropriate error code and
3551 error message
3552
3553 Examples:
3554
3555
3556
3557 6.4.26. Soloing a sampler channel
3558
3559 The front-end can solo/unsolo a specific sampler channel by sending
3560 the following command:
3561
3562 SET CHANNEL SOLO <sampler-channel> <solo>
3563
3564 Where <sampler-channel> is the respective sampler channel number as
3565 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3566 (Section 6.4.4) command and <solo> should be replaced either by "1"
3567 to solo the channel or "0" to unsolo the channel.
3568
3569 Possible Answers:
3570
3571 "OK" -
3572
3573 on success
3574
3575 "WRN:<warning-code>:<warning-message>" -
3576
3577 if the channel was soloed/unsoloed, but there are noteworthy
3578 issue(s) related, providing an appropriate warning code and
3579 warning message
3580
3581
3582
3583
3584 Schoenebeck Expires September 12, 2019 [Page 64]
3585
3586 Internet-Draft LinuxSampler Control Protocol March 2019
3587
3588
3589 "ERR:<error-code>:<error-message>" -
3590
3591 in case it failed, providing an appropriate error code and
3592 error message
3593
3594 Examples:
3595
3596
3597
3598 6.4.27. Assigning a MIDI instrument map to a sampler channel
3599
3600 The front-end can assign a MIDI instrument map to a specific sampler
3601 channel by sending the following command:
3602
3603 SET CHANNEL MIDI_INSTRUMENT_MAP <sampler-channel> <map>
3604
3605 Where <sampler-channel> is the respective sampler channel number as
3606 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3607 (Section 6.4.4) command and <map> can have the following
3608 possibilites:
3609
3610 "NONE" -
3611
3612 This is the default setting. In this case the sampler channel
3613 is not assigned any MIDI instrument map and thus will ignore
3614 all MIDI program change messages.
3615
3616 "DEFAULT" -
3617
3618 The sampler channel will always use the default MIDI instrument
3619 map to handle MIDI program change messages.
3620
3621 numeric ID -
3622
3623 You can assign a specific MIDI instrument map by replacing
3624 <map> with the respective numeric ID of the MIDI instrument map
3625 as returned by the "LIST MIDI_INSTRUMENT_MAPS" (Section 6.7.4)
3626 command. Once that map will be deleted, the sampler channel
3627 would fall back to "NONE".
3628
3629 Read chapter "MIDI Instrument Mapping" (Section 6.7) for details
3630 regarding MIDI instrument mapping.
3631
3632 Possible Answers:
3633
3634 "OK" -
3635
3636 on success
3637
3638
3639
3640 Schoenebeck Expires September 12, 2019 [Page 65]
3641
3642 Internet-Draft LinuxSampler Control Protocol March 2019
3643
3644
3645 "ERR:<error-code>:<error-message>" -
3646
3647 in case it failed, providing an appropriate error code and
3648 error message
3649
3650 Examples:
3651
3652
3653
3654 6.4.28. Adding an effect send to a sampler channel
3655
3656 The front-end can create an additional effect send on a specific
3657 sampler channel by sending the following command:
3658
3659 CREATE FX_SEND <sampler-channel> <midi-ctrl> [<name>]
3660
3661 Where <sampler-channel> is the respective sampler channel number as
3662 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3663 (Section 6.4.4) command, that is the sampler channel on which the
3664 effect send should be created on, <midi-ctrl> is a number between
3665 0..127 defining the MIDI controller which can alter the effect send
3666 level and <name> is an optional argument defining a name for the
3667 effect send entity. The name does not have to be unique, but MUST be
3668 encapsulated into apostrophes and supports escape sequences as
3669 described in chapter "Character Set and Escape Sequences
3670 (Section 7.1)".
3671
3672 Note: there are two possible approaches to apply audio effects with
3673 FX sends: you can either use a) internal effects or b) external
3674 effects. By default, that is as initial routing, effect sends are
3675 automatically routed directly to the sampler channel's audio output
3676 device and the effect send's audio channels are by default
3677 automatically routed to the last audio channels of that audio output
3678 device (for the purpose of applying effects externally that is, e.g.
3679 by using another application), that way you can i.e. first increase
3680 the amount of audio channels on the audio output device for having
3681 dedicated effect send output channels and when "CREATE FX_SEND" is
3682 called, those channels will automatically be picked. You can alter
3683 the destination channels however with "SET FX_SEND
3684 AUDIO_OUTPUT_CHANNEL" (Section 6.4.34). If your intention is rather
3685 to use internal effects instead of external effects, then you first
3686 need to load those internal effects (Section 6.11) and then assign
3687 the FX sends to the desired internal effect by sending "SET FX_SEND
3688 EFFECT" (Section 6.4.35).
3689
3690 Note: Create effect sends on a sampler channel only when needed,
3691 because having effect sends on a sampler channel will decrease
3692 runtime performance, because for implementing channel effect sends,
3693
3694
3695
3696 Schoenebeck Expires September 12, 2019 [Page 66]
3697
3698 Internet-Draft LinuxSampler Control Protocol March 2019
3699
3700
3701 separate (sampler channel local) audio buffers are needed to render
3702 and mix the voices and route the audio signal afterwards to the
3703 master outputs and effect send outputs (along with their respective
3704 effect send levels). A sampler channel without effect sends however
3705 can mix its voices directly into the audio output devices's audio
3706 buffers and is thus faster.
3707
3708 Possible Answers:
3709
3710 "OK[<fx-send-id>]" -
3711
3712 in case a new effect send could be added to the sampler
3713 channel, where <fx-send-id> reflects the unique ID of the newly
3714 created effect send entity
3715
3716 "ERR:<error-code>:<error-message>" -
3717
3718 when a new effect send could not be added, i.e. due to invalid
3719 parameters
3720
3721 Examples:
3722
3723 C: "CREATE FX_SEND 0 91 'Reverb Send'"
3724
3725 S: "OK[0]"
3726
3727 C: "CREATE FX_SEND 0 93"
3728
3729 S: "OK[1]"
3730
3731 6.4.29. Removing an effect send from a sampler channel
3732
3733 The front-end can remove an existing effect send on a specific
3734 sampler channel by sending the following command:
3735
3736 DESTROY FX_SEND <sampler-channel> <fx-send-id>
3737
3738 Where <sampler-channel> is the respective sampler channel number as
3739 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3740 (Section 6.4.4) command, that is the sampler channel from which the
3741 effect send should be removed from and <fx-send-id> is the respective
3742 effect send number as returned by the "CREATE FX_SEND"
3743 (Section 6.4.28) or "LIST FX_SENDS" (Section 6.4.31) command.
3744
3745 Possible Answers:
3746
3747 "OK" -
3748
3749
3750
3751
3752 Schoenebeck Expires September 12, 2019 [Page 67]
3753
3754 Internet-Draft LinuxSampler Control Protocol March 2019
3755
3756
3757 on success
3758
3759 "ERR:<error-code>:<error-message>" -
3760
3761 in case it failed, providing an appropriate error code and
3762 error message
3763
3764 Example:
3765
3766 C: "DESTROY FX_SEND 0 0"
3767
3768 S: "OK"
3769
3770 6.4.30. Getting amount of effect sends on a sampler channel
3771
3772 The front-end can ask for the amount of effect sends on a specific
3773 sampler channel by sending the following command:
3774
3775 GET FX_SENDS <sampler-channel>
3776
3777 Where <sampler-channel> is the respective sampler channel number as
3778 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3779 (Section 6.4.4) command.
3780
3781 Possible Answers:
3782
3783 The sampler will answer by returning the number of effect sends on
3784 the given sampler channel.
3785
3786 Example:
3787
3788 C: "GET FX_SENDS 0"
3789
3790 S: "2"
3791
3792 6.4.31. Listing all effect sends on a sampler channel
3793
3794 The front-end can ask for a list of effect sends on a specific
3795 sampler channel by sending the following command:
3796
3797 LIST FX_SENDS <sampler-channel>
3798
3799 Where <sampler-channel> is the respective sampler channel number as
3800 returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
3801 (Section 6.4.4) command.
3802
3803 Possible Answers:
3804
3805
3806
3807
3808 Schoenebeck Expires September 12, 2019 [Page 68]
3809
3810 Internet-Draft LinuxSampler Control Protocol March 2019
3811
3812
3813 The sampler will answer by returning a comma separated list with
3814 all effect sends' numerical IDs on the given sampler channel.
3815
3816 Examples:
3817
3818 C: "LIST FX_SENDS 0"
3819
3820 S: "0,1"
3821
3822 C: "LIST FX_SENDS 1"
3823
3824 S: ""
3825
3826 6.4.32. Getting effect send information
3827
3828 The front-end can ask for the current settings of an effect send
3829 entity by sending the following command:
3830
3831 GET FX_SEND INFO <sampler-channel> <fx-send-id>
3832
3833 Where <sampler-channel> is the sampler channel number as returned by
3834 the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3835 command and <fx-send-id> reflects the numerical ID of the effect send
3836 entity as returned by the "CREATE FX_SEND" (Section 6.4.28) or "LIST
3837 FX_SENDS" (Section 6.4.31) command.
3838
3839 Possible Answers:
3840
3841 The sampler will answer by sending a <CRLF> separated list. Each
3842 answer line begins with the settings category name followed by a
3843 colon and then a space character <SP> and finally the info
3844 character string to that setting category. At the moment the
3845 following categories are defined:
3846
3847
3848
3849 NAME -
3850
3851 name of the effect send entity (note that this character
3852 string may contain escape sequences (Section 7.1))
3853
3854 MIDI_CONTROLLER -
3855
3856 a value between 0 and 127 reflecting the MIDI controller
3857 which is able to modify the effect send's send level
3858
3859 LEVEL -
3860
3861
3862
3863
3864 Schoenebeck Expires September 12, 2019 [Page 69]
3865
3866 Internet-Draft LinuxSampler Control Protocol March 2019
3867
3868
3869 optionally dotted number reflecting the effect send's
3870 current send level (where a value < 1.0 means attenuation
3871 and a value > 1.0 means amplification)
3872
3873 AUDIO_OUTPUT_ROUTING -
3874
3875 comma separated list which reflects to which audio channel
3876 of the selected audio output device each effect send output
3877 channel is routed to, e.g. "0,3" would mean the effect
3878 send's output channel 0 is routed to channel 0 of the audio
3879 output device and the effect send's output channel 1 is
3880 routed to the channel 3 of the audio output device (see "SET
3881 FX_SEND AUDIO_OUTPUT_CHANNEL" (Section 6.4.34) for details),
3882 if an internal send effect is assigned to the effect send,
3883 then this setting defines the audio channel routing to that
3884 effect instance respectively
3885
3886 EFFECT -
3887
3888 destination send effect chain ID and destination effect
3889 chain position, separated by comma in the form "<effect-
3890 chain>,<chain-pos>" or "NONE" if there is no send effect
3891 assigned to the effect send
3892
3893 The mentioned fields above don't have to be in particular order.
3894
3895 Example:
3896
3897 C: "GET FX_SEND INFO 0 0"
3898
3899 S: "NAME: Reverb Send"
3900
3901 "MIDI_CONTROLLER: 91"
3902
3903 "LEVEL: 0.3"
3904
3905 "AUDIO_OUTPUT_ROUTING: 2,3"
3906
3907 "EFFECT: NONE"
3908
3909 "."
3910
3911 C: "GET FX_SEND INFO 0 1"
3912
3913 S: "NAME: Delay Send (Internal)"
3914
3915 "MIDI_CONTROLLER: 93"
3916
3917
3918
3919
3920 Schoenebeck Expires September 12, 2019 [Page 70]
3921
3922 Internet-Draft LinuxSampler Control Protocol March 2019
3923
3924
3925 "LEVEL: 0.51"
3926
3927 "AUDIO_OUTPUT_ROUTING: 1,2"
3928
3929 "EFFECT: 2,0"
3930
3931 "."
3932
3933 6.4.33. Changing effect send's name
3934
3935 The front-end can alter the current name of an effect send entity by
3936 sending the following command:
3937
3938 SET FX_SEND NAME <sampler-chan> <fx-send-id> <name>
3939
3940 Where <sampler-chan> is the sampler channel number as returned by the
3941 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3942 command, <fx-send-id> reflects the numerical ID of the effect send
3943 entity as returned by the "CREATE FX_SEND" (Section 6.4.28) or "LIST
3944 FX_SENDS" (Section 6.4.31) command and <name> is the new name of the
3945 effect send entity, which does not have to be unique (name MUST be
3946 encapsulated into apostrophes and supports escape sequences as
3947 described in chapter "Character Set and Escape Sequences
3948 (Section 7.1)").
3949
3950 Possible Answers:
3951
3952 "OK" -
3953
3954 on success
3955
3956 "ERR:<error-code>:<error-message>" -
3957
3958 in case it failed, providing an appropriate error code and
3959 error message
3960
3961 Example:
3962
3963 C: "SET FX_SEND NAME 0 0 'Fx Send 1'"
3964
3965 S: "OK"
3966
3967 6.4.34. Altering effect send's audio routing
3968
3969 The front-end can alter the destination of an effect send's audio
3970 channel on a specific sampler channel by sending the following
3971 command:
3972
3973
3974
3975
3976 Schoenebeck Expires September 12, 2019 [Page 71]
3977
3978 Internet-Draft LinuxSampler Control Protocol March 2019
3979
3980
3981 SET FX_SEND AUDIO_OUTPUT_CHANNEL <sampler-chan> <fx-send-id>
3982 <audio-src> <audio-dst>
3983
3984 Where <sampler-chan> is the sampler channel number as returned by the
3985 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
3986 command, <fx-send-id> reflects the numerical ID of the effect send
3987 entity as returned by the "CREATE FX_SEND" (Section 6.4.28) or "LIST
3988 FX_SENDS" (Section 6.4.31) command, <audio-src> is the numerical ID
3989 of the effect send's audio channel which should be rerouted and
3990 <audio-dst> is the numerical ID of either a) the audio output channel
3991 of the sampler channel's audio output device (i.e. if external effect
3992 shall be applied) or b) of the audio input channel of an internal
3993 effect assigned to the FX send where <audio-src> should be routed to.
3994
3995 Note that effect sends can only route audio to the same audio output
3996 device as assigned to the effect send's sampler channel. Also note
3997 that an effect send entity does always have exactly as much audio
3998 channels as its sampler channel. So if the sampler channel is
3999 stereo, the effect send does have two audio channels as well. Also
4000 keep in mind that the amount of audio channels on a sampler channel
4001 might be dependant not only to the deployed sampler engine on the
4002 sampler channel, but also dependant to the instrument currently
4003 loaded. However you can (effectively) turn an i.e. stereo effect
4004 send into a mono one by simply altering its audio routing
4005 appropriately.
4006
4007 Possible Answers:
4008
4009 "OK" -
4010
4011 on success
4012
4013 "WRN:<warning-code>:<warning-message>" -
4014
4015 if audio output channel was set, but there are noteworthy
4016 issue(s) related, providing an appropriate warning code and
4017 warning message
4018
4019 "ERR:<error-code>:<error-message>" -
4020
4021 in case it failed, providing an appropriate error code and
4022 error message
4023
4024 Example:
4025
4026 C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2"
4027
4028 S: "OK"
4029
4030
4031
4032 Schoenebeck Expires September 12, 2019 [Page 72]
4033
4034 Internet-Draft LinuxSampler Control Protocol March 2019
4035
4036
4037 6.4.35. Assigning destination effect to an effect send
4038
4039 The front-end can (re-)assign an internal destination effect to an
4040 effect send by sending the following command:
4041
4042 SET FX_SEND EFFECT <sampler-chan> <fx-send-id> <effect-chain>
4043 <chain-pos>
4044
4045 Where <sampler-chan> is the sampler channel number as returned by the
4046 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
4047 command, <fx-send-id> reflects the numerical ID of the effect send
4048 entity as returned by the "CREATE FX_SEND" (Section 6.4.28) or "LIST
4049 FX_SENDS" (Section 6.4.31) command, <effect-chain> by the numerical
4050 ID of the destination effect chain as returned by the "ADD
4051 SEND_EFFECT_CHAIN" (Section 6.11.14) or "LIST SEND_EFFECT_CHAINS"
4052 (Section 6.11.13) command and <chain-pos> reflects the exact effect
4053 chain position in the effect chain which hosts the actual destination
4054 effect.
4055
4056 Note: This command MUST NOT be used if you want to apply audio
4057 effects externally! By default FX sends are routed directly to the
4058 audio output device for that purpose. You can also revert this
4059 command later on by sending "REMOVE FX_SEND EFFECT" (Section 6.4.36),
4060 which will cause the FX send to be routed directly to the sampler
4061 channel's audio output device instead (i.e. for using external
4062 effects instead of internal effects).
4063
4064 Possible Answers:
4065
4066 "OK" -
4067
4068 on success
4069
4070 "ERR:<error-code>:<error-message>" -
4071
4072 in case it failed, providing an appropriate error code and
4073 error message
4074
4075 Example:
4076
4077 C: "SET FX_SEND EFFECT 0 0 2 5"
4078
4079 S: "OK"
4080
4081
4082
4083
4084
4085
4086
4087
4088 Schoenebeck Expires September 12, 2019 [Page 73]
4089
4090 Internet-Draft LinuxSampler Control Protocol March 2019
4091
4092
4093 6.4.36. Removing destination effect from an effect send
4094
4095 The front-end can (re-)assign a destination effect to an effect send
4096 by sending the following command:
4097
4098 REMOVE FX_SEND EFFECT <sampler-chan> <fx-send-id>
4099
4100 Where <sampler-chan> is the sampler channel number as returned by the
4101 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
4102 command, <fx-send-id> reflects the numerical ID of the effect send
4103 entity as returned by the "CREATE FX_SEND" (Section 6.4.28) or "LIST
4104 FX_SENDS" (Section 6.4.31) command.
4105
4106 After the destination effect has been removed from the effect send,
4107 the audio signal of the effect send will be routed directly to the
4108 audio output device, according to the audio channel routing setting
4109 of the effect send.
4110
4111 Possible Answers:
4112
4113 "OK" -
4114
4115 on success
4116
4117 "ERR:<error-code>:<error-message>" -
4118
4119 in case it failed, providing an appropriate error code and
4120 error message
4121
4122 Example:
4123
4124 C: "REMOVE FX_SEND EFFECT 0 0"
4125
4126 S: "OK"
4127
4128 6.4.37. Altering effect send's MIDI controller
4129
4130 The front-end can alter the MIDI controller of an effect send entity
4131 by sending the following command:
4132
4133 SET FX_SEND MIDI_CONTROLLER <sampler-chan> <fx-send-id> <midi-
4134 ctrl>
4135
4136 Where <sampler-chan> is the sampler channel number as returned by the
4137 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
4138 command, <fx-send-id> reflects the numerical ID of the effect send
4139 entity as returned by the "CREATE FX_SEND" (Section 6.4.28) or "LIST
4140 FX_SENDS" (Section 6.4.31) command and <midi-ctrl> reflects the MIDI
4141
4142
4143
4144 Schoenebeck Expires September 12, 2019 [Page 74]
4145
4146 Internet-Draft LinuxSampler Control Protocol March 2019
4147
4148
4149 controller which shall be able to modify the effect send's send
4150 level.
4151
4152 Possible Answers:
4153
4154 "OK" -
4155
4156 on success
4157
4158 "WRN:<warning-code>:<warning-message>" -
4159
4160 if MIDI controller was set, but there are noteworthy issue(s)
4161 related, providing an appropriate warning code and warning
4162 message
4163
4164 "ERR:<error-code>:<error-message>" -
4165
4166 in case it failed, providing an appropriate error code and
4167 error message
4168
4169 Example:
4170
4171 C: "SET FX_SEND MIDI_CONTROLLER 0 0 91"
4172
4173 S: "OK"
4174
4175 6.4.38. Altering effect send's send level
4176
4177 The front-end can alter the current send level of an effect send
4178 entity by sending the following command:
4179
4180 SET FX_SEND LEVEL <sampler-chan> <fx-send-id> <volume>
4181
4182 Where <sampler-chan> is the sampler channel number as returned by the
4183 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
4184 command, <fx-send-id> reflects the numerical ID of the effect send
4185 entity as returned by the "CREATE FX_SEND" (Section 6.4.28) or "LIST
4186 FX_SENDS" (Section 6.4.31) command and <volume> is an optionally
4187 dotted positive number (a value smaller than 1.0 means attenuation,
4188 whereas a value greater than 1.0 means amplification) reflecting the
4189 new send level.
4190
4191 Possible Answers:
4192
4193 "OK" -
4194
4195 on success
4196
4197
4198
4199
4200 Schoenebeck Expires September 12, 2019 [Page 75]
4201
4202 Internet-Draft LinuxSampler Control Protocol March 2019
4203
4204
4205 "WRN:<warning-code>:<warning-message>" -
4206
4207 if new send level was set, but there are noteworthy issue(s)
4208 related, providing an appropriate warning code and warning
4209 message
4210
4211 "ERR:<error-code>:<error-message>" -
4212
4213 in case it failed, providing an appropriate error code and
4214 error message
4215
4216 Example:
4217
4218 C: "SET FX_SEND LEVEL 0 0 0.15"
4219
4220 S: "OK"
4221
4222 6.4.39. Sending MIDI messages to sampler channel
4223
4224 The front-end can send MIDI events to a specific sampler channel by
4225 sending the following command:
4226
4227 SEND CHANNEL MIDI_DATA <midi-msg> <sampler-chan> <arg1> <arg2>
4228
4229 Where <sampler-chan> is the sampler channel number as returned by the
4230 "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
4231 command, <arg1> and <arg2> arguments depend on the <midi-msg>
4232 argument, which specifies the MIDI message type. Currently, the
4233 following MIDI messages are supported:
4234
4235 "NOTE_ON" -
4236
4237 For turning on MIDI notes, where <arg1> specifies the key
4238 number and <arg2> the velocity as described in the MIDI
4239 specification.
4240
4241 "NOTE_OFF" -
4242
4243 For turning a currently playing MIDI note off, where <arg1>
4244 specifies the key number and <arg2> the velocity as described
4245 in the MIDI specification.
4246
4247 "CC" -
4248
4249 For changing a MIDI controller, where <arg1> specifies the
4250 controller number and <arg2> the new value of the controller as
4251 described in the Control Change section of the MIDI
4252 specification.
4253
4254
4255
4256 Schoenebeck Expires September 12, 2019 [Page 76]
4257
4258 Internet-Draft LinuxSampler Control Protocol March 2019
4259
4260
4261 CAUTION: This command is provided for implementations of virtual MIDI
4262 keyboards and no realtime guarantee whatsoever will be made!
4263
4264 Possible Answers:
4265
4266 "OK" -
4267
4268 on success
4269
4270 "ERR:<error-code>:<error-message>" -
4271
4272 in case it failed, providing an appropriate error code and
4273 error message
4274
4275 Example:
4276
4277 C: "SEND CHANNEL MIDI_DATA NOTE_ON 0 56 112"
4278
4279 S: "OK"
4280
4281 6.4.40. Resetting a sampler channel
4282
4283 The front-end can reset a particular sampler channel by sending the
4284 following command:
4285
4286 RESET CHANNEL <sampler-channel>
4287
4288 Where <sampler-channel> defines the sampler channel to be reset.
4289 This will cause the engine on that sampler channel, its voices and
4290 eventually disk streams and all control and status variables to be
4291 reset.
4292
4293 Possible Answers:
4294
4295 "OK" -
4296
4297 on success
4298
4299 "WRN:<warning-code>:<warning-message>" -
4300
4301 if channel was reset, but there are noteworthy issue(s)
4302 related, providing an appropriate warning code and warning
4303 message
4304
4305 "ERR:<error-code>:<error-message>" -
4306
4307 in case it failed, providing an appropriate error code and
4308 error message
4309
4310
4311
4312 Schoenebeck Expires September 12, 2019 [Page 77]
4313
4314 Internet-Draft LinuxSampler Control Protocol March 2019
4315
4316
4317 Examples:
4318
4319
4320
4321 6.5. Controlling connection
4322
4323 The following commands are used to control the connection to
4324 LinuxSampler.
4325
4326 6.5.1. Register front-end for receiving event messages
4327
4328 The front-end can register itself to the LinuxSampler application to
4329 be informed about noteworthy events by sending this command:
4330
4331 SUBSCRIBE <event-id>
4332
4333 where <event-id> will be replaced by the respective event that client
4334 wants to subscribe to.
4335
4336 Possible Answers:
4337
4338 "OK" -
4339
4340 on success
4341
4342 "WRN:<warning-code>:<warning-message>" -
4343
4344 if registration succeeded, but there are noteworthy issue(s)
4345 related, providing an appropriate warning code and warning
4346 message
4347
4348 "ERR:<error-code>:<error-message>" -
4349
4350 in case it failed, providing an appropriate error code and
4351 error message
4352
4353 Examples:
4354
4355
4356
4357 6.5.2. Unregister front-end for not receiving event messages
4358
4359 The front-end can unregister itself if it doesn't want to receive
4360 event messages anymore by sending the following command:
4361
4362 UNSUBSCRIBE <event-id>
4363
4364
4365
4366
4367
4368 Schoenebeck Expires September 12, 2019 [Page 78]
4369
4370 Internet-Draft LinuxSampler Control Protocol March 2019
4371
4372
4373 Where <event-id> will be replaced by the respective event that client
4374 doesn't want to receive anymore.
4375
4376 Possible Answers:
4377
4378 "OK" -
4379
4380 on success
4381
4382 "WRN:<warning-code>:<warning-message>" -
4383
4384 if unregistration succeeded, but there are noteworthy issue(s)
4385 related, providing an appropriate warning code and warning
4386 message
4387
4388 "ERR:<error-code>:<error-message>" -
4389
4390 in case it failed, providing an appropriate error code and
4391 error message
4392
4393 Examples:
4394
4395
4396
4397 6.5.3. Enable or disable echo of commands
4398
4399 To enable or disable back sending of commands to the client the
4400 following command can be used:
4401
4402 SET ECHO <value>
4403
4404 Where <value> should be replaced either by "1" to enable echo mode or
4405 "0" to disable echo mode. When echo mode is enabled, all commands
4406 send to LinuxSampler will be immediately send back and after this
4407 echo the actual response to the command will be returned. Echo mode
4408 will only be altered for the client connection that issued the "SET
4409 ECHO" command, not globally for all client connections.
4410
4411 Possible Answers:
4412
4413 "OK" -
4414
4415 usually
4416
4417 "ERR:<error-code>:<error-message>" -
4418
4419 on syntax error, e.g. non boolean value
4420
4421
4422
4423
4424 Schoenebeck Expires September 12, 2019 [Page 79]
4425
4426 Internet-Draft LinuxSampler Control Protocol March 2019
4427
4428
4429 Examples:
4430
4431
4432
4433 6.5.4. Close client connection
4434
4435 The client can close its network connection to LinuxSampler by
4436 sending the following command:
4437
4438 QUIT
4439
4440 This is probably more interesting for manual telnet connections to
4441 LinuxSampler than really useful for a front-end implementation.
4442
4443 6.6. Global commands
4444
4445 The following commands have global impact on the sampler.
4446
4447 6.6.1. Current number of active voices
4448
4449 The front-end can ask for the current number of active voices on the
4450 sampler by sending the following command:
4451
4452 GET TOTAL_VOICE_COUNT
4453
4454 Possible Answers:
4455
4456 LinuxSampler will answer by returning the number of all active
4457 voices on the sampler.
4458
4459 6.6.2. Maximum amount of active voices
4460
4461 The front-end can ask for the maximum number of active voices by
4462 sending the following command:
4463
4464 GET TOTAL_VOICE_COUNT_MAX
4465
4466 Possible Answers:
4467
4468 LinuxSampler will answer by returning the maximum number of active
4469 voices.
4470
4471 6.6.3. Current number of active disk streams
4472
4473 The front-end can ask for the current number of active disk streams
4474 on the sampler by sending the following command:
4475
4476 GET TOTAL_STREAM_COUNT
4477
4478
4479
4480 Schoenebeck Expires September 12, 2019 [Page 80]
4481
4482 Internet-Draft LinuxSampler Control Protocol March 2019
4483
4484
4485 Possible Answers:
4486
4487 LinuxSampler will answer by returning the number of all active
4488 disk streams on the sampler.
4489
4490 6.6.4. Reset sampler
4491
4492 The front-end can reset the whole sampler by sending the following
4493 command:
4494
4495 RESET
4496
4497 Possible Answers:
4498
4499 "OK" -
4500
4501 always
4502
4503 Examples:
4504
4505
4506
4507 6.6.5. General sampler information
4508
4509 The client can ask for general information about the LinuxSampler
4510 instance by sending the following command:
4511
4512 GET SERVER INFO
4513
4514 Possible Answers:
4515
4516 LinuxSampler will answer by sending a <CRLF> separated list. Each
4517 answer line begins with the information category name followed by
4518 a colon and then a space character <SP> and finally the info
4519 character string to that information category. At the moment the
4520 following categories are defined:
4521
4522
4523
4524 DESCRIPTION -
4525
4526 arbitrary textual description about the sampler (note that
4527 the character string may contain escape sequences
4528 (Section 7.1))
4529
4530 VERSION -
4531
4532 version of the sampler
4533
4534
4535
4536 Schoenebeck Expires September 12, 2019 [Page 81]
4537
4538 Internet-Draft LinuxSampler Control Protocol March 2019
4539
4540
4541 PROTOCOL_VERSION -
4542
4543 version of the LSCP specification the sampler complies with
4544 (see Section 2 for details)
4545
4546 INSTRUMENTS_DB_SUPPORT -
4547
4548 either yes or no, specifies whether the sampler is build
4549 with instruments database support.
4550
4551 The mentioned fields above don't have to be in particular order.
4552 Other fields might be added in future.
4553
4554 Example:
4555
4556 C: "GET SERVER INFO"
4557
4558 S: "DESCRIPTION: LinuxSampler - modular, streaming capable
4559 sampler"
4560
4561 "VERSION: 1.0.0.svn23"
4562
4563 "PROTOCOL_VERSION: 1.5"
4564
4565 "INSTRUMENTS_DB_SUPPORT: no"
4566
4567 "."
4568
4569 6.6.6. Getting global volume attenuation
4570
4571 The client can ask for the current global sampler-wide volume
4572 attenuation by sending the following command:
4573
4574 GET VOLUME
4575
4576 Possible Answers:
4577
4578 The sampler will always answer by returning the optional dotted
4579 floating point coefficient, reflecting the current global volume
4580 attenuation.
4581
4582 Note: it is up to the respective sampler engine whether to obey that
4583 global volume parameter or not, but in general all engines SHOULD use
4584 this parameter.
4585
4586
4587
4588
4589
4590
4591
4592 Schoenebeck Expires September 12, 2019 [Page 82]
4593
4594 Internet-Draft LinuxSampler Control Protocol March 2019
4595
4596
4597 6.6.7. Setting global volume attenuation
4598
4599 The client can alter the current global sampler-wide volume
4600 attenuation by sending the following command:
4601
4602 SET VOLUME <volume>
4603
4604 Where <volume> should be replaced by the optional dotted floating
4605 point value, reflecting the new global volume parameter. This value
4606 might usually be in the range between 0.0 and 1.0, that is for
4607 attenuating the overall volume.
4608
4609 Possible Answers:
4610
4611 "OK" -
4612
4613 on success
4614
4615 "WRN:<warning-code>:<warning-message>" -
4616
4617 if the global volume was set, but there are noteworthy issue(s)
4618 related, providing an appropriate warning code and warning
4619 message
4620
4621 "ERR:<error-code>:<error-message>" -
4622
4623 in case it failed, providing an appropriate error code and
4624 error message
4625
4626 6.6.8. Getting global voice limit
4627
4628 The client can ask for the current global sampler-wide limit for
4629 maximum voices by sending the following command:
4630
4631 GET VOICES
4632
4633 Possible Answers:
4634
4635 LinuxSampler will answer by returning the number for the current
4636 limit of maximum voices.
4637
4638 The voice limit setting defines how many voices should maximum be
4639 processed by the sampler at the same time. If the user triggers new
4640 notes which would exceed that voice limit, the sampler engine will
4641 react by stealing old voices for those newly triggered notes. Note
4642 that the amount of voices triggered by a new note can be larger than
4643 one and is dependent to the respective instrument and probably
4644 further criterias.
4645
4646
4647
4648 Schoenebeck Expires September 12, 2019 [Page 83]
4649
4650 Internet-Draft LinuxSampler Control Protocol March 2019
4651
4652
4653 6.6.9. Setting global voice limit
4654
4655 The client can alter the current global sampler-wide limit for
4656 maximum voices by sending the following command:
4657
4658 SET VOICES <max-voices>
4659
4660 Where <max-voices> should be replaced by the integer value,
4661 reflecting the new global amount limit of maximum voices. This value
4662 has to be larger than 0.
4663
4664 Possible Answers:
4665
4666 "OK" -
4667
4668 on success
4669
4670 "WRN:<warning-code>:<warning-message>" -
4671
4672 if the voice limit was set, but there are noteworthy issue(s)
4673 related, providing an appropriate warning code and warning
4674 message
4675
4676 "ERR:<error-code>:<error-message>" -
4677
4678 in case it failed, providing an appropriate error code and
4679 error message
4680
4681 Note: the given value will be passed to all sampler engine instances.
4682 The total amount of maximum voices on the running system might thus
4683 be as big as the given value multiplied by the current amount of
4684 engine instances.
4685
4686 Caution: when adjusting the voice limit, you SHOULD also adjust the
4687 disk stream limit respectively and vice versa.
4688
4689 6.6.10. Getting global disk stream limit
4690
4691 The client can ask for the current global sampler-wide limit for
4692 maximum disk streams by sending the following command:
4693
4694 GET STREAMS
4695
4696 Possible Answers:
4697
4698 LinuxSampler will answer by returning the number for the current
4699 limit of maximum disk streams.
4700
4701
4702
4703
4704 Schoenebeck Expires September 12, 2019 [Page 84]
4705
4706 Internet-Draft LinuxSampler Control Protocol March 2019
4707
4708
4709 The disk stream limit setting defines how many disk streams should
4710 maximum be processed by a sampler engine at the same time. The
4711 higher this value, the more memory (RAM) will be occupied, since
4712 every disk streams allocates a certain buffer size for being able to
4713 perform its streaming operations.
4714
4715 6.6.11. Setting global disk stream limit
4716
4717 The client can alter the current global sampler-wide limit for
4718 maximum disk streams by sending the following command:
4719
4720 SET STREAMS <max-streams>
4721
4722 Where <max-streams> should be replaced by the integer value,
4723 reflecting the new global amount limit of maximum disk streams. This
4724 value has to be positive.
4725
4726 Possible Answers:
4727
4728 "OK" -
4729
4730 on success
4731
4732 "WRN:<warning-code>:<warning-message>" -
4733
4734 if the disk stream limit was set, but there are noteworthy
4735 issue(s) related, providing an appropriate warning code and
4736 warning message
4737
4738 "ERR:<error-code>:<error-message>" -
4739
4740 in case it failed, providing an appropriate error code and
4741 error message
4742
4743 Note: the given value will be passed to all sampler engine instances.
4744 The total amount of maximum disk streams on the running system might
4745 thus be as big as the given value multiplied by the current amount of
4746 engine instances.
4747
4748 Caution: when adjusting the disk stream limit, you SHOULD also adjust
4749 the voice limit respectively and vice versa.
4750
4751 6.7. MIDI Instrument Mapping
4752
4753 The MIDI protocol provides a way to switch between instruments by
4754 sending so called MIDI bank select and MIDI program change messages
4755 which are essentially just numbers. The following commands allow to
4756
4757
4758
4759
4760 Schoenebeck Expires September 12, 2019 [Page 85]
4761
4762 Internet-Draft LinuxSampler Control Protocol March 2019
4763
4764
4765 actually map arbitrary MIDI bank select / program change numbers with
4766 real instruments.
4767
4768 The sampler allows to manage an arbitrary amount of MIDI instrument
4769 maps which define which instrument to load on which MIDI program
4770 change message.
4771
4772 By default, that is when the sampler is launched, there is no map,
4773 thus the sampler will simply ignore all program change messages. The
4774 front-end has to explicitly create at least one map, add entries to
4775 the map and tell the respective sampler channel(s) which MIDI
4776 instrument map to use, so the sampler knows how to react on a given
4777 program change message on the respective sampler channel, that is by
4778 switching to the respectively defined engine type and loading the
4779 respective instrument. See command "SET CHANNEL MIDI_INSTRUMENT_MAP"
4780 (Section 6.4.27) for how to assign a MIDI instrument map to a sampler
4781 channel.
4782
4783 Also note per MIDI specification a bank select message does not cause
4784 to switch to another instrument. Instead when receiving a bank
4785 select message the bank value will be stored and a subsequent program
4786 change message (which may occur at any time) will finally cause the
4787 sampler to switch to the respective instrument as reflected by the
4788 current MIDI instrument map.
4789
4790 6.7.1. Create a new MIDI instrument map
4791
4792 The front-end can add a new MIDI instrument map by sending the
4793 following command:
4794
4795 ADD MIDI_INSTRUMENT_MAP [<name>]
4796
4797 Where <name> is an optional argument allowing to assign a custom name
4798 to the new map. MIDI instrument Map names do not have to be unique,
4799 but MUST be encapsulated into apostrophes and support escape
4800 sequences as described in chapter "Character Set and Escape Sequences
4801 (Section 7.1)".
4802
4803 Possible Answers:
4804
4805 "OK[<map>]" -
4806
4807 in case a new MIDI instrument map could be added, where <map>
4808 reflects the unique ID of the newly created MIDI instrument map
4809
4810 "ERR:<error-code>:<error-message>" -
4811
4812
4813
4814
4815
4816 Schoenebeck Expires September 12, 2019 [Page 86]
4817
4818 Internet-Draft LinuxSampler Control Protocol March 2019
4819
4820
4821 when a new map could not be created, which might never occur in
4822 practice
4823
4824 Examples:
4825
4826 C: "ADD MIDI_INSTRUMENT_MAP 'Standard Map'"
4827
4828 S: "OK[0]"
4829
4830 C: "ADD MIDI_INSTRUMENT_MAP 'Standard Drumkit'"
4831
4832 S: "OK[1]"
4833
4834 C: "ADD MIDI_INSTRUMENT_MAP"
4835
4836 S: "OK[5]"
4837
4838 6.7.2. Delete one particular or all MIDI instrument maps
4839
4840 The front-end can delete a particular MIDI instrument map by sending
4841 the following command:
4842
4843 REMOVE MIDI_INSTRUMENT_MAP <map>
4844
4845 Where <map> reflects the unique ID of the map to delete as returned
4846 by the "LIST MIDI_INSTRUMENT_MAPS" (Section 6.7.4) command.
4847
4848 The front-end can delete all MIDI instrument maps by sending the
4849 following command:
4850
4851 REMOVE MIDI_INSTRUMENT_MAP ALL
4852
4853 Possible Answers:
4854
4855 "OK" -
4856
4857 in case the map(s) could be deleted
4858
4859 "ERR:<error-code>:<error-message>" -
4860
4861 when the given map does not exist
4862
4863 Examples:
4864
4865 C: "REMOVE MIDI_INSTRUMENT_MAP 0"
4866
4867 S: "OK"
4868
4869
4870
4871
4872 Schoenebeck Expires September 12, 2019 [Page 87]
4873
4874 Internet-Draft LinuxSampler Control Protocol March 2019
4875
4876
4877 C: "REMOVE MIDI_INSTRUMENT_MAP ALL"
4878
4879 S: "OK"
4880
4881 6.7.3. Get amount of existing MIDI instrument maps
4882
4883 The front-end can retrieve the current amount of MIDI instrument maps
4884 by sending the following command:
4885
4886 GET MIDI_INSTRUMENT_MAPS
4887
4888 Possible Answers:
4889
4890 The sampler will answer by returning the current number of MIDI
4891 instrument maps.
4892
4893 Example:
4894
4895 C: "GET MIDI_INSTRUMENT_MAPS"
4896
4897 S: "2"
4898
4899 6.7.4. Getting all created MIDI instrument maps
4900
4901 The number of MIDI instrument maps can change on runtime. To get the
4902 current list of MIDI instrument maps, the front-end can send the
4903 following command:
4904
4905 LIST MIDI_INSTRUMENT_MAPS
4906
4907 Possible Answers:
4908
4909 The sampler will answer by returning a comma separated list with
4910 all MIDI instrument maps' numerical IDs.
4911
4912 Example:
4913
4914 C: "LIST MIDI_INSTRUMENT_MAPS"
4915
4916 S: "0,1,5,12"
4917
4918 6.7.5. Getting MIDI instrument map information
4919
4920 The front-end can ask for the current settings of a MIDI instrument
4921 map by sending the following command:
4922
4923 GET MIDI_INSTRUMENT_MAP INFO <map>
4924
4925
4926
4927
4928 Schoenebeck Expires September 12, 2019 [Page 88]
4929
4930 Internet-Draft LinuxSampler Control Protocol March 2019
4931
4932
4933 Where <map> is the numerical ID of the map the front-end is
4934 interested in as returned by the "LIST MIDI_INSTRUMENT_MAPS"
4935 (Section 6.7.4) command.
4936
4937 Possible Answers:
4938
4939 LinuxSampler will answer by sending a <CRLF> separated list. Each
4940 answer line begins with the settings category name followed by a
4941 colon and then a space character <SP> and finally the info
4942 character string to that setting category. At the moment the
4943 following categories are defined:
4944
4945
4946
4947 NAME -
4948
4949 custom name of the given map, which does not have to be
4950 unique (note that this character string may contain escape
4951 sequences (Section 7.1))
4952
4953 DEFAULT -
4954
4955 either true or false, defines whether this map is the
4956 default map
4957
4958 The mentioned fields above don't have to be in particular order.
4959
4960 Example:
4961
4962 C: "GET MIDI_INSTRUMENT_MAP INFO 0"
4963
4964 S: "NAME: Standard Map"
4965
4966 "DEFAULT: true"
4967
4968 "."
4969
4970 6.7.6. Renaming a MIDI instrument map
4971
4972 The front-end can alter the custom name of a MIDI instrument map by
4973 sending the following command:
4974
4975 SET MIDI_INSTRUMENT_MAP NAME <map> <name>
4976
4977 Where <map> is the numerical ID of the map and <name> the new custom
4978 name of the map, which does not have to be unique (name MUST be
4979 encapsulated into apostrophes and supports escape sequences as
4980
4981
4982
4983
4984 Schoenebeck Expires September 12, 2019 [Page 89]
4985
4986 Internet-Draft LinuxSampler Control Protocol March 2019
4987
4988
4989 described in chapter "Character Set and Escape Sequences
4990 (Section 7.1)").
4991
4992 Possible Answers:
4993
4994 "OK" -
4995
4996 on success
4997
4998 "ERR:<error-code>:<error-message>" -
4999
5000 in case the given map does not exist
5001
5002 Example:
5003
5004 C: "SET MIDI_INSTRUMENT_MAP NAME 0 'Foo instruments'"
5005
5006 S: "OK"
5007
5008 6.7.7. Create or replace a MIDI instrument map entry
5009
5010 The front-end can create a new or replace an existing entry in a
5011 sampler's MIDI instrument map by sending the following command:
5012
5013 MAP MIDI_INSTRUMENT [NON_MODAL] <map> <midi_bank> <midi_prog>
5014 <engine_name> <filename> <instrument_index> <volume_value>
5015 [<instr_load_mode>] [<name>]
5016
5017 Where <map> is the numeric ID of the map to alter, <midi_bank> is an
5018 integer value between 0..16383 reflecting the MIDI bank select index,
5019 <midi_prog> an integer value between 0..127 reflecting the MIDI
5020 program change index, <engine_name> a sampler engine name as returned
5021 by the "LIST AVAILABLE_ENGINES" (Section 6.4.8) command (not
5022 encapsulated into apostrophes), <filename> the name of the
5023 instrument's file to be deployed (encapsulated into apostrophes,
5024 supporting escape sequences as described in chapter "Character Set
5025 and Escape Sequences (Section 7.1)"), <instrument_index> the index
5026 (integer value) of the instrument within the given file,
5027 <volume_value> reflects the master volume of the instrument as
5028 optionally dotted number (where a value < 1.0 means attenuation and a
5029 value > 1.0 means amplification). This parameter easily allows to
5030 adjust the volume of all intruments within a custom instrument map
5031 without having to adjust their instrument files. The OPTIONAL
5032 <instr_load_mode> argument defines the life time of the instrument,
5033 that is when the instrument should be loaded, when freed and has
5034 exactly the following possibilities:
5035
5036 "ON_DEMAND" -
5037
5038
5039
5040 Schoenebeck Expires September 12, 2019 [Page 90]
5041
5042 Internet-Draft LinuxSampler Control Protocol March 2019
5043
5044
5045 The instrument will be loaded when needed, that is when
5046 demanded by at least one sampler channel. It will immediately
5047 be freed from memory when not needed by any sampler channel
5048 anymore.
5049
5050 "ON_DEMAND_HOLD" -
5051
5052 The instrument will be loaded when needed, that is when
5053 demanded by at least one sampler channel. It will be kept in
5054 memory even when not needed by any sampler channel anymore.
5055 Instruments with this mode are only freed when the sampler is
5056 reset or all mapping entries with this mode (and respective
5057 instrument) are explicitly changed to "ON_DEMAND" and no
5058 sampler channel is using the instrument anymore.
5059
5060 "PERSISTENT" -
5061
5062 The instrument will immediately be loaded into memory when this
5063 mapping command is sent and the instrument is kept all the
5064 time. Instruments with this mode are only freed when the
5065 sampler is reset or all mapping entries with this mode (and
5066 respective instrument) are explicitly changed to "ON_DEMAND"
5067 and no sampler channel is using the instrument anymore.
5068
5069 not supplied -
5070
5071 In case there is no <instr_load_mode> argument given, it will
5072 be up to the InstrumentManager to decide which mode to use.
5073 Usually it will use "ON_DEMAND" if an entry for the given
5074 instrument does not exist in the InstrumentManager's list yet,
5075 otherwise if an entry already exists, it will simply stick with
5076 the mode currently reflected by the already existing entry,
5077 that is it will not change the mode.
5078
5079 The <instr_load_mode> argument thus allows to define an appropriate
5080 strategy (low memory consumption vs. fast instrument switching) for
5081 each instrument individually. Note, the following restrictions apply
5082 to this argument: "ON_DEMAND_HOLD" and "PERSISTENT" have to be
5083 supported by the respective sampler engine (which is technically the
5084 case when the engine provides an InstrumentManager for its format).
5085 If this is not the case the argument will automatically fall back to
5086 the default value "ON_DEMAND". Also the load mode of one instrument
5087 may automatically change the laod mode of other instrument(s), i.e.
5088 because the instruments are part of the same file and the engine does
5089 not allow a way to manage load modes for them individually. Due to
5090 this, in case the frontend shows the load modes of entries, the
5091 frontend should retrieve the actual mode by i.e. sending "GET
5092 MIDI_INSTRUMENT INFO" (Section 6.7.11) command(s). Finally the
5093
5094
5095
5096 Schoenebeck Expires September 12, 2019 [Page 91]
5097
5098 Internet-Draft LinuxSampler Control Protocol March 2019
5099
5100
5101 OPTIONAL <name> argument allows to set a custom name (encapsulated
5102 into apostrophes, supporting escape sequences as described in chapter
5103 "Character Set and Escape Sequences (Section 7.1)") for the mapping
5104 entry, useful for frontends for displaying an appropriate name for
5105 mapped instruments (using "GET MIDI_INSTRUMENT INFO"
5106 (Section 6.7.11)).
5107
5108 By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is
5109 completely established in the sampler. The OPTIONAL "NON_MODAL"
5110 argument however causes the respective "MAP MIDI_INSTRUMENT" command
5111 to return immediately, that is to let the sampler establish the
5112 mapping in the background. So this argument might be especially
5113 useful for mappings with a "PERSISTENT" type, because these have to
5114 load the respective instruments immediately and might thus block for
5115 a very long time. It is recommended however to use the OPTIONAL
5116 "NON_MODAL" argument only if really necessary, because it has the
5117 following drawbacks: as "NON_MODAL" instructions return immediately,
5118 they may not necessarily return an error i.e. when the given
5119 instrument file turns out to be corrupt, beside that subsequent
5120 commands in a LSCP instruction sequence might fail, because mandatory
5121 mappings are not yet completed.
5122
5123 Possible Answers:
5124
5125 "OK" -
5126
5127 usually
5128
5129 "ERR:<error-code>:<error-message>" -
5130
5131 when the given map or engine does not exist or a value is out
5132 of range
5133
5134 Examples:
5135
5136 C: "MAP MIDI_INSTRUMENT 0 3 0 gig '/usr/share/Steinway D.gig' 0
5137 0.8 PERSISTENT"
5138
5139 S: "OK"
5140
5141 C: "MAP MIDI_INSTRUMENT 0 4 50 gig '/home/john/foostrings.gig' 7
5142 1.0"
5143
5144 S: "OK"
5145
5146 C: "MAP MIDI_INSTRUMENT 0 0 0 gig '/usr/share/piano.gig' 0 1.0
5147 'Normal Piano'"
5148
5149
5150
5151
5152 Schoenebeck Expires September 12, 2019 [Page 92]
5153
5154 Internet-Draft LinuxSampler Control Protocol March 2019
5155
5156
5157 S: "OK"
5158
5159 C: "MAP MIDI_INSTRUMENT 0 1 0 gig '/usr/share/piano.gig' 0 0.25
5160 'Silent Piano'"
5161
5162 S: "OK"
5163
5164 C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/
5165 foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"
5166
5167 S: "OK"
5168
5169 6.7.8. Getting amount of MIDI instrument map entries
5170
5171 The front-end can query the amount of currently existing entries in a
5172 MIDI instrument map by sending the following command:
5173
5174 GET MIDI_INSTRUMENTS <map>
5175
5176 The front-end can query the amount of currently existing entries in
5177 all MIDI instrument maps by sending the following command:
5178
5179 GET MIDI_INSTRUMENTS ALL
5180
5181 Possible Answers:
5182
5183 The sampler will answer by sending the current number of entries
5184 in the MIDI instrument map(s).
5185
5186 Example:
5187
5188 C: "GET MIDI_INSTRUMENTS 0"
5189
5190 S: "234"
5191
5192 C: "GET MIDI_INSTRUMENTS ALL"
5193
5194 S: "954"
5195
5196 6.7.9. Getting indeces of all entries of a MIDI instrument map
5197
5198 The front-end can query a list of all currently existing entries in a
5199 certain MIDI instrument map by sending the following command:
5200
5201 LIST MIDI_INSTRUMENTS <map>
5202
5203 Where <map> is the numeric ID of the MIDI instrument map.
5204
5205
5206
5207
5208 Schoenebeck Expires September 12, 2019 [Page 93]
5209
5210 Internet-Draft LinuxSampler Control Protocol March 2019
5211
5212
5213 The front-end can query a list of all currently existing entries of
5214 all MIDI instrument maps by sending the following command:
5215
5216 LIST MIDI_INSTRUMENTS ALL
5217
5218 Possible Answers:
5219
5220 The sampler will answer by sending a comma separated list of map
5221 ID - MIDI bank - MIDI program triples, where each triple is
5222 encapsulated into curly braces. The list is returned in one
5223 single line. Each triple just reflects the key of the respective
5224 map entry, thus subsequent "GET MIDI_INSTRUMENT INFO"
5225 (Section 6.7.11) command(s) are necessary to retrieve detailed
5226 information about each entry.
5227
5228 Example:
5229
5230 C: "LIST MIDI_INSTRUMENTS 0"
5231
5232 S: "{0,0,0},{0,0,1},{0,0,3},{0,1,4},{1,127,127}"
5233
5234 6.7.10. Remove an entry from the MIDI instrument map
5235
5236 The front-end can delete an entry from a MIDI instrument map by
5237 sending the following command:
5238
5239 UNMAP MIDI_INSTRUMENT <map> <midi_bank> <midi_prog>
5240
5241 Where <map> is the numeric ID of the MIDI instrument map, <midi_bank>
5242 is an integer value between 0..16383 reflecting the MIDI bank value
5243 and <midi_prog> an integer value between 0..127 reflecting the MIDI
5244 program value of the map's entrie's key index triple.
5245
5246 Possible Answers:
5247
5248 "OK" -
5249
5250 usually
5251
5252 "ERR:<error-code>:<error-message>" -
5253
5254 when index out of bounds
5255
5256 Example:
5257
5258 C: "UNMAP MIDI_INSTRUMENT 0 2 127"
5259
5260 S: "OK"
5261
5262
5263
5264 Schoenebeck Expires September 12, 2019 [Page 94]
5265
5266 Internet-Draft LinuxSampler Control Protocol March 2019
5267
5268
5269 6.7.11. Get current settings of MIDI instrument map entry
5270
5271 The front-end can retrieve the current settings of a certain
5272 instrument map entry by sending the following command:
5273
5274 GET MIDI_INSTRUMENT INFO <map> <midi_bank> <midi_prog>
5275
5276 Where <map> is the numeric ID of the MIDI instrument map, <midi_bank>
5277 is an integer value between 0..16383 reflecting the MIDI bank value,
5278 <midi_bank> and <midi_prog> an integer value between 0..127
5279 reflecting the MIDI program value of the map's entrie's key index
5280 triple.
5281
5282 Possible Answers:
5283
5284 LinuxSampler will answer by sending a <CRLF> separated list. Each
5285 answer line begins with the information category name followed by
5286 a colon and then a space character <SP> and finally the info
5287 character string to that info category. At the moment the
5288 following categories are defined:
5289
5290 "NAME" -
5291
5292 Name for this MIDI instrument map entry (if defined). This
5293 name shall be used by frontends for displaying a name for this
5294 mapped instrument. It can be set and changed with the "MAP
5295 MIDI_INSTRUMENT" (Section 6.7.7) command and does not have to
5296 be unique. (note that this character string may contain escape
5297 sequences (Section 7.1))
5298
5299 "ENGINE_NAME" -
5300
5301 Name of the engine to be deployed for this instrument.
5302
5303 "INSTRUMENT_FILE" -
5304
5305 File name of the instrument (note that this path may contain
5306 escape sequences (Section 7.1)).
5307
5308 "INSTRUMENT_NR" -
5309
5310 Index of the instrument within the file.
5311
5312 "INSTRUMENT_NAME" -
5313
5314 Name of the loaded instrument as reflected by its file. In
5315 contrast to the "NAME" field, the "INSTRUMENT_NAME" field
5316
5317
5318
5319
5320 Schoenebeck Expires September 12, 2019 [Page 95]
5321
5322 Internet-Draft LinuxSampler Control Protocol March 2019
5323
5324
5325 cannot be changed (note that this character string may contain
5326 escape sequences (Section 7.1)).
5327
5328 "LOAD_MODE" -
5329
5330 Life time of instrument (see "MAP MIDI_INSTRUMENT"
5331 (Section 6.7.7) for details about this setting).
5332
5333 "VOLUME" -
5334
5335 master volume of the instrument as optionally dotted number
5336 (where a value < 1.0 means attenuation and a value > 1.0 means
5337 amplification)
5338
5339 The mentioned fields above don't have to be in particular order.
5340
5341 Example:
5342
5343 C: "GET MIDI_INSTRUMENT INFO 1 45 120"
5344
5345 S: "NAME: Drums for Foo Song"
5346
5347 "ENGINE_NAME: GigEngine"
5348
5349 "INSTRUMENT_FILE: /usr/share/joesdrumkit.gig"
5350
5351 "INSTRUMENT_NR: 0"
5352
5353 "INSTRUMENT_NAME: Joe's Drumkit"
5354
5355 "LOAD_MODE: PERSISTENT"
5356
5357 "VOLUME: 1.0"
5358
5359 "."
5360
5361 6.7.12. Clear MIDI instrument map
5362
5363 The front-end can clear a whole MIDI instrument map, that is delete
5364 all its entries by sending the following command:
5365
5366 CLEAR MIDI_INSTRUMENTS <map>
5367
5368 Where <map> is the numeric ID of the map to clear.
5369
5370 The front-end can clear all MIDI instrument maps, that is delete all
5371 entries of all maps by sending the following command:
5372
5373
5374
5375
5376 Schoenebeck Expires September 12, 2019 [Page 96]
5377
5378 Internet-Draft LinuxSampler Control Protocol March 2019
5379
5380
5381 CLEAR MIDI_INSTRUMENTS ALL
5382
5383 The command "CLEAR MIDI_INSTRUMENTS ALL" does not delete the maps,
5384 only their entries, thus the map's settings like custom name will be
5385 preservevd.
5386
5387 Possible Answers:
5388
5389 "OK" -
5390
5391 always
5392
5393 Examples:
5394
5395 C: "CLEAR MIDI_INSTRUMENTS 0"
5396
5397 S: "OK"
5398
5399 C: "CLEAR MIDI_INSTRUMENTS ALL"
5400
5401 S: "OK"
5402
5403 6.8. Managing Instruments Database
5404
5405 The following commands describe how to use and manage the instruments
5406 database.
5407
5408 Notice:
5409
5410 All command arguments representing a path or instrument/directory
5411 name support escape sequences as described in chapter "Character
5412 Set and Escape Sequences (Section 7.1)".
5413
5414 All occurrences of a forward slash in instrument and directory
5415 names are escaped with its hex (\x2f) or octal (\057) escape
5416 sequence.
5417
5418 6.8.1. Creating a new instrument directory
5419
5420 The front-end can add a new instrument directory to the instruments
5421 database by sending the following command:
5422
5423 ADD DB_INSTRUMENT_DIRECTORY <dir>
5424
5425 Where <dir> is the absolute path name of the directory to be created
5426 (encapsulated into apostrophes).
5427
5428 Possible Answers:
5429
5430
5431
5432 Schoenebeck Expires September 12, 2019 [Page 97]
5433
5434 Internet-Draft LinuxSampler Control Protocol March 2019
5435
5436
5437 "OK" -
5438
5439 on success
5440
5441 "ERR:<error-code>:<error-message>" -
5442
5443 when the directory could not be created, which can happen if
5444 the directory already exists or the name contains not allowed
5445 symbols
5446
5447 Examples:
5448
5449 C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'"
5450
5451 S: "OK"
5452
5453 6.8.2. Deleting an instrument directory
5454
5455 The front-end can delete a particular instrument directory from the
5456 instruments database by sending the following command:
5457
5458 REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] <dir>
5459
5460 Where <dir> is the absolute path name of the directory to delete.
5461 The optional FORCE argument can be used to force the deletion of a
5462 non-empty directory and all its content.
5463
5464 Possible Answers:
5465
5466 "OK" -
5467
5468 if the directory is deleted successfully
5469
5470 "ERR:<error-code>:<error-message>" -
5471
5472 if the given directory does not exist, or if trying to delete a
5473 non-empty directory, without using the FORCE argument.
5474
5475 Examples:
5476
5477 C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'"
5478
5479 S: "OK"
5480
5481
5482
5483
5484
5485
5486
5487
5488 Schoenebeck Expires September 12, 2019 [Page 98]
5489
5490 Internet-Draft LinuxSampler Control Protocol March 2019
5491
5492
5493 6.8.3. Getting amount of instrument directories
5494
5495 The front-end can retrieve the current amount of directories in a
5496 specific directory by sending the following command:
5497
5498 GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] <dir>
5499
5500 Where <dir> should be replaced by the absolute path name of the
5501 directory. If RECURSIVE is specified, the number of all directories,
5502 including those located in subdirectories of the specified directory,
5503 will be returned.
5504
5505 Possible Answers:
5506
5507 The current number of instrument directories in the specified
5508 directory.
5509
5510 "ERR:<error-code>:<error-message>" -
5511
5512 if the given directory does not exist.
5513
5514 Example:
5515
5516 C: "GET DB_INSTRUMENT_DIRECTORIES '/'"
5517
5518 S: "2"
5519
5520 6.8.4. Listing all directories in specific directory
5521
5522 The front-end can retrieve the current list of directories in
5523 specific directory by sending the following command:
5524
5525 LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] <dir>
5526
5527 Where <dir> should be replaced by the absolute path name of the
5528 directory. If RECURSIVE is specified, the absolute path names of all
5529 directories, including those located in subdirectories of the
5530 specified directory, will be returned.
5531
5532 Possible Answers:
5533
5534 A comma separated list of all instrument directories (encapsulated
5535 into apostrophes) in the specified directory.
5536
5537 "ERR:<error-code>:<error-message>" -
5538
5539 if the given directory does not exist.
5540
5541
5542
5543
5544 Schoenebeck Expires September 12, 2019 [Page 99]
5545
5546 Internet-Draft LinuxSampler Control Protocol March 2019
5547
5548
5549 Example:
5550
5551 C: "LIST DB_INSTRUMENT_DIRECTORIES '/'"
5552
5553 S: "'Piano Collection','Percussion Collection'"
5554
5555 C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'"
5556
5557 S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano
5558 Collection/Acoustic/New','/Percussion Collection'"
5559
5560 6.8.5. Getting instrument directory information
5561
5562 The front-end can ask for the current settings of an instrument
5563 directory by sending the following command:
5564
5565 GET DB_INSTRUMENT_DIRECTORY INFO <dir>
5566
5567 Where <dir> should be replaced by the absolute path name of the
5568 directory the front-end is interested in.
5569
5570 Possible Answers:
5571
5572 LinuxSampler will answer by sending a <CRLF> separated list. Each
5573 answer line begins with the settings category name followed by a
5574 colon and then a space character <SP> and finally the info
5575 character string to that setting category. At the moment the
5576 following categories are defined:
5577
5578
5579
5580 DESCRIPTION -
5581
5582 A brief description of the directory content. Note that the
5583 character string may contain escape sequences (Section 7.1).
5584
5585 CREATED -
5586
5587 The creation date and time of the directory, represented in
5588 "YYYY-MM-DD HH:MM:SS" format
5589
5590 MODIFIED -
5591
5592 The date and time of the last modification of the directory,
5593 represented in "YYYY-MM-DD HH:MM:SS" format
5594
5595 The mentioned fields above don't have to be in particular order.
5596
5597
5598
5599
5600 Schoenebeck Expires September 12, 2019 [Page 100]
5601
5602 Internet-Draft LinuxSampler Control Protocol March 2019
5603
5604
5605 Example:
5606
5607 C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'"
5608
5609 S: "DESCRIPTION: Piano collection of instruments in GigaSampler
5610 format."
5611
5612 "CREATED: 2007-02-05 10:23:12"
5613
5614 "MODIFIED: 2007-04-07 12:50:21"
5615
5616 "."
5617
5618 6.8.6. Renaming an instrument directory
5619
5620 The front-end can alter the name of a specific instrument directory
5621 by sending the following command:
5622
5623 SET DB_INSTRUMENT_DIRECTORY NAME <dir> <name>
5624
5625 Where <dir> is the absolute path name of the directory and <name> is
5626 the new name for that directory.
5627
5628 Possible Answers:
5629
5630 "OK" -
5631
5632 on success
5633
5634 "ERR:<error-code>:<error-message>" -
5635
5636 in case the given directory does not exists, or if a directory
5637 with name equal to the new name already exists.
5638
5639 Example:
5640
5641 C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic'
5642 'Acoustic'"
5643
5644 S: "OK"
5645
5646 6.8.7. Moving an instrument directory
5647
5648 The front-end can move a specific instrument directory by sending the
5649 following command:
5650
5651 MOVE DB_INSTRUMENT_DIRECTORY <dir> <dst>
5652
5653
5654
5655
5656 Schoenebeck Expires September 12, 2019 [Page 101]
5657
5658 Internet-Draft LinuxSampler Control Protocol March 2019
5659
5660
5661 Where <dir> is the absolute path name of the directory to move and
5662 <dst> is the location where the directory will be moved to.
5663
5664 Possible Answers:
5665
5666 "OK" -
5667
5668 on success
5669
5670 "ERR:<error-code>:<error-message>" -
5671
5672 in case a given directory does not exists, or if a directory
5673 with name equal to the name of the specified directory already
5674 exists in the destination directory. Error is also thrown when
5675 trying to move a directory to a subdirectory of itself.
5676
5677 Example:
5678
5679 C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/
5680 Acoustic'"
5681
5682 S: "OK"
5683
5684 6.8.8. Copying instrument directories
5685
5686 The front-end can copy a specific instrument directory by sending the
5687 following command:
5688
5689 COPY DB_INSTRUMENT_DIRECTORY <dir> <dst>
5690
5691 Where <dir> is the absolute path name of the directory to copy and
5692 <dst> is the location where the directory will be copied to.
5693
5694 Possible Answers:
5695
5696 "OK" -
5697
5698 on success
5699
5700 "ERR:<error-code>:<error-message>" -
5701
5702 in case a given directory does not exists, or if a directory
5703 with name equal to the name of the specified directory already
5704 exists in the destination directory. Error is also thrown when
5705 trying to copy a directory to a subdirectory of itself.
5706
5707 Example:
5708
5709
5710
5711
5712 Schoenebeck Expires September 12, 2019 [Page 102]
5713
5714 Internet-Draft LinuxSampler Control Protocol March 2019
5715
5716
5717 C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic'
5718 '/Acoustic/Pianos'"
5719
5720 S: "OK"
5721
5722 6.8.9. Changing the description of directory
5723
5724 The front-end can alter the description of a specific instrument
5725 directory by sending the following command:
5726
5727 SET DB_INSTRUMENT_DIRECTORY DESCRIPTION <dir> <desc>
5728
5729 Where <dir> is the absolute path name of the directory and <desc> is
5730 the new description for the directory (encapsulated into apostrophes,
5731 supporting escape sequences as described in chapter "Character Set
5732 and Escape Sequences (Section 7.1)").
5733
5734 Possible Answers:
5735
5736 "OK" -
5737
5738 on success
5739
5740 "ERR:<error-code>:<error-message>" -
5741
5742 in case the given directory does not exists.
5743
5744 Example:
5745
5746 C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A
5747 collection of piano instruments in various format.'"
5748
5749 S: "OK"
5750
5751 6.8.10. Finding directories
5752
5753 The front-end can search for directories in specific directory by
5754 sending the following command:
5755
5756 FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] <dir> <criteria-
5757 list>
5758
5759 Where <dir> should be replaced by the absolute path name of the
5760 directory to search in. If NON_RECURSIVE is specified, the
5761 directories located in subdirectories of the specified directory will
5762 not be searched. <criteria-list> is a list of search criterias in
5763 form of "key1=val1 key2=val2 ...". The following criterias are
5764 allowed:
5765
5766
5767
5768 Schoenebeck Expires September 12, 2019 [Page 103]
5769
5770 Internet-Draft LinuxSampler Control Protocol March 2019
5771
5772
5773 Where <search-string> is either a regular expression, or a word list
5774 separated with spaces for OR search and with '+' for AND search.
5775
5776 Possible Answers:
5777
5778 A comma separated list with the absolute path names (encapsulated
5779 into apostrophes) of all directories in the specified directory
5780 that satisfy the supplied search criterias.
5781
5782 "ERR:<error-code>:<error-message>" -
5783
5784 if the given directory does not exist.
5785
5786 Example:
5787
5788 C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'"
5789
5790 S: "'/Piano Collection'"
5791
5792 C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01
5793 09:30:13'"
5794
5795 S: "'/Piano Collection','/Percussions'"
5796
5797 6.8.11. Adding instruments to the instruments database
5798
5799 The front-end can add one or more instruments to the instruments
5800 database by sending the following command:
5801
5802 ADD DB_INSTRUMENTS [NON_MODAL] [<mode>[ FILE_AS_DIR]] <db_dir>
5803 <file_path> [<instr_index>]
5804
5805 Where <db_dir> is the absolute path name of a directory (encapsulated
5806 into apostrophes) in the instruments database in which only the new
5807 instruments (that are not already in the database) will be added,
5808 <file_path> is the absolute path name of a file or directory in the
5809 file system (encapsulated into apostrophes). In case an instrument
5810 file is supplied, only the instruments in the specified file will be
5811 added to the instruments database. If the optional <instr_index>
5812 (the index of the instrument within the given file) is supplied too,
5813 then only the specified instrument will be added. In case a
5814 directory is supplied, the instruments in that directory will be
5815 added. The OPTIONAL <mode> argument is only applied when a directory
5816 is provided as <file_path> and specifies how the scanning will be
5817 done and has exactly the following possibilities:
5818
5819 "RECURSIVE" -
5820
5821
5822
5823
5824 Schoenebeck Expires September 12, 2019 [Page 104]
5825
5826 Internet-Draft LinuxSampler Control Protocol March 2019
5827
5828
5829 All instruments will be processed, including those in the
5830 subdirectories, and the respective subdirectory tree structure
5831 will be recreated in the instruments database
5832
5833 "NON_RECURSIVE" -
5834
5835 Only the instruments in the specified directory will be added,
5836 the instruments in the subdirectories will not be processed.
5837
5838 "FLAT" -
5839
5840 All instruments will be processed, including those in the
5841 subdirectories, but the respective subdirectory structure will
5842 not be recreated in the instruments database. All instruments
5843 will be added directly in the specified database directory.
5844
5845 If FILE_AS_DIR argument is supplied, all instruments in an instrument
5846 file will be added to a separate directory in the instruments
5847 database, which name will be the name of the instrument file with the
5848 file extension stripped off.
5849
5850 The difference between regular and NON_MODAL versions of the command
5851 is that the regular command returns when the scanning is finished
5852 while NON_MODAL version returns immediately and a background process
5853 is launched. The GET DB_INSTRUMENTS_JOB INFO (Section 6.8.21)
5854 command can be used to monitor the scanning progress.
5855
5856 Possible Answers:
5857
5858 "OK" -
5859
5860 on success when NON_MODAL is not supplied
5861
5862 "OK[<job-id>]" -
5863
5864 on success when NON_MODAL is supplied, where <job-id> is a
5865 numerical ID used to obtain status information about the job
5866 progress. See GET DB_INSTRUMENTS_JOB INFO (Section 6.8.21)
5867
5868 "ERR:<error-code>:<error-message>" -
5869
5870 if an invalid path is specified.
5871
5872 Examples:
5873
5874 C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI
5875 Bosendorfer 290.gig' 0"
5876
5877
5878
5879
5880 Schoenebeck Expires September 12, 2019 [Page 105]
5881
5882 Internet-Draft LinuxSampler Control Protocol March 2019
5883
5884
5885 S: "OK"
5886
5887 6.8.12. Removing an instrument
5888
5889 The front-end can remove a particular instrument from the instruments
5890 database by sending the following command:
5891
5892 REMOVE DB_INSTRUMENT <instr_path>
5893
5894 Where <instr_path> is the absolute path name (in the instruments
5895 database) of the instrument to remove.
5896
5897 Possible Answers:
5898
5899 "OK" -
5900
5901 if the instrument is removed successfully
5902
5903 "ERR:<error-code>:<error-message>" -
5904
5905 if the given path does not exist or is a directory.