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, );
Audio::Nama - Perl extensions for multitrack audio processing
Nama - Lightweight recorder, mixer and mastering system
nama [options] [project_name]
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.
Use project_root as Nama's top-level directory.
Output debugging information
Use config_file instead of default .namarc
GUI mode (default)
Text-only mode
Create the specified project if necessary
Save and reload ALSA mixer state using alsactl
Don't load saved state
Communicate with engine via NetECI. Start Ecasound in server mode if necessary.
Communicate with engine via libecasoundc (default, if Audio::Ecasound is installed)
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 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.
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.
start
stop
forward
rewind
setpos
vol
pan
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.
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.
chains
showio
dump
dumpall
save
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.
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 settings.
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.
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, then assemble them using link_track to pull the Mixdown tracks into a single project.
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.
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.
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 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 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.
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.
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.
sax_1.wav ------(3)----> loop,3 ----(J3)----> loop,mix
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,output
loop,mix --(1/Master)-> loop,mastering-[NETWORK]->loop,output -> Sound device | +->(2/Mixdown)--> Mixdown_1.wa
In mastering mode (invoked by master_on and released master_off) the following network is used:
master_on
master_off
+---(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.
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)
setpos 65
forward <f_increment_seconds>
rewind <f_increment_seconds>
to_start
to_end
ecasound_start
ecasound_stop
mixdown
mixplay
mixoff
automix
main_off
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
slave_track name target
slave_track
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>
source
send <i_soundcard_channel> (3 or above) | <s_jack_client_name>
send
stereo
mono
set_version <i_version_number>
set_version
sax; version 5; sh
destroy_current_wav
list_versions
vol [ [ + | - | * | / ] <f_value> ]
vol * 1.5 (multiply current volume setting by 1.5)
vol * 1.5
unmute
unity
solo
all
pan [ <f_value> ]
pan_right
pan_left
pan_center
pan_back
show_tracks
show_track
region <s_start_mark_name> <s_end_mark_name>
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
bunch [ <s_group_name> [track1] [track2...] ]
bunch
list_bunches
remove_bunches <s_bunch_name> [<s_bunch_name>...]
remove_bunches
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 10.0
loop_enable 1 5 (loop between mark indices 1 and 5)
loop_enable 1 5
loop_enable start end (loop between mark ids 'start' and 'end')
loop_enable start end
loop_disable
add_ctrl <s_parent_id> <s_effect_code> [ <f_param1> <f_param2>...]
add_ctrl
add_effect <s_effect_code> [ <f_param1> <f_param2>... ]
add_effect
add_effect amp 6 (LADSPA Simple amp 6dB gain)
add_effect amp 6
add_effect var_dali (preset var_dali) Note: no el: or pn: prefix is required
add_effect var_dali
append_effect <s_effect_code> [ <f_param1> <f_param2>... ]
append_effect
insert_effect <s_insert_point_id> <s_effect_code> [ <f_param1> <f_param2>... ]
insert_effect
modify_effect <s_effect_id> <i_parameter> [ + | - | * | / ] <f_value>
modify_effect
modify_effect V 1 1000 (set effect_id V, parameter 1 to 1000)
modify_effect V 1 1000
modify_effect V 1 - 10 (reduce effect_id V, parameter 1 by 10)
modify_effect V 1 - 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>]
add_insert_cooked
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')
to_mark start
mark [ <s_mark_id> ]
mark
remove_mark [ <s_mark_id> | <i_mark_index> ]
remove_mark
remove_mark start (remove mark named 'start')
remove_mark 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]
add_sub_bus
asub Strings_bus
asub Strings_bus streamer_app
update_send_bus <s_name>
update_send_bus
usb Some_bus
add_slave_track <s_bus_name> <s_target_track_name>
add_slave_track
remove_bus <s_bus_name>
remove_bus
No waveform or signal level displays are provided. No latency compensation is provided across the various signal paths, although this function is under development.
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.
None by default.
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.
The main module, Nama.pm is a concatenation of several source files. Patches should be made against the source files.
Joel Roth, <joelz@pobox.com>
2 POD Errors
The following errors were encountered while parsing the POD:
Unknown directive: =comment
Unterminated C<...> sequence
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.