summer-engine 4.3.0 → 4.5.0

package/dist/core/capabilities/content-make/media.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The media tools content.make runs on the person's computer: ffmpeg and
+ * ffprobe (cuts, motion, render, loudness), ImageMagick (captions) and,
+ * for a voice-over, a Whisper (word times). Nothing is installed here: a
+ * missing tool is a clear failure that names it.
+ */
+export declare const FPS = 30;
+export declare const W = 1080;
+export declare const H = 1920;
+/** Where a command is on PATH, or null. */
+export declare function which(command: string, path?: string): string | null;
+export declare function requireTools(names: readonly string[]): void;
+export interface RunResult {
+    stdout: string;
+    stderr: string;
+}
+/** Runs a command to the end; a non-zero exit is an error with the last lines of its output. */
+export declare function run(command: string, args: readonly string[], options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<RunResult>;
+export declare const ffmpeg: (args: readonly string[]) => Promise<RunResult>;
+export declare const magick: (args: readonly string[]) => Promise<RunResult>;
+export interface Probe {
+    width: number;
+    height: number;
+    duration: number;
+    hasAudio: boolean;
+    fps: number;
+}
+export declare function probe(file: string): Promise<Probe>;
+export declare const frames: (seconds: number) => number;
+/**
+ * Per-frame motion (YDIF: mean luma change from the frame before) and
+ * brightness (YAVG) of a video, measured on a small copy so it is fast.
+ */
+export declare function signalStats(file: string, fps?: number): Promise<{
+    ydif: number[];
+    yavg: number[];
+}>;
+/** Means of a per-frame series over fixed windows (seconds) at the series' frame rate. */
+export declare function windowMeans(series: readonly number[], fps: number, windowSeconds: number): number[];
+/** Hard cuts (scene changes above the threshold), at least minGap seconds apart. */
+export declare function sceneCuts(file: string, threshold?: number, minGap?: number): Promise<number[]>;
+/** Integrated loudness (LUFS) and true peak (dBTP) of a file's audio. */
+export declare function loudness(file: string): Promise<{
+    lufs: number;
+    truePeak: number;
+} | null>;
+export declare const round2: (value: number) => number;
+/**
+ * Onsets (beats and hits) of a song, seconds: peaks of the rise in short-time
+ * energy, at least 0.12 s apart. Enough to land cuts on the music.
+ */
+export declare function onsets(file: string, maxSeconds?: number): Promise<number[]>;
+/** Onset times from mono samples (pure; see onsets). */
+export declare function onsetTimes(samples: Float32Array, rate: number): number[];

package/dist/core/capabilities/content-make/media.js

@@ -0,0 +1,172 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { BuildToolError } from "../summer-bundle.js";
+/**
+ * The media tools content.make runs on the person's computer: ffmpeg and
+ * ffprobe (cuts, motion, render, loudness), ImageMagick (captions) and,
+ * for a voice-over, a Whisper (word times). Nothing is installed here: a
+ * missing tool is a clear failure that names it.
+ */
+export const FPS = 30;
+export const W = 1080;
+export const H = 1920;
+/** Where a command is on PATH, or null. */
+export function which(command, path = process.env.PATH ?? "") {
+    for (const dir of path.split(delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = join(dir, command);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+const INSTALL = {
+    ffmpeg: "Install ffmpeg (macOS: brew install ffmpeg), then run it again.",
+    ffprobe: "Install ffmpeg (macOS: brew install ffmpeg), then run it again.",
+    magick: "Install ImageMagick 7 (macOS: brew install imagemagick), then run it again.",
+};
+export function requireTools(names) {
+    const missing = names.filter((name) => !which(name));
+    if (missing.length) {
+        throw new BuildToolError("content_tool_missing", `content.make needs ${missing.join(" and ")} on this computer.`, INSTALL[missing[0]] ?? `Install ${missing[0]}, then run it again.`, undefined, { missing: `${missing.join(", ")} on this computer` });
+    }
+}
+/** Runs a command to the end; a non-zero exit is an error with the last lines of its output. */
+export function run(command, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { cwd: options.cwd, env: options.env ?? process.env, stdio: ["ignore", "pipe", "pipe"] });
+        const out = [];
+        const err = [];
+        child.stdout.on("data", (chunk) => out.push(chunk));
+        child.stderr.on("data", (chunk) => err.push(chunk));
+        child.on("error", reject);
+        child.on("close", (code) => {
+            const stdout = Buffer.concat(out).toString("utf8");
+            const stderr = Buffer.concat(err).toString("utf8");
+            if (code === 0)
+                resolve({ stdout, stderr });
+            else
+                reject(new Error(`${command} ${args.slice(0, 3).join(" ")}... exited ${code}: ${stderr.trim().split("\n").slice(-4).join(" | ")}`));
+        });
+    });
+}
+export const ffmpeg = (args) => run("ffmpeg", ["-v", "error", "-y", ...args]);
+export const magick = (args) => run("magick", args);
+export async function probe(file) {
+    const { stdout } = await run("ffprobe", ["-v", "error", "-show_entries", "stream=codec_type,width,height,avg_frame_rate:format=duration", "-of", "json", file]);
+    const parsed = JSON.parse(stdout);
+    const video = parsed.streams?.find((stream) => stream.codec_type === "video");
+    return {
+        width: video?.width ?? 0,
+        height: video?.height ?? 0,
+        duration: Number(parsed.format?.duration ?? 0),
+        hasAudio: Boolean(parsed.streams?.some((stream) => stream.codec_type === "audio")),
+        fps: rate(video?.avg_frame_rate),
+    };
+}
+function rate(value) {
+    const [num, den] = (value ?? "").split("/").map(Number);
+    return num > 0 && den > 0 ? num / den : FPS;
+}
+export const frames = (seconds) => Math.round(seconds * FPS);
+/**
+ * Per-frame motion (YDIF: mean luma change from the frame before) and
+ * brightness (YAVG) of a video, measured on a small copy so it is fast.
+ */
+export async function signalStats(file, fps) {
+    const vf = `${fps ? `fps=${fps},` : ""}scale=270:-2,signalstats,metadata=print:key=lavfi.signalstats.YDIF:file=-,metadata=print:key=lavfi.signalstats.YAVG:file=-`;
+    const { stdout } = await run("ffmpeg", ["-v", "error", "-i", file, "-vf", vf, "-an", "-f", "null", "-"]);
+    const ydif = [];
+    const yavg = [];
+    for (const line of stdout.split("\n")) {
+        const match = /lavfi\.signalstats\.(YDIF|YAVG)=([\d.]+)/.exec(line);
+        if (!match)
+            continue;
+        (match[1] === "YDIF" ? ydif : yavg).push(Number(match[2]));
+    }
+    return { ydif, yavg };
+}
+/** Means of a per-frame series over fixed windows (seconds) at the series' frame rate. */
+export function windowMeans(series, fps, windowSeconds) {
+    const size = Math.max(1, Math.round(fps * windowSeconds));
+    const out = [];
+    for (let start = 0; start < series.length; start += size) {
+        const slice = series.slice(start, start + size);
+        out.push(round2(slice.reduce((sum, value) => sum + value, 0) / slice.length));
+    }
+    return out;
+}
+/** Hard cuts (scene changes above the threshold), at least minGap seconds apart. */
+export async function sceneCuts(file, threshold = 0.3, minGap = 0.12) {
+    const { stderr } = await run("ffmpeg", ["-hide_banner", "-i", file, "-vf", `select='gt(scene,${threshold})',showinfo`, "-an", "-f", "null", "-"]);
+    const cuts = [];
+    for (const match of stderr.matchAll(/pts_time:([0-9.]+)/g)) {
+        const t = round2(Number(match[1]));
+        if (t > minGap && (!cuts.length || t - cuts[cuts.length - 1] >= minGap))
+            cuts.push(t);
+    }
+    return cuts;
+}
+/** Integrated loudness (LUFS) and true peak (dBTP) of a file's audio. */
+export async function loudness(file) {
+    try {
+        const { stderr } = await run("ffmpeg", ["-hide_banner", "-nostats", "-i", file, "-filter_complex", "ebur128=peak=true", "-f", "null", "-"]);
+        const summary = stderr.slice(stderr.lastIndexOf("Summary:"));
+        const lufs = /I:\s+(-?[\d.]+) LUFS/.exec(summary);
+        const peak = /Peak:\s+(-?[\d.]+) dBFS/.exec(summary);
+        return lufs ? { lufs: Number(lufs[1]), truePeak: peak ? Number(peak[1]) : 0 } : null;
+    }
+    catch {
+        return null;
+    }
+}
+export const round2 = (value) => Math.round(value * 100) / 100;
+/**
+ * Onsets (beats and hits) of a song, seconds: peaks of the rise in short-time
+ * energy, at least 0.12 s apart. Enough to land cuts on the music.
+ */
+export async function onsets(file, maxSeconds = 240) {
+    const rate = 4000;
+    const stdout = await runBinary("ffmpeg", ["-v", "error", "-t", String(maxSeconds), "-i", file, "-ac", "1", "-ar", String(rate), "-f", "f32le", "-"]);
+    const aligned = new Float32Array(new Uint8Array(stdout).buffer, 0, Math.floor(stdout.byteLength / 4));
+    return onsetTimes(aligned, rate);
+}
+/** Onset times from mono samples (pure; see onsets). */
+export function onsetTimes(samples, rate) {
+    const hop = Math.round(rate * 0.01);
+    const energy = [];
+    for (let start = 0; start + hop <= samples.length; start += hop) {
+        let sum = 0;
+        for (let i = start; i < start + hop; i++)
+            sum += samples[i] * samples[i];
+        energy.push(Math.log10(1e-9 + sum / hop));
+    }
+    const flux = energy.map((value, index) => Math.max(0, value - (energy[index - 1] ?? value)));
+    const peaks = [];
+    const window = 50;
+    for (let i = 1; i < flux.length - 1; i++) {
+        if (flux[i] <= flux[i - 1] || flux[i] < flux[i + 1])
+            continue;
+        const around = flux.slice(Math.max(0, i - window), i + window);
+        const mean = around.reduce((sum, value) => sum + value, 0) / around.length;
+        if (flux[i] > mean * 2.2 && flux[i] > 0.15 && (!peaks.length || i * 0.01 - peaks[peaks.length - 1].t >= 0.12))
+            peaks.push({ t: round2(i * 0.01), strength: flux[i] });
+    }
+    // a busy song has an onset every few frames; cuts belong on its accents, the stronger 40%
+    const sorted = peaks.map((peak) => peak.strength).sort((a, b) => a - b);
+    const floor = peaks.length > 20 ? sorted[Math.floor(sorted.length * 0.6)] : 0;
+    return peaks.filter((peak) => peak.strength >= floor).map((peak) => peak.t);
+}
+function runBinary(command, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
+        const out = [];
+        let err = "";
+        child.stdout.on("data", (chunk) => out.push(chunk));
+        child.stderr.on("data", (chunk) => (err += chunk.toString()));
+        child.on("error", reject);
+        child.on("close", (code) => (code === 0 ? resolve(Buffer.concat(out)) : reject(new Error(`${command} exited ${code}: ${err.trim().slice(-300)}`))));
+    });
+}

