Jonathon's AI Wiki

HyperFrames Video Editor Cheatsheet

8 min read

Source: Video Editor Cheatsheet, Showcase — HeyGen HyperFrames docs

A fast operator quick-reference distilling HeyGen’s official Video Editor Cheatsheet — the prompts, CLI commands, Studio keyboard shortcuts, timing attributes, render presets, and quick fixes you reach for while directing an agent to build or edit a HyperFrames video. The core working loop is: keep npx hyperframes preview running, ask the agent for a cut, scrub timing in the Studio, drag the final 10% into place manually, then lint/validate/render/publish. This page is the cheatsheet; the Quickstart + CLI and Rendering articles carry the full detail.

Key Takeaways

  • The fast loop — init --example blank → cd → preview, then keep preview running while the agent edits index.html / compositions/; the Studio hot-reloads so you direct → scrub → tweak → repeat.
  • Pre-render gate — always run npx hyperframes lint then npx hyperframes validate before showing or rendering; lint catches structural mistakes, validate runs the composition in headless Chrome to catch runtime errors.
  • Three render qualities — --quality draft for fast iteration, standard for review links, high --fps 30 for final delivery; --format webm for transparent overlays, --docker for pixel-consistent (deterministic) output across machines.
  • Manual DOM editing is for the last 10% — drag titles/captions/CTAs/logos into place and tweak size/spacing/opacity/color in the Studio when dragging beats describing; then ask the agent to inspect the diff and clean up the CSS.
  • Use agents for the structural work — creating scenes, refactoring repeated patterns, wiring GSAP timelines, and fixing broken timing / layout overflow / render errors.
  • Top gotcha — video cuts off early: the GSAP timeline is shorter than the intended edit. Fix with a trailing tl.set({}, {}, 5) to hold the timeline to the full length.
  • Every visible timed layer should be a clip driven by data-start, data-duration, and data-track-index (treat them like timeline controls).
  • publish shares the editable project, not just the MP4 — it zips, uploads, and prints a stable hyperframes.dev URL with a claim token so the recipient can open, claim, and keep editing.
  • agent-browser is how an agent proves the preview actually works — it opens Chrome against the local preview, scrubs, clicks controls, and screenshots, instead of only claiming the code looks right.
  • The Showcase ships five inspectable production launches (full announcement, website-to-video, timeline-editor reveal, texture/title system, VFX reel) you can clone and remix — they use Git LFS, so install it before cloning or you get pointer files.

Cheatsheet

The fast loop

npx hyperframes init my-video --example blank
cd my-video
npx hyperframes preview        # keep running; Studio hot-reloads as the agent edits

Loop: ask the agent for the first cut/scene/caption/transition → scrub timing in the Studio → drag the last 10% manually → ask the agent to clean up what you changed → lint, validate, render, publish.

Pre-render gate

npx hyperframes lint           # structural mistakes
npx hyperframes validate       # runtime errors (headless Chrome)
npx hyperframes render --quality standard --output review.mp4

Render presets

GoalCommand
Fast iterationnpx hyperframes render --quality draft --output draft.mp4
Review linknpx hyperframes render --quality standard --output review.mp4
Final exportnpx hyperframes render --quality high --fps 30 --output final.mp4
Transparent overlaynpx hyperframes render --format webm --output overlay.webm
Deterministic outputnpx hyperframes render --docker --output final.mp4

WebM = transparent overlays, captions, lower thirds. --docker = pixel-consistent output across different machines.

CLI commands editors use most

CommandUse it for
npx hyperframes init my-videoCreate a new project
npx hyperframes init my-video --example warm-grainStart from a visual template
npx hyperframes init my-video --video source.mp4Import video + generate captions from its audio
npx hyperframes capture https://example.comCapture a website as source material
npx hyperframes previewOpen the live Studio preview
npx hyperframes lintCatch structural mistakes before preview/render
npx hyperframes validateRun in headless Chrome to catch runtime errors
npx hyperframes inspectFind text overflow / layout problems across the timeline
npx hyperframes snapshot --at 1,3,5Save PNG checks at exact timestamps
npx hyperframes render --output final.mp4Render the video
npx hyperframes publishUpload + get a shareable HyperFrames URL
npx hyperframes doctorCheck Node.js, FFmpeg, Chrome, Docker, deps
npx hyperframes docsOpen local CLI docs
npx hyperframes upgradeCheck for a newer CLI version

Studio keyboard shortcuts

Playback — Space play/pause · K stop · J play backward (repeat to shuttle faster) · L play forward (repeat to shuttle faster) · ←/→ step 1 frame · Shift+←/Shift+→ step 10 frames. (J/L ramp playback rate on each repeat; tap K between bursts to stop; hold K + tap J/L to step a frame.)

Work area (in/out points) — I set in-point · Shift+I clear in · O set out-point · Shift+O clear out · A jump to in (or comp start) · E jump to out (or comp end). The in/out points define a work area; with loop on, playback loops within them — handy for tightening a transition without trimming.

