feat: Per-Effect Signature Visualizations — Real-time Curves, Meters, Waveforms for Every Effect

[ChuxiJ]

Epic: Per-Effect Signature Visualizations

Motivation

The defining characteristic of every premium audio plugin is its signature visualization — the element that makes the effect's behavior immediately readable and visually memorable. FabFilter Pro-Q's interactive EQ curve, Pro-C's real-time GR envelope, Valhalla's decay display — these aren't decorations, they are the primary interface. Users read the visualization, not the knob values.

ACE-Step currently has good Parametric EQ visualization but zero visualization for Compressor (beyond a GR bar), Reverb, Delay, Distortion, Filter, Chorus, Flanger, and Phaser. This makes 8 out of 11 effects "blind" — users tweak knobs without seeing what's happening to their audio.

Design Philosophy: Reference-First

MANDATORY: Before designing ANY visualization, the implementer must:

1. Screenshot the equivalent visualization from 3+ professional plugins
2. Study: what data is displayed? What axes? What colors? What resolution? What animation speed?
3. Document the analysis in .llm/research/ui-references/viz-{effect-name}-references.md
4. Implement by closing gaps between our version and the best reference
5. After implementation, do a side-by-side comparison screenshot

Current State

Effect	Current Visualization	Quality
EQ3	150×40px simple curve (no grid, no labels)	Basic
Parametric EQ	220×108px canvas with spectrum + draggable bands + log grid	Good
Compressor	Single amber GR bar + dB number	Minimal
Reverb	None	Missing
Delay	None	Missing
Distortion	None	Missing
Filter	None	Missing
Chorus	None	Missing
Flanger	None	Missing
Phaser	None	Missing
Convolver	None	Missing

Implementation Plan

1. Compressor — Transfer Curve + GR Timeline

Reference plugins to study: FabFilter Pro-C 2, Waves CLA-76, iZotope Ozone Dynamics, SSL Channel

1.1 — Transfer curve (static, updates on param change)

• X axis: Input level (dB)
• Y axis: Output level (dB)
• 45° unity line (gray, dashed) — "no compression"
• Compression curve: shows how signal above threshold is reduced based on ratio
• Knee region: visible rounded transition at threshold
• Threshold marker: vertical line with dB label
• Makeup gain: shifts entire curve up
• Canvas size: at least 120×120px (compact) / 240×240px (expanded)

1.2 — Gain reduction timeline (real-time, animated)

• Scrolling time axis (last 2-5 seconds)
• Y axis: 0 to -30 dB (GR amount)
• Filled area showing real-time gain reduction over time
• Color: effect color (amber/gold) at 60% opacity
• Threshold line reference
• Attack/release envelope visible in the GR shape
• 60fps update from getCompressorReduction() data

1.3 — Sidechain spectrum (when sidechain active)

• Small FFT display of sidechain source
• Shows what's triggering the compressor
• HPF/LPF filter overlay showing sidechain filter range

2. Reverb — Decay Curve + ER Visualization

Reference plugins to study: FabFilter Pro-R, Valhalla VintageVerb, Logic ChromaVerb, Waves H-Reverb

2.1 — Impulse response / decay envelope

• X axis: Time (0 to decay time)
• Y axis: Amplitude (0 to -60dB)
• Pre-delay region (gap before first reflection)
• Early reflections shown as discrete spikes
• Decay tail as filled area with exponential falloff
• Color: effect color (purple/violet) with opacity gradient

2.2 — Frequency-dependent decay (advanced, expanded mode)

• Horizontal: frequency (log scale)
• Vertical: RT60 decay time
• Shows how damping makes highs decay faster
• Color gradient: warm (long decay) to cool (short decay)
• Reference: FabFilter Pro-R's frequency-dependent display

2.3 — For Convolver: IR waveform

• Show loaded impulse response waveform
• Highlight ER region vs tail
• Trim handles visible
• Pre-delay marker

3. Delay — Tap Timeline + Feedback Decay

Reference plugins to study: FabFilter Timeless, Waves H-Delay, Soundtoys EchoBoy, Logic Delay Designer

3.1 — Tap visualization

• Horizontal timeline (0 to ~2 seconds)
• Each delay tap shown as vertical bar
• Bar height = tap level (decaying by feedback amount)
• Bar color fading with each repeat (100% → 60% → 36% → ...)
• Delay time label on first tap
• Beat/tempo grid overlay (quarter notes, eighth notes)

3.2 — Feedback decay envelope

• Exponential decay curve overlaying the taps
• Shows how many repeats before signal drops below audibility
• If feedback > 90%: show warning (infinite repeats)

4. Distortion — Transfer Function Curve + Harmonic Spectrum

Reference plugins to study: FabFilter Saturn 2, Soundtoys Decapitator, iZotope Trash, Softube Saturation Knob

4.1 — Transfer function (waveshaping curve)

• X axis: Input amplitude (-1 to +1)
• Y axis: Output amplitude (-1 to +1)
• Linear reference line (45°, dashed gray) — "no distortion"
• Waveshaping curve overlaid (colored by distortion type)
  • Soft clip: gentle S-curve
  • Overdrive: asymmetric S-curve
  • Fuzz: flat top/bottom (hard clip)
