ecasound.lua

NAME
SYNOPSIS
DESCRIPTION
DOWNLOAD

FUNCTIONS

ECI COMMANDS
CHANGES
AUTHOR
SEE ALSO

NAME

ecasound.lua - Provides access to the ecasound interactive mode

SYNOPSIS

 local E = require 'ecasound'
 E.eci_init()
 local commands = E.eci("int-cmd-list")    -- an array
 E.eci("cs-add play_chainsetup")
 E.eci("c-add 1st_chain")
 E.eci("ai-add /tmp/t.wav")
 E.eci("ao-add /dev/dsp")
 E.eci("cop-add -efl:100")     -- add a chain operator
 E.eci("cop-select 1")
 E.eci("copp-select 1") -- parameter 1 means the 100Hz
 print("aio-status = "..E.eci("aio-status"))
 E.eci("start")
 local freq_ratio = 1.2
 while (true) do
     os.execute("sleep 1")
     if E.eci("engine-status") ~= "running" then break end
     if E.eci("get-position") > 150 then break end
     local freq = E.eci("copp-get")
     if freq < 80 then break end
     if freq > 10000 then freq_ratio = 0.8333 end
     E.eci("copp-set", freq_ratio*freq) -- extra float argument
 end
 E.eci("stop")
 E.eci_cleanup()

DESCRIPTION

This module offers in Lua most of the functions defined in eg: /usr/include/libecasoundc/ecasoundc.h, except 1) instead of eci_command() it is abbreviated to eci(), and 2) those functions concerned with the return-types and return-values are not offered, since all that is handled internally by eci("commandstring"), which returns a Lua string, or array of strings, or a number, or a boolean, according to the command given.

eci() reports errors by returning nil, 'error-string' as is needed by the Lua assert() function. Therefore, commands in the C library which really do return nothing, here in ecasound.lua return not nil, but a zero-length string.

FUNCTIONS

Constructing and destructing

eci_init(): returns nothing
eci_ready(): returns an integer
eci_cleanup(): returns nothing

The Do-Everything Function

eci("commandstring")

eci("commandstring", 987.654)

There are about 200 available commands, see ECI COMMANDS below.

Some commands need a floating-point number as an argument, and this should go as a separate second argument, as in the second example, eg: eci("copp-set", 2805.7)

The return value has its natural Lua datatype, either a string, an array of strings, a number, a boolean, or nil. If the commandstring contains '-is-' then the return value is a boolean, not the integer as returned by the C library; this affects c-is-bypassed, c-is-muted, cop-is-bypassed and cs-is-valid.

eci() reports errors by returning nil, 'error-string' as is needed by the Lua assert() function. Therefore, commands in the C library which really do return nothing, here in ecasound.lua return not nil, but a zero-length string.

Events

eci_events_available(): Returns an integer, the number of events available.
eci_next_event(): Moves the ecasound engine on to the next event; returns nothing.
eci_current_event(): Returns a string.

DOWNLOAD

This module is available on https://luarocks.org/ so you should be able to install it with
luarocks install ecasound
or:
luarocks install http://www.pjb.com.au/comp/lua/ecasound-0.4-0.rockspec

If this results in an error message such as:
Error: Could not find expected file libecasound.a, or libecasound.so, or libecasound.so.* for ecasound -- you may have to install ecasound in your system and/or pass ECAS_DIR or ECAS_LIBDIR to the luarocks command. Example: luarocks install ecasound ECAS_DIR=/usr/local

then you need to find the appropriate directory with:
find /usr/lib -name 'libecasound.*' -print find /usr/local/lib -name 'libecasound.*' -print

and then invoke:
luarocks install \ http://www.pjb.com.au/comp/lua/ecasound-0.4-0.rockspec \ ECAS_LIBDIR=/usr/lib/i386-linux-gnu/ # or wherever

accordingly. You may also need to:
apt-get install ecasound ecasound-doc libecasoundc-dev

ECI COMMANDS

See also man ecasound-iam for more details
see man ecasound for the channel-operators as needed by cop-add
see listplugins for the LADPSA plugin names, and
see analyseplugin for details of their parameters.

This is a list of the ECI commands offered by my system (debian stable):

ai-add ai-attach ai-describe ai-forward ai-get-format ai-get-length ai-get-length-samples ai-get-position ai-get-position-samples ai-getpos ai-index-select ai-iselect ai-list ai-remove ai-rewind ai-select ai-selected ai-set-position ai-set-position-samples ai-setpos ai-status ai-wave-edit aio-register aio-status ao-add ao-add-default ao-attach ao-describe ao-forward ao-get-format ao-get-length ao-get-length-samples ao-get-position ao-get-position-samples ao-getpos ao-index-select ao-iselect ao-list ao-remove ao-rewind ao-select ao-selected ao-set-position ao-set-position-samples ao-setpos ao-status ao-wave-edit

c-add c-bypass c-clear c-deselect c-index-select c-is-bypassed c-is-muted c-iselect c-list c-mute c-muting c-remove c-rename c-select c-select-add c-select-all c-selected c-status cop-add cop-bypass cop-describe cop-get cop-index-select cop-is-bypassed cop-iselect cop-list cop-register cop-remove cop-select cop-selected cop-set cop-status copp-get copp-index-select copp-iselect copp-list copp-select copp-selected copp-set

cs cs-add cs-connect cs-connected cs-disconnect cs-edit cs-forward cs-get-length cs-get-length-samples cs-get-position cs-get-position-samples cs-getpos cs-index-select cs-is-valid cs-iselect cs-list cs-load cs-option cs-remove cs-rewind cs-save cs-save-as cs-select cs-selected cs-set-audio-format cs-set-length cs-set-length-samples cs-set-param cs-set-position cs-set-position-samples cs-setpos cs-status cs-toggle-loop

ctrl-add ctrl-describe ctrl-get-target ctrl-index-select ctrl-iselect ctrl-list ctrl-register ctrl-remove ctrl-select ctrl-selected ctrl-status ctrlp-get ctrlp-list ctrlp-select ctrlp-selected ctrlp-set debug dump-ai-length dump-ai-open-state dump-ai-position dump-ai-selected dump-ao-length dump-ao-open-state dump-ao-position dump-ao-selected dump-c-selected dump-cop-value dump-cs-status dump-length dump-position dump-status dump-target engine-halt engine-launch engine-status es forward fs fw get-length get-position getpos h help int-cmd-list int-log-history int-output-mode-wellformed int-set-float-to-string-precision int-set-log-history-length int-version-lib-age int-version-lib-current int-version-lib-revision int-version-string jack-connect jack-disconnect jack-list-connections ladspa-register lv2-register map-cop-list map-ctrl-list map-ladspa-id-list map-ladspa-list map-lv2-list map-preset-list preset-register q quit resource-file rewind run rw s set-position setpos st start status stop stop-sync t

CHANGES

   20170202  0.4  more robust test_ecasound
   20170201  0.3  various bug-fixes, and improved test_ecasound
   20170131       the eci commands containing '-is-' return boolean
   20170129  0.2  first working version
   20170129  0.1  placeholder only

AUTHOR

Peter J Billam, http://www.pjb.com.au/comp/contact.html