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.

Format	Description	Bytes/Sample
`u8`	Unsigned 8-bit interleaved	1
`s16`	Signed 16-bit interleaved	2
`s32`	Signed 32-bit interleaved	4
`f32`	32-bit float interleaved	4
`u8-planar`	Unsigned 8-bit planar	1
`s16-planar`	Signed 16-bit planar	2
`s32-planar`	Signed 32-bit planar	4
`f32-planar`	32-bit float planar	4

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.

Show AudioDataInit properties

format

AudioSampleFormat

required

The sample format of the audio data. See the sample formats table above.

sampleRate

number

required

The sample rate in Hz (e.g., 44100, 48000).

numberOfFrames

number

required

The number of audio frames. Each frame contains one sample per channel.

numberOfChannels

number

required

The number of audio channels (e.g., 1 for mono, 2 for stereo).

timestamp

number

required

The presentation timestamp in microseconds.

data

BufferSource

required

The raw audio sample data as an ArrayBuffer or TypedArray.

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

Example: Calculate buffer size

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

Example: Copy audio data to a buffer

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

Example: Copy a portion of audio data

// 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

Example: Clone audio data

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

Example: Proper resource cleanup

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

AudioEncoder

Encode raw audio data into compressed formats

AudioDecoder

Decode compressed audio into AudioData

EncodedAudioChunk

Container for encoded audio data

Getting Started

Migration Guides

API Reference

Guides

Cookbook

Examples

Help

AudioData

AudioData

Quick Example

Sample Formats

Constructor

Parameters

Properties

Methods

allocationSize()

Parameters

Returns

copyTo()

Parameters

Returns

clone()

Returns

close()

Returns

Interfaces

AudioDataInit

AudioDataCopyToOptions

Type Aliases

AudioSampleFormat

See Also

AudioEncoder

AudioDecoder

EncodedAudioChunk

​AudioData

​Quick Example

​Sample Formats

​Constructor

​Parameters

​Properties

​Methods

​allocationSize()

​Parameters

​Returns

​copyTo()

​Parameters

​Returns

​clone()

​Returns

​close()

​Returns

​Interfaces

​AudioDataInit

​AudioDataCopyToOptions

​Type Aliases

​AudioSampleFormat

​See Also

AudioEncoder

AudioDecoder

EncodedAudioChunk

AudioData

Quick Example

Sample Formats

Constructor

Parameters

Properties

Methods

allocationSize()

Parameters

Returns

copyTo()

Parameters

Returns

clone()

Returns

close()

Returns

Interfaces

AudioDataInit

AudioDataCopyToOptions

Type Aliases

AudioSampleFormat

See Also