Ecasound(3pm)

📦

version 1.01 · 6 versions

💖 NAME 💖

okay so bestie, welcome to Ecasound(3pm) — a User Contributed Perl Documentation page, and it's literally about Audio::Ecasound — the Perl binding to the ecasound sampler, recorder, fx-processor. 🎧✨

🌸 SYNOPSIS 🌸

no cap, there are like four whole vibes in here and all of them are valid:

One function interface:

use Audio::Ecasound qw(:simple);

eci("cs-add play_chainsetup");
eci("c-add 1st_chain");
eci("-i:some_file.wav");
eci("-o:/dev/dsp");
# multiple \n separated commands
eci("cop-add -efl:100
     # with comments
     cop-select 1
     copp-select 1
     cs-connect");
eci("start");
my $cutoff_inc = 500.0;
while (1) {
    sleep(1);
    last if eci("engine-status") ne "running";

    my $curpos = eci("get-position");
    last if $curpos > 15;

    my $next_cutoff = $cutoff_inc + eci("copp-get");
    # Optional float argument
    eci("copp-set", $next_cutoff);
}
eci("stop");
eci("cs-disconnect");
print "Chain operator status: ", eci("cop-status");

Object Interface

use Audio::Ecasound;

my $e = new Audio::Ecasound;
$e->on_error('');
$e->eci("cs-add play_chainsetup");
# etc.

Vanilla Ecasound Control Interface (See Ecasound's Programmer Guide):

use Audio::Ecasound qw(:std);

command("copp-get");
$precise_float = last_float() / 2;
command_float_arg("copp-set", $precise_float);
warn last_error() if error();

IAM Interface, pretend interactive mode commands are functions.

use Audio::Ecasound qw(:iam :simple);

# iam commands as functions with s/-/_/g
my $val = copp_get;
copp_set $val+0.1; # floats are stringified so beware
eci("-i /dev/dsp"); # not all commands are exported

🦋 DESCRIPTION 🦋

Audio::Ecasound provides perl bindings to the ecasound control interface of the ecasound program. it's giving "let perl drive". 🚗💨 you can use perl to automate or interact with ecasound so you don't have to turn your back on the adoring masses packed into Wembly Stadium. iconic behaviour, honestly.

Ecasound is a software package designed for multitrack audio processing. bestie it does SO much:

audio playback
recording
format conversions
effects processing
mixing
acting as a LADSPA plugin host
being a JACK node

Version >= 2.2.X must be installed to use this package. go check the "SEE ALSO" section for more info. 👑

🎀 INSTALLATION 🎀

perl Makefile.PL

If your perl wasn't built with -Dusethreads or -D_REENTRANT you will be prompted whether to continue with the install. it's in your hands... 🙈 See "THREADING NOTE".

make
make test
make install

🧵 THREADING NOTE 🧵

The ecasoundc library uses pthreads so will may only work if your perl was compiled with threading enabled. check it with:

% perl -V:usethreads

You are welcome to try using the module with non-threaded perls (perhaps -D_REENTRANT alone would work) — it have worked for some. we love an experimental queen 💜

🌈 EXPORT 🌈

Nothing by default, as when going OO.
:simple gives you eci() which does most everything, plus errmsg and on_error. Or you could just import 'eci' and call the others like Audio::Ecasound::errmsg().
:iam imports many iam commands so that you can use them as perl functions. Basically everything listed by ecasound's 'int-cmd-list' except the single letter commands, and hyphens are replaced by underscores. The list is produced at run-time and returned by Audio::Ecasound::get_iam_cmds(). See "IAM COMMANDS".
:std to import the full ecasound control interface detailed in the Ecasound Programmer's Guide.
:raw and raw_r, C functions with minimal wrapping. the _r ones are reentrant and must be passed the object returned by eci_init_r(). I don't know why you would use these, presumably you do. These options may be removed in future. ⚠️

✨ METHODS AND FUNCTIONS ✨

The procedural and OO interfaces use the same functions, the differences are that when called on an Audio::Ecasound object the reentrant C versions are used — so you can have multiple independent engines (with independent options). multiple main characters, no fighting 💅

`new()`

Constructor for Audio::Ecasound objects. It inherits the on_error and other options from the current package settings (defaults if untouched).

`eci('ecasound command string', [$float_argument])`

Sends commands to the Ecasound engine. A single command may be called with an optional float argument (to avoid precision loss). Alternatively, multiple commands may be given separated by newlines (with "#" starting a comment).

If called in non-void context the result of the last command is returned. it may be an integer, float, string (ie. scalar) or a list of strings — which one depends on the ecasound command, so go look at ecasound-iam for each function's return value.

If there is an error, the action given to on_error will be taken. See on_error below for return value caveats when on_error = ''. Error processing is performed for each command in a multiline command.

`on_error('die')`

Set the action to be taken when an error occurs from an "eci" command. may be 'die', 'warn', '', 'confess', ... (default is 'warn'). 😬

When '' is selected, "return;" is used for an error — that is undef or (). To disamibiguate, eci will return '' or ('') for no return value and no string list respectively.

`errmsg()`

The last error message from an "eci" command. It is not reset, so clear it yourself if required with errmsg(''). This shouldn't be necessary though, as you can use "defined" or on_error to find out when errors occur.

The remainder of the functions/methods are the standard Ecasound Control Interface methods, but they come in three flavours. The bare function name may be called with or without an object:

use Audio::Ecasound ':simple':
command($cmd);
# or
my $e = new Audio::Ecasound;
$e = command($cmd);

The other two flavours are low-level, reentrant and non-reentrant. These are thinly wrapped C functions, better documented in the ECI document with the ecasound distribution. Just add 'eci_' to the names below for the non-reentrant version, and then add a '_r' to the end for the reentrant version. The reentrant version takes an extra first argument: the object returned by eci_init_r() which must be destroyed with eci_cleanup_r().

command($cmd_string)
eci_command_float_arg($cmd_string, $float_arg)
$bool = eci_error()
$err_str = eci_last_error()
$float = eci_last_float()
$int = eci_last_integer()
$lint = eci_last_long_integer()
$str = eci_last_string()
$n = eci_last_string_list_count()
$str_n = eci_last_string_list_item($n)
$type_str = eci_last_type() 's' 'S' 'i' 'li' 'f' ''

👑 IAM COMMANDS 👑

When the :iam tag is imported, most of the commands in ecasound's interactive mode become perl functions. the '-'s become '_'s so they're valid perl names ('cop-get' is cop_get, etc.) 🪄 The list is printed with:

use Audio::Ecasound qw(:iam :simple);
print join ' ', Audio::Ecasound::get_iam_cmds();

The arguments are joined together as a string and then sent to ecasound. This means that float precision is lost — unlike with the two argument "eci", so use it. Also use "eci" for command-line style commands like eci "-i /dev/dsp". But for most other things you can just use the iam command itself (s/-/_/g):

use Audio::Ecasound qw(:iam :simple);
... # setup stuff
print status;
start;
$v = copp_get;
copp_set $v + 1.2;

I would never encourage anyone to use "no strict 'subs';" but with :iam you may enjoy a little less discipline. 🙈✨

See the iam_int.pl example file in the eg directory.

🍓 EXAMPLES 🍓

See the "eg/" subdirectory. that's it, that's the whole section, go look 👀

💀 TROUBLESHOOTING 💀

The ecasound command 'debug' could be useful. add eci "debug 63" to the top of your program. The argument is various bits OR'd and controls the amount and type of debugging information. see the ecasound documentation of source, or just try your favorite powers of two. 🔥

there was a bug effecting Audio::Ecasound with ecasound version 2.4.4, causing problems with :iam mode, and test failure ("Do you need to predeclare cs_set_length"). See <http://www.eca.cx/ecasound-list/2006/12/0007.html> and <http://www.eca.cx/ecasound-list/2006/06/0004.html>.

🧚 FILES AND ENVIRONMENT 🧚

The libecasoundc library now uses the environment variable ECASOUND to find the ecasound executable. If it is not set then the libarary will print a warning. To suppress it, simply set the ECASOUND variable: eg. export ECASOUND=ecaosund

The ecasound library will still process ~/.ecasoundrc and other setup files for default values. See the library documentation.

💜 AUTHOR 💜

This software may be distributed under the same terms as Perl itself.

⭐ SEE ALSO ⭐

The Ecasound Programmer's Guide and ECI doc, ecasound, ecasound-iam, http://eca.cx/, http://www.ladspa.org/

The internals of libecasoundc have been rebuilt and now interact with a running ecasound via a socket using a protocol defined in the Programmer's Guide. The C library is now just a compatibility layer and the Python version now talks directly to the socket. It would be straight forward to write an equivalent Perl version should the need arise. a girl can dream ✨

okay bestie that's the whole page 🫶 perl v5.42.3, dated 2026-08-19 — and that's the Ecasound(3pm) manual page, signed, sealed, slayed. 💅🎀 bye!!

📦 where this page comes from

ubuntu stonking: libaudio-ecasound-perl 1.01-5build6 · Artistic-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms