/ 
Audio-Ecasound-Multitrack-0.96
/ Audio::Multitrack

NAME

Audio::Multitrack - Perl extensions for multitrack audio processing

nama - Multitrack recording/mixing application

SYNOPSIS

nama options project_name

OPTIONS

-d project_root_dir

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

-g

Graphical user interface

-t

Text user interface (default)

-f config_file

Use config_file instead of default .namarc

-c

Create the named project

-a

Save and reload ALSA mixer state using alsactl

-m

Suppress loading of saved state

-e

Don't load static effects data

-s

Don't load static effects data cache

DESCRIPTION

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.

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 buses. A group REC-enable button and group default-version setting make it possible to record and manage a group of songs.

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

STATIC AND DYNAMIC COMMANDS

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

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

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 arm command under the text interface.

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.

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.

LADSPA

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

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 arm or 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.

TEXT UI

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

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 help for a command summary, help command for help with command.

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 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 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 group_off) excludes all user tracks from the chain setup, and is typically used when playing back mixdown tracks. The 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.

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

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

BUGS AND LIMITATIONS

- Text-only mode (initiated with the -t option) currently lacks the loop 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.

EXPORT

None by default.

DEPENDENCIES

This module requires that you have installed the following Perl modules. These modules can be downloaded automagically if 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 listplugins and analyseplugin must also be installed in a directory in your execution PATH. See http://ladspa.org .

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

AVAILABILITY

CPAN, for the distribution.

Pull source code using this command:

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

AUTHOR

Joel Roth, <joelz@pobox.com>

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.