kunitoki/sonic-skills / skills/audio-performance-debug
audio-performance-debug
UnverifiedProfiling 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |