github-featured/heygen-com--hyperframes
2
0
Fork 0
Code Issues Pull Requests Deployments Models Agent Notes Packages Projects Releases Wiki Activity

feat(cli): accept ffmpeg-style rational fps (NTSC, PAL, slow-mo)

Browse Source 
Replaces the rigid `--fps 24|30|60` whitelist with a numeric range and
adds support for ffmpeg-style fractional framerates so NTSC stays exact
end-to-end.

- `--fps 30` keeps working (integer fps)
- `--fps 30000/1001` now means exact NTSC 29.97 (not the lossy decimal)
- `--fps 24000/1001`, `--fps 60000/1001`, `--fps 25/50/120/240` all work
- Decimals like `--fps 29.97` are rejected with a friendly error pointing
  the user at the rational form, since `29.97` and `30000/1001` round
  to different framerates inside ffmpeg

Carries an `Fps = { num: number; den: number }` rational end-to-end:
RenderConfig, EncoderOptions, StreamingEncoderOptions, CaptureOptions,
DockerRenderOptions, Studio API request body, regression-harness
meta.json. The `-r` and `-framerate` ffmpeg args emit the rational form
verbatim (`30000/1001`) so no decimal round-trip happens at the encoder
boundary. Frame-interval math uses `1000 * den / num` ms (33.366… for
NTSC, 33.333… for integer 30).

Helpers live in @hyperframes/core:
- `parseFps(input: string | number): FpsParseResult` — discriminated
  parser used by both the CLI and the Studio API route
- `fpsToFfmpegArg(fps: Fps): string` — emits "30" or "30000/1001"
- `fpsToNumber(fps: Fps): number` — for arithmetic (telemetry, frame
  count, frame-index → time)

Studio API wire format accepts polymorphic `fps: number | string`:
- number → integer fps (`30`)
- string → rational (`"30000/1001"`)
Decimals are rejected; matches the same rule as the CLI.

