--- linuxsampler/trunk/Documentation/lscp.xml 2006/11/25 18:07:35 943 +++ linuxsampler/trunk/Documentation/lscp.xml 2006/11/26 16:29:57 944 @@ -13,7 +13,7 @@ - + LinuxSampler Control Protocol + + + MAP MIDI_INSTRUMENT <midi_bank_msb> + <midi_bank_lsb> <midi_prog> <engine_name> + <filename> <instrument_index> <volume_value> + [<instr_load_mode>] [<name>] + + + Where <midi_bank_msb> is an integer value between + 0..127 reflecting the MIDI bank select MSB (coarse) index, + <midi_bank_lsb> an integer value between 0..127 reflecting + the MIDI bank select LSB (fine) 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 engine does not exist or a value + is out of range + + + + + + Examples: + + + C: "MAP MIDI_INSTRUMENT 3 0 0 gig '/usr/share/Steinway D.gig' 0 0.8 PERSISTENT" + S: "OK" + + + + + C: "MAP MIDI_INSTRUMENT 127 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 1 0 0 gig '/usr/share/piano.gig' 0 0.25 'Silent Piano'" + S: "OK" + + + + + C: "MAP MIDI_INSTRUMENT 99 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 MIDI + instrument map entries by sending the following + command: + + + GET MIDI_INSTRUMENTS + + + Possible Answers: + + + LinuxSampler will answer by sending the current number of + entries in the sampler's MIDI instrument map. + + + + Example: + + + C: "GET MIDI_INSTRUMENTS" + S: "634" + + +
+ +
+ The front-end can query a list of all currently existing MIDI + instrument map entries by sending the following command: + + + LIST MIDI_INSTRUMENTS + + + Possible Answers: + + + LinuxSampler will answer by sending a comma separated + list of MIDI bank MSB (coarse) - MIDI bank LSB (fine) - + 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" + S: "{0,0,0},{0,0,1},{120,0,3},{120,0,4},{23,127,127}" + + +
+ +
+ The front-end can delete an entry from the MIDI instrument + map by sending the following command: + + + UNMAP MIDI_INSTRUMENT <midi_bank_msb> <midi_bank_lsb> <midi_prog> + + + + Where <midi_bank_msb> is an integer value between 0..127 + reflecting the MIDI bank MSB (coarse) value, <midi_bank_lsb> + an integer value between 0..127 reflecting the MIDI bank LSB + (fine) value and <midi_prog> an integer value between + 0..127 reflecting the MIDI program value of the map entrie's key + index triple. + + + Possible Answers: + + + "OK" - + + usually + + + "ERR:<error-code>:<error-message>" - + + when index out of bounds + + + + + + Example: + + + C: "UNMAP MIDI_INSTRUMENT 2 40 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 <midi_bank_msb> <midi_bank_lsb> <midi_prog> + + + + Where <midi_bank_msb> is an integer value between 0..127 + reflecting the MIDI bank MSB (coarse) value, <midi_bank_lsb> + an integer value between 0..127 reflecting the MIDI bank LSB + (fine) value and <midi_prog> an integer value between + 0..127 reflecting the MIDI program value of the map 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 3 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 the whole MIDI instrument map, that + is delete all entries by sending the following command: + + + CLEAR MIDI_INSTRUMENTS + + + + Possible Answers: + + + "OK" - + + always + + + + + + Example: + + + C: "CLEAR MIDI_INSTRUMENTS" + S: "OK" + + +
+ + +
The grammar of the control protocol as descibed in is defined below using Backus-Naur Form (BNF as described in ) @@ -3486,6 +3893,10 @@ ADD SP CHANNEL + / MAP SP map_instruction + + / UNMAP SP unmap_instruction + / GET SP get_instruction / CREATE SP create_instruction @@ -3496,7 +3907,8 @@ / LOAD SP load_instruction - / REMOVE SP CHANNEL SP sampler_channel + / REMOVE SP remove_instruction + / SET SP set_instruction @@ -3506,7 +3918,9 @@ / SELECT SP text - / RESET SP CHANNEL SP sampler_channel + / RESET SP reset_instruction + + / CLEAR SP clear_instruction / RESET @@ -3550,6 +3964,30 @@ +map_instruction = + + MIDI_INSTRUMENT SP midi_bank_msb SP midi_bank_lsb SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value + + / MIDI_INSTRUMENT SP midi_bank_msb SP midi_bank_lsb SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode + + / MIDI_INSTRUMENT SP midi_bank_msb SP midi_bank_lsb SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP entry_name + + / MIDI_INSTRUMENT SP midi_bank_msb SP midi_bank_lsb 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_bank_msb SP midi_bank_lsb SP midi_prog + + + +remove_instruction = + + CHANNEL SP sampler_channel + + + get_instruction = AVAILABLE_ENGINES @@ -3604,6 +4042,10 @@ / TOTAL_VOICE_COUNT_MAX + / MIDI_INSTRUMENTS + + / MIDI_INSTRUMENT SP INFO SP midi_bank_msb SP midi_bank_lsb SP midi_prog + set_instruction = @@ -3634,6 +4076,18 @@ +reset_instruction = + + CHANNEL SP sampler_channel + + + +clear_instruction = + + MIDI_INSTRUMENTS + + + destroy_instruction = AUDIO_OUTPUT_DEVICE SP number @@ -3706,6 +4160,8 @@ / AVAILABLE_AUDIO_OUTPUT_DRIVERS + / MIDI_INSTRUMENTS + load_instr_args = @@ -3722,6 +4178,16 @@ +instr_load_mode = + + ON_DEMAND + + / ON_DEMAND_HOLD + + / PERSISTENT + + + device_index = number @@ -3760,6 +4226,24 @@ +midi_bank_msb = + + number + + + +midi_bank_lsb = + + number + + + +midi_prog = + + number + + + volume_value = dotnum @@ -3790,6 +4274,12 @@ stringval + + +entry_name = + + stringval + param_val_list =