--- name: hyperframes description: Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For dev-loop CLI commands (init, lint, inspect, preview, render) see the hyperframes-cli skill; for asset preprocessing commands (tts, transcribe, remove-background) see the hyperframes-media skill. --- # HyperFrames HTML is the source of truth for video. A composition is an HTML file with `data-*` attributes for timing, a GSAP timeline for animation, and CSS for appearance. The framework handles clip visibility, media playback, and timeline sync. ## Approach ### Discovery (exploratory requests only) For open-ended requests ("make me a product launch video", "create something for our brand") where the user hasn't committed to a direction, understand intent before picking colors: - **Audience** — who watches this? Developers? Executives? General consumers? - **Platform** — where does it play? Social (15s), website hero, product demo, internal? - **Priority** — what matters most? Motion quality? Content accuracy? Brand fidelity? Speed? - **Variations** — does the user want options, or a single best shot? For specific requests ("add a title card", "fix the timing on scene 3"), skip discovery. For exploratory requests, consider offering 2-3 variations that differ meaningfully — not just color swaps, but different pacing, energy levels, or structural approaches. One safe/expected, one ambitious. Don't mandate this — it's a tool available when appropriate. ### Step 1: Design system If `design.md` or `DESIGN.md` exists in the project, read it first (check both casings — they're different files on Linux). It's the source of truth for brand colors, fonts, and constraints. Use its exact values — don't invent colors or substitute fonts. Any format works (YAML frontmatter, prose, tables — just extract the values). If it names fonts you can't find locally (no `fonts/` directory with `.woff2` files, not a built-in font), warn the user before writing HTML: "design.md specifies [font name] but no font files found. Please add .woff2 files to `fonts/` or I'll fall back to [closest built-in alternative]." If no `design.md` exists, offer the user a choice: 1. **User named a style or mood?** → Read [visual-styles.md](./visual-styles.md) for the 8 named presets. Pick the closest match. 2. **Want to browse options visually?** → Run the design picker: read [references/design-picker.md](references/design-picker.md) for the full workflow. This serves a visual picker page. The user configures mood, palette, typography, and motion in the browser, then copies the generated design.md and pastes it back into the conversation. 3. **Want to skip and go fast?** → Ask: mood, light or dark, any brand colors/fonts? Then pick a palette from [house-style.md](./house-style.md). **design.md defines the brand. It does not define video composition rules.** Those come from [references/video-composition.md](references/video-composition.md) and [house-style.md](./house-style.md). Use brand colors at video-appropriate scale — not at web-UI opacity. ### Step 2: Prompt expansion Always run on every composition (except single-scene pieces and trivial edits). This step grounds the user's intent against `design.md` and `house-style.md` and produces a consistent intermediate that every downstream agent reads the same way. Read [references/prompt-expansion.md](references/prompt-expansion.md) for the full process and output format. ### Step 3: Plan Before writing HTML, think at a high level: 1. **What** — what should the viewer experience? Identify the narrative arc, key moments, and emotional beats. 2. **Structure** — how many compositions, which are sub-compositions vs inline, what tracks carry what (video, audio, overlays, captions). 3. **Rhythm** — declare your scene rhythm before implementing. Which scenes are quick hits, which are holds, where do shaders land, where does energy peak. Name the pattern: fast-fast-SLOW-fast-SHADER-hold. Read [references/beat-direction.md](references/beat-direction.md) for rhythm templates. 4. **Timing** — which clips drive the duration, where do transitions land, what's the pacing. 5. **Layout** — build the end-state first. See "Layout Before Animation" below. 6. **Animate** — then add motion using the rules below. **Build what was asked.** A request for "a title card" is not a request for "a title card + 3 supporting scenes + ambient music + captions." Every scene, every element, every tween should earn its place. If additional scenes or elements would genuinely improve the piece, propose them — don't add them. For small edits (fix a color, adjust timing, add one element), skip straight to the rules. Before writing ANY composition HTML — verify you have a visual identity from Step 1. If you're reaching for `#333`, `#3b82f6`, or `Roboto`, you skipped it. ## Layout Before Animation Position every element where it should be at its **most visible moment** — the frame where it's fully entered, correctly placed, and not yet exiting. Write this as static HTML+CSS first. No GSAP yet. **Why this matters:** If you position elements at their animated start state (offscreen, scaled to 0, opacity 0) and tween them to where you think they should land, you're guessing the final layout. Overlaps are invisible until the video renders. By building the end state first, you can see and fix layout problems before adding any motion. ### The process 1. **Identify the hero frame** for each scene — the moment when the most elements are simultaneously visible. This is the layout you build. 2. **Write static CSS** for that frame. The `.scene-content` container MUST fill the full scene using `width: 100%; height: 100%; padding: Npx;` with `display: flex; flex-direction: column; gap: Npx; box-sizing: border-box`. Use padding to push content inward — NEVER `position: absolute; top: Npx` on a content container. Absolute-positioned content containers overflow when content is taller than the remaining space. Reserve `position: absolute` for decoratives only. 3. **Add entrances with `gsap.from()`** — animate FROM offscreen/invisible TO the CSS position. The CSS position is the ground truth; the tween describes the journey to get there. (In sub-compositions loaded via `data-composition-src`, prefer `gsap.fromTo()` — see load-bearing GSAP rules in [references/motion-principles.md](references/motion-principles.md).) 4. **Add exits with `gsap.to()`** — animate TO offscreen/invisible FROM the CSS position. ### Example ```css /* scene-content fills the scene, padding positions content */ .scene-content { display: flex; flex-direction: column; justify-content: center; width: 100%; height: 100%; padding: 120px 160px; gap: 24px; box-sizing: border-box; } .title { font-size: 120px; } .subtitle { font-size: 42px; } /* Container fills any scene size (1920x1080, 1080x1920, etc). Padding positions content. Flex + gap handles spacing. */ ``` **WRONG — hardcoded dimensions and absolute positioning:** ```css .scene-content { position: absolute; top: 200px; left: 160px; width: 1920px; height: 1080px; display: flex; /* ... */ } ``` ```js // Step 3: Animate INTO those positions tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0); tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2); tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3); // Step 4: Animate OUT from those positions tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3); tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1); tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2); ``` ### When elements share space across time If element A exits before element B enters in the same area, both should have correct CSS positions for their respective hero frames. The timeline ordering guarantees they never visually coexist — but if you skip the layout step, you won't catch the case where they accidentally overlap due to a timing error. ### What counts as intentional overlap Layered effects (glow behind text, shadow elements, background patterns) and z-stacked designs (card stacks, depth layers) are intentional. The layout step is about catching **unintentional** overlap — two headlines landing on top of each other, a stat covering a label, content bleeding off-frame. ## Data Attributes ### All Clips | Attribute | Required | Values | | ------------------ | --------------------------------- | ------------------------------------------------------ | | `id` | Yes | Unique identifier | | `data-start` | Yes | Seconds or clip ID reference (`"el-1"`, `"intro + 2"`) | | `data-duration` | Required for img/div/compositions | Seconds. Video/audio defaults to media duration. | | `data-track-index` | Yes | Integer. Same-track clips cannot overlap. | | `data-media-start` | No | Trim offset into source (seconds) | | `data-volume` | No | 0-1 (default 1) | `data-track-index` does **not** affect visual layering — use CSS `z-index`. ### Composition Clips | Attribute | Required | Values | | ---------------------------- | -------- | ----------------------------------------------------------------- | | `data-composition-id` | Yes | Unique composition ID | | `data-start` | Yes | Start time (root composition: use `"0"`) | | `data-duration` | Yes | Takes precedence over GSAP timeline duration | | `data-width` / `data-height` | Yes | Pixel dimensions (1920x1080 or 1080x1920) | | `data-composition-src` | No | Path to external HTML file | | `data-variable-values` | No | JSON object of per-instance variable overrides on a sub-comp host | On the root `` element: | Attribute | Required | Values | | ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | `data-composition-variables` | No | JSON array of declared variables (id/type/label/default) — drives Studio editing UI and provides defaults for `getVariables()` | ## Composition Structure Sub-compositions loaded via `data-composition-src` use a `

Hyperframes

Description

Latest Changes

Install Hyperframes with One Click