cursedbelt 2.7.0 → 3.0.0

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

@@ -1,347 +0,0 @@
-// 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

@@ -1,115 +0,0 @@
-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 '../../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

@@ -1,232 +0,0 @@
-// 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 '../../core/media';
-import {
-  buildProbeArgs,
-  buildThumbnailArgs,
-  buildTrimArgs,
-  type ProbeResult,
-  parseFfmpegProgress,
-  parseFfprobe,
-} from '../../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;
-  }
-}