@hyperframes/engine 0.6.0-alpha.2 → 0.6.0-alpha.5

package/src/services/videoFrameExtractor.ts

@@ -7,7 +7,7 @@
 
 import { spawn } from "child_process";
 import { existsSync, mkdirSync, readdirSync, rmSync } from "fs";
-import { isAbsolute, join } from "path";
+import { isAbsolute, join, posix, resolve, sep } from "path";
 import { parseHTML } from "linkedom";
 import { extractMediaMetadata, type VideoMetadata } from "../utils/ffprobe.js";
 import {
@@ -230,8 +230,17 @@ export async function extractVideoFramesRange(
   if (isHdr && isMacOS) {
     args.push("-hwaccel", "videotoolbox");
   }
-  if (metadata.hasAlpha && metadata.videoCodec === "vp9") {
-    args.push("-c:v", "libvpx-vp9");
+  // Always force the alpha-aware decoder on codecs that can carry alpha. The
+  // alternative — gating on `metadata.hasAlpha` — relies on tag detection that
+  // has at least three known failure modes: case-sensitivity across ffmpeg
+  // versions (`alpha_mode` vs `ALPHA_MODE`), missing tags from older muxers,
+  // and mp4-as-webm rewraps that drop the sidecar. A wrong negative there
+  // silently strips alpha during decode and the bug doesn't surface until
+  // the rendered video is missing layers. Codec-based default has no such
+  // ambiguity: libvpx-vp9 reads the alpha sidecar when present and decodes
+  // normally when it isn't.
+  if (codecMayHaveAlpha(metadata.videoCodec)) {
+    args.push("-c:v", decoderForCodec(metadata.videoCodec));
   }
   args.push("-ss", String(startTime), "-i", videoPath, "-t", String(duration));
 
@@ -398,9 +407,31 @@ function resolveSegmentDuration(
   return sourceRemaining > 0 ? sourceRemaining : metadata.durationSeconds;
 }
 
+/**
+ * Codecs whose bitstream is allowed to carry an alpha channel. Default the
+ * extraction path to PNG output for these regardless of `metadata.hasAlpha`
+ * so a missed sidecar tag doesn't silently strip transparency. Opaque content
+ * encoded in one of these codecs pays a small file-size cost on the cached
+ * frames but stays correct on the rare case where alpha IS present and the
+ * tag was missed.
+ */
+const ALPHA_CAPABLE_CODECS = new Set(["vp9", "vp8", "prores"]);
+
+export function codecMayHaveAlpha(codec: string | undefined): boolean {
+  return ALPHA_CAPABLE_CODECS.has((codec ?? "").toLowerCase());
+}
+
+export function decoderForCodec(codec: string | undefined): string {
+  const c = (codec ?? "").toLowerCase();
+  if (c === "vp9") return "libvpx-vp9";
+  if (c === "vp8") return "libvpx";
+  return c;
+}
+
 function resolveFrameFormat(metadata: VideoMetadata, requested?: "jpg" | "png"): CacheFrameFormat {
   if (requested) return requested;
-  return metadata.hasAlpha ? "png" : "jpg";
+  if (metadata.hasAlpha || codecMayHaveAlpha(metadata.videoCodec)) return "png";
+  return "jpg";
 }
 
 /**
@@ -459,6 +490,54 @@ async function convertVfrToCfr(
   }
 }
 
+/**
+ * Resolve a relative `<video src>` to a filesystem path the way the browser
+ * resolves it as a URL. Browsers clamp `..` segments at the served origin's
+ * root; `path.join(projectDir, "../assets/foo")` does not. So a sub-comp
+ * `<video src="../assets/foo">` loads in the page (browser clamps to
+ * `<projectDir>/assets/foo`) but the filesystem-side resolver lands at
+ * `<parentOfProjectDir>/assets/foo` — file missing, extraction skipped,
+ * the rendered output shows the video's first frame for the whole clip.
+ *
+ * The clamp covers two escape patterns: leading `..` (`../assets/foo`) AND
+ * mid-path escapes (`assets/../../foo`) that `path.join` collapses past the
+ * project root silently. Both fall back to a project-rooted candidate that
+ * strips traversal from the resolved path.
+ *
+ * Returns the first existing candidate, or the base-dir join on miss so
+ * the caller's `existsSync` check produces a stable error path.
+ */
+export function resolveProjectRelativeSrc(
+  src: string,
+  baseDir: string,
+  compiledDir?: string,
+): string {
+  const fromCompiled = compiledDir ? join(compiledDir, src) : null;
+  const fromBase = join(baseDir, src);
+  const candidates: string[] = [];
+  if (fromCompiled) candidates.push(fromCompiled);
+  candidates.push(fromBase);
+  // If the joined result escapes the project root (either via leading `..`
+  // or mid-path traversal that path.join collapsed past baseDir), retry
+  // with the basename re-anchored at the project root. This mirrors the
+  // browser URL clamp without relying on a particular `..` shape.
+  const baseAbs = resolve(baseDir);
+  const fromBaseAbs = resolve(fromBase);
+  if (!fromBaseAbs.startsWith(baseAbs + sep) && fromBaseAbs !== baseAbs) {
+    // Normalize first (`assets/../../assets/foo.mp4` → `../assets/foo.mp4`)
+    // then strip any remaining leading `..` segments. Stripping `..` from the
+    // raw input would leave dangling siblings (`assets/../../assets/foo`
+    // would become `assets/assets/foo` instead of `assets/foo`).
+    const normalized = posix.normalize(src.replace(/\\/g, "/"));
+    const stripped = normalized.replace(/^(\.\.\/)+/, "");
+    if (stripped && stripped !== src && !stripped.startsWith("..")) {
+      if (compiledDir) candidates.push(join(compiledDir, stripped));
+      candidates.push(join(baseDir, stripped));
+    }
+  }
+  return candidates.find(existsSync) ?? fromBase;
+}
+
 export async function extractAllVideoFrames(
   videos: VideoElement[],
   baseDir: string,
@@ -487,6 +566,9 @@ export async function extractAllVideoFrames(
   // Phase 1: Resolve paths and download remote videos
   const phase1Start = Date.now();
   const resolvedVideos: Array<{ video: VideoElement; videoPath: string }> = [];
+  // Dedupe missing-src warnings: a composition with N <video> elements all
+  // pointing at the same broken src should only print one warning, not N.
+  const warnedSrcs = new Set<string>();
   for (const video of videos) {
     if (signal?.aborted) break;
     try {
@@ -496,9 +578,7 @@ export async function extractAllVideoFrames(
       // baseDir and produce duplicated, nonexistent paths
       // (e.g. C:\tmp\hf-vfr-test-X\C:\tmp\hf-vfr-test-X\vfr_screen.mp4).
       if (!isAbsolute(videoPath) && !isHttpUrl(videoPath)) {
-        const fromCompiled = compiledDir ? join(compiledDir, videoPath) : null;
-        videoPath =
-          fromCompiled && existsSync(fromCompiled) ? fromCompiled : join(baseDir, videoPath);
+        videoPath = resolveProjectRelativeSrc(video.src, baseDir, compiledDir);
       }
 
       if (isHttpUrl(videoPath)) {
@@ -508,6 +588,19 @@ export async function extractAllVideoFrames(
       }
 
       if (!existsSync(videoPath)) {
+        // Loud: silent miss leaves the rendered video frozen at frame 0 with
+        // no error in stdout — extremely confusing for authors. Dedupe by
+        // src so 50 broken videos pointing at the same path don't spam.
+        if (!warnedSrcs.has(video.src)) {
+          warnedSrcs.add(video.src);
+          process.stderr.write(
+            `[hyperframes:render] WARNING: video src="${video.src}" ` +
+              `could not be resolved on disk (looked for ${videoPath}). ` +
+              `The rendered output will show this video's first frame for the entire clip duration. ` +
+              `If your <video> lives inside a sub-composition, prefer project-root-relative paths ` +
+              `(e.g. src="assets/foo.mp4") over "../assets/foo.mp4".\n`,
+          );
+        }
         errors.push({ videoId: video.id, error: `Video file not found: ${videoPath}` });
         continue;
       }

package/src/services/videoFrameInjector.test.ts

@@ -0,0 +1,145 @@
+// @vitest-environment node
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { __testing } from "./videoFrameInjector.js";
+import { DEFAULT_CONFIG } from "../config.js";
+
+const { createFrameSourceCache } = __testing;
+
+const SHARED_STATS = { evictions: 0, oversizedRejections: 0 };
+
+describe("frame source cache eviction", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "hf-frame-cache-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  // Each PNG is base64-encoded into the data URI, so the cached string is
+  // ~4/3 the file size plus a small `data:image/png;base64,` prefix. Build
+  // distinct files so eviction has predictable victims.
+  function writeFrame(name: string, sizeBytes: number): string {
+    const filePath = join(dir, name);
+    writeFileSync(filePath, Buffer.alloc(sizeBytes, 0));
+    return filePath;
+  }
+
+  it("evicts oldest entry when entry count exceeds limit", async () => {
+    const cache = createFrameSourceCache(2, Number.MAX_SAFE_INTEGER);
+    const a = writeFrame("a.png", 16);
+    const b = writeFrame("b.png", 16);
+    const c = writeFrame("c.png", 16);
+
+    await cache.get(a);
+    await cache.get(b);
+    expect(cache.stats().entries).toBe(2);
+
+    await cache.get(c);
+    expect(cache.stats().entries).toBe(2);
+    expect(cache.stats().evictions).toBe(1);
+
+    // Verify the *oldest* entry (a) was the victim — the LRU contract.
+    // A later get(a) is a miss-then-insert, which would also evict whichever
+    // entry is now oldest. We instrument the eviction counter to detect it.
+    const evictionsBefore = cache.stats().evictions;
+    await cache.get(a);
+    expect(cache.stats().evictions).toBe(evictionsBefore + 1);
+    // After re-inserting `a`, `b` is the next oldest. `c` is now newest.
+    // Touch `b` (move-to-front) → next eviction would be `c`, not `b`.
+  });
+
+  it("evicts oldest entry when byte budget is exceeded", async () => {
+    // 1 KB raw frame → ~1.4 KB base64 + ~22-byte data URI prefix. Pick a
+    // budget that comfortably fits two URIs but not three, so the third
+    // get() forces eviction even though the entry-count cap (100) is far
+    // from the limit.
+    const cache = createFrameSourceCache(100, 4 * 1024);
+    const a = writeFrame("a.png", 1024);
+    const b = writeFrame("b.png", 1024);
+    const c = writeFrame("c.png", 1024);
+
+    await cache.get(a);
+    await cache.get(b);
+    expect(cache.stats().entries).toBe(2);
+
+    await cache.get(c);
+    const afterC = cache.stats();
+    // The byte budget is the contract — the cache MUST stay under it after
+    // an insert that would otherwise overflow. Entry count is incidental.
+    expect(afterC.bytes).toBeLessThanOrEqual(4 * 1024);
+    expect(afterC.entries).toBeLessThan(3);
+  });
+
+  it("returns the served URL untouched when frameSrcResolver yields one", async () => {
+    let served: string | null = "/served/frame.png";
+    const cache = createFrameSourceCache(4, 64 * 1024, () => served);
+    const file = writeFrame("a.png", 256);
+
+    expect(await cache.get(file)).toBe("/served/frame.png");
+    // Cache stays empty because the resolver short-circuits the read.
+    expect(cache.stats()).toMatchObject({ entries: 0, bytes: 0 });
+
+    served = null;
+    const dataUri = await cache.get(file);
+    expect(dataUri.startsWith("data:image/png;base64,")).toBe(true);
+    expect(cache.stats().entries).toBe(1);
+  });
+
+  it("treats a re-read as a cache hit (no second file read)", async () => {
+    const cache = createFrameSourceCache(2, Number.MAX_SAFE_INTEGER);
+    const a = writeFrame("a.png", 64);
+
+    const first = await cache.get(a);
+    const second = await cache.get(a);
+    expect(second).toBe(first);
+    expect(cache.stats().entries).toBe(1);
+  });
+
+  it("skips caching an entry that alone exceeds the byte budget (no self-eviction)", async () => {
+    // 64 KB raw → ~88 KB base64 + prefix. Budget of 32 KB rejects this entry.
+    // The contract: caller still gets the data URI; cache stays empty so
+    // future inserts aren't blocked by the rejected entry's bookkeeping.
+    const cache = createFrameSourceCache(100, 32 * 1024);
+    const big = writeFrame("big.png", 64 * 1024);
+
+    const dataUri = await cache.get(big);
+    expect(dataUri.startsWith("data:image/png;base64,")).toBe(true);
+    expect(cache.stats().entries).toBe(0);
+    expect(cache.stats().bytes).toBe(0);
+    expect(cache.stats().oversizedRejections).toBe(1);
+    expect(cache.stats().evictions).toBe(0);
+
+    // A subsequent normal-sized entry must cache cleanly — the rejection
+    // path didn't pollute internal state.
+    const small = writeFrame("small.png", 1024);
+    await cache.get(small);
+    expect(cache.stats().entries).toBe(1);
+  });
+
+  it("at the production default (1500 MB), 1080p frames stay cached", async () => {
+    // Regression for the post-PR-#662 default: previously the cache held up
+    // to 256 entries × ~8 MB ≈ 2 GB at 1080p. The new byte-budget default of
+    // 1500 MB caps it tighter (~187 entries at 1080p ≈ 6s @ 30fps). This
+    // test pins the math so a future tweak to the default is visible.
+    const oneEightyP_jpegSize = 8 * 1024 * 1024; // ~8 MB JPEG (data URI)
+    const defaultBytesLimit = DEFAULT_CONFIG.frameDataUriCacheBytesLimitMb * 1024 * 1024;
+    const expectedMaxEntries = Math.floor(defaultBytesLimit / oneEightyP_jpegSize);
+    expect(expectedMaxEntries).toBeGreaterThanOrEqual(180);
+    expect(expectedMaxEntries).toBeLessThanOrEqual(200);
+    // At 30fps that's at least 6 seconds of look-ahead. Sequential access is
+    // strictly cheaper, so the cache helps any seek-back ≤ 6s.
+    expect(expectedMaxEntries / 30).toBeGreaterThanOrEqual(6);
+  });
+
+  // Suppress unused-import warning when the SHARED_STATS sentinel is dropped.
+  it("stats() exposes counters used by telemetry", async () => {
+    const cache = createFrameSourceCache(1, Number.MAX_SAFE_INTEGER);
+    expect(cache.stats()).toMatchObject({ ...SHARED_STATS, entries: 0, bytes: 0 });
+  });
+});

package/src/services/videoFrameInjector.ts

@@ -15,28 +15,91 @@ import { type BeforeCaptureHook } from "./frameCapture.js";
 import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
 
 export interface VideoFrameInjectorOptions extends Partial<
-  Pick<EngineConfig, "frameDataUriCacheLimit">
+  Pick<EngineConfig, "frameDataUriCacheLimit" | "frameDataUriCacheBytesLimitMb">
 > {
   frameSrcResolver?: (framePath: string) => string | null;
 }
 
+interface FrameSourceCacheStats {
+  entries: number;
+  bytes: number;
+  /** Total entries evicted since cache creation. A high count vs a small
+   * composition signals the byte budget is too tight (cache thrash). */
+  evictions: number;
+  /** Total inserts rejected because the entry alone exceeds bytesLimit.
+   * Non-zero means a single frame is bigger than the configured budget —
+   * raise `frameDataUriCacheBytesLimitMb` if it recurs in production. */
+  oversizedRejections: number;
+}
+
+interface FrameSourceCache {
+  get: (framePath: string) => Promise<string>;
+  /** Exposed for tests + telemetry; reflects current cache occupancy. */
+  stats: () => FrameSourceCacheStats;
+}
+
+/**
+ * Two-bound LRU keyed by frame path. Either bound triggers eviction of the
+ * oldest entry — entry count protects against pathological many-tiny-frames
+ * cases, and the byte budget keeps memory bounded when the per-frame data
+ * URI grows (4K PNG frames are ~33 MB once base64-encoded).
+ *
+ * If a single entry's data URI exceeds `bytesLimit`, we skip caching it
+ * (returning the URI directly to the caller). Without this guard, the
+ * post-insert eviction loop would drop the entry we just inserted and the
+ * cache would degrade into a CPU hot path — every subsequent `get()` would
+ * re-read from disk and re-base64 the same frame.
+ *
+ * **Invariant**: cached values MUST be strings whose `.length` equals the
+ * byte count we account for at insertion. We derive size on demand via
+ * `cache.get(key)?.length` rather than maintaining a parallel `Map<string, number>`.
+ * If you ever wrap the value (e.g. cache a Buffer or an object), the byte
+ * accounting silently breaks — switch to a parallel size map first.
+ */
 function createFrameSourceCache(
-  cacheLimit: number,
+  entryLimit: number,
+  bytesLimit: number,
   frameSrcResolver?: (framePath: string) => string | null,
-) {
+): FrameSourceCache {
   const cache = new Map<string, string>();
   const inFlight = new Map<string, Promise<string>>();
+  let totalBytes = 0;
+  let evictions = 0;
+  let oversizedRejections = 0;
+
+  function evictOldest(): void {
+    const oldestKey = cache.keys().next().value;
+    if (!oldestKey) return;
+    // Snapshot the value before deleting so the byte-size derivation can't
+    // accidentally read post-delete (a future reorder would silently lose
+    // accounting and surface as `totalBytes` drifting out of sync).
+    const dropped = cache.get(oldestKey);
+    cache.delete(oldestKey);
+    totalBytes = Math.max(0, totalBytes - (dropped?.length ?? 0));
+    evictions++;
+  }
 
   function remember(framePath: string, dataUri: string): string {
+    // Skip caching entries that alone exceed the byte budget. Caching them
+    // would trigger immediate self-eviction on insert and pollute LRU order
+    // by displacing the previous entry's slot.
+    if (dataUri.length > bytesLimit) {
+      oversizedRejections++;
+      // Drop any stale prior version so the caller sees consistent state.
+      if (cache.has(framePath)) {
+        totalBytes = Math.max(0, totalBytes - (cache.get(framePath)?.length ?? 0));
+        cache.delete(framePath);
+      }
+      return dataUri;
+    }
     if (cache.has(framePath)) {
+      totalBytes = Math.max(0, totalBytes - (cache.get(framePath)?.length ?? 0));
       cache.delete(framePath);
     }
     cache.set(framePath, dataUri);
-    if (cache.size > cacheLimit) {
-      const oldestKey = cache.keys().next().value;
-      if (oldestKey) {
-        cache.delete(oldestKey);
-      }
+    totalBytes += dataUri.length;
+    while ((cache.size > entryLimit || totalBytes > bytesLimit) && cache.size > 0) {
+      evictOldest();
     }
     return dataUri;
   }
@@ -70,9 +133,19 @@ function createFrameSourceCache(
     return pending;
   }
 
-  return { get };
+  return {
+    get,
+    stats: () => ({
+      entries: cache.size,
+      bytes: totalBytes,
+      evictions,
+      oversizedRejections,
+    }),
+  };
 }
 
+export const __testing = { createFrameSourceCache };
+
 /**
  * Creates a BeforeCaptureHook that injects pre-extracted video frames
  * into the page, replacing native <video> elements with frame images.
@@ -83,11 +156,16 @@ export function createVideoFrameInjector(
 ): BeforeCaptureHook | null {
   if (!frameLookup) return null;
 
-  const cacheLimit = Math.max(
+  const entryLimit = Math.max(
     32,
     config?.frameDataUriCacheLimit ?? DEFAULT_CONFIG.frameDataUriCacheLimit,
   );
-  const frameCache = createFrameSourceCache(cacheLimit, config?.frameSrcResolver);
+  const bytesLimitMb = Math.max(
+    64,
+    config?.frameDataUriCacheBytesLimitMb ?? DEFAULT_CONFIG.frameDataUriCacheBytesLimitMb,
+  );
+  const bytesLimit = bytesLimitMb * 1024 * 1024;
+  const frameCache = createFrameSourceCache(entryLimit, bytesLimit, config?.frameSrcResolver);
   const lastInjectedFrameByVideo = new Map<string, number>();
 
   return async (page: Page, time: number) => {

package/src/utils/alphaBlit.test.ts

@@ -511,6 +511,16 @@ describe("blitRgba8OverRgb48le", () => {
     expect(canvas.readUInt16LE(4)).toBe(0);
   });
 
+  it("fully opaque DOM with srgb transfer expands 8-bit channels to 16-bit SDR", () => {
+    const canvas = makeHdrFrame(1, 1, 10000, 20000, 30000);
+    const dom = makeDomRgba(1, 1, 255, 128, 1, 255);
+    blitRgba8OverRgb48le(dom, canvas, 1, 1, "srgb");
+
+    expect(canvas.readUInt16LE(0)).toBe(65535);
+    expect(canvas.readUInt16LE(2)).toBe(128 * 257);
+    expect(canvas.readUInt16LE(4)).toBe(257);
+  });
+
   it("sRGB→HLG: black stays black, white stays white", () => {
     const canvasBlack = makeHdrFrame(1, 1, 0, 0, 0);
     const domBlack = makeDomRgba(1, 1, 0, 0, 0, 255);

package/src/utils/alphaBlit.ts

@@ -249,7 +249,7 @@ export function decodePngToRgb48le(buf: Buffer): { width: number; height: number
  * bt2020). For neutral/near-neutral content (text, UI) the gamut difference
  * is negligible.
  */
-function buildSrgbToHdrLut(transfer: "hlg" | "pq"): Uint16Array {
+function buildSrgbToSignalLut(transfer: "hlg" | "pq" | "srgb"): Uint16Array {
   const lut = new Uint16Array(256);
 
   // HLG OETF constants (Rec. 2100)
@@ -267,6 +267,11 @@ function buildSrgbToHdrLut(transfer: "hlg" | "pq"): Uint16Array {
   const sdrNits = 203.0;
 
   for (let i = 0; i < 256; i++) {
+    if (transfer === "srgb") {
+      lut[i] = i * 257;
+      continue;
+    }
+
     // sRGB EOTF: signal → linear (range 0–1, relative to SDR white)
     const v = i / 255;
     const linear = v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
@@ -288,12 +293,15 @@ function buildSrgbToHdrLut(transfer: "hlg" | "pq"): Uint16Array {
   return lut;
 }
 
-const SRGB_TO_HLG = buildSrgbToHdrLut("hlg");
-const SRGB_TO_PQ = buildSrgbToHdrLut("pq");
+const SRGB_TO_SRGB_16 = buildSrgbToSignalLut("srgb");
+const SRGB_TO_HLG = buildSrgbToSignalLut("hlg");
+const SRGB_TO_PQ = buildSrgbToSignalLut("pq");
 
 /** Select the correct sRGB→HDR LUT for the given transfer function. */
-function getSrgbToHdrLut(transfer: "hlg" | "pq"): Uint16Array {
-  return transfer === "pq" ? SRGB_TO_PQ : SRGB_TO_HLG;
+function getSrgbToSignalLut(transfer: "hlg" | "pq" | "srgb"): Uint16Array {
+  if (transfer === "pq") return SRGB_TO_PQ;
+  if (transfer === "hlg") return SRGB_TO_HLG;
+  return SRGB_TO_SRGB_16;
 }
 
 // ── Alpha compositing ─────────────────────────────────────────────────────────
@@ -317,10 +325,10 @@ export function blitRgba8OverRgb48le(
   canvas: Buffer,
   width: number,
   height: number,
-  transfer: "hlg" | "pq" = "hlg",
+  transfer: "hlg" | "pq" | "srgb" = "hlg",
 ): void {
   const pixelCount = width * height;
-  const lut = getSrgbToHdrLut(transfer);
+  const lut = getSrgbToSignalLut(transfer);
 
   for (let i = 0; i < pixelCount; i++) {
     const da = domRgba[i * 4 + 3] ?? 0;

package/src/utils/ffprobe.test.ts

@@ -225,6 +225,46 @@ describe("ffprobe missing-binary fallback", () => {
     expect(meta.hasAlpha).toBe(true);
   });
 
+  // Regression: newer libavformat builds (and the output of `hyperframes
+  // remove-background` itself) write the VP9-alpha sidecar tag as
+  // `ALPHA_MODE` (uppercase). The lowercase-only check classified those
+  // files as having no alpha, the producer extracted them as JPGs, and
+  // the injected <img> overlays were fully opaque rectangles that hid
+  // every static element below them on the z-stack. The bug was silent —
+  // studio preview rendered correctly via native <video> playback while
+  // production renders covered headlines and captions with the avatar.
+  it("extractMediaMetadata detects ALPHA_MODE (uppercase) streams from newer ffmpeg builds", async () => {
+    const { spawn } = createSpawnSpy([
+      {
+        kind: "exit",
+        code: 0,
+        stdout: JSON.stringify({
+          streams: [
+            {
+              codec_type: "video",
+              codec_name: "vp9",
+              width: 320,
+              height: 180,
+              r_frame_rate: "30/1",
+              avg_frame_rate: "30/1",
+              pix_fmt: "yuv420p",
+              tags: { ALPHA_MODE: "1" },
+            },
+          ],
+          format: { duration: "1.5" },
+        }),
+      },
+    ]);
+    vi.resetModules();
+    vi.doMock("child_process", () => ({ spawn }));
+
+    const { extractMediaMetadata: extractMediaMetadataMocked } = await import("./ffprobe.js");
+    const meta = await extractMediaMetadataMocked("/tmp/alpha-uppercase.webm");
+
+    expect(meta.videoCodec).toBe("vp9");
+    expect(meta.hasAlpha).toBe(true);
+  });
+
   it("extractMediaMetadata rethrows ffprobe-missing error for non-image files without fallback", async () => {
     const { spawn } = createSpawnSpy([{ kind: "missing" }]);
     vi.resetModules();

package/src/utils/ffprobe.ts

@@ -203,6 +203,21 @@ function extractStillImageMetadata(filePath: string): StillImageMetadata | null
   }
 }
 
+/**
+ * Read an ffprobe tag case-insensitively. ffmpeg/libavformat versions disagree
+ * on tag casing — VP9 alpha is `alpha_mode` in older builds and `ALPHA_MODE`
+ * in newer ones; HDR tags vary similarly. Use this for any sidecar tag where
+ * you want to be resilient across muxer versions.
+ */
+function readTagCI(tags: Record<string, string | undefined> | undefined, name: string): string {
+  if (!tags) return "";
+  const target = name.toLowerCase();
+  for (const [key, value] of Object.entries(tags)) {
+    if (key.toLowerCase() === target && typeof value === "string") return value;
+  }
+  return "";
+}
+
 function parseFrameRate(frameRateStr: string | undefined): number {
   if (!frameRateStr) return 0;
   const parts = frameRateStr.split("/");
@@ -277,7 +292,7 @@ export async function extractMediaMetadata(filePath: string): Promise<VideoMetad
         : null;
     const colorSpace = ffprobeColorSpace ?? stillImageMeta?.colorSpace ?? null;
     const pixelFormat = videoStream.pix_fmt || "";
-    const alphaMode = videoStream.tags?.alpha_mode || "";
+    const alphaMode = readTagCI(videoStream.tags, "alpha_mode");
     const hasAlpha =
       /(^|[^a-z])yuva|rgba|argb|bgra|gbrap|gray[a-z0-9]*a/i.test(pixelFormat) || alphaMode === "1";