@hypit/hypit 0.2.6 → 0.2.7

package/packages/video-cli/src/snapshot.ts

@@ -0,0 +1,186 @@
+import { createReadStream, createWriteStream } from "node:fs";
+import { mkdir, mkdtemp, readFile, rename, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, extname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { Readable } from "node:stream";
+import type { ReadableStream as NodeReadableStream } from "node:stream/web";
+import { pipeline } from "node:stream/promises";
+import type { CliIo } from "@hypit/cli";
+import { assertHyperframesDocument, hyperframesHtmlAssetUrls, hyperframesHtmlDomain } from "@hypit/hyperframes";
+import type { HyperframesDocument, HyperframesHtmlProject } from "@hypit/hyperframes";
+import { FileResourceStore } from "@hypit/resource-store-fs";
+import { hyperframesFramesRequest, renderHyperframesCapabilities, renderHyperframesTypes, verifyHyperframesFrames } from "@hypit/render-hyperframes";
+import type { Need } from "@hypit/protocol";
+import { creationEnvironment, selectedProvider, providerLine, providerView } from "./creation.js";
+import type { CreationEnvironment } from "./creation.js";
+import { snapshotFrameLabel, writeFrameGrid } from "./frame-grid.js";
+
+const MEDIA_TYPES: Readonly<Record<string, string>> = {
+  ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp",
+  ".mp4": "video/mp4", ".webm": "video/webm", ".woff": "font/woff", ".woff2": "font/woff2", ".ttf": "font/ttf", ".otf": "font/otf",
+};
+
+async function readProject(source: string, html: string, resources: FileResourceStore): Promise<HyperframesHtmlProject> {
+  const assets = [];
+  const base = /^https?:/u.test(source) ? new URL(source) : pathToFileURL(source);
+  for (const url of hyperframesHtmlAssetUrls(html)) {
+    const address = new URL(url, base);
+    let mediaType: string | undefined;
+    let stream: Readable;
+    if (address.protocol === "file:") {
+      if (base.protocol !== "file:") throw new Error(`Network HTML cannot read local asset ${url}`);
+      const path = fileURLToPath(address);
+      mediaType = MEDIA_TYPES[extname(path).toLowerCase()];
+      if (mediaType === undefined) throw new Error(`Unsupported snapshot asset ${url}; use compiled HTML with inline scripts and styles`);
+      stream = createReadStream(path);
+    } else if (address.protocol === "http:" || address.protocol === "https:") {
+      const response = await fetch(address);
+      if (!response.ok || response.body === null) throw new Error(`Snapshot asset ${url}: HTTP ${response.status}`);
+      mediaType = response.headers.get("content-type")?.split(";")[0]?.trim();
+      if (mediaType === undefined || !Object.values(MEDIA_TYPES).includes(mediaType)) {
+        await response.body.cancel();
+        throw new Error(`Unsupported snapshot asset ${url} (${mediaType}); use compiled HTML with inline scripts and styles`);
+      }
+      stream = Readable.fromWeb(response.body as NodeReadableStream<Uint8Array>);
+    } else throw new Error(`Unsupported snapshot asset protocol ${address.protocol}`);
+    try { assets.push({ url, artifact: await resources.putStream(stream, mediaType) }); }
+    finally { stream.destroy(); }
+  }
+  return { html, assets };
+}
+
+const OPTIONS = ["--studio", "--to", "--at-frame", "--start-frame", "--end-frame-exclusive", "--step-frames", "--grid", "--cell", "--runtime", "--workspace"];
+
+export function writeSnapshotHelp(io: CliIo): void {
+  io.write(`hypit snapshot\nCapture exact frames from an existing compiled HyperFrames HTML programme through the selected Runtime Profile.\n\n`
+    + `  hypit snapshot --studio <studio-url> --at-frame <n[,n,…]> --to <directory>\n`
+    + `  hypit snapshot <index.html|HTML-URL> --at-frame <n[,n,…]> --to <directory>\n`
+    + `  hypit snapshot <index.html|HTML-URL> --start-frame <n> --end-frame-exclusive <n> [--step-frames <n>] --to <directory>\n`
+    + `      [--grid <columns>x<rows>] [--cell <pixels>] [--runtime <profile>] [--workspace <project>] [--json]\n\n`
+    + `Frame indices are zero-based on the original programme clock. Ranges exclude the end.\n`
+    + `Writes full-size PNGs and optional paginated grids. --cell controls grid image width (default 480).\n`
+    + `Uses render-frames, one immediate request. Browser preparation belongs to the selected Provider.\n`
+    + `HTML carries the compiled frame clock and media/font URLs; scripts and styles are inline.\nStudio exposes its current programme at http://<host>:<port>/__studio/visual.html.\n`);
+}
+
+export async function runSnapshotCli(argv: readonly string[], io: CliIo, environment: CreationEnvironment = creationEnvironment()): Promise<void> {
+  if (argv.includes("--help")) { writeSnapshotHelp(io); return; }
+  const options = new Map<string, string>();
+  const positionals = [];
+  const json = argv.includes("--json");
+  for (let index = 1; index < argv.length; index++) {
+    const arg = argv[index]!;
+    if (["--json", "--debug", "--verbose", "--no-color"].includes(arg)) continue;
+    if (arg === "--color") { index++; continue; }
+    if (!arg.startsWith("--")) { positionals.push(arg); continue; }
+    if (!OPTIONS.includes(arg)) throw new Error(`Unknown snapshot option ${arg}`);
+    if (options.has(arg)) throw new Error(`${arg} cannot be repeated`);
+    const value = argv[++index];
+    if (!value || value.startsWith("--")) throw new Error(`${arg} requires a value`);
+    options.set(arg, value);
+  }
+  const studio = options.get("--studio");
+  if (positionals.length !== (studio === undefined ? 1 : 0) || !options.has("--to")) throw new Error("snapshot takes one HTML input or --studio <url>, and --to <directory>");
+  const integer = (raw: string | undefined, label: string, minimum = 0): number => {
+    if (raw === undefined || !/^\d+$/u.test(raw) || !Number.isSafeInteger(Number(raw)) || Number(raw) < minimum) throw new Error(`${label} needs an integer >= ${minimum}`);
+    return Number(raw);
+  };
+  const source = studio === undefined
+    ? /^https?:\/\//u.test(positionals[0]!) ? positionals[0]! : resolve(environment.cwd, positionals[0]!)
+    : new URL("/__studio/document", studio).href;
+  let document: HyperframesDocument | undefined;
+  let html: string;
+  if (studio !== undefined) {
+    const response = await fetch(source);
+    if (!response.ok) throw new Error(`Studio programme: HTTP ${response.status} ${await response.text()}`);
+    document = await response.json() as HyperframesDocument;
+    assertHyperframesDocument(document);
+    html = document.html;
+  } else if (/^https?:/u.test(source)) {
+    const response = await fetch(source);
+    if (!response.ok) throw new Error(`Snapshot HTML: HTTP ${response.status} ${await response.text()}`);
+    html = await response.text();
+  } else html = await readFile(source, "utf8");
+  const domain = document ?? hyperframesHtmlDomain(html);
+  const explicit = options.get("--at-frame");
+  let frames: number[];
+  if (explicit !== undefined) {
+    if (["--start-frame", "--end-frame-exclusive", "--step-frames"].some(key => options.has(key))) throw new Error("Choose --at-frame or a frame range");
+    frames = explicit.split(",").map(value => integer(value, "--at-frame"));
+  } else {
+    const start = integer(options.get("--start-frame"), "--start-frame");
+    const end = integer(options.get("--end-frame-exclusive"), "--end-frame-exclusive");
+    const step = integer(options.get("--step-frames") ?? "1", "--step-frames", 1);
+    if (end <= start || end > domain.frameCount) throw new Error(`The frame range must satisfy 0 <= start < end <= ${domain.frameCount}`);
+    frames = Array.from({ length: Math.ceil((end - start) / step) }, (_, index) => start + index * step);
+  }
+  const grid = options.get("--grid")?.split("x");
+  if (grid !== undefined && grid.length !== 2) throw new Error("--grid needs columns x rows, for example 4x3");
+  const columns = grid === undefined ? undefined : integer(grid[0], "grid columns", 1);
+  const rows = grid === undefined ? undefined : integer(grid[1], "grid rows", 1);
+  if (options.has("--cell") && grid === undefined) throw new Error("--cell requires --grid");
+  const cell = integer(options.get("--cell") ?? "480", "--cell", 32);
+  const to = resolve(environment.cwd, options.get("--to")!);
+  if (await stat(to).then(() => true, () => false)) throw new Error(`Destination ${to} already exists`);
+  const temporary = await mkdtemp(join(tmpdir(), "hypit-snapshot-"));
+  let staging: string | undefined;
+  try {
+    const resources = new FileResourceStore(temporary);
+    let input: { document: HyperframesDocument } | { project: HyperframesHtmlProject };
+    if (document !== undefined) {
+      for (const artifact of document.artifacts) {
+        const response = await fetch(new URL(`/__studio/material/${artifact.resource}`, studio));
+        if (!response.ok || response.body === null) throw new Error(`Studio material ${artifact.resource}: HTTP ${response.status}`);
+        const stream = Readable.fromWeb(response.body as NodeReadableStream<Uint8Array>);
+        try { await resources.writeStream(artifact, stream); }
+        finally { stream.destroy(); }
+      }
+      input = { document };
+    } else input = { project: await readProject(source, html, resources) };
+    const need: Need = { id: "need:hypit-snapshot", capability: renderHyperframesCapabilities.renderFrames,
+      returns: renderHyperframesTypes.frames, result: "record:hypit-snapshot", constraints: hyperframesFramesRequest({ ...input, frames }) };
+    const { host, profile } = await environment.openHost(options.get("--runtime"), options.get("--workspace"));
+    const provider = await selectedProvider(host, need, profile);
+    if (!json) io.write(`Capturing ${frames.length} frames through ${providerLine(provider)}\n`);
+    const report = json ? io.writeProgress : io.writeProgress ?? io.write;
+    const fulfilled = await host.invoke(need, resources, {
+      reportProgress: async progress => { report?.(`  · ${progress.phase}\n`); },
+      reportDiagnostic: async diagnostic => { report?.(`  · ${diagnostic.message}\n`); },
+    });
+    if (fulfilled.value.kind !== "inline") throw new Error("The frame list came back by reference");
+    verifyHyperframesFrames(fulfilled.value.value);
+    const images = fulfilled.value.value;
+    if (images.length !== frames.length) throw new Error(`Requested ${frames.length} frames, received ${images.length}`);
+    await mkdir(dirname(to), { recursive: true });
+    staging = await mkdtemp(join(dirname(to), ".hypit-snapshot-"));
+    const files = [];
+    for (const [index, image] of images.entries()) {
+      const frame = frames[index]!;
+      const name = `frame-${String(frame).padStart(9, "0")}.png`;
+      const stream = await resources.open(image.resource);
+      if (stream === undefined) throw new Error(`Snapshot frame ${frame} is unavailable`);
+      await pipeline(stream, createWriteStream(join(staging, name), { flags: "wx" }));
+      files.push({ frame, seconds: frame * domain.frameRate.denominator / domain.frameRate.numerator, path: join(to, name) });
+    }
+    const grids: string[] = [];
+    if (columns !== undefined && rows !== undefined) {
+      const count = columns * rows;
+      for (let offset = 0; offset < files.length; offset += count) {
+        const page = [];
+        for (const file of files.slice(offset, offset + count)) page.push({ path: join(staging, `frame-${String(file.frame).padStart(9, "0")}.png`),
+          label: await snapshotFrameLabel(file.frame, file.seconds, cell) });
+        const name = `grid-${String(grids.length + 1).padStart(3, "0")}.jpg`;
+        await writeFrameGrid(page, join(staging, name), cell, columns);
+        grids.push(join(to, name));
+      }
+    }
+    await rename(staging, to);
+    staging = undefined;
+    if (json) io.write(`${JSON.stringify({ format: "hypit.video-cli-snapshot@1", source, ...providerView(provider), frames: files, grids }, null, 2)}\n`);
+    else io.write(`Captured ${files.length} PNGs${grids.length === 0 ? "" : ` and ${grids.length} grid${grids.length === 1 ? "" : "s"}`}\n  ${to}\n`);
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+    if (staging !== undefined) await rm(staging, { recursive: true, force: true });
+  }
+}

package/packages/yt-dlp/src/download.ts

@@ -10,13 +10,22 @@
  * keep changing, so an unpinned copy makes the same link fetch differently on two machines. This is
  * the same shape WhisperX and OpenCV already use for their Python programs.
  */
-import { spawnSync } from "node:child_process";
+import { execFile } from "node:child_process";
 import { copyFile, mkdtemp, readdir, rename, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { extname, join } from "node:path";
 
 import { requireVideoDownload } from "./environment.js";
 
+function runExec(file: string, args: readonly string[], options: { readonly timeout?: number; readonly maxBuffer?: number; readonly signal?: AbortSignal | undefined } = {}): Promise<{ readonly stdout: string; readonly stderr: string }> {
+  return new Promise((resolve, reject) => {
+    execFile(file, [...args], { encoding: "utf8", windowsHide: true, ...options }, (error, stdout, stderr) => {
+      if (error !== null) reject(Object.assign(error, { stdout, stderr }));
+      else resolve({ stdout: String(stdout), stderr: String(stderr) });
+    });
+  });
+}
+
 /**
  * Whether this is a link to fetch rather than a path to open.
  *
@@ -42,30 +51,35 @@ export function isVideoUrl(value: string): boolean {
  * nothing under the bound. `--no-playlist` keeps a link inside a playlist from fetching the playlist.
  * The container follows the target's extension.
  */
-export async function downloadVideo(url: string, target: string): Promise<void> {
+export async function downloadVideo(url: string, target: string, options: { readonly signal?: AbortSignal } = {}): Promise<void> {
   const container = extname(target).slice(1).toLowerCase();
   if (!["mp4", "mkv", "webm", "mov"].includes(container)) {
     throw new Error(`${target} must end in .mp4, .mkv, .webm or .mov`);
   }
   const executable = requireVideoDownload();
-  const media = spawnSync("ffmpeg", ["-version"], { encoding: "utf8", windowsHide: true, timeout: 15_000 });
-  if (media.status !== 0) throw new Error("FFmpeg is unavailable on PATH; install your selected media toolchain before fetching video");
+  try {
+    await runExec("ffmpeg", ["-version"], { timeout: 15_000, signal: options.signal });
+  } catch (error) {
+    if (options.signal?.aborted) throw error;
+    throw new Error("FFmpeg is unavailable on PATH; install your selected media toolchain before fetching video");
+  }
   const work = await mkdtemp(join(tmpdir(), "hypit-fetch-"));
   try {
-    const result = spawnSync(executable, [
-      "--ignore-config", "--no-update", "--no-remote-components", "--no-plugin-dirs",
-      "--no-js-runtimes", "--js-runtimes", `node:${process.execPath}`,
-      "--no-playlist", "--no-progress", "--quiet",
-      "--format", "bv*+ba/b",
-      "--merge-output-format", container,
-      "--format-sort", "res:1080,vcodec:h264",
-      "--output", join(work, "video.%(ext)s"),
-      url,
-    ], { encoding: "utf8", windowsHide: true, timeout: 900_000 });
-
-    if (result.error !== undefined) throw result.error;
-    if (result.status !== 0) {
-      throw new Error(`yt-dlp could not fetch ${url}: ${(result.stderr ?? "").trim().slice(-2000)}`);
+    try {
+      await runExec(executable, [
+        "--ignore-config", "--no-update", "--no-remote-components", "--no-plugin-dirs",
+        "--no-js-runtimes", "--js-runtimes", `node:${process.execPath}`,
+        "--no-playlist", "--no-progress", "--quiet",
+        "--format", "bv*+ba/b",
+        "--merge-output-format", container,
+        "--format-sort", "res:1080,vcodec:h264",
+        "--output", join(work, "video.%(ext)s"),
+        url,
+      ], { timeout: 900_000, maxBuffer: 10 * 1024 * 1024, signal: options.signal });
+    } catch (cause) {
+      if (options.signal?.aborted) throw cause;
+      const error = cause as { stderr?: string; message?: string };
+      throw new Error(`yt-dlp could not fetch ${url}: ${(error.stderr ?? error.message ?? "").trim().slice(-2000)}`);
     }
     const finished = (await readdir(work)).filter((name) => !name.endsWith(".part"));
     const [file] = finished.sort();