• Drive amount visually changes curve shape in real-time
• This is THE defining visualization — makes the distortion character immediately visible

4.2 — Harmonic spectrum (expanded mode)

• Show FFT of output when driven with a test tone
• Harmonics visible as peaks above fundamental
• Even harmonics labeled (2nd, 4th) vs odd (3rd, 5th, 7th)
• Helps users understand the tonal character

5. Filter — Frequency Response + LFO Waveform

Reference plugins to study: FabFilter Volcano, Waves MetaFilter, Ableton Auto Filter, u-he Filterscape

5.1 — Filter response curve

• Same axes as EQ: frequency (log) × gain (dB)
• Show actual filter shape: LP/HP/BP with resonance peak
• Cutoff frequency marker (draggable dot)
• Resonance peak clearly visible
• Animate: when LFO is active, the cutoff marker sweeps back and forth
• Spectrum analyzer behind the curve (showing what audio goes through)

5.2 — LFO waveform display (when LFO enabled)

• Small waveform showing current LFO shape (sine)
• Phase indicator dot moving along waveform
• Rate label (Hz or sync division)
• Depth shown as waveform amplitude

6. Chorus/Flanger/Phaser — Modulation Visualization

Reference plugins to study: Soundtoys MicroShift, Waves MetaFlanger, FabFilter Timeless (modulation display)

6.1 — Chorus: delay time modulation

• Dual lines showing L/R delay time modulation over time
• X axis: time (scrolling, last ~2 seconds)
• Y axis: delay time (ms)
• LFO wave visible as smooth oscillation
• Depth shown as amplitude of oscillation

6.2 — Flanger: comb filter sweep

• Frequency response showing moving comb filter notches
• Notches sweep up and down with LFO
• Feedback direction shown (positive = peaks, negative = notches)
• Animate at actual LFO rate

6.3 — Phaser: allpass phase response

• Phase response curve showing moving phase shift notches
• Number of notches matches stage count
• Sweep animation at LFO rate
• Feedback resonance peaks visible

7. Limiter — GR Timeline + True Peak Display

Reference plugins to study: FabFilter Pro-L 2, Waves L2, iZotope Ozone Maximizer

7.1 — Gain reduction timeline

• Scrolling time axis (last 5-10 seconds)
• Y axis: 0 to -20 dB GR
• Filled area (inverted — GR grows downward)
• Ceiling line marked
• Peak indicators showing where limiting occurred most
• Color: red when GR > 6dB, amber when 3-6dB, green when < 3dB

7.2 — True peak meter

• Vertical bar showing dBTP (true peak)
• Ceiling threshold line
• ISP (inter-sample peak) indicator when detected
• Peak hold with numeric readout

Shared Visualization Infrastructure

Canvas Rendering Best Practices

• Use devicePixelRatio for retina-sharp rendering (2× on retina)
• Use requestAnimationFrame for all animated displays
• Throttle to 30fps when effect panel is in background/collapsed
• Pre-compute static elements (grid lines, labels) and cache as offscreen canvas
• Only redraw dynamic elements (real-time data) per frame

Data Flow

AudioWorklet/AnalyserNode → SharedArrayBuffer/postMessage → requestAnimationFrame → Canvas

• Metering data: from audio engine at audio rate, downsampled to display rate
• Parameter data: from Zustand store via React props
• Static curves (transfer function, filter response): recalculate only on parameter change

Responsive Sizing

• Compact mode (in card): Minimum viable visualization (120×60px)
• Expanded mode (full editor): Full-size with labels, grid, legends (400×200px+)
• Canvas resolution always matches display size × devicePixelRatio

Acceptance Criteria

• Compressor: transfer curve with threshold/ratio/knee + real-time GR timeline
• Reverb: decay envelope with ER + pre-delay visualization
• Convolver: IR waveform display with ER/tail regions
• Delay: tap timeline with feedback decay + tempo grid
• Distortion: transfer function curve (waveshaping) for each mode
• Filter: frequency response with animated LFO sweep + resonance peak
• Chorus: L/R delay time modulation waveform
• Flanger: animated comb filter sweep
• Phaser: animated allpass notch sweep
• Limiter: GR timeline + true peak meter (when limiter exists per feat: Mastering-Grade Limiter & Loudness Management — True Peak, LUFS Workflow, Dithering #1208)
• All visualizations render at 60fps on mid-range hardware
• All visualizations respect compact (in-card) and expanded (full-editor) modes
• Reference comparison screenshots stored in .llm/research/ui-references/ for each effect
• EQ3 curve upgraded from 150×40px to at least 200×80px with frequency grid

References (MUST collect screenshots before implementing each)

• FabFilter product gallery — best-in-class plugin visualizations
• iZotope product gallery — data-rich, informative displays
• Valhalla DSP — elegant, simple, effective reverb displays
• Soundtoys — character-driven, personality in every pixel
• u-he — detailed, skeuomorphic, rich information density
• Plugin Boutique screenshots — comparison shopping for visual references