--- linuxsampler/trunk/Documentation/lscp.xml 2005/07/20 21:43:23 705 +++ linuxsampler/trunk/Documentation/lscp.xml 2006/12/20 19:40:37 991 @@ -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 a sampler's MIDI instrument map by sending the following + command: + + + MAP MIDI_INSTRUMENT <map> + <midi_bank> <midi_prog> <engine_name> + <filename> <instrument_index> <volume_value> + [<instr_load_mode>] [<name>] + + + Where <map> is the numeric ID of the map to alter, + <midi_bank> is an integer value between + 0..16383 reflecting the MIDI bank select index, + <midi_prog> an + integer value between 0..127 reflecting the MIDI program change + index, <engine_name> a sampler engine name as returned by + the "LIST AVAILABLE_ENGINES" + command (not encapsulated into apostrophes), <filename> the name + of the instrument's file to be deployed (encapsulated into apostrophes), + <instrument_index> the index (integer value) of the instrument + within the given file, <volume_value> reflects the master + volume of the instrument as optionally dotted number (where a + value < 1.0 means attenuation and a value > 1.0 means + amplification). This parameter easily allows to adjust the + volume of all intruments within a custom instrument map + without having to adjust their instrument files. The + OPTIONAL <instr_load_mode> argument defines the life + time of the instrument, that is when the instrument should + be loaded, when freed and has exactly the following + possibilities: + + + "ON_DEMAND" - + + The instrument will be loaded when needed, + that is when demanded by at least one sampler + channel. It will immediately be freed from memory + when not needed by any sampler channel anymore. + + + "ON_DEMAND_HOLD" - + + The instrument will be loaded when needed, + that is when demanded by at least one sampler + channel. It will be kept in memory even when + not needed by any sampler channel anymore. + Instruments with this mode are only freed + when the sampler is reset or all mapping + entries with this mode (and respective + instrument) are explicitly changed to + "ON_DEMAND" and no sampler channel is using + the instrument anymore. + + + "PERSISTENT" - + + The instrument will immediately be loaded + into memory in the background when this mapping + command is sent and the instrument is kept all + the time. Instruments with this mode are + only freed when the sampler is reset or all + mapping entries with this mode (and + respective instrument) are explicitly + changed to "ON_DEMAND" and no sampler + channel is using the instrument anymore. + + + not supplied - + + In case there is no <instr_load_mode> + argument given, it will be up to the + InstrumentManager to decide which mode to use. + Usually it will use "ON_DEMAND" if an entry + for the given instrument does not exist in + the InstrumentManager's list yet, otherwise + if an entry already exists, it will simply + stick with the mode currently reflected by + the already existing entry, that is it will + not change the mode. + + + + + + The <instr_load_mode> argument thus allows to define an + appropriate strategy (low memory consumption vs. fast + instrument switching) for each instrument individually. Note, the + following restrictions apply to this argument: "ON_DEMAND_HOLD" and + "PERSISTENT" have to be supported by the respective sampler engine + (which is technically the case when the engine provides an + InstrumentManager for its format). If this is not the case the + argument will automatically fall back to the default value + "ON_DEMAND". Also the load mode of one instrument may + automatically change the laod mode of other instrument(s), i.e. + because the instruments are part of the same file and the + engine does not allow a way to manage load modes for them + individually. Due to this, in case the frontend shows the + load modes of entries, the frontend should retrieve the actual + mode by i.e. sending + "GET MIDI_INSTRUMENT INFO" + command(s). Finally the OPTIONAL <name> argument allows to + set a custom name (encapsulated into apostrophes) for the mapping + entry, useful for frontends for displaying an appropriate name for + mapped instruments (using + "GET MIDI_INSTRUMENT INFO"). + + + The "MAP MIDI_INSTRUMENT" command + will immediately return, thus it will not block when an + instrument is to be loaded due to a "PERSISTENT" type + entry as instruments are loaded in the background. As a + consequence this command may not necessarily return an error + i.e. when the given instrument file does not exist or may + turn out to be corrupt. + + + Possible Answers: + + + "OK" - + + usually + + + "ERR:<error-code>:<error-message>" - + + when the given map or engine does not exist or a value + is out of range + + + + + + Examples: + + + C: "MAP MIDI_INSTRUMENT 0 3 0 gig '/usr/share/Steinway D.gig' 0 0.8 PERSISTENT" + S: "OK" + + + + + C: "MAP MIDI_INSTRUMENT 0 4 50 gig '/home/john/foostrings.gig' 7 1.0" + S: "OK" + + + + + C: "MAP MIDI_INSTRUMENT 0 0 0 gig '/usr/share/piano.gig' 0 1.0 'Normal Piano'" + S: "OK" + C: "MAP MIDI_INSTRUMENT 0 1 0 gig '/usr/share/piano.gig' 0 0.25 'Silent Piano'" + S: "OK" + + + + + C: "MAP MIDI_INSTRUMENT 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'" + S: "OK" + + +
+ +
+ The front-end can query the amount of currently existing + entries in a MIDI instrument map by sending the following + command: + + + GET MIDI_INSTRUMENTS <map> + + + The front-end can query the amount of currently existing + entries in all MIDI instrument maps by sending the following + command: + + + GET MIDI_INSTRUMENTS ALL + + + Possible Answers: + + + The sampler will answer by sending the current number of + entries in the MIDI instrument map(s). + + + + Example: + + + C: "GET MIDI_INSTRUMENTS 0" + S: "234" + + + + + C: "GET MIDI_INSTRUMENTS ALL" + S: "954" + + +
+ +
+ The front-end can query a list of all currently existing + entries in a certain MIDI instrument map by sending the following + command: + + + LIST MIDI_INSTRUMENTS <map> + + + Where <map> is the numeric ID of the MIDI instrument map. + The front-end can query a list of all currently existing + entries of all MIDI instrument maps by sending the following + command: + + + LIST MIDI_INSTRUMENTS ALL + + + + Possible Answers: + + + The sampler will answer by sending a comma separated + list of map ID - MIDI bank - MIDI program triples, where + each triple is encapsulated into curly braces. The + list is returned in one single line. Each triple + just reflects the key of the respective map entry, + thus subsequent + "GET MIDI_INSTRUMENT INFO" + command(s) are necessary to retrieve detailed informations + about each entry. + + + + Example: + + + C: "LIST MIDI_INSTRUMENTS 0" + S: "{0,0,0},{0,0,1},{0,0,3},{0,1,4},{1,127,127}" + + +
+ +
+ The front-end can delete an entry from a MIDI instrument + map by sending the following command: + + + UNMAP MIDI_INSTRUMENT <map> <midi_bank> <midi_prog> + + + + Where <map> is the numeric ID of the MIDI instrument map, + <midi_bank> is an integer value between 0..16383 + reflecting the MIDI bank value and + <midi_prog> an integer value between + 0..127 reflecting the MIDI program value of the map's entrie's key + index triple. + + + Possible Answers: + + + "OK" - + + usually + + + "ERR:<error-code>:<error-message>" - + + when index out of bounds + + + + + + Example: + + + C: "UNMAP MIDI_INSTRUMENT 0 2 127" + S: "OK" + + +
+ +
+ The front-end can retrieve the current settings of a certain + instrument map entry by sending the following command: + + + GET MIDI_INSTRUMENT INFO <map> <midi_bank> <midi_prog> + + + + Where <map> is the numeric ID of the MIDI instrument map, + <midi_bank> is an integer value between 0..16383 + reflecting the MIDI bank value, <midi_bank> + and <midi_prog> an integer value between + 0..127 reflecting the MIDI program value of the map's entrie's key + index triple. + + + Possible Answers: + + + LinuxSampler will answer by sending a <CRLF> + separated list. Each answer line begins with the + information category name followed by a colon and then + a space character <SP> and finally the info + character string to that info category. At the moment + the following categories are defined: + "NAME" - + + Name for this MIDI instrument map entry (if defined). + This name shall be used by frontends for displaying a + name for this mapped instrument. It can be set and + changed with the + "MAP MIDI_INSTRUMENT" + command and does not have to be unique. + + + "ENGINE_NAME" - + + Name of the engine to be deployed for this + instrument. + + + "INSTRUMENT_FILE" - + + File name of the instrument. + + + "INSTRUMENT_NR" - + + Index of the instrument within the file. + + + "INSTRUMENT_NAME" - + + Name of the loaded instrument as reflected by its file. + In contrast to the "NAME" field, the "INSTRUMENT_NAME" field + cannot be changed. + + + "LOAD_MODE" - + + Life time of instrument + (see "MAP MIDI_INSTRUMENT" for details about this setting). + + + "VOLUME" - + + master volume of the instrument as optionally + dotted number (where a value < 1.0 means attenuation + and a value > 1.0 means amplification) + + + The mentioned fields above don't have to be in particular order. + + + + Example: + + + C: "GET MIDI_INSTRUMENT INFO 1 45 120" + S: "NAME: Drums for Foo Song" +    "ENGINE_NAME: GigEngine" +    "INSTRUMENT_FILE: /usr/share/joesdrumkit.gig" +    "INSTRUMENT_NR: 0" +    "INSTRUMENT_NAME: Joe's Drumkit" +    "LOAD_MODE: PERSISTENT" +    "VOLUME: 1.0" +    "." + + +
+ +
+ The front-end can clear a whole MIDI instrument map, that + is delete all its entries by sending the following command: + + + CLEAR MIDI_INSTRUMENTS <map> + + + Where <map> is the numeric ID of the map to clear. + The front-end can clear all MIDI instrument maps, that + is delete all entries of all maps by sending the following + command: + + + CLEAR MIDI_INSTRUMENTS ALL + + + The command "CLEAR MIDI_INSTRUMENTS ALL" does not delete the + maps, only their entries, thus the map's settings like + custom name will be preservevd. + + Possible Answers: + + + "OK" - + + always + + + + + + Examples: + + + C: "CLEAR MIDI_INSTRUMENTS 0" + S: "OK" + + + + + C: "CLEAR MIDI_INSTRUMENTS ALL" + S: "OK" + + +
+ + +
The grammar of the control protocol as descibed in is defined below using Backus-Naur Form (BNF as described in ) @@ -3319,13 +4237,13 @@ line = - /* epsilon (empty line ignored) */ + /* epsilon (empty line ignored) */ - / comment + / comment - / command + / command - / error + / error @@ -3345,233 +4263,365 @@ command = - ADD SP CHANNEL + ADD SP add_instruction + + / MAP SP map_instruction + + / UNMAP SP unmap_instruction - / GET SP get_instruction + / GET SP get_instruction - / CREATE SP create_instruction + / CREATE SP create_instruction - / DESTROY SP destroy_instruction + / DESTROY SP destroy_instruction - / LIST SP list_instruction + / LIST SP list_instruction - / LOAD SP load_instruction + / LOAD SP load_instruction - / REMOVE SP CHANNEL SP sampler_channel + / REMOVE SP remove_instruction - / SET SP set_instruction + / SET SP set_instruction - / SUBSCRIBE SP subscribe_event + / SUBSCRIBE SP subscribe_event - / UNSUBSCRIBE SP unsubscribe_event + / UNSUBSCRIBE SP unsubscribe_event - / SELECT SP text + / SELECT SP text - / RESET SP CHANNEL SP sampler_channel + / RESET SP reset_instruction - / RESET + / CLEAR SP clear_instruction - / QUIT + / RESET + + / QUIT + + + +add_instruction = + + CHANNEL + + / MIDI_INSTRUMENT_MAP + + / MIDI_INSTRUMENT_MAP SP map_name subscribe_event = - CHANNEL_COUNT + AUDIO_OUTPUT_DEVICE_COUNT + + / AUDIO_OUTPUT_DEVICE_INFO + + / MIDI_INPUT_DEVICE_COUNT + + / MIDI_INPUT_DEVICE_INFO + + / CHANNEL_COUNT + + / VOICE_COUNT - / VOICE_COUNT + / STREAM_COUNT - / STREAM_COUNT + / BUFFER_FILL - / BUFFER_FILL + / CHANNEL_INFO - / CHANNEL_INFO + / MIDI_INSTRUMENT_MAP_COUNT - / MISCELLANEOUS + / MIDI_INSTRUMENT_MAP_INFO + + / MIDI_INSTRUMENT_COUNT + + / MIDI_INSTRUMENT_INFO + + / MISCELLANEOUS + + / TOTAL_VOICE_COUNT unsubscribe_event = - CHANNEL_COUNT + AUDIO_OUTPUT_DEVICE_COUNT + + / AUDIO_OUTPUT_DEVICE_INFO + + / MIDI_INPUT_DEVICE_COUNT - / VOICE_COUNT + / MIDI_INPUT_DEVICE_INFO - / STREAM_COUNT + / CHANNEL_COUNT - / BUFFER_FILL + / VOICE_COUNT - / CHANNEL_INFO + / STREAM_COUNT - / MISCELLANEOUS + / BUFFER_FILL + + / CHANNEL_INFO + + / MIDI_INSTRUMENT_MAP_COUNT + + / MIDI_INSTRUMENT_MAP_INFO + + / MIDI_INSTRUMENT_COUNT + + / MIDI_INSTRUMENT_INFO + + / MISCELLANEOUS + + / TOTAL_VOICE_COUNT + + + +map_instruction = + + MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value + + / MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode + + / MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP entry_name + + / MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode SP entry_name + + + +unmap_instruction = + + MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog + + + +remove_instruction = + + CHANNEL SP sampler_channel + + / MIDI_INSTRUMENT_MAP SP midi_map + + / MIDI_INSTRUMENT_MAP SP ALL get_instruction = - AVAILABLE_ENGINES + 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 - / AVAILABLE_MIDI_INPUT_DRIVERS + / AUDIO_OUTPUT_DRIVER SP INFO SP string - / MIDI_INPUT_DRIVER SP INFO SP string + / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string - / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string + / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list - / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list + / AUDIO_OUTPUT_DEVICES - / AVAILABLE_AUDIO_OUTPUT_DRIVERS + / MIDI_INPUT_DEVICES - / AUDIO_OUTPUT_DRIVER SP INFO SP string + / AUDIO_OUTPUT_DEVICE SP INFO SP number - / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string + / MIDI_INPUT_DEVICE SP INFO SP number - / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP key_val_list + / MIDI_INPUT_PORT SP INFO SP number SP number - / AUDIO_OUTPUT_DEVICES + / MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string - / MIDI_INPUT_DEVICES + / AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number - / AUDIO_OUTPUT_DEVICE SP INFO SP number + / AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP string - / MIDI_INPUT_DEVICE SP INFO SP number + / CHANNELS - / MIDI_INPUT_PORT SP INFO SP number SP number + / CHANNEL SP INFO SP sampler_channel - / MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string + / CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel - / AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number + / CHANNEL SP STREAM_COUNT SP sampler_channel - / AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP string + / CHANNEL SP VOICE_COUNT SP sampler_channel - / CHANNELS + / ENGINE SP INFO SP engine_name - / CHANNEL SP INFO SP sampler_channel + / SERVER SP INFO - / CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel + / TOTAL_VOICE_COUNT - / CHANNEL SP STREAM_COUNT SP sampler_channel + / TOTAL_VOICE_COUNT_MAX - / CHANNEL SP VOICE_COUNT SP sampler_channel + / MIDI_INSTRUMENTS SP midi_map - / ENGINE SP INFO SP engine_name + / MIDI_INSTRUMENTS SP ALL - / SERVER SP INFO + / MIDI_INSTRUMENT SP INFO SP midi_map SP midi_bank SP midi_prog + + / MIDI_INSTRUMENT_MAPS + + / MIDI_INSTRUMENT_MAP SP INFO SP midi_map set_instruction = - AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list + AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list + + / AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '=' param_val_list - / 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_DEVICE_PARAMETER SP number SP string '=' param_val_list + / MIDI_INPUT_PORT_PARAMETER SP number 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 - / CHANNEL SP set_chan_instruction + / MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name - / ECHO SP boolean + / ECHO SP boolean create_instruction = - AUDIO_OUTPUT_DEVICE SP string SP key_val_list + AUDIO_OUTPUT_DEVICE SP string SP key_val_list - / AUDIO_OUTPUT_DEVICE SP string + / AUDIO_OUTPUT_DEVICE SP string - / MIDI_INPUT_DEVICE SP string SP key_val_list + / MIDI_INPUT_DEVICE SP string SP key_val_list - / MIDI_INPUT_DEVICE SP string + / MIDI_INPUT_DEVICE SP string + + + +reset_instruction = + + CHANNEL SP sampler_channel + + + +clear_instruction = + + MIDI_INSTRUMENTS SP midi_map + + / MIDI_INSTRUMENTS SP ALL destroy_instruction = - AUDIO_OUTPUT_DEVICE SP number + AUDIO_OUTPUT_DEVICE SP number - / MIDI_INPUT_DEVICE SP number + / MIDI_INPUT_DEVICE SP number load_instruction = - INSTRUMENT SP load_instr_args + INSTRUMENT SP load_instr_args - / ENGINE SP load_engine_args + / ENGINE SP load_engine_args set_chan_instruction = - AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index + AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index - / AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index SP audio_channel_index + / AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index SP audio_channel_index - / AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name + / 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 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_DEVICE SP sampler_channel SP device_index - / MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_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_CHANNEL SP sampler_channel SP midi_input_channel_index - / MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name + / MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name - / VOLUME SP sampler_channel SP volume_value + / VOLUME SP sampler_channel SP volume_value - / MUTE SP sampler_channel SP boolean + / MUTE SP sampler_channel SP boolean - / SOLO 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 key_val_list = - string '=' param_val_list + string '=' param_val_list - / key_val_list SP string '=' param_val_list + / key_val_list SP string '=' param_val_list buffer_size_type = - BYTES + BYTES - / PERCENTAGE + / PERCENTAGE list_instruction = - AUDIO_OUTPUT_DEVICES + AUDIO_OUTPUT_DEVICES + + / MIDI_INPUT_DEVICES + + / CHANNELS + + / AVAILABLE_ENGINES - / MIDI_INPUT_DEVICES + / AVAILABLE_MIDI_INPUT_DRIVERS - / CHANNELS + / AVAILABLE_AUDIO_OUTPUT_DRIVERS - / AVAILABLE_ENGINES + / MIDI_INSTRUMENTS SP midi_map - / AVAILABLE_MIDI_INPUT_DRIVERS + / MIDI_INSTRUMENTS SP ALL - / AVAILABLE_AUDIO_OUTPUT_DRIVERS + / MIDI_INSTRUMENT_MAPS load_instr_args = - filename SP instrument_index SP sampler_channel + filename SP instrument_index SP sampler_channel - / NON_MODAL SP filename SP instrument_index SP sampler_channel + / NON_MODAL SP filename SP instrument_index SP sampler_channel load_engine_args = - engine_name SP sampler_channel + engine_name SP sampler_channel + + + +instr_load_mode = + + ON_DEMAND + + / ON_DEMAND_HOLD + + / PERSISTENT @@ -3603,7 +4653,7 @@ number - / ALL + / ALL @@ -3613,11 +4663,29 @@ +midi_map = + + number + + + +midi_bank = + + number + + + +midi_prog = + + number + + + volume_value = dotnum - / number + / number @@ -3645,11 +4713,23 @@ +map_name = + + stringval + + + +entry_name = + + stringval + + + param_val_list = param_val - / param_val_list','param_val + / param_val_list','param_val @@ -3657,13 +4737,11 @@ string - / '\'' string '\'' - - / '\"' string '\"' + / stringval - / number + / number - / dotnum + / dotnum @@ -3674,7 +4752,87 @@
This chapter will describe all currently defined events supported by LinuxSampler. -
+
+ Client may want to be notified when the total number of audio output devices on the + back-end changes by issuing the following command: + + + SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT + + + Server will start sending the following notification messages: + + + "NOTIFY:AUDIO_OUTPUT_DEVICE_COUNT:<devices>" + + + where <devices> will be replaced by the new number + of audio output devices. +
+ +
+ Client may want to be notified when changes were made to audio output devices on the + back-end by issuing the following command: + + + SUBSCRIBE AUDIO_OUTPUT_DEVICE_INFO + + + Server will start sending the following notification messages: + + + "NOTIFY:AUDIO_OUTPUT_DEVICE_INFO:<device-id>" + + + where <device-id> will be replaced by the numerical ID of the audio output device, + which settings has been changed. The front-end will have to send + the respective command to actually get the audio output device info. Because these messages + will be triggered by LSCP commands issued by other clients rather than real + time events happening on the server, it is believed that an empty notification + message is sufficient here. +
+ +
+ Client may want to be notified when the total number of MIDI input devices on the + back-end changes by issuing the following command: + + + SUBSCRIBE MIDI_INPUT_DEVICE_COUNT + + + Server will start sending the following notification messages: + + + "NOTIFY:MIDI_INPUT_DEVICE_COUNT:<devices>" + + + where <devices> will be replaced by the new number + of MIDI input devices. +
+ +
+ Client may want to be notified when changes were made to MIDI input devices on the + back-end by issuing the following command: + + + SUBSCRIBE MIDI_INPUT_DEVICE_INFO + + + Server will start sending the following notification messages: + + + "NOTIFY:MIDI_INPUT_DEVICE_INFO:<device-id>" + + + where <device-id> will be replaced by the numerical ID of the MIDI input device, + which settings has been changed. The front-end will have to send + the respective command to actually get the MIDI input device info. Because these messages + will be triggered by LSCP commands issued by other clients rather than real + time events happening on the server, it is believed that an empty notification + message is sufficient here. +
+ +
Client may want to be notified when the total number of channels on the back-end changes by issuing the following command: @@ -3751,7 +4909,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: @@ -3771,6 +4929,106 @@ 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 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.