--- linuxsampler/trunk/Documentation/lscp.xml 2006/12/27 16:17:08 1001 +++ linuxsampler/trunk/Documentation/lscp.xml 2008/09/30 02:16:41 1782 @@ -16,7 +16,7 @@ to an annoying "missing Normative/Informative References" error message --> - + LinuxSampler Control Protocol + S: "OK" + + + + + C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE" + S: "OK" @@ -2113,6 +2121,12 @@ number of the sampler channel the instrument should be assigned to. Each sampler channel can only have one instrument. + Notice: since LSCP 1.2 the <filename> argument supports + escape characters for special characters (see chapter + "Character Set and Escape Sequences" + for details) and accordingly backslash characters in the filename + MUST now be escaped as well! + The difference between regular and NON_MODAL versions of the command is that the regular command returns OK only after the instrument has been fully loaded and the channel is ready to be used while NON_MODAL version @@ -2148,10 +2162,18 @@ - Example: + Example (Unix): - + C: LOAD INSTRUMENT '/home/joe/gigs/cello.gig' 0 0 + S: OK + + + Example (Windows): + + + C: LOAD INSTRUMENT 'D:/MySounds/cello.gig' 0 0 + S: OK @@ -2429,7 +2451,9 @@ DESCRIPTION - - arbitrary description text about the engine + arbitrary description text about the engine + (note that the character string may contain + escape sequences) VERSION - @@ -2513,7 +2537,8 @@ the file name of the loaded instrument, "NONE" if there's no instrument yet loaded for this sampler - channel + channel (note: since LSCP 1.2 this path may contain + escape sequences) INSTRUMENT_NR - @@ -2523,7 +2548,9 @@ INSTRUMENT_NAME - - the instrument name of the loaded instrument + the instrument name of the loaded instrument + (note: since LSCP 1.2 this character string may contain + escape sequences) INSTRUMENT_STATUS - @@ -2555,7 +2582,7 @@ VOLUME - optionally dotted number for the channel volume factor - (where a value < 1.0 means attenuation and a value > + (where a value < 1.0 means attenuation and a value > 1.0 means amplification) @@ -3241,7 +3268,9 @@ sampler channel on which the effect send should be created on, <midi-ctrl> is a number between 0..127 defining the MIDI controller which can alter the effect send level and <name> is an optional argument defining a name - for the effect send entity. The name does not have to be unique. + for the effect send entity. The name does not have to be unique, but MUST be + encapsulated into apostrophes and supports escape sequences as described in chapter + "Character Set and Escape Sequences". By default, that is as initial routing, the effect send's audio channels are automatically routed to the last audio channels of the sampler channel's @@ -3287,7 +3316,7 @@ S: "OK[0]" - + C: "CREATE FX_SEND 0 93" S: "OK[1]" @@ -3431,7 +3460,22 @@ NAME - - name of the effect send entity + name of the effect send entity + (note that this character string may contain + escape sequences) + + + MIDI_CONTROLLER - + + a value between 0 and 127 reflecting the MIDI controller + which is able to modify the effect send's send level + + + LEVEL - + + optionally dotted number reflecting the effect send's + current send level (where a value < 1.0 means attenuation + and a value > 1.0 means amplification) AUDIO_OUTPUT_ROUTING - @@ -3458,12 +3502,58 @@ C: "GET FX_SEND INFO 0 0" S: "NAME: Reverb Send" +    "MIDI_CONTROLLER: 91" +    "LEVEL: 0.3"    "AUDIO_OUTPUT_ROUTING: 2,3"    "." +
+ 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" + or "LIST CHANNELS" command, + <fx-send-id> reflects the numerical ID of the effect send entity + as returned by the "CREATE FX_SEND" + or "LIST FX_SENDS" command and + <name> is the new name of the effect send entity, which + does not have to be unique (name MUST be encapsulated into apostrophes + and supports escape sequences as described in chapter + "Character Set and Escape Sequences"). + + + 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" + + +
+
The front-end can alter the destination of an effect send's audio channel on a specific sampler channel by sending the following command: @@ -3524,6 +3614,159 @@
+
+ The front-end can alter the MIDI controller of an effect + send entity by sending the following command: + + + SET FX_SEND MIDI_CONTROLLER <sampler-chan> <fx-send-id> <midi-ctrl> + + + Where <sampler-chan> is the sampler channel number + as returned by the "ADD CHANNEL" + or "LIST CHANNELS" command, + <fx-send-id> reflects the numerical ID of the effect send entity + as returned by the "CREATE FX_SEND" + or "LIST FX_SENDS" command and + <midi-ctrl> reflects the MIDI controller which shall be + able to modify the effect send's send level. + + Possible Answers: + + + "OK" - + + on success + + + "WRN:<warning-code>:<warning-message>" - + + if MIDI controller was set, but there are noteworthy + issue(s) related, providing an appropriate warning code and + warning message + + + "ERR:<error-code>:<error-message>" - + + in case it failed, providing an appropriate error code and error message + + + + + Example: + + + C: "SET FX_SEND MIDI_CONTROLLER 0 0 91" + S: "OK" + + +
+ +
+ The front-end can alter the current send level of an effect + send entity by sending the following command: + + + SET FX_SEND LEVEL <sampler-chan> <fx-send-id> <volume> + + + Where <sampler-chan> is the sampler channel number + as returned by the "ADD CHANNEL" + or "LIST CHANNELS" command, + <fx-send-id> reflects the numerical ID of the effect send entity + as returned by the "CREATE FX_SEND" + or "LIST FX_SENDS" command and + <volume> is an optionally dotted positive number (a value + smaller than 1.0 means attenuation, whereas a value greater than + 1.0 means amplification) reflecting the new send level. + + Possible Answers: + + + "OK" - + + on success + + + "WRN:<warning-code>:<warning-message>" - + + if new send level was set, but there are noteworthy + issue(s) related, providing an appropriate warning code and + warning message + + + "ERR:<error-code>:<error-message>" - + + in case it failed, providing an appropriate error code and error message + + + + + Example: + + + C: "SET FX_SEND LEVEL 0 0 0.15" + S: "OK" + + +
+ +
+ The front-end can send MIDI events to specific sampler channel + by sending the following command: + + + SEND CHANNEL MIDI_DATA <midi-msg> <sampler-chan> <arg1> <arg2> + + + Where <sampler-chan> is the sampler channel number + as returned by the "ADD CHANNEL" + or "LIST CHANNELS" command, + <arg1> and <arg2> arguments depend on the <midi-msg> argument, which + specifies the MIDI message type. Currently, the following MIDI messages are supported: + + + "NOTE_ON" - + + For turning on MIDI notes, where <arg1> + specifies the key number and <arg2> the velocity + as described in the MIDI specification. + + + "NOTE_OFF" - + + For turning a currently playing MIDI note off, where <arg1> + specifies the key number and <arg2> the velocity + as described in the MIDI specification. + + + + + CAUTION: This command is provided for implementations of virtual MIDI keyboards + and no realtime guarantee whatsoever will be made! + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + in case it failed, providing an appropriate error code and error message + + + + + Example: + + + C: "SEND CHANNEL MIDI_DATA NOTE_ON 0 56 112" + S: "OK" + + +
The front-end can reset a particular sampler channel by sending the following command: @@ -3746,6 +3989,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: @@ -3793,7 +4054,9 @@ DESCRIPTION - - arbitrary textual description about the sampler + arbitrary textual description about the sampler + (note that the character string may contain + escape sequences) VERSION - @@ -3807,6 +4070,12 @@ complies with (see for details) + INSTRUMENTS_DB_SUPPORT - + + either yes or no, specifies whether the + sampler is build with instruments database support. + + @@ -3814,6 +4083,65 @@ The mentioned fields above don't have to be in particular order. Other fields might be added in future.
+ +
+ The client can ask for the current global sampler-wide volume + attenuation by sending the following command: + + + GET VOLUME + + + Possible Answers: + + + The sampler will always answer by returning the optional + dotted floating point coefficient, reflecting the current + global volume attenuation. + + + + Note: it is up to the respective sampler engine whether to obey + that global volume parameter or not, but in general all engines SHOULD + use this parameter. +
+ +
+ The client can alter the current global sampler-wide volume + attenuation by sending the following command: + + + SET VOLUME <volume> + + + Where <volume> should be replaced by the optional dotted + floating point value, reflecting the new global volume parameter. + This value might usually be in the range between 0.0 and 1.0, that + is for attenuating the overall volume. + + Possible Answers: + + + "OK" - + + on success + + + "WRN:<warning-code>:<warning-message>" - + + if the global volume was set, but there are noteworthy + issue(s) related, providing an appropriate warning code and + warning message + + + "ERR:<error-code>:<error-message>" - + + in case it failed, providing an appropriate error code and error message + + + + +
@@ -3844,7 +4172,7 @@ cause the sampler to switch to the respective instrument as reflected by the current MIDI instrument map. -
+
The front-end can add a new MIDI instrument map by sending the following command: @@ -3854,7 +4182,10 @@ Where <name> is an optional argument allowing to assign a custom name to the new map. MIDI instrument Map - names do not have to be unique. + names do not have to be unique, but MUST be encapsulated + into apostrophes and support escape sequences as described + in chapter "Character Set and Escape Sequences". + Possible Answers: @@ -4025,7 +4356,15 @@ NAME - custom name of the given map, - which does not have to be unique + which does not have to be unique + (note that this character string may contain + escape sequences) + + + DEFAULT - + + either true or false, + defines whether this map is the default map @@ -4039,6 +4378,7 @@ C: "GET MIDI_INSTRUMENT_MAP INFO 0" S: "NAME: Standard Map" +    "DEFAULT: true"    "." @@ -4054,7 +4394,10 @@ Where <map> is the numerical ID of the map and <name> the new custom name of the map, which does not - have to be unique. + have to be unique (name MUST be encapsulated into apostrophes + and supports escape sequences as described in chapter + "Character Set and Escape Sequences"). + Possible Answers: @@ -4087,7 +4430,7 @@ command: - MAP MIDI_INSTRUMENT <map> + MAP MIDI_INSTRUMENT [NON_MODAL] <map> <midi_bank> <midi_prog> <engine_name> <filename> <instrument_index> <volume_value> [<instr_load_mode>] [<name>] @@ -4101,11 +4444,13 @@ 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 - value < 1.0 means attenuation and a value > 1.0 means + value < 1.0 means attenuation and a value > 1.0 means amplification). This parameter easily allows to adjust the volume of all intruments within a custom instrument map without having to adjust their instrument files. The @@ -4140,7 +4485,7 @@ "PERSISTENT" - The instrument will immediately be loaded - into memory in the background when this mapping + into memory when this mapping command is sent and the instrument is kept all the time. Instruments with this mode are only freed when the sampler is reset or all @@ -4183,20 +4528,27 @@ load modes of entries, the frontend should retrieve the actual mode by i.e. sending "GET MIDI_INSTRUMENT INFO" - command(s). Finally the OPTIONAL <name> argument allows to - set a custom name (encapsulated into apostrophes) for the mapping - entry, useful for frontends for displaying an appropriate name for + command(s). Finally the OPTIONAL <name> argument allows to set a custom name + (encapsulated into apostrophes, supporting escape sequences as described in chapter + "Character Set and Escape Sequences") for the + mapping entry, useful for frontends for displaying an appropriate name for mapped instruments (using "GET MIDI_INSTRUMENT INFO"). - The "MAP MIDI_INSTRUMENT" command - will immediately return, thus it will not block when an - instrument is to be loaded due to a "PERSISTENT" type - entry as instruments are loaded in the background. As a - consequence this command may not necessarily return an error - i.e. when the given instrument file does not exist or may - turn out to be corrupt. + By default, "MAP MIDI_INSTRUMENT" commands block until the mapping is + completely established in the sampler. The OPTIONAL "NON_MODAL" argument + however causes the respective "MAP MIDI_INSTRUMENT" command to return + immediately, that is to let the sampler establish the mapping in the + background. So this argument might be especially useful for mappings with + a "PERSISTENT" type, because these have to load the respective instruments + immediately and might thus block for a very long time. It is recommended + however to use the OPTIONAL "NON_MODAL" argument only if really necessary, + because it has the following drawbacks: as "NON_MODAL" instructions return + immediately, they may not necessarily return an error i.e. when the given + instrument file turns out to be corrupt, beside that subsequent commands + in a LSCP instruction sequence might fail, because mandatory mappings are + not yet completed. Possible Answers: @@ -4239,7 +4591,7 @@ - C: "MAP MIDI_INSTRUMENT 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'" + C: "MAP MIDI_INSTRUMENT NON_MODAL 1 8 120 gig '/home/joe/foodrums.gig' 0 1.0 PERSISTENT 'Foo Drumkit'" S: "OK" @@ -4403,7 +4755,9 @@ name for this mapped instrument. It can be set and changed with the "MAP MIDI_INSTRUMENT" - command and does not have to be unique. + command and does not have to be unique. + (note that this character string may contain + escape sequences) "ENGINE_NAME" - @@ -4414,7 +4768,9 @@ "INSTRUMENT_FILE" - - File name of the instrument. + File name of the instrument + (note that this path may contain + escape sequences). "INSTRUMENT_NR" - @@ -4426,7 +4782,8 @@ Name of the loaded instrument as reflected by its file. In contrast to the "NAME" field, the "INSTRUMENT_NAME" field - cannot be changed. + cannot be changed (note that this character string may contain + escape sequences). "LOAD_MODE" - @@ -4438,7 +4795,7 @@ "VOLUME" - master volume of the instrument as optionally - dotted number (where a value < 1.0 means attenuation + dotted number (where a value < 1.0 means attenuation and a value > 1.0 means amplification) @@ -4510,8 +4867,1542 @@
- +
+ The following commands describe how to use and manage + the instruments database. + Notice: + + + All command arguments representing a path or + instrument/directory name support escape sequences as described in chapter + "Character Set and Escape Sequences". + + All occurrences of a forward slash in instrument and directory + names are escaped with its hex (\x2f) or octal (\057) escape sequence. + + + + +
+ The front-end can add a new instrument directory to the + 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. + Note that the character string may contain + 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" +    "." + + +
+ +
+ 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 + (encapsulated into apostrophes, supporting escape sequences as described in chapter + "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" + + +
+ +
+ 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"). + + + + 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"). + + + + + 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>[ FILE_AS_DIR]] <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. + + + + + + If FILE_AS_DIR argument is supplied, all instruments in an instrument + file will be added to a separate directory in the instruments database, which + name will be the name of the instrument file with the file extension stripped off. + + 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. + Note that the character string may contain + 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. + + + 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. + + + ARTISTS - + + Lists the artist names. + Note that the character string may contain + escape sequences. + + + KEYWORDS - + + Provides a list of keywords that refer to the instrument. + Keywords are separated with semicolon and blank. + Note that the character string may contain + 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" +    "." + + +
+ +
+ 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 + (encapsulated into apostrophes, supporting escape sequences as described in chapter + "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" + + +
+ +
+ 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"). + + + + 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"). + + + + 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"). + + + + 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"). + + + + 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"). + + + + 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" +    "." + + +
+ +
+ The front-end can remove all instruments and directories and re-create + the instruments database structure (e.g., in case of a database corruption) + by sending the following command: + + + FORMAT INSTRUMENTS_DB + + + + Possible Answers: + + + "OK" - + + on success + + + "ERR:<error-code>:<error-message>" - + + If the formatting of the instruments database + failed. + + + + +
+ +
+ The 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" + + +
+ +
+ + + +
+ The sampler allows to edit instruments while playing with the + sampler by spawning an external (3rd party) instrument editor + application for a given instrument. The 3rd party instrument + editor applications have to place a respective plugin DLL file + into the sampler's plugins directory. The sampler will + automatically try to load all plugin DLLs in that directory on + startup and only on startup! + At the moment there is only one command for this feature set, + but this will most probably change in future. + +
+ The front-end can request to open an appropriate instrument + editor application by sending the following command: + + + EDIT CHANNEL INSTRUMENT <sampler-channel> + + + Where <sampler-channel> should be replaced by the + number of the sampler channel as given by the + "ADD CHANNEL" + or "LIST CHANNELS" + command. + + The sampler will try to ask all registered instrument + editors (or to be more specific: their sampler plugins) + whether they are capable to handle the instrument on the + given sampler channel. The sampler will simply use the first + instrument editor application which replied with a positive + answer and spawn that instrument editor application within + the sampler's process and provide that application access + to the instrument's data structures, so both applications + can share and access the same instruments data at the same + time, thus allowing to immediately hear changes with the + sampler made by the instrument editor. + + Note: consequently instrument editors are always spawned + locally on the same machine where the sampler is running + on! + + Possible Answers: + + + "OK" - + + when an appropriate instrument editor was + launched + + + "WRN:<warning-code>:<warning-message>" - + + when an appropriate instrument editor was + launched, but there are noteworthy issues + + + "ERR:<error-code>:<error-message>" - + + when an appropriate instrument editor + could not be launched + + + + + + Examples: + + + C: "EDIT CHANNEL INSTRUMENT 0" + S: "OK" + + +
+
+ +
+ You can query detailed informations about files located + at the same system where the sampler instance is running on. + Using this command set allows to retrieve file informations + even remotely from another machine. + +
+ The front-end can retrieve the amount of instruments + within a given instrument file by sending the + following command: + + + GET FILE INSTRUMENTS <filename> + + + Where <filename> is the name of the instrument + file (encapsulated into apostrophes, supporting escape + sequences as described in chapter + "Character Set and Escape + Sequences"). + + The sampler will try to ask all sampler engines, + whether they support the given file and ask the first + engine with a positive answer for the amount of + instruments. + + Possible Answers: + + + On success, the sampler will answer by + returning the amount of instruments. + + "ERR:<error-code>:<error-message>" - + + if the file could not be handled + + + + + + Examples: + + + C: "GET FILE INSTRUMENTS 'D:/Sounds/Foo.gig'" + S: "10" + + +
+ +
+ The front-end can retrieve a list of all instruments + within a given instrument file by sending the + following command: + + + LIST FILE INSTRUMENTS <filename> + + + Where <filename> is the name of the instrument + file (encapsulated into apostrophes, supporting escape + sequences as described in chapter + "Character Set and Escape + Sequences"). + + The sampler will try to ask all sampler engines, + whether they support the given file and ask the first + engine with a positive answer for a list of IDs for the + instruments in the given file. + + Possible Answers: + + + On success, the sampler will answer by + returning a comma separated list of + instrument IDs. + + "ERR:<error-code>:<error-message>" - + + if the file could not be handled + + + + + + Examples: + + + C: "LIST FILE INSTRUMENTS 'D:/Sounds/Foo.gig'" + S: "0,1,2,3,4,5,6,7,8,9" + + +
+ +
+ The front-end can retrieve detailed informations + about a specific instrument within a given instrument + file by sending the following command: + + + GET FILE INSTRUMENT INFO <filename> + <instr-id> + + + Where <filename> is the name of the instrument + file (encapsulated into apostrophes, supporting escape + sequences as described in chapter + "Character Set and Escape + Sequences") and <instr-id> is the numeric + instrument ID as returned by the + + "LIST FILE INSTRUMENTS" command. + + The sampler will try to ask all sampler engines, + whether they support the given file and ask the first + engine with a positive answer for informations about the + specific instrument in the given file. + + Possible Answers: + + + LinuxSampler will answer by sending a <CRLF> separated list. + Each answer line begins with the settings category name + followed by a colon and then a space character <SP> and finally + the info character string to that setting category. At the + moment the following categories are defined: + + + + NAME - + + name of the instrument as + stored in the instrument file + + + FORMAT_FAMILY - + + name of the sampler format + of the given instrument + + + FORMAT_VERSION - + + version of the sampler format + the instrumen is stored as + + + PRODUCT - + + official product name of the + instrument as stored in the file + + + + ARTISTS - + + artists / sample library + vendor of the instrument + + + KEY_BINDINGS - + + comma separated list of integer values representing + the instrument's key mapping in the range between 0 .. 127, + reflecting the analog meaning of the MIDI specification. + + + KEYSWITCH_BINDINGS - + + comma separated list of integer values representing + the instrument's keyswitch mapping in the range between 0 .. 127, + reflecting the analog meaning of the MIDI specification. + + + + + + + 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 @@ -4585,12 +6476,22 @@ / 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 + + / SEND SP send_instruction + / RESET / QUIT @@ -4601,6 +6502,24 @@ CHANNEL + / DB_INSTRUMENT_DIRECTORY SP db_path + + / DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename + + / DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP FILE_AS_DIR SP db_path SP filename + + / DB_INSTRUMENTS SP scan_mode SP db_path SP filename + + / DB_INSTRUMENTS SP scan_mode SP FILE_AS_DIR 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 / MIDI_INSTRUMENT_MAP SP map_name @@ -4619,6 +6538,10 @@ / CHANNEL_COUNT + / CHANNEL_MIDI + + / DEVICE_MIDI + / VOICE_COUNT / STREAM_COUNT @@ -4627,6 +6550,10 @@ / CHANNEL_INFO + / FX_SEND_COUNT + + / FX_SEND_INFO + / MIDI_INSTRUMENT_MAP_COUNT / MIDI_INSTRUMENT_MAP_INFO @@ -4635,10 +6562,24 @@ / MIDI_INSTRUMENT_INFO + / DB_INSTRUMENT_DIRECTORY_COUNT + + / DB_INSTRUMENT_DIRECTORY_INFO + + / DB_INSTRUMENT_COUNT + + / DB_INSTRUMENT_INFO + + / DB_INSTRUMENTS_JOB_INFO + / MISCELLANEOUS + / TOTAL_STREAM_COUNT + / TOTAL_VOICE_COUNT + / GLOBAL_INFO + unsubscribe_event = @@ -4653,6 +6594,10 @@ / CHANNEL_COUNT + / CHANNEL_MIDI + + / DEVICE_MIDI + / VOICE_COUNT / STREAM_COUNT @@ -4661,6 +6606,10 @@ / CHANNEL_INFO + / FX_SEND_COUNT + + / FX_SEND_INFO + / MIDI_INSTRUMENT_MAP_COUNT / MIDI_INSTRUMENT_MAP_INFO @@ -4669,21 +6618,35 @@ / MIDI_INSTRUMENT_INFO + / DB_INSTRUMENT_DIRECTORY_COUNT + + / DB_INSTRUMENT_DIRECTORY_INFO + + / DB_INSTRUMENT_COUNT + + / DB_INSTRUMENT_INFO + + / DB_INSTRUMENTS_JOB_INFO + / MISCELLANEOUS + / TOTAL_STREAM_COUNT + / TOTAL_VOICE_COUNT + / GLOBAL_INFO + map_instruction = - MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value + MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value - / MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode + / MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode - / MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP entry_name + / MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP entry_name - / MIDI_INSTRUMENT SP midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode SP entry_name + / MIDI_INSTRUMENT SP modal_arg midi_map SP midi_bank SP midi_prog SP engine_name SP filename SP instrument_index SP volume_value SP instr_load_mode SP entry_name @@ -4701,6 +6664,12 @@ / MIDI_INSTRUMENT_MAP SP ALL + / DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path + + / DB_INSTRUMENT_DIRECTORY SP db_path + + / DB_INSTRUMENT SP db_path + get_instruction = @@ -4753,6 +6722,8 @@ / SERVER SP INFO + / TOTAL_STREAM_COUNT + / TOTAL_VOICE_COUNT / TOTAL_VOICE_COUNT_MAX @@ -4771,6 +6742,26 @@ / 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 + + / FILE SP INSTRUMENTS SP filename + + / FILE SP INSTRUMENT SP INFO SP filename SP instrument_index + set_instruction = @@ -4781,16 +6772,36 @@ / MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list + / MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE + / MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list / CHANNEL SP set_chan_instruction / 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 + / FX_SEND SP MIDI_CONTROLLER SP sampler_channel SP fx_send_id SP midi_ctrl + + / 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 + + / DB_INSTRUMENT SP FILE_PATH SP filename SP filename + / ECHO SP boolean + / VOLUME SP volume_value + create_instruction = @@ -4823,6 +6834,36 @@ +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 + + / LOST SP DB_INSTRUMENT_FILES + + + +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 = AUDIO_OUTPUT_DEVICE SP number @@ -4873,6 +6914,26 @@ +edit_instruction = + + CHANNEL SP INSTRUMENT SP sampler_channel + + + +format_instruction = + + INSTRUMENTS_DB + + + +modal_arg = + + /* epsilon (empty argument) */ + + / NON_MODAL SP + + + key_val_list = string '=' param_val_list @@ -4911,6 +6972,22 @@ / 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 + + / FILE SP INSTRUMENTS SP filename + + + +send_instruction = + + CHANNEL SP MIDI_DATA SP string SP sampler_channel SP number SP number + load_instr_args = @@ -5033,25 +7110,31 @@ filename = - stringval + path + + + +db_path = + + path map_name = - stringval + stringval_escaped entry_name = - stringval + stringval_escaped fx_send_name = - stringval + stringval_escaped @@ -5063,6 +7146,7 @@ + param_val = string @@ -5075,8 +7159,149 @@ +query_val_list = + + string '=' query_val + + / query_val_list SP string '=' query_val + + + +query_val = + + text_escaped + + / stringval_escaped + + + +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. + + The following LSCP commands support escape sequences as part + of their filename / path based arguments and / or may contain + a filename / path with escape sequences in their response: + + "LOAD INSTRUMENT" + "GET CHANNEL INFO" + "MAP MIDI_INSTRUMENT" + "GET MIDI_INSTRUMENT INFO" + "ADD DB_INSTRUMENT_DIRECTORY" + "ADD DB_INSTRUMENTS" + "REMOVE DB_INSTRUMENT_DIRECTORY" + "REMOVE DB_INSTRUMENT" + "GET DB_INSTRUMENT_DIRECTORIES" + "LIST DB_INSTRUMENT_DIRECTORIES" + "GET DB_INSTRUMENT_DIRECTORY INFO" + "GET DB_INSTRUMENTS" + "LIST DB_INSTRUMENTS" + "GET DB_INSTRUMENT INFO" + "SET DB_INSTRUMENT_DIRECTORY NAME" + "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION" + "SET DB_INSTRUMENT NAME" + "SET DB_INSTRUMENT DESCRIPTION" + "FIND DB_INSTRUMENTS" + "FIND DB_INSTRUMENT_DIRECTORIES" + "MOVE DB_INSTRUMENT" + "MOVE DB_INSTRUMENT_DIRECTORY" + "COPY DB_INSTRUMENT" + "COPY DB_INSTRUMENT_DIRECTORY" + "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 + the path, thus if a directory- or filename includes a forward slash + (not intended as path node separator), you MUST escape that slash + either with the respective hex escape sequence ("\x2f") or with the + respective octal escape sequence ("\057"). + + + + Note for Windows: file path arguments in LSCP are expected + to use forward slashes as directory node separator similar + to Unix based operating systems. In contrast to Unix however + a Windows typical drive character is expected to be + prefixed to the path. That is an original Windows file path + like "D:\Sounds\My.gig" would become in LSCP: + "D:/Sounds/My.gig". + + + + The following LSCP commands even support escape sequences as + part of at least one of their text-based arguments (i.e. entity name, + description) and / or may contain escape sequences in at least one of + their text-based fields in their response: + + "GET SERVER INFO" + "GET ENGINE INFO" + "GET CHANNEL INFO" + "CREATE FX_SEND" + "GET FX_SEND INFO" + "SET FX_SEND NAME" + "GET MIDI_INSTRUMENT INFO" + "GET MIDI_INSTRUMENT_MAP INFO" + "ADD MIDI_INSTRUMENT_MAP" + "MAP MIDI_INSTRUMENT" + "SET MIDI_INSTRUMENT_MAP NAME" + "GET DB_INSTRUMENT_DIRECTORY INFO" + "SET DB_INSTRUMENT_DIRECTORY NAME" + "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION" + "FIND DB_INSTRUMENT_DIRECTORIES" + "GET DB_INSTRUMENT INFO" + "SET DB_INSTRUMENT NAME" + "SET DB_INSTRUMENT DESCRIPTION" + "FIND DB_INSTRUMENTS" + + Please note that these lists are manually maintained. If you + find a command that also supports escape sequences we forgot to + mention here, please report it! + +
@@ -5180,6 +7405,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: @@ -5191,7 +7466,7 @@ Server will start sending the following notification messages: - "NOTIFY:VOICE_COUNT:<sampler-channel> <voices> + "NOTIFY:VOICE_COUNT:<sampler-channel> <voices>" where <sampler-channel> will be replaced by the sampler channel the @@ -5261,6 +7536,44 @@ message is sufficient here.
+
+ 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. +
+ +
+ 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. +
+
Client may want to be notified when the total number of voices on the back-end changes by issuing the following command: @@ -5272,13 +7585,31 @@ Server will start sending the following notification messages: - "NOTIFY:TOTAL_VOICE_COUNT:<voices> + "NOTIFY:TOTAL_VOICE_COUNT:<voices>" where <voices> will be replaced by the new number of 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: @@ -5361,6 +7692,151 @@ message is sufficient here.
+
+ 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. + + +
+ +
+ 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: @@ -5439,6 +7915,16 @@ + + + ASCII format for Network Interchange + + UCLA + + + + +