#!/usr/bin/env perl
require 5.10.1;
use Audio::Nama;
Audio::Nama::main();
__END__
=head1 NAME
B<Nama> - digital audio workstation
=head1 SYNOPSIS
B<nama> [I<options>] [I<project_name>]
=head1 DESCRIPTION
B<Nama> performs multitrack recording, effects processing,
editing, mixing, mastering, live performance and
general-purpose audio processing, using the Ecasound
realtime audio engine.
=head2 Audio Functionality
Audio projects may be developed using tracks, buses,
effects, sends, inserts, marks, regions, fades, sequences
and edits. Each track may contain one or more WAV files,
which may be recorded or imported.
Effects processing by LADSPA, LV2 and Ecasound
plugins may be performed in realtime, or cached (e.g.
frozen) to a file. The user may toggle between cached and
dynamic processing for a track. Audio regions may be
altered, duplicated, time-shifted or replaced.
Nama supports MIDI functionality via midish.
=head2 Presets and templates
To facilitate reuse, a track's plugins and inserts can be
stored as an effect chain. Effect profiles and project
templates provide templating for groups of tracks and entire
projects, respectively.
=head2 Audio framework
Audio IO is via JACK or ALSA. Soundcard IO is normally
routed to JACK with transparent fallback to ALSA.
=head2 Persistence
Project data parameters related to audio configuration are
serialized as JSON and tracked using Git when available. The
entire project history is retained and may be managed using
branches and tags.
Nama supports Ladish Level 1 session handling.
=head2 User interfaces
Nama has fully featured terminal command prompt, a Tk
GUI, and experimental OSC and remote-command modes.
The command prompt accepts Nama commands, Ecasound
interactive-mode commands, shell commands and perl code.
It has command history and autocompletion. The help
system provides documentation and keyword search
covering Nama commands and effects.
The hotkey mode provides a convenient way to select, view,
and modify effect parameters.
By default, Nama displays a graphic user interface while
the command processor runs in a terminal window.
=head1 OPTIONS
=over 12
=item B<--gui, -g>
Start Nama in GUI mode
=item B<--text, -t>
Start Nama in text mode
=item B<--config, -f>
Specify configuration file (default: ~/.namarc)
=item B<--project-root, -d>
Specify project root directory
=item B<--create-project, -c>
Create project if it doesn't exist
=item B<--net-eci, -n>
Use Ecasound's Net-ECI interface
=item B<--libecasoundc, -l>
Use Ecasound's libecasoundc interface
=item B<--save-alsa, -a>
Save/restore alsa state with project data
=item B<--help, -h>
This help display
=back
Debugging options:
=over 12
=item B<--no-static-effects-data, -s>
Don't load effects data
=item B<--no-state, -m>
Don't load project state
=item B<--no-static-effects-cache, -e>
Bypass effects data cache
=item B<--regenerate-effects-cache, -r>
Regenerate the effects data cache
=item B<--no-reconfigure-engine, -R>
Don't automatically configure engine
=item B<--debugging-output, -D>
Emit debugging information
=item B<--fake-jack, -J>
Simulate JACK environment
=item B<--fake-alsa, -A>
Simulate ALSA environment
=item B<--no-ecasound, -E>
Don't spawn Ecasound process
=item B<--execute-command, -X>
Supply a command to execute
=back
=head1 CONTROLLING NAMA/ECASOUND
The Ecasound audio engine is configured through use of
I<chain setups> that specify the signal processing network.
Nama serves as an intermediary, taking high-level commands
from the user, generating appropriate chain setups for user
tasks such as recording, playback, mixing, etc., and running
the audio engine.
=head2 Configuration Commands
Configuration commands affect I<future> runs of the audio
engine. For example, B<rec, play, mon> and B<off> determine
whether the current track will get its audio stream from an
external (e.g. live) source, whether an existing WAV file
will be played back, and whether a new WAV file will be
recorded. Nama responds to these commands by reconfiguring
the engine and displaying the updated track status. See 'man
::ChainSetup' for details on how the chain setup created.
=head2 Realtime Commands
Once a chain setup is loaded and the engine is launched,
commands can be issued to control the realtime behavior of
the audio processing engine. These commands include
transport C<start> and C<stop>, playback repositioning
commands such C<forward>, C<rewind> and C<setpos>. Effects
may be added, modified or removed while the engine is
running.
=head2 Configuration
General configuration of sound devices and program options
is performed by editing the F<.namarc> file. On Nama's first
run, a default version of F<.namarc> is usually placed in
the user's home directory.
=head1 Tk GRAPHICAL UI
Invoked by default if Tk is installed, this interface
provides a subset of Nama's functionality on two
windows:
=head2 Main Window
The top section has buttons for creating, loading and saving
projects, adding tracks, adding effects to tracks. In
short, for setup.
Below are buttons for controlling the transport (start, stop
and friends) and for setting marks.
The GUI project name bar and time display change color to
indicate whether the upcoming operation will include live
recording (red), mixdown (yellow) or playback (green).
=head2 Effects Window
The B<effects window> provides sliders for each effect
parameter of each track. Parameter range, defaults, and log/linear
scaling hints are automatically detected. Text-entry widgets
are used to enter parameters values for plugins without
hinted ranges. Any parameter label can be clicked to
add a parameter controller.
=head2 Terminal Window
The command prompt is available in the terminal window
during GUI operation. Text commands are used to access
Nama's more advanced functions.
=head1 TEXT USER INTERFACE
Press the I<Enter> key if necessary to get the
command prompt, which will look something like this:
=over 12
C<nama sax ('h' for help)E<gt>>
=back
In this instance, 'sax' is the current track.
When using buses, the bus is indicated before the track:
=over 12
C<nama Strings/violin ('h' for help)E<gt>>
=back
At the prompt, you can enter Nama and Ecasound commands, Perl code
preceded by C<eval> or shell code preceded by C<!>.
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 C<eval> or C<!> the entire line (up to double
semicolons ';;' if present) will be given to the
corresponding interpreter.
You can access command history using up-arrow/down-arrow.
Type C<help> for general help, C<help command> for help with
C<command>, C<help foo> for help with commands containing
the string C<foo>. C<help_effect foo bar> lists all
plugins/presets/controller containing both I<foo> and
I<bar>. Tab-completion is provided for Nama commands, Ecasound-iam
commands, plugin/preset/controller names, and project names.
Many effects have abbreviations, such as 'afx' for
'add_effect'.
=head1 TRACKS
Each track has a descriptive name (i.e. vocal) and an
integer track-number assigned when the track is created.
New user tracks initially belong to the Main bus.
Track output signals are usually mixed and pass through the
Master track on the way to soundcard for monitoring.
The following sections describes track attributes and
their effects.
=head2 Width
Specifying 'mono' means the track has one input channel, which
will be recorded as a mono WAV file. Mono track signals are
automatically duplicated to stereo and a pan effect is provided.
Specifying 'stereo' for a track means that two channels of
audio input will be recorded as an interleaved stereo WAV
file. You can also use a 'stereo' declaration to avoid the
automatic channel copy usually applied to single-channel
sources.
Specifying N channels for a track ('set width N') means N
successive input channels will be recorded as an N-channel
interleaved WAV file.
=head2 REC/PLAY/MON/OFF
Each track, including Master and Mixdown, has its own
REC/MON/PLAY/OFF setting.
The I<MON> setting means that the track source is connected to
the track input, and the track output is supplied for
monitoring by the Main bus and other submixes if any.
The I<REC> setting prepares the track is ready to record a
WAV file.
The I<PLAY> setting enqueues an audio file for playback
from disk as the track source.
I<REC> and I<PLAY> settings also create the monitoring
routes associated with I<MON> status.
I<OFF> setting tells Nama to remove the track from the audio
network. I<OFF> status also results when no audio source is
available. A track with no recorded WAV files
will show OFF status, even if set to PLAY.
=head3 Bus setting
Buses can force the status of their member tracks to OFF.
Nama provides MON and OFF settings for buses.
OFF (set by C<bus_off>) removes all member tracks from the chain
setup, MON (set by C<bus_mon> restores them.
The B<mixplay> command sets the Mixdown track to PLAY and the
Main bus to OFF.
=head2 Version Numbers
Multiple WAV files ("takes") can be recorded for each track. These are
distinguished by a version number that increments with each
recording run, i.e. F<sax_1.wav>, F<sax_2.wav>, etc. All
WAV files recorded in the same run have the same version
numbers.
The version numbers of files for playback can be selected at
the bus or track level. By setting the bus version
to 5, you can play back version 5 of several tracks
at once. Version 5 could signify the fifth take of a song, or
the fifth song of a live recording session.
The track version setting, if present, overrides the bus
setting. Setting the track version to zero restores control
of the version number to the bus.
The Main bus version setting does I<not> currently propagate to
other buses.
=head2 Marks
Marks in Nama are similar to those in other audio editing
software. One limitation is that mark positions are relative
to the beginning of an Ecasound chain setup. If your project
involves a single track, and you will be shortening the
stream by setting a region to play, set any marks you need
I<after> defining the region.
=head2 Regions
The C<region> command allows you to define endpoints for a
portion of an audio file. You can then use the C<shift>
command to move the region to the desired time position.
Each track can have one region definition. To create
multiple regions, the C<new_region> command takes a pair of
marks to create a read-only copy of the current track with
the specified region definition.
You can control this region as you would any other other
track, applying effects, adjusting volume, etc.
Currently, regions are not clipped out of their host track.
This feature may be implemented in future.
=head3 Using Tracks from Other Projects
The C<link_track> clones a read-only track from
another track, which may belong to a different project.
=head2 Effects
Each track gets volume and pan effects by default. New
effects added using C<add_effect> are applied before pan
volume controls. You can position effects anywhere you
choose using C<insert_effect> or C<position_effect>.
=head3 Fades
Nama allows you to place fades on any track. Fades are
defined by mark position and duration. An additional volume
operator, -eadb, is applied to each track to host the
envelope controller that implements fades.
=head3 Sends and Inserts
The C<send> command can route 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.
The C<add_insert> command configures a pre- or 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.
Each track can have one pre-fader and one post-fader insert.
=head2 Bunches
A bunch is just a list of track names. Bunch names are used
with the keyword C<for> to apply one or more commands to several
tracks at once. A bunch can be created with the C<new_bunch>
command. Any bus name can also be treated as a bunch.
Finally, several system defined bunches are available:
=over 12
=item B<rec>, B<mon>, B<off>
All tracks with the corresponding I<setting> in the current bus
=back
=head2 Buses
=head3 Sub Buses
B<Buses> enable multiple tracks to be routed through a
single mix track before feeding the Main mixer bus (or
possibly, another bus.)
The following commands create a bus and assign
three tracks to it. The mix track takes the name of
the bus and is stereo by default.
# create a bus named Strings with a same-named mix track
add_bus Strings
# create tracks for the bus
add_tracks violin cello bass
# move the tracks from the Main bus (default) to the Strings bus
for violin cello bass; move_to_bus Strings
# use the mix track to control bus output volume
Strings vol - 10
=head3 Submixes
B<Submixes> are a type of bus used to provide instrument
monitors, or to send the outputs from multiple user tracks
to an external program such as jconverter.
=head1 ROUTING
=head2 General Notes
While Nama can address tracks by either name and track number,
the chain setups use the track number exclusively.
The Master track (mixer output control) is always
chain 1, the Mixdown track is always chain 2.
In single-engine mode, Nama uses Ecasound loop devices where
necessary to connect two tracks, or to allow one track to
have multiple inputs or outputs. Each loop device adds one
buffer, which increases latency. In dual-engine mode, JACK
ports are used for interconnections instead of loop devices.
=head2 Flow Diagrams
The following diagrams apply to Nama's single-engine, mode.
(The same topology is used in dual-engine mode.)
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 show the track number/name.
The stereo outputs of each user track terminate at
Master_in, a loop device at the mixer input.
=head3 Track, REC status
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, or if C<rec_disable> is issued.
=head3 Track, MON status
sax_1.wav ------(3)----> Master_in
=head3 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.
Master_in --(1)--> Master_out --+--------> Sound device
|
+-->(2)--> Mixdown_1.wav
=head3 Mastering Mode
In mastering mode (invoked by C<master_on> and released
C<master_off>) the following network, receives the Master
track signal as input and provides an output to the
soundcard or WAV file.
+- Low -+
| |
Master_in --- Eq --+- Mid -+--- Boost -> soundcard/wav_out
| |
+- High +
The B<Eq> track hosts an equalizer.
The B<Low>, B<Mid> and B<High> tracks each apply a bandpass
filter, a compressor and a spatialiser.
The B<Boost> track applies gain and a limiter.
These effects and their default parameters are defined
in the configuration file F<.namarc>.
=head2 Mixdown
The C<mixdown> command configures Nama for mixdown. The
Mixdown track is set to REC (equivalent to C<Mixdown rec>)
and the audio monitoring output is turned off (equivalent to
C<Master off>).
Mixdown proceeds after you start the transport.
As a convenience, Mixdown_nn.wav will be symlinked to
F<<branch_name>_nn.wav> in the project directory. (If git is
disabled or not available F<<project_name>_nn.wav> is used
instead.) Corresponding encoded files are created if the
"mixdown_encodings" option is set. Acceptable values are a
space-separated list. The default is "mixdown_encodings: ogg
mp3".
=head2 The Preview and Doodle Modes, and the Eager Setting
These non-recording modes, invoked by C<preview> and
C<doodle> commands tweak the routing rules for special
purposes. B<Preview mode> disables recording of WAV files
to disk. B<Doodle mode> disables PLAY inputs while
excluding any tracks with the same source as a currently
routed track. The C<arm> command releases both preview and
doodle modes.
The eager setting causes the engine to start immediately
following a reconfiguration.
These modes are unnecessary in Nama's dual-engine mode.
=head2 Saving Projects
The C<save> command is the usual way to
preserve your work.
When you type C<save>, Settings related to the state of the
project are saved in the file F<State.json> in the current
project directory. F<State.json> is tracked by git.
C<save> updates several other data files as well:
F<Aux.json>, in the current project directory, contains
data that is part of the project (such as command history,
track comments, and current operating modes) but with no direct
effect on the project audio.
F<global_effect_chains.json>, in the project root directory,
contains system and user defined effect chains.
=head3 Save without Git
C<save somename.json> will save project state to a file of
that name. Similarly C<get somename.json> will load the
corresponding file. The F<.json> suffix may be omitted if
"use_git: 0" is set in F<.namarc>.
=head3 Save with Git
When git is installed, Nama uses it to store snapshots of
every step in the history of your project.
While you can continue using the same C<save> and C<get>
with snapshots, the underlying version control gives
them huge advantages over files: (1) they can sprout
branches, (2) they retain their history and (3) they are
never overwritten.
When you type C<save initial-mix>, the latest snapshot is
tagged with the name "initial-mix", which you can recall
later with the command C<get initial-mix>.
You can include a comment with the snapshot:
C<save initial-mix "sounds good enough to send to the front office">
Nama lets you create new branches, starting at any snapshot.
To start a new branch called I<compressed-mix> starting at a
snapshot called I<initial-mix> you would say:
C<new_branch compressed-mix initial-mix>
If you want to go back to working on the master branch, use
C<branch master>.
You can also issue native git commands at the Nama prompt.
=head3 Git history example
All projects begin on the "master" branch. Because this is
the default branch, it is not displayed in the prompt.
Otherwise "master" is not special in any way.
In the graphs below, the letters indicate
named snapshots.
create test-project
...
save a
...
save b
...
save c
---a---b---c (master)
get a
...
save d
...
save e
...
save f
d---e---f (a-branch)
/
-----a----b---c (master)
Now, you want to go back to try something different at "c":
get c
...
save g
d---e---f (a-branch)
/
----a----b---c (master)
\
g (c-branch CURRENT HEAD)
You could also go back to master, and restart
from there:
get master
...
save h
...
save i
d---e---f (a-branch)
/
----a----b---c---h---i (master CURRENT HEAD)
\
g (c-branch)
While the merging of branches may be possible,
the function has not been tested.
=head2 Exiting
When you type C<quit> Nama will automatically save your work
to F<State.json>. If you I<don't> want this behavior, use
Ctrl-C to exit Nama.
=head2 Jack ports list file
Use I<source filename.ports> to ask Nama
to connect multiple JACK ports listed in a file
F<filename.ports> to the input
port(s) of that track.
If the track is stereo, ports from the list are alternately
connected to left and right channels.
=head2 Track edits
An edit consists of audio clips and data structures
associated with a particular track and version. The edit
replaces part of the original WAV file, allowing you to fix
wrong notes, or substitute one phrase for another.
Each track can host multiple edits. Edits are
non-destructive; they are achieved by using Ecasound's
ability to crossfade and sequence.
Select the track to be edited and the correct version.
Before creating the edit, you will now need to create three
marks:
=over 4
=item * play start point
=item * rec start point
=item * rec end point
=back
The edit will replace the audio between the rec start and
rec end points.
There are two ways to set these points.
=head3 set_edit_points command
Position the playback head a few seconds before the edit.
Enter the I<set_edit_points> command. This will start the
engine. Hit the B<P> key three times to designate the
playback start, punch-in and punch-out positions.
=head3 Specify points individually
Position the playback head at the position you want playback
for the edit to start. Enter the I<set_play_start_mark>
command.
Use the same procedure to set the rec start and rec end
positions using the I<set_rec_start_mark>
and I<set_rec_end_mark> commands.
=head3 Provide marks as arguments to I<new_edit> (not implemented)
Type I<new_edit play_start_mark rec_start_mark rec_end_mark>.)
=head3 Create the edit
Enter the I<new_edit> command to create the necessary
tracks and data structures.
Use I<preview_edit> to confirm the edit positions. The
engine will run and you will hear the host track with the
target region removed. Playback will be restricted to the
edit region. You may use I<preview_out> to hear the clip to
be removed.
Use I<list_marks> to see the edit marks and I<modify_mark>
to nudge them into perfect position.
Once you are satisfied with the mark positions, you are
ready to record your edit.
Enter I<start_edit>. Playback will begin at first mark. The
replacement clip will be recorded from the source specified
in the original track.
Each I<start_edit> command will record an additional version
on the edit track. I<redo_edit> will delete (destructively)
the most recent audio clip and begin recording anew.
You may specify another range for editing and use
the editing procedure again as many times as
you like. Edits may not overlap.
=head3 Merging edits
I<merge_edits> will recursively merge all edits applied to
the current track and version, creating a new version.
I recommend that you merge edits when you are satisfied,
with the results to protect your edits against an accidental
change in mark, region or version settings.
I<restore_edits> acts on a merged version of the current
track, selecting the prior unmerged version with all edits
and region definitions in "live" form. You may continue to
create new edits. B<TO BE IMPLEMENTED>
I<list_edits> will label the edits by index and time.
I<end_edit_mode> will restore normal playback mode
I<destroy_edit>
Behind the scenes, the host track becomes the mix track to a
bus. Sources for the bus are the original audio track, and
zero or more edits, each represented by one track object.
=head1 REMOTE CONTROL
You can send now send commands from a remote process, and
also get information back. Understand that this code opens a
remote execution hole.
In F<.namarc> you need something like:
remote_control_port: 57000
Then Nama will set up a listener for remote commands.
The usual return value will be a single newline.
However, if you send an 'eval' command followed by perl
code, the return value will be the result of the perl code
executed with a newline appended. If the result is a list,
the items will be joined by spaces into a single string.
If the result is an object or data structure, it will be
returned in a serialized form.
For example, if you send this string:
eval $this_track->name
The return value will be the name of the current track.
=head1 TEXT COMMANDS
=head2 Help commands
=head4 B<help> (h) - Display help on Nama commands.
=over 8
help [ <integer:help_topic_index> | <string:help_topic_name> | <string:command_name> ]
help marks # display the help category marks and all commands containing marks
help 6 # display help on the effects category
help mfx # display help on modify_effect - shortcut mfx
=back
=head4 B<help_effect> (hfx he) - Display detailed help on LADSPA or LV2 effects.
=over 8
help_effect <string:label> | <integer:unique_id>
help_effect 1970
# display help on Fons Adriaensen's parametric EQ (LADSPA)
help_effect etd
# prints a short message to consult Ecasound manpage,
# where the etd chain operator is documented.
hfx lv2-vocProc
# display detailed help on the LV2 VocProc effect
=back
=head4 B<find_effect> (ffx fe) - Display one-line help for effects matching the search string(s).
=over 8
find_effect <string:keyword1> [ <string:keyword2>... ]
find_effect compressor
# List all effects containing "compressor" in their name or parameters
fe feedback
# List all effects matching "feedback"
# (for example a delay with a feedback parameter)
=back
=head2 General commands
=head4 B<exit> (quit q) - Exit Nama, saving settings (the current project).
=over 8
exit
=back
=head4 B<memoize> - Enable WAV directory caching, so Nama won't have to scan
the entire project folder for new files after every run.
(default)
=over 8
memoize
=back
=head4 B<unmemoize> - Disable WAV directory caching.
=over 8
unmemoize
=back
=head2 Transport commands
=head4 B<stop> (s) - Stop transport. Stop the engine, when recording or playing back.
=over 8
stop
=back
=head4 B<start> (t) - Start the transport rolling
=over 8
start
rec # prepare the curent track to be recorded.
start # Start the engine/transport rolling (play now!)
stop # Stop the engine, cleanup, prepare to review
=back
=head4 B<getpos> (gp) - Get the current playhead position (in seconds).
=over 8
getpos
start # Start the engine.
gp # Get the current position of the playhead. Where am I?
=back
=head4 B<setpos> (sp) - Set current playhead position (in seconds).
=over 8
setpos <float:position_seconds>
setpos 65.5
=back
=head4 B<forward> (fw) - Move playback position forwards (in seconds).
=over 8
forward <float:increment_seconds>
fw 23.7
=back
=head4 B<rewind> (rw) - Move playback position backwards (in seconds).
=over 8
rewind <float:decrement_seconds>
rewind 6.5
=back
=head4 B<to_start> (beg) - Set the playback head to the start. A synonym for setpos 0.
=over 8
to_start
=back
=head4 B<to_end> (end) - Set the playback head to end minus 10 seconds.
=over 8
to_end
=back
=head4 B<ecasound_start> - Ecasound-only start. Nama will not monitor the transport.
For diagnostic use.
=over 8
ecasound_start
=back
=head4 B<ecasound_stop> - Ecasound-only stop. Nama will not monitor the transport.
For diagnostic use.
=over 8
ecasound_stop
=back
=head4 B<restart_ecasound> - Restart the Ecasound process. May help if Ecasound has crashed
or is behaving oddly.
=over 8
restart_ecasound
=back
=head4 B<preview> (song) - Enter the preview mode. Configure Nama for playback and
passthru of live inputs without recording (for mic test,
rehearsal, etc.)
=over 8
preview
rec # Set the current track to record from its source.
preview # Enter the preview mode.
start # Playback begins. You can play live, adjust effects,
# forward, rewind, etc.
stop # Stop the engine/transport.
arm # Restore to normal recording/playback mode.
=back
=head4 B<doodle> (live) - Enter doodle mode. Passthru of live inputs without
recording. No playback. Intended for rehearsing and
adjusting effects.
=over 8
doodle
doodle # Switch into doodle mode.
start # start the engine/transport running.
(fool around)
stop # Stop the engine.
arm # Return to normal mode, allowing play and record to disk
=back
=head2 Mix commands
=head4 B<mixdown> (mxd) - Enter mixdown mode for subsequent engine runs. You will
record a new mix each time you use the start command
until you leave the mixdown mode using "mixoff".
=over 8
mixdown
mixdown # Enter mixdown mode
start # Start the transport. The mix will be recorded by the
# Mixdown track. The engine will run until the
# longest track ends. (After mixdown Nama places
# a symlink to the WAV file and possibly ogg/mp3
# encoded versions in the project directory.)
mixoff # Return to the normal mode.
=back
=head4 B<mixplay> (mxp) - Enter Mixdown play mode, setting user tracks to OFF
and only playing the Mixdown track. Use "mixoff" to
leave this mode.
=over 8
mixplay
mixplay # Enter the Mixdown play mode.
start # Play the Mixdown track.
stop # Stop playback.
mixoff # Return to normal mode.
=back
=head4 B<mixoff> (mxo) - Leave the mixdown or mixplay mode. Sets Mixdown track to OFF,
user tracks to MON.
=over 8
mixoff
=back
=head4 B<automix> - Normalize track volume levels and fix DC-offsets, then mixdown.
=over 8
automix
=back
=head4 B<master_on> (mr) - Turn on the mastering mode, adding tracks Eq, Low, Mid, High
and Boost, if necessary. The mastering setup allows for one
EQ and a three-band multiband compression and a final
boosting stage. Using "master_off" to leave the mastering mode.
=over 8
master_on
mr # Turn on master mode.
start # Start the playback.
# Now you can adjust the Boost or global EQ.
stop # Stop the engine.
=back
=head4 B<master_off> (mro) - Leave mastering mode. The mastering network is disabled.
=over 8
master_off
=back
=head2 Track commands
=head4 B<add_track> (add new) - Create a new audio track.
=over 8
add_track <string:name>
add_track clarinet
# create a mono track called clarinet with input
# from soundcard channel 1.
=back
=head4 B<add_tracks> - Create one or more new tracks in one go.
=over 8
add_tracks <string:name1> [ <string:name2>... ]
add_tracks violin viola contra_bass
=back
=head4 B<add_midi_track> (amt) - Create a new MIDI track.
=over 8
add_midi_track <string:name>
=back
=head4 B<link_track> (link) - Create a read-only track, that uses audio files from another track.
=over 8
link_track [<string:project_name>] <string:track_name> <string:link_name>
link my_song_part1 Mixdown part_1
# Create a read-only track "part_1" in the current project
# using files from track "Mixdown" in project "my_song_part_1".
#
link_track compressed_piano piano
# Create a read-only track "compressed_piano" using files from
# track "piano". This is one way to provide wet and dry
# (processed and unprocessed) versions of same source.
# Another way would be to use inserts.
=back
=head4 B<import_audio> (import) - Import a sound file (wav, ogg, mp3, etc.) to the
current track, resampling it if necessary. The
imported file is set as current version.
=over 8
import_audio <string:full_path_to_file> [ <integer:frequency> ]
import /home/samples/bells.flac
# import the file bells.flac to the current track
import /home/music/song.mp3 44100
# import song.mp3, specifying the frequency
=back
=head4 B<set_track> - Directly set current track parameters (use with care!).
=over 8
set_track <string:track_field> <value>
=back
=head4 B<record> (rec) - Set the current track to record its source. Creates the
monitoring route if necessary. Recording to disk will begin
on the next engine start. Use the "mon" or "off" commands to
disable recording.
=over 8
record
rec
# Set the current track to record.
start
# A new version (take) will be written to disk,
# creating a file such as sax_1.wav. Other tracks
# may be recording or playing back as well.
stop
# Stop the recording/playback, automatically enter playback mode
=back
=head4 B<play> - Set the current track to playback the currently selected version.
Creates the monitoring route if necessary. The selected audio file
will play the next time the engine starts.
=over 8
play
=back
=head4 B<mon> - Create a monitoring route for the current track at
the next opportunity.
=over 8
mon
=back
=head4 B<off> - Remove the monitoring route for the current track and all
track I/O at the next opportunity. You can re-include it
using "mon", "play" or "rec" commands.
=over 8
off
=back
=head4 B<source> (src r) - Set the current track's input (source), for example
to a soundcard channel, or JACK client name
=over 8
source <integer:soundcard_channel> | <string:jack_client_name>
| <string:jack_port_name> <string:jack_ports_list> |
| <string:track_name> | <string:loop_id> | 'jack' | 'null'
source 3
# Take input from soundcard channel 3 (3/4 if track is stereo)
#
source null
# Track's input is silence. This is useful for when an effect such
# as a metronome or signal generator provides a source.
#
source LinuxSampler
# Record input from the JACK client named LinuxSampler.
#
source synth:output_3
# record from the JACK client synth, using the
# port output_3 (see he jackd and jack_lsp manpages
# for more information).
#
source jack
# This leaves the track input exposed as JACK ports
# such as Nama:sax_in_1 for manual connection.
#
source kit.ports
# The JACK ports listed in the file kit.ports (if it exists)
# will be connected to the track input.
#
# Ports are listed pairwise in the .ports files for stereo tracks.
# This is convenient for use with the Hydrogen drumkit,
# whose outputs use one JACK port per voice.
=back
=head4 B<send> (aux) - Set an aux send for the current track. Remove sends with remove_send .
=over 8
send <integer:soundcard_channel> | <string:jack_client_name> | <string:loop_id>
send 3 # Send the track output to soundcard channel 3.
send jconvolver # Send the track output to the jconvolver JACK client.
=back
=head4 B<remove_send> (nosend noaux) - Remove aux send from the current track.
=over 8
remove_send
=back
=head4 B<stereo> - Configure the current track to record two channels of audio
=over 8
stereo
=back
=head4 B<mono> - Configure the current track to record one channel of audio
=over 8
mono
=back
=head4 B<set_version> (version ver) - Select a WAV file, by version number, for current track playback
(Overrides a bus-level version setting)
=over 8
set_version <integer:version_number>
piano # Select the piano track.
version 2 # Select the second recorded version
sh # Display information about the current track
=back
=head4 B<destroy_current_wav> - Remove the currently selected recording version from the
current track after confirming user intent. This DESTRUCTIVE
command removes the underlying audio file from your disk.
Use with caution.
=over 8
destroy_current_wav
=back
=head4 B<list_versions> (lver) - List WAV versions of the current track. This will print the
numbers.
=over 8
list_versions
list_versions # May print something like: 1 2 5 7 9
# The other versions might have been deleted earlier by you.
=back
=head4 B<vol> (v) - Change or show the current track's volume.
=over 8
vol [ [ + | - | / | * ] <float:volume> ]
vol * 1.5 # Multiply the current volume by 1.5
vol 75 # Set the current volume to 75
# Depending on your namarc configuration, this means
# either 75% of full volume (-ea) or 75 dB (-eadb).
vol - 5.7 # Decrease current volume by 5.7 (percent or dB)
vol # Display the volume setting of the current track.
=back
=head4 B<mute> (c cut) - Mute the current track by reducing the volume parameter.
Use "unmute" to restore the former volume level.
=over 8
mute
=back
=head4 B<unmute> (nomute C uncut) - Restore previous volume level. It can be used after mute or solo.
=over 8
unmute
=back
=head4 B<unity> - Set the current track's volume to unity. This will change the volume to the default value (100% or 0 dB).
=over 8
unity
vol 55 # Set volume to 55
unity # Set volume to the unity value.
vol # Display the current volume (should be 100 or 0,
# depending on your settings in namarc.)
=back
=head4 B<solo> (sl) - Mute all tracks but the current track or the tracks or
bunches specified. You can reverse this with nosolo.
=over 8
solo [ <strack_name_1> | <string:bunch_name_1> ] [ <string:track_name_2 | <string:bunch_name_2> ] ...
solo # Mute all tracks but the current track.
nosolo # Unmute all tracks, restoring prior state.
solo piano bass Drums # Mute everything but piano, bass and Drums.
=back
=head4 B<nosolo> (nsl) - Unmute all tracks which have been muted by a solo command.
Tracks that had been muted before the solo command stay muted.
=over 8
nosolo
=back
=head4 B<all> - Unmute all tracks that are currently muted
=over 8
all
piano # Select track piano
mute # Mute the piano track.
sax # Select the track sax.
solo # Mute other tracks
nosolo # Unmute other tracks (piano is still muted)
all # all tracks play
=back
=head4 B<pan> (p) - Change or display the current panning position of the
current track. Panning is moving the audio in the stereo
panorama between right and left. Position is given in percent.
0 is hard left and 100 hard right, 50% is dead centre.
=over 8
pan [ <float:pan_position_in_percent> ]
pan 75 # Pan the track to a position between centre and hard right
p 50 # Move the current track to the centre.
pan # Show the current position of the track in the stereo panorama.
=back
=head4 B<pan_right> (pr) - Pan the current track hard right. this is a synonym for pan 100.
Can be reversed with pan_back.
=over 8
pan_right
=back
=head4 B<pan_left> (pl) - Pan the current track hard left. This is a synonym for pan 0.
Can be reversed with pan_back.
=over 8
pan_left
=back
=head4 B<pan_center> (pc) - Pan the current track to the centre. This is a synonym for pan 50.
Can be reversed with pan_back.
=over 8
pan_center
=back
=head4 B<pan_back> (pb) - Restore the current track's pan position prior to pan_left,
pan_right or pan_center commands.
=over 8
pan_back
=back
=head4 B<show_tracks> (lt show) - Show a list of tracks, including their index number, volume,
pan position, recording status and source.
=over 8
show_tracks
=back
=head4 B<show_tracks_all> (sha showa) - Like show_tracks, but includes hidden tracks as well. Useful for debugging.
=over 8
show_tracks_all
=back
=head4 B<show_bus_tracks> (ltb showb) - Show a list of tracks in the current bus.
=over 8
show_bus_tracks
=back
=head4 B<show_track> (sh -fart) - Display full information about the current track: index, recording
status, effects and controllers, inserts, the selected
WAV version, and signal width (channel count).
=over 8
show_track
=back
=head2 Setup commands
=head4 B<show_mode> (shm) - Display the current record/playback mode. this will indicate the
mode (doodle, preview, etc.) and possible record/playback settings.
=over 8
show_mode
=back
=head2 Track commands
=head4 B<show_track_latency> (shl) - Display the latency information for the current track.
=over 8
show_track_latency
=back
=head2 Diagnostics commands
=head4 B<show_latency_all> (shla) - Dump all latency data.
=over 8
show_latency_all
=back
=head2 Track commands
=head4 B<set_region> (srg) - Specify a playback region for the current track using marks.
Can be reversed with remove_region.
=over 8
set_region <string:start_mark_name> <string:end_mark_name>
sax # Select "sax" as the current track.
setpos 2.5 # Move the playhead to 2.5 seconds.
mark sax_start # Create a mark
sp 120.5 # Move playhead to 120.5 seconds.
mark sax_end # Create another mark
set_region sax_start sax_end
# Play only the audio from 2.5 to 120.5 seconds.
=back
=head4 B<add_region> - Make a copy of the current track using the supplied a region
definition. The original track is untouched.
=over 8
add_region <string:start_mark_name> | <float:start_time> <string:end_mark_name> | <float:end_time> [ <string:region_name> ]
sax # Select "sax" as the current track.
add_region sax_start 66.7 trimmed_sax
# Create "trimmed_sax", a copy of "sax" with a region defined
# from mark "sax_start" to 66.7 seconds.
=back
=head4 B<remove_region> (rrg) - Remove the region definition from the current track.
Remove the current track if it is an auxiliary track.
=over 8
remove_region
=back
=head4 B<shift_track> (shift playat pat) - Choose an initial delay before playing a track or region.
Can be reversed by unshift_track.
=over 8
shift_track <string:start_mark_name> | <integer:start_mark_index | <float:start_seconds>
piano # Select "piano" as current track.
shift 6.7 # Move the start of track to 6.7 seconds.
=back
=head4 B<unshift_track> (unshift) - Restore the playback start time of a track or region to 0.
=over 8
unshift_track
=back
=head4 B<modifiers> (mods mod) - Add/show modifiers for the current track (man ecasound for details).
This provides direct control over Ecasound track modifiers
It is not needed for normal work.
=over 8
modifiers [ Audio file sequencing parameters ]
modifiers select 5 15.2
# Apply Ecasound's select modifier to the current track.
# The usual way to accomplish this is with a region definition.
=back
=head4 B<nomodifiers> (nomods nomod) - Remove modifiers from the current track.
=over 8
nomodifiers
=back
=head4 B<normalize> (ecanormalize) - Apply ecanormalize to the current track version. This will
raise the gain/volume of the current track as far as
possible without clipping and store it that way on disk.
Note: this will permanently change the file.
=over 8
normalize
=back
=head4 B<fixdc> (ecafixdc) - Fix the DC-offset of the current track using ecafixdc.
Note: This will permanently change the file.
=over 8
fixdc
=back
=head4 B<autofix_tracks> (autofix) - Apply ecafixdc and ecanormalize to all current versions of all tracks, set to playback (MON).
=over 8
autofix_tracks
=back
=head4 B<remove_track> - Remove the current track with its effects, inserts, etc.
Audio files are unchanged.
=over 8
remove_track
=back
=head2 Bus commands
=head4 B<bus_mon> (bmon) - Set the current bus mix_track to monitor (the default behaviour).
=over 8
bus_mon
=back
=head4 B<bus_off> (boff) - Set current bus mixtrack to OFF. Can be reversed
with bus_rec or bus_mon.
=over 8
bus_off
=back
=head2 Group commands
=head4 B<bus_version> (bver gver) - Set the default monitoring version for tracks in the current bus.
=over 8
bus_version
=back
=head4 B<add_bunch> (abn) -
=over 8
add_bunch <string:bunch_name> [ <string:track_name_1> | <integer:track_index_1> ] ...
add_bunch strings violin cello bass
# Create a bunch "strings" with tracks violin, cello and bass.
for strings; mute # Mute all tracks in the strings bunch.
for strings; vol * 0.8
# Lower the volume of all tracks in bunch "strings" by a
# a factor of 0.8.
=back
=head4 B<list_bunches> (lbn) - Display a list of all bunches and their tracks.
=over 8
list_bunches
=back
=head4 B<remove_bunch> (rbn) - Remove the specified bunches. This does not remove
the tracks, only the grouping.
=over 8
remove_bunch <string:bunch_name> [ <string:bunch_name> ] ...
=back
=head4 B<add_to_bunch> (atbn) - Add track(s) to an existing bunch.
=over 8
add_to_bunch <string:bunch_name> <string:track1> [ <string:track2> ] ...
add_to_bunch woodwind oboe sax flute
=back
=head2 Project commands
=head4 B<commit> (ci) - Commit Nama's current state
=over 8
commit <string:message>
=back
=head4 B<tag> - Git tag the current branch HEAD commit
=over 8
tag <string:tag_name> [<string:message>]
=back
=head4 B<branch> (br) - Change to named branch
=over 8
branch <string:branch_name>
=back
=head4 B<list_branches> (lb lbr) - List branches
=over 8
list_branches
=back
=head4 B<new_branch> (nbr) - Create a new branch
=over 8
new_branch <string:new_branch_name> [<string:existing_branch_name>]
=back
=head4 B<save_state> (keep save) - Save the project settings as file or git snapshot
=over 8
save_state [ <string:settings_target> [ <string:message> ] ]
=back
=head4 B<get_state> (get recall retrieve) - Retrieve project settings from file or snapshot
=over 8
get_state <string:settings_target>
=back
=head4 B<list_projects> (lp) - List all projects. This will list all Nama projects, which are stored in the Nama project root directory.
=over 8
list_projects
=back
=head4 B<new_project> (create) - Create or open a new empty Nama project.
=over 8
new_project <string:new_project_name>
create jam
=back
=head4 B<load_project> (load) - Load an existing project. This will load the project from the default project state file. If you wish to load a project state saved to a user specific file, load the project and then use get_state.
=over 8
load_project <string:existing_project_name>
load my_old_song
=back
=head4 B<project_name> (project name) - Display the name of the current project.
=over 8
project_name
=back
=head4 B<new_project_template> (npt) - Make a project template based on the current project. This will include tracks and busses.
=over 8
new_project_template <string:template_name> [ <string:template_description> ]
new_project_template my_band_setup "tracks and busses for bass, drums and me"
=back
=head4 B<use_project_template> (upt apt) - Use a template to create tracks in a newly created, empty project.
=over 8
use_project_template <string:template_name>
apt my_band_setup # Will add all the tracks for your basic band setup.
=back
=head4 B<list_project_templates> (lpt) - List all project templates.
=over 8
list_project_templates
=back
=head4 B<destroy_project_template> - Remove one or more project templates.
=over 8
destroy_project_template <string:template_name1> [ <string:template_name2> ] ...
=back
=head2 Setup commands
=head4 B<generate> (gen) - Generate an Ecasound chain setup for audio processing manually. Mainly useful for diagnostics and debugging.
=over 8
generate
=back
=head4 B<arm> - Generate and connect a setup to record or playback. If you are in dodle or preview mode, this will bring you back to normal mode.
=over 8
arm
=back
=head4 B<arm_start> (arms) - Generate and connect the setup and then start. This means, that you can directly record or listen to your tracks.
=over 8
arm_start
=back
=head4 B<connect> (con) - Connect the setup, so everything is ready to run. Ifusing JACK, this means, that Nama will connect to all the necessary JACK ports.
=over 8
connect
=back
=head4 B<disconnect> (dcon) - Disconnect the setup. If running with JACK, this will disconnect from all JACK ports.
=over 8
disconnect
=back
=head4 B<show_chain_setup> (chains) - Show the underlying Ecasound chain setup for the current working condition. Mainly useful for diagnostics and debugging.
=over 8
show_chain_setup
=back
=head4 B<loop> (l) - Loop the playback between two points. Can be stopped with loop_disable
=over 8
loop <string:start_mark_name> | <integer:start_mark_index> | <float:start_time_in_secs> <string:end_mark_name> | <integer:end_mark_index> | <float:end_time_in_secs>
loop 1.5 10.0 # Loop between 1.5 and 10.0 seconds.
loop 1 5 # Loop between marks with indeices 1 and 5, see list_marks.
loop sax_start 12.6 # Loop between mark sax_start and 12.6 seconds.
=back
=head4 B<noloop> (nl) - Disable looping.
=over 8
noloop
=back
=head2 Effect commands
=head4 B<add_controller> (acl) - Add a controller to an effect (current effect, by default). Controllers can be modified by using mfx and removed using rfx.
=over 8
add_controller [ <string:operator_id> ] <string:effect_code> [ <float:param1> <float:param2> ] ...
add_effect etd 100 2 2 50 50 # Add a stero delay of 100ms.
# the delay will get the effect ID E .
# Now we want to slowly change the delay to 200ms.
acl E klg 1 100 200 2 0 100 15 200 # Change the delay time linearly (klg)
=back
=head4 B<add_effect> (afx) - Add an effect
=over 8
add_effect [ (before <fx_alias> | first | last ) ] <fx_alias> [ <float:param1> <float:param2>... ]
"before", "first" and "last" can be abbreviated "b", "f" and "l", respectively.
We want to add the decimator effect (a LADSPA plugin).
help_effect decimator # Print help about its paramters/controls.
# We see two input controls: bitrate and samplerate
afx decimator 12 22050 # prints "Added GO (Decimator)"
# We have added the decimator with 12bits and a sample rate of 22050Hz.
# GO is the effect ID, which you will need to modify it.
=back
=head4 B<add_effect_last> (afxl) - Same as add-effect last
=over 8
add_effect_last <fx_alias> [ <float:param1> <float:param2>... ]
=back
=head4 B<add_effect_first> (afxf) - Same as add-effect first
=over 8
add_effect_first <fx_alias> [ <float:param1> <float:param2>... ]
=back
=head4 B<add_effect_before> (afxb) - Same as add-effect before
=over 8
add_effect_before <fx_alias> <fx_alias> [ <float:param1> <float:param2>... ]
=back
=head4 B<modify_effect> (mfx) - Modify effect parameter(s).
=over 8
modify_effect [ <fx_alias> ] <integer:parameter> [ + | - | * | / ] <float:value>
fx_alias can be: a position, effect ID, nickname or effect code
To change the roomsize of our reverb effect to 62
lfx
# We see that reverb has unique effect ID AF and roomsize is the
# first parameter.
mfx AF 1 62
#
mfx AF,BG 1 75
# Change the first parameter of both AF and BG to 75.
#
mfx CE 6,10 -3
# Change parameters 6 and 10 of effect CE to -3
#
mfx D 4 + 10
# Increase the fourth parameter of effect D by 10.
#
mfx A,B,C 3,6 * 5
# Adjust parameters 3 and 6 of effect A, B and C by a factor of 5.
=back
=head4 B<remove_effect> (rfx) - Remove effects. They don't have to be on the current track.
=over 8
remove_effect <fx_alias1> [ <fx_alias2> ] ...
=back
=head4 B<position_effect> (pfx) - Position an effect before another effect (use 'ZZZ' for end).
=over 8
position_effect <string:id_to_move> <string:position_id>
position_effect G F # Move effecit with unique ID G before F.
=back
=head4 B<show_effect> (sfx) - Show information about an effect. Default is to print information on the current effect.
=over 8
show_effect [ <string:effect_id1> ] [ <string:effect_id2> ] ...
sfx # Print name, unique ID and parameters/controls of the current effect.
sfx H # Print out all information about effect with unique ID H.
=back
=head4 B<dump_effect> (dfx) - Dump all data of current effect object
=over 8
dump_effect
=back
=head4 B<list_effects> (lfx) - Print a short list of all effects on the current track, only including unique ID and effect name.
=over 8
list_effects
=back
=head2 General commands
=head4 B<hotkeys> (hk) - Use this command to set the hotkey mode. (You may also use the hash symbol '#'.)
Hit the Escape key to return to command mode.
=over 8
hotkeys
=back
=head4 B<hotkeys_always> (hka) - Activate hotkeys mode after each command.
=over 8
hotkeys_always
=back
=head4 B<hotkeys_off> (hko) - Disable hotkeys always mode
=over 8
hotkeys_off
=back
=head4 B<hotkeys_list> (hkl lhk) - List hotkey bindings
=over 8
hotkeys_list
=back
=head2 Effect commands
=head4 B<add_insert> (ain) - Add an external send/return insert to current track.
=over 8
add_insert External: ( pre | post ) <string:send_id> [ <string:return_id> ]
Local wet/dry: local
add_insert pre jconvolver
# Add a prefader insert. The current track signal is sent
# to jconvolver and returned to the vol/pan controls.
add_insert post jconvolver csound
# Send the current track postfader signal (after vol/pan
# controls) to jconvolver, getting the return from csound.
guitar # Select the guitar track
ain local # Create a local insert
guitar-1-wet # Select the wet arm
afx G2reverb 50 5.0 0.6 0.5 0 -16 -20 # add a reverb
afx etc 6 100 45 2.5 # add a chorus effect on the reverbed signal
guitar # Change back to the main guitar track
wet 25 # Set the balance between wet/dry track to 25% wet, 75% dry.
=back
=head4 B<set_insert_wetness> (wet) - Set wet/dry balance of the insert for the current track. The balance is given in percent, 0 meaning dry and 100 wet signal only.
=over 8
set_insert_wetness [ pre | post ] <n_wetness>
wet pre 50 # Set the prefader insert to be balanced 50/50 wet/dry.
wet 100 # Simpler if there's only one insert
=back
=head4 B<remove_insert> (rin) - Remove an insert from the current track.
=over 8
remove_insert [ pre | post ]
rin # If there is only one insert on the current track, remove it.
remove_insert post # Remove the postfader insert from the current track.
=back
=head4 B<ctrl_register> (crg) - List all Ecasound controllers. Controllers include linear controllers and oscillators.
=over 8
ctrl_register
=back
=head4 B<preset_register> (prg) - List all Ecasound effect presets. See the Ecasound manpage for more detail on effect_presets.
=over 8
preset_register
=back
=head4 B<ladspa_register> (lrg) - List all LADSPA plugins, that Ecasound/Nama can find.
=over 8
ladspa_register
=back
=head2 Mark commands
=head4 B<list_marks> (lmk lm) - List all marks with index, name and their respective positions in time.
=over 8
list_marks
=back
=head4 B<to_mark> (tmk tom) - Move the playhead to the named mark or mark index.
=over 8
to_mark <string:mark_name> | <integer:mark_index>
to_mark sax_start # Jump to the position marked by sax_mark.
tmk 2 # Move to the mark with the index 2.
=back
=head4 B<add_mark> (mark amk k) - Drop a new mark at the current playback position. this will fail, if a mark is already placed on that exact position.
=over 8
add_mark [ <string:mark_id> ]
mark start # Create a mark named "start" at the current position.
=back
=head4 B<remove_mark> (rmk) - Remove a mark
=over 8
remove_mark [ <string:mark_name> | <integer:mark_index> ]
remove_mark start # remove the mark named start
rmk 16 # Remove the mark with the index 16.
rmk # Remove the current mark
=back
=head4 B<next_mark> (nmk) - Move the playhead to the next mark.
=over 8
next_mark
=back
=head4 B<previous_mark> (pmk) - Move the playhead to the previous mark.
=over 8
previous_mark
=back
=head4 B<name_mark> - Give a name to the current mark.
=over 8
name_mark <string:mark_name>
=back
=head4 B<modify_mark> (move_mark mmk) - Change the position (time) of the current mark.
=over 8
modify_mark [ + | - ] <float:seconds>
move_mark + 2.3 # Move the current mark 2.3 seconds forward from its
mmk 16.8 # Move the current mark to 16.8 seconds, no matter, where it is now.
=back
=head2 Diagnostics commands
=head4 B<engine_status> (egs) - Display the Ecasound audio processing engine status.
=over 8
engine_status
=back
=head4 B<dump_track> (dump) - Dump current track data.
=over 8
dump_track
=back
=head4 B<dump_group> (dumpg) - Dump group settings for user tracks.
=over 8
dump_group
=back
=head4 B<dump_all> (dumpa) - Dump most internal state data.
=over 8
dump_all
=back
=head4 B<dump_io> - Show chain inputs and outputs.
=over 8
dump_io
=back
=head2 Help commands
=head4 B<list_history> (lh) - List the command history. Every project stores its own command history.
=over 8
list_history
=back
=head2 Bus commands
=head4 B<add_submix_cooked> - Create a submix using all tracks in bus "Main"
=over 8
add_submix_cooked <string:name> <destination>
add_submix_cooked front_of_house 7
# send a custom mix named "front_of_house"
# to soundcard channels 7/8
=back
=head4 B<add_submix_raw> (asr) - Add a submix using tracks in Main bus (unprocessed signals, lower latency)
=over 8
add_submix_raw <string:name> <destination>
asbr Reverb jconv # Add a raw send bus called Reverb, with its output
=back
=head4 B<add_bus> (abs) - Add a sub bus. This is a bus, as known from other DAWs. The default output goes to a mix track and that is routed to the mixer (the Master track). All busses begin with a capital letter!
=over 8
add_bus <string:name> [ <string:track_name> | <string:jack_client> | <integer:soundcard_channel> ]
abs Brass # Add a bus, "Brass", routed to the Main bus (e.g. mixer)
abs special csound # Add a bus, "special" routed to JACK client "csound"
=back
=head4 B<update_submix> (usm) - Include tracks added since the submix was created.
=over 8
update_submix <string:name>
update_submix Reverb
=back
=head4 B<remove_bus> - Remove a bus or submix
=over 8
remove_bus <string:bus_name>
=back
=head4 B<list_buses> (lbs) - List buses and their parameters (TODO).
=over 8
list_buses
=back
=head4 B<set_bus> (sbs) - Set bus parameters. This command is intended for advanced users.
=over 8
set_bus <string:busname> <key> <value>
=back
=head2 Effect commands
=head4 B<overwrite_effect_chain> (oec) - Create a new effect chain, overwriting an existing one
of the same name.
=over 8
overwrite_effect_chain Same as for new_effect_chain
=back
=head4 B<new_effect_chain> (nec) - Create an effect chain, a named list of effects with all
parameter settings. Useful for storing effect setups
for particular instruments.
=over 8
new_effect_chain <string:name> [ <effect_id_1> <effect_id_2>... ]
new_effect_chain my_piano
# Create a new effect chain, "my_piano", storing all
# effects and their settings from the current track
# except the fader (vol/pan) settings.
nec my_guitar A C F G H
# Create a new effect chain, "my_guitar",
# storing the effects with IDs A, C, F, G, H and
# their respective settings.
=back
=head4 B<delete_effect_chain> (dec destroy_effect_chain) - Delete an effect chain definition. Does not affect the
project state. This command is not reversible by undo.
=over 8
delete_effect_chain <string:effect_chain_name>
=back
=head4 B<find_effect_chains> (fec) - Dump effect chains, matching key/value pairs if provided
=over 8
find_effect_chains [ <string:key_1> <string:value_1> ] ...
fec # List all effect chains with their effects.
=back
=head4 B<find_user_effect_chains> (fuec) - List all *user* created effect chains, matching key/value pairs, if provided.
=over 8
find_user_effect_chains [ <string:key_1> <string:value_1> ] ...
=back
=head4 B<bypass_effects> (bypass bfx) - Bypass effects on the current track. With no parameters default to bypassing the current effect.
=over 8
bypass_effects [ <string:effect_id_1> <string:effect_id_2>... | 'all' ]
bypass all # Bypass all effects on the current track, except vol and pan.
bypass AF # Only bypass the effect with the unique ID AF.
=back
=head4 B<bring_back_effects> (restore_effects bbfx) - Restore effects. If no parameter is given, the default is to restore the current effect.
=over 8
bring_back_effects [ <string:effect_id_1> <string:effect_id_2> ... | 'all' ]
bbfx # Restore the current effect.
restore_effect AF # Restore the effect with the unique ID AF.
bring_back_effects all # Restore all effects.
=back
=head4 B<new_effect_profile> (nep) - Create a new effect profile. An effect profile is a named group of effect chains for multiple tracks. Useful for storing a basic template of standard effects for a group of instruments, like a drum kit.
=over 8
new_effect_profile <string:bunch_name> [ <string:effect_profile_name> ]
add_bunch Drums snare toms kick # Create a buch called Drums.
nep Drums my_drum_effects # Create an effect profile, call my_drum_effects
=back
=head4 B<apply_effect_profile> (aep) - Apply an effect profile. this will add all the effects in it to the list of tracks stored in the effect profile. Note: You must give the tracks the same names as in the original project, where you created the effect profile.
=over 8
apply_effect_profile <string:effect_profile_name>
=back
=head4 B<destroy_effect_profile> - Delete an effect profile. This will delete the effect profile definition from your disk. All projects, which use this effect profile will NOT be affected.
=over 8
destroy_effect_profile <string:effect_profile_name>
=back
=head4 B<list_effect_profiles> (lep) - List all effect profiles.
=over 8
list_effect_profiles
=back
=head4 B<show_effect_profiles> (sepr) - List effect profile.
=over 8
show_effect_profiles
=back
=head4 B<full_effect_profiles> (fep) - Dump effect profile data structure.
=over 8
full_effect_profiles
=back
=head2 Track commands
=head4 B<cache_track> (cache ct bounce freeze) - Cache the current track. Same as freezing or bouncing. This
is useful for larger projects or low-power CPUs, since
effects do not have to be recomputed for subsequent engine
runs.
Cache_track stores the effects-processed output of the
current track as a new version (WAV file) which becomes the
current version. The current effects, inserts and region
definition are removed and stored.
To go back to the original track state, use the
uncache_track command. The show_track display appends a "c"
to version numbers created by cache_track (and therefore
reversible by uncache)
=over 8
cache_track [ <float:additional_processing_time> ]
cache 10 # Cache the curent track and append 10 seconds extra time,
=back
=head2 Effect commands
=head4 B<uncache_track> (uncache unc) - Select the uncached track version. This restores effects, but not inserts.
=over 8
uncache_track
=back
=head2 General commands
=head4 B<do_script> (do) - Execute Nama commands from a file in the main project's directory or in the Nama project root directory. A script is a list of Nama commands, just as you would type them on the Nama prompt.
=over 8
do_script <string:filename>
do prepare_my_drums # Execute the script prepare_my_drums.
=back
=head4 B<scan> - Re-read the project's .wav directory. Mainly useful for troubleshooting.
=over 8
scan
=back
=head2 Effect commands
=head4 B<add_fade> (afd fade) - Add a fade-in or fade-out to the current track.
=over 8
add_fade ( in | out ) marks/times (see examples)
fade in mark1 # Fade in,starting at mark1 and using the
# default fade time of 0.5 seconds.
fade out mark2 2 # Fade out over 2 seconds, starting at mark2 .
fade out 2 mark2 # Fade out over 2 seconds, ending at mark2 .
fade in mark1 mark2 # Fade in starting at mark1, ending at mark2 .
=back
=head4 B<remove_fade> (rfd) - Remove a fade from the current track.
=over 8
remove_fade <integer:fade_index_1> [ <integer:fade_index_2> ] ...
list_fade # Print a list of all fades and their tracks.
rfd 2 # Remove the fade with the index (n) 2.
=back
=head4 B<list_fade> (lfd) - List all fades.
=over 8
list_fade
=back
=head2 Track commands
=head4 B<add_comment> (comment ac) - Add a comment to the current track (replacing any previous comment). A comment maybe a short discription, notes on instrument settings, etc.
=over 8
add_comment <string:comment>
ac "Guitar, treble on 50%"
=back
=head4 B<remove_comment> (rc) - Remove a comment from the current track.
=over 8
remove_comment
=back
=head4 B<show_comment> (sc) - Show the comment for the current track.
=over 8
show_comment
=back
=head4 B<show_comments> (sca) - Show all track comments.
=over 8
show_comments
=back
=head4 B<add_version_comment> (avc) - Add a version comment (replacing any previous user comment). This will add a comment for the current version of the current track.
=over 8
add_version_comment <string:comment>
avc "The good take with the clear 6/8"
=back
=head4 B<remove_version_comment> (rvc) - Remove version comment(s) from the current track.
=over 8
remove_version_comment
=back
=head4 B<show_version_comment> (svc) - Show version comment(s) of the curent track.
=over 8
show_version_comment
=back
=head4 B<show_version_comments_all> (svca) - Show all version comments for the current track.
=over 8
show_version_comments_all
=back
=head4 B<set_system_version_comment> (ssvc) - Set a system version comment. Useful for testing and diagnostics.
=over 8
set_system_version_comment <string:comment>
=back
=head2 Midi commands
=head4 B<midish_command> (m) - Send the command text to the midish MIDI sequencer. Midish must be installed and enabled in namarc. See the midish manpage and fullonline documentation for more.
=over 8
midish_command <string:command_text>
m tracknew my_midi_track
=back
=head4 B<midish_mode_on> (mmo) - All users commands sent to midish, until
=over 8
midish_mode_on
=back
=head4 B<midish_mode_off> (mmx) - Exit midish mode, restore default Nama command mode, no midish sync
=over 8
midish_mode_off
=back
=head4 B<midish_mode_off_ready_to_play> (mmxrp) - Exit midish mode, sync midish start (p) with Ecasound
=over 8
midish_mode_off_ready_to_play
=back
=head4 B<midish_mode_off_ready_to_record> (mmxrr) - Exit midish mode, sync midish start (r) with Ecasound
=over 8
midish_mode_off_ready_to_record
=back
=head2 Edit commands
=head4 B<new_edit> (ned) - Create an edit for the current track and version.
=over 8
new_edit
=back
=head4 B<set_edit_points> (sep) - Mark play-start, record-start and record-end positions for the current edit.
=over 8
set_edit_points
=back
=head4 B<list_edits> (led) - List all edits for current track and version.
=over 8
list_edits
=back
=head4 B<select_edit> (sed) - Select an edit to modify or delete. After selection it is the current edit.
=over 8
select_edit <integer:edit_index>
=back
=head4 B<end_edit_mode> (eem) - Switch back to normal playback/record mode. The track will play full length again. Edits are managed via a sub- bus.
=over 8
end_edit_mode
=back
=head4 B<destroy_edit> - Remove an edit and all associated audio files. If no parameter is given, the default is to destroy the current edit. Note: The data will be lost permanently. Use with care!
=over 8
destroy_edit [ <integer:edit_index> ]
=back
=head4 B<preview_edit_in> (pei) - Play the track region without the edit segment.
=over 8
preview_edit_in
=back
=head4 B<preview_edit_out> (peo) - Play the removed edit segment.
=over 8
preview_edit_out
=back
=head4 B<play_edit> (ped) - Play a completed edit.
=over 8
play_edit
=back
=head4 B<record_edit> (red) - Record an audio file for the current edit.
=over 8
record_edit
=back
=head4 B<edit_track> (et) - Set the edit track as the current track.
=over 8
edit_track
=back
=head4 B<host_track_alias> (hta) - Set the host track alias as the current track.
=over 8
host_track_alias
=back
=head4 B<host_track> (ht) - Set the host track (edit sub-bus mix track) as the current track.
=over 8
host_track
=back
=head4 B<version_mix_track> (vmt) - Set the version mix track as the current track.
=over 8
version_mix_track
=back
=head4 B<play_start_mark> (psm) - Select (and move to) play start mark of the current edit.
=over 8
play_start_mark
=back
=head4 B<rec_start_mark> (rsm) - Select (and move to) rec start mark of the current edit.
=over 8
rec_start_mark
=back
=head4 B<rec_end_mark> (rem) - Select (and move to) rec end mark of the current edit.
=over 8
rec_end_mark
=back
=head4 B<set_play_start_mark> (spsm) - Set play_start_mark to the current playback position.
=over 8
set_play_start_mark
=back
=head4 B<set_rec_start_mark> (srsm) - Set rec_start_mark to the current playback position.
=over 8
set_rec_start_mark
=back
=head4 B<set_rec_end_mark> (srem) - Set rec_end_mark to current playback position.
=over 8
set_rec_end_mark
=back
=head4 B<disable_edits> (ded) - Turn off the edits for the current track and playback the original. This will exclude the edit sub bus.
=over 8
disable_edits
=back
=head4 B<merge_edits> (med) - Mix edits and original into a new host-track. this will write a new audio file to disk and the host track will have a new version for this.
=over 8
merge_edits
=back
=head2 Track commands
=head4 B<explode_track> - Make the current track into a sub bus, with one track for each version.
=over 8
explode_track
=back
=head4 B<move_to_bus> (mtb) - Move the current track to another bus. A new track is always in the Main bus. So to reverse this action use move_to_bus Main .
=over 8
move_to_bus <string:bus_name>
asub Drums # Create a new sub bus, called Drums.
snare # Make snare the current track.
mtb Drums # Move the snare track into the sub bus Drums.
=back
=head4 B<promote_version_to_track> (pvt) - Create a read-only track using the specified version of the current track.
=over 8
promote_version_to_track <integer:version_number>
=back
=head2 General commands
=head4 B<read_user_customizations> (ruc) - Re-read the user customizations file 'custom.pl'.
=over 8
read_user_customizations
=back
=head2 Setup commands
=head4 B<limit_run_time> (lr) - Stop recording after the last audio file finishes playing. Can be turned off with limit_run_time_off.
=over 8
limit_run_time [ <float:additional_seconds> ]
=back
=head4 B<limit_run_time_off> (lro) - Disable the recording stop timer.
=over 8
limit_run_time_off
=back
=head4 B<offset_run> (ofr) - Record/play from a mark, rather than from the start, i.e. 0.0 seconds.
=over 8
offset_run <string:mark_name>
=back
=head4 B<offset_run_off> (ofro) - Turn back to starting from 0.
=over 8
offset_run_off
=back
=head2 General commands
=head4 B<view_waveform> (wview) - Launch mhwavedit to view/edit waveform of the current track and version. This requires to start Nama on a graphical terminal, like xterm or gterm or from GNOME via alt+F2 .
=over 8
view_waveform
=back
=head4 B<edit_waveform> (wedit) - Launch audacity to view/edit the waveform of the current track and version. This requires starting Nama on a graphical terminal like xterm or gterm or from GNOME starting Nama using alt+F2 .
=over 8
edit_waveform
=back
=head2 Setup commands
=head4 B<rerecord> (rerec) - Record as before. This will set all the tracks to record, which have been recorded just before you listened back.
=over 8
rerecord
for piano guitar;rec # Set piano and guitar track to record.
# do your recording and ilstening.
# You want to record another version of both piano and guitar:
rerec # Sets piano and guitar to record again.
=back
=head2 Track commands
=head4 B<analyze_level> (anl) - Print Ecasound amplitude analysis for current track. This will show highest volume and statistics.
=over 8
analyze_level
=back
=head2 General commands
=head4 B<for> - Execute command(s) for several tracks.
=over 8
for <string:track_name_1> [ <string:track_name_2>} ... ; <string:commands>
for piano guitar; vol - 3; pan 75 # reduce volume and pan right
for snare kick toms cymbals; mtb Drums # move tracks to bus Drums
=back
=head2 Project commands
=head4 B<git> - Execute git command in the project directory
=over 8
git <string:command_name> [arguments]
=back
=head2 Track commands
=head4 B<edit_rec_setup_hook> (ersh) - Edit the REC hook script for current track
=over 8
edit_rec_setup_hook
=back
=head4 B<edit_rec_cleanup_hook> (erch) - Edit the REC cleanup hook script for current track
=over 8
edit_rec_cleanup_hook
=back
=head4 B<remove_fader_effect> (rffx) - Remove vol pan or fader on current track
=over 8
remove_fader_effect vol | pan | fader
=back
=head4 B<rename_track> - Rename a track and its WAV files
=over 8
rename_track <string:old_track> <string:new_track>
=back
=head2 Sequence commands
=head4 B<new_sequence> (nsq) - Define a new sequence
=over 8
new_sequence <string:name> <track1, track2,...>
=back
=head4 B<select_sequence> (slsq) - Select named sequence as current sequence
=over 8
select_sequence
=back
=head4 B<list_sequences> (lsq) - List all user sequences
=over 8
list_sequences
=back
=head4 B<show_sequence> (ssq) - Display clips making up current sequence
=over 8
show_sequence
=back
=head4 B<append_to_sequence> (asq) - Append items to sequence
=over 8
append_to_sequence [<string:name1>,...]
asq chorus # append chorus track to current sequence
asq # append current track to current sequence
=back
=head4 B<insert_in_sequence> (isq) - Insert items into sequence before index i
=over 8
insert_in_sequence <string:name1> [<string:name2>,...] <integer:index>
=back
=head4 B<remove_from_sequence> (rsq) - Remove items from sequence
=over 8
remove_from_sequence <integer:index1> [<integer:index2>,...]
=back
=head4 B<delete_sequence> (dsq) - Delete entire sequence
=over 8
delete_sequence <string:sequence>
=back
=head4 B<add_spacer> (asp) - Add a spacer to the current sequence, in specified position, or appending (if no position is given)
=over 8
add_spacer <float:duration> [<integer:position>]
=back
=head4 B<convert_to_sequence> (csq) - Convert the current track to a sequence
=over 8
convert_to_sequence
=back
=head4 B<merge_sequence> (msq) - Cache and MON the current sequence mix track, disable the sequence
=over 8
merge_sequence
=back
=head4 B<snip> - Create a sequence from the current track by removing
the region(s) defined by mark pair(s). Not supported if
the current track is already a sequence.
=over 8
snip <mark_pair1> [<mark_pair2>...]
snip cut1-start cut1-end cut2-start cut2-end
This removes cut1 and cut2 regions from the current track
by creating a sequence.
=back
=head4 B<compose> (compose_sequence compose_into_sequence) - Compose a new sequence using the region(s) of the named track
defined by mark pair(s). If the sequence of that name exists,
append the regions to that sequence (compose_into_sequence).
=over 8
compose <string:sequence_name> <string:trackname> <mark_pair1> [<mark_pair2>...]
compose speeches conference-audio speaker1-start speaker1-end
speaker2-start speaker2-end
This creates a "speeches" sequence with two clips
for speaker1 and speaker2.
=back
=head2 General commands
=head4 B<undo> - Roll back last commit (use "git log" to see specific commands)
Note: redo is not supported yet
=over 8
undo
=back
=head4 B<redo> - Restore the last undone commit (TODO)
=over 8
redo
=back
=head4 B<show_head_commit> (show_head last_command last) - Show the last commit, which undo will roll back.
A commit may contain multiple commands.
The last_* aliases are meaningful when autosave: undo is set.
In that case each commit contains only a single command
=over 8
show_head_commit
=back
=head2 Mode commands
=head4 B<eager> - Set eager mode
=over 8
eager on | off
=back
=head2 Engine commands
=head4 B<new_engine> (neg) - Start a named Ecasound engine, or bind to an existing engine
=over 8
new_engine <string:engine_name> <integer:port>
=back
=head4 B<select_engine> (seg) - Select an ecasound engine (advanced users only!)
=over 8
select_engine <string:engine_name>
=back
=head2 Track commands
=head4 B<set_track_engine_group> (steg) - Set the current track's engine affiliation
=over 8
set_track_engine_group <string:engine_name>
=back
=head2 Bus commands
=head4 B<set_bus_engine_group> (sbeg) - Set the current bus's engine affiliation
=over 8
set_bus_engine_group <string:engine_name>
=back
=head4 B<select_submix> (ssm) - Set the target for the trim command
=over 8
select_submix <string:submix_name>
=back
=head4 B<trim_submix> (trim tsm) - Control a submix fader
=over 8
trim_submix
# reduce vol of current track in in_ear_monitor by 3dB
select_submix in_ear_monitor
trim vol - 3
=back
=head2 Effect commands
=head4 B<nickname_effect> (nfx nick) - Add a nickname to the current effect (and create an alias)
=over 8
nickname_effect <lower_case_string:nickname>
add_track guitar
afx Plate
nick reverb # current effect gets name "reverb1"
mfx reverb1 1 0.05 # modify first reverb effect on current track
mfx reverb 1 2 # works, because current track has one effect named "reverb"
afx reverb # add another Plate effect, gets name "reverb2"
rfx reverb # Error, multiple reverb effects are present on this
# track. Please use a numerical suffix.
mfx reverb2 1 3 # modify second reverb effect
rfx reverb1 # removes reverb1
ifx reverb2 reverb # insert another reverb effect (reverb3) before reverb2
rfx reverb3 # remove reverb3
rfx reverb # removes reverb2, as it is the sole remain reverb effect
=back
=head4 B<delete_nickname_definition> (dnd) - Delete a nickname definition. Previously named effects keep their names.
=over 8
delete_nickname_definition
afx Plate # add Plate effect
nick reverb # name it "reverb", and create a nickname for Plate
dnd reverb # removes nickname definition
afx reverb # error
=back
=head4 B<remove_nickname> (rnick) - Remove the "name" attribute of the current effect
=over 8
remove_nickname
afx Plate
nick reverb
mfx reverb 1 3
rnick
mfx reverb 1 3 # Error: effect named "reverb" not found on current track
=back
=head4 B<list_nickname_definitions> (lnd) - List defined nicknames
=over 8
list_nickname_definitions
=back
=head4 B<set_effect_name> (sen) - Set a nickname only (don't creating an alias)
=over 8
set_effect_name <string:name>
=back
=head4 B<set_effect_surname> (ses) - Set an effect surname
=over 8
set_effect_surname <string:surname>
=back
=head4 B<remove_effect_name> (ren) - Remove current effect name
=over 8
remove_effect_name
=back
=head4 B<remove_effect_surname> (res) - Remove current effect surname
=over 8
remove_effect_surname
=back
=head2 Track commands
=head4 B<select_track> - Set a particular track as the current, or default track
against which track-related commands are executed.
=over 8
select_track <string:track-name> | <integer:track-number>
=back
=head1 REALTIME OPERATION
Nama selects realtime or nonrealtime parameters based on the
B<realtime_profile>, B<ecasound_buffersize> and
B<ecasound_globals> fields in F<.namarc>. You can
optionally specify the buffersizes as a multiple of the JACK
period size. Note that for best realtime operation under
JACK you will have to configure jackd appropriately as well.
The B<realtime> and B<auto> profiles are useful when using
Nama/Ecasound for live fx processing or live monitoring.
The B<realtime> profile sets a small buffersize and other low
latency settings whenever a soundcard or JACK client is
connected.
The B<nonrealtime> profile uses a bigger buffer, providing
extended margins for stable operation. It is suitable for
post-processing, or for recording without live monitoring
responsibilities.
The B<auto> profile defaults to nonrealtime settings. It
switches to realtime, low-latency settings when a track has
a live input.
=head1 DIAGNOSTICS
On any change in setup, the GUI display updates and
C<show_tracks> command is executed automatically showing
what to expect the next time the engine is started.
You can use the C<chains> command to verify the Ecasound
chain setup. (The Ecasound command C<cs-save-as mysetup.ecs>
will additionally store all engine data, effects as
well as routing.)
The C<dump> command displays data for the current track.
The C<dumpall> command shows all state that would be saved.
This is the same output that is written to the F<State.yml>
file when you issue the C<save> command.
=head1 BUGS AND LIMITATIONS
No latency compensation across signal paths is provided at
present. This feature is under development.
=head1 SECURITY CONCERNS
If you are using Nama with the NetECI interface (i.e. if
Audio::Ecasound is I<not> installed) you should block TCP
port 2868 if your computer is exposed to the Internet.
=head1 INSTALLATION
The following commands, available on Unixlike systems with
Perl installed, will pull in Nama and other Perl libraries
required for text mode operation:
C<cpanm Audio::Nama>
-or-
C<PERL_MM_USE_DEFAULT=1 cpan Audio::Nama>
To use the GUI, you will need to install Tk:
C<cpanm Tk>
You may want to install Audio::Ecasound if you prefer not to
run Ecasound in server mode:
C<cpanm Audio::Ecasound>
You can pull the source code as follows:
C<git clone git://github.com/bolangi/nama.git>
Consult the F<BUILD> file for build instructions.
=head1 SUPPORT
The Nama mailing list is a suitable forum for questions
regarding Nama installation, usage, bugs, feature requests, etc.
http://www.freelists.org/list/nama
For questions and discussion related to Ecasound
https://lists.sourceforge.net/lists/listinfo/ecasound-list
=head1 PATCHES
The modules that make up this application are the
preprocessed output from several source files. Patches
against these source files are preferred.
=head1 AUTHOR
Joel Roth, E<lt>joelz@pobox.comE<gt>
=head1 CONTRIBUTORS
Alex Stone
Brett McCoy
Dubphil
F. Silvain ++
Joy Bausch
Julien Claassen ++
Kevin Utter
Lars Bjørndal
Philippe Schelté
Philipp Überbacher
Raphaël Mouneyres ++
Rusty Perez
S. Massy ++
=head1 COPYRIGHT & LICENSE
Copyright (c) 2009-2013 by Joel Roth.
This is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License,
Version 3.