--- linuxsampler/trunk/Documentation/lscp.xml 2007/10/07 10:32:53 1387
+++ linuxsampler/trunk/Documentation/lscp.xml 2007/10/11 18:53:29 1399
@@ -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,8 +3971,8 @@
DESCRIPTION -
- arbitrary textual description about the sampler
- (note that the character string may contain
+ arbitrary textual description about the sampler
+ (note that the character string may contain
escape sequences)
@@ -4077,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:
@@ -4087,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:
@@ -4258,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 -
@@ -4294,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:
@@ -4652,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" -
@@ -4663,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" -
@@ -4675,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" -
@@ -6393,13 +6418,13 @@
/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
- / DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP raw_path
+ / DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped
- / DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP raw_path
+ / DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped
- / DB_INSTRUMENT SP NAME SP db_path SP raw_path
+ / DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped
- / DB_INSTRUMENT SP DESCRIPTION SP db_path SP raw_path
+ / DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
/ ECHO SP boolean
@@ -6715,19 +6740,19 @@
map_name =
- stringval
+ stringval_escaped
entry_name =
- stringval
+ stringval_escaped
fx_send_name =
- stringval
+ stringval_escaped
@@ -6762,9 +6787,9 @@
query_val =
- raw_path_base
+ text_escaped
- / raw_path
+ / stringval_escaped
@@ -6811,6 +6836,72 @@
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"
+ "SET DB_INSTRUMENT_DIRECTORY NAME"
+ "SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"
+ "FIND DB_INSTRUMENT_DIRECTORIES"
+ "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!
+