ecasound-iam (1)
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 EIAM use is ecasound´s control interface (ECI), which
is a small library providing easy access to the EIAM commands from out-
side of libecasound. When issuing EIAM commands using ECI, it´s possi-
ble that commands also return information. Currently supported return
value types are: string [s], list of strings [S], integer [i], long
integer [li] and floating-point number [f]. These definitions are used
throughout this document. Commands that do not return anything are
marked with [-]. Additionally, return type [e] marks an error condi-
tion. 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, q
Quit ecasound session. What this means in practice depends on
the client (library throws an exception). [-]
start, t
Processing is started (play). [-]
stop, s
Stop processing. [-]
run Like ´start´ but blocks until processing is finished. [-]
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 pro-
cessing. 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, out-
puts, chains, etc) are connected to some chainsetup. There can be many
chainsetups but only one can be connected. Similarly only one chain-
setup 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 typ-
ing 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 chain-
setups. [-]
"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 con-
nected)? [i]
cs-connect
Connect currently selected chainsetup to engine. Only one chain-
setup can be connected at a time. [-]
cs-disconnect
Disconnect currently connected chainsetup. [-]
cs-connected
Returns the name of currently connected chainsetup. [s]
cs-rewind ´time-in-seconds´, rewind ´time-in-seconds´, rw ´time-in-sec-
onds´
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-sec-
onds´ 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-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). [-]
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 infi-
nite length and chainsetup length is not explicitly set with
´cs-set-length´). [-]
cs-set-param
Interpret general chainsetup parameters like for example "-b"
(buffersize), "-m" (mixmode), "-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 chain-
setup. 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
Print status info about all chainsetups. [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! 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 other-
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 con-
trollers. 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
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. [-]
ai-add ´input_format_string´
Adds a new input object. See ecasound(1) man page for more info
about the argument format (´-i´ option). [-]
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)). [-]
ao-add-default
Adds the default output device (see ecasoundrc(5)). [-]
ai-select ´aobject_name´, ao-select ´aobject_name´
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 ´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. Espe-
cially 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). [-]
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-wave-edit, ao-wave-edit
The currently selected audio object is loaded into an external
wave editor (see ecasoundrc(5)). [-]
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 chain-
setup 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´
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 pro-
cessing. [-]
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. [f]
cop-register
Prints a list of registered chain operators. [s]
preset-register
Prints a list of registered effect presets. [s]
ladspa-register
ctrl-add ´copc_format_string´
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 ´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]
INTERNAL COMMANDS
Internal commands are not directly aimed at normal use. They are pri-
marily meant for use in scripting and frontends.
int-cmd-list
Returns a list of all registered EIAM commands. [S]
int-output-mode-wellformed
Select the well-format output format for log messages. [-]
int-cmd-version-string
Returns EIAM parser version string. [s]
int-cmd-version-lib-current
Returns EIAM library interface version (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-ctrl-list
Prints a list of registered controllers using the format speci-
fied in section OPERATOR DESCRIPTIONS. [s]
DUMP COMMANDS
The following dump commands are not meant for normal use. Their pri-
mary 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 std-
out).
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 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 sec-
onds, 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 sec-
onds, 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 regis-
tered 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, loga-
rithmic_flag,output_flag´
AUTHOR
Kai Vehmanen, <kai.vehmanen@wakkanet.fi>
20.08.2003 ecasound-iam(1)