--- linuxsampler/trunk/Documentation/lscp.xml 2007/10/11 20:45:49 1401 +++ linuxsampler/trunk/Documentation/lscp.xml 2008/04/29 15:44:09 1727 @@ -16,9 +16,9 @@ to an annoying "missing Normative/Informative References" error message --> - + - LinuxSampler Control Protocol (draft) + LinuxSampler Control Protocol @@ -34,7 +34,7 @@ schoenebeck at software minus engineering dot org - + LinuxSampler Developers LSCP @@ -2162,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 @@ -3924,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: @@ -5715,7 +5741,7 @@ 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"). @@ -5958,7 +5984,7 @@ FORMAT INSTRUMENTS_DB - + Possible Answers: @@ -5977,6 +6003,72 @@
+
+ The front-end can retrieve the list of all instrument files in the instruments database + that don't exist in the filesystem by sending the following command: + + + FIND LOST DB_INSTRUMENT_FILES + + + + Possible Answers: + + + A comma separated list with the absolute path names + (encapsulated into apostrophes) of all lost instrument files. + "ERR:<error-code>:<error-message>" - + + in case it failed, providing an appropriate error code and error message. + + + + + Example: + + + C: "FIND LOST DB_INSTRUMENT_FILES" + S: "'/gigs/Bosendorfer 290.gig','/gigs/Steinway D.gig','/gigs/Free Piano.gig'" + + +
+ +
+ The front-end can substitute all occurrences of an instrument file + in the instruments database with a new one by sending the following command: + + + SET DB_INSTRUMENT FILE_PATH <old_path> <new_path> + + + Where <old_path> is the absolute path name of the instrument file + to substitute with <new_path>. + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + in case it failed, providing an appropriate error code and error message. + + + + + + Example: + + + C: "SET DB_INSTRUMENT FILE_PATH '/gigs/Bosendorfer 290.gig' '/gigs/pianos/Bosendorfer 290.gig'" + S: "OK" + + +
+ @@ -5997,7 +6089,7 @@ editor application by sending the following command: - EDIT INSTRUMENT <sampler-channel> + EDIT CHANNEL INSTRUMENT <sampler-channel> Where <sampler-channel> should be replaced by the @@ -6049,14 +6141,193 @@ Examples: - C: "EDIT INSTRUMENT 0" + 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 @@ -6186,6 +6457,10 @@ / CHANNEL_COUNT + / CHANNEL_MIDI + + / DEVICE_MIDI + / VOICE_COUNT / STREAM_COUNT @@ -6218,6 +6493,8 @@ / MISCELLANEOUS + / TOTAL_STREAM_COUNT + / TOTAL_VOICE_COUNT / GLOBAL_INFO @@ -6236,6 +6513,10 @@ / CHANNEL_COUNT + / CHANNEL_MIDI + + / DEVICE_MIDI + / VOICE_COUNT / STREAM_COUNT @@ -6268,6 +6549,8 @@ / MISCELLANEOUS + / TOTAL_STREAM_COUNT + / TOTAL_VOICE_COUNT / GLOBAL_INFO @@ -6358,6 +6641,8 @@ / SERVER SP INFO + / TOTAL_STREAM_COUNT + / TOTAL_VOICE_COUNT / TOTAL_VOICE_COUNT_MAX @@ -6392,6 +6677,10 @@ / VOLUME + / FILE SP INSTRUMENTS SP filename + + / FILE SP INSTRUMENT SP INFO SP filename SP instrument_index + set_instruction = @@ -6426,6 +6715,8 @@ / DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped + / DB_INSTRUMENT SP FILE_PATH SP filename SP filename + / ECHO SP boolean / VOLUME SP volume_value @@ -6472,6 +6763,8 @@ / DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list + / LOST SP DB_INSTRUMENT_FILES + move_instruction = @@ -6542,7 +6835,7 @@ edit_instruction = - INSTRUMENT SP sampler_channel + CHANNEL SP INSTRUMENT SP sampler_channel @@ -6606,6 +6899,8 @@ / DB_INSTRUMENTS SP db_path + / FILE SP INSTRUMENTS SP filename + load_instr_args = @@ -6865,6 +7160,11 @@ "MOVE DB_INSTRUMENT_DIRECTORY" "COPY DB_INSTRUMENT" "COPY DB_INSTRUMENT_DIRECTORY" + "FIND LOST DB_INSTRUMENT_FILES" + "SET DB_INSTRUMENT FILE_PATH" + "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 @@ -6875,6 +7175,16 @@ + 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 @@ -7008,6 +7318,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:DEVICE_MIDI:<device-id> <port-id> NOTE_ON <note> <velocity>" + "NOTIFY:DEVICE_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: @@ -7145,6 +7505,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: