1188 lines
51 KiB
HTML
1188 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>>
|