Skip to content

Open source CapCut alternative.

TypeScript
10.4 KB
Raw Blame
// Packaging a finished render as an HLS ladder.
//
// A share plays through HLS rather than the flattened mp4 for two reasons. The
// edge refuses to cache a single object past 512 MB (worker/cf/media.ts), which
// a long or 4K cut passes easily — so the one file that most needs the cache is
// the one that never gets it, while segments of a few megabytes always do. And
// a ladder is what lets one asset serve a phone on a weak cellular link and a
// desktop on a 4K panel, which a fixed-bitrate file cannot.
//
// The ladder is built FROM the rendered master, not from the timeline. By that
// point the pixels are already upright, already BT.709 SDR, and already
// composited, so this stage is a pure transcode and never has to know what a
// clip is.
import { spawn } from "node:child_process";
import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
import path from "node:path";
import { runFfmpeg, type RenderHandle } from "./exportPipeline";
import { assertGraphSafe } from "./filterGraph";
import { hasStream, videoDimensions } from "./util";

/** Segment length. Six seconds is the common VOD choice: long enough that
 * per-segment request overhead stays small on a long cut, short enough that a
 * player switching rungs commits to only a few seconds of the wrong bitrate. */
export const HLS_SEGMENT_SECONDS = 6;

/** Audio is encoded per variant rather than as one shared rendition. It costs
 * this much extra per rung, which buys variants that are each self-contained —
 * no audio group to mis-associate, and a rung switch that can never desync. */
const AUDIO_KBPS = 128;

/**
 * One rung, addressed by the SHORT side so portrait and landscape ladders are
 * the same ladder. `kbps` is the video bitrate for a 16:9 frame at that short
 * side; an aspect that carries more pixels scales up from it.
 */
export interface Rung {
  name: string;
  shortSide: number;
  kbps: number;
}

export const HLS_RUNGS: Rung[] = [
  { name: "360p", shortSide: 360, kbps: 800 },
  { name: "540p", shortSide: 540, kbps: 1400 },
  { name: "720p", shortSide: 720, kbps: 2800 },
  { name: "1080p", shortSide: 1080, kbps: 5000 },
  { name: "1440p", shortSide: 1440, kbps: 9000 },
  { name: "2160p", shortSide: 2160, kbps: 18000 },
];

/** Rungs published in the first pass. The share becomes watchable once these
 * land, so they are the ones a phone would pick anyway. */
export const FIRST_PASS_RUNGS = 3;

export interface PlannedRung extends Rung {
  width: number;
  height: number;
  /** Video bitrate after scaling `kbps` for this frame's pixel count. */
  videoKbps: number;
}

const even = (n: number) => Math.max(2, 2 * Math.round(n / 2));

/**
 * The rungs worth building for a source of this size: every rung below the
 * source's short side, plus one capped AT the source. Upscaling is never
 * useful — it spends encode time and storage to add no detail — so the top rung
 * is the source itself.
 */
export function planLadder(width: number, height: number): PlannedRung[] {
  const sourceShort = Math.min(width, height);
  const aspect = width / height;
  const plan: PlannedRung[] = [];
  for (const rung of HLS_RUNGS) {
    const capped = Math.min(rung.shortSide, sourceShort);
    const portrait = height > width;
    const w = even(portrait ? capped : capped * aspect);
    const h = even(portrait ? capped / aspect : capped);
    // `kbps` is tuned for 16:9, whose pixel count at a given short side is the
    // same in both orientations. A squarer or wider frame at that short side
    // carries a different pixel count and needs proportionally different bits.
    const reference = ((capped * capped) * 16) / 9;
    const videoKbps = Math.round(rung.kbps * Math.min(2.5, Math.max(0.5, (w * h) / reference)));
    plan.push({ ...rung, width: w, height: h, videoKbps });
    if (capped >= sourceShort) break;
  }
  return plan;
}

/** `#EXT-X-STREAM-INF` line plus the variant path it introduces. */
export interface Variant {
  inf: string;
  uri: string;
}

/** Pull the variant entries out of a master playlist ffmpeg wrote, so passes
 * that ran separately can be merged into one master. */
function parseVariants(master: string): Variant[] {
  const lines = master.split("\n").map((l) => l.trim());
  const out: Variant[] = [];
  for (let i = 0; i < lines.length; i++) {
    if (!lines[i].startsWith("#EXT-X-STREAM-INF")) continue;
    const uri = lines[i + 1];
    if (uri && !uri.startsWith("#")) out.push({ inf: lines[i], uri });
  }
  return out;
}

/** A master playlist listing `variants`, ordered lowest bitrate first so a
 * player with no measurement yet starts on the rung most likely to play. */
function masterPlaylist(variants: Variant[]): string {
  const bandwidth = (v: Variant) => Number(/BANDWIDTH=(\d+)/.exec(v.inf)?.[1] ?? 0);
  const ordered = [...variants].sort((a, b) => bandwidth(a) - bandwidth(b));
  return ["#EXTM3U", "#EXT-X-VERSION:3", ...ordered.flatMap((v) => [v.inf, v.uri]), ""].join("\n");
}

/**
 * Encode `rungs` out of `source` into `outDir`, in ONE ffmpeg run.
 *
 * The single run is the point: the graph decodes the source once and splits it
 * to every rung. Running ffmpeg per rung would re-decode the whole file each
 * time, which on a 4K master is most of the cost of the job and would saturate
 * a render pool that only has four slots.
 */
