--- web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.html 2006/11/25 17:18:12 940
+++ web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.html 2007/03/29 10:06:37 1137
@@ -3,139 +3,159 @@
-
-
+ a { font-weight: bold; }
+ a:link { color: #900; background-color: transparent; }
+ a:visited { color: #633; background-color: transparent; }
+ a:active { color: #633; background-color: transparent; }
+
+ p { margin-left: 2em; margin-right: 2em; }
+ p.copyright { font-size: x-small; }
+ p.toc { font-size: small; font-weight: bold; margin-left: 3em; }
+ table.toc { margin: 0 0 0 3em; padding: 0; border: 0; vertical-align: text-top; }
+ td.toc { font-size: small; font-weight: bold; vertical-align: text-top; }
+
+ ol.text { margin-left: 2em; margin-right: 2em; }
+ ul.text { margin-left: 2em; margin-right: 2em; }
+ li { margin-left: 3em; }
+
+ /* RFC-2629
-This document is an Internet-Draft and is
-in full conformance with all provisions of Section 10 of RFC 2026.
+ TOC TOC
-
LinuxSampler Developers C. Schoenebeck
-Internet-Draft Interessengemeinschaft Software
-Expires: May 29, 2007 Engineering e. V.
+ November 25, 2006
+Intended status: Standards Track Engineering e. V. Expires: September 30, 2007 March 29, 2007
LinuxSampler Control Protocol
LSCP 1.1
LinuxSampler Control Protocol
LSCP 1.2Status of this Memo
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. @@ -153,11 +173,11 @@ The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.
-This Internet-Draft will expire on May 29, 2007.
+This Internet-Draft will expire on September 30, 2007.-Copyright © The Internet Society (2006). All Rights Reserved.
+Copyright © The IETF Trust (2007).TOC |
TOC |
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as - described in [RFC2119] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” 1997.). + described in [RFC2119] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” 1997.).
This protocol is always case-sensitive if not explicitly claimed the opposite. @@ -432,8 +525,9 @@ return and line feed characters respectively.
TOC |
TOC |
LSCP will certainly be extended and enhanced by-and-by. Each official release of the LSCP specification will be tagged with a unique version @@ -476,13 +570,14 @@
Compatibility can only be claimed if both rules are true. The frontend can use the - "GET SERVER INFO" (General sampler informations) command to + "GET SERVER INFO" (General sampler informations) command to get the version of the LSCP specification the sampler complies with.
TOC |
TOC |
LinuxSampler is a so called software sampler application capable to playback audio samples from a computer's Random @@ -502,8 +597,9 @@ there.
TOC |
TOC |
Main focus of this protocol is to provide a way to configure a running LinuxSampler instance and to retrieve information @@ -514,8 +610,9 @@ via MIDI System Exclusive Messages.
TOC |
TOC |
There are two distinct methods of communication between a running instance of LinuxSampler and one or more control @@ -529,11 +626,12 @@ methods will be described next.
TOC |
TOC |
This simple communication method is based on - TCP (Defense Advanced Research Projects Agency, “TRANSMISSION CONTROL PROTOCOL,” 1981.) [RFC793]. The + TCP (Defense Advanced Research Projects Agency, “TRANSMISSION CONTROL PROTOCOL,” 1981.) [RFC793]. The front-end application establishes a TCP connection to the LinuxSampler instance on a certain host system. Then the front-end application will send certain ASCII based commands @@ -574,8 +672,9 @@ MUST be sent back in the same order.
TOC |
TOC |
Result set could be one of the following types:
@@ -766,8 +865,9 @@TOC |
TOC |
This more sophisticated communication method is actually only an extension of the simple request/response @@ -844,7 +944,7 @@
where <event-id> will be replace by the respective event that client is no longer interested in receiving. For - a list of supported events see Section 8 (Events). + a list of supported events see Section 8 (Events).
Example: the fill states of disk stream buffers have changed on sampler channel 4 and the LinuxSampler instance @@ -890,19 +990,21 @@ it wants to receive.
TOC |
TOC |
This chapter will describe the available control commands that can be sent on the TCP connection in detail. Some certain - commands (e.g. "GET CHANNEL INFO" (Getting sampler channel information) - or "GET ENGINE INFO" (Getting information about an engine)) lead to + commands (e.g. "GET CHANNEL INFO" (Getting sampler channel information) + or "GET ENGINE INFO" (Getting information about an engine)) lead to multiple-line responses. In this case LinuxSampler signals the end of the response by a "." (single dot) line.
TOC |
TOC |
White lines, that is lines which only contain space and tabulator characters, and lines that start with a "#" @@ -911,8 +1013,9 @@ file.
TOC |
TOC |
Instances of drivers in LinuxSampler are called devices. You can use multiple audio devices simultaneously, e.g. to @@ -946,8 +1049,9 @@ possible values, etc.
TOC |
TOC |
Use the following command to get the number of audio output drivers currently available for the @@ -985,8 +1089,9 @@
TOC |
TOC |
Use the following command to list all audio output drivers currently available for the LinuxSampler @@ -1025,8 +1130,9 @@
TOC |
TOC |
Use the following command to get detailed information @@ -1043,7 +1149,7 @@
Where <audio-output-driver> is the name of the audio output driver, returned by the - "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Getting all available audio output drivers) command. + "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Getting all available audio output drivers) command.
Possible Answers:
@@ -1124,8 +1230,9 @@TOC |
TOC |
Use the following command to get detailed information @@ -1140,10 +1247,10 @@
Where <audio> is the name of the audio output - driver as returned by the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Getting all available audio output drivers) command, + driver as returned by the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Getting all available audio output drivers) command, <prm> a specific parameter name for which information should be obtained (as returned by the - "GET AUDIO_OUTPUT_DRIVER INFO" (Getting information about a specific audio output driver) command) and + "GET AUDIO_OUTPUT_DRIVER INFO" (Getting information about a specific audio output driver) command) and <deplist> is an optional list of parameters on which the sought parameter <prm> depends on, <deplist> is a list of key-value pairs in form of "key1=val1 key2=val2 ...", where character string values @@ -1200,7 +1307,7 @@
@@ -1211,7 +1318,7 @@either true or false, defines if this parameter must be given when the device is to be created with the - 'CREATE AUDIO_OUTPUT_DEVICE' (Creating an audio output device) + 'CREATE AUDIO_OUTPUT_DEVICE' (Creating an audio output device) command (always returned, no matter which driver parameter)
@@ -1250,7 +1357,7 @@either true or false, if false then this parameter can be changed at any time, once the device is created by - the 'CREATE AUDIO_OUTPUT_DEVICE' (Creating an audio output device) + the 'CREATE AUDIO_OUTPUT_DEVICE' (Creating an audio output device) command (always returned, no matter which driver parameter)
@@ -3895,14 +4047,23 @@reflects the default value for this parameter which is used when the device is created and not explicitly - given with the 'CREATE AUDIO_OUTPUT_DEVICE' (Creating an audio output device) command, + given with the 'CREATE AUDIO_OUTPUT_DEVICE' (Creating an audio output device) command, in case of MULTIPLCITY=true, this is a comma separated list, that's why character strings are encapsulated into apostrophes (') @@ -1378,8 +1485,9 @@
--
TOC 6.2.5. Creating an audio output device
++
TOC 6.2.5. +Creating an audio output device
Use the following command to create a new audio output device for the desired audio output system:
@@ -1393,7 +1501,7 @@Where <audio-output-driver> should be replaced by the desired audio output system as returned by the - "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Getting all available audio output drivers) + "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Getting all available audio output drivers) command and <param-list> by an optional list of driver specific parameters in form of "key1=val1 key2=val2 ...", where character string values should be encapsulated into apostrophes ('). @@ -1462,8 +1570,9 @@
--
TOC 6.2.6. Destroying an audio output device
++
TOC 6.2.6. +Destroying an audio output device
Use the following command to destroy a created output device:
@@ -1477,8 +1586,8 @@Where <device-id> should be replaced by the numerical ID of the audio output device as given by the - "CREATE AUDIO_OUTPUT_DEVICE" (Creating an audio output device) - or "LIST AUDIO_OUTPUT_DEVICES" (Getting all created audio output device list) + "CREATE AUDIO_OUTPUT_DEVICE" (Creating an audio output device) + or "LIST AUDIO_OUTPUT_DEVICES" (Getting all created audio output device list) command.
Possible Answers: @@ -1531,8 +1640,9 @@
--
TOC 6.2.7. Getting all created audio output device count
++
TOC 6.2.7. +Getting all created audio output device count
Use the following command to count all created audio output devices:
@@ -1568,8 +1678,9 @@
--
TOC 6.2.8. Getting all created audio output device list
++
TOC 6.2.8. +Getting all created audio output device list
Use the following command to list all created audio output devices:
@@ -1605,8 +1716,9 @@
--
TOC 6.2.9. Getting current settings of an audio output device
++
TOC 6.2.9. +Getting current settings of an audio output device
Use the following command to get current settings of a specific, created audio output device:
@@ -1620,7 +1732,7 @@Where <device-id> should be replaced by numerical ID of the audio output device as e.g. returned by the - "LIST AUDIO_OUTPUT_DEVICES" (Getting all created audio output device list) command. + "LIST AUDIO_OUTPUT_DEVICES" (Getting all created audio output device list) command.
Possible Answers:
@@ -1640,7 +1752,7 @@@@ -1681,7 +1793,7 @@ order. The fields above are only those fields which are returned by all audio output devices. Every audio output driver might have its own, additional driver specific parameters (see - Section 6.2.3 (Getting information about a specific audio output driver)) + Section 6.2.3 (Getting information about a specific audio output driver)) which are also returned by this command.identifier of the used audio output driver, as also returned by the - "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Getting all available audio output drivers) + "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Getting all available audio output drivers) command
Example: @@ -1711,8 +1823,9 @@
--
TOC 6.2.10. Changing settings of audio output devices
++
TOC 6.2.10. +Changing settings of audio output devices
Use the following command to alter a specific setting of a created audio output device:
@@ -1726,8 +1839,8 @@Where <device-id> should be replaced by the numerical ID of the audio output device as given by the - "CREATE AUDIO_OUTPUT_DEVICE" (Creating an audio output device) - or "LIST AUDIO_OUTPUT_DEVICES" (Getting all created audio output device list) + "CREATE AUDIO_OUTPUT_DEVICE" (Creating an audio output device) + or "LIST AUDIO_OUTPUT_DEVICES" (Getting all created audio output device list) command, <key> by the name of the parameter to change and <value> by the new value for this parameter.
@@ -1779,8 +1892,9 @@
--
TOC 6.2.11. Getting information about an audio channel
++
TOC 6.2.11. +Getting information about an audio channel
Use the following command to get information about an audio channel:
@@ -1793,8 +1907,8 @@Where <device-id> is the numerical ID of the audio output device as given by the - "CREATE AUDIO_OUTPUT_DEVICE" (Creating an audio output device) - or "LIST AUDIO_OUTPUT_DEVICES" (Getting all created audio output device list) + "CREATE AUDIO_OUTPUT_DEVICE" (Creating an audio output device) + or "LIST AUDIO_OUTPUT_DEVICES" (Getting all created audio output device list) command and <audio-chan> the audio channel number.
Possible Answers: @@ -1921,8 +2035,9 @@
--
TOC 6.2.12. Getting information about specific audio channel parameter
++
TOC 6.2.12. +Getting information about specific audio channel parameter
Use the following command to get detailed information about specific audio channel parameter:
@@ -1935,11 +2050,11 @@Where <dev-id> is the numerical ID of the audio output device as returned by the - "CREATE AUDIO_OUTPUT_DEVICE" (Creating an audio output device) - or "LIST AUDIO_OUTPUT_DEVICES" (Getting all created audio output device list) + "CREATE AUDIO_OUTPUT_DEVICE" (Creating an audio output device) + or "LIST AUDIO_OUTPUT_DEVICES" (Getting all created audio output device list) command, <chan> the audio channel number and <param> a specific channel parameter name for which information should - be obtained (as returned by the "GET AUDIO_OUTPUT_CHANNEL INFO" (Getting information about an audio channel) command). + be obtained (as returned by the "GET AUDIO_OUTPUT_CHANNEL INFO" (Getting information about an audio channel) command).
Possible Answers:
@@ -2067,8 +2182,9 @@
--
TOC 6.2.13. Changing settings of audio output channels
++
TOC 6.2.13. +Changing settings of audio output channels
Use the following command to alter a specific setting of an audio output channel:
@@ -2081,8 +2197,8 @@Where <dev-id> should be replaced by the numerical ID of the audio output device as returned by the - "CREATE AUDIO_OUTPUT_DEVICE" (Creating an audio output device) - or "LIST AUDIO_OUTPUT_DEVICES" (Getting all created audio output device list) + "CREATE AUDIO_OUTPUT_DEVICE" (Creating an audio output device) + or "LIST AUDIO_OUTPUT_DEVICES" (Getting all created audio output device list) command, <chn> by the audio channel number, <key> by the name of the parameter to change and <value> by the new value for this parameter.
@@ -2144,8 +2260,9 @@
--
TOC 6.3. Configuring MIDI input drivers
++
TOC 6.3. +Configuring MIDI input drivers
Instances of drivers in LinuxSampler are called devices. You can use multiple MIDI devices simultaneously, e.g. to use MIDI over ethernet as @@ -2174,8 +2291,9 @@ possible values, etc.
--
TOC 6.3.1. Getting amount of available MIDI input drivers
++
TOC 6.3.1. +Getting amount of available MIDI input drivers
Use the following command to get the number of MIDI input drivers currently available for the @@ -2213,8 +2331,9 @@
--
TOC 6.3.2. Getting all available MIDI input drivers
++
TOC 6.3.2. +Getting all available MIDI input drivers
Use the following command to list all MIDI input drivers currently available for the LinuxSampler instance: @@ -2251,8 +2370,9 @@
--
TOC 6.3.3. Getting information about a specific MIDI input driver
++
TOC 6.3.3. +Getting information about a specific MIDI input driver
Use the following command to get detailed information about a specific MIDI input driver:
@@ -2265,7 +2385,7 @@Where <midi-input-driver> is the name of the MIDI input driver as returned - by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Getting all available MIDI input drivers) command. + by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Getting all available MIDI input drivers) command.
Possible Answers:
@@ -2332,8 +2452,9 @@
--
TOC 6.3.4. Getting information about specific MIDI input driver parameter
++
TOC 6.3.4. +Getting information about specific MIDI input driver parameter
Use the following command to get detailed information about a specific parameter of a specific MIDI input driver:
@@ -2346,9 +2467,9 @@Where <midit> is the name of the MIDI input driver as returned - by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Getting all available MIDI input drivers) command, <param> a specific + by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Getting all available MIDI input drivers) command, <param> a specific parameter name for which information should be obtained (as returned by the - "GET MIDI_INPUT_DRIVER INFO" (Getting information about a specific MIDI input driver) command) and <deplist> is an optional list + "GET MIDI_INPUT_DRIVER INFO" (Getting information about a specific MIDI input driver) command) and <deplist> is an optional list of parameters on which the sought parameter <param> depends on, <deplist> is a key-value pair list in form of "key1=val1 key2=val2 ...", where character string values are encapsulated into apostrophes ('). Arguments @@ -2395,7 +2516,7 @@
@@ -2406,7 +2527,7 @@either true or false, defines if this parameter must be given when the device is to be created with the - 'CREATE MIDI_INPUT_DEVICE' (Creating a MIDI input device) command + 'CREATE MIDI_INPUT_DEVICE' (Creating a MIDI input device) command (always returned, no matter which driver parameter)
@@ -2445,7 +2566,7 @@either true or false, if false then this parameter can be changed at any time, once the device is created by - the 'CREATE MIDI_INPUT_DEVICE' (Creating a MIDI input device) command + the 'CREATE MIDI_INPUT_DEVICE' (Creating a MIDI input device) command (always returned, no matter which driver parameter)
+reflects the default value for this parameter which is used when the device is created and not explicitly - given with the 'CREATE MIDI_INPUT_DEVICE' (Creating a MIDI input device) command, + given with the 'CREATE MIDI_INPUT_DEVICE' (Creating a MIDI input device) command, in case of MULTIPLCITY=true, this is a comma separated list, that's why character strings are encapsulated into apostrophes (') @@ -2519,8 +2640,9 @@
--
TOC 6.3.5. Creating a MIDI input device
++
TOC 6.3.5. +Creating a MIDI input device
Use the following command to create a new MIDI input device for the desired MIDI input system:
@@ -2533,7 +2655,7 @@Where <midi-input-driver> should be replaced by the desired MIDI input system as returned - by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Getting all available MIDI input drivers) command and <param-list> by an + by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Getting all available MIDI input drivers) command and <param-list> by an optional list of driver specific parameters in form of "key1=val1 key2=val2 ...", where character string values should be encapsulated into apostrophes ('). Note that there might be drivers which require parameter(s) to be @@ -2589,8 +2711,9 @@
--
TOC 6.3.6. Destroying a MIDI input device
++
TOC 6.3.6. +Destroying a MIDI input device
Use the following command to destroy a created MIDI input device:
@@ -2603,8 +2726,8 @@Where <device-id> should be replaced by the device's numerical ID as returned by the - "CREATE MIDI_INPUT_DEVICE" (Creating a MIDI input device) - or "LIST MIDI_INPUT_DEVICES" (Getting all created MIDI input device list) + "CREATE MIDI_INPUT_DEVICE" (Creating a MIDI input device) + or "LIST MIDI_INPUT_DEVICES" (Getting all created MIDI input device list) command.
Possible Answers: @@ -2654,8 +2777,9 @@
--
TOC 6.3.7. Getting all created MIDI input device count
++
TOC 6.3.7. +Getting all created MIDI input device count
Use the following command to count all created MIDI input devices:
@@ -2691,8 +2815,9 @@
--
TOC 6.3.8. Getting all created MIDI input device list
++
TOC 6.3.8. +Getting all created MIDI input device list
Use the following command to list all created MIDI input devices:
@@ -2738,8 +2863,9 @@
--
TOC 6.3.9. Getting current settings of a MIDI input device
++
TOC 6.3.9. +Getting current settings of a MIDI input device
Use the following command to get current settings of a specific, created MIDI input device:
@@ -2752,8 +2878,8 @@Where <device-id> is the numerical ID of the MIDI input device as returned by the - "CREATE MIDI_INPUT_DEVICE" (Creating a MIDI input device) - or "LIST MIDI_INPUT_DEVICES" (Getting all created MIDI input device list) + "CREATE MIDI_INPUT_DEVICE" (Creating a MIDI input device) + or "LIST MIDI_INPUT_DEVICES" (Getting all created MIDI input device list) command.
Possible Answers: @@ -2776,7 +2902,7 @@
@@ -2806,7 +2932,7 @@ order. The fields above are only those fields which are returned by all MIDI input devices. Every MIDI input driver might have its own, additional driver specific parameters (see - "GET MIDI_INPUT_DRIVER INFO" (Getting information about a specific MIDI input driver) command) which are also returned + "GET MIDI_INPUT_DRIVER INFO" (Getting information about a specific MIDI input driver) command) which are also returned by this command.identifier of the used MIDI input driver, as e.g. - returned by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Getting all available MIDI input drivers) + returned by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Getting all available MIDI input drivers) command
Example: @@ -2826,8 +2952,9 @@
--
TOC 6.3.10. Changing settings of MIDI input devices
++
TOC 6.3.10. +Changing settings of MIDI input devices
Use the following command to alter a specific setting of a created MIDI input device:
@@ -2841,8 +2968,8 @@Where <device-id> should be replaced by the numerical ID of the MIDI input device as returned by the - "CREATE MIDI_INPUT_DEVICE" (Creating a MIDI input device) - or "LIST MIDI_INPUT_DEVICES" (Getting all created MIDI input device list) + "CREATE MIDI_INPUT_DEVICE" (Creating a MIDI input device) + or "LIST MIDI_INPUT_DEVICES" (Getting all created MIDI input device list) command, <key> by the name of the parameter to change and <value> by the new value for this parameter.
@@ -2893,8 +3020,9 @@
--
TOC 6.3.11. Getting information about a MIDI port
++
TOC 6.3.11. +Getting information about a MIDI port
Use the following command to get information about a MIDI port:
@@ -2907,8 +3035,8 @@Where <device-id> is the numerical ID of the MIDI input device as returned by the - "CREATE MIDI_INPUT_DEVICE" (Creating a MIDI input device) - or "LIST MIDI_INPUT_DEVICES" (Getting all created MIDI input device list) + "CREATE MIDI_INPUT_DEVICE" (Creating a MIDI input device) + or "LIST MIDI_INPUT_DEVICES" (Getting all created MIDI input device list) command and <midi-port> the MIDI input port number.
Possible Answers: @@ -2955,8 +3083,9 @@
--
TOC 6.3.12. Getting information about specific MIDI port parameter
++
TOC 6.3.12. +Getting information about specific MIDI port parameter
Use the following command to get detailed information about specific MIDI port parameter:
@@ -2969,11 +3098,11 @@Where <dev-id> is the numerical ID of the MIDI input device as returned by the - "CREATE MIDI_INPUT_DEVICE" (Creating a MIDI input device) - or "LIST MIDI_INPUT_DEVICES" (Getting all created MIDI input device list) + "CREATE MIDI_INPUT_DEVICE" (Creating a MIDI input device) + or "LIST MIDI_INPUT_DEVICES" (Getting all created MIDI input device list) command, <port> the MIDI port number and <param> a specific port parameter name for which information should be - obtained (as returned by the "GET MIDI_INPUT_PORT INFO" (Getting information about a MIDI port) command). + obtained (as returned by the "GET MIDI_INPUT_PORT INFO" (Getting information about a MIDI port) command).
Possible Answers:
@@ -3096,8 +3225,9 @@
--
TOC 6.3.13. Changing settings of MIDI input ports
++
TOC 6.3.13. +Changing settings of MIDI input ports
Use the following command to alter a specific setting of a MIDI input port:
@@ -3111,8 +3241,8 @@Where <device-id> should be replaced by the numerical ID of the MIDI device as returned by the - "CREATE MIDI_INPUT_DEVICE" (Creating a MIDI input device) - or "LIST MIDI_INPUT_DEVICES" (Getting all created MIDI input device list) + "CREATE MIDI_INPUT_DEVICE" (Creating a MIDI input device) + or "LIST MIDI_INPUT_DEVICES" (Getting all created MIDI input device list) command, <port> by the MIDI port number, <key> by the name of the parameter to change and <value> by the new value for this parameter. @@ -3162,16 +3292,18 @@
--
TOC 6.4. Configuring sampler channels
++
TOC 6.4. +Configuring sampler channels
The following commands describe how to add and remove sampler channels, associate a sampler channel with a sampler engine, load instruments and connect sampler channels to MIDI and audio devices.
--
TOC 6.4.1. Loading an instrument
++
TOC 6.4.1. +Loading an instrument
An instrument file can be loaded and assigned to a sampler channel by one of the following commands:
@@ -3193,7 +3325,7 @@ is that the regular command returns OK only after the instrument has been fully loaded and the channel is ready to be used while NON_MODAL version returns immediately and a background process is launched to load the instrument - on the channel. The GET CHANNEL INFO (Getting sampler channel information) + on the channel. The GET CHANNEL INFO (Getting sampler channel information) command can be used to obtain loading progress from INSTRUMENT_STATUS field. LOAD command will perform sanity checks such as making sure that the file could be read and it is of a proper format @@ -3247,8 +3379,9 @@
--
TOC 6.4.2. Loading a sampler engine
++
TOC 6.4.2. +Loading a sampler engine
A sampler engine type can be associated to a specific sampler channel by the following command: @@ -3262,10 +3395,10 @@
Where <engine-name> is an engine name as obtained by the - "LIST AVAILABLE_ENGINES" (Getting all available engines) command and <sampler-channel> + "LIST AVAILABLE_ENGINES" (Getting all available engines) command and <sampler-channel> the sampler channel as returned by the - "ADD CHANNEL" (Adding a new sampler channel) or - "LIST CHANNELS" (Getting all created sampler channel list) command where + "ADD CHANNEL" (Adding a new sampler channel) or + "LIST CHANNELS" (Getting all created sampler channel list) command where the engine type should be assigned to. This command should be issued after adding a new sampler channel and before any other control commands on the new sampler channel. It can also be used to change @@ -3321,8 +3454,9 @@
--
TOC 6.4.3. Getting all created sampler channel count
++
TOC 6.4.3. +Getting all created sampler channel count
The number of sampler channels can change on runtime. To get the current amount of sampler channels, the front-end can send the @@ -3359,8 +3493,9 @@
--
TOC 6.4.4. Getting all created sampler channel list
++
TOC 6.4.4. +Getting all created sampler channel list
The number of sampler channels can change on runtime. To get the current list of sampler channels, the front-end can send the @@ -3398,8 +3533,9 @@
--
TOC 6.4.5. Adding a new sampler channel
++
TOC 6.4.5. +Adding a new sampler channel
A new sampler channel can be added to the end of the sampler channel list by sending the following command: @@ -3472,8 +3608,9 @@
--
TOC 6.4.6. Removing a sampler channel
++
TOC 6.4.6. +Removing a sampler channel
A sampler channel can be removed by sending the following command:
@@ -3487,8 +3624,8 @@Where <sampler-channel> should be replaced by the number of the sampler channel as given by the - "ADD CHANNEL" (Adding a new sampler channel) - or "LIST CHANNELS" (Getting all created sampler channel list) + "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command. The channel numbers of all subsequent sampler channels remain the same.
@@ -3538,8 +3675,9 @@
--
TOC 6.4.7. Getting amount of available engines
++
TOC 6.4.7. +Getting amount of available engines
The front-end can ask for the number of available engines by sending the following command:
@@ -3574,8 +3712,9 @@
--
TOC 6.4.8. Getting all available engines
++
TOC 6.4.8. +Getting all available engines
The front-end can ask for a list of all available engines by sending the following command:
@@ -3613,8 +3752,9 @@
--
TOC 6.4.9. Getting information about an engine
++
TOC 6.4.9. +Getting information about an engine
The front-end can ask for information about a specific engine by sending the following command: @@ -3628,7 +3768,7 @@
Where <engine-name> is an engine name as obtained by the - "LIST AVAILABLE_ENGINES" (Getting all available engines) command. + "LIST AVAILABLE_ENGINES" (Getting all available engines) command.
Possible Answers:
@@ -3685,8 +3825,9 @@
--
TOC 6.4.10. Getting sampler channel information
++
TOC 6.4.10. +Getting sampler channel information
The front-end can ask for the current settings of a sampler channel by sending the following command: @@ -3700,8 +3841,8 @@
Where <sampler-channel> is the sampler channel number the front-end is interested in - as returned by the "ADD CHANNEL" (Adding a new sampler channel) - or "LIST CHANNELS" (Getting all created sampler channel list) command. + as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command.
Possible Answers:
@@ -3829,7 +3970,7 @@@@ -3856,6 +3997,17 @@optionally dotted number for the channel volume factor - (where a value < 1.0 means attenuation and a value > + (where a value < 1.0 means attenuation and a value > 1.0 means amplification)
MIDI_INSTRUMENT_MAP - +
+++ +Determines to which MIDI instrument map this sampler + channel is assigned to. Read chapter + "SET CHANNEL MIDI_INSTRUMENT_MAP" (Assigning a MIDI instrument map to a sampler channel) + for a list of possible values. +
+
"MIDI_INPUT_CHANNEL: 5"
+"VOLUME: 1.0" +
+"MUTE: false" +
+"SOLO: false" +
+"MIDI_INSTRUMENT_MAP: NONE" +
"."
TOC |
TOC |
The front-end can ask for the current number of active voices on a sampler channel by sending the following command: @@ -3916,8 +4077,8 @@
Where <sampler-channel> is the sampler channel number the front-end is interested in - as returned by the "ADD CHANNEL" (Adding a new sampler channel) - or "LIST CHANNELS" (Getting all created sampler channel list) command. + as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command.
Possible Answers:
@@ -3941,8 +4102,9 @@TOC |
TOC |
The front-end can ask for the current number of active disk streams on a sampler channel by sending the following command: @@ -3956,8 +4118,8 @@
Where <sampler-channel> is the sampler channel number the front-end is interested in - as returned by the "ADD CHANNEL" (Adding a new sampler channel) - or "LIST CHANNELS" (Getting all created sampler channel list) command. + as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command.
Possible Answers:
@@ -3983,8 +4145,9 @@TOC |
TOC |
The front-end can ask for the current fill state of all disk streams on a sampler channel by sending the following command: @@ -4009,8 +4172,8 @@
to get the fill state in percent, where <sampler-channel> is the sampler channel number the front-end is interested in - as returned by the "ADD CHANNEL" (Adding a new sampler channel) - or "LIST CHANNELS" (Getting all created sampler channel list) command. + as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command.
Possible Answers:
@@ -4060,8 +4223,9 @@TOC |
TOC |
The front-end can set the audio output device on a specific sampler channel by sending the following command: @@ -4075,11 +4239,11 @@
Where <sampler-channel> is the respective sampler channel - number as returned by the "ADD CHANNEL" (Adding a new sampler channel) - or "LIST CHANNELS" (Getting all created sampler channel list) command and + number as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command and <audio-device-id> is the numerical ID of the audio output device as given by the - "CREATE AUDIO_OUTPUT_DEVICE" (Creating an audio output device) - or "LIST AUDIO_OUTPUT_DEVICES" (Getting all created audio output device list) + "CREATE AUDIO_OUTPUT_DEVICE" (Creating an audio output device) + or "LIST AUDIO_OUTPUT_DEVICES" (Getting all created audio output device list) command.
Possible Answers: @@ -4126,9 +4290,10 @@
-
TOC |
TOC |
DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
@@ -4191,8 +4356,9 @@TOC |
TOC |
The front-end can alter the audio output channel on a specific sampler channel by sending the following command: @@ -4206,8 +4372,8 @@
Where <sampler-chan> is the sampler channel number - as returned by the "ADD CHANNEL" (Adding a new sampler channel) - or "LIST CHANNELS" (Getting all created sampler channel list) command, <audio-out> is the + as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command, <audio-out> is the numerical ID of the sampler channel's audio output channel which should be rerouted and <audio-in> is the numerical ID of the audio channel of the selected audio output device where <audio-out> should be routed to. @@ -4257,8 +4423,9 @@
TOC |
TOC |
The front-end can set the MIDI input device on a specific sampler channel by sending the following command: @@ -4272,11 +4439,11 @@
Where <sampler-channel> is the sampler channel number - as returned by the "ADD CHANNEL" (Adding a new sampler channel) - or "LIST CHANNELS" (Getting all created sampler channel list) command + as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command and <midi-device-id> is the numerical ID of the MIDI input device as returned by the - "CREATE MIDI_INPUT_DEVICE" (Creating a MIDI input device) - or "LIST MIDI_INPUT_DEVICES" (Getting all created MIDI input device list) command. + "CREATE MIDI_INPUT_DEVICE" (Creating a MIDI input device) + or "LIST MIDI_INPUT_DEVICES" (Getting all created MIDI input device list) command.
Possible Answers:
@@ -4323,8 +4490,9 @@TOC |
TOC |
DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
@@ -4387,8 +4555,9 @@TOC |
TOC |
The front-end can alter the MIDI input port on a specific sampler channel by sending the following command: @@ -4450,8 +4619,9 @@
TOC |
TOC |
The front-end can alter the MIDI channel a sampler channel should listen to by sending the following command: @@ -4513,8 +4683,9 @@
TOC |
TOC |
The front-end can alter the volume of a sampler channel by sending the following command: @@ -4577,8 +4748,9 @@
TOC |
TOC |
The front-end can mute/unmute a specific sampler channel by sending the following command: @@ -4592,8 +4764,8 @@
Where <sampler-channel> is the respective sampler channel - number as returned by the "ADD CHANNEL" (Adding a new sampler channel) - or "LIST CHANNELS" (Getting all created sampler channel list) command and + number as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command and <mute> should be replaced either by "1" to mute the channel or "0" to unmute the channel.
@@ -4642,8 +4814,9 @@TOC |
TOC |
The front-end can solo/unsolo a specific sampler channel by sending the following command: @@ -4657,8 +4830,8 @@
Where <sampler-channel> is the respective sampler channel - number as returned by the "ADD CHANNEL" (Adding a new sampler channel) - or "LIST CHANNELS" (Getting all created sampler channel list) command and + number as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command and <solo> should be replaced either by "1" to solo the channel or "0" to unsolo the channel.
@@ -4706,9 +4879,753 @@+
TOC |
The front-end can assign a MIDI instrument map to a specific sampler channel + by sending the following command: +
++
++SET CHANNEL MIDI_INSTRUMENT_MAP <sampler-channel> <map> +
+
+ +
+Where <sampler-channel> is the respective sampler channel + number as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command and + <map> can have the following possibilites: +
++
++"NONE" - +
+++ + +This is the default setting. In this case + the sampler channel is not assigned any MIDI + instrument map and thus will ignore all MIDI + program change messages. +
+"DEFAULT" - +
+++ + +The sampler channel will always use the + default MIDI instrument map to handle MIDI + program change messages. +
+numeric ID - +
+++ + +You can assign a specific MIDI instrument map + by replacing <map> with the respective numeric + ID of the MIDI instrument map as returned by the + "LIST MIDI_INSTRUMENT_MAPS" (Getting all created MIDI instrument maps) + command. Once that map will be deleted, the sampler + channel would fall back to "NONE". +
+
+ +
+Read chapter "MIDI Instrument Mapping" (MIDI Instrument Mapping) + for details regarding MIDI instrument mapping. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case it failed, providing an appropriate error code and error message +
+
+ +
+Examples: +
++
+++
+
+ +
+TOC |
The front-end can create an additional effect send on a specific sampler channel + by sending the following command: +
++
++CREATE FX_SEND <sampler-channel> <midi-ctrl> [<name>] +
+
+ +
+Where <sampler-channel> is the respective sampler channel + number as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command, that is the + sampler channel on which the effect send should be created on, <midi-ctrl> + is a number between 0..127 defining the MIDI controller which can alter the + effect send level and <name> is an optional argument defining a name + for the effect send entity. The name does not have to be unique. +
+By default, that is as initial routing, the effect send's audio channels + are automatically routed to the last audio channels of the sampler channel's + audio output device, that way you can i.e. first increase the amount of audio + channels on the audio output device for having dedicated effect send output + channels and when "CREATE FX_SEND" is called, those channels will automatically + be picked. You can alter the destination channels however with + "SET FX_SEND AUDIO_OUTPUT_CHANNEL" (Altering effect send's audio routing). + +
+Note: Create effect sends on a sampler channel only when needed, because having effect + sends on a sampler channel will decrease runtime performance, because for implementing channel + effect sends, separate (sampler channel local) audio buffers are needed to render and mix + the voices and route the audio signal afterwards to the master outputs and effect send + outputs (along with their respective effect send levels). A sampler channel without effect + sends however can mix its voices directly into the audio output devices's audio buffers + and is thus faster. + +
+Possible Answers: +
++
++"OK[<fx-send-id>]" - +
+++ + +in case a new effect send could be added to the + sampler channel, where <fx-send-id> reflects the + unique ID of the newly created effect send entity +
+"ERR:<error-code>:<error-message>" - +
+++ + +when a new effect send could not be added, i.e. + due to invalid parameters +
+
+ +
+Examples: +
++
++C: "CREATE FX_SEND 0 91 'Reverb Send'" +
+S: "OK[0]" +
+
+ +
++
++C: "CREATE FX_SEND 0 93" +
+S: "OK[1]" +
+
+ +
+TOC |
The front-end can remove an existing effect send on a specific sampler channel + by sending the following command: +
++
++DESTROY FX_SEND <sampler-channel> <fx-send-id> +
+
+ +
+Where <sampler-channel> is the respective sampler channel + number as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command, that is the + sampler channel from which the effect send should be removed from and + <fx-send-id> is the respective effect send number as returned by the + "CREATE FX_SEND" (Adding an effect send to a sampler channel) + or "LIST FX_SENDS" (Listing all effect sends on a sampler channel) command. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case it failed, providing an appropriate error code and + error message +
+
+ +
+Example: +
++
++C: "DESTROY FX_SEND 0 0" +
+S: "OK" +
+
+ +
+TOC |
The front-end can ask for the amount of effect sends on a specific sampler channel + by sending the following command: +
++
++GET FX_SENDS <sampler-channel> +
+
+ +
+Where <sampler-channel> is the respective sampler channel + number as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command. +
+Possible Answers: +
++
++The sampler will answer by returning the number of effect + sends on the given sampler channel. +
+
+ +
+Example: +
++
++C: "GET FX_SENDS 0" +
+S: "2" +
+
+ +
+TOC |
The front-end can ask for a list of effect sends on a specific sampler channel + by sending the following command: +
++
++LIST FX_SENDS <sampler-channel> +
+
+ +
+Where <sampler-channel> is the respective sampler channel + number as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command. +
+Possible Answers: +
++
++The sampler will answer by returning a comma separated list + with all effect sends' numerical IDs on the given sampler + channel. +
+
+ +
+Examples: +
++
++C: "LIST FX_SENDS 0" +
+S: "0,1" +
+
+ +
++
++C: "LIST FX_SENDS 1" +
+S: "" +
+
+ +
+TOC |
The front-end can ask for the current settings of an effect send entity + by sending the following command: +
++
++GET FX_SEND INFO <sampler-channel> <fx-send-id> +
+
+ +
+Where <sampler-channel> is the sampler channel number + as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command and + <fx-send-id> reflects the numerical ID of the effect send entity + as returned by the "CREATE FX_SEND" (Adding an effect send to a sampler channel) + or "LIST FX_SENDS" (Listing all effect sends on a sampler channel) command. + +
+Possible Answers: +
++
++The sampler will answer by sending a <CRLF> separated list. + Each answer line begins with the settings category name + followed by a colon and then a space character <SP> and finally + the info character string to that setting category. At the + moment the following categories are defined: +
++
+++ + +NAME - +
+++ + +name of the effect send entity +
+MIDI_CONTROLLER - +
+++ + +a value between 0 and 127 reflecting the MIDI controller + which is able to modify the effect send's send level +
+LEVEL - +
+++ + +optionally dotted number reflecting the effect send's + current send level (where a value < 1.0 means attenuation + and a value > 1.0 means amplification) +
+AUDIO_OUTPUT_ROUTING - +
+++ + +comma separated list which reflects to which audio + channel of the selected audio output device each + effect send output channel is routed to, e.g. "0,3" would + mean the effect send's output channel 0 is routed to channel + 0 of the audio output device and the effect send's output + channel 1 is routed to the channel 3 of the audio + output device (see + "SET FX_SEND AUDIO_OUTPUT_CHANNEL" (Altering effect send's audio routing) + for details) +
+
+ +
+The mentioned fields above don't have to be in particular order. +
+Example: +
++
++C: "GET FX_SEND INFO 0 0" +
+S: "NAME: Reverb Send" +
+"MIDI_CONTROLLER: 91" +
+"LEVEL: 0.3" +
+"AUDIO_OUTPUT_ROUTING: 2,3" +
+"." +
+
+ +
+TOC |
The front-end can alter the current name of an effect + send entity by sending the following command: +
++
++SET FX_SEND NAME <sampler-chan> <fx-send-id> <name> +
+
+ +
+Where <sampler-chan> is the sampler channel number + as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command, + <fx-send-id> reflects the numerical ID of the effect send entity + as returned by the "CREATE FX_SEND" (Adding an effect send to a sampler channel) + or "LIST FX_SENDS" (Listing all effect sends on a sampler channel) command and + <name> is the new name of the effect send entity, which + does not have to be unique. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case it failed, providing an appropriate error code and error message +
+
+ +
+Example: +
++
++C: "SET FX_SEND NAME 0 0 'Fx Send 1'" +
+S: "OK" +
+
+ +
+TOC |
The front-end can alter the destination of an effect send's audio channel on a specific + sampler channel by sending the following command: +
++
++SET FX_SEND AUDIO_OUTPUT_CHANNEL <sampler-chan> <fx-send-id> <audio-src> <audio-dst> +
+
+ +
+Where <sampler-chan> is the sampler channel number + as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command, + <fx-send-id> reflects the numerical ID of the effect send entity + as returned by the "CREATE FX_SEND" (Adding an effect send to a sampler channel) + or "LIST FX_SENDS" (Listing all effect sends on a sampler channel) command, + <audio-src> is the numerical ID of the effect send's audio channel + which should be rerouted and <audio-dst> is the numerical ID of + the audio channel of the selected audio output device where <audio-src> + should be routed to. +
+Note that effect sends can only route audio to the same audio output + device as assigned to the effect send's sampler channel. Also note that an + effect send entity does always have exactly as much audio channels as its + sampler channel. So if the sampler channel is stereo, the effect send does + have two audio channels as well. Also keep in mind that the amount of audio + channels on a sampler channel might be dependant not only to the deployed + sampler engine on the sampler channel, but also dependant to the instrument + currently loaded. However you can (effectively) turn an i.e. stereo effect + send into a mono one by simply altering its audio routing appropriately. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"WRN:<warning-code>:<warning-message>" - +
+++ + +if audio output channel was set, but there are noteworthy + issue(s) related, providing an appropriate warning code and + warning message +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case it failed, providing an appropriate error code and error message +
+
+ +
+Example: +
++
++C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2" +
+S: "OK" +
+
+ +
+TOC |
The front-end can alter the MIDI controller of an effect + send entity by sending the following command: +
++
++SET FX_SEND MIDI_CONTROLLER <sampler-chan> <fx-send-id> <midi-ctrl> +
+
+ +
+Where <sampler-chan> is the sampler channel number + as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command, + <fx-send-id> reflects the numerical ID of the effect send entity + as returned by the "CREATE FX_SEND" (Adding an effect send to a sampler channel) + or "LIST FX_SENDS" (Listing all effect sends on a sampler channel) command and + <midi-ctrl> reflects the MIDI controller which shall be + able to modify the effect send's send level. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"WRN:<warning-code>:<warning-message>" - +
+++ + +if MIDI controller was set, but there are noteworthy + issue(s) related, providing an appropriate warning code and + warning message +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case it failed, providing an appropriate error code and error message +
+
+ +
+Example: +
++
++C: "SET FX_SEND MIDI_CONTROLLER 0 0 91" +
+S: "OK" +
+
+ +
+TOC |
The front-end can alter the current send level of an effect + send entity by sending the following command: +
++
++SET FX_SEND LEVEL <sampler-chan> <fx-send-id> <volume> +
+
+ +
+Where <sampler-chan> is the sampler channel number + as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command, + <fx-send-id> reflects the numerical ID of the effect send entity + as returned by the "CREATE FX_SEND" (Adding an effect send to a sampler channel) + or "LIST FX_SENDS" (Listing all effect sends on a sampler channel) command and + <volume> is an optionally dotted positive number (a value + smaller than 1.0 means attenuation, whereas a value greater than + 1.0 means amplification) reflecting the new send level. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"WRN:<warning-code>:<warning-message>" - +
+++ + +if new send level was set, but there are noteworthy + issue(s) related, providing an appropriate warning code and + warning message +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case it failed, providing an appropriate error code and error message +
+
+ +
+Example: +
++
++C: "SET FX_SEND LEVEL 0 0 0.15" +
+S: "OK" +
+
+ +
TOC |
TOC |
The front-end can reset a particular sampler channel by sending the following command:
@@ -4772,14 +5689,16 @@TOC |
TOC |
The following commands are used to control the connection to LinuxSampler.
TOC |
TOC |
The front-end can register itself to the LinuxSampler application to be informed about noteworthy events by sending this command: @@ -4841,8 +5760,9 @@
TOC |
TOC |
The front-end can unregister itself if it doesn't want to receive event messages anymore by sending the following command: @@ -4904,8 +5824,9 @@
TOC |
TOC |
To enable or disable back sending of commands to the client the following command can be used:
@@ -4960,8 +5881,9 @@TOC |
TOC |
The client can close its network connection to LinuxSampler by sending the following command:
@@ -4977,14 +5899,16 @@ LinuxSampler than really useful for a front-end implementation.TOC |
TOC |
The following commands have global impact on the sampler.
TOC |
TOC |
The front-end can ask for the current number of active voices on the sampler by sending the following command: @@ -5009,8 +5933,9 @@
TOC |
TOC |
The front-end can ask for the maximum number of active voices by sending the following command: @@ -5035,8 +5960,9 @@
TOC |
TOC |
The front-end can reset the whole sampler by sending the following command:
@@ -5075,8 +6001,9 @@TOC |
TOC |
The client can ask for general informations about the LinuxSampler instance by sending the following command: @@ -5124,7 +6051,7 @@
@@ -5138,12 +6065,1114 @@version of the LSCP specification the sampler - complies with (see Section 2 (Versioning of this specification) for details) + complies with (see Section 2 (Versioning of this specification) for details)
The mentioned fields above don't have to be in particular order. Other fields might be added in future.
+TOC |
The client can ask for the current global sampler-wide volume + attenuation by sending the following command: +
++
++GET VOLUME +
+
+ +
+Possible Answers: +
++
++The sampler will always answer by returning the optional + dotted floating point coefficient, reflecting the current + global volume attenuation. + +
+
+ +
+Note: it is up to the respective sampler engine whether to obey + that global volume parameter or not, but in general all engines SHOULD + use this parameter. +
+TOC |
The client can alter the current global sampler-wide volume + attenuation by sending the following command: +
++
++SET VOLUME <volume> +
+
+ +
+Where <volume> should be replaced by the optional dotted + floating point value, reflecting the new global volume parameter. + This value might usually be in the range between 0.0 and 1.0, that + is for attenuating the overall volume. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"WRN:<warning-code>:<warning-message>" - +
+++ + +if the global volume was set, but there are noteworthy + issue(s) related, providing an appropriate warning code and + warning message +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case it failed, providing an appropriate error code and error message +
+
+ +
+TOC |
The MIDI protocol provides a way to switch between instruments + by sending so called MIDI bank select and MIDI program change + messages which are essentially just numbers. The following commands + allow to actually map arbitrary MIDI bank select / program change + numbers with real instruments. +
+The sampler allows to manage an arbitrary amount of MIDI + instrument maps which define which instrument to load on + which MIDI program change message. +
+By default, that is when the sampler is launched, there is no + map, thus the sampler will simply ignore all program change + messages. The front-end has to explicitly create at least one + map, add entries to the map and tell the respective sampler + channel(s) which MIDI instrument map to use, so the sampler + knows how to react on a given program change message on the + respective sampler channel, that is by switching to the + respectively defined engine type and loading the respective + instrument. See command + "SET CHANNEL MIDI_INSTRUMENT_MAP" (Assigning a MIDI instrument map to a sampler channel) + for how to assign a MIDI instrument map to a sampler channel. +
+Also note per MIDI specification a bank select message does not + cause to switch to another instrument. Instead when receiving a + bank select message the bank value will be stored and a subsequent + program change message (which may occur at any time) will finally + cause the sampler to switch to the respective instrument as + reflected by the current MIDI instrument map. +
+TOC |
The front-end can add a new MIDI instrument map by sending + the following command: +
++
++ADD MIDI_INSTRUMENT_MAP [<name>] +
+
+ +
+Where <name> is an optional argument allowing to + assign a custom name to the new map. MIDI instrument Map + names do not have to be unique. +
+Possible Answers: +
++
++"OK[<map>]" - +
+++ + +in case a new MIDI instrument map could + be added, where <map> reflects the + unique ID of the newly created MIDI + instrument map +
+"ERR:<error-code>:<error-message>" - +
+++ + +when a new map could not be created, which + might never occur in practice +
+
+ +
+Examples: +
++
++C: "ADD MIDI_INSTRUMENT_MAP 'Standard Map'" +
+S: "OK[0]" +
+
+ +
++
++C: "ADD MIDI_INSTRUMENT_MAP 'Standard Drumkit'" +
+S: "OK[1]" +
+
+ +
++
++C: "ADD MIDI_INSTRUMENT_MAP" +
+S: "OK[5]" +
+
+ +
+TOC |
The front-end can delete a particular MIDI instrument map + by sending the following command: +
++
++REMOVE MIDI_INSTRUMENT_MAP <map> +
+
+ +
+Where <map> reflects the unique ID of the map to delete + as returned by the "LIST MIDI_INSTRUMENT_MAPS" (Getting all created MIDI instrument maps) + command. +
+The front-end can delete all MIDI instrument maps by + sending the following command: +
++
++REMOVE MIDI_INSTRUMENT_MAP ALL +
+
+ +
+Possible Answers: +
++
++"OK" - +
+++ + +in case the map(s) could be deleted +
+"ERR:<error-code>:<error-message>" - +
+++ + +when the given map does not exist +
+
+ +
+Examples: +
++
++C: "REMOVE MIDI_INSTRUMENT_MAP 0" +
+S: "OK" +
+
+ +
++
++C: "REMOVE MIDI_INSTRUMENT_MAP ALL" +
+S: "OK" +
+
+ +
+TOC |
The front-end can retrieve the current amount of MIDI + instrument maps by sending the following command: +
++
++GET MIDI_INSTRUMENT_MAPS +
+
+ +
+Possible Answers: +
++
++The sampler will answer by returning the current + number of MIDI instrument maps. +
+
+ +
+Example: +
++
++C: "GET MIDI_INSTRUMENT_MAPS" +
+S: "2" +
+
+ +
+TOC |
The number of MIDI instrument maps can change on runtime. To get the + current list of MIDI instrument maps, the front-end can send the + following command: +
++
++LIST MIDI_INSTRUMENT_MAPS +
+
+ +
+Possible Answers: +
++
++The sampler will answer by returning a comma separated list + with all MIDI instrument maps' numerical IDs. +
+
+ +
+Example: +
++
++C: "LIST MIDI_INSTRUMENT_MAPS" +
+S: "0,1,5,12" +
+
+ +
+TOC |
The front-end can ask for the current settings of a MIDI + instrument map by sending the following command: +
++
++GET MIDI_INSTRUMENT_MAP INFO <map> +
+
+ +
+Where <map> is the numerical ID of the map the + front-end is interested in as returned by the + "LIST MIDI_INSTRUMENT_MAPS" (Getting all created MIDI instrument maps) + command. +
+Possible Answers: +
++
++LinuxSampler will answer by sending a <CRLF> separated list. + Each answer line begins with the settings category name + followed by a colon and then a space character <SP> and finally + the info character string to that setting category. At the + moment the following categories are defined: +
++
+++ + +NAME - +
+++ + +custom name of the given map, + which does not have to be unique +
+DEFAULT - +
+++ + +either true or false, + defines whether this map is the default map +
+
+ +
+The mentioned fields above don't have to be in particular order. +
+Example: +
++
++C: "GET MIDI_INSTRUMENT_MAP INFO 0" +
+S: "NAME: Standard Map" +
+"DEFAULT: true" +
+"." +
+
+ +
+TOC |
The front-end can alter the custom name of a MIDI + instrument map by sending the following command: +
++
++SET MIDI_INSTRUMENT_MAP NAME <map> <name> +
+
+ +
+Where <map> is the numerical ID of the map and + <name> the new custom name of the map, which does not + have to be unique. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case the given map does not exist +
+
+ +
+Example: +
++
++C: "SET MIDI_INSTRUMENT_MAP NAME 0 'Foo instruments'" +
+S: "OK" +
+
+ +
+TOC |
The front-end can create a new or replace an existing entry + in a sampler's MIDI instrument map by sending the following + command: +
++
++MAP MIDI_INSTRUMENT [NON_MODAL] <map> + <midi_bank> <midi_prog> <engine_name> + <filename> <instrument_index> <volume_value> + [<instr_load_mode>] [<name>] +
+
+ +
+Where <map> is the numeric ID of the map to alter, + <midi_bank> is an integer value between + 0..16383 reflecting the MIDI bank select index, + <midi_prog> an + integer value between 0..127 reflecting the MIDI program change + index, <engine_name> a sampler engine name as returned by + the "LIST AVAILABLE_ENGINES" (Getting all available engines) + command (not encapsulated into apostrophes), <filename> the name + of the instrument's file to be deployed (encapsulated into apostrophes), + <instrument_index> the index (integer value) of the instrument + within the given file, <volume_value> reflects the master + volume of the instrument as optionally dotted number (where a + value < 1.0 means attenuation and a value > 1.0 means + amplification). This parameter easily allows to adjust the + volume of all intruments within a custom instrument map + without having to adjust their instrument files. The + OPTIONAL <instr_load_mode> argument defines the life + time of the instrument, that is when the instrument should + be loaded, when freed and has exactly the following + possibilities: +
++
++"ON_DEMAND" - +
+++ + +The instrument will be loaded when needed, + that is when demanded by at least one sampler + channel. It will immediately be freed from memory + when not needed by any sampler channel anymore. +
+"ON_DEMAND_HOLD" - +
+++ + +The instrument will be loaded when needed, + that is when demanded by at least one sampler + channel. It will be kept in memory even when + not needed by any sampler channel anymore. + Instruments with this mode are only freed + when the sampler is reset or all mapping + entries with this mode (and respective + instrument) are explicitly changed to + "ON_DEMAND" and no sampler channel is using + the instrument anymore. +
+"PERSISTENT" - +
+++ + +The instrument will immediately be loaded + into memory when this mapping + command is sent and the instrument is kept all + the time. Instruments with this mode are + only freed when the sampler is reset or all + mapping entries with this mode (and + respective instrument) are explicitly + changed to "ON_DEMAND" and no sampler + channel is using the instrument anymore. +
+not supplied - +
+++ + +In case there is no <instr_load_mode> + argument given, it will be up to the + InstrumentManager to decide which mode to use. + Usually it will use "ON_DEMAND" if an entry + for the given instrument does not exist in + the InstrumentManager's list yet, otherwise + if an entry already exists, it will simply + stick with the mode currently reflected by + the already existing entry, that is it will + not change the mode. +
+
+ +
++ The <instr_load_mode> argument thus allows to define an + appropriate strategy (low memory consumption vs. fast + instrument switching) for each instrument individually. Note, the + following restrictions apply to this argument: "ON_DEMAND_HOLD" and + "PERSISTENT" have to be supported by the respective sampler engine + (which is technically the case when the engine provides an + InstrumentManager for its format). If this is not the case the + argument will automatically fall back to the default value + "ON_DEMAND". Also the load mode of one instrument may + automatically change the laod mode of other instrument(s), i.e. + because the instruments are part of the same file and the + engine does not allow a way to manage load modes for them + individually. Due to this, in case the frontend shows the + load modes of entries, the frontend should retrieve the actual + mode by i.e. sending + "GET MIDI_INSTRUMENT INFO" (Get current settings of MIDI instrument map entry) + command(s). Finally the OPTIONAL <name> argument allows to + set a custom name (encapsulated into apostrophes) for the mapping + entry, useful for frontends for displaying an appropriate name for + mapped instruments (using + "GET MIDI_INSTRUMENT INFO" (Get current settings of MIDI instrument map entry)). + +
++ By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is + completely established in the sampler. The OPTIONAL "NON_MODAL" argument + however causes the respective "MAP MIDI_INSTRUMENT" command to return + immediately, that is to let the sampler establish the mapping in the + background. So this argument might be especially useful for mappings with + a "PERSISTENT" type, because these have to load the respective instruments + immediately and might thus block for a very long time. It is recommended + however to use the OPTIONAL "NON_MODAL" argument only if really necessary, + because it has the following drawbacks: as "NON_MODAL" instructions return + immediately, they may not necessarily return an error i.e. when the given + instrument file turns out to be corrupt, beside that subsequent commands + in a LSCP instruction sequence might fail, because mandatory mappings are + not yet completed. + +
+Possible Answers: +
++
++"OK" - +
+++ + +usually +
+"ERR:<error-code>:<error-message>" - +
+++ + +when the given map or engine does not exist or a value + is out of range +
+
+ +
+Examples: +
++
++C: "MAP MIDI_INSTRUMENT 0 3 0 gig '/usr/share/Steinway D.gig' 0 0.8 PERSISTENT" +
+S: "OK" +
+
+ +
++
++C: "MAP MIDI_INSTRUMENT 0 4 50 gig '/home/john/foostrings.gig' 7 1.0" +
+S: "OK" +
+
+ +
++
++C: "MAP MIDI_INSTRUMENT 0 0 0 gig '/usr/share/piano.gig' 0 1.0 'Normal Piano'" +
+S: "OK" +
+C: "MAP MIDI_INSTRUMENT 0 1 0 gig '/usr/share/piano.gig' 0 0.25 'Silent Piano'" +
+S: "OK" +
+
+ +
++
++C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'" +
+S: "OK" +
+
+ +
+TOC |
The front-end can query the amount of currently existing + entries in a MIDI instrument map by sending the following + command: +
++
++GET MIDI_INSTRUMENTS <map> +
+
+ +
+The front-end can query the amount of currently existing + entries in all MIDI instrument maps by sending the following + command: +
++
++GET MIDI_INSTRUMENTS ALL +
+
+ +
+Possible Answers: +
++
++The sampler will answer by sending the current number of + entries in the MIDI instrument map(s). +
+
+ +
+Example: +
++
++C: "GET MIDI_INSTRUMENTS 0" +
+S: "234" +
+
+ +
++
++C: "GET MIDI_INSTRUMENTS ALL" +
+S: "954" +
+
+ +
+TOC |
The front-end can query a list of all currently existing + entries in a certain MIDI instrument map by sending the following + command: +
++
++LIST MIDI_INSTRUMENTS <map> +
+
+ +
+Where <map> is the numeric ID of the MIDI instrument map. +
+The front-end can query a list of all currently existing + entries of all MIDI instrument maps by sending the following + command: +
++
++LIST MIDI_INSTRUMENTS ALL +
+
+ +
+Possible Answers: +
++
++The sampler will answer by sending a comma separated + list of map ID - MIDI bank - MIDI program triples, where + each triple is encapsulated into curly braces. The + list is returned in one single line. Each triple + just reflects the key of the respective map entry, + thus subsequent + "GET MIDI_INSTRUMENT INFO" (Get current settings of MIDI instrument map entry) + command(s) are necessary to retrieve detailed informations + about each entry. +
+
+ +
+Example: +
++
++C: "LIST MIDI_INSTRUMENTS 0" +
+S: "{0,0,0},{0,0,1},{0,0,3},{0,1,4},{1,127,127}" +
+
+ +
+TOC |
The front-end can delete an entry from a MIDI instrument + map by sending the following command: +
++
++UNMAP MIDI_INSTRUMENT <map> <midi_bank> <midi_prog> +
+
+ +
++ Where <map> is the numeric ID of the MIDI instrument map, + <midi_bank> is an integer value between 0..16383 + reflecting the MIDI bank value and + <midi_prog> an integer value between + 0..127 reflecting the MIDI program value of the map's entrie's key + index triple. + +
+Possible Answers: +
++
++"OK" - +
+++ + +usually +
+"ERR:<error-code>:<error-message>" - +
+++ + +when index out of bounds +
+
+ +
+Example: +
++
++C: "UNMAP MIDI_INSTRUMENT 0 2 127" +
+S: "OK" +
+
+ +
+TOC |
The front-end can retrieve the current settings of a certain + instrument map entry by sending the following command: +
++
++GET MIDI_INSTRUMENT INFO <map> <midi_bank> <midi_prog> +
+
+ +
++ Where <map> is the numeric ID of the MIDI instrument map, + <midi_bank> is an integer value between 0..16383 + reflecting the MIDI bank value, <midi_bank> + and <midi_prog> an integer value between + 0..127 reflecting the MIDI program value of the map's entrie's key + index triple. + +
+Possible Answers: +
++
++LinuxSampler will answer by sending a <CRLF> + separated list. Each answer line begins with the + information category name followed by a colon and then + a space character <SP> and finally the info + character string to that info category. At the moment + the following categories are defined: +
+"NAME" - +
+++ + +Name for this MIDI instrument map entry (if defined). + This name shall be used by frontends for displaying a + name for this mapped instrument. It can be set and + changed with the + "MAP MIDI_INSTRUMENT" (Create or replace a MIDI instrument map entry) + command and does not have to be unique. +
+"ENGINE_NAME" - +
+++ + +Name of the engine to be deployed for this + instrument. +
+"INSTRUMENT_FILE" - +
+++ + +File name of the instrument. +
+"INSTRUMENT_NR" - +
+++ + +Index of the instrument within the file. +
+"INSTRUMENT_NAME" - +
+++ + +Name of the loaded instrument as reflected by its file. + In contrast to the "NAME" field, the "INSTRUMENT_NAME" field + cannot be changed. +
+"LOAD_MODE" - +
+++ + +Life time of instrument + (see "MAP MIDI_INSTRUMENT" (Create or replace a MIDI instrument map entry) for details about this setting). +
+"VOLUME" - +
+++ + +master volume of the instrument as optionally + dotted number (where a value < 1.0 means attenuation + and a value > 1.0 means amplification) +
+The mentioned fields above don't have to be in particular order. +
+
+ +
+Example: +
++
++C: "GET MIDI_INSTRUMENT INFO 1 45 120" +
+S: "NAME: Drums for Foo Song" +
+"ENGINE_NAME: GigEngine" +
+"INSTRUMENT_FILE: /usr/share/joesdrumkit.gig" +
+"INSTRUMENT_NR: 0" +
+"INSTRUMENT_NAME: Joe's Drumkit" +
+"LOAD_MODE: PERSISTENT" +
+"VOLUME: 1.0" +
+"." +
+
+ +
+TOC |
The front-end can clear a whole MIDI instrument map, that + is delete all its entries by sending the following command: +
++
++CLEAR MIDI_INSTRUMENTS <map> +
+
+ +
+Where <map> is the numeric ID of the map to clear. +
+The front-end can clear all MIDI instrument maps, that + is delete all entries of all maps by sending the following + command: +
++
++CLEAR MIDI_INSTRUMENTS ALL +
+
+ +
+The command "CLEAR MIDI_INSTRUMENTS ALL" does not delete the + maps, only their entries, thus the map's settings like + custom name will be preservevd. +
+Possible Answers: +
++
++"OK" - +
+++ + +always +
+
+ +
+Examples: +
++
++C: "CLEAR MIDI_INSTRUMENTS 0" +
+S: "OK" +
+
+ +
++
++C: "CLEAR MIDI_INSTRUMENTS ALL" +
+S: "OK" +
+
+ +
TOC |
TOC |
The grammar of the control protocol as descibed in Section 6 (Description for control commands) - is defined below using Backus-Naur Form (BNF as described in [RFC2234] (Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications,” 1997.)) +
The grammar of the control protocol as descibed in Section 6 (Description for control commands) + is defined below using Backus-Naur Form (BNF as described in [RFC2234] (Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications,” 1997.)) where applicable.
@@ -5201,7 +7230,13 @@command =
-ADD SP CHANNEL +
ADD SP add_instruction + +
+/ MAP SP map_instruction + +
+/ UNMAP SP unmap_instruction
/ GET SP get_instruction @@ -5219,7 +7254,7 @@
/ LOAD SP load_instruction
-/ REMOVE SP CHANNEL SP sampler_channel +
/ REMOVE SP remove_instruction
/ SET SP set_instruction @@ -5234,7 +7269,10 @@
/ SELECT SP text
-/ RESET SP CHANNEL SP sampler_channel +
/ RESET SP reset_instruction + +
+/ CLEAR SP clear_instruction
/ RESET @@ -5246,10 +7284,37 @@
+
add_instruction = +
++CHANNEL + +
+/ MIDI_INSTRUMENT_MAP + +
+/ MIDI_INSTRUMENT_MAP SP map_name + +
+
+ +
subscribe_event =
-CHANNEL_COUNT +
AUDIO_OUTPUT_DEVICE_COUNT + +
+/ AUDIO_OUTPUT_DEVICE_INFO + +
+/ MIDI_INPUT_DEVICE_COUNT + +
+/ MIDI_INPUT_DEVICE_INFO + +
+/ CHANNEL_COUNT
/ VOICE_COUNT @@ -5264,19 +7329,52 @@
/ CHANNEL_INFO
+/ FX_SEND_COUNT + +
+/ FX_SEND_INFO + +
+/ MIDI_INSTRUMENT_MAP_COUNT + +
+/ MIDI_INSTRUMENT_MAP_INFO + +
+/ MIDI_INSTRUMENT_COUNT + +
+/ MIDI_INSTRUMENT_INFO + +
/ MISCELLANEOUS
/ TOTAL_VOICE_COUNT
+/ GLOBAL_INFO + +
unsubscribe_event =
-CHANNEL_COUNT +
AUDIO_OUTPUT_DEVICE_COUNT + +
+/ AUDIO_OUTPUT_DEVICE_INFO + +
+/ MIDI_INPUT_DEVICE_COUNT + +
+/ MIDI_INPUT_DEVICE_INFO + +
+/ CHANNEL_COUNT
/ VOICE_COUNT @@ -5291,12 +7389,75 @@
/ CHANNEL_INFO
+/ FX_SEND_COUNT + +
+/ FX_SEND_INFO + +
+/ MIDI_INSTRUMENT_MAP_COUNT + +
+/ MIDI_INSTRUMENT_MAP_INFO + +
+/ MIDI_INSTRUMENT_COUNT + +
+/ MIDI_INSTRUMENT_INFO + +
/ MISCELLANEOUS
/ TOTAL_VOICE_COUNT
+/ GLOBAL_INFO + +
+
+ +
+map_instruction = +
++MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value + +
+/ MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode + +
+/ MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP entry_name + +
+/ MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode SP entry_name + +
+
+ +
+unmap_instruction = +
++MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog + +
+
+ +
+remove_instruction = +
++CHANNEL SP sampler_channel + +
+/ MIDI_INSTRUMENT_MAP SP midi_map + +
+/ MIDI_INSTRUMENT_MAP SP ALL + +
@@ -5381,6 +7542,30 @@
/ TOTAL_VOICE_COUNT_MAX
+/ MIDI_INSTRUMENTS SP midi_map + +
+/ MIDI_INSTRUMENTS SP ALL + +
+/ MIDI_INSTRUMENT SP INFO SP midi_map SP midi_bank SP midi_prog + +
+/ MIDI_INSTRUMENT_MAPS + +
+/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map + +
+/ FX_SENDS SP sampler_channel + +
+/ FX_SEND SP INFO SP sampler_channel SP fx_send_id + +
+/ VOLUME + +
@@ -5402,9 +7587,27 @@
/ CHANNEL SP set_chan_instruction
+/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name + +
+/ FX_SEND SP NAME SP sampler_channel SP fx_send_id SP fx_send_name + +
+/ FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id SP audio_channel_index SP audio_channel_index + +
+/ FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP midi_ctrl + +
+/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value + +
/ ECHO SP boolean
+/ VOLUME SP volume_value + +
@@ -5423,6 +7626,33 @@
/ MIDI_INPUT_DEVICE SP string
+/ FX_SEND SP sampler_channel SP midi_ctrl + +
+/ FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name + +
++ +
+reset_instruction = +
++CHANNEL SP sampler_channel + +
+
+ +
+clear_instruction = +
++MIDI_INSTRUMENTS SP midi_map + +
+/ MIDI_INSTRUMENTS SP ALL + +
@@ -5435,6 +7665,9 @@
/ MIDI_INPUT_DEVICE SP number
+/ FX_SEND SP sampler_channel SP fx_send_id + +
@@ -5486,6 +7719,27 @@
/ SOLO SP sampler_channel SP boolean
+/ MIDI_INSTRUMENT_MAP SP sampler_channel SP midi_map + +
+/ MIDI_INSTRUMENT_MAP SP sampler_channel SP NONE + +
+/ MIDI_INSTRUMENT_MAP SP sampler_channel SP DEFAULT + +
++ +
+modal_arg = +
++/* epsilon (empty argument) */ + +
+/ NON_MODAL SP + +
@@ -5534,6 +7788,18 @@
/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
+/ MIDI_INSTRUMENTS SP midi_map + +
+/ MIDI_INSTRUMENTS SP ALL + +
+/ MIDI_INSTRUMENT_MAPS + +
+/ FX_SENDS SP sampler_channel + +
@@ -5558,6 +7824,21 @@
+
instr_load_mode = +
++ON_DEMAND + +
+/ ON_DEMAND_HOLD + +
+/ PERSISTENT + +
+
+ +
device_index =
@@ -5615,6 +7896,42 @@
+
midi_map = +
++number + +
+
+ +
+midi_bank = +
++number + +
+
+ +
+midi_prog = +
++number + +
+
+ +
+midi_ctrl = +
++number + +
+
+ +
volume_value =
@@ -5645,6 +7962,15 @@
+
fx_send_id = +
++number + +
+
+ +
engine_name =
@@ -5663,6 +7989,33 @@
+
map_name = +
++stringval + +
+
+ +
+entry_name = +
++stringval + +
+
+ +
+fx_send_name = +
++stringval + +
+
+ +
param_val_list =
@@ -5694,14 +8047,140 @@
--
TOC 8. Events
++
TOC 8. +Events
This chapter will describe all currently defined events supported by LinuxSampler.
-
--
TOC 8.1. Number of sampler channels changed
+
++
TOC 8.1. +Number of audio output devices changed
+ +Client may want to be notified when the total number of audio output devices on the + back-end changes by issuing the following command: +
++
++SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT +
++ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:AUDIO_OUTPUT_DEVICE_COUNT:<devices>" +
++ +
+where <devices> will be replaced by the new number + of audio output devices. +
+
++
TOC 8.2. +Audio output device's settings changed
+ +Client may want to be notified when changes were made to audio output devices on the + back-end by issuing the following command: +
++
++SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO +
++ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:AUDIO_OUTPUT_DEVICE_INFO:<device-id>" +
++ +
+where <device-id> will be replaced by the numerical ID of the audio output device, + which settings has been changed. The front-end will have to send + the respective command to actually get the audio output device info. Because these messages + will be triggered by LSCP commands issued by other clients rather than real + time events happening on the server, it is believed that an empty notification + message is sufficient here. +
+
++
TOC 8.3. +Number of MIDI input devices changed
+ +Client may want to be notified when the total number of MIDI input devices on the + back-end changes by issuing the following command: +
++
++SUBSCRIBE MIDI_INPUT_DEVICE_COUNT +
++ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:MIDI_INPUT_DEVICE_COUNT:<devices>" +
++ +
+where <devices> will be replaced by the new number + of MIDI input devices. +
+
++
TOC 8.4. +MIDI input device's settings changed
+ +Client may want to be notified when changes were made to MIDI input devices on the + back-end by issuing the following command: +
++
++SUBSCRIBE MIDI_INPUT_DEVICE_INFO +
++ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:MIDI_INPUT_DEVICE_INFO:<device-id>" +
++ +
+where <device-id> will be replaced by the numerical ID of the MIDI input device, + which settings has been changed. The front-end will have to send + the respective command to actually get the MIDI input device info. Because these messages + will be triggered by LSCP commands issued by other clients rather than real + time events happening on the server, it is believed that an empty notification + message is sufficient here. +
+
++
TOC 8.5. +Number of sampler channels changed
Client may want to be notified when the total number of channels on the back-end changes by issuing the following command: @@ -5728,8 +8207,9 @@ of sampler channels.
--
TOC 8.2. Number of active voices changed
++
TOC 8.6. +Number of active voices changed
Client may want to be notified when the number of voices on the back-end changes by issuing the following command: @@ -5747,7 +8227,7 @@
-"NOTIFY:VOICE_COUNT:<sampler-channel> <voices> +
"NOTIFY:VOICE_COUNT:<sampler-channel> <voices>"
@@ -5757,8 +8237,9 @@ active voices on that channel.
--
TOC 8.3. Number of active disk streams changed
++
TOC 8.7. +Number of active disk streams changed
Client may want to be notified when the number of streams on the back-end changes by issuing the following command: SUBSCRIBE STREAM_COUNT @@ -5786,8 +8267,9 @@ active disk streams on that channel.
--
TOC 8.4. Disk stream buffer fill state changed
++
TOC 8.8. +Disk stream buffer fill state changed
Client may want to be notified when the buffer fill state of a disk stream on the back-end changes by issuing the following command: @@ -5812,12 +8294,13 @@
where <sampler-channel> will be replaced by the sampler channel the buffer fill state change occurred on and <fill-data> will be replaced by the - buffer fill data for this channel as described in Section 6.4.13 (Current fill state of disk stream buffers) - as if the "GET CHANNEL BUFFER_FILL PERCENTAGE" (Current fill state of disk stream buffers) command was issued on this channel. + buffer fill data for this channel as described in Section 6.4.13 (Current fill state of disk stream buffers) + as if the "GET CHANNEL BUFFER_FILL PERCENTAGE" (Current fill state of disk stream buffers) command was issued on this channel.
-
--
TOC 8.5. Channel information changed
+
++
TOC 8.9. +Channel information changed
Client may want to be notified when changes were made to sampler channels on the back-end by issuing the following command: @@ -5847,9 +8330,70 @@ time events happening on the server, it is believed that an empty notification message is sufficient here.
+
++
TOC 8.10. +Number of effect sends changed
+ +Client may want to be notified when the number of effect sends on + a particular sampler channel is changed by issuing the following command: +
++
++SUBSCRIBE FX_SEND_COUNT +
++ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:FX_SEND_COUNT:<channel-id> <fx-sends>" +
++ +
+where <channel-id> will be replaced by the numerical ID of the sampler + channel, on which the effect sends number is changed and <fx-sends> will + be replaced by the new number of effect sends on that channel. +
+
++
TOC 8.11. +Effect send information changed
+ +Client may want to be notified when changes were made to effect sends on a + a particular sampler channel by issuing the following command: +
++
++SUBSCRIBE FX_SEND_INFO +
++ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:FX_SEND_INFO:<channel-id> <fx-send-id>" +
++ +
+where <channel-id> will be replaced by the numerical ID of the sampler + channel, on which an effect send entity is changed and <fx-send-id> will + be replaced by the numerical ID of the changed effect send. +
--
TOC 8.6. Total number of active voices changed
++
TOC 8.12. +Total number of active voices changed
Client may want to be notified when the total number of voices on the back-end changes by issuing the following command: @@ -5867,7 +8411,7 @@
-"NOTIFY:TOTAL_VOICE_COUNT:<voices> +
"NOTIFY:TOTAL_VOICE_COUNT:<voices>"
@@ -5875,9 +8419,165 @@
where <voices> will be replaced by the new number of all currently active voices.
+
++
TOC 8.13. +Number of MIDI instrument maps changed
+ +Client may want to be notified when the number of MIDI instrument maps on the + back-end changes by issuing the following command: +
++
++SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT +
++ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:MIDI_INSTRUMENT_MAP_COUNT:<maps>" +
++ +
+where <maps> will be replaced by the new number + of MIDI instrument maps. +
+
++
TOC 8.14. +MIDI instrument map information changed
+ +Client may want to be notified when changes were made to MIDI instrument maps on the + back-end by issuing the following command: +
++
++SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO +
++ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:MIDI_INSTRUMENT_MAP_INFO:<map-id>" +
++ +
+where <map-id> will be replaced by the numerical ID of the MIDI instrument map, + for which information changes occurred. The front-end will have to send + the respective command to actually get the MIDI instrument map info. Because these messages + will be triggered by LSCP commands issued by other clients rather than real + time events happening on the server, it is believed that an empty notification + message is sufficient here. +
+
++
TOC 8.15. +Number of MIDI instruments changed
+ +Client may want to be notified when the number of MIDI instrument maps on the + back-end changes by issuing the following command: +
++
++SUBSCRIBE MIDI_INSTRUMENT_COUNT +
++ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:MIDI_INSTRUMENT_COUNT:<map-id> <instruments>" +
++ +
+where <map-id> is the numerical ID of the MIDI instrument map, in which + the nuber of instruments has changed and <instruments> will be replaced by + the new number of MIDI instruments in the specified map. +
+
++
TOC 8.16. +MIDI instrument information changed
+ +Client may want to be notified when changes were made to MIDI instruments on the + back-end by issuing the following command: +
++
++SUBSCRIBE MIDI_INSTRUMENT_INFO +
++ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:MIDI_INSTRUMENT_INFO:<map-id> <bank> <program>" +
++ +
+where <map-id> will be replaced by the numerical ID of the MIDI instrument map, + in which a MIDI instrument is changed. <bank> and <program> specifies + the location of the changed MIDI instrument in the map. The front-end will have to send + the respective command to actually get the MIDI instrument info. Because these messages + will be triggered by LSCP commands issued by other clients rather than real + time events happening on the server, it is believed that an empty notification + message is sufficient here. +
+
++
TOC 8.17. +Global settings changed
+ +Client may want to be notified when changes to the global settings + of the sampler were made by issuing the following command: +
++
++SUBSCRIBE GLOBAL_INFO +
++ +
+Server will start sending the following types of notification messages: +
++
++"NOTIFY:GLOBAL_INFO:VOLUME <volume>" - Notifies that the + golbal volume of the sampler is changed, where <volume> will be + replaced by the optional dotted floating point value, reflecting the + new global volume parameter. +
++ +
--
TOC 8.7. Miscellaneous and debugging events
++
TOC 8.18. +Miscellaneous and debugging events
Client may want to be notified of miscellaneous and debugging events occurring at the server by issuing the following command: @@ -5905,8 +8605,9 @@ user AS IS to facilitate debugging.
--
TOC 9. Security Considerations
++
TOC 9. +Security Considerations
As there is so far no method of authentication and authorization defined and so not required for a client applications to succeed to @@ -5914,8 +8615,9 @@ system the LinuxSampler instance is running on.
--
TOC 10. Acknowledgments
++
TOC 10. +Acknowledgments
This document has benefited greatly from the comments of the following people, discussed on the LinuxSampler developer's mailing @@ -5936,7 +8638,7 @@
-+
TOC
TOC 11. References
[RFC2119] @@ -5948,7 +8650,7 @@
-+
TOC
TOC Author's Address
@@ -5966,58 +8668,53 @@ schoenebeck at software minus engineering dot org
--
TOC Intellectual Property Statement
++
TOC Full Copyright Statement
-The IETF takes no position regarding the validity or scope of -any intellectual property or other rights that might be claimed -to pertain to the implementation or use of the technology -described in this document or the extent to which any license -under such rights might or might not be available; neither does -it represent that it has made any effort to identify any such -rights. Information on the IETF's procedures with respect to -rights in standards-track and standards-related documentation -can be found in BCP 11. Copies of claims of rights made -available for publication and any assurances of licenses to -be made available, or the result of an attempt made -to obtain a general license or permission for the use of such -proprietary rights by implementors or users of this -specification can be obtained from the IETF Secretariat.
+Copyright © The IETF Trust (2007).-The IETF invites any interested party to bring to its -attention any copyrights, patents or patent applications, or -other proprietary rights which may cover technology that may be -required to practice this standard. Please address the -information to the IETF Executive Director.
-Full Copyright Statement
+This document is subject to the rights, +licenses and restrictions contained in BCP 78, +and except as set forth therein, +the authors retain all their rights.-Copyright © The Internet Society (2006). All Rights Reserved.
+This document and the information contained herein are provided +on an “AS IS” basis and THE CONTRIBUTOR, +THE ORGANIZATION HE/SHE REPRESENTS +OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST +AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT +THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY +IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR +PURPOSE. +Intellectual Property
-This document and translations of it may be copied and furnished to -others, and derivative works that comment on or otherwise explain it -or assist in its implementation may be prepared, copied, published and -distributed, in whole or in part, without restriction of any kind, -provided that the above copyright notice and this paragraph are -included on all such copies and derivative works. However, this -document itself may not be modified in any way, such as by removing -the copyright notice or references to the Internet Society or other -Internet organizations, except as needed for the purpose of -developing Internet standards in which case the procedures for -copyrights defined in the Internet Standards process must be -followed, or as required to translate it into languages other than -English.
+The IETF takes no position regarding the validity or scope of any +Intellectual Property Rights or other rights that might be claimed +to pertain to the implementation or use of the technology +described in this document or the extent to which any license +under such rights might or might not be available; nor does it +represent that it has made any independent effort to identify any +such rights. +Information on the procedures with respect to +rights in RFC documents can be found in BCP 78 and BCP 79.-The limited permissions granted above are perpetual and will not be -revoked by the Internet Society or its successors or assignees.
+Copies of IPR disclosures made to the IETF Secretariat and any +assurances of licenses to be made available, +or the result of an attempt made to obtain a general license or +permission for the use of such proprietary rights by implementers or +users of this specification can be obtained from the IETF on-line IPR +repository at http://www.ietf.org/ipr.-This document and the information contained herein is provided on an -“AS IS” basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING -TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING -BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION -HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF -MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+The IETF invites any interested party to bring to its attention +any copyrights, +patents or patent applications, +or other +proprietary rights that may cover technology that may be required +to implement this standard. +Please address the information to the IETF at ietf-ipr@ietf.org.Acknowledgment
-Funding for the RFC Editor function is currently provided by the -Internet Society.
+Funding for the RFC Editor function is provided by +the IETF Administrative Support Activity (IASA).