/audio-performance-debug

name: audio-performance-debug
description: >
  Profiling strategy for audio CPU issues — xruns, spikes, and buffer underruns. Use when
  the user reports CPU overload, audio glitches under load, or performance regressions.
  Trigger on phrases like "I'm getting xruns", "my plugin causes CPU spikes", "dropouts
  under high voice count", "audio thread is too slow", "how do I profile my DSP".
  References audio-numerics-review for denormal slowdown and audio-dsp-review for
  lock contention.

Audio Performance Debug

Audio performance requires good worst-case complexity, not average-case — the audio thread fires on a hard deadline every buffer, regardless of what else is happening.

Step 1 — Identify the symptom

Measure before guessing. Different symptoms point to different root causes.

| Symptom | Measurement approach | |---------|---------------------| | Consistent high CPU average | CPU meter in DAW; `perf stat` / Instruments Time Profiler | | Sporadic xruns / dropouts | Host xrun log; correlate with system events (GC, network, page fault) | | CPU spikes on note-on | Profile with many simultaneous note-on events; watch for allocation spikes | | Latency reporting wrong | Log `getLatencySamples()` before and after `prepareToPlay` at varying buffer sizes | | Gets worse with more voices | Profile with 1 vs 8 vs 32 voices; O(N²) shows quadratic growth | | Memory bandwidth pressure | `perf mem` / VTune memory bandwidth counter; cache miss rate |

Step 2 — Locate the hotspot

• [ ] Build a release (optimized) binary before profiling — debug builds are not representative.
• [ ] Use a reproducible test case: fixed buffer size, fixed voice count, looped audio.
• [ ] Attach a profiler to the audio thread specifically, not the whole process.
• [ ] Identify the top-3 hottest functions by exclusive CPU time, not inclusive.
• [ ] Check whether the spike is periodic (every N buffers → container rehash or GC) or random (OS jitter, page fault).

| Platform | Profiler | Notes | |----------|----------|-------| | macOS | Instruments — Time Profiler | Filter to audio I/O thread; use "hide system libraries" to focus on your code | | macOS | Instruments — Allocations | Catch allocations on the audio thread during a session | | Linux | `perf record -g` + `perf report` | `--call-graph dwarf` for C++ templates; `perf stat` for cache miss ratio | | Windows | VTune Profiler — Hotspots | Use "Platform Profiler" preset; filter to realtime thread | | Cross-platform | Tracy | Frame-level instrumentation; zero-cost when disabled; shows per-buffer timing | | JUCE | `juce::PerformanceCounter` | Inline timer around suspect blocks; logs to console |

Step 3 — Fix patterns

| Anti-pattern | Why it hurts | Optimization | |--------------|-------------|--------------| | O(N²) voice loop | Quadratic growth — 32 voices = 1024 iterations per sample | Restructure to O(N): batch per-voice work, use SIMD across voices | | Wrong FFT size | Power-of-two FFT on non-power-of-two frames → zero-padding waste | Size FFT to next power-of-two; or use prime-factor FFT (FFTW `FFTW_MEASURE`) | | Unnecessary buffer copy | `memcpy` of full buffer each callback | Process in-place; pass pointer + length; avoid intermediate staging buffers | | `std::map` / `unordered_map` lookup on audio thread | O(log N) / amortized O(1) but with cache misses; `unordered_map` rehash = alloc | Replace with `std::array` + index, or a sorted `std::array` with `lower_bound` | | `unordered_map` insert | Triggers rehash → heap allocation on audio thread | Pre-populate at `prepareToPlay`; never insert during playback | | Heap allocation on audio thread | `new`/`delete` acquires global allocator lock | Pre-allocate in `prepareToPlay`; use pool or ring buffer; see `audio-dsp-review` | | First-touch page fault | OS maps physical pages on first write → stall | `prepareToPlay`: allocate AND write to every byte of every buffer | | Scalar loop over samples | Compiler may not auto-vectorize complex loops | Use JUCE `FloatVectorOperations`, `xsimd`, or explicit SIMD intrinsics | | Denormal-induced slowdown | Subnormal FP values cause 100× slowdown on x86 | Set FTZ+DAZ in `prepareToPlay`; see `audio-numerics-review` | | Lock contention | Mutex held by UI thread blocks audio thread | Replace with atomics or SPSC queue; see `audio-dsp-review` |

For anti-pattern code examples and platform profiler workflows see `references/performance-patterns.md`.