Registry / serialization / node-web-audio-api

node-web-audio-api

library1.0.9jsnpmunverified

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.

serialization

npm install node-web-audio-api

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-WEB-AUDIO-API

node-web-audio-api

serializationjavascriptv1.0.9

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AudioContext

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

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

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

OscillatorNode

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

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

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

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

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

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.

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);

Debug

Known issues

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

affects: >=1.0.0

gotchaSupport 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.

affects: >=1.0.0

gotchaWhen 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' } })`.

affects: >=1.0.0

gotchaPrebuilt 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.

affects: >=1.0.0

gotchaIf 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.

affects: >=1.0.0

Errors

Common errors & fixes

DeviceNotAvailable

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

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

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

Upgrade

Version history

1.0.9latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/ircam-ismm/node-web-audio-api ↗

packagehttps://www.npmjs.com/package/node-web-audio-api ↗