--- linuxsampler/trunk/Documentation/lscp.xml 2007/03/29 10:01:50 1136
+++ linuxsampler/trunk/Documentation/lscp.xml 2007/04/16 15:51:18 1161
@@ -34,7 +34,7 @@
schoenebeck at software minus engineering dot org
-
+
LinuxSampler Developers
LSCP
@@ -3959,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.
+
+
@@ -4734,6 +4740,734 @@
+
+
+ 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 <dir>
+
+
+ Where <dir> should be replaced by the absolute path
+ name of the directory.
+
+ 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 <dir>
+
+
+ Where <dir> should be replaced by the absolute path
+ name of the directory.
+
+ 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'"
+
+
+
+
+
+ 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 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 add one or more instruments
+ to the instruments database by sending the following command:
+
+
+ ADD DB_INSTRUMENTS [<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:
+
+
+ "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.
+
+
+ not supplied -
+
+ The subdirectory tree structure will be recreated
+ in the instruments database and all instruments will be
+ processed and added to the respective subdirectory
+ in the instruments database.
+
+
+
+
+
+ Possible Answers:
+
+
+ "OK" -
+
+ on success
+
+
+ "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 <dir>
+
+
+ Where <dir> should be replaced by the absolute path name
+ of the directory.
+
+ 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 <dir>
+
+
+ Where <dir> should be replaced by the absolute path
+ name of the directory.
+
+ 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'"
+
+
+
+
+
+ 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 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"
+
+
+
+
+
+
@@ -4809,12 +5543,12 @@
/ UNSUBSCRIBE SP unsubscribe_event
- / SELECT SP text
-
/ RESET SP reset_instruction
/ CLEAR SP clear_instruction
+ / MOVE SP move_instruction
+
/ RESET
/ QUIT
@@ -4825,6 +5559,16 @@
CHANNEL
+ / DB_INSTRUMENT_DIRECTORY SP pathname
+
+ / DB_INSTRUMENTS SP FLAT SP pathname SP pathname
+
+ / DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP pathname
+
+ / DB_INSTRUMENTS SP pathname SP pathname
+
+ / DB_INSTRUMENTS SP pathname SP pathname SP instrument_index
+
/ MIDI_INSTRUMENT_MAP
/ MIDI_INSTRUMENT_MAP SP map_name
@@ -4863,6 +5607,14 @@
/ MIDI_INSTRUMENT_INFO
+ / DB_INSTRUMENT_DIRECTORY_COUNT
+
+ / DB_INSTRUMENT_DIRECTORY_INFO
+
+ / DB_INSTRUMENT_COUNT
+
+ / DB_INSTRUMENT_INFO
+
/ MISCELLANEOUS
/ TOTAL_VOICE_COUNT
@@ -4903,6 +5655,14 @@
/ MIDI_INSTRUMENT_INFO
+ / DB_INSTRUMENT_DIRECTORY_COUNT
+
+ / DB_INSTRUMENT_DIRECTORY_INFO
+
+ / DB_INSTRUMENT_COUNT
+
+ / DB_INSTRUMENT_INFO
+
/ MISCELLANEOUS
/ TOTAL_VOICE_COUNT
@@ -4937,6 +5697,12 @@
/ MIDI_INSTRUMENT_MAP SP ALL
+ / DB_INSTRUMENT_DIRECTORY SP FORCE SP pathname
+
+ / DB_INSTRUMENT_DIRECTORY SP pathname
+
+ / DB_INSTRUMENT SP pathname
+
get_instruction =
@@ -5007,6 +5773,14 @@
/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
+ / DB_INSTRUMENT_DIRECTORIES SP pathname
+
+ / DB_INSTRUMENT_DIRECTORY SP INFO SP pathname
+
+ / DB_INSTRUMENTS SP pathname
+
+ / DB_INSTRUMENT SP INFO SP pathname
+
/ VOLUME
@@ -5033,6 +5807,14 @@
/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
+ / DB_INSTRUMENT_DIRECTORY SP NAME SP pathname SP dirname
+
+ / DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP pathname SP stringval
+
+ / DB_INSTRUMENT SP NAME SP pathname SP dirname
+
+ / DB_INSTRUMENT SP DESCRIPTION SP pathname SP stringval
+
/ ECHO SP boolean
/ VOLUME SP volume_value
@@ -5069,6 +5851,14 @@
+move_instruction =
+
+ DB_INSTRUMENT_DIRECTORY SP pathname SP pathname
+
+ / DB_INSTRUMENT SP pathname SP pathname
+
+
+
destroy_instruction =
AUDIO_OUTPUT_DEVICE SP number
@@ -5165,6 +5955,10 @@
/ FX_SENDS SP sampler_channel
+ / DB_INSTRUMENT_DIRECTORIES SP pathname
+
+ / DB_INSTRUMENTS SP pathname
+
load_instr_args =
@@ -5285,6 +6079,18 @@
+pathname =
+
+ stringval
+
+
+
+dirname =
+
+ stringval
+
+
+
filename =
stringval
@@ -5672,6 +6478,110 @@
+
+ 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 of miscellaneous and debugging events occurring at
the server by issuing the following command: