Encoding

Video and audio encoding configuration and utilities

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.

Show properties

width · number · default: "1280"

Video width in pixels.

height · number · default: "720"

Video height in pixels.

bitrate · number | Quality · default: "1000000"

Target bitrate or quality level.

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.

Show properties

numberOfChannels · number · default: "2"

Number of audio channels.

sampleRate · number · default: "48000"

Audio sample rate in Hz.

bitrate · number | Quality · default: "128000"

Target bitrate or quality level.

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