--- linuxsampler/trunk/Documentation/lscp.xml 2007/06/22 13:40:53 1249 +++ linuxsampler/trunk/Documentation/lscp.xml 2007/10/07 10:32:53 1387 @@ -16,7 +16,7 @@ to an annoying "missing Normative/Informative References" error message --> - + LinuxSampler Control Protocol (draft) + S: "OK" + + + + + C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE" + S: "OK" @@ -2113,7 +2121,7 @@ number of the sampler channel the instrument should be assigned to. Each sampler channel can only have one instrument. - Notice: since LSCP 1.3 the <filename> argument supports + Notice: since LSCP 1.2 the <filename> argument supports escape characters for special characters (see chapter "Character Set and Escape Sequences" for details) and accordingly backslash characters in the filename @@ -3951,7 +3959,9 @@ DESCRIPTION - - arbitrary textual description about the sampler + arbitrary textual description about the sampler + (note that the character string may contain + escape sequences) VERSION - @@ -4415,9 +4425,10 @@ 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 + command(s). Finally the OPTIONAL <name> argument allows to set a custom name + (encapsulated into apostrophes, supporting escape sequences as described in chapter + "Character Set and Escape Sequences") for the + mapping entry, useful for frontends for displaying an appropriate name for mapped instruments (using "GET MIDI_INSTRUMENT INFO"). @@ -4752,6 +4763,18 @@
The following commands describe how to use and manage the instruments database. + Notice: + + + All command arguments representing a path or + instrument/directory name support escape sequences as described in chapter + "Character Set and Escape Sequences". + + All occurrences of a forward slash in instrument and directory + names are escaped with its hex (\x2f) or octal (\057) escape sequence. + + +
The front-end can add a new instrument directory to the @@ -4929,7 +4952,9 @@ DESCRIPTION - - A brief description of the directory content + A brief description of the directory content. + Note that the character string may contain + escape sequences. CREATED - @@ -5093,7 +5118,9 @@ Where <dir> is the absolute path name of the directory and - <desc> is the new description for the directory. + <desc> is the new description for the directory + (encapsulated into apostrophes, supporting escape sequences as described in chapter + "Character Set and Escape Sequences"). Possible Answers: @@ -5138,7 +5165,9 @@ NAME='<search-string>' Restricts the search to directories, which names - satisfy the supplied search string. + satisfy the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences"). @@ -5169,7 +5198,10 @@ DESCRIPTION='<search-string>' Restricts the search to directories with description - that satisfies the supplied search string. + that satisfies the supplied search string + (encapsulated into apostrophes, supporting escape + sequences as described in chapter + "Character Set and Escape Sequences"). @@ -5430,7 +5462,9 @@ INSTRUMENT_FILE - - File name of the instrument. + File name of the instrument. + Note that the character string may contain + escape sequences. INSTRUMENT_NR - @@ -5469,7 +5503,9 @@ DESCRIPTION - - A brief description of the instrument + A brief description of the instrument. + Note that the character string may contain + escape sequences. IS_DRUM - @@ -5480,18 +5516,24 @@ PRODUCT - - The product title of the instrument + The product title of the instrument. + Note that the character string may contain + escape sequences. ARTISTS - - Lists the artist names + Lists the artist names. + Note that the character string may contain + escape sequences. KEYWORDS - Provides a list of keywords that refer to the instrument. - Keywords are separated with semicolon and blank. + Keywords are separated with semicolon and blank. + Note that the character string may contain + escape sequences. @@ -5648,7 +5690,9 @@ Where <instr> is the absolute path name of the instrument and - <desc> is the new description for the instrument. + <desc> is the new description for the instrument + (encapsulated into apostrophes, supporting escape sequences as described in chapter + "Character Set and Escape Sequences"). Possible Answers: @@ -5693,7 +5737,9 @@ NAME='<search-string>' Restricts the search to instruments, which names - satisfy the supplied search string. + satisfy the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences"). @@ -5735,28 +5781,36 @@ DESCRIPTION='<search-string>' Restricts the search to instruments with description - that satisfies the supplied search string. + that satisfies the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences"). PRODUCT='<search-string>' Restricts the search to instruments with product info - that satisfies the supplied search string. + that satisfies the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences"). ARTISTS='<search-string>' Restricts the search to instruments with artists info - that satisfies the supplied search string. + that satisfies the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences"). KEYWORDS='<search-string>' Restricts the search to instruments with keyword list - that satisfies the supplied search string. + that satisfies the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences"). @@ -5870,8 +5924,112 @@
+
+ The front-end can remove all instruments and directories and re-create + the instruments database structure (e.g., in case of a database corruption) + by sending the following command: + + + FORMAT INSTRUMENTS_DB + + + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + If the formatting of the instruments database + failed. + + + + +
+
+ + +
+ The sampler allows to edit instruments while playing with the + sampler by spawning an external (3rd party) instrument editor + application for a given instrument. The 3rd party instrument + editor applications have to place a respective plugin DLL file + into the sampler's plugins directory. The sampler will + automatically try to load all plugin DLLs in that directory on + startup and only on startup! + At the moment there is only one command for this feature set, + but this will most probably change in future. + +
+ The front-end can request to open an appropriate instrument + editor application by sending the following command: + + + EDIT INSTRUMENT <sampler-channel> + + + Where <sampler-channel> should be replaced by the + number of the sampler channel as given by the + "ADD CHANNEL" + or "LIST CHANNELS" + command. + + The sampler will try to ask all registered instrument + editors (or to be more specific: their sampler plugins) + whether they are capable to handle the instrument on the + given sampler channel. The sampler will simply use the first + instrument editor application which replied with a positive + answer and spawn that instrument editor application within + the sampler's process and provide that application access + to the instrument's data structures, so both applications + can share and access the same instruments data at the same + time, thus allowing to immediately hear changes with the + sampler made by the instrument editor. + + Note: consequently instrument editors are always spawned + locally on the same machine where the sampler is running + on! + + Possible Answers: + + + "OK" - + + when an appropriate instrument editor was + launched + + + "WRN:<warning-code>:<warning-message>" - + + when an appropriate instrument editor was + launched, but there are noteworthy issues + + + "ERR:<error-code>:<error-message>" - + + when an appropriate instrument editor + could not be launched + + + + + + Examples: + + + C: "EDIT INSTRUMENT 0" + S: "OK" + + +
+
@@ -5959,6 +6117,8 @@ / EDIT SP edit_instruction + / FORMAT SP format_instruction + / RESET / QUIT @@ -5969,19 +6129,19 @@ CHANNEL - / DB_INSTRUMENT_DIRECTORY SP pathname + / DB_INSTRUMENT_DIRECTORY SP db_path - / DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP pathname SP pathname + / DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename - / DB_INSTRUMENTS SP scan_mode SP pathname SP pathname + / DB_INSTRUMENTS SP scan_mode SP db_path SP filename - / DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname + / DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename - / DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname SP instrument_index + / DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index - / DB_INSTRUMENTS SP pathname SP pathname + / DB_INSTRUMENTS SP db_path SP filename - / DB_INSTRUMENTS SP pathname SP pathname SP instrument_index + / DB_INSTRUMENTS SP db_path SP filename SP instrument_index / MIDI_INSTRUMENT_MAP @@ -6115,11 +6275,11 @@ / MIDI_INSTRUMENT_MAP SP ALL - / DB_INSTRUMENT_DIRECTORY SP FORCE SP pathname + / DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path - / DB_INSTRUMENT_DIRECTORY SP pathname + / DB_INSTRUMENT_DIRECTORY SP db_path - / DB_INSTRUMENT SP pathname + / DB_INSTRUMENT SP db_path @@ -6191,17 +6351,17 @@ / FX_SEND SP INFO SP sampler_channel SP fx_send_id - / DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname + / DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path - / DB_INSTRUMENT_DIRECTORIES SP pathname + / DB_INSTRUMENT_DIRECTORIES SP db_path - / DB_INSTRUMENT_DIRECTORY SP INFO SP pathname + / DB_INSTRUMENT_DIRECTORY SP INFO SP db_path - / DB_INSTRUMENTS SP RECURSIVE SP pathname + / DB_INSTRUMENTS SP RECURSIVE SP db_path - / DB_INSTRUMENTS SP pathname + / DB_INSTRUMENTS SP db_path - / DB_INSTRUMENT SP INFO SP pathname + / DB_INSTRUMENT SP INFO SP db_path / DB_INSTRUMENTS_JOB SP INFO SP number @@ -6217,6 +6377,8 @@ / MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list + / MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE + / MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list / CHANNEL SP set_chan_instruction @@ -6231,13 +6393,13 @@ / 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 NAME SP db_path SP raw_path - / DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP pathname SP stringval + / DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP raw_path - / DB_INSTRUMENT SP NAME SP pathname SP dirname + / DB_INSTRUMENT SP NAME SP db_path SP raw_path - / DB_INSTRUMENT SP DESCRIPTION SP pathname SP stringval + / DB_INSTRUMENT SP DESCRIPTION SP db_path SP raw_path / ECHO SP boolean @@ -6277,29 +6439,29 @@ find_instruction = - DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP query_val_list + DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list - / DB_INSTRUMENTS SP pathname SP query_val_list + / DB_INSTRUMENTS SP db_path SP query_val_list - / DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP pathname SP query_val_list + / DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP query_val_list - / DB_INSTRUMENT_DIRECTORIES SP pathname SP query_val_list + / DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list move_instruction = - DB_INSTRUMENT_DIRECTORY SP pathname SP pathname + DB_INSTRUMENT_DIRECTORY SP db_path SP db_path - / DB_INSTRUMENT SP pathname SP pathname + / DB_INSTRUMENT SP db_path SP db_path copy_instruction = - DB_INSTRUMENT_DIRECTORY SP pathname SP pathname + DB_INSTRUMENT_DIRECTORY SP db_path SP db_path - / DB_INSTRUMENT SP pathname SP pathname + / DB_INSTRUMENT SP db_path SP db_path @@ -6359,6 +6521,12 @@ +format_instruction = + + INSTRUMENTS_DB + + + modal_arg = /* epsilon (empty argument) */ @@ -6405,13 +6573,13 @@ / FX_SENDS SP sampler_channel - / DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname + / DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path - / DB_INSTRUMENT_DIRECTORIES SP pathname + / DB_INSTRUMENT_DIRECTORIES SP db_path - / DB_INSTRUMENTS SP RECURSIVE SP pathname + / DB_INSTRUMENTS SP RECURSIVE SP db_path - / DB_INSTRUMENTS SP pathname + / DB_INSTRUMENTS SP db_path @@ -6533,21 +6701,15 @@ -pathname = +filename = - stringval + path -dirname = +db_path = - stringval - - - -filename = - - stringval_escaped + path @@ -6577,6 +6739,7 @@ + param_val = string @@ -6599,9 +6762,9 @@ query_val = - string + raw_path_base - / stringval + / raw_path @@ -6619,7 +6782,7 @@
- Older versions of this protocol up to and including v1.2 only + Older versions of this protocol up to and including v1.1 only supported the standard ASCII character set (ASCII code 0 - 127) , all younger versions of this protocol however support the Extended ASCII character set (ASCII code @@ -6643,7 +6806,7 @@ Notice: due to the transition of certain parts of the protocol which now support escape sequences, a slight backward - incompatibility to protocols version v1.2 and younger has been + incompatibility to protocols version v1.1 and younger has been introduced. The only difference is that in parts of the protocol where escape characters are now supported, a backslash characters MUST be escaped as well (that is as double backslash), whereas