Ecasound library contains an interpreter module that understands
a set of commands aimed at controlling various library services.
This is called the ecasound interactive mode (EIAM). All programs
linked to ecasound library can use this facility.
ECI API and return types
A special case of EIAM use is ecasound's control interface (ECI),
which is a small library providing easy access to the EIAM
commands from outside of libecasound. When issuing EIAM commands using
ECI, it's possible that commands also return information. Currently
supported return value types are: string [s], list of strings [S]
(elements separated by commas; escaped if necessary), integer [i],
long integer [li] and floating-point number [f]. These definitions are
used throughout this document. Commands that return nothing (void) are
marked with [-]. Additionally, return type [e] marks an error condition.
When an EIAM results in an error, a error string explaining the
condition is returned.
Realtime commands
It's not possible to use all EIAM commands to modify and control
objects that belong to a connected chainsetup. Commands that
do support this are: 'start', 'stop', 'setpos', 'rewind', 'forward',
'c-select', 'c-muting', 'c-bypass', 'cop-select', 'copp-select'
and 'copp-value'.
Another set of commands are those which can be used with connected
chainsetups, but not without an audible break. These are: 'cop-add',
'cop-remove', 'ctrl-add', 'ctrl-select', 'ctrl-remove'
In addition, most non-modifying (const) commands work with
connected setups.
GENERAL
"quit,
Quit ecasound session. What this means in practice depends on the
client (library throws an exception). [-]
"start,
Processing is started (play). [-]
"stop,
Stop processing. [-]
"run"
Like 'start' but blocks until processing is finished. [-]
"debug
Set debug level to 'debug-level'. Notice that client programs can
reimplement the debug routines. [-]
"help',
Help! [-]
GLOBAL
"engine-status"
Returns a string describing the engine status (running, stopped,
finished, error, not ready). See also cs-status. [s]
"engine-launch"
Initializes and starts the engine. Doesn't start the actual
processing. See also start. [-]
"engine-halt"
Stops the engine. Does not disconnect the chainsetup that
was running. See also stop. [-]
CHAINSETUPS
Chainsetup is the central data object. All other objects (inputs,
outputs, chains, etc) are connected to some chainsetup. There can be
many chainsetups but only one can be connected. Similarly only
one chainsetup can be selected. If not otherwise specified operations
are done on the selected chainsetup. Some operations also require
that selected chainsetup is not connected.
"cs-add
Adds a new chainsetup with name 'name'. 'name' is now
the selected chainsetup. [-]
"cs-remove"
Removes currently selected chainsetup. [-]
"cs-list"
Returns a list of all chainsetups. [S]
"cs-select
Selects chainsetup 'name'. [-]
"cs-selected"
Returns the name of currently selected chainsetup. [s]
"cs-index-select
Selects a chainsetup based on a short index string. Chainsetup names
can be rather long. This command can be used to avoid typing
these long names. 'cs_index' is an integer value, where '1' refers to
the first audio input/output. You can use 'cs-list' and 'cs-status'
to get a full list of currently available chainsetups. [-]
"cs-load
Adds a new chainsetup by loading it from file 'filename'.
'filename' is now the selected chainsetup. [-]
"cs-save"
Saves the currently selected chainsetup to file. If chainsetup was loaded
from a file, the saved version will replace the original. If it doesn't
have a default filename, it's saved to "chainsetup_name.ecs". [-]
"cs-save-as
Saves currently selected chainsetup to file 'filename'. [-]
"cs-edit"
Currently selected chainsetup is saved to a temporary file. This
file is loaded to an external editor (see ecasoundrc(5) ). After
editing, the chainsetup is loaded back to ecasound. [-]
"cs-is-valid"
Whether currently selected chainsetup is valid (=can be connected)? [i]
"cs-connect"
Connect currently selected chainsetup to engine. Only one chainsetup
can be connected at a time. [-]
"cs-disconnect"
Disconnect currently connected chainsetup. [-]
"cs-connected"
Returns the name of currently connected chainsetup. [s]
"cs-rewind
Rewinds the current chainsetup position by 'time-in-seconds' seconds.
Position of all inputs and outputs attached to the selected chainsetup
is also affected. [-]
"cs-forward
The current chainsetup position is forwarded by 'time-in-seconds'
seconds. Position of all inputs and outputs attached to the selected chainsetup
is also affected. [-]
"cs-set-position
Sets the chainsetup position to 'time-in-seconds' seconds from the
beginning. Position of all inputs and outputs attached to the selected
chainsetup is also affected. [-]
"cs-set-position-samples
Sets the chainsetup position to 'time-in-samples' samples from the
beginning. Position of all inputs and outputs attached to the selected
chainsetup is also affected. [-]
"cs-get-position,
Returns the current chainsetup position in seconds. [f]
"cs-get-position-samples"
Returns the current chainsetup position in samples. [li]
"cs-get-length,
Returns the chainsetup length in seconds (if known). [f]
"cs-get-length-samples,
Returns the chainsetup length in samples (if known). [li]
"cs-set-length
Sets processing time in seconds (doesn't have to be an integer value).
A special-case value of '-1' will set the chainsetup length
according to the longest input object. [-]
"cs-set-length-samples
Sets processing time in samples. [-]
"cs-toggle-loop"
Toggle looping. When processing is finished, engine will start
again from the initial position. It's not always possible to enable looping
(for instance all inputs and outputs have infinite length and
chainsetup length is not explicitly set with 'cs-set-length'). [-]
"cs-set-param"
Interpret general chainsetup parameters like for example
"-b" (buffersize), "-n" (name), etc. See ecasound(1) for
more info. [-]
"cs-set-audio-format
Set the default sample parameters for currently selected chainsetup.
For example cd-quality audio would be "16,2,44100". This does the
same as command-line argument "-f" (see ecasound(1) ). [-]
"cs-status,
Print status info about all chainsetups. [s]
"cs-option
One powerful feature of the interactive-mode is that it
provides full access to ecasound's command-line syntax.
For instance, command "cs-option -efb:400,200" means that
a bandpass filter is added to the currently selected
chain, with initial parameters 400 (center frequency)
and 200 (width in Hz).
Note! EIAM implicitly interprets all strings beginning
with a '-' as "cs-option string".
CHAINS
Chain is a simple signal flow abstraction. Every chain has one input
and one output. All chain operators and their controllers are attached
to chains. Chains can be muted, unmuted and be bypassed. If not
otherwise stated, all operations are done to currently selected
chainsetup.
"c-add
Adds a set of chains. Added chains are automatically selected. Note
that commas in chain names are not allowed. [-]
"c-remove"
Removes selected chains. [-]
"c-list"
Returns a list of all chains. [S]
"c-select
Selects chains. Other chains are automatically deselected. [-]
"c-index-select
Selects a set of chains based on the list of indixes. Each index is
an integer value, where '1' refers to the first chain. You can use
'c-list' and 'c-status' to get a full list of currently available
chains. [-]
"c-select-all"
Selects all chains. [-]
"c-select-add
Selects more chains. [-]
"c-deselect
Deselects chains. [-]
"c-selected"
Returns a list of selected chains. [S]
"c-clear"
Clear selected chains by removing all chain operators and controllers.
Doesn't change how chains are connected to inputs and outputs. [-]
"c-rename
Renames the selected chain. When using this command, exactly one chain must
be selected. [-]
"c-muting"
Toggle chain muting. When chain is muted, all data that goes through
is muted. [-]
"c-mute"
Toggle chain muting. Note! Deprecated, use c-muting instead. [-]
"c-bypass"
Toggle chain bypassing. When chain is bypassed, sample data is passed
through untouched. [-]
"c-status,
Print status info about all chains. [s]
AUDIO INPUT/OUTPUT OBJECTS
If not otherwise stated, all operations are done to currently selected
object. All commands with ai- prefix operate on audio inputs,
while commands with ao- operate on outputs.
"ai-add
Adds a new input object. See ecasound(1) man page for more info about
the argument format ('-i' option). [-]
"ao-add
Adds a new output object. See ecasound(1) man page for more info about
the argument format ('-o' option). If argument is omitted,
a default output device is added (see ecasoundrc(5) ). [-]
"ao-add-default"
Adds the default output device (see ecasoundrc(5) ). [-]
"ai-select
Selects an audio object. 'aobject_name' refers to the string
used when creating the object (see above). Note! All input
object names are required to be unique. Similarly all output
names need to be unique. However, it's possible that the same
object name exists both as an input and as an output. [-]
"ai-index-select
Select some audio object based on a short index string. Especially file
names can be rather long. This command can be used to avoid typing
these long names when selecting audio objects. 'aobject_index' is
an integer value, where '1' refers to the first audio input/output.
You can use 'ai-list' and 'ao-list' to get a full list of currently
available inputs/outputs. [-]
"ai-selected,
Returns the name of the currently selected audio object. [s]
"ai-attach,
Attaches the currently selected audio object to all selected chains. [-]
"ai-remove,
Removes the currently selected audio object from the chainsetup. [-]
"ai-forward
Selected audio object is forwarded by 'time-in-seconds' seconds.
Time should be given as a floating point value (eg. 0.001 is the
same as 1ms). [-]
"ai-rewind
Selected audio object is rewinded by 'time-in-seconds' seconds.
Time should be given as a floating point value (eg. 0.001 is the
same as 1ms). [-]
"ai-setpos
Set audio object position to 'time_in_seconds'. [-]
"ai-set-position-samples
Set audio object position to 'time_in_samples'. [-]
"ai-getpos,
Returns the audio object position in seconds. [f]
"ai-get-position-samples,
Returns the audio object position in samples. [li]
"ai-get-length,
Returns the audio object length in seconds. [f]
"ai-get-length-samples,
Returns the audio object length in samples. [li]
"ai-get-format,
Returns the audio format of the selected audio input/output as a
formatted string. See documentation for '-f' command-line option. [s]
"ai-wave-edit,
The currently selected audio object is loaded into an external
wave editor (see ecasoundrc(5) ). [-]
"ai-list,
Returns a list of all input/output objects. [S]
"aio-register"
Prints a list of registered audio object types. [s]
"aio-status"
Audio object status (index strings, position, length, etc). [s]
CHAIN OPERATORS
Chain operators are used to process and analyze sample data.
They are attached to chains. If not otherwise stated,
currently selected chainsetup and chain are used. Also,
'chainop_id' and 'param_id' are used to select chain operators
and their parameters. First valid value for these parameters
is 1.
"cop-add
Adds a new chain operator. Argument format is
"-<id_string>:par1,...,parN". In addition to normal chain operators,
this commmand can also be used to add effect presets and various
plugins. Note; it is not possible to add operators to multiple
chains at once. In other words only one chain should be selected
when issuing 'cop-add'. See ecasound(1) man page for more
info. [-]
"cop-remove"
Removes the selected chain operator. [-]
"cop-list"
Returns a list of all chain operators attached to the currently
selected chain. [S]
"cop-select
Selects a chain operator. [-]
"cop-selected"
Returns the index number of currently selected chain operator. [i]
"cop-set
Changes the value of a single chain operator parameter. Unlike other
chain operator commands, this can also be used during processing. [-]
"cop-status"
Returns info about chain operator status. [s]
"copp-list"
Returns a list of selected chain operator's parameters. [S]
"copp-select
Selects a chain operator parameter. [-]
"copp-selected"
Returns the index number of currently selected chain operator parameter. [i]
"copp-set
Sets the selected parameter value to 'value'. [-]
"copp-get"
Returns the selected parameter value. [f]
"cop-register"
Prints a list of registered chain operators. [s]
"preset-register"
Prints a list of registered effect presets. [s]
"ladspa-register"
Prints a list of registered LADSPA plugins. [s]
CONTROLLERS
Controllers are used to control individual chain operator parameters.
They are attached to chains. If not otherwise stated, currently
selected chainsetup and chains are used.
"ctrl-add
Adds a new controller and attach it to currently selected chain
operator. Argument format is "-<id_string>:<param_id>,<range_low>,
<range_high>,par1,...,parN". See ecasound(1) man page for more
info. [-]
"ctrl-remove"
Removes the selected controller. [-]
"ctrl-list"
Returns a list of all controllers attached to the currently
selected chain. [S]
"ctrl-select
Selects a controller. [-]
"ctrl-selected"
Returns the index number of currently selected controller. [i]
"ctrl-status"
Returns info about controller status. [s]
"ctrl-register"
Prints a list of registered controllers. [s]
INTERNAL COMMANDS
Internal commands are not directly aimed at normal use. They
are primarily meant for use in scripting and frontends.
"int-cmd-list"
Returns a list of all registered EIAM commands. [S]
"int-log-history"
Returns recent log messages sent by libecasound modules. This
is a good tool for debugging ECI/EIAM scripts and applications. [s]
"int-output-mode-wellformed"
Select the well-format output format for log messages. [-]
"int-set-float-to-string-precision"
Sets precision used in float to text conversions. Note that
this can be used to control the precision of float return values
for ECI commands. [-]
"int-set-log-history-length"
Sets the log history length. Defaults to 5 items. [-]
"int-cmd-version-string"
Returns EIAM parser version string. [s]
"int-cmd-version-lib-current"
Returns EIAM library interface version (libtool). [i]
Object maps are central repositories for commonly used object types.
By querying the maps, applications can get a list of all registered
object types and their properties.
"map-cop-list"
Prints a list of registered chain operators using
the format specified in section OPERATOR DESCRIPTIONS. [s]
"map-preset-list"
Prints a list of registered effect presets using
the format specified in section OPERATOR DESCRIPTIONS. [s]
"map-ladspa-list"
Prints a list of registered LADSPA plugins using
the format specified in section OPERATOR DESCRIPTIONS. [s]
"map-ladspa-id-list"
Prints a list of registered LADSPA plugins using
the format specified in section OPERATOR DESCRIPTIONS.
Numerical LADPSA plugin identifiers are used. [s]
"map-ctrl-list"
Prints a list of registered controllers using
the format specified in section OPERATOR DESCRIPTIONS. [s]
DUMP COMMANDS
The following dump commands are not meant for normal use.
Their primary purpose is to provide an easy way to get
internal state information from libecasound. All dump
commands output a single line with syntax "key value"
to the selected output stream (defaults to stdout).
"dump-target
Set target stream for dumping. [-]
"dump-status"
Dumps engine status - 'running', 'stopped', 'finished' or 'notready'. [-]
"dump-position"
Dumps the global position. Printed in seconds using a floating-point
representation. [-]
"dump-length"
Dumps the overall processing length. Printed in seconds using a floating-point
representation. [-]
"dump-cs-status"
Dumps status string for the currently selected chainsetup - 'connected',
'selected' or an empty string. [-]
"dump-c-selected"
Dumps the name of currently selected chain. [-]
"dump-ai-selected"
Dumps label of currently selected audio input. If no input is
selected, dumps an empty string. [-]
"dump-ai-position"
Dumps position of currently selected audio inputs. Printed in
seconds, using a floating-point representation. [-]
"dump-ai-length"
Dumps length of currently selected audio input. Printed in seconds,
using a floating-point representation. [-]
"dump-ai-open-state"
Dumps audio input state info. Either 'open' or 'closed'. [-]
"dump-ao-selected"
Dumps label of currently selected audio output. If no output is
selected, dumps an empty string. [-]
"dump-ao-position"
Dumps position of currently selected audio outputs. Printed in
seconds, using a floating-point representation. [-]
"dump-ao-length"
Dumps length of currently selected audio output. Printed in seconds,
using a floating-point representation. [-]
"dump-ao-open-state"
Dumps audio output state info. Either 'open' or 'closed'. [-]
"dump-cop-value
Dumps chain operator parameter value. 'chainop' and 'param' are
operator and parameter index values (1...n). [-]
OPERATOR DESCRIPTIONS
The map-xxx-list commands return a string containing all registered
objects of the given type xxx. Each line of the output describes
one registered type. The used syntax is:
