#!/usr/bin/env perl
require 5.10.1;
use Audio::Nama;
Audio::Nama::main();
__END__
=head1 NAME

B<Nama> - Ecasound-based recorder, mixer and mastering system

=head1 SYNOPSIS

B<nama> [I<options>] [I<project_name>]

=head1 DESCRIPTION

B<Nama> is an application for multitrack recording,
non-destructive editing, mixing and mastering using the
Ecasound audio engine developed by Kai Vehmanen.
Primarily text-based, it also has a simple Tk based GUI.
 
Features include tracks with multiple versions (AKA takes)
buses, effects, presets, sends, inserts, marks, regions,
edits, templates and user-defined commands. Nama runs under
JACK and ALSA audio frameworks, automatically detects LADSPA
plugins, and supports Ladish Level 1 session handling.

Nama's audio processing is non-destructive by default:
effects are applied in realtime; edits are accomplished
through crossfades. These modifications to a track can be
frozen as a new version for that track.
 
The command prompt accepts Nama commands, Ecasound
interactive-mode commands, shell commands and perl code,
with command history and autocompletion.  The help
system provides documentation and keyword search 
covering Nama commands and effects.

By default, Nama displays a simple graphic interface while
the command processor runs in a terminal window. The B<-t>
option provides a text-only interface for console users.

=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.
After lauching the engine, realtime control capabilities are
available, for example to adjust effect parameters and set playback
position.

Nama serves as an intermediary, taking high-level commands
from the user, generating appropriate chain setups for
recording, playback, mixing, etc. and running the audio
engine.

=head2 Static Commands

Static commands affect I<future> runs of the audio engine.
For example, B<rec, mon> and B<off> determine whether the
current track will get its audio stream from an external
(usually live) source or whether an existing WAV file will
be played back. Nama responds to static commands by
automatically reconfiguring the engine and displaying the
updated track status.

=head2 Dynamic Commands

Once a chain setup is loaded and the engine is launched,
another set of commands controls the realtime behavior of
the audio processing engine. Commonly used I<dynamic
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 only (yellow) or playback only (green).  Live
recording and mixdown can take place simultaneously.

=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.

=head2 Terminal Window 

The command prompt appears 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 sub-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.

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/MON/OFF

Track REC/MON/OFF status guides audio processing.

Each track, including Master and Mixdown, has its own
REC/MON/OFF setting and displays its own REC/MON/OFF status.
Each bus also has REC, MON and OFF settings that
influence the behavior of user tracks.

=head3 Track status

As the name suggests, I<REC> status indicates that a track
is ready to record a WAV file. 

I<MON> status indicates an audio stream is available from
disk. This status requires the presence of a file matching
the bus or track version number, if specified. A track set
to REC with no live input will default to MON status.

I<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.

=head3 Bus setting

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 bus REC setting is obsolete, now equivalent to MON.) 

The B<mixplay> command sets the Mixdown track to MON and the
Main bus to OFF.

=head2 Version Number

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
sub-buses. If you have sub-buses you must set bus version 
numbers for each separately if desired.

=head2 Marks

Marks in Nama are similar to those in other audio editing
software, with one small caveat: 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. Use the C<shift> command
to specify a delay for starting playback.

Each track can have one region definition. For multiple
regions, the C<new_region> command takes a pair of marks to
create a read-only copy of the current track with 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 after pan 
volume controls.  You can position effects anywhere you choose
using C<insert_effect>.

=head3 Fades

Nama allows you to place fades on any track. Fades are
logarithmic, defined by a mark position and a 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

=item B<REC>, B<MON>, B<OFF>

All tracks with the corresponding I<status> in the current bus

=back

=head2 Buses

=head3 Sub Buses

B<Sub buses> enable multiple tracks to be routed through a
single mix track before feeding the main mixer bus (or
possibly another sub bus.) 

The following commands create a sub 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 feeding a mix track named Strings
	add_sub_bus Strings 

	# create tracks for the sub-bus
	add_tracks violin cello bass

	# move the tracks from the Main bus (default) to the Strings bus
	for violin cello bass; set bus Strings

	# use the mix track to control bus output volume
	Strings vol - 10

=head3 Send Buses

B<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 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.

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.

=head2 Flow Diagrams

Let's examine the signal flow from track 3, the first 
available user track. Assume track 3 is named "sax".

We will divide the signal flow into track and mixer
sections.  Parentheses 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<Main 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 Preview and Doodle Modes

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 MON inputs while enabling only one REC track per
signal source. The C<arm> command releases both preview
and doodle modes.

=head2 Saving Projects

The C<save> command is the usual way to save your work.
Settings related to the state of the current mix
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
and track comments) 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.

C<save somename.json> save to a file of that
name.  Similarly C<get somename.json> will load the
corresponding file. The F<.json> suffix may be omitted if
git is disabled in F<.namarc>.

=head3 Requirements to Use Git for saving projects

To use git for version control, you must have git installed and, 
"use_git: 1" must be set in F<.namarc>.

=head3 Standard git commands

You can issue git commands in the normal way,
and Nama will stay out of your way. Note that
merging of branches is untested.

=head3 Simplified Workflow Using Git to Manage Project State

Use the C<save> command periodically. On each save command,
changes to F<State.json> will be committed to the
repository.  The commit message will include a list of
commands executed since the previous commit.

The C<save> and C<get> commands for branches behave in a
similar way to save/restore of named files. 

You can say C<save initial-mix> and C<get initial-mix> 
and have them behave as expected, without being
familiar with Git.

What actually happens: C<save initial-mix> will save project
state to F<State.json>, commit changes to that file to the
git repository, and tag current branch's HEAD commit as
"initial-mix". The current branch does not change, remains
in the default branch, "master". 

Later on, on typing C<get initial-mix>, Nama automatically
promotes the tagged commit "initial-mix" to a branch named
"initial-mix-branch" which becomes the current branch.

If you want to start a new branch 
at tag "initial-mix" you can say this: 

C<new_branch compressed-mix initial-mix

=head2 Exiting

When you type C<quit> Nama will automatically save your work
to F<State.json>. This will overwrite previous settings in
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 ports> or I<source filename.ports> to ask Nama
to connect multiple JACK ports listed in a file
(F<trackname.ports> or F<filename.ports>) to the input
ports for that track, which will be set to
I<ecasound:trackname_in_1> for mono. A stereo track will
use I<ecasound:trackname_in_2> as well.

If the track is stereo, ports from the list are alternately
connected to left and right channels. Larger numbers
of channels are handled similarly.

=head2 Track edits

An edit is an audio clip 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
sub-bus. Sources for the bus are the original audio track, and
zero or more edits, each represented by one track object.

=head1 TEXT COMMANDS

=head2 Help commands

=head4 B<help> (h) - Display help on Nama commands.

=over 8

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

C<help marks 
help 6 
help mfx 
>



=back

=head4 B<help_effect> (hfx he) - Display detailed help on a LADSPA or LV2 effect or ask a note to consult the Ecasound manpage for Ecasound's internal effects. For LADSPA and LV2 effects use either the analyseplugin oder analyselv2.

=over 8

C<help_effect> <s_label> | <i_unique_id>

C<help_effect 1970 
he etd 
hfx lv2-vocProc 
>



=back

=head4 B<find_effect> (ffx fe) - Display one-line help for effects matching the search string(s).

=over 8

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

C<find_effect compressor 
fe feedback 
>



=back

=head2 General commands

=head4 B<exit> (quit q) - Exit Nama, saving settings (the current project).

=over 8

C<exit> 

=back

=head4 B<memoize> - Enable WAV directory caching, so Nama won't have to scan the entire project folder for new fiels after every run.

=over 8

C<memoize> 

=back

=head4 B<unmemoize> - Disable WAV directory caching.

=over 8

C<unmemoize> 

=back

=head2 Transport commands

=head4 B<stop> (s) - Stop transport. Stop the engine, when recording or playing back.

=over 8

C<stop> 

C<rec 
start 
stop 
>



=back

=head4 B<start> (t) - Start transport. Start the engine, to start recording or playing back.

=over 8

C<start> 

C<doodle 
start 
stop 
>



=back

=head4 B<getpos> (gp) - Get the current playhead position (in seconds).

=over 8

C<getpos> 

C<start 
gp 
>



=back

=head4 B<setpos> (sp) - Set current playhead position (in seconds).

=over 8

C<setpos> <f_position_seconds>

C<setpos 65.0>



=back

=head4 B<forward> (fw) - Move playback position forwards (in seconds). Oldschool forwarding.

=over 8

C<forward> <f_increment_seconds>

C<fw 23.7>



=back

=head4 B<rewind> (rw) - Move playback position backwards (in seconds). Oldschool rewind.

=over 8

C<rewind> <f_decrement_seconds>

C<rewind 6.5>



=back

=head4 B<to_start> (beg) - Set the playback head to the start. A synonym for setpos 0.0 .

=over 8

C<to_start> 

=back

=head4 B<to_end> (end) - Set the playback head to end minus 10 seconds.

=over 8

C<to_end> 

=back

=head4 B<ecasound_start> (T) - Ecasound-only start. Mainly useful for diagnostics and debugging. Use the command start in normal circumstances.

=over 8

C<ecasound_start> 

=back

=head4 B<ecasound_stop> (S) - Ecasound-only stop. Mainly useful for diagnostics and debugging. Use command stop in normal circumstances.

=over 8

C<ecasound_stop> 

=back

=head4 B<restart_ecasound> - Restart the Ecasound application again, when it has crashed or is behaving oddly.

=over 8

C<restart_ecasound> 

=back

=head4 B<preview> - Enter the preview mode. Configure Nama to allow playback and passthru of inputs (for mic test, rehearsals, etc.). Nothing is recorded to disk!

=over 8

C<preview> 

C<rec 
preview 
start 
stop 
arm 
>



=back

=head4 B<doodle> - Enter the doodle mode. In doodle mode all live inputs from tracks - set to record - are enabled. Nama excludes multiple tracks having the same input. This mode is designed to allow rehearsing and adjusting effects without listening to playback -as in preview.

=over 8

C<doodle> 

C<doodle 
start 
stop 
arm 
>



=back

=head2 Mix commands

=head4 B<mixdown> (mxd) - Enter mixdown mode for subsequent engine runs. You will record new mixes, until you leave mixdown mode by mixoff.

=over 8

C<mixdown> 

C<mxd 
t 
mxo 
>



=back

=head4 B<mixplay> (mxp) - Enter mixdown file playback mode, setting user tracks to OFF and only playing the Mixdown track. You can leave the mixplay mode by using mixoff.

=over 8

C<mixplay> 

C<mixplay 
start 
stop 
mxo 
>



=back

=head4 B<mixoff> (mxo) - Leave the mixdown or mixplay mode. Set Mixdown track to OFF, user tracks to MON.

=over 8

C<mixoff> 

=back

=head4 B<automix> - Normalize track volume levels and fix DC-offsets. Then mix dwn to the Mixdown track.

=over 8

C<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. Leave the mastering mode by master_off.

=over 8

C<master_on> 

C<mr 
start 
stop 
>



=back

=head4 B<master_off> (mro) - Leave mastering mode. Remove the EQ, multi-band compression and Booster.

=over 8

C<master_off> 

=back

=head2 Track commands

=head4 B<add_track> (add new) - Create a new audio track.

=over 8

C<add_track> <s_name>

C<add_track clarinet 
>



=back

=head4 B<add_tracks> - Create one or more new tracks in one go.

=over 8

C<add_tracks> <s_name1> [ <s_name2>... ]

C<add_tracks violin viola contra_bass>



=back

=head4 B<link_track> (link) - Create a read-only track, that uses audio files from another track.

=over 8

C<link_track> <s_dest_name> <s_source_name> [ <s_project> ]

C<link part_1 Mixdown my_long_song_1 
link_track piano_conp piano 
>



=back

=head4 B<import_audio> (import) - Import a sound file (wav, ogg, mp3, etc.) to the current track, resampling it, if necessary.

=over 8

C<import_audio> <s_full_path_to_file> [ <i_frequency> ]

C<import /home/samples/bells.flac 
import /home/music/song.mp3 44100 
>



=back

=head4 B<set_track> - Directly set current track parameters (use with care!).

=over 8

C<set_track> <s_track_field> <value>

=back

=head4 B<record> (rec) - Set current track to record from its input (also known as REC-enabling).

=over 8

C<record> 

C<rec 
start 
stop 
>



=back

=head4 B<mon> (on) - Set current track to playback the currently selected version. by default the last version is always played.

=over 8

C<mon> 

C<mon>



=back

=head4 B<off> (z) - Set current track to OFF (exclude from setup). You can include the track with mon or rec.

=over 8

C<off> 

=back

=head4 B<rec_defeat> (rd) - Prevent writing an audio file for the current track. So the track will just pass thru the incoming audio. Useful for tracks connected to internal signal generators.

=over 8

C<rec_defeat> 

=back

=head4 B<rec_enable> (re) - Allow writing an audio file for the current track. This is the opposite to rec_defeat. Useful to record a metronome or other special track to disk.

=over 8

C<rec_enable> 

=back

=head4 B<source> (src r) - Set the current track's input (source). This can be a soundcard channel or a JACK client name.

=over 8

C<source> <i_soundcard_channel> | 'null' | <s_jack_client_name> | <s_jack_port_name> | 'jack'

C<source 3 
source null 
src LinuxSampler 
r synth:output_3 
src jack 
>



=back

=head4 B<send> (aux) - Set an aux send for the current track. Remove sends with remove_send .

=over 8

C<send> <i_soundcard_channel> | <s_jack_client_name> | <s_loop_id>

C<send 3 
send jconvolver 
>



=back

=head4 B<remove_send> (nosend noaux) - Remove an aux send from the current track.

=over 8

C<remove_send> 

=back

=head4 B<stereo> - Set the current track to stereo (two channels). Will record two channels or easily import stereo audio files.

=over 8

C<stereo> 

=back

=head4 B<mono> - Set the current track to mono (one channel). Will record one channel or easily import mono audio files (this is the default, when creating a track).

=over 8

C<mono> 

=back

=head4 B<set_version> (version ver) - Set the active version of the current track for playback/monitoring (overrides group version setting).

=over 8

C<set_version> <i_version_number>

C<piano 
version 2 
sh 
>



=back

=head4 B<destroy_current_wav> - DESTRUCTIVE: Remove the current track\'s currently selected recording. This removes the underlying  audio file on your disk. USE WITH CARE!

=over 8

C<destroy_current_wav> 

=back

=head4 B<list_versions> (lver) - List versions of the current track. This will print the numbers of all versions of this track to the screen.

=over 8

C<list_versions> 

C<list_versions 
>



=back

