Audio::Nama::ChainSetup - routines for generating Ecasound chain setup
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.
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
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
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
Unterminated parts of the network are discarded. Then redundant loop devices are
removed from the graph to minimize latency.
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
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
sax_out -> soundcard_out
In this case, the track, chain_id and other data can be specified as vertex or
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
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'.