/usr/share/doc/ecasound/users

<!DOCTYPE html>
<html >
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="generator" content="hevea 2.28">
<style type="text/css">
.li-itemize{margin:1ex 0ex;}
.li-enumerate{margin:1ex 0ex;}
.dd-description{margin:0ex 0ex 1ex 4ex;}
.dt-description{margin:0ex;}
.toc{list-style:none;}
.footnotetext{margin:0ex; padding:0ex;}
div.footnotetext P{margin:0px; text-indent:1em;}
.thefootnotes{text-align:left;margin:0ex;}
.dt-thefootnotes{margin:0em;}
.dd-thefootnotes{margin:0em 0em 0em 2em;}
.footnoterule{margin:1em auto 1em 0px;width:50%;}
.caption{padding-left:2ex; padding-right:2ex; margin-left:auto; margin-right:auto}
.title{margin:2ex auto;text-align:center}
.titlemain{margin:1ex 2ex 2ex 1ex;}
.titlerest{margin:0ex 2ex;}
.center{text-align:center;margin-left:auto;margin-right:auto;}
.flushleft{text-align:left;margin-left:0ex;margin-right:auto;}
.flushright{text-align:right;margin-left:auto;margin-right:0ex;}
div table{margin-left:inherit;margin-right:inherit;margin-bottom:2px;margin-top:2px}
td table{margin:auto;}
table{border-collapse:collapse;}
td{padding:0;}
.cellpadding0 tr td{padding:0;}
.cellpadding1 tr td{padding:1px;}
pre{text-align:left;margin-left:0ex;margin-right:auto;}
blockquote{margin-left:4ex;margin-right:4ex;text-align:left;}
td p{margin:0px;}
.boxed{border:1px solid black}
.textboxed{border:1px solid black}
.vbar{border:none;width:2px;background-color:black;}
.hbar{border:none;height:2px;width:100%;background-color:black;}
.hfill{border:none;height:1px;width:200%;background-color:black;}
.vdisplay{border-collapse:separate;border-spacing:2px;width:auto; empty-cells:show; border:2px solid red;}
.vdcell{white-space:nowrap;padding:0px; border:2px solid green;}
.display{border-collapse:separate;border-spacing:2px;width:auto; border:none;}
.dcell{white-space:nowrap;padding:0px; border:none;}
.dcenter{margin:0ex auto;}
.vdcenter{border:solid #FF8000 2px; margin:0ex auto;}
.minipage{text-align:left; margin-left:0em; margin-right:auto;}
.marginpar{border:solid thin black; width:20%; text-align:left;}
.marginparleft{float:left; margin-left:0ex; margin-right:1ex;}
.marginparright{float:right; margin-left:1ex; margin-right:0ex;}
.theorem{text-align:left;margin:1ex auto 1ex 0ex;}
.part{margin:2ex auto;text-align:center}
</style>
<title>Ecasound User's Guide
</title>
</head>
<body >
<!--HEVEA command line is: /usr/bin/hevea -o html_uguide/users_guide.html ./users_guide.latex -->
<!--CUT STYLE book--><!--CUT DEF chapter 1 --><table class="title"><tr><td style="padding:1ex"><h1 class="titlemain">Ecasound User&#X2019;s Guide</h1><h3 class="titlerest">Kai Vehmanen</h3><h3 class="titlerest">19042009</h3></td></tr>
</table><!--TOC chapter id="sec1" Contents-->
<h1 id="sec1" class="chapter">Contents</h1><!--SEC END --><ul class="toc"><li class="li-toc">
<a href="#sec2">Chapter&#XA0;1&#XA0;&#XA0;Preface</a>
</li><li class="li-toc"><a href="#sec3">Chapter&#XA0;2&#XA0;&#XA0;Document history</a>
</li><li class="li-toc"><a href="#sec4">Chapter&#XA0;3&#XA0;&#XA0;Introduction</a>
<ul class="toc"><li class="li-toc">
<a href="#sec5">3.1&#XA0;&#XA0;What is Ecasound?</a>
</li></ul>
</li><li class="li-toc"><a href="#sec6">Chapter&#XA0;4&#XA0;&#XA0;Ecasound concepts</a>
<ul class="toc"><li class="li-toc">
<a href="#sec7">4.1&#XA0;&#XA0;Audio object</a>
</li><li class="li-toc"><a href="#sec8">4.2&#XA0;&#XA0;Chain</a>
</li><li class="li-toc"><a href="#sec9">4.3&#XA0;&#XA0;Chain operators and controllers</a>
</li><li class="li-toc"><a href="#sec10">4.4&#XA0;&#XA0;Chainsetup</a>
</li><li class="li-toc"><a href="#sec11">4.5&#XA0;&#XA0;Current position</a>
</li><li class="li-toc"><a href="#sec12">4.6&#XA0;&#XA0;Ecasound Control Interface - ECI</a>
</li><li class="li-toc"><a href="#sec13">4.7&#XA0;&#XA0;Ecasound Interactive Mode - EIAM</a>
</li><li class="li-toc"><a href="#sec14">4.8&#XA0;&#XA0;Ecasound Option Syntax - EOS</a>
</li></ul>
</li><li class="li-toc"><a href="#sec15">Chapter&#XA0;5&#XA0;&#XA0;Using</a>
<ul class="toc"><li class="li-toc">
<a href="#sec16">5.1&#XA0;&#XA0;Where to start?</a>
</li><li class="li-toc"><a href="#sec17">5.2&#XA0;&#XA0;Rules for creating and modifying chainsetups</a>
</li><li class="li-toc"><a href="#sec18">5.3&#XA0;&#XA0;Chain operators and controllers</a>
</li><li class="li-toc"><a href="#sec19">5.4&#XA0;&#XA0;Configuration</a>
</li><li class="li-toc"><a href="#sec20">5.5&#XA0;&#XA0;Common problems</a>
<ul class="toc"><li class="li-toc">
<a href="#sec21">5.5.1&#XA0;&#XA0;I get occasional audio dropouts during operation? How to get rid of them?</a>
</li><li class="li-toc"><a href="#sec22">5.5.2&#XA0;&#XA0;Can I use multiple soundcards?</a>
</li><li class="li-toc"><a href="#sec23">5.5.3&#XA0;&#XA0;Problems with panning mono files</a>
</li><li class="li-toc"><a href="#sec24">5.5.4&#XA0;&#XA0;Filenames with commas not handled correctly</a>
</li></ul>
</li></ul>
</li><li class="li-toc"><a href="#sec25">Chapter&#XA0;6&#XA0;&#XA0;User interfaces and Applications</a>
<ul class="toc"><li class="li-toc">
<a href="#sec26">6.1&#XA0;&#XA0;Ecasound</a>
</li><li class="li-toc"><a href="#sec27">6.2&#XA0;&#XA0;Ecasignalview</a>
<ul class="toc"><li class="li-toc">
<a href="#sec28">6.2.1&#XA0;&#XA0;Basic use</a>
</li><li class="li-toc"><a href="#sec29">6.2.2&#XA0;&#XA0;Further Reading</a>
</li></ul>
</li><li class="li-toc"><a href="#sec30">6.3&#XA0;&#XA0;Ecatools</a>
</li></ul>
</li><li class="li-toc"><a href="#sec31">Chapter&#XA0;7&#XA0;&#XA0;Advanced features</a>
<ul class="toc"><li class="li-toc">
<a href="#sec32">7.1&#XA0;&#XA0;Audio loop devices</a>
<ul class="toc"><li class="li-toc">
<a href="#sec33">7.1.1&#XA0;&#XA0;Example of use</a>
</li></ul>
</li><li class="li-toc"><a href="#sec34">7.2&#XA0;&#XA0;Ecasound Wave Files - the EWF (.ewf) format</a>
<ul class="toc"><li class="li-toc">
<a href="#sec35">7.2.1&#XA0;&#XA0;General</a>
</li><li class="li-toc"><a href="#sec36">7.2.2&#XA0;&#XA0;File format</a>
</li><li class="li-toc"><a href="#sec37">7.2.3&#XA0;&#XA0;Example of ewf use</a>
</li></ul>
</li><li class="li-toc"><a href="#sec38">7.3&#XA0;&#XA0;Effect presets</a>
<ul class="toc"><li class="li-toc">
<a href="#sec39">7.3.1&#XA0;&#XA0;General</a>
</li><li class="li-toc"><a href="#sec40">7.3.2&#XA0;&#XA0;Example of preset use</a>
</li><li class="li-toc"><a href="#sec41">7.3.3&#XA0;&#XA0;Preset parameters</a>
</li><li class="li-toc"><a href="#sec42">7.3.4&#XA0;&#XA0;Parameter descriptors</a>
</li></ul>
</li><li class="li-toc"><a href="#sec43">7.4&#XA0;&#XA0;Gate operators</a>
<ul class="toc"><li class="li-toc">
<a href="#sec44">7.4.1&#XA0;&#XA0;Example of use</a>
</li></ul>
</li><li class="li-toc"><a href="#sec45">7.5&#XA0;&#XA0;LADSPA plugins</a>
<ul class="toc"><li class="li-toc">
<a href="#sec46">7.5.1&#XA0;&#XA0;Ecasound is not able to find any LADSPA plugins I have installed!</a>
</li></ul>
</li><li class="li-toc"><a href="#sec47">7.6&#XA0;&#XA0;JACK Audio Server</a>
<ul class="toc"><li class="li-toc">
<a href="#sec48">7.6.1&#XA0;&#XA0;Basic Input and Output</a>
</li><li class="li-toc"><a href="#sec49">7.6.2&#XA0;&#XA0;More Advanced Port Creation</a>
</li><li class="li-toc"><a href="#sec50">7.6.3&#XA0;&#XA0;Transport Control</a>
</li><li class="li-toc"><a href="#sec51">7.6.4&#XA0;&#XA0;JACK and Ecasound states</a>
</li><li class="li-toc"><a href="#sec52">7.6.5&#XA0;&#XA0;Troubleshooting</a>
</li><li class="li-toc"><a href="#sec53">7.6.6&#XA0;&#XA0;Deprecated JACK input/output syntax</a>
</li></ul>
</li></ul>
</li><li class="li-toc"><a href="#sec54">Chapter&#XA0;8&#XA0;&#XA0;Miscellaneous</a>
<ul class="toc"><li class="li-toc">
<a href="#sec55">8.1&#XA0;&#XA0;Security Considerations</a>
</li></ul>
</li></ul>
<!--TOC chapter id="sec2" Preface-->
<h1 id="sec2" class="chapter">Chapter&#XA0;1&#XA0;&#XA0;Preface</h1><!--SEC END --><p>This document describes Ecasound from the user&#X2019;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&#X2019;ve used references to other sources whenever suitable. 
For instance, Ecasound&#X2019;s man pages are a very good (and up-to-date!)
source of information. They are also available in HTML-format.</p><p>If not otherwise specified, all documentation refers to the latest
Ecasound version.</p>
<!--TOC chapter id="sec3" Document history-->
<h1 id="sec3" class="chapter">Chapter&#XA0;2&#XA0;&#XA0;Document history</h1><!--SEC END --><ul class="itemize"><li class="li-itemize">
19.04.2009 - Removed duplicate Ecasound history section and added
more web URLs pointing to other sources of 
		 documentation.
</li><li class="li-itemize">31.01.2009 - Lots of minor improvements in preparation for 
2.6.0 release.
</li><li class="li-itemize">29.01.2009 - Updated &#X201C;JACK Audio Server&#X201D; section to match 
the changes in 2.6.0 release.
</li><li class="li-itemize">05.08.2008 - Fixed a bug in example of loop device usage.
</li><li class="li-itemize">09.03.2008 - Updated the EWF file section. Replace uses of &#X201C;/dev/dsp&#X201D;
with &#X201C;alsa&#X201D; in many examples.
</li><li class="li-itemize">06.12.2006 - Added notes concerning quoting EOS arguments containing
commas.
</li><li class="li-itemize">04.06.2006 - Some minor improvements to the text. Updated the descriptions of
realtime-lsm and rlimits-rtprio mechanisms.
</li><li class="li-itemize">25.04.2005 - From now on, only major changes are logged to this changelog
section. For detailed change history, refer to CVS history.
</li><li class="li-itemize">23.04.2005 - Started using the &#X201C;hevea&#X201D; style-package and converted 
all links to use the hevea macros (resulting in real hyperlinks
		 in the HTML output). Renamed the section 
		 &#X201C;Security considerations when running with root privileges&#X201D;
		 to shorter &#X201C;Security Considerations&#X201D;, added info
		 about Realtime LSM module.
</li><li class="li-itemize">01.04.2005 - Updated &#X201C;Ecasignalview&#X201D; documentation.
</li><li class="li-itemize">30.03.2005 - Added sections on &#X201C;Preset parameters&#X201D; and 
&#X201C;Parameter descriptors&#X201D;.
</li><li class="li-itemize">11.12.2004 - Added section &#X201C;Filenames with commas not handled correctly&#X201D;
</li><li class="li-itemize">18.12.2003 - Many typo fixes and other corrections from Eric 
Rzewnicki.
</li><li class="li-itemize">18.11.2003 - Typo fixes.
</li><li class="li-itemize">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.
</li><li class="li-itemize">13.08.2003 - Updated documentation concerning JACK transport 
functions.
</li><li class="li-itemize">31.10.2002 - Few section layout bugs fixed.
</li><li class="li-itemize">30.10.2002 - Added JACK documentation, minor layout changes.
</li><li class="li-itemize">17.10.2002 - Updated Ecasound overview.
</li><li class="li-itemize">17.07.2002 - Added documentation for ecasignalview.
</li><li class="li-itemize">18.05.2002 - Fixed a few typos.
</li><li class="li-itemize">21.10.2001 - Added material from the Ecasound FAQ.
</li><li class="li-itemize">21.10.2001 - Added this history section. Document was 
restructured and all major chapters reviewed.
</li><li class="li-itemize">01.02.2001 - Updated the &#X201C;Current position&#X201D; section.
</li></ul>
<!--TOC chapter id="sec4" Introduction-->
<h1 id="sec4" class="chapter">Chapter&#XA0;3&#XA0;&#XA0;Introduction</h1><!--SEC END -->
<!--TOC section id="sec5" What is Ecasound?-->
<h2 id="sec5" class="section">3.1&#XA0;&#XA0;What is Ecasound?</h2><!--SEC END --><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>
<!--TOC chapter id="sec6" Ecasound concepts-->
<h1 id="sec6" class="chapter">Chapter&#XA0;4&#XA0;&#XA0;Ecasound concepts</h1><!--SEC END -->
<!--TOC section id="sec7" Audio object-->
<h2 id="sec7" class="section">4.1&#XA0;&#XA0;Audio object</h2><!--SEC END --><p>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.</p>
<!--TOC section id="sec8" Chain-->
<h2 id="sec8" class="section">4.2&#XA0;&#XA0;Chain</h2><!--SEC END --><p>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).</p><p>But there are some differences. First it&#X2019;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&#X2019;s just easier. A second important difference 
is that chains can transport multiple channels of audio. It&#X2019;s possible
to attach mono, stereo or 24ch (or bigger) audio feeds to one 
chain. Also all chain operators can handle these multichannel 
streams.</p><p>In addition to chain operators, chains also have separate
&#X201C;mute&#X201D; and &#X201C;bypass&#X201D; functions.</p>
<!--TOC section id="sec9" Chain operators and controllers-->
<h2 id="sec9" class="section">4.3&#XA0;&#XA0;Chain operators and controllers</h2><!--SEC END --><p>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.</p><p>It&#X2019;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).</p><p>Both types of objects are attached to chains. The term <em>chain object</em> 
refers to all objects that can be attached to chains - ie. 
operators and controllers.</p>
<!--TOC section id="sec10" Chainsetup-->
<h2 id="sec10" class="section">4.4&#XA0;&#XA0;Chainsetup</h2><!--SEC END --><p>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 <em>connected</em> is used to describe a chainsetup that
is in use. </p><p>Another important chainsetup concept is that of a <em>selected</em>
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.</p><p>Loading and saving chainsetups is the primary mechanism 
for storing and restoring state information. When saving 
to files, the <em>.ecs</em> file format is used. The file syntax
uses the same notation as Ecasound&#X2019;s console (and command-line)
interface. This makes it easy to edit the chainsetup files
outside Ecasound, either manually or using external utils.
See <a href="http://nosignal.fi/ecasound/Documentation/ecasound_manpage.html">ecasound(1)</a> 
man page for details.</p>
<!--TOC section id="sec11" Current position-->
<h2 id="sec11" class="section">4.5&#XA0;&#XA0;Current position</h2><!--SEC END --><p>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.</p>
<!--TOC section id="sec12" Ecasound Control Interface - ECI-->
<h2 id="sec12" class="section">4.6&#XA0;&#XA0;Ecasound Control Interface - ECI</h2><!--SEC END --><p>Ecasound Control Interface is an API for application
developers who want to take advantage of libecasound 
in their own apps. See &#X201C;Ecasound Control Interface Guide&#X201D; 
and &#X201C;Ecasound Programmer&#X2019;s Guide&#X201D; for more information.</p>
<!--TOC section id="sec13" Ecasound Interactive Mode - EIAM-->
<h2 id="sec13" class="section">4.7&#XA0;&#XA0;Ecasound Interactive Mode - EIAM</h2><!--SEC END --><p>Most of Ecasound&#X2019;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&#X2019;s Interactive Mode (EIAM)</p><p>The most common frontend for the Interactive Mode is the console-mode
Ecasound program. You can enter its Enteractive Mode 
by issuing &#X201C;ecasound -c&#X201D;. For more detailed information
the available commands, see <span style="font-family:monospace">ecasound-iam(1)</span> man page.</p>
<!--TOC section id="sec14" Ecasound Option Syntax - EOS-->
<h2 id="sec14" class="section">4.8&#XA0;&#XA0;Ecasound Option Syntax - EOS</h2><!--SEC END --><p>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.</p><p>But it doesn&#X2019;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. </p><p>As a result, the same syntax (tokens that look like
&#X201C;-prefix:arg1,arg2,...,argN&#X201D;), 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 &#X201C;-prefix:"ar,g1",arg2&#X201D;).</p><p>Following is a partial list of the places where EOS syntax 
has been used:</p><ul class="itemize"><li class="li-itemize">
parsing command-line options
</li><li class="li-itemize">the interactive-mode (as arguments to the &#X2019;cs-option&#X2019; command
[2.1dev4 and newer])
</li><li class="li-itemize">saved chainsetup-files (.ecs format)
</li><li class="li-itemize">effect preset definitions (see for example 
&#X201C;/usr/share/ecasound/effect_presets&#X201D;)
</li><li class="li-itemize">generic oscillator definitions (see for example 
&#X201C;/usr/share/ecasound/generic_oscillators&#X201D;
</li></ul>
<!--TOC chapter id="sec15" Using-->
<h1 id="sec15" class="chapter">Chapter&#XA0;5&#XA0;&#XA0;Using</h1><!--SEC END -->
<!--TOC section id="sec16" Where to start?-->
<h2 id="sec16" class="section">5.1&#XA0;&#XA0;Where to start?</h2><!--SEC END --><p>There&#X2019;s no one single right way to use Ecasound. You can use it as 
a simple glue component for doing tasks that aren&#X2019;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.</p><p>This flexibility doesn&#X2019;t come for free. It&#X2019;s difficult to describe
Ecasound&#X2019;s features in a few phrases. Because of this, new users
are encouraged to start from the <span style="font-family:monospace">Examples page</span> at 
<a href="http://nosignal.fi/ecasound/Documentation/examples.html"><span style="font-family:monospace">http://nosignal.fi/ecasound/Documentation/examples.html</span></a>.
It isn&#X2019;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.</p>
<!--TOC section id="sec17" Rules for creating and modifying chainsetups-->
<h2 id="sec17" class="section">5.2&#XA0;&#XA0;Rules for creating and modifying chainsetups</h2><!--SEC END --><p>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:</p><ul class="itemize"><li class="li-itemize">
Every chain has exactly _one_ input and _one_ output.
</li><li class="li-itemize">All inputs and outputs must be connected to some chain.
</li><li class="li-itemize">For every input/output, there is one and only one
definition (example: &#X201C;-i:file.wav&#X201D;).
</li><li class="li-itemize">All routing from and to chains is based on selecting a set of 
chains and then specifying an input or output (example: 
&#X201C;-a:1,2 -i:file.ext&#X201D;).
</li><li class="li-itemize">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.
</li></ul><p>Note that these rules are checked only when <em>connecting</em> the 
chainsetup (when issuing commands such as &#X201C;cs-connect&#X201D;, or &#X201C;start&#X201D;).</p>
<!--TOC section id="sec18" Chain operators and controllers-->
<h2 id="sec18" class="section">5.3&#XA0;&#XA0;Chain operators and controllers</h2><!--SEC END --><p>The best place to start is to read through 
the <a href="http://nosignal.fi/ecasound/Documentation/ecasound_manpage.html">ecasound(1)</a>
man page, which contains documentation for all native Ecasound 
chain objects.</p>
<!--TOC section id="sec19" Configuration-->
<h2 id="sec19" class="section">5.4&#XA0;&#XA0;Configuration</h2><!--SEC END --><p>User preferences are stored in <em>~/.ecasound/ecasoundrc</em>.
See the <a href="http://nosignal.fi/ecasound/Documentation/ecasoundrc_manpage.html">ecasoundrc(5)</a>
manual page for details.</p><p>By default, files for effect presets and oscillator presets are 
in <em>/usr/share/ecasound</em>.</p>
<!--TOC section id="sec20" Common problems-->
<h2 id="sec20" class="section">5.5&#XA0;&#XA0;Common problems</h2><!--SEC END -->
<!--TOC subsection id="sec21" I get occasional audio dropouts during operation? How to get rid of them?-->
<h3 id="sec21" class="subsection">5.5.1&#XA0;&#XA0;I get occasional audio dropouts during operation? How to get rid of them?</h3><!--SEC END --><p>Check <a href="http://www.oreillynet.com/pub/a/linux/2000/11/17/low_latency.html"><span style="font-family:monospace">http://www.oreillynet.com/pub/a/linux/2000/11/17/low_latency.html</span></a>
where you&#X2019;ll find a very good article written by Dave Phillips on
Linux low-latency issues. If you are in a hurry (or desperate :)),
here&#X2019;s a quick list of things to try:</p><ul class="itemize"><li class="li-itemize">
Tune your disks (see the article)
</li><li class="li-itemize">Enable ecasound&#X2019;s double-buffering system by using the <em>-z:db</em>
option [note! this is only necessary with Ecasound 2.0.x and older]
</li><li class="li-itemize">If you&#X2019;re still having problems, run ecasound as root (or with SUID-bit
set) and use ecasound&#X2019;s <em>-r</em> option. This will raise ecasound&#X2019;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]
</li><li class="li-itemize">Try increasing ecasound&#X2019;s buffersize with the <em>-b:sample_frames</em>
option. Something like <em>-b:4096</em> should do the trick.
</li><li class="li-itemize">If all else fails, try the various low-latency kernel patches 
(again, check the article)
</li></ul><p>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 <a href="http://www.linuxdj.com/audio/lad/archive.php"><span style="font-family:monospace">http://www.linuxdj.com/audio/lad/archive.php</span></a>.</p><p>Here are links to selected messages from the ecasound-list archives:
</p><ul class="itemize"><li class="li-itemize">
Tuning parameters for reliable recording <a href="http://nosignal.fi/ecasound-list/2005/04/0038.html"><span style="font-family:monospace">http://nosignal.fi/ecasound-list/2005/04/0038.html</span></a>.
</li><li class="li-itemize">Smart Buffering <a href="http://nosignal.fi/ecasound-list/2001/10/0020.html"><span style="font-family:monospace">http://nosignal.fi/ecasound-list/2001/10/0020.html</span></a>.
</li><li class="li-itemize">Ecasound for Recording <a href="http://nosignal.fi/ecasound-list/2001/06/0016.html"><span style="font-family:monospace">http://nosignal.fi/ecasound-list/2001/06/0016.html</span></a>.
</li></ul>
<!--TOC subsection id="sec22" Can I use multiple soundcards?-->
<h3 id="sec22" class="subsection">5.5.2&#XA0;&#XA0;Can I use multiple soundcards?</h3><!--SEC END --><p>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&#X2019;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": <a href="http://karmak.org/archive/2003/02/audio_quality_HOWTO.htm"><span style="font-family:monospace">http://karmak.org/archive/2003/02/audio_quality_HOWTO.htm</span></a>.
The original page at <a href="http://www.linuxdj.com/audio/quality/"><span style="font-family:monospace">http://www.linuxdj.com/audio/quality/</span></a> is no
longer available. </p>
<!--TOC subsection id="sec23" Problems with panning mono files-->
<h3 id="sec23" class="subsection">5.5.3&#XA0;&#XA0;Problems with panning mono files</h3><!--SEC END --><p>In situations where you need to convert mono
audio objects to multichannel objects, Ecasound
can behave in a somewhat unexpected manner.</p><p>For instance, the correct way to set panning for 
three individual mono input files, and mix the
resulting stereo output to soundcard, is:</p><pre class="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
</pre><p>The actual signal chain is something like:</p><pre class="verbatim">  
monofile1.wav |--'1'---- erc ----| epp |---\
                           \-----|     |---\\
                                            \\
monofile2.wav |--'2'---- erc ----| epp |------- | alsa
                           \-----|     |------- |
                                            //
monofile3.wav |--'3'---- erc ----| epp |---//
                           \-----|     |---/

('---' = mono channel)
</pre><p>The critical points to notice are:</p><ul class="itemize"><li class="li-itemize">
ecasound automatically notices that the three
input files are mono files so chains are initialized
with one mono input
</li><li class="li-itemize">chains contain mono signal until -erc operator,
which transforms the chain into a stereo chain
by copying the data from ch1 to ch2
</li><li class="li-itemize">now -epp works as expected (sets the stereo balance
for one input)
</li><li class="li-itemize">chains are mixed to the soundcard device channel-wise
</li></ul><p>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.</p>
<!--TOC subsection id="sec24" Filenames with commas not handled correctly-->
<h3 id="sec24" class="subsection">5.5.4&#XA0;&#XA0;Filenames with commas not handled correctly</h3><!--SEC END --><p>There are some pitfalls in how commas in filenames are handled
by ecasound. If you have a filename &#X201C;foo,bar.ogg&#X201D;, the following
will not work:</p><pre class="verbatim">ecasound -i foo,bar.ogg -o alsa
</pre><p>The only way around this is to escape all the commas with backslashes:</p><pre class="verbatim">ecasound -i foo\\,bar.ogg -o alsa
</pre><p>The backslash has to be a double-backslash as the shell strips 
one of the backslashes away before passing the string to ecasound.</p>
<!--TOC chapter id="sec25" User interfaces and Applications-->
<h1 id="sec25" class="chapter">Chapter&#XA0;6&#XA0;&#XA0;User interfaces and Applications</h1><!--SEC END --><p>For a complete list of user-interfaces and applications built
on top of Ecasound, visit Ecasound&#X2019;s web site at <a href="http://www.eca.cx"><span style="font-family:monospace">http://www.eca.cx</span></a>.</p>
<!--TOC section id="sec26" Ecasound-->
<h2 id="sec26" class="section">6.1&#XA0;&#XA0;Ecasound</h2><!--SEC END --><p>The standalone program &#X201C;ecasound&#X201D; is the primary user interface
for Ecasound. </p><p>See <a href="http://nosignal.fi/ecasound/Documentation/ecasound_manpage.html">ecasound(1)</a>
man page and the <span style="font-family:monospace">Examples web page</span>
at <a href="http://nosignal.fi/ecasound/Documentation/examples.html"><span style="font-family:monospace">http://nosignal.fi/ecasound/Documentation/examples.html</span></a>.</p>
<!--TOC section id="sec27" Ecasignalview-->
<h2 id="sec27" class="section">6.2&#XA0;&#XA0;Ecasignalview</h2><!--SEC END --><p>Ecasignalview is an utility program for monitoring signal amplitude 
and peak statistics. It&#X2019;s primarily used when adjusting 
signal levels for recording. </p>
<!--TOC subsection id="sec28" Basic use-->
<h3 id="sec28" class="subsection">6.2.1&#XA0;&#XA0;Basic use</h3><!--SEC END --><p>The basic use scenario is to record audio from a soundcard device,
visualize it with vu-meters and write it to a null output. </p><pre class="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
</pre><p>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").</p><p>To monitor the input signal you can either use the soundcard&#X2019;s
analog (or in some cases, digital) monitoring functions by 
enabling line/mic-in monitoring using <em>alsamixer</em> (ALSA),
<em>aumix</em> (OSS) or some other mixer application. Another option is to
use ecasignalview to do the monitoring. In this case the correct
command is:</p><pre class="verbatim"># OSS input and output
ecasignalview /dev/dsp /dev/dsp

# corresponding ALSA command
ecasignalview alsa,default alsa,default
</pre><p>Ecasignalview command-line options allow you to fine-tune
the way monitoring is done:</p><pre class="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
</pre><p>It can also be used with files and real-time devices like
JACK inputs and outputs:
</p><pre class="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
</pre>
<!--TOC subsection id="sec29" Further Reading-->
<h3 id="sec29" class="subsection">6.2.2&#XA0;&#XA0;Further Reading</h3><!--SEC END --><p>See <span style="font-family:monospace">ecatools(1)</span> man page for a detailed listing of 
available command-line options.</p>
<!--TOC section id="sec30" Ecatools-->
<h2 id="sec30" class="section">6.3&#XA0;&#XA0;Ecatools</h2><!--SEC END --><p>
See <span style="font-family:monospace">ecatools(1)</span> man page.</p>
<!--TOC chapter id="sec31" Advanced features-->
<h1 id="sec31" class="chapter">Chapter&#XA0;7&#XA0;&#XA0;Advanced features</h1><!--SEC END -->
<!--TOC section id="sec32" Audio loop devices-->
<h2 id="sec32" class="section">7.1&#XA0;&#XA0;Audio loop devices</h2><!--SEC END --><p>Just by using normal chain connections it&#X2019;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.</p>
<!--TOC subsection id="sec33" Example of use-->
<h3 id="sec33" class="subsection">7.1.1&#XA0;&#XA0;Example of use</h3><!--SEC END --><p>An example use-case where we route audio from chains &#X201C;1&#X201D; and &#X201C;2&#X201D;
to chain &#X201C;3&#X201D; which is amplified and send to a soundcard output (&#X201C;alsa&#X201D;).</p><pre class="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--

</pre><p>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 -&gt; latency of x frames). </p>
<!--TOC section id="sec34" Ecasound Wave Files - the EWF (.ewf) format-->
<h2 id="sec34" class="section">7.2&#XA0;&#XA0;Ecasound Wave Files - the EWF (.ewf) format</h2><!--SEC END -->
<!--TOC subsection id="sec35" General-->
<h3 id="sec35" class="subsection">7.2.1&#XA0;&#XA0;General</h3><!--SEC END --><p>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.</p><p>Starting from Ecasound version 2.5.0, similar functionality is
provided by special purpose audio object types &#X2019;audioloop&#X2019;, &#X2019;audioselect&#X2019;
and others. You may choose between EWF and these audio object types
based on your specific needs. See 
<a href="http://nosignal.fi/ecasound/Documentation/ecasound_manpage.html">ecasound(1)</a>
man page and the <span style="font-family:monospace">Examples web page</span>
at <a href="http://nosignal.fi/ecasound/Documentation/examples.html"><span style="font-family:monospace">http://nosignal.fi/ecasound/Documentation/examples.html</span></a>
for many examples of using these.</p><p>Writing to EWF file is nowadays considered to be a deprecated
feature and it may be removed in a future release.</p>
<!--TOC subsection id="sec36" File format-->
<h3 id="sec36" class="subsection">7.2.2&#XA0;&#XA0;File format</h3><!--SEC END --><p>Ewf-files are stored in ascii format. The syntax is based on &#X201C;key=value&#X201D;
pairs. The same syntax is used with Ecasound resource files. See
<a href="http://nosignal.fi/ecasound/Documentation/ecasoundrc_manpage.html">ecasoundrc(5)</a>
man page for detailed info. Currently recognized ewf keywords are:</p><ul class="itemize"><li class="li-itemize">
source - audio object name (string) [read,write]
</li><li class="li-itemize">offset - insert audio object at offset (time) [read,write] 
</li><li class="li-itemize">start-position - start offset inside audio object (time) [read]
</li><li class="li-itemize">length - how much of audio object data is used (time) [read]
</li><li class="li-itemize">looping - whether to loop sample data (true or false) [read]
</li></ul><p>All time values are interpreted as seconds (need not be an integer
but can be given as a decimal number, e.g. &#X201C;1.05&#X201D;). However if 
the value is an integer number and has a postfix of &#X201C;sa&#X201D; (e.g. 
&#X201C;44100sa&#X201D;), it is interpreted as time expressed as samples (in
case of a multichannel stream, time in sample frames).</p>
<!--TOC subsection id="sec37" Example of ewf use-->
<h3 id="sec37" class="subsection">7.2.3&#XA0;&#XA0;Example of ewf use</h3><!--SEC END --><p>Let&#X2019;s look at a simple example .ewf file:</p><pre class="verbatim"> 
-- test.ewf --
source = test.wav
offset = 5.0
start-position = 2.0
length = 3.0
looping = true
--cut--
</pre><p>Now what happens when you issue "ecasound -i test.ewf -o alsa"? 
Because of the &#X201C;offset&#X201D; definition, the first 5 seconds will be 
silent. After that ecasound will start to read data from &#X201C;test.wav&#X201D;.
But as &#X201C;start-position&#X201D; is not zero, ecasound will skip the 
first 2 seconds. After 8 seconds has passed (&#X201C;offset&#X201D; + 
&#X201C;length&#X201D;), ecasound will loop back to &#X201C;start-position&#X201D;. 
This looping will continue until the user interrupts the operation.</p>
<!--TOC section id="sec38" Effect presets-->
<h2 id="sec38" class="section">7.3&#XA0;&#XA0;Effect presets</h2><!--SEC END -->
<!--TOC subsection id="sec39" General-->
<h3 id="sec39" class="subsection">7.3.1&#XA0;&#XA0;General</h3><!--SEC END --><p>
Ecasound has a powerful effect preset system that allows you to create
new effects by combining basic effects and controllers.</p><p>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 <a href="http://nosignal.fi/ecasound/Documentation/ecasoundrc_manpage.html">ecasoundrc(5)</a>
man page, the same file format and syntax is used):</p><pre class="verbatim"> 
preset_name = effects controllers | ... | effects controllers 
</pre><p>Effects and controllers are specified using the EOS syntax, 
the same syntax that is used for parsing command-line options 
(&#X201C;-ea:100&#X201D;, &#X201C;-kl:1,0,100,5&#X201D;, etc). The pipe character is
used to separate parallel chains. </p><p>Just like in shell scripts, the &#X2019;\&#X2019; character can
be used to spread definitions across multiple lines.</p>
<!--TOC subsection id="sec40" Example of preset use-->
<h3 id="sec40" class="subsection">7.3.2&#XA0;&#XA0;Example of preset use</h3><!--SEC END --><p>
Ecasound effect presets are in fact small Ecasound engines that
behave just like native effects. Here&#X2019;s an example of a 
multi-chain effect preset:</p><pre class="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--
</pre><p>Once defined, you can use the preset in the following way:</p><pre class="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--
 </pre><p>When separate files are used (the &#X201C;-pf:name&#X201D; option), 
Ecasound always loads the first preset it finds. If the 
file contains more presets (additional &#X201C;key=value&#X201D; -pairs),
they are ignored.</p><p>An alternative way to define presets is to put the 
definition in the global preset list (usually in 
&#X201C;/usr/local/share/ecasound/effect_presets&#X201D;. Once you&#X2019;ve
added a line defining &#X201C;bassbooster&#X201D;, you can use it 
like:</p><pre class="verbatim"> 
--cut--
ecasound -a:1 -i:some.mp3 -pn:bassbooster
         -a:2 -i:another.mp3 -pn:bassbooster
         -a:1,2 -o:alsa
--cut--
</pre>
<!--TOC subsection id="sec41" Preset parameters-->
<h3 id="sec41" class="subsection">7.3.3&#XA0;&#XA0;Preset parameters</h3><!--SEC END --><p>Parameters of operators belonging to a preset can be
exposed as preset paramters. Example:</p><pre class="verbatim">--cut preset definition--
f_res_lowpass = -ef3:%1,1.5,0.7
--cut--
</pre><p>In the above example, the lowpass filter cutoff is exposed 
as a parameter of the &#X201C;f_res_lowpass&#X201D; preset. The preset
can be used just like any other Ecasound operator. The 
following two commands will results in identical output:</p><pre class="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--
</pre>
<!--TOC subsection id="sec42" Parameter descriptors-->
<h3 id="sec42" class="subsection">7.3.4&#XA0;&#XA0;Parameter descriptors</h3><!--SEC END --><p>Ecasound preset parameters can be described using the following
set of descriptors:</p><pre class="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)
</pre><p>The option can only be used inside preset definitions (in &#X201C;effect_presets&#X201D;
files, or individual &#X201C;*.ecp&#X201D; files). An example preset parameter
definition:</p><pre class="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--
</pre><p>The above preset &#X201C;f_two_filters&#X201D; has two parameters, which 
are described using the &#X201C;-pd&#X201D; descriptor. Recommended lower and
upper bounds for the parameters are defined with &#X201C;-ppl&#X201D; and
&#X201C;-ppu&#X201D; descriptors. Default values for the parameters are 
specified with &#X201C;-ppd&#X201D;.</p>
<!--TOC section id="sec43" Gate operators-->
<h2 id="sec43" class="section">7.4&#XA0;&#XA0;Gate operators</h2><!--SEC END --><p>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:</p>
<!--TOC subsection id="sec44" Example of use-->
<h3 id="sec44" class="subsection">7.4.1&#XA0;&#XA0;Example of use</h3><!--SEC END --><p>The following sequence cuts the section [60:00 sec -&gt; 
61:00 sec] from &#X201C;guitar.wav&#X201D; into &#X201C;gate-test.wav&#X201D;:</p><pre class="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--
</pre><p>The threshold gate is used similarly:</p><pre class="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--
 </pre><p>In the first case, the gate is opened when the RMS-volume goes over the &#X201C;11.2%&#X201D;
threshold, and closed when RMS-volume falls below &#X201C;5%&#X201D;. In the second,
case, both entry and close thresholds are &#X201C;5%&#X201D; (peak volume).</p>
<!--TOC section id="sec45" LADSPA plugins-->
<h2 id="sec45" class="section">7.5&#XA0;&#XA0;LADSPA plugins</h2><!--SEC END --><p>Ecasound supports LADSPA-effect plugins (Linux Audio Developer&#X2019;s 
Simple Plugin API). See <a href="http://nosignal.fi/ecasound/Documentation/ecasound_manpage.html">ecasound(1)</a>
man page and the LADSPA web site at &#X201C;www.ladspa.org&#X201D; for more information.</p>
<!--TOC subsection id="sec46" Ecasound is not able to find any LADSPA plugins I have installed!-->
<h3 id="sec46" class="subsection">7.5.1&#XA0;&#XA0;Ecasound is not able to find any LADSPA plugins I have installed!</h3><!--SEC END --><p>Just installing the LADSPA SDK - &#X201C;www.ladspa.org&#X201D;
- should be enough. The plugins themselves are stored in shared library 
files (.so). They are usually stored in &#X201C;/usr/local/lib/ladspa&#X201D;. To test 
whether Ecasound finds the plugins, issue:</p><p>echo "ladspa-register" | ecasound -c</p><p>You should get a list of all installed LADSPA plugins. If this doesn&#X2019;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&#X2019;ve compiled Ecasound yourself you
should recompile after installing the LADSPA SDK.</p><p>Also, check Dave Phillips&#X2019; great
article on Oreillynet - 
<a href="http://www.oreillynet.com/pub/a/linux/2001/02/02/ladspa.html"><span style="font-family:monospace">http://www.oreillynet.com/pub/a/linux/2001/02/02/ladspa.html</span></a>.</p>
<!--TOC section id="sec47" JACK Audio Server-->
<h2 id="sec47" class="section">7.6&#XA0;&#XA0;JACK Audio Server</h2><!--SEC END --><p>
<a id="JACK Audio Server"></a></p><p>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.</p><p>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. </p><p>Note that Ecasound must be compiled with JACK support enabled 
(the &#X201C;&#X2013;with-jack&#X201D; configure option) to take advantage of
the functionality described in this section.</p>
<!--TOC subsection id="sec48" Basic Input and Output-->
<h3 id="sec48" class="subsection">7.6.1&#XA0;&#XA0;Basic Input and Output</h3><!--SEC END --><p>Let&#X2019;s start with how to play a file using Ecasound and JACK:</p><pre class="verbatim">ecasound -i foo.wav -o jack,system
</pre><p>This will create a separate JACK output port for each channel
of &#X201C;foo.wav&#X201D;, and automatically connect these Ecasound ports to
the JACK system PCM output ports. </p><p>Note that ecasound does not allow to mix objects with different 
sampling rates (without explicitly inserting &#X201C;samplerate&#X201D; 
conversion objects). That means that if sampling rate of &#X201C;foo.wav&#X201D;
does not match the current JACK system rate, the above command
wil fail.</p><p>The connections creadted are as follows:</p><pre class="verbatim">ecasound:out_1    --&gt;       system:playback_1
ecasound:out_2    --&gt;       system:playback_2
</pre><p>If &#X201C;foo.wav&#X201D; was a four channel file, the same command would 
connect all channels:</p><pre class="verbatim">ecasound:out_1    --&gt;       system:playback_1
ecasound:out_2    --&gt;       system:playback_2
ecasound:out_3    --&gt;       system:playback_3
ecasound:out_4    --&gt;       system:playback_4
</pre><p>To record a file, you&#X2019;d issue:</p><pre class="verbatim">ecasound -f:,2 -i jack,system -o foo.wav
ecasound -f:f32,2,44100 -i jack,system -o foo.wav
</pre><p>Here we use &#X201C;-f:bits,channels,srate&#X201D; to set how many channels 
to record from the sound device using JACK. As described in 
the <a href="http://nosignal.fi/ecasound/Documentation/ecasound_manpage.html">ecasound(1)</a>
man page, the parameters to &#X201C;-f&#X201D; 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). </p><p>It is possible to add another &#X201C;-f&#X201D; before &#X201C;-o foo.wav&#X201D;
if you want to write the file in a different format. For 
example to convert the sample format to 16bit fixed:</p><pre class="verbatim">ecasound -f:f32,2 -i jack,system -f:s16,2 -o foo.wav
</pre>
<!--TOC subsection id="sec49" More Advanced Port Creation-->
<h3 id="sec49" class="subsection">7.6.2&#XA0;&#XA0;More Advanced Port Creation</h3><!--SEC END --><p>Ecasound also offers the following alternative ways 
to create input and output ports:</p><pre class="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
</pre><p>See <a href="http://nosignal.fi/ecasound/Documentation/ecasound_manpage.html">ecasound(1)</a>
manual page for descriptions of the &#X201C;jack_multi&#X201D; audio object and the variants 
of &#X201C;jack&#X201D; usage.</p>
<!--TOC subsection id="sec50" Transport Control-->
<h3 id="sec50" class="subsection">7.6.3&#XA0;&#XA0;Transport Control</h3><!--SEC END --><p>Transport controls are functions like &#X201C;start&#X201D;, &#X201C;stop&#X201D;, &#X201C;seek&#X201D;, 
etc, that are commonly available in audio applications that 
maintain some kind of current position. JACK&#X2019;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 (&#X201C;notransport&#X201D;, &#X201C;send&#X201D;, &#X201C;recv&#X201D; 
and &#X201C;sendrecv&#X201D;).</p><p>By default Ecasound will both send and reveive transport 
events (position and state) to other JACK clients 
(mode &#X201C;sendrecv&#X201D;):</p><pre class="verbatim">ecasound -c -i null -o jack
</pre><p>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 &#X201C;engine-launch&#X201D; 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 
&#X201C;stop&#X201D;, &#X201C;setpos 20&#X201D;, &#X201C;rw 10&#X201D;, &#X201C;fw 10&#X201D;, and so should
affect other apps.</p><p>By default, Ecasound doesn&#X2019;t react to outside transport 
control. To enable this:</p><pre class="verbatim">ecasound -c -i foo.wav -o jack,system -G:jack,eca_slave,recv
</pre><p>After giving an initial &#X201C;engine-launch&#X201D; to Ecasound, you should
now be able to use other JACK apps to control Ecasound&#X2019;s
playback of &#X201C;foo.wav&#X201D;. </p><p>To combine external control with the ability to control 
the transport from ecasound&#X2019;s user-interface:</p><pre class="verbatim">ecasound -c -i foo.wav -o jack,system -G:jack,eca_slave,sendrecv
</pre>
<!--TOC subsection id="sec51" JACK and Ecasound states-->
<h3 id="sec51" class="subsection">7.6.4&#XA0;&#XA0;JACK and Ecasound states</h3><!--SEC END --><p>To have a good understanding of the overall system, it&#X2019;s important
to understand how Ecasound and JACK states relate to each other.</p><p>When an Ecasound chainsetup is connected (EIAM-command &#X201C;cs-connect&#X201D;),
a connection is established with the JACK server, and all the 
JACK ports in that chainsetup are registered to it. 
Once Ecasound&#X2019;s engine is launched with EIAM-command &#X201C;engine-launch&#X201D;,
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.</p><p>When Ecasound processing is started (either with &#X201C;start&#X201D; or
by an incoming transport event), Ecasound&#X2019;s engine runs 
as a node in the JACK system. When processing is stopped (either 
with &#X201C;stop&#X201D;, or by a transport event), Ecasound&#X2019;s engine is 
not run.</p><p>Any connections (initiated by Ecasound) to other clients, 
are disconnected once &#X201C;engine-halt&#X201D; 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 (&#X201C;cs-disconnect&#X201D;).</p><p>Note! Normally you don&#X2019;t need to go through all the steps one
by one. Instead issuing &#X201C;start&#X201D; will automatically connect
the chainsetup and launch the engine. Similarly &#X201C;cs-disconnect&#X201D;
will stop processing and halt the engine if needed.</p>
<!--TOC subsection id="sec52" Troubleshooting-->
<h3 id="sec52" class="subsection">7.6.5&#XA0;&#XA0;Troubleshooting</h3><!--SEC END --><p>Ecasound v2.2 and earlier don&#X2019;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 &#X201C;-b:xxx&#X201D;) and sampling 
rate (with &#X201C;-f:bits,channels,srate&#X201D; and possibly using the
<em>resample</em> audio object). This is the first thing to
check if communication with JACK does not work.</p><p>Future versions of Ecasound will hopefully solve this 
problem. This issue is covered by Ecasound development item 
&#X201C;edi-31 - Support for dynamic sampling rate and buffersize changes.&#X201D;.</p>
<!--TOC subsection id="sec53" Deprecated JACK input/output syntax-->
<h3 id="sec53" class="subsection">7.6.6&#XA0;&#XA0;Deprecated JACK input/output syntax</h3><!--SEC END --><p>
Ecasound 2.5 and older supported &#X201C;jack_alsa&#X201D;, &#X201C;jack_auto&#X201D; 
and &#X201C;jack_generic&#X201D; object types, but these are now replaced 
by a more generic &#X201C;jack&#X201D; interface. The old variants this
work, but are now considered deprecated (they work but may be
removed in a future Ecasound release).</p>
<!--TOC chapter id="sec54" Miscellaneous-->
<h1 id="sec54" class="chapter">Chapter&#XA0;8&#XA0;&#XA0;Miscellaneous</h1><!--SEC END -->
<!--TOC section id="sec55" Security Considerations-->
<h2 id="sec55" class="section">8.1&#XA0;&#XA0;Security Considerations</h2><!--SEC END --><p>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 &#X2019;sudo&#X2019; 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?</p><p>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, ...).</p><p>The basic problem is that Ecasound (or at least 2.0 and earlier) 
doesn&#X2019;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.</p><p>But all in all, this shouldn&#X2019;t be that big of an issue for many users. For
noncritical uses, just don&#X2019;t set the suid-bit, but run as a normal user. If 
you have an untrusted setup, and you don&#X2019;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:</p><pre class="verbatim"> 
        cd /usr/local/bin
        chown root.ecausers ecasound
        chmod 4750 ecasound
</pre><p>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 &#X2019;ecausers&#X2019; group can 
start it. You of course first have to create the &#X2019;ecausers&#X2019; group to your
system.</p><p>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.</p><p>The Realtime Linux Security Module (LSM) is one practical solution 
(see <a href="http://sourceforge.net/projects/realtime-lsm/"><span style="font-family:monospace">http://sourceforge.net/projects/realtime-lsm/</span></a> and 
<a href="http://lwn.net/Articles/106009/"><span style="font-family:monospace">http://lwn.net/Articles/106009/</span></a>). 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.</p><p>A more recent approach, and one that might be adopted by popular GNU/Linux distributions, 
is the <em>rtprio</em> extension to Linux resource limits. See 
<a href="http://lwn.net/Articles/134460/">f</a>or a good overview of this approach and how 
it compared to the LSM mechanism described above.</p><!--CUT END -->
<!--HTMLFOOT-->
<!--ENDHTML-->
<!--FOOTER-->
<hr style="height:2"><blockquote class="quote"><em>This document was translated from L<sup>A</sup>T<sub>E</sub>X by
</em><a href="http://hevea.inria.fr/index.html"><em>H</em><em><span style="font-size:small"><sup>E</sup></span></em><em>V</em><em><span style="font-size:small"><sup>E</sup></span></em><em>A</em></a><em>.</em></blockquote></body>
</html>
ecasound-doc 2.9.1-7ubuntu2 / usr / share / doc / ecasound / users_guide.html
