Use Hyperframes for custom HTML/CSS motion graphics: animated titles, stat reveals, charts, diagrams, logo stings, and full-frame graphic b-roll. Keep make_cards.py for its existing Remotion card templates. Follow this reference when the user requests Hyperframes or needs custom graphics in a reel.

Hyperframes produces a source clip. The selected reel renderer still assembles the cut, mixes VO/music, grades, captions, and exports it. This adapter outputs opaque MP4 clips; it does not add transparent overlays or a fourth cut-plan renderer. For a lower third over footage, compose the footage and graphic together in Hyperframes before rendering that segment.

Set up a source project

Requires Node 22+, npm, ffmpeg/ffprobe, and a Chromium browser supported by Hyperframes. No HeyGen account or API key is needed for local rendering. Check node --version; Node 18 is enough for Remotion cards but not Hyperframes. Missing tools are reported, never replaced with stills without the user's choice.

Resolve REEL_BUILDER to the installed skill directory. Copy the starter once into an unused project directory; keep dependencies outside the installed skill:

REEL_BUILDER=/absolute/path/to/skills/reel-builder
mkdir -p work/motion
cp -R "$REEL_BUILDER/assets/hyperframes-motion" work/motion/title
npm --prefix work/motion/title ci --no-audit --no-fund

The starter's package.json and package-lock.json pin Hyperframes and GSAP. Review those pins quarterly against upstream releases; update them together in a dedicated dependency change and repeat the render validation below. First use may require Hyperframes' browser download. Diagnose with the local CLI's doctor --json; read its ok value, not just the exit code. Use browser ensure when the browser is absent. A blocked Chrome launch requires a host that can run Chromium; a still-image substitute is not a verified render.

Author the animation

Edit work/motion/title/index.html or use an existing local Hyperframes project. The adapter renders that project's index.html with its project-local CLI.

Keep one standalone root with data-composition-id, explicit data-width, data-height, and data-duration in seconds.
Match the project's aspect ratio. The starter is 1080×1920; use 1920×1080 for landscape or 1080×1080 for square and adjust the layout. --resolution 4k supersamples the matching 1080 canvas; it does not redesign the composition.
Register the paused GSAP timeline under window.__timelines using the root's composition ID. Use seekable animations, finite durations, and explicit starting values. Avoid wall clocks, unseeded randomness, and asynchronous render-time data fetching.
Keep assets local and fonts licensed. The starter uses npm-installed GSAP; no CDN script is needed. Bundle fonts with @font-face for consistent type.
Give timed elements stable IDs and durations. Keep text inside the safe area and readable for the intended slot. Match the root and clip durations when changing the starter's length.
Keep narration and music in the reel. The adapter discards composition audio and adds silence; use --vo-overlay at reel assembly for speech under graphics.

For advanced authoring, consult upstream's composition contract and CLI reference. Use the locally pinned CLI; adapting their examples does not require installing upstream agent skills, publishing a project, or sending feedback.

Preview and render the clip

From the reel project directory:

python3 "$REEL_BUILDER/scripts/render_hyperframes.py" work/motion/title \
  --preview --out preview/motion-title.mp4
python3 "$REEL_BUILDER/scripts/render_hyperframes.py" work/motion/title \
  --aspect 9:16 --resolution 1080 --out work/motion/title.mp4

The script runs Hyperframes' check, renders, conforms the media, and probes the output. Its docstring defines prerequisites, file side effects, JSON stdout, error behavior, and the output media contract. --preview produces the reel's preview dimensions; use the full-size clip in the cut plan. Optional interactive editing: npm --prefix work/motion/title run preview.

View the animation before using it. Inspect entrance, midpoint, and final frames for clipping, font substitution, blank frames, and timing; play the MP4 to judge motion. For a quick contact sheet:

python3 "$REEL_BUILDER/scripts/probe_clips.py" work/motion --out work/motion-clips.json
python3 "$REEL_BUILDER/scripts/contact_sheet.py" work/motion-clips.json --outdir work/motion-sheets

Place it in the reel

The conformed clip is ready for the existing clip / in / duration fields:

{"clip": "work/motion/title.mp4", "in": 0.0, "duration": 3.0, "note": "animated title over VO"}

Keep the segment within the rendered duration. For a talking-head insert, replace picture in the intended speech slot and preserve the continuous VO with render_reel.py --vo-overlay work/vo_tight.mp4; inserting extra time without updating the VO alignment breaks synchronization. Music-video graphics use the same beat-based slot timing as footage.

Keep generated files in work/motion/; do not put them into the raw/ symlink. Retain the HTML and its assets for revisions. A render failure preserves the previous MP4; never treat that older file as proof the revision rendered.

After changing graphics, rerender the clip, update plan/cut_plan.json, reopen any affected gate, then rerender and QC the draft/master. If the path and duration stayed the same, touch plan/cut_plan.json invalidates the downstream renders: pipeline staleness tracks the plan, not nested HTML assets. Gate 1 still receives plan plus draft; Gate 2 still receives the final graded reel. Check brand colors in that graded reel; --grade none preserves graphic colors.

Validate changes to this integration

Run python3 -m unittest discover -s tests -v from the repository. From a fresh copy of the starter with npm ci, render its three-second clip using the two commands above. Confirm the preview is 540×960 and the full clip 1080×1920, 30fps H.264/yuv420p with stereo 48kHz AAC. Inspect the frames, then reference the full clip in a cut plan and run render_reel.py --grade none plus check_cuts.py. Repeat with a landscape composition before changing aspect handling. Tests use process-boundary fixtures; these real renders verify the browser and npm integration.