Skip to content

Write HTML. Render video. Built for agents.

21.0 KB
Raw Blame
import { statSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import {
  formatRenderOutputTimestamp,
  fpsToNumber,
  isAspectAgnosticResolutionAlias,
  normalizeResolutionFlag,
  parseFps,
  type CanvasResolution,
  type Fps,
  type FpsParseResult,
} from "@hyperframes/core";
import {
  EXTRACT_CACHE_DIR_DISABLED_ALIASES,
  MAX_VP9_CPU_USED,
  MIN_VP9_CPU_USED,
  isVideoFrameFormat,
  type VideoFrameFormat,
} from "@hyperframes/engine";
import { errorBox } from "../../ui/format.js";
import { parseEnumFlag } from "../../cloud/parsing.js";
import { failUsage } from "../../utils/commandResult.js";
import { resolveProject } from "../../utils/project.js";
import {
  hasExplicitCompositionArg,
  parseGifLoopArg,
  parseHlsSegmentSecondsArg,
  resolveBrowserTimeoutMsArg,
  resolveCompositionEntryArg,
  resolveDefaultFpsArg,
} from "../../utils/renderArgs.js";
import { normalizeSkillSlug } from "../../telemetry/skill.js";
import { loadProjectConfig } from "../../utils/projectConfig.js";
import { type CatalogUsage, summarizeCatalogUsage } from "../../utils/catalogUsage.js";

const QUALITY_ALIASES = {
  draft: { quality: "draft" as const },
  standard: { quality: "standard" as const },
  high: { quality: "high" as const },
  looks: { quality: "standard" as const, crf: 16 },
  delivery: { quality: "high" as const },
} as const;
const RENDER_FORMATS = ["mp4", "webm", "mov", "png-sequence", "gif", "hls"] as const;
const VALID_FORMAT = new Set<string>(RENDER_FORMATS);
const RENDER_FORMAT_LABEL = "mp4, webm, mov, png-sequence, gif, or hls";

/** Mirrors the producer's `DEFAULT_HLS_SEGMENT_SECONDS`; the plan is built before the producer loads. */
const DEFAULT_HLS_SEGMENT_SECONDS = 4;

export type RenderFormat = (typeof RENDER_FORMATS)[number];
export type RenderQuality = "draft" | "standard" | "high";
export type BrowserGpuMode = "auto" | "hardware" | "software";
export type HdrMode = "auto" | "force-hdr" | "force-sdr";
export type RenderProject = ReturnType<typeof resolveProject>;

const FORMAT_EXT: Record<RenderFormat, string> = {
  mp4: ".mp4",
  webm: ".webm",
  mov: ".mov",
  "png-sequence": "",
  gif: ".gif",
  // Directory output, like png-sequence: playlists and .ts segments go inside.
  hls: "",
};

export interface RenderCommandArgs {
  dir?: string;
  composition?: string;
  output?: string;
  fps?: string;
  quality?: string;
  skill?: string;
  format?: string;
  "gif-loop"?: string;
  "hls-segment-seconds"?: string;
  "video-frame-format"?: string;
  "page-motion-blur"?: string;
  workers?: string;
  docker?: boolean;
  hdr?: boolean;
  sdr?: boolean;
  crf?: string;
  "video-bitrate"?: string;
  "vp9-cpu-used"?: string;
  gpu?: boolean;
  "browser-gpu"?: boolean;
  quiet?: boolean;
  debug?: boolean;
  "best-effort"?: boolean;
  strict?: boolean;
  "strict-all"?: boolean;
  "lint-verbose"?: boolean;
  "max-concurrent-renders"?: string;
  variables?: string;
  "variables-file"?: string;
  "strict-variables"?: boolean;
  batch?: string;
  "batch-concurrency"?: string;
  "batch-fail-fast"?: boolean;
  json?: boolean;
  resolution?: string;
  "page-side-compositing"?: boolean;
  "browser-timeout"?: string;
  "protocol-timeout"?: string;
  "player-ready-timeout"?: string;
  resume?: boolean;
  "keep-segments"?: boolean;
  "low-memory-mode"?: boolean;
  "experimental-fast-capture"?: boolean;
  "frames-cache-dir"?: string;
}

export interface RenderPlan {
  project: RenderProject;
  entryFile?: string;
  renderTarget: string;
  fps: Fps;
  quality: RenderQuality;
  authoringSkill?: string;
  invalidAuthoringSkill?: string;
  /** Which resolution step provided authoringSkill: an explicit --skill flag, or the project's own config. */
  authoringSkillSource?: "flag" | "project-config";
  /** Catalog items installed in this project, and those the entry reaches. */
  catalogUsage: CatalogUsage;
  format: RenderFormat;
  gifLoop?: number;
  gifFpsCapped: boolean;
  /** HLS target segment length in seconds; only set for `format: "hls"`. */
  hlsSegmentSeconds?: number;
  videoFrameFormat: VideoFrameFormat;
  pageMotionBlur?: "off";
  outputResolution?: CanvasResolution;
  outputResolutionAspectAgnostic: boolean;
  outputResolutionRaw?: string;
  workers?: number;
  protocolTimeout?: number;
  playerReadyTimeout?: number;
  pageNavigationTimeoutMs?: number;
  batchPath?: string;
  batchConcurrency: number;
  batchFailFast: boolean;
  batchOutputTemplate: string;
  outputPath: string;
  useDocker: boolean;
  useGpu: boolean;
  browserGpuMode: BrowserGpuMode;
  quiet: boolean;
  lintVerbose: boolean;
  debug: boolean;
  /** Segmented capture: reuse a prior run's validated segments. */
  resumeSegments: boolean;
  /** Segmented capture: keep the segment directory after success. */
  keepSegments: boolean;
  bestEffort: boolean;
  batchJson: boolean;
  effectiveQuiet: boolean;
  strictAll: boolean;
  strictErrors: boolean;
  crf?: number;
  vp9CpuUsed?: number;
  videoBitrate?: string;
  hdrMode: HdrMode;
  pageSideCompositing: boolean;
  experimentalFastCapture: boolean;
  variablesArg?: string;
  variablesFileArg?: string;
  strictVariables: boolean;
  environment: Readonly<Record<string, string>>;
  /** Names of HF_-/HYPERFRAMES_-prefixed env vars present at plan time (never values), capped at 20. */
  hfEnvOverrides: readonly string[];
}

function formatFpsParseError(
  input: string,
  reason: Exclude<FpsParseResult, { ok: true }>["reason"],
): string {
  switch (reason) {
    case "empty":
      return "Frame rate must not be empty.";
    case "not-a-number":
      return `Got "${input}". Frame rate must be an integer (e.g. 30) or a rational (e.g. 30000/1001 for NTSC).`;
    case "non-positive":
      return `Got "${input}". Frame rate must be greater than zero.`;
    case "out-of-range":
      return `Got "${input}". Frame rate must be in the range 1–240.`;
    case "invalid-fraction":
      return `Got "${input}". Rational frame rates must be two positive integers separated by '/' (e.g. 30000/1001).`;
    case "ambiguous-decimal":
      return `Got "${input}". Decimal frame rates are ambiguous — use the exact rational form instead (e.g. 30000/1001 for 29.97).`;
  }
}

function parseRenderFormat(input: string): RenderFormat | undefined {
  if (!VALID_FORMAT.has(input)) return undefined;
  return RENDER_FORMATS.find((format) => format === input);
}

function positiveInteger(raw: string, title: string, message: string, min = 1): number {
  const parsed = Number(raw);
  if (!Number.isInteger(parsed) || parsed < min) {
    errorBox(title, message);
    failUsage();
  }
  return parsed;
}

const HF_ENV_OVERRIDE_RE = /^(HF|HYPERFRAMES)_/;
const MAX_REPORTED_ENV_OVERRIDES = 20;

/** HF_-prefixed keys the CLI sets for itself during bootstrap rather than keys an operator
 * set to steer a render: cli.ts points shaderTransitionWorkerPool at the worker bundled
 * next to cli.js, so that key is present on essentially every built-CLI run and says
 * nothing about how this render was configured. */
const CLI_INTERNAL_HF_ENV_KEYS = new Set(["HF_SHADER_WORKER_ENTRY"]);

/** Names (never values, since some could hold paths or secrets) of HF_-/HYPERFRAMES_-prefixed
 * env vars present when this plan resolves, snapshotted before this render's own preflight
 * injects its ffmpeg/ffprobe path overrides, which would otherwise always read back as
 * operator-set. */
function resolveHfEnvOverrides(): readonly string[] {
  return Object.keys(process.env)
    .filter((name) => HF_ENV_OVERRIDE_RE.test(name) && !CLI_INTERNAL_HF_ENV_KEYS.has(name))
    .sort()
    .slice(0, MAX_REPORTED_ENV_OVERRIDES);
}

/** Parse and validate command input into an immutable execution plan. */
// fallow-ignore-next-line complexity
export function createRenderPlan(args: RenderCommandArgs, now = new Date()): RenderPlan {
  const pageMotionBlur = parseEnumFlag(args["page-motion-blur"], ["off"] as const, {
    flag: "--page-motion-blur",
  });
  const hfEnvOverrides = resolveHfEnvOverrides();
  const hasExplicitComposition = hasExplicitCompositionArg(args.composition);
  const project = resolveProject(args.dir, { requireIndex: !hasExplicitComposition });
  const entryFile = resolveCompositionEntryArg(args.composition, project.dir, statSync);
  const renderTarget = entryFile ? resolve(project.dir, entryFile) : project.indexPath;
  const fpsArg = resolveDefaultFpsArg(args.fps, project.dir, project.indexPath, entryFile);
  const fpsParse = parseFps(fpsArg ?? "30");
  if (!fpsParse.ok) {
    errorBox("Invalid fps", formatFpsParseError(fpsArg ?? "30", fpsParse.reason));
    failUsage();
  }
  let fps = fpsParse.value;

  const qualityRaw = args.quality ?? "looks";
  if (!(qualityRaw in QUALITY_ALIASES)) {
    errorBox(
      "Invalid quality",
      `Got "${qualityRaw}". Must be draft, looks, delivery, standard, or high.`,
    );
    failUsage();
  }
  const qualityAlias = QUALITY_ALIASES[qualityRaw as keyof typeof QUALITY_ALIASES];
  const quality = qualityAlias.quality;

  // Attribution resolves the explicit --skill flag first, then falls back to
  // the owning skill persisted in hyperframes.json — so re-renders, batch
  // renders, and `npm run render` (which never re-pass the flag) stay
  // attributed to the workflow that created the project.
  const flagSkill = normalizeSkillSlug(args.skill);
  const projectConfigSkill = loadProjectConfig(project.dir).authoringSkill;
  const authoringSkill = flagSkill ?? projectConfigSkill;
  const invalidAuthoringSkill =
    typeof args.skill === "string" && args.skill.trim() !== "" && !flagSkill
      ? args.skill
      : undefined;
  // Same flag-then-project-config resolution as authoringSkill above, named
  // for telemetry (which attribution actually won, not just its value).
  const authoringSkillSource = flagSkill
    ? "flag"
    : projectConfigSkill
      ? "project-config"
      : undefined;

  // Resolved here, once, from the same entry the render will use: batch rows
  // vary only their variables, so every row shares this composition tree.
  const catalogUsage = summarizeCatalogUsage(project.dir, renderTarget);

  const formatRaw = args.format ?? "mp4";
  const format = parseRenderFormat(formatRaw);
  if (!format) {
    errorBox("Invalid format", `Got "${formatRaw}". Must be ${RENDER_FORMAT_LABEL}.`);
    failUsage();
  }

  let gifFpsCapped = false;
  if (format === "gif" && fpsToNumber(fps) > 30) {
    fps = { num: 30, den: 1 };
    gifFpsCapped = true;
  }
  const gifLoopParse = parseGifLoopArg(args["gif-loop"]);
  if (!gifLoopParse.ok) {
    errorBox("Invalid gif-loop", gifLoopParse.message);
    failUsage();
  }
  const gifLoop = gifLoopParse.value ?? (format === "gif" ? 0 : undefined);

  const hlsSegmentParse = parseHlsSegmentSecondsArg(args["hls-segment-seconds"]);
  if (!hlsSegmentParse.ok) {
    errorBox("Invalid hls-segment-seconds", hlsSegmentParse.message);
    failUsage();
  }
  const hlsSegmentSeconds =
    format === "hls" ? (hlsSegmentParse.value ?? DEFAULT_HLS_SEGMENT_SECONDS) : undefined;

  const videoFrameFormatRaw = args["video-frame-format"] ?? "auto";
  if (!isVideoFrameFormat(videoFrameFormatRaw)) {
    errorBox(
      "Invalid video-frame-format",
      `Got "${videoFrameFormatRaw}". Must be auto, jpg, or png.`,
    );
    failUsage();
  }

  let outputResolution: CanvasResolution | undefined;
  let outputResolutionAspectAgnostic = false;
  if (args.resolution !== undefined) {
    outputResolution = normalizeResolutionFlag(args.resolution);
    if (!outputResolution) {
      errorBox(
        "Invalid resolution",
        `Got "${args.resolution}". Must be one of: landscape, portrait, landscape-4k, portrait-4k, square, square-4k ` +
          `(or aliases 1080p, 4k, uhd, 1080p-square, square-1080p, 4k-square).`,
      );
      failUsage();
    }
    outputResolutionAspectAgnostic = isAspectAgnosticResolutionAlias(args.resolution);
    if (args.hdr) {
      errorBox(
        "Conflicting flags",
        "--resolution cannot be combined with --hdr. The HDR pipeline composites at composition dimensions and does not yet support supersampling.",
        "Render in two passes: HDR at composition resolution, then upscale separately with ffmpeg.",
      );
      failUsage();
    }
  }
  if (args.hdr && args.sdr) {
    errorBox("Conflicting flags", "--hdr and --sdr are mutually exclusive.");
    failUsage();
  }
  if (format === "hls" && args.hdr) {
    errorBox(
      "Unsupported HLS output",
      "--hdr cannot be combined with --format hls. HLS output is SDR only (H.264 + AAC in MPEG-TS); HDR10 would need fMP4 segments and HEVC.",
      "Render HDR to MP4, or drop --hdr.",
    );
    failUsage();
  }
  // Fixed-length segments come from the software encoder's forced-keyframe
  // lock, which GPU encoders ignore; the producer rejects the pair too.
  if (format === "hls" && args.gpu) {
    errorBox(
      "Unsupported HLS output",
      "--gpu cannot be combined with --format hls. Fixed-length segments require the software encoder's forced-keyframe lock, which GPU encoders ignore.",
      "Re-run without --gpu.",
    );
    failUsage();
  }

  const workers =
    args.workers != null && args.workers !== "auto"
      ? positiveInteger(
          args.workers,
          "Invalid workers",
          `Got "${args.workers}". Must be a positive number or "auto".`,
        )
      : undefined;
  const protocolTimeout =
    args["protocol-timeout"] != null
      ? positiveInteger(
          args["protocol-timeout"],
          "Invalid protocol-timeout",
          `Got "${args["protocol-timeout"]}". Must be a number >= 1000 (ms).`,
          1000,
        )
      : undefined;
  const playerReadyTimeout =
    args["player-ready-timeout"] != null
      ? positiveInteger(
          args["player-ready-timeout"],
          "Invalid player-ready-timeout",
          `Got "${args["player-ready-timeout"]}". Must be a number >= 1000 (ms).`,
          1000,
        )
      : undefined;

  const environment: Record<string, string> = {};
  if (args["page-side-compositing"] === false) environment.HF_PAGE_SIDE_COMPOSITING = "false";
  if (args["low-memory-mode"] != null) {
    environment.PRODUCER_LOW_MEMORY_MODE = args["low-memory-mode"] ? "true" : "false";
  }
  if (args["experimental-fast-capture"] != null) {
    environment.PRODUCER_EXPERIMENTAL_FAST_CAPTURE = args["experimental-fast-capture"]
      ? "true"
      : "false";
  }
  // Sugar for HYPERFRAMES_EXTRACT_CACHE_DIR. Disabling aliases pass through
  // verbatim for the engine helper; positive paths become CWD-stable here.
  if (typeof args["frames-cache-dir"] === "string" && args["frames-cache-dir"].trim() !== "") {
    const raw = args["frames-cache-dir"].trim();
    const normalized = raw.toLowerCase();
    const isDisableAlias = EXTRACT_CACHE_DIR_DISABLED_ALIASES.includes(normalized);
    environment.HYPERFRAMES_EXTRACT_CACHE_DIR = isDisableAlias ? raw : resolve(raw);
  }
  if (args["max-concurrent-renders"] != null) {
    const parsed = positiveInteger(
      args["max-concurrent-renders"],
      "Invalid max-concurrent-renders",
      `Got "${args["max-concurrent-renders"]}". Must be a number between 1 and 10.`,
    );
    if (parsed > 10) {
      errorBox(
        "Invalid max-concurrent-renders",
        `Got "${args["max-concurrent-renders"]}". Must be a number between 1 and 10.`,
      );
      failUsage();
    }
    environment.PRODUCER_MAX_CONCURRENT_RENDERS = String(parsed);
  }

  const batchPath =
    typeof args.batch === "string" && args.batch.trim() !== "" ? args.batch.trim() : undefined;
  if (batchPath && (args.variables != null || args["variables-file"] != null)) {
    errorBox(
      "Conflicting variables flags",
      "Use either --batch or --variables/--variables-file, not both.",
    );
    failUsage();
  }
  if (!batchPath && args["batch-concurrency"] != null) {
    errorBox("Invalid batch-concurrency", "--batch-concurrency requires --batch.");
    failUsage();
  }
  if (!batchPath && args["batch-fail-fast"]) {
    errorBox("Invalid batch-fail-fast", "--batch-fail-fast requires --batch.");
    failUsage();
  }
  const batchConcurrency =
    args["batch-concurrency"] != null
      ? positiveInteger(
          args["batch-concurrency"],
          "Invalid batch-concurrency",
          `Got "${args["batch-concurrency"]}". Must be a positive integer.`,
        )
      : 1;

  const rendersDir = resolve("renders");
  const ext = FORMAT_EXT[format];
  const timestamp = formatRenderOutputTimestamp(now);
  const batchOutputTemplate = args.output
    ? args.output
    : join(rendersDir, `${project.name}_${timestamp}_{index}${ext}`);
  const outputPath = args.output
    ? resolve(args.output)
    : join(rendersDir, `${project.name}_${timestamp}${ext}`);

  const useDocker = args.docker ?? false;
  const useGpu = args.gpu ?? false;
  const browserGpuMode = resolveBrowserGpuForCli(useDocker, args["browser-gpu"]);
  if (useDocker && args["browser-gpu"] === true) {
    errorBox(
      "Browser GPU is local-only",
      "--browser-gpu uses the host Chrome GPU backend. Docker mode keeps browser rendering deterministic and does not expose a cross-platform Chrome GPU backend.",
      "Run without --docker, or use --gpu for Docker GPU encoding where your Docker host supports GPU passthrough.",
    );
    failUsage();
  }

  const videoBitrate = args["video-bitrate"]?.trim();
  if (args.crf != null && videoBitrate) {
    errorBox("Conflicting encoder settings", "Use either --crf or --video-bitrate, not both.");
    failUsage();
  }
  const crf =
    args.crf != null
      ? positiveInteger(
          args.crf,
          "Invalid crf",
          `Got "${args.crf}". Must be a non-negative integer.`,
          0,
        )
      : format === "mov" || args["video-bitrate"]
        ? undefined
        : "crf" in qualityAlias
          ? qualityAlias.crf
          : undefined;
  let vp9CpuUsed: number | undefined;
  if (args["vp9-cpu-used"] != null) {
    const parsed = Number(args["vp9-cpu-used"]);
    if (!Number.isInteger(parsed) || parsed < MIN_VP9_CPU_USED || parsed > MAX_VP9_CPU_USED) {
      errorBox(
        "Invalid vp9-cpu-used",
        `Got "${args["vp9-cpu-used"]}". Must be an integer between ${MIN_VP9_CPU_USED} and ${MAX_VP9_CPU_USED}.`,
      );
      failUsage();
    }
    vp9CpuUsed = parsed;
  }
  if (args["video-bitrate"] != null && !videoBitrate) {
    errorBox(
      "Invalid video-bitrate",
      `Got "${args["video-bitrate"]}". Must be a non-empty bitrate such as "10M".`,
    );
    failUsage();
  }
  if (format === "mov" && (crf !== undefined || videoBitrate !== undefined)) {
    const flag = crf !== undefined ? "--crf" : "--video-bitrate";
    errorBox(
      "Unsupported ProRes rate control",
      `${flag} does not apply to MOV. MOV uses a fixed alpha-preserving ProRes 4444 profile.`,
      `Remove ${flag}, or choose MP4/WebM when you need CRF or target-bitrate control.`,
    );
    failUsage();
  }

  const quiet = args.quiet ?? false;
  const batchJson = args.json ?? false;
  return Object.freeze({
    project,
    entryFile,
    renderTarget,
    fps,
    quality,
    authoringSkill,
    invalidAuthoringSkill,
    authoringSkillSource,
    catalogUsage,
    format,
    gifLoop,
    gifFpsCapped,
    hlsSegmentSeconds,
    videoFrameFormat: videoFrameFormatRaw,
    pageMotionBlur,
    outputResolution,
    outputResolutionAspectAgnostic,
    outputResolutionRaw: args.resolution,
    workers,
    protocolTimeout,
    playerReadyTimeout,
    pageNavigationTimeoutMs: resolveBrowserTimeoutMsArg(args["browser-timeout"]),
    batchPath,
    batchConcurrency,
    batchFailFast: args["batch-fail-fast"] ?? false,
    batchOutputTemplate,
    outputPath,
    useDocker,
    useGpu,
    browserGpuMode,
    quiet,
    lintVerbose: args["lint-verbose"] ?? false,
    debug: args.debug ?? false,
    resumeSegments: args.resume ?? false,
    keepSegments: args["keep-segments"] ?? false,
    bestEffort: args["best-effort"] ?? true,
    batchJson,
    effectiveQuiet: quiet || (batchPath != null && batchJson),
    strictAll: args["strict-all"] ?? false,
    strictErrors: (args.strict ?? false) || (args["strict-all"] ?? false),
    crf,
    vp9CpuUsed,
    videoBitrate,
    hdrMode: args.sdr ? "force-sdr" : args.hdr ? "force-hdr" : "auto",
    pageSideCompositing: args["page-side-compositing"] !== false,
    experimentalFastCapture: args["experimental-fast-capture"] === true,
    variablesArg: args.variables,
    variablesFileArg: args["variables-file"],
    strictVariables: args["strict-variables"] ?? false,
    environment: Object.freeze(environment),
    hfEnvOverrides,
  });
}

export function applyRenderEnvironment(plan: RenderPlan): void {
  for (const [key, value] of Object.entries(plan.environment)) process.env[key] = value;
}

export function renderOutputDirectory(plan: RenderPlan): string {
  return dirname(plan.outputPath);
}

/** Resolve browser GPU mode from Docker, CLI, env, then the auto default. */
// Re-exported by render.ts to preserve its tested public seam.
export function resolveBrowserGpuForCli(
  useDocker: boolean,
  browserGpuArg: boolean | undefined,
  envMode = process.env.PRODUCER_BROWSER_GPU_MODE,
): BrowserGpuMode {
  if (useDocker) return "software";
  if (browserGpuArg === true) return "hardware";
  if (browserGpuArg === false) return "software";
  if (envMode === "hardware" || envMode === "software" || envMode === "auto") return envMode;
  return "auto";
}