{"id":16152,"library":"node-web-audio-api","title":"Node Web Audio API","description":"Node Web Audio API provides a robust and specification-compliant implementation of the W3C Web Audio API for Node.js environments. Currently at version 1.0.9, it leverages a performant Rust backend (`web-audio-api-rs`) and `napi-rs` bindings to offer core audio processing capabilities, including `AudioContext`, `OscillatorNode`, and `GainNode`, suitable for server-side audio generation and manipulation. While a strict release cadence isn't published, updates align with improvements in its underlying Rust components. Key differentiators include its high performance and strict adherence to the Web Audio API specification, which is crucial for developers porting browser-based audio applications or building new audio services in Node.js. An accompanying `isomorphic-web-audio-api` package is available for cross-platform development.","status":"active","version":"1.0.9","language":"javascript","source_language":"en","source_url":"https://github.com/ircam-ismm/node-web-audio-api","tags":["javascript","audio","web audio api","webaudio","sound","music","dsp","rust","node-api","typescript"],"install":[{"cmd":"npm install node-web-audio-api","lang":"bash","label":"npm"},{"cmd":"yarn add node-web-audio-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-web-audio-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Prefer ESM imports in modern Node.js and TypeScript projects. CommonJS `require` is also supported as shown in the package examples.","wrong":"const AudioContext = require('node-web-audio-api').AudioContext;","symbol":"AudioContext","correct":"import { AudioContext } from 'node-web-audio-api';"},{"note":"Named exports are standard for most Web Audio API classes. Avoid direct property access on the `require` result if you intend to use all exports.","wrong":"const OscillatorNode = require('node-web-audio-api').OscillatorNode;","symbol":"OscillatorNode","correct":"import { OscillatorNode } from 'node-web-audio-api';"},{"note":"All core Web Audio API classes are available as named exports from the main package entry point. There are no separate module paths for individual nodes.","wrong":"import GainNode from 'node-web-audio-api/GainNode';","symbol":"GainNode","correct":"import { GainNode } from 'node-web-audio-api';"}],"quickstart":{"code":"import { AudioContext, OscillatorNode, GainNode } from 'node-web-audio-api';\n\nconst audioContext = new AudioContext();\n\nconsole.log('Generating audio for 10 seconds...');\n\nconst stopTime = audioContext.currentTime + 10;\n\nconst intervalId = setInterval(() => {\n  if (audioContext.currentTime >= stopTime) {\n    clearInterval(intervalId);\n    console.log('Audio generation stopped.');\n    audioContext.close(); // Important to close context to release resources\n    return;\n  }\n\n  const now = audioContext.currentTime;\n  const frequency = 200 + Math.random() * 2800; // Random frequency between 200Hz and 3000Hz\n\n  const env = new GainNode(audioContext, { gain: 0 });\n  env.connect(audioContext.destination);\n  env.gain\n    .setValueAtTime(0, now)\n    .linearRampToValueAtTime(0.2, now + 0.02)\n    .exponentialRampToValueAtTime(0.0001, now + 1);\n\n  const osc = new OscillatorNode(audioContext, { frequency });\n  osc.connect(env);\n  osc.start(now);\n  osc.stop(now + 1);\n}, 80);\n","lang":"typescript","description":"This quickstart initializes an AudioContext and creates an oscillating sound with a random frequency and a decaying envelope every 80 milliseconds for a duration of 10 seconds."},"warnings":[{"fix":"Rewrite code to utilize `AudioBuffer#copyToChannel(source, channelNumber)` or `AudioBuffer#copyFromChannel(destination, channelNumber)` instead of `getChannelData()`.","message":"The `AudioBuffer#getChannelData` method can be unreliable in certain situations. It is strongly recommended to use `AudioBuffer#copyToChannel` and `AudioBuffer#copyFromChannel` for safe and consistent sample manipulation.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Avoid relying on advanced MediaStream functionalities. For complex streaming scenarios, consider alternative Node.js audio processing libraries or external services.","message":"Support for MediaStream features (beyond a minimal audio input stream and `MediaStreamSourceNode`) is limited. The library primarily focuses on the core Web Audio API specification, not the broader MediaStream API.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Initialize the `AudioContext` with `{ sinkId: { type: 'none' } }` to explicitly declare it as headless or without an audio output, e.g., `new AudioContext({ sinkId: { type: 'none' } })`.","message":"When running in environments without audio output devices (e.g., Docker containers, headless servers), creating an `AudioContext` without specific configuration will result in a `DeviceNotAvailable` error and crash the application.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure JACK or PipeWire with JACK compatibility is installed and configured on your Linux system. If issues persist, consider building from source after installing the Rust toolchain.","message":"Prebuilt binaries for Linux platforms are built with the `jack` flag and require either a properly configured JACK Audio Connection Kit or `pipewire-jack` backend to function correctly. Without these, the library may fail to initialize or produce audio.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Install the Rust toolchain using `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh` and then run `npm install` within the package directory or your project.","message":"If prebuilt binaries are not available for your specific platform/architecture, or if you wish to modify the source, a Rust toolchain must be installed on your system to compile the native modules. This is a common requirement for `napi-rs` based packages.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Initialize the audio context with `new AudioContext({ sinkId: { type: 'none' } })` to indicate it should run without an audio output device.","cause":"Attempting to create a new `AudioContext` instance in an environment (e.g., Docker, CI/CD) that lacks a physical audio output device without specifying a 'none' sink.","error":"DeviceNotAvailable"},{"fix":"First, ensure `npm install` ran successfully. If the error persists, you may need to compile the package from source. Install the Rust toolchain (`rustup install stable`) and then navigate to the package's `node_modules` directory (`cd node_modules/node-web-audio-api`) and run `npm run build`.","cause":"The current platform or architecture does not have a precompiled binary available, or the local environment is preventing its detection (e.g., network issues during install, permission problems).","error":"Error: Could not find prebuilt binary for node-web-audio-api"},{"fix":"On Debian/Ubuntu, install `build-essential` via `sudo apt-get install build-essential`. On macOS, install Xcode Command Line Tools via `xcode-select --install`. Ensure your Rust toolchain is also up-to-date (`rustup update`).","cause":"This error typically indicates missing C/C++ build tools required by the Rust compiler for native module compilation, common on Linux (e.g., `build-essential`) or macOS (Xcode Command Line Tools).","error":"error: linking with `cc` failed: exit status: 1"}],"ecosystem":"npm"}