Audio sources

Audio source classes for adding audio samples to output tracks

Audio sources are used to add audio samples to output audio tracks. All audio sources extend the base AudioSource class.

AudioBufferSource

Converts AudioBuffer instances (from the Web Audio API) to audio samples, encodes them, and adds them to the output track.

Constructor

new AudioBufferSource(encodingConfig: AudioEncodingConfig)

encodingConfig · AudioEncodingConfig · required

Configuration object that controls audio encoding.

Show AudioEncodingConfig properties

codec · AudioCodec · required

The audio codec for encoding. Common values: 'aac', 'opus', 'mp3', 'vorbis', 'flac', or various PCM codecs like 'pcm-s16le'.

bitrate · number | Quality

Target bitrate in bits per second, or a Quality object for subjective quality levels. Required for compressed audio codecs (like AAC, Opus, MP3), unused for PCM codecs.

bitrateMode · 'constant' | 'variable'

Bitrate encoding mode.

fullCodecString · string

Full codec string from Mediabunny Codec Registry. Auto-constructed if not provided.

onEncodedPacket · (packet: EncodedPacket, meta?: EncodedAudioChunkMetadata) => unknown

Callback for each successfully encoded packet.

onEncoderConfig · (config: AudioEncoderConfig) => unknown

Callback when the internal WebCodecs encoder config is created.

Methods

add

Converts an AudioBuffer to audio samples, encodes them, and adds them to the output. The first AudioBuffer starts at timestamp 0, with subsequent buffers following the cumulative duration.

add(audioBuffer: AudioBuffer): Promise<void>

audioBuffer · AudioBuffer · required

The AudioBuffer to convert and encode.

returns · Promise<void>

Resolves when the output is ready to receive more samples. Await this to respect backpressure.

close

Closes the source, preventing future samples and signaling no more data will be added to this track.

close(): void

Calling close() is optional but recommended after adding the last sample for improved performance and reduced memory usage.

---

AudioSampleSource

Adds raw, unencoded audio samples to an output audio track with automatic encoding.

Constructor

new AudioSampleSource(encodingConfig: AudioEncodingConfig)

encodingConfig · AudioEncodingConfig · required

Configuration object that controls audio encoding. See AudioBufferSource for detailed properties.

Methods

add

Encodes an audio sample and adds it to the output.

add(audioSample: AudioSample): Promise<void>

audioSample · AudioSample · required

The audio sample to encode and add.

returns · Promise<void>

Resolves when the output is ready to receive more samples. Await this to respect backpressure.

close

Closes the source. See AudioBufferSource.close() for details.

close(): void

---

EncodedAudioPacketSource

Directly pipes pre-encoded audio packets into the output file without additional encoding.

Constructor

new EncodedAudioPacketSource(codec: AudioCodec)

codec · AudioCodec · required

The codec used to encode the packets. Examples: 'aac', 'opus', 'mp3', 'vorbis', 'flac'.

Methods

add

Adds an encoded packet to the output audio track. Packets must be added in decode order.

add(
  packet: EncodedPacket,
  meta?: EncodedAudioChunkMetadata
): Promise<void>

packet · EncodedPacket · required

The encoded audio packet to add. Cannot be a metadata-only packet.

meta · EncodedAudioChunkMetadata

Additional encoder metadata. You should pass this for the first call, including a valid decoder config.

returns · Promise<void>

Resolves when the output is ready to receive more samples. Await this to respect backpressure.

close

Closes the source. See AudioBufferSource.close() for details.

close(): void

---

MediaStreamAudioTrackSource

Encodes data from a live MediaStreamAudioTrack (e.g., microphone or media element) and pipes it to the output. Audio is automatically captured once the connected Output is started.

Constructor

new MediaStreamAudioTrackSource(
  track: MediaStreamAudioTrack,
  encodingConfig: AudioEncodingConfig
)

track · MediaStreamAudioTrack · required

The audio MediaStreamTrack to capture audio from.

encodingConfig · AudioEncodingConfig · required

Configuration object that controls audio encoding. See AudioBufferSource for detailed properties.

Properties

errorPromise · Promise<never>

A promise that rejects upon any error within this source. This promise never resolves. You should handle this promise to catch internal errors.

paused · boolean

Whether this source is currently paused as a result of calling pause().

Methods

pause

Pauses the capture of audio data. Audio data emitted by the media stream is ignored while paused. This does not close the underlying track.

pause(): void

resume

Resumes the capture of audio data after being paused.

resume(): void

close

Stops capturing and closes the source. See AudioBufferSource.close() for details.

close(): void

Make sure to handle the errorPromise field so that internal errors are properly surfaced.

If MediaStreamTrackProcessor is not supported in the main thread, Mediabunny will attempt to use it in a Web Worker. If neither is available, an AudioContext fallback is used with the deprecated (but still functional) ScriptProcessorNode.