{"id":10524,"library":"audio-buffer-utils","title":"Audio Buffer Utilities","description":"audio-buffer-utils is a JavaScript utility library providing a comprehensive set of functions for manipulating `AudioBuffer` objects, primarily for Web Audio API contexts and Node.js environments. Currently at version 5.1.2, it offers operations such as creation, cloning, slicing, concatenation, mathematical transformations (reverse, invert, normalize), and various data manipulations (fill, resize, trim, pad, shift, rotate). The library focuses on performance optimization for audio processing tasks and is part of the `audiojs` organization, which maintains other Web Audio related packages. While offering robust functionality, its internal API stability is noted as 'unstable' in its badges, indicating potential API changes in minor versions, though the package is actively maintained and has a steady release cadence for bug fixes and minor features.","status":"active","version":"5.1.2","language":"javascript","source_language":"en","source_url":"git://github.com/audiojs/audio-buffer-utils","tags":["javascript","web","audio","audiojs","api","buffer","web audio","audio-buffer"],"install":[{"cmd":"npm install audio-buffer-utils","lang":"bash","label":"npm"},{"cmd":"yarn add audio-buffer-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add audio-buffer-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally by `util.create` for flexible AudioBuffer instantiation from various data sources.","package":"audio-buffer-from","optional":false},{"reason":"Used for efficient multi-dimensional array operations on audio data.","package":"ndarray","optional":false}],"imports":[{"note":"The library exports a single default object containing all utility functions. Access them as properties of this 'util' object.","wrong":"import { create, clone } from 'audio-buffer-utils'; // Incorrect named imports","symbol":"util","correct":"import util from 'audio-buffer-utils';"},{"note":"For CommonJS environments, the entire utility collection is exported as the module's default export.","symbol":"util","correct":"const util = require('audio-buffer-utils');"},{"note":"All functions like `create`, `clone`, `slice` are methods on the default-exported 'util' object, not individual named exports.","wrong":"import { create } from 'audio-buffer-utils'; // 'create' is not a named export","symbol":"create","correct":"import util from 'audio-buffer-utils';\nconst newBuffer = util.create(100);"}],"quickstart":{"code":"import util from 'audio-buffer-utils';\n\n// Create a mono buffer with 100 samples\nconst sampleRate = 44100;\nconst monoBuffer = util.create(100, 1, sampleRate);\nconsole.log(`Created mono buffer: ${monoBuffer.length} samples, ${monoBuffer.numberOfChannels} channel(s).`);\n\n// Create a stereo buffer with 2 seconds duration\nconst stereoBuffer = util.create(2 * sampleRate, 2, sampleRate);\nconsole.log(`Created stereo buffer: ${stereoBuffer.length} samples, ${stereoBuffer.numberOfChannels} channel(s).`);\n\n// Clone a buffer\nconst clonedBuffer = util.clone(monoBuffer);\nconsole.log(`Cloned buffer is equal to original: ${util.equal(monoBuffer, clonedBuffer)}`);\n\n// Slice a portion of the buffer\nconst slicedBuffer = util.slice(stereoBuffer, 0.5 * sampleRate, 1.5 * sampleRate);\nconsole.log(`Sliced buffer from 0.5s to 1.5s: ${slicedBuffer.length} samples.`);\n\n// Example of filling a channel with a value\nutil.fill(monoBuffer, null, 0.5); // Fill monoBuffer with 0.5\nconsole.log(`Mono buffer first sample after fill: ${monoBuffer.getChannelData(0)[0]}`);","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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(...)`.","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).","error":"TypeError: util.create is not a function"},{"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.","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`.","error":"RangeError: Offset + length out of bounds"},{"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`.","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.","error":"TypeError: Failed to execute 'connect' on 'AudioNode': parameter 1 is not of type 'AudioNode'."}],"ecosystem":"npm"}