HyperFrames: Make a Video End to End

HyperFrames renders video from HTML: a composition is an HTML file whose elements declare timing with data-* attributes, whose animation runs on a seekable timeline, and whose media playback the framework owns. This skill is where every video job starts. It works out what state the project is in, turns "make me a video" into a confirmed brief, chooses the route that fits the deliverable, and runs the production from plan to a finished MP4. The standard: the message is clear by the second beat, every frame was looked at by you before the owner sees it, the scope is exactly what was asked, and nothing is rendered as final before the owner says go (unless they told you to just make it).

When to use

• "Make a 30-second promo for our site", "a launch video for the new feature", "explain how DNS works as a video", "animate this stat", "add captions to my clip", "a pitch deck we can click through", "a video for this song", "turn PR #1187 into a changelog video", "port my Remotion project".
• Any request to edit, inspect, check, preview or render an existing HyperFrames project.
• Inputs can be a website URL, a GitHub pull request, a script or brief, notes, footage, music, or exported design files.
• HyperFrames is the default way to make the video unless the owner chooses another tool or only wants a screen recording.

What you need

• Your computer set up for HyperFrames: run the check in references/computer-setup.md first (Node 22+ and FFmpeg are not installed by default) and start every CLI call with its environment line. Work goes in ~/Desktop/<your name> - Work space/<job>/<project>/.
• The request in the owner's words, and any material they gave (files, links, a script, brand guidelines). If you cannot find an attached file on your computer, ask with clarify.
• The owner's remembered video preferences and saved recipes from memory (destination, aspect, language, voice, style preset, review preference).
• Access, per route: a website is captured on your own computer (npx hyperframes capture) or read in your browser; a private GitHub PR needs the connected GitHub app or your browser signed in by the owner (a public PR's diff downloads without either); footage and music come from the owner. When none of these is available, ask the owner via clarify or work from files they provide.
• Voice comes from your text_to_speech tool and pictures from image_generate. Music and sound effects only from sources whose licence allows commercial use, checked and recorded (see media-use). No hosted rendering, no third-party AI service, no API keys.

Method

1. Start from the project's state

Apply the first row that matches; do not evaluate lower rows.

State	Action
The owner explicitly asks to port existing Remotion source	Route remotion-to-hyperframes (see references/routes.md). Skip the interview.
A specific operation on an existing project: inspect, diagnose, check, preview, render, batch-render	Do only that operation; load hyperframes-cli.
A question, a hold, an idea with no concrete change, or a felt note on a built film	Follow hyperframes-studio, step 1: classify the message before touching files.
A new film asked for inside an existing project	Follow hyperframes-studio, step 6 (a follow-on stays; a new aspect or route is a new project).
A specific edit to an existing project	Make the edit; no interview. Read npx hyperframes timeline --json instead of opening every file.
BRIEF.md exists	Read its workflow, flow and storyboard, then execute that route. Ask no brief questions.
No brief, but hyperframes.json or STORYBOARD.md exists	Resume from the files and remembered preferences. If the route cannot be told apart, ask one routing question only.
Fresh creation	Run the intent interview (references/intent-interview.md), then route once with step 3's table.

If a fresh request does not say what the video is about, ask that before routing, after checking memory and saved recipes.

2. Keep the project's CLI current

A scaffolded project pins hyperframes@<version> in its package.json scripts, and the pin never advances by itself. When you resume a project with a pin, probe once before the first command that affects the render:

npx hyperframes@latest upgrade --project . --check

Keep the explicit . (older releases read the next flag as the directory). If the project is behind, apply with npx hyperframes@latest upgrade --project . and verify with npx hyperframes check. A passing check proves the compositions still validate, not that frames are identical, so name the old and new version in your summary. If the check fails, revert the package.json change, stay on the pin, and say why.

3. Route fresh creation

Match the deliverable the owner wants, not a word they used in passing. Use the first matching row, then read that route's entry in references/routes.md (its contract, interview questions and how to run it here). If the request does not satisfy the route's contract, keep routing.

Priority	Request	Route
1	Explicitly port existing Remotion source	remotion-to-hyperframes
2	A presentation, pitch deck or navigable interactive deck	slideshow
3	Plain captions or subtitles on existing talking-head footage, footage unchanged	embedded-captions
4	Designed overlays on existing talking-head, interview or podcast footage, footage unchanged	talking-head-recut
5	A beat-synced video from a music track, no narration or site capture	music-to-video
6	An explicitly short, unnarrated, motion-first unit, typically under 10 s	motion-graphics
7	Explain a GitHub pull request or code change	pr-to-video
8	Market or show a website, product, app or company from a URL or site brief	product-launch-video
9	Explain a topic, article or notes with invented visuals, no product or site	faceless-explainer
10	Any other custom video or composition	general-video

Resolving common ambiguities:

• A short animated title, logo sting, stat hit, chart hit, map hit or standalone lower-third is motion-graphics when it is unnarrated and motion is the message. A static title card, a narrated sequence, a longer montage or a custom loop is general-video.
• A short motion graphic may use a URL, tweet or article as source material; a generic "make a video from this site" is product-launch-video. A launch video from the owner's own code project (no live site): see brag.
• Footage plus captions is embedded-captions; footage plus designed cards is talking-head-recut. Retiming, reordering, recolouring or remixing footage is a custom edit: general-video.
• A music file selects music-to-video only when its beat grid drives the piece. Music as a bed does not change the route.
• "I want a storyboard" changes the review, not the route; with no other signal, use general-video. A confirmed storyboard sheet may itself be the deliverable.
• The narrative routes work up to about 3 minutes and are strongest at 30 to 90 s. Route a clearly longer piece to general-video. Length never overrides a port, deck, caption, overlay or music-driven deliverable.

4. Confirm the brief once, then build from it

For fresh creation the interview (references/intent-interview.md) runs the whole conversation: memory and recipes first, triage, the pitch round for unformed requests (references/pitch-round.md), the route's must-have questions, the two run-shape questions (storyboard review? automation or companion?), one capability offer (references/capability-menu.md), and a hand-off summary that separates what the owner said from what you inferred. Scaffold the project, then write BRIEF.md (references/brief-format.md). From then on BRIEF.md is the only routing record: answer every later "what did we agree?" from it, and write each confirmed change back into it.

5. Plan, review, produce, deliver

1. Plan. Write STORYBOARD.md: the decisions (message, audience, arc, format, the spine that threads every beat), then one ## Frame N block per scene with its on-screen content, voiceover, duration, motion citation and why (references/storyboard.md). Write SCRIPT.md when there is narration. Establish the design (frame.md, see hyperframes-creative) before any HTML. Search the registry for every named look before planning to hand-build it (hyperframes-registry).
2. Review the plan when storyboard: yes: the plan in chat, then a sketched storyboard.html rendered to stills for the owner (references/review-loop.md). Autonomous runs post the same summary as a heads-up and continue.
3. Produce in dependency order (references/production-loop.md): registry blocks installed once, assets staged, voice lines made with text_to_speech and measured, scenes built (inline for up to about six short scenes; with delegate_task workers beyond that, per references/scene-workers.md), durations synced to the real voice, the index assembled, transitions, captions, then npx hyperframes check passing and a contact sheet you have looked at with vision_analyze.
4. Final look. The owner cannot open a preview on your computer. Send key frames and a --quality draft render with MEDIA:/absolute/path and ask one thing: render the final, or what changes? Render --quality delivery only on a yes (an autonomous run asks this one question too, unless the owner said not to ask anything).
5. Deliver the MP4 attached with MEDIA:/absolute/path, verified with ffprobe, with the summary below. Offer once to save the run as a recipe (references/review-loop.md).

6. Load the domain skills you need

Load with skill_view only what the current stage needs. They inform the work; this skill keeps ownership of the deliverable.

Need	Skill
Composition structure, timing attributes, tracks, sub-compositions, variables, media, determinism	hyperframes-core
Init, lint, check, snapshot, compare, batch and local render, diagnostics	hyperframes-cli
Zoom, punch-in, reframe, Ken Burns, camera moves, masks, paths, SVG, 3D keyframes	hyperframes-keyframes
Registry blocks and components; any named look (CRT, glitch, grain, shimmer, confetti, chart, code window, map) before hand-building it	hyperframes-registry
Talking with the owner about a built film; timeline layout; safe zones	hyperframes-studio
Motion rules, scene blueprints, transitions, runtime adapters	hyperframes-animation
Design spec, palette, typography, narration, beat planning, storyboard recipe	hyperframes-creative
Voice, music, sound effects, images, logos, captions, transcripts, grades, media treatments	media-use
Fades, ducking, carving the music under a voice, audio effects	hyperframes-audio

Edit requests that cross domains need every skill in their row: a cut, trim, splice or reorder is hyperframes-core (copy its creator-editing-recipes.md); a zoom or camera move adds hyperframes-keyframes (animate the inner wrapper, not the timed clip); a match cut or whip pan adds hyperframes-animation and hyperframes-registry; fades, ducking or audio effects add hyperframes-audio; laying a project out to read well adds hyperframes-studio; sourcing or generating media is media-use. A constant data-playback-rate is render-safe; a speed ramp is a rate lane in data-automation. Feedback that footage looks dark, flat or dull, should feel retro, or needs a face hidden is a media treatment: media-use, not a CSS filter. When a build carries important photographic media, include one media-polish look in the final pass; leaving it unchanged is a valid result.

Output

• The finished video attached in your reply with MEDIA:/absolute/path/to/renders/<name>.mp4, plus a delivery note:

**<Title>** (<route>), <duration> s, <width>x<height>, <fps> fps, <size> MB
File: ~/Desktop/<name> - Work space/<job>/<project>/renders/<name>.mp4
Message: "<the one sentence>" for <audience>, made for <destination>.
Scenes: 01 Hook (0 to 4.2 s), 02 Problem (4.2 to 9 s), ... (contact sheet attached)
Decisions I made: <inferred choices with their reasons>
Sources and licences: voice <tool/voice>, music <title, source, licence>, footage <owner's>
Next: say which frame to change by number, or "save as recipe".

• The project folder stays in your work space (BRIEF.md, STORYBOARD.md, SCRIPT.md, index.html, compositions/, assets/, assets/LICENSES.md, renders/). Copy the final to ~/Desktop/Team/ too when teammates need it.

Checks before you finish

• The scope is exactly what was asked: a title card is not a title card plus three scenes and music.
• npx hyperframes check passes (lint included, contrast resolved, 0 layout errors) and you looked at a contact sheet of scene midpoints and every cut.
• The owner approved the final look, or said to just make it; the delivery render used --quality delivery.
• The MP4 exists, is non-empty, and ffprobe shows the expected duration (equal to the root data-duration), size, fps and an audio stream when the film has sound.
• BRIEF.md and STORYBOARD.md match what was built, the stated runtime is the real one, and every third-party asset's licence is recorded.

Pitfalls

• Asking what memory already knows. Check memory and recipes before the first question; recommend the remembered value and name where it came from.
• A form question for an unformed request. "What's the message?" hands the owner the blank they came to have filled. Pitch five concepts instead.
• Rendering because checks passed. Checks are not approval. Send the review package and wait for the answer.
• A localhost link for the owner. They cannot open it. Send frames and a draft MP4.
• Approximating the product. Use real captures and recordings, or hold the slot with a labelled placeholder.
• The slideshow and the screensaver. Every beat a fresh card, or motion that says nothing: both read as generic. Reveal on the voice, keep one world, give one beat a held frame.
• Silent hosted dependencies. Never set an API key, never run cloud, publish or feedback, never send frames to a hosted model. Everything renders on your computer.