Ecasound documentation - User's guide
Kai Vehmanen
24042001
Table of Contents
1: Preface
2: Introduction
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
- 3.0.2: Audio object
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.2.2: Audio objects
4.3: Configuration
5: User interfaces
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
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.
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.
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.
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: GeneralHere 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:
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:
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).
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).
See ecasound(1).
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 controllersEffects 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--
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.