High-level — wasmpeg

Complete reference for the default wasmpeg export — load, scale, decode, decodeAudio, probe, encode, run — with parameters, return shapes, and examples for each.

The default export. Accepts any JS input type — File, Blob, URL string, Uint8Array, ArrayBuffer, HTMLVideoElement, HTMLCanvasElement, ImageData — and handles buffer management and format inference for you. Source: src/js/wasmpeg.mjs.

Accepted input types

Every method takes the same input union. Normalization happens in normalizeInput (src/js/exec.mjs):

• File / Blob — read into memory; a File’s .name is used for the format hint (a plain Blob has none).
• URL string (http://, https://) — fetched; the URL pathname is used for the hint. A failed fetch throws.
• Absolute path string (starts with /) — treated as a WASM virtual-filesystem path. Only decode and encode accept this; decodeAudio and probe reject it.
• Uint8Array / ArrayBuffer — used as-is.
• HTMLVideoElement / HTMLCanvasElement / ImageData — read as raw RGBA pixels (valid only for scale and encode; the others throw). A video element must be loaded, or it throws video element has no dimensions.

Anything else throws Unsupported input type.

load

Loads and initializes the WASM module.

Signature

await wasmpeg.load(opts?)

Parameters

Behavior

Resolves a promise; safe to call multiple times (later calls resolve immediately). In a browser with WebGPU it loads the WebGPU build, otherwise the CPU build. Every other method throws call wasmpeg.load() first until this resolves.

Example

await wasmpeg.load();
await wasmpeg.load({ wasmPath: '/static/wasmpeg/cpu.js' });

scale

Decodes the first frame (or takes raw pixels) and runs a filtergraph.

Signature

await wasmpeg.scale(input, dstW, dstH, filter?)

Parameters

Returns

A Uint8ClampedArray of RGBA8 pixels, length dstW * dstH * 4.

Example

const rgba = await wasmpeg.scale(file, 1280, 720);
const fx   = await wasmpeg.scale(file, 1280, 720, 'scale=1280:720,hflip');

See the scale & filter guide and the filter reference.

decode

Opens a video decoder.

Signature

await wasmpeg.decode(input, { format }?)

Parameters

Returns

A Decoder object. Throws on raw-pixel input — use scale() for that.

Description

For byte inputs the demuxer is content-probed unless you pass format or the source name maps to a known non-probing format (the hint table in src/js/formats.js). An absolute-path input is opened from the WASM filesystem with the image2 demuxer, which is the reliable path for single-frame images.

Example

const dec = await wasmpeg.decode(file);
const dec = await wasmpeg.decode(bytes, { format: 'dnxhd' });

See the decode video guide.

Decoder object

The object returned by decode().

Properties

Methods

decodeAudio

Opens an audio decoder.

Signature

await wasmpeg.decodeAudio(input, { format }?)

Parameters

Returns

An AudioDecoder object. Decoded samples are interleaved 32-bit float at the source’s sample rate and channel count.

Example

const aud = await wasmpeg.decodeAudio(file);

See the decode audio guide.

AudioDecoder object

Properties

Methods

probe

Reads container metadata without decoding frames.

Signature

await wasmpeg.probe(input)

Parameters

Returns

{
  format:   string,        // demuxer name, e.g. "mov,mp4,m4a,3gp,3g2,mj2"
  duration: number|null,   // seconds, null if unknown
  bitrate:  number,        // overall bitrate in kb/s (-1 if unknown)
  streams:  [{ index: number, type: string }],   // type: video|audio|data|subtitle|attachment|unknown
  video:    { width, height, fpsNum, fpsDen },   // each field -1 if no video stream
  audio:    { sampleRate, channels },            // each field -1 if no audio stream
}

video and audio always exist; their fields are -1 when that stream type is absent. duration is null rather than -1 when unknown.

Example

const info = await wasmpeg.probe(file);

See the probe guide for field-by-field detail.

encode

Encodes frames (or raw pixels) and returns container bytes.

Signature

await wasmpeg.encode(input, opts?)

Parameters

Returns

A Uint8Array of the encoded container bytes.

Description

For raw-pixel input (canvas, video element, ImageData) it encodes that one frame. For a decoded input it opens a decoder, scales each frame to width/height, and pushes frames at fps until end of stream or frames is reached. The default container is image2pipe with the mjpeg codec — a single-stream image grab. image2 won’t work here; it needs numbered files on a real filesystem. The decoder and encoder are always closed, even on error.

Example

const jpg = await wasmpeg.encode(file, { codec: 'mjpeg', frames: 1 });
const png = await wasmpeg.encode(canvas, { codec: 'png' });

See the encode guide.

run

Low-level escape hatch — passes an FFmpeg-style arg array straight to the dispatcher.

Signature

await wasmpeg.run(input, args)

Parameters

Returns

RGBA pixels for a filter op, or a Decoder object for a decode-only command. See the command reference for the full surface.

Example

const rgba = await wasmpeg.run(file, ['-vf', 'scale=640:360,hflip']);

Memory and lifecycle

Buffer management is automatic at this level, but decoder lifecycles are not. Video and audio decoders each draw from a pool of 8 WASM session slots — always call close() when done, or a long-lived page can exhaust them and the next open throws ENOMEM (-12). scale, probe, and encode open and close their own sessions internally, so only decode/decodeAudio hand you something to close. To manage memory and lifecycles yourself, drop to the gpu namespace.