--- linuxsampler/trunk/Documentation/lscp.xml 2006/12/27 16:17:08 1001
+++ linuxsampler/trunk/Documentation/lscp.xml 2007/05/24 14:04:18 1200
@@ -34,7 +34,7 @@
schoenebeck at software minus engineering dot org
-
+
LinuxSampler Developers
LSCP
@@ -2555,7 +2555,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)
@@ -3287,7 +3287,7 @@
S: "OK[0]"
-
+
C: "CREATE FX_SEND 0 93"
S: "OK[1]"
@@ -3434,6 +3434,19 @@
name of the effect send entity
+ 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 -
comma separated list which reflects to which audio
@@ -3458,12 +3471,55 @@
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.
+
+ 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 +3580,102 @@
+
+ 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 reset a particular sampler channel by sending the following command:
@@ -3807,6 +3959,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 +3972,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
+
+
+
+
+
@@ -4028,6 +4245,12 @@
which does not have to be unique
+ DEFAULT -
+
+ either true or false,
+ defines whether this map is the default map
+
+
@@ -4039,6 +4262,7 @@
C: "GET MIDI_INSTRUMENT_MAP INFO 0"
S: "NAME: Standard Map"
+ "DEFAULT: true"
"."
@@ -4087,7 +4311,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>]
@@ -4105,7 +4329,7 @@
<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 +4364,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
@@ -4190,13 +4414,19 @@
"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 +4469,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"
@@ -4438,7 +4668,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,6 +4740,1130 @@
+
+
+ The following commands describe how to use and manage
+ the instruments database.
+
+
+ The front-end can add a new instrument directory to the
+ instruments database by sending the following command:
+
+
+ ADD DB_INSTRUMENT_DIRECTORY <dir>
+
+
+ Where <dir> is the absolute path name of the directory
+ to be created (encapsulated into apostrophes).
+
+ Possible Answers:
+
+
+ "OK" -
+
+ on success
+
+
+ "ERR:<error-code>:<error-message>" -
+
+ when the directory could not be created, which
+ can happen if the directory already exists or the
+ name contains not allowed symbols
+
+
+
+
+
+ Examples:
+
+
+ C: "ADD DB_INSTRUMENT_DIRECTORY '/Piano Collection'"
+ S: "OK"
+
+
+
+
+
+ The front-end can delete a particular instrument directory
+ from the instruments database by sending the following command:
+
+
+ REMOVE DB_INSTRUMENT_DIRECTORY [FORCE] <dir>
+
+
+ Where <dir> is the absolute path name of the directory
+ to delete. The optional FORCE argument can be used to
+ force the deletion of a non-empty directory and all its content.
+
+ Possible Answers:
+
+
+ "OK" -
+
+ if the directory is deleted successfully
+
+
+ "ERR:<error-code>:<error-message>" -
+
+ if the given directory does not exist, or
+ if trying to delete a non-empty directory,
+ without using the FORCE argument.
+
+
+
+
+
+ Examples:
+
+
+ C: "REMOVE DB_INSTRUMENT_DIRECTORY FORCE '/Piano Collection'"
+ S: "OK"
+
+
+
+
+
+ The front-end can retrieve the current amount of
+ directories in a specific directory by sending the following command:
+
+
+ GET DB_INSTRUMENT_DIRECTORIES [RECURSIVE] <dir>
+
+
+ Where <dir> should be replaced by the absolute path
+ name of the directory. If RECURSIVE is specified, the number of
+ all directories, including those located in subdirectories of the
+ specified directory, will be returned.
+
+ Possible Answers:
+
+
+ The current number of instrument directories
+ in the specified directory.
+ "ERR:<error-code>:<error-message>" -
+
+ if the given directory does not exist.
+
+
+
+
+
+ Example:
+
+
+ C: "GET DB_INSTRUMENT_DIRECTORIES '/'"
+ S: "2"
+
+
+
+
+
+ The front-end can retrieve the current list of directories
+ in specific directory by sending the following command:
+
+
+ LIST DB_INSTRUMENT_DIRECTORIES [RECURSIVE] <dir>
+
+
+ Where <dir> should be replaced by the absolute path
+ name of the directory. If RECURSIVE is specified, the absolute path names
+ of all directories, including those located in subdirectories of the
+ specified directory, will be returned.
+
+ Possible Answers:
+
+
+ A comma separated list of all instrument directories
+ (encapsulated into apostrophes) in the specified directory.
+ "ERR:<error-code>:<error-message>" -
+
+ if the given directory does not exist.
+
+
+
+
+ Example:
+
+
+ C: "LIST DB_INSTRUMENT_DIRECTORIES '/'"
+ S: "'Piano Collection','Percussion Collection'"
+
+
+
+
+ C: "LIST DB_INSTRUMENT_DIRECTORIES RECURSIVE '/'"
+ S: "'/Piano Collection','/Piano Collection/Acoustic','/Piano Collection/Acoustic/New','/Percussion Collection'"
+
+
+
+
+
+ The front-end can ask for the current settings of an
+ instrument directory by sending the following command:
+
+
+ GET DB_INSTRUMENT_DIRECTORY INFO <dir>
+
+
+ Where <dir> should be replaced by the absolute path
+ name of the directory the front-end is interested in.
+
+ Possible Answers:
+
+
+ LinuxSampler will answer by sending a <CRLF> separated list.
+ Each answer line begins with the settings category name
+ followed by a colon and then a space character <SP> and finally
+ the info character string to that setting category. At the
+ moment the following categories are defined:
+
+
+
+ DESCRIPTION -
+
+ A brief description of the directory content
+
+
+ CREATED -
+
+ The creation date and time of the directory,
+ represented in "YYYY-MM-DD HH:MM:SS" format
+
+
+ MODIFIED -
+
+ The date and time of the last modification of the
+ directory, represented in "YYYY-MM-DD HH:MM:SS" format
+
+
+
+
+
+
+ The mentioned fields above don't have to be in particular order.
+
+ Example:
+
+
+ C: "GET DB_INSTRUMENT_DIRECTORY INFO '/Piano Collection'"
+ S: "DESCRIPTION: Piano collection of instruments in GigaSampler format."
+ "CREATED: 2007-02-05 10:23:12"
+ "MODIFIED: 2007-04-07 12:50:21"
+ "."
+
+
+
+
+
+ The front-end can alter the name of a specific
+ instrument directory by sending the following command:
+
+
+ SET DB_INSTRUMENT_DIRECTORY NAME <dir> <name>
+
+
+ Where <dir> is the absolute path name of the directory and
+ <name> is the new name for that directory.
+
+ Possible Answers:
+
+
+ "OK" -
+
+ on success
+
+
+ "ERR:<error-code>:<error-message>" -
+
+ in case the given directory does not exists,
+ or if a directory with name equal to the new
+ name already exists.
+
+
+
+
+
+ Example:
+
+
+ C: "SET DB_INSTRUMENT_DIRECTORY NAME '/Piano Collection/Acustic' 'Acoustic'"
+ S: "OK"
+
+
+
+
+
+ The front-end can move a specific
+ instrument directory by sending the following command:
+
+
+ MOVE DB_INSTRUMENT_DIRECTORY <dir> <dst>
+
+
+ Where <dir> is the absolute path name of the directory
+ to move and <dst> is the location where the directory will
+ be moved to.
+
+ Possible Answers:
+
+
+ "OK" -
+
+ on success
+
+
+ "ERR:<error-code>:<error-message>" -
+
+ in case a given directory does not exists,
+ or if a directory with name equal to the name
+ of the specified directory already exists in
+ the destination directory. Error is also thrown
+ when trying to move a directory to a subdirectory
+ of itself.
+
+
+
+
+
+ Example:
+
+
+ C: "MOVE DB_INSTRUMENT_DIRECTORY '/Acoustic' '/Piano Collection/Acoustic'"
+ S: "OK"
+
+
+
+
+
+ The front-end can copy a specific
+ instrument directory by sending the following command:
+
+
+ COPY DB_INSTRUMENT_DIRECTORY <dir> <dst>
+
+
+ Where <dir> is the absolute path name of the directory
+ to copy and <dst> is the location where the directory will
+ be copied to.
+
+ Possible Answers:
+
+
+ "OK" -
+
+ on success
+
+
+ "ERR:<error-code>:<error-message>" -
+
+ in case a given directory does not exists,
+ or if a directory with name equal to the name
+ of the specified directory already exists in
+ the destination directory. Error is also thrown
+ when trying to copy a directory to a subdirectory
+ of itself.
+
+
+
+
+
+ Example:
+
+
+ C: "COPY DB_INSTRUMENT_DIRECTORY '/Piano Collection/Acoustic' '/Acoustic/Pianos'"
+ S: "OK"
+
+
+
+
+
+ The front-end can alter the description of a specific
+ instrument directory by sending the following command:
+
+
+ SET DB_INSTRUMENT_DIRECTORY DESCRIPTION <dir> <desc>
+
+
+ Where <dir> is the absolute path name of the directory and
+ <desc> is the new description for the directory.
+
+ Possible Answers:
+
+
+ "OK" -
+
+ on success
+
+
+ "ERR:<error-code>:<error-message>" -
+
+ in case the given directory does not exists.
+
+
+
+
+
+ Example:
+
+
+ C: "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION '/Piano Collection' 'A collection of piano instruments in various format.'"
+ S: "OK"
+
+
+
+
+
+ The front-end can search for directories
+ in specific directory by sending the following command:
+
+
+ FIND DB_INSTRUMENT_DIRECTORIES [NON_RECURSIVE] <dir> <criteria-list>
+
+
+ Where <dir> should be replaced by the absolute path
+ name of the directory to search in. If NON_RECURSIVE is specified, the
+ directories located in subdirectories of the specified directory will not
+ be searched. <criteria-list> is a list of search criterias
+ in form of "key1=val1 key2=val2 ...". The following criterias are
+ allowed:
+
+ NAME='<search-string>'
+
+ Restricts the search to directories, which names
+ satisfy the supplied search string.
+
+
+
+ CREATED='[<date-after>]..[<date-before>]'
+
+ Restricts the search to directories, which creation
+ date satisfies the specified period, where <date-after>
+ and <date-before> are in "YYYY-MM-DD HH:MM:SS" format.
+ If <date-after> is omitted the search is restricted to
+ directories created before <date-before>. If
+ <date-before> is omitted, the search is restricted
+ to directories created after <date-after>.
+
+
+
+ MODIFIED='[<date-after>]..[<date-before>]'
+
+ Restricts the search to directories, which
+ date of last modification satisfies the specified period, where
+ <date-after> and <date-before> are in "YYYY-MM-DD HH:MM:SS"
+ format. If <date-after> is omitted the search is restricted to
+ directories, which are last modified before <date-before>. If
+ <date-before> is omitted, the search is restricted to directories,
+ which are last modified after <date-after>.
+
+
+
+ DESCRIPTION='<search-string>'
+
+ Restricts the search to directories with description
+ that satisfies the supplied search string.
+
+
+
+
+ Where <search-string> is either a regular expression, or a
+ word list separated with spaces for OR search and with '+' for AND search.
+
+ Possible Answers:
+
+
+ A comma separated list with the absolute path names (encapsulated into
+ apostrophes) of all directories in the specified directory that satisfy
+ the supplied search criterias.
+ "ERR:<error-code>:<error-message>" -
+
+ if the given directory does not exist.
+
+
+
+
+ Example:
+
+
+ C: "FIND DB_INSTRUMENT_DIRECTORIES '/' NAME='Piano'"
+ S: "'/Piano Collection'"
+
+
+
+
+ C: "FIND DB_INSTRUMENT_DIRECTORIES '/' CREATED='..2007-04-01 09:30:13'"
+ S: "'/Piano Collection','/Percussions'"
+
+
+
+
+
+ The front-end can add one or more instruments
+ to the instruments database by sending the following command:
+
+
+ ADD DB_INSTRUMENTS [NON_MODAL] [<mode>] <db_dir> <file_path> [<instr_index>]
+
+
+ Where <db_dir> is the absolute path name of a directory
+ (encapsulated into apostrophes) in the instruments database in which
+ only the new instruments (that are not already in the database) will
+ be added, <file_path> is the absolute path name of a file or
+ directory in the file system (encapsulated into apostrophes). In case
+ an instrument file is supplied, only the instruments in the specified
+ file will be added to the instruments database. If the optional
+ <instr_index> (the index of the instrument within the given file)
+ is supplied too, then only the specified instrument will be added.
+ In case a directory is supplied, the instruments in that directory
+ will be added. The OPTIONAL <mode> argument is only applied
+ when a directory is provided as <file_path> and specifies how the
+ scanning will be done and has exactly the following possibilities:
+
+
+ "RECURSIVE" -
+
+ All instruments will be processed, including those
+ in the subdirectories, and the respective subdirectory
+ tree structure will be recreated in the instruments
+ database
+
+
+ "NON_RECURSIVE" -
+
+ Only the instruments in the specified directory
+ will be added, the instruments in the subdirectories
+ will not be processed.
+
+
+ "FLAT" -
+
+ All instruments will be processed, including those
+ in the subdirectories, but the respective subdirectory
+ structure will not be recreated in the instruments
+ database. All instruments will be added directly in
+ the specified database directory.
+
+
+
+
+
+ The difference between regular and NON_MODAL versions of the command
+ is that the regular command returns when the scanning is finished
+ while NON_MODAL version returns immediately and a background process is launched.
+ The GET DB_INSTRUMENTS_JOB INFO
+ command can be used to monitor the scanning progress.
+
+ Possible Answers:
+
+
+ "OK" -
+
+ on success when NON_MODAL is not supplied
+
+
+ "OK[<job-id>]" -
+
+ on success when NON_MODAL is supplied, where <job-id>
+ is a numerical ID used to obtain status information about the job progress.
+ See GET DB_INSTRUMENTS_JOB INFO
+
+
+
+ "ERR:<error-code>:<error-message>" -
+
+ if an invalid path is specified.
+
+
+
+
+
+ Examples:
+
+
+ C: "ADD DB_INSTRUMENTS '/Piano Collection' '/home/me/gigs/PMI Bosendorfer 290.gig' 0"
+ S: "OK"
+
+
+
+
+
+ The front-end can remove a particular instrument
+ from the instruments database by sending the following command:
+
+
+ REMOVE DB_INSTRUMENT <instr_path>
+
+
+ Where <instr_path> is the absolute path name
+ (in the instruments database) of the instrument to remove.
+
+ Possible Answers:
+
+
+ "OK" -
+
+ if the instrument is removed successfully
+
+
+ "ERR:<error-code>:<error-message>" -
+
+ if the given path does not exist or
+ is a directory.
+
+
+
+
+
+ Examples:
+
+
+ C: "REMOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290'"
+ S: "OK"
+
+
+
+
+
+ The front-end can retrieve the current amount of
+ instruments in a specific directory by sending the following command:
+
+
+ GET DB_INSTRUMENTS [RECURSIVE] <dir>
+
+
+ Where <dir> should be replaced by the absolute path name
+ of the directory. If RECURSIVE is specified, the number of all
+ instruments, including those located in subdirectories of the
+ specified directory, will be returned.
+
+ Possible Answers:
+
+
+ The current number of instruments
+ in the specified directory.
+ "ERR:<error-code>:<error-message>" -
+
+ if the given directory does not exist.
+
+
+
+
+
+ Example:
+
+
+ C: "GET DB_INSTRUMENTS '/Piano Collection'"
+ S: "2"
+
+
+
+
+
+ The front-end can retrieve the current list of instruments
+ in specific directory by sending the following command:
+
+
+ LIST DB_INSTRUMENTS [RECURSIVE] <dir>
+
+
+ Where <dir> should be replaced by the absolute path
+ name of the directory. If RECURSIVE is specified, the absolute path
+ names of all instruments, including those located in subdirectories
+ of the specified directory, will be returned.
+
+ Possible Answers:
+
+
+ A comma separated list of all instruments
+ (encapsulated into apostrophes) in the specified directory.
+ "ERR:<error-code>:<error-message>" -
+
+ if the given directory does not exist.
+
+
+
+
+ Example:
+
+
+ C: "LIST DB_INSTRUMENTS '/Piano Collection'"
+ S: "'Bosendorfer 290','Steinway D'"
+
+
+
+
+ C: "LIST DB_INSTRUMENTS RECURSIVE '/Piano Collection'"
+ S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D','/Piano Collection/Lite/Free Piano'"
+
+
+
+
+
+ The front-end can ask for the current settings of an
+ instrument by sending the following command:
+
+
+ GET DB_INSTRUMENT INFO <instr_path>
+
+
+ Where <instr_path> should be replaced by the absolute path
+ name of the instrument the front-end is interested in.
+
+ Possible Answers:
+
+
+ LinuxSampler will answer by sending a <CRLF> separated list.
+ Each answer line begins with the settings category name
+ followed by a colon and then a space character <SP> and finally
+ the info character string to that setting category. At the
+ moment the following categories are defined:
+
+
+
+ INSTRUMENT_FILE -
+
+ File name of the instrument.
+
+
+ INSTRUMENT_NR -
+
+ Index of the instrument within the file.
+
+
+ FORMAT_FAMILY -
+
+ The format family of the instrument.
+
+
+ FORMAT_VERSION -
+
+ The format version of the instrument.
+
+
+ SIZE -
+
+ The size of the instrument in bytes.
+
+
+ CREATED -
+
+ The date and time when the instrument is added
+ in the instruments database, represented in
+ "YYYY-MM-DD HH:MM:SS" format
+
+
+ MODIFIED -
+
+ The date and time of the last modification of the
+ instrument's database settings, represented in
+ "YYYY-MM-DD HH:MM:SS" format
+
+
+ DESCRIPTION -
+
+ A brief description of the instrument
+
+
+ IS_DRUM -
+
+ either true or false, determines whether the
+ instrument is a drumkit or a chromatic instrument
+
+
+ PRODUCT -
+
+ The product title of the instrument
+
+
+ ARTISTS -
+
+ Lists the artist names
+
+
+ KEYWORDS -
+
+ Provides a list of keywords that refer to the instrument.
+ Keywords are separated with semicolon and blank.
+
+
+
+
+
+
+ The mentioned fields above don't have to be in particular order.
+
+ Example:
+
+
+ C: "GET DB_INSTRUMENT INFO '/Piano Collection/Bosendorfer 290'"
+ S: "INSTRUMENT_FILE: /home/me/gigs/Bosendorfer 290.gig"
+ "INSTRUMENT_NR: 0"
+ "FORMAT_FAMILY: GIG"
+ "FORMAT_VERSION: 2"
+ "SIZE: 2050871870"
+ "CREATED: 2007-02-05 10:23:12"
+ "MODIFIED: 2007-04-07 12:50:21"
+ "DESCRIPTION: "
+ "IS_DRUM: false"
+ "PRODUCT: GRANDIOSO Bosendorfer 290"
+ "ARTISTS: Post Musical Instruments"
+ "KEYWORDS: Bosendorfer"
+ "."
+
+
+
+
+
+ The front-end can alter the name of a specific
+ instrument by sending the following command:
+
+
+ SET DB_INSTRUMENT NAME <instr> <name>
+
+
+ Where <instr> is the absolute path name of the instrument and
+ <name> is the new name for that instrument.
+
+ Possible Answers:
+
+
+ "OK" -
+
+ on success
+
+
+ "ERR:<error-code>:<error-message>" -
+
+ in case the given instrument does not exists,
+ or if an instrument with name equal to the new
+ name already exists.
+
+
+
+
+
+ Example:
+
+
+ C: "SET DB_INSTRUMENT NAME '/Piano Collection/Bosendorfer' 'Bosendorfer 290'"
+ S: "OK"
+
+
+
+
+
+ The front-end can move a specific instrument to another directory by
+ sending the following command:
+
+
+ MOVE DB_INSTRUMENT <instr> <dst>
+
+
+ Where <instr> is the absolute path name of the instrument
+ to move and <dst> is the directory where the instrument will
+ be moved to.
+
+ Possible Answers:
+
+
+ "OK" -
+
+ on success
+
+
+ "ERR:<error-code>:<error-message>" -
+
+ in case the given instrument does not exists,
+ or if an instrument with name equal to the name of the
+ specified instrument already exists in the destination
+ directory.
+
+
+
+
+
+ Example:
+
+
+ C: "MOVE DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Piano Collection/Acoustic'"
+ S: "OK"
+
+
+
+
+
+ The front-end can copy a specific instrument to another directory by
+ sending the following command:
+
+
+ COPY DB_INSTRUMENT <instr> <dst>
+
+
+ Where <instr> is the absolute path name of the instrument
+ to copy and <dst> is the directory where the instrument will
+ be copied to.
+
+ Possible Answers:
+
+
+ "OK" -
+
+ on success
+
+
+ "ERR:<error-code>:<error-message>" -
+
+ in case the given instrument does not exists,
+ or if an instrument with name equal to the name of the
+ specified instrument already exists in the destination
+ directory.
+
+
+
+
+
+ Example:
+
+
+ C: "COPY DB_INSTRUMENT '/Piano Collection/Bosendorfer 290' '/Acoustic/Pianos/'"
+ S: "OK"
+
+
+
+
+
+ The front-end can alter the description of a specific
+ instrument by sending the following command:
+
+
+ SET DB_INSTRUMENT DESCRIPTION <instr> <desc>
+
+
+ Where <instr> is the absolute path name of the instrument and
+ <desc> is the new description for the instrument.
+
+ Possible Answers:
+
+
+ "OK" -
+
+ on success
+
+
+ "ERR:<error-code>:<error-message>" -
+
+ in case the given instrument does not exists.
+
+
+
+
+
+ Example:
+
+
+ C: "SET DB_INSTRUMENT DESCRIPTION '/Piano Collection/Acoustic/Bosendorfer 290' 'No comment :)'"
+ S: "OK"
+
+
+
+
+
+ The front-end can search for instruments
+ in specific directory by sending the following command:
+
+
+ FIND DB_INSTRUMENTS [NON_RECURSIVE] <dir> <criteria-list>
+
+
+ Where <dir> should be replaced by the absolute path
+ name of the directory to search in. If NON_RECURSIVE is specified, the
+ directories located in subdirectories of the specified directory will not
+ be searched. <criteria-list> is a list of search criterias
+ in form of "key1=val1 key2=val2 ...". The following criterias are
+ allowed:
+
+ NAME='<search-string>'
+
+ Restricts the search to instruments, which names
+ satisfy the supplied search string.
+
+
+
+ SIZE=[<min>]..[<max>]
+
+ Restricts the search to instruments, which
+ size is in the specified range. If <min> is omitted,
+ the search results are restricted to instruments with size less then
+ or equal to <max>. If <max> is omitted, the
+ search is restricted to instruments with size greater then
+ or equal to <min>.
+
+
+
+ CREATED='[<date-after>]..[<date-before>]'
+
+ Restricts the search to instruments, which creation
+ date satisfies the specified period, where <date-after>
+ and <date-before> are in "YYYY-MM-DD HH:MM:SS" format.
+ If <date-after> is omitted the search is restricted to
+ instruments created before <date-before>. If
+ <date-before> is omitted, the search is restricted
+ to instruments created after <date-after>.
+
+
+
+ MODIFIED='[<date-after>]..[<date-before>]'
+
+ Restricts the search to instruments, which
+ date of last modification satisfies the specified period, where
+ <date-after> and <date-before> are in "YYYY-MM-DD HH:MM:SS"
+ format. If <date-after> is omitted the search is restricted to
+ instruments, which are last modified before <date-before>. If
+ <date-before> is omitted, the search is restricted to instruments,
+ which are last modified after <date-after>.
+
+
+
+ DESCRIPTION='<search-string>'
+
+ Restricts the search to instruments with description
+ that satisfies the supplied search string.
+
+
+
+ PRODUCT='<search-string>'
+
+ Restricts the search to instruments with product info
+ that satisfies the supplied search string.
+
+
+
+ ARTISTS='<search-string>'
+
+ Restricts the search to instruments with artists info
+ that satisfies the supplied search string.
+
+
+
+ KEYWORDS='<search-string>'
+
+ Restricts the search to instruments with keyword list
+ that satisfies the supplied search string.
+
+
+
+ IS_DRUM=true | false
+
+ Either true or false. Restricts the search to
+ drum kits or chromatic instruments.
+
+
+
+ FORMAT_FAMILIES='<format-list>'
+
+ Restricts the search to instruments of the supplied format families,
+ where <format-list> is a comma separated list of format families.
+
+
+
+
+ Where <search-string> is either a regular expression, or a
+ word list separated with spaces for OR search and with '+' for AND search.
+
+ Possible Answers:
+
+
+ A comma separated list with the absolute path names (encapsulated into
+ apostrophes) of all instruments in the specified directory that satisfy
+ the supplied search criterias.
+ "ERR:<error-code>:<error-message>" -
+
+ if the given directory does not exist.
+
+
+
+
+ Example:
+
+
+ C: "FIND DB_INSTRUMENTS '/Piano Collection' NAME='bosendorfer+290'"
+ S: "'/Piano Collection/Bosendorfer 290'"
+
+
+
+
+ C: "FIND DB_INSTRUMENTS '/Piano Collection' CREATED='2007-04-01 09:30:13..'"
+ S: "'/Piano Collection/Bosendorfer 290','/Piano Collection/Steinway D'"
+
+
+
+
+
+ The front-end can ask for the current status of a
+ particular database instruments job by sending the following command:
+
+
+ GET DB_INSTRUMENTS_JOB INFO <job-id>
+
+
+ Where <job-id> should be replaced by the numerical ID
+ of the job the front-end is interested in.
+
+ Possible Answers:
+
+
+ LinuxSampler will answer by sending a <CRLF> separated list.
+ Each answer line begins with the settings category name
+ followed by a colon and then a space character <SP> and finally
+ the info character string to that setting category. At the
+ moment the following categories are defined:
+
+
+
+ FILES_TOTAL -
+
+ The total number of files scheduled for scanning
+
+
+ FILES_SCANNED -
+
+ The current number of scanned files
+
+
+ SCANNING -
+
+ The absolute path name of the file which is currently
+ being scanned
+
+
+ STATUS -
+
+ An integer value between 0 and 100 indicating the
+ scanning progress percentage of the file which is
+ currently being scanned
+
+
+
+
+
+
+ The mentioned fields above don't have to be in particular order.
+
+ Example:
+
+
+ C: "GET DB_INSTRUMENTS_JOB INFO 2"
+ S: "FILES_TOTAL: 12"
+ "FILES_SCANNED: 7"
+ "SCANNING: /home/me/gigs/Bosendorfer 290.gig"
+ "STATUS: 42"
+ "."
+
+
+
+
+
+
@@ -4585,12 +5939,16 @@
/ 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
+
/ RESET
/ QUIT
@@ -4601,6 +5959,20 @@
CHANNEL
+ / DB_INSTRUMENT_DIRECTORY SP pathname
+
+ / DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP pathname SP pathname
+
+ / DB_INSTRUMENTS SP scan_mode SP pathname SP pathname
+
+ / DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname
+
+ / DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname SP instrument_index
+
+ / DB_INSTRUMENTS SP pathname SP pathname
+
+ / DB_INSTRUMENTS SP pathname SP pathname SP instrument_index
+
/ MIDI_INSTRUMENT_MAP
/ MIDI_INSTRUMENT_MAP SP map_name
@@ -4627,6 +5999,10 @@
/ CHANNEL_INFO
+ / FX_SEND_COUNT
+
+ / FX_SEND_INFO
+
/ MIDI_INSTRUMENT_MAP_COUNT
/ MIDI_INSTRUMENT_MAP_INFO
@@ -4635,10 +6011,22 @@
/ 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
+
unsubscribe_event =
@@ -4661,6 +6049,10 @@
/ CHANNEL_INFO
+ / FX_SEND_COUNT
+
+ / FX_SEND_INFO
+
/ MIDI_INSTRUMENT_MAP_COUNT
/ MIDI_INSTRUMENT_MAP_INFO
@@ -4669,21 +6061,33 @@
/ 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
+
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 +6105,12 @@
/ MIDI_INSTRUMENT_MAP SP ALL
+ / DB_INSTRUMENT_DIRECTORY SP FORCE SP pathname
+
+ / DB_INSTRUMENT_DIRECTORY SP pathname
+
+ / DB_INSTRUMENT SP pathname
+
get_instruction =
@@ -4771,6 +6181,22 @@
/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
+ / DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname
+
+ / DB_INSTRUMENT_DIRECTORIES SP pathname
+
+ / DB_INSTRUMENT_DIRECTORY SP INFO SP pathname
+
+ / DB_INSTRUMENTS SP RECURSIVE SP pathname
+
+ / DB_INSTRUMENTS SP pathname
+
+ / DB_INSTRUMENT SP INFO SP pathname
+
+ / DB_INSTRUMENTS_JOB SP INFO SP number
+
+ / VOLUME
+
set_instruction =
@@ -4787,10 +6213,26 @@
/ 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 pathname SP dirname
+
+ / DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP pathname SP stringval
+
+ / DB_INSTRUMENT SP NAME SP pathname SP dirname
+
+ / DB_INSTRUMENT SP DESCRIPTION SP pathname SP stringval
+
/ ECHO SP boolean
+ / VOLUME SP volume_value
+
create_instruction =
@@ -4823,6 +6265,34 @@
+find_instruction =
+
+ DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP query_val_list
+
+ / DB_INSTRUMENTS SP pathname SP query_val_list
+
+ / DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP pathname SP query_val_list
+
+ / DB_INSTRUMENT_DIRECTORIES SP pathname SP query_val_list
+
+
+
+move_instruction =
+
+ DB_INSTRUMENT_DIRECTORY SP pathname SP pathname
+
+ / DB_INSTRUMENT SP pathname SP pathname
+
+
+
+copy_instruction =
+
+ DB_INSTRUMENT_DIRECTORY SP pathname SP pathname
+
+ / DB_INSTRUMENT SP pathname SP pathname
+
+
+
destroy_instruction =
AUDIO_OUTPUT_DEVICE SP number
@@ -4873,6 +6343,14 @@
+modal_arg =
+
+ /* epsilon (empty argument) */
+
+ / NON_MODAL SP
+
+
+
key_val_list =
string '=' param_val_list
@@ -4911,6 +6389,14 @@
/ FX_SENDS SP sampler_channel
+ / DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname
+
+ / DB_INSTRUMENT_DIRECTORIES SP pathname
+
+ / DB_INSTRUMENTS SP RECURSIVE SP pathname
+
+ / DB_INSTRUMENTS SP pathname
+
load_instr_args =
@@ -5031,6 +6517,18 @@
+pathname =
+
+ stringval
+
+
+
+dirname =
+
+ stringval
+
+
+
filename =
stringval
@@ -5075,6 +6573,32 @@
+query_val_list =
+
+ string '=' query_val
+
+ / query_val_list SP string '=' query_val
+
+
+
+query_val =
+
+ string
+
+ / stringval
+
+
+
+scan_mode =
+
+ RECURSIVE
+
+ / NON_RECURSIVE
+
+ / FLAT
+
+
+
@@ -5191,7 +6715,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 +6785,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,7 +6834,7 @@
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
@@ -5359,6 +6921,151 @@
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 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.