fix(video): improve local YouTube workflow (#74)

Author: caiopizzol

README.md

@@ -87,10 +87,10 @@ verifying the source, routing formats safely, covering animations, and reporting
 
 ### Media
 
-| Skill                                                                    | Type      | Purpose                                           |
-| ------------------------------------------------------------------------ | --------- | ------------------------------------------------- |
-| [`download-youtube-video`](skills/media/download-youtube-video/SKILL.md) | Focused   | Download one public video as an exact local file  |
-| [`summarize-youtube`](skills/media/summarize-youtube/SKILL.md)           | Composite | Summarize spoken and visual evidence from YouTube |
+| Skill                                                                    | Type      | Purpose                                              |
+| ------------------------------------------------------------------------ | --------- | ---------------------------------------------------- |
+| [`download-youtube-video`](skills/media/download-youtube-video/SKILL.md) | Focused   | Download one accessible video as an exact local file |
+| [`summarize-youtube`](skills/media/summarize-youtube/SKILL.md)           | Composite | Summarize spoken and visual evidence from YouTube    |
 
 ## Install
 

apps/video-tools-cli/src/arguments.ts

@@ -2,7 +2,10 @@ export interface PrepareArguments {
   command: "prepare";
   inputPath: string;
   artifactsDirectory?: string;
+  expectedSha256?: string;
+  only?: "audio" | "frames";
   frameCount?: number;
+  timestampsSeconds?: number[];
   maxFrames?: number;
   timeoutMs?: number;
   containerImage?: string;
@@ -22,7 +25,10 @@ export function parseArguments(argv: readonly string[]): CliArguments {
   }
 
   let artifactsDirectory: string | undefined;
+  let expectedSha256: string | undefined;
+  let only: "audio" | "frames" | undefined;
   let frameCount: number | undefined;
+  const timestampsSeconds: number[] = [];
   let maxFrames: number | undefined;
   let timeoutMs: number | undefined;
   let containerImage: string | undefined;
@@ -34,12 +40,21 @@ export function parseArguments(argv: readonly string[]): CliArguments {
       case "--artifacts-dir":
         artifactsDirectory = value;
         break;
+      case "--expected-sha256":
+        expectedSha256 = sha256(value, option);
+        break;
+      case "--only":
+        only = mediaLane(value);
+        break;
       case "--max-frames":
         maxFrames = positiveInteger(value, option);
         break;
       case "--frame-count":
         frameCount = positiveInteger(value, option);
         break;
+      case "--frame-time":
+        timestampsSeconds.push(nonNegativeNumber(value, option));
+        break;
       case "--timeout-ms":
         timeoutMs = positiveInteger(value, option);
         break;
@@ -51,12 +66,24 @@ export function parseArguments(argv: readonly string[]): CliArguments {
     }
     index += 1;
   }
+  if (frameCount !== undefined && timestampsSeconds.length > 0) {
+    throw new Error("--frame-count and --frame-time cannot be used together");
+  }
+  if (
+    only === "audio" &&
+    (frameCount !== undefined || timestampsSeconds.length > 0 || maxFrames !== undefined)
+  ) {
+    throw new Error("frame options cannot be used with --only audio");
+  }
 
   return {
     command: "prepare",
     inputPath,
     ...(artifactsDirectory === undefined ? {} : { artifactsDirectory }),
+    ...(expectedSha256 === undefined ? {} : { expectedSha256 }),
+    ...(only === undefined ? {} : { only }),
     ...(frameCount === undefined ? {} : { frameCount }),
+    ...(timestampsSeconds.length === 0 ? {} : { timestampsSeconds }),
     ...(maxFrames === undefined ? {} : { maxFrames }),
     ...(timeoutMs === undefined ? {} : { timeoutMs }),
     ...(containerImage === undefined ? {} : { containerImage }),
@@ -78,3 +105,22 @@ function positiveInteger(value: string, option: string): number {
     throw new Error(`${option} requires a positive integer`);
   return parsed;
 }
+
+function nonNegativeNumber(value: string, option: string): number {
+  if (value.trim() === "") throw new Error(`${option} requires a non-negative number`);
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0)
+    throw new Error(`${option} requires a non-negative number`);
+  return parsed;
+}
+
+function sha256(value: string, option: string): string {
+  if (!/^[a-f0-9]{64}$/i.test(value))
+    throw new Error(`${option} requires 64 hexadecimal characters`);
+  return value.toLowerCase();
+}
+
+function mediaLane(value: string): "audio" | "frames" {
+  if (value !== "audio" && value !== "frames") throw new Error("--only requires audio or frames");
+  return value;
+}

apps/video-tools-cli/src/cli.ts

@@ -3,11 +3,15 @@ import { parseArguments } from "./arguments.ts";
 import { isComplete, prepareVideo } from "./prepare-video.ts";
 
 const usage = `Usage:
-  video-tools prepare <video-path> [--artifacts-dir <directory>] [--frame-count <count>] [--max-frames <count>] [--timeout-ms <milliseconds>] [--container-image <name@sha256:digest>]
+  video-tools prepare <video-path> [--artifacts-dir <directory>] [--expected-sha256 <sha256>] [--only <audio|frames>] [--frame-count <count> | --frame-time <seconds>...] [--max-frames <count>] [--timeout-ms <milliseconds>] [--container-image <name@sha256:digest>]
 
 When --artifacts-dir is omitted, the command creates an isolated temporary directory and reports
 its location in the JSON result. Temporary derivatives are retained for the caller to inspect.
 
+Repeat --frame-time to extract exact moments. Do not combine it with --frame-count.
+Use --only when the other media lane is not needed.
+Pass --expected-sha256 to prove a later pass reads the same source bytes.
+
 --timeout-ms bounds each tool invocation, not the total run. A preparation that runs several
 stages may therefore exceed it in aggregate.
 

apps/video-tools-cli/src/prepare-video.ts

@@ -76,6 +76,21 @@ export async function prepareVideo(
     audio: null,
     inputChanged: null,
   };
+  if (args.expectedSha256 !== undefined && args.expectedSha256 !== identity.sha256) {
+    return {
+      ...empty,
+      capability: null,
+      capabilityGap: null,
+      inputChanged: {
+        outcome: "input-changed",
+        inputPath,
+        message:
+          "the original file no longer matches the expected SHA-256, so no derivatives were created",
+        initialSha256: args.expectedSha256,
+        finalSha256: identity.sha256,
+      },
+    };
+  }
 
   let exec = options.hostExec ?? execWithBun;
   let image: ContainerIdentity | undefined;
@@ -131,29 +146,37 @@ export async function prepareVideo(
   if (probe.outcome !== "ok") return { ...empty, capability, capabilityGap: null, probe };
 
   const written: string[] = [];
-  const frames = await extractFrames({
-    inputPath,
-    parentSha256: identity.sha256,
-    artifactsDirectory,
-    durationSeconds: probe.probe.durationSeconds,
-    ...(args.frameCount === undefined ? {} : { frameCount: args.frameCount }),
-    cwd,
-    exec,
-    ...(args.maxFrames === undefined ? {} : { maxFrames: args.maxFrames }),
-    ...(args.timeoutMs === undefined ? {} : { timeoutMs: args.timeoutMs }),
-  });
-  if (frames.outcome === "ok") written.push(...frames.frames.map((frame) => frame.derivative.path));
-  const audio = probe.probe.hasAudioStream
-    ? await extractAudio({
-        inputPath,
-        parentSha256: identity.sha256,
-        artifactsDirectory,
-        probe: probe.probe,
-        cwd,
-        exec,
-        ...(args.timeoutMs === undefined ? {} : { timeoutMs: args.timeoutMs }),
-      })
-    : null;
+  const frames =
+    args.only === "audio"
+      ? null
+      : await extractFrames({
+          inputPath,
+          parentSha256: identity.sha256,
+          artifactsDirectory,
+          durationSeconds: probe.probe.durationSeconds,
+          ...(args.frameCount === undefined ? {} : { frameCount: args.frameCount }),
+          ...(args.timestampsSeconds === undefined
+            ? {}
+            : { timestampsSeconds: args.timestampsSeconds }),
+          cwd,
+          exec,
+          ...(args.maxFrames === undefined ? {} : { maxFrames: args.maxFrames }),
+          ...(args.timeoutMs === undefined ? {} : { timeoutMs: args.timeoutMs }),
+        });
+  if (frames?.outcome === "ok")
+    written.push(...frames.frames.map((frame) => frame.derivative.path));
+  const audio =
+    args.only !== "frames" && probe.probe.hasAudioStream
+      ? await extractAudio({
+          inputPath,
+          parentSha256: identity.sha256,
+          artifactsDirectory,
+          probe: probe.probe,
+          cwd,
+          exec,
+          ...(args.timeoutMs === undefined ? {} : { timeoutMs: args.timeoutMs }),
+        })
+      : null;
   if (audio?.outcome === "ok") written.push(audio.derivative.path);
 
   const inputChanged = await detectInputChange({ identity, writtenPaths: written });
@@ -173,9 +196,11 @@ export async function prepareVideo(
 
 export function isComplete(result: PrepareVideoResult): boolean {
   if (result.capabilityGap !== null || result.inputChanged !== null) return false;
-  if (result.probe?.outcome !== "ok" || result.frames?.outcome !== "ok") return false;
-  if (!result.probe.probe.hasAudioStream) return true;
-  if (result.audio?.outcome !== "ok") return false;
+  if (result.probe?.outcome !== "ok") return false;
+  if (result.frames !== null && result.frames.outcome !== "ok") return false;
+  if (result.audio !== null && result.audio.outcome !== "ok") return false;
+  if (result.frames === null && result.audio === null) return !result.probe.probe.hasAudioStream;
+  if (result.audio === null) return true;
   // A source with several audio streams is not fully read after one of them. Reporting complete
   // coverage here is the same overclaim the frame lane already refuses to make.
   return result.audio.selection.omittedStreamIndexes.length === 0;

apps/video-tools-cli/tests/arguments.test.ts

@@ -37,6 +37,62 @@ describe("parseArguments", () => {
       inputPath: "fixture.mp4",
     });
   });
+
+  it("parses an audio-only preparation", () => {
+    expect(
+      parseArguments([
+        "prepare",
+        "fixture.mp4",
+        "--expected-sha256",
+        digest.toUpperCase(),
+        "--only",
+        "audio",
+      ]),
+    ).toEqual({
+      command: "prepare",
+      inputPath: "fixture.mp4",
+      expectedSha256: digest,
+      only: "audio",
+    });
+  });
+
+  it("parses exact frame times", () => {
+    expect(
+      parseArguments([
+        "prepare",
+        "fixture.mp4",
+        "--only",
+        "frames",
+        "--frame-time",
+        "0",
+        "--frame-time",
+        "12.5",
+      ]),
+    ).toEqual({
+      command: "prepare",
+      inputPath: "fixture.mp4",
+      only: "frames",
+      timestampsSeconds: [0, 12.5],
+    });
+  });
+
+  it("refuses ambiguous and invalid frame times", () => {
+    expect(() =>
+      parseArguments(["prepare", "fixture.mp4", "--frame-count", "3", "--frame-time", "1"]),
+    ).toThrow("cannot be used together");
+    expect(() => parseArguments(["prepare", "fixture.mp4", "--frame-time", "-1"])).toThrow(
+      "non-negative number",
+    );
+    expect(() => parseArguments(["prepare", "fixture.mp4", "--frame-time", " "])).toThrow(
+      "non-negative number",
+    );
+    expect(() =>
+      parseArguments(["prepare", "fixture.mp4", "--only", "audio", "--frame-time", "1"]),
+    ).toThrow("frame options");
+    expect(() =>
+      parseArguments(["prepare", "fixture.mp4", "--expected-sha256", "not-a-hash"]),
+    ).toThrow("64 hexadecimal characters");
+  });
 });
 
 describe("parsePinnedImage", () => {

apps/video-tools-cli/tests/prepare-video.test.ts

@@ -44,6 +44,28 @@ function missing(command: string): Error {
 }
 
 describe("prepareVideo capability reporting", () => {
+  it("extracts frames at exact times", async () => {
+    const directory = await temporaryDirectory();
+    const inputPath = join(directory, "clip.mp4");
+    await writeFile(inputPath, "video bytes");
+
+    const result = await prepareVideo(
+      {
+        command: "prepare",
+        inputPath,
+        artifactsDirectory: join(directory, "artifacts"),
+        only: "frames",
+        timestampsSeconds: [3, 1],
+      },
+      { cwd: directory, hostExec: workingExec() },
+    );
+
+    if (result.frames?.outcome !== "ok") throw new Error("expected prepared frames");
+    expect(result.frames.sampling.timestampsSeconds).toEqual([1, 3]);
+    expect(result.audio).toBeNull();
+    expect(isComplete(result)).toBe(true);
+  });
+
   it("creates and reports a temporary artifacts directory when the caller omits one", async () => {
     const directory = await temporaryDirectory();
     const inputPath = join(directory, "clip.mp4");
@@ -217,7 +239,12 @@ describe("prepareVideo audio coverage", () => {
     });
 
     const result = await prepareVideo(
-      { command: "prepare", inputPath, artifactsDirectory: join(directory, "artifacts") },
+      {
+        command: "prepare",
+        inputPath,
+        artifactsDirectory: join(directory, "artifacts"),
+        only: "audio",
+      },
       {
         cwd: directory,
         hostExec: async (request) => {
@@ -233,12 +260,54 @@ describe("prepareVideo audio coverage", () => {
     );
 
     if (result.audio?.outcome !== "ok") throw new Error("expected an extracted audio lane");
+    expect(result.frames).toBeNull();
     expect(result.audio.selection.omittedStreamIndexes).toEqual([]);
     expect(isComplete(result)).toBe(true);
   });
 });
 
 describe("prepareVideo source identity", () => {
+  it("stops before tooling when the source changes between passes", async () => {
+    const directory = await temporaryDirectory();
+    const inputPath = join(directory, "clip.mp4");
+    const artifactsDirectory = join(directory, "artifacts");
+    await writeFile(inputPath, "first video bytes");
+    const first = await prepareVideo(
+      { command: "prepare", inputPath, artifactsDirectory, only: "audio" },
+      { cwd: directory, hostExec: workingExec() },
+    );
+    await writeFile(inputPath, "different video bytes");
+    let called = false;
+
+    const second = await prepareVideo(
+      {
+        command: "prepare",
+        inputPath,
+        artifactsDirectory,
+        expectedSha256: first.file.sha256,
+        only: "frames",
+        timestampsSeconds: [1],
+      },
+      {
+        cwd: directory,
+        hostExec: async () => {
+          called = true;
+          return { exitCode: 0, stdout: "", stderr: "" };
+        },
+      },
+    );
+
+    expect(second.inputChanged).toMatchObject({
+      outcome: "input-changed",
+      initialSha256: first.file.sha256,
+      finalSha256: second.file.sha256,
+    });
+    expect(second.frames).toBeNull();
+    expect(second.audio).toBeNull();
+    expect(called).toBe(false);
+    expect(isComplete(second)).toBe(false);
+  });
+
   it("discards every derivative and reports input-changed when the original moved underneath it", async () => {
     const directory = await temporaryDirectory();
     const inputPath = join(directory, "clip.mp4");