versioncam 0.1.1

package/dist/render/ffmpeg.js

@@ -0,0 +1,72 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+/**
+ * Finds ffmpeg and ffprobe.
+ *
+ * A system install is preferred: it is what a developer already has, and it
+ * is the one whose version they can see. `ffmpeg-static` is an optional
+ * dependency for CI images that have neither — optional because downloading a
+ * ~70 MB binary during `npm install` is rude in someone else's repository.
+ */
+let cachedFfmpeg = null;
+let cachedFfprobe = null;
+function onPath(binary) {
+    const probe = spawnSync(binary, ["-version"], { stdio: "ignore" });
+    return probe.status === 0;
+}
+function fromStaticPackage() {
+    try {
+        const require = createRequire(import.meta.url);
+        const resolved = require("ffmpeg-static");
+        return typeof resolved === "string" ? resolved : (resolved.default ?? null);
+    }
+    catch {
+        return null;
+    }
+}
+export function ffmpegPath() {
+    if (cachedFfmpeg)
+        return cachedFfmpeg;
+    if (onPath("ffmpeg"))
+        return (cachedFfmpeg = "ffmpeg");
+    const fallback = fromStaticPackage();
+    if (fallback)
+        return (cachedFfmpeg = fallback);
+    throw new Error("ffmpeg not found. Install it (`brew install ffmpeg`, `apt install ffmpeg`) " +
+        "or add the optional ffmpeg-static dependency.");
+}
+/**
+ * ffprobe, which `ffmpeg-static` does not ship — it is a separate package.
+ * Only the system one is looked for; without it, duration checks are
+ * unavailable rather than wrong.
+ */
+export function ffprobePath() {
+    if (cachedFfprobe)
+        return cachedFfprobe;
+    if (onPath("ffprobe"))
+        return (cachedFfprobe = "ffprobe");
+    throw new Error("ffprobe not found. It usually installs alongside ffmpeg; on a minimal " +
+        "image install the full ffmpeg package rather than ffmpeg-static.");
+}
+export function ffprobeSync(args) {
+    return execFileSync(ffprobePath(), args, { encoding: "utf8" });
+}
+/** For `versioncam doctor`: report rather than throw. */
+export function ffmpegStatus() {
+    let ffmpeg = null;
+    let ffprobe = null;
+    try {
+        ffmpeg = ffmpegPath();
+    }
+    catch {
+        ffmpeg = null;
+    }
+    try {
+        ffprobe = ffprobePath();
+    }
+    catch {
+        ffprobe = null;
+    }
+    return { ffmpeg, ffprobe };
+}
+//# sourceMappingURL=ffmpeg.js.map

package/dist/render/ffmpeg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ffmpeg.js","sourceRoot":"","sources":["../../src/render/ffmpeg.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;GAOG;AAEH,IAAI,YAAY,GAAkB,IAAI,CAAC;AACvC,IAAI,aAAa,GAAkB,IAAI,CAAC;AAExC,SAAS,MAAM,CAAC,MAAc;IAC5B,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IACnE,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC;AAC5B,CAAC;AAED,SAAS,iBAAiB;IACxB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC/C,MAAM,QAAQ,GAAG,OAAO,CAAC,eAAe,CAAkC,CAAC;QAC3E,OAAO,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC;IAC9E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,IAAI,YAAY;QAAE,OAAO,YAAY,CAAC;IACtC,IAAI,MAAM,CAAC,QAAQ,CAAC;QAAE,OAAO,CAAC,YAAY,GAAG,QAAQ,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAG,iBAAiB,EAAE,CAAC;IACrC,IAAI,QAAQ;QAAE,OAAO,CAAC,YAAY,GAAG,QAAQ,CAAC,CAAC;IAC/C,MAAM,IAAI,KAAK,CACb,6EAA6E;QAC3E,+CAA+C,CAClD,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW;IACzB,IAAI,aAAa;QAAE,OAAO,aAAa,CAAC;IACxC,IAAI,MAAM,CAAC,SAAS,CAAC;QAAE,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;IAC1D,MAAM,IAAI,KAAK,CACb,wEAAwE;QACtE,kEAAkE,CACrE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAc;IACxC,OAAO,YAAY,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;AACjE,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,YAAY;IAI1B,IAAI,MAAM,GAAkB,IAAI,CAAC;IACjC,IAAI,OAAO,GAAkB,IAAI,CAAC;IAClC,IAAI,CAAC;QACH,MAAM,GAAG,UAAU,EAAE,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC;IACD,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,EAAE,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAC7B,CAAC"}

package/dist/render/presentation.d.ts

@@ -0,0 +1,19 @@
+import type { Presentation } from "../config.js";
+import type { Rect } from "../core/timeline.js";
+/**
+ * Where the captured app is drawn inside the output canvas.
+ *
+ * With no presentation the app fills the canvas edge to edge, which is exact
+ * rather than approximate: the output's aspect is derived from the viewport's,
+ * so there is nothing to letterbox. Presentation insets it to make room for a
+ * backdrop and a frame.
+ */
+export declare function frameAreaFor(canvas: {
+    width: number;
+    height: number;
+}, viewport: {
+    width: number;
+    height: number;
+}, presentation: Presentation | null): Rect;
+/** Whether the caption sits under the app or over it. */
+export declare function captionPlacement(presentation: Presentation | null): "below" | "overlay" | "none";

package/dist/render/presentation.js

@@ -0,0 +1,27 @@
+import { fitFrameArea } from "../core/compose.js";
+/**
+ * Where the captured app is drawn inside the output canvas.
+ *
+ * With no presentation the app fills the canvas edge to edge, which is exact
+ * rather than approximate: the output's aspect is derived from the viewport's,
+ * so there is nothing to letterbox. Presentation insets it to make room for a
+ * backdrop and a frame.
+ */
+export function frameAreaFor(canvas, viewport, presentation) {
+    const padding = presentation?.padding ?? 0;
+    if (!presentation || padding <= 0) {
+        return { x: 0, y: 0, w: canvas.width, h: canvas.height };
+    }
+    return fitFrameArea(canvas, viewport, padding);
+}
+/** Whether the caption sits under the app or over it. */
+export function captionPlacement(presentation) {
+    const mode = presentation?.caption ?? "auto";
+    if (mode === "none")
+        return "none";
+    if (mode === "below" || mode === "overlay")
+        return mode;
+    // "auto": there is only room below the app if something made room.
+    return (presentation?.padding ?? 0) > 0 ? "below" : "overlay";
+}
+//# sourceMappingURL=presentation.js.map

package/dist/render/presentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentation.js","sourceRoot":"","sources":["../../src/render/presentation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIlD;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAyC,EACzC,QAA2C,EAC3C,YAAiC;IAEjC,MAAM,OAAO,GAAG,YAAY,EAAE,OAAO,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC,YAAY,IAAI,OAAO,IAAI,CAAC,EAAE,CAAC;QAClC,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;IAC3D,CAAC;IACD,OAAO,YAAY,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AACjD,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,gBAAgB,CAC9B,YAAiC;IAEjC,MAAM,IAAI,GAAG,YAAY,EAAE,OAAO,IAAI,MAAM,CAAC;IAC7C,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,MAAM,CAAC;IACnC,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACxD,mEAAmE;IACnE,OAAO,CAAC,YAAY,EAAE,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAChE,CAAC"}

package/dist/render/render.d.ts

