/webaudio-review

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())` |