## ecasound documentation - manual pages

# ecasound-iam

## 24.04.2001

## 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 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], 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 [-].

## 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-mute', 'c-bypass', 'c-rewind', 'c-forward', 'c-setpos', '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. [-]

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

help', 'h'
  Help! [-]

  ## GLOBAL

  status, st
    General status info. [s]

  engine-status
    Returns a string describing the engine status (running, stopped, finished, error, not ready). [s]

  ## 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'
    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. 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 '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-get-position, cs-getpos, getpos, get-position
    Returns the current chainsetup position in seconds. [f]

  cs-get-length, get-length
    Returns the chainsetup length in seconds (if known). [f]

  cs-set-length 'seconds'
    Sets processing time in seconds (doesn't have to be an integer value). [-]

  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), "-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 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, cs
    Print status info about all chainsetups. [s]

  ## 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. [-]

  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
    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', c-set-position '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. [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). [-]

  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)). [-]

  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. 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-getpos, ai-get-position, ao-getpos, ao-get-position
    Returns the audio object position in seconds. [f]

  ai-get-length, ao-get-length
    Returns the audio object length in seconds. [f]

  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 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. 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
    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. [-]

  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
    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. 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]

  ## OBJECT MAPS

  Object maps are a central repositories for commonly used objects. When object is registered to a map, a regular expression is attached to it. When object map receives a request for a new object, it goes through all registered regular expressions, and returns an object attached to the matching expression. Object maps can also provide a list of all registered objects.

map-aio-list
  **not implemented** Returns a list of regular expressions matching registered audio object types. [S].

map-aio-device-list
  **not implemented** Returns a list of regular expressions matching registered realtime audio object types. [S].

map-aio-type 'regexp'
  **not implemented** Returns the type name handling regular expression 'regexp'. [s].

map-cop-list
  **not implemented** Returns a list of regular expressions (chainop prefixes) matching registered chain operator types types. [S].

map-cop-type 'regexp'
  **not implemented** Returns the type name handling regular expression 'regexp'. [s].

map-ctrl-list
  **not implemented** Returns a list of regular expressions (controller prefixes) matching registered controller types types. [S].

map-ctrl-type 'regexp'
  **not implemented** Returns the type name handling regular expression 'regexp'. [s].

map-preset-list
  **not implemented** Returns a list of regular expressions (preset names) matching available operator presets. [S].

map-ladspa-list
  **not implemented** Returns a list of regular expressions (LADSPA unique id numbers) matching registered LADSPA plugins. [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-cmd-version-string
  Returns EIAM parser version string. [s]

int-cmd-version-lib-current
  Returns EIAM library interface version (libtool). [i]

int-cmd-version-lib-revision
  Returns EIAM library interface revision (libtool). [i]

int-cmd-version-lib-age
  Returns EIAM library interface age (libtool). [i]

  ## 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). [-]

  ## SEE ALSO

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

  ## AUTHOR

  Kai Vehmanen, <kaiv@wakkanet.fi>