=head4 B<vol> (v) - Change or show the current track's volume.

=over 8

C<vol> [ [ + | - | / | * ] <f_volume> ]

C<vol * 1.5 
vol 75 
vol - 5.7 
vol 
>



=back

=head4 B<mute> (c cut) - Mute the current track. Turn the current track's volume absolutely down. You can unmute the track with the command unmute.

=over 8

C<mute> 

=back

=head4 B<unmute> (C uncut) - Restore previous volume level. It can be used after mute or solo.

=over 8

C<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

C<unity> 

C<vol 55 
unity 
vol 
>



=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

C<solo> [ <strack_name_1> | <s_bunch_name_1> ] [ <s_track_name_2 | <s_bunch_name_2> ] ...

C<solo 
nosolo 
solo piano bass Drums 
>



=back

=head4 B<nosolo> (nsl) - Unjute all tracks, which have been turned down by solo. Tracks, that had beenmuted before the solo command stay muted.

=over 8

C<nosolo> 

=back

=head4 B<all> - Unmute all tracks, this includes tracks muted by solo and other single tracks muted previously by mute.

=over 8

C<all> 

C<piano 
mute 
sax 
solo 
all 
>



=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

C<pan> [ <f_pan_position_in_percent> ]

C<pan 75 
p 50 
pan 
>



=back

=head4 B<pan_right> (pr) - Pan the current track hard right. this is a synonym for pan 100 . Can be reverse with pan_back .

=over 8

C<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

C<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

C<pan_center> 

=back

=head4 B<pan_back> (pb) - Restore the current track's pan position prior to pan_left, pan_right or pan_center .

=over 8

C<pan_back> 

=back

=head4 B<show_tracks> (lt show) - Show a list of tracks, including their index number, volume, pan position, recording status and input.

=over 8

C<show_tracks> 

=back

=head4 B<show_tracks_all> (sha showa) - Show a list of all tracks, visible and hidden, with their ndex number, recording status, input, volume and pan position. This is mainly useful for diagnostics and debugging.

=over 8

C<show_tracks_all> 

=back

=head4 B<show_bus_tracks> (ltb showb) - Show a list of tracks in the current bus.

=over 8

C<show_bus_tracks> 

=back

=head4 B<show_track> (sh) - Display information about the current track, including index, recording status, effects, inserts, versions, stereo width (a.k.a. channel count) and controllers.

=over 8

C<show_track> 

=back

=head2 Setup commands

=head4 B<show_mode> (shm) - Display the current record/playback mode. this will indicate the mode - i.e. doodle, preview, etc. - and possible record/playback settings.

=over 8

C<show_mode> 

=back

=head2 Track commands

=head4 B<show_track_latency> (shl) - Display the latency information for the current track.

=over 8

C<show_track_latency> 

=back

=head2 Diagnostics commands

=head4 B<show_latency_all> (shla) - Dump all latency data.

=over 8

C<show_latency_all> 

=back

=head2 Track commands

=head4 B<set_region> (srg) - Specify a playback region for the current track using marks. Use the command new_region to create more than one region from a track. Can be reversed with remove_region .

=over 8

C<set_region> <s_start_mark_name> <s_end_mark_name>

C<sax 
setpos 2.5 
mark sax_start 
sp 120.5 
mark sax_end 
set_region sax_start sax_end 
>



=back

=head4 B<add_region> (arg) - Create a region for the current track using an auxiliary track. This is a named region, which leaves the original track visible and untouched.

=over 8

C<add_region> <s_start_mark_name> | <f_start_time> <s_end_mark_name> | <f_end_time> [ <s_region_name> ]

C<sax 
new_region sax_start 66.7 trimmed_sax 
>



=back

=head4 B<remove_region> (rrg) - Remove the current region (including associated the auxiliary track).

=over 8

C<remove_region> 

=back

=head4 B<shift_track> (shift playat pat) - Move the beginning of the track or region, also known as offsetting or shifting. Can be reversed by unshift_track .

=over 8

C<shift_track> <s_start_mark_name> | <i_start_mark_index | <f_start_seconds>

C<piano 
shift 6.7 
>



=back

=head4 B<unshift_track> (unshift) - Move the start of a track or region back to 0.0 seconds (the beginning of the setup.

=over 8

C<unshift_track> 

=back

=head4 B<modifiers> (mods mod) - Add/show modifiers for the current track (man ecasound for details). This is only useful in rare cases.

=over 8

C<modifiers> [ Audio file sequencing parameters ]

C<modifiers select 5 15.2 
>



=back

=head4 B<nomodifiers> (nomods nomod) - Remove modifiers from the current track.

=over 8

C<nomodifiers> 

=back

=head4 B<normalize> (norm ecanormalize) - Apply ecanormalize to the current track version. This will raise the gain/volume of the current track as far as possible and store it that way on disk. Note: this will permanently change the file.

=over 8

C<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

C<fixdc> 

=back

=head4 B<autofix_tracks> (autofix) - Apply the commands fixdc and normalize to all current version of all tracks, that are set to playback, i.e. MON .

=over 8

C<autofix_tracks> 

=back

=head4 B<remove_track> - Remove the current track. This will only remove the effects and display. all recorded audio will emain on your disk. The default is to ask, before Nama removes a track. this can be changed in namarc .

=over 8

C<remove_track> 

=back

=head2 Bus commands

=head4 B<bus_rec> (brec grec) - Set a bus mix_track to record (the default behaviour).

=over 8

C<bus_rec> 

=back

=head4 B<bus_mon> (bmon gmon) - Set a bus mix_track to playback. This only does anything, if a complete bus has been cached/frozend/bounced before.

=over 8

C<bus_mon> 

=back

=head4 B<bus_off> (boff goff) - Set a bus mixtrack to OFF. Can be reversed with bus_rec and bus_mon.

=over 8

C<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

C<bus_version> 

=back

=head4 B<add_bunch> (abn) - Define a bunch of tracks. A bunch is useful for shorter for statements.

=over 8

C<add_bunch> <s_bunch_name> [ <s_track_name_1> | <i_track_index_1> ] ...

C<new_bunch woodwind 
nb strings violin cello basso 
for strings;mute 
for strings;vol * 0.8 
>



=back

=head4 B<list_bunches> (lbn) - Dispaly a list of all bunches and their tracks.

=over 8

C<list_bunches> 

=back

=head4 B<remove_bunch> (rbn) - Remove the specified bunches. This does not remove the tracks, only the groupings.

=over 8

C<remove_bunch> <s_bunch_name> [ <s_bunch_name> ] ...

=back

=head4 B<add_to_bunch> (atbn) - Add track(s) to a bunch.

=over 8

C<add_to_bunch> <s_bunch_name> <s_track1> [ <s_track2> ] ...

C<add_to_bunch woodwind oboe sax_1 flute 
>



=back

=head2 Project commands

=head4 B<commit> (ci) - Commit Nama's current state

=over 8

C<commit> <s_message>

=back

=head4 B<tag> - Git tag the current branch HEAD commit

=over 8

C<tag> <s_tag_name> [<s_message>]

=back

=head4 B<branch> (br) - Change to named branch

=over 8

C<branch> <s_branch_name>

=back

=head4 B<list_branches> (lb lbr) - List branches when called with no arguments

=over 8

C<list_branches> <s_branch_name>

=back

=head4 B<new_branch> (nbr) - Create a new branch

=over 8

C<new_branch> <s_new_branch_name> [<s_existing_branch_name>]

=back

=head4 B<save_state> (keep save) - Save the project settings as file or tagged commit

=over 8

C<save_state> [ <s_settings_target> [ <s_message> ] ]

=back

=head4 B<get_state> (get recall retrieve) - Retrieve project settings from file, branch or tag

=over 8

C<get_state> <s_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

C<list_projects> 

=back

=head4 B<new_project> (create) - Create or open a new empty Nama project.

=over 8

C<new_project> <s_new_project_name>

C<create my_song>



=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 teh project and then use get_state.

=over 8

C<load_project> <s_existing_project_name>

C<load my_old_song>



=back

=head4 B<project_name> (project name) - Display the name of the current project.

=over 8

C<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

C<new_project_template> <s_template_name> [ <s_template_description> ]

C<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

C<use_project_template> <s_template_name>

C<apt my_band_setup 
>



=back

=head4 B<list_project_templates> (lpt) - List all project templates.

=over 8

C<list_project_templates> 

=back

=head4 B<destroy_project_template> - Remove one or more project templates.

=over 8

C<destroy_project_template> <s_template_name1> [ <s_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

C<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

C<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

C<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

C<connect> 

=back

=head4 B<disconnect> (dcon) - Disconnect the setup. If running with JACK, this will disconnect from all JACK ports.

=over 8

C<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

C<show_chain_setup> 

=back

=head4 B<loop> (l) - Loop the playback between two points. Can be stopped with loop_disable

=over 8

C<loop> <s_start_mark_name> | <i_start_mark_index> | <f_start_time_in_secs> <s_end_mark_name> | <i_end_mark_index> | <f_end_time_in_secs>

C<loop 1.5 10.0 
loop 1 5 
loop sax_start 12.6 
>



=back

=head4 B<noloop> (nl) - Disable looping.

=over 8

C<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 remove using rfx.

=over 8

C<add_controller> [ <s_operator_id> ] <s_effect_code> [ <f_param1> <f_param2> ] ...

C<add_effect etd 100 2 2 50 50 
acl E klg 1 100 200 2 0 100 15 200 
>



=back

=head4 B<add_effect> (afx) - Add an effect prefader (before vol/pan controls) to the current track. Remove effects with reove_effect.

=over 8

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

C<help_effect decimator 
afx decimator 12 22050 
>



=back

=head4 B<append_effect> (apfx) - Add an effect postfader (after vol/pan conrols) to the current track. Remove effect with remove_effect.

=over 8

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

C<apfx var_dali 
>



=back

=head4 B<insert_effect> (ifx) - Place an effect before the specified unique effect ID. You will experience a short pause in playback.

=over 8

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

C<lfx 
ifx AF etd 125 2 2 40 60 
>



=back

=head4 B<modify_effect> (mfx modify_controller mcl) - Modify effect parameter(s).

=over 8

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

C<lfx 
mfx AF 1 62 
mfx AF,BG 1 75 
mfx CE 6,10 -3 
mfx D 4 + 10 
mfx A,B,C 3,6 * 5 
>



=back

=head4 B<remove_effect> (rfx remove_controller rcl) - Remove effects. They don't have to be on the current track.

=over 8

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

=back

=head4 B<position_effect> (pfx) - Position an effect before another effect (use 'ZZZ' for end).

=over 8

C<position_effect> <s_id_to_move> <s_position_id>

C<position_effect G F 
>



=back

=head4 B<show_effect> (sfx) - Show information about an effect. Default is to print information on the current effect.

=over 8

C<show_effect> [ <s_effect_id1> ] [ <s_effect_id2> ] ...

C<sfx 
sfx H 
>



=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

C<list_effects> 

=back

=head4 B<add_insert> (ain) - Add an external send/return insert to current track.

=over 8

C<add_insert> ( pre | post ) <s_send_id> [ <s_return_id> ] -or- local (for wet/dry control)

C<add_insert pre jconvolver 
ain post jconvolver csound 
guitar 
ain local 
guitar-1-wet 
afx G2reverb 50 5.0 0.6 0.5 0 -16 -20 
afx etc 6 100 45 2.5 
guitar 
wet 25 
>



=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

C<set_insert_wetness> [ pre | post ] <n_wetness>

C<wet pre 50 
set_insert_wetness 100 
>



=back

=head4 B<remove_insert> (rin) - Remove an insert from the current track.

=over 8

C<remove_insert> [ pre | post ]

C<rin 
remove_insert post 
>



=back

=head4 B<ctrl_register> (crg) - List all Ecasound controllers. Controllers include linear controllers and oscillators.

=over 8

C<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

C<preset_register> 

=back

=head4 B<ladspa_register> (lrg) - List all LADSPA plugins, that Ecasound/Nama can find.

=over 8

C<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

C<list_marks> 

=back

=head4 B<to_mark> (tmk tom) - Move the playhead to the named mark or mark index.

=over 8

C<to_mark> <s_mark_name> | <i_mark_index>

C<to_mark sax_start 
tmk 2 
>



=back

=head4 B<add_mark> (mark amk) - Drop a new mark at the current playback position. this will fail, if a mark is already placed on that exact position.

=over 8

C<add_mark> [ <s_mark_id> ]

C<k important 
>



=back

=head4 B<remove_mark> (rmk rom) - Remove a mark. The default is to remove the current mark, if no parameter is given.

=over 8

C<remove_mark> [ <s_mark_name> | <i_mark_index> ]

C<remove_mark important 
rmk 16 
>



=back

=head4 B<next_mark> (nmk) - Move the playhead to the next mark.

=over 8

C<next_mark> 

=back

=head4 B<previous_mark> (pmk) - Move the playhead to the previous mark.

=over 8

C<previous_mark> 

=back

=head4 B<name_mark> - Give a name to the current mark.

=over 8

C<name_mark> <s_mark_name>

=back

=head4 B<modify_mark> (move_mark mmk) - Change the position (time) of the current mark.

=over 8

C<modify_mark> [ + | - ] <f_seconds>

C<move_mark + 2.3 
mmk 16.8 
>



=back

=head2 Diagnostics commands

=head4 B<engine_status> (egs) - Display the Ecasound audio processing engine status.

=over 8

C<engine_status> 

=back

=head4 B<dump_track> (dump) - Dump current track data.

=over 8

C<dump_track> 

=back

=head4 B<dump_group> (dumpg) - Dump group settings for user tracks.

=over 8

C<dump_group> 

=back

=head4 B<dump_all> (dumpa) - Dump most internal state data.

=over 8

C<dump_all> 

=back

=head4 B<dump_io> - Show chain inputs and outputs.

=over 8

C<dump_io> 

=back

=head2 Help commands

=head4 B<list_history> (lh) - List the command history. Every project stores its own command history.

=over 8

C<list_history> 

=back

=head2 Bus commands

=head4 B<add_send_bus_cooked> (asbc) - Add a send bus, that copies all user tracks with effects and inserts (a.k.a. cooked signals). All busses begin with a capital letter!

=over 8

C<add_send_bus_cooked> <s_name> <destination>

C<asbc Reverb jconv 
>



=back

=head4 B<add_send_bus_raw> (asbr) - Add a send bus, that copies all user tracks wihtout processing (a.k.a. raw signals). All busses begin with a capital letter!

=over 8

C<add_send_bus_raw> <s_name> <destination>

C<asbr Reverb jconv 
>



=back

=head4 B<add_sub_bus> (asub) - 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

C<add_sub_bus> <s_name> [ <s_track_name> | <s_jack_client> | <i_soundcard_channel> ]

C<asub Brass 
asub special csound 
>



=back

=head4 B<update_send_bus> (usb) - Include tracks added since the send bus was created.

=over 8

C<update_send_bus> <s_name>

C<update_send_bus Reverb 
>



=back

=head4 B<remove_bus> - Remove a bus.

=over 8

C<remove_bus> <s_bus_name>

=back

=head4 B<list_buses> (lbs) - List buses and their parameters (TODO).

=over 8

C<list_buses> 

=back

=head4 B<set_bus> (sbs) - Set bus parameters. This command is intended for advanced users.

=over 8

C<set_bus> <s_busname> <key> <value>

=back

=head2 Effect commands

=head4 B<new_effect_chain> (nec) - Create a new effect chain. An effect chain i a list of effects with all their parameters stored. Useful for creating small processing templates for frequently used instruments.

=over 8

C<new_effect_chain> <s_name> [ <effect_id_1>, <effect_id_2> ] ...

C<new_effect_chain my_piano 
nec my_guitar A C F G H 
>



=back

=head4 B<add_effect_chain> (aec) - Add an effect chain to the current track.

=over 8

C<add_effect_chain> <s_effect_chain_name>

C<aec my_piano 
>



=back

=head4 B<overwrite_effect_chain> (oec) - Add an effect chain, overwriting or replacing the current effects. Current effects are pushed onto the bypass list, so they aren't lost completely.

=over 8

C<overwrite_effect_chain> <s_effect_chain_name>

=back

=head4 B<delete_effect_chain> (dec destroy_effect_chain) - Delete an effect chain definition. After that the effect chain will no longer be available to add. Projects, which use the effect chain won't be affected.

=over 8

C<delete_effect_chain> <s_effect_chain_name>

=back

=head4 B<find_effect_chains> (fec) - Dump effect chains, matching key/value pairs if provided

=over 8

C<find_effect_chains> [ <s_key_1> <s_value_1> ] ...

C<fec 
>



=back

=head4 B<find_user_effect_chains> (fuec) - List all *user* created effect chains, matching key/value pairs, if provided.

=over 8

C<find_user_effect_chains> [ <s_key_1> <s_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

C<bypass_effects> [ <s_effect_id_1> <s_effect_id_2>... | 'all' ]

C<bypass all 
bypass 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

C<bring_back_effects> [ <s_effect_id_1> <s_effect_id_2> ... | 'all' ]

C<bbfx 
restore_effect AF 
bring_back_effects all 
>



=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

C<new_effect_profile> <s_bunch_name> [ <s_effect_profile_name> ]

C<new_bunch Drums snare toms kick 
nep Drums 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

C<apply_effect_profile> <s_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

C<destroy_effect_profile> <s_effect_profile_name>

=back

=head4 B<list_effect_profiles> (lep) - List all effect profiles.

=over 8

C<list_effect_profiles> 

=back

=head4 B<show_effect_profiles> (sepr) - List effect profile.

=over 8

C<show_effect_profiles> 

=back

=head4 B<full_effect_profiles> (fep) - Dump effect profile data structure.

=over 8

C<full_effect_profiles> 

=back

=head2 Track commands

=head4 B<cache_track> (cache ct) - Cache the current track, a.k.a. freezing or bouncing. Store a version of the current track with all processing to disk. Useful to save on processor power in large projects. Can be reversed by uncache_track .

=over 8

C<cache_track> [ <f_additional_processing_time> ]

C<cache 10 
>



=back

=head2 Effect commands

=head4 B<uncache_track> (uncache unc) - Select the uncached track version. This restores effects, but not inserts.

=over 8

C<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

C<do_script> <s_filename>

C<do prepare_my_drums 
>



=back

=head4 B<scan> - Re-read the project's .wav directory. Mainly useful for troubleshooting.

=over 8

C<scan> 

=back

=head2 Effect commands

=head4 B<add_fade> (afd fade) - Add a fade-in or fade-out to the current track.

=over 8

C<add_fade> ( in | out ) marks/times (see examples)

C<fade in mark1 
fade out mark2 2 
fade out 2 mark2 
fade in mark1 mark2 
>



=back

=head4 B<remove_fade> (rfd) - Remove a fade from the current track.

=over 8

C<remove_fade> <i_fade_index_1> [ <i_fade_index_2> ] ...

C<list_fade 
rfd 2 
>



=back

=head4 B<list_fade> (lfd) - List all fades.

=over 8

C<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

C<add_comment> <s_comment>

C<ac "Guitar, treble on 50%">



=back

=head4 B<remove_comment> (rc) - Remove a comment from the current track.

=over 8

C<remove_comment> 

=back

=head4 B<show_comment> (sc) - Show the comment for the current track.

=over 8

C<show_comment> 

=back

=head4 B<show_comments> (sca) - Show all track comments.

=over 8

C<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

C<add_version_comment> <s_comment>

C<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

C<remove_version_comment> 

=back

=head4 B<show_version_comment> (svc) - Show version comment(s) of the curent track.

=over 8

C<show_version_comment> 

=back

=head4 B<show_version_comments_all> (svca) - Show all version comments for the current track.

=over 8

C<show_version_comments_all> 

=back

=head4 B<set_system_version_comment> (ssvc) - Set a system version comment. Useful for testing and diagnostics.

=over 8

C<set_system_version_comment> <s_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

C<midish_command> <s_command_text>

C<m tracknew my_midi_track>



=back

=head4 B<midish_mode_on> (mmo) - All users commands sent to midish, until

=over 8

C<midish_mode_on> 

=back

=head4 B<midish_mode_off> (mmx) - Exit midish mode, restore default Nama command mode, no midish sync

=over 8

C<midish_mode_off> 

=back

=head4 B<midish_mode_off_ready_to_play> (mmxrp) - Exit midish mode, sync midish start (p) with Ecasound

=over 8

C<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

C<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

C<new_edit> 

=back

=head4 B<set_edit_points> (sep) - Mark play-start, record-start and record-end positions for the current edit.

=over 8

C<set_edit_points> 

=back

=head4 B<list_edits> (led) - List all edits for current track and version.

=over 8

C<list_edits> 

=back

=head4 B<select_edit> (sed) - Select an edit to modify or delete. After selection it is the current edit.

=over 8

C<select_edit> <i_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

C<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

C<destroy_edit> [ <i_edit_index> ]

=back

=head4 B<preview_edit_in> (pei) - Play the track region without the edit segment.

=over 8

C<preview_edit_in> 

=back

=head4 B<preview_edit_out> (peo) - Play the removed edit segment.

=over 8

C<preview_edit_out> 

=back

=head4 B<play_edit> (ped) - Play a completed edit.

=over 8

C<play_edit> 

=back

=head4 B<record_edit> (red) - Record an audio file for the current edit.

=over 8

C<record_edit> 

=back

=head4 B<edit_track> (et) - Set the edit track as the current track.

=over 8

C<edit_track> 

=back

=head4 B<host_track_alias> (hta) - Set the host track alias as the current track.

=over 8

C<host_track_alias> 

=back

=head4 B<host_track> (ht) - Set the host track (edit sub-bus mix track) as the current track.

=over 8

C<host_track> 

=back

=head4 B<version_mix_track> (vmt) - Set the version mix track as the current track.

=over 8

C<version_mix_track> 

=back

=head4 B<play_start_mark> (psm) - Select (and move to) play start mark of the current edit.

=over 8

C<play_start_mark> 

=back

=head4 B<rec_start_mark> (rsm) - Select (and move to) rec start mark of the current edit.

=over 8

C<rec_start_mark> 

=back

=head4 B<rec_end_mark> (rem) - Select (and move to) rec end mark of the current edit.

=over 8

C<rec_end_mark> 

=back

=head4 B<set_play_start_mark> (spsm) - Set play_start_mark to the current playback position.

=over 8

C<set_play_start_mark> 

=back

=head4 B<set_rec_start_mark> (srsm) - Set rec_start_mark to the current playback position.

=over 8

C<set_rec_start_mark> 

=back

=head4 B<set_rec_end_mark> (srem) - Set rec_end_mark to current playback position.

=over 8

C<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

C<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

C<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

C<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

C<move_to_bus> <s_bus_name>

C<asub Drums 
snare 
mtb Drums 
>



=back

=head4 B<promote_version_to_track> (pvt) - Create a read-only track using the specified version of the current track.

=over 8

C<promote_version_to_track> <i_version_number>

=back

=head2 General commands

=head4 B<read_user_customizations> (ruc) - Re-read the user customizations file 'custom.pl'.

=over 8

C<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

C<limit_run_time> [ <f_additional_seconds> ]

=back

=head4 B<limit_run_time_off> (lro) - Disable the recording stop timer.

=over 8

C<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

C<offset_run> <s_mark_name>

=back

=head4 B<offset_run_off> (ofro) - Turn back to starting from 0.

=over 8

C<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

C<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

C<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

C<rerecord> 

C<for piano guitar;rec 
rerec 
>



=back

=head2 General commands

=head4 B<eager> - Output audio as soon as possible. This will start playing or recording, as soon as a working setup is created.

=over 8

C<eager> off | doodle | preview

C<eager doodle 
eager off 
>



=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

C<analyze_level> 

=back

=head2 General commands

=head4 B<for> - Execute command(s) for several tracks.

=over 8

C<for> <s_track_name_1> [ <s_track_name_2>} ... ; <s_commands>

C<for piano guitar;vol / 2;pan 75 
for snare kick toms cymbals;mtb Drums 
>



=back

=head2 Project commands

=head4 B<git> - Execute git command in the project directory

=over 8

C<git> <s_command_name> [argument,...]

=back

=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 waveform or signal level displays are provided.  

No latency compensation across signal paths is provided at
present, although this feature is planned.

=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 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.
