milestone 6: add export-video ffmpeg baseline with snapshots

docs/phase1_knowledge.md

@@ -11,6 +11,7 @@ Implement executable, testable milestones of P17 without drifting from locked re
 - Analyze media inspector expanded from `PPM` to `PNG`, `JPEG`, `MP4`, and `MOV`.
 - Video probing baseline added with `ffprobe` (`width`, `height`, `aspect`, `orientation`, `codec`, `fps`).
 - Added `export-image` CLI baseline using `ffmpeg` with deterministic profile-driven output sizing.
+- Added `export-video` CLI baseline using `ffmpeg` with deterministic profile-driven output sizing (`MP4`/H.264 output).
 - Externalized rules in `config/ruleset.v1.json`.
 - White-canvas policy logic for feed profiles with workflow-gated `feed_app_direct` fallback.
 - Locked margin formula v1 and contain/no-crop invariant flags.
@@ -32,9 +33,10 @@ Implement executable, testable milestones of P17 without drifting from locked re
 - Introduced raster fixture generation (`ffmpeg`) and analyze e2e coverage for PNG/JPEG fixtures.
 - Added video fixture generation (`ffmpeg`) and analyze coverage for MP4/MOV fixtures.
 - Added export integration/e2e snapshot tests with fixture outputs in `tests/fixtures/exports`.
+- Added export-video integration/e2e snapshot tests and dedicated export-video snapshot fixtures.
 
 ## Deferred
 
 - Advanced video inspection fields (`bitrate`, `duration`, audio stream metadata, color metadata).
-- Video export/transcode profiles beyond image-frame export baseline.
+- Advanced video export/transcode policies (audio mapping, bitrate controls, codec variants beyond baseline MP4/H.264).
 - Empirical quality validation harness.

package.json

@@ -7,6 +7,7 @@
     "recommend": "bun run src/cli/recommend.ts",
     "analyze": "bun run src/cli/analyze.ts",
     "export-image": "bun run src/cli/export_image.ts",
+    "export-video": "bun run src/cli/export_video.ts",
     "test": "bun test",
     "test:unit": "bun test tests/recommend.test.ts tests/white_canvas.test.ts tests/media_inspector.test.ts tests/tier.test.ts",
     "test:integration": "bun test tests/integration",
@@ -20,6 +21,7 @@
     "fixtures:e2e": "bun run tests/fixtures/e2e/generate-snapshots.ts",
     "fixtures:e2e:analyze": "bun run tests/fixtures/e2e/generate-analyze-snapshots.ts",
     "fixtures:e2e:export": "bun run tests/fixtures/e2e/generate-export-snapshots.ts",
+    "fixtures:e2e:export-video": "bun run tests/fixtures/e2e/generate-export-video-snapshots.ts",
     "fixtures:visual": "bun run tests/fixtures/visual/generate-snapshots.ts",
     "fixtures:pixel": "bun run tests/fixtures/pixel/generate-snapshots.ts"
   },

src/cli/export_video.ts

