## Ecasound documentation - User's guide

## Kai Vehmanen

## 24042001

# Table of Contents

## 1: Preface

## 2: Introduction

### 2.1: What is ecasound?

### 2.2: History

## 3: Ecasound library concepts

3.0.1: Chain
3.0.2: Audio object
3.0.3: Chain operators and controllers
3.0.4: Chainsetup
3.0.5: Concept of current position
3.0.6: Interactive-mode

## 4: Using

### 4.1: Where to start?

### 4.2: Creating ecasound chainsetups

4.2.1: General
4.2.2: Audio objects
4.2.3: Chain operators
4.2.4: Controllers
4.2.5: Effect presets
4.2.6: LADSPA plugins

### 4.3: Configuration

## 5: User interfaces

### 5.1: ecasound

### 5.2: ecatools

## 1: Preface

This document describes ecasound's use from 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 in a very good shape. They are also available in HTML-format.

## 2: Introduction

### 2.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. As most functionality is located in shared libraries, creating alternative user-interfaces is easy. A versatile console mode interface is included in the package.

### 2.2: History

I've programmed ecasound for my own recording purposes. The first versions ran under IBM Os/2. I used them for finalizing my analog 4-track recordings. My 4-track was a nice tool, but it had its limits. So eventually I started to use Windows-based multitrack software. I still used ecasound for fx processing and finalizing. When I ported ecasound to Linux, a lot of the code was rewritten from scratch. During this I also added multitrack capabilities to ecasound. It took a lot of work, but in the end I was able to get rid of all my Windows recording software. Nowadays I use ecasound for all my music projects. Because of this, I also continue to improve and develop ecasound.

## 3: Ecasound library concepts

3.0.1: Chain

Chain is a simple signal flow abstraction. Every chain has one input and one output. All chain operators and their controllers are attached to chains. Chain can be muted and bypassed.

3.0.2: Audio object

Audio object is a really generic concept. Practically anything that is able to produce or receive audio data can be an ecasound audio object. Currently there's support for soundcard drivers/subsystems, various file formats and various types of data-piping. Notice that objects can be used both for input and output.

3.0.3: Chain operators and controllers

Chain operators are used to process and analyze sample data. Controllers are used to control individual chain operator parameters. Both types of objects are attached to chains. Term chain object refers to all objects that can be attached to chains - ie. operators and controllers.

3.0.4: Chainsetup

Chainsetup is the central data object. All other objects (inputs, outputs, chains, etc) are connected to some chainsetup. There can be many chainsetups but only one can be connected. Similarly only one chainsetup can be selected. Chainsetups are also used for loading and saving state information. The format used is identical to the command-line syntax used by the console mode user-interface, which makes it easy to edit saved chainsetups. See ecasound(1) for details.

3.0.5: Concept of current position

Only audio objects and chainsetups have a current position. When you change position of a chain, you're changing position of audio objects connected to that chain. Also, when you change chainsetup position, all chains (= all audio objects attached to them) are affected.

3.0.6: Interactive-mode

Ecasound library can be controlled with simple commands. This is called the interactive-mode. All programs linked to ecasound library can use this facility.

## 4: Using

### 4.1: Where to start?

There's no one single way to use ecasound. You can use it as a simple glue component for doing tasks, which aren't handled by other applications you are using, or because ecasound does these tasks more easily. But ecasound can also serve as the centre of your studio setup, doing everything from effects processing to multitrack recording and mixing.

But this flexibility doesn't come for free. It's difficult to describe ecasound's features in a few phrases. Because of this, I encourage new users to start from ecasound examples.html page. It isn't a perfect introduction, and definitely not the only way to use ecasound, but it does give an overall view of what can be done with ecasound, and more importantly, that most tasks are actually quite easy to perform.

### 4.2: Creating ecasound chainsetups

4.2.1: General

Here are a few rules that help writing valid chainsetups. Whether you are writing chainsetup files (.ecs), using command-line arguments, using a graphical frontend, etc, these rules are always useful:

