--- linuxsampler/trunk/Documentation/lscp.xml 2006/11/26 16:29:57 944 +++ linuxsampler/trunk/Documentation/lscp.xml 2006/12/15 21:40:27 973 @@ -11,9 +11,12 @@ - - + + + + LinuxSampler Control Protocol + 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 the sampler's MIDI instrument map by sending the following + in a sampler's MIDI instrument map by sending the following command: - MAP MIDI_INSTRUMENT <midi_bank_msb> - <midi_bank_lsb> <midi_prog> <engine_name> + MAP MIDI_INSTRUMENT <map> + <midi_bank> <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 + 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 + 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 @@ -3582,7 +3911,7 @@ "ERR:<error-code>:<error-message>" - - when the given engine does not exist or a value + when the given map or engine does not exist or a value is out of range @@ -3592,13 +3921,13 @@ Examples: - C: "MAP MIDI_INSTRUMENT 3 0 0 gig '/usr/share/Steinway D.gig' 0 0.8 PERSISTENT" + C: "MAP MIDI_INSTRUMENT 0 3 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" + C: "MAP MIDI_INSTRUMENT 0 4 50 gig '/home/john/foostrings.gig' 7 1.0" S: "OK" @@ -3606,61 +3935,86 @@ 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'" + C: "MAP MIDI_INSTRUMENT 0 1 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'" + 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 MIDI - instrument map entries by sending the following + The front-end can query the amount of currently existing + entries in a MIDI instrument map by sending the following command: - GET MIDI_INSTRUMENTS + 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: - LinuxSampler will answer by sending the current number of - entries in the sampler's MIDI instrument map. + The sampler will answer by sending the current number of + entries in the MIDI instrument map(s). Example: - C: "GET MIDI_INSTRUMENTS" - S: "634" + 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 MIDI - instrument map entries by sending the following command: +
+ 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 + 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: - 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 + 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. @@ -3670,26 +4024,26 @@ Example: - C: "LIST MIDI_INSTRUMENTS" - S: "{0,0,0},{0,0,1},{120,0,3},{120,0,4},{23,127,127}" + 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 the MIDI instrument + The front-end can delete an entry from a MIDI instrument map by sending the following command: - UNMAP MIDI_INSTRUMENT <midi_bank_msb> <midi_bank_lsb> <midi_prog> + UNMAP MIDI_INSTRUMENT <map> <midi_bank> <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 + 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. @@ -3712,7 +4066,7 @@ Example: - C: "UNMAP MIDI_INSTRUMENT 2 40 127" + C: "UNMAP MIDI_INSTRUMENT 0 2 127" S: "OK" @@ -3723,15 +4077,15 @@ instrument map entry by sending the following command: - GET MIDI_INSTRUMENT INFO <midi_bank_msb> <midi_bank_lsb> <midi_prog> + GET MIDI_INSTRUMENT INFO <map> <midi_bank> <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 + 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. @@ -3797,7 +4151,7 @@ Example: - C: "GET MIDI_INSTRUMENT INFO 3 45 120" + C: "GET MIDI_INSTRUMENT INFO 1 45 120" S: "NAME: Drums for Foo Song"    "ENGINE_NAME: GigEngine"    "INSTRUMENT_FILE: /usr/share/joesdrumkit.gig" @@ -3811,13 +4165,25 @@
- The front-end can clear the whole MIDI instrument map, that - is delete all entries by sending the following command: + The front-end can clear a whole MIDI instrument map, that + is delete all its entries by sending the following command: - CLEAR MIDI_INSTRUMENTS + 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: @@ -3830,10 +4196,16 @@ - Example: + Examples: - C: "CLEAR MIDI_INSTRUMENTS" + C: "CLEAR MIDI_INSTRUMENTS 0" + S: "OK" + + + + + C: "CLEAR MIDI_INSTRUMENTS ALL" S: "OK" @@ -3891,7 +4263,7 @@ command = - ADD SP CHANNEL + ADD SP add_instruction / MAP SP map_instruction @@ -3908,7 +4280,6 @@ / LOAD SP load_instruction / REMOVE SP remove_instruction - / SET SP set_instruction @@ -3928,6 +4299,16 @@ +add_instruction = + + CHANNEL + + / MIDI_INSTRUMENT_MAP + + / MIDI_INSTRUMENT_MAP SP map_name + + + subscribe_event = CHANNEL_COUNT @@ -3966,19 +4347,19 @@ 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_map SP midi_bank 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_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_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_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_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 + / 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_bank_msb SP midi_bank_lsb SP midi_prog + MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog @@ -3986,6 +4367,10 @@ CHANNEL SP sampler_channel + / MIDI_INSTRUMENT_MAP SP midi_map + + / MIDI_INSTRUMENT_MAP SP ALL + get_instruction = @@ -4042,9 +4427,15 @@ / TOTAL_VOICE_COUNT_MAX - / MIDI_INSTRUMENTS + / 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 SP INFO SP midi_bank_msb SP midi_bank_lsb SP midi_prog + / MIDI_INSTRUMENT_MAP SP INFO SP midi_map @@ -4060,6 +4451,8 @@ / CHANNEL SP set_chan_instruction + / MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name + / ECHO SP boolean @@ -4084,7 +4477,9 @@ clear_instruction = - MIDI_INSTRUMENTS + MIDI_INSTRUMENTS SP midi_map + + / MIDI_INSTRUMENTS SP ALL @@ -4128,6 +4523,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 = @@ -4160,7 +4561,11 @@ / AVAILABLE_AUDIO_OUTPUT_DRIVERS - / MIDI_INSTRUMENTS + / MIDI_INSTRUMENTS SP midi_map + + / MIDI_INSTRUMENTS SP ALL + + / MIDI_INSTRUMENT_MAPS @@ -4226,13 +4631,13 @@ -midi_bank_msb = +midi_map = number -midi_bank_lsb = +midi_bank = number @@ -4274,6 +4679,12 @@ stringval + + +map_name = + + stringval + entry_name =