--- linuxsampler/trunk/Documentation/lscp.xml 2005/09/23 06:58:26 778 +++ linuxsampler/trunk/Documentation/lscp.xml 2007/01/14 17:10:59 1026 @@ -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: @@ -3433,9 +3925,764 @@ 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 <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 in the background 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"). + + + 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. + + + 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 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 ) @@ -3484,7 +4731,11 @@ command = - ADD SP CHANNEL + ADD SP add_instruction + + / MAP SP map_instruction + + / UNMAP SP unmap_instruction / GET SP get_instruction @@ -3496,7 +4747,7 @@ / LOAD SP load_instruction - / REMOVE SP CHANNEL SP sampler_channel + / REMOVE SP remove_instruction / SET SP set_instruction @@ -3506,7 +4757,9 @@ / SELECT SP text - / RESET SP CHANNEL SP sampler_channel + / RESET SP reset_instruction + + / CLEAR SP clear_instruction / RESET @@ -3514,9 +4767,27 @@ +add_instruction = + + CHANNEL + + / MIDI_INSTRUMENT_MAP + + / 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 @@ -3526,6 +4797,14 @@ / CHANNEL_INFO + / MIDI_INSTRUMENT_MAP_COUNT + + / MIDI_INSTRUMENT_MAP_INFO + + / MIDI_INSTRUMENT_COUNT + + / MIDI_INSTRUMENT_INFO + / MISCELLANEOUS / TOTAL_VOICE_COUNT @@ -3534,7 +4813,15 @@ unsubscribe_event = - CHANNEL_COUNT + AUDIO_OUTPUT_DEVICE_COUNT + + / AUDIO_OUTPUT_DEVICE_INFO + + / MIDI_INPUT_DEVICE_COUNT + + / MIDI_INPUT_DEVICE_INFO + + / CHANNEL_COUNT / VOICE_COUNT @@ -3544,12 +4831,48 @@ / 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 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 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 + + + +unmap_instruction = + + MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog + + + +remove_instruction = + + CHANNEL SP sampler_channel + + / MIDI_INSTRUMENT_MAP SP midi_map + + / MIDI_INSTRUMENT_MAP SP ALL + + + get_instruction = AVAILABLE_ENGINES @@ -3604,6 +4927,22 @@ / TOTAL_VOICE_COUNT_MAX + / MIDI_INSTRUMENTS SP midi_map + + / MIDI_INSTRUMENTS SP ALL + + / MIDI_INSTRUMENT SP INFO SP midi_map SP midi_bank SP midi_prog + + / MIDI_INSTRUMENT_MAPS + + / 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 = @@ -3618,8 +4957,18 @@ / CHANNEL SP set_chan_instruction + / 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 + create_instruction = @@ -3632,6 +4981,24 @@ / 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 = @@ -3640,6 +5007,8 @@ / MIDI_INPUT_DEVICE SP number + / FX_SEND SP sampler_channel SP fx_send_id + load_instruction = @@ -3674,6 +5043,12 @@ / SOLO SP sampler_channel SP boolean + / MIDI_INSTRUMENT_MAP SP sampler_channel SP midi_map + + / MIDI_INSTRUMENT_MAP SP sampler_channel SP NONE + + / MIDI_INSTRUMENT_MAP SP sampler_channel SP DEFAULT + key_val_list = @@ -3706,6 +5081,14 @@ / AVAILABLE_AUDIO_OUTPUT_DRIVERS + / MIDI_INSTRUMENTS SP midi_map + + / MIDI_INSTRUMENTS SP ALL + + / MIDI_INSTRUMENT_MAPS + + / FX_SENDS SP sampler_channel + load_instr_args = @@ -3722,6 +5105,16 @@ +instr_load_mode = + + ON_DEMAND + + / ON_DEMAND_HOLD + + / PERSISTENT + + + device_index = number @@ -3760,6 +5153,30 @@ +midi_map = + + number + + + +midi_bank = + + number + + + +midi_prog = + + number + + + +midi_ctrl = + + number + + + volume_value = dotnum @@ -3780,6 +5197,12 @@ +fx_send_id = + + number + + + engine_name = string @@ -3792,6 +5215,24 @@ +map_name = + + stringval + + + +entry_name = + + stringval + + + +fx_send_name = + + stringval + + + param_val_list = param_val @@ -3804,9 +5245,7 @@ string - / '\'' string '\'' - - / '\"' string '\"' + / stringval / number @@ -3821,7 +5260,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: @@ -3898,7 +5417,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: @@ -3938,6 +5457,88 @@ 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 of miscellaneous and debugging events occurring at the server by issuing the following command: