Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Vanilagy/mediabunny/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The encoding module provides types and functions for configuring and checking media encoding capabilities.

​
Types

​
VideoEncodingConfig

Configuration object that controls video encoding.
​
codec
VideoCodec
required
The video codec that should be used for encoding the video samples (frames).
​
bitrate
number | Quality
required
The target bitrate for the encoded video, in bits per second. Alternatively, a subjective Quality can be provided.
​
keyFrameInterval
number
default:"5"
The interval, in seconds, of how often frames are encoded as a key frame. Frequent key frames improve seeking behavior but increase file size. When using multiple video tracks, you should give them all the same key frame interval.
​
sizeChangeBehavior
'deny' | 'passThrough' | 'fill' | 'contain' | 'cover'
default:"'deny'"
Video frames may change size over time. This field controls the behavior in case this happens.
  • 'deny' (default): Throw an error, requiring all frames to have the exact same dimensions
  • 'passThrough': Allow the change and directly pass the frame to the encoder
  • 'fill': Stretch the image to fill the entire original box, potentially altering aspect ratio
  • 'contain': Contain the entire image within the original box while preserving aspect ratio (may cause letterboxing)
  • 'cover': Scale the image until the entire original box is filled, while preserving aspect ratio
​
alpha
'discard' | 'keep'
default:"'discard'"
What to do with alpha data contained in the video samples.
  • 'discard' (default): Only the samples’ color data is kept; the video is opaque
  • 'keep': The samples’ alpha data is also encoded as side data. Pair this with a container format that supports transparency (WebM or Matroska)
​
bitrateMode
'constant' | 'variable'
default:"'variable'"
Configures the bitrate mode.
​
latencyMode
'quality' | 'realtime'
default:"'quality'"
The latency mode used by the encoder; controls the performance-quality tradeoff.
  • 'quality' (default): The encoder prioritizes quality over latency, and no frames can be dropped
  • 'realtime': The encoder prioritizes low latency over quality, and may drop frames if overloaded
​
onEncodedPacket
(packet: EncodedPacket, meta?: EncodedVideoChunkMetadata) => unknown
Called for each successfully encoded packet. Both the packet and the encoding metadata are passed.
​
onEncoderConfig
(config: VideoEncoderConfig) => unknown
Called when the internal encoder config is created.
Source: encode.ts:33

​
AudioEncodingConfig

Configuration object that controls audio encoding.
​
codec
AudioCodec
required
The audio codec that should be used for encoding the audio samples.
​
bitrate
number | Quality
The target bitrate for the encoded audio, in bits per second. Alternatively, a subjective Quality can be provided. Required for compressed audio codecs, unused for PCM codecs.
​
bitrateMode
'constant' | 'variable'
Configures the bitrate mode.
​
onEncodedPacket
(packet: EncodedPacket, meta?: EncodedAudioChunkMetadata) => unknown
Called for each successfully encoded packet. Both the packet and the encoding metadata are passed.
​
onEncoderConfig
(config: AudioEncoderConfig) => unknown
Called when the internal encoder config is created.
Source: encode.ts:230

​
Quality

Represents a subjective media quality level. 
class Quality {
  constructor(factor: number);
}
Source: encode.ts:339

​
Quality constants

​
QUALITY_VERY_LOW

Represents a very low media quality. 
const QUALITY_VERY_LOW: Quality; // factor: 0.3
Source: encode.ts:420

​
QUALITY_LOW

Represents a low media quality. 
const QUALITY_LOW: Quality; // factor: 0.6
Source: encode.ts:426

​
QUALITY_MEDIUM

Represents a medium media quality. 
const QUALITY_MEDIUM: Quality; // factor: 1.0
Source: encode.ts:432

​
QUALITY_HIGH

Represents a high media quality. 
const QUALITY_HIGH: Quality; // factor: 2.0
Source: encode.ts:438

​
QUALITY_VERY_HIGH

Represents a very high media quality. 
const QUALITY_VERY_HIGH: Quality; // factor: 4.0
Source: encode.ts:444

​
Functions

​
canEncode

Checks if the browser is able to encode the given codec. 
function canEncode(codec: MediaCodec): Promise<boolean>
​
codec
MediaCodec
required
The media codec to check for encoding support.
​
return
Promise<boolean>
A promise that resolves to true if the codec can be encoded, false otherwise.
Source: encode.ts:451

​
canEncodeVideo

Checks if the browser is able to encode the given video codec with the given parameters. 
function canEncodeVideo(
  codec: VideoCodec,
  options?: {
    width?: number;
    height?: number;
    bitrate?: number | Quality;
  } & VideoEncodingAdditionalOptions
): Promise<boolean>
​
codec
VideoCodec
required
The video codec to check.
​
options
object
Optional encoding parameters to test.
​
return
Promise<boolean>
A promise that resolves to true if the video codec can be encoded with the given parameters.
Source: encode.ts:468

​
canEncodeAudio

Checks if the browser is able to encode the given audio codec with the given parameters. 
function canEncodeAudio(
  codec: AudioCodec,
  options?: {
    numberOfChannels?: number;
    sampleRate?: number;
    bitrate?: number | Quality;
  } & AudioEncodingAdditionalOptions
): Promise<boolean>
​
codec
AudioCodec
required
The audio codec to check.
​
options
object
Optional encoding parameters to test.
​
return
Promise<boolean>
A promise that resolves to true if the audio codec can be encoded with the given parameters.
Source: encode.ts:585

​
canEncodeSubtitles

