frames/docs/guides/video-editor-cheatsheet.mdx

---
title: Video Editor Cheatsheet
description: "Fast reference for video editors and creative people directing agents, cutting timing, tweaking layouts, previewing, and publishing Frames projects."
---

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

## The Fast Loop

```bash
npx @hanzo/frames init my-video --example blank
cd my-video
npx @hanzo/frames 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:

```bash
npx @hanzo/frames lint
npx @hanzo/frames check
npx @hanzo/frames render --quality standard --output review.mp4
```

For fast iteration renders, use draft quality:

```bash
npx @hanzo/frames render --quality draft --output draft.mp4
```

For final delivery:

```bash
npx @hanzo/frames render --quality high --fps 30 --output final.mp4
```

## Terminal Shortcuts

Move around projects quickly:

```bash
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 Frames project folders:

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

Run Frames 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:

```bash
npx @hanzo/frames preview
```

Use a different port if `3002` is already busy:

```bash
npx @hanzo/frames preview --port 4567
```

Inside the Studio, shortcuts are grouped the same way the playbar's `⌨` panel groups them — playback first, then work-area markers, view controls, and app-level commands. Open the `⌨` panel in the playbar for an in-app cheatsheet, a frame-jump input, and live readouts of the in/out points.

### Playback

| Shortcut | Action |
| --- | --- |
| `Space` | Play or pause |
| `K` | Stop |
| `J` | Play backward (press again to shuttle faster) |
| `L` | Play forward (press again to shuttle faster) |
| `←` / `→` | Step 1 frame |
| `Shift+←` / `Shift+→` | Step 10 frames |

`J` and `L` build the classic NLE shuttle: each repeat ramps the playback rate up. Tap `K` between shuttle bursts to stop. With `K` held, tapping `J` or `L` steps one frame in that direction.

### Work area (in / out points)

| Shortcut | Action |
| --- | --- |
| `I` | Set in-point at the playhead |
| `Shift+I` | Clear in-point |
| `O` | Set out-point at the playhead |
| `Shift+O` | Clear out-point |
| `A` | Jump to in-point (or composition start if unset) |
| `E` | Jump to out-point (or composition end if unset) |

The in and out points define a **work area**. When loop is on, both forward and backward playback loop within those boundaries — useful for tightening a transition or scrubbing a single clip without trimming it. The seek bar renders a teal band between in and out, with tick markers at each point. Clear the markers from the `⌨` panel or with `Shift+I` and `Shift+O`.

### View

| Shortcut | Action |
| --- | --- |
| `Cmd+Scroll` / `Ctrl+Scroll` over the preview | Zoom the preview at the cursor |

### Application

| Shortcut | Action |
| --- | --- |
| `Shift+T` | Show or hide the timeline editor |
| `Cmd+1` / `Ctrl+1` | Switch sidebar to Compositions |
| `Cmd+2` / `Ctrl+2` | Switch sidebar to Assets |
| `Cmd+Z` / `Ctrl+Z` | Undo |
| `Cmd+Shift+Z` / `Ctrl+Shift+Z` / `Ctrl+Y` | Redo |
| `Delete` / `Backspace` | Delete the selected timeline clip or DOM element (when not typing in an editor) |
| `Escape` | Leave a sub-composition or close editor 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 is expected — preview plays in real time, render captures one frame at a time.
</Tip>

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

## Timing Cheatsheet

Every visible timed layer should usually be a clip:

```html
<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:

```html
<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>
```

<Warning>
  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.
</Warning>

## Render Presets

| Goal | Command |
| --- | --- |
| Fast iteration | `npx @hanzo/frames render --quality draft --output draft.mp4` |
| Review link | `npx @hanzo/frames render --quality standard --output review.mp4` |
| Final export | `npx @hanzo/frames render --quality high --fps 30 --output final.mp4` |
| Transparent overlay | `npx @hanzo/frames render --format webm --output overlay.webm` |
| Deterministic output | `npx @hanzo/frames 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:

```bash
npx @hanzo/frames publish
```

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

```bash
npx @hanzo/frames publish ./my-video   # publish a specific folder
npx @hanzo/frames 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:

```bash
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 Frames 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 @hanzo/frames 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 @hanzo/frames doctor` |
| Port already in use | `npx @hanzo/frames preview --port 4567` |
| Render fails | `npx @hanzo/frames lint` then `npx @hanzo/frames check` |
| Need exact frame checks | `npx @hanzo/frames snapshot --at 1,2.5,5` |
| Text overflows in the frame | `npx @hanzo/frames check` |
| Final render is too slow | Try `--quality draft`, reduce image sizes, or lower `--fps` |
| Need to share editable project | `npx @hanzo/frames publish` |

<CardGroup cols={2}>
  <Card title="Prompt Guide" icon="wand-magic-sparkles" href="/guides/prompting">
    How to direct AI agents to build better videos
  </Card>
  <Card title="Timeline Editing" icon="timeline" href="/guides/timeline-editing">
    Timing, tracks, and GSAP timeline patterns
  </Card>
  <Card title="Common Mistakes" icon="circle-exclamation" href="/guides/common-mistakes">
    Pitfalls the linter can't catch
  </Card>
  <Card title="CLI Reference" icon="terminal" href="/packages/cli">
    Full command reference
  </Card>
</CardGroup>