--- linuxsampler/trunk/Documentation/lscp.xml 2007/06/22 13:40:53 1249 +++ linuxsampler/trunk/Documentation/lscp.xml 2019/03/11 15:07:49 3501 @@ -16,25 +16,27 @@ to an annoying "missing Normative/Informative References" error message --> - + - LinuxSampler Control Protocol (draft) + LinuxSampler Control Protocol - Interessengemeinschaft Software Engineering e. V. + LinuxSampler.org
- Max-Planck-Str. 39 + Crudebyte Engineering + Hofgartenstr. 3 - 74081 Heilbronn + 74189 Weinsberg Germany - schoenebeck at software minus engineering dot org + +49 7134 911614 + cuse@users.sf.net
- + LinuxSampler Developers LSCP @@ -514,7 +516,7 @@ what parameters drivers are offering, how to retrieve their possible values, etc. -
+
Use the following command to get the number of audio output drivers currently available for the LinuxSampler instance: @@ -539,7 +541,7 @@
-
+
Use the following command to list all audio output drivers currently available for the LinuxSampler instance: @@ -566,7 +568,7 @@
+ output driver" anchor="GET AUDIO_OUTPUT_DRIVER INFO" lscp_cmd="true"> Use the following command to get detailed information about a specific audio output driver: @@ -639,7 +641,7 @@
+ output driver parameter" anchor="GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO" lscp_cmd="true"> Use the following command to get detailed information about a specific audio output driver parameter: @@ -827,7 +829,7 @@
-
+
Use the following command to create a new audio output device for the desired audio output system: @@ -887,7 +889,7 @@
-
+
Use the following command to destroy a created output device: @@ -956,7 +958,7 @@
-
+
Use the following command to list all created audio output devices: @@ -979,7 +981,7 @@
-
+
Use the following command to get current settings of a specific, created audio output device: @@ -1052,7 +1054,7 @@
-
+
Use the following command to alter a specific setting of a created audio output device: @@ -1097,7 +1099,7 @@
-
+
Use the following command to get information about an audio channel: @@ -1197,7 +1199,7 @@
-
+
Use the following command to get detailed information about specific audio channel parameter: @@ -1303,7 +1305,7 @@
-
+
Use the following command to alter a specific setting of an audio output channel: @@ -1381,7 +1383,7 @@ showing how to retrieve what parameters drivers are offering, how to retrieve their possible values, etc. -
+
Use the following command to get the number of MIDI input drivers currently available for the LinuxSampler instance: @@ -1406,7 +1408,7 @@
-
+
Use the following command to list all MIDI input drivers currently available for the LinuxSampler instance: @@ -1430,7 +1432,7 @@
-
+
Use the following command to get detailed information about a specific MIDI input driver: @@ -1486,7 +1488,7 @@
-
+
Use the following command to get detailed information about a specific parameter of a specific MIDI input driver: @@ -1641,7 +1643,7 @@
-
+
Use the following command to create a new MIDI input device for the desired MIDI input system: @@ -1691,7 +1693,7 @@
-
+
Use the following command to destroy a created MIDI input device: @@ -1733,7 +1735,7 @@
-
+
Use the following command to count all created MIDI input devices: @@ -1757,7 +1759,7 @@
-
+
Use the following command to list all created MIDI input devices: @@ -1786,7 +1788,7 @@
-
+
Use the following command to get current settings of a specific, created MIDI input device: @@ -1852,7 +1854,7 @@
-
+
Use the following command to alter a specific setting of a created MIDI input device: @@ -1898,7 +1900,7 @@
-
+
Use the following command to get information about a MIDI port: @@ -1942,7 +1944,7 @@
-
+
Use the following command to get detailed information about specific MIDI port parameter: @@ -2047,7 +2049,7 @@
-
+
Use the following command to alter a specific setting of a MIDI input port: @@ -2061,7 +2063,8 @@ or "LIST MIDI_INPUT_DEVICES" 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. + parameter (encapsulated into apostrophes) or NONE (not encapsulated into apostrophes) + for specifying no value for parameters allowing a list of values. Possible Answers: @@ -2088,7 +2091,14 @@ Example: - + C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='20:0'" + S: "OK" + + + + + C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE" + S: "OK"
@@ -2099,7 +2109,7 @@ sampler channel with a sampler engine, load instruments and connect sampler channels to MIDI and audio devices. -
+
An instrument file can be loaded and assigned to a sampler channel by one of the following commands: @@ -2113,7 +2123,7 @@ number of the sampler channel the instrument should be assigned to. Each sampler channel can only have one instrument. - Notice: since LSCP 1.3 the <filename> argument supports + Notice: since LSCP 1.2 the <filename> argument supports escape characters for special characters (see chapter "Character Set and Escape Sequences" for details) and accordingly backslash characters in the filename @@ -2154,10 +2164,18 @@ - Example: + Example (Unix): - + C: LOAD INSTRUMENT '/home/joe/gigs/cello.gig' 0 0 + S: OK + + + Example (Windows): + + + C: LOAD INSTRUMENT 'D:/MySounds/cello.gig' 0 0 + S: OK
@@ -2217,7 +2235,7 @@
-
+
The number of sampler channels can change on runtime. To get the current amount of sampler channels, the front-end can send the following command: @@ -2241,7 +2259,7 @@
-
+
The number of sampler channels can change on runtime. To get the current list of sampler channels, the front-end can send the following command: @@ -2266,7 +2284,7 @@
-
+
A new sampler channel can be added to the end of the sampler channel list by sending the following command: @@ -2318,7 +2336,7 @@
-
+
A sampler channel can be removed by sending the following command: @@ -2364,7 +2382,7 @@
-
+
The front-end can ask for the number of available engines by sending the following command: @@ -2386,7 +2404,7 @@
-
+
The front-end can ask for a list of all available engines by sending the following command: @@ -2406,12 +2424,12 @@ C: "LIST AVAILABLE_ENGINES" - S: "'GigEngine','AkaiEngine','DLSEngine','JoesCustomEngine'" + S: "'gig','sfz','sf2'"
-
+
The front-end can ask for information about a specific engine by sending the following command: @@ -2435,7 +2453,9 @@ DESCRIPTION - - arbitrary description text about the engine + arbitrary description text about the engine + (note that the character string may contain + escape sequences) VERSION - @@ -2450,18 +2470,26 @@ The mentioned fields above don't have to be in particular order. - Example: + Examples: - C: "GET ENGINE INFO JoesCustomEngine" - S: "DESCRIPTION: this is Joe's custom sampler engine" -    "VERSION: testing-1.0" + C: "GET ENGINE INFO gig" + S: "DESCRIPTION: GigaSampler Format Engine" +    "VERSION: 1.110" +    "." + C: "GET ENGINE INFO sf2" + S: "DESCRIPTION: SoundFont Format Engine" +    "VERSION: 1.4" +    "." + C: "GET ENGINE INFO sfz" + S: "DESCRIPTION: SFZ Format Engine" +    "VERSION: 1.11"    "."
-
+
The front-end can ask for the current settings of a sampler channel by sending the following command: @@ -2494,7 +2522,7 @@ numerical ID of the audio output device which is currently connected to this sampler channel to output - the audio signal, "NONE" if there's no device + the audio signal, "-1" if there's no device connected to this sampler channel @@ -2519,37 +2547,61 @@ the file name of the loaded instrument, "NONE" if there's no instrument yet loaded for this sampler - channel + channel (note: since LSCP 1.2 this path may contain + escape sequences) INSTRUMENT_NR - - the instrument index number of the loaded instrument + the instrument index number of the loaded instrument, + "-1" if there's no instrument loaded for this sampler + channel INSTRUMENT_NAME - - the instrument name of the loaded instrument + the instrument name of the loaded instrument + (note: since LSCP 1.2 this character string may contain + escape sequences) INSTRUMENT_STATUS - - integer values 0 to 100 indicating loading progress percentage for the instrument. Negative - value indicates a loading exception. Value of 100 indicates that the instrument is fully + Integer values 0 to 100 indicating loading progress + percentage for the instrument. Negative + value indicates a loading exception (also returns "-1" in case no + instrument was yet to be loaded on the sampler channel). + Value of 100 indicates that the instrument is fully loaded. MIDI_INPUT_DEVICE - + DEPRECATED: THIS FIELD WILL DISAPPEAR! numerical ID of the MIDI input device which is currently connected to this sampler channel to deliver - MIDI input commands, "NONE" if there's no device + MIDI input commands, "-1" if there's no device connected to this sampler channel + Should not be used anymore as of LSCP v1.6 and younger. + This field is currently only preserved for backward compatibility. + + This field a relict from times where only one MIDI input per + sampler channel was allowed. Use "GET CHANNEL MIDI_INPUTS" + instead. MIDI_INPUT_PORT - - port number of the MIDI input device + DEPRECATED: THIS FIELD WILL DISAPPEAR! + port number of the MIDI input device (in case a + MIDI device was already assigned to the sampler + channel) + Should not be used anymore as of LSCP v1.6 and younger. + This field is currently only preserved for backward compatibility. + + This field a relict from times where only one MIDI input per + sampler channel was allowed. Use "GET CHANNEL MIDI_INPUTS" + instead. MIDI_INPUT_CHANNEL - @@ -2598,7 +2650,7 @@ C: "GET CHANNEL INFO 34" - S: "ENGINE_NAME: GigEngine" + S: "ENGINE_NAME: gig"    "VOLUME: 1.0"    "AUDIO_OUTPUT_DEVICE: 0"    "AUDIO_OUTPUT_CHANNELS: 2" @@ -2619,7 +2671,7 @@
-
+
The front-end can ask for the current number of active voices on a sampler channel by sending the following command: @@ -2646,7 +2698,7 @@
-
+
The front-end can ask for the current number of active disk streams on a sampler channel by sending the following command: @@ -2675,7 +2727,7 @@
-
+
The front-end can ask for the current fill state of all disk streams on a sampler channel by sending the following command: @@ -2728,7 +2780,7 @@
-
+
The front-end can set the audio output device on a specific sampler channel by sending the following command: @@ -2774,8 +2826,8 @@
-
- DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON! +
+ DEPRECATED: THIS COMMAND WILL DISAPPEAR! The front-end can alter the audio output type on a specific sampler channel by sending the following command: @@ -2815,9 +2867,16 @@ + Deprecated: + + + Should not be used anymore. This command is currently only preserved for backward compatibility. + This command is a relict from times where there was no sophisticated driver management yet. Use "CREATE AUDIO_OUTPUT_DEVICE" and "SET CHANNEL AUDIO_OUTPUT_DEVICE" instead. + +
-
+
The front-end can alter the audio output channel on a specific sampler channel by sending the following command: @@ -2862,7 +2921,188 @@
-
+
+ The front-end can add a MIDI input on a specific sampler + channel by sending the following command: + + + ADD CHANNEL MIDI_INPUT <sampler-channel> <midi-device-id> [<midi-input-port>] + + + Where <sampler-channel> is the sampler channel number + as returned by the "ADD CHANNEL" + or "LIST CHANNELS" command + and <midi-device-id> is the numerical ID of the MIDI input + device as returned by the + "CREATE MIDI_INPUT_DEVICE" + or "LIST MIDI_INPUT_DEVICES" command, + and <midi-input-port> is an optional MIDI input port number of that + MIDI input device. If <midi-input-port> is omitted, + then the MIDI input device's first port (port number 0) is + used. + + + Possible Answers: + + + "OK" - + + on success + + + "WRN:<warning-code>:<warning-message>" - + + if MIDI input port was connected, 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 + + + + + Examples: + + + C: "ADD CHANNEL MIDI_INPUT 0 0" + S: "OK" + C: "ADD CHANNEL MIDI_INPUT 1 0" + S: "OK" + C: "ADD CHANNEL MIDI_INPUT 1 1 1" + S: "OK" + C: "ADD CHANNEL MIDI_INPUT 1 2 0" + S: "OK" + + + Since: + + + Introduced with LSCP v1.6 + + +
+ +
+ The front-end can remove one ore more MIDI input(s) on a + specific sampler channel by sending the following command: + + + REMOVE CHANNEL MIDI_INPUT <sampler-channel> [<midi-device-id> [<midi-input-port>]] + + + Where <sampler-channel> is the sampler channel number + as returned by the "ADD CHANNEL" + or "LIST CHANNELS" command + and <midi-device-id> and <midi-input-port> are + optional numerical IDs defining the MIDI input device and + one of its MIDI ports as returned by the + "LIST CHANNEL MIDI_INPUTS" command. + + + + If <midi-input-port> is omitted, then all MIDI input + ports of <midi-device-id> are disconnected from this + sampler channel. + + + + If both, <midi-device-id> and <midi-input-port> + are omitted, then all MIDI input ports currently connected + to this sampler channel are disconnected from this sampler + channel. + + + Possible Answers: + + + "OK" - + + on success + + + "WRN:<warning-code>:<warning-message>" - + + if MIDI input porst were disconnected, 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 + + + + + Examples: + + + C: "REMOVE CHANNEL MIDI_INPUT 0" + S: "OK" + C: "REMOVE CHANNEL MIDI_INPUT 1" + S: "OK" + C: "REMOVE CHANNEL MIDI_INPUT 1 2 0" + S: "OK" + + + Since: + + + Introduced with LSCP v1.6 + + +
+ +
+ The front-end can query a list of all currently connected + MIDI inputs of a certain sampler channel by sending the following + command: + + + LIST CHANNEL MIDI_INPUTS <sampler-channel> + + + Where <sampler-channel> is the sampler channel number + as returned by the "ADD CHANNEL" + or "LIST CHANNELS" command. + + + Possible Answers: + + + The sampler will answer by sending a comma separated + list of MIDI input device ID - MIDI input port number pairs, where + each pair is encapsulated into curly braces. The + list is returned in one single line. The MIDI input + device ID corresponds to the number returned by + "LIST MIDI_INPUT_DEVICES" + and the port number is the index of the respective MIDI + port of that MIDI input device. + + + + Example: + + + C: "LIST CHANNEL MIDI_INPUTS 0" + S: "{0,0},{1,3},{2,0}" + + + + Since: + + + Introduced with LSCP v1.6 + + +
+ +
+ DEPRECATED: THIS COMMAND WILL DISAPPEAR! + The front-end can set the MIDI input device on a specific sampler channel by sending the following command: @@ -2877,6 +3117,16 @@ "CREATE MIDI_INPUT_DEVICE" or "LIST MIDI_INPUT_DEVICES" command. + + If more than 1 MIDI inputs are currently connected to this + sampler channel: Sending this command will disconnect ALL + currently connected MIDI input ports connected to this + sampler channel before establishing the new MIDI input + connection. So this command does NOT add the connection, + it replaces all existing ones instead. This behavior is due + to preserving full behavior backward compatibility. + + Possible Answers: @@ -2905,10 +3155,17 @@ + Deprecated: + + + Should not be used anymore as of LSCP v1.6 and younger. This command is currently only preserved for backward compatibility. + This command is a relict from times where only one MIDI input per sampler channel was allowed. Use "ADD CHANNEL MIDI_INPUT" and "REMOVE CHANNEL MIDI_INPUT" instead. + +
-
- DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON! +
+ DEPRECATED: THIS COMMAND WILL DISAPPEAR! The front-end can alter the MIDI input type on a specific sampler channel by sending the following command: @@ -2920,6 +3177,16 @@ Where <midi-input-type> is currently only "ALSA" and <sampler-channel> is the respective sampler channel number. + + If more than 1 MIDI inputs are currently connected to this + sampler channel: Sending this command will disconnect ALL + currently connected MIDI input ports connected to this + sampler channel before establishing the new MIDI input + connection. So this command does NOT add the connection, + it replaces all existing ones instead. This behavior is due + to preserving full behavior backward compatibility. + + Possible Answers: @@ -2948,9 +3215,18 @@ + Deprecated: + + + Should not be used anymore. This command is currently only preserved for backward compatibility. + This command is a relict from times where only 1 MIDI input per sampler channels was allowed and where no sophisticated driver management existed yet. Use "ADD CHANNEL MIDI_INPUT" and "REMOVE CHANNEL MIDI_INPUT" instead. + +
-
+
+ DEPRECATED: THIS COMMAND WILL DISAPPEAR! + The front-end can alter the MIDI input port on a specific sampler channel by sending the following command: @@ -2961,6 +3237,19 @@ Where <midi-input-port> is a MIDI input port number of the MIDI input device connected to the sampler channel given by <sampler-channel>. + + + If more than 1 MIDI inputs are currently connected to this + sampler channel: Sending this command will switch the + connection of the first (and only the first) MIDI input port + currently being connected to this sampler channel, to + another port of the same MIDI input device. Or in other + words: the first MIDI input port currently connected to + this sampler channel will be disconnected, and the requested + other port of its MIDI input device will be connected to + this sampler channel instead. This behavior is due + to preserving full behavior backward compatibility. + Possible Answers: @@ -2990,9 +3279,16 @@ + Deprecated: + + + Should not be used anymore. This command is currently only preserved for backward compatibility. + This command is a relict from times where only one MIDI input per sampler channel was allowed. Use "ADD CHANNEL MIDI_INPUT" and "REMOVE CHANNEL MIDI_INPUT" instead. + +
-
+
The front-end can alter the MIDI channel a sampler channel should listen to by sending the following command: @@ -3000,8 +3296,9 @@ SET CHANNEL MIDI_INPUT_CHANNEL <sampler-channel> <midi-input-chan> - Where <midi-input-chan> is the number of the new MIDI input channel where - <sampler-channel> should listen to or "ALL" to listen on all 16 MIDI + Where <midi-input-chan> is the number + of the new MIDI input channel (zero indexed!) where + <sampler-channel> should listen to, or "ALL" to listen on all 16 MIDI channels. Possible Answers: @@ -3029,12 +3326,15 @@ Examples: - + C: "SET CHANNEL MIDI_INPUT_CHANNEL 0 0" + S: "OK" + C: "SET CHANNEL MIDI_INPUT_CHANNEL 1 ALL" + S: "OK"
-
+
The front-end can alter the volume of a sampler channel by sending the following command: @@ -3077,7 +3377,7 @@
-
+
The front-end can mute/unmute a specific sampler channel by sending the following command: @@ -3121,7 +3421,7 @@
-
+
The front-end can solo/unsolo a specific sampler channel by sending the following command: @@ -3165,7 +3465,7 @@
-
+
The front-end can assign a MIDI instrument map to a specific sampler channel by sending the following command: @@ -3233,7 +3533,7 @@
-
+
The front-end can create an additional effect send on a specific sampler channel by sending the following command: @@ -3247,15 +3547,25 @@ 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". + for the effect send entity. The name does not have to be unique, but MUST be + encapsulated into apostrophes and supports escape sequences as described in chapter + "Character Set and Escape Sequences". + + Note: there are two possible approaches to apply audio effects with FX sends: + you can either use a) internal effects or b) external effects. + By default, that is as initial routing, effect sends are automatically routed + directly to the sampler channel's audio output device and the effect send's + audio channels are by default automatically routed to the last audio channels + of that audio output device (for the purpose of applying effects externally that is, + e.g. by using another application), 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". + If your intention is rather to use internal effects instead of external effects, + then you first need to load those internal effects + and then assign the FX sends to the desired internal effect by sending + "SET FX_SEND EFFECT". Note: Create effect sends on a sampler channel only when needed, because having effect @@ -3301,7 +3611,7 @@
-
+
The front-end can remove an existing effect send on a specific sampler channel by sending the following command: @@ -3343,7 +3653,7 @@
-
+
The front-end can ask for the amount of effect sends on a specific sampler channel by sending the following command: @@ -3372,7 +3682,7 @@
-
+
The front-end can ask for a list of effect sends on a specific sampler channel by sending the following command: @@ -3408,7 +3718,7 @@
-
+
The front-end can ask for the current settings of an effect send entity by sending the following command: @@ -3437,7 +3747,9 @@ NAME - - name of the effect send entity + name of the effect send entity + (note that this character string may contain + escape sequences) MIDI_CONTROLLER - @@ -3463,7 +3775,21 @@ channel 1 is routed to the channel 3 of the audio output device (see "SET FX_SEND AUDIO_OUTPUT_CHANNEL" - for details) + for details), if an internal send + effect is assigned to the effect + send, then this setting defines the + audio channel routing to that + effect instance respectively + + + EFFECT - + + destination send effect chain ID + and destination effect chain + position, separated by comma in the + form "<effect-chain>,<chain-pos>" + or "NONE" if there is no send effect + assigned to the effect send @@ -3480,12 +3806,24 @@    "MIDI_CONTROLLER: 91"    "LEVEL: 0.3"    "AUDIO_OUTPUT_ROUTING: 2,3" +    "EFFECT: NONE" +    "." + + + + + C: "GET FX_SEND INFO 0 1" + S: "NAME: Delay Send (Internal)" +    "MIDI_CONTROLLER: 93" +    "LEVEL: 0.51" +    "AUDIO_OUTPUT_ROUTING: 1,2" +    "EFFECT: 2,0"    "."
-
+
The front-end can alter the current name of an effect send entity by sending the following command: @@ -3500,7 +3838,10 @@ as returned by the "CREATE FX_SEND" or "LIST FX_SENDS" command and <name> is the new name of the effect send entity, which - does not have to be unique. + does not have to be unique (name MUST be encapsulated into apostrophes + and supports escape sequences as described in chapter + "Character Set and Escape Sequences"). + Possible Answers: @@ -3526,7 +3867,7 @@
-
+
The front-end can alter the destination of an effect send's audio channel on a specific sampler channel by sending the following command: @@ -3542,8 +3883,10 @@ or "LIST FX_SENDS" 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. + either a) the audio output channel of the sampler channel's audio output + device (i.e. if external effect shall be applied) or b) of the audio + input channel of an internal effect assigned to the FX send 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 @@ -3586,7 +3929,109 @@
-
+
+ The front-end can (re-)assign an internal destination effect to an + effect send by sending the following command: + + + SET FX_SEND EFFECT <sampler-chan> <fx-send-id> <effect-chain> <chain-pos> + + + Where <sampler-chan> is the sampler channel number + as returned by the "ADD CHANNEL" + or "LIST CHANNELS" command, + <fx-send-id> reflects the numerical ID of the effect send entity + as returned by the "CREATE FX_SEND" + or "LIST FX_SENDS" command, + <effect-chain> by the numerical ID of the destination + effect chain as returned by the + "ADD SEND_EFFECT_CHAIN" + or + "LIST SEND_EFFECT_CHAINS" + command and <chain-pos> reflects the exact effect + chain position in the effect chain which hosts the actual + destination effect. + + Note: This command MUST NOT be used if you want to apply + audio effects externally! By default FX sends are routed directly + to the audio output device for that purpose. + You can also revert this command later on by sending + "REMOVE FX_SEND EFFECT", + which will cause the FX send to be routed directly to the sampler channel's + audio output device instead (i.e. for using external effects instead of + internal effects). + + + 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 EFFECT 0 0 2 5" + S: "OK" + + +
+ +
+ The front-end can (re-)assign a destination effect to an + effect send by sending the following command: + + + REMOVE FX_SEND EFFECT <sampler-chan> <fx-send-id> + + + Where <sampler-chan> is the sampler channel number + as returned by the "ADD CHANNEL" + or "LIST CHANNELS" command, + <fx-send-id> reflects the numerical ID of the effect send entity + as returned by the "CREATE FX_SEND" + or "LIST FX_SENDS" command. + + After the destination effect has been removed from the + effect send, the audio signal of the effect send will be + routed directly to the audio output device, according to the + audio channel routing setting of the effect send. + + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + in case it failed, providing an appropriate error code and error message + + + + + Example: + + + C: "REMOVE FX_SEND EFFECT 0 0" + S: "OK" + + +
+ +
The front-end can alter the MIDI controller of an effect send entity by sending the following command: @@ -3634,7 +4079,7 @@
-
+
The front-end can alter the current send level of an effect send entity by sending the following command: @@ -3683,7 +4128,72 @@
-
+
+ The front-end can send MIDI events to a specific sampler channel + by sending the following command: + + + SEND CHANNEL MIDI_DATA <midi-msg> <sampler-chan> <arg1> <arg2> + + + Where <sampler-chan> is the sampler channel number + as returned by the "ADD CHANNEL" + or "LIST CHANNELS" command, + <arg1> and <arg2> arguments depend on the <midi-msg> argument, which + specifies the MIDI message type. Currently, the following MIDI messages are supported: + + + "NOTE_ON" - + + For turning on MIDI notes, where <arg1> + specifies the key number and <arg2> the velocity + as described in the MIDI specification. + + + "NOTE_OFF" - + + For turning a currently playing MIDI note off, where <arg1> + specifies the key number and <arg2> the velocity + as described in the MIDI specification. + + + "CC" - + + For changing a MIDI controller, where <arg1> + specifies the controller number and <arg2> the + new value of the controller as described in the Control + Change section of the MIDI specification. + + + + + CAUTION: This command is provided for implementations of virtual MIDI keyboards + and no realtime guarantee whatsoever will be made! + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + in case it failed, providing an appropriate error code and error message + + + + + Example: + + + C: "SEND CHANNEL MIDI_DATA NOTE_ON 0 56 112" + S: "OK" + + +
+ +
The front-end can reset a particular sampler channel by sending the following command: @@ -3731,7 +4241,7 @@
The following commands are used to control the connection to LinuxSampler. -
+
The front-end can register itself to the LinuxSampler application to be informed about noteworthy events by sending this command: @@ -3773,7 +4283,7 @@
-
+
The front-end can unregister itself if it doesn't want to receive event messages anymore by sending the following command: @@ -3815,7 +4325,7 @@
-
+
To enable or disable back sending of commands to the client the following command can be used: @@ -3853,7 +4363,7 @@
-
+
The client can close its network connection to LinuxSampler by sending the following command: @@ -3868,7 +4378,7 @@
The following commands have global impact on the sampler. -
+
The front-end can ask for the current number of active voices on the sampler by sending the following command: @@ -3886,7 +4396,7 @@
-
+
The front-end can ask for the maximum number of active voices by sending the following command: @@ -3904,6 +4414,24 @@
+
+ The front-end can ask for the current number of active disk streams on + the sampler by sending the following command: + + + GET TOTAL_STREAM_COUNT + + + + Possible Answers: + + + LinuxSampler will answer by returning the number of all active + disk streams on the sampler. + + +
+
The front-end can reset the whole sampler by sending the following command: @@ -3930,8 +4458,8 @@
-
- The client can ask for general informations about the LinuxSampler +
+ The client can ask for general information about the LinuxSampler instance by sending the following command: @@ -3951,7 +4479,9 @@ DESCRIPTION - - arbitrary textual description about the sampler + arbitrary textual description about the sampler + (note that the character string may contain + escape sequences) VERSION - @@ -3977,9 +4507,21 @@ The mentioned fields above don't have to be in particular order. Other fields might be added in future. + + Example: + + + C: "GET SERVER INFO" + S: "DESCRIPTION: LinuxSampler - modular, streaming capable sampler" +    "VERSION: 1.0.0.svn23" +    "PROTOCOL_VERSION: 1.5" +    "INSTRUMENTS_DB_SUPPORT: no" +    "." + +
-
+
The client can ask for the current global sampler-wide volume attenuation by sending the following command: @@ -4001,7 +4543,7 @@ use this parameter.
-
+
The client can alter the current global sampler-wide volume attenuation by sending the following command: @@ -4037,6 +4579,143 @@
+ +
+ The client can ask for the current global sampler-wide limit + for maximum voices by sending the following command: + + + GET VOICES + + + Possible Answers: + + + LinuxSampler will answer by returning the number for + the current limit of maximum voices. + + + + The voice limit setting defines how many voices should maximum + be processed by the sampler at the same time. If the user + triggers new notes which would exceed that voice limit, the + sampler engine will react by stealing old voices for those + newly triggered notes. Note that the amount of voices triggered + by a new note can be larger than one and is dependent to the + respective instrument and probably further criterias. +
+ +
+ The client can alter the current global sampler-wide limit + for maximum voices by sending the following command: + + + SET VOICES <max-voices> + + + Where <max-voices> should be replaced by the integer + value, reflecting the new global amount limit of maximum voices. + This value has to be larger than 0. + + Possible Answers: + + + "OK" - + + on success + + + "WRN:<warning-code>:<warning-message>" - + + if the voice limit 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 + + + + + + Note: the given value will be passed to all sampler engine instances. + The total amount of maximum voices on the running system might thus + be as big as the given value multiplied by the current amount of engine + instances. + + Caution: when adjusting the voice limit, you SHOULD also + adjust the disk stream limit respectively and vice versa. +
+ +
+ The client can ask for the current global sampler-wide limit + for maximum disk streams by sending the following command: + + + GET STREAMS + + + Possible Answers: + + + LinuxSampler will answer by returning the number for + the current limit of maximum disk streams. + + + + The disk stream limit setting defines how many disk streams should + maximum be processed by a sampler engine at the same time. The + higher this value, the more memory (RAM) will be occupied, since + every disk streams allocates a certain buffer size for being able + to perform its streaming operations. +
+ +
+ The client can alter the current global sampler-wide limit + for maximum disk streams by sending the following command: + + + SET STREAMS <max-streams> + + + Where <max-streams> should be replaced by the integer + value, reflecting the new global amount limit of maximum disk streams. + This value has to be positive. + + Possible Answers: + + + "OK" - + + on success + + + "WRN:<warning-code>:<warning-message>" - + + if the disk stream limit 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 + + + + + + Note: the given value will be passed to all sampler engine instances. + The total amount of maximum disk streams on the running system might + thus be as big as the given value multiplied by the current amount of + engine instances. + + Caution: when adjusting the disk stream limit, you SHOULD also + adjust the voice limit respectively and vice versa. +
+
@@ -4067,7 +4746,7 @@ cause the sampler to switch to the respective instrument as reflected by the current MIDI instrument map. -
+
The front-end can add a new MIDI instrument map by sending the following command: @@ -4077,7 +4756,10 @@ 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. + names do not have to be unique, but MUST be encapsulated + into apostrophes and support escape sequences as described + in chapter "Character Set and Escape Sequences". + Possible Answers: @@ -4120,7 +4802,7 @@
-
+
The front-end can delete a particular MIDI instrument map by sending the following command: @@ -4170,7 +4852,7 @@
-
+
The front-end can retrieve the current amount of MIDI instrument maps by sending the following command: @@ -4196,7 +4878,7 @@
-
+
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: @@ -4221,7 +4903,7 @@
-
+
The front-end can ask for the current settings of a MIDI instrument map by sending the following command: @@ -4248,7 +4930,9 @@ NAME - custom name of the given map, - which does not have to be unique + which does not have to be unique + (note that this character string may contain + escape sequences) DEFAULT - @@ -4274,7 +4958,7 @@
-
+
The front-end can alter the custom name of a MIDI instrument map by sending the following command: @@ -4284,7 +4968,10 @@ 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. + have to be unique (name MUST be encapsulated into apostrophes + and supports escape sequences as described in chapter + "Character Set and Escape Sequences"). + Possible Answers: @@ -4311,7 +4998,7 @@
-
+
The front-end can create a new or replace an existing entry in a sampler's MIDI instrument map by sending the following command: @@ -4415,9 +5102,10 @@ load modes of entries, the frontend should retrieve the actual mode by i.e. sending "GET MIDI_INSTRUMENT INFO" - 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 + command(s). Finally the OPTIONAL <name> argument allows to set a custom name + (encapsulated into apostrophes, supporting escape sequences as described in chapter + "Character Set and Escape Sequences") for the + mapping entry, useful for frontends for displaying an appropriate name for mapped instruments (using "GET MIDI_INSTRUMENT INFO"). @@ -4483,7 +5171,7 @@
-
+
The front-end can query the amount of currently existing entries in a MIDI instrument map by sending the following command: @@ -4523,7 +5211,7 @@
-
+
The front-end can query a list of all currently existing entries in a certain MIDI instrument map by sending the following command: @@ -4552,7 +5240,7 @@ just reflects the key of the respective map entry, thus subsequent "GET MIDI_INSTRUMENT INFO" - command(s) are necessary to retrieve detailed informations + command(s) are necessary to retrieve detailed information about each entry. @@ -4566,7 +5254,7 @@
-
+
The front-end can delete an entry from a MIDI instrument map by sending the following command: @@ -4608,7 +5296,7 @@
-
+
The front-end can retrieve the current settings of a certain instrument map entry by sending the following command: @@ -4641,7 +5329,9 @@ name for this mapped instrument. It can be set and changed with the "MAP MIDI_INSTRUMENT" - command and does not have to be unique. + command and does not have to be unique. + (note that this character string may contain + escape sequences) "ENGINE_NAME" - @@ -4652,7 +5342,9 @@ "INSTRUMENT_FILE" - - File name of the instrument. + File name of the instrument + (note that this path may contain + escape sequences). "INSTRUMENT_NR" - @@ -4664,7 +5356,8 @@ Name of the loaded instrument as reflected by its file. In contrast to the "NAME" field, the "INSTRUMENT_NAME" field - cannot be changed. + cannot be changed (note that this character string may contain + escape sequences). "LOAD_MODE" - @@ -4700,7 +5393,7 @@
-
+
The front-end can clear a whole MIDI instrument map, that is delete all its entries by sending the following command: @@ -4752,8 +5445,20 @@
The following commands describe how to use and manage the instruments database. + Notice: + + + All command arguments representing a path or + instrument/directory name support escape sequences as described in chapter + "Character Set and Escape Sequences". + + All occurrences of a forward slash in instrument and directory + names are escaped with its hex (\x2f) or octal (\057) escape sequence. + + + -
+
The front-end can add a new instrument directory to the instruments database by sending the following command: @@ -4791,7 +5496,7 @@
-
+
The front-end can delete a particular instrument directory from the instruments database by sending the following command: @@ -4830,7 +5535,7 @@
-
+
The front-end can retrieve the current amount of directories in a specific directory by sending the following command: @@ -4865,7 +5570,7 @@
-
+
The front-end can retrieve the current list of directories in specific directory by sending the following command: @@ -4905,7 +5610,7 @@
-
+
The front-end can ask for the current settings of an instrument directory by sending the following command: @@ -4929,7 +5634,9 @@ DESCRIPTION - - A brief description of the directory content + A brief description of the directory content. + Note that the character string may contain + escape sequences. CREATED - @@ -4962,7 +5669,7 @@
-
+
The front-end can alter the name of a specific instrument directory by sending the following command: @@ -5000,7 +5707,7 @@
-
+
The front-end can move a specific instrument directory by sending the following command: @@ -5042,7 +5749,7 @@
-
+
The front-end can copy a specific instrument directory by sending the following command: @@ -5084,7 +5791,7 @@
-
+
The front-end can alter the description of a specific instrument directory by sending the following command: @@ -5093,7 +5800,9 @@ Where <dir> is the absolute path name of the directory and - <desc> is the new description for the directory. + <desc> is the new description for the directory + (encapsulated into apostrophes, supporting escape sequences as described in chapter + "Character Set and Escape Sequences"). Possible Answers: @@ -5120,7 +5829,7 @@
-
+
The front-end can search for directories in specific directory by sending the following command: @@ -5138,7 +5847,9 @@ NAME='<search-string>' Restricts the search to directories, which names - satisfy the supplied search string. + satisfy the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences"). @@ -5169,7 +5880,10 @@ DESCRIPTION='<search-string>' Restricts the search to directories with description - that satisfies the supplied search string. + that satisfies the supplied search string + (encapsulated into apostrophes, supporting escape + sequences as described in chapter + "Character Set and Escape Sequences"). @@ -5205,12 +5919,12 @@
-
+
The front-end can add one or more instruments to the instruments database by sending the following command: - ADD DB_INSTRUMENTS [NON_MODAL] [<mode>] <db_dir> <file_path> [<instr_index>] + ADD DB_INSTRUMENTS [NON_MODAL] [<mode>[ FILE_AS_DIR]] <db_dir> <file_path> [<instr_index>] Where <db_dir> is the absolute path name of a directory @@ -5255,6 +5969,10 @@ + If FILE_AS_DIR argument is supplied, all instruments in an instrument + file will be added to a separate directory in the instruments database, which + name will be the name of the instrument file with the file extension stripped off. + The difference between regular and NON_MODAL versions of the command is that the regular command returns when the scanning is finished while NON_MODAL version returns immediately and a background process is launched. @@ -5294,7 +6012,7 @@
-
+
The front-end can remove a particular instrument from the instruments database by sending the following command: @@ -5331,7 +6049,7 @@
-
+
The front-end can retrieve the current amount of instruments in a specific directory by sending the following command: @@ -5366,7 +6084,7 @@
-
+
The front-end can retrieve the current list of instruments in specific directory by sending the following command: @@ -5406,7 +6124,7 @@
-
+
The front-end can ask for the current settings of an instrument by sending the following command: @@ -5430,7 +6148,9 @@ INSTRUMENT_FILE - - File name of the instrument. + File name of the instrument. + Note that the character string may contain + escape sequences. INSTRUMENT_NR - @@ -5469,7 +6189,9 @@ DESCRIPTION - - A brief description of the instrument + A brief description of the instrument. + Note that the character string may contain + escape sequences. IS_DRUM - @@ -5480,18 +6202,24 @@ PRODUCT - - The product title of the instrument + The product title of the instrument. + Note that the character string may contain + escape sequences. ARTISTS - - Lists the artist names + Lists the artist names. + Note that the character string may contain + escape sequences. KEYWORDS - Provides a list of keywords that refer to the instrument. - Keywords are separated with semicolon and blank. + Keywords are separated with semicolon and blank. + Note that the character string may contain + escape sequences. @@ -5521,7 +6249,7 @@
-
+
The front-end can alter the name of a specific instrument by sending the following command: @@ -5559,7 +6287,7 @@
-
+
The front-end can move a specific instrument to another directory by sending the following command: @@ -5599,7 +6327,7 @@
-
+
The front-end can copy a specific instrument to another directory by sending the following command: @@ -5639,7 +6367,7 @@
-
+
The front-end can alter the description of a specific instrument by sending the following command: @@ -5648,7 +6376,9 @@ Where <instr> is the absolute path name of the instrument and - <desc> is the new description for the instrument. + <desc> is the new description for the instrument + (encapsulated into apostrophes, supporting escape sequences as described in chapter + "Character Set and Escape Sequences"). Possible Answers: @@ -5675,7 +6405,7 @@
-
+
The front-end can search for instruments in specific directory by sending the following command: @@ -5693,7 +6423,9 @@ NAME='<search-string>' Restricts the search to instruments, which names - satisfy the supplied search string. + satisfy the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences"). @@ -5735,28 +6467,36 @@ DESCRIPTION='<search-string>' Restricts the search to instruments with description - that satisfies the supplied search string. + that satisfies the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences"). PRODUCT='<search-string>' Restricts the search to instruments with product info - that satisfies the supplied search string. + that satisfies the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences"). ARTISTS='<search-string>' Restricts the search to instruments with artists info - that satisfies the supplied search string. + that satisfies the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences"). KEYWORDS='<search-string>' Restricts the search to instruments with keyword list - that satisfies the supplied search string. + that satisfies the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences"). @@ -5806,7 +6546,7 @@
-
+
The front-end can ask for the current status of a particular database instruments job by sending the following command: @@ -5870,11 +6610,1404 @@
+
+ The front-end can remove all instruments and directories and re-create + the instruments database structure (e.g., in case of a database corruption) + by sending the following command: + + + FORMAT INSTRUMENTS_DB + + + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + If the formatting of the instruments database + failed. + + + + +
+ +
+ The front-end can retrieve the list of all instrument files in the instruments database + that don't exist in the filesystem by sending the following command: + + + FIND LOST DB_INSTRUMENT_FILES + + + + Possible Answers: + + + A comma separated list with the absolute path names + (encapsulated into apostrophes) of all lost instrument files. + "ERR:<error-code>:<error-message>" - + + in case it failed, providing an appropriate error code and error message. + + + + + Example: + + + C: "FIND LOST DB_INSTRUMENT_FILES" + S: "'/gigs/Bosendorfer 290.gig','/gigs/Steinway D.gig','/gigs/Free Piano.gig'" + + +
+ +
+ The front-end can substitute all occurrences of an instrument file + in the instruments database with a new one by sending the following command: + + + SET DB_INSTRUMENT FILE_PATH <old_path> <new_path> + + + Where <old_path> is the absolute path name of the instrument file + to substitute with <new_path>. + + 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 DB_INSTRUMENT FILE_PATH '/gigs/Bosendorfer 290.gig' '/gigs/pianos/Bosendorfer 290.gig'" + S: "OK" + + +
+
-
+
+ The sampler allows to edit instruments while playing with the + sampler by spawning an external (3rd party) instrument editor + application for a given instrument. The 3rd party instrument + editor applications have to place a respective plugin DLL file + into the sampler's plugins directory. The sampler will + automatically try to load all plugin DLLs in that directory on + startup and only on startup! + At the moment there is only one command for this feature set, + but this will most probably change in future. + +
+ The front-end can request to open an appropriate instrument + editor application by sending the following command: + + + EDIT CHANNEL INSTRUMENT <sampler-channel> + + + Where <sampler-channel> should be replaced by the + number of the sampler channel as given by the + "ADD CHANNEL" + or "LIST CHANNELS" + command. + + The sampler will try to ask all registered instrument + editors (or to be more specific: their sampler plugins) + whether they are capable to handle the instrument on the + given sampler channel. The sampler will simply use the first + instrument editor application which replied with a positive + answer and spawn that instrument editor application within + the sampler's process and provide that application access + to the instrument's data structures, so both applications + can share and access the same instruments data at the same + time, thus allowing to immediately hear changes with the + sampler made by the instrument editor. + + Note: consequently instrument editors are always spawned + locally on the same machine where the sampler is running + on! + + Possible Answers: + + + "OK" - + + when an appropriate instrument editor was + launched + + + "WRN:<warning-code>:<warning-message>" - + + when an appropriate instrument editor was + launched, but there are noteworthy issues + + + "ERR:<error-code>:<error-message>" - + + when an appropriate instrument editor + could not be launched + + + + + + Examples: + + + C: "EDIT CHANNEL INSTRUMENT 0" + S: "OK" + + +
+
+ +
+ You can query detailed information about files located + at the same system where the sampler instance is running on. + Using this command set allows to retrieve file information + even remotely from another machine. + +
+ The front-end can retrieve the amount of instruments + within a given instrument file by sending the + following command: + + + GET FILE INSTRUMENTS <filename> + + + Where <filename> is the name of the instrument + file (encapsulated into apostrophes, supporting escape + sequences as described in chapter + "Character Set and Escape + Sequences"). + + The sampler will try to ask all sampler engines, + whether they support the given file and ask the first + engine with a positive answer for the amount of + instruments. + + Possible Answers: + + + On success, the sampler will answer by + returning the amount of instruments. + + "ERR:<error-code>:<error-message>" - + + if the file could not be handled + + + + + + Examples: + + + C: "GET FILE INSTRUMENTS 'D:/Sounds/Foo.gig'" + S: "10" + + +
+ +
+ The front-end can retrieve a list of all instruments + within a given instrument file by sending the + following command: + + + LIST FILE INSTRUMENTS <filename> + + + Where <filename> is the name of the instrument + file (encapsulated into apostrophes, supporting escape + sequences as described in chapter + "Character Set and Escape + Sequences"). + + The sampler will try to ask all sampler engines, + whether they support the given file and ask the first + engine with a positive answer for a list of IDs for the + instruments in the given file. + + Possible Answers: + + + On success, the sampler will answer by + returning a comma separated list of + instrument IDs. + + "ERR:<error-code>:<error-message>" - + + if the file could not be handled + + + + + + Examples: + + + C: "LIST FILE INSTRUMENTS 'D:/Sounds/Foo.gig'" + S: "0,1,2,3,4,5,6,7,8,9" + + +
+ +
+ The front-end can retrieve detailed information + about a specific instrument within a given instrument + file by sending the following command: + + + GET FILE INSTRUMENT INFO <filename> + <instr-id> + + + Where <filename> is the name of the instrument + file (encapsulated into apostrophes, supporting escape + sequences as described in chapter + "Character Set and Escape + Sequences") and <instr-id> is the numeric + instrument ID as returned by the + + "LIST FILE INSTRUMENTS" command. + + The sampler will try to ask all sampler engines, + whether they support the given file and ask the first + engine with a positive answer for information about the + specific instrument in the given file. + + 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 - + + name of the instrument as + stored in the instrument file + + + FORMAT_FAMILY - + + name of the sampler format + of the given instrument + + + FORMAT_VERSION - + + version of the sampler format + the instrumen is stored as + + + PRODUCT - + + official product name of the + instrument as stored in the file + + + + ARTISTS - + + artists / sample library + vendor of the instrument + + + KEY_BINDINGS - + + comma separated list of integer values representing + the instrument's key mapping in the range between 0 .. 127, + reflecting the analog meaning of the MIDI specification. + + + KEYSWITCH_BINDINGS - + + comma separated list of integer values representing + the instrument's keyswitch mapping in the range between 0 .. 127, + reflecting the analog meaning of the MIDI specification. + + + + + + + The mentioned fields above don't have to be in particular order. + + Example: + + + C: "GET FILE INSTRUMENT INFO 'D:/Sounds/Foo.gig' 0" + S: "NAME: Lunatic Loops" +    "FORMAT_FAMILY: GIG" +    "FORMAT_VERSION: 3" +    "PRODUCT: The Backbone Bongo Beats" +    "ARTISTS: Jimmy the Fish" +    "." + + +
+
+
+ There are two possible approaches to apply audio effects + (e.g. reverb, delay, compression). + You can either a) load and apply internal effects or you can b) route + effect sends directly to dedicated output channels of your + audio device and apply effects externally (e.g. by routing + those dedicated output channels to another application). + This chapter describes how to load and manage internal effects. + If your intention is rather to apply effects externally, then + you can omit this chapter. For applying effects externally, you + just need to create FX sends + on the respective sampler channel(s) + and adjust their destination audio channels + appropriately, because by default FX sends are automatically routed + directly to the audio output device. + The sampler usually provides a set of internal audio effects. + The exact set of effects depends on the availability + of third party effect plugins installed on the system where the + sampler runs on (e.g. LADSPA plugins). + At the moment only "send effects" are supported. Support for + "insert effects" and "master effects" is planned to be added at + a later point. + The following commands allow to retrieve the set of internal + effects available to the sampler, detailed information about + those effects and to create and destroy instances of such + effects. After an instance of an effect is created, the effect + instance can be inserted into the audio signal path of the + sampler, e.g. as send effect. + The sampler allows to create an arbitrary amount of so called + send effect chains. Each effect chain can host an arbitrary + amount of effect instances. The output of the first effect + instance in an effect chain is fed to the input of the second + effect instance of the chain and so on. So effects in one chain + are processed sequentially. Send effect chains however are + processed in parallel to other send effect chains. Audio signals + of sampler channels are fed to send effects by creating FX sends + to the respective sampler channel and assigning a destination + send effect to that FX by using the + "SET FX_SEND EFFECT" + command. The latter allows to route the FX send to the beginning + of a send effect chain, as well as directly to any other + position of the send effect chain. + +
+ The front-end can retrieve the amount of internal + effects, available to the sampler by sending + the following command: + + + GET AVAILABLE_EFFECTS + + + + Possible Answers: + + + The sampler will answer by returning the current + number of effects available to the sampler. + + + + Examples: + + + C: "GET AVAILABLE_EFFECTS" + S: "129" + + +
+ +
+ The set of available internal effects can change at + runtime. The front-end can retrieve the list of internal + effects, available to the sampler by sending the following + command: + + + LIST AVAILABLE_EFFECTS + + + + Possible Answers: + + + The sampler will answer by returning a comma + separated list with numerical IDs of effects. Note: + the numercial ID of an effect is generated by the + sampler for the current moment. The numerical ID of + the same effect can change at runtime, e.g. when the + user requests a rescan of available effect plugins. + + + + Example: + + + C: "LIST AVAILABLE_EFFECTS" + S: "5,6,7,120,121,122,123,124" + + +
+ +
+ The front-end can ask for general information about an + effect by sending the following command: + + + GET EFFECT INFO <effect-index> + + + Where <effect-index> is the numerical ID of an + effect as returned by the + "LIST AVAILABLE_EFFECTS" + command. + Possible Answers: + + + LinuxSampler will answer by sending a <CRLF> separated list. + Each answer line begins with the effect information + category name, followed by a colon and then a space + character <SP> and finally the info character + string to that effect information category. At the + moment the following categories are defined: + + + SYSTEM - + + name of the effect plugin system + the effect is based on + (e.g. "LADSPA") + + + MODULE - + + module of the effect plugin + system that contains this effect, + the module is usually the + dynamic-linked library (DLL) + filename of the effect plugin, + including full path (note that this + filename may contain + escape sequences) + + + NAME - + + character string defining the + unique name of the effect within its + module (note that the character + string may contain + escape sequences) + + + DESCRIPTION - + + human readable name of the + effect, intended to be displayed in + user interfaces (note that the + character string may contain + escape sequences) + + + + + + + The mentioned fields above don't have to be in particular order. + + Example: + + + C: "GET EFFECT INFO 121" + S: "SYSTEM: LADSPA" +    "MODULE: /usr/lib/ladspa/lowpass_iir_1891.so" +    "NAME: lowpass_iir" +    "DESCRIPTION: Glame Lowpass Filter" +    "." + + +
+ +
+ The front-end can spawn an instance of the desired + effect by sending the following command: + + + CREATE EFFECT_INSTANCE <effect-system> <module> <effect-name> + + + Where <effect-system> is the "SYSTEM" field, + <module> the "MODULE" field and <effect-name> + the "NAME" field as returned by the + "GET EFFECT INFO" + command. The filename of argument <module> and the + character string of argument <effect-name> may contain + escape sequences. + + The sampler will try to load the requested effect and to + create an instance of it. To allow loading the same effect + on a different machine, probably even running a completely + different operating system (e.g. Linux vs. Windows), the + sampler tries to match <module> "softly". That means + it first tries to find an effect that exactly matches the + given <module> argument. If there is no exact match, + the sampler will try to lower the restrictions on matching + the <module> argument more and more, e.g. by ignoring + upper / lower case differences and by ignoring the path of + the DLL filename and file extension. If there is still no + match at the end, the sampler will try to ignore the + <module> argument completely and as a last resort + search for an effect that only matches the given + <effect-system> and <effect-name> arguments. + + Possible Answers: + + + "OK[<effect-instance>]" - + + in case the effect instance was + successfully created, where + <effect-instance> is the numerical ID + of the new effect instance + + + "WRN:<warning-code>:<warning-message>" - + + in case the effect instance was spawned + successfully, but there are noteworthy + issue(s) related, providing an appropriate + warning code and warning message + + + "ERR:<error-code>:<error-message>" - + + if the effect could not be instantiated + + + + + + Examples: + + + C: "CREATE EFFECT_INSTANCE LADSPA '/usr/lib/ladspa/mod_delay_1419.so' 'modDelay'" + S: "OK[0]" + + +
+ +
+ The front-end can spawn an instance of the desired + effect by sending the following command: + + + CREATE EFFECT_INSTANCE <effect-index> + + + Where <effect-index> is the numerical ID of the + effect as returned by the + "LIST AVAILABLE_EFFECTS" + command. + + The sampler will try to load the requested effect and to + create an instance of it. + + Note: Since the numerical ID of a certain effect can + change at any time, you should not use this command in + LSCP files to restore a certain effect at a later time! To + store a sampler session including all its effects, use the + portable text-based + version of "CREATE EFFECT_INSTANCE" instead! This + allows to restore a sampler session with all its effects + also on other machines, possibly even running a completely + different operating system (e.g. Linux vs. Windows), with + different plugin directories or plugin DLL names. + + Possible Answers: + + + "OK[<effect-instance>]" - + + in case the effect instance was + successfully created, where + <effect-instance> is the numerical ID + of the new effect instance + + + "WRN:<warning-code>:<warning-message>" - + + in case the effect instance was spawned + successfully, but there are noteworthy + issue(s) related, providing an appropriate + warning code and warning message + + + "ERR:<error-code>:<error-message>" - + + if the effect could not be instantiated + + + + + + Examples: + + + C: "CREATE EFFECT_INSTANCE 72" + S: "OK[5]" + + +
+ +
+ The front-end can destroy an unusued effect instance and + thus freeing it from memory by sending the following command: + + + DESTROY EFFECT_INSTANCE <effect-instance> + + + Where <effect-instance> is the numerical ID of the + effect instance as returned by the + "CREATE EFFECT_INSTANCE" or + "LIST EFFECT_INSTANCES" + command. + + The effect instance can only be destroyed if it's not + used in any part of the sampler's audio signal path anymore. + If the effect instance is still in use somewhere, trying to + destroy the effect instance will result in an error + message. + + Possible Answers: + + + "OK" - + + in case the effect instance was successfully destroyed + + + "ERR:<error-code>:<error-message>" - + + in case it failed, providing an appropriate error code and + error message + + + + + + Examples: + + + C: "DESTROY EFFECT_INSTANCE 5" + S: "OK" + + +
+ +
+ The front-end can retrieve the current amount of effect + instances by sending the following command: + + + GET EFFECT_INSTANCES + + + + Possible Answers: + + + The sampler will answer by returning the current + number of effect instances created and not yet + destroyed in the current sampler session. + + + + Examples: + + + C: "GET EFFECT_INSTANCES" + S: "14" + + +
+ +
+ The front-end can retrieve the current list of effect + instances by sending the following command: + + + LIST EFFECT_INSTANCES + + + + Possible Answers: + + + The sampler will answer by returning a comma + separated list with numerical IDs of effects + instances. + + + + Example: + + + C: "LIST EFFECT_INSTANCES" + S: "9,11,14,15,16,17,25" + + +
+ +
+ The front-end can ask for the current information about + a particular effect instance by sending the following command: + + + GET EFFECT_INSTANCE INFO <effect-instance> + + + Where <effect-instance> is the numerical ID of an + effect instance as returned by the + "CREATE EFFECT_INSTANCE" + or + "LIST EFFECT_INSTANCES" + command. + + 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 information category. At the + moment the following categories are defined: + + + SYSTEM - + + name of the effect plugin system + the effect is based on + (e.g. "LADSPA") + + + MODULE - + + module of the effect plugin + system that contains this effect, + the module is usually the + dynamic-linked library (DLL) + filename of the effect plugin, + including full path (note that this + filename may contain + escape sequences) + + + NAME - + + character string defining the + unique name of the effect within its + module (note that the character + string may contain + escape sequences) + + + DESCRIPTION - + + human readable name of the + effect, intended to be displayed in + user interfaces (note that the + character string may contain + escape sequences) + + + INPUT_CONTROLS - + + amount of input controls the + effect instance provides, to allow + controlling the effect parameters in + realtime + + + + + + + The mentioned fields above don't have to be in particular order. + + Example: + + + C: "GET EFFECT_INSTANCE INFO 3" + S: "SYSTEM: LADSPA" +    "MODULE: /usr/lib/ladspa/mod_delay_1419.so" +    "NAME: modDelay" +    "DESCRIPTION: Modulatable delay" +    "INPUT_CONTROLS: 1" +    "." + + +
+ +
+ Effects typically provide a certain set of effect + parameters which can be altered by the user in realtime + (e.g. depth of a reverb effect, duration of a delay effect, + dry / wet signal ratio). Those controllable effect parameters + are called "input controls". The front-end can ask for the + current information of an effect instance's input control + by sending the following command: + + + GET EFFECT_INSTANCE_INPUT_CONTROL INFO <effect-instance> <input-control> + + + Where <effect-instance> is the numerical ID of an + effect instance as returned by the + "CREATE EFFECT_INSTANCE" + or + "LIST EFFECT_INSTANCES" + command and <input-control> is the index of the input + control within the numerical bounds as returned by the + "INPUT_CONTROLS" field of the + "GET EFFECT_INSTANCE INFO" + command. + + 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 information category. There are + information categories which are always returned, + independent of the respective effect parameter and + there are optional information categories + which are only shown for certain effect parameters. + At the moment the following categories are defined: + + + DESCRIPTION - + + (always returned) + human readable name of the + effect parameter, intended to be + displayed in user interfaces (note + that the character string may + contain escape sequences) + + + VALUE - + + + (always returned) + current (optional dotted) + floating point value of this effect + parameter + + + RANGE_MIN - + + + (optionally returned) + minimum allowed value for this + effect parameter + + + RANGE_MAX - + + + (optionally returned) + maximum allowed value for this + effect parameter + + + POSSIBILITIES - + + + (optionally returned) + comma separated list of + (optional dotted) floating point + numbers, reflecting the exact set of + possible values for this effect + parameter + + + DEFAULT - + + + (optionally returned) + default value of this effect + parameter + + + + + + + The mentioned fields above don't have to be in particular order. + + Example: + + + C: "GET EFFECT_INSTANCE_INPUT_CONTROL INFO 1 0" + S: "DESCRIPTION: Base delay (s)" +    "VALUE: 0.500" +    "RANGE_MIN: 0.000" +    "." + + +
+ +
+ The front-end can alter the current value of an effect + parameter by sending the following command: + + + SET EFFECT_INSTANCE_INPUT_CONTROL VALUE <effect-instance> <input-control> <value> + + + Where <effect-instance> is the numerical ID of the + effect instance as returned by the + "CREATE EFFECT_INSTANCE" or + "LIST EFFECT_INSTANCES" + command, <input-control> is the index of the input + control within the numerical bounds as returned by the + "INPUT_CONTROLS" field of the + "GET EFFECT_INSTANCE INFO" + command and <value> is the new (optional dotted) + floating point value for this effect parameter. + + Possible Answers: + + + "OK" - + + in case the effect was altered successfully + + + "ERR:<error-code>:<error-message>" - + + in case it failed, providing an appropriate error code and + error message + + + + + + Examples: + + + C: "SET EFFECT_INSTANCE_INPUT_CONTROL VALUE 0 1 0.5" + S: "OK" + + +
+ +
+ The front-end can retrieve the current amount of send + effect chains of an audio output device by sending the + following command: + + + GET SEND_EFFECT_CHAINS <audio-device> + + + Where <audio-device> should be replaced by the + numerical ID of the audio output device as given by the + "CREATE AUDIO_OUTPUT_DEVICE" + or "LIST AUDIO_OUTPUT_DEVICES" + command. + + Possible Answers: + + + The sampler will answer by returning the current + number of send effect chains of the supplied audio + output device. + + + + Examples: + + + C: "GET SEND_EFFECT_CHAINS 0" + S: "4" + + +
+ +
+ The front-end can retrieve the current list of send + effect chains of an audio output device by sending the + following command: + + + LIST SEND_EFFECT_CHAINS <audio-device> + + + Where <audio-device> should be replaced by the + numerical ID of the audio output device as given by the + "CREATE AUDIO_OUTPUT_DEVICE" + or "LIST AUDIO_OUTPUT_DEVICES" + command. + + Possible Answers: + + + The sampler will answer by returning a comma + separated list with numerical IDs of send effect + chains of the supplied audio output device. + + + + + Examples: + + + C: "LIST SEND_EFFECT_CHAINS 0" + S: "3,4,7" + + +
+ +
+ The front-end can add a send effect chain by sending the + following command: + + + ADD SEND_EFFECT_CHAIN <audio-device> + + + Where <audio-device> should be replaced by the + numerical ID of the audio output device as given by the + "CREATE AUDIO_OUTPUT_DEVICE" + or "LIST AUDIO_OUTPUT_DEVICES" + command. + + Possible Answers: + + + "OK[<effect-chain>]" - + + in case the send effect chain was + added successfully, where + <effect-chain> is the numerical ID + of the new send effect chain + + + "ERR:<error-code>:<error-message>" - + + if the send effect chain could not be added + + + + + + Examples: + + + C: "ADD SEND_EFFECT_CHAIN 0" + S: "OK[2]" + + +
+ +
+ The front-end can remove a send effect chain by sending + the following command: + + + REMOVE SEND_EFFECT_CHAIN <audio-device> <effect-chain> + + + Where <audio-device> should be replaced by the + numerical ID of the audio output device as given by the + "CREATE AUDIO_OUTPUT_DEVICE" + or "LIST AUDIO_OUTPUT_DEVICES" + command and <effect-chain> by the numerical ID as + returned by the + "ADD SEND_EFFECT_CHAIN" + or + "LIST SEND_EFFECT_CHAINS" + command. + + Possible Answers: + + + "OK" - + + in case the send effect chain was + removed successfully + + + "ERR:<error-code>:<error-message>" - + + if the send effect chain could not be removed + + + + + + Examples: + + + C: "REMOVE SEND_EFFECT_CHAIN 0 2" + S: "OK" + + +
+ +
+ The front-end can ask for information of a send effect + chain by sending the following command: + + + GET SEND_EFFECT_CHAIN INFO <audio-device> <effect-chain> + + + Where <audio-device> should be replaced by the + numerical ID of the audio output device as given by the + "CREATE AUDIO_OUTPUT_DEVICE" + or "LIST AUDIO_OUTPUT_DEVICES" + command and <effect-chain> by the numerical ID as + returned by the + "ADD SEND_EFFECT_CHAIN" + or + "LIST SEND_EFFECT_CHAINS" + command. + + 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 information category. + At the moment the following categories are defined: + + + EFFECT_COUNT - + + amount of effects in this send + effect chain + + + EFFECT_SEQUENCE - + + comma separated list of the + numerical IDs of the effect + instances in this send effect chain, + in the order as they are procssed in + the effect chain + + + + + + + The mentioned fields above don't have to be in particular order. + + Example: + + + C: "GET SEND_EFFECT_CHAIN INFO 0 2" + S: "EFFECT_COUNT: 3" +    "EFFECT_SEQUENCE: 31,4,7" +    "." + + +
+ +
+ The front-end can add an unused effect instance to the + end of a send effect chain by sending the following command: + + + APPEND SEND_EFFECT_CHAIN EFFECT <audio-device> <effect-chain> <effect-instance> + + + Where <audio-device> should be replaced by the + numerical ID of the audio output device as given by the + "CREATE AUDIO_OUTPUT_DEVICE" + or "LIST AUDIO_OUTPUT_DEVICES" + command and <effect-chain> by the numerical ID as + returned by the + "ADD SEND_EFFECT_CHAIN" + or + "LIST SEND_EFFECT_CHAINS" + command and <effect-instance> as returned by the + "CREATE EFFECT_INSTANCE" or + "LIST EFFECT_INSTANCES" + command. + Only unused effect instances can be added to the effect + chain. Trying to add an effect instance which is already in + use somewhere in the audio signal path of the sampler will + result in an error. + + Possible Answers: + + + "OK" - + + in case the effect instance was + added successfully to the chain + + + "ERR:<error-code>:<error-message>" - + + if the effect instance could not be added + + + + + + Examples: + + + C: "APPEND SEND_EFFECT_CHAIN EFFECT 0 2 38" + S: "OK" + + +
+ +
+ The front-end can add an unused effect instance to a + certain position of a send effect chain by sending the + following command: + + + INSERT SEND_EFFECT_CHAIN EFFECT <audio-device> <effect-chain> <chain-pos> <effect-instance> + + + Where <audio-device> should be replaced by the + numerical ID of the audio output device as given by the + "CREATE AUDIO_OUTPUT_DEVICE" + or "LIST AUDIO_OUTPUT_DEVICES" + command, <effect-chain> by the numerical ID as + returned by the + "ADD SEND_EFFECT_CHAIN" + or + "LIST SEND_EFFECT_CHAINS" + command, <effect-instance> as returned by the + "CREATE EFFECT_INSTANCE" or + "LIST EFFECT_INSTANCES" + command and <chain-pos> the exact position of the + effect chain where the supplied effect shall be inserted + to. + Only unused effect instances can be added to the effect + chain. Trying to add an effect instance which is already in + use somewhere in the audio signal path of the sampler will + result in an error. + + Possible Answers: + + + "OK" - + + in case the effect instance was + added successfully to the chain + + + "ERR:<error-code>:<error-message>" - + + if the effect instance could not be added + + + + + + Examples: + + + C: "INSERT SEND_EFFECT_CHAIN EFFECT 0 2 4 38" + S: "OK" + + +
+ +
+ The front-end can remove an effect instance from a + certain position of a send effect chain by sending the + following command: + + + REMOVE SEND_EFFECT_CHAIN EFFECT <audio-device> <effect-chain> <chain-pos> + + + Where <audio-device> should be replaced by the + numerical ID of the audio output device as given by the + "CREATE AUDIO_OUTPUT_DEVICE" + or "LIST AUDIO_OUTPUT_DEVICES" + command, <effect-chain> by the numerical ID as + returned by the + "ADD SEND_EFFECT_CHAIN" + or + "LIST SEND_EFFECT_CHAINS" + command and <chain-pos> the exact position of the + effect instance to be removed from the effect chain. + + Possible Answers: + + + "OK" - + + in case the effect instance was + removed successfully + + + "ERR:<error-code>:<error-message>" - + + if the effect instance could not be removed + + + + + + Examples: + + + C: "REMOVE SEND_EFFECT_CHAIN EFFECT 0 2 4" + S: "OK" + + +
+ +
+
+
The grammar of the control protocol as descibed in is defined below using Backus-Naur Form (BNF as described in ) @@ -5889,22 +8022,28 @@ input = - line LF + line - / line CR LF + / error line = - /* epsilon (empty line ignored) */ + statement LF + + / statement CR LF + + + +statement = + + /* epsilon (empty statement/line ignored) */ / comment / command - / error - comment = @@ -5959,6 +8098,14 @@ / EDIT SP edit_instruction + / FORMAT SP format_instruction + + / SEND SP send_instruction + + / APPEND SP append_instruction + + / INSERT SP insert_instruction + / RESET / QUIT @@ -5969,24 +8116,34 @@ CHANNEL - / DB_INSTRUMENT_DIRECTORY SP pathname + / CHANNEL SP MIDI_INPUT SP sampler_channel SP device_index - / DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP pathname SP pathname + / CHANNEL SP MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index - / DB_INSTRUMENTS SP scan_mode SP pathname SP pathname + / DB_INSTRUMENT_DIRECTORY SP db_path - / DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname + / DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename - / DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname SP instrument_index + / DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP FILE_AS_DIR SP db_path SP filename - / DB_INSTRUMENTS SP pathname SP pathname + / DB_INSTRUMENTS SP scan_mode SP db_path SP filename - / DB_INSTRUMENTS SP pathname SP pathname SP instrument_index + / DB_INSTRUMENTS SP scan_mode SP FILE_AS_DIR SP db_path SP filename + + / DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename + + / DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index + + / DB_INSTRUMENTS SP db_path SP filename + + / DB_INSTRUMENTS SP db_path SP filename SP instrument_index / MIDI_INSTRUMENT_MAP / MIDI_INSTRUMENT_MAP SP map_name + / SEND_EFFECT_CHAIN SP device_index + subscribe_event = @@ -6001,6 +8158,10 @@ / CHANNEL_COUNT + / CHANNEL_MIDI + + / DEVICE_MIDI + / VOICE_COUNT / STREAM_COUNT @@ -6033,10 +8194,20 @@ / MISCELLANEOUS + / TOTAL_STREAM_COUNT + / TOTAL_VOICE_COUNT / GLOBAL_INFO + / EFFECT_INSTANCE_COUNT + + / EFFECT_INSTANCE_INFO + + / SEND_EFFECT_CHAIN_COUNT + + / SEND_EFFECT_CHAIN_INFO + unsubscribe_event = @@ -6051,6 +8222,10 @@ / CHANNEL_COUNT + / CHANNEL_MIDI + + / DEVICE_MIDI + / VOICE_COUNT / STREAM_COUNT @@ -6083,10 +8258,20 @@ / MISCELLANEOUS + / TOTAL_STREAM_COUNT + / TOTAL_VOICE_COUNT / GLOBAL_INFO + / EFFECT_INSTANCE_COUNT + + / EFFECT_INSTANCE_INFO + + / SEND_EFFECT_CHAIN_COUNT + + / SEND_EFFECT_CHAIN_INFO + map_instruction = @@ -6111,15 +8296,27 @@ CHANNEL SP sampler_channel + / CHANNEL SP MIDI_INPUT SP sampler_channel + + / CHANNEL SP MIDI_INPUT SP sampler_channel SP device_index + + / CHANNEL SP MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index + / MIDI_INSTRUMENT_MAP SP midi_map / MIDI_INSTRUMENT_MAP SP ALL - / DB_INSTRUMENT_DIRECTORY SP FORCE SP pathname + / SEND_EFFECT_CHAIN SP device_index SP effect_chain - / DB_INSTRUMENT_DIRECTORY SP pathname + / SEND_EFFECT_CHAIN SP EFFECT SP device_index SP effect_chain SP chain_pos - / DB_INSTRUMENT SP pathname + / FX_SEND SP EFFECT SP sampler_channel SP fx_send_id + + / DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path + + / DB_INSTRUMENT_DIRECTORY SP db_path + + / DB_INSTRUMENT SP db_path @@ -6127,6 +8324,20 @@ AVAILABLE_ENGINES + / AVAILABLE_EFFECTS + + / EFFECT_INSTANCES + + / EFFECT SP INFO SP effect_index + + / EFFECT_INSTANCE SP INFO SP effect_instance + + / EFFECT_INSTANCE_INPUT_CONTROL SP INFO SP effect_instance SP input_control + + / SEND_EFFECT_CHAINS SP device_index + + / SEND_EFFECT_CHAIN SP INFO SP device_index SP effect_chain + / AVAILABLE_MIDI_INPUT_DRIVERS / MIDI_INPUT_DRIVER SP INFO SP string @@ -6173,6 +8384,8 @@ / SERVER SP INFO + / TOTAL_STREAM_COUNT + / TOTAL_VOICE_COUNT / TOTAL_VOICE_COUNT_MAX @@ -6191,22 +8404,30 @@ / FX_SEND SP INFO SP sampler_channel SP fx_send_id - / DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname + / DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path - / DB_INSTRUMENT_DIRECTORIES SP pathname + / DB_INSTRUMENT_DIRECTORIES SP db_path - / DB_INSTRUMENT_DIRECTORY SP INFO SP pathname + / DB_INSTRUMENT_DIRECTORY SP INFO SP db_path - / DB_INSTRUMENTS SP RECURSIVE SP pathname + / DB_INSTRUMENTS SP RECURSIVE SP db_path - / DB_INSTRUMENTS SP pathname + / DB_INSTRUMENTS SP db_path - / DB_INSTRUMENT SP INFO SP pathname + / DB_INSTRUMENT SP INFO SP db_path / DB_INSTRUMENTS_JOB SP INFO SP number / VOLUME + / VOICES + + / STREAMS + + / FILE SP INSTRUMENTS SP filename + + / FILE SP INSTRUMENT SP INFO SP filename SP instrument_index + set_instruction = @@ -6217,8 +8438,12 @@ / MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list + / MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE + / MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list + / EFFECT_INSTANCE_INPUT_CONTROL SP VALUE SP effect_instance SP input_control SP control_value + / CHANNEL SP set_chan_instruction / MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name @@ -6231,18 +8456,32 @@ / FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value - / DB_INSTRUMENT_DIRECTORY SP NAME SP pathname SP dirname + / FX_SEND SP EFFECT SP sampler_channel SP fx_send_id SP effect_chain SP chain_pos - / DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP pathname SP stringval + / DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped - / DB_INSTRUMENT SP NAME SP pathname SP dirname + / DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped - / DB_INSTRUMENT SP DESCRIPTION SP pathname SP stringval + / DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped + + / DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped + + / DB_INSTRUMENT SP FILE_PATH SP filename SP filename / ECHO SP boolean + / SHELL SP INTERACT SP boolean + + / SHELL SP AUTO_CORRECT SP boolean + + / SHELL SP DOC SP boolean + / VOLUME SP volume_value + / VOICES SP number + + / STREAMS SP number + create_instruction = @@ -6259,6 +8498,10 @@ / FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name + / EFFECT_INSTANCE SP effect_index + + / EFFECT_INSTANCE SP effect_system SP module SP effect_name + reset_instruction = @@ -6277,29 +8520,31 @@ find_instruction = - DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP query_val_list + DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list + + / DB_INSTRUMENTS SP db_path SP query_val_list - / DB_INSTRUMENTS SP pathname SP query_val_list + / DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP query_val_list - / DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP pathname SP query_val_list + / DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list - / DB_INSTRUMENT_DIRECTORIES SP pathname SP query_val_list + / LOST SP DB_INSTRUMENT_FILES move_instruction = - DB_INSTRUMENT_DIRECTORY SP pathname SP pathname + DB_INSTRUMENT_DIRECTORY SP db_path SP db_path - / DB_INSTRUMENT SP pathname SP pathname + / DB_INSTRUMENT SP db_path SP db_path copy_instruction = - DB_INSTRUMENT_DIRECTORY SP pathname SP pathname + DB_INSTRUMENT_DIRECTORY SP db_path SP db_path - / DB_INSTRUMENT SP pathname SP pathname + / DB_INSTRUMENT SP db_path SP db_path @@ -6311,6 +8556,8 @@ / FX_SEND SP sampler_channel SP fx_send_id + / EFFECT_INSTANCE SP number + load_instruction = @@ -6321,6 +8568,18 @@ +append_instruction = + + SEND_EFFECT_CHAIN SP EFFECT SP device_index SP effect_chain SP effect_instance + + + +insert_instruction = + + SEND_EFFECT_CHAIN SP EFFECT SP device_index SP effect_chain SP chain_pos SP effect_instance + + + set_chan_instruction = AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index @@ -6355,7 +8614,13 @@ edit_instruction = - INSTRUMENT SP sampler_channel + CHANNEL SP INSTRUMENT SP sampler_channel + + + +format_instruction = + + INSTRUMENTS_DB @@ -6391,8 +8656,16 @@ / CHANNELS + / CHANNEL SP MIDI_INPUTS SP sampler_channel + / AVAILABLE_ENGINES + / AVAILABLE_EFFECTS + + / EFFECT_INSTANCES + + / SEND_EFFECT_CHAINS SP number + / AVAILABLE_MIDI_INPUT_DRIVERS / AVAILABLE_AUDIO_OUTPUT_DRIVERS @@ -6405,13 +8678,21 @@ / FX_SENDS SP sampler_channel - / DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname + / DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path - / DB_INSTRUMENT_DIRECTORIES SP pathname + / DB_INSTRUMENT_DIRECTORIES SP db_path - / DB_INSTRUMENTS SP RECURSIVE SP pathname + / DB_INSTRUMENTS SP RECURSIVE SP db_path - / DB_INSTRUMENTS SP pathname + / DB_INSTRUMENTS SP db_path + + / FILE SP INSTRUMENTS SP filename + + + +send_instruction = + + CHANNEL SP MIDI_DATA SP string SP sampler_channel SP number SP number @@ -6439,6 +8720,12 @@ +effect_instance = + + number + + + device_index = number @@ -6509,6 +8796,12 @@ +control_value = + + real + + + sampler_channel = number @@ -6533,39 +8826,63 @@ -pathname = +filename = - stringval + path -dirname = +db_path = - stringval + path -filename = +map_name = stringval_escaped -map_name = +entry_name = - stringval + stringval_escaped -entry_name = +fx_send_name = - stringval + stringval_escaped -fx_send_name = +effect_name = + + stringval_escaped + + + +effect_index = + + number + + + +effect_chain = + + number + + + +chain_pos = + + number + + + +input_control = - stringval + number @@ -6577,6 +8894,7 @@ + param_val = string @@ -6599,9 +8917,9 @@ query_val = - string + text_escaped - / stringval + / stringval_escaped @@ -6615,11 +8933,23 @@ +effect_system = + + string + + + +module = + + filename + + +
- Older versions of this protocol up to and including v1.2 only + Older versions of this protocol up to and including v1.1 only supported the standard ASCII character set (ASCII code 0 - 127) , all younger versions of this protocol however support the Extended ASCII character set (ASCII code @@ -6643,18 +8973,107 @@ Notice: due to the transition of certain parts of the protocol which now support escape sequences, a slight backward - incompatibility to protocols version v1.2 and younger has been + incompatibility to protocols version v1.1 and younger has been introduced. The only difference is that in parts of the protocol where escape characters are now supported, a backslash characters MUST be escaped as well (that is as double backslash), whereas in the old versions a single backslash was sufficient. + + The following LSCP commands support escape sequences as part + of their filename / path based arguments and / or may contain + a filename / path with escape sequences in their response: + + "LOAD INSTRUMENT" + "GET CHANNEL INFO" + "MAP MIDI_INSTRUMENT" + "GET MIDI_INSTRUMENT INFO" + "ADD DB_INSTRUMENT_DIRECTORY" + "ADD DB_INSTRUMENTS" + "REMOVE DB_INSTRUMENT_DIRECTORY" + "REMOVE DB_INSTRUMENT" + "GET DB_INSTRUMENT_DIRECTORIES" + "LIST DB_INSTRUMENT_DIRECTORIES" + "GET DB_INSTRUMENT_DIRECTORY INFO" + "GET DB_INSTRUMENTS" + "LIST DB_INSTRUMENTS" + "GET DB_INSTRUMENT INFO" + "SET DB_INSTRUMENT_DIRECTORY NAME" + "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION" + "SET DB_INSTRUMENT NAME" + "SET DB_INSTRUMENT DESCRIPTION" + "FIND DB_INSTRUMENTS" + "FIND DB_INSTRUMENT_DIRECTORIES" + "MOVE DB_INSTRUMENT" + "MOVE DB_INSTRUMENT_DIRECTORY" + "COPY DB_INSTRUMENT" + "COPY DB_INSTRUMENT_DIRECTORY" + "FIND LOST DB_INSTRUMENT_FILES" + "SET DB_INSTRUMENT FILE_PATH" + "GET FILE INSTRUMENTS" + "LIST FILE INSTRUMENTS" + "GET FILE INSTRUMENT INFO" + "GET EFFECT INFO" + "GET EFFECT_INSTANCE INFO" + "CREATE EFFECT_INSTANCE" + + Note that the forward slash character ('/') has a special meaning in + filename / path based arguments: it acts as separator of the nodes in + the path, thus if a directory- or filename includes a forward slash + (not intended as path node separator), you MUST escape that slash + either with the respective hex escape sequence ("\x2f") or with the + respective octal escape sequence ("\057"). + + + + Note for Windows: file path arguments in LSCP are expected + to use forward slashes as directory node separator similar + to Unix based operating systems. In contrast to Unix however + a Windows typical drive character is expected to be + prefixed to the path. That is an original Windows file path + like "D:\Sounds\My.gig" would become in LSCP: + "D:/Sounds/My.gig". + + + + The following LSCP commands even support escape sequences as + part of at least one of their text-based arguments (i.e. entity name, + description) and / or may contain escape sequences in at least one of + their text-based fields in their response: + + "GET SERVER INFO" + "GET ENGINE INFO" + "GET CHANNEL INFO" + "CREATE FX_SEND" + "GET FX_SEND INFO" + "SET FX_SEND NAME" + "GET MIDI_INSTRUMENT INFO" + "GET MIDI_INSTRUMENT_MAP INFO" + "ADD MIDI_INSTRUMENT_MAP" + "MAP MIDI_INSTRUMENT" + "SET MIDI_INSTRUMENT_MAP NAME" + "GET DB_INSTRUMENT_DIRECTORY INFO" + "SET DB_INSTRUMENT_DIRECTORY NAME" + "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION" + "FIND DB_INSTRUMENT_DIRECTORIES" + "GET DB_INSTRUMENT INFO" + "SET DB_INSTRUMENT NAME" + "SET DB_INSTRUMENT DESCRIPTION" + "FIND DB_INSTRUMENTS" + "GET EFFECT INFO" + "GET EFFECT_INSTANCE INFO" + "CREATE EFFECT_INSTANCE" + + Please note that these lists are manually maintained. If you + find a command that also supports escape sequences we forgot to + mention here, please report it! +
This chapter will describe all currently defined events supported by LinuxSampler. -
+
Client may want to be notified when the total number of audio output devices on the back-end changes by issuing the following command: @@ -6672,7 +9091,7 @@ of audio output devices.
-
+
Client may want to be notified when changes were made to audio output devices on the back-end by issuing the following command: @@ -6694,7 +9113,7 @@ message is sufficient here.
-
+
Client may want to be notified when the total number of MIDI input devices on the back-end changes by issuing the following command: @@ -6712,7 +9131,7 @@ of MIDI input devices.
-
+
Client may want to be notified when changes were made to MIDI input devices on the back-end by issuing the following command: @@ -6734,7 +9153,7 @@ message is sufficient here.
-
+
Client may want to be notified when the total number of channels on the back-end changes by issuing the following command: @@ -6752,7 +9171,57 @@ of sampler channels.
-
+
+ Client may want to be notified when MIDI data arrive on sampler channels on + back-end side, by issuing the following command: + + + SUBSCRIBE CHANNEL_MIDI + + + Server will start sending one of the the following notification messages: + + + "NOTIFY:CHANNEL_MIDI:<channel-id> NOTE_ON <note> <velocity>" + "NOTIFY:CHANNEL_MIDI:<channel-id> NOTE_OFF <note> <velocity>" + + + where <channel-id> will be replaced by the ID of the sampler channel where the MIDI + data arrived. <note> and <velocity> are integer values in the range between + 0 .. 127, reflecting the analog meaning of the MIDI specification. + + CAUTION: no guarantee whatsoever will be made that MIDI events are actually all + delivered by this mechanism! With other words: events could be lost at any time! + This restriction was made to keep the RT-safeness of the backend's MIDI and audio + thread unaffected by this feature. +
+ +
+ Client may want to be notified when MIDI data arrive on MIDI input devices by issuing the following command: + + + SUBSCRIBE DEVICE_MIDI + + + Server will start sending one of the the following notification messages: + + + "NOTIFY:DEVICE_MIDI:<device-id> <port-id> NOTE_ON <note> <velocity>" + "NOTIFY:DEVICE_MIDI:<device-id> <port-id> NOTE_OFF <note> <velocity>" + + + where <device-id> <port-id> will be replaced + by the IDs of the respective MIDI input device and the device's MIDI port where the MIDI + data arrived. <note> and <velocity> are integer values in the range between + 0 .. 127, reflecting the analog meaning of the MIDI specification. + + CAUTION: no guarantee whatsoever will be made that MIDI events are actually all + delivered by this mechanism! With other words: events could be lost at any time! + This restriction was made to keep the RT-safeness of the backend's MIDI and audio + thread unaffected by this feature. +
+ +
Client may want to be notified when the number of voices on the back-end changes by issuing the following command: @@ -6771,7 +9240,7 @@ active voices on that channel.
-
+
Client may want to be notified when the number of streams on the back-end changes by issuing the following command: SUBSCRIBE STREAM_COUNT @@ -6790,7 +9259,7 @@ active disk streams on that channel.
-
+
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: @@ -6811,7 +9280,7 @@ "GET CHANNEL BUFFER_FILL PERCENTAGE" command was issued on this channel.
-
+
Client may want to be notified when changes were made to sampler channels on the back-end by issuing the following command: @@ -6833,7 +9302,7 @@ message is sufficient here.
-
+
Client may want to be notified when the number of effect sends on a particular sampler channel is changed by issuing the following command: @@ -6852,7 +9321,7 @@ be replaced by the new number of effect sends on that channel.
-
+
Client may want to be notified when changes were made to effect sends on a a particular sampler channel by issuing the following command: @@ -6871,7 +9340,7 @@ be replaced by the numerical ID of the changed effect send.
-
+
Client may want to be notified when the total number of voices on the back-end changes by issuing the following command: @@ -6889,7 +9358,25 @@ all currently active voices.
-
+
+ Client may want to be notified when the total number of disk streams on the + back-end changes by issuing the following command: + + + SUBSCRIBE TOTAL_STREAM_COUNT + + + Server will start sending the following notification messages: + + + "NOTIFY:TOTAL_STREAM_COUNT:<streams>" + + + where <streams> will be replaced by the new number of + all currently active disk streams. +
+ +
Client may want to be notified when the number of MIDI instrument maps on the back-end changes by issuing the following command: @@ -6907,7 +9394,7 @@ of MIDI instrument maps.
-
+
Client may want to be notified when changes were made to MIDI instrument maps on the back-end by issuing the following command: @@ -6929,7 +9416,7 @@ message is sufficient here.
-
+
Client may want to be notified when the number of MIDI instrument maps on the back-end changes by issuing the following command: @@ -6948,7 +9435,7 @@ the new number of MIDI instruments in the specified map.
-
+
Client may want to be notified when changes were made to MIDI instruments on the back-end by issuing the following command: @@ -6971,7 +9458,7 @@ message is sufficient here.
-
+
Client may want to be notified when changes to the global settings of the sampler were made by issuing the following command: @@ -6987,10 +9474,22 @@ replaced by the optional dotted floating point value, reflecting the new global volume parameter. + + "NOTIFY:GLOBAL_INFO:VOICES <max-voices>" - Notifies that the + golbal limit of the sampler for maximum voices is changed, where + <max-voices> will be an integer value, reflecting the + new global voice limit parameter. + + + "NOTIFY:GLOBAL_INFO:STREAMS <max-streams>" - Notifies that the + golbal limit of the sampler for maximum disk streams is changed, where + <max-streams> will be an integer value, reflecting the + new global disk streams limit parameter. +
-
+
Client may want to be notified when the number of instrument directories in a particular directory in the instruments database is changed by issuing the following command: @@ -7012,7 +9511,7 @@ is not sent for the subdirectories in that directory.
-
+
Client may want to be notified when changes were made to directories in the instruments database by issuing the following command: @@ -7042,7 +9541,7 @@ the new name of the directory, encapsulated into apostrophes.
-
+
Client may want to be notified when the number of instruments in a particular directory in the instruments database is changed by issuing the following command: @@ -7064,7 +9563,7 @@ is not sent for the instruments in that directory.
-
+
Client may want to be notified when changes were made to instruments in the instruments database by issuing the following command: @@ -7094,7 +9593,7 @@ the new name of the instrument, encapsulated into apostrophes.
-
+
Client may want to be notified when the status of particular database instruments job is changed by issuing the following command: @@ -7116,7 +9615,84 @@ message is sufficient here.
-
+
+ Client may want to be notified when the number of effect instances + is changed by issuing the following command: + + + SUBSCRIBE EFFECT_INSTANCE_COUNT + + + Server will start sending the following notification messages: + + + "EFFECT_INSTANCE_COUNT:<instances>" + + + where <instances> will be replaced by the new number + of effect instances. +
+ +
+ Client may want to be notified when changes were made to effect instances + on the back-end by issuing the following command: + + + SUBSCRIBE EFFECT_INSTANCE_INFO + + + Server will start sending the following notification messages: + + + "EFFECT_INSTANCE_INFO:<instance-id>" + + + where <instance-id> will be replaced by the numerical ID + of the effect instance. +
+ +
+ Client may want to be notified when the number of send effect chains + is changed by issuing the following command: + + + SUBSCRIBE SEND_EFFECT_CHAIN_COUNT + + + Server will start sending the following notification messages: + + + "NOTIFY:SEND_EFFECT_CHAIN_COUNT:<device-id> <chains>" + + + where <device-id> will be replaced by the numerical ID of the audio + output device, in which the number of send effect chains is changed and + <chains> will be replaced by the new number of send effect chains. +
+ +
+ Client may want to be notified when changes were made to send effect chains + on the back-end by issuing the following command: + + + SUBSCRIBE SEND_EFFECT_CHAIN_INFO + + + Server will start sending the following notification messages: + + + "SEND_EFFECT_CHAIN_INFO:<device-id> <chain-id> <instances>" - + Notifies that the number of effect instances in a particular send effect chain + is changed, where <device-id> will be replaced by the numerical ID of the audio + output device the send effect chain belongs to, <chain-id> will be replaced + by the numerical ID of the send effect chain in which the number of effect instances + has changed and <instances> will be replaced by the new number + of effect instances in the specified send effect chain. + + +
+ +
Client may want to be notified of miscellaneous and debugging events occurring at the server by issuing the following command: