#!/usr/bin/env perl
use Audio::Multitrack;
Audio::Multitrack::mainloop();

__END__
=head1 NAME

B<Audio::Multitrack> - Perl extensions for multitrack audio processing

B<nama> - Multitrack recording/mixing application

=head1 SYNOPSIS

B<nama> I<options> I<project_name>

=head1 OPTIONS

=over 12

=item B<-d> I<project_root_dir>

Use I<project_root_dir> as nama top-level project directory (default $HOME/nama)

=item B<-g>

Graphical user interface

=item B<-t>

Text user interface (default)

=item B<-f> I<config_file>

Use I<config_file> instead of default .namarc

=item B<-c>

Create the project named after all options

=item B<-a>

Save and reload ALSA state using alsactl

=item B<-m>

Suppress loading of saved state

=item B<-e>

Don't load static effects data

=item B<-s>

Don't load static effects data cache

=back

=head1 DESCRIPTION

B<Audio::Multitrack> provides class libraries for managing
tracks and buses.  

B<Nama> is a recorder/mixer application with text and
graphical interfaces. It is configured as a single mixer bus
with per-track volume/pan/effects, a master fader, and a
mixdown track.

There are two types of commands. 

B<Static commands> control the chain setup that will be
used for audio processing. They are generally used
while the audio processing engine is I<not> running.

For example, the REC/MON/OFF status for a track and its
associated group controls whether that track will be
included in the next Ecasound chain setup, and whether the
audio stream will be recorded or played back.

After issuing static commands, use the the I<arm> command
(or GUI button) to generate a chain setup file and connect
it to the audio processing engine.  This is usually the last
operation before pressing the start button.

B<Dynamic commands> operate in realtime, affecting
volume, pan, and playback head position while the engine is
running. Effects parameters you can adjust at any time.
Playback position can only be adjusted after the chain
setup is connected.

On the first run the program creates $HOME/.namarc, the
configuration file and project directory $HOME/nama.  WAV
files and parameter settings for each project are stored in
.wav directories under $HOME/nama.  You probably want to edit the
default .namarc to suit your audio configuration.

Project state can be stored/retrieved. These data are stored
in the State.yml file in the project directory. The storage
format is user-friendly YAML.

To be certain your chain setup loads correctly, you may need
to regenerate the setup using the Arm button in the GUI or
the I<arm> command under the text interface.  

=head1 LADSPA

Audio::Multitrack will automatically incorporate locally
available LADSPA plugins provided you have the 'analyseplugin'
program (part of LADSPA client libraries) installed.  

=head1 Tk GRAPHICAL UI 

Invoked using the -g switch on the nama command line, 
the Tk interface provides two panels for record/mix
and effects. Linear/log sliders are automatically used for most
plugins. For other plugins, text-entry widgets are used to
enter parameters. 

The GUI time display color indicates whether the upcoming
operation will include recording (red), mixing only (yellow) or
playback only (green).  

Even in GUI mode the text command prompt appears in the
terminal window, and text commands may be issued at any
time.

=head1 TEXT UI

The command line interpreter starts by default
or by using the B<-t> option when invoking nama.

B<Enter command:>

Nama and Ecasound-IAM commands can be entered
directly.

Perl code should be preceded by "eval ".

Shell code should be preceded by "!".

Commands on the same line should be separated by semicolons
(';'). 

Note that if an 'eval' or '!' appears at the beginning of a
command, the entire line will be give to the corresponding
interpreter.

In other situations, the lines are split on semicolons and
each part is executed appropriately as Nama, Ecasound, perl
code or shell commands.

You can access history using up-arrow/down-arrow
(Ctrl-P/Ctrl-N on Mac). 

Type B<help> for a command summary, B<help command> for
help with I<command>. 

=head1 TRACKS

Multiple WAV files can be recorded for each track. These are
identified by version number. Identical version numbers indicate WAV files
recorded at the same time. Version number increments
automatically so that the order of version numbers
follows the time sequence of the recordings.

Each track, including Master and Mixdown, has its own
REC/MON/OFF setting and displays its own REC/MON/OFF
status. The Master track has only MON/OFF status. Setting REC
status for the Mixdown track is the same as issuing
the 'mixdown' command.

Master and Mixdown tracks can behave differently from 
user-created tracks because they belong to different
groups. 

All user-created tracks belong to the Tracker group.
The Tracker group has REC/MON/OFF and version
settings that apply to all user tracks.

Tracker group MON setting (text command 'group_monitor')
forces all user tracks with a REC setting to MON status.
Tracker group MON mode triggers automatically after a
successful recording.

Tracker group OFF setting (text 'group_off') excludes all user
tracks from the chain setup. Can be useful when playing back files
recorded through the Mixdown function. The
text 'mixplay' command sets the Tracker group to OFF.

A track with no recorded WAV files that is set to MON will
show OFF status.


=head1 SAMPLE SESSION

Here is a typical sequence of commands to record tracks
with Nama:

create marys_little_helper       # new project
add guitar; r1                   # record track 'guitar' from input 1
add piano; r2                    # record track 'piano' from input 2
add drums; r3                    # record track 'drums' from input 3
arm
start
(perform song)
stop
show                             # new versions of guitar, piano and drums
                                 # appear
arm; start                       # review recording

group_record                     # rec-enable group
guitar mon; piano mon; drums mon # set three tracks to monitor mode
add vocals; r2                   # record track 'vocals' from input 2
arm
start
(perform vocals)
stop

arm; start                       # review recording

(adjust effects)

mixdown; show                    # set mixdown mode, show results
arm; start                       # record mixdown track
stop
mixplay                          # mixdown playback mode
arm; start                       # review completed mix

=head1 DIRECTORY STRUCTURE

$project_root is the directory where your project files,
including WAV files you record, will go. $project_root
is defined in the first non-comment line of 
your .namarc file.

File or directory                     Explanation
--------------------------------------------------------------------------
$HOME/.namarc                         Nama configuration file
$project_root/project_name/.wav       WAV files we record will be stored here
$project_root/project_name/Setup.ecs  Ecasound chainsetup, dynamically generated
$project_root/project_name/State.yml  Default save file for project parameters
$project_root/project_name/.namarc    Project-specific configuration

=head1 BUGS AND LIMITATIONS

No GUI remove-track command is provided.

Default GUI volume sliders are not log scaled.

The post-recording cleanup routine deletes
newly recorded soundfiles under 44100 bytes in size. 

Parameter controllers support is not complete

=head1 EXPORT

None by default.

=head1 DEPENDENCIES

This module requires that you have installed these Perl modules:

	Carp
	Data::YAML
	IO::All
	Cwd
	Storable 
	Data::Dumper
	Getopt::Std
	Tk
	Audio::Ecasound
	Parse::RecDescent
	YAML::Tiny
	Data::YAML
	File::Find::Rule
	File::Spec::Link

The Ecasound audio processing libraries must also be
installed.  Ecasound may be obtained from
http://ecasound.seul.org/ecasound/ or as precompiled binary
packages for your Un*x distribution.

LADSPA libraries and plugins are strongly recommended.  In
that case, the LADSPA utility program 'analyseplugin' must
also be installed in a directory in your execution PATH.  See
http://ladspa.org .

'file', a BSD utility program, is also needed.

=head1 AVAILABILITY

CPAN, for the distribution.

Pull source code using this command: 

    git clone git://github.com/bolangi/nama.git

=head1 AUTHOR

Joel Roth, E<lt>joelz@pobox.comE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright 2007 by Joel Roth

This library is licensed under GPL version 2.
See the file COPYING (included in the
distribution) for terms and conditions.
