WebCodecs Video Transcoding Lab

A dependency-free browser lab for reproducing WebCodecs encode/decode failures with a live webcam source. It runs an isolated matrix of codec, encoder/decoder hardware-acceleration path, input-resolution, and encoded-output-resolution combinations and retains stage-level diagnostics for every case.

Run it

Webcam access requires a secure context. localhost qualifies:

bun run dev

Open http://localhost:8080 in a Chromium-based browser, start the camera, choose the matrix, and select Run matrix.

No install or build step is required. If Bun is unavailable, any static server can serve the directory, for example python3 -m http.server 8080.

What each case does

For each codec × acceleration path × input size × output size combination, the lab:

1. Probes the exact VideoEncoderConfig and base VideoDecoderConfig, including each stage's hardwareAcceleration preference.
2. Center-crops the current webcam frame to the requested input aspect ratio.
3. Scales that input frame to the encoded output size.
4. Forces frame zero to be a keyframe and records its type, size, timestamp, and first 64 bytes.
5. Configures VideoDecoder from the encoder's emitted decoderConfig metadata when available.
6. Submits encoded chunks to the decoder and waits for both codec queues to flush.
7. Classifies failures by stage: support probe, encoder configuration/submission/output/flush, decoder submission/callback/output/flush, or user stop.

The acceleration paths map to WebCodecs' no-preference, prefer-hardware, and prefer-software hints. In addition to matching automatic, hardware, and software paths, the lab can test hardware-preferred encode → software-preferred decode and software-preferred encode → hardware-preferred decode. Browsers may still choose different implementations, so the matrix reports requested preferences rather than claiming which codecs were used.

Cases run serially so simultaneous hardware codec pressure does not contaminate the result. Click a result cell to inspect the emitted decoder configuration and full event timeline. Export JSON includes the browser user agent, actual camera track settings, selected matrix dimensions, run options, summaries, and all case diagnostics.

The 90p edge sweep preset includes nearby even dimensions from 176×100 down to 144×80. Even dimensions are deliberate: many YUV 4:2:0 codec paths reject odd widths or heights before reaching the decoder behavior under investigation.

Tests

bun test

The test suite covers matrix construction, resolution parsing, bitrate estimation, summaries, and binary diagnostic serialization. Live WebCodecs behavior must be tested in the browser because it depends on the browser build, OS, and available hardware codec implementation.