16 |
to an annoying "missing Normative/Informative References" error message --> |
to an annoying "missing Normative/Informative References" error message --> |
17 |
<?rfc strict="no" ?> |
<?rfc strict="no" ?> |
18 |
|
|
19 |
<rfc category="std" ipr="full3978" docName="LSCP 1.2cvs"> |
<rfc category="std" ipr="full3978" docName="LSCP 1.2"> |
20 |
<front> |
<front> |
21 |
<title>LinuxSampler Control Protocol (draft)</title> |
<title>LinuxSampler Control Protocol</title> |
22 |
<author initials='C.S.' surname="Schoenebeck" fullname='C. |
<author initials='C.S.' surname="Schoenebeck" fullname='C. |
23 |
Schoenebeck'> |
Schoenebeck'> |
24 |
<organization> |
<organization> |
34 |
<email>schoenebeck at software minus engineering dot org</email> |
<email>schoenebeck at software minus engineering dot org</email> |
35 |
</address> |
</address> |
36 |
</author> |
</author> |
37 |
<date month="September" year="2007"/> |
<date month="October" year="2007"/> |
38 |
<workgroup>LinuxSampler Developers</workgroup> |
<workgroup>LinuxSampler Developers</workgroup> |
39 |
<keyword>LSCP</keyword> |
<keyword>LSCP</keyword> |
40 |
<abstract> |
<abstract> |
2443 |
<list> |
<list> |
2444 |
<t>DESCRIPTION - |
<t>DESCRIPTION - |
2445 |
<list> |
<list> |
2446 |
<t>arbitrary description text about the engine</t> |
<t>arbitrary description text about the engine |
2447 |
|
(note that the character string may contain |
2448 |
|
<xref target="character_set">escape sequences</xref>)</t> |
2449 |
</list> |
</list> |
2450 |
</t> |
</t> |
2451 |
<t>VERSION - |
<t>VERSION - |
2529 |
<list> |
<list> |
2530 |
<t>the file name of the loaded instrument, "NONE" if |
<t>the file name of the loaded instrument, "NONE" if |
2531 |
there's no instrument yet loaded for this sampler |
there's no instrument yet loaded for this sampler |
2532 |
channel</t> |
channel (note: since LSCP 1.2 this path may contain |
2533 |
|
<xref target="character_set">escape sequences</xref>)</t> |
2534 |
</list> |
</list> |
2535 |
</t> |
</t> |
2536 |
<t>INSTRUMENT_NR - |
<t>INSTRUMENT_NR - |
2540 |
</t> |
</t> |
2541 |
<t>INSTRUMENT_NAME - |
<t>INSTRUMENT_NAME - |
2542 |
<list> |
<list> |
2543 |
<t>the instrument name of the loaded instrument</t> |
<t>the instrument name of the loaded instrument |
2544 |
|
(note: since LSCP 1.2 this character string may contain |
2545 |
|
<xref target="character_set">escape sequences</xref>)</t> |
2546 |
</list> |
</list> |
2547 |
</t> |
</t> |
2548 |
<t>INSTRUMENT_STATUS - |
<t>INSTRUMENT_STATUS - |
3260 |
sampler channel on which the effect send should be created on, <midi-ctrl> |
sampler channel on which the effect send should be created on, <midi-ctrl> |
3261 |
is a number between 0..127 defining the MIDI controller which can alter the |
is a number between 0..127 defining the MIDI controller which can alter the |
3262 |
effect send level and <name> is an optional argument defining a name |
effect send level and <name> is an optional argument defining a name |
3263 |
for the effect send entity. The name does not have to be unique.</t> |
for the effect send entity. The name does not have to be unique, but MUST be |
3264 |
|
encapsulated into apostrophes and supports escape sequences as described in chapter |
3265 |
|
"<xref target="character_set">Character Set and Escape Sequences</xref>".</t> |
3266 |
|
|
3267 |
<t>By default, that is as initial routing, the effect send's audio channels |
<t>By default, that is as initial routing, the effect send's audio channels |
3268 |
are automatically routed to the last audio channels of the sampler channel's |
are automatically routed to the last audio channels of the sampler channel's |
3452 |
<list> |
<list> |
3453 |
<t>NAME - |
<t>NAME - |
3454 |
<list> |
<list> |
3455 |
<t>name of the effect send entity</t> |
<t>name of the effect send entity |
3456 |
|
(note that this character string may contain |
3457 |
|
<xref target="character_set">escape sequences</xref>)</t> |
3458 |
</list> |
</list> |
3459 |
</t> |
</t> |
3460 |
<t>MIDI_CONTROLLER - |
<t>MIDI_CONTROLLER - |
3517 |
as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref> |
as returned by the <xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref> |
3518 |
or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and |
or <xref target="LIST FX_SENDS">"LIST FX_SENDS"</xref> command and |
3519 |
<name> is the new name of the effect send entity, which |
<name> is the new name of the effect send entity, which |
3520 |
does not have to be unique.</t> |
does not have to be unique (name MUST be encapsulated into apostrophes |
3521 |
|
and supports escape sequences as described in chapter |
3522 |
|
"<xref target="character_set">Character Set and Escape Sequences</xref>"). |
3523 |
|
</t> |
3524 |
|
|
3525 |
<t>Possible Answers:</t> |
<t>Possible Answers:</t> |
3526 |
<t> |
<t> |
3971 |
<list> |
<list> |
3972 |
<t>DESCRIPTION - |
<t>DESCRIPTION - |
3973 |
<list> |
<list> |
3974 |
<t>arbitrary textual description about the sampler</t> |
<t>arbitrary textual description about the sampler |
3975 |
|
(note that the character string may contain |
3976 |
|
<xref target="character_set">escape sequences</xref>)</t> |
3977 |
</list> |
</list> |
3978 |
</t> |
</t> |
3979 |
<t>VERSION - |
<t>VERSION - |
4089 |
cause the sampler to switch to the respective instrument as |
cause the sampler to switch to the respective instrument as |
4090 |
reflected by the current MIDI instrument map.</t> |
reflected by the current MIDI instrument map.</t> |
4091 |
|
|
4092 |
<section title="Create a new MIDI instrument map" anchor="ADD MIDI_INSTRUMENT MAP"> |
<section title="Create a new MIDI instrument map" anchor="ADD MIDI_INSTRUMENT_MAP"> |
4093 |
<t>The front-end can add a new MIDI instrument map by sending |
<t>The front-end can add a new MIDI instrument map by sending |
4094 |
the following command:</t> |
the following command:</t> |
4095 |
<t> |
<t> |
4099 |
</t> |
</t> |
4100 |
<t>Where <name> is an optional argument allowing to |
<t>Where <name> is an optional argument allowing to |
4101 |
assign a custom name to the new map. MIDI instrument Map |
assign a custom name to the new map. MIDI instrument Map |
4102 |
names do not have to be unique.</t> |
names do not have to be unique, but MUST be encapsulated |
4103 |
|
into apostrophes and support escape sequences as described |
4104 |
|
in chapter "<xref target="character_set">Character Set and Escape Sequences</xref>". |
4105 |
|
</t> |
4106 |
|
|
4107 |
<t>Possible Answers:</t> |
<t>Possible Answers:</t> |
4108 |
<t> |
<t> |
4273 |
<t>NAME - |
<t>NAME - |
4274 |
<list> |
<list> |
4275 |
<t>custom name of the given map, |
<t>custom name of the given map, |
4276 |
which does not have to be unique</t> |
which does not have to be unique |
4277 |
|
(note that this character string may contain |
4278 |
|
<xref target="character_set">escape sequences</xref>)</t> |
4279 |
</list> |
</list> |
4280 |
</t> |
</t> |
4281 |
<t>DEFAULT - |
<t>DEFAULT - |
4311 |
</t> |
</t> |
4312 |
<t>Where <map> is the numerical ID of the map and |
<t>Where <map> is the numerical ID of the map and |
4313 |
<name> the new custom name of the map, which does not |
<name> the new custom name of the map, which does not |
4314 |
have to be unique.</t> |
have to be unique (name MUST be encapsulated into apostrophes |
4315 |
|
and supports escape sequences as described in chapter |
4316 |
|
"<xref target="character_set">Character Set and Escape Sequences</xref>"). |
4317 |
|
</t> |
4318 |
|
|
4319 |
<t>Possible Answers:</t> |
<t>Possible Answers:</t> |
4320 |
<t> |
<t> |
4445 |
load modes of entries, the frontend should retrieve the actual |
load modes of entries, the frontend should retrieve the actual |
4446 |
mode by i.e. sending |
mode by i.e. sending |
4447 |
<xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref> |
<xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref> |
4448 |
command(s). Finally the OPTIONAL <name> argument allows to |
command(s). Finally the OPTIONAL <name> argument allows to set a custom name |
4449 |
set a custom name (encapsulated into apostrophes) for the mapping |
(encapsulated into apostrophes, supporting escape sequences as described in chapter |
4450 |
entry, useful for frontends for displaying an appropriate name for |
"<xref target="character_set">Character Set and Escape Sequences</xref>") for the |
4451 |
|
mapping entry, useful for frontends for displaying an appropriate name for |
4452 |
mapped instruments (using |
mapped instruments (using |
4453 |
<xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>). |
<xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref>). |
4454 |
</t> |
</t> |
4672 |
name for this mapped instrument. It can be set and |
name for this mapped instrument. It can be set and |
4673 |
changed with the |
changed with the |
4674 |
<xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref> |
<xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref> |
4675 |
command and does not have to be unique.</t> |
command and does not have to be unique. |
4676 |
|
(note that this character string may contain |
4677 |
|
<xref target="character_set">escape sequences</xref>)</t> |
4678 |
</list> |
</list> |
4679 |
</t> |
</t> |
4680 |
<t>"ENGINE_NAME" - |
<t>"ENGINE_NAME" - |
4685 |
</t> |
</t> |
4686 |
<t>"INSTRUMENT_FILE" - |
<t>"INSTRUMENT_FILE" - |
4687 |
<list> |
<list> |
4688 |
<t>File name of the instrument.</t> |
<t>File name of the instrument |
4689 |
|
(note that this path may contain |
4690 |
|
<xref target="character_set">escape sequences</xref>).</t> |
4691 |
</list> |
</list> |
4692 |
</t> |
</t> |
4693 |
<t>"INSTRUMENT_NR" - |
<t>"INSTRUMENT_NR" - |
4699 |
<list> |
<list> |
4700 |
<t>Name of the loaded instrument as reflected by its file. |
<t>Name of the loaded instrument as reflected by its file. |
4701 |
In contrast to the "NAME" field, the "INSTRUMENT_NAME" field |
In contrast to the "NAME" field, the "INSTRUMENT_NAME" field |
4702 |
cannot be changed.</t> |
cannot be changed (note that this character string may contain |
4703 |
|
<xref target="character_set">escape sequences</xref>).</t> |
4704 |
</list> |
</list> |
4705 |
</t> |
</t> |
4706 |
<t>"LOAD_MODE" - |
<t>"LOAD_MODE" - |
5997 |
editor application by sending the following command:</t> |
editor application by sending the following command:</t> |
5998 |
<t> |
<t> |
5999 |
<list> |
<list> |
6000 |
<t>EDIT INSTRUMENT <sampler-channel></t> |
<t>EDIT CHANNEL INSTRUMENT <sampler-channel></t> |
6001 |
</list> |
</list> |
6002 |
</t> |
</t> |
6003 |
<t>Where <sampler-channel> should be replaced by the |
<t>Where <sampler-channel> should be replaced by the |
6049 |
<t>Examples:</t> |
<t>Examples:</t> |
6050 |
<t> |
<t> |
6051 |
<list> |
<list> |
6052 |
<t>C: "EDIT INSTRUMENT 0"</t> |
<t>C: "EDIT CHANNEL INSTRUMENT 0"</t> |
6053 |
<t>S: "OK"</t> |
<t>S: "OK"</t> |
6054 |
</list> |
</list> |
6055 |
</t> |
</t> |
6418 |
</t> |
</t> |
6419 |
<t>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value |
<t>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value |
6420 |
</t> |
</t> |
6421 |
<t>/ DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP raw_path |
<t>/ DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped |
6422 |
</t> |
</t> |
6423 |
<t>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP raw_path |
<t>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped |
6424 |
</t> |
</t> |
6425 |
<t>/ DB_INSTRUMENT SP NAME SP db_path SP raw_path |
<t>/ DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped |
6426 |
</t> |
</t> |
6427 |
<t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP raw_path |
<t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped |
6428 |
</t> |
</t> |
6429 |
<t>/ ECHO SP boolean |
<t>/ ECHO SP boolean |
6430 |
</t> |
</t> |
6542 |
</t> |
</t> |
6543 |
<t>edit_instruction = |
<t>edit_instruction = |
6544 |
<list> |
<list> |
6545 |
<t>INSTRUMENT SP sampler_channel |
<t>CHANNEL SP INSTRUMENT SP sampler_channel |
6546 |
</t> |
</t> |
6547 |
</list> |
</list> |
6548 |
</t> |
</t> |
6740 |
</t> |
</t> |
6741 |
<t>map_name = |
<t>map_name = |
6742 |
<list> |
<list> |
6743 |
<t>stringval |
<t>stringval_escaped |
6744 |
</t> |
</t> |
6745 |
</list> |
</list> |
6746 |
</t> |
</t> |
6747 |
<t>entry_name = |
<t>entry_name = |
6748 |
<list> |
<list> |
6749 |
<t>stringval |
<t>stringval_escaped |
6750 |
</t> |
</t> |
6751 |
</list> |
</list> |
6752 |
</t> |
</t> |
6753 |
<t>fx_send_name = |
<t>fx_send_name = |
6754 |
<list> |
<list> |
6755 |
<t>stringval |
<t>stringval_escaped |
6756 |
</t> |
</t> |
6757 |
</list> |
</list> |
6758 |
</t> |
</t> |
6787 |
</t> |
</t> |
6788 |
<t>query_val = |
<t>query_val = |
6789 |
<list> |
<list> |
6790 |
<t>raw_path_base |
<t>text_escaped |
6791 |
</t> |
</t> |
6792 |
<t>/ raw_path |
<t>/ stringval_escaped |
6793 |
</t> |
</t> |
6794 |
</list> |
</list> |
6795 |
</t> |
</t> |
6836 |
where escape characters are now supported, a backslash characters |
where escape characters are now supported, a backslash characters |
6837 |
MUST be escaped as well (that is as double backslash), whereas |
MUST be escaped as well (that is as double backslash), whereas |
6838 |
in the old versions a single backslash was sufficient.</t> |
in the old versions a single backslash was sufficient.</t> |
6839 |
|
|
6840 |
|
<t>The following LSCP commands support escape sequences as part |
6841 |
|
of their filename / path based arguments and / or may contain |
6842 |
|
a filename / path with escape sequences in their response: |
6843 |
|
<list> |
6844 |
|
<t><xref target="LOAD INSTRUMENT">"LOAD INSTRUMENT"</xref></t> |
6845 |
|
<t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t> |
6846 |
|
<t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t> |
6847 |
|
<t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t> |
6848 |
|
<t><xref target="ADD DB_INSTRUMENT_DIRECTORY">"ADD DB_INSTRUMENT_DIRECTORY"</xref></t> |
6849 |
|
<t><xref target="ADD DB_INSTRUMENTS">"ADD DB_INSTRUMENTS"</xref></t> |
6850 |
|
<t><xref target="REMOVE DB_INSTRUMENT_DIRECTORY">"REMOVE DB_INSTRUMENT_DIRECTORY"</xref></t> |
6851 |
|
<t><xref target="REMOVE DB_INSTRUMENT">"REMOVE DB_INSTRUMENT"</xref></t> |
6852 |
|
<t><xref target="GET DB_INSTRUMENT_DIRECTORIES">"GET DB_INSTRUMENT_DIRECTORIES"</xref></t> |
6853 |
|
<t><xref target="LIST DB_INSTRUMENT_DIRECTORIES">"LIST DB_INSTRUMENT_DIRECTORIES"</xref></t> |
6854 |
|
<t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t> |
6855 |
|
<t><xref target="GET DB_INSTRUMENTS">"GET DB_INSTRUMENTS"</xref></t> |
6856 |
|
<t><xref target="LIST DB_INSTRUMENTS">"LIST DB_INSTRUMENTS"</xref></t> |
6857 |
|
<t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t> |
6858 |
|
<t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t> |
6859 |
|
<t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t> |
6860 |
|
<t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t> |
6861 |
|
<t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t> |
6862 |
|
<t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t> |
6863 |
|
<t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t> |
6864 |
|
<t><xref target="MOVE DB_INSTRUMENT">"MOVE DB_INSTRUMENT"</xref></t> |
6865 |
|
<t><xref target="MOVE DB_INSTRUMENT_DIRECTORY">"MOVE DB_INSTRUMENT_DIRECTORY"</xref></t> |
6866 |
|
<t><xref target="COPY DB_INSTRUMENT">"COPY DB_INSTRUMENT"</xref></t> |
6867 |
|
<t><xref target="COPY DB_INSTRUMENT_DIRECTORY">"COPY DB_INSTRUMENT_DIRECTORY"</xref></t> |
6868 |
|
</list> |
6869 |
|
Note that the forward slash character ('/') has a special meaning in |
6870 |
|
filename / path based arguments: it acts as separator of the nodes in |
6871 |
|
the path, thus if a directory- or filename includes a forward slash |
6872 |
|
(not intended as path node separator), you MUST escape that slash |
6873 |
|
either with the respective hex escape sequence ("\x2f") or with the |
6874 |
|
respective octal escape sequence ("\057"). |
6875 |
|
</t> |
6876 |
|
|
6877 |
|
<t> |
6878 |
|
The following LSCP commands even support escape sequences as |
6879 |
|
part of at least one of their text-based arguments (i.e. entity name, |
6880 |
|
description) and / or may contain escape sequences in at least one of |
6881 |
|
their text-based fields in their response: |
6882 |
|
<list> |
6883 |
|
<t><xref target="GET SERVER INFO">"GET SERVER INFO"</xref></t> |
6884 |
|
<t><xref target="GET ENGINE INFO">"GET ENGINE INFO"</xref></t> |
6885 |
|
<t><xref target="GET CHANNEL INFO">"GET CHANNEL INFO"</xref></t> |
6886 |
|
<t><xref target="CREATE FX_SEND">"CREATE FX_SEND"</xref></t> |
6887 |
|
<t><xref target="GET FX_SEND INFO">"GET FX_SEND INFO"</xref></t> |
6888 |
|
<t><xref target="SET FX_SEND NAME">"SET FX_SEND NAME"</xref></t> |
6889 |
|
<t><xref target="GET MIDI_INSTRUMENT INFO">"GET MIDI_INSTRUMENT INFO"</xref></t> |
6890 |
|
<t><xref target="GET MIDI_INSTRUMENT_MAP INFO">"GET MIDI_INSTRUMENT_MAP INFO"</xref></t> |
6891 |
|
<t><xref target="ADD MIDI_INSTRUMENT_MAP">"ADD MIDI_INSTRUMENT_MAP"</xref></t> |
6892 |
|
<t><xref target="MAP MIDI_INSTRUMENT">"MAP MIDI_INSTRUMENT"</xref></t> |
6893 |
|
<t><xref target="SET MIDI_INSTRUMENT_MAP NAME">"SET MIDI_INSTRUMENT_MAP NAME"</xref></t> |
6894 |
|
<t><xref target="GET DB_INSTRUMENT_DIRECTORY INFO">"GET DB_INSTRUMENT_DIRECTORY INFO"</xref></t> |
6895 |
|
<t><xref target="SET DB_INSTRUMENT_DIRECTORY NAME">"SET DB_INSTRUMENT_DIRECTORY NAME"</xref></t> |
6896 |
|
<t><xref target="SET DB_INSTRUMENT_DIRECTORY DESCRIPTION">"SET DB_INSTRUMENT_DIRECTORY DESCRIPTION"</xref></t> |
6897 |
|
<t><xref target="FIND DB_INSTRUMENT_DIRECTORIES">"FIND DB_INSTRUMENT_DIRECTORIES"</xref></t> |
6898 |
|
<t><xref target="GET DB_INSTRUMENT INFO">"GET DB_INSTRUMENT INFO"</xref></t> |
6899 |
|
<t><xref target="SET DB_INSTRUMENT NAME">"SET DB_INSTRUMENT NAME"</xref></t> |
6900 |
|
<t><xref target="SET DB_INSTRUMENT DESCRIPTION">"SET DB_INSTRUMENT DESCRIPTION"</xref></t> |
6901 |
|
<t><xref target="FIND DB_INSTRUMENTS">"FIND DB_INSTRUMENTS"</xref></t> |
6902 |
|
</list> |
6903 |
|
Please note that these lists are manually maintained. If you |
6904 |
|
find a command that also supports escape sequences we forgot to |
6905 |
|
mention here, please report it! |
6906 |
|
</t> |
6907 |
</section> |
</section> |
6908 |
</section> |
</section> |
6909 |
|
|