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