@@ -0,0 +1,59 @@
+import type { Browser, Page } from "playwright";
+import type { ResolvedConfig } from "../config.js";
+import type { Timeline } from "../core/timeline.js";
+import type { EncodeResult } from "./encode.js";
+export type RenderTarget = {
+    kind: "recording";
+    id: string;
+    dir: string;
+} | {
+    kind: "scene";
+    id: string;
+};
+/**
+ * Open the render page at the exact output size, at DPR 1.
+ *
+ * DPR 1 is deliberate: the canvas is already authored in output pixels, and a
+ * device scale factor of 2 would make the screenshot twice as wide and then
+ * need downscaling — a second resample on top of the one `drawImage` already
+ * did.
+ */
+export declare function openRenderPage(browser: Browser, config: ResolvedConfig, target: RenderTarget): Promise<{
+    page: Page;
+    durationFrames: number;
+    fps: number;
+}>;
+export type RenderOutcome = EncodeResult & {
+    id: string;
+    durationFrames: number;
+    fps: number;
+    sheet: string;
+};
+export declare function renderRecording(browser: Browser, config: ResolvedConfig, id: string): Promise<RenderOutcome>;
+export declare function renderScene(browser: Browser, config: ResolvedConfig, id: string): Promise<RenderOutcome>;
+export declare function contactSheet(browser: Browser, config: ResolvedConfig, target: RenderTarget, options?: {
+    frames?: number[];
+}): Promise<string>;
+/**
+ * One frame, rendered at output size.
+ *
+ * The same page and the same `setFrame` the encoder drives, so this is the
+ * frame that would be in the video rather than an approximation of it. A
+ * contact sheet's tile is a quarter the width and settles nothing about a
+ * caption's legibility or whether a control is cropped; this is the look
+ * that does.
+ */
+export declare function renderFrame(browser: Browser, config: ResolvedConfig, target: RenderTarget, frame: number): Promise<Buffer>;
+/** The timeline of a recording on disk, for reporting without a browser. */
+export declare function readTimeline(config: ResolvedConfig, id: string): Promise<Timeline>;
+export declare function withBrowser<T>(fn: (browser: Browser) => Promise<T>): Promise<T>;
+declare global {
+    interface Window {
+        __render?: {
+            ready: Promise<void>;
+            setFrame: (frame: number) => Promise<void>;
+            durationFrames: number;
+            fps: number;
+        };
+    }
+}

package/dist/render/render.js

