Audio Gain

Audio Gain sits anywhere in an audio chain: source → filters → Audio Output. In Grafit the cables are the engine wiring — connecting the Audio input splices this node into the shared AVAudioEngine graph, and every player, filter, and output renders on that one engine clock, so inserting or removing the node mid-playback never causes drift or crackle.

Under the hood the node hosts an AVAudioUnitEQ with zero bands, using only its global gain stage. The Gain port is a linear multiplier that is converted to decibels internally: 1.0 is unity (0 dB), 2.0 is roughly +6 dB, 0.5 is roughly −6 dB, and a value at or near 0 hard-mutes the signal at −96 dB. Pan is applied on the effect's output mixer, moving the signal between the left (−1) and right (+1) channels.

The filtered signal is emitted from the Audio output as a new engine-backed snapshot, so filters chain indefinitely and an Audio FFT or Audio Analysis node can tap the signal after this node — every filter carries its own analysis tap. The Level output is a peak-decay RMS meter of the post-gain signal: it rises instantly and falls musically, ready to drive brightness or scale directly.

Setting Enable to false engages the audio unit's clean bypass: audio still flows through the chain, just unprocessed. If the Audio cable is removed, the upstream source simply reverts to its previous routing — nothing clicks, nothing stalls.

Outputs: Audio (the processed signal, chainable to more filters or an Audio Output) and Level (peak-decay RMS of the processed signal — instant rise, smooth fall).

Because Gain is linear rather than dB, it behaves intuitively when driven by 0…1 control signals: an LFO or fader sweeping 0→1 fades from silence to unity with no extra math.

• Master fader for a track: Audio Player → Audio Gain → Audio Output, with Gain cabled to a UI slider for live volume control during a performance.
• Sidechain-style ducking of a music bed: Audio Player (music) → Audio Gain → Audio Output, with the music's Gain driven by an inverted Level from a second (voice) chain — the bed dips whenever the voice speaks.
• Auto-pan: Audio Player → Audio Gain → Audio Output, with Pan cabled to an LFO (sine, −1…+1) for a slow stereo sweep.
• Balancing parallel branches: one Audio Player fanned out to two chains — Audio Filter (low-pass) → Audio Gain and Audio Filter (high-pass) → Audio Gain — each Gain trims its branch before both feed the Audio Output; fan-out is first-class in the engine.
• Loudness-reactive visuals without an FFT: Audio Player → Audio Gain → Audio Output, with the Gain node's Level output wired straight to a Canvas Scale or a generator's brightness.
• Pre-effect drive trim: Audio Player → Audio Gain → Audio Distortion → Audio Output — push Gain above 1.0 to hit the distortion harder, in addition to its own Pre Gain.

• Gain is clamped at 4 (≈ +12 dB); for more extreme boosts, chain two Audio Gain nodes — but watch the Level output for clipping-range values first.
• A Gain of exactly 0 is a true mute (−96 dB), which makes Audio Gain a convenient cable-driven mute switch: wire a Bool→Float conversion or a 0/1 toggle into Gain.
• Put an Audio FFT after the Gain node (its Audio output) to analyze the signal at performance level; tap before it to analyze independent of the fader position.
• Use Enable = false rather than Gain = 0 when you want a bypass instead of silence — bypass keeps the dry signal flowing to everything downstream.
• Live input (microphone or a loopback driver) arrives through the engine's realtime source bridge, so Audio Gain works on the mic exactly as it does on files.