VizLab User Guide
An audio-reactive visualization design workbench for mapping DSP snapshot data to real-time visual arrangements.
Overview
VizLab connects the audio processing world of Touchstone recipes to visual output. Load a recipe, feed it a test signal, and map DSP snapshot values (filter cutoff, gain reduction, chaos attractor position, etc.) to visual parameters on a SwiftUI Canvas arrangement.
The core loop:
- A Touchstone recipe processes audio in real time
- Snapshot polling reads DSP state from each node at 30 Hz
- Parameter mappings translate snapshot values into visual parameters
- An Arrangement renders the visual output at 60 fps on a Canvas
Getting Started
First Launch
- Select a recipe from the sidebar — bundled Touchstone recipes are available
- Choose a signal source from the controls panel (sine, noise, sweep, etc.)
- Press Play to start audio processing
- Pick an arrangement type from the arrangement picker
Navigation
| Area | Purpose |
|---|---|
| Sidebar | Recipe browser + arrangement picker |
| Canvas | 60 fps visual output |
| Inspector | Parameter mappings + manual overrides |
| Controls | Signal type, frequency, input level |
Signal Sources
VizLab includes 13 built-in test signals (the same set as Workbench, minus live input and sample playback):
| Category | Types |
|---|---|
| Basic | Sine, sawtooth, square, noise, silence |
| Tonal | Gated burst, PWM, FM |
| Transient | Impulse, pluck, arpeggio |
| Modulated | Sweep, sample & hold |
The frequency slider (20 Hz – 2 kHz) controls pitch for tonal signals. Different signal types exercise different aspects of the recipe — use sweep to see how filter-based recipes respond across the spectrum, or noise for broadband excitation.
Arrangements
Arrangements are the visual output layer. Each arrangement type defines its own set of visual parameters and rendering logic.
| Arrangement | Description |
|---|---|
| Plasma Nebula | Particle system with spiral attractor, ported from Hecate's PlasmaFieldView |
| Dot Swarm | Particle field with configurable attraction/repulsion |
| EQ Bars | Spectrum analyzer visualization |
| Waveform Scope | Oscilloscope-style waveform display |
| Ring Visualizer | Circular audio visualization |
| Lissajous | Parametric curve display |
| Grid Warp | Deformable grid responsive to audio |
Each arrangement declares parameterDefinitions — named parameters with ranges and defaults that control the visual output.
Parameter Mappings
The core of VizLab: connecting DSP snapshot data to visual parameters.
Creating a Mapping
- Open the Mapping Editor in the inspector
- Source: Pick a snapshot field (e.g.,
svf_node.Cutoff,chaos.x,compressor.GainReduction) - Target: Pick a visual parameter from the active arrangement
- Curve: Choose how the value is transformed — linear, exponential, logarithmic, or S-curve (same curves as Touchstone modulation)
- Range: Set the output min/max to scale the snapshot value to the visual parameter's range
Snapshot Fields
Snapshot fields are extracted from each node's FDSPSnapshot at 30 Hz. The available fields depend on the DSP component:
- Filters: Cutoff, Resonance, output levels
- Dynamics: Gain reduction, threshold, envelope levels
- Modulators: x, y, z (for Chaos Attractor, Knot Modulator), phase, rate
- Distortion: Drive, transfer curve points
- All nodes: Input/output levels, bypass state
Manual Overrides
Use the override sliders in the controls panel to manually set any visual parameter. Manual overrides take precedence over snapshot-driven mappings — useful for testing visual behavior at specific parameter values.
Visual Recipes
A Visual Recipe bundles an arrangement type, parameter mappings, and color configuration into a JSON file. Visual recipes can be exported and imported via the File menu.
Structure:
- Arrangement type — which visual arrangement to use
- Mappings — snapshot field → visual parameter connections with curves/ranges
- Color config — palette and color parameters for the arrangement
Tips
Choosing Signal Sources for Visualization
- Sweep — Best for seeing how frequency-dependent effects (filters, phasers) translate to visuals over time
- Noise — Broadband excitation shows the full dynamic range of the recipe
- Gated burst — Tests how visuals respond to signal onset/offset (attack/release behavior)
- Silence — See self-oscillating filters, feedback loops, and reverb tails in visual form
Mapping Strategy
Start with high-level mappings (RMS → overall intensity, spectral centroid → color) then layer in specific snapshot fields for detail. Multi-output modulators (Chaos Attractor x/y/z) are excellent for driving spatial parameters — map x to position, y to size, z to color shift for correlated but non-identical visual movement.