6a39e4f5f5
Renamed directory "dev" to "dev_tools". Replaced the ecasound-2.7.2 with a new download of ecasound. The reason is that the previous ecasound directory had all the Makefiles checked in with hardcoded paths from Naomi's computer. This prevented anyone else from being able to build. I copied over the modified version of ecacontrol.py.
1187 lines
51 KiB
HTML
1187 lines
51 KiB
HTML
<html><head>
|
|
<title>ecasound</title>
|
|
<link rev="made" href="mailto:kvehmanen -at- eca -dot- cx">
|
|
</head>
|
|
<body>
|
|
<hr>
|
|
<h1>ecasound</h1>
|
|
<h2>18.08.2010</h2>
|
|
|
|
<html><head>
|
|
<link rev="made" href="mailto:kvehmanen -at- eca -dot- cx">
|
|
</head>
|
|
<body>
|
|
<hr>
|
|
<h1></h1>
|
|
|
|
<html><head>
|
|
<title>ecasound(1)</title>
|
|
<link rev="made" href="mailto:kvehmanen -at- eca -dot- cx">
|
|
</head>
|
|
<body>
|
|
<hr>
|
|
<h1>ecasound(1)</h1>
|
|
<h2> Multimedia software</h2>
|
|
<h2>18.08.2010</h2>
|
|
|
|
|
|
<p>
|
|
<h2>NAME</h2>ecasound - sample editor, multitrack recorder, fx-processor, etc.
|
|
<p>
|
|
<h2>SYNOPSIS</h2>
|
|
<strong>ecasound</strong> [ general_options ] { [ chain_setup ] [ effect_setup ] [ input_setup ] [ output_setup ] }
|
|
<p>
|
|
<h2>DESCRIPTION</h2>
|
|
<p>
|
|
Ecasound is a software package designed for multitrack audio
|
|
processing. It can be used for simple tasks like audio playback,
|
|
recording and format conversions, as well as for multitrack effect
|
|
processing, mixing, recording and signal recycling. Ecasound supports
|
|
a wide range of audio inputs, outputs and effect algorithms.
|
|
Effects and audio objects can be combined in various ways, and their
|
|
parameters can be controlled by operator objects like oscillators
|
|
and MIDI-CCs. A versatile console mode user-interface is included
|
|
in the package.
|
|
<p>
|
|
<h2>OPTIONS</h2>
|
|
<p>
|
|
Note! All options except those mentioned in <em>ecasound options</em> and
|
|
<em>Global options</em>, can be used in ecasound chainsetup files (.ecs).
|
|
<p>
|
|
<dl>
|
|
<p>
|
|
|
|
<strong>ECASOUND OPTIONS</strong>
|
|
<p>
|
|
These options are parsed and handled by the ecasound frontend binary and
|
|
are not passed to backend library. This means that these options may
|
|
not work in other applications that use ecasound libraries for their
|
|
functionality.
|
|
<p>
|
|
<dl>
|
|
<p><dt><strong>-c</strong><dd>
|
|
Starts ecasound in interactive mode. In interactive mode you can
|
|
control ecasound with simple commands ("start", "stop", "pause",
|
|
etc.). See <a href="ecasound-iam_manpage.html">ecasound-iam </a>.
|
|
<p>
|
|
<p><dt><strong>-C</strong><dd>
|
|
Disables ecasound's interactive mode (see '-c' and '-K').
|
|
</dl>
|
|
<p>
|
|
<p><dt><strong>-D</strong><dd>
|
|
Print all debug information to stderr (unbuffered, plain output
|
|
without ncurses).
|
|
<p>
|
|
<p><dt><strong>-s[:]chainsetup-file</strong><dd>
|
|
Create a new chainsetup from file 'chainsetup-file' and add
|
|
it to the current session. Chainsetup files commonly have
|
|
a filename ending to the '.ecs' extension. A chainsetup can
|
|
contain inputs, outputs, chains, effects, controllers -- i.e.
|
|
objects one one specific configuration of audio processing
|
|
elements. A session, on the other hand, is a collection of
|
|
one or more chainsetups. Only one of the chainsetups may be
|
|
connected (i.e. it can be run/processed). But it is possible
|
|
to have another chainsetup select (i.e. can be configured)
|
|
while other one is current connteced (i.e. running).
|
|
<p>
|
|
<p><dt><strong>-E "cmd1 [[args] ; cmd2 args ; ... ; cmdN]"</strong><dd>
|
|
Execute a set of Ecasound Interactive mode (EIAM) commands
|
|
at launch. These commands are executed immediately after
|
|
ecasound is started. If the command line contains sufficient
|
|
options to create a valid chainsetup that will be executed,
|
|
the launch commands are executed after the other command
|
|
line options are parsed, but before the processing engine
|
|
is started. Note that this command is a feature of
|
|
the ecasound frontend binary and not supported by
|
|
the library backend. This means that other clients may
|
|
not support the '-E' option, and also that the launch
|
|
commands are not saved as part of chainsetup or session
|
|
state.
|
|
<p>
|
|
<p><dt><strong>--server</strong><dd>
|
|
Enables the so called NetECI mode, in which ecasound can
|
|
be controlled remotely over a socket connection. When
|
|
activated, clients can connect to the running ecasound
|
|
session, and use interactive mode commands to control and
|
|
observe ecasound processing.
|
|
<p>
|
|
The NetECI protocol is defined in
|
|
<a href="http://eca.cx/ecasound/Documentation/programmers_guide/ecasound_programmers_guide.html#neteci-various">Ecasound's Programmer Guide</a>
|
|
<p>
|
|
One example client using this feature is ecamonitor(1). This
|
|
utility is included in the Ecasound distribution package (requires
|
|
a working Python environment).
|
|
<p>
|
|
<em>Warning!</em> If the machine running ecasound, is connected to
|
|
a public network, be sure to block ecasound's port in your
|
|
firewall! As there is no access control implemented for incoming
|
|
connections, anyone can otherwise connect, control and observe your
|
|
ecasound sessions.
|
|
This option replaces '--daemon' (deprecated in 2.6.0).
|
|
<p>
|
|
<p><dt><strong>--server-tcp-port=NNN</strong><dd>
|
|
Set the TCP port used by the daemon mode. By default
|
|
ecasound will use port number <em>2868</em>.
|
|
This option replaces '--daemon-port' (deprecated in 2.6.0).
|
|
<p>
|
|
<p><dt><strong>--no-server</strong><dd>
|
|
Disable ecasound's daemon mode. This is the default.
|
|
This option replaces '--nodaemon' (deprecated in 2.6.0).
|
|
<p>
|
|
<p><dt><strong>--osc-udp-port=NNN</strong><dd>
|
|
Enables support for Open Source Control (OSC). Ecasound will listen
|
|
for incoming OSC messages on UDP port NNN. Ecasound's OSC interface
|
|
is documented at:
|
|
<http://ecasound.git.sourceforge.net/git/gitweb.cgi?p=ecasound/ecasound;a=blob;f=Documentation/ecasound_osc_interface.txt;hb=HEAD>
|
|
<p>
|
|
Note that OSC support is still experimental and the interface
|
|
might change in later versions of Ecasound.
|
|
<p>
|
|
This option was added to ecasound 2.7.0.
|
|
<p>
|
|
<p><dt><strong>--keep-running,-K</strong><dd>
|
|
Do not exit when processing is finished/stopped. Only affects
|
|
non-interactive operating mode (see -c/-C).
|
|
Option added to ecasound 2.4.2.
|
|
<p>
|
|
<p><dt><strong>--help,-h</strong><dd>
|
|
Show this help.
|
|
<p>
|
|
<p><dt><strong>--version</strong><dd>
|
|
Print version info.
|
|
<p>
|
|
</dl>
|
|
<p>
|
|
|
|
<strong>GLOBAL OPTIONS</strong>
|
|
<p>
|
|
<dl>
|
|
<p>
|
|
<p><dt><strong>-d, -dd, -ddd</strong><dd>
|
|
Increase the amount of printed debug messages. <em>-d</em> adds
|
|
some verbosity, while <em>-ddd</em> results in very detailed
|
|
output.
|
|
<p>
|
|
<p><dt><strong>-d:debug_level</strong><dd>
|
|
Set the debug level mask to 'debug_level'. This a bitmasked value with
|
|
the following classes: errors (1), info (2), subsystems (4), module_names (8),
|
|
user_objects (16), system_objects 32, functions (64), continuous (128) and
|
|
eiam_return_values (256). Default is 271 (1+2+4+8+256). See sourcode
|
|
documentation for the ECA_LOGGER class for more detailed information.
|
|
<p>
|
|
<p><dt><strong>-R[:]path-to-file</strong><dd>
|
|
Use ecasound resource file (see ecasoundrc man page) 'path-to-file' as
|
|
the only source of setting resource value. Specifying this option
|
|
will disable the normal policy of querying both global and user (if exists)
|
|
resource files.
|
|
<p>
|
|
<p><dt><strong>-q</strong><dd>
|
|
Quiet mode, no output. Same as <em>-d:0</em>.
|
|
<p>
|
|
</dl>
|
|
<p>
|
|
|
|
<strong>GENERAL CHAINSETUP OPTIONS</strong>
|
|
<dl>
|
|
<p>
|
|
<p><dt><strong>-a:chainname1, chainname2, ...</strong><dd>
|
|
Selects active signal chains. All inputs and outputs following
|
|
this '-a' option are assigned to selected chains (until a new -a
|
|
option is specified). When adding effects, controllers and other
|
|
chain operators, only one chain can be selected at a time. If no -a option
|
|
has been given, chain 'default' is used instead when adding objects.
|
|
Chain name 'all' is also reserved. It will cause all existing chains
|
|
to be selected. By giving multiple -a options, you can control to which
|
|
chains effects, inputs and outputs are assigned to. Look at the <strong>EXAMPLES</strong>
|
|
section for more detailed info about the usage of this option.
|
|
<p>
|
|
<p><dt><strong>-n:name</strong><dd>
|
|
Sets the name of chainsetup to 'name'. If not specified, defaults
|
|
either to "command-line-setup" or to the file name from which
|
|
chainsetup was loaded. Whitespaces are not allowed.
|
|
<p>
|
|
<p><dt><strong>-x</strong><dd>
|
|
Truncate outputs. All output object are opened in overwrite mode.
|
|
Any existing files will be truncated.
|
|
<p>
|
|
<p><dt><strong>-X</strong><dd>
|
|
Open outputs for updating. Ecasound opens all outputs - if target
|
|
format allows it - in readwrite mode.
|
|
<p>
|
|
<p><dt><strong>-z:feature</strong><dd>
|
|
Enables 'feature'. Most features can be disabled using notation
|
|
<em>-z:nofeature</em>. '-z:db,dbsize' enables double-buffering for audio
|
|
objects that support it (dbsize=0 for default, otherwise buffer
|
|
size in sample frames). '-z:nodb' disables double-buffering.
|
|
'-z:intbuf' and '-z:nointbuf' control whether extra internal buffering
|
|
is allowed for realtime devices. Disabling this can reduce
|
|
latency times in some situations. With '-z:xruns', processing will be
|
|
halted if an under/overrun occurs. '-z:multitrack' and
|
|
'z:nomultitrack' can be used to force ecasound to enable or disable
|
|
multitrack-mode. In rare cases you may want to explicitly specify
|
|
the recording offset with '-z:multitrack,offset-in-samples'. The
|
|
offset is the amount of samples skipped when recording from
|
|
real-time inputs. '-z:psr' enables the <em>precise-sample-rates</em> mode
|
|
for OSS-devices. '-z:mixmode,sum' enables mixing mode where channels
|
|
are mixed by summing all channels. The default is '-z:mixmode,avg',
|
|
in which channels are mixed by averaging. Mixmode selection was first
|
|
added to ecasound 2.4.0.
|
|
See <a href="ecasoundrc_manpage.html">ecasoundrc man page</a>.
|
|
<p>
|
|
</dl>
|
|
<p>
|
|
|
|
<strong>CHAINSETUP BUFFERING AND PERFORMANCE OPTIONS</strong>
|
|
<dl>
|
|
<p>
|
|
<p><dt><strong>-B:buffering_mode</strong><dd>
|
|
Selects the default buffering mode. Mode is one of: 'auto' (default),
|
|
'nonrt', 'rt', 'rtlowlatency'.
|
|
<p>
|
|
<p><dt><strong>-b:buffer size</strong><dd>
|
|
Sets the size of buffer in samples (must be an exponent of 2). This
|
|
is quite an important option. For real-time processing, you should
|
|
set this as low as possible to reduce the processing delay. Some
|
|
machines can handle buffer values as low as 64 and 128. In some
|
|
circumstances (for instance when using oscillator envelopes) small
|
|
buffer sizes will make envelopes act more smoothly. When not processing
|
|
in real-time (all inputs and outputs are normal files), values between
|
|
512 - 4096 often give better results. Default is 1024.
|
|
<p>
|
|
<p><dt><strong>-r:sched_priority</strong><dd>
|
|
Use realtime scheduling policy (SCHED_FIFO). This is impossible if
|
|
ecasound doesn't have root priviledges. Beware! This gives better
|
|
performance, but can cause total lock-ups if something goes wrong.
|
|
The 'sched_priority' can be omitted (0=omitted). If given,
|
|
this is the static priority to the highest priority ecasound thread.
|
|
Other ecasound threads run with priority 'sched_priority-1...n'.
|
|
Value '-1' can be used to disable raised-priority mode.
|
|
<p>
|
|
<p><dt><strong>-z:feature</strong><dd>
|
|
Relevant features are -z:db,xxx (-z:nodb) and -z:intbuf (-z:nointbuf).
|
|
See section <em>General chainsetup options</em> for details.
|
|
<p>
|
|
</dl>
|
|
<p>
|
|
|
|
<strong>PROCESSING CONTROL</strong>
|
|
<dl>
|
|
<p><dt><strong>-t:seconds</strong><dd>
|
|
Sets processing time in seconds (doesn't have to be an integer value).
|
|
If processing time isn't set, engine stops when all inputs are
|
|
finished. This option is equivalent to the 'cs-set-length' EIAM
|
|
command. A special-case value of '-1' will set the chainsetup length
|
|
according to the longest input object.
|
|
<p>
|
|
<p><dt><strong>-tl</strong><dd>
|
|
Enables looping. When processing is finished, engine will start
|
|
again from beginning. This option is equivalent to the 'cs-loop'
|
|
EIAM command.
|
|
<p>
|
|
</dl>
|
|
<p>
|
|
|
|
<strong>INPUT/OUTPUT SETUP</strong>
|
|
<p>
|
|
See <a href="users_guide/html_uguide/users_guide.html">ecasound user's guide</a> for
|
|
more detailed documentation.
|
|
<p>
|
|
<dl>
|
|
<p><dt><strong>-G:mgrtype,optstring</strong><dd>
|
|
Sets options for audio object manager type 'mgrtype'.
|
|
For available options, see "OBJECT TYPE SPECIFIC NOTES" below.
|
|
<p>
|
|
<p><dt><strong>-f:sample_format,channel,sample-rate,interleaving</strong><dd>
|
|
Sets the audio stream parameters for subsequent audio objects.
|
|
To set different parameters for different audio objects, multiple
|
|
'-f' options have to be specified (note the ordering, the '-f'
|
|
options should precede the audio objects for them to have any
|
|
effect). See documentation for '-i' and '-o' options.
|
|
<p>
|
|
When an audio object is opened (e.g. a file or sound device
|
|
is opened, or connection is made to a sound server), the audio
|
|
stream parameters are passed to the object. It should be noted that
|
|
not all audio objects allow to set any or all of the parameters.
|
|
For instance when opening existing audio files, many file formats
|
|
have a header describing the file audio parameters. In
|
|
these cases the audio file header overrides the parameters
|
|
passed with '-f' option. Similarly when creating JACK inputs and
|
|
outputs, the JACK server mandates the sampling rate and sample
|
|
format.
|
|
<p>
|
|
If no '-f' option is specified, or some of the argument fields
|
|
are left empty (e.g. '-f:,2,44100'), ecasound will use default values. These
|
|
default values are defined in ecasoundrc configuration file. See
|
|
ecasoundrc(5) manual page.
|
|
<p>
|
|
Note that ecasound opens out files by default in update mode.
|
|
Unless option '-x' (overwrite outputs) option is given,
|
|
audio parameters of an existing audio file take preference over
|
|
the params set with '-f'.
|
|
<p>
|
|
Sample format is given as a formatted string. The first letter is
|
|
either "u", "s" and "f" (unsigned, signed, floating point). The
|
|
following number specifies sample size in bits. If sample is
|
|
little endian, "_le" is added to the end. Similarly if big endian,
|
|
"_be" is added. If endianess is not specified, host byte-order is used.
|
|
Currently supported formats are "u8" (same as "8"), "s16_le" (same
|
|
as "16"), "s16_be", "s24_le", "s24_be", "s32_le", "s32_be", "f32_le"
|
|
and "f32_be". An empty string "" picks the system default sample
|
|
format.
|
|
<p>
|
|
The 4th parameter defines the channel layout. The available
|
|
options are 'i' (interleaved' and 'n' (noninterleaved). With
|
|
the noninterleaved setting, ecasound will process samples
|
|
one channel at a time, and the blocksize is set with '-b'.
|
|
The default setting is 'i'.
|
|
<p>
|
|
<p><dt><strong>-y:seconds</strong><dd>
|
|
Sets starting position for last specified input/output. If
|
|
you need more flexible control over audio objects, you should
|
|
use the <em>.ewf</em> format.
|
|
<p>
|
|
<p><dt><strong>-i[:]input-file-or-device[,params]</strong><dd>
|
|
Specifies a new input source that is connected to all selected chains (chains
|
|
are selected with '-a:...'). Connecting multiple inputs to the same chain is
|
|
not possible, but one input can be connected to multiple chains. Input can be
|
|
a a file, device or some other audio object (see below). If the input is
|
|
a file, its type is determined using the file name extension. If the object
|
|
name contains any commas, the name must be enclosed in backquotes to avoid
|
|
confusing the parser. Currently supported formats are RIFF WAVE files (.wav),
|
|
audio-cd tracks (.cdr), ecasound EWF files (.ewf), RAW audio data (.raw) and
|
|
MPEG audio files (.mp2,.mp3). More audio formats are supported via libaudiofile
|
|
and libsndfile libraries (see documentation below). MikMod is also supported (.xm,
|
|
.mod, .s3m, .it, etc). MIDI files (.mid) are supported using Timidity++.
|
|
Similarly Ogg Vorbis (.ogg) can be read, and written if ogg123 and vorbize tools
|
|
are installed; FLAC files (.flac) with flac command-line tools or using
|
|
libsndfile; and AAC files (.aac/.m4a/.mp4) with faad2/faac tools. Supported
|
|
realtime devices are OSS audio devices (/dev/dsp*), ALSA audio and loopback
|
|
devices and JACK audio subsystem. If no inputs are specified, the first
|
|
non-option (doesn't start with '-') command line argument is considered
|
|
to be an input.
|
|
<p>
|
|
<p><dt><strong>-o[:]output-file-or-device[,params]</strong><dd>
|
|
Works in the same way as the -i option. If no outputs are specified,
|
|
the default output device is used (see ~/.ecasoundrc). If the object
|
|
name contains any commas, the name must be enclosed in backquotes to
|
|
avoid confusing the parser. Note, many object types do not support
|
|
output (e.g. MikMod, MIDI and many others).
|
|
<p>
|
|
<em>OBJECT TYPE SPECIFIC NOTES</em>
|
|
<p><dt><strong>ALSA devices - 'alsa'</strong><dd>
|
|
When using ALSA drivers, instead of a device filename, you need to
|
|
use the following option syntax: <strong>-i[:]alsa,pcm_device_name</strong>.
|
|
<p>
|
|
<p><dt><strong>ALSA direct-hw and plugin access - 'alsahw', 'alsaplugin'</strong><dd>
|
|
It's also possible to use a specific card and device combination
|
|
using the following notation: <strong>-i[:]alsahw,card_number,device_number,subdevice_number</strong>.
|
|
Another option is the ALSA PCM plugin layer. It works just like
|
|
the normal ALSA pcm-devices, but with automatic channel count and
|
|
sample format conversions. Option syntax is
|
|
<strong>-i[:]alsaplugin,card_number,device_number,subdevice_number</strong>.
|
|
<p>
|
|
<p><dt><strong>aRts input/output - 'arts'</strong><dd>
|
|
If enabled at compile-time, ecasound supports audio input and
|
|
output using aRts audio server. Option syntax is <strong>-i:arts</strong>,
|
|
<strong>-o:arts</strong>.
|
|
<p>
|
|
<p><dt><strong>Audio file sequencing - 'audioloop', 'select', 'playat'</strong><dd>
|
|
Ecasound provides a set of special audio object types that
|
|
can be used for temporal sequencing of audio files - i.e. looping,
|
|
playing only a select portion of a file, playing file at a spefific
|
|
time, and other such operation.
|
|
<p>
|
|
Looping is possible with <strong>-i:audioloop,file.ext,params</strong>. The
|
|
file name (or any object type understood by Ecasound) given
|
|
as the second parameter is played back continuously looping
|
|
back to the beginning when the end of file is reached. Any additional
|
|
parameters given are passed unaltered to the file object.
|
|
Parameters 3...N are passed as is to the child object (i.e.
|
|
"-i audioloop,foo.wav,bar1,bar2" will pass parameters
|
|
"bar1,bar2" to the "foo.wav" object.
|
|
<p>
|
|
To select and use only a specific segment of an audio object,
|
|
the <strong>-i:select,start-time,duration,file.ext,params</strong> can
|
|
be used. This will play "duration" of "file.ext", starting at
|
|
"start-time". The time values should be given as seconds (e.g.
|
|
"2.25", or as samples (e.g. "25000sa"). Parameters 4...N are
|
|
passed as is to the child object.
|
|
<p>
|
|
To play an audio object at a given moment in time,
|
|
the <strong>-i:playat,play-at-time,file.ext,params</strong> can be
|
|
used. This will play "file.ext" after position reaches
|
|
"play-at-time". The time values should be given as seconds (e.g.
|
|
"2.25", or as samples (e.g. "25000sa"). Parameters 2...N are
|
|
passed as is to the child object.
|
|
<p>
|
|
<p><dt><strong>Ecasound Wave Files (EWF) - '*.ewf'</strong><dd>
|
|
A special file format that allows to slice and loop full (or segments)
|
|
of audio files. This format is specific to Ecasound.
|
|
See <a href="users_guide/html_uguide/users_guide.html">ecasound user's guide</a> for more
|
|
detailed information.
|
|
<p>
|
|
See also audio object types 'audioloop', 'select' and 'playat'.
|
|
<p>
|
|
<p><dt><strong>JACK input/outputs - Overview</strong><dd>
|
|
JACK is a low-latency audio server that can be used to connect
|
|
multiple independent audio application to each other.
|
|
It is different from other audio server efforts in that
|
|
it has been designed from the ground up to be suitable for low-latency
|
|
professional audio work.
|
|
<p>
|
|
<p><dt><strong>JACK input/outputs - 'jack'</strong><dd>
|
|
Ecasound provides multiple ways to communicate with JACK
|
|
servers. To create a JACK input or output object, one should use <strong>-i jack</strong> and
|
|
<strong>-o jack</strong>. These create JACK client ports "ecasound:in_N" and
|
|
"ecasound:out_n" respectively ('N' is replaced by the channel number).
|
|
Ecasound automatically creates one JACK port for each channel (number
|
|
of channels is set with <strong>-f:bits,channels,rate</strong> option).
|
|
<p>
|
|
It is important to note that by default JACK ports are not connected
|
|
anywhere (e.g. to soundcard input/outputs, or to other apps). One thus
|
|
has to connect the ports with an external program (e.g. "QJackCtl"
|
|
or "jack_connect").
|
|
<p>
|
|
<p><dt><strong>JACK input/outputs - 'jack,clientname,portprefix'</strong><dd>
|
|
<strong>"jack,clientname"</strong> For simple use scanerios, ecasound provides a way to autoconnect
|
|
the ecasound ports. This can be done with by giving the peer client
|
|
name as the second parameter to the "jack" object, e.g. <strong>-o jack,clientname</strong>.
|
|
As an example, <strong>-o jack,system</strong> will create an output that is
|
|
automatically connected to outputs of the default system soundcard.
|
|
The client parameter can be omitted, in which case no automatic
|
|
connections are made.
|
|
<p>
|
|
If one needs to change the port prefix (e.g. "in" in client name
|
|
"ecasound:in_N"), the prefix can be specified as the third parameter to
|
|
"jack" object, e.g. <strong>-o jack,,fxout</strong>. Also the third parameter can be
|
|
omitted, in which case the default prefixes "in" and "out" are used.
|
|
<p>
|
|
<p><dt><strong>JACK input/outputs - 'jack_multi'</strong><dd>
|
|
A variant of 'jack' object type is 'jack_multi'. The full object syntax
|
|
is <strong>jack_multi,destport1,...,destportN</strong>. When a 'jack_multi' object
|
|
is connected to a JACK server, first channel of the object is connected
|
|
to JACK port 'destport1', second to 'destport2' and so forth. For
|
|
instance "-f:32,2,44100 -o jack_multi,foo:in,bar:in"
|
|
creates a stereo ecasound output object, with its left and right
|
|
channels routed to two difference JACK clients. The destination ports
|
|
must be active when the ecasound engine is launched, or otherwise
|
|
the connections cannot be established. If destination ports are not
|
|
specified for all channels, or zero length strings are given, those
|
|
ports are not connected at launch by ecasound.
|
|
<p>
|
|
<p><dt><strong>JACK input/outputs - 'jack_alsa', 'jack_auto', 'jack_generic' (**deprecated since 2.6.0**)</strong><dd>
|
|
Ecasound 2.5 and older supported "jack_alsa", "jack_auto" and "jack_generic" object
|
|
types, but these are now replaced by a more generic "jack" interface, and thus are
|
|
now deprecated (they work but are no longer documented).
|
|
<p>
|
|
<p><dt><strong>JACK input/outputs - client options</strong><dd>
|
|
Additionally global JACK options can be set using
|
|
<strong>-G:jack,client_name,operation_mode</strong> option. 'client_name'
|
|
is the name used when registering ecasound to the JACK system.
|
|
If 'operation_mode' is "notransport", ecasound will ignore
|
|
any transport state changes in the JACK-system; in mode
|
|
"send" it will send all start, stop and position-change events to
|
|
other JACK clients; in mode "recv" ecasound will follow JACK start,
|
|
stop and position-change events; and mode "sendrecv" (the default)
|
|
which is a combination of the two previous modes.
|
|
<p>
|
|
More details about ecasound's JACK support can be found
|
|
from Ecasound User's Guide.
|
|
<p>
|
|
<p><dt><strong>Libaudiofile - 'audiofile'</strong><dd>
|
|
If libaudiofile support was enabled at compile-time, this
|
|
option allows you to force Ecasound to use libaudiofile
|
|
for reading/writing a certain audio file. Option syntax
|
|
is <strong>-i:audiofile,foobar.ext</strong> (same for <strong>-o</strong>).
|
|
<p>
|
|
<p><dt><strong>Libsndfile - 'sndfile'</strong><dd>
|
|
If libsndfile support was enabled at compile-time, this
|
|
option allows you to force Ecasound to use libsndfile
|
|
for reading/writing a certain audio file. Option syntax
|
|
is <strong>-i:sndfile,foobar.ext[,.format-ext]</strong> (same for <strong>-o</strong>).
|
|
The optional third parameter "format" can be used to
|
|
override the audio format (for example you can create an
|
|
AIFF file with filename "foo.wav").
|
|
<p>
|
|
<p><dt><strong>Loop device - 'loop'</strong><dd>
|
|
Loop devices make it possible to route (loop back) data between
|
|
chains. Option syntax is <strong>-[io][:]loop,tag</strong>. If you add
|
|
a loop output with tag '1', all data written to this output is routed
|
|
to any loop input with tag '1'. The tag can be either numerical
|
|
(e.g. '-i:loop,1') or a string (e.g. "-i:loop,vocals"). Like
|
|
with other input/output objects, you can attach the same loop
|
|
device to multiple chains and this way split/mix the signal.
|
|
<p>
|
|
Note: this 'loop' device is different from 'audioloop' (latter
|
|
added to ecasound v2.5.0).
|
|
<p>
|
|
<p><dt><strong>Mikmod - 'mikmod'</strong><dd>
|
|
If mikmod support was enabled at compile-time, this
|
|
option allows you to force Ecasound to use Mikmod
|
|
for reading/writing a certain module file. Option syntax
|
|
is <strong>-i:mikmod,foobar.ext</strong>.
|
|
<p>
|
|
<p><dt><strong>Null inputs/outputs - 'null'</strong><dd>
|
|
If you specify "null" or "/dev/null" as the input or output,
|
|
a null audio device is created. This is useful if you just want
|
|
to analyze sample data without writing it to a file. There's
|
|
also a realtime variant, "rtnull", which behaves just like "null"
|
|
objects, except all i/o is done at realtime speed.
|
|
<p>
|
|
<p><dt><strong>Resample - 'resample'</strong><dd>
|
|
Object type 'resample' can be used to resample audio
|
|
object's audio data to match the sampling rate used
|
|
in the active chainsetup. For example,
|
|
<strong>ecasound -f:16,2,44100 -i resample,22050,foo.wav -o /dev/dsp</strong>,
|
|
will resample file from 22.05kHz to 44.1kHz and write the
|
|
result to the soundcard device. Child sampling rate can be
|
|
replaced with keyword 'auto'. In this case ecasound will try
|
|
to query the child object for its sampling rate. This works with
|
|
files formats such as .wav which store meta information about
|
|
the audio file format. To use 'auto' in the previous example,
|
|
<strong>ecasound -f:16,2,44100 -i resample,auto,foo.wav -o /dev/dsp</strong>.
|
|
<p>
|
|
Parameters 4...N are passed as is to the child object (i.e.
|
|
"-i resample,22050,foo.wav,bar1,bar2" will pass parameters
|
|
"bar1,bar2" to the "foo.wav" object.
|
|
<p>
|
|
If ecasound was compiled with support for libsamplerate, you can
|
|
use 'resample-hq' to use the highest quality resampling algorithm
|
|
available. To force ecasound to use the internal resampler,
|
|
'resampler-lq' (low-quality) can be used.
|
|
<p>
|
|
<p><dt><strong>Reverse - 'reverse'</strong><dd>
|
|
Object type 'reverse' can be used to reverse audio
|
|
data coming from an audio object. As an example,
|
|
<strong>ecasound -i reverse,foo.wav -o /dev/dsp</strong> will play
|
|
'foo.wav' backwards. Reversing output objects is not
|
|
supported. Note! Trying to reverse audio object types with really
|
|
slow seek operation (like mp3), works extremely badly.
|
|
Try converting to an uncompressed format (wav or raw)
|
|
first, and then do reversation.
|
|
<p>
|
|
Parameters 3...N are passed as is to the child object (i.e.
|
|
"-i reverse,foo.wav,bar1,bar2" will pass parameters
|
|
"bar1,bar2" to the "foo.wav" object.
|
|
<p>
|
|
<p><dt><strong>System standard streams and named pipes - 'stdin', 'stdout'</strong><dd>
|
|
You can use standard streams (stdin and stdout) by giving <strong>stdin</strong>
|
|
or <strong>stdout</strong> as the file name. Audio data is assumed to be in
|
|
raw/headerless (.raw) format. If you want to use named pipes,
|
|
create them with the proper file name extension before use.
|
|
<p>
|
|
<p><dt><strong>Tone generator - 'tone'</strong><dd>
|
|
To generate a test tone, input <strong>-i:tone,type,freq,duration-secs</strong>
|
|
can be used. Parameter 'type' specifies the tone type: currently
|
|
only 'sine' is supported. The 'freq' parameter sets the frequency
|
|
of the generated tone and 'duration-secs' the length of the generated
|
|
stream. Specifying zero, or a negative value, as the duration will
|
|
produce an infinite stream. This feature was first added to Ecasound
|
|
2.4.7.
|
|
<p>
|
|
<p><dt><strong>Typeselect - 'typeselect'</strong><dd>
|
|
The special 'typeselect' object type can be used to override
|
|
how ecasound maps filename extensions and object types. For
|
|
instance <strong>ecasound -i typeselect,.mp3,an_mp3_file.wav -o /dev/dsp</strong>.
|
|
would play the file 'an_mp3_file.wav' as an mp3-file and not
|
|
as an wav-file as would happen without typeselect.
|
|
<p>
|
|
Parameters 4...N are passed as is to the child object (i.e.
|
|
"-i typeselect,.au,foo.wav,bar1,bar2" will pass parameters
|
|
"bar1,bar2" to the "foo.wav" object.
|
|
<p>
|
|
</dl>
|
|
<p>
|
|
|
|
<strong>MIDI SETUP</strong>
|
|
<p>
|
|
<dl>
|
|
<p><dt><strong>MIDI I/O devices - general</strong><dd>
|
|
If no MIDI-device is specified, the default MIDI-device is
|
|
used (see ecasoundrc(5)).
|
|
<p>
|
|
<p><dt><strong>-Md:rawmidi,device_name</strong><dd>
|
|
Add a rawmidi MIDI I/O device to the setup. 'device_name' can be anything
|
|
that can be accessed using the normal UNIX file operations and
|
|
produces raw MIDI bytes. Valid devices are for example OSS rawmidi
|
|
devices (/dev/midi00), ALSA rawmidi devices (/dev/snd/midiC2D0), named
|
|
pipes (see mkfifo man page), and normal files.
|
|
<p>
|
|
<p><dt><strong>-Md:alsaseq,sequencer-port</strong><dd>
|
|
Adds a ALSA MIDI sequencer port to the setup. 'sequencer-port' identifies
|
|
a port to connect to. It can be numerical (e.g. 128:1), or a client
|
|
name (e.g. "KMidimon").
|
|
<p>
|
|
<p><dt><strong>-Mms:device_id</strong><dd>
|
|
Sends MMC start ("Deferred Play") and stop ("Stop") with
|
|
device ID 'device_id'.
|
|
<p>
|
|
While Ecasound does not directly support syncing transport state
|
|
to incoming MMC messages, this can be achieved by connecting Ecasound
|
|
to JACK input/outputs, and using a tool such as JackMMC and JackCtlMMC (
|
|
see <http://jackctlmmc.sourceforge.net/>) to convert MMC messages
|
|
into JACK transport change events.
|
|
<p>
|
|
<p><dt><strong>-Mss</strong><dd>
|
|
Sends MIDI-sync (i.e. "MIDI Start" and "MIDI Stop" system realtime
|
|
messages) .to the selected MIDI-device. Notice that as Ecasound will
|
|
not send <em>MIDI-clock</em>, but only the <em>start</em> and <em>stop</em> messages.
|
|
<p>
|
|
</dl>
|
|
<p>
|
|
|
|
<strong>EFFECT SETUP</strong>
|
|
<p>
|
|
<em>PRESETS</em>
|
|
<p>
|
|
Ecasound has a powerful effect preset system that allows you create
|
|
new effects by combining basic effects and controllers. See
|
|
<a href="users_guide/html_uguide/users_guide.html">ecasound user's guide</a> for more
|
|
detailed information.
|
|
<p>
|
|
<dl>
|
|
<p>
|
|
<p><dt><strong>-pf:preset_file.eep</strong><dd>
|
|
Uses the first preset found from file 'preset_file.eep' as
|
|
a chain operator.
|
|
<p>
|
|
<p><dt><strong>-pn:preset_name</strong><dd>
|
|
Find preset 'preset_name' from global preset database and use
|
|
it as a chain operator. See ecasoundrc man page for info about the
|
|
preset database.
|
|
<p>
|
|
</dl>
|
|
<p>
|
|
<em>SIGNAL ANALYSIS</em>
|
|
<p>
|
|
<dl>
|
|
<p>
|
|
<p><dt><strong>-ev</strong><dd>
|
|
Analyzes sample data to find out how much the signal can
|
|
be amplified without clipping. The resulting percent value
|
|
can be used as a parameter to '-ea' (amplify). A statistical
|
|
summary, containing info about the stereo-image and
|
|
distribution of sample values, is printed out at the end
|
|
of processing.
|
|
<p>
|
|
<p><dt><strong>-evp</strong><dd>
|
|
Peak amplitude watcher. Maintains peak information for
|
|
each processed channels. Peak information is resetted
|
|
on every read.
|
|
<p>
|
|
<p><dt><strong>-ezf</strong><dd>
|
|
Finds the optimal value for DC-adjusting. You can use the result
|
|
as a parameter to -ezx effect.
|
|
<p>
|
|
</dl>
|
|
<p>
|
|
<em>GENERAL SIGNAL PROCESSING ALGORITHMS</em>
|
|
<dl>
|
|
<p><dt><strong>-eS:stamp-id</strong><dd>
|
|
Audio stamp. Takes a snapshot of passing audio data and stores
|
|
it using id 'stamp-id' (integer number). This data can later be
|
|
used by controllers and other operators.
|
|
<p>
|
|
<p><dt><strong>-ea:amplify%</strong><dd>
|
|
Adjusts the signal amplitude to 'amplify%' percent (linear scale, i.e.
|
|
individual samples are multiplied by 'amplify%/100'). See also
|
|
'-eadb'.
|
|
<p>
|
|
<p><dt><strong>-eac:amplify%,channel</strong><dd>
|
|
Amplifies signal of channel 'channel' by amplify-% percent (linear
|
|
scale, i.e. individual samples are multiplied by 'amplify%/100').
|
|
'channel' ranges from 1...n where n is the total number of channels.
|
|
See also '-eadb'.
|
|
<p>
|
|
<p><dt><strong>-eadb:gain-dB[,channel]</strong><dd>
|
|
Adjusts signal level by 'gain-dB', with a gain of 0dB having no effect
|
|
to the signal, negative gains attenuating the signal and positive
|
|
gain values amplifying it. The 'channel' parameter (1...n) is optional.
|
|
If 'channel' parameter is specified, and its value is nonzero, gain is
|
|
only applied to the given channel (1...n).
|
|
<p>
|
|
<p><dt><strong>-eaw:amplify%,max-clipped-samples</strong><dd>
|
|
Amplifies signal by amplify-% percent (linear scale, i.e. individual
|
|
samples are multiplied by 'amplify%/100'). If number of consecutive
|
|
clipped samples (resulting sample value is outside the nominal
|
|
[-1,1] range), a warning will be issued.
|
|
<p>
|
|
<p><dt><strong>-eal:limit-%</strong><dd>
|
|
Limiter effect. Limits audio level to 'limit-%' (linear scale) with
|
|
values equal or greater than 100% resulting in no change to
|
|
the signal.
|
|
<p>
|
|
<p><dt><strong>-ec:rate,threshold-%</strong><dd>
|
|
Compressor (a simple one). 'rate' is the compression rate in
|
|
decibels ('rate' dB change in input signal causes 1dB change
|
|
in output). 'threshold' varies between 0.0 (silence) and
|
|
1.0 (max amplitude).
|
|
<p>
|
|
<p><dt><strong>-eca:peak-level-%, release-time-sec, fast-crate, crate</strong><dd>
|
|
A more advanced compressor (original algorithm by John S. Dyson).
|
|
If you give a value of 0 to any parameter, the default is used.
|
|
'peak-level-%' essentially specifies how hard the peak limiter
|
|
is pushed. The default of 69% is good. 'release_time' is given
|
|
in seconds. This compressor is very sophisticated, and actually
|
|
the release time is complex. This is one of the dominant release
|
|
time controls, but the actual release time is dependent on a lot of
|
|
factors regarding the dynamics of the audio in. 'fastrate' is the
|
|
compression ratio for the fast compressor. This is not really
|
|
the compression ratio. Value of 1.0 is infinity to one, while the
|
|
default 0.50 is 2:1. Another really good value is special cased in
|
|
the code: 0.25 is somewhat less than 2:1, and sounds super smooth.
|
|
'rate' is the compression ratio for the entire compressor chain.
|
|
The default is 1.0, and holds the volume very constant without many nasty
|
|
side effects. However the dynamics in music are severely restricted,
|
|
and a value of 0.5 might keep the music more intact.
|
|
<p>
|
|
<p><dt><strong>-enm:threshold-level-%,pre-hold-time-msec,attack-time-msec,post-hold-time-msec,release-time-msec</strong><dd>
|
|
Noise gate. Supports multichannel processing (each channel
|
|
processed separately). When signal amplitude falls below
|
|
'threshold_level_%' percent (100% means maximum amplitude), gate
|
|
is activated. If the signal stays below the threshold for
|
|
'th_time' ms, it's faded out during the attack phase of
|
|
'attack' ms. If the signal raises above the 'threshold_level'
|
|
and stays there over 'hold' ms the gate is released during
|
|
'release' ms.
|
|
<p>
|
|
<p><dt><strong>-ei:pitch-shift-%</strong><dd>
|
|
Pitch shifter. Modifies audio pitch by altering its length.
|
|
<p>
|
|
<p><dt><strong>-epp:right-%</strong><dd>
|
|
Stereo panner. Changes the relative balance between the first
|
|
two channels. When 'right-%' is 0, only signal on the left
|
|
(1st) channel is passed through. Similarly if it is '100',
|
|
only right (2nd) channel is let through.
|
|
<p>
|
|
<p><dt><strong>-ezx:channel-count,delta-ch1,...,delta-chN</strong><dd>
|
|
Adjusts the signal DC by 'delta-chX', where X is the
|
|
channel number. Use -ezf to find the optimal delta
|
|
values.
|
|
<p>
|
|
</dl>
|
|
<p>
|
|
<em>ENVELOPE MODULATION</em>
|
|
<dl>
|
|
<p>
|
|
<p><dt><strong>-eemb:bpm,on-time-%</strong><dd>
|
|
Pulse gate (pulse frequency given as beats-per-minute).
|
|
<p>
|
|
<p><dt><strong>-eemp:freq-Hz,on-time-%</strong><dd>
|
|
Pulse gate.
|
|
<p>
|
|
<p><dt><strong>-eemt:bpm,depth-%</strong><dd>
|
|
Tremolo effect (tremolo speed given as beats-per-minute).
|
|
<p>
|
|
</dl>
|
|
<p>
|
|
<em>FILTER EFFECTS</em>
|
|
<dl>
|
|
<p><dt><strong>-ef1:center_freq, width</strong><dd>
|
|
Resonant bandpass filter. 'center_freq' is the center frequency. Width
|
|
is specified in Hz.
|
|
<p>
|
|
<p><dt><strong>-ef3:cutoff_freq, reso, gain</strong><dd>
|
|
Resonant lowpass filter. 'cutoffr_freq' is the filter cutoff
|
|
frequency. 'reso' means resonance. Usually the best values for
|
|
resonance are between 1.0 and 2.0, but you can use even bigger values.
|
|
'gain' is the overall gain-factor. It's a simple multiplier (1.0
|
|
is the normal level). With high resonance values it often is useful
|
|
to reduce the gain value.
|
|
<p>
|
|
<p><dt><strong>-ef4:cutoff, resonance</strong><dd>
|
|
Resonant lowpass filter (3rd-order, 36dB, original algorithm by Stefan
|
|
M. Fendt). Simulates an analog active RC-lowpass design. Cutoff is a
|
|
value between [0,1], while resonance is between [0,infinity).
|
|
<p>
|
|
<p><dt><strong>-efa:delay-samples,feedback-%</strong><dd>
|
|
Allpass filter. Passes all frequencies with no change in amplitude.
|
|
However, at the same time it imposes a frequency-dependent
|
|
phase-shift.
|
|
<p>
|
|
<p><dt><strong>-efc:delay-samples,radius</strong><dd>
|
|
Comb filter. Allows the spikes of the comb to pass through.
|
|
Value of 'radius' should be between [0, 1.0).
|
|
<p>
|
|
<p><dt><strong>-efb:center-freq,width</strong><dd>
|
|
Bandpass filter. 'center_freq' is the center frequency. Width
|
|
is specified in Hz.
|
|
<p>
|
|
<p><dt><strong>-efh:cutoff-freq</strong><dd>
|
|
Highpass filter. Only frequencies above 'cutoff_freq' are passed
|
|
through.
|
|
<p>
|
|
<p><dt><strong>-efi:delay-samples,radius</strong><dd>
|
|
Inverse comb filter. Filters out the spikes of the comb. There
|
|
are 'delay_in_samples-2' spikes. Value of 'radius' should be
|
|
between [0, 1.0). The closer it is to the maximum value,
|
|
the deeper the dips of the comb are.
|
|
<p>
|
|
<p><dt><strong>-efl:cutoff-freq</strong><dd>
|
|
Lowpass filter. Only frequencies below 'cutoff_freq' are passed
|
|
through.
|
|
<p>
|
|
<p><dt><strong>-efr:center-freq,width</strong><dd>
|
|
Bandreject filter. 'center_freq' is the center frequency. Width
|
|
is specified in Hz.
|
|
<p>
|
|
<p><dt><strong>-efs:center-freq,width</strong><dd>
|
|
Resonator. 'center_freq' is the center frequency. Width is specified
|
|
in Hz. Basicly just another resonating bandpass filter.
|
|
<p>
|
|
</dl>
|
|
<p>
|
|
<em>CHANNEL MIXING / ROUTING</em>
|
|
<dl>
|
|
<p>
|
|
<p><dt><strong>-chcopy:from-channel, to-channel</strong><dd>
|
|
Copy channel 'from_channel' to 'to_channel'. If 'to_channel'
|
|
doesn't exist, it is created. Channel indexing starts from 1.
|
|
Option added to ecasound 2.4.5.
|
|
<p>
|
|
<p><dt><strong>-chmove:from-channel, to-channel</strong><dd>
|
|
Copy channel 'from_channel' to 'to_channel', and mutes the source
|
|
channel 'from_channel'. Channel indexing starts from 1.
|
|
Option added to ecasound 2.4.5.
|
|
<p>
|
|
<p><dt><strong>-chorder:ch1,...,chN</strong><dd>
|
|
Reorder, omit and/r duplicate chain channels. The resulting
|
|
audio stream has total of 'N' channels. Each parameter specifies
|
|
the source channel to use for given output channel. As an
|
|
example, '-chorder:2,1' would reverse the channels of
|
|
a stereo stream ('out1,out2' = 'in2,in1'). Specifying the same
|
|
source channel multiple times is allowed. For example, '-chorder:2,2'
|
|
would route the second channel to both two output channels
|
|
('out1,out2' = 'in2,in2'). If 'chX' is zero, the given channel 'X'
|
|
will be muted in the output stream. Option added to ecasound 2.7.0.
|
|
<p>
|
|
<p><dt><strong>-chmix:to-channel</strong><dd>
|
|
Mix all source channels to channel 'to_channel'. If 'to_channel'
|
|
doesn't exist, it is created. Channel indexing starts from 1.
|
|
Option added to ecasound 2.4.5.
|
|
<p>
|
|
<p><dt><strong>-chmute:channel</strong><dd>
|
|
Mutes the channel 'channel'. Channel indexing starts from 1.
|
|
Option added to ecasound 2.4.5.
|
|
<p>
|
|
<p><dt><strong>-erc:from-channel,to-channel</strong><dd>
|
|
Deprecated, see <em>-chcopy</em>.
|
|
<p>
|
|
<p><dt><strong>-erm:to-channel</strong><dd>
|
|
Deprecated, see <em>-chmix</em>.
|
|
<p>
|
|
</dl>
|
|
<p>
|
|
<em>TIME-BASED EFFECTS</em>
|
|
<dl>
|
|
<p>
|
|
<p><dt><strong>-etc:delay-time-msec,variance-time-samples,feedback-%,lfo-freq</strong><dd>
|
|
Chorus.
|
|
<p>
|
|
<p><dt><strong>-etd:delay-time-msec,surround-mode,number-of-delays,mix-%,feedback-%</strong><dd>
|
|
Delay effect. 'delay time' is the delay time in milliseconds.
|
|
'surround-mode' is a integer with following meanings: 0 = normal,
|
|
1 = surround, 2 = stereo-spread. 'number_of_delays' should be
|
|
obvious. Beware that large number of delays and huge delay times
|
|
need a lot of CPU power. 'mix-%' determines how much effected (wet)
|
|
signal is mixed to the original. 'feedback-%' represents how much of
|
|
the signal is recycled in each delay or, if you prefer, at what rate
|
|
the repeated snippet of delayed audio fades. Note that sufficiently
|
|
low feedback values may result in a number of audible repetitions
|
|
lesser than what you have specified for 'number_of_delays', especially
|
|
if you have set a low value for 'mix-%'. By default the value for this
|
|
parameter is 100% (No signal loss.).
|
|
<p>
|
|
<p><dt><strong>-ete:room_size,feedback-%,wet-%</strong><dd>
|
|
A more advanced reverb effect (original algorithm by Stefan M. Fendt).
|
|
'room_size' is given in meters, 'feedback-%' is the feedback level
|
|
given in percents and 'wet-%' is the amount of reverbed signal added
|
|
to the original signal.
|
|
<p>
|
|
<p><dt><strong>-etf:delay-time-msec</strong><dd>
|
|
Fake-stereo effect. The input signal is summed to mono. The
|
|
original signal goes to the left channels while a delayed
|
|
version (with delay of 'delay time' milliseconds) is goes to
|
|
the right. With a delay time of 1-40 milliseconds this
|
|
adds a stereo-feel to mono-signals.
|
|
<p>
|
|
<p><dt><strong>-etl:delay-time-msec,variance-time-samples,feedback-%,lfo-freq</strong><dd>
|
|
Flanger.
|
|
<p>
|
|
<p><dt><strong>-etm:delay-time-msec,number-of-delays,mix-%</strong><dd>
|
|
Multitap delay. 'delay time' is the delay time in milliseconds.
|
|
'number_of_delays' should be obvious. 'mix-%' determines how much
|
|
effected (wet) signal is mixed to the original.
|
|
<p>
|
|
<p><dt><strong>-etp:delay-time-msec,variance-time-samples,feedback-%,lfo-freq</strong><dd>
|
|
Phaser.
|
|
<p>
|
|
<p><dt><strong>-etr:delay-time,surround-mode,feedback-%</strong><dd>
|
|
Reverb effect. 'delay time' is the delay time in milliseconds.
|
|
If 'surround-mode' is 'surround', reverbed signal moves around the
|
|
stereo image. 'feedback-%' determines how much effected (wet)
|
|
signal is fed back to the reverb.
|
|
<p>
|
|
</dl>
|
|
<p>
|
|
<em>LADSPA-PLUGINS</em>
|
|
<dl>
|
|
<p><dt><strong>-el:plugin_unique_name,param-1,...,param-N</strong><dd>
|
|
Ecasound supports LADSPA-effect plugins (Linux Audio Developer's Simple
|
|
Plugin API). Plugins are located in shared library (.so) files in
|
|
/usr/local/share/ladspa (configured in ecasoundrc man page). One shared
|
|
library file can contain multiple plugin objects, but every plugin
|
|
has a unique plugin name. This name is used for selecting plugins.
|
|
See <a href="http://www.linuxdj.com/audio/lad">LAD mailing list web site</a> for
|
|
more info about LADSPA. Other useful sites are <a href="http://www.ladspa.org">LADSPA home
|
|
page</a> and <a href="http://www.ffem.org/gdam/ladspa-doc/ladspa.html">LADSPA
|
|
documentation</a>.
|
|
<p>
|
|
<p><dt><strong>-eli:plugin_unique_number,param-1,...,param-N</strong><dd>
|
|
Same as above expect plugin's unique id-number is used. It
|
|
is guaranteed that these id-numbers are unique among all
|
|
LADSPA plugins.
|
|
<p>
|
|
</dl>
|
|
<p>
|
|
<em>GATE SETUP</em>
|
|
<p>
|
|
<dl>
|
|
<p>
|
|
<p><dt><strong>-gc:start-time,len</strong><dd>
|
|
Time crop gate. Initially gate is closed. After 'start-time' seconds
|
|
has elapsed, gate opens and remains open for 'len' seconds. When
|
|
closed, passing audio buffers are trucated to zero length.
|
|
<p>
|
|
<p><dt><strong>-ge:open-threshold-%,close-thold-%,volume-mode,reopen-count</strong><dd>
|
|
Threshold gate. Initially gate is closed. It is opened when volume
|
|
goes over 'othreshold' percent. After this, if volume drops below
|
|
'cthold' percent, gate is closed and won't be opened again, unless the
|
|
'reopen-count' is set to anything other than zero.
|
|
If 'value_mode' is 'rms', average RMS volume is used. Otherwise
|
|
peak average is used. When closed, passing audio buffers are trucated
|
|
to zero length.
|
|
If the 'reopen-count' is set to a positive number, then the gate will
|
|
restart its operation that many times. So for example, a reopen count
|
|
of 1 will cause up to 2 openings of the gate. A negative value for 'reopen-count'
|
|
will result in the gate reopening indefinitely. The 'reopen-count' is invaluable
|
|
in recording vinyl and tapes, where you can set things up and then recording
|
|
starts whenever the needle is on the vinyl, and stops when it's off. As many sides
|
|
as you like can be recorded in one session. You will need to experiment with
|
|
buffer lengths and start/stop levels to get reliable settings for your equipment.
|
|
<p>
|
|
<p><dt><strong>-gm:state</strong><dd>
|
|
Manual gate. If 'state' is 1, gate is open and all samples are
|
|
passed through. If 'state' is zero, gate is closed an no samples are
|
|
let through. This chain operator is useful when writing to an output
|
|
needs to be stopped dynamically (without stopping the whole engine).
|
|
<p>
|
|
</dl>
|
|
<p>
|
|
|
|
<em>CONTROL ENVELOPE SETUP</em>
|
|
<dl>
|
|
<p>
|
|
Controllers can be used to dynamically change effect parameters
|
|
during processing. All controllers are attached to the selected
|
|
(=usually the last specified effect/controller) effect. The first
|
|
three parameters are common for all controllers. 'fx_param'
|
|
specifies the parameter to be controlled. Value '1' means
|
|
the first parameter, '2' the second and so on. 'start_value'
|
|
and 'end_value' set the value range. For examples, look at the
|
|
the <strong>EXAMPLES</strong> section.
|
|
<p>
|
|
<p><dt><strong>-kos:fx-param,start-value,end-value,freq,i-phase</strong><dd>
|
|
Sine oscillator with frequency of 'freq' Hz and initial phase
|
|
of 'i_phase' times pi.
|
|
<p>
|
|
<p><dt><strong>-kog:fx-param,freq,mode,point-pairs,start-value,end-value,pos1,value1,...</strong><dd>
|
|
Generic oscillator. Frequency 'freq' Hz, mode either '0' for
|
|
static values or '1' for linear interpolation. 'point-pairs'
|
|
specifies the number of 'posN' - 'valueN' pairs to include.
|
|
'start-value' and 'end-value' are used as border values.
|
|
All 'posN' and 'valueN' must be between 0.0 and 1.0. Also,
|
|
for all 'posN' values 'pos1 < pos2 < ... < posN' must be true.
|
|
<p>
|
|
<p><dt><strong>-kf:fx-param,start-value,end-value,freq,mode,genosc-number</strong><dd>
|
|
Generic oscillator. 'genosc_number' is the number of the
|
|
oscillator preset to be loaded. Mode is either '0' for
|
|
static values or '1' for linear interpolation. The location for
|
|
the preset file is taken from ./ecasoundrc (see <em>ecasoundrc man page</em>).
|
|
<p>
|
|
<p><dt><strong>-kl:fx-param,start-value,end-value,time-seconds</strong><dd>
|
|
Linear envelope that starts from 'start_value' and linearly
|
|
changes to 'end_value' during 'time_in_seconds'. Can
|
|
be used for fadeins and fadeouts.
|
|
<p>
|
|
<p><dt><strong>-kl2:fx-param,start-value,end-value,1st-stage-length-sec,2nd-stage-length-sec</strong><dd>
|
|
Two-stage linear envelope, a more versatile tool for doing fade-ins
|
|
and fade-outs. Stays at 'start_value' for '1st_stage_length' seconds
|
|
and then linearly changes towards 'end_value' during
|
|
'2nd_stage_length' seconds.
|
|
<p>
|
|
<p><dt><strong>-klg:fx-param,low-value,high-value,point_count,pos1,value1,...,posN,valueN</strong><dd>
|
|
Generic linear envelope. This controller source can be
|
|
used to map custom envelopes to chain operator parameters. Number of
|
|
envelope points is specified in 'point_count'. Each envelope point
|
|
consists of a position and a matching value. Number of pairs must
|
|
match 'point_count' (i.e. 'N==point_count'). The 'posX' parameters are given
|
|
as seconds (from start of the stream). The envelope points are specified as
|
|
float values in range '[0,1]'. Before envelope values are mapped to operator
|
|
parameters, they are mapped to the target range of '[low-value,high-value]'. E.g.
|
|
a value of '0' will set operator parameter to 'low-value' and a value of
|
|
'1' will set it to 'high-value'. For the initial segment '[0,pos1]', the envelope
|
|
will output value of 'value1' (e.g. 'low-value').
|
|
<p>
|
|
<p><dt><strong>-km:fx-param,start-value,end-value,controller,channel</strong><dd>
|
|
MIDI continuous controller (control change messages).
|
|
Messages on the MIDI-channel 'channel' that are coming from
|
|
controller number 'controller' are used as the controller
|
|
source. As recommended by the MIDI-specification, channel
|
|
numbering goes from 1 to 16. Possible controller numbers
|
|
are values from 0 to 127. The MIDI-device where bytes
|
|
are read from can be specified using <em>-Md</em> option.
|
|
Otherwise the default MIDI-device is used as specified in
|
|
<em>~ecasound/ecasoundrc</em> (see <em>ecasoundrc man page</em>).
|
|
Defaults to <em>/dev/midi</em>.
|
|
<p>
|
|
<p><dt><strong>-ksv:fx-param,start-value,end-value,stamp-id,rms-toggle</strong><dd>
|
|
Volume analyze controller. Analyzes the audio stored in
|
|
stamp 'stamp-id' (see '-eS:id' docs), and creates
|
|
control data based on the results. If 'rms-toggle' is non-zero,
|
|
RMS-volume is used to calculate the control value. Otherwise
|
|
average peak-amplitude is used.
|
|
<p>
|
|
<p><dt><strong>-kx</strong><dd>
|
|
This is a special switch that can be used when you need
|
|
to control controller parameters with another controller.
|
|
When you specify <em>-kx</em>, the last specified controller
|
|
will be set as the control target. Then you just add
|
|
another controller as usual.
|
|
</dl>
|
|
<p>
|
|
|
|
<strong>INTERACTIVE MODE</strong>
|
|
<p>
|
|
See <em>ecasound-iam(1)</em> man page.
|
|
<p>
|
|
</dl>
|
|
<p>
|
|
<h2>ENVIRONMENT</h2>
|
|
<p>
|
|
<dl>
|
|
<p><dt><strong>ECASOUND</strong><dd>
|
|
If defined, some utility programs and scripts will use
|
|
the <em>ECASOUND</em> environment as the default path to
|
|
ecasound executable.
|
|
<p>
|
|
<p><dt><strong>ECASOUND_LOGFILE</strong><dd>
|
|
Output all debugging messages to a separate log file. If defined,
|
|
<em>ECASOUND_LOGFILE</em> defines the logfile path. This is a good tool for
|
|
debugging ECI/EIAM scripts and applications.
|
|
<p>
|
|
<p><dt><strong>ECASOUND_LOGLEVEL</strong><dd>
|
|
Select which messages are written to the logfile defined by
|
|
<em>ECASOUND_LOGFILE</em>. The syntax for <em>-d:level</em> is used. If not
|
|
defined, all messages are written. Defaults to -d:319 (everything else
|
|
but 'functions (64)' and 'continuous (128)' class messages).
|
|
<p>
|
|
<p><dt><strong>COLUMNS</strong><dd>
|
|
Ecasound honors the <em>COLUMNS</em> environment variable when
|
|
formatting printed trace messages. If <em>COLUMNS</em> is not set,
|
|
a default of 74 is used.
|
|
<p>
|
|
<p><dt><strong>TMPDIR</strong><dd>
|
|
Some functions of Ecasound (e.g. "cs-edit" interactive command) require
|
|
creation of temporary files. By default, these files are created under
|
|
"/tmp", but this can be overridden by setting the <em>TMPDIR</em> environment
|
|
variable.
|
|
</dl>
|
|
<p>
|
|
<h2>RETURN VALUES</h2>
|
|
<p>
|
|
In interactive mode, ecasound always returns zero.
|
|
<p>
|
|
In non-interactive (batch) mode, a non-zero value is returned
|
|
for the following errors:
|
|
<p>
|
|
<dl>
|
|
<p><dt><strong>1</strong><dd>
|
|
Unable to create a valid chainsetup with the given parameters. Can be
|
|
caused by invalid option syntax, etc.
|
|
<p>
|
|
<p><dt><strong>2</strong><dd>
|
|
Unable to start processing. This can be caused by insufficient file
|
|
permissions, inability to access some system resources, etc.
|
|
<p>
|
|
<p><dt><strong>3</strong><dd>
|
|
Error during processing. Possible causes: output object has run
|
|
out of free disk space, etc.
|
|
<p>
|
|
<p><dt><strong>4</strong><dd>
|
|
Error during process termination and/or cleanup. See section
|
|
on 'SIGNALS' for further details.
|
|
<p>
|
|
<h2>SIGNALS</h2>
|
|
<p>
|
|
When ecasound receives any of the POSIX signals SIGINT (ctrl-c),
|
|
SIGHUP, SIGTERM or SIGQUIT, normal cleanup and exit procedure is
|
|
initiated. Here normal exit means that e.g. file headers are
|
|
updated before closing, helper processes are terminated in normal
|
|
way, and so forth.
|
|
<p>
|
|
If, while doing the cleanup described above, ecasound receives
|
|
another signal (of the same set of POSIX signals), ecasound
|
|
will skip the normal cleanup procedure, and terminate
|
|
immediately. Any remaining cleanup tasks will be skipped.
|
|
Depending on the runtime state and configuration, this brute
|
|
force exit may have some side-effects. Ecasound will return
|
|
exit code of '4' if normal cleanup was skipped.
|
|
<p>
|
|
Special case handling is applied to the SIGINT (ctrl-c) signal.
|
|
If a SIGINT signal is received during the cleanup procedure,
|
|
ecasound will ignore the signal once, and emit a notice to 'stderr'
|
|
that cleanup is already in progress. Any subsequent SIGINT signals
|
|
will no longer get special handling, and instead process will
|
|
terminate immediately (and possibly without proper cleanup).
|
|
<p>
|
|
<h2>FILES</h2>
|
|
<p>
|
|
<em>~/.ecasound</em>
|
|
The default directory for ecasound user resource files.
|
|
See the <a href="ecasoundrc_manpage.html">ecasoundrc (5) man page</a> man page.
|
|
<p>
|
|
<em>*.ecs</em>
|
|
Ecasound Chainsetup files. Syntax is more or less the
|
|
same as with command-line arguments.
|
|
<p>
|
|
<em>*.ecp</em>
|
|
Ecasound Chain Preset files. Used for storing effect
|
|
and chain operator presets. See <a href="users_guide/html_uguide/users_guide.html">ecasound user's guide</a> for
|
|
more better documentation.
|
|
<p>
|
|
<em>*.ews</em>
|
|
Ecasound Wave Stats. These files are used to cache
|
|
waveform data.
|
|
<p>
|
|
<h2>EXAMPLES</h2>
|
|
<p>
|
|
Examples of how to perform common tasks with ecasound can
|
|
be found at
|
|
<a href="http://eca.cx/ecasound/Documentation/examples.html">http://eca.cx/ecasound/Documentation/examples.html</a>.
|
|
<p>
|
|
<h2>SEE ALSO</h2>
|
|
<p>
|
|
<a href="ecatools_manpage.html">ecatools (1) man page</a>,
|
|
<a href="ecasound-iam_manpage.html">ecasound-iam (1) man page</a>
|
|
<a href="ecasoundrc_manpage.html">ecasoundrc (5) man page</a>,
|
|
<a href="index.html">"HTML docs in the Documentation subdirectory"</a>
|
|
<p>
|
|
<h2>BUGS</h2>
|
|
<p>
|
|
See file BUGS. If ecasound behaves weirdly, try to
|
|
increase the debug level to see what's going on.
|
|
<p>
|
|
<h2>AUTHOR</h2>
|
|
<p>
|
|
Kai Vehmanen, <<a href="mailto:kvehmanen -at- eca -dot- cx"><em>kvehmanen -at- eca -dot- cx</em></a>>
|