--- linuxsampler/trunk/Documentation/lscp.xml 2006/12/20 19:40:37 991
+++ linuxsampler/trunk/Documentation/lscp.xml 2007/03/29 09:40:45 1135
@@ -34,7 +34,7 @@
schoenebeck at software minus engineering dot org
-
+
LinuxSampler Developers
LSCP
@@ -2555,7 +2555,7 @@
VOLUME -
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)
@@ -3227,6 +3227,456 @@
+
+ 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
+
+
+ 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"
+ 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"
+ "."
+
+
+
+
+
+ The front-end can alter the current name of an effect
+ send entity by sending the following command:
+
+
+ SET FX_SEND NAME <sampler-chan> <fx-send-id> <name>
+
+
+ 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 and
+ <name> is the new name of the effect send entity, which
+ does not have to be unique.
+
+ 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 NAME 0 0 'Fx Send 1'"
+ S: "OK"
+
+
+
+
+
+ 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 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"
+ 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 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"
+
+
+
+
+
+ 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"
+ 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 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"
+
+
+
+
The front-end can reset a particular sampler channel by sending the following command:
@@ -3516,6 +3966,65 @@
The mentioned fields above don't have to be in particular order.
Other fields might be added in future.
+
+
+ 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.
+
+
+
+ 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
+
+
+
+
+
@@ -3730,6 +4239,12 @@
which does not have to be unique
+ DEFAULT -
+
+ either true or false,
+ defines whether this map is the default map
+
+
@@ -3789,7 +4304,7 @@
command:
- MAP MIDI_INSTRUMENT <map>
+ MAP MIDI_INSTRUMENT [NON_MODAL] <map>
<midi_bank> <midi_prog> <engine_name>
<filename> <instrument_index> <volume_value>
[<instr_load_mode>] [<name>]
@@ -3807,7 +4322,7 @@
<instrument_index> the index (integer value) of the instrument
within the given file, <volume_value> reflects the master
volume of the instrument as optionally dotted number (where a
- value < 1.0 means attenuation and a value > 1.0 means
+ value < 1.0 means attenuation and a value > 1.0 means
amplification). This parameter easily allows to adjust the
volume of all intruments within a custom instrument map
without having to adjust their instrument files. The
@@ -3842,7 +4357,7 @@
"PERSISTENT" -
The instrument will immediately be loaded
- into memory in the background when this mapping
+ into memory when this mapping
command is sent and the instrument is kept all
the time. Instruments with this mode are
only freed when the sampler is reset or all
@@ -3892,13 +4407,19 @@
"GET MIDI_INSTRUMENT INFO").
- The "MAP MIDI_INSTRUMENT" command
- will immediately return, thus it will not block when an
- instrument is to be loaded due to a "PERSISTENT" type
- entry as instruments are loaded in the background. As a
- consequence this command may not necessarily return an error
- i.e. when the given instrument file does not exist or may
- turn out to be corrupt.
+ By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is
+ completely established in the sampler. The OPTIONAL "NON_MODAL" argument
+ however causes the respective "MAP MIDI_INSTRUMENT" command to return
+ immediately, that is to let the sampler establish the mapping in the
+ background. So this argument might be especially useful for mappings with
+ a "PERSISTENT" type, because these have to load the respective instruments
+ immediately and might thus block for a very long time. It is recommended
+ however to use the OPTIONAL "NON_MODAL" argument only if really necessary,
+ because it has the following drawbacks: as "NON_MODAL" instructions return
+ immediately, they may not necessarily return an error i.e. when the given
+ instrument file turns out to be corrupt, beside that subsequent commands
+ in a LSCP instruction sequence might fail, because mandatory mappings are
+ not yet completed.
Possible Answers:
@@ -3941,7 +4462,7 @@
- C: "MAP MIDI_INSTRUMENT 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"
+ C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'"
S: "OK"
@@ -4140,7 +4661,7 @@
"VOLUME" -
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)
@@ -4329,6 +4850,10 @@
/ CHANNEL_INFO
+ / FX_SEND_COUNT
+
+ / FX_SEND_INFO
+
/ MIDI_INSTRUMENT_MAP_COUNT
/ MIDI_INSTRUMENT_MAP_INFO
@@ -4341,6 +4866,8 @@
/ TOTAL_VOICE_COUNT
+ / GLOBAL_INFO
+
unsubscribe_event =
@@ -4363,6 +4890,10 @@
/ CHANNEL_INFO
+ / FX_SEND_COUNT
+
+ / FX_SEND_INFO
+
/ MIDI_INSTRUMENT_MAP_COUNT
/ MIDI_INSTRUMENT_MAP_INFO
@@ -4375,17 +4906,19 @@
/ TOTAL_VOICE_COUNT
+ / GLOBAL_INFO
+
map_instruction =
- MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value
+ MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value
- / MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode
+ / MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode
- / MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP entry_name
+ / MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP entry_name
- / MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode SP entry_name
+ / MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode SP entry_name
@@ -4469,6 +5002,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
+
+ / VOLUME
+
set_instruction =
@@ -4485,8 +5024,18 @@
/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
+ / FX_SEND SP NAME SP sampler_channel SP fx_send_id SP fx_send_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
+
create_instruction =
@@ -4499,6 +5048,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 +5074,8 @@
/ MIDI_INPUT_DEVICE SP number
+ / FX_SEND SP sampler_channel SP fx_send_id
+
load_instruction =
@@ -4563,6 +5118,14 @@
+modal_arg =
+
+ /* epsilon (empty argument) */
+
+ / NON_MODAL SP
+
+
+
key_val_list =
string '=' param_val_list
@@ -4599,6 +5162,8 @@
/ MIDI_INSTRUMENT_MAPS
+ / FX_SENDS SP sampler_channel
+
load_instr_args =
@@ -4681,6 +5246,12 @@
+midi_ctrl =
+
+ number
+
+
+
volume_value =
dotnum
@@ -4701,6 +5272,12 @@
+fx_send_id =
+
+ number
+
+
+
engine_name =
string
@@ -4725,6 +5302,12 @@
+fx_send_name =
+
+ stringval
+
+
+
param_val_list =
param_val
@@ -4861,7 +5444,7 @@
Server will start sending the following notification messages:
- "NOTIFY:VOICE_COUNT:<sampler-channel> <voices>
+ "NOTIFY:VOICE_COUNT:<sampler-channel> <voices>"
where <sampler-channel> will be replaced by the sampler channel the
@@ -4931,6 +5514,44 @@
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:
+
+
+ SUBSCRIBE FX_SEND_COUNT
+
+
+ Server will start sending the following notification messages:
+
+
+ "NOTIFY:FX_SEND_COUNT:<channel-id> <fx-sends>"
+
+
+ where <channel-id> will be replaced by the numerical ID of the sampler
+ channel, on which the effect sends number is changed and <fx-sends> will
+ 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:
+
+
+ SUBSCRIBE FX_SEND_INFO
+
+
+ Server will start sending the following notification messages:
+
+
+ "NOTIFY:FX_SEND_INFO:<channel-id> <fx-send-id>"
+
+
+ where <channel-id> will be replaced by the numerical ID of the sampler
+ channel, on which an effect send entity is changed and <fx-send-id> will
+ 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:
@@ -4942,7 +5563,7 @@
Server will start sending the following notification messages:
- "NOTIFY:TOTAL_VOICE_COUNT:<voices>
+ "NOTIFY:TOTAL_VOICE_COUNT:<voices>"
where <voices> will be replaced by the new number of
@@ -5031,6 +5652,25 @@
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:
+
+
+ SUBSCRIBE GLOBAL_INFO
+
+
+ Server will start sending the following types of notification messages:
+
+
+ "NOTIFY:GLOBAL_INFO:VOLUME <volume>" - Notifies that the
+ golbal volume of the sampler is changed, where <volume> will be
+ replaced by the optional dotted floating point value, reflecting the
+ new global volume parameter.
+
+
+
+
Client may want to be notified of miscellaneous and debugging events occurring at
the server by issuing the following command: