--- linuxsampler/trunk/Documentation/lscp.xml 2005/07/20 21:43:23 705 +++ linuxsampler/trunk/Documentation/lscp.xml 2007/03/22 20:39:04 1108 @@ -11,9 +11,12 @@ - - + + + + LinuxSampler Control Protocol "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 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: @@ -3226,6 +3821,42 @@
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: + + + GET TOTAL_VOICE_COUNT + + + + Possible Answers: + + + LinuxSampler will answer by returning the number of all active + voices on the sampler. + + +
+ +
+ The front-end can ask for the maximum number of active voices + by sending the following command: + + + GET TOTAL_VOICE_COUNT_MAX + + + + Possible Answers: + + + LinuxSampler will answer by returning the maximum number + of active voices. + + +
+
The front-end can reset the whole sampler by sending the following command: @@ -3294,9 +3925,770 @@ 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 + + + + +
+
+ + +
+ The MIDI protocol provides a way to switch between instruments + by sending so called MIDI bank select and MIDI program change + messages which are essentially just numbers. The following commands + allow to actually map arbitrary MIDI bank select / program change + numbers with real instruments. + The sampler allows to manage an arbitrary amount of MIDI + instrument maps which define which instrument to load on + which MIDI program change message. + By default, that is when the sampler is launched, there is no + map, thus the sampler will simply ignore all program change + messages. The front-end has to explicitly create at least one + map, add entries to the map and tell the respective sampler + channel(s) which MIDI instrument map to use, so the sampler + knows how to react on a given program change message on the + respective sampler channel, that is by switching to the + respectively defined engine type and loading the respective + instrument. See command + "SET CHANNEL MIDI_INSTRUMENT_MAP" + for how to assign a MIDI instrument map to a sampler channel. + Also note per MIDI specification a bank select message does not + cause to switch to another instrument. Instead when receiving a + bank select message the bank value will be stored and a subsequent + program change message (which may occur at any time) will finally + 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: + + + ADD MIDI_INSTRUMENT_MAP [<name>] + + + 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. + + Possible Answers: + + + "OK[<map>]" - + + in case a new MIDI instrument map could + be added, where <map> reflects the + unique ID of the newly created MIDI + instrument map + + + "ERR:<error-code>:<error-message>" - + + when a new map could not be created, which + might never occur in practice + + + + + + Examples: + + + C: "ADD MIDI_INSTRUMENT_MAP 'Standard Map'" + S: "OK[0]" + + + + + C: "ADD MIDI_INSTRUMENT_MAP 'Standard Drumkit'" + S: "OK[1]" + + + + + C: "ADD MIDI_INSTRUMENT_MAP" + S: "OK[5]" + + +
+ +
+ The front-end can delete a particular MIDI instrument map + by sending the following command: + + + REMOVE MIDI_INSTRUMENT_MAP <map> + + + Where <map> reflects the unique ID of the map to delete + as returned by the "LIST MIDI_INSTRUMENT_MAPS" + command. + The front-end can delete all MIDI instrument maps by + sending the following command: + + + REMOVE MIDI_INSTRUMENT_MAP ALL + + + + Possible Answers: + + + "OK" - + + in case the map(s) could be deleted + + + "ERR:<error-code>:<error-message>" - + + when the given map does not exist + + + + + + Examples: + + + C: "REMOVE MIDI_INSTRUMENT_MAP 0" + S: "OK" + + + + + C: "REMOVE MIDI_INSTRUMENT_MAP ALL" + S: "OK" + + +
+ +
+ The front-end can retrieve the current amount of MIDI + instrument maps by sending the following command: + + + GET MIDI_INSTRUMENT_MAPS + + + + Possible Answers: + + + The sampler will answer by returning the current + number of MIDI instrument maps. + + + + Example: + + + C: "GET MIDI_INSTRUMENT_MAPS" + S: "2" + + +
+ +
+ 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: + + + LIST MIDI_INSTRUMENT_MAPS + + + Possible Answers: + + + The sampler will answer by returning a comma separated list + with all MIDI instrument maps' numerical IDs. + + + Example: + + + C: "LIST MIDI_INSTRUMENT_MAPS" + S: "0,1,5,12" + + +
+ +
+ The front-end can ask for the current settings of a MIDI + instrument map by sending the following command: + + + GET MIDI_INSTRUMENT_MAP INFO <map> + + + Where <map> is the numerical ID of the map the + front-end is interested in as returned by the + "LIST MIDI_INSTRUMENT_MAPS" + command. + + 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 - + + custom name of the given map, + which does not have to be unique + + + + + + + The mentioned fields above don't have to be in particular order. + + Example: + + + C: "GET MIDI_INSTRUMENT_MAP INFO 0" + S: "NAME: Standard Map" +    "." + + +
+ +
+ The front-end can alter the custom name of a MIDI + instrument map by sending the following command: + + + SET MIDI_INSTRUMENT_MAP NAME <map> <name> + + + 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. + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + in case the given map does not exist + + + + + + Example: + + + C: "SET MIDI_INSTRUMENT_MAP NAME 0 'Foo instruments'" + S: "OK" + + +
+ +
+ The front-end can create a new or replace an existing entry + in a sampler's MIDI instrument map by sending the following + command: + + + MAP MIDI_INSTRUMENT [NON_MODAL] <map> + <midi_bank> <midi_prog> <engine_name> + <filename> <instrument_index> <volume_value> + [<instr_load_mode>] [<name>] + + + Where <map> is the numeric ID of the map to alter, + <midi_bank> is an integer value between + 0..16383 reflecting the MIDI bank select index, + <midi_prog> an + integer value between 0..127 reflecting the MIDI program change + index, <engine_name> a sampler engine name as returned by + the "LIST AVAILABLE_ENGINES" + command (not encapsulated into apostrophes), <filename> the name + of the instrument's file to be deployed (encapsulated into apostrophes), + <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 + 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 + OPTIONAL <instr_load_mode> argument defines the life + time of the instrument, that is when the instrument should + be loaded, when freed and has exactly the following + possibilities: + + + "ON_DEMAND" - + + The instrument will be loaded when needed, + that is when demanded by at least one sampler + channel. It will immediately be freed from memory + when not needed by any sampler channel anymore. + + + "ON_DEMAND_HOLD" - + + The instrument will be loaded when needed, + that is when demanded by at least one sampler + channel. It will be kept in memory even when + not needed by any sampler channel anymore. + Instruments with this mode are only freed + when the sampler is reset or all mapping + entries with this mode (and respective + instrument) are explicitly changed to + "ON_DEMAND" and no sampler channel is using + the instrument anymore. + + + "PERSISTENT" - + + The instrument will immediately be loaded + 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 + mapping entries with this mode (and + respective instrument) are explicitly + changed to "ON_DEMAND" and no sampler + channel is using the instrument anymore. + + + not supplied - + + In case there is no <instr_load_mode> + argument given, it will be up to the + InstrumentManager to decide which mode to use. + Usually it will use "ON_DEMAND" if an entry + for the given instrument does not exist in + the InstrumentManager's list yet, otherwise + if an entry already exists, it will simply + stick with the mode currently reflected by + the already existing entry, that is it will + not change the mode. + + + + + + The <instr_load_mode> argument thus allows to define an + appropriate strategy (low memory consumption vs. fast + instrument switching) for each instrument individually. Note, the + following restrictions apply to this argument: "ON_DEMAND_HOLD" and + "PERSISTENT" have to be supported by the respective sampler engine + (which is technically the case when the engine provides an + InstrumentManager for its format). If this is not the case the + argument will automatically fall back to the default value + "ON_DEMAND". Also the load mode of one instrument may + automatically change the laod mode of other instrument(s), i.e. + because the instruments are part of the same file and the + engine does not allow a way to manage load modes for them + individually. Due to this, in case the frontend shows the + 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 + mapped instruments (using + "GET MIDI_INSTRUMENT INFO"). + + + 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: + + + "OK" - + + usually + + + "ERR:<error-code>:<error-message>" - + + when the given map or engine does not exist or a value + is out of range + + + + + + Examples: + + + C: "MAP MIDI_INSTRUMENT 0 3 0 gig '/usr/share/Steinway D.gig' 0 0.8 PERSISTENT" + S: "OK" + + + + + C: "MAP MIDI_INSTRUMENT 0 4 50 gig '/home/john/foostrings.gig' 7 1.0" + S: "OK" + + + + + C: "MAP MIDI_INSTRUMENT 0 0 0 gig '/usr/share/piano.gig' 0 1.0 'Normal Piano'" + S: "OK" + C: "MAP MIDI_INSTRUMENT 0 1 0 gig '/usr/share/piano.gig' 0 0.25 'Silent Piano'" + S: "OK" + + + + + C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'" + S: "OK" + + +
+ +
+ The front-end can query the amount of currently existing + entries in a MIDI instrument map by sending the following + command: + + + GET MIDI_INSTRUMENTS <map> + + + The front-end can query the amount of currently existing + entries in all MIDI instrument maps by sending the following + command: + + + GET MIDI_INSTRUMENTS ALL + + + Possible Answers: + + + The sampler will answer by sending the current number of + entries in the MIDI instrument map(s). + + + + Example: + + + C: "GET MIDI_INSTRUMENTS 0" + S: "234" + + + + + C: "GET MIDI_INSTRUMENTS ALL" + S: "954" + + +
+ +
+ The front-end can query a list of all currently existing + entries in a certain MIDI instrument map by sending the following + command: + + + LIST MIDI_INSTRUMENTS <map> + + + Where <map> is the numeric ID of the MIDI instrument map. + The front-end can query a list of all currently existing + entries of all MIDI instrument maps by sending the following + command: + + + LIST MIDI_INSTRUMENTS ALL + + + + Possible Answers: + + + The sampler will answer by sending a comma separated + list of map ID - MIDI bank - MIDI program triples, where + each triple is encapsulated into curly braces. The + list is returned in one single line. Each triple + just reflects the key of the respective map entry, + thus subsequent + "GET MIDI_INSTRUMENT INFO" + command(s) are necessary to retrieve detailed informations + about each entry. + + + + Example: + + + C: "LIST MIDI_INSTRUMENTS 0" + S: "{0,0,0},{0,0,1},{0,0,3},{0,1,4},{1,127,127}" + + +
+ +
+ The front-end can delete an entry from a MIDI instrument + map by sending the following command: + + + UNMAP MIDI_INSTRUMENT <map> <midi_bank> <midi_prog> + + + + Where <map> is the numeric ID of the MIDI instrument map, + <midi_bank> is an integer value between 0..16383 + reflecting the MIDI bank value and + <midi_prog> an integer value between + 0..127 reflecting the MIDI program value of the map's entrie's key + index triple. + + + Possible Answers: + + + "OK" - + + usually + + + "ERR:<error-code>:<error-message>" - + + when index out of bounds + + + + + + Example: + + + C: "UNMAP MIDI_INSTRUMENT 0 2 127" + S: "OK" + + +
+ +
+ The front-end can retrieve the current settings of a certain + instrument map entry by sending the following command: + + + GET MIDI_INSTRUMENT INFO <map> <midi_bank> <midi_prog> + + + + Where <map> is the numeric ID of the MIDI instrument map, + <midi_bank> is an integer value between 0..16383 + reflecting the MIDI bank value, <midi_bank> + and <midi_prog> an integer value between + 0..127 reflecting the MIDI program value of the map's entrie's key + index triple. + + + 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 info category. At the moment + the following categories are defined: + "NAME" - + + Name for this MIDI instrument map entry (if defined). + This name shall be used by frontends for displaying a + name for this mapped instrument. It can be set and + changed with the + "MAP MIDI_INSTRUMENT" + command and does not have to be unique. + + + "ENGINE_NAME" - + + Name of the engine to be deployed for this + instrument. + + + "INSTRUMENT_FILE" - + + File name of the instrument. + + + "INSTRUMENT_NR" - + + Index of the instrument within the file. + + + "INSTRUMENT_NAME" - + + Name of the loaded instrument as reflected by its file. + In contrast to the "NAME" field, the "INSTRUMENT_NAME" field + cannot be changed. + + + "LOAD_MODE" - + + Life time of instrument + (see "MAP MIDI_INSTRUMENT" for details about this setting). + + + "VOLUME" - + + master volume of the instrument as optionally + dotted number (where a value < 1.0 means attenuation + and a value > 1.0 means amplification) + + + The mentioned fields above don't have to be in particular order. + + + + Example: + + + C: "GET MIDI_INSTRUMENT INFO 1 45 120" + S: "NAME: Drums for Foo Song" +    "ENGINE_NAME: GigEngine" +    "INSTRUMENT_FILE: /usr/share/joesdrumkit.gig" +    "INSTRUMENT_NR: 0" +    "INSTRUMENT_NAME: Joe's Drumkit" +    "LOAD_MODE: PERSISTENT" +    "VOLUME: 1.0" +    "." + + +
+ +
+ The front-end can clear a whole MIDI instrument map, that + is delete all its entries by sending the following command: + + + CLEAR MIDI_INSTRUMENTS <map> + + + Where <map> is the numeric ID of the map to clear. + The front-end can clear all MIDI instrument maps, that + is delete all entries of all maps by sending the following + command: + + + CLEAR MIDI_INSTRUMENTS ALL + + + The command "CLEAR MIDI_INSTRUMENTS ALL" does not delete the + maps, only their entries, thus the map's settings like + custom name will be preservevd. + + Possible Answers: + + + "OK" - + + always + + + + + + Examples: + + + C: "CLEAR MIDI_INSTRUMENTS 0" + S: "OK" + + + + + C: "CLEAR MIDI_INSTRUMENTS ALL" + S: "OK" + + +
+
+
The grammar of the control protocol as descibed in is defined below using Backus-Naur Form (BNF as described in ) @@ -3319,13 +4711,13 @@ line = - /* epsilon (empty line ignored) */ + /* epsilon (empty line ignored) */ - / comment + / comment - / command + / command - / error + / error @@ -3345,233 +4737,395 @@ command = - ADD SP CHANNEL + ADD SP add_instruction + + / MAP SP map_instruction + + / UNMAP SP unmap_instruction + + / GET SP get_instruction + + / CREATE SP create_instruction + + / DESTROY SP destroy_instruction + + / LIST SP list_instruction - / GET SP get_instruction + / LOAD SP load_instruction - / CREATE SP create_instruction + / REMOVE SP remove_instruction - / DESTROY SP destroy_instruction + / SET SP set_instruction - / LIST SP list_instruction + / SUBSCRIBE SP subscribe_event - / LOAD SP load_instruction + / UNSUBSCRIBE SP unsubscribe_event - / REMOVE SP CHANNEL SP sampler_channel + / SELECT SP text - / SET SP set_instruction + / RESET SP reset_instruction - / SUBSCRIBE SP subscribe_event + / CLEAR SP clear_instruction - / UNSUBSCRIBE SP unsubscribe_event + / RESET - / SELECT SP text + / QUIT - / RESET SP CHANNEL SP sampler_channel + + +add_instruction = + + CHANNEL - / RESET + / MIDI_INSTRUMENT_MAP - / QUIT + / MIDI_INSTRUMENT_MAP SP map_name subscribe_event = - CHANNEL_COUNT + AUDIO_OUTPUT_DEVICE_COUNT + + / AUDIO_OUTPUT_DEVICE_INFO + + / MIDI_INPUT_DEVICE_COUNT + + / MIDI_INPUT_DEVICE_INFO + + / CHANNEL_COUNT + + / VOICE_COUNT + + / STREAM_COUNT - / VOICE_COUNT + / BUFFER_FILL - / STREAM_COUNT + / CHANNEL_INFO - / BUFFER_FILL + / MIDI_INSTRUMENT_MAP_COUNT - / CHANNEL_INFO + / MIDI_INSTRUMENT_MAP_INFO - / MISCELLANEOUS + / MIDI_INSTRUMENT_COUNT + + / MIDI_INSTRUMENT_INFO + + / MISCELLANEOUS + + / TOTAL_VOICE_COUNT unsubscribe_event = - CHANNEL_COUNT + AUDIO_OUTPUT_DEVICE_COUNT + + / AUDIO_OUTPUT_DEVICE_INFO + + / MIDI_INPUT_DEVICE_COUNT + + / MIDI_INPUT_DEVICE_INFO + + / CHANNEL_COUNT + + / VOICE_COUNT + + / STREAM_COUNT + + / BUFFER_FILL + + / CHANNEL_INFO + + / MIDI_INSTRUMENT_MAP_COUNT + + / MIDI_INSTRUMENT_MAP_INFO + + / MIDI_INSTRUMENT_COUNT + + / MIDI_INSTRUMENT_INFO + + / MISCELLANEOUS + + / TOTAL_VOICE_COUNT + + + +map_instruction = + + MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value - / VOICE_COUNT + / 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 - / STREAM_COUNT + / 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 - / BUFFER_FILL + / 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 + + + +unmap_instruction = + + MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog + + + +remove_instruction = + + CHANNEL SP sampler_channel - / CHANNEL_INFO + / MIDI_INSTRUMENT_MAP SP midi_map - / MISCELLANEOUS + / MIDI_INSTRUMENT_MAP SP ALL get_instruction = - AVAILABLE_ENGINES + AVAILABLE_ENGINES + + / AVAILABLE_MIDI_INPUT_DRIVERS + + / MIDI_INPUT_DRIVER SP INFO SP string + + / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string + + / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list + + / AVAILABLE_AUDIO_OUTPUT_DRIVERS + + / AUDIO_OUTPUT_DRIVER SP INFO SP string + + / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string - / AVAILABLE_MIDI_INPUT_DRIVERS + / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list - / MIDI_INPUT_DRIVER SP INFO SP string + / AUDIO_OUTPUT_DEVICES - / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string + / MIDI_INPUT_DEVICES - / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list + / AUDIO_OUTPUT_DEVICE SP INFO SP number - / AVAILABLE_AUDIO_OUTPUT_DRIVERS + / MIDI_INPUT_DEVICE SP INFO SP number - / AUDIO_OUTPUT_DRIVER SP INFO SP string + / MIDI_INPUT_PORT SP INFO SP number SP number - / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string + / MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string - / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list + / AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number - / AUDIO_OUTPUT_DEVICES + / AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP string - / MIDI_INPUT_DEVICES + / CHANNELS - / AUDIO_OUTPUT_DEVICE SP INFO SP number + / CHANNEL SP INFO SP sampler_channel - / MIDI_INPUT_DEVICE SP INFO SP number + / CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel - / MIDI_INPUT_PORT SP INFO SP number SP number + / CHANNEL SP STREAM_COUNT SP sampler_channel - / MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string + / CHANNEL SP VOICE_COUNT SP sampler_channel - / AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number + / ENGINE SP INFO SP engine_name - / AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP string + / SERVER SP INFO - / CHANNELS + / TOTAL_VOICE_COUNT - / CHANNEL SP INFO SP sampler_channel + / TOTAL_VOICE_COUNT_MAX - / CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel + / MIDI_INSTRUMENTS SP midi_map - / CHANNEL SP STREAM_COUNT SP sampler_channel + / MIDI_INSTRUMENTS SP ALL - / CHANNEL SP VOICE_COUNT SP sampler_channel + / MIDI_INSTRUMENT SP INFO SP midi_map SP midi_bank SP midi_prog - / ENGINE SP INFO SP engine_name + / MIDI_INSTRUMENT_MAPS - / SERVER SP INFO + / 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 = - AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list + AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list + + / AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '=' param_val_list + + / MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list - / AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '=' param_val_list + / MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list - / MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list + / CHANNEL SP set_chan_instruction - / MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list + / MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name - / CHANNEL SP set_chan_instruction + / FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id SP audio_channel_index SP audio_channel_index - / ECHO SP boolean + / 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 = - AUDIO_OUTPUT_DEVICE SP string SP key_val_list + AUDIO_OUTPUT_DEVICE SP string SP key_val_list + + / AUDIO_OUTPUT_DEVICE SP string - / AUDIO_OUTPUT_DEVICE SP string + / MIDI_INPUT_DEVICE SP string SP key_val_list - / MIDI_INPUT_DEVICE SP string SP key_val_list + / MIDI_INPUT_DEVICE SP string - / 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 = + + CHANNEL SP sampler_channel + + + +clear_instruction = + + MIDI_INSTRUMENTS SP midi_map + + / MIDI_INSTRUMENTS SP ALL destroy_instruction = - AUDIO_OUTPUT_DEVICE SP number + AUDIO_OUTPUT_DEVICE SP number + + / MIDI_INPUT_DEVICE SP number - / MIDI_INPUT_DEVICE SP number + / FX_SEND SP sampler_channel SP fx_send_id load_instruction = - INSTRUMENT SP load_instr_args + INSTRUMENT SP load_instr_args - / ENGINE SP load_engine_args + / ENGINE SP load_engine_args set_chan_instruction = - AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index + AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index + + / AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index SP audio_channel_index + + / AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name + + / MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index SP midi_input_channel_index - / AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index SP audio_channel_index + / MIDI_INPUT_DEVICE SP sampler_channel SP device_index - / AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name + / MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index - / MIDI_INPUT SP sampler_channel SP device_index SP midi_input_port_index SP midi_input_channel_index + / MIDI_INPUT_CHANNEL SP sampler_channel SP midi_input_channel_index - / MIDI_INPUT_DEVICE SP sampler_channel SP device_index + / MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name - / MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index + / VOLUME SP sampler_channel SP volume_value - / MIDI_INPUT_CHANNEL SP sampler_channel SP midi_input_channel_index + / MUTE SP sampler_channel SP boolean - / MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name + / SOLO SP sampler_channel SP boolean - / VOLUME SP sampler_channel SP volume_value + / MIDI_INSTRUMENT_MAP SP sampler_channel SP midi_map - / MUTE SP sampler_channel SP boolean + / MIDI_INSTRUMENT_MAP SP sampler_channel SP NONE + + / MIDI_INSTRUMENT_MAP SP sampler_channel SP DEFAULT + + + +modal_arg = + + /* epsilon (empty argument) */ - / SOLO SP sampler_channel SP boolean + / NON_MODAL SP key_val_list = - string '=' param_val_list + string '=' param_val_list - / key_val_list SP string '=' param_val_list + / key_val_list SP string '=' param_val_list buffer_size_type = - BYTES + BYTES - / PERCENTAGE + / PERCENTAGE list_instruction = - AUDIO_OUTPUT_DEVICES + AUDIO_OUTPUT_DEVICES + + / MIDI_INPUT_DEVICES + + / CHANNELS + + / AVAILABLE_ENGINES + + / AVAILABLE_MIDI_INPUT_DRIVERS - / MIDI_INPUT_DEVICES + / AVAILABLE_AUDIO_OUTPUT_DRIVERS - / CHANNELS + / MIDI_INSTRUMENTS SP midi_map - / AVAILABLE_ENGINES + / MIDI_INSTRUMENTS SP ALL - / AVAILABLE_MIDI_INPUT_DRIVERS + / MIDI_INSTRUMENT_MAPS - / AVAILABLE_AUDIO_OUTPUT_DRIVERS + / FX_SENDS SP sampler_channel load_instr_args = - filename SP instrument_index SP sampler_channel + filename SP instrument_index SP sampler_channel - / NON_MODAL SP filename SP instrument_index SP sampler_channel + / NON_MODAL SP filename SP instrument_index SP sampler_channel load_engine_args = - engine_name SP sampler_channel + engine_name SP sampler_channel + + + +instr_load_mode = + + ON_DEMAND + + / ON_DEMAND_HOLD + + / PERSISTENT @@ -3603,7 +5157,7 @@ number - / ALL + / ALL @@ -3613,11 +5167,35 @@ +midi_map = + + number + + + +midi_bank = + + number + + + +midi_prog = + + number + + + +midi_ctrl = + + number + + + volume_value = dotnum - / number + / number @@ -3633,6 +5211,12 @@ +fx_send_id = + + number + + + engine_name = string @@ -3645,11 +5229,29 @@ +map_name = + + stringval + + + +entry_name = + + stringval + + + +fx_send_name = + + stringval + + + param_val_list = param_val - / param_val_list','param_val + / param_val_list','param_val @@ -3657,13 +5259,11 @@ string - / '\'' string '\'' - - / '\"' string '\"' + / stringval - / number + / number - / dotnum + / dotnum @@ -3674,7 +5274,87 @@
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: + + + 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. +
+ +
+ 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. +
+ +
+ 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. +
+ +
+ 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. +
+ +
Client may want to be notified when the total number of channels on the back-end changes by issuing the following command: @@ -3703,7 +5383,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 @@ -3751,7 +5431,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: @@ -3773,6 +5453,163 @@ 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: + + + SUBSCRIBE TOTAL_VOICE_COUNT + + + Server will start sending the following notification messages: + + + "NOTIFY:TOTAL_VOICE_COUNT:<voices>" + + + where <voices> will be replaced by the new number of + all currently active voices. +
+ +
+ 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. +
+ +
+ 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. +
+ +
+ 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. +
+ +
+ 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. +
+ +
+ 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: