Merge pull request #1034 from heygen-com/fix/retrocompat-fps-input

fix(producer): accept plain integer fps in createRenderJob

Author: miguel-heygen

docs/packages/engine.mdx

@@ -96,7 +96,7 @@ import {
 } from '@hyperframes/engine';
 
 // 1. Create a capture session
-const session = await createCaptureSession({ fps: 30, width: 1920, height: 1080 });
+const session = await createCaptureSession({ fps: { num: 30, den: 1 }, width: 1920, height: 1080 });
 
 // 2. Initialize with a composition
 await initializeSession(session, './my-video/index.html');
@@ -163,7 +163,7 @@ const webmPreset = getEncoderPreset('standard', 'webm');
 
 // Encode captured frames to video
 await encodeFramesFromDir(framesDir, 'frame_%06d.png', outputPath, {
-  fps: 30,
+  fps: { num: 30, den: 1 },
   ...webmPreset,
 });
 
@@ -195,7 +195,7 @@ import { spawnStreamingEncoder } from '@hyperframes/engine';
 
 const encoder = await spawnStreamingEncoder({
   outputPath: './output.mp4',
-  fps: 30,
+  fps: { num: 30, den: 1 },
   width: 1920,
   height: 1080,
 });

docs/packages/producer.mdx

@@ -60,28 +60,26 @@ The producer uses a two-step API: create a render job configuration, then execut
 import { createRenderJob, executeRenderJob } from '@hyperframes/producer';
 
 const job = createRenderJob({
-  input: './my-video/index.html',
-  output: './output.mp4',
   fps: 30,
   quality: 'standard',
 });
 
-const result = await executeRenderJob(job);
+await executeRenderJob(job, './my-video', './output.mp4');
 ```
 
 ### Render Configuration
 
 ```typescript
-import type { RenderConfig } from '@hyperframes/producer';
+import { createRenderJob } from '@hyperframes/producer';
 
-const config: RenderConfig = {
-  fps: 30,                   // 24, 30, or 60
+const job = createRenderJob({
+  fps: 30,                   // integer, or { num: 30000, den: 1001 } for NTSC
   quality: 'standard',       // 'draft', 'standard', or 'high'
-  format: 'mp4',             // 'mp4' or 'webm' (WebM renders with transparency)
+  format: 'mp4',             // 'mp4', 'webm', 'mov', or 'png-sequence'
   workers: 4,                // Parallel render workers (1-8)
   useGpu: false,             // GPU-accelerated encoding
   debug: false,              // Debug logging
-};
+});
 ```
 
 #### WebM with Transparency

packages/core/src/core.types.ts

@@ -20,6 +20,15 @@ export interface Fps {
   den: number;
 }
 
+export type FpsInput = number | Fps;
+
+export function toFps(input: FpsInput): Fps {
+  if (typeof input === "number") {
+    return { num: input, den: 1 };
+  }
+  return input;
+}
+
 /**
  * Decimal value of an {@link Fps} rational. Used at sites that need a
  * `number` for arithmetic (frame-index → time, frame intervals, telemetry

packages/core/src/index.ts

@@ -12,6 +12,7 @@ export type {
   MediaElementType,
   CanvasResolution,
   Fps,
+  FpsInput,
   FpsParseResult,
   MediaFile,
   CompositionAPI,
@@ -42,6 +43,7 @@ export {
   normalizeResolutionFlag,
   parseFps,
   parseFpsWithDefault,
+  toFps,
   fpsToNumber,
   fpsToFfmpegArg,
   TIMELINE_COLORS,

packages/producer/src/index.ts

@@ -12,6 +12,7 @@ export {
   executeRenderJob,
   RenderCancelledError,
   type RenderConfig,
+  type RenderConfigInput,
   type RenderJob,
   type RenderStatus,
   type RenderPerfSummary,

packages/producer/src/services/renderOrchestrator.ts

@@ -44,7 +44,7 @@ import {
   appendFileSync,
 } from "fs";
 import { parseHTML } from "linkedom";
-import { type CanvasResolution, type Fps } from "@hyperframes/core";
+import { type CanvasResolution, type Fps, type FpsInput, toFps } from "@hyperframes/core";
 import {
   type EngineConfig,
   resolveConfig,
@@ -1343,10 +1343,12 @@ export async function compositeHdrFrame(
   }
 }
 
-export function createRenderJob(config: RenderConfig): RenderJob {
+export type RenderConfigInput = Omit<RenderConfig, "fps"> & { fps: FpsInput };
+
+export function createRenderJob(config: RenderConfigInput): RenderJob {
   return {
     id: randomUUID(),
-    config,
+    config: { ...config, fps: toFps(config.fps) },
     status: "queued",
     progress: 0,
     currentStage: "Queued",