- Every chain has exactly _one_ input and _one_ output.
- All inputs and outputs must be connected to some chain.
- For every input/output, there must be exactly _one_ input/output specification (example specification: '-i:file.ext').
- All routing from/to chains is based on selecting a set of chains and then specifying an input or output (example: '-a:1,2 -i:file.ext').
- All audio copying and mixing is done channel-wise. If you attach a 4-channel input and a two-channel output to a chain, chain will have 4 channels of audio, but only the first two channels will be written to the output file.

4.2.2: Audio objects

ewf - ecasound wave file
Ecasound wave file (.ewf) is a simple wrapper format for controlling other audio objects. One important feature of ewf is the ability to seek beyond end position. When first write operation is performed, current file position is stored into the .ewf file and the actual audio object is opened for writing. When reading, you get silence until the offset position is reached. Shortly put, this is a practical way to save disk space when doing multitrack recording. Newer versions of ewf-format support looping, ranges, etc

Ewf-files themselves are simple ascii files that contain key-value pairs. The format used is the same as with ecasound resource files. See ecasoundrc(5) manual page for more info. Currently recognized keywords are:

- source - audio object name [read,write]
- offset - insert audio object at offset (seconds) [read,write]
- start-position - start offset inside audio object (seconds) [read]
- length - how much of audio object data is used (seconds) [read]
- looping - whether to loop sample data (true or false) [read]

subsubsubsubsect(Example of ewf use) Let's take an example .ewf file:

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

So what happens when you issue "ecasound -i test.ewf -o /dev/dsp". The first 5 secs will be silent, then ecasound starts to read data from test.wav (offset inside test.wav is 2 secs). After 8 secs (offset + length) of playback, we'll loop back to start (2 sec from beginning of test.wav).

Audio loop devices
Loop devices were added to ecasound version 1.7.0. You use them like this:

    --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 -o:loop,1
             -a:2 -i:another.mp3 -o:loop,1
             -a:3 -i:loop,1 -o /dev/dsp -ea:200
    --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).

4.2.3: Chain operators

See ecasound(1).

Some examples of the use of gate operators
Gates are just like any other chain operators. They are assigned to a chain, and process buffers of samples data. With gates you can easily crop sections of audio files, and do automatic volume-based cropping. For instance.

    --cut--
    ###| /empty1 |$ ls -la guitar.wav
    -rw-rw-r--   1 kaiv     kaiv     15790124 Sep 30 23:27 guitar.wav

    ###| /empty1 |$ ecasound_debug -i guitar.wav -o gate-test.wav -gc:60,1

    ###| /empty1 |$ ls -la gate-test.wav
    -rw-rw-r--   1 kaiv     kaiv       180268 Dec 12 22:13 gate-test.wav
    --cut--

This cut the section [60:00 sec -> 61:00 sec] from guitar.wav into gate-test.wav. The old '-gc' would have just muted all audio outside the [60,61] region. The threshold gate is used similarly:

    --cut--
    ###| /empty1 |$ ecasound_debug -i gate-test.wav -o gate-test-rms.wav -ge:11.2,5,1

    ###| /empty1 |$ ecasound_debug -i gate-test.wav -o gate-test-peak.wav -ge:5,5,0

    ###| /empty1 |$ 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 one, gate is opened when the RMS-volume goes over the 11.2% threshold, and closed when RMS-volume falls below 5%. In the second, both entry and close thresholds are 5% (peak volume).

4.2.4: Controllers

See ecasound(1).

4.2.5: Effect presets

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 parsing engine is used):

    preset_name = effects controllers | ... | effects controllers

Effects and controllers are specified using the same format as used in command-line parsing (-ea:100, -kl:1,0,100,5, etc). You can add a new parallel chain using the pipe characher '|'. '\' sign is used to continue preset definition on the next line.

Example of preset use
Ecasound effect presets are in fact small ecasound engines pretending to be effects. Here's an example of multi-chain effect preset:

    -- 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:/dev/dsp
    --cut--

4.2.6: LADSPA plugins

Ecasound supports LADSPA-effect plugins (Linux Audio Developer's Simple Plugin API). See ecasound(1) for more info.

### 4.3: Configuration

User preferences are stored to ~/.ecasouncrc. See ecasoundrc(5) manual page for more info.

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

## 5: User interfaces

Probably the best place to start is the examples section of ecasound HTML-documentation: examples.html.

### 5.1: ecasound

See ecasound(1).

### 5.2: ecatools

See ecatools(1).