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

__END__
=head1 NAME

B<Audio::Ecasound::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> F<project_root>

Use F<project_root> as Nama's top-level directory. Default: $HOME/nama

=item B<-g>

Graphical mode, with text interface in terminal window

=item B<-t>

Text-only mode

=item B<-f> F<config_file>

Use F<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
tracks and buses, and a track oriented user interface for managing 
runs of the Ecasound audio-processing engine.

B<Nama> is a recorder/mixer application that configures
Ecasound as a single mixer bus.

In its default mode B<Nama> provides a Tk GUI interface,
with a command line interface running simultaneously in the
terminal window.

=head1 STATIC AND DYNAMIC COMMANDS

It may be helpful to observe commands or actions for audio
processing fall into two categories:

Some commands control the Ecasound chain setup that will be
used for audio processing. 

For example, setting the REC/MON/OFF status of a track
or bus determines whether it will be included next time
the transport is armed, and whether the audio stream
will be recorded to a file or played back from an existing
file. 

This is the first part: you set up tracks to your liking.
Then you issue the I<arm> command to configure and connect
the Ecasound engine.

Other commands influence the audio processing engine as it
runs, for example volume and pan controls, and any changes
to the position of the playback head.

=head1 FIRST RUN

On the first run the program prompts the user for permission
to create the configuration file, usually F<$HOME/.namarc>, and
a recording projects directory, F<$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 F<State.yml> file in the project
directory.

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

Logarithmic sliders are provided automatically for effects
with hinting. Otherwise text-entry widgets are used.

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

The text command prompt appears in the terminal window
during GUI operation. Text commands may be issued at any
time.

=head1 TEXT UI

Press the I<Enter> key to get the following command prompt.

=over 12

B<Enter command:>

=back

You can now enter commands.  Nama and Ecasound
commands may be entered directly. You may also enter Perl
code preceded by "eval" or shell code preceded by "!".

Multiple commands on a single line are allowed if delimited
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
the parts are executed sequentially.

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

Type B<help> for general help, 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 bus has only MON/OFF status. Setting REC
status for the Mixdown bus has the same effect as issuing
the B<mixdown> command.

All user tracks belong to the Tracker group, which has
a group REC/MON/OFF setting and a default version setting.

Setting the group to MON (text command B<group_monitor>)
forces user tracks with a REC setting to MON status if
a WAV file is available to play, or OFF status if no
audio stream is available. 

The group MON mode triggers automatically after a recording
that leaves files longer than a second.

The 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 all 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)

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

(engine runs)

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

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

- The loop_enable command is available only in the default mode.
  Timer events are currently handled through the Tk graphic toolkit,
  which requires X.

- GUI volume sliders are linear scaled.

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

- 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 the following Perl modules. 

	Data::YAML
	IO::All
	Getopt::Std
	Tk
	Audio::Ecasound
	Parse::RecDescent
	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 and user interfaces for multitrack recording with
the Ecasound audio processing engine
