`--fps 60` renders GSAP/DOM motion at 30fps (render seek re-quantizes to hardcoded canonicalFps=30)

[zerfl]

Describe the bug

Rendering with --fps 60 produces a correct 60fps CFR file, but all GSAP/DOM-driven motion only updates 30 times per second — every other frame is an exact duplicate. WebGL shader transitions are NOT affected and play at a true 60fps, which makes it very visible: shader moments are smooth, every plain scene stutters.

The render-seek path re-quantizes every requested time onto a hardcoded canonicalFps = 30, regardless of the requested render fps. There is no attribute, CLI flag, or env var that changes it.

It does not show up in the Studio preview, because preview plays in real time off requestAnimationFrame and never goes through the render-seek path — so "smooth in preview, juddery in the render" is the tell.

Link to reproduction

https://github.com/zerfl/hyperframes-fps-repro

Steps to reproduce

1. Clone the reproduction repo (a blank hyperframes init scaffold with one linearly-moving box).
2. Render at 60 and at 30 fps:
   npx hyperframes@0.7.10 render . -o repro_60fps.mp4 --fps 60 --workers 1
npx hyperframes@0.7.10 render . -o repro_30fps.mp4 --fps 30 --workers 1
3. Play repro_60fps.mp4 — the box judders. Then inspect per-frame motion:
   ffmpeg -i repro_60fps.mp4 -vf "select='between(n,60,99)',signalstats,metadata=print:key=lavfi.signalstats.YDIF" -an -f null - 2>&1 | grep -oE 'YDIF=[0-9.]+'

Expected behavior

At --fps 60 the timeline is sampled on a 60fps grid: every output frame is a distinct timeline position, matching the (smooth) Studio preview. For the repro's linear motion, all 240 frames differ.

Actual behavior

The 60fps file updates motion only every other frame. The per-frame luma delta alternates motion/zero:

0.317 0.000 0.317 0.000 0.317 0.000 0.317 0.000 ...

= 30fps motion in a 60fps container. Exact duplicate count: repro_60fps.mp4 → 240 frames, ~104 exact consecutive duplicates; repro_30fps.mp4 (control) → 120 frames, 0 duplicates (30fps renders correctly).

Root cause: renderSeek → seekTimelineDeterministically → quantizeTimeToFrame(t, canonicalFps), with canonicalFps hardcoded to 30 (packages/core/src/runtime/state.ts) and never wired to --fps. So output frame k (time k/60) seeks to floor(k/2)/30, collapsing frames (0,1),(2,3),… in pairs. The shader path is exempt because it samples HF_VIRTUAL_TIME at the exact t. Full file:line breakdown in the attached ISSUE notes / repro README.

Environment

✓ Version          0.7.10 (latest)
✓ Node.js          v20.19.0 (darwin x64)
✓ CPU              16 cores · Intel(R) Core(TM) i7-10700K CPU @ 3.80GHz
✓ Memory           16.0 GB total · 6.0 GB available
✓ FFmpeg           ffmpeg 7.1.1 at /usr/local/bin/ffmpeg
✓ FFprobe          ffprobe 7.1.1 at /usr/local/bin/ffprobe
✓ Chrome           system: /Applications/Google Chrome.app/...
✓ Docker           Docker version 29.5.3 · running

Additional context

• Deterministic, platform-independent (pure seek arithmetic), so Docker/Linux renders are affected identically.
• The injected window.__HF_EXPORT_RENDER_SEEK_CONFIG (mode/step/offsetFraction, packages/producer/src/services/fileServer.ts) is never consumed (only referenced as a string in packages/core/src/compiler/htmlDocument.ts) — likely the intended home for a fix that drives canonicalFps from the render fps.
• Workaround for anyone blocked: after hf.seek(t), re-seek the GSAP master to the exact t. Snippet in the repro's notes.

[zerfl]

Disclaimer: I used Claude Code to assist me with this issue. Parts of the code or explanation are ai-driven. I did confirm that the workaround works.

Render quantizes all GSAP/DOM motion to a hardcoded 30fps grid, so --fps 60 produces 30fps motion in a 60fps container

Summary

When rendering with --fps 60, the output .mp4 is a correct 60fps CFR file, but all GSAP/DOM-driven motion only updates 30 times per second — every other frame is a duplicate. WebGL shader transitions are unaffected and play at a true 60fps, which makes the regression very visible: shader moments are buttery, every plain scene stutters.

The cause is that the runtime re-quantizes every render seek to a hardcoded canonicalFps = 30, regardless of the requested render fps. There is no attribute, CLI flag, or env var that changes it.

This does not show up in the Studio preview, because preview plays in real time off requestAnimationFrame and never goes through the render-seek path.

Environment

• Repo: heygen-com/hyperframes @ commit 0c1e236d
• @hyperframes/core 0.7.10 (also reproduces with the CLI's bundled 0.7.6 runtime)
• CLI: npx hyperframes render . --fps 60 --quality high
• macOS (Chrome/ANGLE-Metal) — but the cause is platform-independent (pure seek math), so Docker/Linux are affected identically.

Reproduction

Any composition whose motion is a GSAP timeline registered on window.__timelines. A linear tween makes it unambiguous:

<div data-hf-id="m" id="main" data-composition-id="main" data-width="1080" data-height="1920" data-start="0" data-duration="4">
  <div data-hf-id="b" id="box" style="position:absolute;top:0;left:0;width:200px;height:200px;background:#fff"></div>
</div>
<script>
  var tl = gsap.timeline({ paused: true });
  // Linear vertical drift: at a true 60fps every frame must differ.
  tl.to("#box", { y: 1700, duration: 4, ease: "none" }, 0);
  window.__timelines = window.__timelines || {};
  window.__timelines["main"] = tl;
</script>

npx hyperframes render . -o out.mp4 --fps 60

Expected

Every one of the 240 frames is a distinct position (≈0.83px/frame). Motion matches the Studio preview.

Actual

The box advances only every other frame: frames (0,1) identical, (2,3) identical, … → 120 distinct positions in a 240-frame file = 30fps motion.

Evidence / how to verify

Per-frame luma delta on a continuously-moving section exposes the cadence (mpdecimate/framehash are unreliable here — a static grain overlay and font anti-aliasing make duplicate frames hash-distinct):

ffmpeg -i out.mp4 -vf "select='between(n,195,240)',signalstats,metadata=print:key=lavfi.signalstats.YDIF" \
  -an -f null - 2>&1 | grep -oE 'YDIF=[0-9.]+'

• GSAP scene: 0.63, 0.001, 0.90, 0.002, 1.04, 0.004, 1.08, 0.001, … — alternating move / ~0 → 2:1 frame doubling (30fps).
• Shader transition (same file): 5.30, 4.54, 5.39, 4.28, 4.94, … — every frame moves → true 60fps.

The ~0.00x values are not exact zeros; they are the grain overlay's sub-pixel dither on an otherwise-frozen frame, which is why naive duplicate-frame detectors miss it.

Root cause

The render-seek path floors the requested time onto the canonicalFps grid, and canonicalFps is a hardcoded 30 with no setter anywhere in production code.

1. The producer hands the page the correct, already-fps-quantized frame time and calls window.__hf.seek(t):

   • packages/producer/src/services/fileServer.ts:534-540

     hf.seek = function(t) {
       p.renderSeek(t);                                  // ← seeks GSAP timeline (re-quantized below)
       var nextTimeMs = (Math.max(0, Number(t) || 0)) * 1000;
       if (window.__HF_VIRTUAL_TIME__ && typeof window.__HF_VIRTUAL_TIME__.seekToTime === "function") {
         window.__HF_VIRTUAL_TIME__.seekToTime(nextTimeMs); // ← exact time → shader/rAF clock (60fps OK)
       }
       seekSameOriginChildFrames(window, nextTimeMs);
     };

2. renderSeek re-quantizes that exact time to canonicalFps:

   • packages/core/src/runtime/player.ts:209-227 (renderSeek, reads deps.getCanonicalFps() at :211, quantizes at :224)
   • packages/core/src/runtime/player.ts:78-87 (seekTimelineDeterministically → quantizeTimeToFrame(timeSeconds, canonicalFps) at :83)

3. The quantizer floors onto the grid:

   • packages/core/src/inline-scripts/parityContract.ts:35

     export function quantizeTimeToFrame(timeSeconds: number, fps: number): number {
       const safeFps = Number.isFinite(fps) && fps > 0 ? fps : 30;
       const safeTime = Number.isFinite(timeSeconds) && timeSeconds > 0 ? timeSeconds : 0;
       const frameIndex = Math.floor(safeTime * safeFps + 1e-9);
       return frameIndex / safeFps;
     }

   For output frame k at time k/60: quantizeTimeToFrame(k/60, 30) = floor(k/2)/30 → frames (0,1) → 0, (2,3) → 1/30, … i.e. exact 2:1 duplication.

4. canonicalFps is only ever 30:

   • packages/core/src/runtime/state.ts:101 — canonicalFps: 30 (the only assignment in production code; the sole non-test write to state.canonicalFps is in state.test.ts)
   • packages/core/src/runtime/init.ts:1923 — getCanonicalFps: () => state.canonicalFps
   • init.ts parses data-width/height/duration/start/end but no fps attribute; nothing wires the render --fps into state.canonicalFps.

Why the shader path is exempt

hf.seek advances __HF_VIRTUAL_TIME__ to the exact t (fileServer.ts:537-538); shaders/requestAnimationFrame sample that clock and so move at the true render fps. Only the GSAP master timeline goes through the 30fps-quantized renderSeek.

Dead config (worth removing or wiring up)

The producer injects window.__HF_EXPORT_RENDER_SEEK_CONFIG (mode, step: 1/120, offsetFraction: 0.5) at packages/producer/src/services/fileServer.ts:297-326, but nothing consumes it — the only other reference is a string entry in packages/core/src/compiler/htmlDocument.ts:16. It looks like the scaffolding for sub-frame render seeking was started but never connected, which is likely the intended home for the fix.

Impact

• Every render above 30fps silently delivers 30fps motion for non-shader content. The container fps, frame count, and file size all look correct, so it is easy to miss.
• Determinism itself is fine (the quantization is stable) — the grid is just pinned to the wrong value.

Workaround (composition-side, no runtime changes)

For anyone blocked today: after the original hf.seek(t) runs, re-seek the GSAP master to the exact t. This keeps shader/media/deterministic-adapter sync intact and restores true 60fps DOM motion. (No-op in the Studio preview.)

(function enableExact60fpsRenderSeek() {
  function wrapSeek(fn) {
    if (typeof fn !== "function" || fn.__hfExact60) return fn;
    var wrapped = function (t) {
      var r = fn.apply(this, arguments);
      var master = window.__timelines && window.__timelines["main"];
      if (master) { try { master.pause(); master.time(Math.max(0, Number(t) || 0), false); } catch (e) {} }
      return r;
    };
    wrapped.__hfExact60 = true;
    return wrapped;
  }
  function trapHf(obj) {
    if (!obj || obj.__hfExact60Trapped) return;
    obj.__hfExact60Trapped = true;
    var stored = wrapSeek(obj.seek);
    Object.defineProperty(obj, "seek", {
      configurable: true, enumerable: true,
      get: function () { return stored; },
      set: function (fn) { stored = wrapSeek(fn); },
    });
  }
  var held = window.__hf;
  if (held) trapHf(held);
  try {
    Object.defineProperty(window, "__hf", {
      configurable: true, enumerable: true,
      get: function () { return held; },
      set: function (v) { held = v; trapHf(v); },
    });
  } catch (e) {}
})();

Suggested fix direction

Drive canonicalFps from the actual render fps (the producer already knows it — e.g. quantizeTimeToFrame(checkpointSec, fps) at packages/producer/src/parity-harness.ts:239) instead of pinning it to 30, so the render-seek grid matches the output grid. Quantization (determinism) is preserved; only the grid resolution changes.