web-audio-api

A pure JavaScript implementation of the Web Audio API for Node.js.

• Render existing audio graphs on the server.
• Test audio in CI: Node, Deno, and Bun.
• Decode and analyze 20+ formats outside of browser.
• Run tone.js and web audio libs via import 'web-audio-api/polyfill'.
• PCM in and out through stdio via CLI.

npm install web-audio-api

Use

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

This renders one second of a 440 Hz tone into memory without opening an audio device. Use the samples in a test or save them to a file. See render-to-buffer.js.

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

import 'web-audio-api/polyfill'
// npm install @audio/mic

const stream = await navigator.mediaDevices.getUserMedia({ audio: true })
const ctx = new AudioContext()
const src = ctx.createMediaStreamSource(stream)
src.connect(ctx.destination)

// stop capture
stream.getAudioTracks()[0].stop()

const devices = await navigator.mediaDevices.enumerateDevices()
const usb = devices.find(d => d.kind === 'audioinput' && d.label.includes('USB'))
const stream = await navigator.mediaDevices.getUserMedia({ audio: { deviceId: { exact: usb.deviceId } } })
const ctx = new AudioContext({ sinkId: devices.find(d => d.kind === 'audiooutput' && d.label.includes('Headphones')).deviceId })

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

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

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

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

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.onended = () => ctx.close()
osc.start()
osc.stop(ctx.currentTime + 1) // play for one second, then close the device

npm install @audio/mic

import { AudioContext, MediaStreamAudioSourceNode, CustomMediaStreamTrack, MediaStream } from 'web-audio-api'
import mic from '@audio/mic'

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

const track = new CustomMediaStreamTrack({
  kind: 'audio',
  label: 'mic',
  settings: { channelCount: 1, sampleSize: 16, sampleRate: ctx.sampleRate }
})
const stream = new MediaStream([track])

const src = new MediaStreamAudioSourceNode(ctx, { mediaStream: stream })
src.connect(ctx.destination) // live monitor

// @audio/mic's read(cb) is single-shot; re-arm it inside the callback.
const read = mic({ sampleRate: ctx.sampleRate, channels: 1, bitDepth: 16 })
const pump = () => read((err, buf) => {
  if (err || !buf) return
  track.pushData(buf, { channels: 1, bitDepth: 16 })
  pump()
})
pump()

await ctx.close()

Examples

node examples/<name>.js runs each example with its defaults. node examples/<name>.js --help for every accepted argument, option, keyboard control, and alternate invocation.

API

• speaker.js: Hello world
• lfo.js: Tremolo via LFO
• spatial.js: Sound moving through space
• worklet.js: Custom AudioWorkletProcessor
• linked-params.js: One source controlling many gains
• fft.js: Frequency spectrum
• render-to-buffer.js: Offline render → buffer
• process-file.js: Audio file → EQ + compress → render
• pipe-stdout.js: PCM to stdout – pipe to aplay, sox, etc.
• mic.js: Live microphone → speakers with RMS meter (requires @audio/mic)
• recorder.js: Record the mic to a WAV file, with a level meter (requires @audio/mic)
• reverb.js: Convolver with a seeded impulse response – 2 0.35 3s

Test signals

• tone.js: Reference pitch – sine A4 2s
• sweep.js: Hear the audible range – 20..20k exp 3s
• noise.js: White, pink, brown, blue, violet – pink 2s
• impulse.js: Dirac click – 5 0.5s
• dtmf.js: Dial a phone number – 5551234
• stereo-test.js: Left, right, center – 1k 1s
• metronome.js: Programmable stick click – 80..240 10m X-x-x-x-
• tuner.js: Guitar tuner – mic pitch in cents – 440 (requires @audio/mic)
• latency-tester.js: Round-trip latency: speakers → mic, in ms (requires @audio/mic)
• level-meter.js: Mic RMS and peak in dBFS, fast or slow ballistics (requires @audio/mic)

Synthesis

• subtractive-synth.js: Sawtooth → filter sweep → ADSR
• additive.js: Waveforms from harmonics – square 220 16 3s
• fm-synthesis.js: DX7 frequency modulation – 440 2 5 3s
• karplus-strong.js: A string plucked from noise – A4 4s
• wavetable.js: Fourier wavetables, crossfaded – organ 220 0.3 6s
• granular.js: Grain cloud from a seeded buffer – 0.08 15 4 10s

Generative

• sequencer.js: Step sequencer – precise timing
• serial.js: Twelve-tone rows (Webern) – 72 30s
• gamelan.js: Balinese kotekan – two parts, one melody – 120 20s
• drone.js: Tanpura, pads, or cinematic strings – voice=strings melody=pentatonic freq=D3 -d 30s
• jazz.js: Jazz in seven styles, modal first, lead on guitar, flute, harp, or piano – style=ambient lead=harp
• euclidean.js: Bjorklund rhythms, 2–3 voices – 120 16 3,5,7 20s

Illusions

• shepard.js: Pitch that rises forever – up 15s
• risset-rhythm.js: Beat that accelerates forever – up 120 20s
• binaural-beats.js: Third tone from two (headphones!) – 200 10 10s
• missing-fundamental.js: Your brain fills in the note – 100 3s
• beating.js: Two close frequencies dance – 440 3 5s
• octave-illusion.js: One tone jumps register and side (headphones!) – 400 800 2 12s
• scale-illusion.js: Two scales split between ears, regrouped by pitch (headphones!) – 200 261.63 8s
• tritone-paradox.js: Up or down? Tritone pairs that refuse to decide – 0 8 1.2
• continuity.js: A tone sounds unbroken through noise bursts – 440 0.6 on 15s
• streaming.js: Two tones fuse into one stream or split into two – 240 4 15s
• huggins-pitch.js: A pitch that exists in neither ear (headphones!) – 600 20s
• zwicker-tone.js: An after-tone lingers where the notch was – 2000 3 2 20s

Performance

Run npm run bench:compare for an offline-render comparison with node-web-audio-api. The runner alternates engines after warmup and reports median and p95 times over 50 renders. Saved results include raw samples, hardware, and versions.

These are short offline graphs, not audio-device latency measurements or realtime guarantees. Measure your own graph and deployment host.

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

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.
• CustomMediaStreamTrack – extends MediaStreamTrack with a public constructor and pushData(chunk, options) to feed audio data (e.g. from a microphone). Prior art: CanvasCaptureMediaStreamTrack. See the mic FAQ.

Alternatives

• node-web-audio-api – Rust DSP with Node bindings and native prebuilds; its browser export uses native Web Audio. Compare on your graph, especially when realtime performance matters.
• 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

ॐ