Client-side video conversion package used by @wordpress/upload-media. It currently converts animated GIFs to MP4/WebM during media upload.
This package is not used directly. When an animated GIF is uploaded, its frames are decoded using the browser’s native ImageDecoder API and re-encoded via WebCodecs (VideoEncoder) using the mediabunny library as an internal implementation detail. All processing runs inside a Web Worker to keep the main thread responsive.
Installation
Install the module:
npm install @wordpress/video-conversion --save
Requirements
- WebCodecs support: the browser must expose
ImageDecoderandVideoEncoder(available in Chromium-based browsers and Safari 16.4+). - Web Workers support: the browser must support Web Workers.
API Reference
cancelOperations
Cancels all ongoing operations for a given item ID.
Cancellation takes effect at async boundaries (waiting for the lock, encoder-support check, decoder completion, between frames).
Parameters
- id
ItemId: Item ID.
Returns
Promise< boolean >: Whether an operation was cancelled.
convertGifToVideo
Converts an animated GIF to a video file (MP4 or WebM).
Decodes GIF frames via the browser ImageDecoder (honoring per-frame delays) and re-encodes them with mediabunny / WebCodecs.
Accepts the GIF as a Blob so the bytes are read once, here in the worker, instead of being materialized on the main thread and transferred. An ArrayBuffer is still accepted for direct callers and tests.
Parameters
- id
ItemId: Item ID. - gifSource
ArrayBuffer | Blob: GIF file as a Blob/File or ArrayBuffer. - outputMimeType
string: Output MIME type (‘video/mp4’ or ‘video/webm’). - maxDimensions
number: Optional maximum dimension for downscaling.
Returns
Promise< ArrayBuffer >: Encoded video buffer.
UNSUPPORTED_ERROR_PREFIX
Message prefix for “unsupported but graceful” outcomes (no WebCodecs, unsupported codec). Consumers detect this prefix and fall back to uploading the original GIF instead of surfacing a hard error.
The contract is the message prefix, not the Error type: the worker RPC layer (comctx) serializes a thrown error to its message string only – the Error subclass, name, and stack do not survive the worker boundary.