{"id":14326,"library":"web-audio-api","title":"Portable Web Audio API for Node.js","description":"The `web-audio-api` package provides a 100% compliant, portable implementation of the W3C Web Audio API specification for Node.js environments. It currently stands at version 1.3.3 and aims for a stable, consistent release cadence, often aligning with updates to its underlying digital signal processing dependencies. Key differentiators include its complete WPT (Web Platform Tests) conformance, enabling server-side audio generation, CI/CD audio testing without requiring physical speakers, and the ability to run existing Web Audio API libraries like Tone.js directly in Node.js. It supports all 26 audio node types, sample-accurate scheduling, AudioWorklets, and full AudioParam automation. It can output in real-time via the `speaker` package or render to `Float32Array` buffers for offline processing.","status":"active","version":"1.3.3","language":"javascript","source_language":"en","source_url":"https://github.com/audiojs/web-audio-api","tags":["javascript","audio","audiojs","sound","music","web audio","web audio api","waa","dsp","typescript"],"install":[{"cmd":"npm install web-audio-api","lang":"bash","label":"npm"},{"cmd":"yarn add web-audio-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add web-audio-api","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides real-time audio output functionality for `AudioContext`. Automatically detected if present.","package":"audio-speaker","optional":true},{"reason":"Used for biquad filter coefficients and half-band FIR derivation.","package":"digital-filter","optional":false},{"reason":"Used for wavetable synthesis in `PeriodicWave`.","package":"periodic-function","optional":false}],"imports":[{"note":"ESM-only since v1.0.0. Use `import` statement for Node.js modules.","wrong":"const { AudioContext } = require('web-audio-api')","symbol":"AudioContext","correct":"import { AudioContext } from 'web-audio-api'"},{"note":"ESM-only. Used for rendering audio to a buffer without real-time output.","wrong":"const OfflineAudioContext = require('web-audio-api').OfflineAudioContext","symbol":"OfflineAudioContext","correct":"import { OfflineAudioContext } from 'web-audio-api'"},{"note":"This import extends the global `AudioContext` and `OfflineAudioContext` for browser environments. Not typically needed for Node.js usage.","wrong":"require('web-audio-api/polyfill')","symbol":"Polyfill","correct":"import 'web-audio-api/polyfill'"}],"quickstart":{"code":"import { AudioContext } from 'web-audio-api';\n\nconst ctx = new AudioContext();\n\n// Ensure the context is running; important for some environments.\n// In a browser environment, this might be triggered by user interaction.\n// In Node.js, we explicitly resume.\nawait ctx.resume();\n\nconst osc = ctx.createOscillator();\nosc.type = 'sine'; // Default is 'sine', but good to be explicit\nosc.frequency.value = 440; // A4 note\n\nconst gainNode = ctx.createGain();\ngainNode.gain.value = 0.5; // Half volume\n\nosc.connect(gainNode);\ngainNode.connect(ctx.destination);\n\nosc.start();\nconsole.log('Playing A440 for 2 seconds...');\n\n// Stop after 2 seconds\nsetTimeout(() => {\n  osc.stop();\n  ctx.close(); // Important to release resources, especially in Node.js\n  console.log('Audio stopped and context closed.');\n}, 2000);\n","lang":"typescript","description":"Demonstrates creating an AudioContext, an oscillator, connecting it to the destination via a gain node, playing a tone, and stopping it, closing the context cleanly."},"warnings":[{"fix":"Migrate CommonJS `require()` calls to ES module `import` statements. Ensure your Node.js project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json` or using `.mjs` file extensions).","message":"The package moved to be ESM-only for its main entry point, requiring `import` statements instead of `require()`. This was a major shift for Node.js users.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always include `await ctx.resume()` after creating a new `AudioContext` instance to ensure audio processing begins.","message":"The `AudioContext` in Node.js requires an explicit `ctx.resume()` call to start processing audio, similar to how browsers often gate audio playback on user interaction. Failing to call `resume()` will result in no sound.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If you intend to use real-time audio output, ensure `audio-speaker` is installed as a dependency: `npm install audio-speaker`.","message":"For real-time audio output, `web-audio-api` automatically detects and uses the `speaker` package. If `speaker` is not installed, it will fall back to other output mechanisms or fail to produce real-time sound.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"This is primarily an internal change and generally not breaking for users consuming the public API. However, if you were relying on specific internal implementation details (which is not recommended), you might need to adjust. Ensure `digital-filter` and `periodic-function` are installed if not already (they are listed as dependencies).","message":"Internal DSP implementations for `BiquadFilterNode`, `PeriodicWave`, and `WaveShaperNode` were refactored to delegate coefficient math and wavetable synthesis to external `digital-filter` and `periodic-function` libraries.","severity":"breaking","affected_versions":">=1.3.0"}],"env_vars":null,"search_vec":"'1.3.3':34 '100':15 '26':95 'abil':79 'accur':101 'aim':36 'align':44 'api':4,11,24,85,136 'audio':3,10,23,68,71,84,96,128,133,135 'audioj':129 'audioparam':106 'audioworklet':103 'autom':107 'buffer':123 'cadenc':42 'ci/cd':70 'complet':58 'compliant':16 'conform':63 'consist':40 'current':30 'depend':53 'differenti':55 'digit':50 'direct':89 'dsp':138 'enabl':64 'environ':28 'exist':82 'float32array':122 'full':105 'generat':69 'implement':18 'includ':56 'javascript':127 'key':54 'librari':86 'like':87 'music':131 'node':97 'node.js':6,27,91 'offlin':125 'often':43 'output':110 'packag':12,118 'physic':75 'platform':61 'portabl':1,17 'process':52,126 'provid':13 'real':113 'real-tim':112 'releas':41 'render':120 'requir':74 'run':81 'sampl':100 'sample-accur':99 'schedul':102 'server':66 'server-sid':65 'side':67 'signal':51 'sound':130 'speaker':76,117 'specif':25 'stabl':39 'stand':31 'support':93 'test':62,72 'time':114 'tone.js':88 'type':98 'typescript':139 'under':49 'updat':46 'version':33 'via':115 'w3c':21 'waa':137 'web':2,9,22,60,83,132,134 'web-audio-api':8 'without':73 'wpt':59","created_at":"2026-04-20T01:59:07.578889+00:00","updated_at":"2026-04-20T01:59:07.578889+00:00","problems":[{"fix":"Change your import statement from `const { AudioContext } = require('web-audio-api')` to `import { AudioContext } from 'web-audio-api'`. Ensure your Node.js project is configured for ESM (e.g., add `\"type\": \"module\"` to your `package.json` or rename files to `.mjs`).","cause":"Attempting to `require()` the `web-audio-api` package in a CommonJS module context, but the package is now ESM-only.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module ...web-audio-api/index.js from ... not supported."},{"fix":"Add `await ctx.resume()` immediately after creating your `AudioContext` instance: `const ctx = new AudioContext(); await ctx.resume();`","cause":"The `AudioContext` was created but `ctx.resume()` was not called, preventing the audio graph from starting.","error":"AudioContext.destination.connect: The destination is not yet initialized or ready."},{"fix":"Verify that `await ctx.resume()` has been called on the `AudioContext` and that all `AudioNode` connections are correctly chained, e.g., `osc.connect(gainNode); gainNode.connect(ctx.destination);`","cause":"Often happens when an `AudioNode` is not correctly connected or if `ctx.destination` is not available, which can be an symptom of the `AudioContext` not being resumed.","error":"TypeError: Cannot read properties of undefined (reading 'connect')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.5.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/audiojs/web-audio-api","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/web-audio-api","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","web-framework","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}