@@ -0,0 +1,144 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { launchBrowser } from "../driver/launch.js";
+import { renderConfigOf } from "../config.js";
+import { bundleScenes } from "../loader.js";
+import { contactSheet as encodeContactSheet, encodeFromPage, } from "./encode.js";
+import { distPageDir, installRenderRoutes, RENDER_ORIGIN } from "./serve.js";
+/**
+ * Open the render page at the exact output size, at DPR 1.
+ *
+ * DPR 1 is deliberate: the canvas is already authored in output pixels, and a
+ * device scale factor of 2 would make the screenshot twice as wide and then
+ * need downscaling — a second resample on top of the one `drawImage` already
+ * did.
+ */
+export async function openRenderPage(browser, config, target) {
+    const context = await browser.newContext({
+        viewport: config.output,
+        deviceScaleFactor: 1,
+        reducedMotion: "reduce",
+        timezoneId: config.clock.timezoneId,
+        locale: config.clock.locale,
+    });
+    const page = await context.newPage();
+    const problems = [];
+    page.on("pageerror", (error) => problems.push(error.message));
+    page.on("console", (message) => {
+        if (message.type() === "error")
+            problems.push(message.text());
+    });
+    await installRenderRoutes(page, {
+        distDir: distPageDir(),
+        renderConfig: renderConfigOf(config),
+        recordingDir: target.kind === "recording" ? target.dir : undefined,
+        scenesBundle: (await bundleScenes(config)) ?? undefined,
+    });
+    const query = target.kind === "recording"
+        ? "recording"
+        : `scene=${encodeURIComponent(target.id)}`;
+    const response = await page.goto(`${RENDER_ORIGIN}/?${query}&headless=1`, {
+        waitUntil: "domcontentloaded",
+    });
+    if (!response || !response.ok()) {
+        await context.close();
+        throw new Error(`The render page did not load (${response?.status() ?? "no response"}). ` +
+            `Expected it at ${distPageDir()} — run \`npm run build\` in the recorder package.`);
+    }
+    await page.waitForFunction(() => window.__render !== undefined, undefined, {
+        timeout: 30_000,
+    });
+    await page.evaluate(() => window.__render?.ready);
+    const info = await page.evaluate(() => ({
+        durationFrames: window.__render?.durationFrames ?? 0,
+        fps: window.__render?.fps ?? 60,
+    }));
+    if (info.durationFrames === 0) {
+        await context.close();
+        throw new Error(`The render page reported no frames for ${target.kind} "${target.id}".` +
+            (problems.length ? `\n${problems.join("\n")}` : ""));
+    }
+    return { page, ...info };
+}
+async function renderTarget(browser, config, target) {
+    const { page, durationFrames, fps } = await openRenderPage(browser, config, target);
+    try {
+        const encoded = await encodeFromPage(page, {
+            id: target.id,
+            fps,
+            durationFrames,
+            outDir: config.outputDir,
+        });
+        const sheet = await encodeContactSheet(page, {
+            id: target.id,
+            durationFrames,
+            outDir: config.outputDir,
+        });
+        return { ...encoded, id: target.id, durationFrames, fps, sheet };
+    }
+    finally {
+        await page.context().close();
+    }
+}
+export async function renderRecording(browser, config, id) {
+    const dir = join(config.recordingsDir, id);
+    if (!existsSync(join(dir, "timeline.json"))) {
+        throw new Error(`No recording for "${id}". Run \`versioncam record ${id}\` first.`);
+    }
+    return renderTarget(browser, config, { kind: "recording", id, dir });
+}
+export async function renderScene(browser, config, id) {
+    return renderTarget(browser, config, { kind: "scene", id });
+}
+export async function contactSheet(browser, config, target, options = {}) {
+    const { page, durationFrames } = await openRenderPage(browser, config, target);
+    try {
+        return await encodeContactSheet(page, {
+            id: target.id,
+            durationFrames,
+            frames: options.frames,
+            outDir: config.outputDir,
+        });
+    }
+    finally {
+        await page.context().close();
+    }
+}
+/**
+ * One frame, rendered at output size.
+ *
+ * The same page and the same `setFrame` the encoder drives, so this is the
+ * frame that would be in the video rather than an approximation of it. A
+ * contact sheet's tile is a quarter the width and settles nothing about a
+ * caption's legibility or whether a control is cropped; this is the look
+ * that does.
+ */
+export async function renderFrame(browser, config, target, frame) {
+    const { page, durationFrames } = await openRenderPage(browser, config, target);
+    try {
+        if (!Number.isInteger(frame) || frame < 0 || frame >= durationFrames) {
+            throw new Error(`Frame ${frame} is not in "${target.id}": it runs 0–${durationFrames - 1}.`);
+        }
+        await page.evaluate((n) => window.__render?.setFrame(n), frame);
+        return await page.locator("#stage").screenshot({ type: "png" });
+    }
+    finally {
+        await page.context().close();
+    }
+}
+/** The timeline of a recording on disk, for reporting without a browser. */
+export async function readTimeline(config, id) {
+    const file = join(config.recordingsDir, id, "timeline.json");
+    return JSON.parse(await readFile(file, "utf8"));
+}
+export async function withBrowser(fn) {
+    const browser = await launchBrowser();
+    try {
+        return await fn(browser);
+    }
+    finally {
+        await browser.close();
+    }
+}
+//# sourceMappingURL=render.js.map

package/dist/render/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../src/render/render.ts"],"names":[],"mappings":"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"}

package/dist/render/sampling.d.ts

