Provided by: nama_1.078-2_all bug

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 WAV 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, providing command history and autocompletion.  The help system
       covers internal commands and LADSPA effects and includes keyword search.

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

   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 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 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, one for general control, the second for effects.

       The main window 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 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 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

       We describe the effect of Main bus REC/MON/OFF settings on member tracks. (Sub-bus
       settings have similar effects on their tracks.)

       The Main bus REC setting does not limit user track status in any way.

       The Main bus MON setting disables recording for member tracks.  Track REC status is forced
       to MON if a WAV file is available, or OFF if no WAV file is available.

       The Main bus OFF setting forces all user tracks to OFF status, causing them 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.

       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.

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

       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.

       Only one region may be specified per track. To work around this limitation, use the
       "new_region" command to clone a track, specifying a new region definition. You can then
       independently control volume and pan of this new region, apply effects, etc.

       The "link_track" command can clone tracks from other Nama 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 initial volume operator, -eadb, is additionally applied to
       tracks as necessary 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" 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 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
       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 a name and a 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 -+
                              |       |
                ------ 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.

   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.

   Autosave
       The save command is the usual way to save your work.  Most settings are saved in the file
       State.yml in the current project directory.

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

       If you load a new project and there are unsaved changes, Nama will automatically save
       settings in a file tagged with the current date and time, for example,
       State-autosave-2010.09.20-15:32:05.

       By specifying some number of minutes for the autosave_interval configuration variable in
       your .namarc file, Nama will save your settings periodically. However, Nama will not save
       settings while the engine is running.

       To avoid creating duplicate files, the new settings file will be created only if it
       differs from the previous file.

   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

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

       help_effect (hfx he) - Display analyseplugin output if available or one-line help

               "help_effect" <s_label> | <i_unique_id>

       find_effect (ffx fe) - Display one-line help for effects matching search strings

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

   General commands
       exit (quit q) - Exit program, saving settings

               "exit"

       memoize - Enable WAV dir cache

               "memoize"

       unmemoize - Disable WAV dir cache

               "unmemoize"

   Transport commands
       stop (s) - Stop transport

               "stop"

       start (t) - Start transport

               "start"

       getpos (gp) - Get current playhead position (seconds)

               "getpos"

       setpos (sp) - Set current playhead position

               "setpos" <f_position_seconds>

               "setpos 65 (set play position to 65 seconds from start)"

       forward (fw) - Move playback position forward

               "forward" <f_increment_seconds>

       rewind (rw) - Move transport position backward

               "rewind" <f_increment_seconds>

       to_start (beg) - Set playback head to start

               "to_start"

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

               "to_end"

       ecasound_start (T) - Ecasound-only start

               "ecasound_start"

       ecasound_stop (S) - Ecasound-only stop

               "ecasound_stop"

       preview - Start engine with rec_file disabled (for mic test, etc.)

               "preview"

       doodle - Start engine while monitoring REC-enabled inputs

               "doodle"

   Mix commands
       mixdown (mxd) - Enable mixdown for subsequent engine runs

               "mixdown"

       mixplay (mxp) - Enable mixdown file playback, setting user tracks to OFF

               "mixplay"

       mixoff (mxo) - Set Mixdown track to OFF, user tracks to MON

               "mixoff"

       automix - Normalize track vol levels, then mixdown

               "automix"

       master_on (mr) - Enter mastering mode. Add tracks Eq, Low, Mid, High and Boost if
       necessary

               "master_on"

       master_off (mro) - Leave mastering mode

               "master_off"

   Track commands
       add_track (add new) - Create a new track

               "add_track" <s_name> [ <s_key1> <s_val1> <s_key2> <s_val2>... ]

               "add_track clarinet group woodwinds"

       add_tracks (add new) - Create one or more new tracks

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

               "add_track sax violin tuba"

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

               "link_track" <s_name> <s_target> [ <s_project> ]

               "link_track intro Mixdown song_intro creates a track 'intro' using all .WAV
               versions from the Mixdown track of 'song_intro' project"

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

               "import_audio" <s_wav_file_path> [i_frequency]

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

               "set_track" <s_track_field> value

       rec - REC-enable current track

               "rec"

       mon (on) - Set current track to MON

               "mon"

       off (z) - Set current track to OFF (exclude from chain setup)

               "off"

       rec_defeat (rd) - Prevent writing a WAV file for current track

               "rec_defeat"

       rec_enable (re) - Allow writing a WAV file for current track

               "rec_enable"

       source (src r) - Set track source

               "source" <i_soundcard_channel> | 'null' (for metronome) | <s_jack_client_name> |
               <s_jack_port_name> | 'jack' (opens ports ecasound:trackname_in_N, connects ports
               listed in trackname.ports if present in project_root dir)

               "source "MPlayer [20120]:out_0""

       send (out aux) - Set aux send

               "send" <i_soundcard_channel> (3 or above) | <s_jack_client_name>

       remove_send (nosend rms) - Remove aux send

               "remove_send"

       stereo - Record two channels for current track

               "stereo"

       mono - Record one channel for current track

               "mono"

       set_version (version n ver) - Set track version number for monitoring (overrides group
       version setting)

               "set_version" <i_version_number>

               "sax; version 5; sh"

       destroy_current_wav - Unlink current track's selected WAV version (use with care!)

               "destroy_current_wav"

       list_versions (lver lv) - List version numbers of current track

               "list_versions"

       vol (v) - Set, modify or show current track volume

               "vol" [ [ + | - | * | / ] <f_value> ]

               "vol * 1.5 (multiply current volume setting by 1.5)"

       mute (c cut) - Mute current track volume

               "mute"

       unmute (C uncut) - Restore previous volume level

               "unmute"

       unity - Set current track volume to unity

               "unity"

       solo (sl) - Mute all but current track

               "solo" [track_name(s)] [bunch_name(s)]

       nosolo (nsl) - Release solo, previously muted tracks are still muted

               "nosolo"

       all - Release solo, unmuting all tracks

               "all"

       pan (p) - Get/set current track pan position

               "pan" [ <f_value> ]

       pan_right (pr) - Pan current track fully right

               "pan_right"

       pan_left (pl) - Pan current track fully left

               "pan_left"

       pan_center (pc) - Set pan center

               "pan_center"

       pan_back (pb) - Restore current track pan setting prior to pan_left, pan_right or
       pan_center

               "pan_back"

       show_tracks (lt) - Show track status

               "show_tracks"

       show_tracks_all (show sha showa) - Show status of all tracks, visible and hidden

               "show_tracks_all"

       show_bus_tracks (shb) - Show tracks in current bus

               "show_bus_tracks"

       show_track (sh) - Show current track status

               "show_track"

   Setup commands
       show_mode (shm) - Show current record/playback modes

               "show_mode"

   Track commands
       set_region (srg) - Specify a playback region for the current track using marks. Use
       'new_region' for multiple regions.

               "set_region" <s_start_mark_name> <s_end_mark_name>

       new_region (nrg) - Create a region for the current track using an auxiliary track

               "new_region" <s_start_mark_name> <s_end_mark_name> [<s_region_name>]

       remove_region (rrg) - Remove region (including associated auxiliary track)

               "remove_region"

       shift_track (shift playat pat) - Set playback delay for track or region

               "shift_track" <s_start_mark_name> | <i_start_mark_index | <f_start_seconds>

       unshift_track (unshift) - Remove playback delay for track or region

               "unshift_track"

       modifiers (mods mod) - Set/show modifiers for current track (man ecasound for details)

               "modifiers" [ Audio file sequencing parameters ]

               "modifiers select 5 15.2"

       nomodifiers (nomods nomod) - Remove modifiers from current track

               "nomodifiers"

       normalize (norm ecanormalize) - Apply ecanormalize to current track version

               "normalize"

       fixdc (ecafixdc) - Apply ecafixdc to current track version

               "fixdc"

       autofix_tracks (autofix) - Fixdc and normalize selected versions of all MON tracks

               "autofix_tracks"

       remove_track - Remove effects, parameters and GUI for current track

               "remove_track"

   Bus commands
       bus_rec (brec grec) - Rec-enable bus tracks

               "bus_rec"

       bus_mon (bmon gmon) - Set group-mon mode for bus tracks

               "bus_mon"

       bus_off (boff goff) - Set group-off mode for bus tracks

               "bus_off"

   Group commands
       bus_version (bn bver bv gver gn gv) - Set default monitoring version for tracks in current
       bus

               "bus_version"

       new_bunch (nb) - Define a bunch of tracks

               "new_bunch" <s_group_name> [<s_track1> <s_track2>...]

       list_bunches (lb) - List track bunches

               "list_bunches"

       remove_bunches (rb) - Remove the definition of a track bunch

               "remove_bunches" <s_bunch_name> [<s_bunch_name>...]

       add_to_bunch (ab) - Add track(s) to a bunch

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

   Project commands
       save_state (keep save) - Save project settings to disk

               "save_state" [ <s_settings_file> ]

       get_state (recall retrieve) - Retrieve project settings

               "get_state" [ <s_settings_file> ]

       list_projects (lp) - List projects

               "list_projects"

       create_project (create) - Create a new project

               "create_project" <s_new_project_name>

       load_project (load) - Load an existing project using last saved state

               "load_project" <s_project_name>

       project_name (project name) - Show current project name

               "project_name"

       new_project_template (npt) - Make a project template based on current project

               "new_project_template" <s_template_name> [<s_template_description>]

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

               "use_project_template" <s_template_name>

       list_project_templates (lpt) - List project templates

               "list_project_templates"

       remove_project_template (rpt dpt) - Remove one or more project templates

               "remove_project_template" <s_template_name1> [<s_template_name2>... ]

   Setup commands
       generate (gen) - Generate chain setup for audio processing

               "generate"

       arm - Generate and connect chain setup

               "arm"

       connect (con) - Connect chain setup

               "connect"

       disconnect (dcon) - Disconnect chain setup

               "disconnect"

       show_chain_setup (chains) - Show current Ecasound chain setup

               "show_chain_setup"

       loop_enable (loop) - Loop playback between two points

               "loop_enable" <start> <end> (start, end: mark names, mark indices, decimal
               seconds)

               "loop_enable 1.5 10.0  ; loop between 1.5 and 10.0 seconds loop_enable 1 5       ;
               loop between mark indices 1 and 5 loop_enable start end ; loop between mark ids
               'start' and 'end' "

       loop_disable (noloop nl) - Disable automatic looping

               "loop_disable"

   Effect commands
       add_controller (acl) - Add a controller to an operator (current operator, by default) use
       mfx to modify, rfx to remove)

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

       add_effect (afx) - Add effect to the end of current track

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

               "add_effect amp 6     ; LADSPA Simple amp 6dB gain add_effect var_dali  ; preset
               var_dali. Note that you don't need ; Ecasound's el: or pn: prefix "

       insert_effect (ifx) - Place effect before specified effect (engine stopped, prior to arm
       only)

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

       modify_effect (mfx modify_controller mcl) - Modify an effect parameter

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

               "modify_effect V 1 -1           ; set effect_id V, parameter 1 to -1 modify_effect
               V 1 - 10         ; reduce effect_id V, parameter 1 by 10 modify_effect V 1,2,3 +
               0.5    ; modify multiple parameters modify_effect V,AC,AD 1,2 3.14 ; set multiple
               effects/parameters "

       remove_effect (rfx remove_controller rcl) - Remove effects from selected 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_effect_id>]

       show_effect (sfx) - Show effect information

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

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

               "add_insert" ( pre | post ) <s_send_id> [<s_return_id>]

       set_insert_wetness (wet) - Set wet/dry balance for current track insert: 100 = all wet, 0
       = all dry

               "set_insert_wetness" [ pre | post ] <n_wetness>

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

               "remove_insert" [ pre | post ]

       ctrl_register (crg) - List Ecasound controllers

               "ctrl_register"

       preset_register (prg) - List Ecasound presets

               "preset_register"

       ladspa_register (lrg) - List LADSPA plugins

               "ladspa_register"

   Mark commands
       list_marks (lmk lm) - List all marks

               "list_marks"

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

               "to_mark" <s_mark_id> | <i_mark_index>

               "to_mark start (go to mark named 'start')"

       new_mark (mark k) - Drop mark at current playback position

               "new_mark" [ <s_mark_id> ]

       remove_mark (rmk rom) - Remove mark, default to current mark

               "remove_mark" [ <s_mark_id> | <i_mark_index> ]

               "remove_mark start (remove mark named 'start')"

       next_mark (nmk nm) - Move playback head to next mark

               "next_mark"

       previous_mark (pmk pm) - Move playback head to previous mark

               "previous_mark"

       name_mark (nmk nom) - Give a name to the current mark

               "name_mark" <s_mark_id>

               "name_mark start"

       modify_mark (move_mark mmk mm) - Change the time setting of current mark

               "modify_mark" [ + | - ] <f_seconds>

   Diagnostics commands
       engine_status (egs) - Display Ecasound audio processing engine status

               "engine_status"

       dump_track (dumpt dump) - Dump current track data

               "dump_track"

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

               "dump_group"

       dump_all (dumpall dumpa) - Dump most internal state

               "dump_all"

       show_io (showio) - Show chain inputs and outputs

               "show_io"

   Help commands
       list_history (lh) - List command history

               "list_history"

   Bus commands
       add_send_bus_cooked (asbc) - Add a send bus that copies all user tracks' processed signals

               "add_send_bus_cooked" <s_name> <destination>

               "asbc Reverb jconv"

       add_send_bus_raw (asbr) - Add a send bus that copies all user tracks' raw signals

               "add_send_bus_raw" <s_name> <destination>

               "asbr Reverb jconv"

       add_sub_bus (asub) - Add a sub bus (default destination: to mixer via eponymous track)

               "add_sub_bus" <s_name> [destination: s_track_name|s_jack_client|n_soundcard
               channel]

               "asub Strings_bus asub Strings_bus some_jack_client "

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

               "update_send_bus" <s_name>

               "usb Some_bus"

       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

               "set_bus" <s_busname> <key> <val>

   Effect commands
       new_effect_chain (nec) - Define a reusable sequence of effects (effect chain) with current
       parameters

               "new_effect_chain" <s_name> [<op1>, <op2>,...]

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

               "add_effect_chain" <s_name>

       overwrite_effect_chain (oec) - Add an effect chain overwriting current effects (which are
       pushed onto stack)

               "overwrite_effect_chain" <s_name>

       delete_effect_chain (dec) - Delete an effect chain definition from the list

               "delete_effect_chain" <s_name>

       list_effect_chains (lec) - List effect chains, matching any strings provided

               "list_effect_chains" [<s_frag1> <s_frag2>... ]

       bypass_effects (bypass bye) - Bypass track effects (pushing them onto stack) except
       vol/pan

               "bypass_effects"

       restore_effects (restore ref) - Restore bypassed track effects

               "restore_effects"

       new_effect_profile (nep) - Create a named group of effect chains for multiple tracks

               "new_effect_profile" <s_bunch_name> [<s_effect_profile_name>]

       apply_effect_profile (aep) - Use an effect profile to overwrite effects of multiple tracks

               "apply_effect_profile" <s_effect_profile_name>

       overlay_effect_profile (oep) - Use an effect profile to add effects to multiple tracks

               "overlay_effect_profile" <s_effect_profile_name>

       delete_effect_profile (dep) - Remove an effect chain bunch definition

               "delete_effect_profile" <s_effect_profile_name>

       list_effect_profiles (lep) - List effect chain bunches

               "list_effect_profiles"

   Track commands
       cache_track (cache ct) - Store an effects-processed track signal as a new version

               "cache_track" [<f_additional_processing_time>]

   Effect commands
       uncache_track (uncache unc) - Select the uncached track version; restores effects (but not
       inserts)

               "uncache_track"

   General commands
       do_script (do) - Execute Nama commands from a file in project_dir or project_root

               "do_script" <s_filename>

       scan - Re-read project's .wav directory

               "scan"

   Effect commands
       add_fade (afd fade) - Add a fade-in or fade-out to current track

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

               "fade in mark1        ; fade in default 0.5s starting at mark1 fade out mark2 2
               ; fade out over 2s starting at mark2 fade out 2 mark2     ; fade out over 2s
               ending at mark2 fade out mark1 mark2 ; fade out from mark1 to mark2 "

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

               "remove_fade" <i_fade_index1> [<i_fade_index2>...]

       list_fade (lfd) - List fades

               "list_fade"

   Track commands
       add_comment (comment ac) - Add comment to current track (replacing any previous comment)

               "add_comment"

       remove_comment (rc) - Remove comment from current track

               "remove_comment"

       show_comment (sc) - Show comment for current track

               "show_comment"

       show_comments (scs) - Show all track comments

               "show_comments"

       add_version_comment (comment avc) - Add version comment (replacing any previous user
       comment)

               "add_version_comment"

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

               "remove_version_comment"

       show_version_comment (svc) - Show version comment(s)

               "show_version_comment"

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

               "show_version_comments_all"

       set_system_version_comment (comment ssvc) - Set system version comment (for testing only)

               "set_system_version_comment"

   Midi commands
       midish_command (m) - Send command text to 'midish' MIDI sequencer shell

               "midish_command" <s_command_text>

   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

               "set_edit_points"

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

               "list_edits"

       select_edit (sed) - Select an edit to modify or delete, becomes current edit

               "select_edit" <i_edit_index>

       end_edit_mode (eem) - Current track plays full length (input from edit sub-bus)

               "end_edit_mode"

       destroy_edit - Remove an edit and all associated WAV files (destructive)

               "destroy_edit" [<i_edit_index>] (defaults to current edit)

       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 a WAV file for the current edit

               "record_edit"

       edit_track (et) - Set the edit track as 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

               "play_start_mark"

       rec_start_mark (rsm) - Select (and move to) rec start mark

               "rec_start_mark"

       rec_end_mark (rem) - Select (and move to) rec end mark

               "rec_end_mark"

       set_play_start_mark (spsm) - Set play_start_mark to current engine position

               "set_play_start_mark"

       set_rec_start_mark (srsm) - Set rec_start_mark to current engine position

               "set_rec_start_mark"

       set_rec_end_mark (srem) - Set rec_end_mark to current engine position

               "set_rec_end_mark"

       disable_edits (ded) - Disable editing sub-bus, restore standard track behavior

               "disable_edits"

       merge_edits (med) - Mix edits and original into a new host-track WAV version

               "merge_edits"

   Track commands
       explode_track - Make track into a sub-bus, with one track for each version

               "explode_track"

       move_to_bus (mtb) - Move current track to another bus

               "move_to_bus" <s_bus_name>

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

               "promote_version_to_track" <i_version_number>

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

               "read_user_customizations"

   Setup commands
       limit_run_time (lrt) - Stop recording after last WAV file finishes playing

               "limit_run_time" [<f_additional_seconds>]

       limit_run_time_off (lro) - Disable recording stop timer

               "limit_run_time_off"

       offset_run (ofr) - Record/play from mark position

               "offset_run" <s_mark_name>

       offset_run_off (ofo) - Clear offset run mode

               "offset_run_off"

   General commands
       view_waveform (wview) - Launch mhwavedit to view/edit waveform of current track/version
       WAV file

               "view_waveform"

       edit_waveform (wedit) - Launch audacity to view/edit waveform of current track/version WAV
       file

               "edit_waveform"

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

COPYRIGHT & LICENSE

       Copyright (c) 2009-2010 by Joel Roth.

       This is free software; you can redistribute it and/or modify it under the terms of the
       Artistic License, version 2.0.