@hyperframes/engine 0.6.46 → 0.6.47

package/src/services/streamingEncoder.ts

@@ -231,14 +231,21 @@ export function buildStreamingArgs(
           if (bitrate) args.push("-b:v", bitrate);
           else args.push("-global_quality", String(quality));
           break;
+        case "amf":
+          if (bitrate) args.push("-b:v", bitrate);
+          else args.push("-rc", "cqp", "-qp_i", String(quality), "-qp_p", String(quality));
+          break;
       }
 
-      // Mirror SW branch: GPU h264 paths emit B-frames by default (nvenc, qsv,
-      // vaapi) and produce the same negative-DTS freeze for downstream players.
+      // Mirror SW branch: GPU h264 paths emit B-frames by default (nvenc, amf,
+      // qsv, vaapi) and produce the same negative-DTS freeze for downstream players.
       // See chunkEncoder.buildEncoderArgs for the full explanation.
       if (
         codec === "h264" &&
-        (gpuEncoder === "nvenc" || gpuEncoder === "qsv" || gpuEncoder === "vaapi")
+        (gpuEncoder === "nvenc" ||
+          gpuEncoder === "qsv" ||
+          gpuEncoder === "vaapi" ||
+          gpuEncoder === "amf")
       ) {
         args.push("-bf", "0");
         if (gpuEncoder === "qsv") {

package/src/services/videoFrameInjector.test.ts

@@ -1,9 +1,30 @@
 // @vitest-environment node
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, beforeEach, afterEach, vi } 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 { type Page } from "puppeteer-core";
+
+// Hoist mocks before importing the module under test so the mock factory wins.
+// The cache-hygiene block exercises createVideoFrameInjector against stubbed
+// page-side primitives so we can assert on Node-side state (cache poisoning)
+// without standing up a real browser.
+const { injectVideoFramesBatchMock, syncVideoFrameVisibilityMock } = vi.hoisted(() => ({
+  injectVideoFramesBatchMock: vi.fn<
+    (page: Page, updates: Array<{ videoId: string; dataUri: string }>) => Promise<string[]>
+  >(async (_page, updates) => updates.map((u) => u.videoId)),
+  syncVideoFrameVisibilityMock: vi.fn<(page: Page, ids: string[]) => Promise<void>>(
+    async () => undefined,
+  ),
+}));
+
+vi.mock("./screenshotService.js", () => ({
+  injectVideoFramesBatch: injectVideoFramesBatchMock,
+  syncVideoFrameVisibility: syncVideoFrameVisibilityMock,
+}));
+
+import { __testing, createVideoFrameInjector } from "./videoFrameInjector.js";
+import { type FrameLookupTable } from "./videoFrameExtractor.js";
 import { DEFAULT_CONFIG } from "../config.js";
 
 const { createFrameSourceCache } = __testing;
@@ -143,3 +164,91 @@ describe("frame source cache eviction", () => {
     expect(cache.stats()).toMatchObject({ ...SHARED_STATS, entries: 0, bytes: 0 });
   });
 });
