contrib/avcodec: in-process video decode, plus the CI wiring to actually gate it

[paul-hammant]

contrib/avcodec — in-process FFmpeg video decode, so a renderer no longer has to transcode a whole clip to disk first. Aim #1 on aether-ui's video roadmap.

The module is Paul's work (commit 1); commits 2–3 are the shaping-up.

What the module does

A thin FFmpeg veneer following contrib/sqlite: C shim + module.ae + a catalogue entry with a pkg-config probe. Nothing vendored — user programs link -lavcodec -lavformat -lavutil -lswscale via their aether.toml.

Before, aether-ui's video_frame spawned ffmpeg to transcode a clip to raw RGBA on disk and fs.pread'd frames back: 27.6 MB for 6s of 320×240, ~1.5 GB per minute of 1080p, and no workaround at all for a live source (camera, network stream) since there is no file to pread. Now 27.6 MB → 0.

Surface is deliberately narrow — open, next frame as packed RGBA8888, close. Two ways to take a frame, mirroring sqlite's blob accessors: next_frame allocates a fresh owned string; next_frame_into writes into a caller-owned buffer, allocating nothing per frame (at 1080p30 that is 250 MB/s of churn avoided). fps() returns a ratio, not a float, because 30000/1001 does not survive a float round-trip.

The CI gate could never have passed

The module arrived with a good test — self-generating fixture via ffmpeg, clean SKIP when the binary is absent, and a sharp comment noting that the undersized-buffer assertion passed even with both capacity guards deleted (because the decoder was already at EOF), so it opens a fresh decoder to test a real refusal.

But its contrib_check.sh entry could not run. On a box with all four FFmpeg dev libraries installed:

FAIL  avcodec/decode  (build)
undefined reference to `avcodec_receive_frame'

The runner builds each test with ae build --extra <shim.c>, which compiles the shim but has no way to pass -l flags. So any module backed by a system library compiles and then dies at link. The entry was wired in but structurally incapable of running.

Fix: an optional fifth column naming the pkg-config modules a test must link against. When set, the runner stages an aether.toml workspace carrying link_flags — the same shape tests/integration/sqlite_roundtrip already uses, which is where ae's get_link_flags() picks them up — and SKIPs when pkg-config cannot find them, since an absent FFmpeg is a provisioning gap rather than a code defect.

I first tried @link(...) in module.ae (following sqlite's declaration). That does not work for this path and was reverted — // aether-link: is emitted by codegen as advice for a downstream build, not consumed by ae build.

Verification

Both paths, on this box:

with FFmpeg:     PASS  avcodec/decode  (run)      + all 6 existing contrib tests
without:         SKIP  avcodec/decode  (pkg-config: ... not found)

The module itself passes all six assertions — open + geometry, frame_bytes = w·h·4, fps ratio 10/1, a full RGBA frame, 20 frames decoded to EOF via the reused buffer, and the undersized-buffer refusal leaving the decoder usable.

make ci — C suite 230/230, .ae 975/977. Both failures are pre-existing and unrelated: integration_http_server_h2 (diagnosed in pesky_bug.md — an h2 connection-reuse bug, not the "50-stream" concurrency issue its name suggests) and http_middleware_d1, which passes in isolation and is the known load-sensitive flake.

Also

TODO.md gains a parked item: contrib/sqlite is covered by tests/integration/sqlite_roundtrip/ rather than contrib_check.sh, so contrib runtime coverage lives in two places with different shapes. The fix above means the table can now do generically what that shell driver does by hand — worth consolidating, but it rewrites a working test for no new coverage, so it is parked with the concrete next step written down.

🤖 Generated with Claude Code