--- linuxsampler/trunk/Documentation/lscp.xml 2005/05/09 15:04:52 533
+++ linuxsampler/trunk/Documentation/lscp.xml 2005/05/09 17:40:33 534
@@ -31,7 +31,7 @@
schoenebeck at software minus engineering dot org
-
+
LinuxSampler Developers
LSCP
@@ -379,7 +379,7 @@
where <event-id> will be replace by the respective
event that client is no longer interested in receiving. For
- a list of supported events see chapter 6.
+ a list of supported events see .
Example: the fill states of disk stream buffers have
changed on sampler channel 4 and the LinuxSampler instance
@@ -428,7 +428,8 @@
This chapter will describe the available control commands
that can be sent on the TCP connection in detail. Some certain
- commands (e.g. "GET CHANNEL INFO" or "GET ENGINE INFO") lead to
+ commands (e.g. "GET CHANNEL INFO"
+ or "GET ENGINE INFO") lead to
multiple-line responses. In this case LinuxSampler signals the
end of the response by a "." (single dot) line.
@@ -472,13 +473,38 @@
what parameters drivers are offering, how to retrieve their
possible values, etc.
-
+
+ Use the following command to get the number of
+ audio output drivers currently available for the
+ LinuxSampler instance:
+
+
+ GET AVAILABLE_AUDIO_OUTPUT_DRIVERS
+
+
+ Possible Answers:
+
+
+ LinuxSampler will answer by sending the
+ number of audio output drivers.
+
+
+ Example:
+
+
+ C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
+ S: "2"
+
+
+
+
+
Use the following command to list all audio output
drivers currently available for the LinuxSampler
instance:
- GET AVAILABLE_AUDIO_OUTPUT_DRIVERS
+ LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS
Possible Answers:
@@ -492,14 +518,14 @@
Example:
- C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
+ C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"
S: "ALSA,JACK"
+ output driver" anchor="GET AUDIO_OUTPUT_DRIVER INFO">
Use the following command to get detailed information
about a specific audio output driver:
@@ -509,8 +535,8 @@
Where <audio-output-driver> is the name of the
- audio output driver, returned by the "GET
- AVAILABLE_AUDIO_OUTPUT_DRIVERS" command.
+ audio output driver, returned by the
+ "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" command.
Possible Answers:
@@ -572,7 +598,7 @@
+ output driver parameter" anchor="GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO">
Use the following command to get detailed information
about a specific audio output driver parameter:
@@ -581,9 +607,11 @@
Where <audio> is the name of the audio output
- driver as returned by the "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS" command,
+ driver as returned by the
+ "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" command,
<prm> a specific parameter name for which information should be
- obtained (as returned by the "GET AUDIO_OUTPUT_DRIVER INFO" command) and
+ obtained (as returned by the
+ "GET AUDIO_OUTPUT_DRIVER INFO" command) and
<deplist> is an optional list of parameters on which the sought
parameter <prm> depends on, <deplist> is a list of key-value
pairs in form of "key1=val1 key2=val2 ...", where character string values
@@ -630,8 +658,8 @@
either true or false, defines if this parameter must be
given when the device is to be created with the
- 'CREATE AUDIO_OUTPUT_DEVICE' command
- (always returned, no matter which driver parameter)
+ 'CREATE AUDIO_OUTPUT_DEVICE'
+ command (always returned, no matter which driver parameter)
@@ -639,8 +667,8 @@
either true or false, if false then this parameter can
be changed at any time, once the device is created by
- the 'CREATE AUDIO_OUTPUT_DEVICE' command
- (always returned, no matter which driver parameter)
+ the 'CREATE AUDIO_OUTPUT_DEVICE'
+ command (always returned, no matter which driver parameter)
@@ -672,7 +700,8 @@
reflects the default value for this parameter which is
used when the device is created and not explicitly
- given with the 'CREATE AUDIO_OUTPUT_DEVICE' command,
+ given with the
+ 'CREATE AUDIO_OUTPUT_DEVICE' command,
in case of MULTIPLCITY=true, this is a comma separated
list, that's why character strings are encapsulated into
apostrophes (')
@@ -757,7 +786,7 @@
-
+
Use the following command to create a new audio output device for the desired audio output system:
@@ -815,7 +844,7 @@
-
+
Use the following command to destroy a created output device:
@@ -823,8 +852,10 @@
Where <device-id> should be replaced by the numerical ID of the
- audio output device as given by the "CREATE AUDIO_OUTPUT_DEVICE" or
- "GET AUDIO_OUTPUT_DEVICES" command.
+ audio output device as given by the
+ "CREATE AUDIO_OUTPUT_DEVICE"
+ or "LIST AUDIO_OUTPUT_DEVICES"
+ command.
Possible Answers:
@@ -859,7 +890,7 @@
-
+
Use the following command to count all created audio output devices:
@@ -882,7 +913,7 @@
-
+
Use the following command to list all created audio output devices:
@@ -905,7 +936,7 @@
-
+
Use the following command to get current settings of a specific, created audio output device:
@@ -914,7 +945,7 @@
Where <device-id> should be replaced by numerical ID
of the audio output device as e.g. returned by the
- "LIST AUDIO_OUTPUT_DEVICES" command.
+ "LIST AUDIO_OUTPUT_DEVICES" command.
Possible Answers:
LinuxSampler will answer by sending a <CRLF> separated list.
Each answer line begins with the information category name
@@ -928,7 +959,9 @@
DRIVER -
identifier of the used audio output driver, as also
- returned by the "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
+ returned by the
+
+ "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"
command
@@ -957,8 +990,8 @@
order. The fields above are only those fields which are
returned by all audio output devices. Every audio output driver
might have its own, additional driver specific parameters (see
- "GET AUDIO_OUTPUT_DRIVER INFO" command) which are also returned
- by this command.
+ )
+ which are also returned by this command.
Example:
@@ -976,7 +1009,7 @@
-
+
Use the following command to alter a specific setting of a created audio output device:
@@ -1018,7 +1051,7 @@
-
+
Use the following command to get information about an audio channel:
@@ -1116,7 +1149,7 @@
-
+
Use the following command to get detailed information about specific audio channel parameter:
@@ -1126,9 +1159,11 @@
Where <dev-id> is the numerical ID of the audio output device as returned
- by the "GET AUDIO_OUTPUT_DEVICES" command, <chan> the audio channel number
+ by the "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 "GET AUDIO_OUTPUT_CHANNEL INFO" command).
+ be obtained (as returned by the
+ "GET AUDIO_OUTPUT_CHANNEL INFO" command).
Possible Answers:
@@ -1219,7 +1254,7 @@
-
+
Use the following command to alter a specific setting of an audio output channel:
@@ -1295,12 +1330,37 @@
showing how to retrieve what parameters drivers are offering, how to retrieve their
possible values, etc.
-
+
+ Use the following command to get the number of
+ MIDI input drivers currently available for the
+ LinuxSampler instance:
+
+
+ GET AVAILABLE_MIDI_INPUT_DRIVERS
+
+
+ Possible Answers:
+
+
+ LinuxSampler will answer by sending the
+ number of available MIDI input drivers.
+
+
+ Example:
+
+
+ C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"
+ S: "2"
+
+
+
+
+
Use the following command to list all MIDI input drivers currently available
for the LinuxSampler instance:
- GET AVAILABLE_MIDI_INPUT_DRIVERS
+ LIST AVAILABLE_MIDI_INPUT_DRIVERS
Possible Answers:
@@ -1313,13 +1373,13 @@
Example:
- C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"
+ C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
S: "ALSA,JACK"
-
+
Use the following command to get detailed information about a specific MIDI input driver:
@@ -1373,7 +1433,7 @@
-
+
Use the following command to get detailed information about a specific parameter of a specific MIDI input driver:
@@ -1382,9 +1442,11 @@
Where <midi-t> is the name of the MIDI input driver as returned
- by the "GET AVAILABLE_MIDI_INPUT_DRIVERS" command, <param> a specific
+ by the
+ "LIST AVAILABLE_MIDI_INPUT_DRIVERS" command, <param> a specific
parameter name for which information should be obtained (as returned by the
- "GET MIDI_INPUT_DRIVER INFO" command) and <deplist> is an optional list
+
+ "GET MIDI_INPUT_DRIVER INFO" command) and <deplist> is an optional list
of parameters on which the sought parameter <param> depends on,
<deplist> is a key-value pair list in form of "key1=val1 key2=val2 ...",
where character string values are encapsulated into apostrophes ('). Arguments
@@ -1425,7 +1487,8 @@
either true or false, defines if this parameter must be
given when the device is to be created with the
- 'CREATE MIDI_INPUT_DEVICE' command
+
+ 'CREATE MIDI_INPUT_DEVICE' command
(always returned, no matter which driver parameter)
@@ -1434,7 +1497,8 @@
either true or false, if false then this parameter can
be changed at any time, once the device is created by
- the 'CREATE MIDI_INPUT_DEVICE' command
+ the
+ 'CREATE MIDI_INPUT_DEVICE' command
(always returned, no matter which driver parameter)
@@ -1467,7 +1531,8 @@
reflects the default value for this parameter which is
used when the device is created and not explicitly
- given with the 'CREATE MIDI_INPUT_DEVICE' command,
+ given with the
+ 'CREATE MIDI_INPUT_DEVICE' command,
in case of MULTIPLCITY=true, this is a comma separated
list, that's why character strings are encapsulated into
apostrophes (')
@@ -1523,7 +1588,7 @@
-
+
Use the following command to create a new MIDI input device for the desired MIDI input system:
@@ -1571,7 +1636,7 @@
-
+
Use the following command to destroy a created MIDI input device:
@@ -1610,7 +1675,7 @@
-
+
Use the following command to count all created MIDI input devices:
@@ -1634,7 +1699,7 @@
-
+
Use the following command to list all created MIDI input devices:
@@ -1663,7 +1728,7 @@
-
+
Use the following command to get current settings of a specific, created MIDI input device:
@@ -1687,7 +1752,8 @@
DRIVER -
identifier of the used MIDI input driver, as e.g.
- returned by the "GET AVAILABLE_MIDI_INPUT_DRIVERS"
+ returned by the
+ "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
command
@@ -1710,7 +1776,8 @@
order. The fields above are only those fields which are
returned by all MIDI input devices. Every MIDI input driver
might have its own, additional driver specific parameters (see
- "GET MIDI_INPUT_DRIVER INFO" command) which are also returned
+
+ "GET MIDI_INPUT_DRIVER INFO" command) which are also returned
by this command.
Example:
@@ -1724,7 +1791,7 @@
-
+
Use the following command to alter a specific setting of a created MIDI input device:
@@ -1767,7 +1834,7 @@
-
+
Use the following command to get information about a MIDI port:
@@ -1809,7 +1876,7 @@
-
+
Use the following command to get detailed information about specific MIDI port parameter:
@@ -1818,9 +1885,11 @@
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
+ by the
+ "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).
+ obtained (as returned by the
+ "GET MIDI_INPUT_PORT INFO" command).
Possible Answers:
@@ -1911,7 +1980,7 @@
-
+
Use the following command to alter a specific setting of a MIDI input port:
@@ -1959,7 +2028,7 @@
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.
-
+
An instrument file can be loaded and assigned to a sampler channel by one of the following commands:
@@ -1977,7 +2046,8 @@
is that the regular command returns OK only after the instrument has been
fully loaded and the channel is ready to be used while NON_MODAL version
returns immediately and a background process is launched to load the instrument
- on the channel. GET CHANNEL INFO command can be used to obtain loading
+ on the channel. The GET CHANNEL INFO
+ command can be used to obtain loading
progress from INSTRUMENT_STATUS field. LOAD command will perform sanity checks
such as making sure that the file could be read and it is of a proper format
and SHOULD return ERR and SHOULD not launch the background process should any
@@ -2015,7 +2085,7 @@
-
+
A sample engine can be deployed and assigned to a specific sampler
channel by the following command:
@@ -2025,7 +2095,8 @@
Where <engine-name> is an engine name as obtained by the
- "GET AVAILABLE_ENGINES" command and <sampler-channel> the sampler channel 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.
@@ -2061,7 +2132,7 @@
-
+
The number of sampler channels can change on runtime. To get the
current amount of sampler channels, the front-end can send the
following command:
@@ -2085,7 +2156,7 @@
-
+
The number of sampler channels can change on runtime. To get the
current list of sampler channels, the front-end can send the
following command:
@@ -2110,7 +2181,7 @@
-
+
A new sampler channel can be added to the end of the sampler
channel list by sending the following command:
@@ -2162,7 +2233,7 @@
-
+
A sampler channel can be removed by sending the following command:
@@ -2205,8 +2276,8 @@
-
- The front-end can ask for all available engines by sending the following command:
+
+ The front-end can ask for the number of available engines by sending the following command:
GET AVAILABLE_ENGINES
@@ -2215,6 +2286,28 @@
Possible Answers:
+ LinuxSampler will answer by sending the number of available engines.
+
+
+ Example:
+
+
+ C: "GET AVAILABLE_ENGINES"
+ S: "4"
+
+
+
+
+
+ The front-end can ask for a list of all available engines by sending the following command:
+
+
+ LIST AVAILABLE_ENGINES
+
+
+ Possible Answers:
+
+
LinuxSampler will answer by sending a comma separated character
string of the engines' names. Engine names can consist of lower and
upper cases, digits and underlines ("_" character).
@@ -2223,13 +2316,13 @@
Example:
- C: "GET AVAILABLE_ENGINES"
+ C: "LIST AVAILABLE_ENGINES"
S: "GigEngine,AkaiEngine,DLSEngine,JoesCustomEngine"
-
+
The front-end can ask for information about a specific engine by
sending the following command:
@@ -2238,7 +2331,8 @@
Where <engine-name> is an engine name as obtained by the
- "GET AVAILABLE_ENGINES" command.
+
+ "LIST AVAILABLE_ENGINES" command.
Possible Answers:
@@ -2278,7 +2372,7 @@
-
+
The front-end can ask for the current settings of a sampler channel
by sending the following command:
@@ -2407,7 +2501,7 @@
-
+
The front-end can ask for the current number of active voices on a
sampler channel by sending the following command:
@@ -2432,7 +2526,7 @@
-
+
The front-end can ask for the current number of active disk streams
on a sampler channel by sending the following command:
@@ -2459,7 +2553,7 @@
-
+
The front-end can ask for the current fill state of all disk streams
on a sampler channel by sending the following command:
@@ -2510,7 +2604,7 @@
-
+
The front-end can set the audio output device on a specific sampler
channel by sending the following command:
@@ -2552,7 +2646,7 @@
-
+
DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
The front-end can alter the audio output type on a specific sampler
@@ -2595,7 +2689,7 @@
-
+
The front-end can alter the audio output channel on a specific
sampler channel by sending the following command:
@@ -2638,7 +2732,7 @@
-
+
The front-end can set the MIDI input device on a specific sampler
channel by sending the following command:
@@ -2679,7 +2773,7 @@
-
+
DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
The front-end can alter the MIDI input type on a specific sampler
@@ -2722,7 +2816,7 @@
-
+
The front-end can alter the MIDI input port on a specific sampler
channel by sending the following command:
@@ -2764,7 +2858,7 @@
-
+
The front-end can alter the MIDI channel a sampler channel should
listen to by sending the following command:
@@ -2806,7 +2900,7 @@
-
+
The front-end can alter the volume of a sampler channel by sending
the following command:
@@ -2849,7 +2943,7 @@
-
+
The front-end can reset a particular sampler channel by sending the following command:
@@ -2897,7 +2991,7 @@
The following commands are used to control the connection to LinuxSampler.
-
+
The front-end can register itself to the LinuxSampler application to
be informed about noteworthy events by sending this command:
@@ -2939,7 +3033,7 @@
-
+
The front-end can unregister itself if it doesn't want to receive event
messages anymore by sending the following command:
@@ -2981,7 +3075,7 @@
-
+
To enable or disable back sending of commands to the client the following command can be used:
@@ -3019,7 +3113,7 @@
-
+
The client can close its network connection to LinuxSampler by sending the following command:
@@ -3034,7 +3128,7 @@
The following commands have global impact on the sampler.
-
+
The front-end can reset the whole sampler by sending the following command:
@@ -3062,16 +3156,16 @@
-
+
TODO: will soon automatically included from src/network/lscp.y,
meanwhile have a look at that file to get the exact definition of
the command syntax.
-
+
This chapter will describe all currently defined events supported by LinuxSampler.
-
+
Client may want to be notified when the total number of channels on the
back-end changes by issuing the following command:
@@ -3089,7 +3183,7 @@
of sampler channels.
-
+
Client may want to be notified when the number of voices on the
back-end changes by issuing the following command:
@@ -3108,7 +3202,7 @@
active voices on that channel.
-
+
Client may want to be notified when the number of streams on the back-end
changes by issuing the following command: SUBSCRIBE STREAM_COUNT
@@ -3127,7 +3221,7 @@
active disk streams on that channel.
-
+
Client may want to be notified when the buffer fill state of a disk stream
on the back-end changes by issuing the following command:
@@ -3142,12 +3236,13 @@
where <sampler-channel> will be replaced by the sampler channel the
- buffer fill state change occurred and <fill-data> will be replaced by the
- buffer fill data for this channel as described in 5.4.12 as if the
- "GET CHANNEL BUFFER_FILL PERCENTAGE" was issued on this channel.
+ buffer fill state change occurred on and <fill-data> will be replaced by the
+ buffer fill data for this channel as described in
+ as if the
+ "GET CHANNEL BUFFER_FILL PERCENTAGE" command was issued on this channel.
-
+
Client may want to be notified when changes were made to sampler channels on the
back-end changes by issuing the following command:
@@ -3169,7 +3264,7 @@
message is sufficient here.
-
+
Client may want to be notified of miscellaneous and debugging events occurring at
the server by issuing the following command: