cursedbelt-server 1.0.0

package/src/server/media-bun/streaming.ts

@@ -0,0 +1,347 @@
+// Pure ffmpeg/ffprobe argument builders + parsers for the STREAMING pipeline: faststart
+// remux, the HLS adaptive-bitrate ladder, scrub-preview sprite sheets + WebVTT, poster
+// frames, and a codec-aware probe. No Bun.spawn, no I/O — every argv + parser here is unit
+// tested without ffmpeg present; `video.ts` is the thin spawn shell that runs them
+// (probeVideoStream / runFfmpegProgress / extractFrameJpeg).
+//
+// Companion to `ffmpeg.ts` (which owns the trim/thumbnail builders + basic probe): these
+// are the additional pieces a streaming server (cursedalchemy's media pipeline, the
+// binary-server) needs to turn an upload into web-seekable, adaptively-streamable output.
+//
+// ffmpeg/ffprobe are expected on PATH (or via FFMPEG_PATH/FFPROBE_PATH) — never an npm dep.
+
+import path from 'node:path';
+
+// ── Web-safe encode primitives (one source of truth for "decodes everywhere") ──────────
+// libx264 defaults to HIGH profile, whose CABAC/8x8-transform features some hardware
+// decoders mis-handle (solid GREEN frame); Main profile drops those at negligible cost and
+// is universally supported. yuv420p is the only chroma layout browsers decode reliably.
+export const h264WebVideoArgs = (crf: string): string[] => [
+  '-c:v',
+  'libx264',
+  '-preset',
+  'veryfast',
+  '-crf',
+  crf,
+  '-profile:v',
+  'main',
+  '-pix_fmt',
+  'yuv420p',
+];
+export const aacWebAudioArgs = (bitrate: string): string[] => ['-c:a', 'aac', '-b:a', bitrate];
+/** Move the moov atom to the front so playback can start before the full download. */
+export const FASTSTART = ['-movflags', '+faststart'];
+/** Cap the long edge at ~1080p, keep aspect, force even dimensions (yuv420p needs even). */
+export const LIBRARY_SCALE = "scale='min(1920,iw)':'-2'";
+/** Higher quality than ephemeral Moments (28) — this output is retained. */
+export const LIBRARY_CRF = '23';
+
+// ── Codec-aware probe (richer than ffmpeg.ts's ProbeResult: adds codecs/pixfmt/audio so the
+//    pipeline can DECIDE whether to stream-copy) ────────────────────────────────────────
+export interface VideoProbe {
+  duration: number;
+  width: number;
+  height: number;
+  vcodec: string;
+  acodec: string;
+  pixfmt: string;
+  hasAudio: boolean;
+}
+
+export const EMPTY_PROBE: VideoProbe = {
+  duration: 0,
+  width: 0,
+  height: 0,
+  vcodec: '',
+  acodec: '',
+  pixfmt: '',
+  hasAudio: false,
+};
+
+/** ffprobe argv: one call for everything the pipeline decides on (codecs + dims + duration). */
+export const buildStreamProbeArgs = (filePath: string): string[] => [
+  '-v',
+  'error',
+  '-show_entries',
+  'format=duration:stream=index,codec_type,codec_name,width,height,pix_fmt',
+  '-of',
+  'json',
+  filePath,
+];
+
+interface StreamProbeJson {
+  format?: { duration?: string };
+  streams?: Array<{
+    codec_type?: string;
+    codec_name?: string;
+    width?: number;
+    height?: number;
+    pix_fmt?: string;
+  }>;
+}
+
+/** Parse the `buildStreamProbeArgs` JSON into a {@link VideoProbe}. */
+export const parseStreamProbe = (json: StreamProbeJson): VideoProbe => {
+  const streams = Array.isArray(json?.streams) ? json.streams : [];
+  const v = streams.find((s) => s.codec_type === 'video') ?? {};
+  const a = streams.find((s) => s.codec_type === 'audio');
+  return {
+    duration: Number(json?.format?.duration) || 0,
+    width: Number(v.width) || 0,
+    height: Number(v.height) || 0,
+    vcodec: String(v.codec_name ?? ''),
+    acodec: String(a?.codec_name ?? ''),
+    pixfmt: String(v.pix_fmt ?? ''),
+    hasAudio: Boolean(a),
+  };
+};
+
+// ── Faststart: stream-copy a source that's already web-safe (fast, lossless — just move the
+//    moov atom), else re-encode to the web-safe ladder. ─────────────────────────────────
+export const canStreamCopy = (p: VideoProbe, maxWidth = 1920): boolean =>
+  p.vcodec === 'h264' &&
+  p.pixfmt === 'yuv420p' &&
+  (p.acodec === '' || p.acodec === 'aac') &&
+  p.width > 0 &&
+  p.width <= maxWidth;
+
+export const faststartArgs = (
+  inPath: string,
+  outPath: string,
+  opts: { copy: boolean; crf?: number },
+): string[] => {
+  if (opts.copy) return ['-i', inPath, '-c', 'copy', ...FASTSTART, outPath];
+  const crf = String(opts.crf ?? Number(LIBRARY_CRF));
+  return [
+    '-i',
+    inPath,
+    '-vf',
+    LIBRARY_SCALE,
+    ...h264WebVideoArgs(crf),
+    ...aacWebAudioArgs('160k'),
+    ...FASTSTART,
+    outPath,
+  ];
+};
+
+/**
+ * Parse one ffmpeg `-progress pipe:1` line into elapsed microseconds, or null if the line
+ * carries no out_time. `runFfmpegProgress` turns a stream of these into a 0..99 percent.
+ */
+export const parseProgressMicros = (line: string): number | null => {
+  const m = /^out_time_us=(\d+)/.exec(line) ?? /^out_time_ms=(\d+)/.exec(line);
+  if (!m) return null;
+  return line.startsWith('out_time_ms') ? Number(m[1]) * 1000 : Number(m[1]);
+};
+
+// ── HLS adaptive-bitrate ladder ─────────────────────────────────────────────────────────
+// Per-rung video bitrate cap + buffer + audio rate. One source of truth for rung tuning.
+const LADDER_PRESETS: Record<number, { maxrate: string; bufsize: string; abr: string }> = {
+  360: { maxrate: '856k', bufsize: '1200k', abr: '96k' },
+  480: { maxrate: '1400k', bufsize: '2100k', abr: '128k' },
+  720: { maxrate: '2800k', bufsize: '4200k', abr: '128k' },
+  1080: { maxrate: '5000k', bufsize: '7500k', abr: '192k' },
+  1440: { maxrate: '8000k', bufsize: '12000k', abr: '192k' },
+  2160: { maxrate: '16000k', bufsize: '24000k', abr: '192k' },
+};
+
+/** Drop unknown/too-tall rungs (never upscale); always keep at least the source-or-720 rung. */
+export const resolveLadder = (heights: number[], sourceHeight: number): number[] => {
+  const valid = heights
+    .filter((h) => LADDER_PRESETS[h])
+    .filter((h) => sourceHeight <= 0 || h <= sourceHeight);
+  const ladder = valid.length ? valid : [Math.min(720, sourceHeight || 720)];
+  return [...new Set(ladder)].sort((a, b) => a - b);
+};
+
+/**
+ * Build the HLS multi-rendition transcode. `outDir/<height>/` subdirs must already exist.
+ * Emits master.m3u8 + per-rung playlist.m3u8 + mpegts segments, variants NAMED by height
+ * so storage keys read `…/720/seg_00001.ts` rather than an opaque index.
+ */
+export const hlsLadderArgs = (
+  inPath: string,
+  outDir: string,
+  opts: {
+    heights: number[];
+    crf: number;
+    hasAudio: boolean;
+    // When set, ffmpeg AES-128-encrypts every segment using this key-info file (line 1 = the
+    // key URI written into the playlist's #EXT-X-KEY, line 2 = the raw 16-byte key file, line 3
+    // = IV hex). Yields encrypted-at-rest, edge-cacheable segments the player decrypts. Used by
+    // the private-media pipeline; omit for public (plaintext) media.
+    keyInfoFile?: string;
+  },
+): string[] => {
+  const hs = opts.heights.length ? opts.heights : [720];
+  const n = hs.length;
+  const filter =
+    `[0:v]split=${n}${hs.map((_, i) => `[v${i}]`).join('')};` +
+    hs.map((h, i) => `[v${i}]scale=-2:${h}[vo${i}]`).join(';');
+
+  const args: string[] = ['-i', inPath, '-filter_complex', filter];
+  hs.forEach((h, i) => {
+    const p = LADDER_PRESETS[h] ?? LADDER_PRESETS[720];
+    args.push(
+      '-map',
+      `[vo${i}]`,
+      `-c:v:${i}`,
+      'libx264',
+      '-preset',
+      'veryfast',
+      `-crf:v:${i}`,
+      String(opts.crf),
+      `-profile:v:${i}`,
+      'main',
+      `-maxrate:v:${i}`,
+      p.maxrate,
+      `-bufsize:v:${i}`,
+      p.bufsize,
+    );
+  });
+  args.push('-pix_fmt', 'yuv420p');
+  if (opts.hasAudio) {
+    hs.forEach((h, i) => {
+      const p = LADDER_PRESETS[h] ?? LADDER_PRESETS[720];
+      args.push('-map', 'a:0', `-c:a:${i}`, 'aac', `-b:a:${i}`, p.abr, '-ac', '2');
+    });
+  }
+  const varMap = hs
+    .map((h, i) => (opts.hasAudio ? `v:${i},a:${i},name:${h}` : `v:${i},name:${h}`))
+    .join(' ');
+  args.push(
+    '-f',
+    'hls',
+    '-hls_time',
+    '4',
+    '-hls_playlist_type',
+    'vod',
+    '-hls_segment_type',
+    'mpegts',
+    ...(opts.keyInfoFile ? ['-hls_key_info_file', opts.keyInfoFile] : []),
+    '-master_pl_name',
+    'master.m3u8',
+    '-hls_segment_filename',
+    path.join(outDir, '%v', 'seg_%05d.ts'),
+    '-var_stream_map',
+    varMap,
+    path.join(outDir, '%v', 'playlist.m3u8'),
+  );
+  return args;
+};
+
+/** Poster: a frame `atSeconds` in (default ~1s, to skip black intros), scaled to the library
+ *  width, as JPEG. Pass a smaller seek (or 0) for very short clips — seeking past EOF yields no
+ *  frame and the extract fails, so callers that know the duration should clamp `atSeconds`. */
+export const posterArgs = (inPath: string, outPath: string, atSeconds = 1): string[] => [
+  '-ss',
+  String(Math.max(0, atSeconds)),
+  '-i',
+  inPath,
+  '-vframes',
+  '1',
+  '-vf',
+  LIBRARY_SCALE,
+  outPath,
+];
+
+/** Decode a still image to a width-capped JPEG thumbnail. The fallback for formats sharp's
+ *  prebuilt binary can't decode — notably HEIC/HEVC (iPhone photos), which the licensed-out
+ *  libheif build rejects but ffmpeg's hevc decoder handles. `-update 1` writes the single frame
+ *  to a fixed filename (no image-sequence pattern); height rounds to even (`-2`) for the encoder. */
+export const imageThumbnailArgs = (inPath: string, outPath: string, maxWidth = 512): string[] => [
+  '-i',
+  inPath,
+  '-vf',
+  `scale='min(${maxWidth},iw)':-2`,
+  '-frames:v',
+  '1',
+  '-update',
+  '1',
+  outPath,
+];
+
+/** ffmpeg argv to grab one scaled JPEG frame at `atSeconds` on stdout (`-ss` before `-i`
+ *  fast-seeks — instant on a faststart file). The spawn runner reads pipe:1. */
+export const buildFrameJpegArgs = (
+  filePath: string,
+  atSeconds: number,
+  maxWidth = 240,
+): string[] => [
+  '-ss',
+  String(Math.max(0, atSeconds)),
+  '-i',
+  filePath,
+  '-frames:v',
+  '1',
+  '-vf',
+  `scale=${maxWidth}:-2`,
+  '-f',
+  'mjpeg',
+  'pipe:1',
+];
+
+// ── Scrub-preview sprite sheet + WebVTT (YouTube-style hover/drag thumbnails) ───────────
+const SPRITE_THUMB_WIDTH = 160;
+const SPRITE_MAX_TILES = 144; // a single ~12×12 sheet; widen the interval past this
+
+export interface SpritePlan {
+  effInterval: number; // seconds between sampled frames (widened for long videos)
+  count: number;
+  cols: number;
+  rows: number;
+  thumbW: number;
+  thumbH: number;
+}
+
+/** Sheet geometry: sample every `interval`s, widening it so a long video still fits one sheet. */
+export const planSprite = (
+  duration: number,
+  interval: number,
+  srcW: number,
+  srcH: number,
+): SpritePlan => {
+  const dur = Math.max(1, duration);
+  const effInterval = Math.max(1, interval, Math.ceil(dur / SPRITE_MAX_TILES));
+  const count = Math.max(1, Math.min(SPRITE_MAX_TILES, Math.ceil(dur / effInterval)));
+  const cols = Math.ceil(Math.sqrt(count));
+  const rows = Math.ceil(count / cols);
+  const thumbW = SPRITE_THUMB_WIDTH;
+  const thumbH = srcW > 0 ? Math.max(2, Math.round((thumbW * srcH) / srcW / 2) * 2) : 90;
+  return { effInterval, count, cols, rows, thumbW, thumbH };
+};
+
+export const spriteArgs = (inPath: string, outPath: string, plan: SpritePlan): string[] => [
+  '-i',
+  inPath,
+  '-vf',
+  `fps=1/${plan.effInterval},scale=${plan.thumbW}:-2,tile=${plan.cols}x${plan.rows}`,
+  '-frames:v',
+  '1',
+  '-q:v',
+  '5',
+  outPath,
+];
+
+const vttTime = (s: number): string => {
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  const sec = s % 60;
+  return `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}:${sec.toFixed(3).padStart(6, '0')}`;
+};
+
+/**
+ * WebVTT thumbnail track: one cue per tile pointing at a `#xywh` media fragment of the sheet.
+ * The sprite URL is relative (default "sprites.jpg") so it resolves against the VTT's own route.
+ */
+export const buildSpriteVtt = (plan: SpritePlan, spriteName = 'sprites.jpg'): string => {
+  let out = 'WEBVTT\n\n';
+  for (let i = 0; i < plan.count; i++) {
+    const start = i * plan.effInterval;
+    const end = (i + 1) * plan.effInterval;
+    const x = (i % plan.cols) * plan.thumbW;
+    const y = Math.floor(i / plan.cols) * plan.thumbH;
+    out += `${vttTime(start)} --> ${vttTime(end)}\n${spriteName}#xywh=${x},${y},${plan.thumbW},${plan.thumbH}\n\n`;
+  }
+  return out;
+};

package/src/server/media-bun/video.spec.ts

@@ -0,0 +1,115 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { VideoProgressEvent } from 'cursedbelt-core/media';
+import { extractThumbnail, isFfmpegAvailable, probeMedia, trimVideo } from './video';
+
+// ffmpeg/ffprobe are required for these; skip cleanly if absent (CI without them).
+const haveFfmpeg = await isFfmpegAvailable();
+
+let dir = '';
+let source = '';
+
+/** Synthesize a 10s 320×240 test clip with ffmpeg's lavfi sources. */
+async function makeSource(path: string): Promise<void> {
+  const proc = Bun.spawn(
+    [
+      'ffmpeg',
+      '-hide_banner',
+      '-y',
+      '-f',
+      'lavfi',
+      '-i',
+      'testsrc=duration=10:size=320x240:rate=15',
+      '-f',
+      'lavfi',
+      '-i',
+      'sine=frequency=440:duration=10',
+      '-pix_fmt',
+      'yuv420p',
+      '-c:v',
+      'libx264',
+      '-c:a',
+      'aac',
+      '-shortest',
+      path,
+    ],
+    { stdout: 'ignore', stderr: 'ignore' },
+  );
+  await proc.exited;
+  if (proc.exitCode !== 0) throw new Error('failed to synthesize test clip');
+}
+
+beforeAll(async () => {
+  if (!haveFfmpeg) return;
+  dir = mkdtempSync(join(tmpdir(), 'cb-media-video-'));
+  source = join(dir, 'source.mp4');
+  await makeSource(source);
+});
+
+afterAll(() => {
+  if (dir) rmSync(dir, { recursive: true, force: true });
+});
+
+// SKIPPED on a host without ffmpeg/ffprobe — it synthesizes and decodes real media. Runs by default wherever ffmpeg is installed.
+describe.skipIf(!haveFfmpeg)('media-bun video (ffmpeg)', () => {
+  test('probeMedia reads dimensions + duration', async () => {
+    const meta = await probeMedia(source);
+    expect(meta.width).toBe(320);
+    expect(meta.height).toBe(240);
+    expect(meta.durationSeconds).toBeGreaterThan(9);
+    expect(meta.durationSeconds).toBeLessThan(11);
+  });
+
+  test('trimVideo writes a ~6s clip and reports progress (acceptance #9)', async () => {
+    const out = join(dir, 'trim.mp4');
+    const events: VideoProgressEvent[] = [];
+    await trimVideo({ inputPath: source, outputPath: out, startSeconds: 2, endSeconds: 8 }, (e) =>
+      events.push(e),
+    );
+
+    expect(await Bun.file(out).exists()).toBe(true);
+    const meta = await probeMedia(out);
+    expect(meta.durationSeconds).toBeGreaterThan(5.5);
+    expect(meta.durationSeconds).toBeLessThan(6.5);
+
+    // Saw at least one encode event and a terminal done at 100%.
+    expect(events.some((e) => e.phase === 'encode')).toBe(true);
+    expect(events.at(-1)).toEqual({ phase: 'done', progressPercent: 100 });
+  }, 30_000);
+
+  test('trimVideo can output webm', async () => {
+    const out = join(dir, 'trim.webm');
+    await trimVideo({
+      inputPath: source,
+      outputPath: out,
+      startSeconds: 1,
+      endSeconds: 3,
+      format: 'webm',
+      quality: 'low',
+    });
+    expect(await Bun.file(out).exists()).toBe(true);
+  }, 30_000);
+
+  test('extractThumbnail writes a single frame', async () => {
+    const out = join(dir, 'thumb.jpg');
+    await extractThumbnail(source, 4, out);
+    expect((await Bun.file(out).size) > 0).toBe(true);
+  });
+
+  test('trimVideo rejects an invalid spec', async () => {
+    await expect(
+      trimVideo({
+        inputPath: source,
+        outputPath: join(dir, 'x.mp4'),
+        startSeconds: 5,
+        endSeconds: 5,
+      }),
+    ).rejects.toThrow(/Invalid VideoTrimSpec/);
+  });
+
+  test('probeMedia throws on a missing file', async () => {
+    await expect(probeMedia(join(dir, 'nope.mp4'))).rejects.toThrow();
+  });
+});

