diff --git a/.github/scripts/contrib_check.sh b/.github/scripts/contrib_check.sh
index ce1bd4fb..01188eb5 100755
--- a/.github/scripts/contrib_check.sh
+++ b/.github/scripts/contrib_check.sh
@@ -38,15 +38,29 @@ mkdir -p "$run_dir"
 # code is correct. Those tests are gated for RUNTIME correctness (the thing that
 # actually caught the WS rot); making them leak-clean is separate follow-up
 # work. i18n/collate was written leak-clean by design, so it IS leak-gated.
+AVC="contrib/avcodec"
 TW="contrib/tinyweb"
 I18N="contrib/i18n"
+# <label>|<test .ae>|<extra C sources>|<leakgate>|<pkg-config modules>
+#
+# Column 5 is optional and names the pkg-config modules the test must LINK
+# against. It exists because `ae build --extra foo.c` compiles the shim but has
+# no way to pass -l flags — a module needing a system library therefore
+# compiles and then dies at link with "undefined reference". When column 5 is
+# set the runner stages an aether.toml workspace (the same shape
+# tests/integration/sqlite_roundtrip uses) so the flags reach gcc via
+# get_link_flags(), and SKIPS the entry when pkg-config cannot find the
+# modules — an absent system library is a provisioning gap, not a test failure.
 TESTS=(
-  "tinyweb/spec|$TW/test_spec.ae||run"
-  "tinyweb/inventory|$TW/test_inventory.ae|$TW/ws_handshake.c|run"
-  "tinyweb/integration|$TW/test_integration.ae|$TW/ws_handshake.c|run"
-  "tinyweb/schema_api|$TW/test_schema_api.ae|$TW/ws_handshake.c|run"
-  "tinyweb/websocket|$TW/test_websocket.ae|$TW/ws_handshake.c|run"
-  "i18n/collate|$I18N/collate/test_collate.ae|$I18N/aether_i18n.c $I18N/utf8proc/utf8proc.c $I18N/ducet/ducet_data.c|leak"
+  # avcodec: needs FFmpeg's dev libraries to LINK and the ffmpeg BINARY to
+  # generate its clip; the test itself SKIPs cleanly without the latter.
+  "avcodec/decode|$AVC/test_avcodec.ae|$AVC/aether_avcodec.c|run|libavcodec libavformat libavutil libswscale"
+  "tinyweb/spec|$TW/test_spec.ae||run|"
+  "tinyweb/inventory|$TW/test_inventory.ae|$TW/ws_handshake.c|run|"
+  "tinyweb/integration|$TW/test_integration.ae|$TW/ws_handshake.c|run|"
+  "tinyweb/schema_api|$TW/test_schema_api.ae|$TW/ws_handshake.c|run|"
+  "tinyweb/websocket|$TW/test_websocket.ae|$TW/ws_handshake.c|run|"
+  "i18n/collate|$I18N/collate/test_collate.ae|$I18N/aether_i18n.c $I18N/utf8proc/utf8proc.c $I18N/ducet/ducet_data.c|leak|"
 )
 
 # Kill any stray cache/test binaries squatting ports before we start (aborted
