--- web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.html 2006/12/27 16:17:08 1001 +++ web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.html 2006/12/27 16:23:46 1002 @@ -145,7 +145,7 @@
-This Internet-Draft will expire on June 23, 2007.
+This Internet-Draft will expire on June 30, 2007.
@@ -318,7 +318,19 @@
Soloing a sampler channel
6.4.24.
Assigning a MIDI instrument map to a sampler channel
- 6.4.25.
+ 6.4.25.
+Adding an effect send to a sampler channel
+ 6.4.26.
+Removing an effect send from a sampler channel
+ 6.4.27.
+Getting amount of effect sends on a sampler channel
+ 6.4.28.
+Listing all effect sends on a sampler channel
+ 6.4.29.
+Getting effect send information
+ 6.4.30.
+Altering effect send's audio routing
+ 6.4.31.
Resetting a sampler channel
6.5.
Controlling connection
@@ -4949,9 +4961,427 @@
-
TOC |
The front-end can create an additional effect send on a specific sampler channel + by sending the following command: +
++
++CREATE FX_SEND <sampler-channel> <midi-ctrl> [<name>] +
+
+ +
+Where <sampler-channel> is the respective sampler channel + number as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command, that is the + sampler channel on which the effect send should be created on, <midi-ctrl> + is a number between 0..127 defining the MIDI controller which can alter the + effect send level and <name> is an optional argument defining a name + for the effect send entity. The name does not have to be unique. +
+By default, that is as initial routing, the effect send's audio channels + are automatically routed to the last audio channels of the sampler channel's + audio output device, that way you can i.e. first increase the amount of audio + channels on the audio output device for having dedicated effect send output + channels and when "CREATE FX_SEND" is called, those channels will automatically + be picked. You can alter the destination channels however with + "SET FX_SEND AUDIO_OUTPUT_CHANNEL" (Altering effect send's audio routing). + +
+Note: Create effect sends on a sampler channel only when needed, because having effect + sends on a sampler channel will decrease runtime performance, because for implementing channel + effect sends, separate (sampler channel local) audio buffers are needed to render and mix + the voices and route the audio signal afterwards to the master outputs and effect send + outputs (along with their respective effect send levels). A sampler channel without effect + sends however can mix its voices directly into the audio output devices's audio buffers + and is thus faster. + +
+Possible Answers: +
++
++"OK[<fx-send-id>]" - +
+++ + +in case a new effect send could be added to the + sampler channel, where <fx-send-id> reflects the + unique ID of the newly created effect send entity +
+"ERR:<error-code>:<error-message>" - +
+++ + +when a new effect send could not be added, i.e. + due to invalid parameters +
+
+ +
+Examples: +
++
++C: "CREATE FX_SEND 0 91 'Reverb Send'" +
+S: "OK[0]" +
+
+ +
++
++C: "CREATE FX_SEND 0 93" +
+S: "OK[1]" +
+
+ +
+TOC |
The front-end can remove an existing effect send on a specific sampler channel + by sending the following command: +
++
++DESTROY FX_SEND <sampler-channel> <fx-send-id> +
+
+ +
+Where <sampler-channel> is the respective sampler channel + number as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command, that is the + sampler channel from which the effect send should be removed from and + <fx-send-id> is the respective effect send number as returned by the + "CREATE FX_SEND" (Adding an effect send to a sampler channel) + or "LIST FX_SENDS" (Listing all effect sends on a sampler channel) command. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case it failed, providing an appropriate error code and + error message +
+
+ +
+Example: +
++
++C: "DESTROY FX_SEND 0 0" +
+S: "OK" +
+
+ +
+TOC |
The front-end can ask for the amount of effect sends on a specific sampler channel + by sending the following command: +
++
++GET FX_SENDS <sampler-channel> +
+
+ +
+Where <sampler-channel> is the respective sampler channel + number as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command. +
+Possible Answers: +
++
++The sampler will answer by returning the number of effect + sends on the given sampler channel. +
+
+ +
+Example: +
++
++C: "GET FX_SENDS 0" +
+S: "2" +
+
+ +
+TOC |
The front-end can ask for a list of effect sends on a specific sampler channel + by sending the following command: +
++
++LIST FX_SENDS <sampler-channel> +
+
+ +
+Where <sampler-channel> is the respective sampler channel + number as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command. +
+Possible Answers: +
++
++The sampler will answer by returning a comma separated list + with all effect sends' numerical IDs on the given sampler + channel. +
+
+ +
+Examples: +
++
++C: "LIST FX_SENDS 0" +
+S: "0,1" +
+
+ +
++
++C: "LIST FX_SENDS 1" +
+S: "" +
+
+ +
+TOC |
The front-end can ask for the current settings of an effect send entity + by sending the following command: +
++
++GET FX_SEND INFO <sampler-channel> <fx-send-id> +
+
+ +
+Where <sampler-channel> is the sampler channel number + as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command and + <fx-send-id> reflects the numerical ID of the effect send entity + as returned by the "CREATE FX_SEND" (Adding an effect send to a sampler channel) + or "LIST FX_SENDS" (Listing all effect sends on a sampler channel) command. + +
+Possible Answers: +
++
++The sampler will answer by sending a <CRLF> separated list. + Each answer line begins with the settings category name + followed by a colon and then a space character <SP> and finally + the info character string to that setting category. At the + moment the following categories are defined: +
++
+++ + +NAME - +
+++ + +name of the effect send entity +
+AUDIO_OUTPUT_ROUTING - +
+++ + +comma separated list which reflects to which audio + channel of the selected audio output device each + effect send output channel is routed to, e.g. "0,3" would + mean the effect send's output channel 0 is routed to channel + 0 of the audio output device and the effect send's output + channel 1 is routed to the channel 3 of the audio + output device (see + "SET FX_SEND AUDIO_OUTPUT_CHANNEL" (Altering effect send's audio routing) + for details) +
+
+ +
+The mentioned fields above don't have to be in particular order. +
+Example: +
++
++C: "GET FX_SEND INFO 0 0" +
+S: "NAME: Reverb Send" +
+"AUDIO_OUTPUT_ROUTING: 2,3" +
+"." +
+
+ +
+TOC |
The front-end can alter the destination of an effect send's audio channel on a specific + sampler channel by sending the following command: +
++
++SET FX_SEND AUDIO_OUTPUT_CHANNEL <sampler-chan> <fx-send-id> <audio-src> <audio-dst> +
+
+ +
+Where <sampler-chan> is the sampler channel number + as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command, + <fx-send-id> reflects the numerical ID of the effect send entity + as returned by the "CREATE FX_SEND" (Adding an effect send to a sampler channel) + or "LIST FX_SENDS" (Listing all effect sends on a sampler channel) command, + <audio-src> is the numerical ID of the effect send's audio channel + which should be rerouted and <audio-dst> is the numerical ID of + the audio channel of the selected audio output device where <audio-src> + should be routed to. +
+Note that effect sends can only route audio to the same audio output + device as assigned to the effect send's sampler channel. Also note that an + effect send entity does always have exactly as much audio channels as its + sampler channel. So if the sampler channel is stereo, the effect send does + have two audio channels as well. Also keep in mind that the amount of audio + channels on a sampler channel might be dependant not only to the deployed + sampler engine on the sampler channel, but also dependant to the instrument + currently loaded. However you can (effectively) turn an i.e. stereo effect + send into a mono one by simply altering its audio routing appropriately. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"WRN:<warning-code>:<warning-message>" - +
+++ + +if audio output channel was set, but there are noteworthy + issue(s) related, providing an appropriate warning code and + warning message +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case it failed, providing an appropriate error code and error message +
+
+ +
+Example: +
++
++C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2" +
+S: "OK" +
+
+ +
+TOC |
The front-end can reset a particular sampler channel by sending the following command: @@ -6761,6 +7191,12 @@
/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map
+/ FX_SENDS SP sampler_channel + +
+/ FX_SEND SP INFO SP sampler_channel SP fx_send_id + +
@@ -6785,6 +7221,9 @@
/ 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
@@ -6806,6 +7245,12 @@/ 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 + +
@@ -6839,6 +7284,9 @@
/ MIDI_INPUT_DEVICE SP number
+/ FX_SEND SP sampler_channel SP fx_send_id + +
@@ -6956,6 +7404,9 @@
/ MIDI_INSTRUMENT_MAPS
+/ FX_SENDS SP sampler_channel + +
@@ -7079,6 +7530,15 @@
+
midi_ctrl = +
++number + +
+
+ +
volume_value =
@@ -7109,6 +7569,15 @@
+
fx_send_id = +
++number + +
+
+ +
engine_name =
@@ -7140,6 +7609,15 @@stringval + +
++ +
+fx_send_name = +
++stringval