#!/usr/bin/env perl
use Audio::Ecasound::Multitrack;
Audio::Ecasound::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 F<.namarc>

=item B<-c>

Create the named project

=item B<-a>

Save and reload ALSA mixer 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::Ecasound::Multitrack> provides class libraries for managing
tracks and buses and the associated WAV files, typically generated by
recording runs of the Ecasound audio-processing engine.

B<Nama> is a recorder/mixer application that configures
Ecasound as a single mixer bus.  Vol/pan/effects are
provided on all tracks and on the main output and mixdown
output.  A group REC-enable button and group default-version
setting make it possible to record and manage a group of songs.

B<Nama> provides both command-line and GUI interfaces.
The command-line interface includes a help system
documenting all commands.

=head1 STATIC AND DYNAMIC COMMANDS

It may be helpful to observe that commands or actions
under Nama fall into two categories.

B<Static commands> control the chain setup that will be
used for audio processing. They do not influence
the realtime operation of the audio processing engine. 

For example, setting the REC/MON/OFF status of a track 
determines whether that track will be
included in the I<next> processing run, and whether the
audio stream will be recorded or played back.

When the tracks are configured to your liking, you issue the
B<arm> command 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.

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 FIRST RUN

On the first run the program prompts the user for permission
to create the configuration file, usually $HOME/.namarc, and
a recording projects directory, which is $HOME/nama by
default.  You should then edit .namarc to suit your audio
configuration.

=head1 PERSISTENCE

Project state can be stored/retrieved. These data are stored
by default in the State.yml file in the project directory
in easily readable YAML format.

=head1 LADSPA

B<Nama> will automatically detect locally available
LADSPA plugins provided you have the B<listplugins> and
B<analyseplugin> programs which are part of LADSPA SDK.

=head1 Tk GRAPHICAL UI 

Invoked by default, the Tk interface provides all
functionality on two panels, one for general control,
the second for effects. 

Linear/log slider scaling with hinted ranges are provided
automatically for most effects.  Text-entry widgets are used
to enter parameters for other plugins. 

After issuing the B<arm> or B<connect> commands, the GUI
time display changes color to indicate whether the upcoming operation
will include live recording (red), mixdown 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

Each track has a descriptive name (i.e. vocal) and an
integer track-number assigned when the track is created.

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 has the same effect as issuing
the B<mixdown> command.

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

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 B<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 command B<group_off>)
excludes all user tracks from the chain setup, and is
typically used when playing back mixdown tracks.  The
B<mixplay> command sets the Mixdown group
to MON and 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 text commands to:
- record instrumental parts
- separately record a vocalist
- mix down the result to a stereo tract

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                              # generate chain setup and connect engine
start

(perform music)

stop
show                             # new versions of guitar, piano and drums
                                 # appear
group_monitor                    # set group MON
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

group_monitor                    # set group MON
arm; start                       # review recording

(adjust effects)

mixdown; show                    # set mixdown mode, show to confirm
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

- Text-only mode (initiated with the -t option) currently
lacks the loop-enable function available in the default mode. This
is because events are provided through the Tk graphic
toolkit, which requires X. 

- Default GUI volume sliders are linear scaled.

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

- A project should be loaded or created before issuing
other commands. Many commands will crash the system
if issued without a project loaded.

- To be able to run entirely without Tk and without X
  you will need to delete the line containing 'use Tk' 
  from Multitrack.pm.

=head1 EXPORT

None by default.

=head1 DEPENDENCIES

This module requires that you have installed the 
following Perl modules. These modules can be downloaded
automagically if B<Audio::Ecasound::Multitrack>
is installed from CPAN. 

	Data::YAML
	IO::All
	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 plugins are also recommended.  In that case, the
LADSPA utility programs B<listplugins> and B<analyseplugin>
must also be installed in a directory in your execution
PATH. See http://ladspa.org .

B<file>, a BSD utility program, is also needed. It is most likely
already provided with your operating system.

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

=head1 ABSTRACT

Classes for track and bus and their signal routing. 

Recorder-mixer application generates chain setups and issues
commands to the Ecasound audio processing engine.

Configuration data and project settings are stored in YAML
formatted text files. 

