First, take a look at [[install]] for how to get your system set up.

Basic parameters for your sound devices and recording
formats are defined the top of the Ecmd program file, which
you should edit to your liking with your favorite text
editor. A benefit of working this way is that once Ecmd is 
configured, you will never break
your setup by mistakenly pressing a button.

Buttons provide complete control over Ecasound transport
setup including:

+ generate chain setup

+ connect setup

+ disconnect

+ kill and restart Ecasound engine

In many instances, chain setups are generated and
connected automatically. To be sure, just click 
**Generate and connect**

#### Basic Recording Scenario ####

Once your static configuration is out of the way,
what is left for you to do to record a live session?

+ Name your new session and click **New**

+ Add tracks by NAME and REC channel (you can monitor
  without specifying a MON channel)

+ Add effects, if any

+ Select output templates - at minimum **Rec\_file**. (You can
  leave **Rec\_file** ON in all basic recording and monitoring
  scenarios.) If you're using JACK, press in JACK ON/OFF
  button to turn it light blue before generating your
  chain setup.

+ Set the **Tracker** (group control) menubutton to REC

+ Confirm the red highlighting for record tracks (version
  numbers are generated automatically)

+ Press **Start**

After recording a song, Ecmd kicks into monitor mode for
that song version. Press **Start** to review it.

When you're done reviewing, press **Stop**. To record
the next song, set **Tracker**
REC and then **Start**. You don't need to worry about
setting the version number.


#### An Introduction to Ecmd Templates ####

When you start Ecmd, just below the orange time indicator is
a group of OUTPUT buttons. These are a powerful,
configurable feature, giving you a lot of gee-whiz
flexibility for free.

Each button corresponds to an output template. Each template
can route one of three audio signals for each track:

+ The _raw_ signal from a sound device or file

+ The _cooked_ signal, stereo with volume, pan and effects,
  which is what results from operating the track and effect sliders

+ The _mixed_ signal, which is all of the _cooked_ signals
  combined into one stereo signal, with additional effects
  for the mix track (always the first track shown, with the
  same name as the session.)

Each template can be configured to select either REC signals
(live from the sound card) or MON signals (from file
playback) or both. Templates can also add various pre and
post processing functions to the chains they control.

Having understood a bit about templates the following Ecmd
usage scenarios will be easier to understand. Realize,
however, that these choices are not exclusive. All the
following scenarios can take place simultaneously, that is,
you can do a rough mixdown while recording, while using Ecmd
to provide effects processing for your electric guitar.

(**Note:** If more than one template asks for a
copy of a _cooked_ signal, that signal will go through a loop
device, which may be too much latency for live effects.)


#### Mixing Scenario ####

Go to the Tracker menubutton and select a version. Press the
Stereo output templates. Add a few effects and press
**Start** (You can add effects while the transport is
running, too.)

Stop the playback, activate Mix template, bump the Tracker
MON setting (to write and connect the chain setup) and
press **Start**

#### Live Effects ####

Pressing the button for the **Live** template means that
effects you place on REC tracks will be routed to the
same numbered output channel, or whatever MON channel you
set in the track listing. (At present this is a stereo
signal, routed to two adjacent channels.)


#### Backing Tracks ####

Copy or link an audio file to the .WAV directory for a
new recording session. Ecmd will find it automatically and 
make a corresponding track entry. In the track listing,
set the version number to **1** and the track status to 'MON'.
Once a track version number is set manually, the global
version setting will ignore it. So you can fix one or more
tracks to specific versions while setting other tracks
in tandem to another version number using the Tracker
menubutton.

#### Playback Effects ####

Press the **Multi** template button to send cooked playback
tracks to the multichannel sound card.  

The **Stereo** template button uses the same routing pattern
as the **Mix** template. All _cooked_ non-muted tracks are 
mixed down to two channels for output to the Stereo device.


#### Why doesn't my REC track turn pink? ####

The track background turns pink and the Status field shows
REC to indicate a track ready to record.

Three conditions must be met for a track to get REC status:

+ The group status setting in the Tracker menubutton must be
  set to REC

+ The track **Status** menubutton must be set to REC

+ You must specify a CHANNEL NUMBER in the **Rec** menubutton
  for the track 

In addition, if you want these signals to be written to
disk, the **Rec\_file** button MUST be lit. This is the
default. The only time you would want to turn **Rec\_file**
off is when using Ecmd for fiddling with guitar
effects that you don't want to record.

If you want to be sure you're going to record, have a look
at the terminal window: you will see the results of the
Ecasound 'fs' command, indicating files open for writing.

#### Persistent Settings ####

Track status, effects parameters, output template selection,
ALSA mixer state and many other settings are stored when you
exit Ecmd by pressing **Quit** on the right in the top row of
buttons. Pressing **Load** will load a previous session with
the specified name, bringing back those settings.

**Load No-State** is there for the temporary convenience of
developers or others who need to ignore previous state data
after upgrading. (Future Ecmd versions will not try to restore
settings they lack data for.)

To save keystrokes you can load a session from the command
line.

        $ ecmd my_gig 

will load an existing session called 'my_gig'.

        $ ecmd -m my_gig

will do the same ignoring persistent settings.

        $ ecmd -c my_gig

will create a new session called 'my_gig'.

Probably you will want to run ecmd with root privileges:

        $ sudo ecmd


#### Marks ####

If you want to mark places in your songs, just click
on a blue marker button. It will display the time position
and then jump you to that position on being pressed.

To reuse a marker button, press **Set** to turn the markers
blue, which means, "ready to use."

Sorry, automatic per version marker settings are a TODO
item. For now, just use the following Perl Commands:

       &save_state("/ecmd_home/my_gig/song7") 
and
       &retrieve_state("/ecmd_home/my_gig/song7")
 

#### Fast Forward and Friends ####

These buttons are almost self explanatory. Initially the
buttons jump the transport in units of seconds. Pressing the
**Sec** button in the center of the row will cause the jump
unit to change to **Min** allowing you to jump forward or back
by up to an hour at a time. 

#### Effects ####

Click on the menubuttons at the right of the track list to
set an effect for that track. Here are your choices:

        EF  Ecasound effects, you get sliders, thanks to hints
            from Luis Pablo Gasparotto's Tkeca
        
        P1, P2  Ecasound presets, no sliders

        L1, L2, L3, L4, L5  LADSPA effects, sliders     and
                alphabetical order coming soon

The menu shows the names of the effects and the number of
parameters for each.

When you select an effect, it pops up under the track name
in the Effects window. _Unless you are using an effect with
sliders, you will have to set your parameters **before**
connecting your chain setup._ 

To remove an effect, click on the effect name where it
appears and select **Remove**. (Hmmmm. Bypass might be nice,
too.)

If you want to apply a Midi or other controller to a
parameter, just click on the parameter name. 
