shorts-maker 0.3.0

package/src/pipeline/media.ts

@@ -0,0 +1,312 @@
+// ffmpeg/ffprobe helpers: probing, pause detection, and clip cutting.
+
+import { dirname, join } from "node:path";
+import { mkdtemp, rm } from "node:fs/promises";
+import { BADGE_SECONDS, overlayFilter, type Overlay } from "./overlay.ts";
+
+export interface VideoInfo {
+  duration: number; // seconds
+  width: number;
+  height: number;
+  isVertical: boolean;
+}
+
+export class MediaError extends Error {}
+
+function require_(tool: string): void {
+  if (!Bun.which(tool)) {
+    throw new MediaError(
+      `\`${tool}\` was not found on PATH. Install ffmpeg (e.g. \`brew install ffmpeg\`).`,
+    );
+  }
+}
+
+async function run(
+  cmd: string[],
+  signal?: AbortSignal,
+): Promise<{ code: number; stdout: string; stderr: string }> {
+  const proc = Bun.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
+  const onAbort = () => proc.kill(); // deleting the job kills the ffmpeg/ffprobe child
+  if (signal?.aborted) proc.kill();
+  else signal?.addEventListener("abort", onAbort, { once: true });
+  try {
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+    const code = await proc.exited;
+    return { code, stdout, stderr };
+  } finally {
+    signal?.removeEventListener("abort", onAbort);
+  }
+}
+
+export async function probe(video: string, signal?: AbortSignal): Promise<VideoInfo> {
+  require_("ffprobe");
+  const { code, stdout, stderr } = await run([
+    "ffprobe", "-v", "error", "-print_format", "json",
+    "-show_format", "-show_streams", video,
+  ], signal);
+  if (code !== 0) throw new MediaError(`ffprobe failed for ${video}:\n${stderr.trim()}`);
+
+  const data = JSON.parse(stdout);
+  let duration = Number(data.format?.duration ?? 0);
+  let width = 0;
+  let height = 0;
+  for (const stream of data.streams ?? []) {
+    if (stream.codec_type === "video") {
+      width = Number(stream.width ?? 0);
+      height = Number(stream.height ?? 0);
+      if (!duration) duration = Number(stream.duration ?? 0);
+      break;
+    }
+  }
+  if (!(duration > 0)) throw new MediaError(`Could not determine duration of ${video}.`);
+  return { duration, width, height, isVertical: height >= width };
+}
+
+/**
+ * Times (seconds) of natural pauses, for cutting where speech drops out.
+ * Uses ffmpeg's silencedetect on the audio only; each pause's midpoint is a cut candidate.
+ */
+export async function silenceCutPoints(
+  video: string,
+  signal?: AbortSignal,
+  noiseDb = -30,
+  minSilence = 0.25,
+): Promise<number[]> {
+  require_("ffmpeg");
+  const { stderr } = await run([
+    "ffmpeg", "-i", video, "-map", "0:a:0",
+    "-af", `silencedetect=noise=${noiseDb}dB:d=${minSilence}`,
+    "-f", "null", "-",
+  ], signal);
+  const nums = (re: RegExp) => [...stderr.matchAll(re)].map((m) => Number(m[1]));
+  const starts = nums(/silence_start:\s*([0-9.]+)/g);
+  const ends = nums(/silence_end:\s*([0-9.]+)/g);
+  const mids: number[] = [];
+  for (let i = 0; i < Math.min(starts.length, ends.length); i++) {
+    mids.push((starts[i]! + ends[i]!) / 2);
+  }
+  return mids.sort((a, b) => a - b);
+}
+
+let hwEncoder: boolean | undefined;
+
+/** Whether this ffmpeg can use Apple's hardware H.264 encoder — far faster than libx264. */
+function hasVideoToolbox(): boolean {
+  if (hwEncoder === undefined) {
+    hwEncoder = false;
+    if (process.platform === "darwin") {
+      const proc = Bun.spawnSync(["ffmpeg", "-hide_banner", "-encoders"]);
+      hwEncoder = proc.stdout.toString().includes("h264_videotoolbox");
+    }
+  }
+  return hwEncoder;
+}
+
+const H264_VIDEOTOOLBOX = ["-c:v", "h264_videotoolbox", "-q:v", "60"];
+const LIBX264 = ["-c:v", "libx264", "-preset", "veryfast", "-crf", "20"];
+
+/** One timescale for every piece we mux — concatenating mismatched ones scrambles timestamps. */
+const TIMESCALE = "90000";
+
+/** Cut [start, end] by stream-copy. Instant, and bit-for-bit the source's quality. */
+async function copyCut(
+  video: string,
+  outFile: string,
+  start: number,
+  end: number,
+  signal?: AbortSignal,
+): Promise<void> {
+  const { code, stderr } = await run([
+    "ffmpeg", "-y", "-ss", start.toFixed(3), "-i", video, "-t", (end - start).toFixed(3),
+    "-c", "copy", "-avoid_negative_ts", "make_zero", "-movflags", "+faststart", outFile,
+  ], signal);
+  if (code !== 0) throw new MediaError(`Clip cut failed for ${outFile}:\n${stderr.trim()}`);
+}
+
+async function ffprobeText(args: string[], signal?: AbortSignal): Promise<string> {
+  require_("ffprobe");
+  const { code, stdout, stderr } = await run(["ffprobe", "-v", "error", ...args], signal);
+  if (code !== 0) throw new MediaError(`ffprobe failed:\n${stderr.trim()}`);
+  return stdout.trim();
+}
+
+const videoPacketPts = (file: string, extra: string[] = []) =>
+  ["-select_streams", "v:0", "-show_entries", "packet=pts_time", "-of", "csv=p=0", ...extra, file];
+
+/** Presentation time of the clip's first video frame — often nonzero, thanks to B-frames. */
+async function firstVideoPts(file: string, signal?: AbortSignal): Promise<number> {
+  // `%+#1` reads a single packet, so this stays instant on a long clip.
+  const out = await ffprobeText(videoPacketPts(file, ["-read_intervals", "%+#1"]), signal);
+  return Number.parseFloat(out.split("\n")[0] ?? "0") || 0;
+}
+
+async function lastVideoPts(file: string, signal?: AbortSignal): Promise<number> {
+  const out = await ffprobeText(videoPacketPts(file), signal);
+  const times = out.split("\n").map((l) => Number.parseFloat(l)).filter((n) => Number.isFinite(n));
+  if (!times.length) throw new MediaError(`No video frames in ${file}.`);
+  return Math.max(...times);
+}
+
+async function frameDuration(file: string, signal?: AbortSignal): Promise<number> {
+  const out = await ffprobeText(
+    ["-select_streams", "v:0", "-show_entries", "stream=r_frame_rate", "-of", "csv=p=0", file],
+    signal,
+  );
+  const [num, den] = out.split("/").map(Number);
+  if (!num || !den) throw new MediaError(`Could not read the frame rate of ${file}.`);
+  return den / num;
+}
+
+async function videoCodec(file: string, signal?: AbortSignal): Promise<string> {
+  return ffprobeText(
+    ["-select_streams", "v:0", "-show_entries", "stream=codec_name", "-of", "csv=p=0", file],
+    signal,
+  );
+}
+
+/** Escape a path for a single-quoted `file` line in a concat list. */
+const concatPath = (p: string) => p.replace(/'/g, "'\\''");
+
+/** Re-encode the whole clip with the badge drawn on it. Correct for any codec, but slow. */
+async function encodeWithBadge(
+  input: string,
+  outFile: string,
+  overlay: Overlay,
+  extraOutput: string[],
+  signal?: AbortSignal,
+): Promise<void> {
+  const encode = (encoder: string[]) =>
+    run([
+      "ffmpeg", "-y", "-i", input,
+      // One video + (if present) one audio track; the source container may also carry
+      // subtitles or data streams, which an .mp4 clip has no use for.
+      "-map", "0:v:0", "-sn", "-dn",
+      "-vf", overlayFilter(overlay),
+      ...encoder, "-pix_fmt", "yuv420p", "-video_track_timescale", TIMESCALE,
+      ...extraOutput, outFile,
+    ], signal);
+
+  const hw = hasVideoToolbox();
+  let { code, stderr } = await encode(hw ? H264_VIDEOTOOLBOX : LIBX264);
+  // VideoToolbox can refuse a source it can't take (unusual dimensions, no GPU session
+  // available); libx264 always works, so a hardware failure is retried in software.
+  if (code !== 0 && hw && !signal?.aborted) ({ code, stderr } = await encode(LIBX264));
+  if (code !== 0) throw new MediaError(`Badge encode failed for ${outFile}:\n${stderr.trim()}`);
+}
+
+/**
+ * Draw the badge onto `part` without re-encoding the whole thing.
+ *
+ * The badge only exists in the first `BADGE_SECONDS`, so only that much video needs to be
+ * re-encoded. The clip's video is split at the first keyframe past the badge, the short
+ * head is re-encoded, and the (much longer) tail is copied untouched and concatenated back
+ * on. On a 2-minute part this is ~10x faster than re-encoding all of it.
+ *
+ * Only the *video* is split. Audio is copied whole from `part` at the end, because an
+ * audio packet almost never lands exactly on the video keyframe, and splicing it there
+ * shifts every later frame out of sync with the picture.
+ */
+async function badgeByReencodingHead(
+  part: string,
+  outFile: string,
+  overlay: Overlay,
+  tmp: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  const segments = join(tmp, "seg%d.mp4");
+  const { code, stderr } = await run([
+    "ffmpeg", "-y", "-i", part, "-map", "0:v:0", "-c", "copy",
+    "-f", "segment", "-segment_format", "mp4", "-segment_times", String(BADGE_SECONDS),
+    "-reset_timestamps", "1", segments,
+  ], signal);
+  if (code !== 0) throw new MediaError(`Could not split ${part} for the badge:\n${stderr.trim()}`);
+
+  const head = join(tmp, "seg0.mp4");
+  const tail = join(tmp, "seg1.mp4");
+  const encodedHead = join(tmp, "head.mp4");
+  await encodeWithBadge(head, encodedHead, overlay, ["-an"], signal);
+
+  // Re-encoding rebases the head to start at 0; the source's own first frame usually sits a
+  // little later. Shifting the joined video back by that much keeps it in step with the
+  // audio, which is copied from `part` with its original timing.
+  const offset = await firstVideoPts(part, signal);
+
+  const videoInput: string[] = [];
+  if (await Bun.file(tail).exists()) {
+    // Every piece must share a timescale, or the concat demuxer rescales them into nonsense.
+    const retimed = join(tmp, "tail.mp4");
+    const remux = await run(
+      ["ffmpeg", "-y", "-i", tail, "-c", "copy", "-video_track_timescale", TIMESCALE, retimed],
+      signal,
+    );
+    if (remux.code !== 0) throw new MediaError(`Could not remux the clip tail:\n${remux.stderr.trim()}`);
+
+    // The tail is placed one frame after the *encoded* head's last frame. Stating the
+    // duration explicitly matters: left to itself, concat offsets by the head's container
+    // duration, which rounds and opens a visible gap at the join.
+    const headEnd = (await lastVideoPts(encodedHead, signal)) + (await frameDuration(encodedHead, signal));
+    const list = join(tmp, "concat.txt");
+    await Bun.write(
+      list,
+      `ffconcat version 1.0\nfile '${concatPath(encodedHead)}'\nduration ${headEnd.toFixed(6)}\nfile '${concatPath(retimed)}'\n`,
+    );
+    videoInput.push("-f", "concat", "-safe", "0", "-i", list);
+  } else {
+    // No keyframe past the badge — the split produced only a head, which is the whole clip.
+    videoInput.push("-i", encodedHead);
+  }
+
+  const mux = await run([
+    "ffmpeg", "-y", "-itsoffset", offset.toFixed(6), ...videoInput, "-i", part,
+    "-map", "0:v:0", "-map", "1:a:0?", "-c", "copy", "-movflags", "+faststart", outFile,
+  ], signal);
+  if (mux.code !== 0) throw new MediaError(`Could not assemble ${outFile}:\n${mux.stderr.trim()}`);
+}
+
+/**
+ * Cut [start, end] out of `video`.
+ *
+ * Without an overlay this is a pure stream-copy. With one, the badge is burned in — see
+ * `badgeByReencodingHead` for how that avoids re-encoding the whole clip.
+ */
+export async function cutClip(
+  video: string,
+  outFile: string,
+  start: number,
+  end: number,
+  signal?: AbortSignal,
+  overlay?: Overlay,
+): Promise<void> {
+  require_("ffmpeg");
+  const stop = end < start + 0.1 ? start + 0.1 : end;
+
+  if (!overlay) return copyCut(video, outFile, start, stop, signal);
+
+  // Staged next to the clip, not in the system temp dir: these intermediates are as big as
+  // the part itself, and /tmp is often a smaller (or different) volume than the output.
+  const tmp = await mkdtemp(join(dirname(outFile), ".badge-"));
+  try {
+    // Cut first, then draw on the cut. The badge's fade is timed from the clip's own start,
+    // and a copy-cut is near-free, so this costs nothing over cutting and encoding at once.
+    const part = join(tmp, "part.mp4");
+    await copyCut(video, part, start, stop, signal);
+
+    // Splicing a re-encoded head onto a copied tail only works when both are the same codec.
+    if ((await videoCodec(part, signal)) === "h264") {
+      try {
+        await badgeByReencodingHead(part, outFile, overlay, tmp, signal);
+        return;
+      } catch (err) {
+        if (signal?.aborted) throw err;
+        // Any surprise in the splice (odd keyframes, VFR, an exotic profile) falls back to
+        // the slow path, which handles anything ffmpeg can decode.
+      }
+    }
+    await encodeWithBadge(part, outFile, overlay, ["-map", "0:a:0?", "-c:a", "copy", "-movflags", "+faststart"], signal);
+  } finally {
+    await rm(tmp, { recursive: true, force: true }).catch(() => {});
+  }
+}

package/src/pipeline/overlay.ts

@@ -0,0 +1,138 @@
+// The burned-in "PART 2" badge: where it can sit, and the ffmpeg filter that draws it.
+
+import { existsSync } from "node:fs";
+
+/** Fixed spots the badge can be pinned to — picked per job in the New split form. */
+export const OVERLAY_POSITIONS = [
+  "top-left",
+  "top-center",
+  "top-right",
+  "center",
+  "bottom-left",
+  "bottom-center",
+  "bottom-right",
+] as const;
+
+export type OverlayPosition = (typeof OVERLAY_POSITIONS)[number];
+
+/** Facebook Reels and Shorts both cover the bottom and right edge with their own UI. */
+export const DEFAULT_OVERLAY_POSITION: OverlayPosition = "top-center";
+
+export function isOverlayPosition(value: unknown): value is OverlayPosition {
+  return typeof value === "string" && (OVERLAY_POSITIONS as readonly string[]).includes(value);
+}
+
+export interface Overlay {
+  /** Badge label, e.g. "PART 2" or "FINAL PART". */
+  text: string;
+  position: OverlayPosition;
+  /** Source dimensions — the badge is sized and inset relative to the frame. */
+  width: number;
+  height: number;
+}
+
+/**
+ * Seconds the badge stays up, and how long it takes to fade out at the end of that.
+ * `BADGE_SECONDS` also decides where a clip is split for re-encoding — see `cutClip`.
+ */
+export const BADGE_SECONDS = 4;
+const SHOW_FOR = BADGE_SECONDS;
+const FADE = 0.75;
+
+/**
+ * How far down a vertical frame the top row of badges starts. The Dynamic Island's bottom
+ * edge lands at ~7.1% of frame height on the worst case (iPhone 16 Pro), so this clears it.
+ */
+const TOP_SAFE_FRACTION = 0.12;
+
+const FONT_CANDIDATES = [
+  "/System/Library/Fonts/Supplemental/Arial Bold.ttf", // macOS
+  "/System/Library/Fonts/Helvetica.ttc",
+  "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf", // Debian / Ubuntu
+  "/usr/share/fonts/dejavu/DejaVuSans-Bold.ttf", // Fedora / Arch
+  "/usr/share/fonts/truetype/liberation/LiberationSans-Bold.ttf",
+  "C:/Windows/Fonts/arialbd.ttf", // Windows
+];
+
+let fontCache: string | null | undefined;
+
+/** A concrete bold font file, or null to let drawtext resolve "Sans" via fontconfig. */
+function fontFile(): string | null {
+  if (fontCache === undefined) {
+    // A path with a quote or backslash can't be escaped reliably inside a filtergraph.
+    fontCache = FONT_CANDIDATES.find((p) => !/['\\]/.test(p) && existsSync(p)) ?? null;
+  }
+  return fontCache;
+}
+
+/**
+ * Make `text` safe to sit inside a single-quoted drawtext option. A literal `'` cannot be
+ * escaped there without closing the quote, so it becomes a typographic apostrophe; `%` and
+ * `\` would otherwise start an expansion or an escape.
+ */
+function escapeText(text: string): string {
+  return text.replace(/'/g, "’").replace(/\\/g, "").replace(/%/g, "％");
+}
+
+const clamp = (n: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, n));
+
+/**
+ * The `-vf` chain that burns `overlay` into a clip.
+ *
+ * `setpts=PTS-STARTPTS` rebases time to the clip, so the badge's 4-second window is
+ * measured from where the part begins rather than from the source's timeline.
+ *
+ * drawtext's `alpha` scales the glyph, border, *and* box colors together, so a single
+ * expression fades the whole badge out as one.
+ */
+export function overlayFilter(overlay: Overlay): string {
+  const { width, height, position } = overlay;
+  const short = Math.min(width, height) || 1080;
+
+  const fontsize = clamp(Math.round(short * 0.055), 22, 96);
+  const pad = Math.round(fontsize * 0.45); // box padding around the glyphs
+  const margin = Math.round(short * 0.045); // gap between the box and the frame edge
+
+  // The box extends `pad` beyond the text on every side, so the text is inset by
+  // `margin + pad` to leave the *box* sitting `margin` from the edge.
+  const inset = margin + pad;
+
+  // A vertical clip plays edge-to-edge on an iPhone, putting the top of the frame under the
+  // Dynamic Island — which reaches ~7% of the way down. Top-row badges drop below it. A
+  // horizontal clip is letterboxed well clear of the island, so it keeps the plain margin.
+  const topInset = height > width ? Math.round(height * TOP_SAFE_FRACTION) + pad : inset;
+
+  const [vert, horiz] = position === "center" ? ["center", "center"] : position.split("-");
+
+  const x =
+    horiz === "left" ? `${inset}` : horiz === "right" ? `w-text_w-${inset}` : "(w-text_w)/2";
+  const y =
+    vert === "top" ? `${topInset}` : vert === "bottom" ? `h-text_h-${inset}` : "(h-text_h)/2";
+
+  const solidUntil = SHOW_FOR - FADE;
+  const alpha = `if(lt(t,${solidUntil}),1,if(lt(t,${SHOW_FOR}),(${SHOW_FOR}-t)/${FADE},0))`;
+
+  const font = fontFile();
+  const opts = [
+    font ? `fontfile='${font}'` : "font='Sans'",
+    `text='${escapeText(overlay.text)}'`,
+    `fontsize=${fontsize}`,
+    "fontcolor=white",
+    `borderw=${Math.max(2, Math.round(fontsize * 0.04))}`,
+    "bordercolor=black@0.85",
+    "box=1",
+    "boxcolor=black@0.5",
+    `boxborderw=${pad}`,
+    `x=${x}`,
+    `y=${y}`,
+    `alpha='${alpha}'`,
+    // Skip the filter entirely once the badge is gone, rather than drawing it invisibly.
+    `enable='lt(t,${SHOW_FOR})'`,
+  ];
+  return `setpts=PTS-STARTPTS,drawtext=${opts.join(":")}`;
+}
+
+/** The badge text for a part: "PART 3", or "FINAL PART" for the last one. */
+export function overlayText(index: number, total: number): string {
+  return index === total && total > 1 ? "FINAL PART" : `PART ${index}`;
+}

package/src/pipeline/parts.ts

@@ -0,0 +1,78 @@
+// Split the whole video into contiguous parts, cutting on pauses.
+
+export interface Part {
+  index: number;
+  start: number;
+  end: number;
+  title: string;
+  hashtags: string[];
+}
+
+export function duration(p: Part): number {
+  return p.end - p.start;
+}
+
+function toParts(spans: [number, number][]): Part[] {
+  return spans.map(([start, end], i) => ({ index: i + 1, start, end, title: "", hashtags: [] }));
+}
+
+/**
+ * Chunk the video into contiguous parts, snapping each cut to the nearest pause.
+ *
+ * `boundaries` is a list of candidate cut times (pause midpoints). Parts are contiguous
+ * and cover 0 → `totalDuration` entirely, cut on pauses so none ends mid-sentence.
+ *
+ * `targetLen` is a **cap**, not a quota: the video is divided into the fewest parts that
+ * keeps each one around or under it (`ceil(total / targetLen)`), then split *evenly* at
+ * that count. So a 96-minute video with a 15-minute target becomes 7 parts of ~13.8 min —
+ * not 6 full 15-min parts plus a 6-min stub. Snapping a cut to a real pause can still
+ * carry a part a little past the cap when pauses are sparse.
+ *
+ * If even parts would come out shorter than `minLast`, one part is dropped and the rest
+ * stretch to absorb it (e.g. 46 min at a 15-min target → 3 × 15.3 min, not 4 × 11.5 min).
+ */
+export function buildParts(
+  boundaries: number[],
+  totalDuration: number,
+  targetLen = 900,
+  minLast?: number,
+): Part[] {
+  const minTail = minLast ?? targetLen * 0.8; // e.g. 12 min for a 15-min target
+  const bounds = boundaries.filter((b) => b > 0 && b < totalDuration).sort((a, b) => a - b);
+
+  if (totalDuration <= targetLen) return toParts([[0, totalDuration]]);
+
+  const nMax = Math.ceil(totalDuration / targetLen);
+  for (let n = nMax; n >= 1; n--) {
+    const spans = splitInto(bounds, totalDuration, n);
+    const last = spans[spans.length - 1]!;
+    if (n <= 1 || last[1] - last[0] >= minTail) return toParts(spans);
+  }
+  return toParts([[0, totalDuration]]);
+}
+
+/**
+ * Build up to `n` contiguous spans of ~`total / n` each, cut on the nearest pause.
+ *
+ * Cut i aims at the *absolute* mark `i * total / n` rather than `previousCut + length`, so
+ * a cut that lands late doesn't push every later cut late too (that drift used to shave
+ * minutes off the final part).
+ */
+function splitInto(bounds: number[], total: number, n: number): [number, number][] {
+  const spans: [number, number][] = [];
+  let cut = 0;
+  for (let i = 1; i < n; i++) {
+    const targetT = (total * i) / n;
+    // Nearest pause that still moves us forward and leaves room for a final part.
+    let best: number | undefined;
+    for (const b of bounds) {
+      if (b <= cut + 1 || b >= total - 0.5) continue;
+      if (best === undefined || Math.abs(b - targetT) < Math.abs(best - targetT)) best = b;
+    }
+    if (best === undefined) break;
+    spans.push([cut, best]);
+    cut = best;
+  }
+  spans.push([cut, total]); // final part takes the rest
+  return spans;
+}