--- linuxsampler/trunk/Documentation/lscp.xml 2007/05/16 14:37:22 1188 +++ linuxsampler/trunk/Documentation/lscp.xml 2007/06/22 14:21:03 1250 @@ -16,9 +16,9 @@ to an annoying "missing Normative/Informative References" error message --> - + - LinuxSampler Control Protocol + LinuxSampler Control Protocol (draft) @@ -34,7 +34,7 @@ schoenebeck at software minus engineering dot org - + LinuxSampler Developers LSCP @@ -61,8 +61,8 @@ (front-end) and server (LinuxSampler) respectively. Lines in examples must be interpreted as every line being CRLF terminated (carriage return character followed by line feed - character as defined in the ASCII standard), thus the following - example: + character as defined in the ASCII standard ), + thus the following example: @@ -2113,6 +2113,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 @@ -4325,7 +4331,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 @@ -5202,7 +5210,7 @@ to the instruments database by sending the following command: - ADD DB_INSTRUMENTS [<mode>] <db_dir> <file_path> [<instr_index>] + ADD DB_INSTRUMENTS [NON_MODAL] [<mode>] <db_dir> <file_path> [<instr_index>] Where <db_dir> is the absolute path name of a directory @@ -5220,6 +5228,14 @@ scanning will be done and has exactly the following possibilities: + "RECURSIVE" - + + All instruments will be processed, including those + in the subdirectories, and the respective subdirectory + tree structure will be recreated in the instruments + database + + "NON_RECURSIVE" - Only the instruments in the specified directory @@ -5236,23 +5252,29 @@ the specified database directory. - not supplied - - - The subdirectory tree structure will be recreated - in the instruments database and all instruments will be - processed and added to the respective subdirectory - in the instruments database. - - + The difference between regular and NON_MODAL versions of the command + is that the regular command returns when the scanning is finished + while NON_MODAL version returns immediately and a background process is launched. + The GET DB_INSTRUMENTS_JOB INFO + command can be used to monitor the scanning progress. + Possible Answers: "OK" - - on success + on success when NON_MODAL is not supplied + + + "OK[<job-id>]" - + + on success when NON_MODAL is supplied, where <job-id> + is a numerical ID used to obtain status information about the job progress. + See GET DB_INSTRUMENTS_JOB INFO + "ERR:<error-code>:<error-message>" - @@ -5677,7 +5699,7 @@ 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 @@ -5740,7 +5762,7 @@ 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. @@ -5784,6 +5806,70 @@ +
+ The front-end can ask for the current status of a + particular database instruments job by sending the following command: + + + GET DB_INSTRUMENTS_JOB INFO <job-id> + + + Where <job-id> should be replaced by the numerical ID + of the job the front-end is interested in. + + 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: + + + + FILES_TOTAL - + + The total number of files scheduled for scanning + + + FILES_SCANNED - + + The current number of scanned files + + + SCANNING - + + The absolute path name of the file which is currently + being scanned + + + STATUS - + + An integer value between 0 and 100 indicating the + scanning progress percentage of the file which is + currently being scanned + + + + + + + The mentioned fields above don't have to be in particular order. + + Example: + + + C: "GET DB_INSTRUMENTS_JOB INFO 2" + S: "FILES_TOTAL: 12" +    "FILES_SCANNED: 7" +    "SCANNING: /home/me/gigs/Bosendorfer 290.gig" +    "STATUS: 42" +    "." + + +
+ @@ -5871,6 +5957,8 @@ / COPY SP copy_instruction + / EDIT SP edit_instruction + / RESET / QUIT @@ -5883,9 +5971,13 @@ / DB_INSTRUMENT_DIRECTORY SP pathname - / DB_INSTRUMENTS SP FLAT SP pathname SP pathname + / DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP pathname SP pathname + + / DB_INSTRUMENTS SP scan_mode SP pathname SP pathname - / DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP pathname + / DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname + + / DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname SP instrument_index / DB_INSTRUMENTS SP pathname SP pathname @@ -5937,6 +6029,8 @@ / DB_INSTRUMENT_INFO + / DB_INSTRUMENTS_JOB_INFO + / MISCELLANEOUS / TOTAL_VOICE_COUNT @@ -5985,6 +6079,8 @@ / DB_INSTRUMENT_INFO + / DB_INSTRUMENTS_JOB_INFO + / MISCELLANEOUS / TOTAL_VOICE_COUNT @@ -6107,6 +6203,8 @@ / DB_INSTRUMENT SP INFO SP pathname + / DB_INSTRUMENTS_JOB SP INFO SP number + / VOLUME @@ -6255,6 +6353,12 @@ +edit_instruction = + + INSTRUMENT SP sampler_channel + + + modal_arg = /* epsilon (empty argument) */ @@ -6443,7 +6547,7 @@ filename = - stringval + stringval_escaped @@ -6501,8 +6605,50 @@ +scan_mode = + + RECURSIVE + + / NON_RECURSIVE + + / FLAT + + + + +
+ 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. +
@@ -6688,7 +6834,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: @@ -6948,6 +7094,28 @@ the new name of the instrument, encapsulated into apostrophes.
+
+ Client may want to be notified when the status of particular database + instruments job is changed by issuing the following command: + + + SUBSCRIBE DB_INSTRUMENTS_JOB_INFO + + + Server will start sending the following notification messages: + + + "NOTIFY:DB_INSTRUMENTS_JOB_INFO:<job-id>" + + + where <job-id> will be replaced by the numerical ID of the job, + which status is changed. The front-end will have to send the respective + command to actually get the status 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 of miscellaneous and debugging events occurring at the server by issuing the following command: @@ -7026,6 +7194,16 @@ + + + ASCII format for Network Interchange + + UCLA + + + + +