--- linuxsampler/trunk/Documentation/lscp.xml 2006/12/18 10:28:00 984
+++ linuxsampler/trunk/Documentation/lscp.xml 2006/12/27 16:17:08 1001
@@ -3227,6 +3227,304 @@
+
+ The front-end can create an additional effect send on a specific sampler channel
+ by sending the following command:
+
+
+ CREATE FX_SEND <sampler-channel> <midi-ctrl> [<name>]
+
+
+ Where <sampler-channel> is the respective sampler channel
+ number as returned by the "ADD CHANNEL"
+ or "LIST CHANNELS" command, that is the
+ sampler channel on which the effect send should be created on, <midi-ctrl>
+ is a number between 0..127 defining the MIDI controller which can alter the
+ effect send level and <name> is an optional argument defining a name
+ for the effect send entity. The name does not have to be unique.
+
+ By default, that is as initial routing, the effect send's audio channels
+ are automatically routed to the last audio channels of the sampler channel's
+ audio output device, that way you can i.e. first increase the amount of audio
+ channels on the audio output device for having dedicated effect send output
+ channels and when "CREATE FX_SEND" is called, those channels will automatically
+ be picked. You can alter the destination channels however with
+ "SET FX_SEND AUDIO_OUTPUT_CHANNEL".
+
+
+ Note: Create effect sends on a sampler channel only when needed, because having effect
+ sends on a sampler channel will decrease runtime performance, because for implementing channel
+ effect sends, separate (sampler channel local) audio buffers are needed to render and mix
+ the voices and route the audio signal afterwards to the master outputs and effect send
+ outputs (along with their respective effect send levels). A sampler channel without effect
+ sends however can mix its voices directly into the audio output devices's audio buffers
+ and is thus faster.
+
+
+ Possible Answers:
+
+
+ "OK[<fx-send-id>]" -
+
+ in case a new effect send could be added to the
+ sampler channel, where <fx-send-id> reflects the
+ unique ID of the newly created effect send entity
+
+
+ "ERR:<error-code>:<error-message>" -
+
+ when a new effect send could not be added, i.e.
+ due to invalid parameters
+
+
+
+
+
+ Examples:
+
+
+ C: "CREATE FX_SEND 0 91 'Reverb Send'"
+ S: "OK[0]"
+
+
+
+
+ C: "CREATE FX_SEND 0 93"
+ S: "OK[1]"
+
+
+
+
+
+ The front-end can remove an existing effect send on a specific sampler channel
+ by sending the following command:
+
+
+ DESTROY FX_SEND <sampler-channel> <fx-send-id>
+
+
+ Where <sampler-channel> is the respective sampler channel
+ number as returned by the "ADD CHANNEL"
+ or "LIST CHANNELS" command, that is the
+ sampler channel from which the effect send should be removed from and
+ <fx-send-id> is the respective effect send number as returned by the
+ "CREATE FX_SEND"
+ or "LIST FX_SENDS" command.
+
+ Possible Answers:
+
+
+ "OK" -
+
+ on success
+
+
+ "ERR:<error-code>:<error-message>" -
+
+ in case it failed, providing an appropriate error code and
+ error message
+
+
+
+
+
+ Example:
+
+
+ C: "DESTROY FX_SEND 0 0"
+ S: "OK"
+
+
+
+
+
+ The front-end can ask for the amount of effect sends on a specific sampler channel
+ by sending the following command:
+
+
+ GET FX_SENDS <sampler-channel>
+
+
+ Where <sampler-channel> is the respective sampler channel
+ number as returned by the "ADD CHANNEL"
+ or "LIST CHANNELS" command.
+
+ Possible Answers:
+
+
+ The sampler will answer by returning the number of effect
+ sends on the given sampler channel.
+
+
+
+ Example:
+
+
+ C: "GET FX_SENDS 0"
+ S: "2"
+
+
+
+
+
+ The front-end can ask for a list of effect sends on a specific sampler channel
+ by sending the following command:
+
+
+ LIST FX_SENDS <sampler-channel>
+
+
+ Where <sampler-channel> is the respective sampler channel
+ number as returned by the "ADD CHANNEL"
+ or "LIST CHANNELS" command.
+
+ Possible Answers:
+
+
+ The sampler will answer by returning a comma separated list
+ with all effect sends' numerical IDs on the given sampler
+ channel.
+
+
+
+ Examples:
+
+
+ C: "LIST FX_SENDS 0"
+ S: "0,1"
+
+
+
+
+ C: "LIST FX_SENDS 1"
+ S: ""
+
+
+
+
+
+ The front-end can ask for the current settings of an effect send entity
+ by sending the following command:
+
+
+ GET FX_SEND INFO <sampler-channel> <fx-send-id>
+
+
+ Where <sampler-channel> is the sampler channel number
+ as returned by the "ADD CHANNEL"
+ or "LIST CHANNELS" command and
+ <fx-send-id> reflects the numerical ID of the effect send entity
+ as returned by the "CREATE FX_SEND"
+ or "LIST FX_SENDS" command.
+
+
+ Possible Answers:
+
+
+ The sampler will answer by sending a <CRLF> separated list.
+ Each answer line begins with the settings category name
+ followed by a colon and then a space character <SP> and finally
+ the info character string to that setting category. At the
+ moment the following categories are defined:
+
+
+
+ NAME -
+
+ name of the effect send entity
+
+
+ AUDIO_OUTPUT_ROUTING -
+
+ comma separated list which reflects to which audio
+ channel of the selected audio output device each
+ effect send output channel is routed to, e.g. "0,3" would
+ mean the effect send's output channel 0 is routed to channel
+ 0 of the audio output device and the effect send's output
+ channel 1 is routed to the channel 3 of the audio
+ output device (see
+ "SET FX_SEND AUDIO_OUTPUT_CHANNEL"
+ for details)
+
+
+
+
+
+
+ The mentioned fields above don't have to be in particular order.
+
+ Example:
+
+
+ C: "GET FX_SEND INFO 0 0"
+ S: "NAME: Reverb Send"
+ "AUDIO_OUTPUT_ROUTING: 2,3"
+ "."
+
+
+
+
+
+ The front-end can alter the destination of an effect send's audio channel on a specific
+ sampler channel by sending the following command:
+
+
+ SET FX_SEND AUDIO_OUTPUT_CHANNEL <sampler-chan> <fx-send-id> <audio-src> <audio-dst>
+
+
+ Where <sampler-chan> is the sampler channel number
+ as returned by the "ADD CHANNEL"
+ 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,
+ <audio-src> is the numerical ID of the effect send's audio channel
+ which should be rerouted and <audio-dst> is the numerical ID of
+ the audio channel of the selected audio output device where <audio-src>
+ should be routed to.
+
+ Note that effect sends can only route audio to the same audio output
+ device as assigned to the effect send's sampler channel. Also note that an
+ effect send entity does always have exactly as much audio channels as its
+ sampler channel. So if the sampler channel is stereo, the effect send does
+ have two audio channels as well. Also keep in mind that the amount of audio
+ channels on a sampler channel might be dependant not only to the deployed
+ sampler engine on the sampler channel, but also dependant to the instrument
+ currently loaded. However you can (effectively) turn an i.e. stereo effect
+ send into a mono one by simply altering its audio routing appropriately.
+
+ Possible Answers:
+
+
+ "OK" -
+
+ on success
+
+
+ "WRN:<warning-code>:<warning-message>" -
+
+ if audio output channel was set, but there are noteworthy
+ issue(s) related, providing an appropriate warning code and
+ warning message
+
+
+ "ERR:<error-code>:<error-message>" -
+
+ in case it failed, providing an appropriate error code and error message
+
+
+
+
+ Example:
+
+
+ C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2"
+ S: "OK"
+
+
+
+
+
The front-end can reset a particular sampler channel by sending the following command:
@@ -4469,6 +4767,10 @@
/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map
+ / FX_SENDS SP sampler_channel
+
+ / FX_SEND SP INFO SP sampler_channel SP fx_send_id
+
set_instruction =
@@ -4485,6 +4787,8 @@
/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
+ / FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id SP audio_channel_index SP audio_channel_index
+
/ ECHO SP boolean
@@ -4499,6 +4803,10 @@
/ MIDI_INPUT_DEVICE SP string
+ / FX_SEND SP sampler_channel SP midi_ctrl
+
+ / FX_SEND SP sampler_channel SP midi_ctrl SP fx_send_name
+
reset_instruction =
@@ -4521,6 +4829,8 @@
/ MIDI_INPUT_DEVICE SP number
+ / FX_SEND SP sampler_channel SP fx_send_id
+
load_instruction =
@@ -4599,6 +4909,8 @@
/ MIDI_INSTRUMENT_MAPS
+ / FX_SENDS SP sampler_channel
+
load_instr_args =
@@ -4681,6 +4993,12 @@
+midi_ctrl =
+
+ number
+
+
+
volume_value =
dotnum
@@ -4701,6 +5019,12 @@
+fx_send_id =
+
+ number
+
+
+
engine_name =
string
@@ -4725,6 +5049,12 @@
+fx_send_name =
+
+ stringval
+
+
+
param_val_list =
param_val
@@ -5031,7 +5361,7 @@
message is sufficient here.
- <
+
Client may want to be notified of miscellaneous and debugging events occurring at
the server by issuing the following command: