Webaudio review

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