Node Web Audio API

Common errors

• DeviceNotAvailable

  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.
  fix Initialize the audio context with `new AudioContext({ sinkId: { type: 'none' } })` to indicate it should run without an audio output device.

• Error: Could not find prebuilt binary for node-web-audio-api

  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).
  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`.

• error: linking with `cc` failed: exit status: 1

  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).
  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`).

Warnings

• gotcha 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.
  Fix: Rewrite code to utilize `AudioBuffer#copyToChannel(source, channelNumber)` or `AudioBuffer#copyFromChannel(destination, channelNumber)` instead of `getChannelData()`.
• gotcha 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.
  Fix: Avoid relying on advanced MediaStream functionalities. For complex streaming scenarios, consider alternative Node.js audio processing libraries or external services.
• gotcha 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.
  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' } })`.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install node-web-audio-api npm
• yarn add node-web-audio-api yarn
• pnpm add node-web-audio-api pnpm

Imports

• AudioContext
  wrong:

  const AudioContext = require('node-web-audio-api').AudioContext;

  correct:

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

  Prefer ESM imports in modern Node.js and TypeScript projects. CommonJS `require` is also supported as shown in the package examples.
• OscillatorNode
  wrong:

  const OscillatorNode = require('node-web-audio-api').OscillatorNode;

  correct:

  import { OscillatorNode } from 'node-web-audio-api';

  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.
• GainNode
  wrong:

  import GainNode from 'node-web-audio-api/GainNode';

  correct:

  import { GainNode } from 'node-web-audio-api';

  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.

Quickstart

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.

import { AudioContext, OscillatorNode, GainNode } from 'node-web-audio-api';

const audioContext = new AudioContext();

console.log('Generating audio for 10 seconds...');

const stopTime = audioContext.currentTime + 10;

const intervalId = setInterval(() => {
  if (audioContext.currentTime >= stopTime) {
    clearInterval(intervalId);
    console.log('Audio generation stopped.');
    audioContext.close(); // Important to close context to release resources
    return;
  }

  const now = audioContext.currentTime;
  const frequency = 200 + Math.random() * 2800; // Random frequency between 200Hz and 3000Hz

  const env = new GainNode(audioContext, { gain: 0 });
  env.connect(audioContext.destination);
  env.gain
    .setValueAtTime(0, now)
    .linearRampToValueAtTime(0.2, now + 0.02)
    .exponentialRampToValueAtTime(0.0001, now + 1);

  const osc = new OscillatorNode(audioContext, { frequency });
  osc.connect(env);
  osc.start(now);
  osc.stop(now + 1);
}, 80);