@@ -57,7 +71,7 @@ reap_orphans() {
 reap_orphans
 
 for entry in "${TESTS[@]}"; do
-  IFS='|' read -r label src extras leakgate <<< "$entry"
+  IFS='|' read -r label src extras leakgate pcmods <<< "$entry"
 
   if [ ! -f "$src" ]; then
     printf '  SKIP  %-22s (%s not found)\n' "$label" "$src"
@@ -71,7 +85,36 @@ for entry in "${TESTS[@]}"; do
   extra_flags=""
   for c in $extras; do extra_flags="$extra_flags --extra $c"; done
 
-  if ! berr="$("$AE$EXE_EXT" build "$src" $extra_flags -o "$out" 2>&1)"; then
+  if [ -n "$pcmods" ]; then
+    # Needs system libraries. Skip rather than fail when they are absent —
+    # a missing FFmpeg is a provisioning gap on this box, not a code defect.
+    if ! pkg-config --exists $pcmods 2>/dev/null; then
+      printf '  SKIP  %-22s (pkg-config: %s not found)\n' "$label" "$pcmods"
+      continue
+    fi
+    # `ae build --extra` cannot pass -l flags, so stage a workspace whose
+    # aether.toml carries them; ae threads link_flags into gcc via
+    # get_link_flags(). Same shape as tests/integration/sqlite_roundtrip.
+    work="$run_dir/${safe}.work"
+    rm -rf "$work"; mkdir -p "$work"
+    ln -s "$(pwd)/contrib" "$work/contrib"
+    cp "$src" "$work/probe.ae"
+    extra_toml=""
+    for c in $extras; do extra_toml="$extra_toml\"$c\", "; done
+    {
+      printf '[project]\nname = "%s"\nversion = "0.0.0"\n\n' "$safe"
+      printf '[[bin]]\nname = "probe"\npath = "probe.ae"\n'
+      printf 'extra_sources = [%s]\n\n' "${extra_toml%, }"
+      printf '[build]\nlink_flags = "%s"\n' "$(pkg-config --libs $pcmods)"
+    } > "$work/aether.toml"
+    abs_out="$(pwd)/$out"; abs_ae="$(pwd)/${AE#./}$EXE_EXT"
+    if ! berr="$( cd "$work" && "$abs_ae" build probe.ae -o "$abs_out" 2>&1 )"; then
+      printf '  FAIL  %-22s (build)\n' "$label"
+      echo "$berr" | grep -iE "error" | head -5
+      rc=1
+      continue
+    fi
+  elif ! berr="$("$AE$EXE_EXT" build "$src" $extra_flags -o "$out" 2>&1)"; then
     printf '  FAIL  %-22s (build)\n' "$label"
     echo "$berr" | grep -iE "error" | head -5
     rc=1
diff --git a/TODO.md b/TODO.md
index 9dd1f6ec..50403635 100644
--- a/TODO.md
+++ b/TODO.md
@@ -531,6 +531,47 @@ case (no `--with=fs` → engine errors clearly):
 
 ## Other parked work
 
+### Contrib runtime coverage is split across two mechanisms
+
+`contrib/sqlite` is **not** in `.github/scripts/contrib_check.sh` — it is
+covered by `tests/integration/sqlite_roundtrip/` instead. So contrib
+runtime coverage currently lives in two places with different shapes, and
+nothing says which a new module should use.
+
+Noticed while fixing the `avcodec` entry (2026-08-09), which had been added
+to `contrib_check.sh` but could never pass: the runner builds with
+`ae build --extra shim.c`, which compiles a C shim but **cannot pass `-l`
+flags**, so any module backed by a system library compiled and then died at
+link with `undefined reference`. The fix taught `contrib_check.sh` a fifth
+column naming pkg-config modules; when set it stages an `aether.toml`
+workspace carrying `link_flags` — which is precisely the shape
+`sqlite_roundtrip` had been using all along, hand-rolled in its own `.sh`.
+
+So the two mechanisms now overlap: `contrib_check.sh` can do what
+`sqlite_roundtrip` does, generically and in a table.
+
+**The work:** move `contrib/sqlite` into the `contrib_check.sh` table
+
+```
+"sqlite/roundtrip|contrib/sqlite/test_sqlite.ae|contrib/sqlite/aether_sqlite.c|run|sqlite3"
+```
+
+and retire `tests/integration/sqlite_roundtrip/`. Needs a
+`contrib/sqlite/test_sqlite.ae` first — the existing `probe.ae` is written
+for the workspace harness and would need adapting.
+
+**Why it is worth doing:** one table means a new native-backed contrib
+module gets runtime coverage by adding one line, rather than by copying a
+50-line shell driver and rediscovering the `aether.toml` trick. It also
+puts sqlite into the nightly's `make contrib-check-valgrind` sweep, which
+it is currently outside of.
+
+**Why it is parked:** the avcodec fix already covers the mechanism, sqlite
+*is* tested today (just elsewhere), and consolidating means rewriting a
+working test — pure cleanup with no new coverage. Do it when someone next
+adds a native-backed contrib module and has to choose between the two
+patterns.
+
 ### `std.bignum` — deferred optimizations
 
 The arbitrary-precision integer surface (`std/bignum/module.ae`) is functionally
diff --git a/contrib/avcodec/aether_avcodec.c b/contrib/avcodec/aether_avcodec.c
new file mode 100644
index 00000000..f359d576
--- /dev/null
+++ b/contrib/avcodec/aether_avcodec.c
@@ -0,0 +1,244 @@
+/* contrib/avcodec — thin FFmpeg video-decode veneer for Aether.
+ *
+ * The narrowest surface that removes the intermediate file: open a media
+ * source, pull decoded frames as packed RGBA8888, close. Deliberately video-
+ * only and deliberately not a media framework — audio, seeking, filtering and
+ * stream selection are all future work, and none of them are needed to feed a
+ * vg LIVE_RASTER region.
+ *
+ *   avc_open_raw(url, want_w, want_h)   -> Decoder*  (NULL on failure)
+ *   avc_width_raw(d) / avc_height_raw(d)-> int       (the SCALED output size)
+ *   avc_frame_bytes_raw(d)              -> int       (w*h*4)
+ *   avc_fps_num_raw(d) / avc_fps_den_raw(d) -> int   (source rate as a ratio)
+ *   avc_try_next_frame(d)               -> int       (1 = frame ready, 0 = EOF/error)
+ *   avc_get_frame_bytes()               -> const char*  (TLS slot from last try_)
+ *   avc_get_frame_length()              -> int
+ *   avc_release_frame()                 -> void      (free early; else next try_ frees)
+ *   avc_copy_frame_into_raw(d, buf, cap)-> int       (bytes written; 0 on failure)
+ *   avc_pts_ms_raw(d)                   -> int       (presentation time of the last frame)
+ *   avc_error_raw(d)                    -> const char*  (always non-NULL)
+ *   avc_close_raw(d)                    -> void
+ *
+ * The try_/get_/release_ trio mirrors contrib/sqlite's blob accessors, so
+ * binary data crosses the boundary the same way it already does elsewhere.
+ * avc_copy_frame_into_raw is the zero-allocation path: it writes straight
+ * into a caller-owned buffer, which is what a per-frame video loop wants —
+ * at 1080p a frame is 8 MB and allocating one per frame at 30fps is 250 MB/s
+ * of churn.
+ *
+ * A C-only dependency, like contrib/sqlite: user programs link
+ * -lavcodec -lavformat -lavutil -lswscale via aether.toml's link_flags.
+ * Nothing is vendored here.
+ */
+
+#include <libavcodec/avcodec.h>
+#include <libavformat/avformat.h>
+#include <libavutil/imgutils.h>
+#include <libswscale/swscale.h>
+#include <stdlib.h>
+#include <string.h>
+
+typedef struct {
+    AVFormatContext* fmt;
+    AVCodecContext*  dec;
+    struct SwsContext* sws;
+    AVFrame*   frame;      /* decoded, source pixel format */
+    AVFrame*   rgba;       /* converted, packed RGBA8888   */
+    AVPacket*  pkt;
+    uint8_t*   rgba_buf;   /* backing store for `rgba`     */
+    int        stream_idx;
+    int        out_w, out_h;
+    int        fps_num, fps_den;
+    long       pts_ms;
+    char       err[256];
+} Decoder;
+
+void avc_close_raw(void* h);   /* used by the open path's error unwind */
+
+/* TLS frame slot — same shape as sqlite's blob slot. */
+static _Thread_local char* g_frame_bytes = NULL;
+static _Thread_local int   g_frame_len   = 0;
+
+static void free_frame_tls(void) {
+    if (g_frame_bytes) { free(g_frame_bytes); g_frame_bytes = NULL; }
+    g_frame_len = 0;
+}
+
+static void set_err(Decoder* d, const char* msg) {
+    if (!d) return;
+    snprintf(d->err, sizeof(d->err), "%s", msg ? msg : "");
+}
+
+void* avc_open_raw(const char* url, int want_w, int want_h) {
+    if (!url) return NULL;
+    Decoder* d = (Decoder*)calloc(1, sizeof(Decoder));
+    if (!d) return NULL;
+    d->stream_idx = -1;
+
+    if (avformat_open_input(&d->fmt, url, NULL, NULL) < 0) {
+        set_err(d, "cannot open input");
+        free(d);
+        return NULL;
+    }
+    if (avformat_find_stream_info(d->fmt, NULL) < 0) {
+        set_err(d, "no stream info");
+        avformat_close_input(&d->fmt);
+        free(d);
+        return NULL;
+    }
+
+    const AVCodec* codec = NULL;
+    d->stream_idx = av_find_best_stream(d->fmt, AVMEDIA_TYPE_VIDEO, -1, -1, &codec, 0);
+    if (d->stream_idx < 0 || !codec) {
+        set_err(d, "no video stream");
+        avformat_close_input(&d->fmt);
+        free(d);
+        return NULL;
+    }
+
+    AVStream* st = d->fmt->streams[d->stream_idx];
+    d->dec = avcodec_alloc_context3(codec);
+    if (!d->dec || avcodec_parameters_to_context(d->dec, st->codecpar) < 0 ||
+        avcodec_open2(d->dec, codec, NULL) < 0) {
+        set_err(d, "cannot open decoder");
+        if (d->dec) avcodec_free_context(&d->dec);
+        avformat_close_input(&d->fmt);
+        free(d);
+        return NULL;
+    }
+
+    /* want_w/want_h <= 0 means "source size". Scaling here rather than in the
+       caller keeps the RGBA conversion and the resize in one swscale pass. */
+    d->out_w = want_w > 0 ? want_w : d->dec->width;
+    d->out_h = want_h > 0 ? want_h : d->dec->height;
+
+    AVRational fr = av_guess_frame_rate(d->fmt, st, NULL);
+    d->fps_num = fr.num > 0 ? fr.num : 0;
+    d->fps_den = fr.den > 0 ? fr.den : 1;
+
+    d->sws = sws_getContext(d->dec->width, d->dec->height, d->dec->pix_fmt,
+                            d->out_w, d->out_h, AV_PIX_FMT_RGBA,
+                            SWS_BILINEAR, NULL, NULL, NULL);
+    d->frame = av_frame_alloc();
+    d->rgba  = av_frame_alloc();
+    d->pkt   = av_packet_alloc();
+    if (!d->sws || !d->frame || !d->rgba || !d->pkt) {
+        set_err(d, "alloc failed");
+        avc_close_raw(d);
+        return NULL;
+    }
+
+    int nbytes = av_image_get_buffer_size(AV_PIX_FMT_RGBA, d->out_w, d->out_h, 1);
+    d->rgba_buf = (uint8_t*)av_malloc((size_t)nbytes);
+    if (!d->rgba_buf) {
+        set_err(d, "alloc failed");
+        avc_close_raw(d);
+        return NULL;
+    }
+    av_image_fill_arrays(d->rgba->data, d->rgba->linesize, d->rgba_buf,
+                         AV_PIX_FMT_RGBA, d->out_w, d->out_h, 1);
+    return d;
+}
+
+int avc_width_raw(void* h)        { Decoder* d = (Decoder*)h; return d ? d->out_w : 0; }
+int avc_height_raw(void* h)       { Decoder* d = (Decoder*)h; return d ? d->out_h : 0; }
+int avc_frame_bytes_raw(void* h)  { Decoder* d = (Decoder*)h; return d ? d->out_w * d->out_h * 4 : 0; }
+int avc_fps_num_raw(void* h)      { Decoder* d = (Decoder*)h; return d ? d->fps_num : 0; }
+int avc_fps_den_raw(void* h)      { Decoder* d = (Decoder*)h; return d ? d->fps_den : 1; }
+int avc_pts_ms_raw(void* h)       { Decoder* d = (Decoder*)h; return d ? (int)d->pts_ms : 0; }
+
+const char* avc_error_raw(void* h) {
+    Decoder* d = (Decoder*)h;
+    return (d && d->err[0]) ? d->err : "";
+}
+
+/* Decode until one frame is converted into d->rgba. Returns 1 on success,
+   0 at EOF or on error. Packets that yield no frame (B-frame reordering,
+   parameter sets) are consumed and the loop continues, so a caller sees one
+   call == one frame rather than having to understand FFmpeg's buffering. */
+static int decode_one(Decoder* d) {
+    if (!d || !d->fmt || !d->dec) return 0;
+    for (;;) {
+        int rc = avcodec_receive_frame(d->dec, d->frame);
+        if (rc == 0) {
+            sws_scale(d->sws, (const uint8_t* const*)d->frame->data,
+                      d->frame->linesize, 0, d->dec->height,
+                      d->rgba->data, d->rgba->linesize);
+            AVStream* st = d->fmt->streams[d->stream_idx];
+            int64_t pts = d->frame->best_effort_timestamp;
+            if (pts == AV_NOPTS_VALUE) pts = 0;
+            d->pts_ms = (long)(pts * av_q2d(st->time_base) * 1000.0);
+            return 1;
+        }
+        if (rc != AVERROR(EAGAIN) && rc != AVERROR_EOF) {
+            set_err(d, "decode error");
+            return 0;
+        }
+        if (rc == AVERROR_EOF) return 0;
+
+        int got = 0;
+        while (av_read_frame(d->fmt, d->pkt) >= 0) {
+            if (d->pkt->stream_index == d->stream_idx) {
+                int sc = avcodec_send_packet(d->dec, d->pkt);
+                av_packet_unref(d->pkt);
+                if (sc < 0) { set_err(d, "send packet failed"); return 0; }
+                got = 1;
+                break;
+            }
+            av_packet_unref(d->pkt);
+        }
+        if (!got) {
+            /* Input exhausted: flush the decoder's held frames, then EOF. */
+            avcodec_send_packet(d->dec, NULL);
+            if (avcodec_receive_frame(d->dec, d->frame) == 0) {
+                sws_scale(d->sws, (const uint8_t* const*)d->frame->data,
+                          d->frame->linesize, 0, d->dec->height,
+                          d->rgba->data, d->rgba->linesize);
+                return 1;
+            }
+            return 0;
+        }
+    }
+}
+
+/* Decode the next frame into the TLS slot (allocating a copy). */
+int avc_try_next_frame(void* h) {
+    free_frame_tls();
+    Decoder* d = (Decoder*)h;
+    if (!decode_one(d)) return 0;
+    int n = d->out_w * d->out_h * 4;
+    g_frame_bytes = (char*)malloc((size_t)n);
+    if (!g_frame_bytes) { g_frame_len = 0; return 0; }
+    memcpy(g_frame_bytes, d->rgba_buf, (size_t)n);
+    g_frame_len = n;
+    return 1;
+}
+
+const char* avc_get_frame_bytes(void) { return g_frame_bytes ? g_frame_bytes : ""; }
+int         avc_get_frame_length(void) { return g_frame_len; }
+void        avc_release_frame(void)    { free_frame_tls(); }
+
+/* Zero-allocation path: decode straight into a caller-owned buffer.
+   Returns bytes written, or 0 on EOF/failure/insufficient capacity. */
+int avc_copy_frame_into_raw(void* h, void* buf, int cap) {
+    Decoder* d = (Decoder*)h;
+    if (!d || !buf) return 0;
+    int n = d->out_w * d->out_h * 4;
+    if (cap < n) return 0;
+    if (!decode_one(d)) return 0;
+    memcpy(buf, d->rgba_buf, (size_t)n);
+    return n;
+}
+
+void avc_close_raw(void* h) {
+    Decoder* d = (Decoder*)h;
+    if (!d) return;
+    if (d->sws)      sws_freeContext(d->sws);
+    if (d->frame)    av_frame_free(&d->frame);
+    if (d->rgba)     av_frame_free(&d->rgba);
+    if (d->pkt)      av_packet_free(&d->pkt);
+    if (d->rgba_buf) av_free(d->rgba_buf);
+    if (d->dec)      avcodec_free_context(&d->dec);
+    if (d->fmt)      avformat_close_input(&d->fmt);
+    free(d);
+}
diff --git a/contrib/avcodec/module.ae b/contrib/avcodec/module.ae
new file mode 100644
index 00000000..4f16f2bb
--- /dev/null
+++ b/contrib/avcodec/module.ae
@@ -0,0 +1,104 @@
+// contrib.avcodec — thin FFmpeg video-decode veneer for Aether.
+// Import with: import contrib.avcodec
+//
+//   avcodec.open(url, w, h)      -> (dec, err)   // w/h <= 0 = source size
+//   avcodec.width(dec)           -> int          // the SCALED output width
+//   avcodec.height(dec)          -> int
+//   avcodec.frame_bytes(dec)     -> int          // w*h*4
+//   avcodec.fps(dec)             -> (num, den)   // source rate as a ratio
+//   avcodec.next_frame(dec)      -> (bytes, n, err)   // "" ,0, "eof" at end
+//   avcodec.next_frame_into(dec, buf, cap) -> (n, err) // zero-allocation
+//   avcodec.pts_ms(dec)          -> int          // presentation time of last frame
+//   avcodec.errmsg(dec)          -> string
+//   avcodec.close(dec)           -> void
+//
+// Video only, by design. Audio, seeking and stream selection are future
+// work; none are needed to feed decoded frames to a renderer, which is the
+// job this exists for.
+//
+// Two ways to take a frame, matching contrib/sqlite's blob accessors:
+//
+//   next_frame       allocates a fresh owned string per frame — simplest,
+//                    and fine at small sizes.
+//   next_frame_into  writes into a caller-owned buffer — nothing is
+//                    allocated per frame. At 1080p a frame is 8 MB and
+//                    30fps is 250 MB/s of churn, so a long-running player
+//                    should use this one. Pair it with bytes.to_string
+//                    (NOT bytes.finish, which destroys the buffer) if the
+//                    pixels then need to be passed on as a string.
+//
+// A C-only dependency: link with
+//   [build] link_flags = "-laether_avcodec -lavcodec -lavformat -lavutil -lswscale"
+// Nothing is vendored in contrib/.
+
+exports(
+    avc_open_raw, avc_close_raw,
+    avc_width_raw, avc_height_raw, avc_frame_bytes_raw,
+    avc_fps_num_raw, avc_fps_den_raw, avc_pts_ms_raw,
+    avc_try_next_frame, avc_get_frame_bytes, avc_get_frame_length,
+    avc_release_frame, avc_copy_frame_into_raw, avc_error_raw,
+    open, close, width, height, frame_bytes, fps, pts_ms,
+    next_frame, next_frame_into, errmsg
+)
+
+extern avc_open_raw(url: string, want_w: int, want_h: int) -> ptr
+extern avc_close_raw(dec: ptr)
+extern avc_width_raw(dec: ptr) -> int
+extern avc_height_raw(dec: ptr) -> int
+extern avc_frame_bytes_raw(dec: ptr) -> int
+extern avc_fps_num_raw(dec: ptr) -> int
+extern avc_fps_den_raw(dec: ptr) -> int
+extern avc_pts_ms_raw(dec: ptr) -> int
+extern avc_try_next_frame(dec: ptr) -> int
+extern avc_get_frame_bytes() -> string
+extern avc_get_frame_length() -> int
+extern avc_release_frame()
+extern avc_copy_frame_into_raw(dec: ptr, buf: ptr, cap: int) -> int
+extern avc_error_raw(dec: ptr) -> string
+extern string_new_with_length(data: string, length: int) -> ptr
+
+// Open a media source. `want_w`/`want_h` <= 0 means "source size"; anything
+// else scales during the RGBA conversion, so resizing costs no extra pass.
+open(url: string, want_w: int, want_h: int) -> {
+    d = avc_open_raw(url, want_w, want_h)
+    if d == null { return null, "cannot open ${url}" }
+    return d, ""
+}
+
+close(dec: ptr) { avc_close_raw(dec) }
+
+width(dec: ptr) -> int       { return avc_width_raw(dec) }
+height(dec: ptr) -> int      { return avc_height_raw(dec) }
+frame_bytes(dec: ptr) -> int { return avc_frame_bytes_raw(dec) }
+pts_ms(dec: ptr) -> int      { return avc_pts_ms_raw(dec) }
+errmsg(dec: ptr) -> string   { return avc_error_raw(dec) }
+
+// Source frame rate as a ratio rather than a float: 30000/1001 (NTSC) does
+// not survive a float round-trip cleanly, and a presentation-timestamp model
+// wants the exact ratio.
+fps(dec: ptr) -> {
+    return avc_fps_num_raw(dec), avc_fps_den_raw(dec)
+}
+
+// Decode the next frame as packed RGBA8888. Returns ("", 0, "eof") at the
+// end of the stream — EOF is not an error, so callers loop until n == 0.
+next_frame(dec: ptr) -> {
+    ok = avc_try_next_frame(dec)
+    if ok == 0 { return "", 0, "eof" }
+    raw = avc_get_frame_bytes()
+    n = avc_get_frame_length()
+    owned = string_new_with_length(raw, n)
+    avc_release_frame()
+    return owned, n, ""
+}
+
+// Zero-allocation variant: decode straight into a caller-owned buffer.
+// Returns (0, "eof") at end of stream, (0, "buffer too small") if cap is
+// under frame_bytes(dec).
+next_frame_into(dec: ptr, buf: ptr, cap: int) -> {
+    need = avc_frame_bytes_raw(dec)
+    if cap < need { return 0, "buffer too small: need ${need}, have ${cap}" }
+    n = avc_copy_frame_into_raw(dec, buf, cap)
+    if n == 0 { return 0, "eof" }
+    return n, ""
+}
diff --git a/contrib/avcodec/test_avcodec.ae b/contrib/avcodec/test_avcodec.ae
new file mode 100644
index 00000000..9106e51b
--- /dev/null
+++ b/contrib/avcodec/test_avcodec.ae
@@ -0,0 +1,101 @@
+// test_avcodec.ae — contrib/avcodec runtime gate.
+//
+// Generates its own clip with ffmpeg so the test carries no fixture, and
+// SKIPS cleanly when ffmpeg is absent -- the shim needs FFmpeg's libraries
+// to build at all, but the ffmpeg BINARY is only needed to make test input.
+import contrib.avcodec
+import std.string
+import std.bytes
+import std.os
+import std.list
+import std.fs
+
+extern exit(code: int)
+
+fail(msg: string) { println("  FAIL: ${msg}"); exit(1) }
+pass(msg: string) { println("  PASS: ${msg}") }
+
+main() {
+    clip = "/tmp/_avc_test_clip.mp4"
+    av = list.new()
+    _ = list.add(av, "-y")
+    _ = list.add(av, "-f")
+    _ = list.add(av, "lavfi")
+    _ = list.add(av, "-i")
+    _ = list.add(av, "testsrc=size=64x48:rate=10:duration=2")
+    _ = list.add(av, "-pix_fmt")
+    _ = list.add(av, "yuv420p")
+    _ = list.add(av, clip)
+    _o, st, e = os.run_capture("ffmpeg", av, null)
+    list.free(av)
+    if st != 0 {
+        println("  SKIP: ffmpeg not available to generate test input")
+        return
+    }
+
+    d, err = avcodec.open(clip, 64, 48)
+    if string.length(err) > 0 { fail("open: ${err}") }
+    if avcodec.width(d) != 64 { fail("width ${avcodec.width(d)} want 64") }
+    if avcodec.height(d) != 48 { fail("height ${avcodec.height(d)} want 48") }
+    pass("open + geometry")
+
+    fb = avcodec.frame_bytes(d)
+    if fb != 64 * 48 * 4 { fail("frame_bytes ${fb} want ${64 * 48 * 4}") }
+    pass("frame_bytes is w*h*4")
+
+    num, den = avcodec.fps(d)
+    if num <= 0 { fail("fps num ${num}") }
+    if den <= 0 { fail("fps den ${den}") }
+    pass("fps ratio ${num}/${den}")
+
+    // Allocation path.
+    px, n, ferr = avcodec.next_frame(d)
+    if n != fb { fail("next_frame n=${n} want ${fb}") }
+    if string.length(ferr) > 0 { fail("next_frame err ${ferr}") }
+    pass("next_frame returns a full RGBA frame")
+
+    // Zero-allocation path, one buffer reused to EOF. Counting to the end
+    // also proves EOF is reported as n==0 rather than looping forever.
+    buf = bytes.new(fb)
+    count = 1
+    guard = 0
+    while guard < 400 {
+        m, e2 = avcodec.next_frame_into(d, bytes.data(buf), fb)
+        if m == 0 { guard = 400 }
+        else {
+            if m != fb { fail("next_frame_into m=${m} want ${fb}") }
+            count = count + 1
+            guard = guard + 1
+        }
+    }
+    // 2s at 10fps: expect ~20 frames. Assert a RANGE, not an exact count --
+    // encoders round duration differently and an exact number would be a
+    // flake waiting to happen.
+    if count < 15 { fail("decoded only ${count} frames, want ~20") }
+    if count > 25 { fail("decoded ${count} frames, want ~20") }
+    pass("decoded ${count} frames to EOF via the reused buffer")
+
+    // A buffer that is too small must be refused, not overrun.
+    //
+    // On a FRESH decoder: the loop above ran `d` to EOF, and at EOF
+    // next_frame_into returns 0 whatever the capacity -- so asserting here
+    // against `d` passed even with BOTH capacity guards deleted. Testing a
+    // refusal needs a decoder that would otherwise have succeeded.
+    d2, err2 = avcodec.open(clip, 64, 48)
+    if string.length(err2) > 0 { fail("reopen: ${err2}") }
+    small = bytes.new(16)
+    m2, e3 = avcodec.next_frame_into(d2, bytes.data(small), 16)
+    if m2 != 0 { fail("undersized buffer accepted (m2=${m2})") }
+    if string.length(e3) == 0 { fail("undersized buffer gave no error") }
+    // ...and the same decoder still works with a correct buffer, proving
+    // the refusal did not consume the frame or wedge the decoder.
+    ok_buf = bytes.new(fb)
+    m3, e4 = avcodec.next_frame_into(d2, bytes.data(ok_buf), fb)
+    if m3 != fb { fail("decoder unusable after a refused read (m3=${m3})") }
+    avcodec.close(d2)
+    pass("undersized buffer is refused, decoder still usable")
+
+    avcodec.close(d)
+    _e = fs.delete(clip)
+    println("=== test_avcodec passed ===")
+}
diff --git a/tests/scripts/contrib_build.sh b/tests/scripts/contrib_build.sh
index 33f2500b..a1d8c762 100755
--- a/tests/scripts/contrib_build.sh
+++ b/tests/scripts/contrib_build.sh
@@ -156,6 +156,21 @@ probe_sqlite() {
     return 1
 }
 
+probe_avcodec() {
+    # FFmpeg's decode libraries. Video-only shim, but swscale does the RGBA
+    # conversion and avutil carries the frame/image helpers, so all four are
+    # required together -- a partial install is a SKIP, not a half-build.
+    if [ -n "$CROSS_MODE" ]; then
+        cross_dep_present libavcodec/avcodec.h avcodec
+        return
+    fi
+    if pkg-config --exists libavcodec libavformat libavutil libswscale 2>/dev/null; then
+        pkg-config --cflags-only-I libavcodec libavformat libavutil libswscale
+        return 0
+    fi
+    return 1
+}
+
 probe_lua() {
     for v in lua5.4 lua5.3 lua; do
         if pkg-config --exists "$v" 2>/dev/null; then
@@ -415,6 +430,7 @@ build_module() {
 # args are exactly what the build loop calls.
 CATALOGUE=(
     "sqlite|sqlite       contrib/sqlite/aether_sqlite.c           AETHER_HAS_SQLITE  probe_sqlite"
+    "avcodec|avcodec     contrib/avcodec/aether_avcodec.c         AETHER_HAS_AVCODEC probe_avcodec"
     "python|host_python  contrib/host/python/aether_host_python.c AETHER_HAS_PYTHON  probe_python"
     "lua|host_lua        contrib/host/lua/aether_host_lua.c       AETHER_HAS_LUA     probe_lua"
     "perl|host_perl      contrib/host/perl/aether_host_perl.c     AETHER_HAS_PERL    probe_perl"