Files
jbernard077andMiguel Ángel 6f799aaa41 docs: align infinite-repeat guidance with bounded repeat: -1 lint (#3795)
Since v0.7.71 (#2763), gsap_infinite_repeat demotes to a warning when the
root declares a finite data-duration: deterministic seeking and export clip
to that explicit window. Without one it remains a hard error (unbounded
timeline duration breaks render planning).

Update every doc site that still teaches the old absolute ban — the core
determinism contract, the animation adapter notes, and the design-guide
tables/checklists — to state the bounded allowance and keep the finite-count
formula for loops that must end before the composition does.

skills/hyperframes-animation/rules/ambient-glow-bloom.md is intentionally
untouched: its shimmer must stop before the composition ends, which is
exactly the case where a computed finite count is still required.

Co-authored-by: Miguel Ángel <miguel.sierra@heygen.com>
2026-10-02 05:59:04 -07:00

4.9 KiB

Translation limitations

What the skill explicitly cannot translate, separated from the blocker-list (which is enforced by lint_source.py). These are known gaps — surface them to the user as translation notes when translating the surrounding composition.

React patterns the skill refuses

See escape-hatch.md. Any of these triggers a bow-out:

  • useState, useReducer driving animation
  • useEffect / useLayoutEffect with non-empty deps (side effects)
  • async calculateMetadata
  • Third-party React UI libraries (MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI)

@remotion/lambda is no longer in this list — it's a warning, not a blocker, because Lambda config is orthogonal to composition rendering. The skill drops the imports and renderMediaOnLambda(...) calls and writes a TRANSLATION_NOTES.md entry. See escape-hatch.md.

Patterns that work with caveats

Volume ramps on <Audio>

Remotion accepts a function for volume:

<Audio src={...} volume={(f) => interpolate(f, [0, 30], [0, 1])} />

HF ramps volume with a data-automation volume lane on the <audio> (form in hyperframes-core/references/creator-editing-recipes.md). Translation: write the lane from the interpolate points, OR bake the ramp into the audio file with ffmpeg afade. The dropped-ramp path produces audibly different output but visually-identical video, so SSIM passes — just flag it.

<Loop> with stateful children

<Loop durationInFrames={30}>
  <CounterThatIncrementsViaUseRef />
</Loop>

A bounded GSAP repeat can reproduce visual repetition when its finite count is derived from the visible duration. If the looped child has cross-iteration state (a counter, a randomness seed), HF won't reproduce it identically per iteration. Bow out unless the child is fully deterministic per-iteration; use repeat: -1 only when the root declares a finite data-duration.

Remotion's <Img> with crossOrigin

<Img src="https://other-domain.com/x.png" crossOrigin="anonymous" />

HF's renderer doesn't enforce CORS the same way Remotion does. Most public images work; private images served with auth headers won't. If the source uses crossOrigin="use-credentials", the asset needs to be downloaded and inlined at translation time.

Custom presentation in <TransitionSeries>

const customPresentation: PresentationComponent = ({ children, presentationProgress }) => {
  return <div style={{ filter: `blur(${(1 - presentationProgress) * 20}px)` }}>{children}</div>;
};

Pure presentations (transform/filter/opacity computed from progress) translate to GSAP tweens cleanly. Presentations that read useCurrentFrame() internally or have stateful children don't — bow out.

Code-split components (React.lazy)

const HeavyChart = React.lazy(() => import("./HeavyChart"));

React.lazy is async and doesn't fit the deterministic-render model. Translate to a regular import; the resulting HF composition will just include all the code upfront.

Patterns that always work

  • <AbsoluteFill> and <Sequence> (any nesting)
  • useCurrentFrame() derivations: interpolate, spring, Easing, interpolateColors, manual math
  • <Audio>, <Video>, <Img>, <IFrame> with simple props
  • staticFile() references
  • Custom React subcomponents that are pure functions of props
  • Custom hooks that are pure derivations of useCurrentFrame
  • @remotion/lottie (translates to HF's Lottie adapter)
  • @remotion/google-fonts/<Family> (translates to <link> or @font-face)
  • Sync calculateMetadata (resolved at translation time)
  • <TransitionSeries> with built-in presentations (fade, slide, wipe, clockWipe, flip, iris)

What the skill never tries to translate

These are out-of-scope by design:

  • HDR rendering — HF supports HDR but Remotion doesn't, so there's nothing to translate from.
  • Variable frame rate — both tools assume constant fps.
  • Multi-composition <Composition> lists — translate one at a time. The skill prompts the user to choose which composition.
  • Remotion Studio props panel — visual prop editing in HF Studio needs different infrastructure; out of scope.

Reporting gaps to the user

When translation produces something but the something has gaps, write a TRANSLATION_NOTES.md next to the output:

# Translation notes

The following Remotion patterns were translated with caveats:

- `<Audio volume={(f) => ...}>` (line 15): volume ramp written as a
  `data-automation` volume lane (see `creator-editing-recipes.md`); the
  ffmpeg `afade` bake-in is the alternative.
- `<HeavyChart>` (line 30): translated as inline HTML. The original
  React.lazy boundary was dropped — bundle size unchanged because HF
  serves a single HTML file.

If any of these caveats matter, consider the runtime interop pattern
instead.

This file is also generated by the skill alongside the HF output, not held in the corpus.