+
+describe("createVideoFrameInjector cache hygiene against page-side skips", () => {
+  // Build a minimal FrameLookupTable stand-in that returns one fixed payload
+  // for every time so we can drive the hook deterministically. The real
+  // table is exercised exhaustively in videoFrameExtractor.test.ts.
+  function fakeTable(payload: { videoId: string; framePath: string; frameIndex: number }) {
+    return {
+      getActiveFramePayloads: () =>
+        new Map([
+          [payload.videoId, { framePath: payload.framePath, frameIndex: payload.frameIndex }],
+        ]),
+    } as unknown as FrameLookupTable;
+  }
+
+  // Bypass the on-disk frame cache by handing back a synthetic data URI.
+  function inlineResolver(framePath: string): string {
+    return `data:image/png;base64,fake-${framePath}`;
+  }
+
+  beforeEach(() => {
+    injectVideoFramesBatchMock.mockReset();
+    syncVideoFrameVisibilityMock.mockReset();
+    syncVideoFrameVisibilityMock.mockResolvedValue(undefined);
+  });
+
+  it("does not poison the lastInjected cache when the page reports zero ids injected", async () => {
+    // Regression for the agentic-finecut scenario after PR #1028's ancestor
+    // skip: when injectVideoFramesBatch silently drops a video (its sub-comp
+    // host is hidden), the caller used to record `lastInjectedFrame[v] = N`
+    // anyway. On the next frame, if the source frameIndex is unchanged
+    // (low-fps source, multiple output frames per source frame, or
+    // non-frame-aligned host start), the cache short-circuits the second
+    // call and the host's first visible frame paints blank because the
+    // replacement <img> was never created.
+    //
+    // Pin the contract: when the page returns `[]` (no ids actually
+    // injected), the cache must not record those frameIndexes, so a follow-
+    // up call at the same frameIndex still issues an inject.
+    const fakePage = {} as Page;
+    const hook = createVideoFrameInjector(
+      fakeTable({ videoId: "pip", framePath: "/p", frameIndex: 5 }),
+      {
+        frameSrcResolver: inlineResolver,
+      },
+    );
+    expect(hook).not.toBeNull();
+
+    // First call: simulate the ancestor-hidden skip — page-side reports it
+    // injected nothing.
+    injectVideoFramesBatchMock.mockResolvedValueOnce([]);
+    await hook!(fakePage, 0);
+    expect(injectVideoFramesBatchMock).toHaveBeenCalledTimes(1);
+    expect(injectVideoFramesBatchMock).toHaveBeenLastCalledWith(fakePage, [
+      { videoId: "pip", dataUri: "data:image/png;base64,fake-/p" },
+    ]);
+
+    // Second call: same frameIndex, but the previous call did not really
+    // paint. The cache must NOT short-circuit; the inject must run again.
+    injectVideoFramesBatchMock.mockResolvedValueOnce(["pip"]);
+    await hook!(fakePage, 0);
+    expect(injectVideoFramesBatchMock).toHaveBeenCalledTimes(2);
+    expect(injectVideoFramesBatchMock).toHaveBeenLastCalledWith(fakePage, [
+      { videoId: "pip", dataUri: "data:image/png;base64,fake-/p" },
+    ]);
+  });
+
+  it("does cache normally when the page reports the id as injected", async () => {
+    // Counter-test: when injection succeeds for a videoId, the cache must
+    // record it and a second call at the same frameIndex must short-circuit.
+    // This pins the happy path so a future refactor can't trade the skip
+    // bug for a never-cache regression.
+    const fakePage = {} as Page;
+    const hook = createVideoFrameInjector(
+      fakeTable({ videoId: "pip", framePath: "/p", frameIndex: 5 }),
+      {
+        frameSrcResolver: inlineResolver,
+      },
+    );
+
+    injectVideoFramesBatchMock.mockResolvedValueOnce(["pip"]);
+    await hook!(fakePage, 0);
+    expect(injectVideoFramesBatchMock).toHaveBeenCalledTimes(1);
+
+    await hook!(fakePage, 0);
+    // Cache hit — no second inject for the same frameIndex.
+    expect(injectVideoFramesBatchMock).toHaveBeenCalledTimes(1);
+  });
+});

package/src/services/videoFrameInjector.ts

