NAME

Audio::Ecasound::Multitrack - Perl extensions for multitrack audio processing

Nama - Lightweight recorder, mixer and mastering system

SYNOPSIS

nama [options] [project_name]

DESCRIPTION

Nama is a lightweight recorder/mixer application using Ecasound in the back end to provide effects processing, cut-and-paste, mastering, and other functions typically found in digital audio workstations.

By default, Nama starts up a GUI interface with a command line interface running in the terminal window. The -t option provides a text-only interface for console users.

OPTIONS

-d project_root

Use project_root as Nama's top-level directory.

-f config_file

Use config_file instead of default .namarc

-g

GUI/text mode (default)

-t

Text-only mode

-c

Create the named project

-a

Save and reload ALSA mixer state using alsactl

-m

Don't load saved state

CONTROLLING ECASOUND

Ecasound is configured through use of chain setups. Chain setups are central to controlling Ecasound. Nama generates appropriate chain setups for recording, playback, and mixing covering a large portion of Ecasound's functionality.

Commands for audio processing with Nama/Ecasound fall into two categories: static commands that influence the chain setup and dynamic commands that influence the realtime behavior of the audio processing engine.

STATIC COMMANDS

The rec, mon and B <off> commands are examples of static commands. They influence whether the current track will get its audio stream from a live source (soundcard or JACK client) and store its as a WAV file, for whether an existing file will be played back. Other static commands include loop_enable and the stereo/mono commands which specify the width of a track's signal source. Like a spreadsheet recalculating, Nama automatically detects when static commands require that Ecasound be reconfigured with a new chain setup.

DYNAMIC COMMANDS

Once a chain setup is loaded and the engine launched, another subset of commands controls the audio processing engine. Commonly used dynamic commands include start and stop; forward, rewind and setpos commands for repositioning the playback head; and vol and pan for adjusting effect parameters. Effect parameters may be adjusted at any time. Effects may be added during audio processing.

DIAGNOSTICS

The current chain setup may be inspected with the chains command. The showio command displays the data structure used to generate the chain setup. dump displays data for the current track. dumpall shows the state of most program objects and variables (identical to the State.yml file created by the save command.)

Tk GRAPHICAL UI

Invoked by default, the Tk interface provides all functionality on two panels, one for general control, the second for effects.

Many plugins include hinting data, which is used to set parameter range and to provide logarithmic sliders for such parameters as frequency.

The GUI provides text-entry widgets to specify parameters for plugins without hinting.

The GUI project name bar and time display change color to indicate whether the upcoming operation will include live recording (red), mixdown only (yellow) or playback only (green). Live recording and mixdown can take place simultaneously.

The text command prompt appears in the terminal window during GUI operation, and text commands may be issued at any time.

TEXT UI

Press the Enter key if necessary to get the following command prompt.

nama ('h' for help)>

You can enter Nama and Ecasound commands directly, Perl code preceded by eval or shell code preceded by !.

Multiple commands on a single line are allowed if delimited by semicolons. Usually the lines are split on semicolons and the parts are executed sequentially, however if the line begins with eval or ! the entire line will be given to the corresponding interpreter.

You can access command history using up-arrow/down-arrow.

Type help for general help, help command for help with command, help foo for help with commands containing the string foo. help_effect foo bar lists all plugins/presets/controller containing both foo and bar. Tab-completion is provided for Nama commands, Ecasound-iam commands, plugin/preset/controller names, and project names.

TRACKS

Ecasound deals with audio processing at the level of devices, files, and signal-processing chains. Nama implements tracks to provide a level of control and convenience comparable to many digital audio workstations.

Each track has a descriptive name (i.e. vocal) and an integer track-number assigned when the track is created.

VERSION NUMBER

Multiple WAV files can be recorded for each track. These are identified by a version number that increments with each recording run, i.e. sax_1.wav, sax_2.wav, etc. All files recorded at the same time have the same version numbers.

Version numbers for playback can be selected at the group or track level. By setting the group version number to 5, you can play back the fifth take of a song, or perhaps the fifth song of a live recording session.

The track's version setting, if present, overrides the group setting. Setting the track version to zero restores control of the version number to the default group setting.

REC/MON/OFF

REC/MON/OFF status is used to generate the chain setup for an audio processing run.

Each track, including Master and Mixdown, has its own REC/MON/OFF setting and displays its own REC/MON/OFF status. The Tracker group, which includes all user tracks, also has REC, MON and OFF settings. These provides a convenient way to control the behavior of all user tracks.

As the name suggests, REC status indicates that a track is ready to record a WAV file. You need to set both track and group to REC to source an audio stream from JACK or the soundcard.

MON status indicates an audio stream available from disk. It requires a MON setting for the track or group as well as the presence of file with the selected version number. A track set to REC with no audio stream available with default to MON status.

OFF status means that no audio is available for the track from any source. A track with no recorded WAV files will show OFF status, even if set to MON.

An OFF setting for the track or group always results in OFF status. A track with OFF status will be excluded from the chain setup. (This setting is distinct from the action of the mute command, which sets the volume of the track to zero.)

All user tracks belong to the Tracker group, which has a group REC/MON/OFF setting and a default version setting for the entire group.

Setting the group to MON (group_monitor or gmon) forces user tracks with a REC setting to MON status if a WAV file is available to play, or OFF status if no audio stream is available.

The group MON mode triggers automatically after a recording has created new WAV files.

The group OFF setting (text command group_off) excludes all user tracks from the chain setup, and is typically used when playing back mixdown tracks. The mixplay command sets the Mixdown track to MON and the Tracker group to OFF.

The Master bus has only MON/OFF status. Setting REC status for the Mixdown bus has the same effect as issuing the mixdown command. (A start command must be issued for mixdown to commence.)

REGIONS

The region command allows you to define endpoints for a portion of an audio file. Use the shift command to specify a delay for starting playback.

Only one region may be specified per track. Use the link_track command to clone a track in order to make use of multiple regions or versions of a single track.

link_track can clone tracks from other projects. Thus you could create the sections of a song in separate projects, then assemble them using link_track to pull the Mixdown tracks into a single project for mastering.

ROUTING

Nama identifies tracks by both a name and a number. The track number is used to identify corresponding Ecasound signal-processing chains.

Raw, cooked and mixed signals

Nama's signal flow is organized at three levels: raw, cooked and mixed.

"Raw" signals are the inputs to user tracks. Raw signals can come from the soundcard, a WAV file, or a JACK client.

"Cooked" signals are the output of user tracks after volume, pan and effects processing.

The "mixed" signal is the combined outputs of all user tracks. It is delivered to the Master fader, and to the Mixdown WAV file during mixdown.

Loop devices

Nama uses Ecasound loop devices to be able to deliver each of these signals classes to multiple "customers", i.e. to other chains using that signal as input.

An optimizing pass eliminates loop devices that have only one customer for the signal they provide.

Flow diagrams

Let's examine the signal flow from track 3, the first available user track. Assume track 3 is named "sax". All effects for track 3 are applied to chain 3.

We will divide the signal flow into track and mixer sections. Parentheses indicate chain identifiers or the corresponding track name.

All "cooked" signals (i.e. the outputs of each user track) terminate at loop,111.

Track, REC status

Sound device   --+---(3)----> loop,3 ---(J3)----> loop,111
  /JACK client   |
                 +---(R3)---> sax_1.wav

REC status indicates that the source of the signal is the soundcard or JACK client. The input signal will be written directly to a file except in the preview and doodle modes.

Track, MON status

sax_1.wav ------(3)----> loop,3 ----(J3)----> loop,111

Mixer, with mixdown enabled

In the second part of the flow graph, the mixed signal is delivered to an output device through the Master chain, which can host additional effects. The Mixdown track can also host effects, however these should be used during playback only.

loop,111 --(MixLink)---> loop,222 --(1/Master)---> Sound device
                             |
                             +------(2/Mixdown)--> Mixdown_1.wav

Mastering Mode

In mastering mode (invoked by master_on and released master_off) the MixLink chain is replaced by several tracks with mastering-related effects.

                             +---(Low)---+ 
                             |           |
loop,111 --(Eq)--> loop,120 -+---(Mid)---+ loop,130 --(Boost)--> loop,222
                             |           |
                             +---(High)--+ 

The Eq track hosts an equalizer.

The Low, Mid and High tracks each apply a bandpass filter, a compressor and a spatialiser.

The Boost track applies gain and a limiter.

These effects (and optional default parameters) are defined in the configuration file .namarc.

Preview and Doodle Modes

These non-recording modes, invoked by preview and doodle commands tweak the routing rules for special purposes. Preview mode simply disables recording of WAV files to disk. Doodle mode disables MON inputs while enabling only one REC track per signal source. The arm command releases both preview and doodle modes.

TEXT COMMANDS

Help commands

help (h) - Display help

help [ <i_help_topic_index> | <s_help_topic_name> | <s_command_name> ]

help_effect (hfx he) - Display analyseplugin output if available or one-line help

help_effect <s_label> | <i_unique_id>

find_effect (ffx fe) - Display one-line help for effects matching search strings

find_effect <s_keyword1> [ <s_keyword2>... ]

General commands

exit (quit q) - Exit program, saving settings

exit

memoize - Enable WAV dir cache

memoize

unmemoize - Disable WAV dir cache

unmemoize

Transport commands

stop (s) - Stop transport

stop

start (t) - Start transport

start

getpos (gp) - Get current playhead position (seconds)

getpos

setpos (sp) - Set current playhead position

setpos <f_position_seconds>

setpos 65 (set play position to 65 seconds from start)

forward (fw) - Move playback position forward

forward <f_increment_seconds>

rewind (rw) - Move transport position backward

rewind <f_increment_seconds>

to_start (beg) - Set playback head to start

to_start

to_end (end) - Set playback head to end minus 10 seconds

to_end

ecasound_start (T) - Ecasound-only start

ecasound_start

ecasound_stop (S) - Ecasound-only stop

ecasound_stop

preview - Start engine with rec_file disabled (for mic test, etc.)

preview

doodle - Start engine while monitoring REC-enabled inputs

doodle

Mix commands

mixdown (mxd) - Enable mixdown for subsequent engine runs

mixdown

mixplay (mxp) - Enable mixdown file playback, setting user tracks to OFF

mixplay

mixoff (mxo) - Set Mixdown track to OFF, user tracks to MON

mixoff

automix - Normalize track vol levels, then mixdown

automix

master_on (mr) - Enter mastering mode. Add tracks Eq, Low, Mid, High and Boost if necessary

master_on

master_off (mro) - Leave mastering mode

master_off

Track commands

add_track (add new) - Create one or more new tracks

add_track <s_name1> [ <s_name2>... ]

add_track sax violin tuba

link_track (link) - Create a read-only track that uses .WAV files from another track.

link_track <s_name> <s_target> [ <s_project> ]

link_track intro Mixdown song_intro creates a track 'intro' using all .WAV versions from the Mixdown track of 'song_intro' project

import_audio (import) - Import a WAV file, resampling if necessary

import_audio <s_wav_file> [i_frequency]

set_track (set) - Directly set current track parameters (use with care!)

set_track <s_track_field> value

rec - REC-enable current track

rec

mon - Set current track to MON

mon

off (z) - Set current track to OFF (exclude from chain setup)

off

source (src r) - Set track source

source <s_jack_client_name> | <i_soundcard_channel>

send (out aux m) - Set auxilary track destination

send <s_jack_client_name> | <i_soundcard_channel> (3 or above)

stereo - Record two channels for current track

stereo

mono - Record one channel for current track

mono

set_version (version n ver) - Set track version number for monitoring (overrides group version setting)

set_version <i_version_number>

sax; version 5; sh

destroy_current_wav - Unlink current track's selected WAV version (use with care!)

destroy_current_wav

list_versions (lver lv) - List version numbers of current track

list_versions

vol (v) - Set, modify or show current track volume

vol [ [ + | - | * | / ] <f_value> ]

vol * 1.5 (multiply current volume setting by 1.5)

mute (c cut) - Mute current track volume

mute

unmute (C uncut) - Restore previous volume level

unmute

unity - Set current track volume to unity

unity

solo - Mute all but current track

solo

all (nosolo) - Unmute tracks after solo

all

pan (p) - Get/set current track pan position

pan [ <f_value> ]

pan_right (pr) - Pan current track fully right

pan_right

pan_left (pl) - Pan current track fully left

pan_left

pan_center (pc) - Set pan center

pan_center

pan_back (pb) - Restore current track pan setting prior to pan_left, pan_right or pan_center

pan_back

show_tracks (show tracks) - Show status of all tracks

show_tracks

show_track (sh) - Show current track status

show_track

region - Specify a track region for playback using marks. Nama allows one region per track.

region <s_start_mark_name> <s_end_mark_name>

remove_region (rmr) - Remove region definition. Entire track plays back.

remove_region

shift_track (shift) - Set playback delay for track/region

shift_track <s_start_mark_name> | <i_start_mark_index | <f_start_seconds>

unshift_track (unshift) - Remove playback delay for track/region

unshift_track

modifiers (mods mod) - Set/show modifiers for current track (man ecasound for details)

modifiers [ Audio file sequencing parameters ]

modifiers select 5 15.2

nomodifiers (nomods nomod) - Remove modifiers from current track

nomodifiers

normalize (norm ecanormalize) - Apply ecanormalize to current track version

normalize

fixdc (ecafixdc) - Apply ecafixdc to current track version

fixdc

autofix_track (autofix) - Fixdc and normalize selected versions of all MON tracks

autofix_track

remove_track (rmt) - Remove effects, parameters and GUI for current track

remove_track

Group commands

group_rec (grec R) - Rec-enable user tracks

group_rec

group_mon (gmon M) - Rec-disable user tracks

group_mon

group_version (gn gver gv) - Set group version for monitoring (overridden by track-version settings)

group_version

group_off (goff Z) - Group OFF mode, exclude all user tracks from chain setup

group_off

bunch (bn) - Define/list groups of tracks

bunch [ <s_group_name> [track1] [track2...] ]

list_bunches (lb) - List groups of tracks (bunches)

list_bunches

remove_bunches (rb) - Remove alias for group(s) of tracks (bunches)

remove_bunches <s_bunch_name> [<s_bunch_name>...]

Project commands

save_state (keep save) - Save project settings to disk

save_state [ <s_settings_file> ]

get_state (recall restore retrieve) - Retrieve project settings

get_state [ <s_settings_file> ]

list_projects (lp) - List projects

list_projects

create_project (create) - Create a new project

create_project <s_new_project_name>

load_project (load) - Load an existing project using last saved state

load_project <s_project_name>

project_name (project name) - Show current project name

project_name

Setup commands

generate (gen) - Generate chain setup for audio processing

generate

arm - Generate and connect chain setup

arm

connect (con) - Connect chain setup

connect

disconnect (dcon) - Disconnect chain setup

disconnect

show_chain_setup (chains) - Show current Ecasound chain setup

show_chain_setup

loop_enable (loop) - Loop playback between two points

loop_enable <start> <end> (start, end: mark names, mark indices, decimal seconds)

loop_enable 1.5 10.0 (loop between 1.5 and 10.0 seconds)

loop_enable 1 5 (loop between mark indices 1 and 5)

loop_enable start end (loop between mark ids 'start' and 'end')

loop_disable (noloop nl) - Disable automatic looping

loop_disable

Effect commands

add_ctrl (acl cla) - Add a controller to an operator

add_ctrl <s_parent_id> <s_effect_code> [ <f_param1> <f_param2>...]

add_effect (fxa afx) - Add effect to current track (placed before volume control)

add_effect <s_effect_code> [ <f_param1> <f_param2>... ]

add_effect amp 6 (LADSPA Simple amp 6dB gain)

add_effect var_dali (preset var_dali) Note: no el: or pn: prefix is required

append_effect - Add effect to the end of current track (mainly legacy use)

append_effect <s_effect_code> [ <f_param1> <f_param2>... ]

insert_effect (ifx fxi) - Place effect before specified effect (engine stopped, prior to arm only)

insert_effect <s_insert_point_id> <s_effect_code> [ <f_param1> <f_param2>... ]

modify_effect (fxm mfx) - Modify an effect parameter

modify_effect <s_effect_id> <i_parameter> [ + | - | * | / ] <f_value>

modify_effect V 1 1000 (set effect_id V, parameter 1 to 1000)

modify_effect V 1 - 10 (reduce effect_id V, parameter 1 by 10)

remove_effect (fxr rfx) - Remove effects from selected track

remove_effect <s_effect_id1> [ <s_effect_id2>...]

ctrl_register (crg) - List Ecasound controllers

ctrl_register

preset_register (prg) - List Ecasound presets

preset_register

ladspa_register (lrg) - List LADSPA plugins

ladspa_register

Mark commands

list_marks (lm) - List all marks

list_marks

to_mark (tom) - Move playhead to named mark or mark index

to_mark <s_mark_id> | <i_mark_index>

to_mark start (go to mark named 'start')

mark (k) - Drop mark at current playback position

mark [ <s_mark_id> ]

remove_mark (rmm) - Remove mark, default to current mark

remove_mark [ <s_mark_id> | <i_mark_index> ]

remove_mark start (remove mark named 'start')

next_mark (nm) - Move playback head to next mark

next_mark

previous_mark (pm) - Move playback head to previous mark

previous_mark

name_mark (nmk nom) - Give a name to the current mark

name_mark <s_mark_id>

name_mark start

modify_mark (move_mark mm) - Change the time setting of current mark

modify_mark [ + | - ] <f_seconds>

Diagnostics commands

engine_status (egs) - Display Ecasound audio processing engine status

engine_status

dump_track (dumpt dump) - Dump current track data

dump_track

dump_group (dumpgroup dumpg) - Dump group settings for user tracks

dump_group

dump_all (dumpall dumpa) - Dump most internal state

dump_all

show_io (showio) - Show chain inputs and outputs

show_io

BUGS AND LIMITATIONS

Text commands are required to invoke preview and mastering modes, and to define and shift track regions.

Compensation for LADSPA plugin latencies and ADC and buffering delays during multitrack recording is not fully implemented.

The default GUI colors aren't great.

No waveform display.

PATCHES

The main module, Multitrack.pm is a concatenation of several source files. Patches should be made against the source files (see below.)

EXPORT

None by default.

AVAILABILITY

CPAN, for the distribution.

cpan Audio::Ecasound::Multitrack

You will need to install Tk to use the GUI.

cpan Tk

You can pull the source code as follows:

git clone git://github.com/bolangi/nama.git

Build instructions are contained in the README file.

AUTHOR

Joel Roth, <joelz@pobox.com>

cpanm Audio::Ecasound::Multitrack

perl -MCPAN -e shell
install Audio::Ecasound::Multitrack