Video Editor Cheatsheet

Fast reference for video editors and creative people directing agents, cutting timing, tweaking layouts, previewing, and publishing HyperFrames projects.

Use this as a fast reference when you are directing agents, cutting timing, making visual layout tweaks, previewing, and sharing HyperFrames projects.

The Fast Loop

npx hyperframes init my-video --example blank
cd my-video
npx hyperframes preview

Keep the preview running while your agent edits index.html or files in compositions/. The Studio updates automatically, so you can direct the agent, scrub the result, make manual visual tweaks, then repeat.

Most production work should feel like this:

1. Ask the agent for the first cut, scene, caption pass, transition, or cleanup.
2. Use the Studio preview and timeline to check timing.
3. Use manual DOM editing for Figma-like layout tweaks: select elements, move them, and adjust visual properties directly.
4. Ask the agent to clean up or generalize anything you changed manually.
5. Lint, validate, render, and publish.

Before showing or rendering a project:

npx hyperframes lint
npx hyperframes validate
npx hyperframes render --quality standard --output review.mp4

For fast iteration renders, use draft quality:

npx hyperframes render --quality draft --output draft.mp4

For final delivery:

npx hyperframes render --quality high --fps 30 --output final.mp4

Terminal Shortcuts

Move around projects quickly:

pwd                 # show current folder
ls                  # list files
cd my-video         # enter a project folder
cd ..               # go up one folder
cd -                # jump back to the previous folder
open .              # open the current folder in Finder on macOS
code .              # open the current folder in VS Code, if installed

Common HyperFrames project folders:

cd assets           # source videos, images, audio
cd compositions     # reusable scenes and overlays
cd ..               # back to the project root

Run HyperFrames commands from the project root, where index.html lives. If you are not sure where you are, run pwd then ls. If you see index.html, you are in the right place.

Preview Shortcuts

Start the Studio:

npx hyperframes preview

Use a different port if 3002 is already busy:

npx hyperframes preview --port 4567

Inside the Studio:

Shortcut	Use
Space	Play or pause (focus on the page body)
Left Arrow / Right Arrow	Nudge seek bar by 1 second (seek bar focused)
Shift+Left Arrow / Shift+Right Arrow	Nudge seek bar by 5 seconds (seek bar focused)
Shift+T	Show or hide the timeline editor
Cmd+1 / Ctrl+1	Switch to Compositions
Cmd+2 / Ctrl+2	Switch to Assets
Delete / Backspace	Delete the selected timeline clip (when not typing in an editor)
Escape	Leave a sub-composition or close editor dialogs

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 is expected — preview plays in real time, render captures one frame at a time.

Agent-Led Editing

Ask the agent to verify visible changes in the browser. For a user-visible edit, a good handoff is:

Run the preview, check it with agent-browser, take a screenshot, and render a draft MP4 to take a look at the frames with ffmpeg.

Manual DOM Editing

In the Studio, you can edit the DOM visually for the final 10% of creative adjustment where dragging is faster than describing.

Use manual DOM editing for:

• moving titles, captions, product cards, logos, and overlays into position
• adjusting size, spacing, opacity, color, and other visual properties
• checking composition balance at an exact timestamp
• making Figma-like placement tweaks

Use agents for:

• creating scenes from scratch
• refactoring repeated visual patterns
• wiring GSAP timelines
• fixing broken timing, layout overflow, or render errors
• turning a manual visual tweak into reusable, clean HTML/CSS

After manual DOM edits, ask the agent to inspect the diff and keep the source clean:

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.

CLI Commands Editors Use Most

