Audio-Nama
view release on metacpan or search on metacpan
#!/usr/bin/env perl
use Audio::Nama;
Audio::Nama::main();
__END__
=head1 NAME
=encoding UTF-8
B<Nama> - multitrack recorder and digital audio workstation
=head1 SYNOPSIS
B<nama> [I<options>] [I<project-name>]
=head1 DESCRIPTION
A multitrack audio application for recording, effects
processing, editing, mixing, mastering and live
performance. It can also perform general-purpose audio
processing, such as 5.1 to stereo conversion. Nama uses
Ecasound as the audio processing engine.
=head2 Audio projects
Projects in Nama are audio networks of tracks and buses.
Tracks may contain one or more RIFF (.wav) files, as well as
effects, sends, inserts, marks, regions, fades,
edits and sequences. Tracks can host LADSPA, LV2 and
Ecasound plugins. Audio regions may be altered, duplicated,
time-shifted or replaced.
Audio processing is performed in realtime when a track is
played and may be cached (frozen) to a new audio file.
Project data is serialized as JSON. The complete history
is tracked by the git version control system. As a result,
projects can be managed using branches and tags, and provide
undo/redo.
Nama supports some MIDI functionality via midish.
=head2 Presets and templates
To facilitate reuse, a track's plugins and inserts can be
stored as an I<effect chain>. I<Effect profiles> apply effect
chains to groups of tracks. I<Project templates> are for
duplicating an entire project sans audio files.
=head2 Audio device
Nama performs Audio IO via JACK or ALSA. Soundcard IO goes
via JACK, if running, with transparent fallback to ALSA.
Nama supports Ladish Level 1 session handling.
=head2 User interfaces
Nama has fully featured terminal command prompt, a Tk
GUI, and experimental OSC and remote-command modes.
The command prompt can run Nama commands, Ecasound
interactive-mode commands, commands for the midish MIDI
recorder/player, shell commands and perl code. Commands and
filenames can be autocompleted using the TAB key. Command
history is available to browse with up and down arrows.
The help system provides documentation and keyword search
covering Nama commands and effects-processing
plugins.
=head1 OPTIONS
=over 12
=item B<--gui, -g>
Start Nama in GUI mode (default when Tk is available)
=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<--use-pwd, -p>
Use current dir for all WAV and project files
=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
=item B<--regenerate-effects-cache, -r>
Regenerate the effects data cache
=back
Debugging options:
Configuration commands affect I<future> runs of the audio
engine. For example, B<rec, play, mon> and B<off> determine
whether the current track will get its audio stream from an
external (e.g. live) source, whether an existing audio file
will be played back, and whether a new audio file will be
recorded. Nama responds to these commands by reconfiguring
the engine and displaying the updated track status. See 'man
::ChainSetup' for details on how the chain setup created.
=head2 Realtime Commands
Once a chain setup is loaded and the engine is launched,
commands can be issued to control the realtime behavior of
the audio processing engine. These commands include
transport C<start> and C<stop>, playback head 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, which is
formatted as YAML. On Nama's first run, a default version of
F<.namarc> is 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 (yellow) or playback (green).
=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. Any parameter label can be clicked to
add a parameter controller.
=head2 Waveform Window
Provides a conventional view with waveform and playback head.
=head2 Terminal Window
The command prompt is available the terminal window
and provides access to all of Nama's 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 untitled sax ('h' for help)E<gt>>
=back
In this instance, 'sax' is the current track in the
'untitled' default project.
When using buses, the bus is indicated before the track:
=over 12
C<nama untitled 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.
Most commands have abbreviations, such as 'afx' for
'add-effect'. These are shown in the help listings.
=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
Main 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. You can also use a 'stereo' declaration to avoid the
automatic channel copy usually applied to single-channel
sources.
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/PLAY/MON/OFF
Basic signal routing for each track is controlled by its
setting to REC, MON, PLAY or OFF.
The I<MON> setting prepares to connect the live track source.
The I<REC> setting prepares to connect the live track source and
record it to an audio file.
The I<PLAY> setting enqueues an audio file for playback from
purposes. B<Preview mode> disables recording of WAV files
to disk. B<Doodle mode> disables PLAY inputs while
excluding any tracks with the same source as a currently
routed track. The C<arm> command releases both preview and
doodle modes.
The eager setting causes the engine to start immediately
following a reconfiguration.
=head2 Saving Projects
If git is available, projects are saved automatically after
each command and it is not necessary to explicitly save
your work.
When you type C<save>, Settings related to the state of the
project are saved in the file F<State.json> in the
project directory. F<State.json> is tracked by git.
C<save> updates several other data files as well:
F<Aux.json>, also in the project directory, contains
data that is part of the project (such as command history,
track comments, and current operating modes) but with no direct
effect on the project audio.
F<global_effect_chains.json>, in the project root directory
(usually F<~/nama>) contains system and user defined effect
chains.
=head3 Save without Git
C<save somename.json> will save project state to a file of
that name. Similarly C<get somename.json> will load the
corresponding file. The F<.json> suffix may be omitted if
"use_git: 0" is set in F<.namarc>.
=head3 Save with Git
If git is available, Nama uses it to store snapshots of
every step in the history of your project.
When you type C<save initial-mix>, the latest snapshot is
tagged with the name "initial-mix", which you can recall
later with the command C<get initial-mix>.
You can include a comment with the snapshot:
C<save initial-mix "sounds good enough to send to the front office">
Nama lets you create new branches, starting at any snapshot.
To start a new branch called I<compressed-mix> starting at a
snapshot called I<initial-mix> you would say:
C<new-branch compressed-mix initial-mix>
If you want to go back to working on the master branch, use
C<branch master>.
You can also issue native git commands at the Nama prompt.
=head3 Git history example
All projects begin on the "master" branch. Because this is
the default branch, it is not displayed in the prompt.
Otherwise "master" is not special in any way.
In the graphs below, the letters indicate
named snapshots.
create test-project
...
save a
...
save b
...
save c
---a---b---c (master)
get a
...
save d
...
save e
...
save f
d---e---f (a-branch)
/
-----a----b---c (master)
Now, you want to go back to try something different at "c":
get c
...
save g
d---e---f (a-branch)
/
----a----b---c (master)
\
g (c-branch CURRENT HEAD)
You could also go back to master, and restart
from there:
get master
...
save h
...
save i
d---e---f (a-branch)
/
----a----b---c---h---i (master CURRENT HEAD)
\
g (c-branch)
Merging of branches is not supported.
=head2 Exiting
When you type C<quit> Nama will automatically save your work
to F<State.json>. If you I<don't> want this behavior, use
=over 8
list-effect-profiles
=back
=head4 B<show-effect-profiles> (sepr) - List effect profile.
=over 8
show-effect-profiles
=back
=head4 B<full-effect-profiles> (fep) - Dump effect profile data structure.
=over 8
full-effect-profiles
=back
=head2 Track commands
=head4 B<cache-track> (cache ct bounce freeze) - Cache the current track. Same as freezing or bouncing. This
is useful for larger projects or low-power CPUs, since
effects do not have to be recomputed for subsequent engine
runs.
Cache_track stores the effects-processed output of the
current track as a new version (WAV file) which becomes the
current version. The current effects, inserts and region
definition are removed and stored.
To go back to the original track state, use the
uncache-track command. The show-track display appends a "c"
to version numbers created by cache-track (and therefore
reversible by uncache)
=over 8
cache-track [ <float:additional_processing_time> ]
cache 10 # Cache the curent track and append 10 seconds extra time,
=back
=head2 Effect commands
=head4 B<uncache-track> (uncache unc) - Select the uncached track version. This restores effects, but not inserts.
=over 8
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
do-script <string:filename>
do prepare_my_drums # Execute the script prepare_my_drums.
=back
=head4 B<scan> - Re-read the project's .wav directory. Mainly useful for troubleshooting.
=over 8
scan
=back
=head2 Effect commands
=head4 B<add-fade> (afd fade) - Add a fade-in or fade-out to the current track.
=over 8
add-fade ( in | out ) marks/times (see examples)
fade in mark1 # Fade in,starting at mark1 and using the
# default fade time of 0.5 seconds.
fade out mark2 2 # Fade out over 2 seconds, starting at mark2 .
fade out 2 mark2 # Fade out over 2 seconds, ending at mark2 .
fade in mark1 mark2 # Fade in starting at mark1, ending at mark2 .
=back
=head4 B<remove-fade> (rfd) - Remove a fade from the current track.
=over 8
remove-fade <integer:fade_index_1> [ <integer:fade_index_2> ] ...
list-fade # Print a list of all fades and their tracks.
rfd 2 # Remove the fade with the index (n) 2.
=back
=head4 B<list-fade> (lfd) - List all fades.
=over 8
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
( run in 1.497 second using v1.01-cache-2.11-cpan-0b5f733616e )