-This Internet-Draft will expire on June 18, 2007.
+This Internet-Draft will expire on July 18, 2007.-Copyright © The Internet Society (2006).
+Copyright © The Internet Society (2007).@@ -4933,9 +4969,593 @@optionally dotted number for the channel volume factor - (where a value < 1.0 means attenuation and a value > + (where a value < 1.0 means attenuation and a value > 1.0 means amplification)
-
| TOC |
The front-end can create an additional effect send on a specific sampler channel + by sending the following command: +
++
++CREATE FX_SEND <sampler-channel> <midi-ctrl> [<name>] +
+
+ +
+Where <sampler-channel> is the respective sampler channel + number as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command, that is the + sampler channel on which the effect send should be created on, <midi-ctrl> + is a number between 0..127 defining the MIDI controller which can alter the + effect send level and <name> is an optional argument defining a name + for the effect send entity. The name does not have to be unique. +
+By default, that is as initial routing, the effect send's audio channels + are automatically routed to the last audio channels of the sampler channel's + audio output device, that way you can i.e. first increase the amount of audio + channels on the audio output device for having dedicated effect send output + channels and when "CREATE FX_SEND" is called, those channels will automatically + be picked. You can alter the destination channels however with + "SET FX_SEND AUDIO_OUTPUT_CHANNEL" (Altering effect send's audio routing). + +
+Note: Create effect sends on a sampler channel only when needed, because having effect + sends on a sampler channel will decrease runtime performance, because for implementing channel + effect sends, separate (sampler channel local) audio buffers are needed to render and mix + the voices and route the audio signal afterwards to the master outputs and effect send + outputs (along with their respective effect send levels). A sampler channel without effect + sends however can mix its voices directly into the audio output devices's audio buffers + and is thus faster. + +
+Possible Answers: +
++
++"OK[<fx-send-id>]" - +
+++ + +in case a new effect send could be added to the + sampler channel, where <fx-send-id> reflects the + unique ID of the newly created effect send entity +
+"ERR:<error-code>:<error-message>" - +
+++ + +when a new effect send could not be added, i.e. + due to invalid parameters +
+
+ +
+Examples: +
++
++C: "CREATE FX_SEND 0 91 'Reverb Send'" +
+S: "OK[0]" +
+
+ +
++
++C: "CREATE FX_SEND 0 93" +
+S: "OK[1]" +
+
+ +
+| TOC |
The front-end can remove an existing effect send on a specific sampler channel + by sending the following command: +
++
++DESTROY FX_SEND <sampler-channel> <fx-send-id> +
+
+ +
+Where <sampler-channel> is the respective sampler channel + number as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command, that is the + sampler channel from which the effect send should be removed from and + <fx-send-id> is the respective effect send number as returned by the + "CREATE FX_SEND" (Adding an effect send to a sampler channel) + or "LIST FX_SENDS" (Listing all effect sends on a sampler channel) command. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case it failed, providing an appropriate error code and + error message +
+
+ +
+Example: +
++
++C: "DESTROY FX_SEND 0 0" +
+S: "OK" +
+
+ +
+| TOC |
The front-end can ask for the amount of effect sends on a specific sampler channel + by sending the following command: +
++
++GET FX_SENDS <sampler-channel> +
+
+ +
+Where <sampler-channel> is the respective sampler channel + number as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command. +
+Possible Answers: +
++
++The sampler will answer by returning the number of effect + sends on the given sampler channel. +
+
+ +
+Example: +
++
++C: "GET FX_SENDS 0" +
+S: "2" +
+
+ +
+| TOC |
The front-end can ask for a list of effect sends on a specific sampler channel + by sending the following command: +
++
++LIST FX_SENDS <sampler-channel> +
+
+ +
+Where <sampler-channel> is the respective sampler channel + number as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command. +
+Possible Answers: +
++
++The sampler will answer by returning a comma separated list + with all effect sends' numerical IDs on the given sampler + channel. +
+
+ +
+Examples: +
++
++C: "LIST FX_SENDS 0" +
+S: "0,1" +
+
+ +
++
++C: "LIST FX_SENDS 1" +
+S: "" +
+
+ +
+| TOC |
The front-end can ask for the current settings of an effect send entity + by sending the following command: +
++
++GET FX_SEND INFO <sampler-channel> <fx-send-id> +
+
+ +
+Where <sampler-channel> is the sampler channel number + as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command and + <fx-send-id> reflects the numerical ID of the effect send entity + as returned by the "CREATE FX_SEND" (Adding an effect send to a sampler channel) + or "LIST FX_SENDS" (Listing all effect sends on a sampler channel) command. + +
+Possible Answers: +
++
++The sampler will answer by sending a <CRLF> separated list. + Each answer line begins with the settings category name + followed by a colon and then a space character <SP> and finally + the info character string to that setting category. At the + moment the following categories are defined: +
++
+++ + +NAME - +
+++ + +name of the effect send entity +
+MIDI_CONTROLLER - +
+++ + +a value between 0 and 127 reflecting the MIDI controller + which is able to modify the effect send's send level +
+LEVEL - +
+++ + +optionally dotted number reflecting the effect send's + current send level (where a value < 1.0 means attenuation + and a value > 1.0 means amplification) +
+AUDIO_OUTPUT_ROUTING - +
+++ + +comma separated list which reflects to which audio + channel of the selected audio output device each + effect send output channel is routed to, e.g. "0,3" would + mean the effect send's output channel 0 is routed to channel + 0 of the audio output device and the effect send's output + channel 1 is routed to the channel 3 of the audio + output device (see + "SET FX_SEND AUDIO_OUTPUT_CHANNEL" (Altering effect send's audio routing) + for details) +
+
+ +
+The mentioned fields above don't have to be in particular order. +
+Example: +
++
++C: "GET FX_SEND INFO 0 0" +
+S: "NAME: Reverb Send" +
+"MIDI_CONTROLLER: 91" +
+"LEVEL: 0.3" +
+"AUDIO_OUTPUT_ROUTING: 2,3" +
+"." +
+
+ +
+| TOC |
The front-end can alter the destination of an effect send's audio channel on a specific + sampler channel by sending the following command: +
++
++SET FX_SEND AUDIO_OUTPUT_CHANNEL <sampler-chan> <fx-send-id> <audio-src> <audio-dst> +
+
+ +
+Where <sampler-chan> is the sampler channel number + as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command, + <fx-send-id> reflects the numerical ID of the effect send entity + as returned by the "CREATE FX_SEND" (Adding an effect send to a sampler channel) + or "LIST FX_SENDS" (Listing all effect sends on a sampler channel) command, + <audio-src> is the numerical ID of the effect send's audio channel + which should be rerouted and <audio-dst> is the numerical ID of + the audio channel of the selected audio output device where <audio-src> + should be routed to. +
+Note that effect sends can only route audio to the same audio output + device as assigned to the effect send's sampler channel. Also note that an + effect send entity does always have exactly as much audio channels as its + sampler channel. So if the sampler channel is stereo, the effect send does + have two audio channels as well. Also keep in mind that the amount of audio + channels on a sampler channel might be dependant not only to the deployed + sampler engine on the sampler channel, but also dependant to the instrument + currently loaded. However you can (effectively) turn an i.e. stereo effect + send into a mono one by simply altering its audio routing appropriately. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"WRN:<warning-code>:<warning-message>" - +
+++ + +if audio output channel was set, but there are noteworthy + issue(s) related, providing an appropriate warning code and + warning message +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case it failed, providing an appropriate error code and error message +
+
+ +
+Example: +
++
++C: "SET FX_SEND AUDIO_OUTPUT_CHANNEL 0 0 0 2" +
+S: "OK" +
+
+ +
+| TOC |
The front-end can alter the MIDI controller of an effect + send entity by sending the following command: +
++
++SET FX_SEND MIDI_CONTROLLER <sampler-chan> <fx-send-id> <midi-ctrl> +
+
+ +
+Where <sampler-chan> is the sampler channel number + as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command, + <fx-send-id> reflects the numerical ID of the effect send entity + as returned by the "CREATE FX_SEND" (Adding an effect send to a sampler channel) + or "LIST FX_SENDS" (Listing all effect sends on a sampler channel) command and + <midi-ctrl> reflects the MIDI controller which shall be + able to modify the effect send's send level. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"WRN:<warning-code>:<warning-message>" - +
+++ + +if MIDI controller was set, but there are noteworthy + issue(s) related, providing an appropriate warning code and + warning message +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case it failed, providing an appropriate error code and error message +
+
+ +
+Example: +
++
++C: "SET FX_SEND MIDI_CONTROLLER 0 0 91" +
+S: "OK" +
+
+ +
+| TOC |
The front-end can alter the current send level of an effect + send entity by sending the following command: +
++
++SET FX_SEND LEVEL <sampler-chan> <fx-send-id> <volume> +
+
+ +
+Where <sampler-chan> is the sampler channel number + as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command, + <fx-send-id> reflects the numerical ID of the effect send entity + as returned by the "CREATE FX_SEND" (Adding an effect send to a sampler channel) + or "LIST FX_SENDS" (Listing all effect sends on a sampler channel) command and + <volume> is an optionally dotted positive number (a value + smaller than 1.0 means attenuation, whereas a value greater than + 1.0 means amplification) reflecting the new send level. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"WRN:<warning-code>:<warning-message>" - +
+++ + +if new send level was set, but there are noteworthy + issue(s) related, providing an appropriate warning code and + warning message +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case it failed, providing an appropriate error code and error message +
+
+ +
+Example: +
++
++C: "SET FX_SEND LEVEL 0 0 0.15" +
+S: "OK" +
+
+ +
+| TOC |
The front-end can reset a particular sampler channel by sending the following command: @@ -5376,6 +5996,94 @@
The mentioned fields above don't have to be in particular order. Other fields might be added in future.
+| TOC |
The client can ask for the current global sampler-wide volume + attenuation by sending the following command: +
++
++GET VOLUME +
+
+ +
+Possible Answers: +
++
++The sampler will always answer by returning the optional + dotted floating point coefficient, reflecting the current + global volume attenuation. + +
+
+ +
+Note: it is up to the respective sampler engine whether to obey + that global volume parameter or not, but in general all engines SHOULD + use this parameter. +
+| TOC |
The client can alter the current global sampler-wide volume + attenuation by sending the following command: +
++
++SET VOLUME <volume> +
+
+ +
+Where <volume> should be replaced by the optional dotted + floating point value, reflecting the new global volume parameter. + This value might usually be in the range between 0.0 and 1.0, that + is for attenuating the overall volume. +
+Possible Answers: +
++
++"OK" - +
+++ + +on success +
+"WRN:<warning-code>:<warning-message>" - +
+++ + +if the global volume was set, but there are noteworthy + issue(s) related, providing an appropriate warning code and + warning message +
+"ERR:<error-code>:<error-message>" - +
+++ + +in case it failed, providing an appropriate error code and error message +
+
+ +
| TOC |
@@ -6508,7 +7216,19 @@master volume of the instrument as optionally - dotted number (where a value < 1.0 means attenuation + dotted number (where a value < 1.0 means attenuation and a value > 1.0 means amplification)
subscribe_event =
-CHANNEL_COUNT +
AUDIO_OUTPUT_DEVICE_COUNT + +
+/ AUDIO_OUTPUT_DEVICE_INFO + +
+/ MIDI_INPUT_DEVICE_COUNT + +
+/ MIDI_INPUT_DEVICE_INFO + +
+/ CHANNEL_COUNT
/ VOICE_COUNT @@ -6523,6 +7243,18 @@
/ CHANNEL_INFO
+/ MIDI_INSTRUMENT_MAP_COUNT + +
+/ MIDI_INSTRUMENT_MAP_INFO + +
+/ MIDI_INSTRUMENT_COUNT + +
+/ MIDI_INSTRUMENT_INFO + +
/ MISCELLANEOUS
@@ -6535,7 +7267,19 @@unsubscribe_event =
-CHANNEL_COUNT +
AUDIO_OUTPUT_DEVICE_COUNT + +
+/ AUDIO_OUTPUT_DEVICE_INFO + +
+/ MIDI_INPUT_DEVICE_COUNT + +
+/ MIDI_INPUT_DEVICE_INFO + +
+/ CHANNEL_COUNT
/ VOICE_COUNT @@ -6550,6 +7294,18 @@
/ CHANNEL_INFO
+/ MIDI_INSTRUMENT_MAP_COUNT + +
+/ MIDI_INSTRUMENT_MAP_INFO + +
+/ MIDI_INSTRUMENT_COUNT + +
+/ MIDI_INSTRUMENT_INFO + +
/ MISCELLANEOUS
@@ -6697,6 +7453,15 @@/ MIDI_INSTRUMENT_MAP SP INFO SP midi_map
+/ FX_SENDS SP sampler_channel + +
+/ FX_SEND SP INFO SP sampler_channel SP fx_send_id + +
+/ VOLUME + +
@@ -6721,9 +7486,21 @@
/ 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 + +
+/ FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP midi_ctrl + +
+/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value + +
/ ECHO SP boolean
+/ VOLUME SP volume_value + +
@@ -6742,6 +7519,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 + +
@@ -6775,6 +7558,9 @@
/ MIDI_INPUT_DEVICE SP number
+/ FX_SEND SP sampler_channel SP fx_send_id + +
@@ -6892,6 +7678,9 @@
/ MIDI_INSTRUMENT_MAPS
+/ FX_SENDS SP sampler_channel + +
@@ -7015,6 +7804,15 @@
+
midi_ctrl = +
++number + +
+
+ +
volume_value =
@@ -7045,6 +7843,15 @@
+
fx_send_id = +
++number + +
+
+ +
engine_name =
@@ -7081,6 +7888,15 @@
+
fx_send_name = +
++stringval + +
+
+ +
param_val_list =
@@ -7118,9 +7934,133 @@This chapter will describe all currently defined events supported by LinuxSampler.
-
+
TOC 8.1. +Number of audio output devices changed
+ +Client may want to be notified when the total number of audio output devices on the + back-end changes by issuing the following command: +
++
++SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT +
++ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:AUDIO_OUTPUT_DEVICE_COUNT:<devices>" +
++ +
+where <devices> will be replaced by the new number + of audio output devices. +
+
++
TOC 8.2. +Audio output device's settings changed
+ +Client may want to be notified when changes were made to audio output devices on the + back-end by issuing the following command: +
++
++SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO +
++ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:AUDIO_OUTPUT_DEVICE_INFO:<device-id>" +
++ +
+where <device-id> will be replaced by the numerical ID of the audio output device, + which settings has been changed. The front-end will have to send + the respective command to actually get the audio output device info. Because these messages + will be triggered by LSCP commands issued by other clients rather than real + time events happening on the server, it is believed that an empty notification + message is sufficient here. +
+
++
TOC 8.3. +Number of MIDI input devices changed
+ +Client may want to be notified when the total number of MIDI input devices on the + back-end changes by issuing the following command: +
++
++SUBSCRIBE MIDI_INPUT_DEVICE_COUNT +
++ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:MIDI_INPUT_DEVICE_COUNT:<devices>" +
++ +
+where <devices> will be replaced by the new number + of MIDI input devices. +
+
++
TOC 8.4. +MIDI input device's settings changed
+ +Client may want to be notified when changes were made to MIDI input devices on the + back-end by issuing the following command: +
++
++SUBSCRIBE MIDI_INPUT_DEVICE_INFO +
++ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:MIDI_INPUT_DEVICE_INFO:<device-id>" +
++ +
+where <device-id> will be replaced by the numerical ID of the MIDI input device, + which settings has been changed. The front-end will have to send + the respective command to actually get the MIDI input device info. Because these messages + will be triggered by LSCP commands issued by other clients rather than real + time events happening on the server, it is believed that an empty notification + message is sufficient here. +
+
++
TOC 8.5. Number of sampler channels changed
Client may want to be notified when the total number of channels on the @@ -7149,7 +8089,7 @@
-
TOC 8.2. +
8.6. Number of active voices changed
Client may want to be notified when the number of voices on the @@ -7179,7 +8119,7 @@
-
TOC 8.3. +
8.7. Number of active disk streams changed
Client may want to be notified when the number of streams on the back-end @@ -7209,7 +8149,7 @@
-
TOC 8.4. +
8.8. Disk stream buffer fill state changed
Client may want to be notified when the buffer fill state of a disk stream @@ -7238,9 +8178,9 @@ buffer fill data for this channel as described in Section 6.4.13 (Current fill state of disk stream buffers) as if the "GET CHANNEL BUFFER_FILL PERCENTAGE" (Current fill state of disk stream buffers) command was issued on this channel.
-
+
-
TOC 8.5. +
8.9. Channel information changed
Client may want to be notified when changes were made to sampler channels on the @@ -7273,7 +8213,7 @@
-
TOC 8.6. +
8.10. Total number of active voices changed
Client may want to be notified when the total number of voices on the @@ -7300,9 +8240,135 @@
where <voices> will be replaced by the new number of all currently active voices.
+
++
TOC 8.11. +Number of MIDI instrument maps changed
+ +Client may want to be notified when the number of MIDI instrument maps on the + back-end changes by issuing the following command: +
++
++SUBSCRIBE MIDI_INSTRUMENT_MAP_COUNT +
++ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:MIDI_INSTRUMENT_MAP_COUNT:<maps>" +
++ +
+where <maps> will be replaced by the new number + of MIDI instrument maps. +
+
++
TOC 8.12. +MIDI instrument map information changed
+ +Client may want to be notified when changes were made to MIDI instrument maps on the + back-end by issuing the following command: +
++
++SUBSCRIBE MIDI_INSTRUMENT_MAP_INFO +
++ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:MIDI_INSTRUMENT_MAP_INFO:<map-id>" +
++ +
+where <map-id> will be replaced by the numerical ID of the MIDI instrument map, + for which information changes occurred. The front-end will have to send + the respective command to actually get the MIDI instrument map info. Because these messages + will be triggered by LSCP commands issued by other clients rather than real + time events happening on the server, it is believed that an empty notification + message is sufficient here. +
+
++
TOC 8.13. +Number of MIDI instruments changed
+ +Client may want to be notified when the number of MIDI instrument maps on the + back-end changes by issuing the following command: +
++
++SUBSCRIBE MIDI_INSTRUMENT_COUNT +
++ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:MIDI_INSTRUMENT_COUNT:<map-id> <instruments>" +
++ +
+where <map-id> is the numerical ID of the MIDI instrument map, in which + the nuber of instruments has changed and <instruments> will be replaced by + the new number of MIDI instruments in the specified map. +
+
++
TOC 8.14. +MIDI instrument information changed
+ +Client may want to be notified when changes were made to MIDI instruments on the + back-end by issuing the following command: +
++
++SUBSCRIBE MIDI_INSTRUMENT_INFO +
++ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:MIDI_INSTRUMENT_INFO:<map-id> <bank> <program>" +
++ +
+where <map-id> will be replaced by the numerical ID of the MIDI instrument map, + in which a MIDI instrument is changed. <bank> and <program> specifies + the location of the changed MIDI instrument in the map. The front-end will have to send + the respective command to actually get the MIDI instrument info. Because these messages + will be triggered by LSCP commands issued by other clients rather than real + time events happening on the server, it is believed that an empty notification + message is sufficient here. +
-
TOC 8.7. +
8.15. Miscellaneous and debugging events
Client may want to be notified of miscellaneous and debugging events occurring at @@ -7397,7 +8463,7 @@
TOC Full Copyright Statement
-Copyright © The Internet Society (2006).
+Copyright © The Internet Society (2007).This document is subject to the rights, licenses and restrictions contained in BCP 78,