Command	Use it for
npx hyperframes init my-video	Create a new project
npx hyperframes init my-video --example warm-grain	Start from a visual template
npx hyperframes init my-video --video source.mp4	Import video and generate captions from the source audio
npx hyperframes capture https://example.com	Capture a website as source material for a video
npx hyperframes preview	Open the live Studio preview
npx hyperframes lint	Catch structural mistakes before preview or render
npx hyperframes validate	Run the composition in headless Chrome to catch runtime errors
npx hyperframes inspect	Find text overflow and layout problems across the timeline
npx hyperframes snapshot --at 1,3,5	Save PNG checks at exact timestamps
npx hyperframes render --output final.mp4	Render the video
npx hyperframes publish	Upload the project and get a shareable HyperFrames URL
npx hyperframes doctor	Check Node.js, FFmpeg, Chrome, Docker, and other dependencies
npx hyperframes docs	Open local CLI docs
npx hyperframes upgrade	Check for a newer CLI version

Timing Cheatsheet

Every visible timed layer should usually be a clip:

<h1
  class="clip"
  data-start="0"
  data-duration="3"
  data-track-index="0"
>
  Opening title
</h1>

Use these attributes like timeline controls:

Attribute	Video editor meaning
data-start	When the layer starts
data-duration	How long the layer stays active
data-track-index	Timeline track number
data-media-start	Offset into a media file
data-volume	Audio volume for an audio or video clip
data-composition-src	Nested scene or reusable overlay

For GSAP animation, register one paused timeline per composition:

<script>
  window.__timelines = window.__timelines || {};
  const tl = gsap.timeline({ paused: true });

  tl.from("#title", { opacity: 0, y: 40, duration: 0.6 });
  tl.set({}, {}, 5); // keeps the timeline at least 5 seconds long

  window.__timelines["main"] = tl;
</script>

If a video cuts off early, check that the GSAP timeline is at least as long as the intended edit. The final tl.set({}, {}, 5) pattern is the fix.

Render Presets

Goal	Command
Fast iteration	npx hyperframes render --quality draft --output draft.mp4
Review link	npx hyperframes render --quality standard --output review.mp4
Final export	npx hyperframes render --quality high --fps 30 --output final.mp4
Transparent overlay	npx hyperframes render --format webm --output overlay.webm
Deterministic output	npx hyperframes render --docker --output final.mp4

Use WebM for transparent overlays, captions, and lower thirds. Use --docker when you need pixel-consistent output across different machines.

Publish and Share

Use publish when you want to share the editable project, not just the rendered MP4:

npx hyperframes publish

Publish zips the current project, uploads it, and prints a stable hyperframes.dev URL. The URL includes a claim token so the recipient can open it, claim the project, and continue editing in the web app.

npx hyperframes publish ./my-video   # publish a specific folder
npx hyperframes publish --yes        # skip the confirmation prompt in scripts

Publish expects an index.html at the project root. It ignores .git, node_modules, dist, .next, and coverage.

What Agent Browser Is

agent-browser is a browser automation tool for AI agents. It opens Chrome, navigates to your preview, clicks controls, reads page state, and captures screenshots. It is how an agent proves the video preview actually works instead of only saying the code looks right.

Typical verification flow:

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

Use it when you want the agent to open the HyperFrames Studio preview, play or scrub the video, click timeline controls, inspect visible UI text, capture screenshots for review, or record proof of a tested flow.

For editor-facing changes, keep npx hyperframes preview running, then have the agent use agent-browser against the local preview URL.

Quick Fixes

Problem	Command or check
Preview will not start	npx hyperframes doctor
Port already in use	npx hyperframes preview --port 4567
Render fails	npx hyperframes lint then npx hyperframes validate
Need exact frame checks	npx hyperframes snapshot --at 1,2.5,5
Text overflows in the frame	npx hyperframes inspect
Final render is too slow	Try --quality draft, reduce image sizes, or lower --fps
Need to share editable project	npx hyperframes publish

Prompt Guide

How to direct AI agents to build better videos

Timeline Editing

Timing, tracks, and GSAP timeline patterns

Common Mistakes

Pitfalls the linter can’t catch

CLI Reference

Full command reference