Existing meta.json fixtures with integer `"fps": 30` continue to load
unchanged — the regression-harness validator now normalizes both number
and string inputs through `parseFps`.
This commit is contained in:
Theodor Kleynhans
2026-05-09 00:09:15 +02:00
parent b58e447305
commit 5dcc89c930
27 changed files with 725 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/cli/src/commands/benchmark.ts
+13 -7
View File
@@ -14,10 +14,11 @@ import { c } from "../ui/colors.js";
import { formatBytes, formatDuration, errorBox } from "../ui/format.js";
import * as clack from "@clack/prompts";
import { withMeta } from "../utils/updateCheck.js";
import { fpsToFfmpegArg } from "@hyperframes/core";
interface BenchmarkConfig {
label: string;
fps: 24 | 30 | 60;
fps: import("@hyperframes/core").Fps;
quality: "draft" | "standard" | "high";
workers: number;
}
@@ -35,12 +36,14 @@ interface ConfigResult {
avgSize: number | null;
}
const FPS_30: import("@hyperframes/core").Fps = { num: 30, den: 1 };
const FPS_60: import("@hyperframes/core").Fps = { num: 60, den: 1 };
const DEFAULT_CONFIGS: BenchmarkConfig[] = [
{ label: "30fps \u00B7 draft \u00B7 2w", fps: 30, quality: "draft", workers: 2 },
{ label: "30fps \u00B7 standard \u00B7 2w", fps: 30, quality: "standard", workers: 2 },
{ label: "30fps \u00B7 high \u00B7 2w", fps: 30, quality: "high", workers: 2 },
{ label: "30fps \u00B7 standard \u00B7 4w", fps: 30, quality: "standard", workers: 4 },
{ label: "60fps \u00B7 standard \u00B7 4w", fps: 60, quality: "standard", workers: 4 },
{ label: "30fps \u00B7 draft \u00B7 2w", fps: FPS_30, quality: "draft", workers: 2 },
{ label: "30fps \u00B7 standard \u00B7 2w", fps: FPS_30, quality: "standard", workers: 2 },
{ label: "30fps \u00B7 high \u00B7 2w", fps: FPS_30, quality: "high", workers: 2 },
{ label: "30fps \u00B7 standard \u00B7 4w", fps: FPS_30, quality: "standard", workers: 4 },
{ label: "60fps \u00B7 standard \u00B7 4w", fps: FPS_60, quality: "standard", workers: 4 },
];
export default defineCommand({
@@ -162,7 +165,10 @@ export default defineCommand({
withMeta({
results: results.map((r) => ({
config: r.config.label,
fps: r.config.fps,
// Emit fps in the on-the-wire form so the JSON payload is
// round-trippable through `parseFps` (e.g. "30000/1001" stays
// exact; integer fps stays integer).
fps: fpsToFfmpegArg(r.config.fps),
quality: r.config.quality,
workers: r.config.workers,
avgTimeMs: r.avgTime,
packages/cli/src/commands/render.test.ts
+11 -11
View File
@@ -68,7 +68,7 @@ describe("renderLocal browser GPU config", () => {
setEnv("PRODUCER_BROWSER_GPU_MODE", "hardware");
await renderLocal("/tmp/project", "/tmp/out.mp4", {
fps: 30,
fps: { num: 30, den: 1 },
quality: "standard",
format: "mp4",
gpu: false,
@@ -86,7 +86,7 @@ describe("renderLocal browser GPU config", () => {
it("forwards browserGpuMode='auto' into producer config (probe-then-choose)", async () => {
await renderLocal("/tmp/project", "/tmp/out.mp4", {
fps: 30,
fps: { num: 30, den: 1 },
quality: "standard",
format: "mp4",
gpu: false,
@@ -104,7 +104,7 @@ describe("renderLocal browser GPU config", () => {
it("passes an explicit hardware override for default local browser GPU", async () => {
await renderLocal("/tmp/project", "/tmp/out.mp4", {
fps: 30,
fps: { num: 30, den: 1 },
quality: "standard",
format: "mp4",
gpu: false,
@@ -137,7 +137,7 @@ describe("renderLocal browser GPU config", () => {
it("forwards parsed --variables payload to createRenderJob", async () => {
await renderLocal("/tmp/project", "/tmp/out.mp4", {
fps: 30,
fps: { num: 30, den: 1 },
quality: "standard",
format: "mp4",
gpu: false,
@@ -152,7 +152,7 @@ describe("renderLocal browser GPU config", () => {
it("forwards format: png-sequence through to createRenderJob", async () => {
await renderLocal("/tmp/project", "/tmp/frames", {
fps: 30,
fps: { num: 30, den: 1 },
quality: "standard",
format: "png-sequence",
gpu: false,
@@ -166,7 +166,7 @@ describe("renderLocal browser GPU config", () => {
it("omits variables from createRenderJob when not provided", async () => {
await renderLocal("/tmp/project", "/tmp/out.mp4", {
fps: 30,
fps: { num: 30, den: 1 },
quality: "standard",
format: "mp4",
gpu: false,
@@ -180,7 +180,7 @@ describe("renderLocal browser GPU config", () => {
it("forwards entryFile to createRenderJob when --composition is set", async () => {
await renderLocal("/tmp/project", "/tmp/out.mp4", {
fps: 30,
fps: { num: 30, den: 1 },
quality: "standard",
format: "mp4",
gpu: false,
@@ -195,7 +195,7 @@ describe("renderLocal browser GPU config", () => {
it("omits entryFile from createRenderJob when --composition is not set", async () => {
await renderLocal("/tmp/project", "/tmp/out.mp4", {
fps: 30,
fps: { num: 30, den: 1 },
quality: "standard",
format: "mp4",
gpu: false,
@@ -209,7 +209,7 @@ describe("renderLocal browser GPU config", () => {
it("forwards outputResolution to createRenderJob when --resolution is set", async () => {
await renderLocal("/tmp/project", "/tmp/out.mp4", {
fps: 30,
fps: { num: 30, den: 1 },
quality: "standard",
format: "mp4",
gpu: false,
@@ -224,7 +224,7 @@ describe("renderLocal browser GPU config", () => {
it("omits outputResolution from createRenderJob by default", async () => {
await renderLocal("/tmp/project", "/tmp/out.mp4", {
fps: 30,
fps: { num: 30, den: 1 },
quality: "standard",
format: "mp4",
gpu: false,
@@ -245,7 +245,7 @@ describe("renderLocal browser GPU config", () => {
});
await renderLocal("/tmp/project", "/tmp/out.mp4", {
fps: 30,
fps: { num: 30, den: 1 },
quality: "standard",
format: "mp4",
gpu: false,
packages/cli/src/commands/render.ts
+52 -11
View File
@@ -51,12 +51,43 @@ import {
validateVariables,
formatVariableValidationIssue,
normalizeResolutionFlag,
parseFps,
fpsToNumber,
fpsToFfmpegArg,
type VariableValidationIssue,
type CanvasResolution,
type Fps,
type FpsParseResult,
} from "@hyperframes/core";
const VALID_FPS = new Set([24, 30, 60]);
const VALID_QUALITY = new Set(["draft", "standard", "high"]);
/**
* Map a {@link FpsParseResult} failure reason to a human-friendly
* error-box message. The empty / undefined / default-fallthrough case
* shouldn't be reachable from the CLI flag (citty supplies a default of
* "30") but the branch exists so this helper can be reused by other
* fps-accepting CLI surfaces in the future.
*/
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).`;
}
}
const VALID_FORMAT = new Set(["mp4", "webm", "mov", "png-sequence"]);
// `png-sequence` writes a directory of frames rather than a single muxed file,
// so its "extension" is empty — the auto-output path becomes a directory name.
@@ -95,7 +126,10 @@ export default defineCommand({
fps: {
type: "string",
alias: "f",
description: "Frame rate: 24, 30, 60",
description:
"Frame rate. Accepts integer (24, 25, 30, 50, 60, 120, 240) or " +
"ffmpeg-style rational (30000/1001 for NTSC 29.97, 24000/1001 for " +
"23.976, 60000/1001 for 59.94). Range 1-240.",
default: "30",
},
quality: {
@@ -194,12 +228,17 @@ export default defineCommand({
const project = resolveProject(args.dir);
// ── Validate fps ───────────────────────────────────────────────────────
const fpsRaw = parseInt(args.fps ?? "30", 10);
if (!VALID_FPS.has(fpsRaw)) {
errorBox("Invalid fps", `Got "${args.fps ?? "30"}". Must be 24, 30, or 60.`);
// Accept either integer (`30`) or ffmpeg-style rational (`30000/1001`).
// The whitelist-based validator was replaced with a sane numeric range so
// legitimate framerates (NTSC trio, PAL, 120/240 slow-mo) work without
// CLI gymnastics. The exact rational survives end-to-end into FFmpeg's
// `-r` / `-framerate` flags via `fpsToFfmpegArg`.
const fpsParse = parseFps(args.fps ?? "30");
if (!fpsParse.ok) {
errorBox("Invalid fps", formatFpsParseError(args.fps ?? "30", fpsParse.reason));
process.exit(1);
}
const fps = fpsRaw as 24 | 30 | 60;
const fps: Fps = fpsParse.value;
// ── Validate quality ───────────────────────────────────────────────────
const qualityRaw = args.quality ?? "standard";
@@ -354,7 +393,9 @@ export default defineCommand({
console.log(
c.accent("\u25C6") + " Rendering " + c.accent(nameLabel) + c.dim(" \u2192 " + outputPath),
);
console.log(c.dim(" " + fps + "fps \u00B7 " + quality + " \u00B7 " + workerLabel));
console.log(
c.dim(" " + fpsToFfmpegArg(fps) + "fps \u00B7 " + quality + " \u00B7 " + workerLabel),
);
if (outputResolution) {
// Don't claim "supersampled" — when the composition is already at the
// target dimensions, the DPR resolves to 1 and no supersampling
@@ -521,7 +562,7 @@ export default defineCommand({
});
interface RenderOptions {
fps: 24 | 30 | 60;
fps: Fps;
quality: "draft" | "standard" | "high";
format: "mp4" | "webm" | "mov" | "png-sequence";
workers?: number;
@@ -865,7 +906,7 @@ async function renderDocker(
// Track metrics (no job object available from Docker — use a minimal stub)
trackRenderComplete({
durationMs: elapsed,
fps: options.fps,
fps: fpsToNumber(options.fps),
quality: options.quality,
workers: options.workers,
docker: true,
@@ -964,7 +1005,7 @@ function handleRenderError(
): never {
const message = error instanceof Error ? error.message : String(error);
trackRenderError({
fps: options.fps,
fps: fpsToNumber(options.fps),
quality: options.quality,
docker,
workers: options.workers,
@@ -1001,7 +1042,7 @@ function trackRenderMetrics(
trackRenderComplete({
durationMs: elapsedMs,
fps: options.fps,
fps: fpsToNumber(options.fps),
quality: options.quality,
workers: options.workers ?? perf?.workers,
docker,
packages/cli/src/server/studioServer.ts
+3 -1
View File
@@ -213,7 +213,9 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
}
const job = createRenderJob({
fps: opts.fps as 24 | 30 | 60,
// opts.fps is already an Fps rational — see vite-config-studio
// adapter for the same convention.
fps: opts.fps,
quality: opts.quality as "draft" | "standard" | "high",
format: opts.format,
outputResolution: opts.outputResolution,
packages/cli/src/utils/dockerRunArgs.test.ts
+25 -2
View File
@@ -2,7 +2,7 @@ import { describe, expect, it } from "vitest";
import { buildDockerRunArgs, type DockerRenderOptions } from "./dockerRunArgs.js";
const BASE: DockerRenderOptions = {
fps: 30,
fps: { num: 30, den: 1 },
quality: "standard",
format: "mp4",
gpu: false,
@@ -151,7 +151,7 @@ describe("buildDockerRunArgs", () => {
const args = buildDockerRunArgs({
...FIXED_INPUT,
options: {
fps: 60,
fps: { num: 60, den: 1 },
quality: "high",
format: "webm",
workers: 8,
@@ -240,6 +240,29 @@ describe("buildDockerRunArgs", () => {
expect(args).not.toContain("--composition");
});
it("forwards rational --fps verbatim (NTSC 30000/1001)", () => {
// Regression for the fps fraction-syntax feature: the rational form must
// survive the host → container hop as a single `30000/1001` argument so
// the in-container CLI re-parses it as exact NTSC, not 29.97 decimal.
const args = buildDockerRunArgs({
...FIXED_INPUT,
options: { ...BASE, fps: { num: 30000, den: 1001 } },
});
const fpsIdx = args.indexOf("--fps");
expect(fpsIdx).toBeGreaterThanOrEqual(0);
expect(args[fpsIdx + 1]).toBe("30000/1001");
});
it("forwards integer --fps as a bare integer string", () => {
const args = buildDockerRunArgs({
...FIXED_INPUT,
options: { ...BASE, fps: { num: 60, den: 1 } },
});
const fpsIdx = args.indexOf("--fps");
expect(fpsIdx).toBeGreaterThanOrEqual(0);
expect(args[fpsIdx + 1]).toBe("60");
});
it("forwards --resolution to the container when outputResolution is set", () => {
const args = buildDockerRunArgs({
...FIXED_INPUT,
packages/cli/src/utils/dockerRunArgs.ts
+10 -2
View File
@@ -7,6 +7,8 @@
* a test in `dockerRunArgs.test.ts` — that combination is what catches
* silent-drop regressions like the one that lost `--hdr` historically.
*/
import { fpsToFfmpegArg, type Fps } from "@hyperframes/core";
export interface DockerRunArgsInput {
imageTag: string;
/** Absolute host path to the project directory (mounted read-only at /project). */
@@ -19,7 +21,13 @@ export interface DockerRunArgsInput {
}
export interface DockerRenderOptions {
fps: 24 | 30 | 60;
/**
* Frame rate as an exact rational; see `Fps` in @hyperframes/core. The
* docker-run arg builder serializes this back to a `--fps` string
* (`"30"` or `"30000/1001"`) which the in-container CLI re-parses with
* `parseFps`, so the rational survives the host → container hop.
*/
fps: Fps;
quality: "draft" | "standard" | "high";
format: "mp4" | "webm" | "mov" | "png-sequence";
workers?: number;
@@ -54,7 +62,7 @@ export function buildDockerRunArgs(input: DockerRunArgsInput): string[] {
"--output",
`/output/${outputFilename}`,
"--fps",
String(options.fps),
fpsToFfmpegArg(options.fps),
"--quality",
options.quality,
"--format",
packages/core/src/core.types.ts
+125
View File
@@ -2,6 +2,131 @@
export type ExecutionMode = "planning" | "design" | "execution" | null;
// ── Frame rate ──────────────────────────────────────────────────────────────
/**
* Frame rate as an exact rational. Carrying `{num, den}` end-to-end (rather
* than collapsing to `29.97`) lets us pass NTSC / drop-frame rates straight
* through to FFmpeg via `-r 30000/1001` without any decimal round-trip.
*
* Integer fps is represented with `den: 1` (e.g. `{ num: 30, den: 1 }`).
*
* Use {@link fpsToNumber} when arithmetic forces a decimal (e.g. `setTimeout`
* intervals) and {@link fpsToFfmpegArg} when emitting FFmpeg `-r` /
* `-framerate` strings.
*/
export interface Fps {
num: number;
den: number;
}
/**
* Decimal value of an {@link Fps} rational. Used at sites that need a
* `number` for arithmetic (frame-index → time, frame intervals, telemetry
* payloads) where the small precision loss of the decimal is acceptable.
*/
export function fpsToNumber(fps: Fps): number {
return fps.num / fps.den;
}
/**
* FFmpeg-style fps argument. Returns `"30"` for integer fps and `"30000/1001"`
* for rationals — both forms are accepted verbatim by FFmpeg's `-r` and
* `-framerate` flags. We keep integer fps as a bare integer so existing
* snapshot tests / log output don't churn for the common case.
*/
export function fpsToFfmpegArg(fps: Fps): string {
return fps.den === 1 ? String(fps.num) : `${fps.num}/${fps.den}`;
}
/**
* Discriminated parse result for {@link parseFps}. Lets the CLI / route
* validation own its own error UX without losing the structured failure
* reason.
*/
export type FpsParseResult =
| { ok: true; value: Fps }
| {
ok: false;
reason:
| "empty"
| "not-a-number"
| "non-positive"
| "out-of-range"
| "invalid-fraction"
| "ambiguous-decimal";
};
/**
* Parse a user-supplied fps spec into an {@link Fps} rational.
*
* Accepted forms:
* - integer string `"30"` → `{ num: 30, den: 1 }`
* - integer number `30` → `{ num: 30, den: 1 }`
* - rational string `"30000/1001"` → `{ num: 30000, den: 1001 }` (exact NTSC)
*
* Rejected:
* - empty / non-numeric input
* - decimals like `"29.97"` — callers must spell rationals with `/` so the
* exact denominator is unambiguous (FFmpeg treats `29.97` as a slightly
* different framerate than `30000/1001`).
* - division by zero, negative or zero numerator
* - decimal value outside `[1, 240]` — defensive bounds for "human" fps
* ranges (24, 25, 30, 50, 60, 120, 240, plus the NTSC trio).
*/
export function parseFps(input: string | number): FpsParseResult {
if (typeof input === "number") {
if (!Number.isFinite(input)) return { ok: false, reason: "not-a-number" };
if (!Number.isInteger(input)) return { ok: false, reason: "ambiguous-decimal" };
if (input <= 0) return { ok: false, reason: "non-positive" };
if (input > 240) return { ok: false, reason: "out-of-range" };
return { ok: true, value: { num: input, den: 1 } };
}
const raw = input.trim();
if (raw === "") return { ok: false, reason: "empty" };
if (raw.includes("/")) {
const parts = raw.split("/");
if (parts.length !== 2) return { ok: false, reason: "invalid-fraction" };
const num = Number(parts[0]);
const den = Number(parts[1]);
if (!Number.isFinite(num) || !Number.isFinite(den)) {
return { ok: false, reason: "not-a-number" };
}
if (!Number.isInteger(num) || !Number.isInteger(den)) {
return { ok: false, reason: "invalid-fraction" };
}
if (den <= 0) return { ok: false, reason: "invalid-fraction" };
if (num <= 0) return { ok: false, reason: "non-positive" };
const decimal = num / den;
if (decimal < 1 || decimal > 240) return { ok: false, reason: "out-of-range" };
return { ok: true, value: { num, den } };
}
// Integer-only path — reject `"29.97"` so users are explicit about the
// exact rational they want.
if (!/^-?\d+$/.test(raw)) {
// Allow caller to differentiate "29.97" from "abc" if they want; both
// are user errors but the message can be friendlier for decimals.
if (/^-?\d*\.\d+$/.test(raw)) return { ok: false, reason: "ambiguous-decimal" };
return { ok: false, reason: "not-a-number" };
}
const n = Number(raw);
if (n <= 0) return { ok: false, reason: "non-positive" };
if (n > 240) return { ok: false, reason: "out-of-range" };
return { ok: true, value: { num: n, den: 1 } };
}
/**
* Convenience wrapper around {@link parseFps} for callsites that want the
* default-30-fps fallback when input is `undefined`. Does NOT swallow parse
* errors — those still surface via the discriminated result.
*/
export function parseFpsWithDefault(input: string | number | undefined): FpsParseResult {
if (input === undefined || input === "") return { ok: true, value: { num: 30, den: 1 } };
return parseFps(input);
}
/** Video orientation / aspect ratio. */
export type Orientation = "16:9" | "9:16";
packages/core/src/index.ts
+6
View File
@@ -11,6 +11,8 @@ export type {
TimelineElementType,
MediaElementType,
CanvasResolution,
Fps,
FpsParseResult,
MediaFile,
CompositionAPI,
PlayerAPI,
@@ -38,6 +40,10 @@ export {
CANVAS_DIMENSIONS,
VALID_CANVAS_RESOLUTIONS,
normalizeResolutionFlag,
parseFps,
parseFpsWithDefault,
fpsToNumber,
fpsToFfmpegArg,
TIMELINE_COLORS,
DEFAULT_DURATIONS,
COMPOSITION_VARIABLE_TYPES,
packages/core/src/parseFps.test.ts
+158
View File
@@ -0,0 +1,158 @@
import { describe, expect, it } from "vitest";
import { parseFps, fpsToNumber, fpsToFfmpegArg } from "./core.types";
describe("parseFps — integer forms", () => {
it("parses integer string '30' as { num: 30, den: 1 }", () => {
const result = parseFps("30");
expect(result.ok).toBe(true);
if (result.ok) expect(result.value).toEqual({ num: 30, den: 1 });
});
it("parses integer number 30 as { num: 30, den: 1 }", () => {
const result = parseFps(30);
expect(result.ok).toBe(true);
if (result.ok) expect(result.value).toEqual({ num: 30, den: 1 });
});
it("parses '24' / '60' / '120' / '240' as integer fps with den=1", () => {
for (const n of [24, 60, 120, 240]) {
const result = parseFps(String(n));
expect(result.ok).toBe(true);
if (result.ok) expect(result.value).toEqual({ num: n, den: 1 });
}
});
it("trims surrounding whitespace on integer strings", () => {
const result = parseFps(" 30 ");
expect(result.ok).toBe(true);
if (result.ok) expect(result.value).toEqual({ num: 30, den: 1 });
});
});
describe("parseFps — rational forms", () => {
it("parses '30000/1001' as exact NTSC", () => {
const result = parseFps("30000/1001");
expect(result.ok).toBe(true);
if (result.ok) expect(result.value).toEqual({ num: 30000, den: 1001 });
});
it("parses '24000/1001' as 23.976", () => {
const result = parseFps("24000/1001");
expect(result.ok).toBe(true);
if (result.ok) expect(result.value).toEqual({ num: 24000, den: 1001 });
});
it("parses '60000/1001' as 59.94", () => {
const result = parseFps("60000/1001");
expect(result.ok).toBe(true);
if (result.ok) expect(result.value).toEqual({ num: 60000, den: 1001 });
});
it("parses '60/2' as { num: 60, den: 2 } (no auto-simplification)", () => {
// Preserving the literal numerator/denominator keeps `fpsToFfmpegArg`
// round-trippable — if the user typed the rational form, we forward it
// verbatim to ffmpeg.
const result = parseFps("60/2");
expect(result.ok).toBe(true);
if (result.ok) expect(result.value).toEqual({ num: 60, den: 2 });
});
});
describe("parseFps — rejected inputs", () => {
it("rejects 'abc'", () => {
const result = parseFps("abc");
expect(result.ok).toBe(false);
if (!result.ok) expect(result.reason).toBe("not-a-number");
});
it("rejects '30/0' (zero denominator)", () => {
const result = parseFps("30/0");
expect(result.ok).toBe(false);
if (!result.ok) expect(result.reason).toBe("invalid-fraction");
});
it("rejects '30/-1' (negative denominator)", () => {
const result = parseFps("30/-1");
expect(result.ok).toBe(false);
if (!result.ok) expect(result.reason).toBe("invalid-fraction");
});
it("rejects '0' (non-positive)", () => {
const result = parseFps("0");
expect(result.ok).toBe(false);
if (!result.ok) expect(result.reason).toBe("non-positive");
});
it("rejects '241' (out of range)", () => {
const result = parseFps("241");
expect(result.ok).toBe(false);
if (!result.ok) expect(result.reason).toBe("out-of-range");
});
it("rejects '29.97' (ambiguous decimal — must spell rational)", () => {
// The whole point of taking rationals is precision; accepting the
// decimal form silently would invert that guarantee.
const result = parseFps("29.97");
expect(result.ok).toBe(false);
if (!result.ok) expect(result.reason).toBe("ambiguous-decimal");
});
it("rejects empty string", () => {
const result = parseFps("");
expect(result.ok).toBe(false);
if (!result.ok) expect(result.reason).toBe("empty");
});
it("rejects '30000/1001/extra' (too many slashes)", () => {
const result = parseFps("30000/1001/extra");
expect(result.ok).toBe(false);
if (!result.ok) expect(result.reason).toBe("invalid-fraction");
});
it("rejects rational with decimal numerator '30.5/1'", () => {
const result = parseFps("30.5/1");
expect(result.ok).toBe(false);
if (!result.ok) expect(result.reason).toBe("invalid-fraction");
});
it("rejects rational > 240 by decimal value", () => {
// 1000/3 ≈ 333.33 — even though numerator and denominator are integers,
// the decimal value is out of the supported range.
const result = parseFps("1000/3");
expect(result.ok).toBe(false);
if (!result.ok) expect(result.reason).toBe("out-of-range");
});
});
describe("fpsToNumber + fpsToFfmpegArg + frame interval math", () => {
it("integer fps 30/1 → 33.333…ms frame interval", () => {
const fps = { num: 30, den: 1 };
const intervalMs = (1000 * fps.den) / fps.num;
expect(intervalMs).toBeCloseTo(33.333, 3);
});
it("NTSC 30000/1001 → 33.366…ms frame interval", () => {
const fps = { num: 30000, den: 1001 };
const intervalMs = (1000 * fps.den) / fps.num;
// 1001/30 = 33.36666…ms — the canonical NTSC interval. Differs from
// the integer-30 interval by ~0.033 ms (1 ULP at our scales).
expect(intervalMs).toBeCloseTo(33.36666, 3);
expect(intervalMs).not.toBeCloseTo(33.333, 3);
});
it("fpsToNumber collapses rational to decimal", () => {
expect(fpsToNumber({ num: 30, den: 1 })).toBe(30);
expect(fpsToNumber({ num: 30000, den: 1001 })).toBeCloseTo(29.97003, 5);
});
it("fpsToFfmpegArg emits bare integer for den=1", () => {
expect(fpsToFfmpegArg({ num: 30, den: 1 })).toBe("30");
expect(fpsToFfmpegArg({ num: 60, den: 1 })).toBe("60");
});
it("fpsToFfmpegArg emits 'num/den' for rationals", () => {
expect(fpsToFfmpegArg({ num: 30000, den: 1001 })).toBe("30000/1001");
expect(fpsToFfmpegArg({ num: 24000, den: 1001 })).toBe("24000/1001");
expect(fpsToFfmpegArg({ num: 60000, den: 1001 })).toBe("60000/1001");
});
});
packages/core/src/studio-api/routes/render.test.ts
+68
View File
@@ -115,3 +115,71 @@ describe("POST /projects/:id/render — outputResolution forwarding", () => {
}
});
});
describe("POST /projects/:id/render — fps wire format", () => {
// The fps fraction-syntax feature accepts JSON `number` (integer fps) and
// JSON `string` (ffmpeg-style rational) on the wire, normalizing both to
// the structured Fps form before invoking the adapter.
it("forwards integer fps as { num, den: 1 }", async () => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ fps: 60, quality: "standard", format: "mp4" }),
});
expect(spy.mock.calls[0][0].fps).toEqual({ num: 60, den: 1 });
} finally {
cleanup();
}
});
it("parses '30000/1001' string body as exact NTSC", async () => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ fps: "30000/1001", quality: "standard", format: "mp4" }),
});
expect(spy.mock.calls[0][0].fps).toEqual({ num: 30000, den: 1001 });
} finally {
cleanup();
}
});
it("falls back to 30/1 for malformed fps values", async () => {
// Matches the lenient handling of `quality` and `resolution` in the same
// route — the producer surfaces a clearer downstream error if the value
// is genuinely unusable.
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ fps: "abc", quality: "standard", format: "mp4" }),
});
expect(spy.mock.calls[0][0].fps).toEqual({ num: 30, den: 1 });
} finally {
cleanup();
}
});
it("falls back to 30/1 when fps is omitted", async () => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ quality: "standard", format: "mp4" }),
});
expect(spy.mock.calls[0][0].fps).toEqual({ num: 30, den: 1 });
} finally {
cleanup();
}
});
});
packages/core/src/studio-api/routes/render.ts
+14 -3
View File
@@ -3,7 +3,7 @@ import { streamSSE } from "hono/streaming";
import { existsSync, readFileSync, mkdirSync, unlinkSync, readdirSync, statSync } from "node:fs";
import { join } from "node:path";
import type { StudioApiAdapter, RenderJobState } from "../types.js";
import { VALID_CANVAS_RESOLUTIONS, type CanvasResolution } from "../../core.types.js";
import { VALID_CANVAS_RESOLUTIONS, parseFps, type CanvasResolution } from "../../core.types.js";
const VALID_RESOLUTIONS = new Set<string>(VALID_CANVAS_RESOLUTIONS);
@@ -50,7 +50,12 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): void
if (!project) return c.json({ error: "not found" }, 404);
const body = (await c.req.json().catch(() => ({}))) as {
fps?: number;
// Polymorphic per design note in core.types.Fps:
// number → integer fps (e.g. 30)
// string → rational fps (e.g. "30000/1001" for NTSC 29.97)
// Decimals are rejected on purpose so the exact denominator stays
// unambiguous (29.97 ≠ 30000/1001 when ffmpeg consumes them).
fps?: number | string;
quality?: string;
format?: string;
resolution?: string;
@@ -58,7 +63,13 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): void
const VALID_FORMATS = new Set(["mp4", "webm", "mov"]);
const FORMAT_EXT: Record<string, string> = { mp4: ".mp4", webm: ".webm", mov: ".mov" };
const format = VALID_FORMATS.has(body.format ?? "") ? (body.format as string) : "mp4";
const fps: 24 | 30 | 60 = body.fps === 24 || body.fps === 60 ? body.fps : 30;
// Default to 30 fps when unset or unparseable. The route stays lenient on
// invalid fps values (matching the lenient handling of `resolution` and
// `quality` already in this file) — the producer surfaces a clearer error
// message if the caller really did mean to fail loudly.
const fpsParse = body.fps === undefined ? null : parseFps(body.fps);
const fps = fpsParse && fpsParse.ok ? fpsParse.value : { num: 30, den: 1 };
const quality = ["draft", "standard", "high"].includes(body.quality ?? "")
? (body.quality as string)
: "standard";
packages/core/src/studio-api/types.ts
+8 -1
View File
@@ -63,7 +63,14 @@ export interface StudioApiAdapter {
project: ResolvedProject;
outputPath: string;
format: "mp4" | "webm" | "mov";
fps: number;
/**
* Frame rate as an exact rational. The HTTP layer (POST
* `/projects/:id/render`) accepts either a JSON number (integer fps,
* `30`) or a JSON string (ffmpeg-style rational, `"30000/1001"`); the
* route normalizes both into `Fps` before invoking the adapter, so
* adapter implementations only ever see the rational form.
*/
fps: import("../core.types.js").Fps;
quality: string;
jobId: string;
/**
packages/engine/src/services/chunkEncoder.test.ts
+31 -4
View File
@@ -79,7 +79,7 @@ describe("getEncoderPreset", () => {
});
describe("buildEncoderArgs anti-banding", () => {
const baseOptions = { fps: 30, width: 1920, height: 1080 };
const baseOptions = { fps: { num: 30, den: 1 }, width: 1920, height: 1080 };
it("adds aq-mode=3 x264-params for h264 CPU encoding", () => {
const args = buildEncoderArgs(
@@ -148,8 +148,35 @@ describe("buildEncoderArgs anti-banding", () => {
});
});
describe("buildEncoderArgs fps rational forwarding", () => {
// Regression for the fps fraction-syntax feature: rational fps must reach
// ffmpeg's `-r` flag verbatim (e.g. "30000/1001") so NTSC stays exact end-
// to-end rather than being rounded to 29.97 decimal at the encoder boundary.
it("emits integer -r for { num: 30, den: 1 }", () => {
const args = buildEncoderArgs(
{ fps: { num: 30, den: 1 }, width: 1920, height: 1080, codec: "h264" },
["-framerate", "30", "-i", "frames/%04d.png"],
"out.mp4",
);
const rIdx = args.indexOf("-r");
expect(rIdx).toBeGreaterThan(-1);
expect(args[rIdx + 1]).toBe("30");
});
it("emits rational -r for NTSC { num: 30000, den: 1001 }", () => {
const args = buildEncoderArgs(
{ fps: { num: 30000, den: 1001 }, width: 1920, height: 1080, codec: "h264" },
["-framerate", "30000/1001", "-i", "frames/%04d.png"],
"out.mp4",
);
const rIdx = args.indexOf("-r");
expect(rIdx).toBeGreaterThan(-1);
expect(args[rIdx + 1]).toBe("30000/1001");
});
});
describe("buildEncoderArgs GPU preset mapping", () => {
const baseOptions = { fps: 30, width: 1920, height: 1080 };
const baseOptions = { fps: { num: 30, den: 1 }, width: 1920, height: 1080 };
const inputArgs = ["-framerate", "30", "-i", "frames/%04d.png"];
function presetArg(args: string[]): string | undefined {
@@ -232,7 +259,7 @@ describe("buildEncoderArgs GPU preset mapping", () => {
});
describe("buildEncoderArgs color space", () => {
const baseOptions = { fps: 30, width: 1920, height: 1080 };
const baseOptions = { fps: { num: 30, den: 1 }, width: 1920, height: 1080 };
const inputArgs = ["-framerate", "30", "-i", "frames/%04d.png"];
it("adds bt709 color space metadata for h264 CPU encoding", () => {
@@ -365,7 +392,7 @@ describe("getEncoderPreset HDR", () => {
});
describe("buildEncoderArgs HDR color space", () => {
const baseOptions = { fps: 30, width: 1920, height: 1080 };
const baseOptions = { fps: { num: 30, den: 1 }, width: 1920, height: 1080 };
const inputArgs = ["-framerate", "30", "-i", "frames/%04d.png"];
it("emits BT.2020 + arib-std-b67 tags for HDR HLG (h265 SW)", () => {
packages/engine/src/services/chunkEncoder.ts
+4 -3
View File
@@ -17,6 +17,7 @@ import {
} from "../utils/gpuEncoder.js";
import { type HdrTransfer, getHdrEncoderColorParams } from "../utils/hdr.js";
import { formatFfmpegError, runFfmpeg } from "../utils/runFfmpeg.js";
import { fpsToFfmpegArg } from "@hyperframes/core";
import type { EncoderOptions, EncodeResult, MuxResult } from "./chunkEncoder.types.js";
export type { EncoderOptions, EncodeResult, MuxResult } from "./chunkEncoder.types.js";
@@ -105,7 +106,7 @@ export function buildEncoderArgs(
options = { ...options, hdr: undefined };
}
const args: string[] = [...inputArgs, "-r", String(fps)];
const args: string[] = [...inputArgs, "-r", fpsToFfmpegArg(fps)];
const shouldUseGpu = useGpu && gpuEncoder !== null;
if (codec === "h264" || codec === "h265") {
@@ -309,7 +310,7 @@ export async function encodeFramesFromDir(
}
const inputPath = join(framesDir, framePattern);
const inputArgs = ["-framerate", String(options.fps), "-i", inputPath];
const inputArgs = ["-framerate", fpsToFfmpegArg(options.fps), "-i", inputPath];
const args = buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder);
return new Promise((resolve) => {
@@ -432,7 +433,7 @@ export async function encodeFramesChunkedConcat(
const inputPath = join(framesDir, framePattern);
const inputArgs = [
"-framerate",
String(options.fps),
fpsToFfmpegArg(options.fps),
"-start_number",
String(startNumber),
"-i",
packages/engine/src/services/chunkEncoder.types.ts
+3 -1
View File
@@ -1,7 +1,9 @@
import type { HdrTransfer } from "../utils/hdr.js";
import type { Fps } from "@hyperframes/core";
export interface EncoderOptions {
fps: number;
/** Frame rate as an exact rational; see `Fps` in @hyperframes/core. */
fps: Fps;
width: number;
height: number;
codec?: "h264" | "h265" | "vp9" | "prores";
packages/engine/src/services/frameCapture.ts
+6 -3
View File
@@ -10,7 +10,7 @@
import { type Browser, type Page, type Viewport, type ConsoleMessage } from "puppeteer-core";
import { existsSync, mkdirSync, writeFileSync } from "fs";
import { join } from "path";
import { quantizeTimeToFrame } from "@hyperframes/core";
import { quantizeTimeToFrame, fpsToNumber } from "@hyperframes/core";
// ── Extracted modules ───────────────────────────────────────────────────────
import {
@@ -228,7 +228,10 @@ export async function createCaptureSession(
},
captureMode,
beginFrameTimeTicks: 0,
beginFrameIntervalMs: 1000 / Math.max(1, options.fps),
// Frame interval in ms: 1000 * den / num. For 30/1 → 33.333…, for
// 30000/1001 (NTSC) → 33.366…. JavaScript number precision is fine at
// these scales — no rounding required.
beginFrameIntervalMs: (1000 * options.fps.den) / Math.max(1, options.fps.num),
beginFrameHasDamageCount: 0,
beginFrameNoDamageCount: 0,
config,
@@ -591,7 +594,7 @@ async function prepareFrameForCapture(
throw new Error("[FrameCapture] Session not initialized");
}
const quantizedTime = quantizeTimeToFrame(time, options.fps);
const quantizedTime = quantizeTimeToFrame(time, fpsToNumber(options.fps));
const seekStart = Date.now();
// Seek via the __hf protocol. The page's seek() implementation handles
packages/engine/src/services/parallelCoordinator.ts
+4 -1
View File
@@ -185,7 +185,10 @@ async function executeWorkerTask(
if (signal?.aborted) {
throw new Error("Parallel worker cancelled");
}
const time = i / captureOptions.fps;
// captureOptions.fps is an Fps rational; collapse to decimal for the
// frame-index → time math. The 1-in-1001 ULP loss for NTSC is invisible
// at our scales (frame count tops out at single-digit thousands).
const time = (i * captureOptions.fps.den) / captureOptions.fps.num;
if (onFrameBuffer) {
// Streaming mode: capture to buffer and invoke callback
packages/engine/src/services/screenshotService.test.ts
+4 -4
View File
@@ -27,7 +27,7 @@ describe("pageScreenshotCapture supersample plumbing", () => {
await pageScreenshotCapture(page, {
width: 1920,
height: 1080,
fps: 30,
fps: { num: 30, den: 1 },
format: "jpeg",
quality: 80,
});
@@ -45,7 +45,7 @@ describe("pageScreenshotCapture supersample plumbing", () => {
await pageScreenshotCapture(page, {
width: 1920,
height: 1080,
fps: 30,
fps: { num: 30, den: 1 },
format: "jpeg",
deviceScaleFactor: 1,
});
@@ -61,7 +61,7 @@ describe("pageScreenshotCapture supersample plumbing", () => {
await pageScreenshotCapture(page, {
width: 1920,
height: 1080,
fps: 30,
fps: { num: 30, den: 1 },
format: "jpeg",
deviceScaleFactor: 2,
});
@@ -81,7 +81,7 @@ describe("pageScreenshotCapture supersample plumbing", () => {
await pageScreenshotCapture(page, {
width: 1280,
height: 720,
fps: 30,
fps: { num: 30, den: 1 },
format: "jpeg",
deviceScaleFactor: 3,
});
packages/engine/src/services/streamingEncoder.test.ts
+47 -4
View File
@@ -23,7 +23,7 @@ import {
import { DEFAULT_HDR10_MASTERING } from "../utils/hdr.js";
const baseHdrPq: StreamingEncoderOptions = {
fps: 30,
fps: { num: 30, den: 1 },
width: 1920,
height: 1080,
codec: "h265",
@@ -41,7 +41,7 @@ const baseHdrHlg: StreamingEncoderOptions = {
};
const baseSdr: StreamingEncoderOptions = {
fps: 30,
fps: { num: 30, den: 1 },
width: 1920,
height: 1080,
codec: "h264",
@@ -166,9 +166,52 @@ describe("buildStreamingArgs", () => {
});
});
describe("fps rational forwarding", () => {
// Regression for the fps fraction-syntax feature: both `-framerate`
// (input timestamping) and `-r` (output framerate) must carry the
// rational verbatim — collapsing to 29.97 decimal at this boundary
// would defeat the whole point of supporting NTSC end-to-end.
it("emits rational -framerate and -r for NTSC 30000/1001 (image2pipe)", () => {
const sdrNtsc: StreamingEncoderOptions = {
...baseSdr,
fps: { num: 30000, den: 1001 },
};
const args = buildStreamingArgs(sdrNtsc, "/tmp/ntsc.mp4");
const framerateIdx = args.indexOf("-framerate");
expect(framerateIdx).toBeGreaterThan(-1);
expect(args[framerateIdx + 1]).toBe("30000/1001");
const rIdx = args.indexOf("-r");
expect(rIdx).toBeGreaterThan(-1);
expect(args[rIdx + 1]).toBe("30000/1001");
});
it("emits rational -framerate and -r for NTSC 30000/1001 (rawvideo HDR)", () => {
const hdrNtsc: StreamingEncoderOptions = {
...baseHdrPq,
fps: { num: 30000, den: 1001 },
};
const args = buildStreamingArgs(hdrNtsc, "/tmp/ntsc-hdr.mp4");
const framerateIdx = args.indexOf("-framerate");
expect(framerateIdx).toBeGreaterThan(-1);
expect(args[framerateIdx + 1]).toBe("30000/1001");
const rIdx = args.indexOf("-r");
expect(rIdx).toBeGreaterThan(-1);
expect(args[rIdx + 1]).toBe("30000/1001");
});
it("emits bare integer -r for { num: 30, den: 1 }", () => {
const args = buildStreamingArgs(baseSdr, "/tmp/30.mp4");
const rIdx = args.indexOf("-r");
expect(rIdx).toBeGreaterThan(-1);
expect(args[rIdx + 1]).toBe("30");
});
});
describe("GPU preset mapping", () => {
const baseGpu: StreamingEncoderOptions = {
fps: 30,
fps: { num: 30, den: 1 },
width: 1920,
height: 1080,
codec: "h264",
@@ -348,7 +391,7 @@ function createSpawnSpy(): {
}
const baseOptions: StreamingEncoderOptions = {
fps: 30,
fps: { num: 30, den: 1 },
width: 100,
height: 100,
codec: "h264",
packages/engine/src/services/streamingEncoder.ts
+15 -4
View File
@@ -26,6 +26,7 @@ import { formatFfmpegError } from "../utils/runFfmpeg.js";
import { getHdrEncoderColorParams } from "../utils/hdr.js";
import { type EncoderOptions } from "./chunkEncoder.types.js";
import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
import { fpsToFfmpegArg, type Fps } from "@hyperframes/core";
// Re-export EncoderOptions so callers can reference the type via this module.
export type { EncoderOptions } from "./chunkEncoder.types.js";
@@ -99,7 +100,8 @@ export function createFrameReorderBuffer(startFrame: number, endFrame: number):
// ---------------------------------------------------------------------------
export interface StreamingEncoderOptions {
fps: number;
/** Frame rate as an exact rational; see `Fps` in @hyperframes/core. */
fps: Fps;
width: number;
height: number;
codec?: "h264" | "h265" | "vp9" | "prores";
@@ -169,7 +171,7 @@ export function buildStreamingArgs(
"-s",
`${options.width}x${options.height}`,
"-framerate",
String(fps),
fpsToFfmpegArg(fps),
);
if (inputColorTrc) {
args.push(
@@ -184,9 +186,18 @@ export function buildStreamingArgs(
args.push("-i", "-");
} else {
const inputCodec = imageFormat === "png" ? "png" : "mjpeg";
args.push("-f", "image2pipe", "-vcodec", inputCodec, "-framerate", String(fps), "-i", "-");
args.push(
"-f",
"image2pipe",
"-vcodec",
inputCodec,
"-framerate",
fpsToFfmpegArg(fps),
"-i",
"-",
);
}
args.push("-r", String(fps));
args.push("-r", fpsToFfmpegArg(fps));
const shouldUseGpu = useGpu && gpuEncoder !== null;
packages/engine/src/types.ts
+8 -1
View File
@@ -4,6 +4,7 @@
* The engine's page contract. Any web page that wants to be rendered
* as video must expose `window.__hf` implementing the HfProtocol interface.
*/
import type { Fps } from "@hyperframes/core";
// ── Seek Protocol ──────────────────────────────────────────────────────────────
@@ -81,7 +82,13 @@ export interface HfProtocol {
export interface CaptureOptions {
width: number;
height: number;
fps: number;
/**
* Frame rate as an exact rational. Integer fps is `{ num: 30, den: 1 }`;
* NTSC is `{ num: 30000, den: 1001 }`. Captures are scheduled by the
* decimal interval (1000 * den / num ms) but FFmpeg arg builders emit the
* rational form verbatim — see `fpsToFfmpegArg`.
*/
fps: Fps;
format?: "jpeg" | "png";
quality?: number;
deviceScaleFactor?: number;
packages/producer/src/benchmark.ts
+23 -2
View File
@@ -36,6 +36,7 @@ import {
executeRenderJob,
type RenderPerfSummary,
} from "./services/renderOrchestrator.js";
import { parseFps } from "@hyperframes/core";
const scriptDir = dirname(fileURLToPath(import.meta.url));
const testsDir = resolve(scriptDir, "../tests");
@@ -44,7 +45,9 @@ const perfDir = resolve(testsDir, "perf");
interface TestMeta {
name: string;
tags?: string[];
renderConfig: { fps: 24 | 30 | 60 };
// Same on-disk shape as the regression harness — JSON `number` (integer
// fps) or JSON `string` ("30000/1001"). Normalized to Fps when loaded.
renderConfig: { fps: import("@hyperframes/core").Fps };
}
interface BenchmarkRun {
@@ -125,7 +128,25 @@ function discoverFixtures(
if (only && entry !== only) continue;
const meta: TestMeta = JSON.parse(readFileSync(metaPath, "utf-8"));
const rawMeta = JSON.parse(readFileSync(metaPath, "utf-8")) as {
name: string;
tags?: string[];
renderConfig: { fps: number | string };
};
// meta.json on disk uses a JSON `number` for legacy integer fps values
// and a JSON `string` for new ffmpeg-style rationals (e.g. "30000/1001").
// Normalize to the Fps rational shape so downstream code only sees the
// structured form — same convention as the regression harness.
const fpsParse = parseFps(rawMeta.renderConfig.fps);
if (!fpsParse.ok) {
throw new Error(
`Benchmark fixture ${entry}: invalid renderConfig.fps ${JSON.stringify(rawMeta.renderConfig.fps)}`,
);
}
const meta: TestMeta = {
...rawMeta,
renderConfig: { ...rawMeta.renderConfig, fps: fpsParse.value },
};
const fixtureTags = meta.tags ?? [];
// Positive filter (--tags): if provided, fixture must match at least one.
if (tags.length > 0 && !fixtureTags.some((t) => tags.includes(t))) continue;
packages/producer/src/regression-harness.ts
+27 -6
View File
@@ -19,6 +19,7 @@ import { compileForRender } from "./services/htmlCompiler.js";
import { validateCompilation } from "./services/compilationTester.js";
import { extractMediaMetadata } from "./utils/ffprobe.js";
import { buildRmsEnvelope, compareAudioEnvelopes } from "./utils/audioRegression.js";
import { parseFps, fpsToNumber } from "@hyperframes/core";
// ── Types ────────────────────────────────────────────────────────────────────
@@ -31,7 +32,13 @@ type TestMetadata = {
minAudioCorrelation: number;
maxAudioLagWindows: number;
renderConfig: {
fps: 24 | 30 | 60;
/**
* Frame rate. Stored on disk as a JSON number (integer fps, e.g. `30`)
* for legacy meta.json files, or a JSON string (`"30000/1001"` for NTSC)
* for rationals. The metadata validator normalizes both into an `Fps`
* rational at load time so downstream code only sees the structured form.
*/
fps: import("@hyperframes/core").Fps;
format?: "mp4" | "webm"; // Optional: defaults to "mp4"
workers?: number; // Optional: auto-calculates if omitted
/** Force HDR in the harness; omitted/false preserves historical SDR-only test behavior. */
@@ -154,9 +161,23 @@ function validateMetadata(meta: unknown): TestMetadata {
throw new Error("meta.json: 'renderConfig' must be an object");
}
const rc = m.renderConfig as Record<string, unknown>;
if (![24, 30, 60].includes(rc.fps as number)) {
throw new Error("meta.json: 'renderConfig.fps' must be 24, 30, or 60");
// Accept either a JSON number (integer fps, e.g. 30) or a JSON string
// (ffmpeg-style rational, e.g. "30000/1001"). Normalize both into the Fps
// rational shape and write it back onto the metadata object so all
// downstream callers can assume the structured form.
const fpsRaw = rc.fps;
const fpsParse =
typeof fpsRaw === "number" || typeof fpsRaw === "string"
? parseFps(fpsRaw)
: ({ ok: false, reason: "not-a-number" } as const);
if (!fpsParse.ok) {
throw new Error(
`meta.json: 'renderConfig.fps' must be an integer (e.g. 30) or rational string (e.g. "30000/1001"); got ${JSON.stringify(
fpsRaw,
)}`,
);
}
rc.fps = fpsParse.value;
if (rc.format !== undefined && rc.format !== "mp4" && rc.format !== "webm") {
throw new Error("meta.json: 'renderConfig.format' must be 'mp4' or 'webm' (or omit for mp4)");
}
@@ -452,13 +473,13 @@ function saveFailureDetails(
renderedVideoPath,
checkpoint.time,
join(framesDir, `actual_${timeStr}s.png`),
suite.meta.renderConfig.fps,
fpsToNumber(suite.meta.renderConfig.fps),
);
extractFrameAsImage(
snapshotVideoPath,
checkpoint.time,
join(framesDir, `expected_${timeStr}s.png`),
suite.meta.renderConfig.fps,
fpsToNumber(suite.meta.renderConfig.fps),
);
} catch {
logPretty(` Warning: Could not extract frame at ${checkpoint.time}s`, "⚠️");
@@ -666,7 +687,7 @@ async function runTestSuite(
renderedOutputPath,
snapshotVideoPath,
time,
suite.meta.renderConfig.fps,
fpsToNumber(suite.meta.renderConfig.fps),
);
visualCheckpoints.push({
time,
packages/producer/src/server.ts
+10 -2
View File
@@ -38,6 +38,7 @@ import { prepareHyperframeLintBody, runHyperframeLint } from "./services/hyperfr
import { resolveRenderPaths } from "./utils/paths.js";
import { defaultLogger, type ProducerLogger } from "./logger.js";
import { Semaphore } from "./utils/semaphore.js";
import { parseFps } from "@hyperframes/core";
// ---------------------------------------------------------------------------
// Types
@@ -68,7 +69,7 @@ export interface ServerOptions extends HandlerOptions {
interface RenderInput {
projectDir: string;
outputPath?: string | null;
fps: 24 | 30 | 60;
fps: import("@hyperframes/core").Fps;
quality: "draft" | "standard" | "high";
format?: "mp4" | "webm" | "mov";
workers?: number;
@@ -83,7 +84,14 @@ interface PreparedRenderInput {
}
function parseRenderOptions(body: Record<string, unknown>): Omit<RenderInput, "projectDir"> {
const fps = ([24, 30, 60].includes(body.fps as number) ? body.fps : 30) as 24 | 30 | 60;
// Accept either a JSON `number` (integer fps) or a JSON `string` (rational
// like "30000/1001"). Falls back to 30 fps on parse failure to preserve the
// forgiving behaviour the original whitelist had — the producer surfaces a
// clearer downstream error if the value is genuinely unusable.
const fpsRaw = body.fps;
const fpsParse =
typeof fpsRaw === "number" || typeof fpsRaw === "string" ? parseFps(fpsRaw) : null;
const fps = fpsParse && fpsParse.ok ? fpsParse.value : ({ num: 30, den: 1 } as const);
const quality = (
["draft", "standard", "high"].includes(body.quality as string) ? body.quality : "high"
) as "draft" | "standard" | "high";
packages/producer/src/services/renderOrchestrator.ts
+44 -15
View File
@@ -29,7 +29,13 @@ import {
symlinkSync,
} from "fs";
import { parseHTML } from "linkedom";
import { CANVAS_DIMENSIONS, type CanvasResolution } from "@hyperframes/core";
import {
CANVAS_DIMENSIONS,
type CanvasResolution,
type Fps,
fpsToNumber,
fpsToFfmpegArg,
} from "@hyperframes/core";
import {
type EngineConfig,
resolveConfig,
@@ -214,7 +220,17 @@ export type RenderStatus =
| "cancelled";
export interface RenderConfig {
fps: 24 | 30 | 60;
/**
* Frame rate as an exact rational. Integer fps is `{ num: 30, den: 1 }`;
* NTSC is `{ num: 30000, den: 1001 }`. This shape lets the orchestrator
* pass the exact rational through to FFmpeg's `-r` / `-framerate` flags
* without a decimal round-trip — see `fpsToFfmpegArg` in @hyperframes/core.
*
* Use `fpsToNumber(config.fps)` at any site that needs a `number` for
* arithmetic (frame-index → time, telemetry, frame-interval ms). Decimal
* precision at our scales is more than sufficient.
*/
fps: Fps;
quality: "draft" | "standard" | "high";
/**
* Output container format. Defaults to `"mp4"`; existing renders are
@@ -2345,7 +2361,7 @@ export async function executeRenderJob(
perfStages.browserProbeMs = Date.now() - probeStart;
job.duration = composition.duration;
job.totalFrames = Math.ceil(composition.duration * job.config.fps);
job.totalFrames = Math.ceil(composition.duration * fpsToNumber(job.config.fps));
const totalFrames = job.totalFrames;
if (job.duration <= 0) {
@@ -2487,7 +2503,14 @@ export async function executeRenderJob(
extractionResult = await extractAllVideoFrames(
composition.videos,
projectDir,
{ fps: job.config.fps, outputDir: join(compiledDir, "__hyperframes_video_frames") },
// extractAllVideoFrames takes fps as a number (decimal). Frames sampled
// from a video at 29.97 vs 30 differ by ~1 frame in 1000 — not enough
// to break visual parity, and the encoder-side rational keeps the
// output framerate exact.
{
fps: fpsToNumber(job.config.fps),
outputDir: join(compiledDir, "__hyperframes_video_frames"),
},
abortSignal,
{ extractCacheDir: cfg.extractCacheDir },
compiledDir,
@@ -2697,7 +2720,7 @@ export async function executeRenderJob(
captureCalibration = await measureCaptureCostFromSession(
calibrationSession,
totalFrames,
job.config.fps,
fpsToNumber(job.config.fps),
);
logCaptureCalibrationResult(captureCalibration, log);
} catch (error) {
@@ -2741,7 +2764,7 @@ export async function executeRenderJob(
captureCalibration = await measureCaptureCostFromSession(
calibrationSession,
totalFrames,
job.config.fps,
fpsToNumber(job.config.fps),
);
logCaptureCalibrationResult(captureCalibration, log);
} catch (fallbackError) {
@@ -2967,10 +2990,11 @@ export async function executeRenderJob(
return map;
});
const fpsDecimal = fpsToNumber(job.config.fps);
const transitionRanges: TransitionRange[] = transitionMeta.map((t) => ({
...t,
startFrame: Math.floor(t.time * job.config.fps),
endFrame: Math.ceil((t.time + t.duration) * job.config.fps),
startFrame: Math.floor(t.time * fpsDecimal),
endFrame: Math.ceil((t.time + t.duration) * fpsDecimal),
}));
if (transitionRanges.length > 0) {
@@ -3118,7 +3142,8 @@ export async function executeRenderJob(
"-t",
String(duration),
"-r",
String(job.config.fps),
// Pass the rational form to FFmpeg so NTSC stays exact end-to-end.
fpsToFfmpegArg(job.config.fps),
"-vf",
`scale=${dims.width}:${dims.height}:force_original_aspect_ratio=increase,crop=${dims.width}:${dims.height}`,
"-pix_fmt",
@@ -3267,7 +3292,7 @@ export async function executeRenderJob(
beforeCaptureHook,
width,
height,
fps: job.config.fps,
fps: fpsToNumber(job.config.fps),
compositeTransfer,
nativeHdrImageIds,
hdrImageBuffers,
@@ -3295,7 +3320,7 @@ export async function executeRenderJob(
for (let i = 0; i < totalFrames; i++) {
assertNotAborted();
const time = i / job.config.fps;
const time = (i * job.config.fps.den) / job.config.fps.num;
if (hdrPerf) hdrPerf.frames += 1;
// Seek timeline
@@ -3420,7 +3445,7 @@ export async function executeRenderJob(
sceneBuf as Buffer,
el,
time,
job.config.fps,
fpsToNumber(job.config.fps),
hdrVideoFrameSources,
hdrVideoStartTimes,
width,
@@ -3733,7 +3758,7 @@ export async function executeRenderJob(
for (let i = 0; i < totalFrames; i++) {
assertNotAborted();
const time = i / job.config.fps;
const time = (i * job.config.fps.den) / job.config.fps.num;
const { buffer } = await captureFrameToBuffer(session, i, time);
await reorderBuffer.waitForFrame(i);
currentEncoder.writeFrame(buffer);
@@ -3841,7 +3866,7 @@ export async function executeRenderJob(
for (let i = 0; i < job.totalFrames; i++) {
assertNotAborted();
const time = i / job.config.fps;
const time = (i * job.config.fps.den) / job.config.fps.num;
await captureFrame(session, i, time);
job.framesRendered = i + 1;
@@ -4011,7 +4036,11 @@ export async function executeRenderJob(
const perfSummary: RenderPerfSummary = {
renderId: job.id,
totalElapsedMs: totalElapsed,
fps: job.config.fps,
// RenderPerfSummary surfaces fps as a decimal because it lands in JSON
// payloads (CLI telemetry, regression-harness reports) where a single
// number is friendlier than `{num,den}`. Callers needing the rational
// back can read `job.config.fps`.
fps: fpsToNumber(job.config.fps),
quality: job.config.quality,
workers: workerCount,
chunkedEncode: enableChunkedEncode,
packages/producer/src/transparency-test.ts
+1 -1
View File
@@ -31,7 +31,7 @@ const FIXTURE_SRC = join(FIXTURE_DIR, "src");
const WIDTH = 200;
const HEIGHT = 200;
const FPS = 30;
const FPS: import("@hyperframes/core").Fps = { num: 30, den: 1 };
const TRANSPARENT_X = 10; // expected fully transparent
const TRANSPARENT_Y = 10;
const OPAQUE_X = 100; // inside the 50–150 red card
packages/studio/vite.config.ts
+5 -2
View File
@@ -74,7 +74,7 @@ function createViteAdapter(dataDir: string, server: ViteDevServer): StudioApiAda
| null = null;
let _producerModulePromise: Promise<{
createRenderJob: (config: {
fps: 24 | 30 | 60;
fps: import("@hyperframes/core").Fps;
quality: "draft" | "standard" | "high";
format: string;
outputResolution?: "landscape" | "portrait" | "landscape-4k" | "portrait-4k";
@@ -242,7 +242,10 @@ function createViteAdapter(dataDir: string, server: ViteDevServer): StudioApiAda
}
const { createRenderJob, executeRenderJob } = await getProducerModule();
const job = createRenderJob({
fps: opts.fps as 24 | 30 | 60,
// opts.fps is already an Fps rational — the studio-api route
// normalized any wire-format `number | string` into the structured
// form before calling this adapter.
fps: opts.fps,
quality: opts.quality as "draft" | "standard" | "high",
format: opts.format,
outputResolution: opts.outputResolution,