| name | webaudio-review |
| description | Reviews Web Audio API JavaScript/TypeScript code for correctness, thread safety, and deprecated patterns. Use when the user asks to review AudioWorklet code, check an AudioWorkletProcessor, audit Web Audio graph construction, or diagnose crackling/dropouts in a web audio app. Trigger on phrases like "review my Web Audio code", "check my AudioWorklet", "is my AudioWorkletProcessor safe", or "why does my web audio crackle".
|
Web Audio API Safety Review
Note — JS realtime model differs from native:
JavaScript allocation does not look like malloc, but it still creates garbage-collector
work and can introduce render-thread jitter. The same cardinal rule applies:
avoid allocations and blocking operations inside process().
Invoke audio-dsp-review concepts (no allocations, no blocking) adapted for JavaScript:
replace "mutex" with "GC pause" and "malloc" with "object/array creation".
Step 1 — Identify the architecture
Determine which Web Audio pattern is in use before scanning:
| Pattern | Where audio runs | Risk level |
|---|
AudioWorkletProcessor subclass | Dedicated worklet thread | Medium — GC and message overhead |
ScriptProcessorNode | Main thread | High — deprecated; blocks UI |
Main-thread AudioContext only | Main thread | Low — standard graph |
OfflineAudioContext | Offline render | Low — no real-time deadline |
Step 2 — Scan for violations
| Violation | Location | Risk |
|---|
Using ScriptProcessorNode | Anywhere | Deprecated; runs on main thread → dropouts under UI load |
new Float32Array(...) inside process() | AudioWorkletProcessor.process() | GC allocation → potential pause during render |
Creating objects/arrays/closures inside process() | AudioWorkletProcessor.process() | GC pressure → jitter |
port.postMessage() every process() block | AudioWorkletProcessor | High overhead; batch updates or use SharedArrayBuffer |
Accessing window, document, or DOM from worklet | process() or worklet scope | Worklet thread has no DOM access — throws ReferenceError |
Importing non-worklet-safe modules in addModule() | Worklet module file | DOM APIs throw; do network/file loading on the main thread and pass data in |
| Not handling autoplay policy | AudioContext creation | Context starts suspended; must resume on user gesture |
SharedArrayBuffer comms without integer Atomics protocol | Worklet ↔ main comms | Race-prone shared state — Atomics works on integer typed arrays, not Float32Array |
Changing AudioNode graph from worklet thread | process() | connect()/disconnect() are main-thread-only |
| Assuming a hardcoded render quantum in loops/buffers | process() | Spec and browsers use 128-frame quanta today, but code should use output[channel].length |
Forgetting await audioContext.resume() | After user gesture handler | Stays suspended; no audio output |
Step 3 — Write the review
## Web Audio Safety Review: `[file / component]`
### Verdict
[Safe | Has critical violations | Warnings only] — [one sentence summary]
### Critical Violations
**[Category]: [description]**
`file:line` — `offending code`
Why: [realtime or correctness risk]
Fix: [concrete suggestion]
### Warnings
[same format]
### What's Done Well
[correct patterns observed]
### Recommended Fixes (priority order)
1. ...
See references/webaudio-violations.md for BAD/GOOD code examples for every violation above.
Quick fix table
| Violation | Safe alternative |
|---|
ScriptProcessorNode | AudioWorkletProcessor subclass |
new Float32Array() in process() | Pre-allocate in constructor; reuse across calls |
port.postMessage() every block | Batch at lower rate, or use SharedArrayBuffer + integer Atomics |
Raw SharedArrayBuffer reads | Atomics.load() / Atomics.store() on Int32Array / Uint32Array views |
| Graph changes from worklet | Queue a message to main thread; apply in port.onmessage |
| Context suspended | button.addEventListener('click', () => ctx.resume()) |