@@ -0,0 +1,140 @@
+import type {
+  CanvasProfile,
+  ExportVideoInput,
+  Mode,
+  Surface,
+  Workflow,
+} from "../types/contracts";
+import { exportVideo } from "../domain/export_video";
+import { stableStringify } from "../domain/recommend";
+
+type ParsedArgs = ExportVideoInput & { json: boolean };
+
+function parseArgs(argv: string[]): ParsedArgs {
+  if (argv.length === 0 || argv[0]?.startsWith("--")) {
+    throw new Error("Missing required positional arg: <file>");
+  }
+
+  const file = argv[0]!;
+  let out: string | undefined;
+  let mode: Mode | undefined;
+  let surface: Surface | undefined;
+  let workflow: Workflow = "unknown";
+  let whiteCanvas = false;
+  let canvasProfile: CanvasProfile | undefined;
+  let crf: number | undefined;
+  let json = false;
+
+  for (let i = 1; i < argv.length; i += 1) {
+    const token = argv[i];
+    const next = argv[i + 1];
+
+    switch (token) {
+      case "--out":
+        if (!next || next.startsWith("--")) {
+          throw new Error("Missing value for --out");
+        }
+        out = next;
+        i += 1;
+        break;
+      case "--mode":
+        if (!next || next.startsWith("--")) {
+          throw new Error("Missing value for --mode");
+        }
+        mode = next as Mode;
+        i += 1;
+        break;
+      case "--surface":
+        if (!next || next.startsWith("--")) {
+          throw new Error("Missing value for --surface");
+        }
+        surface = next as Surface;
+        i += 1;
+        break;
+      case "--workflow":
+        if (!next || next.startsWith("--")) {
+          throw new Error("Missing value for --workflow");
+        }
+        workflow = next as Workflow;
+        i += 1;
+        break;
+      case "--white-canvas":
+        whiteCanvas = true;
+        break;
+      case "--canvas-profile":
+        if (!next || next.startsWith("--")) {
+          throw new Error("Missing value for --canvas-profile");
+        }
+        canvasProfile = next as CanvasProfile;
+        i += 1;
+        break;
+      case "--crf":
+        if (!next || next.startsWith("--")) {
+          throw new Error("Missing value for --crf");
+        }
+        crf = Number.parseInt(next ?? "", 10);
+        i += 1;
+        break;
+      case "--json":
+        json = true;
+        break;
+      default:
+        throw new Error(`Unknown argument: ${token}`);
+    }
+  }
+
+  if (!out || !mode || !surface) {
+    throw new Error("Missing required args: --out --mode --surface");
+  }
+
+  if (!["reliable", "experimental"].includes(mode)) {
+    throw new Error(`Invalid mode: ${mode}`);
+  }
+
+  if (!["feed", "story", "reel"].includes(surface)) {
+    throw new Error(`Invalid surface: ${surface}`);
+  }
+
+  if (!["app_direct", "api_scheduler", "unknown"].includes(workflow)) {
+    throw new Error(`Invalid workflow: ${workflow}`);
+  }
+
+  if (canvasProfile && !["feed_compat", "feed_app_direct"].includes(canvasProfile)) {
+    throw new Error(`Invalid canvas profile: ${canvasProfile}`);
+  }
+
+  if (crf !== undefined && (!Number.isFinite(crf) || crf < 0 || crf > 51)) {
+    throw new Error(`Invalid crf: ${crf}`);
+  }
+
+  return { file, out, mode, surface, workflow, whiteCanvas, canvasProfile, crf, json };
+}
+
+function printHumanOutput(result: ReturnType<typeof exportVideo>): void {
+  console.log(`Summary: exported ${result.input_path} -> ${result.output_path}`);
+  console.log(`Target: ${result.target_resolution}`);
+  console.log(`Profile: ${result.selected_profile}`);
+  console.log(`Video: codec=${result.video_codec} fps=${result.fps}`);
+  console.log(`White canvas: ${result.white_canvas_enabled ? "enabled" : "disabled"}`);
+  console.log("Next action: run with --json for machine-readable output.");
+}
+
+function main(): void {
+  try {
+    const parsed = parseArgs(process.argv.slice(2));
+    const result = exportVideo(parsed);
+
+    if (parsed.json) {
+      console.log(stableStringify(result));
+      return;
+    }
+
+    printHumanOutput(result);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Error: ${message}`);
+    process.exit(1);
+  }
+}
+
+main();

src/domain/export_video.ts

@@ -0,0 +1,115 @@
+import { mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import type { ExportVideoInput, ExportVideoOutput } from "../types/contracts";
+import { inspectMedia } from "./media_inspector";
+import { recommend } from "./recommend";
+import { parseResolution } from "./rules";
+
+function buildFilter(params: {
+  targetWidth: number;
+  targetHeight: number;
+  whiteCanvasEnabled: boolean;
+  margins: { left: number; top: number; right: number; bottom: number } | null;
+}): string {
+  const { targetWidth, targetHeight, whiteCanvasEnabled, margins } = params;
+
+  if (whiteCanvasEnabled && margins) {
+    const innerWidth = targetWidth - (margins.left + margins.right);
+    const innerHeight = targetHeight - (margins.top + margins.bottom);
+
+    if (innerWidth <= 0 || innerHeight <= 0) {
+      throw new Error("Invalid white-canvas margins: non-positive inner frame");
+    }
+
+    return [
+      `scale=${innerWidth}:${innerHeight}:force_original_aspect_ratio=decrease`,
+      `pad=${innerWidth}:${innerHeight}:(ow-iw)/2:(oh-ih)/2:white`,
+      `pad=${targetWidth}:${targetHeight}:${margins.left}:${margins.top}:white`,
+    ].join(",");
+  }
+
+  return [
+    `scale=${targetWidth}:${targetHeight}:force_original_aspect_ratio=increase`,
+    `crop=${targetWidth}:${targetHeight}`,
+  ].join(",");
+}
+
+export function exportVideo(input: ExportVideoInput): ExportVideoOutput {
+  const workflow = input.workflow ?? "unknown";
+  const crf = input.crf ?? 23;
+
+  const media = inspectMedia(input.file);
+  const recommendation = recommend({
+    mode: input.mode,
+    surface: input.surface,
+    orientation: media.orientation,
+    workflow,
+    whiteCanvas: input.whiteCanvas,
+    canvasProfile: input.canvasProfile,
+    sourceRatio: media.width / media.height,
+  });
+
+  const { width, height } = parseResolution(recommendation.target_resolution);
+  const filter = buildFilter({
+    targetWidth: width,
+    targetHeight: height,
+    whiteCanvasEnabled: recommendation.white_canvas.enabled,
+    margins: recommendation.white_canvas.margins,
+  });
+
+  const resolvedInputPath = resolve(input.file);
+  const resolvedOutputPath = resolve(input.out);
+  mkdirSync(dirname(resolvedOutputPath), { recursive: true });
+
+  const fps = media.fps > 0 ? media.fps : 30;
+  const proc = Bun.spawnSync({
+    cmd: [
+      "ffmpeg",
+      "-y",
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      "-i",
+      resolvedInputPath,
+      "-map",
+      "0:v:0",
+      "-map",
+      "0:a?",
+      "-vf",
+      filter,
+      "-r",
+      String(fps),
+      "-c:v",
+      "libx264",
+      "-c:a",
+      "aac",
+      "-crf",
+      String(crf),
+      "-pix_fmt",
+      "yuv420p",
+      "-movflags",
+      "+faststart",
+      resolvedOutputPath,
+    ],
+    stdout: "pipe",
+    stderr: "pipe",
+    timeout: 60_000,
+  });
+
+  if (proc.exitCode !== 0) {
+    throw new Error(
+      `ffmpeg video export failed (input: ${resolvedInputPath}, filter: ${filter}): ${proc.stderr.toString().trim()}`,
+    );
+  }
+
+  return {
+    input_path: input.file,
+    output_path: input.out,
+    selected_profile: recommendation.selected_profile,
+    target_resolution: recommendation.target_resolution,
+    white_canvas_enabled: recommendation.white_canvas.enabled,
+    ffmpeg_filter: filter,
+    video_codec: "h264",
+    fps,
+  };
+}

src/types/contracts.ts

@@ -136,3 +136,25 @@ export type ExportImageOutput = {
   white_canvas_enabled: boolean;
   ffmpeg_filter: string;
 };
+
+export type ExportVideoInput = {
+  file: string;
+  out: string;
+  mode: Mode;
+  surface: Surface;
+  workflow?: Workflow;
+  whiteCanvas?: boolean;
+  canvasProfile?: CanvasProfile;
+  crf?: number;
+};
+
+export type ExportVideoOutput = {
+  input_path: string;
+  output_path: string;
+  selected_profile: string;
+  target_resolution: Resolution;
+  white_canvas_enabled: boolean;
+  ffmpeg_filter: string;
+  video_codec: string;
+  fps: number;
+};

tests/e2e/export_video.snapshots.e2e.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseJsonStdout, runExportVideoCli } from "../helpers/cli";
+import type { ExportCase } from "../helpers/types";
+
+const fixtureDir = join(import.meta.dir, "..", "fixtures", "e2e");
+const snapshotDir = join(fixtureDir, "snapshots", "export_video");
+const cases = JSON.parse(readFileSync(join(fixtureDir, "export_video_cases.json"), "utf8")) as ExportCase[];
+
+function normalizeExportVideoPayload(payload: Record<string, unknown>): Record<string, unknown> {
+  const normalized = structuredClone(payload) as { input_path?: string; output_path?: string };
+  if (typeof normalized.input_path === "string" && normalized.input_path.startsWith("/")) {
+    normalized.input_path = normalized.input_path.replace(/^.*tests\/fixtures\//, "tests/fixtures/");
+  }
+  if (typeof normalized.output_path === "string" && normalized.output_path.startsWith("/")) {
+    normalized.output_path = normalized.output_path.replace(/^.*tests\/fixtures\//, "tests/fixtures/");
+  }
+  return normalized as Record<string, unknown>;
+}
+
+describe("export-video e2e snapshots", () => {
+  for (const scenario of cases) {
+    test(scenario.id, async () => {
+      const result = await runExportVideoCli(scenario.args);
+      expect(result.exitCode).toBe(0);
+      const expected = normalizeExportVideoPayload(
+        JSON.parse(readFileSync(join(snapshotDir, `${scenario.id}.json`), "utf8")) as Record<string, unknown>,
+      );
+      const actual = normalizeExportVideoPayload(parseJsonStdout(result.stdout, scenario.id));
+      expect(actual).toEqual(expected);
+    });
+  }
+});

tests/fixtures/e2e/export_video_cases.json

@@ -0,0 +1,14 @@
+[
+  {
+    "id": "export-video-reliable-reel-portrait",
+    "args": ["tests/fixtures/images/portrait_video_360x640.mp4", "--out", "tests/fixtures/exports/e2e_export_video_reliable_reel_portrait.mp4", "--mode", "reliable", "--surface", "reel", "--workflow", "unknown", "--json"]
+  },
+  {
+    "id": "export-video-reliable-feed-landscape-white",
+    "args": ["tests/fixtures/images/landscape_video_640x360.mov", "--out", "tests/fixtures/exports/e2e_export_video_reliable_feed_landscape_white.mp4", "--mode", "reliable", "--surface", "feed", "--workflow", "unknown", "--white-canvas", "--canvas-profile", "feed_compat", "--json"]
+  },
+  {
+    "id": "export-video-experimental-story",
+    "args": ["tests/fixtures/images/portrait_video_360x640.mp4", "--out", "tests/fixtures/exports/e2e_export_video_experimental_story.mp4", "--mode", "experimental", "--surface", "story", "--workflow", "unknown", "--json"]
+  }
+]