Congegni
/
sintonia
7
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
sintonia/library/ecasound/Documentation/users_guide/users_guide.latex

1057 lines
41 KiB
Plaintext
Raw Blame History

\documentclass{report}
\usepackage[T1]{fontenc}
\usepackage{ae}
\usepackage{hevea}
\usepackage{hyperref}
\title{Ecasound User's Guide}
\author{Kai Vehmanen}
\date{19042009}
\begin{document}
\maketitle
\tableofcontents
\clearpage
% ----------------------------------------------------------------------
% ----------------------------------------------------------------------
\chapter{Preface}
This document describes Ecasound from the user's point of view. In
addition to the actual user/client-programs, all essential Ecasound
library concepts and features are also discussed. To avoid duplicating
documentation, I've used references to other sources whenever suitable.
For instance, Ecasound's man pages are a very good (and up-to-date!)
source of information. They are also available in HTML-format.
If not otherwise specified, all documentation refers to the latest
Ecasound version.
% ----------------------------------------------------------------------
% ----------------------------------------------------------------------
\chapter{Document history}
\begin{itemize}
\item 19.04.2009 - Removed duplicate Ecasound history section and added
more web URLs pointing to other sources of
documentation.
\item 31.01.2009 - Lots of minor improvements in preparation for
2.6.0 release.
\item 29.01.2009 - Updated ``JACK Audio Server'' section to match
the changes in 2.6.0 release.
\item 05.08.2008 - Fixed a bug in example of loop device usage.
\item 09.03.2008 - Updated the EWF file section. Replace uses of ``/dev/dsp''
with ``alsa'' in many examples.
\item 06.12.2006 - Added notes concerning quoting EOS arguments containing
commas.
\item 04.06.2006 - Some minor improvements to the text. Updated the descriptions of
realtime-lsm and rlimits-rtprio mechanisms.
\item 25.04.2005 - From now on, only major changes are logged to this changelog
section. For detailed change history, refer to CVS history.
\item 23.04.2005 - Started using the ``hevea'' style-package and converted
all links to use the hevea macros (resulting in real hyperlinks
in the HTML output). Renamed the section
``Security considerations when running with root privileges''
to shorter ``Security Considerations'', added info
about Realtime LSM module.
\item 01.04.2005 - Updated ``Ecasignalview'' documentation.
\item 30.03.2005 - Added sections on ``Preset parameters'' and
``Parameter descriptors''.
\item 11.12.2004 - Added section ``Filenames with commas not handled correctly''
\item 18.12.2003 - Many typo fixes and other corrections from Eric
Rzewnicki.
\item 18.11.2003 - Typo fixes.
\item 20.08.2003 - Capitalize Ecasound in all cases where talking
about the software package, not the console mode
user-interface. Updated JACK documentation with
a description of JACK and Ecasound states.
\item 13.08.2003 - Updated documentation concerning JACK transport
functions.
\item 31.10.2002 - Few section layout bugs fixed.
\item 30.10.2002 - Added JACK documentation, minor layout changes.
\item 17.10.2002 - Updated Ecasound overview.
\item 17.07.2002 - Added documentation for ecasignalview.
\item 18.05.2002 - Fixed a few typos.
\item 21.10.2001 - Added material from the Ecasound FAQ.
\item 21.10.2001 - Added this history section. Document was
restructured and all major chapters reviewed.
\item 01.02.2001 - Updated the ``Current position'' section.
\end{itemize}
% ----------------------------------------------------------------------
% ----------------------------------------------------------------------
\chapter{Introduction}
% ----------------------------------------------------------------------
\section{What is Ecasound?}
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.
% ----------------------------------------------------------------------
% ----------------------------------------------------------------------
\chapter{Ecasound concepts}
% ----------------------------------------------------------------------
\section{Audio object}
Audio objects are used to transfer audio from and to Ecasound.
Usually audio objects are either files (like wav, mp3 or ogg)
or devices (soundcard input/output). There are also some
special audio object types for transferring data between
applications.
% ----------------------------------------------------------------------
\section{Chain}
Chain is the central signal flow abstraction. In many ways chains
are similar to audio cables. You have one input and one output
to which you can connect audio producers and consumers
(like guitar and amplifier for instance).
But there are some differences. First it's possible to attach
chain operators (usually effects) to chains. This is somewhat like
replacing one cable with two, and putting an effect box between
them, but with chains it's just easier. A second important difference
is that chains can transport multiple channels of audio. It's possible
to attach mono, stereo or 24ch (or bigger) audio feeds to one
chain. Also all chain operators can handle these multichannel
streams.
In addition to chain operators, chains also have separate
``mute'' and ``bypass'' functions.
% ----------------------------------------------------------------------
\section{Chain operators and controllers}
Chain operators are used to process and analyze sample data.
They can be divided into gates, converters, signal analyzers and
to traditional effects like reverbs, delays and filters.
It's also possible to attach special controller objects to chains.
These controllers are used to control chain operator parameters.
The typical examples are various oscillators and MIDI continous
controllers (knobs, sliders, etc found on MIDI-devices).
Both types of objects are attached to chains. The term \emph{chain object}
refers to all objects that can be attached to chains - ie.
operators and controllers.
% ----------------------------------------------------------------------
\section{Chainsetup}
Chainsetup is the central data object. All other objects (inputs,
outputs, chains, etc) are connected to some chainsetup.
Many chainsetups can exist at the same time (during one session),
but only one of them can be in use. In Ecasound documentation,
the term \emph{connected} is used to describe a chainsetup that
is in use.
Another important chainsetup concept is that of a \emph{selected}
chainsetup. All editing operations are done on the currently selected
chainsetup. It is possible to have one chainsetup connected (currently
processing audio), while editing another, chainsetup that is selected
for editing.
Loading and saving chainsetups is the primary mechanism
for storing and restoring state information. When saving
to files, the \emph{.ecs} file format is used. The file syntax
uses the same notation as Ecasound's console (and command-line)
interface. This makes it easy to edit the chainsetup files
outside Ecasound, either manually or using external utils.
See \href{http://eca.cx/ecasound/Documentation/ecasound_manpage.html}{ecasound(1)}
man page for details.
% ----------------------------------------------------------------------
\section{Current position}
Information about current position is only stored for audio
objects and chainsetups. When you change chainsetup position,
all audio objects are affected. On the other hand, positions
of different audio objects can be changed independently.
% ----------------------------------------------------------------------
\section{Ecasound Control Interface - ECI}
Ecasound Control Interface is an API for application
developers who want to take advantage of libecasound
in their own apps. See ``Ecasound Control Interface Guide''
and ``Ecasound Programmer's Guide'' for more information.
% ----------------------------------------------------------------------
\section{Ecasound Interactive Mode - EIAM}
Most of Ecasound's functionality is located in one
central library (libecasound). One thing that this library
provides is a simple interpreter, which can be used for
controlling Ecasound. This mode of operation is better
known as Ecasound's Interactive Mode (EIAM)
The most common frontend for the Interactive Mode is the console-mode
Ecasound program. You can enter its Enteractive Mode
by issuing ``ecasound -c''. For more detailed information
the available commands, see \texttt{ecasound-iam(1)} man page.
% ----------------------------------------------------------------------
\section{Ecasound Option Syntax - EOS}
One very notable feature of the console-mode ecasound
program is its command-line option syntax. You can
do pretty much everything from the command-line.
But it doesn't end with the console mode ecasound. In
fact, interpreting these options is located in
the main libecasound library, and is very closely tied
to the interactive mode.
As a result, the same syntax (tokens that look like
``-prefix:arg1,arg2,...,argN''), is used in various
parts of libecasound. Note that if any of the arguments
contain commas, those arguments need to be enclosed in
double-quotes (for example ``-prefix:"ar,g1",arg2'').
Following is a partial list of the places where EOS syntax
has been used:
\begin{itemize}
\item parsing command-line options
\item the interactive-mode (as arguments to the 'cs-option' command
[2.1dev4 and newer])
\item saved chainsetup-files (.ecs format)
\item effect preset definitions (see for example
``/usr/share/ecasound/effect\_presets'')
\item generic oscillator definitions (see for example
``/usr/share/ecasound/generic\_oscillators''
\end{itemize}
% ----------------------------------------------------------------------
% ----------------------------------------------------------------------
\chapter{Using}
% ----------------------------------------------------------------------
\section{Where to start?}
There's no one single right way to use Ecasound. You can use it as
a simple glue component for doing tasks that aren't handled by
other applications you are using, or because Ecasound does these tasks
more easily (or better even :)). But Ecasound can also serve as the
centre of your studio setup, doing everything from effects processing
to multitrack recording and mixing.
This flexibility doesn't come for free. It's difficult to describe
Ecasound's features in a few phrases. Because of this, new users
are encouraged to start from the \texttt{Examples page} at
\url{http://www.eca.cx/ecasound/Documentation/examples.html}.
It isn't a perfect introduction, and definitely shows only one way to
use the software, but it does give an overall view of what can be done,
and more importantly, it shows that many tasks are actually quite simple
to do.
% ----------------------------------------------------------------------
\section{Rules for creating and modifying chainsetups}
Here are a few rules that help writing valid chainsetups.
Whether you are editing chainsetup files (.ecs), some
graphical frontend, just using command-line options, etc;
these rules always apply:
\begin{itemize}
\item Every chain has exactly \_one\_ input and \_one\_ output.
\item All inputs and outputs must be connected to some chain.
\item For every input/output, there is one and only one
definition (example: ``-i:file.wav'').
\item All routing from and to chains is based on selecting a set of
chains and then specifying an input or output (example:
``-a:1,2 -i:file.ext'').
\item All audio copying and mixing is done channel-wise. If you attach
a 4-channel input and a two-channel output to a chain, that chain
will have 4 channels of audio, but only the first two channels
will be written to the output file.
\end{itemize}
Note that these rules are checked only when \emph{connecting} the
chainsetup (when issuing commands such as ``cs-connect'', or ``start'').
% ----------------------------------------------------------------------
\section{Chain operators and controllers}
The best place to start is to read through
the \href{http://eca.cx/ecasound/Documentation/ecasound_manpage.html}{ecasound(1)}
man page, which contains documentation for all native Ecasound
chain objects.
% ----------------------------------------------------------------------
\section{Configuration}
User preferences are stored in \emph{\textasciitilde /.ecasound/ecasoundrc}.
See the \href{http://eca.cx/ecasound/Documentation/ecasoundrc\_manpage.html}{ecasoundrc(5)}
manual page for details.
By default, files for effect presets and oscillator presets are
in \emph{/usr/share/ecasound}.
% ----------------------------------------------------------------------
\section{Common problems}
\subsection{I get occasional audio dropouts during operation? How to get rid of them?}
Check \url{http://www.oreillynet.com/pub/a/linux/2000/11/17/low_latency.html}
where you'll find a very good article written by Dave Phillips on
Linux low-latency issues. If you are in a hurry (or desperate :)),
here's a quick list of things to try:
\begin{itemize}
\item Tune your disks (see the article)
\item Enable ecasound's double-buffering system by using the \emph{-z:db}
option [note! this is only necessary with Ecasound 2.0.x and older]
\item If you're still having problems, run ecasound as root (or with SUID-bit
set) and use ecasound's \emph{-r} option. This will raise ecasound's
scheduling priority to realtime (SCHED\_FIFO). [with ecasound 2.1
and newer, just run ecasound as root and it will take care of
tuning the settings]
\item Try increasing ecasound's buffersize with the \emph{-b:sample\_frames}
option. Something like \emph{-b:4096} should do the trick.
\item If all else fails, try the various low-latency kernel patches
(again, check the article)
\end{itemize}
There has been a lot of discussion about tuning your system for better
performance on linux-audio-dev and linux-audio-user mailing lists. You
can browse the list archives at \url{http://www.linuxdj.com/audio/lad/archive.php}.
Here are links to selected messages from the ecasound-list archives:
\begin{itemize}
\item Tuning parameters for reliable recording \url{http://eca.cx/ecasound-list/2005/04/0038.html}.
\item Smart Buffering \url{http://eca.cx/ecasound-list/2001/10/0020.html}.
\item Ecasound for Recording \url{http://eca.cx/ecasound-list/2001/06/0016.html}.
\end{itemize}
\subsection{Can I use multiple soundcards?}
This is possible, but there are some issues you should be aware of. If
you try using multiple cheap soundcards to get more simultaneous
inputs for recording, it's likely that the resulting streams will not
be in sync. This problem is explained in detail in the Linux
Audio-Quality HOWTO section "Notes on Full Duplex Recording, and Other
Realtime Issues": \url{http://karmak.org/archive/2003/02/audio_quality_HOWTO.htm}.
The original page at \url{http://www.linuxdj.com/audio/quality/} is no
longer available.
\subsection{Problems with panning mono files}
In situations where you need to convert mono
audio objects to multichannel objects, Ecasound
can behave in a somewhat unexpected manner.
For instance, the correct way to set panning for
three individual mono input files, and mix the
resulting stereo output to soundcard, is:
\begin{verbatim}
ecasound -a:1 -i:monofile1.wav -erc:1,2 -epp:0 \
-a:2 -i:monofile2.wav -erc:1,2 -epp:50 \
-a:3 -i:monofile3.wav -erc:1,2 -epp:100 \
-a:all -f:16,2,44100 -o:alsa
\end{verbatim}
The actual signal chain is something like:
\begin{verbatim}
monofile1.wav |--'1'---- erc ----| epp |---\
\-----| |---\\
\\
monofile2.wav |--'2'---- erc ----| epp |------- | alsa
\-----| |------- |
//
monofile3.wav |--'3'---- erc ----| epp |---//
\-----| |---/
('---' = mono channel)
\end{verbatim}
The critical points to notice are:
\begin{itemize}
\item ecasound automatically notices that the three
input files are mono files so chains are initialized
with one mono input
\item chains contain mono signal until -erc operator,
which transforms the chain into a stereo chain
by copying the data from ch1 to ch2
\item now -epp works as expected (sets the stereo balance
for one input)
\item chains are mixed to the soundcard device channel-wise
\end{itemize}
If you leave out the -erc operators, chains will still be converted
to stereo (as -epp is a stereo operator), but on each chain, only
the first channel (left) will contain any audio from the input
files.
\subsection{Filenames with commas not handled correctly}
There are some pitfalls in how commas in filenames are handled
by ecasound. If you have a filename ``foo,bar.ogg'', the following
will not work:
\begin{verbatim}
ecasound -i foo,bar.ogg -o alsa
\end{verbatim}
The only way around this is to escape all the commas with backslashes:
\begin{verbatim}
ecasound -i foo\\,bar.ogg -o alsa
\end{verbatim}
The backslash has to be a double-backslash as the shell strips
one of the backslashes away before passing the string to ecasound.
% ----------------------------------------------------------------------
% ----------------------------------------------------------------------
\chapter{User interfaces and Applications}
For a complete list of user-interfaces and applications built
on top of Ecasound, visit Ecasound's web site at \url{http://www.eca.cx}.
% ----------------------------------------------------------------------
\section{Ecasound}
The standalone program ``ecasound'' is the primary user interface
for Ecasound.
See \href{http://eca.cx/ecasound/Documentation/ecasound_manpage.html}{ecasound(1)}
man page and the \texttt{Examples web page}
at \url{http://www.eca.cx/ecasound/Documentation/examples.html}.
% ----------------------------------------------------------------------
\section{Ecasignalview}
Ecasignalview is an utility program for monitoring signal amplitude
and peak statistics. It's primarily used when adjusting
signal levels for recording.
\subsection{Basic use}
The basic use scenario is to record audio from a soundcard device,
visualize it with vu-meters and write it to a null output.
\begin{verbatim}
# OSS-drivers (or properly installed ALSA OSS-emulation)
ecasignalview /dev/dsp null
# native ALSA-mode, recording from the 'default' device
ecasignalview alsa,default null
\end{verbatim}
It is possible to reset the max-peak and clipped-samples
counters by sending a SIGHUP signal to the process (i.e.
from another console: "killall -v -HUP ecasignalview").
To monitor the input signal you can either use the soundcard's
analog (or in some cases, digital) monitoring functions by
enabling line/mic-in monitoring using \emph{alsamixer} (ALSA),
\emph{aumix} (OSS) or some other mixer application. Another option is to
use ecasignalview to do the monitoring. In this case the correct
command is:
\begin{verbatim}
# OSS input and output
ecasignalview /dev/dsp /dev/dsp
# corresponding ALSA command
ecasignalview alsa,default alsa,default
\end{verbatim}
Ecasignalview command-line options allow you to fine-tune
the way monitoring is done:
\begin{verbatim}
# increased refresh rate 20Hz
ecasignalview -r:50 alsa null
# larger buffersize (1024 samples)
ecasignalview -b:1024 alsa null
# recording in mode 32bit/10channels/96000Hz with
# interleaved channels
ecasignalview -f:s32,10,96000,i alsa null
\end{verbatim}
It can also be used with files and real-time devices like
JACK inputs and outputs:
\begin{verbatim}
# monitor audio recorded by JACK system input (first 2ch)
ecasignalview -f:f32,2 jack,system null
# monitor audio from JACK application ``foosynth''
ecasignalview -f:f32,2 jack,foosynth null
# play and monitor a file input
ecasignalview foo.wav alsa
\end{verbatim}
\subsection{Further Reading}
See \texttt{ecatools(1)} man page for a detailed listing of
available command-line options.
% ----------------------------------------------------------------------
\section{Ecatools}
See \texttt{ecatools(1)} man page.
% ----------------------------------------------------------------------
% ----------------------------------------------------------------------
\chapter{Advanced features}
% ----------------------------------------------------------------------
\section{Audio loop devices}
Just by using normal chain connections it's not possible to
route audio from one Ecasound chain to another. One way
around this limitation is loop devices. They were introduced
in Ecasound 1.7.0.
\subsection{Example of use}
An example use-case where we route audio from chains ``1'' and ``2''
to chain ``3'' which is amplified and send to a soundcard output (``alsa'').
\begin{verbatim}
--cut--
# note, the second loop parameter is the loop id-number;
# it is used to associate loop inputs with correct loop outputs
ecasound -a:1 -i:some.mp3
-a:2 -i:another.mp3
-a:1,2 -o:loop,1
-a:3 -ea:200 -i:loop,1 -o alsa
--cut--
\end{verbatim}
Both inputs are eventually routed to chain "3", where a -ea:200 is
applied to the signal. This does have one downside, loop device
adds latency (-b:x -> latency of x frames).
% ----------------------------------------------------------------------
\section{Ecasound Wave Files - the EWF (.ewf) format}
\subsection{General}
Ecasound Wave File (.ewf) is a simple wrapper format for controlling
other audio objects. Ewf files are useful for offsetting or time-shifting
audio files (for instance play a short audio clip in the middle of
a long multitrack mix), for minimizing diskspace usage during
multitrack recording (output offsetting ) and looping.
Starting from Ecasound version 2.5.0, similar functionality is
provided by special purpose audio object types 'audioloop', 'audioselect'
and others. You may choose between EWF and these audio object types
based on your specific needs. See
\href{http://eca.cx/ecasound/Documentation/ecasound_manpage.html}{ecasound(1)}
man page and the \texttt{Examples web page}
at \url{http://www.eca.cx/ecasound/Documentation/examples.html}
for many examples of using these.
Writing to EWF file is nowadays considered to be a deprecated
feature and it may be removed in a future release.
\subsection{File format}
Ewf-files are stored in ascii format. The syntax is based on ``key=value''
pairs. The same syntax is used with Ecasound resource files. See
\href{http://eca.cx/ecasound/Documentation/ecasoundrc\_manpage.html}{ecasoundrc(5)}
man page for detailed info. Currently recognized ewf keywords are:
\begin{itemize}
\item source - audio object name (string) {[}read,write{]}
\item offset - insert audio object at offset (time) {[}read,write{]}
\item start-position - start offset inside audio object (time) {[}read{]}
\item length - how much of audio object data is used (time) {[}read{]}
\item looping - whether to loop sample data (true or false) {[}read{]}
\end{itemize}
All time values are interpreted as seconds (need not be an integer
but can be given as a decimal number, e.g. ``1.05''). However if
the value is an integer number and has a postfix of ``sa'' (e.g.
``44100sa''), it is interpreted as time expressed as samples (in
case of a multichannel stream, time in sample frames).
\subsection{Example of ewf use}
Let's look at a simple example .ewf file:
\begin{verbatim}
-- test.ewf --
source = test.wav
offset = 5.0
start-position = 2.0
length = 3.0
looping = true
--cut--
\end{verbatim}
Now what happens when you issue "ecasound -i test.ewf -o alsa"?
Because of the ``offset'' definition, the first 5 seconds will be
silent. After that ecasound will start to read data from ``test.wav''.
But as ``start-position'' is not zero, ecasound will skip the
first 2 seconds. After 8 seconds has passed (``offset'' +
``length''), ecasound will loop back to ``start-position''.
This looping will continue until the user interrupts the operation.
% ----------------------------------------------------------------------
\section{Effect presets}
\subsection{General}
Ecasound has a powerful effect preset system that allows you to create
new effects by combining basic effects and controllers.
Presets can be stored into separate files or they can be stored
into a global database. Either way, the preset format is the same
(also see \href{http://eca.cx/ecasound/Documentation/ecasoundrc\_manpage.html}{ecasoundrc(5)}
man page, the same file format and syntax is used):
\begin{verbatim}
preset_name = effects controllers | ... | effects controllers
\end{verbatim}
Effects and controllers are specified using the EOS syntax,
the same syntax that is used for parsing command-line options
(``-ea:100'', ``-kl:1,0,100,5'', etc). The pipe character is
used to separate parallel chains.
Just like in shell scripts, the '$\backslash$' character can
be used to spread definitions across multiple lines.
\subsection{Example of preset use}
Ecasound effect presets are in fact small Ecasound engines that
behave just like native effects. Here's an example of a
multi-chain effect preset:
\begin{verbatim}
--cut file 'bassbooster.ecp'--
# let's put the low freqs into one chain and high freqs in another
bassbooster = -efl:2000 -ea:200 | -efh:2000 -ea:50
# note, the '|' sign separates parallel chains
--cut--
\end{verbatim}
Once defined, you can use the preset in the following way:
\begin{verbatim}
--cut--
ecasound -a:1 -i:some.mp3 -pf:bassbooster.ecp
-a:2 -i:another.mp3 -pf:bassbooster.ecp
-a:1,2 -o:alsa
--cut--
\end{verbatim}
When separate files are used (the ``-pf:name'' option),
Ecasound always loads the first preset it finds. If the
file contains more presets (additional ``key=value'' -pairs),
they are ignored.
An alternative way to define presets is to put the
definition in the global preset list (usually in
``/usr/local/share/ecasound/effect\_presets''. Once you've
added a line defining ``bassbooster'', you can use it
like:
\begin{verbatim}
--cut--
ecasound -a:1 -i:some.mp3 -pn:bassbooster
-a:2 -i:another.mp3 -pn:bassbooster
-a:1,2 -o:alsa
--cut--
\end{verbatim}
\subsection{Preset parameters}
Parameters of operators belonging to a preset can be
exposed as preset paramters. Example:
\begin{verbatim}
--cut preset definition--
f_res_lowpass = -ef3:%1,1.5,0.7
--cut--
\end{verbatim}
In the above example, the lowpass filter cutoff is exposed
as a parameter of the ``f\_res\_lowpass'' preset. The preset
can be used just like any other Ecasound operator. The
following two commands will results in identical output:
\begin{verbatim}
--cut--
ecasound -i:foo.mp3 -o:alsa -pn:f_res_lowpass,800
ecasound -i:foo.mp3 -o:alsa -ef3:800,1.5,0.7
--cut--
\end{verbatim}
\subsection{Parameter descriptors}
Ecasound preset parameters can be described using the following
set of descriptors:
\begin{verbatim}
-pd:name_of_preset = preset description
-ppn:par1,...,parN = parameter names (public params)
-ppd:val1,...,valN = default param values
-ppl:val1,...,valN = lower bounds for param values
-ppu:val1,...,valN = upper bounds for param values
-ppt:flags1,...,flagsN = special flags for param N
('i'=integer, 'l'=logarithmic, 'o'=output, 't'=toggle)
\end{verbatim}
The option can only be used inside preset definitions (in ``effect\_presets''
files, or individual ``*.ecp'' files). An example preset parameter
definition:
\begin{verbatim}
--cut--
f_two_filters = -efl:800 -ea:%1 | -efh:800 -ea:%2 \
-pd:Parallel_highpass_and_lowpass_filters \
-ppl:0,0 -ppu:1000,- \
-ppd:100,100 -ppn:lowgain,highgain
--cut--
\end{verbatim}
The above preset ``f\_two\_filters'' has two parameters, which
are described using the ``-pd'' descriptor. Recommended lower and
upper bounds for the parameters are defined with ``-ppl'' and
``-ppu'' descriptors. Default values for the parameters are
specified with ``-ppd''.
% ----------------------------------------------------------------------
\section{Gate operators}
Gates are just like any other chain operators. They are assigned to
a chain, and process passing audio data buffers. One special feature
of gates is the ability to crop sections of audio files, for instance
to achieve automatic volume-based cutting of audio streams:
\subsection{Example of use}
The following sequence cuts the section {[}60:00 sec ->
61:00 sec{]} from ``guitar.wav'' into ``gate-test.wav'':
\begin{verbatim}
--cut--
|\$ ls -la guitar.wav
-rw-rw-r-- 1 kaiv kaiv 15790124 Sep 30 23:27 guitar.wav
|\$ ecasound -i guitar.wav -o gate-test.wav -gc:60,1
|\$ ls -la gate-test.wav
-rw-rw-r-- 1 kaiv kaiv 180268 Dec 12 22:13 gate-test.wav
--cut--
\end{verbatim}
The threshold gate is used similarly:
\begin{verbatim}
--cut--
|\$ ecasound -i gate-test.wav -o gate-test-rms.wav -ge:11.2,5,1
|\$ ecasound -i gate-test.wav -o gate-test-peak.wav -ge:5,5,0
|\$ ls -la gate*wav
-rw-rw-r-- 1 kaiv kaiv 163884 Dec 12 22:18 gate-test-peak.wav
-rw-rw-r-- 1 kaiv kaiv 143404 Dec 12 22:17 gate-test-rms.wav
-rw-rw-r-- 1 kaiv kaiv 180268 Dec 12 22:13 gate-test.wav
--cut--
\end{verbatim}
In the first case, the gate is opened when the RMS-volume goes over the ``11.2\%''
threshold, and closed when RMS-volume falls below ``5\%''. In the second,
case, both entry and close thresholds are ``5\%'' (peak volume).
% ----------------------------------------------------------------------
\section{LADSPA plugins}
Ecasound supports LADSPA-effect plugins (Linux Audio Developer's
Simple Plugin API). See \href{http://eca.cx/ecasound/Documentation/ecasound_manpage.html}{ecasound(1)}
man page and the LADSPA web site at ``www.ladspa.org'' for more information.
\subsection{Ecasound is not able to find any LADSPA plugins I have installed!}
Just installing the LADSPA SDK - ``www.ladspa.org''
- should be enough. The plugins themselves are stored in shared library
files (.so). They are usually stored in ``/usr/local/lib/ladspa''. To test
whether Ecasound finds the plugins, issue:
echo "ladspa-register" | ecasound -c
You should get a list of all installed LADSPA plugins. If this doesn't
work, you need to make sure Ecasound is compiled with LADSPA enabled (ie.
ladspa.h header was present when Ecasound was compiled). The precompiled
rpm-binaries have this, but if you've compiled Ecasound yourself you
should recompile after installing the LADSPA SDK.
Also, check Dave Phillips' great
article on Oreillynet -
\url{http://www.oreillynet.com/pub/a/linux/2001/02/02/ladspa.html}.
% ----------------------------------------------------------------------
\section{JACK Audio Server}
\label{JACK Audio Server}
JACK is system for handling real-time, low latency audio.
It allows multiple independent applications to access the system
audio hardware and also to route audio between applications.
JACK is different from other audio server efforts in that it has been
designed from the ground up to be suitable for professional audio
work. This means that it focuses on two key areas: synchronous
execution of all clients, and low latency operation.
Note that Ecasound must be compiled with JACK support enabled
(the ``--with-jack'' configure option) to take advantage of
the functionality described in this section.
\subsection{Basic Input and Output}
Let's start with how to play a file using Ecasound and JACK:
\begin{verbatim}
ecasound -i foo.wav -o jack,system
\end{verbatim}
This will create a separate JACK output port for each channel
of ``foo.wav'', and automatically connect these Ecasound ports to
the JACK system PCM output ports.
Note that ecasound does not allow to mix objects with different
sampling rates (without explicitly inserting ``samplerate''
conversion objects). That means that if sampling rate of ``foo.wav''
does not match the current JACK system rate, the above command
wil fail.
The connections creadted are as follows:
\begin{verbatim}
ecasound:out_1 --> system:playback_1
ecasound:out_2 --> system:playback_2
\end{verbatim}
If ``foo.wav'' was a four channel file, the same command would
connect all channels:
\begin{verbatim}
ecasound:out_1 --> system:playback_1
ecasound:out_2 --> system:playback_2
ecasound:out_3 --> system:playback_3
ecasound:out_4 --> system:playback_4
\end{verbatim}
To record a file, you'd issue:
\begin{verbatim}
ecasound -f:,2 -i jack,system -o foo.wav
ecasound -f:f32,2,44100 -i jack,system -o foo.wav
\end{verbatim}
Here we use ``-f:bits,channels,srate'' to set how many channels
to record from the sound device using JACK. As described in
the \href{http://eca.cx/ecasound/Documentation/ecasound_manpage.html}{ecasound(1)}
man page, the parameters to ``-f'' may be overridden
by the audio objects. In case of JACK, the server always sets
the sampling rate, and also the sample format is fixed to 32bit
floats. Because of this, the above two examples achieve the same
result (but you may find the latter command more readable).
It is possible to add another ``-f'' before ``-o foo.wav''
if you want to write the file in a different format. For
example to convert the sample format to 16bit fixed:
\begin{verbatim}
ecasound -f:f32,2 -i jack,system -f:s16,2 -o foo.wav
\end{verbatim}
\subsection{More Advanced Port Creation}
Ecasound also offers the following alternative ways
to create input and output ports:
\begin{verbatim}
ecasound -i foo.wav -o jack
ecasound -i foo.wav -o jack,remote_client
ecasound -i foo.wav -o jack,remote_client,local_portprefix
ecasound -i foo.wav -o jack,,local_portprefix
ecasound -i foo.wav -o jack_multi,remote_client:port_1,system:port_2
ecasound -i jack -o foo.wav
ecasound -i jack,remote_client -o foo.wav
ecasound -i jack,local_portprefix -o foo.wav
\end{verbatim}
See \href{http://eca.cx/ecasound/Documentation/ecasound_manpage.html}{ecasound(1)}
manual page for descriptions of the ``jack\_multi'' audio object and the variants
of ``jack'' usage.
\subsection{Transport Control}
Transport controls are functions like ``start'', ``stop'', ``seek'',
etc, that are commonly available in audio applications that
maintain some kind of current position. JACK's transport
control interface allows controlling the transport state
of all the apps connected to one JACK server from a single
application. Ecasound can support this functionality in
four different modes (``notransport'', ``send'', ``recv''
and ``sendrecv'').
By default Ecasound will both send and reveive transport
events (position and state) to other JACK clients
(mode ``sendrecv''):
\begin{verbatim}
ecasound -c -i null -o jack
\end{verbatim}
To use transport control in Ecasound, you have to have at least
one published input or output JACK port. Here we publish
one null output port. After giving the initial ``engine-launch'' command
in Ecasound interactive mode, you are now able to use
further EIAM commands to control all other JACK apps connected
to the same server. Commands like
``stop'', ``setpos 20'', ``rw 10'', ``fw 10'', and so should
affect other apps.
By default, Ecasound doesn't react to outside transport
control. To enable this:
\begin{verbatim}
ecasound -c -i foo.wav -o jack,system -G:jack,eca_slave,recv
\end{verbatim}
After giving an initial ``engine-launch'' to Ecasound, you should
now be able to use other JACK apps to control Ecasound's
playback of ``foo.wav''.
To combine external control with the ability to control
the transport from ecasound's user-interface:
\begin{verbatim}
ecasound -c -i foo.wav -o jack,system -G:jack,eca_slave,sendrecv
\end{verbatim}
\subsection{JACK and Ecasound states}
To have a good understanding of the overall system, it's important
to understand how Ecasound and JACK states relate to each other.
When an Ecasound chainsetup is connected (EIAM-command ``cs-connect''),
a connection is established with the JACK server, and all the
JACK ports in that chainsetup are registered to it.
Once Ecasound's engine is launched with EIAM-command ``engine-launch'',
connections (if any are specified) are made to the ports of other
JACK clients. In this state Ecasound is ready to process
incoming transport state and position changes.
When Ecasound processing is started (either with ``start'' or
by an incoming transport event), Ecasound's engine runs
as a node in the JACK system. When processing is stopped (either
with ``stop'', or by a transport event), Ecasound's engine is
not run.
Any connections (initiated by Ecasound) to other clients,
are disconnected once ``engine-halt'' is issued and engine
operation is stopped. Connection to the remote JACK server
as well as unregistering any ports is performed when chainsetup
is disconnected (``cs-disconnect'').
Note! Normally you don't need to go through all the steps one
by one. Instead issuing ``start'' will automatically connect
the chainsetup and launch the engine. Similarly ``cs-disconnect''
will stop processing and halt the engine if needed.
\subsection{Troubleshooting}
Ecasound v2.2 and earlier don't have the capability to change
the engine buffersize and sampling rate dynamically during
processing. As a consequence, running Ecasound will fail if
the currrent values for these parameters do not match
the ones used by the JACK server. In other words, you have
to correctly set the buffersize (with ``-b:xxx'') and sampling
rate (with ``-f:bits,channels,srate'' and possibly using the
\emph{resample} audio object). This is the first thing to
check if communication with JACK does not work.
Future versions of Ecasound will hopefully solve this
problem. This issue is covered by Ecasound development item
``edi-31 - Support for dynamic sampling rate and buffersize changes.''.
\subsection{Deprecated JACK input/output syntax}
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. The old variants this
work, but are now considered deprecated (they work but may be
removed in a future Ecasound release).
% ----------------------------------------------------------------------
% ----------------------------------------------------------------------
\chapter{Miscellaneous}
% ----------------------------------------------------------------------
\section{Security Considerations}
When given the -r option (raise priority), Ecasound tries to raise
its scheduling priority (to so called SCHED\_FIFO realtime scheduling)
and to avoid swapping, locks all its memory. To do this,
root-privileges are required. So either Ecasound has to be run as
root (logged in as root, or using the 'sudo' program), it has to be
installed with the suid-root bit set, or otherwise be granted necessary
privileges to turn on real-time schedule (see below). Now is this a safe
thing to do?
Although there are no known vulnerabilities, setting Ecasound suid-root is
not safe. Whether this is a real problem depends on the particular setup
(whether connected to a network or not, any untrusted users with shell
access, ...).
The basic problem is that Ecasound (or at least 2.0 and earlier)
doesn't contain any code for altering privilege levels. If it is run
with root-privileges, it does everything as root - including forking
external programs such as mp3 and ogg utilities and editors.
But all in all, this shouldn't be that big of an issue for many users. For
noncritical uses, just don't set the suid-bit, but run as a normal user. If
you have an untrusted setup, and you don't want to login as root, but still
need to run in raised-priority mode, the following can help to limit
the risk of suid-root use:
\begin{verbatim}
cd /usr/local/bin
chown root.ecausers ecasound
chmod 4750 ecasound
\end{verbatim}
In other words, the ecasound binary is set as suid-root (so it is run with
root-privileges), but only root and members of the 'ecausers' group can
start it. You of course first have to create the 'ecausers' group to your
system.
The ideal solution would be that ecasound would not need full root-privileges, but
privileges for changing scheduling and locking memory. On recent Linux systems,
there are couple ways to achieve this.
The Realtime Linux Security Module (LSM) is one practical solution
(see \url{http://sourceforge.net/projects/realtime-lsm/} and
\url{http://lwn.net/Articles/106009/}). This module is a loadable extension for
Linux 2.6 kernels. It selectively grants realtime permissions to specific user groups
or applications. Unfortunately Realtime LSM does not yet come with the standard Linux
kernel, so you need to install it separately.
A more recent approach, and one that might be adopted by popular GNU/Linux distributions,
is the \emph{rtprio} extension to Linux resource limits. See
\href{http://lwn.net/Articles/134460/} for a good overview of this approach and how
it compared to the LSM mechanism described above.
\end{document}
Reference in New Issue View Git Blame Copy Permalink