Skip to main content

​
AudioData

The AudioData class represents a container for audio sample data. It provides access to raw audio samples along with metadata such as sample format, sample rate, channel count, and timestamps.
This API follows the W3C WebCodecs AudioData specification. Refer to the spec for detailed behavior requirements.
Memory Management: AudioData objects hold references to potentially large audio buffers. You must call close() when finished with an AudioData instance to release the underlying memory. Failure to do so can lead to memory leaks.

​
Quick Example

import { AudioData } from 'node-webcodecs';

// Create a 1-second stereo audio buffer at 48kHz
const sampleRate = 48000;
const numberOfChannels = 2;
const numberOfFrames = sampleRate; // 1 second of audio

// Create interleaved float32 audio data
const samples = new Float32Array(numberOfFrames * numberOfChannels);

// Fill with a 440Hz sine wave
for (let i = 0; i < numberOfFrames; i++) {
  const value = Math.sin(2 * Math.PI * 440 * i / sampleRate);
  samples[i * numberOfChannels] = value;     // Left channel
  samples[i * numberOfChannels + 1] = value; // Right channel
}

const audioData = new AudioData({
  format: 'f32',
  sampleRate: sampleRate,
  numberOfFrames: numberOfFrames,
  numberOfChannels: numberOfChannels,
  timestamp: 0,
  data: samples.buffer
});

console.log(`Duration: ${audioData.duration / 1_000_000} seconds`);
console.log(`Format: ${audioData.format}`);

// Always close when done
audioData.close();

​
Sample Formats

Planar vs Interleaved: In interleaved formats, samples alternate between channels (L, R, L, R…). In planar formats, each channel’s samples are stored contiguously in separate planes. Planar formats are often more efficient for audio processing, while interleaved formats are common for I/O operations.
FormatDescriptionBytes/Sample
u8Unsigned 8-bit interleaved1
s16Signed 16-bit interleaved2
s32Signed 32-bit interleaved4
f3232-bit float interleaved4
u8-planarUnsigned 8-bit planar1
s16-planarSigned 16-bit planar2
s32-planarSigned 32-bit planar4
f32-planar32-bit float planar4

​
Constructor

Creates a new AudioData instance from the provided initialization data. 
new AudioData(init: AudioDataInit): AudioData

​
Parameters

​
init
AudioDataInit
required
Configuration object for the audio data.

​
Properties

​
format
AudioSampleFormat | null
required
The sample format of the audio data. Returns null if the AudioData has been closed.
​
sampleRate
number
required
The sample rate in Hz. This value indicates how many samples represent one second of audio.
​
numberOfFrames
number
required
The number of audio frames in this AudioData. A frame consists of one sample per channel at a single point in time.
​
numberOfChannels
number
required
The number of audio channels. For example, 1 for mono audio, 2 for stereo.
​
duration
number
required
The duration in microseconds, calculated as (numberOfFrames / sampleRate) * 1_000_000.
​
timestamp
number
required
The presentation timestamp in microseconds, indicating when this audio should be played.

​
Methods

​
allocationSize()

Calculates the number of bytes needed to hold the audio data when copying with the specified options. 
allocationSize(options: AudioDataCopyToOptions): number

const audioData = new AudioData({
  format: 'f32-planar',
  sampleRate: 48000,
  numberOfFrames: 1024,
  numberOfChannels: 2,
  timestamp: 0,
  data: new Float32Array(1024 * 2).buffer
});

// Calculate size for first plane (channel)
const size = audioData.allocationSize({ planeIndex: 0 });
console.log(`Bytes needed: ${size}`); // 4096 (1024 frames * 4 bytes per f32)

audioData.close();

​
Parameters

​
options
AudioDataCopyToOptions
required
Options specifying which portion of audio to measure.

​
Returns

number - The number of bytes required.

​
copyTo()

Copies audio sample data to a destination buffer. 
copyTo(destination: BufferSource, options: AudioDataCopyToOptions): void

const audioData = new AudioData({
  format: 'f32-planar',
  sampleRate: 48000,
  numberOfFrames: 1024,
  numberOfChannels: 2,
  timestamp: 0,
  data: new Float32Array(1024 * 2).buffer
});

// Allocate destination buffer
const size = audioData.allocationSize({ planeIndex: 0 });
const buffer = new ArrayBuffer(size);

// Copy first channel's data
audioData.copyTo(buffer, { planeIndex: 0 });

// Access as Float32Array
const samples = new Float32Array(buffer);
console.log(`First sample: ${samples[0]}`);

audioData.close();

// Copy only 512 frames starting at frame 256
const partialSize = audioData.allocationSize({
  planeIndex: 0,
  frameOffset: 256,
  frameCount: 512
});

const partialBuffer = new ArrayBuffer(partialSize);
audioData.copyTo(partialBuffer, {
  planeIndex: 0,
  frameOffset: 256,
  frameCount: 512
});

​
Parameters

​
destination
BufferSource
required
The destination buffer to copy audio data into. Must be large enough to hold the data.
​
options
AudioDataCopyToOptions
required
Options specifying which portion of audio to copy.

​
Returns

void

​
clone()

Creates a copy of this AudioData with its own data buffer. 
clone(): AudioData

const audioData = new AudioData({
  format: 'f32',
  sampleRate: 48000,
  numberOfFrames: 1024,
  numberOfChannels: 2,
  timestamp: 0,
  data: new Float32Array(1024 * 2).buffer
});

const cloned = audioData.clone();

// Original and clone are independent
audioData.close();

// Clone is still valid
console.log(`Cloned format: ${cloned.format}`);
cloned.close();

​
Returns

AudioData - A new AudioData instance with copied data.

​
close()

Releases the resources held by this AudioData instance. After calling close(), the AudioData is no longer usable. 
close(): void

const audioData = new AudioData({
  format: 'f32',
  sampleRate: 48000,
  numberOfFrames: 1024,
  numberOfChannels: 2,
  timestamp: 0,
  data: new Float32Array(1024 * 2).buffer
});

// Process audio...
console.log(`Duration: ${audioData.duration}`);

// Release resources when done
audioData.close();

// After close(), format returns null
console.log(`Format after close: ${audioData.format}`); // null

​
Returns

void

​
Interfaces

​
AudioDataInit

Configuration object passed to the AudioData constructor.
​
format
AudioSampleFormat
required
The sample format of the audio data.
​
sampleRate
number
required
The sample rate in Hz.
​
numberOfFrames
number
required
The number of audio frames.
​
numberOfChannels
number
required
The number of audio channels.
​
timestamp
number
required
The presentation timestamp in microseconds.
​
data
BufferSource
required
The raw audio sample data.

​
AudioDataCopyToOptions

Options for the allocationSize() and copyTo() methods.
​
planeIndex
number
required
The index of the plane to copy. For interleaved formats, this is always 0. For planar formats, this is the channel index.
​
frameOffset
number
The offset in frames from the start of the audio data. Defaults to 0.
​
frameCount
number
The number of frames to copy. Defaults to all remaining frames from the offset.
​
format
AudioSampleFormat
Optional target format for conversion during copy. If not specified, uses the source format.

​
Type Aliases

​
AudioSampleFormat

type AudioSampleFormat =
  | "u8"
  | "s16"
  | "s32"
  | "f32"
  | "u8-planar"
  | "s16-planar"
  | "s32-planar"
  | "f32-planar";

​
See Also

AudioEncoder

Encode raw audio data into compressed formats

AudioDecoder

Decode compressed audio into AudioData

EncodedAudioChunk

Container for encoded audio data