Audio Buffer Utilities

Common errors

• TypeError: util.create is not a function

  cause Attempting to destructure or access `create` as a named export from 'audio-buffer-utils', when the library provides a single default export (an object containing all utility functions).
  fix Correct the import statement to `import util from 'audio-buffer-utils';` (ESM) or `const util = require('audio-buffer-utils');` (CommonJS), and then access the function as `util.create(...)`.

• RangeError: Offset + length out of bounds

  cause When using `util.copy(fromBuffer, toBuffer, offset)`, the target `toBuffer` is not large enough to hold all the data from `fromBuffer` starting at the specified `offset`.
  fix Before calling `util.copy`, ensure that `toBuffer.length` is greater than or equal to `offset + fromBuffer.length`. You might need to resize `toBuffer` or create a larger one.

• TypeError: Failed to execute 'connect' on 'AudioNode': parameter 1 is not of type 'AudioNode'.

  cause Attempting to connect the return value of `util.subbuffer` directly to a Web Audio API `AudioNode`. `subbuffer` returns a plain JavaScript object, not an `AudioBuffer` suitable for the Web Audio graph.
  fix After getting a subbuffer with `util.subbuffer`, create a new `AudioBuffer` instance using `AudioContext.createBuffer()` and copy the data from the subbuffer into this new `AudioBuffer` before connecting it to an `AudioNode`.

Warnings

• gotcha The project's stability badge explicitly indicates 'unstable', suggesting that internal APIs, function signatures, or behaviors might change in minor versions without adhering strictly to semantic versioning for non-major releases. Users should exercise caution and thoroughly test when upgrading.
  Fix: Refer to the GitHub repository and release notes for each version upgrade. Pin to specific patch versions (`~x.y.z`) to mitigate unexpected changes in production, and dedicate time for testing new minor versions.
• gotcha The `util.copy(fromBuffer, toBuffer, offset)` function can throw a `RangeError` (or similar) if the data from `fromBuffer`, when combined with the specified `offset`, extends beyond the length of `toBuffer`. This is not an automatic resize.
  Fix: Always ensure the `toBuffer` argument provided to `util.copy` has sufficient allocated length to accommodate all data being copied from `fromBuffer`, considering the starting `offset`.
• gotcha The `util.subbuffer` function returns a 'null-context buffer' – a plain JavaScript object that references a segment of the original buffer's data. This object is *not* a true Web Audio API `AudioBuffer` instance and cannot be used directly with `AudioContext` methods (e.g., `decodeAudioData`) or connected to `AudioNode`s.
  Fix: To use a subbuffer with the Web Audio API, you must explicitly convert its data into a new, proper `AudioBuffer` instance using `AudioContext.createBuffer` and copying the data (e.g., `newBuffer.copyToChannel(...)`) or by using `util.create` with the subbuffer's data.

Install

• npm install audio-buffer-utils npm
• yarn add audio-buffer-utils yarn
• pnpm add audio-buffer-utils pnpm

Imports

• util
  wrong:

  import { create, clone } from 'audio-buffer-utils'; // Incorrect named imports

  correct:

  import util from 'audio-buffer-utils';

  The library exports a single default object containing all utility functions. Access them as properties of this 'util' object.
• util

  const util = require('audio-buffer-utils');

  For CommonJS environments, the entire utility collection is exported as the module's default export.
• create
  wrong:

  import { create } from 'audio-buffer-utils'; // 'create' is not a named export

  correct:

  import util from 'audio-buffer-utils';
  const newBuffer = util.create(100);

  All functions like `create`, `clone`, `slice` are methods on the default-exported 'util' object, not individual named exports.

Quickstart

This quickstart demonstrates how to create, clone, slice, and fill `AudioBuffer` objects using the library's utility functions. It covers basic instantiation for mono and stereo buffers, copying data, extracting sub-sections, and modifying sample values.

import util from 'audio-buffer-utils';

// Create a mono buffer with 100 samples
const sampleRate = 44100;
const monoBuffer = util.create(100, 1, sampleRate);
console.log(`Created mono buffer: ${monoBuffer.length} samples, ${monoBuffer.numberOfChannels} channel(s).`);

// Create a stereo buffer with 2 seconds duration
const stereoBuffer = util.create(2 * sampleRate, 2, sampleRate);
console.log(`Created stereo buffer: ${stereoBuffer.length} samples, ${stereoBuffer.numberOfChannels} channel(s).`);

// Clone a buffer
const clonedBuffer = util.clone(monoBuffer);
console.log(`Cloned buffer is equal to original: ${util.equal(monoBuffer, clonedBuffer)}`);

// Slice a portion of the buffer
const slicedBuffer = util.slice(stereoBuffer, 0.5 * sampleRate, 1.5 * sampleRate);
console.log(`Sliced buffer from 0.5s to 1.5s: ${slicedBuffer.length} samples.`);

// Example of filling a channel with a value
util.fill(monoBuffer, null, 0.5); // Fill monoBuffer with 0.5
console.log(`Mono buffer first sample after fill: ${monoBuffer.getChannelData(0)[0]}`);