NAME
ecasound-iam - ecasound interactive mode
SYNOPSIS
DESCRIPTION
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 interactive mode use is ecasound's control interface
(ECI), which is a small library providing easy access to the
interactive mode commands from outside of libecasound. When issuing
inter commands using the control interface, 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 interactive mode command results
in an error, an error string explaining the condition is returned.
Real-time commands
It's not possible to use all interactive mode commands to modify and
control objects that belong to a connected chainsetup. Commands that do
NOT support this are:
cs-remove, cs-set-length, cs-set-length-samples, cs-toggle-loop,
cs-set-param, cs-option, c-add, c-remove, c-rename, c-clear,
ai-add, ai-remove, ai-attach, ai-forward, ai-rewind,
ai-set-position, ai-set-position-samples, ao-add,
ao-add-default, ao-remove, ao-attach, ao-forward, ao-rewind,
ao-set-position, ao-set-position-samples.
If one of these commands is issued when a chainsetup is connected,
ecasound will first stop and disconnect the chainsetup, process the
command, and the reconnect.
In addition, most non-modifying (const) commands work with connected
setups.
GENERAL
quit, q
Quit ecasound session. What this means in practice depends on
the client implementation. In ecasound interactive mode, 'quit'
terminates the ecasound process. When sent over ecasound server
connection (aka NetECI), 'quit' terminates the active network
connection, but does not terminate the ecasound server process.
[-]
start, t
Processing is started (play). Error string is return if any
errors upon startup are encountered. [e]
stop, s
Stop processing. [-]
run Like 'start' but blocks until processing is finished. Error
string is return if any errors upon startup, or during process,
are encountered. [e]
debug 'debug-level'
Set debug level to 'debug-level'. Notice that client programs
can reimplement the debug routines. [-]
resource-file 'path-to-file'
Overrides the global and user resource files. Does not affect
already created objects. This command is equivalent to '-R'
ecasound option (see ecasound (1) man page).
-prefix:arg1,...,argN
Equivalent to issuing 'cs-option -prefix:arg1,...,argN). See
documentation for 'cs-option'.
help', 'h'
Help! [-]
GLOBAL
engine-status
Returns a string describing the engine status (running, stopped,
finished, error, not ready). See also cs-status. [s]
engine-launch
Starts the real-time engine. Engine will execute the currently
connected chainsetup (see 'cs-connect). This action does not yet
start actual processing (see start and stop). When ecasound is
used as a JACK client, issuing engine-launch makes ecasound an
active JACK client (i.e. ecasound's ports can be connected to
other JACK clients). [-]
engine-halt
Stops the engine. Does not disconnect the chainsetup that was
running. See also cs-disconnet and stop. When ecasound is used
as a JACK client, engine-halt will cause ecasound to become a
deactivated client (all JACK connections are torn down). [-]
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 'name'
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 'name'
Selects chainsetup 'name'. [-]
cs-selected
Returns the name of currently selected chainsetup. [s]
cs-index-select 'cs_index', cs-iselect 'cs_index'
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 'filename'
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 'filename'
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. When
connecting, all resources (e.g. files, soundcard devices,
external programs) needed to execute the chainsetup are
reserved. Only one chainsetup can be connected at a time. Error
string is returned if connection fails (for instance due to
error in allocating the resources). [e]
cs-disconnect
Disconnect currently connected chainsetup. This action will free
all external resources needed by the chainsetup. [-]
cs-connected
Returns the name of currently connected chainsetup. [s]
cs-rewind 'time-in-seconds', rewind 'time-in-seconds', rw
'time-in-seconds'
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 'time-in-seconds', forward 'time-in-seconds', fw
'ttime-in-seconds'
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 'time-in-seconds', cs-setpos 'time-in-seconds', setpos
'time-in-seconds', set-position 'time-in-seconds'
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 'time-in-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, cs-getpos, getpos, 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, get-length
Returns the chainsetup length in seconds (if known). [f]
cs-get-length-samples, get-length-samples
Returns the chainsetup length in samples (if known). [li]
cs-set-length 'seconds'
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 '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 'bits,channels,sample_rate'
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, status, st
Prints out status information about available chainsetup.
Detailed information is printed out for connected (=available
for running) nd selected (=available for editing) chainsetups.
Other chainsetups are listed, but further details are
suppressed. To get full details of a specific chainsetup, select
it with 'cs-select' or 'cs-iselect', and then issue 'cs-select'.
[s]
cs-option '-prefix:arg1,...,argN'
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 that session level options (such as setting debug level) can not
be used with 'cs-option' (i.e. only options that modify chainsetups).
Note! Ecasound interactive mode 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 'cname1,...,cnameN'
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 'cname1,...,cnameN'
Selects chains. Other chains are automatically deselected. [-]
c-index-select 'index1,...,indexN', c-iselect 'index1,...,indexN'
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 'cname1,...,cnameN'
Selects more chains. [-]
c-deselect 'cname1,...,cnameN'
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 'new_name'
Renames the selected chain. When using this command, exactly one
chain must be selected. [-]
c-muting, c-mute
Toggle chain muting. When chain is muted, all data that goes
through is muted. [-]
c-bypass
Toggle chain bypassing. When chain is bypassed, sample data is
passed through unprocessed (all chain operators are disabled for
the given chain). [-]
c-status, cs
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 'input_format_string'
Adds a new input object. See ecasound (1) man page for more info
about the argument format ('-i' option). Note on syntax: if any
of the parameters (such as a filename) contains commas, the
parameter should be enclosed in double-quotes. [-]
ao-add 'output_format_string'
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)).
Note on syntax: if any of the parameters (such as a filename)
contains commas, the parameter should be enclosed in
double-quotes. [-]
ao-add-default
Adds the default output device (see ecasoundrc (5)). [-]
ai-describe, ao-describe
Returns a Ecasound Option Syntax (EOS) compliant string
describing the input/output. See the Ecasound User's Guide for
more information about EOS. This command was introduced in
ecasound 2.4.4. [s]
ai-select 'aobject_name', ao-select 'aobject_name'
Selects an audio object. 'aobject_name' refers to the string
used when creating the object (the first argument given to
ai-add/ao-add). Note that as a important difference to
ai-add/ao-add, one should not enclose the object name in double
quotes for ai-select/ao-select. In the case a chainsetup
contains multiple inputs, or outputs, with identical name,
'ai-select' and 'ao-select' will select the first matching
instance. In order to select a specific instance, the
'ai-iselect' and 'ao-iselect' commands need to be used. [-]
ai-index-select 'aobject_index', ai-iselect 'aobject_index',
ao-index-select 'aobject_index', ao-iselect 'aobject_index'
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, ao-selected
Returns the name of the currently selected audio object. [s]
ai-attach, ao-attach
Attaches the currently selected audio object to all selected
chains. [-]
ai-remove, ao-remove
Removes the currently selected audio object from the chainsetup.
[-]
ai-forward 'time_in_seconds', ai-fw 'time_in_seconds', ao-forward
'time_in_seconds', ao-fw 'time_in_seconds'
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 'time_in_seconds', ai-rw 'time_in_seconds', ao-rewind
'time_in_seconds', ao-rw 'time_in_seconds'
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 'time_in_seconds', ai-set-position 'time_in_seconds',
ao-setpos 'time_in_seconds', ao-set-position 'time_in_seconds'
Set audio object position to 'time_in_seconds'. [-]
ai-set-position-samples 'time_in_samples', ao-set-position-samples
'time_in_samples'
Set audio object position to 'time_in_samples'. [-]
ai-getpos, ai-get-position, ao-getpos, ao-get-position
Returns the audio object position in seconds. [f]
ai-get-position-samples, ao-get-position-samples
Returns the audio object position in samples. [li]
ai-get-length, ao-get-length
Returns the audio object length in seconds. [f]
ai-get-length-samples, ao-get-length-samples
Returns the audio object length in samples. [li]
ai-get-format, ao-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-list, ao-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 'cop_format_string'
Adds a new chain operator. 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-describe
Returns a Ecasound Option Syntax (EOS) compliant string
describing the chain operator. See the Ecasound User's Guide for
more information about EOS. This command was introduced in
ecasound 2.4.4. [s]
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 'param_id', cop-index-select 'param_id', cop-iselect
'param_id'
Selects a chain operator. [-]
cop-selected
Returns the index number of currently selected chain operator.
[i]
cop-set 'chainop_id,param_id,value'
Changes the value of a single chain operator parameter. Unlike
other chain operator commands, this can also be used during
processing. See also 'cop-get'. [-]
cop-get 'chainop_id,param_id'
Returns the current value of chain operator parameter identified
by 'chainop_id' and 'param_id'. This command is a shorthand for
'cop-select chainop_id ; copp-iselect param_id ; copp-get'. [f]
cop-status
Returns info about chain operator status. [s]
copp-list
Returns a list of selected chain operator's parameters. [S]
copp-select 'param_id', copp-index-select 'param_id', copp-iselect
'param_id'
Selects a chain operator parameter. [-]
copp-selected
Returns the index number of currently selected chain operator
parameter. [i]
copp-set 'value'
Sets the selected parameter value to 'value'. [-]
copp-get
Returns the selected parameter value. See also 'cop-get'. [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 'copc_format_string'
Adds a new controller and attach it to currently selected chain
operator. The argument syntax is either
"-<id_string>:par1,...,parN" or just
"<id_string>:par1,...,parN". If parameter itself contains
commas, the parameter should be enclosed in double-quotes. See
ecasound (1) man page for more info. [-]
ctrl-describe
Returns a Ecasound Option Syntax (EOS) compliant string
describing the controller. See the Ecasound User's Guide for
more information about EOS. This command was introduced in
ecasound 2.4.4. [s]
ctrl-remove
Removes the selected controller. [-]
ctrl-list
Returns a list of all controllers attached to the currently
selected chain. [S]
ctrl-select 'param_id', ctrl-index-select 'param_id', ctrl-iselect
'param_id'
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]
ctrl-get-target
Returns the index number of the chain operator that is connected
to the selected controller. The returned index refers to the
currently selected chain (see 'cop-list'). [i]
ctrlp-list
Returns a list of all controller parameters. This command was
introduced in ecasound 2.4.2. [S]
ctrlp-select
Selects a controller parameter. This command was introduced in
ecasound 2.4.2. [-]
ctrlp-selected
Returns the index number of currently selected controller
parameter. This command was introduced in ecasound 2.4.2. [i]
ctrlp-get
Returns the selected controller parameter value. This command
was introduced in ecasound 2.4.2. [f]
ctrlp-set
Sets the selected controller parameter value to 'value'. This
command was introduced in ecasound 2.4.2. [-]
JACK CONNECTION MANAGEMENT
If Ecasound is compiled with support for JACK audio server, the
following set of commands is provided for controlling connections
between JACK ports.
jack-connect 'src-port' 'dest-port'
Make a connection between the two ports given as parameters.
This command is similar to the 'jack_connect' command line tool
that is distributed with JACK package. [-]
jack-disconnect 'src-port' 'dest-port'
Disconnect the two ports given as parameters. This command is
similar to the 'jack_disconnect' command line tool that is
distributed with JACK package. [-]
jack-list-connections
Returns a list of all JACK ports and a list of connections for
each port. This command is similar to the 'jack_lsp' command
line tool (e.g. 'jack_lsp -c') that is distributed with JACK
package. [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 interactive mode 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.
This command was introduced in ecasound 2.4.0. [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 0 items. This command
was introduced in ecasound 2.4.0. [-]
int-cmd-version-string
Returns ecasound interactive mode parser version string. [s]
int-cmd-version-lib-current
Returns ecasound interactive mode library interface version
(libtool). [i]
int-cmd-version-lib-revision
Returns ecasound interactive mode library interface revision
(libtool). [i]
int-cmd-version-lib-age
Returns ecasound interactive mode library interface age
(libtool). [i]
OBJECT MAPS
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 'filename'
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 'chainop,param'
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:
'keyword,name,description,num_of_params,par1_def,par2_def,...'
parX_def describes one object parameter. This definition is
present for all parameters of the described object type. The
used syntax is:
'name,description,defaultvalue,upper_bound_flag,upper_bound,
lower_bound_flag,lower_bound,toggled_flag,integer_flag,
logarithmic_flag,output_flag'
For exact descriptions of these fields, please see the header
file ecasound/libecasound/eca-operator.h.
DEPRECATED COMMANDS
Use of following commands is deprecated. They still work in current
version of Ecasound, but will be dropped in the future:
ai-wave-edit, ao-wave-edit
SEE ALSO
ecasound (1), ecatools (1), ecasoundrc (5)
AUTHOR
Kai Vehmanen, <kvehmanen -at- eca -dot- cx <kvehmanen -at- eca
-dot- cx>>
11.10.2009 ecasound-iam(1)