--- linuxsampler/trunk/Documentation/lscp.xml 2007/09/17 23:15:25 1353
+++ linuxsampler/trunk/Documentation/lscp.xml 2007/10/11 20:45:49 1401
@@ -34,7 +34,7 @@
schoenebeck at software minus engineering dot org
-
+
LinuxSampler Developers
LSCP
@@ -2443,7 +2443,9 @@
DESCRIPTION -
- arbitrary description text about the engine
+ arbitrary description text about the engine
+ (note that the character string may contain
+ escape sequences)
VERSION -
@@ -2527,7 +2529,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 -
@@ -2537,7 +2540,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 -
@@ -3255,7 +3260,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
@@ -3445,7 +3452,9 @@
NAME -
- name of the effect send entity
+ name of the effect send entity
+ (note that this character string may contain
+ escape sequences)
MIDI_CONTROLLER -
@@ -3508,7 +3517,10 @@
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.
+ 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:
@@ -3959,7 +3971,9 @@
DESCRIPTION -
- arbitrary textual description about the sampler
+ arbitrary textual description about the sampler
+ (note that the character string may contain
+ escape sequences)
VERSION -
@@ -4075,7 +4089,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:
@@ -4085,7 +4099,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:
@@ -4256,7 +4273,9 @@
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 -
@@ -4292,7 +4311,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:
@@ -4423,9 +4445,10 @@
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").
@@ -4649,7 +4672,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" -
@@ -4660,7 +4685,9 @@
"INSTRUMENT_FILE" -
- File name of the instrument.
+ File name of the instrument
+ (note that this path may contain
+ escape sequences).
"INSTRUMENT_NR" -
@@ -4672,7 +4699,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" -
@@ -4759,11 +4787,11 @@
The following commands describe how to use and manage
- the instruments database.
+ the instruments database.
Notice:
- All command arguments representing a path or
+ All command arguments representing a path or
instrument/directory name support escape sequences as described in chapter
"Character Set and Escape Sequences".
@@ -4949,8 +4977,8 @@
DESCRIPTION -
- A brief description of the directory content.
- Note that the character string may contain
+ A brief description of the directory content.
+ Note that the character string may contain
escape sequences.
@@ -5162,7 +5190,7 @@
NAME='<search-string>'
Restricts the search to directories, which names
- satisfy the supplied search string (encapsulated into apostrophes,
+ satisfy the supplied search string (encapsulated into apostrophes,
supporting escape sequences as described in chapter
"Character Set and Escape Sequences").
@@ -5196,7 +5224,7 @@
Restricts the search to directories with description
that satisfies the supplied search string
- (encapsulated into apostrophes, supporting escape
+ (encapsulated into apostrophes, supporting escape
sequences as described in chapter
"Character Set and Escape Sequences").
@@ -5459,8 +5487,8 @@
INSTRUMENT_FILE -
- File name of the instrument.
- Note that the character string may contain
+ File name of the instrument.
+ Note that the character string may contain
escape sequences.
@@ -5500,8 +5528,8 @@
DESCRIPTION -
- A brief description of the instrument.
- Note that the character string may contain
+ A brief description of the instrument.
+ Note that the character string may contain
escape sequences.
@@ -5513,23 +5541,23 @@
PRODUCT -
- The product title of the instrument.
- Note that the character string may contain
+ 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
+ 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
+ Keywords are separated with semicolon and blank.
+ Note that the character string may contain
escape sequences.
@@ -5734,7 +5762,7 @@
NAME='<search-string>'
Restricts the search to instruments, which names
- satisfy the supplied search string (encapsulated into apostrophes,
+ satisfy the supplied search string (encapsulated into apostrophes,
supporting escape sequences as described in chapter
"Character Set and Escape Sequences").
@@ -5778,7 +5806,7 @@
DESCRIPTION='<search-string>'
Restricts the search to instruments with description
- that satisfies the supplied search string (encapsulated into apostrophes,
+ that satisfies the supplied search string (encapsulated into apostrophes,
supporting escape sequences as described in chapter
"Character Set and Escape Sequences").
@@ -5787,7 +5815,7 @@
PRODUCT='<search-string>'
Restricts the search to instruments with product info
- that satisfies the supplied search string (encapsulated into apostrophes,
+ that satisfies the supplied search string (encapsulated into apostrophes,
supporting escape sequences as described in chapter
"Character Set and Escape Sequences").
@@ -5796,7 +5824,7 @@
ARTISTS='<search-string>'
Restricts the search to instruments with artists info
- that satisfies the supplied search string (encapsulated into apostrophes,
+ that satisfies the supplied search string (encapsulated into apostrophes,
supporting escape sequences as described in chapter
"Character Set and Escape Sequences").
@@ -5805,7 +5833,7 @@
KEYWORDS='<search-string>'
Restricts the search to instruments with keyword list
- that satisfies the supplied search string (encapsulated into apostrophes,
+ that satisfies the supplied search string (encapsulated into apostrophes,
supporting escape sequences as described in chapter
"Character Set and Escape Sequences").
@@ -5923,7 +5951,7 @@
The front-end can remove all instruments and directories and re-create
- the instruments database structure (e.g., in case of a database corruption)
+ the instruments database structure (e.g., in case of a database corruption)
by sending the following command:
@@ -5951,6 +5979,82 @@
+
+
+
+ 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 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 INSTRUMENT 0"
+ S: "OK"
+
+
+
+
@@ -6038,6 +6142,8 @@
/ EDIT SP edit_instruction
+ / FORMAT SP format_instruction
+
/ RESET
/ QUIT
@@ -6048,19 +6154,19 @@
CHANNEL
- / DB_INSTRUMENT_DIRECTORY SP pathname
+ / DB_INSTRUMENT_DIRECTORY SP db_path
- / DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP pathname SP pathname
+ / DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename
- / DB_INSTRUMENTS SP scan_mode SP pathname SP pathname
+ / DB_INSTRUMENTS SP scan_mode SP db_path SP filename
- / DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname
+ / DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
- / DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname SP instrument_index
+ / DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index
- / DB_INSTRUMENTS SP pathname SP pathname
+ / DB_INSTRUMENTS SP db_path SP filename
- / DB_INSTRUMENTS SP pathname SP pathname SP instrument_index
+ / DB_INSTRUMENTS SP db_path SP filename SP instrument_index
/ MIDI_INSTRUMENT_MAP
@@ -6194,11 +6300,11 @@
/ MIDI_INSTRUMENT_MAP SP ALL
- / DB_INSTRUMENT_DIRECTORY SP FORCE SP pathname
+ / DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path
- / DB_INSTRUMENT_DIRECTORY SP pathname
+ / DB_INSTRUMENT_DIRECTORY SP db_path
- / DB_INSTRUMENT SP pathname
+ / DB_INSTRUMENT SP db_path
@@ -6270,17 +6376,17 @@
/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
- / DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname
+ / DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
- / DB_INSTRUMENT_DIRECTORIES SP pathname
+ / DB_INSTRUMENT_DIRECTORIES SP db_path
- / DB_INSTRUMENT_DIRECTORY SP INFO SP pathname
+ / DB_INSTRUMENT_DIRECTORY SP INFO SP db_path
- / DB_INSTRUMENTS SP RECURSIVE SP pathname
+ / DB_INSTRUMENTS SP RECURSIVE SP db_path
- / DB_INSTRUMENTS SP pathname
+ / DB_INSTRUMENTS SP db_path
- / DB_INSTRUMENT SP INFO SP pathname
+ / DB_INSTRUMENT SP INFO SP db_path
/ DB_INSTRUMENTS_JOB SP INFO SP number
@@ -6312,13 +6418,13 @@
/ 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 NAME SP db_path SP stringval_escaped
- / DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP pathname SP stringval
+ / DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped
- / DB_INSTRUMENT SP NAME SP pathname SP dirname
+ / DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped
- / DB_INSTRUMENT SP DESCRIPTION SP pathname SP stringval
+ / DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
/ ECHO SP boolean
@@ -6358,29 +6464,29 @@
find_instruction =
- DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP query_val_list
+ DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list
- / DB_INSTRUMENTS SP pathname SP query_val_list
+ / DB_INSTRUMENTS SP db_path SP query_val_list
- / DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP pathname SP query_val_list
+ / DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP query_val_list
- / DB_INSTRUMENT_DIRECTORIES SP pathname SP query_val_list
+ / DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
move_instruction =
- DB_INSTRUMENT_DIRECTORY SP pathname SP pathname
+ DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
- / DB_INSTRUMENT SP pathname SP pathname
+ / DB_INSTRUMENT SP db_path SP db_path
copy_instruction =
- DB_INSTRUMENT_DIRECTORY SP pathname SP pathname
+ DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
- / DB_INSTRUMENT SP pathname SP pathname
+ / DB_INSTRUMENT SP db_path SP db_path
@@ -6440,6 +6546,12 @@
+format_instruction =
+
+ INSTRUMENTS_DB
+
+
+
modal_arg =
/* epsilon (empty argument) */
@@ -6486,13 +6598,13 @@
/ FX_SENDS SP sampler_channel
- / DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname
+ / DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
- / DB_INSTRUMENT_DIRECTORIES SP pathname
+ / DB_INSTRUMENT_DIRECTORIES SP db_path
- / DB_INSTRUMENTS SP RECURSIVE SP pathname
+ / DB_INSTRUMENTS SP RECURSIVE SP db_path
- / DB_INSTRUMENTS SP pathname
+ / DB_INSTRUMENTS SP db_path
@@ -6614,39 +6726,33 @@
-pathname =
+filename =
- stringval
+ path
-dirname =
+db_path =
- stringval
-
-
-
-filename =
-
- stringval_escaped
+ path
map_name =
- stringval
+ stringval_escaped
entry_name =
- stringval
+ stringval_escaped
fx_send_name =
- stringval
+ stringval_escaped
@@ -6658,6 +6764,7 @@
+
param_val =
string
@@ -6680,9 +6787,9 @@
query_val =
- string
+ text_escaped
- / stringval
+ / stringval_escaped
@@ -6729,6 +6836,74 @@
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"
+
+ 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").
+
+
+
+ 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!
+