package/src/server/media-bun/video.ts

@@ -0,0 +1,232 @@
+// Video trim / probe / thumbnail via native ffmpeg + ffprobe, spawned with Bun.spawn.
+// All argv construction + output parsing lives in the pure `ffmpeg.ts` (tested without
+// ffmpeg); this file is the thin process shell. The binaries must be on PATH, or set
+// `FFMPEG_PATH` / `FFPROBE_PATH`. Replaces ca's hand-rolled spawn boilerplate.
+
+import {
+  assertValidVideoTrimSpec,
+  type VideoProgressEvent,
+  type VideoTrimSpec,
+} from 'cursedbelt-core/media';
+import {
+  buildProbeArgs,
+  buildThumbnailArgs,
+  buildTrimArgs,
+  type ProbeResult,
+  parseFfmpegProgress,
+  parseFfprobe,
+} from 'cursedbelt-core/media/ffmpeg';
+import {
+  buildFrameJpegArgs,
+  buildStreamProbeArgs,
+  EMPTY_PROBE,
+  parseProgressMicros,
+  parseStreamProbe,
+  type VideoProbe,
+} from './streaming';
+
+const FFMPEG = process.env.FFMPEG_PATH || 'ffmpeg';
+const FFPROBE = process.env.FFPROBE_PATH || 'ffprobe';
+
+/** Is ffmpeg runnable? Cheap probe used to skip server media ops / tests cleanly. */
+export async function isFfmpegAvailable(bin: string = FFMPEG): Promise<boolean> {
+  try {
+    const proc = Bun.spawn([bin, '-version'], { stdout: 'ignore', stderr: 'ignore' });
+    await proc.exited;
+    return proc.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+/** Is ffprobe runnable? */
+export function isFfprobeAvailable(): Promise<boolean> {
+  return isFfmpegAvailable(FFPROBE);
+}
+
+/** Drain a stderr stream line-by-line (ffmpeg uses \r to update progress in place). */
+async function readProgress(
+  stream: ReadableStream<Uint8Array>,
+  totalSeconds: number,
+  onProgress: ((e: VideoProgressEvent) => void) | undefined,
+): Promise<string> {
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let tail = '';
+  for await (const chunk of stream) {
+    const text = decoder.decode(chunk, { stream: true });
+    buffer += text;
+    tail = (tail + text).slice(-4000); // keep a bounded tail for an error message
+    const segments = buffer.split(/[\r\n]/);
+    buffer = segments.pop() ?? '';
+    if (onProgress) {
+      for (const seg of segments) {
+        const ev = parseFfmpegProgress(seg, totalSeconds);
+        if (ev) onProgress(ev);
+      }
+    }
+  }
+  return tail;
+}
+
+/**
+ * Trim `[startSeconds, endSeconds]` from `inputPath` into `outputPath`, re-encoding to
+ * the requested format/quality. `onProgress` receives `encode` events (parsed from
+ * ffmpeg stderr) and a final `done`; on a non-zero exit it emits `error` and throws.
+ */
+export async function trimVideo(
+  spec: VideoTrimSpec,
+  onProgress?: (event: VideoProgressEvent) => void,
+): Promise<void> {
+  assertValidVideoTrimSpec(spec);
+  const total = spec.endSeconds - spec.startSeconds;
+  onProgress?.({ phase: 'encode', progressPercent: 0 });
+
+  const proc = Bun.spawn([FFMPEG, ...buildTrimArgs(spec)], { stdout: 'ignore', stderr: 'pipe' });
+  const tail = await readProgress(proc.stderr as ReadableStream<Uint8Array>, total, onProgress);
+  await proc.exited;
+
+  if (proc.exitCode !== 0) {
+    const message = `ffmpeg trim failed (exit ${proc.exitCode}): ${
+      tail
+        .trim()
+        .split(/[\r\n]/)
+        .pop() ?? ''
+    }`;
+    onProgress?.({ phase: 'error', error: message });
+    throw new Error(message);
+  }
+  onProgress?.({ phase: 'done', progressPercent: 100 });
+}
+
+/** Probe a media file's primary video dimensions + duration + container format. */
+export async function probeMedia(inputPath: string): Promise<ProbeResult> {
+  const proc = Bun.spawn([FFPROBE, ...buildProbeArgs(inputPath)], {
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  const stdout = await new Response(proc.stdout).text();
+  await proc.exited;
+  if (proc.exitCode !== 0) {
+    throw new Error(`ffprobe failed (exit ${proc.exitCode}) for ${inputPath}`);
+  }
+  try {
+    return parseFfprobe(JSON.parse(stdout));
+  } catch (err) {
+    throw new Error(
+      `ffprobe returned unparseable JSON: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+/** Extract a single frame at `atSeconds` from `inputPath` and write it to `output`. */
+export async function extractThumbnail(
+  inputPath: string,
+  atSeconds: number,
+  output: string,
+): Promise<void> {
+  const proc = Bun.spawn([FFMPEG, ...buildThumbnailArgs(inputPath, atSeconds, output)], {
+    stdout: 'ignore',
+    stderr: 'pipe',
+  });
+  const tail = await new Response(proc.stderr).text();
+  await proc.exited;
+  if (proc.exitCode !== 0) {
+    throw new Error(
+      `ffmpeg thumbnail failed (exit ${proc.exitCode}): ${
+        tail
+          .trim()
+          .split(/[\r\n]/)
+          .pop() ?? ''
+      }`,
+    );
+  }
+}
+
+// ── Streaming-pipeline spawn runners (companions to streaming.ts's pure builders) ───────
+
+/**
+ * Codec-aware probe for the streaming pipeline (codecs + pixfmt + audio, so a caller can
+ * decide whether to stream-copy). Best-effort: returns {@link EMPTY_PROBE} on any failure —
+ * the pipeline stays usable (a node is always playable as raw range meanwhile).
+ */
+export async function probeVideoStream(inputPath: string): Promise<VideoProbe> {
+  try {
+    const proc = Bun.spawn([FFPROBE, ...buildStreamProbeArgs(inputPath)], {
+      stdout: 'pipe',
+      stderr: 'ignore',
+    });
+    const stdout = await new Response(proc.stdout).text();
+    await proc.exited;
+    if (proc.exitCode !== 0) return EMPTY_PROBE;
+    return parseStreamProbe(JSON.parse(stdout));
+  } catch {
+    return EMPTY_PROBE;
+  }
+}
+
+/**
+ * Run an ffmpeg transcode while parsing its `-progress pipe:1` stream into a 0..99 percent
+ * (so a slow re-encode reports live progress). `durationSec` is the source duration; 0 ⇒ no
+ * percent. `args` should NOT include the leading `ffmpeg`/`-y`. Resolves true on success;
+ * on failure it passes the trailing stderr to `onError` (the app logs) and resolves false.
+ */
+export async function runFfmpegProgress(
+  args: string[],
+  durationSec: number,
+  onProgress?: (pct: number) => void,
+  onError?: (stderrTail: string) => void,
+): Promise<boolean> {
+  const proc = Bun.spawn([FFMPEG, '-y', '-progress', 'pipe:1', '-nostats', ...args], {
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  if (durationSec > 0 && onProgress && proc.stdout) {
+    void (async () => {
+      const decoder = new TextDecoder();
+      let buf = '';
+      try {
+        for await (const chunk of proc.stdout as ReadableStream<Uint8Array>) {
+          buf += decoder.decode(chunk, { stream: true });
+          const lines = buf.split('\n');
+          buf = lines.pop() ?? '';
+          for (const line of lines) {
+            const us = parseProgressMicros(line);
+            if (us === null) continue;
+            onProgress(Math.max(0, Math.min(99, Math.round((us / 1e6 / durationSec) * 100))));
+          }
+        }
+      } catch {
+        /* progress is best-effort */
+      }
+    })();
+  }
+  await proc.exited;
+  if (proc.exitCode !== 0) {
+    if (onError) onError((await new Response(proc.stderr).text()).slice(-600));
+    return false;
+  }
+  return true;
+}
+
+/**
+ * On-demand single JPEG frame at `atSeconds` (scaled to `maxWidth`) as bytes, or null on
+ * failure. `-ss` before `-i` fast-seeks — instant on a faststart file.
+ */
+export async function extractFrameJpeg(
+  filePath: string,
+  atSeconds: number,
+  maxWidth = 240,
+): Promise<Uint8Array | null> {
+  try {
+    const proc = Bun.spawn([FFMPEG, '-y', ...buildFrameJpegArgs(filePath, atSeconds, maxWidth)], {
+      stdout: 'pipe',
+      stderr: 'ignore',
+    });
+    const bytes = new Uint8Array(await new Response(proc.stdout).arrayBuffer());
+    await proc.exited;
+    return proc.exitCode === 0 && bytes.length > 0 ? bytes : null;
+  } catch {
+    return null;
+  }
+}