--- linuxsampler/trunk/Documentation/lscp.xml 2007/05/24 14:04:18 1200 +++ linuxsampler/trunk/Documentation/lscp.xml 2008/02/16 01:09:33 1695 @@ -16,7 +16,7 @@ to an annoying "missing Normative/Informative References" error message --> - + LinuxSampler Control Protocol + S: "OK" + + + + + C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE" + S: "OK" @@ -2113,6 +2121,12 @@ number of the sampler channel the instrument should be assigned to. Each sampler channel can only have one instrument. + 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 + MUST now be escaped as well! + The difference between regular and NON_MODAL versions of the command is that the regular command returns OK only after the instrument has been fully loaded and the channel is ready to be used while NON_MODAL version @@ -2148,10 +2162,18 @@ - Example: + Example (Unix): - + C: LOAD INSTRUMENT '/home/joe/gigs/cello.gig' 0 0 + S: OK + + + Example (Windows): + + + C: LOAD INSTRUMENT 'D:/MySounds/cello.gig' 0 0 + S: OK @@ -2429,7 +2451,9 @@ DESCRIPTION - - arbitrary description text about the engine + arbitrary description text about the engine + (note that the character string may contain + escape sequences) VERSION - @@ -2513,7 +2537,8 @@ the file name of the loaded instrument, "NONE" if there's no instrument yet loaded for this sampler - channel + channel (note: since LSCP 1.2 this path may contain + escape sequences) INSTRUMENT_NR - @@ -2523,7 +2548,9 @@ INSTRUMENT_NAME - - the instrument name of the loaded instrument + the instrument name of the loaded instrument + (note: since LSCP 1.2 this character string may contain + escape sequences) INSTRUMENT_STATUS - @@ -3241,7 +3268,9 @@ sampler channel on which the effect send should be created on, <midi-ctrl> is a number between 0..127 defining the MIDI controller which can alter the effect send level and <name> is an optional argument defining a name - for the effect send entity. The name does not have to be unique. + for the effect send entity. The name does not have to be unique, but MUST be + encapsulated into apostrophes and supports escape sequences as described in chapter + "Character Set and Escape Sequences". By default, that is as initial routing, the effect send's audio channels are automatically routed to the last audio channels of the sampler channel's @@ -3431,7 +3460,9 @@ NAME - - name of the effect send entity + name of the effect send entity + (note that this character string may contain + escape sequences) MIDI_CONTROLLER - @@ -3494,7 +3525,10 @@ 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. + does not have to be unique (name MUST be encapsulated into apostrophes + and supports escape sequences as described in chapter + "Character Set and Escape Sequences"). + Possible Answers: @@ -3898,6 +3932,24 @@ +
+ The front-end can ask for the current number of active disk streams on + the sampler by sending the following command: + + + GET TOTAL_STREAM_COUNT + + + + Possible Answers: + + + LinuxSampler will answer by returning the number of all active + disk streams on the sampler. + + +
+
The front-end can reset the whole sampler by sending the following command: @@ -3945,7 +3997,9 @@ DESCRIPTION - - arbitrary textual description about the sampler + arbitrary textual description about the sampler + (note that the character string may contain + escape sequences) VERSION - @@ -4061,7 +4115,7 @@ 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: @@ -4071,7 +4125,10 @@ 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. + names do not have to be unique, but MUST be encapsulated + into apostrophes and support escape sequences as described + in chapter "Character Set and Escape Sequences". + Possible Answers: @@ -4242,7 +4299,9 @@ NAME - custom name of the given map, - which does not have to be unique + which does not have to be unique + (note that this character string may contain + escape sequences) DEFAULT - @@ -4278,7 +4337,10 @@ 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. + have to be unique (name MUST be encapsulated into apostrophes + and supports escape sequences as described in chapter + "Character Set and Escape Sequences"). + Possible Answers: @@ -4325,7 +4387,9 @@ 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), + of the instrument's file to be deployed (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences"), <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 @@ -4407,9 +4471,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"). @@ -4633,7 +4698,9 @@ name for this mapped instrument. It can be set and changed with the "MAP MIDI_INSTRUMENT" - command and does not have to be unique. + command and does not have to be unique. + (note that this character string may contain + escape sequences) "ENGINE_NAME" - @@ -4644,7 +4711,9 @@ "INSTRUMENT_FILE" - - File name of the instrument. + File name of the instrument + (note that this path may contain + escape sequences). "INSTRUMENT_NR" - @@ -4656,7 +4725,8 @@ Name of the loaded instrument as reflected by its file. In contrast to the "NAME" field, the "INSTRUMENT_NAME" field - cannot be changed. + cannot be changed (note that this character string may contain + escape sequences). "LOAD_MODE" - @@ -4744,6 +4814,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 @@ -4921,7 +5003,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 - @@ -5085,7 +5169,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: @@ -5130,7 +5216,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"). @@ -5161,7 +5249,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"). @@ -5422,7 +5513,9 @@ INSTRUMENT_FILE - - File name of the instrument. + File name of the instrument. + Note that the character string may contain + escape sequences. INSTRUMENT_NR - @@ -5461,7 +5554,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 - @@ -5472,18 +5567,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. @@ -5640,7 +5741,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: @@ -5685,13 +5788,15 @@ 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"). SIZE=[<min>]..[<max>] - Restricts the search to instruments, which + 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 @@ -5727,34 +5832,42 @@ 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"). IS_DRUM=true | false - Either true or false. Restricts the search to + Either true or false. Restricts the search to drum kits or chromatic instruments. @@ -5862,11 +5975,294 @@
+
+ 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 CHANNEL 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 CHANNEL INSTRUMENT 0" + S: "OK" + + +
+
+ +
+ You can query detailed informations about files located + at the same system where the sampler instance is running on. + Using this command set allows to retrieve file informations + even remotely from another machine. + +
+ The front-end can retrieve the amount of instruments + within a given instrument file by sending the + following command: + + + GET FILE INSTRUMENTS <filename> + + + Where <filename> is the name of the instrument + file (encapsulated into apostrophes, supporting escape + sequences as described in chapter + "Character Set and Escape + Sequences"). + + The sampler will try to ask all sampler engines, + whether they support the given file and ask the first + engine with a positive answer for the amount of + instruments. + + Possible Answers: + + + On success, the sampler will answer by + returning the amount of instruments. + + "ERR:<error-code>:<error-message>" - + + if the file could not be handled + + + + + + Examples: + + + C: "GET FILE INSTRUMENTS 'D:/Sounds/Foo.gig'" + S: "10" + + +
+ +
+ The front-end can retrieve a list of all instruments + within a given instrument file by sending the + following command: + + + LIST FILE INSTRUMENTS <filename> + + + Where <filename> is the name of the instrument + file (encapsulated into apostrophes, supporting escape + sequences as described in chapter + "Character Set and Escape + Sequences"). + + The sampler will try to ask all sampler engines, + whether they support the given file and ask the first + engine with a positive answer for a list of IDs for the + instruments in the given file. + + Possible Answers: + + + On success, the sampler will answer by + returning a comma separated list of + instrument IDs. + + "ERR:<error-code>:<error-message>" - + + if the file could not be handled + + + + + + Examples: + + + C: "LIST FILE INSTRUMENTS 'D:/Sounds/Foo.gig'" + S: "0,1,2,3,4,5,6,7,8,9" + + +
+ +
+ The front-end can retrieve detailed informations + about a specific instrument within a given instrument + file by sending the following command: + + + GET FILE INSTRUMENT INFO <filename> + <instr-id> + + + Where <filename> is the name of the instrument + file (encapsulated into apostrophes, supporting escape + sequences as described in chapter + "Character Set and Escape + Sequences") and <instr-id> is the numeric + instrument ID as returned by the + + "LIST FILE INSTRUMENTS" command. + + The sampler will try to ask all sampler engines, + whether they support the given file and ask the first + engine with a positive answer for informations about the + specific instrument in the given file. + + 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 - + + name of the instrument as + stored in the instrument file + + + FORMAT_FAMILY - + + name of the sampler format + of the given instrument + + + FORMAT_VERSION - + + version of the sampler format + the instrumen is stored as + + + PRODUCT - + + official product name of the + instrument as stored in the file + + + + ARTISTS - + + artists / sample library + vendor of the instrument + + + + + + + The mentioned fields above don't have to be in particular order. + + Example: + + + C: "GET FILE INSTRUMENT INFO 'D:/Sounds/Foo.gig' 0" + S: "NAME: Lunatic Loops" +    "FORMAT_FAMILY: GIG" +    "FORMAT_VERSION: 3" +    "PRODUCT: The Backbone Bongo Beats" +    "ARTISTS: Jimmy the Fish" +    "." + + +
+
+
+
The grammar of the control protocol as descibed in is defined below using Backus-Naur Form (BNF as described in ) @@ -5949,6 +6345,10 @@ / COPY SP copy_instruction + / EDIT SP edit_instruction + + / FORMAT SP format_instruction + / RESET / QUIT @@ -5959,19 +6359,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 @@ -5991,6 +6391,10 @@ / CHANNEL_COUNT + / CHANNEL_MIDI + + / DEVICE_MIDI + / VOICE_COUNT / STREAM_COUNT @@ -6023,6 +6427,8 @@ / MISCELLANEOUS + / TOTAL_STREAM_COUNT + / TOTAL_VOICE_COUNT / GLOBAL_INFO @@ -6041,6 +6447,10 @@ / CHANNEL_COUNT + / CHANNEL_MIDI + + / DEVICE_MIDI + / VOICE_COUNT / STREAM_COUNT @@ -6073,6 +6483,8 @@ / MISCELLANEOUS + / TOTAL_STREAM_COUNT + / TOTAL_VOICE_COUNT / GLOBAL_INFO @@ -6105,11 +6517,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 @@ -6163,6 +6575,8 @@ / SERVER SP INFO + / TOTAL_STREAM_COUNT + / TOTAL_VOICE_COUNT / TOTAL_VOICE_COUNT_MAX @@ -6181,22 +6595,26 @@ / 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 / VOLUME + / FILE SP INSTRUMENTS SP filename + + / FILE SP INSTRUMENT SP INFO SP filename SP instrument_index + set_instruction = @@ -6207,6 +6625,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 @@ -6221,13 +6641,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 stringval_escaped - / DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP pathname SP stringval + / DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped - / DB_INSTRUMENT SP NAME SP pathname SP dirname + / DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped - / DB_INSTRUMENT SP DESCRIPTION SP pathname SP stringval + / DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped / ECHO SP boolean @@ -6267,29 +6687,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 @@ -6343,6 +6763,18 @@ +edit_instruction = + + CHANNEL SP INSTRUMENT SP sampler_channel + + + +format_instruction = + + INSTRUMENTS_DB + + + modal_arg = /* epsilon (empty argument) */ @@ -6389,13 +6821,15 @@ / 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 + + / FILE SP INSTRUMENTS SP filename @@ -6517,39 +6951,33 @@ -pathname = - - stringval - - - -dirname = +filename = - stringval + path -filename = +db_path = - stringval + path map_name = - stringval + stringval_escaped entry_name = - stringval + stringval_escaped fx_send_name = - stringval + stringval_escaped @@ -6561,6 +6989,7 @@ + param_val = string @@ -6583,9 +7012,9 @@ query_val = - string + text_escaped - / stringval + / stringval_escaped @@ -6601,6 +7030,119 @@ + +
+ 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 + 0 - 255). The same group of younger protocols also support + escape sequences, but only for certain, explicitly declared + parts of the protocol. The supported escape sequences are + defined as follows: + + ASCII Character Sequence + Translated into (Name) + \n new line + \r carriage return + \f form feed + \t horizontal tab + \v vertical tab + \' apostrophe + \" quotation mark + \\ backslash + \OOO three digit octal ASCII code of the character + \xHH two digit hex ASCII code of the character + + Notice: due to the transition of certain parts of the + protocol which now support escape sequences, a slight backward + 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 + in the old versions a single backslash was sufficient. + + The following LSCP commands support escape sequences as part + of their filename / path based arguments and / or may contain + a filename / path with escape sequences in their response: + + "LOAD INSTRUMENT" + "GET CHANNEL INFO" + "MAP MIDI_INSTRUMENT" + "GET MIDI_INSTRUMENT INFO" + "ADD DB_INSTRUMENT_DIRECTORY" + "ADD DB_INSTRUMENTS" + "REMOVE DB_INSTRUMENT_DIRECTORY" + "REMOVE DB_INSTRUMENT" + "GET DB_INSTRUMENT_DIRECTORIES" + "LIST DB_INSTRUMENT_DIRECTORIES" + "GET DB_INSTRUMENT_DIRECTORY INFO" + "GET DB_INSTRUMENTS" + "LIST DB_INSTRUMENTS" + "GET DB_INSTRUMENT INFO" + "SET DB_INSTRUMENT_DIRECTORY NAME" + "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION" + "SET DB_INSTRUMENT NAME" + "SET DB_INSTRUMENT DESCRIPTION" + "FIND DB_INSTRUMENTS" + "FIND DB_INSTRUMENT_DIRECTORIES" + "MOVE DB_INSTRUMENT" + "MOVE DB_INSTRUMENT_DIRECTORY" + "COPY DB_INSTRUMENT" + "COPY DB_INSTRUMENT_DIRECTORY" + "GET FILE INSTRUMENTS" + "LIST FILE INSTRUMENTS" + "GET FILE INSTRUMENT INFO" + + Note that the forward slash character ('/') has a special meaning in + filename / path based arguments: it acts as separator of the nodes in + the path, thus if a directory- or filename includes a forward slash + (not intended as path node separator), you MUST escape that slash + either with the respective hex escape sequence ("\x2f") or with the + respective octal escape sequence ("\057"). + + + + Note for Windows: file path arguments in LSCP are expected + to use forward slashes as directory node separator similar + to Unix based operating systems. In contrast to Unix however + a Windows typical drive character is expected to be + prefixed to the path. That is an original Windows file path + like "D:\Sounds\My.gig" would become in LSCP: + "D:/Sounds/My.gig". + + + + The following LSCP commands even support escape sequences as + part of at least one of their text-based arguments (i.e. entity name, + description) and / or may contain escape sequences in at least one of + their text-based fields in their response: + + "GET SERVER INFO" + "GET ENGINE INFO" + "GET CHANNEL INFO" + "CREATE FX_SEND" + "GET FX_SEND INFO" + "SET FX_SEND NAME" + "GET MIDI_INSTRUMENT INFO" + "GET MIDI_INSTRUMENT_MAP INFO" + "ADD MIDI_INSTRUMENT_MAP" + "MAP MIDI_INSTRUMENT" + "SET MIDI_INSTRUMENT_MAP NAME" + "GET DB_INSTRUMENT_DIRECTORY INFO" + "SET DB_INSTRUMENT_DIRECTORY NAME" + "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION" + "FIND DB_INSTRUMENT_DIRECTORIES" + "GET DB_INSTRUMENT INFO" + "SET DB_INSTRUMENT NAME" + "SET DB_INSTRUMENT DESCRIPTION" + "FIND DB_INSTRUMENTS" + + Please note that these lists are manually maintained. If you + find a command that also supports escape sequences we forgot to + mention here, please report it! + +
@@ -6704,6 +7246,56 @@ of sampler channels.
+
+ Client may want to be notified when MIDI data arrive on sampler channels on + back-end side, by issuing the following command: + + + SUBSCRIBE CHANNEL_MIDI + + + Server will start sending one of the the following notification messages: + + + "NOTIFY:CHANNEL_MIDI:<channel-id> NOTE_ON <note> <velocity>" + "NOTIFY:CHANNEL_MIDI:<channel-id> NOTE_OFF <note> <velocity>" + + + where <channel-id> will be replaced by the ID of the sampler channel where the MIDI + data arrived. <note> and <velocity> are integer values in the range between + 0 .. 127, reflecting the analog meaning of the MIDI specification. + + CAUTION: no guarantee whatsoever will be made that MIDI events are actually all + delivered by this mechanism! With other words: events could be lost at any time! + This restriction was made to keep the RT-safeness of the backend's MIDI and audio + thread unaffected by this feature. +
+ +
+ Client may want to be notified when MIDI data arrive on MIDI input devices by issuing the following command: + + + SUBSCRIBE DEVICE_MIDI + + + Server will start sending one of the the following notification messages: + + + "NOTIFY:CHANNEL_MIDI:<device-id> <port-id> NOTE_ON <note> <velocity>" + "NOTIFY:CHANNEL_MIDI:<device-id> <port-id> NOTE_OFF <note> <velocity>" + + + where <device-id> <port-id> will be replaced + by the IDs of the respective MIDI input device and the device's MIDI port where the MIDI + data arrived. <note> and <velocity> are integer values in the range between + 0 .. 127, reflecting the analog meaning of the MIDI specification. + + CAUTION: no guarantee whatsoever will be made that MIDI events are actually all + delivered by this mechanism! With other words: events could be lost at any time! + This restriction was made to keep the RT-safeness of the backend's MIDI and audio + thread unaffected by this feature. +
+
Client may want to be notified when the number of voices on the back-end changes by issuing the following command: @@ -6786,7 +7378,7 @@
- Client may want to be notified when the number of effect sends on + Client may want to be notified when the number of effect sends on a particular sampler channel is changed by issuing the following command: @@ -6841,6 +7433,24 @@ all currently active voices.
+
+ Client may want to be notified when the total number of disk streams on the + back-end changes by issuing the following command: + + + SUBSCRIBE TOTAL_STREAM_COUNT + + + Server will start sending the following notification messages: + + + "NOTIFY:TOTAL_STREAM_COUNT:<streams>" + + + where <streams> will be replaced by the new number of + all currently active disk streams. +
+
Client may want to be notified when the number of MIDI instrument maps on the back-end changes by issuing the following command: @@ -7146,6 +7756,16 @@ + + + ASCII format for Network Interchange + + UCLA + + + + +