[Index] [Examples] [FAQ] [Man pages] [User's guide] [Programmer's guide] [Source tree] [ecasound home page]

[ecasound(1)] [ecatools(1)] [qtecasound(1)] [ecasound-iam(1)] [ecasoundrc(5)]


Ecasound documentation - manual pages

Ecasound-iam

ecasound-iam

27.03.2000

NAME

ecasound-iam - ecasound interactive mode

SYNOPSIS

DESCRIPTION

Ecasound library can be controlled with simple commands. This is called the interactive-mode. All programs linked to ecasound library can use this facility.

Notice! Hyphens and underlines are both accepted in command names (ie. c-add and c_add both work).

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.

debug 'debug-level'
Set debug level to 'debug-level'. Notice that client programs can reimplement the debug routines.

help', 'h'
Help!

GLOBAL

rewind 'time-in-seconds', rw 'time-in-seconds'
Rewind the current position by 'time-in-seconds' seconds.

forward 'time-in-seconds', fw 'ttime-in-seconds'
The current position is forwarded by 'time-in-seconds' seconds.

setpos 'time-in-seconds'
Sets the current position to 'time-in-seconds' seconds from the beginning.

status','st','u'
General status info.

DIRECT ARGUMENTS

One powerful feature of interactive-mode is that it understands ecasound's command-line syntax directly. This is often the easiest way to add effects and files. For instance, command "-efb:400,200" means that a bandpass filter is added to the currently selected chainsetup-chains combination, with initial parameters 400 (center frequency) and 200 (width in Hz).

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'
Add a new chainsetup with name 'name'. 'name' is now the selected chainsetup.

cs-remove
Remove currently selected chainsetup.

cs-select 'name'
Select chainsetup 'name'.

cs-index-select 'cs_index'
Select 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' format is "c<number>". You can get a list of all chainsetups (and their indexes) with the 'cs-status' command.

cs-load 'filename'
Add a new chainsetup by loading it from file 'filename'. 'filename' is now the selected chainsetup.

cs-save
Save currently selected chainsetup to file. If chainsetup was loaded from a file, it's saved to the same file. If it doesn't have a default filename, it's saved to "chainsetup_name.ecs".

cs-save-as 'filename'
Save 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-connect
Connect currently selected chainsetup to engine. Only one chainsetup can be connected at a time.

cs-disconnect
Disconnect currently connected chainsetup.

cs-length 'seconds'
Set processing time in seconds (doesn't have to be an integer value).

cs-loop
Enable looping. When processing is finished, engine will start again from the initial position.

cs-set
Interpret general chainsetup parameters like for example "-b" (buffersize), "-m" (mixmode), "-n" (name), etc. See ecasound(1) for more info.

cs-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, cstatus, cs, a
Print status info about all chainsetups.

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. Chain can be muted, unmuted and it can be bypassed. If not otherwise stated, all operations are done to currently selected chainsetup.

c-add 'cname1,...,cnameN'
Add chains. Added chains are automatically selected.

c-select 'cname1,...,cnameN'
Select chains. Other chains are automatically deselected.

c-deselect 'cname1,...,cnameN'
Deselect chains.

c-select-all
Select all chains.

c-select-add 'cname1,...,cnameN'
Select more chains.

c-remove
Remove selected chains.

c-clear
Clear selected chains by removing all chain operators and controllers. Doesn't change how chains are connected to inputs and outputs.

c-name 'new_name'
Rename selected chains. When using this command, only one chain must selected.

c-muting
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 untouched.

c-forward 'time_in_seconds', c-fw 'time_in_seconds'
Inputs and outputs connected to selected chains are forwarded by 'time-in-seconds' seconds. Time should be given as a floating point value (eg. 0.001 is the same as 1ms). If audio objecst are connected to multiple selected chains, they will be forwarded multiple times.

c-rewind 'time_in_seconds', c-rw 'time_in_seconds'
Inputs and outputs connected to selected chains are rewinded by 'time-in-seconds' seconds. Time should be given as a floating point value (eg. 0.001 is the same as 1ms). If audio objecst are connected to multiple selected chains, they will be forwarded multiple times.

c-setpos 'time_in_seconds'
Set position of all inputs and outputs connected to selected chains to 'time_in_seconds'.

c-status
Print status info about all chains.

AUDIO INPUT/OUTPUT OBJECTS

If not otherwise stated, all operations are done to currently selected chainsetup.

aio-add-input 'input_format_string'
Add a new input object. See ecasound(1) man page for more info about the argument format ('-i' option).

aio-add-output 'output_format_string'
Add 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)).

aio-select 'aobject_name'
Select some audio object. 'aobject_name' is usually a file name, but not always.

aio-select-input 'aobject_name'
Select some audio input.

aio-select-output 'aobject_name'
Select some audio output.

aio-index-select 'aobject_index'
Select some audio object based on 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' format is "i<number>" for inputs and similarly "o<number>" for outputs. You can get a list of all audio objects and their indexes with the 'aio-status' command.

aio-attach
Attach currently selected audio object to all selected chains.

aio-remove
Remove currently selected audio object.

aio-status
Audio object status (index strings, position, length, etc).

aio-forward 'time_in_seconds', aio-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).

aio-rewind 'time_in_seconds', aio-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).

aio-setpos 'time_in_seconds'
Set audio object position to 'time_in_seconds'.

aio-wave-edit
Currently selected audio object is loaded into an external wave editor (see ecasoundrc(5)).

aio-register
Prints a list of registered audio objects.

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 chains 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'
Add 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. See ecasound(1) man page for more info.

cop-remove 'chainop_id'
Remove chain operator.

cop-set 'chainop_id, param_id, value'
Change the value of a single chain operator parameter. Unlike other chain operator commands, this can also be used during processing.

cop-status
Info about chain operator status.

cop-register
Prints a list of registered chain operators.

preset-register
Prints a list of registered effect presets.

ladspa-register
Prints a list of registered LADSPA-plugins.

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.

cop-add-controller 'copc_format_string'
Add 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.

cop-remove-controller 'param_id'
Remove the controller that is attached to the currently selected chain operator.

ctrl-status
Info about controller status.

ctrl-register
Prints a list of registered controllers.

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-aio-selected
Dumps label of currently selected audio object. If no object is selected, dumps an empty string.

dump-aio-position
Dumps position of currently selected audio objects. Printed in seconds, using a floating-point representation.

dump-aio-length
Dumps length of currently selected audio object. Printed in seconds, using a floating-point representation.

dump-aio-open-state
Dumps audio object 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).

SEE ALSO

ecasound(1), qtecasound (1), ecatools (1), ecasoundrc(5)

AUTHOR

Kai Vehmanen, <kaiv@wakkanet.fi>