--- web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.html 2007/06/22 14:24:57 1251 +++ web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.html 2007/09/30 21:51:14 1363 @@ -145,7 +145,7 @@
-This Internet-Draft will expire on December 24, 2007.
+This Internet-Draft will expire on March 4, 2008.
@@ -432,6 +432,12 @@
Finding instruments
6.8.21.
Getting job status information
+ 6.8.22.
+Formatting the instruments database
+ 6.9.
+Editing Instruments
+ 6.9.1.
+Opening an appropriate instrument editor application
7.
Command Syntax
7.1.
@@ -3301,7 +3307,8 @@
or "LIST MIDI_INPUT_DEVICES" (Getting all created MIDI input device list)
command, <port> by the MIDI port number, <key> by the name of
the parameter to change and <value> by the new value for this
- parameter.
+ parameter (encapsulated into apostrophes) or NONE (not encapsulated into apostrophes)
+ for specifying no value for parameters allowing a list of values.
Possible Answers:
@@ -3342,7 +3349,19 @@
+C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='20:0'" +
+S: "OK" +
+
+ +
+
++C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE" +
+S: "OK"
@@ -7247,6 +7266,23 @@
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 (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. + +
+
+ +
TOC |
DESCRIPTION -
-@@ -7757,7 +7795,9 @@A brief description of the directory content +
A brief description of the directory content. + Note that the character string may contain + escape sequences (Character Set and Escape Sequences).
Where <dir> is the absolute path name of the directory and - <desc> is the new description for the directory. + <desc> is the new description for the directory + (encapsulated into apostrophes, supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)").
Possible Answers:
@@ -7824,7 +7864,9 @@Restricts the search to directories, which names - satisfy the supplied search string. + satisfy the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)").
@@ -7867,7 +7909,10 @@
Restricts the search to directories with description - that satisfies the supplied search string. + that satisfies the supplied search string + (encapsulated into apostrophes, supporting escape + sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)").
@@ -8248,6 +8293,8 @@
@@ -8307,7 +8354,9 @@File name of the instrument. + Note that the character string may contain + escape sequences (Character Set and Escape Sequences).
DESCRIPTION -
-@@ -8324,7 +8373,9 @@A brief description of the instrument +
A brief description of the instrument. + Note that the character string may contain + escape sequences (Character Set and Escape Sequences).
PRODUCT -
-@@ -8332,7 +8383,9 @@The product title of the instrument +
The product title of the instrument. + Note that the character string may contain + escape sequences (Character Set and Escape Sequences).
ARTISTS -
-@@ -8342,6 +8395,8 @@Lists the artist names +
Lists the artist names. + Note that the character string may contain + escape sequences (Character Set and Escape Sequences).
@@ -8582,7 +8637,9 @@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 (Character Set and Escape Sequences).
Where <instr> is the absolute path name of the instrument and - <desc> is the new description for the instrument. + <desc> is the new description for the instrument + (encapsulated into apostrophes, supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)").
Possible Answers:
@@ -8649,7 +8706,9 @@Restricts the search to instruments, which names - satisfy the supplied search string. + satisfy the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)").
@@ -8707,7 +8766,9 @@
Restricts the search to instruments with description - that satisfies the supplied search string. + that satisfies the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)").
@@ -8718,7 +8779,9 @@
Restricts the search to instruments with product info - that satisfies the supplied search string. + that satisfies the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)").
@@ -8729,7 +8792,9 @@
Restricts the search to instruments with artists info - that satisfies the supplied search string. + that satisfies the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)").
@@ -8740,7 +8805,9 @@
Restricts the search to instruments with keyword list - that satisfies the supplied search string. + that satisfies the supplied search string (encapsulated into apostrophes, + supporting escape sequences as described in chapter + "Character Set and Escape Sequences (Character Set and Escape Sequences)").
@@ -8910,6 +8977,149 @@
+
TOC |
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. +
+
+ +
+TOC |
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. +
+TOC |
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" (Adding a new sampler channel) + or "LIST CHANNELS" (Getting all created sampler channel list) + 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" +
+
+ +
TOC |
/ EDIT SP edit_instruction
+/ FORMAT SP format_instruction + +
/ RESET
@@ -9043,25 +9256,25 @@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 @@ -9262,13 +9475,13 @@
/ 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
@@ -9376,22 +9589,22 @@
/ 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 @@ -9415,6 +9628,9 @@
/ 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
@@ -9436,16 +9652,16 @@/ 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 @@ -9505,16 +9721,16 @@
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
@@ -9523,10 +9739,10 @@
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
@@ -9535,10 +9751,10 @@
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
@@ -9628,6 +9844,15 @@
+
format_instruction = +
++INSTRUMENTS_DB + +
+
+ +
modal_arg =
@@ -9697,16 +9922,16 @@/ 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
@@ -9889,28 +10114,19 @@
-
pathname = -
--stringval - -
-
- -
-dirname = +
filename =
-stringval +
path
-
filename = +
db_path =
-stringval_escaped +
path
@@ -9988,10 +10204,10 @@
query_val =
-string +
textval_escaped
-/ stringval +
/ stringval_escaped
@@ -10943,3 +11159,4 @@ Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA).