name => 'send_bus_cooked_input',
target => 'all',
chain_id => sub{ $_[0]->n },
input_type => 'loop',
input_object => sub{ my $track = shift;
my $source_track = $tn{$track->target};
'loop,'.$source_track->n},
condition => 1,
status => 1,
);
$sub_bus_mix_setup = Audio::Nama::Rule->new(
name => 'sub_bus_mix_setup',
chain_id => sub { my $track = shift; "J". $track->n },
target => 'all',
input_type => 'loop',
input_object => sub { my $track = shift; "loop," . $track->n },
output_type => 'loop',
output_object => sub{ my $track = shift; "loop,". $track->group },
condition => 1,
status => 1,
);
NAME
Audio::Nama - 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.
- -D
-
Output debugging information
- -f config_file
-
Use config_file instead of default .namarc
- -g
-
GUI mode (default)
- -t
-
Text-only mode
- -c
-
Create the specified project if necessary
- -a
-
Save and reload ALSA mixer state using alsactl
- -m
-
Don't load saved state
- -n
-
Communicate with engine via NetECI. Start Ecasound in server mode if necessary.
- -l
-
Communicate with engine via libecasoundc (default, if Audio::Ecasound is installed)
CONTROLLING NAMA/ECASOUND
Ecasound is configured through use of chain setups. Nama generates appropriate chain setups for recording, playback, mixing, mastering and bus routing.
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
Static commands affect future runs of the audio processing engine. For example, rec, mon and off determine whether the current track will get its audio stream from a live source or whether an existing WAV file will be played back. Nama responds to static commands by reconfiguring the engine as necessary by generating and loading chain setup files.
DYNAMIC COMMANDS
Once a chain setup is loaded and the engine launched, another subset of commands controls the realtime behavior of the audio processing engine. Commonly used dynamic commands include transport start
and stop
; playback head repositioning commands such forward
, rewind
and setpos
; and vol
and pan
for adjusting effect parameters. Effects can be added during audio processing, however this action may be accompanied by an audible click.
CONFIGURATION
General configuration of sound devices and program options is performed by editing the file .namarc. Nama automatically generates this well-commented file on the program's first run, usually placing it in the user's home directory.
DIAGNOSTICS
By inspecting the current chain setup with the chains
command, one can easily determine if the audio engine is properly configured. (It is much easier to read these setups than to write them!) The showio
command displays the data structure used to generate the chain setup. dump
displays data for the current track. The dumpall
command shows the state of most program objects and variables using the same format as 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.
Nama detects and uses plugin hints for parameter range and use of logarithmic scaling. Text-entry widgets are used to enter values for plugins without hinted ranges.
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 audio and loop devices, files, and signal-processing chains. Nama provides tracks, buses, marks and other high-level abstractions. Chief among these are tracks.
Each track has a descriptive name (i.e. vocal) and an integer track-number assigned when the track is created. The following paragraphs describes track fields and settings.
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 version setting, if present, overrides the group setting. Setting the track version to zero restores control of the version number to the group setting.
REC/MON/OFF
Track REC/MON/OFF status guides audio processing.
Each track, including Master and Mixdown, has its own REC/MON/OFF setting and displays its own REC/MON/OFF status. The Main group, which includes all user tracks, also has REC, MON and OFF settings that influence 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 a file with the selected version number. A track set to REC with no live input will 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 a track or group always results in OFF status, causing the track to be excluded from the chain setup. Note: This setting is distinct from the action of the mute
command, which sets the volume of the track to zero.
Newly created user tracks belong to the Main group, which goes through a mixer and Master fader track to the soundcard for monitoring.
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.
GROUPS
Track groups are used internally. The Main group corresponds to a mixer. It has its own REC/MON/OFF setting that influences the rec-status of individual tracks.
When the group is set to OFF, all tracks are OFF. When the group is set to MON, track REC settings are forced to MON. When the group is set to REC, tracks can be any of REC, MON or OFF. and a default version setting for the entire group. The
The group MON mode triggers automatically after a recording run.
The mixplay command sets the Mixdown track to MON and the Main group to OFF.
The Master bus has only MON/OFF status.
BUNCHES
A bunch is just a list of track names. Bunch names are used with for
to apply one or more commands to to several tracks at once. A group name can also be treated as a bunch name.
BUSES
Nama uses buses internally, and provides two kinds of user-defined buses.
Send buses can be used as instrument monitors, or to send pre- or post-fader signals from multiple user tracks to an external program such as jconv.
Sub buses enable multiple tracks to be routed through a single track for vol/pan/effects processing before reaching the mixer.
add_sub_bus Strings
add_tracks violin cello bass
for violin cello bass; set bus Strings
Strings vol - 10 # adjust bus output volume
ROUTING
Nama commands can address tracks by both a name and a number. In Ecasound chain setups, only the track number is used.
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 signal outputs. The following diagrams show the unoptimized routing.
Flow diagrams
Let's examine the signal flow from track 3, the first available user track. Assume track 3 is named "sax".
We will divide the signal flow into track and mixer sections. Parentheses indicate chain identifiers or the corresponding track name.
The stereo outputs of each user track terminate at loop,mix.
Track, REC status
Sound device --+---(3)----> loop,3 ---(J3)----> loop,mix
/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 special preview and doodle modes.
Track, MON status
sax_1.wav ------(3)----> loop,3 ----(J3)----> loop,mix
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 effects. Usually the Master track provides final control before audio output or mixdown.
loop,mix --(1/Master)--> loop,output -> Sound device
|
+----->(2/Mixdown)--> Mixdown_1.wav
During mastering, the mastering network is inserted between the Master track and the output node loop,output
.
loop,mix --(1/Master)-> loop,mastering-[NETWORK]->loop,output -> Sound device
|
+->(2/Mixdown)--> Mixdown_1.wa
Mastering Mode
In mastering mode (invoked by master_on
and released master_off
) the following network is used:
+---(Low)---+
| |
lp,mastering -(Eq)-> lp,crossover +---(Mid)---+ lp,boost --(Boost)--> lp,output
| |
+---(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 their 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 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
General commands
main_off - Turn off main output
main_off
main_on - Turn on main output
main_on
Track commands
add_track (add new) - Create a new track
add_track
<s_name> [ <s_key1> <s_val1> <s_key2> <s_val2>... ]
add_track clarinet group woodwinds
add_tracks (add new) - Create one or more new tracks
add_tracks
<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
Track: commands
slave_track (slave) - Create a read-only track that gets most of its settings from an existing track, used for instrument monitor buses
slave_track
name target
Track commands
import_audio (import) - Import a WAV file to the current track, resampling if necessary
import_audio
<s_wav_file_path> [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
rec_defeat (rd) - Toggle rec-defeat
rec_defeat
source (src r) - Set track source
source
<i_soundcard_channel> | <s_jack_client_name>
send (out aux m) - Set auxilary track destination
send
<i_soundcard_channel> (3 or above) | <s_jack_client_name>
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_tracks (autofix) - Fixdc and normalize selected versions of all MON tracks
autofix_tracks
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)
set multiple effects/parameters: mfx V 1,2,3 + 0.5 mfx V,AC,AD 1,2 3.14
remove_effect (fxr rfx) - Remove effects from selected track
remove_effect
<s_effect_id1> [ <s_effect_id2>...]
add_insert_cooked (ainc) - Add a post-fader send/return to a track
add_insert_cooked
<s_send_id> [<s_return_id>]
set_insert_wetness (wet) - Set wet/dry balance for track insert: 100 = all wet, 0 = all dry
set_insert_wetness
<n_wetness>
remove_insert (rin) - Remove a track's insert
remove_insert
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
Help commands
list_history (lh) - List command history
list_history
Bus commands
add_send_bus_cooked (asbc) - Add a send bus that copies all user tracks' processed signals
add_send_bus_cooked
<s_name> <destination>
asbc jconv
add_send_bus_raw (asbr) - Add a send bus that copies all user tracks' raw signals
add_send_bus_raw
<s_name> <destination>
asbr The_new_bus jconv
add_sub_bus (asub) - Add a bus with arbitrary tracks and destination
add_sub_bus
<s_name> [destination]
asub Strings_bus
asub Strings_bus streamer_app
update_send_bus (usb) - Include tracks added since send bus was created
update_send_bus
<s_name>
usb Some_bus
Track commands
add_slave_track (ast) - Add a slave track to an existing user bus
add_slave_track
<s_bus_name> <s_target_track_name>
Bus commands
remove_bus (rmb) - Remove a bus
remove_bus
<s_bus_name>
BUGS AND LIMITATIONS
No waveform or signal level displays are provided. No latency compensation is provided across the various signal paths, although this function is under development.
SECURITY CONCERNS
If you are using Nama with the NetECI interface (i.e. if Audio::Ecasound is not installed) you should firewall TCP port 2868 if you computer is exposed to the Internet.
EXPORT
None by default.
AVAILABILITY
CPAN, for the distribution.
cpan Audio::Nama
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.
PATCHES
The main module, Nama.pm is a concatenation of several source files. Patches should be made against the source files.
AUTHOR
Joel Roth, <joelz@pobox.com>
2 POD Errors
The following errors were encountered while parsing the POD:
- Around line 1385:
Unknown directive: =comment
- Around line 10405:
Unterminated C<...> sequence