NAME

Nama - Ecasound-based recorder, mixer and mastering system

SYNOPSIS

nama [options] [project_name]

DESCRIPTION

Nama is a text-based application for multitrack recording, effects processing, non-destructive editing and mastering using Ecasound for all audio processing. Nama offers the stable functioning of Ecasound enchanced by high level concepts such as tracks and buses and a convenient command language.

Nama has many functions found in digital-audio workstations including marks, regions, fades, sends, inserts, buses, track freezing and time shifting as well as some functions unique to Nama. Full help is provided, including commands by category and search.

Nama runs under ALSA and JACK audio frameworks, and automatically discovers all available LADSPA plugins.

Nama has a simple graphic interface based on the Tk widget set. By default the GUI displays while the command processor runs in a terminal window. The -t option provides a text-only interface for console users.

OPTIONS

--gui, -g

Start Nama in GUI mode

--text, -t

Start Nama in text mode

--config, -f

Specify configuration file (default: ~/.namarc)

--project-root, -d

Specify project root directory

--create-project, -c

Create project if it doesn't exist

--net-eci, -n

Use Ecasound's Net-ECI interface

--libecasoundc, -l

Use Ecasound's libecasoundc interface

--save-alsa, -a

Save/restore alsa state with project data

--help, -h

This help display

Debugging options:

--no-static-effects-data, -s

Don't load effects data

--no-state, -m

Don't load project state

--no-static-effects-cache, -e

Bypass effects data cache

--regenerate-effects-cache, -r

Regenerate the effects data cache

--no-reconfigure-engine, -R

Don't automatically configure engine

--debugging-output, -D

Emit debugging information

--fake-jack, -J

Simulate JACK environment

--fake-alsa, -A

Simulate ALSA environment

--no-ecasound, -E

Don't spawn Ecasound process

--execute-command, -X

Supply a command to execute

CONTROLLING NAMA/ECASOUND

The Ecasound audio engine is configured through use of chain setups that specify the signal processing network. After lauching the engine, realtime control capabilities are available, for example to adjust signal volume and to set playback position.

Nama serves as an intermediary, taking high-level commands from the user, generating appropriate chain setups for recording, playback, mixing, etc. and running the audio engine.

Nama commands can be divided into two categories.

STATIC COMMANDS

Static commands affect future runs of the audio processing engine. For example, rec, mon and off determine whether the current track will get its audio stream from a live source or whether an existing WAV file will be played back. Nama responds to static commands by automatically reconfiguring the engine and displaying the updated track status.

DYNAMIC COMMANDS

Once a chain setup is loaded and the engine is launched, another set of commands controls the realtime behavior of the audio processing engine. Commonly used dynamic commands include transport start and stop; playback head repositioning commands such forward, rewind and setpos. Effects may be added, modified or removed while the engine is running.

CONFIGURATION

General configuration of sound devices and program options is performed by editing the .namarc file. On Nama's first run, a default version of .namarc is usually placed in the user's home directory.

Tk GRAPHICAL UI

Invoked by default if Tk is installed, this interface provides a subset of Nama's functionality on two panels, one for general control, the second for effects.

The general panel has buttons for project create, load and save, for adding tracks and effects, and for setting the vol, pan and record status of each track.

The GUI project name bar and time display change color to indicate whether the upcoming operation will include live recording (red), mixdown only (yellow) or playback only (green). Live recording and mixdown can take place simultaneously.

The effects window provides sliders for each effect parameters. 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.

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

TEXT UI

Press the Enter key if necessary to get the following command prompt.

nama [sax] ('h' for help)>

In this instance, 'sax' is the current track.

When using sub-buses, the bus is indicated before the track:

nama [Strings/violin] ('h' for help)>

At the prompt, you can enter Nama and Ecasound commands, Perl code preceded by eval or shell code preceded by !.

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 eval or ! 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 help for general help, help command for help with command, help foo for help with commands containing the string foo. help_effect foo bar lists all plugins/presets/controller containing both foo and bar. Tab-completion is provided for Nama commands, Ecasound-iam commands, plugin/preset/controller names, and project names.

TRACKS

Each track has a descriptive name (i.e. vocal) and an integer track-number assigned when the track is created. The following paragraphs describes track attributes and their settings.

WIDTH