@@ -0,0 +1,47 @@
+import type { Mark } from "../core/timeline.js";
+/**
+ * Which frames a contact sheet shows.
+ *
+ * Eight tiles, because that is what fits legibly on a screen at 960px wide and
+ * what a reviewer will actually look at one by one.
+ */
+export declare const SHEET_TILES = 8;
+/** Evenly spaced, ends included: the shape of the clip, knowing nothing about it. */
+export declare function uniformFrames(durationFrames: number, count?: number): number[];
+/**
+ * Frame 0, every beat, and the last frame.
+ *
+ * An evenly spaced sample is blind to what a clip is *about*: a pilot's sheet
+ * missed the one beat it had been written around, because nothing in eight
+ * uniform samples knew where the beats were. The marks do.
+ *
+ * With more beats than tiles the ends are kept and the middle is thinned
+ * evenly — a reviewer who cannot see every beat is better served by the shape
+ * of the whole clip than by its first eight moments.
+ */
+export declare function markedFrames(durationFrames: number, marks: Mark[], count?: number, crossfadeFrames?: number, cuts?: readonly number[]): number[];
+/**
+ * The frame a beat is shown at: its mark, moved past the crossfade that
+ * starts there — the same frame `markedFrames` puts on a sheet, so asking for
+ * a beat by name and looking at its tile are one picture.
+ */
+export declare function beatFrame(mark: Mark, durationFrames: number, crossfadeFrames?: number): number;
+/**
+ * Which frame `frame --at <label>` means, or why there is none.
+ *
+ * By label because matching a beat to a frame number was arithmetic, and an
+ * agent got the arithmetic wrong. The exact label first; then a prefix, case
+ * ignored, because a label is a phrase someone wrote and the first word is
+ * what gets typed back. A prefix that fits several labels is refused rather
+ * than settled by order — the wrong beat looked at confidently is worse than
+ * a question — and every refusal lists the labels there are.
+ */
+export declare function frameAtMark(timeline: {
+    durationFrames: number;
+    marks?: readonly Mark[];
+}, wanted: string, crossfadeFrames?: number): {
+    frame: number;
+    label: string;
+} | {
+    error: string;
+};

package/dist/render/sampling.js

