Skip to content

kunitoki/sonic-skills / skills/audio-artifacts-debug

audio-artifacts-debug

Unverified

Systematic checklist for diagnosing audio artifacts. Use when the user describes a sound quality problem — clicks, pops, crackling, silence, DC offset, aliasing, phase issues, or latency problems. Trigger on phrases like "why do I hear clicks?", "my output has DC offset", "there's aliasing in my oscillator", "phase is wrong in mono", "dropout when CPU spikes". Pairs with audio-dsp-review (realtime safety) and audio-numerics-review (numeric correctness) — use those to fix once the cause is found.

Audio Artifacts Debug

Audio artifacts have diagnostic signatures — match the symptom to the root cause before touching code.

Step 1 — Characterize the artifact

Ask these questions before reading any code.

Artifact typeQuestions to ask
Clicks / popsRegular or random? On buffer boundaries? At note on/off? After channel strip toggle?
Crackling / distortionConstant or load-dependent? Does it correlate with signal level? Worse on silent decay?
Silence / dropoutImmediate or gradual? Only under load? After a specific number of voices? Recovers?
DC offsetConstant or drift? Present from first sample? Appears only after long silence?
AliasingAudible as high-frequency mirror tones? Pitch-dependent? Present at all sample rates?
Phase issuesStereo image collapse in mono? Comb filtering? Only on parallel paths or mid-side?
LatencyDAW reports wrong delay compensation? Wet/dry misaligned? Only at certain buffer sizes?

Step 2 — Narrow to root cause

SymptomLikely causeSkill / check to apply
Click at fixed buffer-length intervalsBuffer boundary discontinuity — uninitialized tail, missing sample-accurate fadeaudio-dsp-review: check process entry/exit
Click correlates with xrun logCPU overload — audio thread missed deadlineaudio-dsp-review: scan for allocations, locks, I/O
Crackling scales with signal amplitudeClipping or fixed-point overflowaudio-numerics-review: overflow, Q-format multiply
Crackling on silent decayDenormal floats — FTZ absentaudio-numerics-review: denormal section
Dropout / silence under loadxrun, NaN propagation, or buffer too small for latencyaudio-dsp-review + audio-numerics-review: NaN guards
Silence after large valueNaN propagated from unclamped sqrt / divisionaudio-numerics-review: NaN / Inf section
DC offset from first sampleUninitialized filter state or delay lineaudio-numerics-review: precision loss / state init
DC offset after long silenceFTZ leaving near-zero state; missing high-passaudio-numerics-review: denormal / FTZ section
Aliasing pitch-tracks with noteOscillator not bandlimited; no anti-alias before downsamplingaudio-numerics-review: check sample-rate handling
Stereo collapses to monoUnmatched processing on L/R; phase inversionaudio-dsp-review: check parallel path symmetry
Comb filtering on monoLatency mismatch on parallel pathsPlugin reports incorrect getLatencySamples()
Latency wrong at buffer-size changePlugin caches latency at init only; not updated on reconfigureaudio-dsp-review: check prepareToPlay reset

Step 3 — Structured diagnosis report

## Audio Artifact Diagnosis: `[file / symptom]`

### Artifact characterization
Type: [clicks | crackling | silence | DC | aliasing | phase | latency]
Observed: [when / under what conditions]
Reproducible: [always | intermittent | load-dependent]

### Root cause hypothesis
Likely cause: [one sentence]
Evidence: [what in the code supports this]
Skill to apply: [audio-dsp-review | audio-numerics-review | both]

### Specific checks to run
1. [file:line] — [what to inspect]
2. ...

### Recommended fix
[Concrete action — no placeholder text]

For artifact-specific diagnostic questions and check-by-check references see references/artifact-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