Specifying 'mono' means a one-channel input, which is recorded as a mono WAV file. Mono signals are duplicated to stereo and a pan effect is provided for all user tracks.

Specifying 'stereo' for a track means that two channels of audio input will be recorded as an interleaved stereo WAV file.

Specifying N channels for a track ('set width N') means N successive input channels will be recorded as an N-channel interleaved WAV file.

VERSION NUMBER

Multiple WAV files can be recorded for each track. These are distinguished by a version number that increments with each recording run, i.e. sax_1.wav, sax_2.wav, etc. All WAV files recorded in the same run have the same version numbers.

The version numbers of files for playback can be selected at the bus or track level. By setting the bus version number to 5, you can play back the fifth take of a song, or perhaps the fifth song of a live recording session.

The track version setting, if present, overrides the bus setting. Setting the track version to zero restores control of the version number to the bus setting.

A bus version setting for the Main bus does not propagate to sub-buses.

REC/MON/OFF

Track REC/MON/OFF status guides audio processing.

Each track, including Master and Mixdown, has its own REC/MON/OFF setting and displays its own REC/MON/OFF status. The Main bus also has REC, MON and OFF settings that influence the behavior of all user tracks.

As the name suggests, REC status indicates that a track is ready to record a WAV file. You need to set both track and bus to REC to record an audio stream to file.

MON status indicates an audio stream available from disk. It requires a MON setting for the track or bus as well as the presence of a file with the selected version number. A track set to REC with no live input will default to MON status.

OFF status means that no audio is available for the track from any source. A track with no recorded WAV files will show OFF status, even if set to MON.

An OFF setting for a track or bus always results in OFF status, causing the track to be excluded from the chain setup. Note: This setting is distinct from the action of the mute command, which sets the volume of the track to zero.

Newly created user tracks belong to the Main bus, which goes through a mixer and Master fader track to the soundcard for monitoring.

MARKS

Marks in Nama are similar to those in other audio editing software, with one small caveat: Mark positions are relative to the beginning of an Ecasound chain setup. If your project involves a single track, and you will be shortening the stream by setting a region to play, set any marks you need after defining the region.

REGIONS

The region command allows you to define endpoints for a portion of an audio file. Use the shift command to specify a delay for starting playback.

Only one region may be specified per track. Use the new_region command to clone a track, specifying a new region definition.

link_track can clone tracks from other projects.

EFFECTS

Each track gets volume and pan effects by default. New effects added using add_effect are applied after pan volume controls. You can position effects anywhere you choose using insert_effect.

FADERS

Nama allows you to place fades on any track. Fades are logarithmic, defined by a mark position and a duration. An extra volume operator, -eadb is applied to the track to enable this function.

SENDS AND INSERTS

The send command can route a track's post-fader output to a soundcard channel or JACK client in addition to the normal mixer input. Nama currently allows one aux send per track.

The add_insert_cooked command configures a post-fader send-and-return to soundcard channels or JACK clients. Wet and dry signal paths are provided, with a default setting of 100% wet.

BUS-LEVEL REC/MON/OFF SETTING

By default, all user tracks belong to Nama's Main bus. The Main bus has its own REC/MON/OFF setting that influences the rec-status of individual tracks.

Setting a bus to OFF forces all of the bus tracks to OFF. When the bus is set to MON, track REC settings are forced to MON. When the bus is set to REC, track status can be REC, MON or OFF.

The Main bus MON mode triggers automatically after a successful recording run.

The mixplay command sets the Mixdown track to MON and the Main bus to OFF.

BUNCHES

A bunch is just a list of track names. Bunch names are used with the keyword for to apply one or more commands to to several tracks at once. A bunch can be created with the new_bunch command. Any bus name can also be treated as a bunch. Finally, a number of special bunch keywords are available.

rec, mon, off

All tracks with the corresponding setting in the current bus

REC, MON, OFF

All tracks with the corresponding status in the current bus

BUSES

Nama uses buses internally, and provides two kinds of user-defined buses.

Sub buses enable multiple tracks to be routed through a single mix track before feeding the main mixer bus (or possibly another sub bus.)

The following commands create a sub bus and assign three tracks to it. The mix track takes the name of the bus. Strings in this case, and is stereo by default.

add_sub_bus Strings
add_tracks violin cello bass
for violin cello bass; set bus Strings
Strings vol - 10