@@ -197,12 +197,22 @@ export function createVideoFrameInjector(
 
     await syncVideoFrameVisibility(page, Array.from(activeIds));
     if (updates.length > 0) {
-      await injectVideoFramesBatch(
-        page,
-        updates.map((u) => ({ videoId: u.videoId, dataUri: u.dataUri })),
+      // Only record cache entries for videos the page actually painted.
+      // injectVideoFramesBatch skips any video whose visual ancestor is
+      // hidden (sub-comp host out-of-window) and returns the subset of ids
+      // it really wrote — recording the rest would short-circuit the next
+      // call at the same frameIndex and leave the host's first visible
+      // frame blank.
+      const injectedIds = new Set(
+        await injectVideoFramesBatch(
+          page,
+          updates.map((u) => ({ videoId: u.videoId, dataUri: u.dataUri })),
+        ),
       );
       for (const update of updates) {
-        lastInjectedFrameByVideo.set(update.videoId, update.frameIndex);
+        if (injectedIds.has(update.videoId)) {
+          lastInjectedFrameByVideo.set(update.videoId, update.frameIndex);
+        }
       }
     }
   };

package/src/utils/gpuEncoder.test.ts

@@ -1,6 +1,71 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 
-import { mapPresetForGpuEncoder } from "./gpuEncoder.js";
+import {
+  getCompiledGpuEncoders,
+  getGpuEncoderName,
+  mapPresetForGpuEncoder,
+  selectUsableGpuEncoder,
+} from "./gpuEncoder.js";
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("getCompiledGpuEncoders", () => {
+  it("recognizes AMD AMF in FFmpeg's encoder list", () => {
+    expect(
+      getCompiledGpuEncoders(`
+ V....D h264_nvenc           NVIDIA NVENC H.264 encoder
+ V....D h264_amf             AMD AMF H.264 Encoder
+ V....D h264_qsv             H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10 (Intel Quick Sync Video)
+`),
+    ).toEqual(["nvenc", "qsv", "amf"]);
+  });
+});
+
+describe("selectUsableGpuEncoder", () => {
+  it("runs probe checks concurrently while preserving candidate priority", async () => {
+    vi.useFakeTimers();
+    const started: string[] = [];
+    const usable = selectUsableGpuEncoder(["nvenc", "amf"], async (encoder) => {
+      started.push(encoder);
+      await new Promise((resolve) => setTimeout(resolve, encoder === "nvenc" ? 50 : 1));
+      return true;
+    });
+
+    await vi.advanceTimersByTimeAsync(1);
+    expect(started).toEqual(["nvenc", "amf"]);
+
+    await vi.advanceTimersByTimeAsync(49);
+    expect(await usable).toBe("nvenc");
+  });
+
+  it("falls through from compiled-but-unusable NVENC to usable AMD AMF", async () => {
+    const usable = await selectUsableGpuEncoder(["nvenc", "amf"], async (encoder) => {
+      return encoder === "amf";
+    });
+
+    expect(usable).toBe("amf");
+  });
+
+  it("treats rejected probe checks as unusable", async () => {
+    const usable = await selectUsableGpuEncoder(["nvenc", "amf"], async (encoder) => {
+      if (encoder === "nvenc") {
+        throw new Error("driver probe failed");
+      }
+      return encoder === "amf";
+    });
+
+    expect(usable).toBe("amf");
+  });
+});
+
+describe("getGpuEncoderName", () => {
+  it("maps AMD AMF to FFmpeg's h264 and hevc encoder names", () => {
+    expect(getGpuEncoderName("amf", "h264")).toBe("h264_amf");
+    expect(getGpuEncoderName("amf", "h265")).toBe("hevc_amf");
+  });
+});
 
 describe("mapPresetForGpuEncoder", () => {
   describe("nvenc", () => {
@@ -49,7 +114,7 @@ describe("mapPresetForGpuEncoder", () => {
   });
 
   describe("other encoders", () => {
-    it.each(["videotoolbox", "vaapi"] as const)(
+    it.each(["videotoolbox", "vaapi", "amf"] as const)(
       "passes preset through unchanged for %s",
       (encoder) => {
         expect(mapPresetForGpuEncoder(encoder, "medium")).toBe("medium");

package/src/utils/gpuEncoder.ts

@@ -7,7 +7,55 @@
 
 import { spawn } from "child_process";
 
-export type GpuEncoder = "nvenc" | "videotoolbox" | "vaapi" | "qsv" | null;
+export type ConcreteGpuEncoder = "nvenc" | "videotoolbox" | "vaapi" | "qsv" | "amf";
+export type GpuEncoder = ConcreteGpuEncoder | null;
+
+const GPU_ENCODER_CANDIDATES: ConcreteGpuEncoder[] = [
+  "nvenc",
+  "videotoolbox",
+  "vaapi",
+  "qsv",
+  "amf",
+];
+
+const H264_ENCODER_BY_GPU: Record<ConcreteGpuEncoder, string> = {
+  nvenc: "h264_nvenc",
+  videotoolbox: "h264_videotoolbox",
+  vaapi: "h264_vaapi",
+  qsv: "h264_qsv",
+  amf: "h264_amf",
+};
+
+const GPU_PROBE_TIMEOUT_MS = 2000;
+const GPU_PROBE_KILL_GRACE_MS = 1000;
+
+export function getCompiledGpuEncoders(ffmpegEncodersStdout: string): ConcreteGpuEncoder[] {
+  return GPU_ENCODER_CANDIDATES.filter((encoder) =>
+    ffmpegEncodersStdout.includes(H264_ENCODER_BY_GPU[encoder]),
+  );
+}
+
+export async function selectUsableGpuEncoder(
+  candidates: readonly ConcreteGpuEncoder[],
+  isUsable: (encoder: ConcreteGpuEncoder) => Promise<boolean>,
+): Promise<GpuEncoder> {
+  const results = await Promise.all(
+    candidates.map(async (encoder) => {
+      try {
+        return { encoder, usable: await isUsable(encoder) };
+      } catch {
+        return { encoder, usable: false };
+      }
+    }),
+  );
+
+  for (const result of results) {
+    if (result.usable) {
+      return result.encoder;
+    }
+  }
+  return null;
+}
 
 export async function detectGpuEncoder(): Promise<GpuEncoder> {
   return new Promise((resolve) => {
@@ -21,11 +69,10 @@ export async function detectGpuEncoder(): Promise<GpuEncoder> {
     });
 
     ffmpeg.on("close", () => {
-      if (stdout.includes("h264_nvenc")) resolve("nvenc");
-      else if (stdout.includes("h264_videotoolbox")) resolve("videotoolbox");
-      else if (stdout.includes("h264_vaapi")) resolve("vaapi");
-      else if (stdout.includes("h264_qsv")) resolve("qsv");
-      else resolve(null);
+      const candidates = getCompiledGpuEncoders(stdout);
+      void selectUsableGpuEncoder(candidates, canUseGpuEncoder)
+        .then(resolve)
+        .catch(() => resolve(null));
     });
 
     ffmpeg.on("error", () => resolve(null));
@@ -52,11 +99,111 @@ export function getGpuEncoderName(encoder: GpuEncoder, codec: "h264" | "h265"):
       return codec === "h264" ? "h264_vaapi" : "hevc_vaapi";
     case "qsv":
       return codec === "h264" ? "h264_qsv" : "hevc_qsv";
+    case "amf":
+      return codec === "h264" ? "h264_amf" : "hevc_amf";
     default:
       return codec === "h264" ? "libx264" : "libx265";
   }
 }
 
+function getProbeArgs(encoder: ConcreteGpuEncoder): string[] {
+  const args = [
+    "-hide_banner",
+    "-loglevel",
+    "error",
+    "-f",
+    "lavfi",
+    "-i",
+    "color=size=16x16:rate=1:duration=1",
+    "-frames:v",
+    "1",
+    "-an",
+  ];
+
+  if (encoder === "vaapi") {
+    args.push("-vaapi_device", "/dev/dri/renderD128", "-vf", "format=nv12,hwupload");
+  }
+
+  args.push("-c:v", getGpuEncoderName(encoder, "h264"));
+
+  if (encoder === "amf") {
+    args.push("-rc", "cqp", "-qp_i", "28", "-qp_p", "28");
+  }
+
+  args.push("-f", "null", "-");
+  return args;
+}
+
+async function canUseGpuEncoder(encoder: ConcreteGpuEncoder): Promise<boolean> {
+  return new Promise((resolve) => {
+    let settled = false;
+    let timedOut = false;
+    let killTimer: ReturnType<typeof setTimeout> | undefined;
+    let stderr = "";
+    const finish = (usable: boolean) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (killTimer) clearTimeout(killTimer);
+      resolve(usable);
+    };
+    const ffmpeg = spawn("ffmpeg", getProbeArgs(encoder), {
+      stdio: ["ignore", "ignore", "pipe"],
+    });
+
+    ffmpeg.stderr?.on("data", (data) => {
+      stderr += data.toString();
+    });
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      ffmpeg.kill("SIGTERM");
+      killTimer = setTimeout(() => {
+        ffmpeg.kill("SIGKILL");
+        finish(false);
+      }, GPU_PROBE_KILL_GRACE_MS);
+    }, GPU_PROBE_TIMEOUT_MS);
+
+    ffmpeg.on("close", (code, signal) => {
+      const usable = code === 0;
+      logGpuProbeFailure(encoder, { code, signal, stderr, timedOut });
+      finish(usable);
+    });
+
+    ffmpeg.on("error", (error) => {
+      logGpuProbeFailure(encoder, { error, timedOut });
+      finish(false);
+    });
+  });
+}
+
+function logGpuProbeFailure(
+  encoder: ConcreteGpuEncoder,
+  result: {
+    code?: number | null;
+    error?: Error;
+    signal?: NodeJS.Signals | null;
+    stderr?: string;
+    timedOut?: boolean;
+  },
+): void {
+  if (!isGpuProbeDebugEnabled()) return;
+  if (result.code === 0 && !result.error && !result.timedOut) return;
+
+  const reason = result.error
+    ? result.error.message
+    : result.timedOut
+      ? `timed out after ${GPU_PROBE_TIMEOUT_MS}ms`
+      : `exit=${String(result.code)} signal=${String(result.signal ?? "")}`;
+  const stderr = result.stderr?.trim();
+  console.warn(`[gpuEncoder] ${encoder} probe failed: ${reason}${stderr ? `\n${stderr}` : ""}`);
+}
+
+function isGpuProbeDebugEnabled(): boolean {
+  const value = process.env.HYPERFRAMES_DEBUG_GPU_PROBE;
+  return value === "1" || value === "true";
+}
+
 // libx264 preset names (ultrafast/superfast/.../placebo) mapped to the
 // equivalent NVENC p1..p7 preset. NVENC rejects libx264 names with
 // AVERROR(EINVAL) ("Error applying encoder options: Invalid argument"),
@@ -93,8 +240,8 @@ const QSV_PRESET_MAP: Record<string, string> = {
  *   through unchanged. Unknown values fall back to `p4` (medium).
  * - `qsv`:  `ultrafast`/`superfast`/`placebo` → nearest supported name;
  *   everything else passes through.
- * - `videotoolbox`, `vaapi`, `null`: no remap (they either ignore `-preset`
- *   entirely or accept the libx264 vocabulary).
+ * - `videotoolbox`, `vaapi`, `amf`, `null`: no remap (they either ignore
+ *   `-preset` entirely or accept the libx264 vocabulary).
  */
 export function mapPresetForGpuEncoder(encoder: GpuEncoder, preset: string): string {
   switch (encoder) {