mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-03 04:38:33 +00:00

Files

T

James 890f305cd1 feat(skills): remotion-to-hyperframes references (6/7)

Adds 11 progressively-disclosed reference files that the skill loads on
demand during translation. Total ~1500 LOC, every file under 200 lines
(skill-creator's progressive-disclosure budget).

  api-map.md         the comprehensive Remotion -> HF translation table
                     (the index; loaded at start of translation)
  timing.md          interpolate, spring (validated configs), easing,
                     count-up, stagger
  sequencing.md      Sequence, Series, Loop, Freeze, AbsoluteFill,
                     Composition root
  media.md           Audio, Video, Img, IFrame, OffthreadVideo,
                     staticFile, asset paths
  transitions.md     @remotion/transitions presentations -> manual GSAP
                     crossfades or HF shader-transitions
  lottie.md          @remotion/lottie -> HF lottie adapter (incl. AE
                     feature limitations note)
  fonts.md           Google Fonts loading, local @font-face, system
                     fallback noise floor
  parameters.md      Zod schemas, defaultProps, sync vs async
                     calculateMetadata
  escape-hatch.md    when to bow out + the runtime interop pattern
                     from PR #214
  limitations.md     known caveat patterns (volume ramps, Loop with
                     state, custom presentations, code-split components)
  eval.md            how to run the validation harness, threshold rule
                     of thumb, what the noise floor looks like

The references are evidence-driven rather than speculative: every spring
config, easing curve, and SSIM threshold is documented from the
validated T1/T2/T3 calibration runs (mean 0.974 / 0.985 / 0.953). The
escape-hatch boundaries match the lint blockers in PR 2 and the T4
fixtures in PR 5.

Replaces the placeholder .gitkeep from PR 1.

2026-04-27 23:55:51 +00:00

3.2 KiB

Raw Blame History

Font translation

Fonts are the dominant non-translation noise floor. Same font-weight: 800 renders perceptibly bolder on HF's chrome-headless-shell than on Remotion's bundled Chromium when there's no real font installed. Validation showed this costs ~0.025 mean SSIM at the noise floor.

Pattern: `@remotion/google-fonts/<Family>`

import { loadFont } from "@remotion/google-fonts/Inter";
loadFont("normal", { weights: ["400", "800"] });

Translate to a <link> tag in <head>:

<head>
  <link rel="preconnect" href="https://fonts.googleapis.com" />
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
  <link
    href="https://fonts.googleapis.com/css2?family=Inter:wght@400;800&display=swap"
    rel="stylesheet"
  />
  <style>
    body {
      font-family: Inter, sans-serif;
    }
  </style>
</head>

Pull the family name and weights from the import path and loadFont arguments. HF's compiler inlines the Google Fonts CSS at render time, so you don't pay a network round-trip per render.

Pattern: local fonts via `@font-face`

import { Font } from "remotion";

Font.loadFont("/MyFont.woff2", "MyFont");

Translate to a @font-face rule:

<style>
  @font-face {
    font-family: "MyFont";
    src: url("assets/MyFont.woff2") format("woff2");
    font-weight: 400;
    font-style: normal;
  }
</style>

Copy the font file into hf-src/assets/ next to the HTML.

Pattern: system font fallback (no font load)

<div style={{ fontFamily: "Helvetica, Arial, sans-serif" }}>...</div>

Same string in HF — but be aware: on Linux without a real Helvetica installed (typical CI environment), Remotion and HF fall back to different sans-serif system fonts because they bundle different Chromium versions. This is the noise floor: ~0.025 mean SSIM cost, visible as different stroke widths at large font weights (800+).

If matching the Remotion render exactly matters for a specific fixture, load the same font explicitly — don't rely on system fallback.

When in doubt: use Inter

Inter renders identically across Chromium versions and is free. Translate any "system sans-serif" Remotion comp to Inter when you need to minimize font drift in the validation harness.

Font loading and `delayRender`

Remotion uses delayRender() to defer the first frame until fonts load. HF's compiler inlines Google Fonts at compile time and waits on @font-face readiness via the Frame Adapter pattern — the delayRender call drops in translation. See media.md.

Multi-weight loading

When Remotion loads multiple weights:

loadFont("normal", { weights: ["400", "500", "700", "800"] });

Inline all weights in the Google Fonts URL:

?family=Inter:wght@400;500;700;800&display=swap

Translation rule: enumerate every distinct font-weight value that appears in the composition's CSS (font-weight: 800 → weight 800 must be loaded). If the Remotion source loads weights that aren't actually used, drop them.

Font subsetting

Remotion's loadFont doesn't subset; HF's compiler doesn't either (yet). Don't try to optimize this in translation — it's lossless to keep the same weight set as the Remotion source.

3.2 KiB Raw Blame History