.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Audio::Nama::ChainSetup 3pm"
.TH Audio::Nama::ChainSetup 3pm "2017-03-27" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Audio::Nama::ChainSetup \- routines for generating Ecasound chain setup
.SS "Overview"
.IX Subsection "Overview"
For the Ecasound engine to run, it must be configured into a
signal processing network. This configuration is called a
\&\*(L"chain setup\*(R".  It is a graph comprised of multiple signal
processing chains, each of which consists of exactly one
input and one output.
.PP
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.
.PP
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 \s-1IO\s0 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.
.SS "The Graph and its Transformations"
.IX Subsection "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.)
.PP
In the case of one track belonging to the Main (default) 
bus, the initial graph would be:
.PP
.Vb 1
\&        soundcard_in \-> sax \-> Master \-> soundcard_out
.Ve
.PP
\&\*(L"soundcard_in\*(R" and \*(L"soundcard_out\*(R" will eventually be mapped
to the appropriate \s-1JACK\s0 or \s-1ALSA\s0 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.
.PP
If we've asked to record the input, we automatically get
this route:
.PP
.Vb 1
\&        soundcard_in \-> sax\-rec\-file \-> wav_out
.Ve
.PP
The track 'sax\-rec\-file' is a temporary clone (slave) of track 'sax'
and connects to all the same inputs.
.PP
A 'send' (for example, a instrument monitor for
the sax player) generates this additional route:
.PP
.Vb 1
\&        sax \-> soundcard_out
.Ve
.PP
Ecasound requires that we insert a loop device where signals fan 
out or fan in.
.PP
.Vb 1
\&        soundcard_in \-> sax \-> sax_out \-> Master \-> soundcard_out
\&
\&                               sax_out \-> soundcard_out
.Ve
.PP
Here 'sax_out' is a loop device. (Note that we prohibit
track names matching *_out or *_in.)
.PP
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.)
.PP
Unterminated parts of the network are discarded. Then
redundant loop devices are removed from the graph to
minimize latency.
.SS "Dispatch"
.IX Subsection "Dispatch"
After routing is complete, Nama iterates over the graph's
edges, transforming them into pairs of \s-1IO\s0 objects that
become the inputs and outputs of Ecasound chains.
.PP
To create an Ecasound chain from
.PP
.Vb 1
\&        Master \-> soundcard_out
.Ve
.PP
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.
.PP
Some edges are without a track at either terminal. For
example this auxiliary send:
.PP
.Vb 1
\&        sax_out \-> soundcard_out
.Ve
.PP
In this case, the track, chain_id and other data can be
specified as vertex or edge attributes.
.PP
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
.PP
.Vb 1
\&    sax\-rec\-file  \-> wav_out
.Ve
.PP
The 'sax\-rec\-file' vertex is assigned the 'chain_id' attribute 
\&'R3' rather than the track index assigned to 'sax\-rec\-file'.