@@ -0,0 +1,129 @@
+/**
+ * Which frames a contact sheet shows.
+ *
+ * Eight tiles, because that is what fits legibly on a screen at 960px wide and
+ * what a reviewer will actually look at one by one.
+ */
+export const SHEET_TILES = 8;
+/** Evenly spaced, ends included: the shape of the clip, knowing nothing about it. */
+export function uniformFrames(durationFrames, count = SHEET_TILES) {
+    const tiles = Math.max(2, Math.min(count, durationFrames));
+    return Array.from({ length: tiles }, (_, i) => Math.round((i / (tiles - 1)) * (durationFrames - 1)));
+}
+/**
+ * Frame 0, every beat, and the last frame.
+ *
+ * An evenly spaced sample is blind to what a clip is *about*: a pilot's sheet
+ * missed the one beat it had been written around, because nothing in eight
+ * uniform samples knew where the beats were. The marks do.
+ *
+ * With more beats than tiles the ends are kept and the middle is thinned
+ * evenly — a reviewer who cannot see every beat is better served by the shape
+ * of the whole clip than by its first eight moments.
+ */
+export function markedFrames(durationFrames, marks, count = SHEET_TILES, crossfadeFrames = 0, cuts = []) {
+    const inRange = (frame) => Number.isInteger(frame) && frame >= 0 && frame < durationFrames;
+    // Past the crossfade, wherever a frame would land inside one.
+    //
+    // The renderer dissolves between states for `crossfadeFrames` after every
+    // cut, and a tile taken inside that window is two pages at once. A reviewer
+    // shown one said so and declined to judge the beat from it, which is the
+    // right answer to a question that should not have been asked.
+    //
+    // A mark is the worst case — it sits on the cut's first frame, where the
+    // blend has barely begun and the tile still shows what was on screen
+    // *before* the wait — but any evenly spread tile can land there too. Marks
+    // stay where they are, because `review` wants the state boundary; only the
+    // picture waits for the dissolve to finish.
+    const settled = (frame) => {
+        const cut = cuts.find((c) => frame > c && frame <= c + crossfadeFrames);
+        const clear = cut === undefined ? frame : cut + crossfadeFrames + 1;
+        return Math.min(clear, durationFrames - 1);
+    };
+    const wanted = [
+        0,
+        ...marks.map((m) => beatFrame(m, durationFrames, crossfadeFrames)),
+        durationFrames - 1,
+    ].filter(inRange);
+    const unique = [...new Set(wanted)].sort((a, b) => a - b);
+    // Fill the rest of the grid with an even spread.
+    //
+    // A clip with one beat gave a sheet of three tiles, and everything between
+    // the beat and the end — a ring highlight, a camera move, whatever the clip
+    // spent six of its ten seconds on — appeared in none of them. The beats are
+    // what a sheet must not miss, not all it may show, so the spare tiles go to
+    // the shape of the clip around them.
+    if (unique.length < count) {
+        const filled = new Set(unique);
+        for (const frame of uniformFrames(durationFrames, count)) {
+            if (filled.size >= count)
+                break;
+            filled.add(settled(frame));
+        }
+        return [...filled].sort((a, b) => a - b);
+    }
+    if (unique.length === count)
+        return unique;
+    const kept = [unique[0]];
+    for (let i = 1; i <= count - 2; i += 1) {
+        kept.push(unique[Math.round((i * (unique.length - 1)) / (count - 1))]);
+    }
+    kept.push(unique[unique.length - 1]);
+    return [...new Set(kept)];
+}
+/**
+ * The frame a beat is shown at: its mark, moved past the crossfade that
+ * starts there — the same frame `markedFrames` puts on a sheet, so asking for
+ * a beat by name and looking at its tile are one picture.
+ */
+export function beatFrame(mark, durationFrames, crossfadeFrames = 0) {
+    return mark.frame === 0
+        ? 0
+        : Math.min(mark.frame + crossfadeFrames, durationFrames - 1);
+}
+/**
+ * Which frame `frame --at <label>` means, or why there is none.
+ *
+ * By label because matching a beat to a frame number was arithmetic, and an
+ * agent got the arithmetic wrong. The exact label first; then a prefix, case
+ * ignored, because a label is a phrase someone wrote and the first word is
+ * what gets typed back. A prefix that fits several labels is refused rather
+ * than settled by order — the wrong beat looked at confidently is worse than
+ * a question — and every refusal lists the labels there are.
+ */
+export function frameAtMark(
+// `marks` optional because recordings made before marks existed have none,
+// whatever the type of a current timeline says.
+timeline, wanted, crossfadeFrames = 0) {
+    const marks = timeline.marks ?? [];
+    if (marks.length === 0) {
+        return {
+            error: "This recording has no beats to go by — no labelled settle(), or it " +
+                "was made before marks existed. Ask for a frame number or --t instead.",
+        };
+    }
+    const labels = [...new Set(marks.map((m) => m.label))];
+    const list = labels.map((l) => `  ${JSON.stringify(l)}`).join("\n");
+    const exact = marks.find((m) => m.label === wanted);
+    const prefix = wanted.toLowerCase();
+    const candidates = labels.filter((l) => l.toLowerCase().startsWith(prefix));
+    if (!exact && candidates.length > 1) {
+        return {
+            error: `${JSON.stringify(wanted)} starts more than one beat:\n${candidates
+                .map((l) => `  ${JSON.stringify(l)}`)
+                .join("\n")}`,
+        };
+    }
+    const mark = exact ??
+        marks.find((m) => candidates.length === 1 && m.label === candidates[0]);
+    if (!mark) {
+        return {
+            error: `No beat is labelled ${JSON.stringify(wanted)}. The beats:\n${list}`,
+        };
+    }
+    return {
+        frame: beatFrame(mark, timeline.durationFrames, crossfadeFrames),
+        label: mark.label,
+    };
+}
+//# sourceMappingURL=sampling.js.map

package/dist/render/sampling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampling.js","sourceRoot":"","sources":["../../src/render/sampling.ts"],"names":[],"mappings":"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"}

package/dist/render/sequence.d.ts

@@ -0,0 +1,24 @@
+export type SequenceInput = {
+    id: string;
+    path: string;
+    duration: number;
+};
+/** Duration of a video file, in seconds. Blocking; ffprobe is quick. */
+export declare function probeDuration(path: string): number;
+/**
+ * The `xfade` chain. Each transition's `offset` is measured from the start of
+ * everything accumulated so far, and every crossfade shortens the total by its
+ * own duration — which is the part that is easy to get wrong and shows up as
+ * a clip that starts before the previous one has finished.
+ */
+export declare function buildFilter(inputs: SequenceInput[]): {
+    filter: string;
+    label: string;
+    total: number;
+};
+export declare function buildSequence(ids: readonly string[], outDir: string): Promise<{
+    path: string;
+    total: number;
+    used: string[];
+    missing: string[];
+}>;

