\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}