@@ -173,11 +173,11 @@ The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.
-This Internet-Draft will expire on August 23, 2007.
+This Internet-Draft will expire on March 4, 2008.-Copyright © The Internet Society (2007).
+Copyright © The IETF Trust (2007).@@ -3237,7 +3307,8 @@ or "LIST MIDI_INPUT_DEVICES" (Getting all created MIDI input device list) command, <port> by the MIDI port number, <key> by the name of the parameter to change and <value> by the new value for this - parameter. + parameter (encapsulated into apostrophes) or NONE (not encapsulated into apostrophes) + for specifying no value for parameters allowing a list of values.
Possible Answers:
@@ -3278,7 +3349,19 @@
+C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='20:0'" +
+S: "OK" +
+
+ +
+
++C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE" +
+S: "OK"
@@ -3313,6 +3396,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 (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 @@ -5327,9 +5416,70 @@
-
| TOC |
The front-end can alter the current name of an effect + send entity by sending the following command: +
++
++SET FX_SEND NAME <sampler-chan> <fx-send-id> <name> +
+
+ +
+Where <sampler-chan> is the sampler channel number + as returned by the "ADD CHANNEL" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) command, + <fx-send-id> reflects the numerical ID of the effect send entity + as returned by the "CREATE FX_SEND" (Adding an effect send to a sampler channel) + or "LIST FX_SENDS" (Listing all effect sends on a sampler channel) command and + <name> is the new name of the effect send entity, which + does not have to be unique. +
+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 FX_SEND NAME 0 0 'Fx Send 1'" +
+S: "OK" +
+
+ +
+| TOC |
The front-end can alter the destination of an effect send's audio channel on a specific @@ -5412,7 +5562,7 @@
| TOC |
The front-end can alter the MIDI controller of an effect @@ -5483,7 +5633,7 @@
| TOC |
The front-end can alter the current send level of an effect @@ -5555,7 +5705,7 @@
| TOC |
The front-end can reset a particular sampler channel by sending the following command: @@ -5987,6 +6137,15 @@ +
INSTRUMENTS_DB_SUPPORT - +
+++ + @@ -6398,6 +6557,15 @@ +either yes or no, specifies whether the + sampler is build with instruments database support. +
+
DEFAULT - +
+++ + @@ -6415,6 +6583,8 @@either true or false, + defines whether this map is the default map +
+
S: "NAME: Standard Map"
+"DEFAULT: true" +
"."
@@ -6504,7 +6674,9 @@ index, <engine_name> a sampler engine name as returned by the "LIST AVAILABLE_ENGINES" (Getting all 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 (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 @@ -7086,6 +7258,1868 @@
+
| TOC |
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 (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. + +
+
+ +
+| TOC |
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" +
+
+ +
+| TOC |
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" +
+
+ +
+| TOC |
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" +
+
+ +
+| TOC |
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'" +
+
+ +
+| TOC |
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. + Note that the character string may contain + escape sequences (Character Set and Escape Sequences). +
+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" +
+"." +
+
+ +
+| TOC |
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" +
+
+ +
+| TOC |
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" +
+
+ +
+| TOC |
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" +
+
+ +
+| TOC |
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 + (encapsulated into apostrophes, supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)"). +
+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" +
+
+ +
+| TOC |
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 (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)"). +
+
+ +
+ + +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 + (encapsulated into apostrophes, supporting escape + sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)"). +
+
+ +
+ + +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'" +
+
+ +
+| TOC |
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 (Getting job status information) + 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 (Getting job status information) + +
+"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" +
+
+ +
+| TOC |
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" +
+
+ +
+| TOC |
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" +
+
+ +
+| TOC |
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'" +
+
+ +
+| TOC |
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. + Note that the character string may contain + escape sequences (Character Set and Escape Sequences). +
+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. + Note that the character string may contain + escape sequences (Character Set and Escape Sequences). +
+IS_DRUM - +
+++ + +either true or false, determines whether the + instrument is a drumkit or a chromatic instrument +
+PRODUCT - +
+++ + +The product title of the instrument. + Note that the character string may contain + escape sequences (Character Set and Escape Sequences). +
+ARTISTS - +
+++ + +Lists the artist names. + Note that the character string may contain + escape sequences (Character Set and Escape Sequences). +
+KEYWORDS - +
+++ + +Provides a list of keywords that refer to the instrument. + Keywords are separated with semicolon and blank. + Note that the character string may contain + escape sequences (Character Set and Escape Sequences). +
+
+ +
+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" +
+"." +
+
+ +
+| TOC |
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" +
+
+ +
+| TOC |
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" +
+
+ +
+| TOC |
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" +
+
+ +
+| TOC |
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 + (encapsulated into apostrophes, supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)"). +
+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" +
+
+ +
+| TOC |
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 (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)"). +
+
+ +
+ + +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 (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)"). +
+
+ +
+ + +PRODUCT='<search-string>' +
++Restricts the search to instruments with product info + that satisfies the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)"). +
+
+ +
+ + +ARTISTS='<search-string>' +
++Restricts the search to instruments with artists info + that satisfies the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)"). +
+
+ +
+ + +KEYWORDS='<search-string>' +
++Restricts the search to instruments with keyword list + that satisfies the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)"). +
+
+ +
+ + +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'" +
+
+ +
+| TOC |
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" +
+"." +
+
+ +
+| TOC |
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. +
+
+ +
+| TOC |
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. +
+| TOC |
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" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) + 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" +
+
+ +
| TOC |
/ 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 + +
+/ FORMAT SP format_instruction + +
/ RESET
@@ -7210,6 +9256,27 @@CHANNEL
+/ DB_INSTRUMENT_DIRECTORY SP db_path + +
+/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename + +
+/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename + +
+/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename + +
+/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index + +
+/ DB_INSTRUMENTS SP db_path SP filename + +
+/ DB_INSTRUMENTS SP db_path SP filename SP instrument_index + +
/ MIDI_INSTRUMENT_MAP
@@ -7249,6 +9316,12 @@/ CHANNEL_INFO
+/ FX_SEND_COUNT + +
+/ FX_SEND_INFO + +
/ MIDI_INSTRUMENT_MAP_COUNT
@@ -7261,12 +9334,30 @@/ 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
+/ GLOBAL_INFO + +
@@ -7300,6 +9391,12 @@
/ CHANNEL_INFO
+/ FX_SEND_COUNT + +
+/ FX_SEND_INFO + +
/ MIDI_INSTRUMENT_MAP_COUNT
@@ -7312,12 +9409,30 @@/ 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
+/ GLOBAL_INFO + +
@@ -7360,6 +9475,15 @@
/ MIDI_INSTRUMENT_MAP SP ALL
+/ DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path + +
+/ DB_INSTRUMENT_DIRECTORY SP db_path + +
+/ DB_INSTRUMENT SP db_path + +
@@ -7465,6 +9589,27 @@
/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
+/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path + +
+/ DB_INSTRUMENT_DIRECTORIES SP db_path + +
+/ DB_INSTRUMENT_DIRECTORY SP INFO SP db_path + +
+/ DB_INSTRUMENTS SP RECURSIVE SP db_path + +
+/ DB_INSTRUMENTS SP db_path + +
+/ DB_INSTRUMENT SP INFO SP db_path + +
+/ DB_INSTRUMENTS_JOB SP INFO SP number + +
/ VOLUME
@@ -7483,6 +9628,9 @@/ 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
@@ -7492,6 +9640,9 @@/ MIDI_INSTRUMENT_MAP SP NAME SP midi_map SP map_name
+/ FX_SEND SP NAME SP sampler_channel SP fx_send_id SP fx_send_name + +
/ FX_SEND SP AUDIO_OUTPUT_CHANNEL SP sampler_channel SP fx_send_id SP audio_channel_index SP audio_channel_index
@@ -7501,6 +9652,18 @@/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
+/ DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped + +
+/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped + +
+/ DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped + +
+/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped + +
/ ECHO SP boolean
@@ -7555,6 +9718,48 @@+
find_instruction = +
++DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list + +
+/ DB_INSTRUMENTS SP db_path SP query_val_list + +
+/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP query_val_list + +
+/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list + +
+
+ +
+move_instruction = +
++DB_INSTRUMENT_DIRECTORY SP db_path SP db_path + +
+/ DB_INSTRUMENT SP db_path SP db_path + +
+
+ +
+copy_instruction = +
++DB_INSTRUMENT_DIRECTORY SP db_path SP db_path + +
+/ DB_INSTRUMENT SP db_path SP db_path + +
+
+ +
destroy_instruction =
@@ -7630,6 +9835,24 @@
+
edit_instruction = +
++INSTRUMENT SP sampler_channel + +
+
+ +
+format_instruction = +
++INSTRUMENTS_DB + +
+
+ +
modal_arg =
@@ -7699,6 +9922,18 @@/ FX_SENDS SP sampler_channel
+/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path + +
+/ DB_INSTRUMENT_DIRECTORIES SP db_path + +
+/ DB_INSTRUMENTS SP RECURSIVE SP db_path + +
+/ DB_INSTRUMENTS SP db_path + +
@@ -7882,7 +10117,16 @@
filename =
-stringval +
path + +
+
+ +
+db_path = +
++path
@@ -7945,6 +10189,111 @@
+
query_val_list = +
++string '=' query_val + +
+/ query_val_list SP string '=' query_val + +
+
+ +
+query_val = +
++textval_escaped + +
+/ stringval_escaped + +
+
+ +
+scan_mode = +
++RECURSIVE + +
+/ NON_RECURSIVE + +
+/ FLAT + +
+
+ +
+| TOC |
Older versions of this protocol up to and including v1.1 only + supported the standard ASCII character set (ASCII code 0 - 127) + [RFC20] (UCLA, “ASCII format for Network Interchange,” 1969.), 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. +
| TOC |
-"NOTIFY:VOICE_COUNT:<sampler-channel> <voices> +
"NOTIFY:VOICE_COUNT:<sampler-channel> <voices>"
@@ -8229,9 +10578,69 @@ time events happening on the server, it is believed that an empty notification message is sufficient here.
-| TOC |
Client may want to be notified when the number of effect sends on + a particular sampler channel is changed by issuing the following command: +
++
++SUBSCRIBE FX_SEND_COUNT +
+
+ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:FX_SEND_COUNT:<channel-id> <fx-sends>" +
+
+ +
+where <channel-id> will be replaced by the numerical ID of the sampler + channel, on which the effect sends number is changed and <fx-sends> will + be replaced by the new number of effect sends on that channel. +
+| TOC |
Client may want to be notified when changes were made to effect sends on a + a particular sampler channel by issuing the following command: +
++
++SUBSCRIBE FX_SEND_INFO +
+
+ +
+Server will start sending the following notification messages: +
++
++"NOTIFY:FX_SEND_INFO:<channel-id> <fx-send-id>" +
+
+ +
+where <channel-id> will be replaced by the numerical ID of the sampler + channel, on which an effect send entity is changed and <fx-send-id> will + be replaced by the numerical ID of the changed effect send. +
+| TOC |
Client may want to be notified when the total number of voices on the @@ -8250,7 +10659,7 @@
-"NOTIFY:TOTAL_VOICE_COUNT:<voices> +
"NOTIFY:TOTAL_VOICE_COUNT:<voices>"
@@ -8260,7 +10669,7 @@
| TOC |
Client may want to be notified when the number of MIDI instrument maps on the @@ -8289,7 +10698,7 @@
| TOC |
Client may want to be notified when changes were made to MIDI instrument maps on the @@ -8322,7 +10731,7 @@
| TOC |
Client may want to be notified when the number of MIDI instrument maps on the @@ -8352,7 +10761,7 @@
| TOC |
Client may want to be notified when changes were made to MIDI instruments on the @@ -8384,9 +10793,229 @@ time events happening on the server, it is believed that an empty notification message is sufficient here.
+| TOC |
Client may want to be notified when changes to the global settings + of the sampler were made by issuing the following command: +
++
++SUBSCRIBE GLOBAL_INFO +
+
+ +
+Server will start sending the following types of notification messages: +
++
++"NOTIFY:GLOBAL_INFO:VOLUME <volume>" - Notifies that the + golbal volume of the sampler is changed, where <volume> will be + replaced by the optional dotted floating point value, reflecting the + new global volume parameter. +
+
+ +
+| TOC |
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. +
+| TOC |
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. +
+| TOC |
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. +
+| TOC |
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. +
+| TOC |
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. +
| TOC |
Client may want to be notified of miscellaneous and debugging events occurring at @@ -8451,6 +11080,8 @@
| TOC |
| [RFC20] | +UCLA, “ASCII format for Network Interchange,” RFC 20, 1969. |
| [RFC2119] | Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” RFC 2119, 1997. |
| [RFC2234] | @@ -8481,7 +11112,7 @@
| TOC |
-Copyright © The Internet Society (2007).
+Copyright © The IETF Trust (2007).This document is subject to the rights, licenses and restrictions contained in BCP 78, @@ -8490,13 +11121,13 @@
This document and the information contained herein are provided on an “AS IS” basis and THE CONTRIBUTOR, -THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), -THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM -ALL WARRANTIES, -EXPRESS OR IMPLIED, -INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE -INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED -WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+THE ORGANIZATION HE/SHE REPRESENTS +OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST +AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT +THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY +IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR +PURPOSE.The IETF takes no position regarding the validity or scope of any @@ -8528,3 +11159,4 @@ Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA).
+