package/dist/render/sequence.js

@@ -0,0 +1,105 @@
+import { spawn } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { ffmpegPath, ffprobeSync } from "./ffmpeg.js";
+/**
+ * Stitches finished clips into one continuous piece.
+ *
+ * Done with ffmpeg's `xfade` over the already-encoded clips rather than by
+ * re-rendering a combined timeline. Re-rendering would mean holding every
+ * clip's frames in one browser page at once for no gain in quality, and the
+ * clips have to stand alone anyway — the sequence is an arrangement of
+ * finished things, not another thing.
+ *
+ * No title cards between clips: each already carries its own caption, and a
+ * card per clip adds a sixth of the running time for nothing.
+ */
+const TRANSITION_S = 0.4;
+/** Duration of a video file, in seconds. Blocking; ffprobe is quick. */
+export function probeDuration(path) {
+    const out = ffprobeSync([
+        "-v",
+        "error",
+        "-show_entries",
+        "format=duration",
+        "-of",
+        "default=nw=1:nk=1",
+        path,
+    ]);
+    const seconds = Number.parseFloat(out.trim());
+    if (!Number.isFinite(seconds)) {
+        throw new Error(`Could not read a duration from ${path}`);
+    }
+    return seconds;
+}
+/**
+ * The `xfade` chain. Each transition's `offset` is measured from the start of
+ * everything accumulated so far, and every crossfade shortens the total by its
+ * own duration — which is the part that is easy to get wrong and shows up as
+ * a clip that starts before the previous one has finished.
+ */
+export function buildFilter(inputs) {
+    if (inputs.length === 1)
+        return { filter: "", label: "0:v", total: inputs[0].duration };
+    const parts = [];
+    let current = "0:v";
+    let accumulated = inputs[0].duration;
+    for (let i = 1; i < inputs.length; i += 1) {
+        const offset = accumulated - TRANSITION_S;
+        const label = i === inputs.length - 1 ? "out" : `x${i}`;
+        parts.push(`[${current}][${i}:v]xfade=transition=fade:duration=${TRANSITION_S}:offset=${offset.toFixed(3)}[${label}]`);
+        current = label;
+        accumulated += inputs[i].duration - TRANSITION_S;
+    }
+    return { filter: parts.join(";"), label: current, total: accumulated };
+}
+export async function buildSequence(ids, outDir) {
+    const missing = [];
+    const inputs = [];
+    for (const id of ids) {
+        const path = join(outDir, `${id}.mp4`);
+        if (!existsSync(path) || statSync(path).size < 1000) {
+            missing.push(id);
+            continue;
+        }
+        inputs.push({ id, path, duration: probeDuration(path) });
+    }
+    if (inputs.length < 2) {
+        throw new Error(`Need at least two rendered clips to build a sequence; have ${inputs.length}.`);
+    }
+    const { filter, label, total } = buildFilter(inputs);
+    const out = join(outDir, "sequence.mp4");
+    await new Promise((resolve, reject) => {
+        const child = spawn(ffmpegPath(), [
+            "-y",
+            ...inputs.flatMap((input) => ["-i", input.path]),
+            "-filter_complex",
+            filter,
+            "-map",
+            `[${label}]`,
+            "-c:v",
+            "libx264",
+            "-preset",
+            "slow",
+            "-crf",
+            "18",
+            "-pix_fmt",
+            "yuv420p",
+            "-movflags",
+            "+faststart",
+            out,
+        ], { stdio: ["ignore", "ignore", "pipe"] });
+        let stderr = "";
+        child.stderr.on("data", (c) => {
+            stderr += c.toString();
+        });
+        child.on("close", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`sequence failed:\n${stderr.slice(-1200)}`));
+        });
+    });
+    return { path: out, total, used: inputs.map((i) => i.id), missing };
+}
+//# sourceMappingURL=sequence.js.map