package/dist/core/capabilities/content-make/plan.d.ts

@@ -0,0 +1,130 @@
+import type { CaptionItem, CaptionStyle, Check, FootageClip, Plan, RefBeat, Reference, ShotSpec, Study } from "./types.js";
+/** Search words of a text: lowercase, letters and digits, three or more characters, no filler. */
+export declare function wordsOf(text: string | undefined | null): string[];
+/** True when the reference speaks (a voice-over or a talking host), not only captions and music. */
+export declare function refHasVoice(ref: Pick<Reference, "beats" | "voPattern">): boolean;
+export interface PickContext {
+    usedReferenceIds: ReadonlySet<string>;
+    usedFormats: ReadonlySet<string>;
+    niches: readonly string[];
+    /** The game's recent commits (what changed today); a brief from the caller comes first, without a sha. */
+    commits: ReadonlyArray<{
+        sha?: string;
+        title: string;
+    }>;
+    /** A voice-over in the team's voice is at hand (voiceFile). */
+    voiceReady: boolean;
+    today: string;
+}
+export interface RefPick {
+    ref: Reference;
+    score: number;
+    /** One line on why it fits today, for the person ("You shipped ... today (commit 3f2a1c)"). */
+    fitReason: string;
+    /** The change it fits, when one does. */
+    commit?: {
+        sha: string;
+        title: string;
+    };
+}
+/** Scores one reference for today; null when it cannot be used (locked, expired, no beats, already made). */
+export declare function scoreReference(ref: Reference, ctx: PickContext): RefPick | null;
+/** The best reference for today, ties broken by id so the same inputs give the same pick. */
+export declare function pickReference(refs: readonly Reference[], ctx: PickContext): RefPick | null;
+/**
+ * The reference's caption look, read from its plain-words description:
+ * where it sits, its case, colour, font kind, and whether it holds one
+ * line or follows the voice word by word.
+ */
+export declare function parseCaptionStyle(captionStyle: string | undefined, hasVoice: boolean): CaptionStyle;
+/** Piecewise-linear map of reference times onto our timeline between matching anchors. */
+export declare function mapTimes(times: readonly number[], refAnchors: readonly number[], ourAnchors: readonly number[]): number[];
+export interface Word {
+    w: string;
+    s: number;
+    e: number;
+}
+/** Caption chunks of up to max words, broken at punctuation or a pause. */
+export declare function chunkWords(words: readonly Word[], max?: number, gap?: number): Word[][];
+/**
+ * Our script words on the times Whisper heard: matching words take their
+ * time; a run Whisper heard differently shares the span it took.
+ */
+export declare function alignScript(script: readonly string[], heard: readonly Word[]): Word[];
+/** Start time of each non-empty line in the aligned words (null for an empty line). */
+export declare function lineStarts(lines: readonly string[], aligned: readonly Word[]): Array<number | null>;
+/** Our cut times under a voice-over: the reference's beat starts land on the starts of our matching lines. */
+export declare function voiceAnchors(beats: readonly RefBeat[], starts: ReadonlyArray<number | null>, refDuration: number, voiceEnd: number): {
+    ref: number[];
+    ours: number[];
+};
+/** The window of a clip with the most motion, outside the ranges already used, not too dark. */
+export declare function bestWindow(clip: FootageClip, seconds: number, used: ReadonlyArray<[number, number]>, after?: number): {
+    t: number;
+    motion: number;
+    clean: boolean;
+};
+export interface BeatMapInput {
+    study: Pick<Study, "cuts" | "duration" | "black">;
+    beats: readonly RefBeat[];
+    lines: readonly string[];
+    clips: readonly FootageClip[];
+    /** Our cut times (the reference's, or mapped under our voice). */
+    cuts: readonly number[];
+    /** What the piece is about (the make's brief): weighs every beat's clip choice. */
+    brief?: string;
+}
+/**
+ * Which clip window plays each reference shot. One player's story: the
+ * clip that fits the most beats leads, and its windows move forward in
+ * time; a beat about cards or pages takes stills when there are any; a
+ * fast run of cuts never shows the same clip twice in a row; a reference
+ * black beat stays black.
+ */
+export declare function beatMap(input: BeatMapInput): ShotSpec[];
+/** Held or per-beat captions from our lines: consecutive beats sharing the reference's caption share one line. */
+export declare function beatCaptions(beats: readonly RefBeat[], lines: readonly string[], cuts: readonly number[], refBounds: readonly number[], mode: CaptionStyle["mode"]): CaptionItem[];
+/** Lines still to write: the reference's own words stay out of our output. */
+export declare function unwrittenLines(plan: Pick<Plan, "lines">): number[];
+export interface CheckInput {
+    shotMotion: readonly number[];
+    /** Longest run of frozen frames in each shot, seconds. */
+    shotFreeze?: readonly number[];
+    shotKinds: ReadonlyArray<"video" | "still" | "black">;
+    shotSeconds: readonly number[];
+    /** Mean motion over the first second. */
+    firstSecondMotion: number;
+    /** Seconds to the first caption or voice (null: none). */
+    firstWords: number | null;
+    refFirstWords: number | null;
+    length: number;
+    refLength: number;
+    loudness: {
+        lufs: number;
+        truePeak: number;
+    } | null;
+    /** Caption boxes as shares of the frame: [left, top, right, bottom]. */
+    captionBoxes: ReadonlyArray<[number, number, number, number]>;
+}
+/** The safe area for text: clear of the top bar, the right-hand buttons and the caption block at the bottom. */
+export declare const SAFE: {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+};
+/** A shot may hold still this long (a beat of a held pose); longer reads as a frozen picture. */
+export declare const FREEZE_LIMIT = 0.8;
+/** The measured checks every piece shows next to it. */
+export declare function evaluateChecks(input: CheckInput): Check[];
+/**
+ * Where to start the song so the most cuts land on its beats: tries every
+ * start (0.01 s steps) and counts cuts within 70 ms of an onset. Ties go to
+ * the start closest to the beats, then the earliest.
+ */
+export declare function musicStart(onsets: readonly number[], cuts: readonly number[], songLength: number): {
+    start: number;
+    hits: number;
+};
+/** Moves each cut onto the song's nearest onset within reach (70 ms), keeping every shot at least 0.1 s. */
+export declare function snapCuts(cuts: readonly number[], onsets: readonly number[], start: number, reach?: number): number[];