auto-compare-video AGENTS.md

HyperFrames Composition Project

Repo layout — multiple videos

This repo holds a series of short comparison videos, each its own self-contained HyperFrames project under videos/<video-name>/ (own package.json, hyperframes.json, meta.json, index.html, assets/, scripts/, renders/, snapshots/). Root-level files (README.md, CLAUDE.md, AGENTS.md, DESIGN.md, vbee.md) are shared across the whole series — DESIGN.md in particular is the fixed layout/style contract every video follows.

All commands below run with cwd inside the specific video's folder (videos/<video-name>/), not the repo root — that's where each video's package.json lives.

The Vbee TTS credentials (.env) live once at the repo root and are shared by every video's scripts/generate-vo.mjs.

To start a new video: create videos/<new-name>/, run hyperframes init inside it, copy the 3-zone layout contract from DESIGN.md, and swap in the new topic's text/images/audio.

Skills — USE THESE FIRST

Always invoke the relevant skill before writing or modifying compositions. Skills encode framework-specific patterns (e.g., window.__timelines registration, data-* attribute semantics, shader-compatible CSS rules) that are NOT in generic web docs. Skipping them produces broken compositions.

Doing anything with HyperFrames? Start at /hyperframes — it tells you what HyperFrames can do and which skill or workflow handles your intent (make a video, TTS / BGM, prep footage, author / animate, render, install blocks), and routes every "make me a…" request (a video, a deck, a composition port) to the right workflow. Read it first, especially when there's no project context to orient you. The workflows it routes to:

• /product-launch-video — a product URL or brief / script → 60-90s product launch / SaaS / promo video.
• /website-to-video — a general website / URL → a video of the site (tour / showcase / social clip from captured visuals); a product launch / promo is /product-launch-video.
• /faceless-explainer — arbitrary text (topic / article / notes), no URL, no website capture → 60-90s faceless explainer.
• /embedded-captions — an existing talking-head video (MP4) → the same footage with captions / subtitles added (rail + embed, or pure-cinematic embed); the footage itself is untouched.
• /talking-head-recut — an existing talking-head / interview / podcast video (MP4) → the same footage packaged with designed graphic overlays (kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, pip) synced to the transcript; the clip plays unchanged underneath. (Plain captions/subtitles → /embedded-captions.)
• /pr-to-video — a GitHub PR (URL / owner/repo#N / "this PR") → 30-90s code-change explainer (changelog / feature reveal / fix / refactor).
• /motion-graphics — a short (typically under 10s) design-led motion graphic, motion-is-the-message, no narration: kinetic type, a stat / number count-up, a chart, a logo sting, a lower-third / overlay, or an animated tweet / headline / captured-page highlight; rendered to MP4 or a transparent overlay. Longer / narrated / custom → /general-video.
• /music-to-video — a music track (audio file, or video to pull audio from) → beat-synced video (lyric / slideshow / kinetic promo). Music drives pacing; user-supplied images / videos are cut onto the same beat grid.
• /slideshow — a presentation / pitch deck / interactive deck — discrete slides, fragment reveals, branching, hotspot navigation, presenter mode. Output is a navigable deck, not a rendered video.
• /general-video — fallback for any other video (title card, longer brand / sizzle reel, multi-scene montage, static loop, custom composition); the original hyperframes authoring flow, any length.