/[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 558 - (show annotations) (download)
Sat May 21 01:30:30 2005 UTC (18 years, 10 months ago) by schoenebeck
File MIME type: text/plain
File size: 102903 byte(s)
LSCP events renamed:
"CHANNELS" -> "CHANNEL_COUNT"
"INFO" -> "CHANNEL_INFO"

1
2
3 LinuxSampler Developers C. Schoenebeck
4 Internet-Draft Interessengemeinschaft Software
5 Expires: November 19, 2005 Engineering e. V.
6 May 21, 2005
7
8
9 LinuxSampler Control Protocol
10 lscp.txt
11
12 Status of this Memo
13
14 This document is an Internet-Draft and is in full conformance with
15 all provisions of Section 10 of RFC2026.
16
17 Internet-Drafts are working documents of the Internet Engineering
18 Task Force (IETF), its areas, and its working groups. Note that
19 other groups may also distribute working documents as
20 Internet-Drafts.
21
22 Internet-Drafts are draft documents valid for a maximum of six months
23 and may be updated, replaced, or obsoleted by other documents at any
24 time. It is inappropriate to use Internet-Drafts as reference
25 material or to cite them other than as "work in progress."
26
27 The list of current Internet-Drafts can be accessed at
28 http://www.ietf.org/ietf/1id-abstracts.txt.
29
30 The list of Internet-Draft Shadow Directories can be accessed at
31 http://www.ietf.org/shadow.html.
32
33 This Internet-Draft will expire on November 19, 2005.
34
35 Copyright Notice
36
37 Copyright (C) The Internet Society (2005). All Rights Reserved.
38
39 Abstract
40
41 The LinuxSampler Control Protocol (LSCP) is an application-level
42 protocol primarily intended for local and remote controlling the
43 LinuxSampler main application, which is a sophisticated console
44 application essentially playing back audio samples and manipulating
45 the samples in real time to certain extent.
46
47
48
49
50
51
52
53
54
55 Schoenebeck Expires November 19, 2005 [Page 1]
56
57 Internet-Draft LinuxSampler Control Protocol May 2005
58
59
60 Table of Contents
61
62 1. Requirements notation . . . . . . . . . . . . . . . . . . . 4
63 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5
64 3. Focus of this protocol . . . . . . . . . . . . . . . . . . . 6
65 4. Communication Overview . . . . . . . . . . . . . . . . . . . 7
66 4.1 Request/response communication method . . . . . . . . . . 7
67 4.1.1 Result format . . . . . . . . . . . . . . . . . . . . 8
68 4.2 Subscribe/notify communication method . . . . . . . . . . 9
69 5. Description for control commands . . . . . . . . . . . . . . 12
70 5.1 Ignored lines and comments . . . . . . . . . . . . . . . . 12
71 5.2 Configuring audio drivers . . . . . . . . . . . . . . . . 12
72 5.2.1 Getting amount of available audio output drivers . . . 12
73 5.2.2 Getting all available audio output drivers . . . . . . 13
74 5.2.3 Getting information about a specific audio output
75 driver . . . . . . . . . . . . . . . . . . . . . . . . 13
76 5.2.4 Getting information about specific audio output
77 driver parameter . . . . . . . . . . . . . . . . . . . 14
78 5.2.5 Creating an audio output device . . . . . . . . . . . 17
79 5.2.6 Destroying an audio output device . . . . . . . . . . 17
80 5.2.7 Getting all created audio output device count . . . . 18
81 5.2.8 Getting all created audio output device list . . . . . 18
82 5.2.9 Getting current settings of an audio output device . . 19
83 5.2.10 Changing settings of audio output devices . . . . . 20
84 5.2.11 Getting information about an audio channel . . . . . 20
85 5.2.12 Getting information about specific audio channel
86 parameter . . . . . . . . . . . . . . . . . . . . . 22
87 5.2.13 Changing settings of audio output channels . . . . . 23
88 5.3 Configuring MIDI input drivers . . . . . . . . . . . . . . 24
89 5.3.1 Getting amount of available MIDI input drivers . . . . 24
90 5.3.2 Getting all available MIDI input drivers . . . . . . . 25
91 5.3.3 Getting information about a specific MIDI input
92 driver . . . . . . . . . . . . . . . . . . . . . . . . 25
93 5.3.4 Getting information about specific MIDI input
94 driver parameter . . . . . . . . . . . . . . . . . . . 26
95 5.3.5 Creating a MIDI input device . . . . . . . . . . . . . 28
96 5.3.6 Destroying a MIDI input device . . . . . . . . . . . . 29
97 5.3.7 Getting all created MIDI input device count . . . . . 29
98 5.3.8 Getting all created MIDI input device list . . . . . . 29
99 5.3.9 Getting current settings of a MIDI input device . . . 30
100 5.3.10 Changing settings of MIDI input devices . . . . . . 31
101 5.3.11 Getting information about a MIDI port . . . . . . . 31
102 5.3.12 Getting information about specific MIDI port
103 parameter . . . . . . . . . . . . . . . . . . . . . 32
104 5.3.13 Changing settings of MIDI input ports . . . . . . . 33
105 5.4 Configuring sampler channels . . . . . . . . . . . . . . . 34
106 5.4.1 Loading an instrument . . . . . . . . . . . . . . . . 34
107 5.4.2 Loading a sampler engine . . . . . . . . . . . . . . . 35
108
109
110
111 Schoenebeck Expires November 19, 2005 [Page 2]
112
113 Internet-Draft LinuxSampler Control Protocol May 2005
114
115
116 5.4.3 Getting all created sampler channel count . . . . . . 36
117 5.4.4 Getting all created sampler channel list . . . . . . . 36
118 5.4.5 Adding a new sampler channel . . . . . . . . . . . . . 36
119 5.4.6 Removing a sampler channel . . . . . . . . . . . . . . 37
120 5.4.7 Getting amount of available engines . . . . . . . . . 38
121 5.4.8 Getting all available engines . . . . . . . . . . . . 38
122 5.4.9 Getting information about an engine . . . . . . . . . 38
123 5.4.10 Getting sampler channel information . . . . . . . . 39
124 5.4.11 Current number of active voices . . . . . . . . . . 41
125 5.4.12 Current number of active disk streams . . . . . . . 41
126 5.4.13 Current fill state of disk stream buffers . . . . . 42
127 5.4.14 Setting audio output device . . . . . . . . . . . . 42
128 5.4.15 Setting audio output type . . . . . . . . . . . . . 43
129 5.4.16 Setting audio output channel . . . . . . . . . . . . 44
130 5.4.17 Setting MIDI input device . . . . . . . . . . . . . 44
131 5.4.18 Setting MIDI input type . . . . . . . . . . . . . . 45
132 5.4.19 Setting MIDI input port . . . . . . . . . . . . . . 45
133 5.4.20 Setting MIDI input channel . . . . . . . . . . . . . 46
134 5.4.21 Setting channel volume . . . . . . . . . . . . . . . 46
135 5.4.22 Resetting a sampler channel . . . . . . . . . . . . 47
136 5.5 Controlling connection . . . . . . . . . . . . . . . . . . 48
137 5.5.1 Register front-end for receiving event messages . . . 48
138 5.5.2 Unregister front-end for not receiving event
139 messages . . . . . . . . . . . . . . . . . . . . . . . 48
140 5.5.3 Enable or disable echo of commands . . . . . . . . . . 49
141 5.5.4 Close client connection . . . . . . . . . . . . . . . 49
142 5.6 Global commands . . . . . . . . . . . . . . . . . . . . . 50
143 5.6.1 Reset sampler . . . . . . . . . . . . . . . . . . . . 50
144 6. Command Syntax . . . . . . . . . . . . . . . . . . . . . . . 51
145 7. Events . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
146 7.1 Number of sampler channels changed . . . . . . . . . . . . 52
147 7.2 Number of active voices changed . . . . . . . . . . . . . 52
148 7.3 Number of active disk streams changed . . . . . . . . . . 52
149 7.4 Disk stream buffer fill state changed . . . . . . . . . . 53
150 7.5 Channel information changed . . . . . . . . . . . . . . . 53
151 7.6 Miscellaneous and debugging events . . . . . . . . . . . . 53
152 8. Security Considerations . . . . . . . . . . . . . . . . . . 55
153 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 56
154 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 56
155 Author's Address . . . . . . . . . . . . . . . . . . . . . . 56
156 Intellectual Property and Copyright Statements . . . . . . . 57
157
158
159
160
161
162
163
164
165
166
167 Schoenebeck Expires November 19, 2005 [Page 3]
168
169 Internet-Draft LinuxSampler Control Protocol May 2005
170
171
172 1. Requirements notation
173
174 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
175 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
176 document are to be interpreted as described in [RFC2119].
177
178 This protocol is always case-sensitive if not explicitly claimed the
179 opposite.
180
181 In examples, "C:" and "S:" indicate lines sent by the client
182 (front-end) and server (LinuxSampler) respectively. Lines in
183 examples must be interpreted as every line being CRLF terminated
184 (carriage return character followed by line feed character as defined
185 in the ASCII standard), thus the following example:
186
187 C: "some line"
188 "another line"
189
190 must actually be interpreted as client sending the following message:
191
192 "some line<CR><LF>another line<CR><LF>"
193
194 where <CR> symbolizes the carriage return character and <LF> the line
195 feed character as defined in the ASCII standard.
196
197 Due to technical reasons, messages can arbitrary be fragmented, means
198 the following example:
199
200 S: "abcd"
201
202 could also happen to be sent in three messages like in the following
203 sequence scenario:
204
205 o server sending message "a"
206 o followed by a delay (pause) with arbitrary duration
207 o followed by server sending message "bcd<CR>"
208 o again followed by a delay (pause) with arbitrary duration
209 o followed by server sending the message "<LF>"
210
211 where again <CR> and <LF> symbolize the carriage return and line feed
212 characters respectively.
213
214
215
216
217
218
219
220
221
222
223 Schoenebeck Expires November 19, 2005 [Page 4]
224
225 Internet-Draft LinuxSampler Control Protocol May 2005
226
227
228 2. Introduction
229
230 LinuxSampler is a so called software sampler application capable to
231 playback audio samples from a computer's Random Access Memory (RAM)
232 as well as directly streaming it from disk. LinuxSampler is designed
233 to be modular. It provides several so called "sampler engines" where
234 each engine is specialized for a certain purpose. LinuxSampler has
235 virtual channels which will be referred in this document as "sampler
236 channels". The channels are in such way virtual as they can be
237 connected to an arbitrary MIDI input method and arbitrary MIDI
238 channel (e.g. sampler channel 17 could be connected to an ALSA
239 sequencer device 64:0 and listening to MIDI channel 1 there). Each
240 sampler engine will be assigned an own instance of one of the
241 available sampler engines (e.g. GigEngine, DLSEngine). The audio
242 output of each sampler channel can be routed to an arbitrary audio
243 output method (ALSA / JACK) and an arbitrary audio output channel
244 there.
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279 Schoenebeck Expires November 19, 2005 [Page 5]
280
281 Internet-Draft LinuxSampler Control Protocol May 2005
282
283
284 3. Focus of this protocol
285
286 Main focus of this protocol is to provide a way to configure a
287 running LinuxSampler instance and to retrieve information about it.
288 The focus of this protocol is not to provide a way to control
289 synthesis parameters or even to trigger or release notes. Or in
290 other words; the focus are those functionalities which are not
291 covered by MIDI or which may at most be handled via MIDI System
292 Exclusive Messages.
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335 Schoenebeck Expires November 19, 2005 [Page 6]
336
337 Internet-Draft LinuxSampler Control Protocol May 2005
338
339
340 4. Communication Overview
341
342 There are two distinct methods of communication between a running
343 instance of LinuxSampler and one or more control applications, so
344 called "front-ends": a simple request/response communication method
345 used by the clients to give commands to the server as well as to
346 inquire about server's status and a subscribe/notify communication
347 method used by the client to subscribe to and receive notifications
348 of certain events as they happen on the server. The latter needs
349 more effort to be implemented in the front-end application. The two
350 communication methods will be described next.
351
352 4.1 Request/response communication method
353
354 This simple communication method is based on TCP. The front-end
355 application establishes a TCP connection to the LinuxSampler instance
356 on a certain host system. Then the front-end application will send
357 certain ASCII based commands as defined in this document (every
358 command line must be CRLF terminated - see "Conventions used in this
359 document" at the beginning of this document) and the LinuxSampler
360 application will response after a certain process time with an
361 appropriate ASCII based answer, also as defined in this document. So
362 this TCP communication is simply based on query and answer paradigm.
363 That way LinuxSampler is only able to answer on queries from
364 front-ends, but not able to automatically send messages to the client
365 if it's not asked to. The fronted should not reconnect to
366 LinuxSampler for every single command, instead it should keep the
367 connection established and simply resend message(s) for subsequent
368 commands. To keep information in the front-end up-to-date the
369 front-end has to periodically send new requests to get the current
370 information from the LinuxSampler instance. This is often referred
371 to as "polling". While polling is simple to implement and may be OK
372 to use in some cases, there may be disadvantages to polling such as
373 network traffic overhead and information being out of date. It is
374 possible for a client or several clients to open more than one
375 connection to the server at the same time. It is also possible to
376 send more than one request to the server at the same time but if
377 those requests are sent over the same connection server MUST execute
378 them sequentially. Upon executing a request server will produce a
379 result set and send it to the client. Each and every request made by
380 the client MUST result in a result set being sent back to the client.
381 No other data other than a result set may be sent by a server to a
382 client. No result set may be sent to a client without the client
383 sending request to the server first. On any particular connection,
384 result sets MUST be sent in their entirety without being interrupted
385 by other result sets. If several requests got queued up at the
386 server they MUST be processed in the order they were received and
387 result sets MUST be sent back in the same order.
388
389
390
391 Schoenebeck Expires November 19, 2005 [Page 7]
392
393 Internet-Draft LinuxSampler Control Protocol May 2005
394
395
396 4.1.1 Result format
397
398 Result set could be one of the following types:
399
400 1. Normal
401 2. Warning
402 3. Error
403
404 Warning and Error result sets MUST be single line and have the
405 following format:
406
407 o "WRN:<warning-code>:<warning-message>"
408 o "ERR:<error-code>:<error-message>"
409
410 Where <warning-code> and <error-code> are numeric unique identifiers
411 of the warning or error and <warning-message> and <error-message> are
412 human readable descriptions of the warning or error respectively.
413
414 Examples:
415
416 C: "LOAD INSTRUMENT '/home/me/Boesendorfer24bit.gig" 0 0
417 S: "WRN:32:This is a 24 bit patch which is not supported natively
418 yet."
419
420 C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA EAR"
421 S: "ERR:3456:Audio output driver 'ALSA' does not have a parameter
422 'EAR'."
423
424 C: "GET AUDIO_OUTPUT_DEVICE INFO 123456"
425 S: "ERR:9:There is no audio output device with index 123456."
426
427 Normal result sets could be:
428
429 1. Empty
430 2. Single line
431 3. Multi-line
432
433 Empty result set is issued when the server only needed to acknowledge
434 the fact that the request was received and it was processed
435 successfully and no additional information is available. This result
436 set has the following format:
437
438 "OK"
439
440 Example:
441
442 C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 CHANNELS=4"
443
444
445
446
447 Schoenebeck Expires November 19, 2005 [Page 8]
448
449 Internet-Draft LinuxSampler Control Protocol May 2005
450
451
452 S: "OK"
453
454 Single line result sets are command specific. One example of a
455 single line result set is an empty line. Multi-line result sets are
456 command specific and may include one or more lines of information.
457 They MUST always end with the following line:
458
459 "."
460
461 Example:
462
463 C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
464 S: "DRIVER: ALSA"
465 "CHANNELS: 2"
466 "SAMPLERATE: 44100"
467 "ACTIVE: true"
468 "FRAGMENTS: 2"
469 "FRAGMENTSIZE: 128"
470 "CARD: '0,0'"
471 "."
472
473 In addition to above mentioned formats, warnings and empty result
474 sets MAY be indexed. In this case, they have the following formats
475 respectively:
476
477 o "WRN[<index>]:<warning-code>:<warning-message>"
478 o "OK[<index>]"
479
480 where <index> is command specific and is used to indicate channel
481 number that the result set was related to or other integer value.
482
483 Each line of the result set MUST end with <CRLF>.
484
485 Examples:
486
487 C: "ADD CHANNEL"
488 S: "OK[12]"
489
490 C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"
491 S: "WRN[0]:32:Sample rate not supported, using 44100 instead."
492
493 4.2 Subscribe/notify communication method
494
495 This more sophisticated communication method is actually only an
496 extension of the simple request/response communication method. The
497 front-end still uses a TCP connection and sends the same commands on
498 the TCP connection. Two extra commands are SUBSCRIBE and UNSUBSCRIBE
499 commands that allow a client to tell the server that it is interested
500
501
502
503 Schoenebeck Expires November 19, 2005 [Page 9]
504
505 Internet-Draft LinuxSampler Control Protocol May 2005
506
507
508 in receiving notifications about certain events as they happen on the
509 server. The SUBSCRIBE command has the following syntax:
510
511 SUBSCRIBE <event-id>
512
513 where <event-id> will be replaced by the respective event that client
514 wants to subscribe to. Upon receiving such request, server SHOULD
515 respond with OK and start sending EVENT notifications when a given
516 even has occurred to the front-end when an event has occurred. It
517 MAY be possible certain events may be sent before OK response during
518 real time nature of their generation. Event messages have the
519 following format:
520
521 NOTIFY:<event-id>:<custom-event-data>
522
523 where <event-id> uniquely identifies the event that has occurred and
524 <custom-event-data> is event specific.
525
526 Several rules must be followed by the server when generating events:
527
528 1. Events MUST NOT be sent to any client who has not issued an
529 appropriate SUBSCRIBE command.
530 2. Events MUST only be sent using the same connection that was used
531 to subscribe to them.
532 3. When response is being sent to the client, event MUST be inserted
533 in the stream before or after the response, but NOT in the
534 middle. Same is true about the response. It should never be
535 inserted in the middle of the event message as well as any other
536 response.
537
538 If the client is not interested in a particular event anymore it MAY
539 issue UNSUBSCRIBE command using the following syntax:
540
541 UNSUBSCRIBE <event-id>
542
543 where <event-id> will be replace by the respective event that client
544 is no longer interested in receiving. For a list of supported events
545 see Section 7.
546
547 Example: the fill states of disk stream buffers have changed on
548 sampler channel 4 and the LinuxSampler instance will react by sending
549 the following message to all clients who subscribed to this event:
550
551 NOTIFY:CHANNEL_BUFFER_FILL:4 [35]62%,[33]80%,[37]98%
552
553 Which means there are currently three active streams on sampler
554 channel 4, where the stream with ID "35" is filled by 62%, stream
555 with ID 33 is filled by 80% and stream with ID 37 is filled by 98%.
556
557
558
559 Schoenebeck Expires November 19, 2005 [Page 10]
560
561 Internet-Draft LinuxSampler Control Protocol May 2005
562
563
564 Clients may choose to open more than one connection to the server and
565 use some connections to receive notifications while using other
566 connections to issue commands to the back-end. This is entirely
567 legal and up to the implementation. This does not change the
568 protocol in any way and no special restrictions exist on the server
569 to allow or disallow this or to track what connections belong to what
570 front-ends. Server will listen on a single port, accept multiple
571 connections and support protocol described in this specification in
572 it's entirety on this single port on each connection that it
573 accepted.
574
575 Due to the fact that TCP is used for this communication, dead peers
576 will be detected automatically by the OS TCP stack. While it may
577 take a while to detect dead peers if no traffic is being sent from
578 server to client (TCP keep-alive timer is set to 2 hours on many
579 OSes) it will not be an issue here as when notifications are sent by
580 the server, dead client will be detected quickly.
581
582 When connection is closed for any reason server MUST forget all
583 subscriptions that were made on this connection. If client
584 reconnects it MUST resubscribe to all events that it wants to
585 receive.
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615 Schoenebeck Expires November 19, 2005 [Page 11]
616
617 Internet-Draft LinuxSampler Control Protocol May 2005
618
619
620 5. Description for control commands
621
622 This chapter will describe the available control commands that can be
623 sent on the TCP connection in detail. Some certain commands (e.g.
624 "GET CHANNEL INFO" (Section 5.4.10) or "GET ENGINE INFO" (Section
625 5.4.9)) lead to multiple-line responses. In this case LinuxSampler
626 signals the end of the response by a "." (single dot) line.
627
628 5.1 Ignored lines and comments
629
630 White lines, that is lines which only contain space and tabulator
631 characters, and lines that start with a "#" character are ignored,
632 thus it's possible for example to group commands and to place
633 comments in a LSCP script file.
634
635 5.2 Configuring audio drivers
636
637 Instances of drivers in LinuxSampler are called devices. You can use
638 multiple audio devices simultaneously, e.g. to output the sound of
639 one sampler channel using the ALSA audio output driver, and on
640 another sampler channel you might want to use the JACK audio output
641 driver. For particular audio output systems it's also possible to
642 create several devices of the same audio output driver, e.g. two
643 separate ALSA audio output devices for using two different sound
644 cards at the same time. This chapter describes all commands to
645 configure LinuxSampler's audio output devices and their parameters.
646
647 Instead of defining commands and parameters for each driver
648 individually, all possible parameters, their meanings and possible
649 values have to be obtained at runtime. This makes the protocol a bit
650 abstract, but has the advantage, that front-ends can be written
651 independently of what drivers are currently implemented and what
652 parameters these drivers are actually offering. This means
653 front-ends can even handle drivers which are implemented somewhere in
654 future without modifying the front-end at all.
655
656 Note: examples in this chapter showing particular parameters of
657 drivers are not meant as specification of the drivers' parameters.
658 Driver implementations in LinuxSampler might have complete different
659 parameter names and meanings than shown in these examples or might
660 change in future, so these examples are only meant for showing how to
661 retrieve what parameters drivers are offering, how to retrieve their
662 possible values, etc.
663
664 5.2.1 Getting amount of available audio output drivers
665
666 Use the following command to get the number of audio output drivers
667 currently available for the LinuxSampler instance:
668
669
670
671 Schoenebeck Expires November 19, 2005 [Page 12]
672
673 Internet-Draft LinuxSampler Control Protocol May 2005
674
675
676 GET AVAILABLE_AUDIO_OUTPUT_DRIVERS
677
678 Possible Answers:
679
680 LinuxSampler will answer by sending the number of audio output
681 drivers.
682
683 Example:
684
685 C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
686 S: "2"
687
688 5.2.2 Getting all available audio output drivers
689
690 Use the following command to list all audio output drivers currently
691 available for the LinuxSampler instance:
692
693 LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS
694
695 Possible Answers:
696
697 LinuxSampler will answer by sending comma separated character
698 strings, each symbolizing an audio output driver.
699
700 Example:
701
702 C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"
703 S: "ALSA,JACK"
704
705 5.2.3 Getting information about a specific audio output driver
706
707 Use the following command to get detailed information about a
708 specific audio output driver:
709
710 GET AUDIO_OUTPUT_DRIVER INFO <audio-output-driver>
711
712 Where <audio-output-driver> is the name of the audio output driver,
713 returned by the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 5.2.2)
714 command.
715
716 Possible Answers:
717
718 LinuxSampler will answer by sending a <CRLF> separated list. Each
719 answer line begins with the information category name followed by
720 a colon and then a space character <SP> and finally the info
721 character string to that info category. At the moment the
722 following information categories are defined:
723
724
725
726
727 Schoenebeck Expires November 19, 2005 [Page 13]
728
729 Internet-Draft LinuxSampler Control Protocol May 2005
730
731
732
733 DESCRIPTION -
734 character string describing the audio output driver
735 VERSION -
736 character string reflecting the driver's version
737 PARAMETERS -
738 comma separated list of all parameters available for the
739 given audio output driver, at least parameters 'channels',
740 'samplerate' and 'active' are offered by all audio output
741 drivers
742 The mentioned fields above don't have to be in particular order.
743
744 Example:
745
746 C: "GET AUDIO_OUTPUT_DRIVER INFO ALSA"
747 S: "DESCRIPTION: Advanced Linux Sound Architecture"
748 "VERSION: 1.0"
749 "PARAMETERS: DRIVER,CHANNELS,SAMPLERATE,ACTIVE,FRAGMENTS,
750 FRAGMENTSIZE,CARD"
751 "."
752
753 5.2.4 Getting information about specific audio output driver parameter
754
755 Use the following command to get detailed information about a
756 specific audio output driver parameter:
757
758 GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO <audio> <prm> [<deplist>]
759
760 Where <audio> is the name of the audio output driver as returned by
761 the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 5.2.2) command,
762 <prm> a specific parameter name for which information should be
763 obtained (as returned by the "GET AUDIO_OUTPUT_DRIVER INFO" (Section
764 5.2.3) command) and <deplist> is an optional list of parameters on
765 which the sought parameter <prm> depends on, <deplist> is a list of
766 key-value pairs in form of "key1=val1 key2=val2 ...", where character
767 string values are encapsulated into apostrophes ('). Arguments given
768 with <deplist> which are not dependency parameters of <prm> will be
769 ignored, means the front-end application can simply put all
770 parameters into <deplist> with the values already selected by the
771 user.
772
773 Possible Answers:
774
775 LinuxSampler will answer by sending a <CRLF> separated list. Each
776 answer line begins with the information category name followed by
777 a colon and then a space character <SP> and finally the info
778 character string to that info category. There are information
779 which is always returned, independently of the given driver
780
781
782
783 Schoenebeck Expires November 19, 2005 [Page 14]
784
785 Internet-Draft LinuxSampler Control Protocol May 2005
786
787
788 parameter and there are optional information which is only shown
789 dependently to given driver parameter. At the moment the
790 following information categories are defined:
791
792 TYPE -
793 either "BOOL" for boolean value(s) or "INT" for integer
794 value(s) or "FLOAT" for dotted number(s) or "STRING" for
795 character string(s) (always returned, no matter which driver
796 parameter)
797 DESCRIPTION -
798 arbitrary text describing the purpose of the parameter (always
799 returned, no matter which driver parameter)
800 MANDATORY -
801 either true or false, defines if this parameter must be given
802 when the device is to be created with the 'CREATE
803 AUDIO_OUTPUT_DEVICE' (Section 5.2.5) command (always returned,
804 no matter which driver parameter)
805 FIX -
806 either true or false, if false then this parameter can be
807 changed at any time, once the device is created by the 'CREATE
808 AUDIO_OUTPUT_DEVICE' (Section 5.2.5) command (always returned,
809 no matter which driver parameter)
810 MULTIPLICITY -
811 either true or false, defines if this parameter allows only one
812 value or a list of values, where true means multiple values and
813 false only a single value allowed (always returned, no matter
814 which driver parameter)
815 DEPENDS -
816 comma separated list of paramters this parameter depends on,
817 means the values for fields 'DEFAULT', 'RANGE_MIN', 'RANGE_MAX'
818 and 'POSSIBILITIES' might depend on these listed parameters,
819 for example assuming that an audio driver (like the ALSA
820 driver) offers parameters 'card' and 'samplerate' then
821 parameter 'samplerate' would depend on 'card' because the
822 possible values for 'samplerate' depends on the sound card
823 which can be chosen by the 'card' parameter (optionally
824 returned, dependent to driver parameter)
825 DEFAULT -
826 reflects the default value for this parameter which is used
827 when the device is created and not explicitly given with the
828 'CREATE AUDIO_OUTPUT_DEVICE' (Section 5.2.5) command, in case
829 of MULTIPLCITY=true, this is a comma separated list, that's why
830 character strings are encapsulated into apostrophes (')
831 (optionally returned, dependent to driver parameter)
832 RANGE_MIN -
833 defines lower limit of the allowed value range for this
834 parameter, can be an integer value as well as a dotted number,
835 this parameter is often used in conjunction with RANGE_MAX, but
836
837
838
839 Schoenebeck Expires November 19, 2005 [Page 15]
840
841 Internet-Draft LinuxSampler Control Protocol May 2005
842
843
844 may also appear without (optionally returned, dependent to
845 driver parameter)
846 RANGE_MAX -
847 defines upper limit of the allowed value range for this
848 parameter, can be an integer value as well as a dotted number,
849 this parameter is often used in conjunction with RANGE_MIN, but
850 may also appear without (optionally returned, dependent to
851 driver parameter)
852 POSSIBILITIES -
853 comma separated list of possible values for this parameter,
854 character strings are encapsulated into apostrophes (optionally
855 returned, dependent to driver parameter)
856
857 The mentioned fields above don't have to be in particular order.
858
859 Examples:
860
861 C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA CARD"
862 S: "DESCRIPTION: sound card to be used"
863 "TYPE: STRING"
864 "MANDATORY: false"
865 "FIX: true"
866 "MULTIPLICITY: false"
867 "DEFAULT: '0,0'"
868 "POSSIBILITIES: '0,0','1,0','2,0'"
869 "."
870
871 C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE"
872 S: "DESCRIPTION: output sample rate in Hz"
873 "TYPE: INT"
874 "MANDATORY: false"
875 "FIX: false"
876 "MULTIPLICITY: false"
877 "DEPENDS: card"
878 "DEFAULT: 44100"
879 "."
880
881 C: "GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA SAMPLERATE
882 CARD='0,0'"
883 S: "DESCRIPTION: output sample rate in Hz"
884 "TYPE: INT"
885 "MANDATORY: false"
886 "FIX: false"
887 "MULTIPLICITY: false"
888 "DEPENDS: card"
889 "DEFAULT: 44100"
890 "RANGE_MIN: 22050"
891
892
893
894
895 Schoenebeck Expires November 19, 2005 [Page 16]
896
897 Internet-Draft LinuxSampler Control Protocol May 2005
898
899
900 "RANGE_MAX: 96000"
901 "."
902
903 5.2.5 Creating an audio output device
904
905 Use the following command to create a new audio output device for
906 the desired audio output system:
907
908 CREATE AUDIO_OUTPUT_DEVICE <audio-output-driver> [<param-list>]
909
910 Where <audio-output-driver> should be replaced by the desired audio
911 output system and <param-list> by an optional list of driver specific
912 parameters in form of "key1=val1 key2=val2 ...", where character
913 string values should be encapsulated into apostrophes ('). Note that
914 there might be drivers which require parameter(s) to be given with
915 this command. Use the previously described commands in this chapter
916 to get this information.
917
918 Possible Answers:
919
920 "OK[<device-id>]" -
921 in case the device was successfully created, where <device-id>
922 is the numerical ID of the new device
923 "WRN[<device-id>]:<warning-code>:<warning-message>" -
924 in case the device was created successfully, where <device-id>
925 is the numerical ID of the new device, but there are noteworthy
926 issue(s) related (e.g. sound card doesn't support given
927 hardware parameters and the driver is using fall-back values),
928 providing an appropriate warning code and warning message
929 "ERR:<error-code>:<error-message>" -
930 in case it failed, providing an appropriate error code and
931 error message
932
933 Examples:
934
935 C: "CREATE AUDIO_OUTPUT_DEVICE ALSA"
936 S: "OK[0]"
937
938 C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"
939 S: "OK[1]"
940
941 5.2.6 Destroying an audio output device
942
943 Use the following command to destroy a created output device:
944
945 DESTROY AUDIO_OUTPUT_DEVICE <device-id>
946
947 Where <device-id> should be replaced by the numerical ID of the audio
948
949
950
951 Schoenebeck Expires November 19, 2005 [Page 17]
952
953 Internet-Draft LinuxSampler Control Protocol May 2005
954
955
956 output device as given by the "CREATE AUDIO_OUTPUT_DEVICE" (Section
957 5.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 5.2.8) command.
958
959 Possible Answers:
960
961 "OK" -
962 in case the device was successfully destroyed
963 "WRN:<warning-code>:<warning-message>" -
964 in case the device was destroyed successfully, but there are
965 noteworthy issue(s) related (e.g. an audio over ethernet
966 driver was unloaded but the other host might not be informed
967 about this situation), providing an appropriate warning code
968 and warning message
969 "ERR:<error-code>:<error-message>" -
970 in case it failed, providing an appropriate error code and
971 error message
972
973 Example:
974
975 C: "DESTROY AUDIO_OUTPUT_DEVICE 0"
976 S: "OK"
977
978 5.2.7 Getting all created audio output device count
979
980 Use the following command to count all created audio output devices:
981
982 GET AUDIO_OUTPUT_DEVICES
983
984 Possible Answers:
985
986 LinuxSampler will answer by sending the current number of all
987 audio output devices.
988
989 Example:
990
991 C: "GET AUDIO_OUTPUT_DEVICES"
992 S: "4"
993
994 5.2.8 Getting all created audio output device list
995
996 Use the following command to list all created audio output devices:
997
998 LIST AUDIO_OUTPUT_DEVICES
999
1000 Possible Answers:
1001
1002 LinuxSampler will answer by sending a comma separated list with
1003 the numerical IDs of all audio output devices.
1004
1005
1006
1007 Schoenebeck Expires November 19, 2005 [Page 18]
1008
1009 Internet-Draft LinuxSampler Control Protocol May 2005
1010
1011
1012 Example:
1013
1014 C: "LIST AUDIO_OUTPUT_DEVICES"
1015 S: "0,1,4,5"
1016
1017 5.2.9 Getting current settings of an audio output device
1018
1019 Use the following command to get current settings of a specific,
1020 created audio output device:
1021
1022 GET AUDIO_OUTPUT_DEVICE INFO <device-id>
1023
1024 Where <device-id> should be replaced by numerical ID of the audio
1025 output device as e.g. returned by the "LIST AUDIO_OUTPUT_DEVICES"
1026 (Section 5.2.8) command.
1027
1028 Possible Answers:
1029
1030 LinuxSampler will answer by sending a <CRLF> separated list. Each
1031 answer line begins with the information category name followed by a
1032 colon and then a space character <SP> and finally the info character
1033 string to that info category. As some parameters might allow
1034 multiple values, character strings are encapsulated into apostrophes
1035 ('). At the moment the following information categories are defined
1036 (independently of device):
1037
1038 DRIVER -
1039 identifier of the used audio output driver, as also returned by
1040 the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 5.2.2)
1041 command
1042 CHANNELS -
1043 amount of audio output channels this device currently offers
1044 SAMPLERATE -
1045 playback sample rate the device uses
1046 ACTIVE -
1047 either true or false, if false then the audio device is
1048 inactive and doesn't output any sound, nor do the sampler
1049 channels connected to this audio device render any audio
1050
1051 The mentioned fields above don't have to be in particular order. The
1052 fields above are only those fields which are returned by all audio
1053 output devices. Every audio output driver might have its own,
1054 additional driver specific parameters (see Section 5.2.3) which are
1055 also returned by this command.
1056
1057 Example:
1058
1059
1060
1061
1062
1063 Schoenebeck Expires November 19, 2005 [Page 19]
1064
1065 Internet-Draft LinuxSampler Control Protocol May 2005
1066
1067
1068 C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
1069 S: "DRIVER: ALSA"
1070 "CHANNELS: 2"
1071 "SAMPLERATE: 44100"
1072 "ACTIVE: true"
1073 "FRAGMENTS: 2"
1074 "FRAGMENTSIZE: 128"
1075 "CARD: '0,0'"
1076 "."
1077
1078 5.2.10 Changing settings of audio output devices
1079
1080 Use the following command to alter a specific setting of a created
1081 audio output device:
1082
1083 SET AUDIO_OUTPUT_DEVICE_PARAMETER <device-id> <key>=<value>
1084
1085 Where <device-id> should be replaced by the numerical ID of the audio
1086 output device, <key> by the name of the parameter to change and
1087 <value> by the new value for this parameter.
1088
1089 Possible Answers:
1090
1091 "OK" -
1092 in case setting was successfully changed
1093 "WRN:<warning-code>:<warning-message>" -
1094 in case setting was changed successfully, but there are
1095 noteworthy issue(s) related, providing an appropriate warning
1096 code and warning message
1097 "ERR:<error-code>:<error-message>" -
1098 in case it failed, providing an appropriate error code and
1099 error message
1100
1101 Example:
1102
1103 C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"
1104 S: "OK"
1105
1106 5.2.11 Getting information about an audio channel
1107
1108 Use the following command to get information about an audio channel:
1109
1110 GET AUDIO_OUTPUT_CHANNEL INFO <device-id> <audio-chan>
1111
1112 Where <device-id> is the numerical ID of the audio output device and
1113 <audio-chan> the audio channel number.
1114
1115 Possible Answers:
1116
1117
1118
1119 Schoenebeck Expires November 19, 2005 [Page 20]
1120
1121 Internet-Draft LinuxSampler Control Protocol May 2005
1122
1123
1124 LinuxSampler will answer by sending a <CRLF> separated list. Each
1125 answer line begins with the information category name followed by
1126 a colon and then a space character <SP> and finally the info
1127 character string to that info category. At the moment the
1128 following information categories are defined:
1129
1130 NAME -
1131 arbitrary character string naming the channel, which doesn't
1132 have to be unique (always returned by all audio channels)
1133 IS_MIX_CHANNEL -
1134 either true or false, a mix-channel is not a real,
1135 independent audio channel, but a virtual channel which is
1136 mixed to another real channel, this mechanism is needed for
1137 sampler engines which need more audio channels than the used
1138 audio system might be able to offer (always returned by all
1139 audio channels)
1140 MIX_CHANNEL_DESTINATION -
1141 numerical ID (positive integer including 0) which reflects
1142 the real audio channel (of the same audio output device)
1143 this mix channel refers to, means where the audio signal
1144 actually will be routed / added to (only returned in case
1145 the audio channel is mix channel)
1146
1147 The mentioned fields above don't have to be in particular order. The
1148 fields above are only those fields which are generally returned for
1149 the described cases by all audio channels regardless of the audio
1150 driver. Every audio channel might have its own, additional driver
1151 and channel specific parameters.
1152
1153 Examples:
1154
1155 C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 0"
1156 S: "NAME: studio monitor left"
1157 "IS_MIX_CHANNEL: false"
1158 "."
1159
1160 C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 1"
1161 S: "NAME: studio monitor right"
1162 "IS_MIX_CHANNEL: false"
1163 "."
1164
1165 C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"
1166 S: "NAME: studio monitor left"
1167 "IS_MIX_CHANNEL: true"
1168 "MIX_CHANNEL_DESTINATION: 1"
1169 "."
1170
1171
1172
1173
1174
1175 Schoenebeck Expires November 19, 2005 [Page 21]
1176
1177 Internet-Draft LinuxSampler Control Protocol May 2005
1178
1179
1180 C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"
1181 S: "NAME: 'ardour (left)'"
1182 "IS_MIX_CHANNEL: false"
1183 "JACK_BINDINGS: 'ardour:0'"
1184 "."
1185
1186 5.2.12 Getting information about specific audio channel parameter
1187
1188 Use the following command to get detailed information about specific
1189 audio channel parameter:
1190
1191 GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO <dev-id> <chan> <param>
1192
1193 Where <dev-id> is the numerical ID of the audio output device as
1194 returned by the "LIST AUDIO_OUTPUT_DEVICES" (Section 5.2.8) command,
1195 <chan> the audio channel number and <param> a specific channel
1196 parameter name for which information should be obtained (as returned
1197 by the "GET AUDIO_OUTPUT_CHANNEL INFO" (Section 5.2.11) command).
1198
1199 Possible Answers:
1200
1201 LinuxSampler will answer by sending a <CRLF> separated list. Each
1202 answer line begins with the information category name followed by
1203 a colon and then a space character <SP> and finally the info
1204 character string to that info category. There are information
1205 which is always returned, independently of the given channel
1206 parameter and there is optional information which is only shown
1207 dependently to the given audio channel. At the moment the
1208 following information categories are defined:
1209
1210 TYPE -
1211 either "BOOL" for boolean value(s) or "INT" for integer
1212 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1213 character string(s) (always returned)
1214 DESCRIPTION -
1215 arbitrary text describing the purpose of the parameter
1216 (always returned)
1217 FIX -
1218 either true or false, if true then this parameter is read
1219 only, thus cannot be altered (always returned)
1220 MULTIPLICITY -
1221 either true or false, defines if this parameter allows only
1222 one value or a list of values, where true means multiple
1223 values and false only a single value allowed (always
1224 returned)
1225 RANGE_MIN -
1226 defines lower limit of the allowed value range for this
1227 parameter, can be an integer value as well as a dotted
1228
1229
1230
1231 Schoenebeck Expires November 19, 2005 [Page 22]
1232
1233 Internet-Draft LinuxSampler Control Protocol May 2005
1234
1235
1236 number, usually used in conjunction with 'RANGE_MAX', but
1237 may also appear without (optionally returned, dependent to
1238 driver and channel parameter)
1239 RANGE_MAX -
1240 defines upper limit of the allowed value range for this
1241 parameter, can be an integer value as well as a dotted
1242 number, usually used in conjunction with 'RANGE_MIN', but
1243 may also appear without (optionally returned, dependent to
1244 driver and channel parameter)
1245 POSSIBILITIES -
1246 comma separated list of possible values for this parameter,
1247 character strings are encapsulated into apostrophes
1248 (optionally returned, dependent to driver and channel
1249 parameter)
1250 The mentioned fields above don't have to be in particular order.
1251
1252 Example:
1253
1254 C: "GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO 1 0 JACK_BINDINGS"
1255 S: "DESCRIPTION: bindings to other JACK clients"
1256 "TYPE: STRING"
1257 "FIX: false"
1258 "MULTIPLICITY: true"
1259 "POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"
1260 "."
1261
1262 5.2.13 Changing settings of audio output channels
1263
1264 Use the following command to alter a specific setting of an audio
1265 output channel:
1266
1267 SET AUDIO_OUTPUT_CHANNEL_PARAMETER <dev-id> <chn> <key>=<value>
1268
1269 Where <dev-id> should be replaced by the numerical ID of the audio
1270 device, <chn> by the audio channel number, <key> by the name of the
1271 parameter to change and <value> by the new value for this parameter.
1272
1273 Possible Answers:
1274
1275 "OK" -
1276 in case setting was successfully changed
1277 "WRN:<warning-code>:<warning-message>" -
1278 in case setting was changed successfully, but there are
1279 noteworthy issue(s) related, providing an appropriate warning
1280 code and warning message
1281 "ERR:<error-code>:<error-message>" -
1282 in case it failed, providing an appropriate error code and
1283 error message
1284
1285
1286
1287 Schoenebeck Expires November 19, 2005 [Page 23]
1288
1289 Internet-Draft LinuxSampler Control Protocol May 2005
1290
1291
1292 Example:
1293
1294 C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"
1295 S: "OK"
1296
1297 C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"
1298 S: "OK"
1299
1300 5.3 Configuring MIDI input drivers
1301
1302 Instances of drivers in LinuxSampler are called devices. You can use
1303 multiple MIDI devices simultaneously, e.g. to use MIDI over ethernet
1304 as MIDI input on one sampler channel and ALSA as MIDI input on
1305 another sampler channel. For particular MIDI input systems it's also
1306 possible to create several devices of the same MIDI input type. This
1307 chapter describes all commands to configure LinuxSampler's MIDI input
1308 devices and their parameters.
1309
1310 Instead of defining commands and parameters for each driver
1311 individually, all possible parameters, their meanings and possible
1312 values have to be obtained at runtime. This makes the protocol a bit
1313 abstract, but has the advantage, that front-ends can be written
1314 independently of what drivers are currently implemented and what
1315 parameters these drivers are actually offering. This means
1316 front-ends can even handle drivers which are implemented somewhere in
1317 future without modifying the front-end at all.
1318
1319 Commands for configuring MIDI input devices are pretty much the same
1320 as the commands for configuring audio output drivers, already
1321 described in the last chapter.
1322
1323 Note: examples in this chapter showing particular parameters of
1324 drivers are not meant as specification of the drivers' parameters.
1325 Driver implementations in LinuxSampler might have complete different
1326 parameter names and meanings than shown in these examples or might
1327 change in future, so these examples are only meant for showing how to
1328 retrieve what parameters drivers are offering, how to retrieve their
1329 possible values, etc.
1330
1331 5.3.1 Getting amount of available MIDI input drivers
1332
1333 Use the following command to get the number of MIDI input drivers
1334 currently available for the LinuxSampler instance:
1335
1336 GET AVAILABLE_MIDI_INPUT_DRIVERS
1337
1338 Possible Answers:
1339
1340
1341
1342
1343 Schoenebeck Expires November 19, 2005 [Page 24]
1344
1345 Internet-Draft LinuxSampler Control Protocol May 2005
1346
1347
1348 LinuxSampler will answer by sending the number of available MIDI
1349 input drivers.
1350
1351 Example:
1352
1353 C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"
1354 S: "2"
1355
1356 5.3.2 Getting all available MIDI input drivers
1357
1358 Use the following command to list all MIDI input drivers currently
1359 available for the LinuxSampler instance:
1360
1361 LIST AVAILABLE_MIDI_INPUT_DRIVERS
1362
1363 Possible Answers:
1364
1365 LinuxSampler will answer by sending comma separated character
1366 strings, each symbolizing a MIDI input driver.
1367
1368 Example:
1369
1370 C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
1371 S: "ALSA,JACK"
1372
1373 5.3.3 Getting information about a specific MIDI input driver
1374
1375 Use the following command to get detailed information about a
1376 specific MIDI input driver:
1377
1378 GET MIDI_INPUT_DRIVER INFO <midi-input-driver>
1379
1380 Where <midi-input-driver> is the name of the MIDI input driver.
1381
1382 Possible Answers:
1383
1384 LinuxSampler will answer by sending a <CRLF> separated list. Each
1385 answer line begins with the information category name followed by
1386 a colon and then a space character <SP> and finally the info
1387 character string to that info category. At the moment the
1388 following information categories are defined:
1389
1390 DESCRIPTION -
1391 arbitrary description text about the MIDI input driver
1392 VERSION -
1393 arbitrary character string regarding the driver's version
1394 PARAMETERS -
1395
1396
1397
1398
1399 Schoenebeck Expires November 19, 2005 [Page 25]
1400
1401 Internet-Draft LinuxSampler Control Protocol May 2005
1402
1403
1404 comma separated list of all parameters available for the
1405 given MIDI input driver
1406 The mentioned fields above don't have to be in particular order.
1407
1408 Example:
1409
1410 C: "GET MIDI_INPUT_DRIVER INFO ALSA"
1411 S: "DESCRIPTION: Advanced Linux Sound Architecture"
1412 "VERSION: 1.0"
1413 "PARAMETERS: DRIVER,ACTIVE"
1414 "."
1415
1416 5.3.4 Getting information about specific MIDI input driver parameter
1417
1418 Use the following command to get detailed information about a
1419 specific parameter of a specific MIDI input driver:
1420
1421 GET MIDI_INPUT_DRIVER_PARAMETER INFO <midit> <param> [<deplist>]
1422
1423 Where <midi-t> is the name of the MIDI input driver as returned by
1424 the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 5.3.2) command,
1425 <param> a specific parameter name for which information should be
1426 obtained (as returned by the "GET MIDI_INPUT_DRIVER INFO" (Section
1427 5.3.3) command) and <deplist> is an optional list of parameters on
1428 which the sought parameter <param> depends on, <deplist> is a
1429 key-value pair list in form of "key1=val1 key2=val2 ...", where
1430 character string values are encapsulated into apostrophes (').
1431 Arguments given with <deplist> which are not dependency parameters of
1432 <param> will be ignored, means the front-end application can simply
1433 put all parameters in <deplist> with the values selected by the user.
1434
1435 Possible Answers:
1436
1437 LinuxSampler will answer by sending a <CRLF> separated list. Each
1438 answer line begins with the information category name followed by a
1439 colon and then a space character <SP> and finally the info character
1440 string to that info category. There is information which is always
1441 returned, independent of the given driver parameter and there is
1442 optional information which is only shown dependent to given driver
1443 parameter. At the moment the following information categories are
1444 defined:
1445
1446 TYPE -
1447 either "BOOL" for boolean value(s) or "INT" for integer
1448 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1449 character string(s) (always returned, no matter which driver
1450 parameter)
1451
1452
1453
1454
1455 Schoenebeck Expires November 19, 2005 [Page 26]
1456
1457 Internet-Draft LinuxSampler Control Protocol May 2005
1458
1459
1460 DESCRIPTION -
1461 arbitrary text describing the purpose of the parameter (always
1462 returned, no matter which driver parameter)
1463 MANDATORY -
1464 either true or false, defines if this parameter must be given
1465 when the device is to be created with the 'CREATE
1466 MIDI_INPUT_DEVICE' (Section 5.3.5) command (always returned, no
1467 matter which driver parameter)
1468 FIX -
1469 either true or false, if false then this parameter can be
1470 changed at any time, once the device is created by the 'CREATE
1471 MIDI_INPUT_DEVICE' (Section 5.3.5) command (always returned, no
1472 matter which driver parameter)
1473 MULTIPLICITY -
1474 either true or false, defines if this parameter allows only one
1475 value or a list of values, where true means multiple values and
1476 false only a single value allowed (always returned, no matter
1477 which driver parameter)
1478 DEPENDS -
1479 comma separated list of paramters this parameter depends on,
1480 means the values for fields 'DEFAULT', 'RANGE_MIN', 'RANGE_MAX'
1481 and 'POSSIBILITIES' might depend on these listed parameters,
1482 for example assuming that an audio driver (like the ALSA
1483 driver) offers parameters 'card' and 'samplerate' then
1484 parameter 'samplerate' would depend on 'card' because the
1485 possible values for 'samplerate' depends on the sound card
1486 which can be chosen by the 'card' parameter (optionally
1487 returned, dependent to driver parameter)
1488 DEFAULT -
1489 reflects the default value for this parameter which is used
1490 when the device is created and not explicitly given with the
1491 'CREATE MIDI_INPUT_DEVICE' (Section 5.3.5) command, in case of
1492 MULTIPLCITY=true, this is a comma separated list, that's why
1493 character strings are encapsulated into apostrophes (')
1494 (optionally returned, dependent to driver parameter)
1495 RANGE_MIN -
1496 defines lower limit of the allowed value range for this
1497 parameter, can be an integer value as well as a dotted number,
1498 this parameter is often used in conjunction with RANGE_MAX, but
1499 may also appear without (optionally returned, dependent to
1500 driver parameter)
1501 RANGE_MAX -
1502 defines upper limit of the allowed value range for this
1503 parameter, can be an integer value as well as a dotted number,
1504 this parameter is often used in conjunction with RANGE_MIN, but
1505 may also appear without (optionally returned, dependent to
1506 driver parameter)
1507
1508
1509
1510
1511 Schoenebeck Expires November 19, 2005 [Page 27]
1512
1513 Internet-Draft LinuxSampler Control Protocol May 2005
1514
1515
1516 POSSIBILITIES -
1517 comma separated list of possible values for this parameter,
1518 character strings are encapsulated into apostrophes (optionally
1519 returned, dependent to driver parameter)
1520
1521 The mentioned fields above don't have to be in particular order.
1522
1523 Example:
1524
1525 C: "GET MIDI_INPUT_DRIVER_PARAMETER INFO ALSA ACTIVE"
1526 S: "DESCRIPTION: Whether device is enabled"
1527 "TYPE: BOOL"
1528 "MANDATORY: false"
1529 "FIX: false"
1530 "MULTIPLICITY: false"
1531 "DEFAULT: true"
1532 "."
1533
1534 5.3.5 Creating a MIDI input device
1535
1536 Use the following command to create a new MIDI input device for the
1537 desired MIDI input system:
1538
1539 CREATE MIDI_INPUT_DEVICE <midi-input-driver> [<param-list>]
1540
1541 Where <midi-input-driver> should be replaced by the desired MIDI
1542 input system and <param-list> by an optional list of driver specific
1543 parameters in form of "key1=val1 key2=val2 ...", where character
1544 string values should be encapsulated into apostrophes ('). Note that
1545 there might be drivers which require parameter(s) to be given with
1546 this command. Use the previously described commands in this chapter
1547 to get that information.
1548
1549 Possible Answers:
1550
1551 "OK[<device-id>]" -
1552 in case the device was successfully created, where <device-id>
1553 is the numerical ID of the new device
1554 "WRN[<device-id>]:<warning-code>:<warning-message>" -
1555 in case the driver was loaded successfully, where <device-id>
1556 is the numerical ID of the new device, but there are noteworthy
1557 issue(s) related, providing an appropriate warning code and
1558 warning message
1559 "ERR:<error-code>:<error-message>" -
1560 in case it failed, providing an appropriate error code and
1561 error message
1562
1563 Example:
1564
1565
1566
1567 Schoenebeck Expires November 19, 2005 [Page 28]
1568
1569 Internet-Draft LinuxSampler Control Protocol May 2005
1570
1571
1572 C: "CREATE MIDI_INPUT_DEVICE ALSA"
1573 S: "OK[0]"
1574
1575 5.3.6 Destroying a MIDI input device
1576
1577 Use the following command to destroy a created MIDI input device:
1578
1579 DESTROY MIDI_INPUT_DEVICE <device-id>
1580
1581 Where <device-id> should be replaced by the device's numerical ID.
1582
1583 Possible Answers:
1584
1585 "OK" -
1586 in case the device was successfully destroyed
1587 "WRN:<warning-code>:<warning-message>" -
1588 in case the device was destroyed, but there are noteworthy
1589 issue(s) related, providing an appropriate warning code and
1590 warning message
1591 "ERR:<error-code>:<error-message>" -
1592 in case it failed, providing an appropriate error code and
1593 error message
1594
1595 Example:
1596
1597 C: "DESTROY MIDI_INPUT_DEVICE 0"
1598 S: "OK"
1599
1600 5.3.7 Getting all created MIDI input device count
1601
1602 Use the following command to count all created MIDI input devices:
1603
1604 GET MIDI_INPUT_DEVICES
1605
1606 Possible Answers:
1607
1608 LinuxSampler will answer by sending the current number of all MIDI
1609 input devices.
1610
1611 Example:
1612
1613 C: "GET MIDI_INPUT_DEVICES"
1614 S: "3"
1615
1616 5.3.8 Getting all created MIDI input device list
1617
1618 Use the following command to list all created MIDI input devices:
1619
1620
1621
1622
1623 Schoenebeck Expires November 19, 2005 [Page 29]
1624
1625 Internet-Draft LinuxSampler Control Protocol May 2005
1626
1627
1628 LIST MIDI_INPUT_DEVICES
1629
1630 Possible Answers:
1631
1632 LinuxSampler will answer by sending a comma separated list with
1633 the numerical Ids of all created MIDI input devices.
1634
1635 Examples:
1636
1637 C: "LIST MIDI_INPUT_DEVICES"
1638 S: "0,1,2"
1639
1640 C: "LIST MIDI_INPUT_DEVICES"
1641 S: "1,3"
1642
1643 5.3.9 Getting current settings of a MIDI input device
1644
1645 Use the following command to get current settings of a specific,
1646 created MIDI input device:
1647
1648 GET MIDI_INPUT_DEVICE INFO <device-id>
1649
1650 Where <device-id> is the numerical ID of the MIDI input device.
1651
1652 Possible Answers:
1653
1654 LinuxSampler will answer by sending a <CRLF> separated list. Each
1655 answer line begins with the information category name followed by
1656 a colon and then a space character <SP> and finally the info
1657 character string to that info category. As some parameters might
1658 allow multiple values, character strings are encapsulated into
1659 apostrophes ('). At the moment the following information
1660 categories are defined (independent of driver):
1661
1662 DRIVER -
1663 identifier of the used MIDI input driver, as e.g. returned
1664 by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 5.3.2)
1665 command
1666 ACTIVE -
1667 either true or false, if false then the MIDI device is
1668 inactive and doesn't listen to any incoming MIDI events and
1669 thus doesn't forward them to connected sampler channels
1670
1671 The mentioned fields above don't have to be in particular order. The
1672 fields above are only those fields which are returned by all MIDI
1673 input devices. Every MIDI input driver might have its own,
1674 additional driver specific parameters (see "GET MIDI_INPUT_DRIVER
1675 INFO" (Section 5.3.3) command) which are also returned by this
1676
1677
1678
1679 Schoenebeck Expires November 19, 2005 [Page 30]
1680
1681 Internet-Draft LinuxSampler Control Protocol May 2005
1682
1683
1684 command.
1685
1686 Example:
1687
1688 C: "GET MIDI_INPUT_DEVICE INFO 0"
1689 S: "DRIVER: ALSA"
1690 "ACTIVE: true"
1691 "."
1692
1693 5.3.10 Changing settings of MIDI input devices
1694
1695 Use the following command to alter a specific setting of a created
1696 MIDI input device:
1697
1698 SET MIDI_INPUT_DEVICE_PARAMETER <device-id> <key>=<value>
1699
1700 Where <device-id> should be replaced by the numerical ID of the MIDI
1701 input device, <key> by the name of the parameter to change and
1702 <value> by the new value for this parameter.
1703
1704 Possible Answers:
1705
1706 "OK" -
1707 in case setting was successfully changed
1708 "WRN:<warning-code>:<warning-message>" -
1709 in case setting was changed successfully, but there are
1710 noteworthy issue(s) related, providing an appropriate warning
1711 code and warning message
1712 "ERR:<error-code>:<error-message>" -
1713 in case it failed, providing an appropriate error code and
1714 error message
1715
1716 Example:
1717
1718 C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"
1719 S: "OK"
1720
1721 5.3.11 Getting information about a MIDI port
1722
1723 Use the following command to get information about a MIDI port:
1724
1725 GET MIDI_INPUT_PORT INFO <device-id> <midi-port>
1726
1727 Where <device-id> is the numerical ID of the MIDI input device and
1728 <midi-port> the MIDI input port number.
1729
1730 Possible Answers:
1731
1732
1733
1734
1735 Schoenebeck Expires November 19, 2005 [Page 31]
1736
1737 Internet-Draft LinuxSampler Control Protocol May 2005
1738
1739
1740 LinuxSampler will answer by sending a <CRLF> separated list. Each
1741 answer line begins with the information category name followed by
1742 a colon and then a space character <SP> and finally the info
1743 character string to that info category. At the moment the
1744 following information categories are defined:
1745 NAME -
1746 arbitrary character string naming the port
1747
1748 The field above is only the one which is returned by all MIDI ports
1749 regardless of the MIDI driver and port. Every MIDI port might have
1750 its own, additional driver and port specific parameters.
1751
1752 Example:
1753
1754 C: "GET MIDI_INPUT_PORT INFO 0 0"
1755 S: "NAME: 'Masterkeyboard'"
1756 "ALSA_SEQ_BINDINGS: '64:0'"
1757 "."
1758
1759 5.3.12 Getting information about specific MIDI port parameter
1760
1761 Use the following command to get detailed information about specific
1762 MIDI port parameter:
1763
1764 GET MIDI_INPUT_PORT_PARAMETER INFO <dev-id> <port> <param>
1765
1766 Where <dev-id> is the numerical ID of the MIDI input device as
1767 returned by the "LIST MIDI_INPUT_DEVICES" (Section 5.3.8) command,
1768 <port> the MIDI port number and <param> a specific port parameter
1769 name for which information should be obtained (as returned by the
1770 "GET MIDI_INPUT_PORT INFO" (Section 5.3.11) command).
1771
1772 Possible Answers:
1773
1774 LinuxSampler will answer by sending a <CRLF> separated list. Each
1775 answer line begins with the information category name followed by
1776 a colon and then a space character <SP> and finally the info
1777 character string to that info category. There is information
1778 which is always returned, independently of the given channel
1779 parameter and there is optional information which are only shown
1780 dependently to the given MIDI port. At the moment the following
1781 information categories are defined:
1782 TYPE -
1783 either "BOOL" for boolean value(s) or "INT" for integer
1784 value(s) or "FLOAT" for dotted number(s) or "STRING" for
1785 character string(s) (always returned)
1786 DESCRIPTION -
1787
1788
1789
1790
1791 Schoenebeck Expires November 19, 2005 [Page 32]
1792
1793 Internet-Draft LinuxSampler Control Protocol May 2005
1794
1795
1796 arbitrary text describing the purpose of the parameter (always
1797 returned)
1798 FIX -
1799 either true or false, if true then this parameter is read only,
1800 thus cannot be altered (always returned)
1801 MULTIPLICITY -
1802 either true or false, defines if this parameter allows only one
1803 value or a list of values, where true means multiple values and
1804 false only a single value allowed (always returned)
1805 RANGE_MIN -
1806 defines lower limit of the allowed value range for this
1807 parameter, can be an integer value as well as a dotted number,
1808 this parameter is usually used in conjunction with 'RANGE_MAX'
1809 but may also appear without (optionally returned, dependent to
1810 driver and port parameter)
1811 RANGE_MAX -
1812 defines upper limit of the allowed value range for this
1813 parameter, can be an integer value as well as a dotted number,
1814 this parameter is usually used in conjunction with 'RANGE_MIN'
1815 but may also appear without (optionally returned, dependent to
1816 driver and port parameter)
1817 POSSIBILITIES -
1818 comma separated list of possible values for this parameter,
1819 character strings are encapsulated into apostrophes (optionally
1820 returned, dependent to device and port parameter)
1821
1822 The mentioned fields above don't have to be in particular order.
1823
1824 Example:
1825
1826 C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"
1827 S: "DESCRIPTION: bindings to other ALSA sequencer clients"
1828 "TYPE: STRING"
1829 "FIX: false"
1830 "MULTIPLICITY: true"
1831 "POSSIBILITIES: '64:0','68:0','68:1'"
1832 "."
1833
1834 5.3.13 Changing settings of MIDI input ports
1835
1836 Use the following command to alter a specific setting of a MIDI input
1837 port:
1838
1839 SET MIDI_INPUT_PORT_PARAMETER <device-id> <port> <key>=<value>
1840
1841 Where <device-id> should be replaced by the numerical ID of the MIDI
1842 device, <port> by the MIDI port number, <key> by the name of the
1843 parameter to change and <value> by the new value for this parameter.
1844
1845
1846
1847 Schoenebeck Expires November 19, 2005 [Page 33]
1848
1849 Internet-Draft LinuxSampler Control Protocol May 2005
1850
1851
1852 Possible Answers:
1853
1854 "OK" -
1855 in case setting was successfully changed
1856 "WRN:<warning-code>:<warning-message>" -
1857 in case setting was changed successfully, but there are
1858 noteworthy issue(s) related, providing an appropriate warning
1859 code and warning message
1860 "ERR:<error-code>:<error-message>" -
1861 in case it failed, providing an appropriate error code and
1862 error message
1863
1864 Example:
1865
1866
1867
1868 5.4 Configuring sampler channels
1869
1870 The following commands describe how to add and remove sampler
1871 channels, deploy sampler engines, load instruments and connect
1872 sampler channels to MIDI and audio devices.
1873
1874 5.4.1 Loading an instrument
1875
1876 An instrument file can be loaded and assigned to a sampler channel by
1877 one of the following commands:
1878
1879 LOAD INSTRUMENT [NON_MODAL] '<filename>' <instr-index>
1880 <sampler-channel>
1881
1882 Where <filename> is the name of the instrument file on the
1883 LinuxSampler instance's host system, <instr-index> the index of the
1884 instrument in the instrument file and <sampler-channel> is the number
1885 of the sampler channel the instrument should be assigned to. Each
1886 sampler channel can only have one instrument.
1887
1888 The difference between regular and NON_MODAL versions of the command
1889 is that the regular command returns OK only after the instrument has
1890 been fully loaded and the channel is ready to be used while NON_MODAL
1891 version returns immediately and a background process is launched to
1892 load the instrument on the channel. The GET CHANNEL INFO (Section
1893 5.4.10) command can be used to obtain loading progress from
1894 INSTRUMENT_STATUS field. LOAD command will perform sanity checks
1895 such as making sure that the file could be read and it is of a proper
1896 format and SHOULD return ERR and SHOULD not launch the background
1897 process should any errors be detected at that point.
1898
1899 Possible Answers:
1900
1901
1902
1903 Schoenebeck Expires November 19, 2005 [Page 34]
1904
1905 Internet-Draft LinuxSampler Control Protocol May 2005
1906
1907
1908 "OK" -
1909 in case the instrument was successfully loaded
1910 "WRN:<warning-code>:<warning-message>" -
1911 in case the instrument was loaded successfully, but there are
1912 noteworthy issue(s) related (e.g. Engine doesn't support one
1913 or more patch parameters provided by the loaded instrument
1914 file), providing an appropriate warning code and warning
1915 message
1916 "ERR:<error-code>:<error-message>" -
1917 in case it failed, providing an appropriate error code and
1918 error message
1919
1920 Example:
1921
1922
1923
1924 5.4.2 Loading a sampler engine
1925
1926 A sample engine can be deployed and assigned to a specific sampler
1927 channel by the following command:
1928
1929 LOAD ENGINE <engine-name> <sampler-channel>
1930
1931 Where <engine-name> is an engine name as obtained by the "LIST
1932 AVAILABLE_ENGINES" (Section 5.4.8) command and <sampler-channel> the
1933 sampler channel the deployed engine should be assigned to. Even if
1934 the respective sampler channel has already a deployed engine with
1935 that engine name, a new engine instance will be assigned to the
1936 sampler channel.
1937
1938 Possible Answers:
1939
1940 "OK" -
1941 in case the engine was successfully deployed
1942 "WRN:<warning-code>:<warning-message>" -
1943 in case the engine was deployed successfully, but there are
1944 noteworthy issue(s) related, providing an appropriate warning
1945 code and warning message
1946 "ERR:<error-code>:<error-message>" -
1947 in case it failed, providing an appropriate error code and
1948 error message
1949
1950 Example:
1951
1952
1953
1954
1955
1956
1957
1958
1959 Schoenebeck Expires November 19, 2005 [Page 35]
1960
1961 Internet-Draft LinuxSampler Control Protocol May 2005
1962
1963
1964 5.4.3 Getting all created sampler channel count
1965
1966 The number of sampler channels can change on runtime. To get the
1967 current amount of sampler channels, the front-end can send the
1968 following command:
1969
1970 GET CHANNELS
1971
1972 Possible Answers:
1973
1974 LinuxSampler will answer by returning the current number of
1975 sampler channels.
1976
1977 Example:
1978
1979 C: "GET CHANNELS"
1980 S: "12"
1981
1982 5.4.4 Getting all created sampler channel list
1983
1984 The number of sampler channels can change on runtime. To get the
1985 current list of sampler channels, the front-end can send the
1986 following command:
1987
1988 LIST CHANNELS
1989
1990 Possible Answers:
1991
1992 LinuxSampler will answer by returning a comma separated list with
1993 all sampler channels numerical IDs.
1994
1995 Example:
1996
1997 C: "LIST CHANNELS"
1998 S: "0,1,2,3,4,5,6,9,10,11,15,20"
1999
2000 5.4.5 Adding a new sampler channel
2001
2002 A new sampler channel can be added to the end of the sampler channel
2003 list by sending the following command:
2004
2005 ADD CHANNEL
2006
2007 This will increment the sampler channel count by one and the new
2008 sampler channel will be appended to the end of the sampler channel
2009 list. The front-end should send the respective, related commands
2010 right after to e.g. load an engine, load an instrument and setting
2011 input, output method and eventually other commands to initialize the
2012
2013
2014
2015 Schoenebeck Expires November 19, 2005 [Page 36]
2016
2017 Internet-Draft LinuxSampler Control Protocol May 2005
2018
2019
2020 new channel. The front-end should use the sampler channel returned
2021 by the answer of this command to perform the previously recommended
2022 commands, to avoid race conditions e.g. with other front-ends that
2023 might also have sent an "ADD CHANNEL" command.
2024
2025 Possible Answers:
2026
2027 "OK[<sampler-channel>]" -
2028 in case a new sampler channel could be added, where
2029 <sampler-channel> reflects the channel number of the new
2030 created sampler channel which should the be used to set up the
2031 sampler channel by sending subsequent intialization commands
2032 "WRN:<warning-code>:<warning-message>" -
2033 in case a new channel was added successfully, but there are
2034 noteworthy issue(s) related, providing an appropriate warning
2035 code and warning message
2036 "ERR:<error-code>:<error-message>" -
2037 in case it failed, providing an appropriate error code and
2038 error message
2039
2040 Example:
2041
2042
2043
2044 5.4.6 Removing a sampler channel
2045
2046 A sampler channel can be removed by sending the following command:
2047
2048 REMOVE CHANNEL <sampler-channel>
2049
2050 This will decrement the sampler channel count by one and also
2051 decrement the channel numbers of all subsequent sampler channels by
2052 one.
2053
2054 Possible Answers:
2055
2056 "OK" -
2057 in case the given sampler channel could be removed
2058 "WRN:<warning-code>:<warning-message>" -
2059 in case the given channel was removed, but there are noteworthy
2060 issue(s) related, providing an appropriate warning code and
2061 warning message
2062 "ERR:<error-code>:<error-message>" -
2063 in case it failed, providing an appropriate error code and
2064 error message
2065
2066 Example:
2067
2068
2069
2070
2071 Schoenebeck Expires November 19, 2005 [Page 37]
2072
2073 Internet-Draft LinuxSampler Control Protocol May 2005
2074
2075
2076
2077
2078 5.4.7 Getting amount of available engines
2079
2080 The front-end can ask for the number of available engines by sending
2081 the following command:
2082
2083 GET AVAILABLE_ENGINES
2084
2085 Possible Answers:
2086
2087 LinuxSampler will answer by sending the number of available
2088 engines.
2089
2090 Example:
2091
2092 C: "GET AVAILABLE_ENGINES"
2093 S: "4"
2094
2095 5.4.8 Getting all available engines
2096
2097 The front-end can ask for a list of all available engines by sending
2098 the following command:
2099
2100 LIST AVAILABLE_ENGINES
2101
2102 Possible Answers:
2103
2104 LinuxSampler will answer by sending a comma separated character
2105 string of the engines' names. Engine names can consist of lower
2106 and upper cases, digits and underlines ("_" character).
2107
2108 Example:
2109
2110 C: "LIST AVAILABLE_ENGINES"
2111 S: "GigEngine,AkaiEngine,DLSEngine,JoesCustomEngine"
2112
2113 5.4.9 Getting information about an engine
2114
2115 The front-end can ask for information about a specific engine by
2116 sending the following command:
2117
2118 GET ENGINE INFO <engine-name>
2119
2120 Where <engine-name> is an engine name as obtained by the "LIST
2121 AVAILABLE_ENGINES" (Section 5.4.8) command.
2122
2123 Possible Answers:
2124
2125
2126
2127 Schoenebeck Expires November 19, 2005 [Page 38]
2128
2129 Internet-Draft LinuxSampler Control Protocol May 2005
2130
2131
2132 LinuxSampler will answer by sending a <CRLF> separated list. Each
2133 answer line begins with the information category name followed by
2134 a colon and then a space character <SP> and finally the info
2135 character string to that info category. At the moment the
2136 following categories are defined:
2137
2138 DESCRIPTION -
2139 arbitrary description text about the engine
2140 VERSION -
2141 arbitrary character string regarding the engine's version
2142
2143 The mentioned fields above don't have to be in particular order.
2144
2145 Example:
2146
2147 C: "GET ENGINE INFO JoesCustomEngine"
2148 S: "DESCRIPTION: this is Joe's custom sampler engine"
2149 "VERSION: testing-1.0"
2150 "."
2151
2152 5.4.10 Getting sampler channel information
2153
2154 The front-end can ask for the current settings of a sampler channel
2155 by sending the following command:
2156
2157 GET CHANNEL INFO <sampler-channel>
2158
2159 Where <sampler-channel> is the sampler channel number the front-end
2160 is interested in.
2161
2162 Possible Answers:
2163
2164 LinuxSampler will answer by sending a <CRLF> separated list. Each
2165 answer line begins with the settings category name followed by a
2166 colon and then a space character <SP> and finally the info
2167 character string to that setting category. At the moment the
2168 following categories are defined:
2169
2170 ENGINE_NAME -
2171 name of the engine that is deployed on the sampler channel,
2172 "NONE" if there's no engine deployed yet for this sampler
2173 channel
2174 AUDIO_OUTPUT_DEVICE -
2175 numerical ID of the audio output device which is currently
2176 connected to this sampler channel to output the audio
2177 signal, "NONE" if there's no device connected to this
2178 sampler channel
2179
2180
2181
2182
2183 Schoenebeck Expires November 19, 2005 [Page 39]
2184
2185 Internet-Draft LinuxSampler Control Protocol May 2005
2186
2187
2188 AUDIO_OUTPUT_CHANNELS -
2189 number of output channels the sampler channel offers
2190 (dependent to used sampler engine and loaded instrument)
2191 AUDIO_OUTPUT_ROUTING -
2192 comma separated list which reflects to which audio channel
2193 of the selected audio output device each sampler output
2194 channel is routed to, e.g. "0,3" would mean the engine's
2195 output channel 0 is routed to channel 0 of the audio output
2196 device and the engine's output channel 1 is routed to the
2197 channel 3 of the audio output device
2198 INSTRUMENT_FILE -
2199 the file name of the loaded instrument, "NONE" if there's no
2200 instrument yet loaded for this sampler channel
2201 INSTRUMENT_NR -
2202 the instrument index number of the loaded instrument
2203 INSTRUMENT_NAME -
2204 the instrument name of the loaded instrument
2205 INSTRUMENT_STATUS -
2206 integer values 0 to 100 indicating loading progress
2207 percentage for the instrument. Negative value indicates a
2208 loading exception. Value of 100 indicates that the
2209 instrument is fully loaded.
2210 MIDI_INPUT_DEVICE -
2211 numerical ID of the MIDI input device which is currently
2212 connected to this sampler channel to deliver MIDI input
2213 commands, "NONE" if there's no device connected to this
2214 sampler channel
2215 MIDI_INPUT_PORT -
2216 port number of the MIDI input device
2217 MIDI_INPUT_CHANNEL -
2218 the MIDI input channel number this sampler channel should
2219 listen to or "ALL" to listen on all MIDI channels
2220 VOLUME -
2221 optionally dotted number for the channel volume factor
2222 (where a value < 1.0 means attenuation and a value > 1.0
2223 means amplification)
2224
2225 The mentioned fields above don't have to be in particular order.
2226
2227 Example:
2228
2229 C: "GET CHANNEL INFO 34"
2230 S: "ENGINE_NAME: GigEngine"
2231 "VOLUME: 1.0"
2232 "AUDIO_OUTPUT_DEVICE: 0"
2233 "AUDIO_OUTPUT_CHANNELS: 2"
2234 "AUDIO_OUTPUT_ROUTING: 0,1"
2235
2236
2237
2238
2239 Schoenebeck Expires November 19, 2005 [Page 40]
2240
2241 Internet-Draft LinuxSampler Control Protocol May 2005
2242
2243
2244 "INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"
2245 "INSTRUMENT_NR: 0"
2246 "INSTRUMENT_NAME: Fazioli Piano"
2247 "INSTRUMENT_STATUS: 100"
2248 "MIDI_INPUT_DEVICE: 0"
2249 "MIDI_INPUT_PORT: 0"
2250 "MIDI_INPUT_CHANNEL: 5"
2251 "."
2252
2253 5.4.11 Current number of active voices
2254
2255 The front-end can ask for the current number of active voices on a
2256 sampler channel by sending the following command:
2257
2258 GET CHANNEL VOICE_COUNT <sampler-channel>
2259
2260 Where <sampler-channel> is the sampler channel number the front-end
2261 is interested in.
2262
2263 Possible Answers:
2264
2265 LinuxSampler will answer by returning the number of active voices
2266 on that channel.
2267
2268 Example:
2269
2270
2271
2272 5.4.12 Current number of active disk streams
2273
2274 The front-end can ask for the current number of active disk streams
2275 on a sampler channel by sending the following command:
2276
2277 GET CHANNEL STREAM_COUNT <sampler-channel>
2278
2279 Where <sampler-channel> is the sampler channel number the front-end
2280 is interested in.
2281
2282 Possible Answers:
2283
2284 LinuxSampler will answer by returning the number of active disk
2285 streams on that channel in case the engine supports disk
2286 streaming, if the engine doesn't support disk streaming it will
2287 return "NA" for not available.
2288
2289 Example:
2290
2291
2292
2293
2294
2295 Schoenebeck Expires November 19, 2005 [Page 41]
2296
2297 Internet-Draft LinuxSampler Control Protocol May 2005
2298
2299
2300
2301
2302 5.4.13 Current fill state of disk stream buffers
2303
2304 The front-end can ask for the current fill state of all disk streams
2305 on a sampler channel by sending the following command:
2306
2307 GET CHANNEL BUFFER_FILL BYTES <sampler-channel>
2308
2309 to get the fill state in bytes or
2310
2311 GET CHANNEL BUFFER_FILL PERCENTAGE <sampler-channel>
2312
2313 to get the fill state in percent, where <sampler-channel> is the
2314 sampler channel number the front-end is interested in.
2315
2316 Possible Answers:
2317
2318 LinuxSampler will either answer by returning a comma separated
2319 string with the fill state of all disk stream buffers on that
2320 channel or an empty line if there are no active disk streams or
2321 "NA" for *not available* in case the engine which is deployed
2322 doesn't support disk streaming. Each entry in the answer list
2323 will begin with the stream's ID in brackets followed by the
2324 numerical representation of the fill size (either in bytes or
2325 percentage). Note: due to efficiency reasons the fill states in
2326 the response are not in particular order, thus the front-end has
2327 to sort them by itself if necessary.
2328
2329 Examples:
2330
2331 C: "GET CHANNEL BUFFER_FILL BYTES 4"
2332 S: "[115]420500,[116]510300,[75]110000,[120]230700"
2333 C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
2334 S: "[115]90%,[116]98%,[75]40%,[120]62%"
2335 C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
2336 S: ""
2337
2338 5.4.14 Setting audio output device
2339
2340 The front-end can set the audio output device on a specific sampler
2341 channel by sending the following command:
2342
2343 SET CHANNEL AUDIO_OUTPUT_DEVICE <sampler-channel>
2344 <audio-device-id>
2345
2346 Where <audio-device-id> is the numerical ID of the audio output
2347 device and <sampler-channel> is the respective sampler channel
2348
2349
2350
2351 Schoenebeck Expires November 19, 2005 [Page 42]
2352
2353 Internet-Draft LinuxSampler Control Protocol May 2005
2354
2355
2356 number.
2357
2358 Possible Answers:
2359
2360 "OK" -
2361 on success
2362 "WRN:<warning-code>:<warning-message>" -
2363 if audio output device was set, but there are noteworthy
2364 issue(s) related, providing an appropriate warning code and
2365 warning message
2366 "ERR:<error-code>:<error-message>" -
2367 in case it failed, providing an appropriate error code and
2368 error message
2369
2370 Examples:
2371
2372
2373
2374 5.4.15 Setting audio output type
2375
2376 DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
2377
2378 The front-end can alter the audio output type on a specific sampler
2379 channel by sending the following command:
2380
2381 SET CHANNEL AUDIO_OUTPUT_TYPE <sampler-channel>
2382 <audio-output-type>
2383
2384 Where <audio-output-type> is currently either "ALSA" or "JACK" and
2385 <sampler-channel> is the respective sampler channel number.
2386
2387 Possible Answers:
2388
2389 "OK" -
2390 on success
2391 "WRN:<warning-code>:<warning-message>" -
2392 if audio output type was set, but there are noteworthy issue(s)
2393 related, providing an appropriate warning code and warning
2394 message
2395 "ERR:<error-code>:<error-message>" -
2396 in case it failed, providing an appropriate error code and
2397 error message
2398
2399 Examples:
2400
2401
2402
2403
2404
2405
2406
2407 Schoenebeck Expires November 19, 2005 [Page 43]
2408
2409 Internet-Draft LinuxSampler Control Protocol May 2005
2410
2411
2412 5.4.16 Setting audio output channel
2413
2414 The front-end can alter the audio output channel on a specific
2415 sampler channel by sending the following command:
2416
2417 SET CHANNEL AUDIO_OUTPUT_CHANNEL <sampler-chan> <audio-out>
2418 <audio-in>
2419
2420 Where <sampler-chan> is the sampler channel number, <audio-out> is
2421 the numerical ID of the sampler channel's audio output channel which
2422 should be rerouted and <audio-in> is the numerical ID of the audio
2423 channel of the selected audio output device where <audio-out> should
2424 be routed to.
2425
2426 Possible Answers:
2427
2428 "OK" -
2429 on success
2430 "WRN:<warning-code>:<warning-message>" -
2431 if audio output channel was set, but there are noteworthy
2432 issue(s) related, providing an appropriate warning code and
2433 warning message
2434 "ERR:<error-code>:<error-message>" -
2435 in case it failed, providing an appropriate error code and
2436 error message
2437
2438 Examples:
2439
2440
2441
2442 5.4.17 Setting MIDI input device
2443
2444 The front-end can set the MIDI input device on a specific sampler
2445 channel by sending the following command:
2446
2447 SET CHANNEL MIDI_INPUT_DEVICE <sampler-channel> <midi-device-id>
2448
2449 Where <sampler-channel> is the sampler channel number and
2450 <midi-device-id> is the the numerical ID of the MIDI input device.
2451
2452 Possible Answers:
2453
2454 "OK" -
2455 on success
2456 "WRN:<warning-code>:<warning-message>" -
2457 if MIDI input device was set, but there are noteworthy issue(s)
2458 related, providing an appropriate warning code and warning
2459 message
2460
2461
2462
2463 Schoenebeck Expires November 19, 2005 [Page 44]
2464
2465 Internet-Draft LinuxSampler Control Protocol May 2005
2466
2467
2468 "ERR:<error-code>:<error-message>" -
2469 in case it failed, providing an appropriate error code and
2470 error message
2471
2472 Examples:
2473
2474
2475
2476 5.4.18 Setting MIDI input type
2477
2478 DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
2479
2480 The front-end can alter the MIDI input type on a specific sampler
2481 channel by sending the following command:
2482
2483 SET CHANNEL MIDI_INPUT_TYPE <sampler-channel> <midi-input-type>
2484
2485 Where <midi-input-type> is currently only "ALSA" and
2486 <sampler-channel> is the respective sampler channel number.
2487
2488 Possible Answers:
2489
2490 "OK" -
2491 on success
2492 "WRN:<warning-code>:<warning-message>" -
2493 if MIDI input type was set, but there are noteworthy issue(s)
2494 related, providing an appropriate warning code and warning
2495 message
2496 "ERR:<error-code>:<error-message>" -
2497 in case it failed, providing an appropriate error code and
2498 error message
2499
2500 Examples:
2501
2502
2503
2504 5.4.19 Setting MIDI input port
2505
2506 The front-end can alter the MIDI input port on a specific sampler
2507 channel by sending the following command:
2508
2509 SET CHANNEL MIDI_INPUT_PORT <sampler-channel> <midi-input-port>
2510
2511 Where <midi-input-port> is a MIDI input port number of the MIDI input
2512 device connected to the sampler channel given by <sampler-channel>.
2513
2514 Possible Answers:
2515
2516
2517
2518
2519 Schoenebeck Expires November 19, 2005 [Page 45]
2520
2521 Internet-Draft LinuxSampler Control Protocol May 2005
2522
2523
2524 "OK" -
2525 on success
2526 "WRN:<warning-code>:<warning-message>" -
2527 if MIDI input port was set, but there are noteworthy issue(s)
2528 related, providing an appropriate warning code and warning
2529 message
2530 "ERR:<error-code>:<error-message>" -
2531 in case it failed, providing an appropriate error code and
2532 error messag
2533
2534 Examples:
2535
2536
2537
2538 5.4.20 Setting MIDI input channel
2539
2540 The front-end can alter the MIDI channel a sampler channel should
2541 listen to by sending the following command:
2542
2543 SET CHANNEL MIDI_INPUT_CHANNEL <sampler-channel> <midi-input-chan>
2544
2545 Where <midi-input-chan> is the number of the new MIDI input channel
2546 where <sampler-channel> should listen to or "ALL" to listen on all 16
2547 MIDI channels.
2548
2549 Possible Answers:
2550
2551 "OK" -
2552 on success
2553 "WRN:<warning-code>:<warning-message>" -
2554 if MIDI input channel was set, but there are noteworthy
2555 issue(s) related, providing an appropriate warning code and
2556 warning message
2557 "ERR:<error-code>:<error-message>" -
2558 in case it failed, providing an appropriate error code and
2559 error message
2560
2561 Examples:
2562
2563
2564
2565 5.4.21 Setting channel volume
2566
2567 The front-end can alter the volume of a sampler channel by sending
2568 the following command:
2569
2570 SET CHANNEL VOLUME <sampler-channel> <volume>
2571
2572
2573
2574
2575 Schoenebeck Expires November 19, 2005 [Page 46]
2576
2577 Internet-Draft LinuxSampler Control Protocol May 2005
2578
2579
2580 Where <volume> is an optionally dotted positive number (a value
2581 smaller than 1.0 means attenuation, whereas a value greater than 1.0
2582 means amplification) and <sampler-channel> defines the sampler
2583 channel where this volume factor should be set.
2584
2585 Possible Answers:
2586
2587 "OK" -
2588 on success
2589 "WRN:<warning-code>:<warning-message>" -
2590 if channel volume was set, but there are noteworthy issue(s)
2591 related, providing an appropriate warning code and warning
2592 message
2593 "ERR:<error-code>:<error-message>" -
2594 in case it failed, providing an appropriate error code and
2595 error message
2596
2597 Examples:
2598
2599
2600
2601 5.4.22 Resetting a sampler channel
2602
2603 The front-end can reset a particular sampler channel by sending the
2604 following command:
2605
2606 RESET CHANNEL <sampler-channel>
2607
2608 Where <sampler-channel> defines the sampler channel to be reset.
2609 This will cause the engine on that sampler channel, its voices and
2610 eventually disk streams and all control and status variables to be
2611 reset.
2612
2613 Possible Answers:
2614
2615 "OK" -
2616 on success
2617 "WRN:<warning-code>:<warning-message>" -
2618 if channel was reset, but there are noteworthy issue(s)
2619 related, providing an appropriate warning code and warning
2620 message
2621 "ERR:<error-code>:<error-message>" -
2622 in case it failed, providing an appropriate error code and
2623 error message
2624
2625 Examples:
2626
2627
2628
2629
2630
2631 Schoenebeck Expires November 19, 2005 [Page 47]
2632
2633 Internet-Draft LinuxSampler Control Protocol May 2005
2634
2635
2636
2637
2638 5.5 Controlling connection
2639
2640 The following commands are used to control the connection to
2641 LinuxSampler.
2642
2643 5.5.1 Register front-end for receiving event messages
2644
2645 The front-end can register itself to the LinuxSampler application to
2646 be informed about noteworthy events by sending this command:
2647
2648 SUBSCRIBE <event-id>
2649
2650 where <event-id> will be replaced by the respective event that client
2651 wants to subscribe to.
2652
2653 Possible Answers:
2654
2655 "OK" -
2656 on success
2657 "WRN:<warning-code>:<warning-message>" -
2658 if registration succeeded, but there are noteworthy issue(s)
2659 related, providing an appropriate warning code and warning
2660 message
2661 "ERR:<error-code>:<error-message>" -
2662 in case it failed, providing an appropriate error code and
2663 error message
2664
2665 Examples:
2666
2667
2668
2669 5.5.2 Unregister front-end for not receiving event messages
2670
2671 The front-end can unregister itself if it doesn't want to receive
2672 event messages anymore by sending the following command:
2673
2674 UNSUBSCRIBE <event-id>
2675
2676 Where <event-id> will be replaced by the respective event that client
2677 doesn't want to receive anymore.
2678
2679 Possible Answers:
2680
2681 "OK" -
2682 on success
2683
2684
2685
2686
2687 Schoenebeck Expires November 19, 2005 [Page 48]
2688
2689 Internet-Draft LinuxSampler Control Protocol May 2005
2690
2691
2692 "WRN:<warning-code>:<warning-message>" -
2693 if unregistration succeeded, but there are noteworthy issue(s)
2694 related, providing an appropriate warning code and warning
2695 message
2696 "ERR:<error-code>:<error-message>" -
2697 in case it failed, providing an appropriate error code and
2698 error message
2699
2700 Examples:
2701
2702
2703
2704 5.5.3 Enable or disable echo of commands
2705
2706 To enable or disable back sending of commands to the client the
2707 following command can be used:
2708
2709 SET ECHO <value>
2710
2711 Where <value> should be replaced either by "1" to enable echo mode or
2712 "0" to disable echo mode. When echo mode is enabled, all commands
2713 send to LinuxSampler will be immediately send back and after this
2714 echo the actual response to the command will be returned. Echo mode
2715 will only be altered for the client connection that issued the "SET
2716 ECHO" command, not globally for all client connections.
2717
2718 Possible Answers:
2719
2720 "OK" -
2721 usually
2722 "ERR:<error-code>:<error-message>" -
2723 on syntax error, e.g. non boolean value
2724
2725 Examples:
2726
2727
2728
2729 5.5.4 Close client connection
2730
2731 The client can close its network connection to LinuxSampler by
2732 sending the following command:
2733
2734 QUIT
2735
2736 This is probably more interesting for manual telnet connections to
2737 LinuxSampler than really useful for a front-end implementation.
2738
2739
2740
2741
2742
2743 Schoenebeck Expires November 19, 2005 [Page 49]
2744
2745 Internet-Draft LinuxSampler Control Protocol May 2005
2746
2747
2748 5.6 Global commands
2749
2750 The following commands have global impact on the sampler.
2751
2752 5.6.1 Reset sampler
2753
2754 The front-end can reset the whole sampler by sending the following
2755 command:
2756
2757 RESET
2758
2759 Possible Answers:
2760
2761 "OK" -
2762 always
2763
2764 Examples:
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799 Schoenebeck Expires November 19, 2005 [Page 50]
2800
2801 Internet-Draft LinuxSampler Control Protocol May 2005
2802
2803
2804 6. Command Syntax
2805
2806 TODO: will soon automatically included from src/network/lscp.y,
2807 meanwhile have a look at that file to get the exact definition of the
2808 command syntax.
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855 Schoenebeck Expires November 19, 2005 [Page 51]
2856
2857 Internet-Draft LinuxSampler Control Protocol May 2005
2858
2859
2860 7. Events
2861
2862 This chapter will describe all currently defined events supported by
2863 LinuxSampler.
2864
2865 7.1 Number of sampler channels changed
2866
2867 Client may want to be notified when the total number of channels on
2868 the back-end changes by issuing the following command:
2869
2870 SUBSCRIBE CHANNEL_COUNT
2871
2872 Server will start sending the following notification messages:
2873
2874 "NOTIFY:CHANNEL_COUNT:<channels>"
2875
2876 where <channels> will be replaced by the new number of sampler
2877 channels.
2878
2879 7.2 Number of active voices changed
2880
2881 Client may want to be notified when the number of voices on the
2882 back-end changes by issuing the following command:
2883
2884 SUBSCRIBE VOICE_COUNT
2885
2886 Server will start sending the following notification messages:
2887
2888 "NOTIFY:VOICE_COUNT:<sampler-channel> <voices>
2889
2890 where <sampler-channel> will be replaced by the sampler channel the
2891 voice count change occurred and <voices> by the new number of active
2892 voices on that channel.
2893
2894 7.3 Number of active disk streams changed
2895
2896 Client may want to be notified when the number of streams on the
2897 back-end changes by issuing the following command: SUBSCRIBE
2898 STREAM_COUNT
2899
2900 SUBSCRIBE STREAM_COUNT
2901
2902 Server will start sending the following notification messages:
2903
2904 "NOTIFY:STREAM_COUNT:<sampler-channel> <streams>"
2905
2906 where <sampler-channel> will be replaced by the sampler channel the
2907 stream count change occurred and <streams> by the new number of
2908
2909
2910
2911 Schoenebeck Expires November 19, 2005 [Page 52]
2912
2913 Internet-Draft LinuxSampler Control Protocol May 2005
2914
2915
2916 active disk streams on that channel.
2917
2918 7.4 Disk stream buffer fill state changed
2919
2920 Client may want to be notified when the buffer fill state of a disk
2921 stream on the back-end changes by issuing the following command:
2922
2923 SUBSCRIBE BUFFER_FILL
2924
2925 Server will start sending the following notification messages:
2926
2927 "NOTIFY:BUFFER_FILL:<sampler-channel> <fill-data>"
2928
2929 where <sampler-channel> will be replaced by the sampler channel the
2930 buffer fill state change occurred on and <fill-data> will be replaced
2931 by the buffer fill data for this channel as described in Section
2932 5.4.13 as if the "GET CHANNEL BUFFER_FILL PERCENTAGE" (Section
2933 5.4.13) command was issued on this channel.
2934
2935 7.5 Channel information changed
2936
2937 Client may want to be notified when changes were made to sampler
2938 channels on the back-end changes by issuing the following command:
2939
2940 SUBSCRIBE CHANNEL_INFO
2941
2942 Server will start sending the following notification messages:
2943
2944 "NOTIFY:CHANNEL_INFO:<sampler-channel>"
2945
2946 where <sampler-channel> will be replaced by the sampler channel the
2947 channel info change occurred. The front-end will have to send the
2948 respective command to actually get the channel info. Because these
2949 messages will be triggered by LSCP commands issued by other clients
2950 rather than real time events happening on the server, it is believed
2951 that an empty notification message is sufficient here.
2952
2953 7.6 Miscellaneous and debugging events
2954
2955 Client may want to be notified of miscellaneous and debugging events
2956 occurring at the server by issuing the following command:
2957
2958 SUBSCRIBE MISCELLANEOUS
2959
2960 Server will start sending the following notification messages:
2961
2962 "NOTIFY:MISCELLANEOUS:<string>"
2963
2964
2965
2966
2967 Schoenebeck Expires November 19, 2005 [Page 53]
2968
2969 Internet-Draft LinuxSampler Control Protocol May 2005
2970
2971
2972 where <string> will be replaced by whatever data server wants to send
2973 to the client. Client MAY display this data to the user AS IS to
2974 facilitate debugging.
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023 Schoenebeck Expires November 19, 2005 [Page 54]
3024
3025 Internet-Draft LinuxSampler Control Protocol May 2005
3026
3027
3028 8. Security Considerations
3029
3030 As there is so far no method of authentication and authorization
3031 defined and so not required for a client applications to succeed to
3032 connect, running LinuxSampler might be a security risk for the host
3033 system the LinuxSampler instance is running on.
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079 Schoenebeck Expires November 19, 2005 [Page 55]
3080
3081 Internet-Draft LinuxSampler Control Protocol May 2005
3082
3083
3084 9. Acknowledgments
3085
3086 This document has benefited greatly from the comments of the
3087 following people, discussed on the LinuxSampler developer's mailing
3088 list:
3089
3090 Rui Nuno Capela
3091 Vladimir Senkov
3092 Mark Knecht
3093
3094 10 References
3095
3096 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
3097 Requirement Levels", BCP 14, RFC 2119, March 1997.
3098
3099
3100 Author's Address
3101
3102 C. Schoenebeck
3103 Interessengemeinschaft Software Engineering e. V.
3104 Max-Planck-Str. 39
3105 74081 Heilbronn
3106 Germany
3107
3108 EMail: schoenebeck at software minus engineering dot org
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135 Schoenebeck Expires November 19, 2005 [Page 56]
3136
3137 Internet-Draft LinuxSampler Control Protocol May 2005
3138
3139
3140 Intellectual Property Statement
3141
3142 The IETF takes no position regarding the validity or scope of any
3143 intellectual property or other rights that might be claimed to
3144 pertain to the implementation or use of the technology described in
3145 this document or the extent to which any license under such rights
3146 might or might not be available; neither does it represent that it
3147 has made any effort to identify any such rights. Information on the
3148 IETF's procedures with respect to rights in standards-track and
3149 standards-related documentation can be found in BCP-11. Copies of
3150 claims of rights made available for publication and any assurances of
3151 licenses to be made available, or the result of an attempt made to
3152 obtain a general license or permission for the use of such
3153 proprietary rights by implementors or users of this specification can
3154 be obtained from the IETF Secretariat.
3155
3156 The IETF invites any interested party to bring to its attention any
3157 copyrights, patents or patent applications, or other proprietary
3158 rights which may cover technology that may be required to practice
3159 this standard. Please address the information to the IETF Executive
3160 Director.
3161
3162
3163 Full Copyright Statement
3164
3165 Copyright (C) The Internet Society (2005). All Rights Reserved.
3166
3167 This document and translations of it may be copied and furnished to
3168 others, and derivative works that comment on or otherwise explain it
3169 or assist in its implementation may be prepared, copied, published
3170 and distributed, in whole or in part, without restriction of any
3171 kind, provided that the above copyright notice and this paragraph are
3172 included on all such copies and derivative works. However, this
3173 document itself may not be modified in any way, such as by removing
3174 the copyright notice or references to the Internet Society or other
3175 Internet organizations, except as needed for the purpose of
3176 developing Internet standards in which case the procedures for
3177 copyrights defined in the Internet Standards process must be
3178 followed, or as required to translate it into languages other than
3179 English.
3180
3181 The limited permissions granted above are perpetual and will not be
3182 revoked by the Internet Society or its successors or assignees.
3183
3184 This document and the information contained herein is provided on an
3185 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
3186 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
3187 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
3188
3189
3190
3191 Schoenebeck Expires November 19, 2005 [Page 57]
3192
3193 Internet-Draft LinuxSampler Control Protocol May 2005
3194
3195
3196 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
3197 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
3198
3199
3200 Acknowledgment
3201
3202 Funding for the RFC Editor function is currently provided by the
3203 Internet Society.
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247 Schoenebeck Expires November 19, 2005 [Page 58]
3248

  ViewVC Help
Powered by ViewVC