Skip to content

kunitoki/sonic-skills / skills/audio-performance-debug

audio-performance-debug

Unverified

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.

SymptomMeasurement approach
Consistent high CPU averageCPU meter in DAW; perf stat / Instruments Time Profiler
Sporadic xruns / dropoutsHost xrun log; correlate with system events (GC, network, page fault)
CPU spikes on note-onProfile with many simultaneous note-on events; watch for allocation spikes
Latency reporting wrongLog getLatencySamples() before and after prepareToPlay at varying buffer sizes
Gets worse with more voicesProfile with 1 vs 8 vs 32 voices; O(N²) shows quadratic growth
Memory bandwidth pressureperf 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).
PlatformProfilerNotes
macOSInstruments — Time ProfilerFilter to audio I/O thread; use "hide system libraries" to focus on your code
macOSInstruments — AllocationsCatch allocations on the audio thread during a session
Linuxperf record -g + perf report--call-graph dwarf for C++ templates; perf stat for cache miss ratio
WindowsVTune Profiler — HotspotsUse "Platform Profiler" preset; filter to realtime thread
Cross-platformTracyFrame-level instrumentation; zero-cost when disabled; shows per-buffer timing
JUCEjuce::PerformanceCounterInline timer around suspect blocks; logs to console

Step 3 — Fix patterns

Anti-patternWhy it hurtsOptimization
O(N²) voice loopQuadratic growth — 32 voices = 1024 iterations per sampleRestructure to O(N): batch per-voice work, use SIMD across voices
Wrong FFT sizePower-of-two FFT on non-power-of-two frames → zero-padding wasteSize FFT to next power-of-two; or use prime-factor FFT (FFTW FFTW_MEASURE)
Unnecessary buffer copymemcpy of full buffer each callbackProcess in-place; pass pointer + length; avoid intermediate staging buffers
std::map / unordered_map lookup on audio threadO(log N) / amortized O(1) but with cache misses; unordered_map rehash = allocReplace with std::array + index, or a sorted std::array with lower_bound
unordered_map insertTriggers rehash → heap allocation on audio threadPre-populate at prepareToPlay; never insert during playback
Heap allocation on audio threadnew/delete acquires global allocator lockPre-allocate in prepareToPlay; use pool or ring buffer; see audio-dsp-review
First-touch page faultOS maps physical pages on first write → stallprepareToPlay: allocate AND write to every byte of every buffer
Scalar loop over samplesCompiler may not auto-vectorize complex loopsUse JUCE FloatVectorOperations, xsimd, or explicit SIMD intrinsics
Denormal-induced slowdownSubnormal FP values cause 100× slowdown on x86Set FTZ+DAZ in prepareToPlay; see audio-numerics-review
Lock contentionMutex held by UI thread blocks audio threadReplace with atomics or SPSC queue; see audio-dsp-review

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

finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 318kUpdated Claude CodeCodexUnverifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 318kUpdated Claude CodeCodexUnverifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 318kUpdated Claude CodeCodexUnverifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall