[Index] [Examples] [FAQ] [Man pages] [User's guide] [Programmer's guide] [Source tree] [ecasound home page]

Ecasound documentation - User's guide


Kai Vehmanen

21022000

Table of Contents

1: Preface

2: Introduction

2.1: What is ecasound?

2.2: History

3: Ecasound library features

3.1: Concepts

3.1.1: Chain
3.1.2: Audio object
3.1.3: Chain operators and controllers
3.1.4: Chainsetup
3.1.5: Concept of current position
3.1.6: Interactive-mode

3.2: Configuration

3.3: Audio objects

3.3.1: ewf - ecasound wave file

3.4: Chain operators

3.5: Controllers

3.6: Effect presets

4: User interfaces

4.1: ecasound

4.2: qtecasound

4.3: ecatools

5: Documentation



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 referenced 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. Several open-source audio packages, like for instance ALSA, OSS, mpg123, lame, libaudiofile and MikMod, are directly supported. One of the advantages of ecasound's chain-based design is that effects can easily be combined both in series and in parallel. Oscillators and MIDI-CCs can be used for controlling effect parameters. Included user-interfaces are ecasound - a versatile console mode interface, qtecasound - a Qt-based X-interface and various command-line utils suitable for batch processing.

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 features

3.1: Concepts

3.1.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.1.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 inputs and outputs are not separated in any way.

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

3.1.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. 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.1.5: Concept of current position

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

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

3.2: 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.

3.3: Audio objects

3.3.1: 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]
  • 3.4: Chain operators

    See ecasound(1).

    3.5: Controllers

    See ecasound(1).

    3.6: Effect presets

    Ecasound has a powerful effect preset system that allows you 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 chain using the pipe characher '|'. '\' sign is used to continue preset definition on the next line.

    4: User interfaces

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

    4.1: ecasound

    See ecasound(1).

    4.2: qtecasound

    See qtecasound(1).

    4.3: ecatools

    See ecatools(1).

    5: Documentation