--- web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.html 2006/12/15 21:40:27 973 +++ web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.html 2006/12/15 21:46:48 974 @@ -3,139 +3,159 @@ - - + +
-TOC |
TOC |
|
-This document is an Internet-Draft and is -in full conformance with all provisions of Section 10 of RFC 2026.
+By submitting this Internet-Draft, +each author represents that any applicable patent or other IPR claims of which +he or she is aware have been or will be disclosed, +and any of which he or she becomes aware will be disclosed, +in accordance with Section 6 of BCP 79.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 30, 2007.
+This Internet-Draft will expire on June 18, 2007.-Copyright © The Internet Society (2006). All Rights Reserved.
+Copyright © The Internet Society (2006).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. @@ -446,8 +481,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 @@ -490,13 +526,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 @@ -516,8 +553,9 @@ there.
TOC |
TOC |
Main focus of this protocol is to provide a way to configure a running LinuxSampler instance and to retrieve information @@ -528,8 +566,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 @@ -543,11 +582,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 @@ -588,8 +628,9 @@ MUST be sent back in the same order.
TOC |
TOC |
Result set could be one of the following types:
@@ -780,8 +821,9 @@TOC |
TOC |
This more sophisticated communication method is actually only an extension of the simple request/response @@ -858,7 +900,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 @@ -904,19 +946,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 "#" @@ -925,8 +969,9 @@ file.
TOC |
TOC |
Instances of drivers in LinuxSampler are called devices. You can use multiple audio devices simultaneously, e.g. to @@ -960,8 +1005,9 @@ possible values, etc.
TOC |
TOC |
Use the following command to get the number of audio output drivers currently available for the @@ -999,8 +1045,9 @@
TOC |
TOC |
Use the following command to list all audio output drivers currently available for the LinuxSampler @@ -1039,8 +1086,9 @@
TOC |
TOC |
Use the following command to get detailed information @@ -1057,7 +1105,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:
@@ -1138,8 +1186,9 @@TOC |
TOC |
Use the following command to get detailed information @@ -1154,10 +1203,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 @@ -1214,7 +1263,7 @@
@@ -1225,7 +1274,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)
@@ -1264,7 +1313,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)
@@ -3909,14 +4003,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 (') @@ -1392,8 +1441,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:
@@ -1407,7 +1457,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 ('). @@ -1476,8 +1526,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:
@@ -1491,8 +1542,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: @@ -1545,8 +1596,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:
@@ -1582,8 +1634,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:
@@ -1619,8 +1672,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:
@@ -1634,7 +1688,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:
@@ -1654,7 +1708,7 @@@@ -1695,7 +1749,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: @@ -1725,8 +1779,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:
@@ -1740,8 +1795,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.
@@ -1793,8 +1848,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:
@@ -1807,8 +1863,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: @@ -1935,8 +1991,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:
@@ -1949,11 +2006,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:
@@ -2081,8 +2138,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:
@@ -2095,8 +2153,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.
@@ -2158,8 +2216,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 @@ -2188,8 +2247,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 @@ -2227,8 +2287,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: @@ -2265,8 +2326,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:
@@ -2279,7 +2341,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:
@@ -2346,8 +2408,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:
@@ -2360,9 +2423,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 @@ -2409,7 +2472,7 @@
@@ -2420,7 +2483,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)
@@ -2459,7 +2522,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 (') @@ -2533,8 +2596,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:
@@ -2547,7 +2611,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 @@ -2603,8 +2667,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:
@@ -2617,8 +2682,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: @@ -2668,8 +2733,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:
@@ -2705,8 +2771,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:
@@ -2752,8 +2819,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:
@@ -2766,8 +2834,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: @@ -2790,7 +2858,7 @@
@@ -2820,7 +2888,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: @@ -2840,8 +2908,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:
@@ -2855,8 +2924,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.
@@ -2907,8 +2976,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:
@@ -2921,8 +2991,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: @@ -2969,8 +3039,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:
@@ -2983,11 +3054,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:
@@ -3110,8 +3181,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:
@@ -3125,8 +3197,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. @@ -3176,16 +3248,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:
@@ -3207,7 +3281,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 @@ -3261,8 +3335,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: @@ -3276,10 +3351,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 @@ -3335,8 +3410,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 @@ -3373,8 +3449,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 @@ -3412,8 +3489,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: @@ -3486,8 +3564,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:
@@ -3501,8 +3580,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.
@@ -3552,8 +3631,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:
@@ -3588,8 +3668,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:
@@ -3627,8 +3708,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: @@ -3642,7 +3724,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:
@@ -3699,8 +3781,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: @@ -3714,8 +3797,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:
@@ -3870,6 +3953,17 @@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: @@ -3930,8 +4033,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:
@@ -3955,8 +4058,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: @@ -3970,8 +4074,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:
@@ -3997,8 +4101,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: @@ -4023,8 +4128,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:
@@ -4074,8 +4179,9 @@TOC |
TOC |
The front-end can set the audio output device on a specific sampler channel by sending the following command: @@ -4089,11 +4195,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: @@ -4140,9 +4246,10 @@
-
TOC |
TOC |
DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
@@ -4205,8 +4312,9 @@TOC |
TOC |
The front-end can alter the audio output channel on a specific sampler channel by sending the following command: @@ -4220,8 +4328,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. @@ -4271,8 +4379,9 @@
TOC |
TOC |
The front-end can set the MIDI input device on a specific sampler channel by sending the following command: @@ -4286,11 +4395,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:
@@ -4337,8 +4446,9 @@TOC |
TOC |
DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
@@ -4401,8 +4511,9 @@TOC |
TOC |
The front-end can alter the MIDI input port on a specific sampler channel by sending the following command: @@ -4464,8 +4575,9 @@
TOC |
TOC |
The front-end can alter the MIDI channel a sampler channel should listen to by sending the following command: @@ -4527,8 +4639,9 @@
TOC |
TOC |
The front-end can alter the volume of a sampler channel by sending the following command: @@ -4591,8 +4704,9 @@
TOC |
TOC |
The front-end can mute/unmute a specific sampler channel by sending the following command: @@ -4606,8 +4720,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.
@@ -4656,8 +4770,9 @@TOC |
TOC |
The front-end can solo/unsolo a specific sampler channel by sending the following command: @@ -4671,8 +4786,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.
@@ -4720,9 +4835,108 @@+
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 |
TOC |
The front-end can reset a particular sampler channel by sending the following command:
@@ -4786,14 +5000,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: @@ -4855,8 +5071,9 @@
TOC |
TOC |
The front-end can unregister itself if it doesn't want to receive event messages anymore by sending the following command: @@ -4918,8 +5135,9 @@
TOC |
TOC |
To enable or disable back sending of commands to the client the following command can be used:
@@ -4974,8 +5192,9 @@TOC |
TOC |
The client can close its network connection to LinuxSampler by sending the following command:
@@ -4991,14 +5210,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: @@ -5023,8 +5244,9 @@
TOC |
TOC |
The front-end can ask for the maximum number of active voices by sending the following command: @@ -5049,8 +5271,9 @@
TOC |
TOC |
The front-end can reset the whole sampler by sending the following command:
@@ -5089,8 +5312,9 @@TOC |
TOC |
The client can ask for general informations about the LinuxSampler instance by sending the following command: @@ -5138,7 +5362,7 @@
@@ -5152,9 +5376,10 @@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 |
TOC |
The MIDI protocol provides a way to switch between instruments by sending so called MIDI bank select and MIDI program change @@ -5162,12 +5387,21 @@ allow to actually map arbitrary MIDI bank select / program change numbers with real instruments.
-By default, that is when the sampler is launched, this map will - be empty, thus the sampler will simply ignore all program change - messages. The front-end has to explicitly add entries to the map - so the sampler knows how to react on a given program change - message, that is by switching to the respectively defined engine - type and loading the respective instrument. +
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 @@ -5176,34 +5410,394 @@ 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 +
+
+ +
+The mentioned fields above don't have to be in particular order. +
+Example: +
++
++C: "GET MIDI_INSTRUMENT_MAP INFO 0" +
+S: "NAME: Standard Map" +
+"." +
+
+ +
+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 |
TOC |
The front-end can create a new or replace an existing entry - in the sampler's MIDI instrument map by sending the following + in a sampler's MIDI instrument map by sending the following command:
-MAP MIDI_INSTRUMENT <midi_bank_msb> - <midi_bank_lsb> <midi_prog> <engine_name> +
MAP MIDI_INSTRUMENT <map> + <midi_bank> <midi_prog> <engine_name> <filename> <instrument_index> <volume_value> [<instr_load_mode>] [<name>]
-
Where <midi_bank_msb> is an integer value between - 0..127 reflecting the MIDI bank select MSB (coarse) index, - <midi_bank_lsb> an integer value between 0..127 reflecting - the MIDI bank select LSB (fine) index, <midi_prog> an +
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) + 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 + 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 @@ -5298,12 +5892,12 @@ 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) + "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)). + "GET MIDI_INSTRUMENT INFO" (Get current settings of MIDI instrument map entry)).
@@ -5332,7 +5926,7 @@
"ERR:<error-code>:<error-message>" -
-@@ -5346,7 +5940,7 @@when the given engine does not exist or a value +
when the given map or engine does not exist or a value is out of range
-C: "MAP MIDI_INSTRUMENT 3 0 0 gig '/usr/share/Steinway D.gig' 0 0.8 PERSISTENT" +
C: "MAP MIDI_INSTRUMENT 0 3 0 gig '/usr/share/Steinway D.gig' 0 0.8 PERSISTENT"
S: "OK"
@@ -5356,7 +5950,7 @@
-C: "MAP MIDI_INSTRUMENT 127 4 50 gig '/home/john/foostrings.gig' 7 1.0" +
C: "MAP MIDI_INSTRUMENT 0 4 50 gig '/home/john/foostrings.gig' 7 1.0"
S: "OK"
@@ -5370,7 +5964,7 @@S: "OK"
-C: "MAP MIDI_INSTRUMENT 1 0 0 gig '/usr/share/piano.gig' 0 0.25 'Silent Piano'" +
C: "MAP MIDI_INSTRUMENT 0 1 0 gig '/usr/share/piano.gig' 0 0.25 'Silent Piano'"
S: "OK"
@@ -5380,7 +5974,7 @@
-C: "MAP MIDI_INSTRUMENT 99 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'" +
C: "MAP MIDI_INSTRUMENT 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"
S: "OK"
@@ -5388,17 +5982,30 @@
--
TOC 6.7.2. Getting ammount of MIDI instrument map entries
++
TOC 6.7.8. +Getting ammount of MIDI instrument map entries
-The front-end can query the amount of currently existing MIDI - instrument map entries by sending the following +
The front-end can query the amount of currently existing + entries in a MIDI instrument map by sending the following command:
-GET MIDI_INSTRUMENTS +
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
@@ -5408,8 +6015,8 @@
-LinuxSampler will answer by sending the current number of - entries in the sampler's MIDI instrument map. +
The sampler will answer by sending the current number of + entries in the MIDI instrument map(s).
@@ -5419,24 +6026,50 @@
-C: "GET MIDI_INSTRUMENTS" +
C: "GET MIDI_INSTRUMENTS 0" +
+S: "234" +
++ +
++
++C: "GET MIDI_INSTRUMENTS ALL"
-S: "634" +
S: "954"
--
TOC 6.7.3. Getting indeces of all MIDI instrument map entries
++
TOC 6.7.9. +Getting indeces of all entries of a MIDI instrument map
-The front-end can query a list of all currently existing MIDI - instrument map entries by sending the following command: +
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 +
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
@@ -5446,13 +6079,13 @@
-LinuxSampler will answer by sending a comma separated - list of MIDI bank MSB (coarse) - MIDI bank LSB (fine) - - 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) +
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.
@@ -5464,34 +6097,35 @@
-C: "LIST MIDI_INSTRUMENTS" +
C: "LIST MIDI_INSTRUMENTS 0"
-S: "{0,0,0},{0,0,1},{120,0,3},{120,0,4},{23,127,127}" +
S: "{0,0,0},{0,0,1},{0,0,3},{0,1,4},{1,127,127}"
--
TOC 6.7.4. Remove an entry from the MIDI instrument map
++
TOC 6.7.10. +Remove an entry from the MIDI instrument map
-The front-end can delete an entry from the MIDI instrument +
The front-end can delete an entry from a MIDI instrument map by sending the following command:
-UNMAP MIDI_INSTRUMENT <midi_bank_msb> <midi_bank_lsb> <midi_prog> +
UNMAP MIDI_INSTRUMENT <map> <midi_bank> <midi_prog>
- Where <midi_bank_msb> is an integer value between 0..127 - reflecting the MIDI bank MSB (coarse) value, <midi_bank_lsb> - an integer value between 0..127 reflecting the MIDI bank LSB - (fine) value and <midi_prog> an integer value between - 0..127 reflecting the MIDI program value of the map entrie's key + 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.
@@ -5524,7 +6158,7 @@
-@@ -5619,7 +6254,7 @@C: "UNMAP MIDI_INSTRUMENT 2 40 127" +
C: "UNMAP MIDI_INSTRUMENT 0 2 127"
S: "OK"
@@ -5532,8 +6166,9 @@
--
TOC 6.7.5. Get current settings of MIDI instrument map entry
++
TOC 6.7.11. +Get current settings of MIDI instrument map entry
The front-end can retrieve the current settings of a certain instrument map entry by sending the following command: @@ -5541,17 +6176,17 @@
-GET MIDI_INSTRUMENT INFO <midi_bank_msb> <midi_bank_lsb> <midi_prog> +
GET MIDI_INSTRUMENT INFO <map> <midi_bank> <midi_prog>
- Where <midi_bank_msb> is an integer value between 0..127 - reflecting the MIDI bank MSB (coarse) value, <midi_bank_lsb> - an integer value between 0..127 reflecting the MIDI bank LSB - (fine) value and <midi_prog> an integer value between - 0..127 reflecting the MIDI program value of the map entrie's key + 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.
@@ -5574,7 +6209,7 @@ 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) + "MAP MIDI_INSTRUMENT" (Create or replace a MIDI instrument map entry) command and does not have to be unique.@@ -5644,7 +6279,7 @@Life time of instrument - (see "MAP MIDI_INSTRUMENT" (Create or replace a MIDI instrument map entry) for details about this setting). + (see "MAP MIDI_INSTRUMENT" (Create or replace a MIDI instrument map entry) for details about this setting).
-C: "GET MIDI_INSTRUMENT INFO 3 45 120" +
C: "GET MIDI_INSTRUMENT INFO 1 45 120"
S: "NAME: Drums for Foo Song"
@@ -5666,20 +6301,39 @@
--
TOC 6.7.6. Clear MIDI instrument map
++
TOC 6.7.12. +Clear MIDI instrument map
-The front-end can clear the whole MIDI instrument map, that - is delete all entries by sending the following command: +
The front-end can clear a whole MIDI instrument map, that + is delete all its entries by sending the following command:
-CLEAR MIDI_INSTRUMENTS +
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:
@@ -5696,12 +6350,22 @@
-
Example: +
Examples:
-C: "CLEAR MIDI_INSTRUMENTS" +
C: "CLEAR MIDI_INSTRUMENTS 0" +
+S: "OK" +
++ +
++
++C: "CLEAR MIDI_INSTRUMENTS ALL"
S: "OK"
@@ -5709,11 +6373,12 @@
--
TOC 7. Command Syntax
++
TOC 7. +Command Syntax
-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.
@@ -5771,7 +6436,7 @@command =
-ADD SP CHANNEL +
ADD SP add_instruction
/ MAP SP map_instruction @@ -5796,7 +6461,6 @@
/ REMOVE SP remove_instruction -
/ SET SP set_instruction @@ -5826,6 +6490,21 @@
+
add_instruction = +
++CHANNEL + +
+/ MIDI_INSTRUMENT_MAP + +
+/ MIDI_INSTRUMENT_MAP SP map_name + +
++ +
subscribe_event =
@@ -5883,16 +6562,16 @@map_instruction =
-MIDI_INSTRUMENT SP midi_bank_msb SP midi_bank_lsb SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value +
MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value
-/ MIDI_INSTRUMENT SP midi_bank_msb SP midi_bank_lsb SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode +
/ MIDI_INSTRUMENT SP 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 midi_bank_msb SP midi_bank_lsb SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP entry_name +
/ MIDI_INSTRUMENT SP 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 midi_bank_msb SP midi_bank_lsb SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode SP entry_name +
/ MIDI_INSTRUMENT SP 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
@@ -5901,7 +6580,7 @@
unmap_instruction =
-MIDI_INSTRUMENT SP midi_bank_msb SP midi_bank_lsb SP midi_prog +
MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog
@@ -5913,6 +6592,12 @@
CHANNEL SP sampler_channel
+/ MIDI_INSTRUMENT_MAP SP midi_map + +
+/ MIDI_INSTRUMENT_MAP SP ALL + +
@@ -5997,10 +6682,19 @@
/ TOTAL_VOICE_COUNT_MAX
-/ MIDI_INSTRUMENTS +
/ MIDI_INSTRUMENTS SP midi_map
-/ MIDI_INSTRUMENT SP INFO SP midi_bank_msb SP midi_bank_lsb SP midi_prog +
/ 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
@@ -6024,6 +6718,9 @@
/ CHANNEL SP set_chan_instruction
+/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name + +
/ ECHO SP boolean
@@ -6060,7 +6757,10 @@clear_instruction =
-MIDI_INSTRUMENTS +
MIDI_INSTRUMENTS SP midi_map + +
+/ MIDI_INSTRUMENTS SP ALL
@@ -6126,6 +6826,15 @@
/ 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 + +
@@ -6174,7 +6883,13 @@
/ AVAILABLE_AUDIO_OUTPUT_DRIVERS
-/ MIDI_INSTRUMENTS +
/ MIDI_INSTRUMENTS SP midi_map + +
+/ MIDI_INSTRUMENTS SP ALL + +
+/ MIDI_INSTRUMENT_MAPS
@@ -6273,7 +6988,7 @@
-
midi_bank_msb = +
midi_map =
number @@ -6282,7 +6997,7 @@
-
midi_bank_lsb = +
midi_bank =
number @@ -6348,6 +7063,15 @@
+
map_name = +
++stringval + +
++ +
entry_name =
@@ -6388,14 +7112,16 @@
--
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 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: @@ -6422,8 +7148,9 @@ of sampler channels.
--
TOC 8.2. Number of active voices changed
++
TOC 8.2. +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: @@ -6451,8 +7178,9 @@ active voices on that channel.
--
TOC 8.3. Number of active disk streams changed
++
TOC 8.3. +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 @@ -6480,8 +7208,9 @@ active disk streams on that channel.
--
TOC 8.4. Disk stream buffer fill state changed
++
TOC 8.4. +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: @@ -6506,12 +7235,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.5. +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: @@ -6542,8 +7272,9 @@ message is sufficient here.
--
TOC 8.6. Total number of active voices changed
++
TOC 8.6. +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: @@ -6570,8 +7301,9 @@ all currently active voices.
--
TOC 8.7. Miscellaneous and debugging events
++
TOC 8.7. +Miscellaneous and debugging events
Client may want to be notified of miscellaneous and debugging events occurring at the server by issuing the following command: @@ -6598,18 +7330,20 @@ wants to send to the client. Client MAY display this data to the 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 connect, running LinuxSampler might be a security risk for the host 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 @@ -6630,7 +7364,7 @@
-+
TOC
TOC 11. References
[RFC2119] @@ -6642,7 +7376,7 @@
-+
TOC
TOC Author's Address
@@ -6660,58 +7394,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 Internet Society (2006).-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 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).