--- linuxsampler/trunk/Documentation/lscp.xml 2005/05/21 20:01:32 561
+++ linuxsampler/trunk/Documentation/lscp.xml 2005/05/23 17:41:34 571
@@ -37,10 +37,10 @@
The LinuxSampler Control Protocol (LSCP) is an
application-level protocol primarily intended for local and
- remote controlling the LinuxSampler main application, which is a
- sophisticated console application essentially playing back audio
- samples and manipulating the samples in real time to certain
- extent.
+ remote controlling the LinuxSampler backend application, which is a
+ sophisticated server-like console application essentially playing
+ back audio samples and manipulating the samples in real time to
+ certain extent.
@@ -112,6 +112,43 @@
return and line feed characters respectively.
+
+ LSCP will certainly be extended and enhanced by-and-by. Each official
+ release of the LSCP specification will be tagged with a unique version
+ tuple. The version tuple consists at least of a major and minor version
+ number like:
+
+
+
+ "1.2"
+
+
+
+ In this example the major version number would be "1" and the minor
+ version number would be "2". Note that the version tuple might also
+ have more than two elements. The major version number defines a
+ group of backward compatible versions. That means a frontend is
+ compatible to the connected sampler if and only if the LSCP versions
+ to which each of the two parties complies to, match both of the
+ following rule:
+
+ Compatibility:
+
+
+ The frontend's LSCP major version and the sampler's LSCP
+ major version are exactly equal.
+ The frontend's LSCP minor version is less or equal than
+ the sampler's LSCP minor version.
+
+
+
+ Compatibility can only be claimed if both rules are true.
+ The frontend can use the
+ "GET SERVER INFO" command to
+ get the version of the LSCP specification the sampler complies with.
+
+
+
LinuxSampler is a so called software sampler application
capable to playback audio samples from a computer's Random
@@ -124,7 +161,7 @@
arbitrary MIDI input method and arbitrary MIDI channel (e.g.
sampler channel 17 could be connected to an ALSA sequencer
device 64:0 and listening to MIDI channel 1 there). Each sampler
- engine will be assigned an own instance of one of the available
+ channel will be associated with an instance of one of the available
sampler engines (e.g. GigEngine, DLSEngine). The audio output of
each sampler channel can be routed to an arbitrary audio output
method (ALSA / JACK) and an arbitrary audio output channel
@@ -154,7 +191,8 @@
methods will be described next.
- This simple communication method is based on TCP. The
+ This simple communication method is based on
+ TCP. The
front-end application establishes a TCP connection to the
LinuxSampler instance on a certain host system. Then the
front-end application will send certain ASCII based commands
@@ -796,7 +834,9 @@
Where <audio-output-driver> should be replaced by the desired audio
- output system and <param-list> by an optional list of driver
+ output system as returned by the
+ "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"
+ command and <param-list> by an optional list of driver
specific parameters in form of "key1=val1 key2=val2 ...", where
character string values should be encapsulated into apostrophes (').
Note that there might be drivers which require parameter(s) to be
@@ -1017,7 +1057,10 @@
Where <device-id> should be replaced by the numerical ID of the
- audio output device, <key> by the name of the parameter to change
+ audio output device as given by the
+ "CREATE AUDIO_OUTPUT_DEVICE"
+ or "LIST AUDIO_OUTPUT_DEVICES"
+ command, <key> by the name of the parameter to change
and <value> by the new value for this parameter.
Possible Answers:
@@ -1058,8 +1101,10 @@
GET AUDIO_OUTPUT_CHANNEL INFO <device-id> <audio-chan>
- Where <device-id> is the numerical ID of the audio output device
- and <audio-chan> the audio channel number.
+ Where <device-id> is the numerical ID of the audio output device as given by the
+ "CREATE AUDIO_OUTPUT_DEVICE"
+ or "LIST AUDIO_OUTPUT_DEVICES"
+ command and <audio-chan> the audio channel number.
Possible Answers:
@@ -1158,8 +1203,9 @@
- Where <dev-id> is the numerical ID of the audio output device as returned
- by the "LIST AUDIO_OUTPUT_DEVICES"
+ Where <dev-id> is the numerical ID of the audio output device as returned by the
+ "CREATE AUDIO_OUTPUT_DEVICE"
+ or "LIST AUDIO_OUTPUT_DEVICES"
command, <chan> the audio channel number
and <param> a specific channel parameter name for which information should
be obtained (as returned by the
@@ -1261,8 +1307,10 @@
SET AUDIO_OUTPUT_CHANNEL_PARAMETER <dev-id> <chn> <key>=<value>
- Where <dev-id> should be replaced by the numerical ID of the audio
- device, <chn> by the audio channel number, <key> by the name of the
+ Where <dev-id> should be replaced by the numerical ID of the audio output device as returned by the
+ "CREATE AUDIO_OUTPUT_DEVICE"
+ or "LIST AUDIO_OUTPUT_DEVICES"
+ command, <chn> by the audio channel number, <key> by the name of the
parameter to change and <value> by the new value for this parameter.
Possible Answers:
@@ -1386,7 +1434,9 @@
GET MIDI_INPUT_DRIVER INFO <midi-input-driver>
- Where <midi-input-driver> is the name of the MIDI input driver.
+ Where <midi-input-driver> is the name of the MIDI input driver as returned
+ by the
+ "LIST AVAILABLE_MIDI_INPUT_DRIVERS" command.
Possible Answers:
@@ -1596,7 +1646,9 @@
- Where <midi-input-driver> should be replaced by the desired MIDI input system and <param-list> by an
+ Where <midi-input-driver> should be replaced by the desired MIDI input system as returned
+ by the
+ "LIST AVAILABLE_MIDI_INPUT_DRIVERS" command and <param-list> by an
optional list of driver specific parameters in form of "key1=val1 key2=val2 ...", where
character string values should be encapsulated into apostrophes (').
Note that there might be drivers which require parameter(s) to be
@@ -1643,7 +1695,10 @@
DESTROY MIDI_INPUT_DEVICE <device-id>
- Where <device-id> should be replaced by the device's numerical ID.
+ Where <device-id> should be replaced by the device's numerical ID as returned by the
+ "CREATE MIDI_INPUT_DEVICE"
+ or "LIST MIDI_INPUT_DEVICES"
+ command.
Possible Answers:
@@ -1735,7 +1790,10 @@
GET MIDI_INPUT_DEVICE INFO <device-id>
- Where <device-id> is the numerical ID of the MIDI input device.
+ Where <device-id> is the numerical ID of the MIDI input device as returned by the
+ "CREATE MIDI_INPUT_DEVICE"
+ or "LIST MIDI_INPUT_DEVICES"
+ command.
Possible Answers:
@@ -1800,7 +1858,10 @@
Where <device-id> should be replaced by the numerical ID of the
- MIDI input device, <key> by the name of the parameter to change and
+ MIDI input device as returned by the
+ "CREATE MIDI_INPUT_DEVICE"
+ or "LIST MIDI_INPUT_DEVICES"
+ command, <key> by the name of the parameter to change and
<value> by the new value for this parameter.
Possible Answers:
@@ -1841,8 +1902,10 @@
GET MIDI_INPUT_PORT INFO <device-id> <midi-port>
- Where <device-id> is the numerical ID of the MIDI input device
- and <midi-port> the MIDI input port number.
+ Where <device-id> is the numerical ID of the MIDI input device as returned by the
+ "CREATE MIDI_INPUT_DEVICE"
+ or "LIST MIDI_INPUT_DEVICES"
+ command and <midi-port> the MIDI input port number.
Possible Answers:
@@ -1884,9 +1947,10 @@
- Where <dev-id> is the numerical ID of the MIDI input device as returned
- by the
- "LIST MIDI_INPUT_DEVICES" command, <port> the MIDI port number and
+ Where <dev-id> is the numerical ID of the MIDI input device as returned by the
+ "CREATE MIDI_INPUT_DEVICE"
+ or "LIST MIDI_INPUT_DEVICES"
+ command, <port> the MIDI port number and
<param> a specific port parameter name for which information should be
obtained (as returned by the
"GET MIDI_INPUT_PORT INFO" command).
@@ -1989,7 +2053,10 @@
Where <device-id> should be replaced by the numerical ID of the
- MIDI device, <port> by the MIDI port number, <key> by the name of
+ MIDI device as returned by the
+ "CREATE MIDI_INPUT_DEVICE"
+ or "LIST MIDI_INPUT_DEVICES"
+ 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.
@@ -2025,8 +2092,9 @@
- The following commands describe how to add and remove sampler channels, deploy
- sampler engines, load instruments and connect sampler channels to MIDI and audio devices.
+ The following commands describe how to add and remove sampler channels, associate a
+ sampler channel with a sampler engine, load instruments and connect sampler channels to
+ MIDI and audio devices.
An instrument file can be loaded and assigned to a sampler channel by one of the following commands:
@@ -2086,7 +2154,7 @@
- A sample engine can be deployed and assigned to a specific sampler
+ A sampler engine type can be associated to a specific sampler
channel by the following command:
@@ -2096,10 +2164,18 @@
Where <engine-name> is an engine name as obtained by the
- "LIST AVAILABLE_ENGINES" command and <sampler-channel> the sampler channel the
- deployed engine should be assigned to. Even if the respective
- sampler channel has already a deployed engine with that engine
- name, a new engine instance will be assigned to the sampler channel.
+ "LIST AVAILABLE_ENGINES" command and <sampler-channel>
+ the sampler channel as returned by the
+ "ADD CHANNEL" or
+ "LIST CHANNELS" command where
+ the engine type should be assigned to. This command should be issued
+ after adding a new sampler channel and before any other control
+ commands on the new sampler channel. It can also be used to change
+ the engine type of a sampler channel. This command has (currently) no
+ way to define or force if a new engine instance should be created and
+ assigned to the given sampler channel or if an already existing
+ instance of that engine type, shared with other sampler channels,
+ should be used.
Possible Answers:
@@ -2384,7 +2460,9 @@
GET CHANNEL INFO <sampler-channel>
- Where <sampler-channel> is the sampler channel number the front-end is interested in.
+ Where <sampler-channel> is the sampler channel number the front-end is interested in
+ as returned by the "ADD CHANNEL"
+ or "LIST CHANNELS" command.
Possible Answers:
@@ -2398,8 +2476,8 @@
ENGINE_NAME -
- name of the engine that is deployed on the sampler
- channel, "NONE" if there's no engine deployed yet for
+ name of the engine that is associated with the sampler
+ channel, "NONE" if there's no engine associated yet for
this sampler channel
@@ -2513,7 +2591,9 @@
GET CHANNEL VOICE_COUNT <sampler-channel>
- Where <sampler-channel> is the sampler channel number the front-end is interested in.
+ Where <sampler-channel> is the sampler channel number the front-end is interested in
+ as returned by the "ADD CHANNEL"
+ or "LIST CHANNELS" command.
Possible Answers:
@@ -2538,7 +2618,9 @@
GET CHANNEL STREAM_COUNT <sampler-channel>
- Where <sampler-channel> is the sampler channel number the front-end is interested in.
+ Where <sampler-channel> is the sampler channel number the front-end is interested in
+ as returned by the "ADD CHANNEL"
+ or "LIST CHANNELS" command.
Possible Answers:
@@ -2572,7 +2654,9 @@
to get the fill state in percent, where <sampler-channel> is the
- sampler channel number the front-end is interested in.
+ sampler channel number the front-end is interested in
+ as returned by the "ADD CHANNEL"
+ or "LIST CHANNELS" command.
Possible Answers:
@@ -2616,9 +2700,13 @@
SET CHANNEL AUDIO_OUTPUT_DEVICE <sampler-channel> <audio-device-id>
- Where <audio-device-id> is the numerical ID of the audio output
- device and <sampler-channel> is the respective sampler channel
- number.
+ Where <sampler-channel> is the respective sampler channel
+ number as returned by the "ADD CHANNEL"
+ or "LIST CHANNELS" command and
+ <audio-device-id> is the numerical ID of the audio output device as given by the
+ "CREATE AUDIO_OUTPUT_DEVICE"
+ or "LIST AUDIO_OUTPUT_DEVICES"
+ command.
Possible Answers:
@@ -2701,7 +2789,9 @@
SET CHANNEL AUDIO_OUTPUT_CHANNEL <sampler-chan> <audio-out> <audio-in>
- Where <sampler-chan> is the sampler channel number, <audio-out> is the
+ Where <sampler-chan> is the sampler channel number
+ as returned by the "ADD CHANNEL"
+ or "LIST CHANNELS" command, <audio-out> is the
numerical ID of the sampler channel's audio output channel which should be
rerouted and <audio-in> is the numerical ID of the audio channel of the selected audio
output device where <audio-out> should be routed to.
@@ -2744,8 +2834,12 @@
SET CHANNEL MIDI_INPUT_DEVICE <sampler-channel> <midi-device-id>
- Where <sampler-channel> is the sampler channel number and <midi-device-id> is the
- the numerical ID of the MIDI input device.
+ Where <sampler-channel> is the sampler channel number
+ as returned by the "ADD CHANNEL"
+ or "LIST CHANNELS" command
+ and <midi-device-id> is the numerical ID of the MIDI input device as returned by the
+ "CREATE MIDI_INPUT_DEVICE"
+ or "LIST MIDI_INPUT_DEVICES" command.
Possible Answers:
@@ -3157,6 +3251,49 @@
+
+
+ The client can ask for general informations about the LinuxSampler
+ instance by sending the following command:
+
+
+ GET SERVER INFO
+
+
+ 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 information category. At the
+ moment the following categories are defined:
+
+
+
+ DESCRIPTION -
+
+ arbitrary textual description about the sampler
+
+
+ VERSION -
+
+ version of the sampler
+
+
+ PROTOCOL_VERSION -
+
+ version of the LSCP specification the sampler
+ complies with (see for details)
+
+
+
+
+
+
+ The mentioned fields above don't have to be in particular order.
+ Other fields might be added in future.
+
@@ -3312,7 +3449,30 @@
- &rfc2119;
+
+
+
+ Key words for use in RFCs to Indicate Requirement Levels
+
+ Harvard University
+
+
+
+
+
+
+
+
+ TRANSMISSION CONTROL PROTOCOL
+
+ Defense Advanced Research Projects Agency
+
+
+
+
+
+
+