--- linuxsampler/trunk/Documentation/lscp.xml 2005/05/23 17:41:34 571 +++ linuxsampler/trunk/Documentation/lscp.xml 2007/05/16 14:22:26 1187 @@ -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 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: @@ -3226,6 +3862,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: @@ -3264,7 +3936,7 @@ LinuxSampler will answer by sending a <CRLF> separated list. - Each answer line begins with the settings category name + 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 information category. At the moment the following categories are defined: @@ -3287,6 +3959,12 @@ complies with (see for details) + INSTRUMENTS_DB_SUPPORT - + + either yes or no, specifies whether the + sampler is build with instruments database support. + + @@ -3294,19 +3972,2623 @@ 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 + + + DEFAULT - + + either true or false, + defines whether this map is the default map + + + + + + + The mentioned fields above don't have to be in particular order. + + Example: + + + C: "GET MIDI_INSTRUMENT_MAP INFO 0" + S: "NAME: Standard Map" +    "DEFAULT: true" +    "." + + +
+ +
+ 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 following commands describe how to use and manage + the instruments database. + +
+ The front-end can add a new instrument directory to the + instruments database by sending the following command: + + + ADD DB_INSTRUMENT_DIRECTORY <dir> + + + Where <dir> is the absolute path name of the directory + to be created (encapsulated into apostrophes). + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + when the directory could not be created, which + can happen if the directory already exists or the + name contains not allowed symbols + + + + + + Examples: + + + C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'" + S: "OK" + + +
+ +
+ The front-end can delete a particular instrument directory + from the instruments database by sending the following command: + + + REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] <dir> + + + Where <dir> is the absolute path name of the directory + to delete. The optional FORCE argument can be used to + force the deletion of a non-empty directory and all its content. + + Possible Answers: + + + "OK" - + + if the directory is deleted successfully + + + "ERR:<error-code>:<error-message>" - + + if the given directory does not exist, or + if trying to delete a non-empty directory, + without using the FORCE argument. + + + + + + Examples: + + + C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'" + S: "OK" + + +
+ +
+ The front-end can retrieve the current amount of + directories in a specific directory by sending the following command: + + + GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] <dir> + + + Where <dir> should be replaced by the absolute path + name of the directory. If RECURSIVE is specified, the number of + all directories, including those located in subdirectories of the + specified directory, will be returned. + + Possible Answers: + + + The current number of instrument directories + in the specified directory. + "ERR:<error-code>:<error-message>" - + + if the given directory does not exist. + + + + + + Example: + + + C: "GET DB_INSTRUMENT_DIRECTORIES '/'" + S: "2" + + +
+ +
+ The front-end can retrieve the current list of directories + in specific directory by sending the following command: + + + LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] <dir> + + + Where <dir> should be replaced by the absolute path + name of the directory. If RECURSIVE is specified, the absolute path names + of all directories, including those located in subdirectories of the + specified directory, will be returned. + + Possible Answers: + + + A comma separated list of all instrument directories + (encapsulated into apostrophes) in the specified directory. + "ERR:<error-code>:<error-message>" - + + if the given directory does not exist. + + + + + Example: + + + C: "LIST DB_INSTRUMENT_DIRECTORIES '/'" + S: "'Piano Collection','Percussion Collection'" + + + + + C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'" + S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano Collection/Acoustic/New','/Percussion Collection'" + + +
+ +
+ The front-end can ask for the current settings of an + instrument directory by sending the following command: + + + GET DB_INSTRUMENT_DIRECTORY INFO <dir> + + + Where <dir> should be replaced by the absolute path + name of the directory the front-end is interested in. + + 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: + + + + DESCRIPTION - + + A brief description of the directory content + + + CREATED - + + The creation date and time of the directory, + represented in "YYYY-MM-DD HH:MM:SS" format + + + MODIFIED - + + The date and time of the last modification of the + directory, represented in "YYYY-MM-DD HH:MM:SS" format + + + + + + + The mentioned fields above don't have to be in particular order. + + Example: + + + C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'" + S: "DESCRIPTION: Piano collection of instruments in GigaSampler format." +    "CREATED: 2007-02-05 10:23:12" +    "MODIFIED: 2007-04-07 12:50:21" +    "." + + +
+ +
+ The front-end can alter the name of a specific + instrument directory by sending the following command: + + + SET DB_INSTRUMENT_DIRECTORY NAME <dir> <name> + + + Where <dir> is the absolute path name of the directory and + <name> is the new name for that directory. + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + in case the given directory does not exists, + or if a directory with name equal to the new + name already exists. + + + + + + Example: + + + C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic' 'Acoustic'" + S: "OK" + + +
+ +
+ The front-end can move a specific + instrument directory by sending the following command: + + + MOVE DB_INSTRUMENT_DIRECTORY <dir> <dst> + + + Where <dir> is the absolute path name of the directory + to move and <dst> is the location where the directory will + be moved to. + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + in case a given directory does not exists, + or if a directory with name equal to the name + of the specified directory already exists in + the destination directory. Error is also thrown + when trying to move a directory to a subdirectory + of itself. + + + + + + Example: + + + C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/Acoustic'" + S: "OK" + + +
+ +
+ The front-end can copy a specific + instrument directory by sending the following command: + + + COPY DB_INSTRUMENT_DIRECTORY <dir> <dst> + + + Where <dir> is the absolute path name of the directory + to copy and <dst> is the location where the directory will + be copied to. + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + in case a given directory does not exists, + or if a directory with name equal to the name + of the specified directory already exists in + the destination directory. Error is also thrown + when trying to copy a directory to a subdirectory + of itself. + + + + + + Example: + + + C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic' '/Acoustic/Pianos'" + S: "OK" + + +
+ +
+ The front-end can alter the description of a specific + instrument directory by sending the following command: + + + SET DB_INSTRUMENT_DIRECTORY DESCRIPTION <dir> <desc> + + + Where <dir> is the absolute path name of the directory and + <desc> is the new description for the directory. + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + in case the given directory does not exists. + + + + + + Example: + + + C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A collection of piano instruments in various format.'" + S: "OK" + + +
+ +
+ The front-end can search for directories + in specific directory by sending the following command: + + + FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] <dir> <criteria-list> + + + Where <dir> should be replaced by the absolute path + name of the directory to search in. If NON_RECURSIVE is specified, the + directories located in subdirectories of the specified directory will not + be searched. <criteria-list> is a list of search criterias + in form of "key1=val1 key2=val2 ...". The following criterias are + allowed: + + NAME='<search-string>' + + Restricts the search to directories, which names + satisfy the supplied search string. + + + + CREATED='[<date-after>]..[<date-before>]' + + Restricts the search to directories, which creation + date satisfies the specified period, where <date-after> + and <date-before> are in "YYYY-MM-DD HH:MM:SS" format. + If <date-after> is omitted the search is restricted to + directories created before <date-before>. If + <date-before> is omitted, the search is restricted + to directories created after <date-after>. + + + + MODIFIED='[<date-after>]..[<date-before>]' + + Restricts the search to directories, which + date of last modification satisfies the specified period, where + <date-after> and <date-before> are in "YYYY-MM-DD HH:MM:SS" + format. If <date-after> is omitted the search is restricted to + directories, which are last modified before <date-before>. If + <date-before> is omitted, the search is restricted to directories, + which are last modified after <date-after>. + + + + DESCRIPTION='<search-string>' + + Restricts the search to directories with description + that satisfies the supplied search string. + + + + + Where <search-string> is either a regular expression, or a + word list separated with spaces for OR search and with '+' for AND search. + + Possible Answers: + + + A comma separated list with the absolute path names (encapsulated into + apostrophes) of all directories in the specified directory that satisfy + the supplied search criterias. + "ERR:<error-code>:<error-message>" - + + if the given directory does not exist. + + + + + Example: + + + C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'" + S: "'/Piano Collection'" + + + + + C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:30:13'" + S: "'/Piano Collection','/Percussions'" + + +
+ +
+ The front-end can add one or more instruments + to the instruments database by sending the following command: + + + ADD DB_INSTRUMENTS [<mode>] <db_dir> <file_path> [<instr_index>] + + + Where <db_dir> is the absolute path name of a directory + (encapsulated into apostrophes) in the instruments database in which + only the new instruments (that are not already in the database) will + be added, <file_path> is the absolute path name of a file or + directory in the file system (encapsulated into apostrophes). In case + an instrument file is supplied, only the instruments in the specified + file will be added to the instruments database. If the optional + <instr_index> (the index of the instrument within the given file) + is supplied too, then only the specified instrument will be added. + In case a directory is supplied, the instruments in that directory + will be added. The OPTIONAL <mode> argument is only applied + when a directory is provided as <file_path> and specifies how the + scanning will be done and has exactly the following possibilities: + + + "NON_RECURSIVE" - + + Only the instruments in the specified directory + will be added, the instruments in the subdirectories + will not be processed. + + + "FLAT" - + + All instruments will be processed, including those + in the subdirectories, but the respective subdirectory + structure will not be recreated in the instruments + database. All instruments will be added directly in + the specified database directory. + + + not supplied - + + The subdirectory tree structure will be recreated + in the instruments database and all instruments will be + processed and added to the respective subdirectory + in the instruments database. + + + + + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + if an invalid path is specified. + + + + + + Examples: + + + C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI Bosendorfer 290.gig' 0" + S: "OK" + + +
+ +
+ The front-end can remove a particular instrument + from the instruments database by sending the following command: + + + REMOVE DB_INSTRUMENT <instr_path> + + + Where <instr_path> is the absolute path name + (in the instruments database) of the instrument to remove. + + Possible Answers: + + + "OK" - + + if the instrument is removed successfully + + + "ERR:<error-code>:<error-message>" - + + if the given path does not exist or + is a directory. + + + + + + Examples: + + + C: "REMOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'" + S: "OK" + + +
+ +
+ The front-end can retrieve the current amount of + instruments in a specific directory by sending the following command: + + + GET DB_INSTRUMENTS [RECURSIVE] <dir> + + + Where <dir> should be replaced by the absolute path name + of the directory. If RECURSIVE is specified, the number of all + instruments, including those located in subdirectories of the + specified directory, will be returned. + + Possible Answers: + + + The current number of instruments + in the specified directory. + "ERR:<error-code>:<error-message>" - + + if the given directory does not exist. + + + + + + Example: + + + C: "GET DB_INSTRUMENTS '/Piano Collection'" + S: "2" + + +
+ +
+ The front-end can retrieve the current list of instruments + in specific directory by sending the following command: + + + LIST DB_INSTRUMENTS [RECURSIVE] <dir> + + + Where <dir> should be replaced by the absolute path + name of the directory. If RECURSIVE is specified, the absolute path + names of all instruments, including those located in subdirectories + of the specified directory, will be returned. + + Possible Answers: + + + A comma separated list of all instruments + (encapsulated into apostrophes) in the specified directory. + "ERR:<error-code>:<error-message>" - + + if the given directory does not exist. + + + + + Example: + + + C: "LIST DB_INSTRUMENTS '/Piano Collection'" + S: "'Bosendorfer 290','Steinway D'" + + + + + C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'" + S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D','/Piano Collection/Lite/Free Piano'" + + +
+ +
+ The front-end can ask for the current settings of an + instrument by sending the following command: + + + GET DB_INSTRUMENT INFO <instr_path> + + + Where <instr_path> should be replaced by the absolute path + name of the instrument the front-end is interested in. + + 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: + + + + INSTRUMENT_FILE - + + File name of the instrument. + + + INSTRUMENT_NR - + + Index of the instrument within the file. + + + FORMAT_FAMILY - + + The format family of the instrument. + + + FORMAT_VERSION - + + The format version of the instrument. + + + SIZE - + + The size of the instrument in bytes. + + + CREATED - + + The date and time when the instrument is added + in the instruments database, represented in + "YYYY-MM-DD HH:MM:SS" format + + + MODIFIED - + + The date and time of the last modification of the + instrument's database settings, represented in + "YYYY-MM-DD HH:MM:SS" format + + + DESCRIPTION - + + A brief description of the instrument + + + IS_DRUM - + + either true or false, determines whether the + instrument is a drumkit or a chromatic instrument + + + PRODUCT - + + The product title of the instrument + + + ARTISTS - + + Lists the artist names + + + KEYWORDS - + + Provides a list of keywords that refer to the instrument. + Keywords are separated with semicolon and blank. + + + + + + + The mentioned fields above don't have to be in particular order. + + Example: + + + C: "GET DB_INSTRUMENT INFO '/Piano Collection/Bosendorfer 290'" + S: "INSTRUMENT_FILE: /home/me/gigs/Bosendorfer 290.gig" +    "INSTRUMENT_NR: 0" +    "FORMAT_FAMILY: GIG" +    "FORMAT_VERSION: 2" +    "SIZE: 2050871870" +    "CREATED: 2007-02-05 10:23:12" +    "MODIFIED: 2007-04-07 12:50:21" +    "DESCRIPTION: " +    "IS_DRUM: false" +    "PRODUCT: GRANDIOSO Bosendorfer 290" +    "ARTISTS: Post Musical Instruments" +    "KEYWORDS: Bosendorfer" +    "." + + +
+ +
+ The front-end can alter the name of a specific + instrument by sending the following command: + + + SET DB_INSTRUMENT NAME <instr> <name> + + + Where <instr> is the absolute path name of the instrument and + <name> is the new name for that instrument. + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + in case the given instrument does not exists, + or if an instrument with name equal to the new + name already exists. + + + + + + Example: + + + C: "SET DB_INSTRUMENT NAME '/Piano Collection/Bosendorfer' 'Bosendorfer 290'" + S: "OK" + + +
+ +
+ The front-end can move a specific instrument to another directory by + sending the following command: + + + MOVE DB_INSTRUMENT <instr> <dst> + + + Where <instr> is the absolute path name of the instrument + to move and <dst> is the directory where the instrument will + be moved to. + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + in case the given instrument does not exists, + or if an instrument with name equal to the name of the + specified instrument already exists in the destination + directory. + + + + + + Example: + + + C: "MOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Piano Collection/Acoustic'" + S: "OK" + + +
+ +
+ The front-end can copy a specific instrument to another directory by + sending the following command: + + + COPY DB_INSTRUMENT <instr> <dst> + + + Where <instr> is the absolute path name of the instrument + to copy and <dst> is the directory where the instrument will + be copied to. + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + in case the given instrument does not exists, + or if an instrument with name equal to the name of the + specified instrument already exists in the destination + directory. + + + + + + Example: + + + C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Acoustic/Pianos/'" + S: "OK" + + +
+ +
+ The front-end can alter the description of a specific + instrument by sending the following command: + + + SET DB_INSTRUMENT DESCRIPTION <instr> <desc> + + + Where <instr> is the absolute path name of the instrument and + <desc> is the new description for the instrument. + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + in case the given instrument does not exists. + + + + + + Example: + + + C: "SET DB_INSTRUMENT DESCRIPTION '/Piano Collection/Acoustic/Bosendorfer 290' 'No comment :)'" + S: "OK" + + +
+ +
+ The front-end can search for instruments + in specific directory by sending the following command: + + + FIND DB_INSTRUMENTS [NON_RECURSIVE] <dir> <criteria-list> + + + Where <dir> should be replaced by the absolute path + name of the directory to search in. If NON_RECURSIVE is specified, the + directories located in subdirectories of the specified directory will not + be searched. <criteria-list> is a list of search criterias + in form of "key1=val1 key2=val2 ...". The following criterias are + allowed: + + NAME='<search-string>' + + Restricts the search to instruments, which names + satisfy the supplied search string. + + + + SIZE=[<min>]..[<max>] + + Restricts the search to instruments, which + size is in the specified range. If <min> is omitted, + the search results are restricted to instruments with size less then + or equal to <max>. If <max> is omitted, the + search is restricted to instruments with size greater then + or equal to <min>. + + + + CREATED='[<date-after>]..[<date-before>]' + + Restricts the search to instruments, which creation + date satisfies the specified period, where <date-after> + and <date-before> are in "YYYY-MM-DD HH:MM:SS" format. + If <date-after> is omitted the search is restricted to + instruments created before <date-before>. If + <date-before> is omitted, the search is restricted + to instruments created after <date-after>. + + + + MODIFIED='[<date-after>]..[<date-before>]' + + Restricts the search to instruments, which + date of last modification satisfies the specified period, where + <date-after> and <date-before> are in "YYYY-MM-DD HH:MM:SS" + format. If <date-after> is omitted the search is restricted to + instruments, which are last modified before <date-before>. If + <date-before> is omitted, the search is restricted to instruments, + which are last modified after <date-after>. + + + + DESCRIPTION='<search-string>' + + Restricts the search to instruments with description + that satisfies the supplied search string. + + + + PRODUCT='<search-string>' + + Restricts the search to instruments with product info + that satisfies the supplied search string. + + + + ARTISTS='<search-string>' + + Restricts the search to instruments with artists info + that satisfies the supplied search string. + + + + KEYWORDS='<search-string>' + + Restricts the search to instruments with keyword list + that satisfies the supplied search string. + + + + IS_DRUM=true | false + + Either true or false. Restricts the search to + drum kits or chromatic instruments. + + + + FORMAT_FAMILIES='<format-list>' + + Restricts the search to instruments of the supplied format families, + where <format-list> is a comma separated list of format families. + + + + + Where <search-string> is either a regular expression, or a + word list separated with spaces for OR search and with '+' for AND search. + + Possible Answers: + + + A comma separated list with the absolute path names (encapsulated into + apostrophes) of all instruments in the specified directory that satisfy + the supplied search criterias. + "ERR:<error-code>:<error-message>" - + + if the given directory does not exist. + + + + + Example: + + + C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+290'" + S: "'/Piano Collection/Bosendorfer 290'" + + + + + C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01 09:30:13..'" + S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D'" + + +
+ +
+
+
- TODO: will soon automatically included from src/network/lscp.y, - meanwhile have a look at that file to get the exact definition of - the command syntax. + The grammar of the control protocol as descibed in + is defined below using Backus-Naur Form (BNF as described in ) + where applicable. + + + + +input = + + line LF + + / line CR LF + + + +line = + + /* epsilon (empty line ignored) */ + + / comment + + / command + + / error + + + +comment = + + '#' + + / comment '#' + + / comment SP + + / comment number + + / comment string + + + +command = + + 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 + + / LOAD SP load_instruction + + / REMOVE SP remove_instruction + + / SET SP set_instruction + + / SUBSCRIBE SP subscribe_event + + / UNSUBSCRIBE SP unsubscribe_event + + / RESET SP reset_instruction + + / CLEAR SP clear_instruction + + / FIND SP find_instruction + + / MOVE SP move_instruction + + / COPY SP copy_instruction + + / RESET + + / QUIT + + + +add_instruction = + + CHANNEL + + / DB_INSTRUMENT_DIRECTORY SP pathname + + / DB_INSTRUMENTS SP FLAT SP pathname SP pathname + + / DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP pathname + + / DB_INSTRUMENTS SP pathname SP pathname + + / DB_INSTRUMENTS SP pathname SP pathname SP instrument_index + + / MIDI_INSTRUMENT_MAP + + / MIDI_INSTRUMENT_MAP SP map_name + + + +subscribe_event = + + 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 + + / FX_SEND_COUNT + + / FX_SEND_INFO + + / MIDI_INSTRUMENT_MAP_COUNT + + / MIDI_INSTRUMENT_MAP_INFO + + / MIDI_INSTRUMENT_COUNT + + / MIDI_INSTRUMENT_INFO + + / DB_INSTRUMENT_DIRECTORY_COUNT + + / DB_INSTRUMENT_DIRECTORY_INFO + + / DB_INSTRUMENT_COUNT + + / DB_INSTRUMENT_INFO + + / MISCELLANEOUS + + / TOTAL_VOICE_COUNT + + / GLOBAL_INFO + + + +unsubscribe_event = + + 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 + + / FX_SEND_COUNT + + / FX_SEND_INFO + + / MIDI_INSTRUMENT_MAP_COUNT + + / MIDI_INSTRUMENT_MAP_INFO + + / MIDI_INSTRUMENT_COUNT + + / MIDI_INSTRUMENT_INFO + + / DB_INSTRUMENT_DIRECTORY_COUNT + + / DB_INSTRUMENT_DIRECTORY_INFO + + / DB_INSTRUMENT_COUNT + + / DB_INSTRUMENT_INFO + + / MISCELLANEOUS + + / TOTAL_VOICE_COUNT + + / GLOBAL_INFO + + + +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 + + / 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 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 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 + + / MIDI_INSTRUMENT_MAP SP midi_map + + / MIDI_INSTRUMENT_MAP SP ALL + + / DB_INSTRUMENT_DIRECTORY SP FORCE SP pathname + + / DB_INSTRUMENT_DIRECTORY SP pathname + + / DB_INSTRUMENT SP pathname + + + +get_instruction = + + 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 + + / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list + + / AUDIO_OUTPUT_DEVICES + + / MIDI_INPUT_DEVICES + + / AUDIO_OUTPUT_DEVICE SP INFO SP number + + / MIDI_INPUT_DEVICE SP INFO SP number + + / MIDI_INPUT_PORT SP INFO SP number SP number + + / MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string + + / AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number + + / AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP string + + / CHANNELS + + / CHANNEL SP INFO SP sampler_channel + + / CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel + + / CHANNEL SP STREAM_COUNT SP sampler_channel + + / CHANNEL SP VOICE_COUNT SP sampler_channel + + / ENGINE SP INFO SP engine_name + + / SERVER SP INFO + + / TOTAL_VOICE_COUNT + + / 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 + + / DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname + + / DB_INSTRUMENT_DIRECTORIES SP pathname + + / DB_INSTRUMENT_DIRECTORY SP INFO SP pathname + + / DB_INSTRUMENTS SP RECURSIVE SP pathname + + / DB_INSTRUMENTS SP pathname + + / DB_INSTRUMENT SP INFO SP pathname + + / VOLUME + + + +set_instruction = + + 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 + + / MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list + + / CHANNEL SP set_chan_instruction + + / 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 + + / DB_INSTRUMENT_DIRECTORY SP NAME SP pathname SP dirname + + / DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP pathname SP stringval + + / DB_INSTRUMENT SP NAME SP pathname SP dirname + + / DB_INSTRUMENT SP DESCRIPTION SP pathname SP stringval + + / ECHO SP boolean + + / VOLUME SP volume_value + + + +create_instruction = + + AUDIO_OUTPUT_DEVICE SP string SP key_val_list + + / AUDIO_OUTPUT_DEVICE SP string + + / MIDI_INPUT_DEVICE SP string SP key_val_list + + / 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 + + + +find_instruction = + + DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP query_val_list + + / DB_INSTRUMENTS SP pathname SP query_val_list + + / DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP pathname SP query_val_list + + / DB_INSTRUMENT_DIRECTORIES SP pathname SP query_val_list + + + +move_instruction = + + DB_INSTRUMENT_DIRECTORY SP pathname SP pathname + + / DB_INSTRUMENT SP pathname SP pathname + + + +copy_instruction = + + DB_INSTRUMENT_DIRECTORY SP pathname SP pathname + + / DB_INSTRUMENT SP pathname SP pathname + + + +destroy_instruction = + + AUDIO_OUTPUT_DEVICE SP number + + / MIDI_INPUT_DEVICE SP number + + / FX_SEND SP sampler_channel SP fx_send_id + + + +load_instruction = + + INSTRUMENT SP load_instr_args + + / ENGINE SP load_engine_args + + + +set_chan_instruction = + + 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 + + / MIDI_INPUT_DEVICE SP sampler_channel SP device_index + + / MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index + + / MIDI_INPUT_CHANNEL SP sampler_channel SP midi_input_channel_index + + / MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name + + / VOLUME SP sampler_channel SP volume_value + + / MUTE SP sampler_channel SP boolean + + / 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 + + + +modal_arg = + + /* epsilon (empty argument) */ + + / NON_MODAL SP + + + +key_val_list = + + string '=' param_val_list + + / key_val_list SP string '=' param_val_list + + + +buffer_size_type = + + BYTES + + / PERCENTAGE + + + +list_instruction = + + AUDIO_OUTPUT_DEVICES + + / MIDI_INPUT_DEVICES + + / CHANNELS + + / AVAILABLE_ENGINES + + / AVAILABLE_MIDI_INPUT_DRIVERS + + / AVAILABLE_AUDIO_OUTPUT_DRIVERS + + / MIDI_INSTRUMENTS SP midi_map + + / MIDI_INSTRUMENTS SP ALL + + / MIDI_INSTRUMENT_MAPS + + / FX_SENDS SP sampler_channel + + / DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname + + / DB_INSTRUMENT_DIRECTORIES SP pathname + + / DB_INSTRUMENTS SP RECURSIVE SP pathname + + / DB_INSTRUMENTS SP pathname + + + +load_instr_args = + + 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 + + + +instr_load_mode = + + ON_DEMAND + + / ON_DEMAND_HOLD + + / PERSISTENT + + + +device_index = + + number + + + +audio_channel_index = + + number + + + +audio_output_type_name = + + string + + + +midi_input_port_index = + + number + + + +midi_input_channel_index = + + number + + / ALL + + + +midi_input_type_name = + + string + + + +midi_map = + + number + + + +midi_bank = + + number + + + +midi_prog = + + number + + + +midi_ctrl = + + number + + + +volume_value = + + dotnum + + / number + + + +sampler_channel = + + number + + + +instrument_index = + + number + + + +fx_send_id = + + number + + + +engine_name = + + string + + + +pathname = + + stringval + + + +dirname = + + stringval + + + +filename = + + stringval + + + +map_name = + + stringval + + + +entry_name = + + stringval + + + +fx_send_name = + + stringval + + + +param_val_list = + + param_val + + / param_val_list','param_val + + + +param_val = + + string + + / stringval + + / number + + / dotnum + + + +query_val_list = + + string '=' query_val + + / query_val_list SP string '=' query_val + + + +query_val = + + string + + / stringval + + + + +
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: @@ -3335,7 +6617,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 @@ -3383,7 +6665,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: @@ -3405,6 +6687,267 @@ 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 when the number of instrument + directories in a particular directory in the instruments database + is changed by issuing the following command: + + + SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT + + + Server will start sending the following notification messages: + + + "NOTIFY:DB_INSTRUMENT_DIRECTORY_COUNT:<dir-path>" + + + where <dir-path> will be replaced by the absolute path + name of the directory in the instruments database, + in which the number of directories is changed. + Note that when a non-empty directory is removed, this event + is not sent for the subdirectories in that directory. +
+ +
+ Client may want to be notified when changes were made to directories + in the instruments database by issuing the following command: + + + SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO + + + Server will start sending the following notification messages: + + + "NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:<dir-path>" + + + where <dir-path> will be replaced by the absolute path name + of the directory, for which information changes occurred. The front-end will have to send + the respective command to actually get the updated directory 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. + + + "NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:NAME <old-dir-path> <new-name>" + + + where <old-dir-path> is the old absolute path name of the directory + (encapsulated into apostrophes), which name is changes and <new-name> is + the new name of the directory, encapsulated into apostrophes. +
+ +
+ Client may want to be notified when the number of instruments + in a particular directory in the instruments database + is changed by issuing the following command: + + + SUBSCRIBE DB_INSTRUMENT_COUNT + + + Server will start sending the following notification messages: + + + "NOTIFY:DB_INSTRUMENT_COUNT:<dir-path>" + + + where <dir-path> will be replaced by the absolute path + name of the directory in the instruments database, + in which the number of instruments is changed. + Note that when a non-empty directory is removed, this event + is not sent for the instruments in that directory. +
+ +
+ Client may want to be notified when changes were made to instruments + in the instruments database by issuing the following command: + + + SUBSCRIBE DB_INSTRUMENT_INFO + + + Server will start sending the following notification messages: + + + "NOTIFY:DB_INSTRUMENT_INFO:<instr-path>" + + + where <instr-path> will be replaced by the absolute path name + of the instrument, which settings are changed. The front-end will have to send + the respective command to actually get the updated directory 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. + + + "NOTIFY:DB_INSTRUMENT_INFO:NAME <old-instr-path> <new-name>" + + + where <old-instr-path> is the old absolute path name of the instrument + (encapsulated into apostrophes), which name is changes and <new-name> is + the new name of the instrument, encapsulated into apostrophes. +
+
Client may want to be notified of miscellaneous and debugging events occurring at the server by issuing the following command: @@ -3459,7 +7002,6 @@ - @@ -3470,7 +7012,19 @@ - + + + + Augmented BNF for Syntax Specifications + + Internet Mail Consortium + + + Demon Internet Ltd + + + +