Nama - Ecasound-based recorder, mixer and mastering system
nama [options] [project_name]
Nama is a recorder/mixer application using Ecasound in the back end to provide multitrack recording, effects processing, and mastering. Nama includes aux sends, inserts, buses, regions and time-shifting functions. Full help is provided, including commands by category, search for commands or effects by name or by arbitrary string.
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.
Start Nama in GUI mode
Start Nama in text mode
Specify configuration file (default: ~/.namarc)
Specify project root directory
Create project if it doesn't exist
Use Ecasound's Net-ECI interface
Use Ecasound's libecasoundc interface
Save/restore alsa state with project data
This help display
Debugging options:
Don't load effects data
Don't load project state
Bypass effects data cache
Regenerate the effects data cache
Don't automatically configure engine
Emit debugging information
Simulate JACK environment
Simulate ALSA environment
Don't spawn Ecasound process
Supply a command to execute
Ecasound is configured through use of chain setups. Nama serves as intermediary generating appropriate chain setups for recording, playback, mixing, etc. and running the audio processing engine according to user commands.
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 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 and displaying the updated track status in text and GUI form.
Once a chain setup is loaded and the engine is 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. Effects may be added, modified or removed while the engine is running.
start
stop
forward
rewind
setpos
General configuration of sound devices and program options is performed by editing the .namarc file. On Nama's first run, a default version of .namarc is usually placed in the user's home directory.
Invoked by default if Tk is installed, this interface provides a large subset of Nama's functionality on two panels, one for general control, the second for effects.
The general panel has buttons for project create, load and save, for adding tracks and effects, and for setting the vol, pan and record status of each track.
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 effects window provides sliders for each effect parameters. Parameter range, defaults, and log/linear scaling hints are automatically detects. Text-entry widgets are used to enter parameters values for plugins without hinted ranges.
The text command prompt appears in the terminal window during GUI operation. Text commands may be issued at any time.
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 !.
eval
!
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.
help
help command
command
help foo
foo
help_effect foo bar
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 their settings.
Specifying 'mono' means one-channel input and recording the raw signal as a mono WAV file. The mono signal is duplicated to a stereo signal with pan in the default mixer configuration.
Specifying 'stereo' means two-channel input with recording as a stereo WAV file.
Specifying N channels ('set width N') means N-channel input with recording as an N-channel WAV file.
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.
The version numbers of files 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.
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.
mute
Newly created user tracks belong to the Main group, which goes through a mixer and Master fader track to the soundcard for monitoring.
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.
region
shift
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
link_track can clone tracks from other projects. Thus you could create the sections of a song in separate projects, pull them into one project using link_track commands, and sequence them using shift commands.
Each track gets volume and pan effects by default. New effects added using add_effect are applied after pan and before volume. You can position effects anywhere you choose using insert_effect and append_effect.
add_effect
insert_effect
append_effect
The send command can routes a track's post-fader output to a soundcard channel or JACK client in addition to the normal mixer input. Nama currently allows one aux send per track.
send
The add_insert_cooked command configures a post-fader send-and-return to soundcard channels or JACK clients. Wet and dry signal paths are provided, with a default setting of 100% wet.
add_insert_cooked
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.
Setting a group to OFF forces all of the group's tracks to OFF. When the group is set to MON, track REC settings are forced to MON. When the group is set to REC, track status can be REC, MON or OFF.
The group MON mode triggers automatically after a successful recording run.
The mixplay command sets the Mixdown track to MON and the Main group to OFF.
A bunch is just a list of track names. Bunch names are used with the keyword for to apply one or more commands to to several tracks at once. A group name can also be treated as a bunch name.
for
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 (currently broken) 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
Nama commands can address tracks by both a name and a number. In Ecasound chain setups, only the track number is used.
Nama uses Ecasound loop devices to join two tracks, or to allow one track to have multiple inputs or outputs.
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 Master_in, a loop device at the mixer input.
Sound device --+---(3)----> Master_in /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.
sax_1.wav ------(3)----> Master_in
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.
Master_in --(1/Master)--> Master_out -> Sound device | +----->(2/Mixdown)--> Mixdown_1.wav
During mastering, the mastering network is inserted between the Master track, and the audio/mixdown output.
In mastering mode (invoked by master_on and released master_off) the following network is used:
master_on
master_off
+-(Low)-+ | | Eq-in -(Eq)-> Eq_out -+-(Mid)-+- Boost_in -(Boost)-> soundcard/wav_out | | +-(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.
The mixdown command configures Nama for mixdown. The Mixdown track is set to REC (equivalent to Mixdown rec) and the audio monitoring output is turned off (equivalent to main_off).
mixdown
Mixdown rec
main_off
Mixdown proceeds after you enter the start command.
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.
preview
doodle
arm
help [ <i_help_topic_index> | <s_help_topic_name> | <s_command_name> ]
help_effect <s_label> | <i_unique_id>
help_effect
find_effect <s_keyword1> [ <s_keyword2>... ]
find_effect
exit
memoize
unmemoize
getpos
setpos <f_position_seconds>
setpos 65 (set play position to 65 seconds from start)
forward <f_increment_seconds>
rewind <f_increment_seconds>
to_start
to_end
ecasound_start
ecasound_stop
mixplay
mixoff
automix
main_on
add_track <s_name> [ <s_key1> <s_val1> <s_key2> <s_val2>... ]
add_track
add_track clarinet group woodwinds
add_tracks <s_name1> [ <s_name2>... ]
add_tracks
add_track sax violin tuba
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 <s_wav_file_path> [i_frequency]
import_audio
set_track <s_track_field> value
set_track
rec
mon
off
rec_defeat
source <i_soundcard_channel> | <s_jack_client_name> | 'jack' (opens ports ecasound:trackname_in_N, connects ports listed in trackname.ports if present in project_root dir)
source
send <i_soundcard_channel> (3 or above) | <s_jack_client_name>
remove_send none what: set auxilary track destination
remove_send
stereo
mono
set_version <i_version_number>
set_version
sax; version 5; sh
destroy_current_wav
list_versions
vol [ [ + | - | * | / ] <f_value> ]
vol
vol * 1.5 (multiply current volume setting by 1.5)
unmute
unity
solo
all
pan [ <f_value> ]
pan
pan_right
pan_left
pan_center
pan_back
show_tracks
show_track
show_mode
set_region <s_start_mark_name> <s_end_mark_name>
set_region
new_region <s_start_mark_name> <s_end_mark_name> [<s_region_name>]
new_region
remove_region
shift_track <s_start_mark_name> | <i_start_mark_index | <f_start_seconds>
shift_track
unshift_track
modifiers [ Audio file sequencing parameters ]
modifiers
modifiers select 5 15.2
nomodifiers
normalize
fixdc
autofix_tracks
remove_track
group_rec
group_mon
group_version
group_off
new_bunch <s_group_name> [<s_track1> <s_track2>...]
new_bunch
list_bunches
remove_bunches <s_bunch_name> [<s_bunch_name>...]
remove_bunches
add_to_bunch <s_bunch_name> <s_track1> [<s_track2>...]
add_to_bunch
save_state [ <s_settings_file> ]
save_state
get_state [ <s_settings_file> ]
get_state
list_projects
create_project <s_new_project_name>
create_project
load_project <s_project_name>
load_project
project_name
generate
connect
disconnect
show_chain_setup
loop_enable <start> <end> (start, end: mark names, mark indices, decimal seconds)
loop_enable
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
add_controller <s_parent_id> <s_effect_code> [ <f_param1> <f_param2>...]
add_controller
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 <s_effect_code> [ <f_param1> <f_param2>... ]
insert_effect <s_insert_point_id> <s_effect_code> [ <f_param1> <f_param2>... ]
modify_effect <s_effect_id> <i_parameter> [ + | - | * | / ] <f_value>
modify_effect
modify_effect V 1 -1 (set effect_id V, parameter 1 to -1)
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 <s_effect_id1> [ <s_effect_id2>...]
remove_effect
add_insert_cooked <s_send_id> [<s_return_id>]
set_insert_wetness <n_wetness>
set_insert_wetness
remove_insert
ctrl_register
preset_register
ladspa_register
list_marks
to_mark <s_mark_id> | <i_mark_index>
to_mark
to_mark start (go to mark named 'start')
new_mark [ <s_mark_id> ]
new_mark
remove_mark [ <s_mark_id> | <i_mark_index> ]
remove_mark
remove_mark start (remove mark named 'start')
next_mark
previous_mark
name_mark <s_mark_id>
name_mark
name_mark start
modify_mark [ + | - ] <f_seconds>
modify_mark
engine_status
dump_track
dump_group
dump_all
show_io
list_history
add_send_bus_cooked <s_name> <destination>
add_send_bus_cooked
asbc jconv
add_send_bus_raw <s_name> <destination>
add_send_bus_raw
asbr The_new_bus jconv
add_sub_bus <s_name> [destination: s_track_name|s_jack_client|n_soundcard channel]
add_sub_bus
asub Strings_bus
asub Strings_bus some_jack_client
update_send_bus <s_name>
update_send_bus
usb Some_bus
remove_bus <s_bus_name>
remove_bus
list_buses
set_bus
new_effect_chain <s_name> [<op1>, <op2>,...]
new_effect_chain
add_effect_chain <s_name>
add_effect_chain
overwrite_effect_chain <s_name>
overwrite_effect_chain
delete_effect_chain <s_name>
delete_effect_chain
list_effect_chains [<s_frag1> <s_frag2>... ]
list_effect_chains
bypass_effects
restore_effects
new_effect_profile <s_bunch_name> [<s_effect_profile_name>]
new_effect_profile
apply_effect_profile <s_effect_profile_name>
apply_effect_profile
overlay_effect_profile <s_effect_profile_name>
overlay_effect_profile
delete_effect_profile <s_effect_profile_name>
delete_effect_profile
list_effect_profiles
cache_track
uncache_track
do_script <s_filename>
do_script
scan
In most situations, the GUI display and the output of the show_tracks command (executed automatically on any change in setup) show what to expect the next time the engine is started.
Additionally, Nama has a number of diagnostic functions that can help resolve problems without resorting to the debugging flag (and wading through its prolific output.) The chains command displays the current chain setup to determine if Ecasound is properly configured for the task at hand. (It is much easier to read these setups than to write them!)
chains
The dump command displays data for the current track. The dumpall command shows all state that would be saved. This is the same output that is written to the State.yml file when you issue the save command.
dump
dumpall
save
No waveform or signal level displays are provided.
No latency compensation across signal paths is provided at present, although this feature is planned.
If you are using Nama with the NetECI interface (i.e. if Audio::Ecasound is not installed) you should block TCP port 2868 if you computer is exposed to the Internet.
The following command, available on Unixlike systems with Perl installed, will pull in Nama and other Perl libraries required for text mode operation:
PERL_MM_USE_DEFAULT=1 cpan Audio::Nama
To use the GUI, you will need to install Tk:
cpan Tk
You may want to install Audio::Ecasound if you prefer not to run Ecasound in server mode:
cpan Audio::Ecasound
You can pull the source code as follows:
git clone git://github.com/bolangi/nama.git
Consult the BUILD file for build instructions.
The Ecasound mailing list is a suitable forum for questions regarding Nama installation, usage, feature requests, etc., as well as questions relating to Ecasound itself.
https://lists.sourceforge.net/lists/listinfo/ecasound-list
The main module, Nama.pm, its sister modules are concatenations of several source files. Patches against the source files are preferred.
Joel Roth, <joelz@pobox.com>
To install Audio::Nama, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Audio::Nama
CPAN shell
perl -MCPAN -e shell install Audio::Nama
For more information on module installation, please visit the detailed CPAN module installation guide.