--- linuxsampler/trunk/Documentation/lscp.xml 2007/03/29 09:40:45 1135 +++ linuxsampler/trunk/Documentation/lscp.xml 2007/06/22 13:40:53 1249 @@ -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.3 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 @@ -3959,6 +3965,12 @@ complies with (see for details) + INSTRUMENTS_DB_SUPPORT - + + either yes or no, specifies whether the + sampler is build with instruments database support. + + @@ -4256,6 +4268,7 @@ C: "GET MIDI_INSTRUMENT_MAP INFO 0" S: "NAME: Standard Map" +    "DEFAULT: true"    "." @@ -4318,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 @@ -4733,6 +4748,1130 @@ + +
+ The following commands describe how to use and manage + the instruments database. + +
+ The front-end can add a new instrument directory to the + instruments database by sending the following command: + + + ADD DB_INSTRUMENT_DIRECTORY <dir> + + + Where <dir> is the absolute path name of the directory + to be created (encapsulated into apostrophes). + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + when the directory could not be created, which + can happen if the directory already exists or the + name contains not allowed symbols + + + + + + Examples: + + + C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'" + S: "OK" + + +
+ +
+ The front-end can delete a particular instrument directory + from the instruments database by sending the following command: + + + REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] <dir> + + + Where <dir> is the absolute path name of the directory + to delete. The optional FORCE argument can be used to + force the deletion of a non-empty directory and all its content. + + Possible Answers: + + + "OK" - + + if the directory is deleted successfully + + + "ERR:<error-code>:<error-message>" - + + if the given directory does not exist, or + if trying to delete a non-empty directory, + without using the FORCE argument. + + + + + + Examples: + + + C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'" + S: "OK" + + +
+ +
+ The front-end can retrieve the current amount of + directories in a specific directory by sending the following command: + + + GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] <dir> + + + Where <dir> should be replaced by the absolute path + name of the directory. If RECURSIVE is specified, the number of + all directories, including those located in subdirectories of the + specified directory, will be returned. + + Possible Answers: + + + The current number of instrument directories + in the specified directory. + "ERR:<error-code>:<error-message>" - + + if the given directory does not exist. + + + + + + Example: + + + C: "GET DB_INSTRUMENT_DIRECTORIES '/'" + S: "2" + + +
+ +
+ The front-end can retrieve the current list of directories + in specific directory by sending the following command: + + + LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] <dir> + + + Where <dir> should be replaced by the absolute path + name of the directory. If RECURSIVE is specified, the absolute path names + of all directories, including those located in subdirectories of the + specified directory, will be returned. + + Possible Answers: + + + A comma separated list of all instrument directories + (encapsulated into apostrophes) in the specified directory. + "ERR:<error-code>:<error-message>" - + + if the given directory does not exist. + + + + + Example: + + + C: "LIST DB_INSTRUMENT_DIRECTORIES '/'" + S: "'Piano Collection','Percussion Collection'" + + + + + C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'" + S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano Collection/Acoustic/New','/Percussion Collection'" + + +
+ +
+ The front-end can ask for the current settings of an + instrument directory by sending the following command: + + + GET DB_INSTRUMENT_DIRECTORY INFO <dir> + + + Where <dir> should be replaced by the absolute path + name of the directory 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: + + + + DESCRIPTION - + + A brief description of the directory content + + + CREATED - + + The creation date and time of the directory, + represented in "YYYY-MM-DD HH:MM:SS" format + + + MODIFIED - + + The date and time of the last modification of the + directory, represented in "YYYY-MM-DD HH:MM:SS" format + + + + + + + The mentioned fields above don't have to be in particular order. + + Example: + + + C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'" + S: "DESCRIPTION: Piano collection of instruments in GigaSampler format." +    "CREATED: 2007-02-05 10:23:12" +    "MODIFIED: 2007-04-07 12:50:21" +    "." + + +
+ +
+ The front-end can alter the name of a specific + instrument directory by sending the following command: + + + SET DB_INSTRUMENT_DIRECTORY NAME <dir> <name> + + + Where <dir> is the absolute path name of the directory and + <name> is the new name for that directory. + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + in case the given directory does not exists, + or if a directory with name equal to the new + name already exists. + + + + + + Example: + + + C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic' 'Acoustic'" + S: "OK" + + +
+ +
+ The front-end can move a specific + instrument directory by sending the following command: + + + MOVE DB_INSTRUMENT_DIRECTORY <dir> <dst> + + + Where <dir> is the absolute path name of the directory + to move and <dst> is the location where the directory will + be moved to. + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + in case a given directory does not exists, + or if a directory with name equal to the name + of the specified directory already exists in + the destination directory. Error is also thrown + when trying to move a directory to a subdirectory + of itself. + + + + + + Example: + + + C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/Acoustic'" + S: "OK" + + +
+ +
+ The front-end can copy a specific + instrument directory by sending the following command: + + + COPY DB_INSTRUMENT_DIRECTORY <dir> <dst> + + + Where <dir> is the absolute path name of the directory + to copy and <dst> is the location where the directory will + be copied to. + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + in case a given directory does not exists, + or if a directory with name equal to the name + of the specified directory already exists in + the destination directory. Error is also thrown + when trying to copy a directory to a subdirectory + of itself. + + + + + + Example: + + + C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic' '/Acoustic/Pianos'" + S: "OK" + + +
+ +
+ The front-end can alter the description of a specific + instrument directory by sending the following command: + + + SET DB_INSTRUMENT_DIRECTORY DESCRIPTION <dir> <desc> + + + Where <dir> is the absolute path name of the directory and + <desc> is the new description for the directory. + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + in case the given directory does not exists. + + + + + + Example: + + + C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A collection of piano instruments in various format.'" + S: "OK" + + +
+ +
+ The front-end can search for directories + in specific directory by sending the following command: + + + FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] <dir> <criteria-list> + + + Where <dir> should be replaced by the absolute path + name of the directory to search in. If NON_RECURSIVE is specified, the + directories located in subdirectories of the specified directory will not + be searched. <criteria-list> is a list of search criterias + in form of "key1=val1 key2=val2 ...". The following criterias are + allowed: + + NAME='<search-string>' + + Restricts the search to directories, which names + satisfy the supplied search string. + + + + CREATED='[<date-after>]..[<date-before>]' + + Restricts the search to directories, which creation + date satisfies the specified period, where <date-after> + and <date-before> are in "YYYY-MM-DD HH:MM:SS" format. + If <date-after> is omitted the search is restricted to + directories created before <date-before>. If + <date-before> is omitted, the search is restricted + to directories created after <date-after>. + + + + MODIFIED='[<date-after>]..[<date-before>]' + + Restricts the search to directories, which + date of last modification satisfies the specified period, where + <date-after> and <date-before> are in "YYYY-MM-DD HH:MM:SS" + format. If <date-after> is omitted the search is restricted to + directories, which are last modified before <date-before>. If + <date-before> is omitted, the search is restricted to directories, + which are last modified after <date-after>. + + + + DESCRIPTION='<search-string>' + + Restricts the search to directories with description + that satisfies the supplied search string. + + + + + Where <search-string> is either a regular expression, or a + word list separated with spaces for OR search and with '+' for AND search. + + Possible Answers: + + + A comma separated list with the absolute path names (encapsulated into + apostrophes) of all directories in the specified directory that satisfy + the supplied search criterias. + "ERR:<error-code>:<error-message>" - + + if the given directory does not exist. + + + + + Example: + + + C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'" + S: "'/Piano Collection'" + + + + + C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:30:13'" + S: "'/Piano Collection','/Percussions'" + + +
+ +
+ The front-end can add one or more instruments + to the instruments database by sending the following command: + + + ADD DB_INSTRUMENTS [NON_MODAL] [<mode>] <db_dir> <file_path> [<instr_index>] + + + Where <db_dir> is the absolute path name of a directory + (encapsulated into apostrophes) in the instruments database in which + only the new instruments (that are not already in the database) will + be added, <file_path> is the absolute path name of a file or + directory in the file system (encapsulated into apostrophes). In case + an instrument file is supplied, only the instruments in the specified + file will be added to the instruments database. If the optional + <instr_index> (the index of the instrument within the given file) + is supplied too, then only the specified instrument will be added. + In case a directory is supplied, the instruments in that directory + will be added. The OPTIONAL <mode> argument is only applied + when a directory is provided as <file_path> and specifies how the + 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 + will be added, the instruments in the subdirectories + will not be processed. + + + "FLAT" - + + All instruments will be processed, including those + in the subdirectories, but the respective subdirectory + structure will not be recreated in the instruments + database. All instruments will be added directly in + the specified database directory. + + + + + + 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 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>" - + + if an invalid path is specified. + + + + + + Examples: + + + C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI Bosendorfer 290.gig' 0" + S: "OK" + + +
+ +
+ The front-end can remove a particular instrument + from the instruments database by sending the following command: + + + REMOVE DB_INSTRUMENT <instr_path> + + + Where <instr_path> is the absolute path name + (in the instruments database) of the instrument to remove. + + Possible Answers: + + + "OK" - + + if the instrument is removed successfully + + + "ERR:<error-code>:<error-message>" - + + if the given path does not exist or + is a directory. + + + + + + Examples: + + + C: "REMOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'" + S: "OK" + + +
+ +
+ The front-end can retrieve the current amount of + instruments in a specific directory by sending the following command: + + + GET DB_INSTRUMENTS [RECURSIVE] <dir> + + + Where <dir> should be replaced by the absolute path name + of the directory. If RECURSIVE is specified, the number of all + instruments, including those located in subdirectories of the + specified directory, will be returned. + + Possible Answers: + + + The current number of instruments + in the specified directory. + "ERR:<error-code>:<error-message>" - + + if the given directory does not exist. + + + + + + Example: + + + C: "GET DB_INSTRUMENTS '/Piano Collection'" + S: "2" + + +
+ +
+ The front-end can retrieve the current list of instruments + in specific directory by sending the following command: + + + LIST DB_INSTRUMENTS [RECURSIVE] <dir> + + + Where <dir> should be replaced by the absolute path + name of the directory. If RECURSIVE is specified, the absolute path + names of all instruments, including those located in subdirectories + of the specified directory, will be returned. + + Possible Answers: + + + A comma separated list of all instruments + (encapsulated into apostrophes) in the specified directory. + "ERR:<error-code>:<error-message>" - + + if the given directory does not exist. + + + + + Example: + + + C: "LIST DB_INSTRUMENTS '/Piano Collection'" + S: "'Bosendorfer 290','Steinway D'" + + + + + C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'" + S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D','/Piano Collection/Lite/Free Piano'" + + +
+ +
+ The front-end can ask for the current settings of an + instrument by sending the following command: + + + GET DB_INSTRUMENT INFO <instr_path> + + + Where <instr_path> should be replaced by the absolute path + name of the instrument 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: + + + + INSTRUMENT_FILE - + + File name of the instrument. + + + INSTRUMENT_NR - + + Index of the instrument within the file. + + + FORMAT_FAMILY - + + The format family of the instrument. + + + FORMAT_VERSION - + + The format version of the instrument. + + + SIZE - + + The size of the instrument in bytes. + + + CREATED - + + The date and time when the instrument is added + in the instruments database, represented in + "YYYY-MM-DD HH:MM:SS" format + + + MODIFIED - + + The date and time of the last modification of the + instrument's database settings, represented in + "YYYY-MM-DD HH:MM:SS" format + + + DESCRIPTION - + + A brief description of the instrument + + + IS_DRUM - + + either true or false, determines whether the + instrument is a drumkit or a chromatic instrument + + + PRODUCT - + + The product title of the instrument + + + ARTISTS - + + Lists the artist names + + + KEYWORDS - + + Provides a list of keywords that refer to the instrument. + Keywords are separated with semicolon and blank. + + + + + + + The mentioned fields above don't have to be in particular order. + + Example: + + + C: "GET DB_INSTRUMENT INFO '/Piano Collection/Bosendorfer 290'" + S: "INSTRUMENT_FILE: /home/me/gigs/Bosendorfer 290.gig" +    "INSTRUMENT_NR: 0" +    "FORMAT_FAMILY: GIG" +    "FORMAT_VERSION: 2" +    "SIZE: 2050871870" +    "CREATED: 2007-02-05 10:23:12" +    "MODIFIED: 2007-04-07 12:50:21" +    "DESCRIPTION: " +    "IS_DRUM: false" +    "PRODUCT: GRANDIOSO Bosendorfer 290" +    "ARTISTS: Post Musical Instruments" +    "KEYWORDS: Bosendorfer" +    "." + + +
+ +
+ The front-end can alter the name of a specific + instrument by sending the following command: + + + SET DB_INSTRUMENT NAME <instr> <name> + + + Where <instr> is the absolute path name of the instrument and + <name> is the new name for that instrument. + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + in case the given instrument does not exists, + or if an instrument with name equal to the new + name already exists. + + + + + + Example: + + + C: "SET DB_INSTRUMENT NAME '/Piano Collection/Bosendorfer' 'Bosendorfer 290'" + S: "OK" + + +
+ +
+ The front-end can move a specific instrument to another directory by + sending the following command: + + + MOVE DB_INSTRUMENT <instr> <dst> + + + Where <instr> is the absolute path name of the instrument + to move and <dst> is the directory where the instrument will + be moved to. + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + in case the given instrument does not exists, + or if an instrument with name equal to the name of the + specified instrument already exists in the destination + directory. + + + + + + Example: + + + C: "MOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Piano Collection/Acoustic'" + S: "OK" + + +
+ +
+ The front-end can copy a specific instrument to another directory by + sending the following command: + + + COPY DB_INSTRUMENT <instr> <dst> + + + Where <instr> is the absolute path name of the instrument + to copy and <dst> is the directory where the instrument will + be copied to. + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + in case the given instrument does not exists, + or if an instrument with name equal to the name of the + specified instrument already exists in the destination + directory. + + + + + + Example: + + + C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Acoustic/Pianos/'" + S: "OK" + + +
+ +
+ The front-end can alter the description of a specific + instrument by sending the following command: + + + SET DB_INSTRUMENT DESCRIPTION <instr> <desc> + + + Where <instr> is the absolute path name of the instrument and + <desc> is the new description for the instrument. + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + in case the given instrument does not exists. + + + + + + Example: + + + C: "SET DB_INSTRUMENT DESCRIPTION '/Piano Collection/Acoustic/Bosendorfer 290' 'No comment :)'" + S: "OK" + + +
+ +
+ The front-end can search for instruments + in specific directory by sending the following command: + + + FIND DB_INSTRUMENTS [NON_RECURSIVE] <dir> <criteria-list> + + + Where <dir> should be replaced by the absolute path + name of the directory to search in. If NON_RECURSIVE is specified, the + directories located in subdirectories of the specified directory will not + be searched. <criteria-list> is a list of search criterias + in form of "key1=val1 key2=val2 ...". The following criterias are + allowed: + + NAME='<search-string>' + + Restricts the search to instruments, which names + satisfy the supplied search string. + + + + SIZE=[<min>]..[<max>] + + 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 + search is restricted to instruments with size greater then + or equal to <min>. + + + + CREATED='[<date-after>]..[<date-before>]' + + Restricts the search to instruments, which creation + date satisfies the specified period, where <date-after> + and <date-before> are in "YYYY-MM-DD HH:MM:SS" format. + If <date-after> is omitted the search is restricted to + instruments created before <date-before>. If + <date-before> is omitted, the search is restricted + to instruments created after <date-after>. + + + + MODIFIED='[<date-after>]..[<date-before>]' + + Restricts the search to instruments, which + date of last modification satisfies the specified period, where + <date-after> and <date-before> are in "YYYY-MM-DD HH:MM:SS" + format. If <date-after> is omitted the search is restricted to + instruments, which are last modified before <date-before>. If + <date-before> is omitted, the search is restricted to instruments, + which are last modified after <date-after>. + + + + DESCRIPTION='<search-string>' + + Restricts the search to instruments with description + that satisfies the supplied search string. + + + + PRODUCT='<search-string>' + + Restricts the search to instruments with product info + that satisfies the supplied search string. + + + + ARTISTS='<search-string>' + + Restricts the search to instruments with artists info + that satisfies the supplied search string. + + + + KEYWORDS='<search-string>' + + Restricts the search to instruments with keyword list + that satisfies the supplied search string. + + + + IS_DRUM=true | false + + Either true or false. Restricts the search to + drum kits or chromatic instruments. + + + + FORMAT_FAMILIES='<format-list>' + + Restricts the search to instruments of the supplied format families, + where <format-list> is a comma separated list of format families. + + + + + Where <search-string> is either a regular expression, or a + word list separated with spaces for OR search and with '+' for AND search. + + Possible Answers: + + + A comma separated list with the absolute path names (encapsulated into + apostrophes) of all instruments in the specified directory that satisfy + the supplied search criterias. + "ERR:<error-code>:<error-message>" - + + if the given directory does not exist. + + + + + Example: + + + C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+290'" + S: "'/Piano Collection/Bosendorfer 290'" + + + + + C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01 09:30:13..'" + S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D'" + + +
+ +
+ 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" +    "." + + +
+ +
+ @@ -4808,12 +5947,18 @@ / UNSUBSCRIBE SP unsubscribe_event - / SELECT SP text - / RESET SP reset_instruction / CLEAR SP clear_instruction + / FIND SP find_instruction + + / MOVE SP move_instruction + + / COPY SP copy_instruction + + / EDIT SP edit_instruction + / RESET / QUIT @@ -4824,6 +5969,20 @@ CHANNEL + / DB_INSTRUMENT_DIRECTORY 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_MODAL SP pathname SP pathname + + / DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname SP instrument_index + + / DB_INSTRUMENTS SP pathname SP pathname + + / DB_INSTRUMENTS SP pathname SP pathname SP instrument_index + / MIDI_INSTRUMENT_MAP / MIDI_INSTRUMENT_MAP SP map_name @@ -4862,6 +6021,16 @@ / MIDI_INSTRUMENT_INFO + / DB_INSTRUMENT_DIRECTORY_COUNT + + / DB_INSTRUMENT_DIRECTORY_INFO + + / DB_INSTRUMENT_COUNT + + / DB_INSTRUMENT_INFO + + / DB_INSTRUMENTS_JOB_INFO + / MISCELLANEOUS / TOTAL_VOICE_COUNT @@ -4902,6 +6071,16 @@ / MIDI_INSTRUMENT_INFO + / DB_INSTRUMENT_DIRECTORY_COUNT + + / DB_INSTRUMENT_DIRECTORY_INFO + + / DB_INSTRUMENT_COUNT + + / DB_INSTRUMENT_INFO + + / DB_INSTRUMENTS_JOB_INFO + / MISCELLANEOUS / TOTAL_VOICE_COUNT @@ -4936,6 +6115,12 @@ / MIDI_INSTRUMENT_MAP SP ALL + / DB_INSTRUMENT_DIRECTORY SP FORCE SP pathname + + / DB_INSTRUMENT_DIRECTORY SP pathname + + / DB_INSTRUMENT SP pathname + get_instruction = @@ -5006,6 +6191,20 @@ / FX_SEND SP INFO SP sampler_channel SP fx_send_id + / DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname + + / DB_INSTRUMENT_DIRECTORIES SP pathname + + / DB_INSTRUMENT_DIRECTORY SP INFO SP pathname + + / DB_INSTRUMENTS SP RECURSIVE SP pathname + + / DB_INSTRUMENTS SP pathname + + / DB_INSTRUMENT SP INFO SP pathname + + / DB_INSTRUMENTS_JOB SP INFO SP number + / VOLUME @@ -5032,6 +6231,14 @@ / 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 DESCRIPTION SP pathname SP stringval + + / DB_INSTRUMENT SP NAME SP pathname SP dirname + + / DB_INSTRUMENT SP DESCRIPTION SP pathname SP stringval + / ECHO SP boolean / VOLUME SP volume_value @@ -5068,6 +6275,34 @@ +find_instruction = + + DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP query_val_list + + / DB_INSTRUMENTS SP pathname SP query_val_list + + / DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP pathname SP query_val_list + + / DB_INSTRUMENT_DIRECTORIES SP pathname SP query_val_list + + + +move_instruction = + + DB_INSTRUMENT_DIRECTORY SP pathname SP pathname + + / DB_INSTRUMENT SP pathname SP pathname + + + +copy_instruction = + + DB_INSTRUMENT_DIRECTORY SP pathname SP pathname + + / DB_INSTRUMENT SP pathname SP pathname + + + destroy_instruction = AUDIO_OUTPUT_DEVICE SP number @@ -5118,6 +6353,12 @@ +edit_instruction = + + INSTRUMENT SP sampler_channel + + + modal_arg = /* epsilon (empty argument) */ @@ -5164,6 +6405,14 @@ / FX_SENDS SP sampler_channel + / DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname + + / DB_INSTRUMENT_DIRECTORIES SP pathname + + / DB_INSTRUMENTS SP RECURSIVE SP pathname + + / DB_INSTRUMENTS SP pathname + load_instr_args = @@ -5284,12 +6533,24 @@ -filename = +pathname = + + stringval + + + +dirname = stringval +filename = + + stringval_escaped + + + map_name = stringval @@ -5328,8 +6589,66 @@ +query_val_list = + + string '=' query_val + + / query_val_list SP string '=' query_val + + + +query_val = + + string + + / stringval + + + +scan_mode = + + RECURSIVE + + / NON_RECURSIVE + + / FLAT + + + + +
+ Older versions of this protocol up to and including v1.2 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.2 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. +
@@ -5515,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: @@ -5671,6 +6990,132 @@
+
+ Client may want to be notified when the number of instrument + directories in a particular directory in the instruments database + is changed by issuing the following command: + + + SUBSCRIBE DB_INSTRUMENT_DIRECTORY_COUNT + + + Server will start sending the following notification messages: + + + "NOTIFY:DB_INSTRUMENT_DIRECTORY_COUNT:<dir-path>" + + + where <dir-path> will be replaced by the absolute path + name of the directory in the instruments database, + in which the number of directories is changed. + Note that when a non-empty directory is removed, this event + is not sent for the subdirectories in that directory. +
+ +
+ Client may want to be notified when changes were made to directories + in the instruments database by issuing the following command: + + + SUBSCRIBE DB_INSTRUMENT_DIRECTORY_INFO + + + Server will start sending the following notification messages: + + + "NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:<dir-path>" + + + where <dir-path> will be replaced by the absolute path name + of the directory, for which information changes occurred. The front-end will have to send + the respective command to actually get the updated directory 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. + + + "NOTIFY:DB_INSTRUMENT_DIRECTORY_INFO:NAME <old-dir-path> <new-name>" + + + where <old-dir-path> is the old absolute path name of the directory + (encapsulated into apostrophes), which name is changes and <new-name> is + the new name of the directory, encapsulated into apostrophes. +
+ +
+ Client may want to be notified when the number of instruments + in a particular directory in the instruments database + is changed by issuing the following command: + + + SUBSCRIBE DB_INSTRUMENT_COUNT + + + Server will start sending the following notification messages: + + + "NOTIFY:DB_INSTRUMENT_COUNT:<dir-path>" + + + where <dir-path> will be replaced by the absolute path + name of the directory in the instruments database, + in which the number of instruments is changed. + Note that when a non-empty directory is removed, this event + is not sent for the instruments in that directory. +
+ +
+ Client may want to be notified when changes were made to instruments + in the instruments database by issuing the following command: + + + SUBSCRIBE DB_INSTRUMENT_INFO + + + Server will start sending the following notification messages: + + + "NOTIFY:DB_INSTRUMENT_INFO:<instr-path>" + + + where <instr-path> will be replaced by the absolute path name + of the instrument, which settings are changed. The front-end will have to send + the respective command to actually get the updated directory 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. + + + "NOTIFY:DB_INSTRUMENT_INFO:NAME <old-instr-path> <new-name>" + + + where <old-instr-path> is the old absolute path name of the instrument + (encapsulated into apostrophes), which name is changes and <new-name> is + 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: @@ -5749,6 +7194,16 @@ + + + ASCII format for Network Interchange + + UCLA + + + + +