Video sources

Video source classes for adding video samples to output tracks

Video sources are used to add video samples (frames) to output video tracks. All video sources extend the base VideoSource class.

CanvasSource

Captures frames from an HTML canvas or OffscreenCanvas element and encodes them for the output video track.

Constructor

new CanvasSource(
  canvas: HTMLCanvasElement | OffscreenCanvas,
  encodingConfig: VideoEncodingConfig
)

canvas · HTMLCanvasElement | OffscreenCanvas · required

The canvas element to capture frames from.

encodingConfig · VideoEncodingConfig · required

Configuration object that controls video encoding.

Show VideoEncodingConfig properties

codec · VideoCodec · required

The video codec for encoding: 'avc', 'hevc', 'vp8', 'vp9', or 'av1'.

bitrate · number | Quality · required

Target bitrate in bits per second, or a Quality object for subjective quality levels.

keyFrameInterval · number · default: "5"

Interval in seconds for encoding key frames. Frequent key frames improve seeking but increase file size.

sizeChangeBehavior · 'deny' | 'passThrough' | 'fill' | 'contain' | 'cover' · default: "'deny'"

Behavior when video frame dimensions change:

• 'deny': Throw an error (requires constant dimensions)
• 'passThrough': Allow the change and pass directly to encoder
• 'fill': Stretch to fill original box (may alter aspect ratio)
• 'contain': Fit within original box preserving aspect ratio (may letterbox)
• 'cover': Scale until original box is filled, preserving aspect ratio

alpha · 'discard' | 'keep' · default: "'discard'"

What to do with alpha channel data:

• 'discard': Only keep color data (opaque video)
• 'keep': Encode alpha as side data (requires WebM/Matroska container)

bitrateMode · 'constant' | 'variable' · default: "'variable'"

Bitrate encoding mode.

latencyMode · 'quality' | 'realtime' · default: "'quality'"

Encoder latency mode:

• 'quality': Prioritize quality, no frame dropping
• 'realtime': Prioritize low latency, may drop frames if overloaded

hardwareAcceleration · 'no-preference' | 'prefer-hardware' | 'prefer-software' · default: "'no-preference'"

Hardware acceleration preference.

fullCodecString · string

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

scalabilityMode · string

Encoding scalability mode identifier as defined by WebRTC-SVC.

contentHint · string

Video content hint as defined by mst-content-hint.

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

Callback for each successfully encoded packet.

onEncoderConfig · (config: VideoEncoderConfig) => unknown

Callback when the internal WebCodecs encoder config is created.

Methods

add

Captures the current canvas state as a video frame, encodes it, and adds it to the output.

add(
  timestamp: number,
  duration?: number,
  encodeOptions?: VideoEncoderEncodeOptions
): Promise<void>

timestamp · number · required

The timestamp of the sample in seconds.

duration · number · default: "0"

The duration of the sample in seconds.

encodeOptions · VideoEncoderEncodeOptions

Additional WebCodecs encoding options.

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.

---

VideoSampleSource

Adds raw, unencoded video samples (frames) to an output video track with automatic encoding.

Constructor

new VideoSampleSource(encodingConfig: VideoEncodingConfig)

encodingConfig · VideoEncodingConfig · required

Configuration object that controls video encoding. See CanvasSource for detailed properties.

Methods

add

Encodes a video sample (frame) and adds it to the output.

add(
  videoSample: VideoSample,
  encodeOptions?: VideoEncoderEncodeOptions
): Promise<void>

videoSample · VideoSample · required

The video sample to encode and add.

encodeOptions · VideoEncoderEncodeOptions

Additional WebCodecs encoding options.

returns · Promise<void>

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

close

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

close(): void

---

EncodedVideoPacketSource

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

Constructor

new EncodedVideoPacketSource(codec: VideoCodec)

codec · VideoCodec · required

The codec used to encode the packets: 'avc', 'hevc', 'vp8', 'vp9', or 'av1'.

Methods

add

Adds an encoded packet to the output video track. Packets must be added in decode order, while timestamps must be presentation timestamps. B-frames are handled automatically.

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

packet · EncodedPacket · required

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

meta · EncodedVideoChunkMetadata

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 CanvasSource.close() for details.

close(): void

---

MediaStreamVideoTrackSource

Encodes frames from a live MediaStreamVideoTrack (e.g., webcam or screen capture) and pipes them to the output. Frames are automatically captured once the connected Output is started.

Constructor

new MediaStreamVideoTrackSource(
  track: MediaStreamVideoTrack,
  encodingConfig: VideoEncodingConfig
)

track · MediaStreamVideoTrack · required

The video MediaStreamTrack to capture frames from.

encodingConfig · VideoEncodingConfig · required

Configuration object that controls video encoding. latencyMode is automatically set to 'realtime'. See CanvasSource for other 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 video frames. Frames emitted by the media stream are ignored while paused. This does not close the underlying track.

pause(): void

resume

Resumes the capture of video frames after being paused.

resume(): void

close

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

close(): void

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