NAME

       Audio::Nama::ChainSetup - routines for generating Ecasound chain setup

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