Ecasound User’s Guide

Kai Vehmanen

19042009

Contents

Chapter 1  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 2  Document history

Chapter 3  Introduction

3.1  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 4  Ecasound concepts

4.1  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.

4.2  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.

4.3  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 chain object refers to all objects that can be attached to chains - ie. operators and controllers.

4.4  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 connected is used to describe a chainsetup that is in use.

Another important chainsetup concept is that of a 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 .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 ecasound(1) man page for details.

4.5  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.

4.6  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.

4.7  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 ecasound-iam(1) man page.

4.8  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:

Chapter 5  Using

5.1  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 Examples page at http://nosignal.fi/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.

5.2  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:

Note that these rules are checked only when connecting the chainsetup (when issuing commands such as “cs-connect”, or “start”).

5.3  Chain operators and controllers

The best place to start is to read through the ecasound(1) man page, which contains documentation for all native Ecasound chain objects.

5.4  Configuration

User preferences are stored in ~/.ecasound/ecasoundrc. See the ecasoundrc(5) manual page for details.

By default, files for effect presets and oscillator presets are in /usr/share/ecasound.

5.5  Common problems

5.5.1  I get occasional audio dropouts during operation? How to get rid of them?

Check 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:

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 http://www.linuxdj.com/audio/lad/archive.php.

Here are links to selected messages from the ecasound-list archives:

5.5.2  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": http://karmak.org/archive/2003/02/audio_quality_HOWTO.htm. The original page at http://www.linuxdj.com/audio/quality/ is no longer available.

5.5.3  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:

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

The actual signal chain is something like:

  
monofile1.wav |--'1'---- erc ----| epp |---\
                           \-----|     |---\\
                                            \\
monofile2.wav |--'2'---- erc ----| epp |------- | alsa
                           \-----|     |------- |
                                            //
monofile3.wav |--'3'---- erc ----| epp |---//
                           \-----|     |---/

('---' = mono channel)

The critical points to notice are:

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.

5.5.4  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:

ecasound -i foo,bar.ogg -o alsa

The only way around this is to escape all the commas with backslashes:

ecasound -i foo\\,bar.ogg -o alsa

The backslash has to be a double-backslash as the shell strips one of the backslashes away before passing the string to ecasound.

Chapter 6  User interfaces and Applications

For a complete list of user-interfaces and applications built on top of Ecasound, visit Ecasound’s web site at http://www.eca.cx.

6.1  Ecasound

The standalone program “ecasound” is the primary user interface for Ecasound.

See ecasound(1) man page and the Examples web page at http://nosignal.fi/ecasound/Documentation/examples.html.

6.2  Ecasignalview

Ecasignalview is an utility program for monitoring signal amplitude and peak statistics. It’s primarily used when adjusting signal levels for recording.

6.2.1  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.

# OSS-drivers (or properly installed ALSA OSS-emulation)
ecasignalview /dev/dsp null

# native ALSA-mode, recording from the 'default' device
ecasignalview alsa,default null

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 alsamixer (ALSA), aumix (OSS) or some other mixer application. Another option is to use ecasignalview to do the monitoring. In this case the correct command is:

# OSS input and output
ecasignalview /dev/dsp /dev/dsp

# corresponding ALSA command
ecasignalview alsa,default alsa,default

Ecasignalview command-line options allow you to fine-tune the way monitoring is done:

# 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

It can also be used with files and real-time devices like JACK inputs and outputs:

# 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

6.2.2  Further Reading

See ecatools(1) man page for a detailed listing of available command-line options.

6.3  Ecatools

See ecatools(1) man page.

Chapter 7  Advanced features

7.1  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.

7.1.1  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”).

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

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).

7.2  Ecasound Wave Files - the EWF (.ewf) format

7.2.1  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 ecasound(1) man page and the Examples web page at http://nosignal.fi/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.

7.2.2  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 ecasoundrc(5) man page for detailed info. Currently recognized ewf keywords are:

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).

7.2.3  Example of ewf use

Let’s look at a simple example .ewf file:

 
-- test.ewf --
source = test.wav
offset = 5.0
start-position = 2.0
length = 3.0
looping = true
--cut--

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.

7.3  Effect presets

7.3.1  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 ecasoundrc(5) man page, the same file format and syntax is used):

 
preset_name = effects controllers | ... | effects controllers 

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 ’\’ character can be used to spread definitions across multiple lines.

7.3.2  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:

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

Once defined, you can use the preset in the following way:

 
--cut--
ecasound -a:1 -i:some.mp3 -pf:bassbooster.ecp
         -a:2 -i:another.mp3 -pf:bassbooster.ecp
         -a:1,2 -o:alsa
--cut--
 

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:

 
--cut--
ecasound -a:1 -i:some.mp3 -pn:bassbooster
         -a:2 -i:another.mp3 -pn:bassbooster
         -a:1,2 -o:alsa
--cut--

7.3.3  Preset parameters

Parameters of operators belonging to a preset can be exposed as preset paramters. Example:

--cut preset definition--
f_res_lowpass = -ef3:%1,1.5,0.7
--cut--

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:

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

7.3.4  Parameter descriptors

Ecasound preset parameters can be described using the following set of descriptors:

 -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)

The option can only be used inside preset definitions (in “effect_presets” files, or individual “*.ecp” files). An example preset parameter definition:

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

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”.

7.4  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:

7.4.1  Example of use

The following sequence cuts the section [60:00 sec -> 61:00 sec] from “guitar.wav” into “gate-test.wav”:

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

The threshold gate is used similarly:

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

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).

7.5  LADSPA plugins

Ecasound supports LADSPA-effect plugins (Linux Audio Developer’s Simple Plugin API). See ecasound(1) man page and the LADSPA web site at “www.ladspa.org” for more information.

7.5.1  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 - http://www.oreillynet.com/pub/a/linux/2001/02/02/ladspa.html.

7.6  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.

7.6.1  Basic Input and Output

Let’s start with how to play a file using Ecasound and JACK:

ecasound -i foo.wav -o jack,system

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:

ecasound:out_1    -->       system:playback_1
ecasound:out_2    -->       system:playback_2

If “foo.wav” was a four channel file, the same command would connect all channels:

ecasound:out_1    -->       system:playback_1
ecasound:out_2    -->       system:playback_2
ecasound:out_3    -->       system:playback_3
ecasound:out_4    -->       system:playback_4

To record a file, you’d issue:

ecasound -f:,2 -i jack,system -o foo.wav
ecasound -f:f32,2,44100 -i jack,system -o foo.wav

Here we use “-f:bits,channels,srate” to set how many channels to record from the sound device using JACK. As described in the 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:

ecasound -f:f32,2 -i jack,system -f:s16,2 -o foo.wav

7.6.2  More Advanced Port Creation

Ecasound also offers the following alternative ways to create input and output ports:

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

See ecasound(1) manual page for descriptions of the “jack_multi” audio object and the variants of “jack” usage.

7.6.3  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”):

ecasound -c -i null -o jack

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:

ecasound -c -i foo.wav -o jack,system -G:jack,eca_slave,recv

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:

ecasound -c -i foo.wav -o jack,system -G:jack,eca_slave,sendrecv

7.6.4  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.

7.6.5  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 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.”.

7.6.6  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 8  Miscellaneous

8.1  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:

 
        cd /usr/local/bin
        chown root.ecausers ecasound
        chmod 4750 ecasound

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 http://sourceforge.net/projects/realtime-lsm/ and 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 rtprio extension to Linux resource limits. See for a good overview of this approach and how it compared to the LSM mechanism described above.


This document was translated from LATEX by HEVEA.