NAME

Nama - Ecasound-based recorder, mixer and mastering system

SYNOPSIS

nama [options] [project_name]

DESCRIPTION

Nama is an application for multitrack recording, non-destructive editing, mixing and mastering using the Ecasound audio engine developed by Kai Vehmanen. Primarily text-based, it also has a simple Tk based GUI.

Features include tracks with multiple versions (AKA takes) buses, effects, presets, sends, inserts, marks, regions, edits, templates and user-defined commands. Nama runs under JACK and ALSA audio frameworks, automatically detects LADSPA plugins, and supports Ladish Level 1 session handling.

Nama's audio processing is non-destructive by default: effects are applied in realtime; edits are accomplished through crossfades. These modifications to a track can be frozen as a new version for that track.

The command prompt accepts Nama commands, Ecasound interactive-mode commands, shell commands and perl code, with command history and autocompletion. The help system provides documentation and keyword search covering Nama commands and effects.

By default, Nama displays a simple graphic interface 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 effect parameters and 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.

Static Commands

Static commands affect future runs of the audio engine. For example, rec, mon and off determine whether the current track will get its audio stream from an external (usually 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 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 windows:

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 only (yellow) or playback only (green). Live recording and mixdown can take place simultaneously.

Effects Window

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

Terminal Window

The command prompt appears in the terminal window during GUI operation. Text commands are used to access Nama's more advanced functions.

TEXT USER INTERFACE

Press the Enter key if necessary to get the command prompt, which will look something like this:

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.

Many effects have abbreviations, such as 'afx' for 'add_effect'.

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 Master track on the way to soundcard for monitoring.

The following sections describes track attributes and their effects.

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.

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

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. Each bus also has REC, MON and OFF settings that influence the behavior of user tracks.

Track status

As the name suggests, REC status indicates that a track is ready to record a WAV file.

MON status indicates an audio stream is available from disk. This status requires the presence of a file matching the bus or track version number, if specified. 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.

Bus setting

Nama provides MON and OFF settings for buses. OFF (set by bus_off) removes all member tracks from the chain setup, MON (set by bus_mon restores them. (The bus REC setting is obsolete, now equivalent to MON.)

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

Version Number

Multiple WAV files ("takes") 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 to 5, you can play back version 5 of several tracks at once. Version 5 could signify the fifth take of a song, or 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.

The Main bus version setting does not currently propagate to sub-buses. If you have sub-buses you must set bus version numbers for each separately if desired.

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.

Each track can have one region definition. For multiple regions, the new_region command takes a pair of marks to create a read-only copy of the current track with region definition.

You can control this region as you would any other other track, applying effects, adjusting volume, etc.

Currently, regions are not clipped out of their host track. This feature may be implemented in future.

Using Tracks from Other Projects

The link_track clones a read-only track from another track, which may belong to a different project.

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.

Fades

Nama allows you to place fades on any track. Fades are logarithmic, defined by a mark position and a duration. An additional volume operator, -eadb, is applied to each track to host the envelope controller that implements fades.

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 command configures a pre- or 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.

Each track can have one pre-fader and one post-fader insert.

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 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, several system defined bunches 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

Sub 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 and is stereo by default.

# create a bus named Strings feeding a mix track named Strings
add_sub_bus Strings 

# create tracks for the sub-bus
add_tracks violin cello bass

# move the tracks from the Main bus (default) to the Strings bus
for violin cello bass; set bus Strings

# use the mix track to control bus output volume
Strings vol - 10

Send Buses

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 jconverter

ROUTING

General Notes

While Nama can address tracks by either name and track number, the chain setups use the track number exclusively.

The Master track (mixer output control) is always chain 1, the Mixdown track is always chain 2.

Nama uses Ecasound loop devices where necessary to connect two tracks, or to allow one track to have multiple inputs or outputs. Each loop device adds one buffer, which increases latency.

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 show the track number/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, or if rec_disable is issued.

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_out --+--------> Sound device
                                |
                                +-->(2)--> Mixdown_1.wav

Mastering Mode

In mastering mode (invoked by master_on and released master_off) the following network, receives the Master track signal as input and provides an output to the soundcard or WAV file.

                   +- Low -+ 
                   |       |
Master_in --- Eq --+- Mid -+--- 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 start the transport.

As a convenience, Mixdown_nn.wav will be symlinked to <branch_name_nn.wav> in the project directory. (If git is disabled or not available <project_name_nn.wav> is used instead.) Corresponding encoded files are created if the "mixdown_encodings" option is set. Acceptable values are a space-separated list. The default is "mixdown_encodings: ogg mp3".

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.

Saving Projects

The save command is the usual way to save your work. Settings related to the state of the current mix are saved in the file State.json in the current project directory. State.json is tracked by git.

save updates several other data files as well:

Aux.json, in the current project directory, contains data that is part of the project (such as command history and track comments) with no direct effect on the project audio.

global_effect_chains.json, in the project root directory, contains system and user defined effect chains.

save somename.json save to a file of that name. Similarly get somename.json will load the corresponding file. The .json suffix may be omitted if git is disabled in .namarc.

Requirements to Use Git for saving projects

To use git for version control, you must have git installed and, "use_git: 1" must be set in .namarc.

Standard git commands

You can issue git commands in the normal way, and Nama will stay out of your way. Note that merging of branches is untested.

Simplified Workflow Using Git to Manage Project State

Use the save command periodically. On each save command, changes to State.json will be committed to the repository. The commit message will include a list of commands executed since the previous commit.

The save and get commands for branches behave in a similar way to save/restore of named files.

You can say save initial-mix and get initial-mix and have them behave as expected, without being familiar with Git.

What actually happens: save initial-mix will save project state to State.json, commit changes to that file to the git repository, and tag current branch's HEAD commit as "initial-mix". The current branch does not change, remains in the default branch, "master".

Later on, on typing get initial-mix, Nama automatically promotes the tagged commit "initial-mix" to a branch named "initial-mix-branch" which becomes the current branch.

If you want to start a new branch at tag "initial-mix" you can say this:

new_branch compressed-mix initial-mix

Exiting

When you type quit Nama will automatically save your work to State.json. This will overwrite previous settings in State.json. If you don't want this behavior, use Ctrl-C to exit Nama.

Jack ports list file

Use source ports or source filename.ports to ask Nama to connect multiple JACK ports listed in a file (trackname.ports or filename.ports) to the input ports for that track, which will be set to ecasound:trackname_in_1 for mono. A stereo track will use ecasound:trackname_in_2 as well.

If the track is stereo, ports from the list are alternately connected to left and right channels. Larger numbers of channels are handled similarly.

Track edits

An edit is an audio clip associated with a particular track and version. The edit replaces part of the original WAV file, allowing you to fix wrong notes, or substitute one phrase for another.

Each track can host multiple edits. Edits are non-destructive; they are achieved by using Ecasound's ability to crossfade and sequence.

Select the track to be edited and the correct version.

Before creating the edit, you will now need to create three marks:

• play start point =item * rec start point =item * rec end point

The edit will replace the audio between the rec start and rec end points.

There are two ways to set these points.

set_edit_points command

Position the playback head a few seconds before the edit. Enter the set_edit_points command. This will start the engine. Hit the P key three times to designate the playback start, punch-in and punch-out positions.

Specify points individually

Position the playback head at the position you want playback for the edit to start. Enter the set_play_start_mark command.

Use the same procedure to set the rec start and rec end positions using the set_rec_start_mark and set_rec_end_mark commands.

Provide marks as arguments to new_edit (not implemented)

Type new_edit play_start_mark rec_start_mark rec_end_mark.)

Create the edit

Enter the new_edit command to create the necessary tracks and data structures.

Use preview_edit to confirm the edit positions. The engine will run and you will hear the host track with the target region removed. Playback will be restricted to the edit region. You may use preview_out to hear the clip to be removed.

Use list_marks to see the edit marks and modify_mark to nudge them into perfect position.

Once you are satisfied with the mark positions, you are ready to record your edit.

Enter start_edit. Playback will begin at first mark. The replacement clip will be recorded from the source specified in the original track.

Each start_edit command will record an additional version on the edit track. redo_edit will delete (destructively) the most recent audio clip and begin recording anew.

You may specify another range for editing and use the editing procedure again as many times as you like. Edits may not overlap.

Merging edits

merge_edits will recursively merge all edits applied to the current track and version, creating a new version.

I recommend that you merge edits when you are satisfied, with the results to protect your edits against an accidental change in mark, region or version settings.

restore_edits acts on a merged version of the current track, selecting the prior unmerged version with all edits and region definitions in "live" form. You may continue to create new edits. TO BE IMPLEMENTED

list_edits will label the edits by index and time.

end_edit_mode will restore normal playback mode

destroy_edit Behind the scenes, the host track becomes the mix track to a sub-bus. Sources for the bus are the original audio track, and zero or more edits, each represented by one track object.

TEXT COMMANDS

Help commands

help (h) - Display help on Nama commands.

help [ <i_help_topic_index> | <s_help_topic_name> | <s_command_name> ]

help marks help 6 help mfx

help_effect (hfx he) - Display detailed help on a LADSPA or LV2 effect or ask a note to consult the Ecasound manpage for Ecasound's internal effects. For LADSPA and LV2 effects use either the analyseplugin oder analyselv2.

help_effect <s_label> | <i_unique_id>

help_effect 1970 he etd hfx lv2-vocProc

find_effect (ffx fe) - Display one-line help for effects matching the search string(s).

find_effect <s_keyword1> [ <s_keyword2>... ]

find_effect compressor fe feedback

General commands

exit (quit q) - Exit Nama, saving settings (the current project).

exit

memoize - Enable WAV directory caching, so Nama won't have to scan the entire project folder for new fiels after every run.

memoize

unmemoize - Disable WAV directory caching.

unmemoize

Transport commands

stop (s) - Stop transport. Stop the engine, when recording or playing back.

stop

rec start stop

start (t) - Start transport. Start the engine, to start recording or playing back.

start

doodle start stop

getpos (gp) - Get the current playhead position (in seconds).

getpos

start gp

setpos (sp) - Set current playhead position (in seconds).

setpos <f_position_seconds>

setpos 65.0

forward (fw) - Move playback position forwards (in seconds). Oldschool forwarding.

forward <f_increment_seconds>

fw 23.7

rewind (rw) - Move playback position backwards (in seconds). Oldschool rewind.

rewind <f_decrement_seconds>

rewind 6.5

to_start (beg) - Set the playback head to the start. A synonym for setpos 0.0 .

to_start

to_end (end) - Set the playback head to end minus 10 seconds.

to_end

ecasound_start (T) - Ecasound-only start. Mainly useful for diagnostics and debugging. Use the command start in normal circumstances.

ecasound_start

ecasound_stop (S) - Ecasound-only stop. Mainly useful for diagnostics and debugging. Use command stop in normal circumstances.

ecasound_stop

restart_ecasound - Restart the Ecasound application again, when it has crashed or is behaving oddly.

restart_ecasound

preview - Enter the preview mode. Configure Nama to allow playback and passthru of inputs (for mic test, rehearsals, etc.). Nothing is recorded to disk!

preview

rec preview start stop arm

doodle - Enter the doodle mode. In doodle mode all live inputs from tracks - set to record - are enabled. Nama excludes multiple tracks having the same input. This mode is designed to allow rehearsing and adjusting effects without listening to playback -as in preview.

doodle

doodle start stop arm

Mix commands

mixdown (mxd) - Enter mixdown mode for subsequent engine runs. You will record new mixes, until you leave mixdown mode by mixoff.

mixdown

mxd t mxo

mixplay (mxp) - Enter mixdown file playback mode, setting user tracks to OFF and only playing the Mixdown track. You can leave the mixplay mode by using mixoff.

mixplay

mixplay start stop mxo

mixoff (mxo) - Leave the mixdown or mixplay mode. Set Mixdown track to OFF, user tracks to MON.

mixoff

automix - Normalize track volume levels and fix DC-offsets. Then mix dwn to the Mixdown track.

automix

master_on (mr) - Turn on the mastering mode, adding tracks Eq, Low, Mid, High and Boost, if necessary. The mastering setup allows for one EQ and a three-band multiband compression and a final boosting stage. Leave the mastering mode by master_off.

master_on

mr start stop

master_off (mro) - Leave mastering mode. Remove the EQ, multi-band compression and Booster.

master_off

Track commands

add_track (add new) - Create a new audio track.

add_track <s_name>

add_track clarinet

add_tracks - Create one or more new tracks in one go.

add_tracks <s_name1> [ <s_name2>... ]

add_tracks violin viola contra_bass

link_track (link) - Create a read-only track, that uses audio files from another track.

link_track <s_dest_name> <s_source_name> [ <s_project> ]

link part_1 Mixdown my_long_song_1 link_track piano_conp piano

import_audio (import) - Import a sound file (wav, ogg, mp3, etc.) to the current track, resampling it, if necessary.

import_audio <s_full_path_to_file> [ <i_frequency> ]

import /home/samples/bells.flac import /home/music/song.mp3 44100

set_track - Directly set current track parameters (use with care!).

set_track <s_track_field> <value>

record (rec) - Set current track to record from its input (also known as REC-enabling).

record

rec start stop

mon (on) - Set current track to playback the currently selected version. by default the last version is always played.

mon

mon

off (z) - Set current track to OFF (exclude from setup). You can include the track with mon or rec.

off

rec_defeat (rd) - Prevent writing an audio file for the current track. So the track will just pass thru the incoming audio. Useful for tracks connected to internal signal generators.

rec_defeat

rec_enable (re) - Allow writing an audio file for the current track. This is the opposite to rec_defeat. Useful to record a metronome or other special track to disk.

rec_enable

source (src r) - Set the current track's input (source). This can be a soundcard channel or a JACK client name.

source <i_soundcard_channel> | 'null' | <s_jack_client_name> | <s_jack_port_name> | 'jack'

source 3 source null src LinuxSampler r synth:output_3 src jack

send (aux) - Set an aux send for the current track. Remove sends with remove_send .

send <i_soundcard_channel> | <s_jack_client_name> | <s_loop_id>

send 3 send jconvolver

remove_send (nosend noaux) - Remove an aux send from the current track.

remove_send

stereo - Set the current track to stereo (two channels). Will record two channels or easily import stereo audio files.

stereo

mono - Set the current track to mono (one channel). Will record one channel or easily import mono audio files (this is the default, when creating a track).

mono

set_version (version ver) - Set the active version of the current track for playback/monitoring (overrides group version setting).

set_version <i_version_number>

piano version 2 sh

destroy_current_wav - DESTRUCTIVE: Remove the current track\'s currently selected recording. This removes the underlying audio file on your disk. USE WITH CARE!

destroy_current_wav

list_versions (lver) - List versions of the current track. This will print the numbers of all versions of this track to the screen.

list_versions

list_versions

vol (v) - Change or show the current track's volume.

vol [ [ + | - | / | * ] <f_volume> ]

vol * 1.5 vol 75 vol - 5.7 vol

mute (c cut) - Mute the current track. Turn the current track's volume absolutely down. You can unmute the track with the command unmute.

mute

unmute (C uncut) - Restore previous volume level. It can be used after mute or solo.

unmute

unity - Set the current track's volume to unity. This will change the volume to the default value (100% or 0 dB).

unity

vol 55 unity vol

solo (sl) - Mute all tracks but the current track or the tracks or bunches specified. You can reverse this with nosolo.

solo [ <strack_name_1> | <s_bunch_name_1> ] [ <s_track_name_2 | <s_bunch_name_2> ] ...

solo nosolo solo piano bass Drums

nosolo (nsl) - Unjute all tracks, which have been turned down by solo. Tracks, that had beenmuted before the solo command stay muted.

nosolo

all - Unmute all tracks, this includes tracks muted by solo and other single tracks muted previously by mute.

all

piano mute sax solo all

pan (p) - Change or display the current panning position of the current track. Panning is moving the audio in the stereo panorama between right and left. Position is given in percent. 0 is hard left and 100 hard right, 50% is dead centre.

pan [ <f_pan_position_in_percent> ]

pan 75 p 50 pan

pan_right (pr) - Pan the current track hard right. this is a synonym for pan 100 . Can be reverse with pan_back .

pan_right

pan_left (pl) - Pan the current track hard left. This is a synonym for pan 0 . Can be reversed with pan_back .

pan_left

pan_center (pc) - Pan the current track to the centre. This is a synonym for pan 50 . Can be reversed with pan_back .

pan_center

pan_back (pb) - Restore the current track's pan position prior to pan_left, pan_right or pan_center .

pan_back

show_tracks (lt show) - Show a list of tracks, including their index number, volume, pan position, recording status and input.

show_tracks

show_tracks_all (sha showa) - Show a list of all tracks, visible and hidden, with their ndex number, recording status, input, volume and pan position. This is mainly useful for diagnostics and debugging.

show_tracks_all

show_bus_tracks (ltb showb) - Show a list of tracks in the current bus.

show_bus_tracks

show_track (sh) - Display information about the current track, including index, recording status, effects, inserts, versions, stereo width (a.k.a. channel count) and controllers.

show_track

Setup commands

show_mode (shm) - Display the current record/playback mode. this will indicate the mode - i.e. doodle, preview, etc. - and possible record/playback settings.

show_mode

Track commands

show_track_latency (shl) - Display the latency information for the current track.

show_track_latency

Diagnostics commands

show_latency_all (shla) - Dump all latency data.

show_latency_all

Track commands

set_region (srg) - Specify a playback region for the current track using marks. Use the command new_region to create more than one region from a track. Can be reversed with remove_region .

set_region <s_start_mark_name> <s_end_mark_name>

sax setpos 2.5 mark sax_start sp 120.5 mark sax_end set_region sax_start sax_end

add_region (arg) - Create a region for the current track using an auxiliary track. This is a named region, which leaves the original track visible and untouched.

add_region <s_start_mark_name> | <f_start_time> <s_end_mark_name> | <f_end_time> [ <s_region_name> ]

sax new_region sax_start 66.7 trimmed_sax

remove_region (rrg) - Remove the current region (including associated the auxiliary track).

remove_region

shift_track (shift playat pat) - Move the beginning of the track or region, also known as offsetting or shifting. Can be reversed by unshift_track .

shift_track <s_start_mark_name> | <i_start_mark_index | <f_start_seconds>

piano shift 6.7

unshift_track (unshift) - Move the start of a track or region back to 0.0 seconds (the beginning of the setup.

unshift_track

modifiers (mods mod) - Add/show modifiers for the current track (man ecasound for details). This is only useful in rare cases.

modifiers [ Audio file sequencing parameters ]

modifiers select 5 15.2

nomodifiers (nomods nomod) - Remove modifiers from the current track.

nomodifiers

normalize (norm ecanormalize) - Apply ecanormalize to the current track version. This will raise the gain/volume of the current track as far as possible and store it that way on disk. Note: this will permanently change the file.

normalize

fixdc (ecafixdc) - Fix the DC-offset of the current track using ecafixdc. Note: This will permanently change the file.

fixdc

autofix_tracks (autofix) - Apply the commands fixdc and normalize to all current version of all tracks, that are set to playback, i.e. MON .

autofix_tracks

remove_track - Remove the current track. This will only remove the effects and display. all recorded audio will emain on your disk. The default is to ask, before Nama removes a track. this can be changed in namarc .

remove_track

Bus commands

bus_rec (brec grec) - Set a bus mix_track to record (the default behaviour).

bus_rec

bus_mon (bmon gmon) - Set a bus mix_track to playback. This only does anything, if a complete bus has been cached/frozend/bounced before.

bus_mon

bus_off (boff goff) - Set a bus mixtrack to OFF. Can be reversed with bus_rec and bus_mon.

bus_off

Group commands

bus_version (bver gver) - Set the default monitoring version for tracks in the current bus.

bus_version

add_bunch (abn) - Define a bunch of tracks. A bunch is useful for shorter for statements.

add_bunch <s_bunch_name> [ <s_track_name_1> | <i_track_index_1> ] ...

new_bunch woodwind nb strings violin cello basso for strings;mute for strings;vol * 0.8

list_bunches (lbn) - Dispaly a list of all bunches and their tracks.

list_bunches

remove_bunch (rbn) - Remove the specified bunches. This does not remove the tracks, only the groupings.

remove_bunch <s_bunch_name> [ <s_bunch_name> ] ...

add_to_bunch (atbn) - Add track(s) to a bunch.

add_to_bunch <s_bunch_name> <s_track1> [ <s_track2> ] ...

add_to_bunch woodwind oboe sax_1 flute

Project commands

commit (ci) - Commit Nama's current state

commit <s_message>

tag - Git tag the current branch HEAD commit

tag <s_tag_name> [<s_message>]

branch (br) - Change to named branch

branch <s_branch_name>

list_branches (lb lbr) - List branches when called with no arguments

list_branches <s_branch_name>

new_branch (nbr) - Create a new branch

new_branch <s_new_branch_name> [<s_existing_branch_name>]

save_state (keep save) - Save the project settings as file or tagged commit

save_state [ <s_settings_target> [ <s_message> ] ]

get_state (get recall retrieve) - Retrieve project settings from file, branch or tag

get_state <s_settings_target>

list_projects (lp) - List all projects. This will list all Nama projects, which are stored in the Nama project root directory.

list_projects

new_project (create) - Create or open a new empty Nama project.

new_project <s_new_project_name>

create my_song

load_project (load) - Load an existing project. This will load the project from the default project state file. If you wish to load a project state saved to a user specific file, load teh project and then use get_state.

load_project <s_existing_project_name>

load my_old_song

project_name (project name) - Display the name of the current project.

project_name

new_project_template (npt) - Make a project template based on the current project. This will include tracks and busses.

new_project_template <s_template_name> [ <s_template_description> ]

new_project_template my_band_setup "tracks and busses for bass, drums and me"

use_project_template (upt apt) - Use a template to create tracks in a newly created, empty project.

use_project_template <s_template_name>

apt my_band_setup

list_project_templates (lpt) - List all project templates.

list_project_templates

destroy_project_template - Remove one or more project templates.

destroy_project_template <s_template_name1> [ <s_template_name2> ] ...

Setup commands

generate (gen) - Generate an Ecasound chain setup for audio processing manually. Mainly useful for diagnostics and debugging.

generate

arm - Generate and connect a setup to record or playback. If you are in dodle or preview mode, this will bring you back to normal mode.

arm

arm_start (arms) - Generate and connect the setup and then start. This means, that you can directly record or listen to your tracks.

arm_start

connect (con) - Connect the setup, so everything is ready to run. Ifusing JACK, this means, that Nama will connect to all the necessary JACK ports.

connect

disconnect (dcon) - Disconnect the setup. If running with JACK, this will disconnect from all JACK ports.

disconnect

show_chain_setup (chains) - Show the underlying Ecasound chain setup for the current working condition. Mainly useful for diagnostics and debugging.

show_chain_setup

loop (l) - Loop the playback between two points. Can be stopped with loop_disable

loop <s_start_mark_name> | <i_start_mark_index> | <f_start_time_in_secs> <s_end_mark_name> | <i_end_mark_index> | <f_end_time_in_secs>

loop 1.5 10.0 loop 1 5 loop sax_start 12.6

noloop (nl) - Disable looping.

noloop

Effect commands

add_controller (acl) - Add a controller to an effect (current effect, by default). Controllers can be modified by using mfx and remove using rfx.

add_controller [ <s_operator_id> ] <s_effect_code> [ <f_param1> <f_param2> ] ...

add_effect etd 100 2 2 50 50 acl E klg 1 100 200 2 0 100 15 200

add_effect (afx) - Add an effect prefader (before vol/pan controls) to the current track. Remove effects with reove_effect.

add_effect <s_effect_code> [ <f_param1> <f_param2>... ]

help_effect decimator afx decimator 12 22050

append_effect (apfx) - Add an effect postfader (after vol/pan conrols) to the current track. Remove effect with remove_effect.

append_effect <s_effect_code> [ <f_param1> <f_param2> ] ...

apfx var_dali

insert_effect (ifx) - Place an effect before the specified unique effect ID. You will experience a short pause in playback.

insert_effect <s_insert_point_id> <s_effect_code> [ <f_param1> <f_param2> ] ...

lfx ifx AF etd 125 2 2 40 60

modify_effect (mfx modify_controller mcl) - Modify effect parameter(s).

modify_effect [ <s_effect_id> ] <i_parameter> [ + | - | * | / ] <f_value>

lfx mfx AF 1 62 mfx AF,BG 1 75 mfx CE 6,10 -3 mfx D 4 + 10 mfx A,B,C 3,6 * 5

remove_effect (rfx remove_controller rcl) - Remove effects. They don't have to be on the current track.

remove_effect <s_effect_id1> [ <s_effect_id2> ] ...

position_effect (pfx) - Position an effect before another effect (use 'ZZZ' for end).

position_effect <s_id_to_move> <s_position_id>

position_effect G F

show_effect (sfx) - Show information about an effect. Default is to print information on the current effect.

show_effect [ <s_effect_id1> ] [ <s_effect_id2> ] ...

sfx sfx H

list_effects (lfx) - Print a short list of all effects on the current track, only including unique ID and effect name.

list_effects

add_insert (ain) - Add an external send/return insert to current track.

add_insert ( pre | post ) <s_send_id> [ <s_return_id> ] -or- local (for wet/dry control)

add_insert pre jconvolver ain post jconvolver csound guitar ain local guitar-1-wet afx G2reverb 50 5.0 0.6 0.5 0 -16 -20 afx etc 6 100 45 2.5 guitar wet 25

set_insert_wetness (wet) - Set wet/dry balance of the insert for the current track. The balance is given in percent, 0 meaning dry and 100 wet signal only.

set_insert_wetness [ pre | post ] <n_wetness>

wet pre 50 set_insert_wetness 100

remove_insert (rin) - Remove an insert from the current track.

remove_insert [ pre | post ]

rin remove_insert post

ctrl_register (crg) - List all Ecasound controllers. Controllers include linear controllers and oscillators.

ctrl_register

preset_register (prg) - List all Ecasound effect presets. See the Ecasound manpage for more detail on effect_presets.

preset_register

ladspa_register (lrg) - List all LADSPA plugins, that Ecasound/Nama can find.

ladspa_register

Mark commands

list_marks (lmk lm) - List all marks with index, name and their respective positions in time.

list_marks

to_mark (tmk tom) - Move the playhead to the named mark or mark index.

to_mark <s_mark_name> | <i_mark_index>

to_mark sax_start tmk 2

add_mark (mark amk) - Drop a new mark at the current playback position. this will fail, if a mark is already placed on that exact position.

add_mark [ <s_mark_id> ]

k important

remove_mark (rmk rom) - Remove a mark. The default is to remove the current mark, if no parameter is given.

remove_mark [ <s_mark_name> | <i_mark_index> ]

remove_mark important rmk 16

next_mark (nmk) - Move the playhead to the next mark.

next_mark

previous_mark (pmk) - Move the playhead to the previous mark.

previous_mark

name_mark - Give a name to the current mark.

name_mark <s_mark_name>

modify_mark (move_mark mmk) - Change the position (time) of the current mark.

modify_mark [ + | - ] <f_seconds>

move_mark + 2.3 mmk 16.8

Diagnostics commands

engine_status (egs) - Display the Ecasound audio processing engine status.

engine_status

dump_track (dump) - Dump current track data.

dump_track

dump_group (dumpg) - Dump group settings for user tracks.

dump_group

dump_all (dumpa) - Dump most internal state data.

dump_all

dump_io - Show chain inputs and outputs.

dump_io

Help commands

list_history (lh) - List the command history. Every project stores its own command history.

list_history

Bus commands

add_send_bus_cooked (asbc) - Add a send bus, that copies all user tracks with effects and inserts (a.k.a. cooked signals). All busses begin with a capital letter!

add_send_bus_cooked <s_name> <destination>

asbc Reverb jconv

add_send_bus_raw (asbr) - Add a send bus, that copies all user tracks wihtout processing (a.k.a. raw signals). All busses begin with a capital letter!

add_send_bus_raw <s_name> <destination>

asbr Reverb jconv

add_sub_bus (asub) - Add a sub bus. This is a bus, as known from other DAWs. The default output goes to a mix track and that is routed to the mixer (the Master track). All busses begin with a capital letter!

add_sub_bus <s_name> [ <s_track_name> | <s_jack_client> | <i_soundcard_channel> ]

asub Brass asub special csound

update_send_bus (usb) - Include tracks added since the send bus was created.

update_send_bus <s_name>

update_send_bus Reverb

remove_bus - Remove a bus.

remove_bus <s_bus_name>

list_buses (lbs) - List buses and their parameters (TODO).

list_buses

set_bus (sbs) - Set bus parameters. This command is intended for advanced users.

set_bus <s_busname> <key> <value>

Effect commands

new_effect_chain (nec) - Create a new effect chain. An effect chain i a list of effects with all their parameters stored. Useful for creating small processing templates for frequently used instruments.

new_effect_chain <s_name> [ <effect_id_1>, <effect_id_2> ] ...

new_effect_chain my_piano nec my_guitar A C F G H

add_effect_chain (aec) - Add an effect chain to the current track.

add_effect_chain <s_effect_chain_name>

aec my_piano

overwrite_effect_chain (oec) - Add an effect chain, overwriting or replacing the current effects. Current effects are pushed onto the bypass list, so they aren't lost completely.

overwrite_effect_chain <s_effect_chain_name>

delete_effect_chain (dec destroy_effect_chain) - Delete an effect chain definition. After that the effect chain will no longer be available to add. Projects, which use the effect chain won't be affected.

delete_effect_chain <s_effect_chain_name>

find_effect_chains (fec) - Dump effect chains, matching key/value pairs if provided

find_effect_chains [ <s_key_1> <s_value_1> ] ...

fec

find_user_effect_chains (fuec) - List all *user* created effect chains, matching key/value pairs, if provided.

find_user_effect_chains [ <s_key_1> <s_value_1> ] ...

bypass_effects (bypass bfx) - Bypass effects on the current track. With no parameters default to bypassing the current effect.

bypass_effects [ <s_effect_id_1> <s_effect_id_2>... | 'all' ]

bypass all bypass AF

bring_back_effects (restore_effects bbfx) - Restore effects. If no parameter is given, the default is to restore the current effect.

bring_back_effects [ <s_effect_id_1> <s_effect_id_2> ... | 'all' ]

bbfx restore_effect AF bring_back_effects all

new_effect_profile (nep) - Create a new effect profile. An effect profile is a named group of effect chains for multiple tracks. Useful for storing a basic template of standard effects for a group of instruments, like a drum kit.

new_effect_profile <s_bunch_name> [ <s_effect_profile_name> ]

new_bunch Drums snare toms kick nep Drums my_drum_effects

apply_effect_profile (aep) - Apply an effect profile. this will add all the effects in it to the list of tracks stored in the effect profile. Note: You must give the tracks the same names as in the original project, where you created the effect profile.

apply_effect_profile <s_effect_profile_name>

destroy_effect_profile - Delete an effect profile. This will delete the effect profile definition from your disk. All projects, which use this effect profile will NOT be affected.

destroy_effect_profile <s_effect_profile_name>

list_effect_profiles (lep) - List all effect profiles.

list_effect_profiles

show_effect_profiles (sepr) - List effect profile.

show_effect_profiles

full_effect_profiles (fep) - Dump effect profile data structure.

full_effect_profiles

Track commands

cache_track (cache ct) - Cache the current track, a.k.a. freezing or bouncing. Store a version of the current track with all processing to disk. Useful to save on processor power in large projects. Can be reversed by uncache_track .

cache_track [ <f_additional_processing_time> ]

cache 10

Effect commands

uncache_track (uncache unc) - Select the uncached track version. This restores effects, but not inserts.

uncache_track

General commands

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.

do_script <s_filename>

do prepare_my_drums

scan - Re-read the project's .wav directory. Mainly useful for troubleshooting.

scan

Effect commands

add_fade (afd fade) - Add a fade-in or fade-out to the current track.

add_fade ( in | out ) marks/times (see examples)

fade in mark1 fade out mark2 2 fade out 2 mark2 fade in mark1 mark2

remove_fade (rfd) - Remove a fade from the current track.

remove_fade <i_fade_index_1> [ <i_fade_index_2> ] ...

list_fade rfd 2

list_fade (lfd) - List all fades.

list_fade

Track commands

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.

add_comment <s_comment>

ac "Guitar, treble on 50%"

remove_comment (rc) - Remove a comment from the current track.

remove_comment

show_comment (sc) - Show the comment for the current track.

show_comment

show_comments (sca) - Show all track comments.

show_comments

add_version_comment (avc) - Add a version comment (replacing any previous user comment). This will add a comment for the current version of the current track.

add_version_comment <s_comment>

avc "The good take with the clear 6/8"

remove_version_comment (rvc) - Remove version comment(s) from the current track.

remove_version_comment

show_version_comment (svc) - Show version comment(s) of the curent track.

show_version_comment

show_version_comments_all (svca) - Show all version comments for the current track.

show_version_comments_all

set_system_version_comment (ssvc) - Set a system version comment. Useful for testing and diagnostics.

set_system_version_comment <s_comment>

Midi commands

midish_command (m) - Send the command text to the midish MIDI sequencer. Midish must be installed and enabled in namarc. See the midish manpage and fullonline documentation for more.

midish_command <s_command_text>

m tracknew my_midi_track

midish_mode_on (mmo) - All users commands sent to midish, until

midish_mode_on

midish_mode_off (mmx) - Exit midish mode, restore default Nama command mode, no midish sync

midish_mode_off

midish_mode_off_ready_to_play (mmxrp) - Exit midish mode, sync midish start (p) with Ecasound

midish_mode_off_ready_to_play

midish_mode_off_ready_to_record (mmxrr) - Exit midish mode, sync midish start (r) with Ecasound

midish_mode_off_ready_to_record

Edit commands

new_edit (ned) - Create an edit for the current track and version.

new_edit

set_edit_points (sep) - Mark play-start, record-start and record-end positions for the current edit.

set_edit_points

list_edits (led) - List all edits for current track and version.

list_edits

select_edit (sed) - Select an edit to modify or delete. After selection it is the current edit.

select_edit <i_edit_index>

end_edit_mode (eem) - Switch back to normal playback/record mode. The track will play full length again. Edits are managed via a sub- bus.

end_edit_mode

destroy_edit - Remove an edit and all associated audio files. If no parameter is given, the default is to destroy the current edit. Note: The data will be lost permanently. Use with care!

destroy_edit [ <i_edit_index> ]

preview_edit_in (pei) - Play the track region without the edit segment.

preview_edit_in

preview_edit_out (peo) - Play the removed edit segment.

preview_edit_out

play_edit (ped) - Play a completed edit.

play_edit

record_edit (red) - Record an audio file for the current edit.

record_edit

edit_track (et) - Set the edit track as the current track.

edit_track

host_track_alias (hta) - Set the host track alias as the current track.

host_track_alias

host_track (ht) - Set the host track (edit sub-bus mix track) as the current track.

host_track

version_mix_track (vmt) - Set the version mix track as the current track.

version_mix_track

play_start_mark (psm) - Select (and move to) play start mark of the current edit.

play_start_mark

rec_start_mark (rsm) - Select (and move to) rec start mark of the current edit.

rec_start_mark

rec_end_mark (rem) - Select (and move to) rec end mark of the current edit.

rec_end_mark

set_play_start_mark (spsm) - Set play_start_mark to the current playback position.

set_play_start_mark

set_rec_start_mark (srsm) - Set rec_start_mark to the current playback position.

set_rec_start_mark

set_rec_end_mark (srem) - Set rec_end_mark to current playback position.

set_rec_end_mark

disable_edits (ded) - Turn off the edits for the current track and playback the original. This will exclude the edit sub bus.

disable_edits

merge_edits (med) - Mix edits and original into a new host-track. this will write a new audio file to disk and the host track will have a new version for this.

merge_edits

Track commands

explode_track - Make the current track into a sub bus, with one track for each version.

explode_track

move_to_bus (mtb) - Move the current track to another bus. A new track is always in the Main bus. So to reverse this action use move_to_bus Main .

move_to_bus <s_bus_name>

asub Drums snare mtb Drums

promote_version_to_track (pvt) - Create a read-only track using the specified version of the current track.

promote_version_to_track <i_version_number>

General commands

read_user_customizations (ruc) - Re-read the user customizations file 'custom.pl'.

read_user_customizations

Setup commands

limit_run_time (lr) - Stop recording after the last audio file finishes playing. Can be turned off with limit_run_time_off.

limit_run_time [ <f_additional_seconds> ]

limit_run_time_off (lro) - Disable the recording stop timer.

limit_run_time_off

offset_run (ofr) - Record/play from a mark, rather than from the start, i.e. 0.0 seconds.

offset_run <s_mark_name>

offset_run_off (ofro) - Turn back to starting from 0.

offset_run_off

General commands

view_waveform (wview) - Launch mhwavedit to view/edit waveform of the current track and version. This requires to start Nama on a graphical terminal, like xterm or gterm or from GNOME via alt+F2 .

view_waveform

edit_waveform (wedit) - Launch audacity to view/edit the waveform of the current track and version. This requires starting Nama on a graphical terminal like xterm or gterm or from GNOME starting Nama using alt+F2 .

edit_waveform

Setup commands

rerecord (rerec) - Record as before. This will set all the tracks to record, which have been recorded just before you listened back.

rerecord

for piano guitar;rec rerec

General commands

eager - Output audio as soon as possible. This will start playing or recording, as soon as a working setup is created.

eager off | doodle | preview

eager doodle eager off

Track commands

analyze_level (anl) - Print Ecasound amplitude analysis for current track. This will show highest volume and statistics.

analyze_level

General commands

for - Execute command(s) for several tracks.

for <s_track_name_1> [ <s_track_name_2>} ... ; <s_commands>

for piano guitar;vol / 2;pan 75 for snare kick toms cymbals;mtb Drums

Project commands

git - Execute git command in the project directory

git <s_command_name> [argument,...]

DIAGNOSTICS

On any change in setup, the GUI display updates and show_tracks command is executed automatically showing what to expect the next time the engine is started.

You can use the chains command to verify the Ecasound chain setup. (The Ecasound command cs-save-as mysetup.ecs will additionally store all engine data, effects as well as routing.)

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 commands, available on Unixlike systems with Perl installed, will pull in Nama and other Perl libraries required for text mode operation:

cpanm Audio::Nama -or- PERL_MM_USE_DEFAULT=1 cpan Audio::Nama

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

cpanm Tk

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

cpanm 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 Nama mailing list is a suitable forum for questions regarding Nama installation, usage, bugs, feature requests, etc.

http://www.freelists.org/list/nama

For questions and discussion related to Ecasound

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

PATCHES

The modules that make up this application are the preprocessed output from several source files. Patches against these source files are preferred.

AUTHOR

Joel Roth, <joelz@pobox.com>

COPYRIGHT & LICENSE

Copyright (c) 2009-2013 by Joel Roth.

This is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, Version 3.

cpanm Audio::Nama

perl -MCPAN -e shell
install Audio::Nama