Function stabilizeClip

tracker/src/video/stabilize.ts:233–291

(
  src: string,
  out: string,
  opts: StabilizeOpts = {},
)

/** Stabilize a clip: detect the plane, smooth, crop locked onto it, encode. */
export async function stabilizeClip(
  src: string,
  out: string,
  opts: StabilizeOpts = {},
): Promise<void> {
  const cropFrac = Math.min(0.95, Math.max(0.3, opts.cropFrac ?? 0.62));
  const probe = await ffprobe(src);
  const { width: W, height: H, fps } = probe;
  const nFrames = probe.frames || Math.ceil((probe.duration || 30) * fps) + 15;
  opts.onProgress?.(0.1);

  // Prefer the live track logged during recording (the tracker knew exactly
  // where the plane was); fall back to offline motion-comp detection.
  const sidecar = `${src}.track.json`;
  let raw: ({ cx: number; cy: number } | null)[];
  if (existsSync(sidecar)) {
    const sc = JSON.parse(readFileSync(sidecar, "utf8"));
    raw = trackFromSidecar(sc, nFrames, fps, opts.alignMs ?? 0);
  } else {
    raw = await detectTrack(src);
  }
  opts.onProgress?.(0.5);
  const track = smoothTrack(raw);

  // Crop window (even dims), 16:9, clamped inside the frame as it follows the plane.
  const cw = Math.round((Math.round(H * cropFrac) * 16) / 9 / 2) * 2;
  const ch = Math.round((Math.round(H * cropFrac)) / 2) * 2;
  const cmds: string[] = [];
  for (let i = 0; i < track.length; i++) {
    const t = (i / fps).toFixed(4);
    const x = Math.max(0, Math.min(W - cw, Math.round(track[i].cx * W - cw / 2)));
    const y = Math.max(0, Math.min(H - ch, Math.round(track[i].cy * H - ch / 2)));
    cmds.push(`${t} crop x ${x}, crop y ${y};`);
  }
  const cmdFile = `${out}.cmds.txt`;
  await writeFile(cmdFile, cmds.join("\n"));

  const outH = opts.outH ?? 720;
  const outW = Math.round((outH * 16) / 9 / 2) * 2;
  await new Promise<void>((resolve, reject) => {
    // niced + thread-capped so the offline encode yields to the live tracker on
    // the already-busy Pi (no hardware H.264 encoder, so this is software x264).
    const ff = spawn("nice", [
      "-n", "19", "ffmpeg",
      "-hide_banner", "-loglevel", "error", "-y", "-threads", "2", "-i", src,
      "-vf", `sendcmd=f=${cmdFile},crop=${cw}:${ch}:0:0,scale=${outW}:${outH}`,
      "-an", "-c:v", "libx264", "-preset", "veryfast", "-crf", "21",
      "-movflags", "+faststart", out,
    ]);
    let err = "";
    ff.stderr.on("data", (c) => (err = (err + c.toString()).slice(-500)));
    ff.on("error", reject);
    ff.on("close", (code) =>
      code === 0 ? resolve() : reject(new Error(`ffmpeg ${code}: ${err}`)),
    );
  });
  await unlink(cmdFile).catch(() => {});
  opts.onProgress?.(1);