Overview

For the Ecasound engine to run, it must be configured into a signal processing network. This configuration is called a ``chain setup''. It is a graph comprised of multiple signal processing chains, each of which consists of exactly one input and one output.

When user input requires a change of configuration, Nama generates an new chain setup file. These files are guaranteed to be consistent with the rules of Ecasound's routing language.

After initializing the data structures, Nama iterates over project tracks and buses to create a first-stage graph. This graph is successively transformed as more routing details are added, then each edge of the graph is processed into a pair of IO objects---one for input and one for output---that together constitute an Ecasound chain. With a bit more processing, the configuration is written out as text in the chain setup file.

The Graph and its Transformations

Generating a chain setup starts with each bus iterating over its member tracks, and connecting them to its mix track. (See man Audio::Nama::Bus.)

In the case of one track belonging to the Main (default) bus, the initial graph would be:

        soundcard_in -> sax -> Master -> soundcard_out

``soundcard_in'' and ``soundcard_out'' will eventually be mapped to the appropriate JACK or ALSA source, depending on whether jackd is running. The Master track hosts the master fader, connects to the main output, and serves as the mix track for the Main bus.

If we've asked to record the input, we automatically get this route:

        soundcard_in -> sax-rec-file -> wav_out

The track 'sax-rec-file' is a temporary clone (slave) of track 'sax' and connects to all the same inputs.

A 'send' (for example, a instrument monitor for the sax player) generates this additional route:

        sax -> soundcard_out

Ecasound requires that we insert a loop device where signals fan out or fan in.

        soundcard_in -> sax -> sax_out -> Master -> soundcard_out
                               sax_out -> soundcard_out

Here 'sax_out' is a loop device. (Note that we prohibit track names matching *_out or *_in.)

Inserts are incorporated by replacing the edge either before or after a track vertex with a network of auxiliary tracks and loop devices. (See man Audio::Nama::Insert.)

Unterminated parts of the network are discarded. Then redundant loop devices are removed from the graph to minimize latency.

Dispatch

After routing is complete, Nama iterates over the graph's edges, transforming them into pairs of IO objects that become the inputs and outputs of Ecasound chains.

To create an Ecasound chain from

        Master -> soundcard_out

Nama uses 'Master' track attributes to provide data. For example track index (1) serves as the chain_id, and the track's send settings determine the soundcard channel or other destination.

Some edges are without a track at either terminal. For example this auxiliary send:

        sax_out -> soundcard_out

In this case, the track, chain_id and other data can be specified as vertex or edge attributes.

Edge attributes override vertex attributes, which override track attributes. This allows routing to be edited and annotated to behaviors different from what the track wants. When a temporary track is used for recording, for example

    sax-rec-file  -> wav_out

The 'sax-rec-file' vertex is assigned the 'chain_id' attribute 'R3' rather than the track index assigned to 'sax-rec-file'.