Send buses can be used as instrument monitors, or to send pre- or post-fader signals from multiple user tracks to an external program such as jconv.

ROUTING

Nama commands can address tracks by both a name and a number. In Ecasound chain setups, only the track number is used.

Loop devices

Nama uses Ecasound loop devices to join two tracks, or to allow one track to have multiple inputs or outputs.

Flow diagrams

Let's examine the signal flow from track 3, the first available user track. Assume track 3 is named "sax".

We will divide the signal flow into track and mixer sections. Parentheses indicate chain identifiers or the corresponding track name.

The stereo outputs of each user track terminate at Master_in, a loop device at the mixer input.

Track, REC status

Sound device   --+---(3)----> Master_in
  /JACK client   |
                 +---(R3)---> sax_1.wav

REC status indicates that the source of the signal is the soundcard or JACK client. The input signal will be written directly to a file except in the special preview and doodle modes.

Track, MON status

sax_1.wav ------(3)----> Master_in

Mixer, with mixdown enabled

In the second part of the flow graph, the mixed signal is delivered to an output device through the Master chain, which can host effects. Usually the Master track provides final control before audio output or mixdown.

Master_in --(1/Master)--> Master_out -> Sound device
                             |
                             +----->(2/Mixdown)--> Mixdown_1.wav

During mastering, the mastering network is inserted between the Master track, and the audio/mixdown output.

Mastering Mode

In mastering mode (invoked by master_on and released master_off) the following network is used:

                      +-(Low)-+ 
                      |       |
Eq-in -(Eq)-> Eq_out -+-(Mid)-+- Boost_in -(Boost)-> soundcard/wav_out
                      |       |
                      +-(High)+ 

The Eq track hosts an equalizer.

The Low, Mid and High tracks each apply a bandpass filter, a compressor and a spatialiser.

The Boost track applies gain and a limiter.

These effects and their default parameters are defined in the configuration file .namarc.

Mixdown

The mixdown command configures Nama for mixdown. The Mixdown track is set to REC (equivalent to Mixdown rec) and the audio monitoring output is turned off (equivalent to main_off).

Mixdown proceeds after you enter the start command.

Preview and Doodle Modes

These non-recording modes, invoked by preview and doodle commands tweak the routing rules for special purposes. Preview mode disables recording of WAV files to disk. Doodle mode disables MON inputs while enabling only one REC track per signal source. The arm command releases both preview and doodle modes.

TEXT COMMANDS

[% qx(./emit_command_headers pod) %]

DIAGNOSTICS

In most situations, the GUI display and the output of the show_tracks command (executed automatically on any change in setup) show what to expect the next time the engine is started.

Additionally, Nama has a number of diagnostic functions that can help resolve problems without resorting to the debugging flag (and wading through its prolific output.) The chains command displays the current chain setup to determine if Ecasound is properly configured for the task at hand. (It is much easier to read these setups than to write them!)

The dump command displays data for the current track. The dumpall command shows all state that would be saved. This is the same output that is written to the State.yml file when you issue the save command.

BUGS AND LIMITATIONS

No waveform or signal level displays are provided.

No latency compensation across signal paths is provided at present, although this feature is planned.

SECURITY CONCERNS

If you are using Nama with the NetECI interface (i.e. if Audio::Ecasound is not installed) you should block TCP port 2868 if your computer is exposed to the Internet.

INSTALLATION

The following command, available on Unixlike systems with Perl installed, will pull in Nama and other Perl libraries required for text mode operation:

PERL_MM_USE_DEFAULT=1 cpan Audio::Nama

To use the GUI, you will need to install Tk:

cpan Tk

You may want to install Audio::Ecasound if you prefer not to run Ecasound in server mode:

cpan Audio::Ecasound

You can pull the source code as follows:

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

Consult the BUILD file for build instructions.

SUPPORT

The Ecasound mailing list is a suitable forum for questions regarding Nama installation, usage, feature requests, etc., as well as questions relating to Ecasound itself.

https://lists.sourceforge.net/lists/listinfo/ecasound-list

PATCHES

The main module, Nama.pm, and its sister modules are concatenations of several source files. Patches against these source files are preferred.

AUTHOR

Joel Roth, <joelz@pobox.com>

cpanm Audio::Nama

perl -MCPAN -e shell
install Audio::Nama