View — Cmd+Scroll / Ctrl+Scroll over the preview zooms at the cursor.

Application — Shift+T toggle timeline editor · Cmd+1/Ctrl+1 sidebar → Compositions · Cmd+2/Ctrl+2 sidebar → Assets · Cmd+Z/Ctrl+Z undo · Cmd+Shift+Z/Ctrl+Shift+Z/Ctrl+Y redo · Delete/Backspace delete selected clip or DOM element (when not typing) · Escape leave a sub-composition / close dialogs.

Tip

Preview uses the same runtime as rendering, so the visual frame matches the output. If preview stutters on a heavy frame but the render is clean, that’s expected — preview plays in real time; render captures one frame at a time.

Timing attributes (treat like timeline controls)

<h1 class="clip" data-start="0" data-duration="3" data-track-index="0">
  Opening title
</h1>
AttributeVideo-editor meaning
data-startWhen the layer starts
data-durationHow long the layer stays active
data-track-indexTimeline track number
data-media-startOffset into a media file
data-volumeAudio volume for an audio/video clip
data-composition-srcNested scene or reusable overlay

GSAP: register one paused timeline per composition in window.__timelines, and keep it at least as long as the edit:

<script>
  window.__timelines = window.__timelines || {};
  const tl = gsap.timeline({ paused: true });
  tl.from("#title", { opacity: 0, y: 40, duration: 0.6 });
  tl.set({}, {}, 5); // holds the timeline to >= 5 seconds
  window.__timelines["main"] = tl;
</script>

Warning

If a video cuts off early, the GSAP timeline is shorter than the intended edit. The trailing tl.set({}, {}, 5) pattern is the fix.

Manual DOM editing vs. agent work

  • Manual DOM editing (the last 10%): move titles, captions, product cards, logos, overlays into position; adjust size, spacing, opacity, color; check composition balance at an exact timestamp; Figma-like placement tweaks.
  • Agents: create scenes from scratch; refactor repeated visual patterns; wire GSAP timelines; fix broken timing, layout overflow, render errors; turn a manual tweak into reusable, clean HTML/CSS.
  • After manual edits, hand back to the agent: “I moved the hero title and resized the CTA manually in Studio. Inspect the changes, clean up the CSS if needed, then run lint and validate.”

Agent-led verification (agent-browser)

agent-browser is browser automation for AI agents — it opens Chrome against your preview, scrubs/clicks controls, reads page state, and screenshots, so the agent proves the preview works rather than asserting the code “looks right.”

agent-browser open http://localhost:3002
agent-browser snapshot -i
agent-browser screenshot --screenshot-dir ./qa

A good user-visible-edit handoff: “Run the preview, check it with agent-browser, take a screenshot, and render a draft MP4 to look at the frames with ffmpeg.” Keep npx hyperframes preview running, then point agent-browser at the local preview URL.

Publish & share

npx hyperframes publish              # zips, uploads, prints a stable hyperframes.dev URL
npx hyperframes publish ./my-video   # publish a specific folder
npx hyperframes publish --yes        # skip the confirm prompt in scripts

publish shares the editable project (with a claim token), not just the rendered MP4. It expects an index.html at the project root and ignores .git, node_modules, dist, .next, coverage.

Quick fixes

ProblemCommand or check
Preview will not startnpx hyperframes doctor
Port already in usenpx hyperframes preview --port 4567
Render failsnpx hyperframes lint then npx hyperframes validate
Need exact frame checksnpx hyperframes snapshot --at 1,2.5,5
Text overflows in the framenpx hyperframes inspect
Final render too slowTry --quality draft, reduce image sizes, or lower --fps
Need to share editable projectnpx hyperframes publish

Showcase — clone-and-remix references

Five inspectable production launches in the heygen-com/hyperframes-launches repo: HyperFrames launch (CSS + GSAP + Lottie + shaders + Three.js + compositing), Website-to-HyperFrames (41.8s, sites → promos/ads/reels), Timeline editor launch (UI mockups + VO + SFX), Texture launch (texture-mask typography + shader backgrounds), and VFX x HeyGen (Three.js + HTML-in-canvas + generated media). They use Git LFS — install it first or the preview opens with pointer files:

brew install git-lfs && git lfs install
GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/heygen-com/hyperframes-launches.git
cd hyperframes-launches
git lfs pull --include="website-to-hyperframes/**"
cd website-to-hyperframes && npx hyperframes preview

Try It

  1. npx hyperframes init my-video --example blank && cd my-video && npx hyperframes preview — start the Studio and leave it running.
  2. Ask your agent for a first cut, then scrub it with Space / J / K / L and set a work area with I / O to loop a transition.
  3. Drag the final placement of a title or CTA manually in the Studio, then have the agent inspect the diff and run npx hyperframes lint + npx hyperframes validate.
  4. npx hyperframes render --quality draft --output draft.mp4 to iterate; switch to --quality high --fps 30 --output final.mp4 for delivery.
  5. npx hyperframes publish to hand a teammate an editable, claimable hyperframes.dev link.

Graph View

Backlinks