audio-artifacts-debug

name

audio-artifacts-debug

description

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 type	Questions to ask
Clicks / pops	Regular or random? On buffer boundaries? At note on/off? After channel strip toggle?
Crackling / distortion	Constant or load-dependent? Does it correlate with signal level? Worse on silent decay?
Silence / dropout	Immediate or gradual? Only under load? After a specific number of voices? Recovers?
DC offset	Constant or drift? Present from first sample? Appears only after long silence?
Aliasing	Audible as high-frequency mirror tones? Pitch-dependent? Present at all sample rates?
Phase issues	Stereo image collapse in mono? Comb filtering? Only on parallel paths or mid-side?
Latency	DAW reports wrong delay compensation? Wet/dry misaligned? Only at certain buffer sizes?

Step 2 — Narrow to root cause

Symptom	Likely cause	Skill / check to apply
Click at fixed buffer-length intervals	Buffer boundary discontinuity — uninitialized tail, missing sample-accurate fade	audio-dsp-review: check process entry/exit
Click correlates with xrun log	CPU overload — audio thread missed deadline	audio-dsp-review: scan for allocations, locks, I/O
Crackling scales with signal amplitude	Clipping or fixed-point overflow	audio-numerics-review: overflow, Q-format multiply
Crackling on silent decay	Denormal floats — FTZ absent	audio-numerics-review: denormal section
Dropout / silence under load	xrun, NaN propagation, or buffer too small for latency	audio-dsp-review + audio-numerics-review: NaN guards
Silence after large value	NaN propagated from unclamped sqrt / division	audio-numerics-review: NaN / Inf section
DC offset from first sample	Uninitialized filter state or delay line	audio-numerics-review: precision loss / state init
DC offset after long silence	FTZ leaving near-zero state; missing high-pass	audio-numerics-review: denormal / FTZ section
Aliasing pitch-tracks with note	Oscillator not bandlimited; no anti-alias before downsampling	audio-numerics-review: check sample-rate handling
Stereo collapses to mono	Unmatched processing on L/R; phase inversion	audio-dsp-review: check parallel path symmetry
Comb filtering on mono	Latency mismatch on parallel paths	Plugin reports incorrect getLatencySamples()
Latency wrong at buffer-size change	Plugin caches latency at init only; not updated on reconfigure	audio-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.