Checks if the browser is able to encode the given subtitle codec. 
function canEncodeSubtitles(codec: SubtitleCodec): Promise<boolean>
​
codec
SubtitleCodec
required
The subtitle codec to check.
​
return
Promise<boolean>
A promise that resolves to true if the subtitle codec can be encoded.
Source: encode.ts:656

​
getEncodableCodecs

Returns the list of all media codecs that can be encoded by the browser. 
function getEncodableCodecs(): Promise<MediaCodec[]>
​
return
Promise<MediaCodec[]>
Array of all encodable video, audio, and subtitle codecs.
Source: encode.ts:669

​
getEncodableVideoCodecs

Returns the list of all video codecs that can be encoded by the browser. 
function getEncodableVideoCodecs(
  checkedCodecs?: VideoCodec[],
  options?: {
    width?: number;
    height?: number;
    bitrate?: number | Quality;
  }
): Promise<VideoCodec[]>
​
checkedCodecs
VideoCodec[]
default:"VIDEO_CODECS"
Array of codecs to check. Defaults to all video codecs.
​
options
object
Optional parameters for encoding capability testing.
​
return
Promise<VideoCodec[]>
Array of encodable video codecs from the checked list.
Source: encode.ts:684

​
getEncodableAudioCodecs

Returns the list of all audio codecs that can be encoded by the browser. 
function getEncodableAudioCodecs(
  checkedCodecs?: AudioCodec[],
  options?: {
    numberOfChannels?: number;
    sampleRate?: number;
    bitrate?: number | Quality;
  }
): Promise<AudioCodec[]>
​
checkedCodecs
AudioCodec[]
default:"AUDIO_CODECS"
Array of codecs to check. Defaults to all audio codecs.
​
options
object
Optional parameters for encoding capability testing.
​
return
Promise<AudioCodec[]>
Array of encodable audio codecs from the checked list.
Source: encode.ts:701

​
getEncodableSubtitleCodecs

Returns the list of all subtitle codecs that can be encoded by the browser. 
function getEncodableSubtitleCodecs(
  checkedCodecs?: SubtitleCodec[]
): Promise<SubtitleCodec[]>
​
checkedCodecs
SubtitleCodec[]
default:"SUBTITLE_CODECS"
Array of codecs to check. Defaults to all subtitle codecs.
​
return
Promise<SubtitleCodec[]>
Array of encodable subtitle codecs from the checked list.
Source: encode.ts:718

​
getFirstEncodableVideoCodec

Returns the first video codec from the given list that can be encoded by the browser. 
function getFirstEncodableVideoCodec(
  checkedCodecs: VideoCodec[],
  options?: {
    width?: number;
    height?: number;
    bitrate?: number | Quality;
  }
): Promise<VideoCodec | null>
​
return
Promise<VideoCodec | null>
The first encodable codec from the list, or null if none are encodable.
Source: encode.ts:730

​
getFirstEncodableAudioCodec

Returns the first audio codec from the given list that can be encoded by the browser. 
function getFirstEncodableAudioCodec(
  checkedCodecs: AudioCodec[],
  options?: {
    numberOfChannels?: number;
    sampleRate?: number;
    bitrate?: number | Quality;
  }
): Promise<AudioCodec | null>
​
return
Promise<AudioCodec | null>
The first encodable codec from the list, or null if none are encodable.
Source: encode.ts:752

​
getFirstEncodableSubtitleCodec

Returns the first subtitle codec from the given list that can be encoded by the browser. 
function getFirstEncodableSubtitleCodec(
  checkedCodecs: SubtitleCodec[]
): Promise<SubtitleCodec | null>
​
checkedCodecs
SubtitleCodec[]
required
Array of subtitle codecs to check.
​
return
Promise<SubtitleCodec | null>
The first encodable codec from the list, or null if none are encodable.
Source: encode.ts:774

​
Usage examples

​
Check encoding capabilities

import { canEncodeVideo, canEncodeAudio } from 'mediabunny';

// Check if AVC encoding is supported
const canEncodeAVC = await canEncodeVideo('avc');
console.log('Can encode AVC:', canEncodeAVC);

// Check with specific parameters
const canEncode4K = await canEncodeVideo('av1', {
  width: 3840,
  height: 2160,
  bitrate: 10_000_000
});

// Check audio encoding
const canEncodeAAC = await canEncodeAudio('aac', {
  numberOfChannels: 2,
  sampleRate: 48000,
  bitrate: 128_000
});

​
Get available codecs

import { getEncodableVideoCodecs, getFirstEncodableVideoCodec } from 'mediabunny';

// Get all encodable video codecs
const videoCodecs = await getEncodableVideoCodecs();
console.log('Available video codecs:', videoCodecs);

// Find the first encodable codec from a preference list
const preferredCodecs = ['av1', 'hevc', 'avc'];
const codec = await getFirstEncodableVideoCodec(preferredCodecs);
console.log('Using codec:', codec);

​
Configure encoding with quality presets

import { QUALITY_HIGH, QUALITY_MEDIUM, type VideoEncodingConfig } from 'mediabunny';

const videoConfig: VideoEncodingConfig = {
  codec: 'avc',
  bitrate: QUALITY_HIGH, // Uses quality preset instead of fixed bitrate
  keyFrameInterval: 3,
  sizeChangeBehavior: 'contain'
};

const audioConfig: AudioEncodingConfig = {
  codec: 'aac',
  bitrate: QUALITY_MEDIUM
};

Build docs developers (and LLMs) love

Get started for freeTalk to us