web-audio-api

Portable Web Audio API / polyfill.

• 100% WPT conformance, no native deps.
• Audio in CI — OfflineAudioContext renders without speakers.
• CLI audio scripting – pipe, process, synthesize from terminal.
• Server-side audio – generate from APIs, bots, pipelines.
• Tone.js and web audio libs work in Node as-is.

npm install web-audio-api

Use

import { AudioContext } from 'web-audio-api'

const ctx = new AudioContext()
await ctx.resume()

const osc = ctx.createOscillator()
osc.frequency.value = 440
osc.connect(ctx.destination)
osc.start()
// → A440 through your speakers

Built-in speaker output via audio-speaker — no extra setup.

Offline rendering

import { OfflineAudioContext } from 'web-audio-api'

const ctx = new OfflineAudioContext(2, 44100, 44100) // 1 second, stereo
const osc = ctx.createOscillator()
osc.frequency.value = 440
osc.connect(ctx.destination)
osc.start()

const buffer = await ctx.startRendering()
// buffer.getChannelData(0) → Float32Array of 44100 samples

Examples

node examples/<name>.js — all parametric. Positional args or key=value with prefix matching (f=440, freq=440 both work). Note names (A4, C#3, Eb5), k for kHz (20k), s/m/h for duration (10m).

Node extensions

Beyond the spec, for Node.js. Not portable to browsers.

• addModule(fn) — register a processor via callback instead of URL, no file needed
• sinkId: stream — pipe PCM to any writable: new AudioContext({ sinkId: process.stdout }) then node synth.js | aplay -f cd
• numberOfChannels, bitDepth — control output format in the constructor
• navigator.mediaDevices.getUserMedia({ audio: true }) — browser-parity microphone capture in Node. Load web-audio-api/polyfill and install audio-mic; browser mic code then runs verbatim. See the mic FAQ.

FAQ

How do I close an AudioContext?

await ctx.close()

Or with [explicit resource management](https://github.com/tc39/proposal-explicit-resource-management): `using ctx = new AudioContext()`

Why does it start suspended?

Per [W3C spec](https://webaudio.github.io/web-audio-api/#dom-audiocontext-audiocontext) — browsers require user gesture before audio plays. Call `await ctx.resume()` to start. `OfflineAudioContext` doesn't need it.

Does it work with Tone.js?

Yes. Tone.js uses `standardized-audio-context` which needs `window.AudioParam` etc. for `instanceof` checks. The polyfill sets that up — just load Tone.js after it:

import 'web-audio-api/polyfill'
const Tone = await import('tone')

Tone.setContext(new AudioContext())
const synth = new Tone.Synth().toDestination()
synth.triggerAttackRelease('C4', '8n')

Tone.js must be a dynamic `import()` — static imports get hoisted before the polyfill runs. Alternatively, use `--import`:

node --import web-audio-api/polyfill app.js

Then static `import * as Tone from 'tone'` works in `app.js`.

How do I decode audio files?

const buffer = await ctx.decodeAudioData(readFileSync('track.mp3'))

WAV, MP3, FLAC, OGG, AAC via [audio-decode](https://github.com/audiojs/audio-decode).

How do I capture audio from the microphone?

In Node, pair [`audio-mic`](https://github.com/audiojs/audio-mic) with `MediaStreamAudioSourceNode.pushData()`:

npm install audio-mic

import { AudioContext, MediaStreamAudioSourceNode } from 'web-audio-api'
import mic from 'audio-mic'

const ctx = new AudioContext()
await ctx.resume()

const src = new MediaStreamAudioSourceNode(ctx, { numberOfChannels: 1, bitDepth: 16 })
src.connect(ctx.destination) // live monitor

const read = mic({ sampleRate: ctx.sampleRate, channels: 1, bitDepth: 16 })
read((err, buf) => {
  if (err || !buf) return
  src.pushData(buf, { channels: 1, bitDepth: 16 })
})

`pushData()` accepts `Float32Array`, `Float32Array[]`, or interleaved 8/16/32-bit integer PCM buffers. Integer PCM conversion uses `pcm-convert`. With `web-audio-api/polyfill`, `navigator.mediaDevices.getUserMedia()` is also available and maps constraints to `audio-mic` options: `{ audio: { sampleRate, channelCount, sampleSize } }`. See [examples/mic.js](examples/mic.js) for a runnable demo with gain and VU meter. To record the graph to a buffer, use `OfflineAudioContext.startRendering()`. To capture live graph output as a stream, use `ctx.createMediaStreamDestination()`.

How do I use it as a polyfill?

import 'web-audio-api/polyfill'
// AudioContext, GainNode, etc. are now global

Can I unit-test audio code?

`OfflineAudioContext` renders without speakers — pair with any test runner. See [render-to-buffer.js](examples/render-to-buffer.js).

How fast is it?

All scenarios render faster than real-time. Pure JS matches Rust napi on simple graphs; heavier DSP (convolution, compression) is 2–4× slower — WASM kernels planned. `npm run bench:all` to measure.

Architecture

Pull-based audio graph. AudioDestinationNode pulls upstream via _tick(), 128-sample render quanta per spec. AudioWorklet runs synchronously (no thread isolation). DSP kernels separated from graph plumbing for future WASM swap.

EventTarget ← Emitter ← DspObject ← AudioNode ← concrete nodes
                                    ← AudioParam
EventTarget ← Emitter ← AudioPort ← AudioInput / AudioOutput

Alternatives

• node-web-audio-api — Rust napi bindings. Faster heavy DSP, but Node-only with native compilation and partial spec.
• standardized-audio-context — Browser-only. Normalizes cross-browser quirks.
• web-audio-api-rs — Pure Rust / WASM.
• web-audio-engine — Archived. Partial spec coverage.
• react-native-audio-api – React native partial implementation.

License

MIT

ॐ