export async function encodeRungs(
  handle: RenderHandle,
  source: string,
  outDir: string,
  rungs: PlannedRung[],
  duration: number,
  onProgress?: (fraction: number) => void
): Promise<Variant[]> {
  await Promise.all(rungs.map((r) => mkdir(path.join(outDir, r.name), { recursive: true })));
  const withAudio = await hasStream(source, "a");

  const split = `[0:v]split=${rungs.length}${rungs.map((_, i) => `[s${i}]`).join("")}`;
  const scales = rungs.map(
    (r, i) => `[s${i}]scale=${r.width}:${r.height}:flags=lanczos[o${i}]`
  );

  const maps: string[] = [];
  for (let i = 0; i < rungs.length; i++) maps.push("-map", `[o${i}]`);
  if (withAudio) for (let i = 0; i < rungs.length; i++) maps.push("-map", "0:a:0");

  const codecArgs: string[] = [];
  rungs.forEach((r, i) => {
    codecArgs.push(
      `-c:v:${i}`, "libx264",
      `-preset:v:${i}`, "veryfast",
      `-profile:v:${i}`, "high",
      `-b:v:${i}`, `${r.videoKbps}k`,
      // A ceiling and a matching buffer are what make the rung honest: without
      // them a complex passage overshoots the bitrate the master advertises and
      // the player that chose this rung on that number stalls.
      `-maxrate:v:${i}`, `${Math.round(r.videoKbps * 1.07)}k`,
      `-bufsize:v:${i}`, `${Math.round(r.videoKbps * 1.5)}k`,
      // Every rung must cut at the same instants or a player cannot switch
      // between them. Forcing IDR frames on the segment grid guarantees it
      // regardless of frame rate; disabling scene-cut keeps x264 from adding
      // keyframes that would let the muxer split somewhere else.
      `-force_key_frames:v:${i}`, `expr:gte(t,n_forced*${HLS_SEGMENT_SECONDS})`,
      `-x264-params:v:${i}`, "scenecut=0"
    );
  });

  const streamMap = rungs
    .map((r, i) => (withAudio ? `v:${i},a:${i},name:${r.name}` : `v:${i},name:${r.name}`))
    .join(" ");

  await runFfmpeg(
    handle,
    [
      "-y",
      "-i", source,
      "-filter_complex", assertGraphSafe([split, ...scales].join(";")),
      ...maps,
      ...codecArgs,
      ...(withAudio ? ["-c:a", "aac", "-b:a", `${AUDIO_KBPS}k`, "-ac", "2"] : []),
      "-pix_fmt", "yuv420p",
      "-f", "hls",
      "-hls_time", String(HLS_SEGMENT_SECONDS),
      "-hls_playlist_type", "vod",
      // Declares that every segment can be decoded without the one before it,
      // which is what lets a player join or switch rungs at any segment.
      "-hls_flags", "independent_segments",
      "-hls_segment_filename", path.join(outDir, "%v", "seg%05d.ts"),
      "-master_pl_name", "master.m3u8",
      "-var_stream_map", streamMap,
      path.join(outDir, "%v", "index.m3u8"),
    ],
    duration > 0 && onProgress
      ? (t) => onProgress(Math.min(1, t / Math.max(0.1, duration)))
      : undefined
  );

  // ffmpeg writes the master beside the variant dirs, naming each variant by
  // the same %v it used for the directory.
  const written = await readFile(path.join(outDir, "master.m3u8"), "utf8").catch(() => "");
  const variants = parseVariants(written);
  return variants.length > 0
    ? variants
    : // A build of ffmpeg that declined to write a master still produced usable
      // variants; describe them from the plan rather than losing the pass.
      rungs.map((r) => ({
        inf: `#EXT-X-STREAM-INF:BANDWIDTH=${(r.videoKbps + AUDIO_KBPS) * 1000},RESOLUTION=${r.width}x${r.height}`,
        uri: `${r.name}/index.m3u8`,
      }));
}

/** Write the merged master covering every variant published so far. */
export async function writeMaster(outDir: string, variants: Variant[]): Promise<void> {
  await writeFile(path.join(outDir, "master.m3u8"), masterPlaylist(variants), "utf8");
}

/** Every file under `dir`, relative to it — what the upload step walks. */
export async function listFiles(dir: string, base = ""): Promise<string[]> {
  const entries = await readdir(path.join(dir, base), { withFileTypes: true });
  const out: string[] = [];
  for (const e of entries) {
    const rel = base ? path.join(base, e.name) : e.name;
    if (e.isDirectory()) out.push(...(await listFiles(dir, rel)));
    else out.push(rel);
  }
  return out;
}

/** Source geometry and duration for a rendered master, with sane fallbacks so a
 * failed probe still produces a usable single-rung ladder. */
export async function probeSource(
  file: string
): Promise<{ width: number; height: number; duration: number }> {
  const dims = await videoDimensions(file);
  return {
    width: dims?.width ?? 1920,
    height: dims?.height ?? 1080,
    duration: await mediaDuration(file),
  };
}

/** Duration in seconds via ffprobe; 0 when unknown. */
function mediaDuration(file: string): Promise<number> {
  return new Promise((resolve) => {
    const p = spawn("ffprobe", [
      "-v", "error",
      "-show_entries", "format=duration",
      "-of", "csv=p=0",
      file,
    ]);
    let out = "";
    const timer = setTimeout(() => {
      p.kill("SIGKILL");
      resolve(0);
    }, 30_000);
    timer.unref();
    p.stdout.on("data", (d) => (out += d));
    p.on("close", () => {
      clearTimeout(timer);
      const seconds = Number(out.trim());
      resolve(Number.isFinite(seconds) && seconds > 0 ? seconds : 0);
    });
    p.on("error", () => {
      clearTimeout(timer);
      resolve(0);
    });
  });
}