hyperframes

name

hyperframes

description

Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, shader backgrounds, procedural WebGL canvas layers, 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), create GLSL/WebGL shader visuals, or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For CLI commands (init, lint, preview, render, transcribe, tts) see the hyperframes-cli 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

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. Timing — which clips drive the duration, where do transitions land, what's the pacing.
4. Layout — build the end-state first. See "Layout Before Animation" below.
5. Animate — then add motion using the rules below.

For small edits (fix a color, adjust timing, add one element), skip straight to the rules.

Visual Identity Gate

Before writing ANY composition HTML, you MUST have a visual identity defined. Do NOT write compositions with default or generic colors.

The locked company brand source, when present, is /workspace/library/design/DESIGN.md. Treat it as authoritative over HyperFrames house palettes and generic style adjectives. Read it first, then translate its brand tokens into CSS custom properties on the composition root before writing scene styles.

Check in this order:

1. /workspace/library/design/DESIGN.md exists? → Read it. Use its exact colors, fonts/typefaces, spacing rhythm, component treatment, imagery rules, motion tone, and "What NOT to Do" constraints.
2. DESIGN.md exists in the project? → Read it. Use its exact colors, fonts/typefaces, motion rules, imagery guidance, and "What NOT to Do" constraints.
3. visual-style.md exists? → Read it. Apply its style_prompt_full and structured fields. (Note: visual-style.md is a project-specific file. visual-styles.md is the style library with 8 named presets — different files.)
4. User named a style (e.g., "Swiss Pulse", "dark and techy", "luxury brand")? → Read visual-styles.md for the 8 named presets. Generate a minimal DESIGN.md with: ## Style Prompt (one paragraph), ## Colors (3-5 hex values with roles), ## Typography (1-2 font families), ## Imagery (logo/photo/illustration/texture direction when relevant), ## What NOT to Do (3-5 anti-patterns).
5. None of the above? → Ask 3 questions before writing any HTML:
   • What's the mood? (explosive / cinematic / fluid / technical / chaotic / warm)
   • Light or dark canvas?
   • Any specific brand colors, fonts, or visual references? Then generate a minimal DESIGN.md from the answers.

Every composition must trace its palette, typography, and imagery treatment back to the locked company DESIGN.md, a project DESIGN.md, visual-style.md, or explicit user direction. If you're reaching for #333, #3b82f6, or Roboto without seeing them in the brand source — you skipped this step.

For motion defaults, sizing, entrance patterns, and easing — follow house-style.md. The house style handles HOW things move. The DESIGN.md handles WHAT things look like.

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.
4. Add exits with gsap.to() — animate TO offscreen/invisible FROM the CSS position.

Example

/* 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:

.scene-content {
  position: absolute;
  top: 200px;
  left: 160px;
  width: 1920px;
  height: 1080px;
  display: flex; /* ... */
}

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

Composition Structure

Sub-compositions loaded via data-composition-src use a <template> wrapper. Standalone compositions (the main index.html) do NOT use <template> — they put the data-composition-id div directly in <body>. Using <template> on a standalone file hides all content from the browser and breaks rendering.

Sub-composition structure:

<template id="my-comp-template">
  <div data-composition-id="my-comp" data-width="1920" data-height="1080">
    <!-- content -->
    <style>
      [data-composition-id="my-comp"] {
        /* scoped styles */
      }
    </style>
    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
    <script>
      window.__timelines = window.__timelines || {};
      const tl = gsap.timeline({ paused: true });
      // tweens...
      window.__timelines["my-comp"] = tl;
    </script>
  </div>
</template>

Load in root: <div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>

Video and Audio

Video must be muted playsinline. Audio is always a separate <audio> element:

<video
  id="el-v"
  data-start="0"
  data-duration="30"
  data-track-index="0"
  src="video.mp4"
  muted
  playsinline
></video>
<audio
  id="el-a"
  data-start="0"
  data-duration="30"
  data-track-index="2"
  src="video.mp4"
  data-volume="1"
></audio>

Timeline Contract

• All timelines start { paused: true } — the player controls playback
• Register every timeline: window.__timelines["<composition-id>"] = tl
• Framework auto-nests sub-timelines — do NOT manually add them
• Duration comes from data-duration, not from GSAP timeline length
• Never create empty tweens to set duration

Shader Canvases

For GLSL/WebGL shader backgrounds, particles, raymarched objects, SDF ornaments, or procedural visual layers, read the shader-authoring skill before writing the composition. HyperFrames shaders must be deterministic and seekable:

• compile shaders synchronously during page load
• render once at time 0
• drive iTime from a GSAP timeline tween, not requestAnimationFrame
• avoid Date.now(), performance.now(), Math.random(), async setup, and infinite repeats
• expose window.__hf = { duration, seek } synchronously at top level; the screenshot-mode capture path polls this adapter and can time out even when window.__timelines exists
• keep window.__timelines["<composition-id>"] registered too, so the same composition works in the normal timeline-driven path
• use @hyperframes/shader-transitions for scene-to-scene texture transitions when available; use custom shader canvases for ambient/procedural layers

If render logs say HeadlessExperimental.beginFrame unavailable and the engine falls back to screenshot mode, be suspicious of live WebGL canvas layers. They can produce a ready MP4 where DOM overlays render but the GL canvas is blank. For must-see procedural visuals such as cells, organelles, particles, diagrams, or generated scientific motion, prefer a deterministic Canvas2D frame(t) renderer unless WebGL is essential. If WebGL is essential, inspect actual MP4 frames for nonblank canvas pixels before calling the video done.

Rules (Non-Negotiable)

Deterministic: No Math.random(), Date.now(), or time-based logic. Use a seeded PRNG if you need pseudo-random values (e.g. mulberry32).

GSAP: Only animate visual properties (opacity, x, y, scale, rotation, color, backgroundColor, borderRadius, transforms). Do NOT animate visibility, display, or call video.play()/audio.play().

Animation conflicts: Never animate the same property on the same element from multiple timelines simultaneously.

No repeat: -1: Infinite-repeat timelines break the capture engine. Calculate the exact repeat count from composition duration: repeat: Math.ceil(duration / cycleDuration) - 1.

Synchronous timeline construction: Never build timelines inside async/await, setTimeout, or Promises. The capture engine reads window.__timelines synchronously after page load. Fonts are embedded by the compiler, so they're available immediately — no need to wait for font loading.

Never do:

1. Forget window.__timelines registration
2. Use video for audio — always muted video + separate <audio>
3. Nest video inside a timed div — use a non-timed wrapper
4. Use data-layer (use data-track-index) or data-end (use data-duration)
5. Animate video element dimensions — animate a wrapper div
6. Call play/pause/seek on media — framework owns playback
7. Create a top-level container without data-composition-id
8. Use repeat: -1 on any timeline or tween — always finite repeats
9. Build timelines asynchronously (inside async, setTimeout, Promise)
10. Use gsap.set() on clip elements from later scenes — they don't exist in the DOM at page load. Use tl.set(selector, vars, timePosition) inside the timeline at or after the clip's data-start time instead.
11. Use <br> in content text — forced line breaks don't account for actual rendered font width. Text that wraps naturally + a <br> produces an extra unwanted break, causing overlap. Let text wrap via max-width instead. Exception: short display titles where each word is deliberately on its own line (e.g., "THE\nIMMORTAL\nGAME" at 130px).

Scene Transitions (Non-Negotiable)

Every multi-scene composition MUST follow ALL of these rules. Violating any one of them is a broken composition.

1. ALWAYS use transitions between scenes. No jump cuts. No exceptions.
2. ALWAYS use entrance animations on every scene. Every element animates IN via gsap.from(). No element may appear fully-formed. If a scene has 5 elements, it needs 5 entrance tweens.
3. NEVER use exit animations except on the final scene. This means: NO gsap.to() that animates opacity to 0, y offscreen, scale to 0, or any other "out" animation before a transition fires. The transition IS the exit. The outgoing scene's content MUST be fully visible at the moment the transition starts.
4. Final scene only: The last scene may fade elements out (e.g., fade to black). This is the ONLY scene where gsap.to(..., { opacity: 0 }) is allowed.

WRONG — exit animation before transition:

// BANNED — this empties the scene before the transition can use it
tl.to("#s1-title", { opacity: 0, y: -40, duration: 0.4 }, 6.5);
tl.to("#s1-subtitle", { opacity: 0, duration: 0.3 }, 6.7);
// transition fires on empty frame

RIGHT — entrance only, transition handles exit:

// Scene 1 entrance animations
tl.from("#s1-title", { y: 50, opacity: 0, duration: 0.7, ease: "power3.out" }, 0.3);
tl.from("#s1-subtitle", { y: 30, opacity: 0, duration: 0.5, ease: "power2.out" }, 0.6);
// NO exit tweens — transition at 7.2s handles the scene change
// Scene 2 entrance animations
tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, 8.0);

Animation Guardrails

• Offset first animation 0.1-0.3s (not t=0)
• Vary eases across entrance tweens — use at least 3 different eases per scene
• Don't repeat an entrance pattern within a scene
• Avoid full-screen linear gradients on dark backgrounds (H.264 banding — use radial or solid + localized glow)
• 60px+ headlines, 20px+ body, 16px+ data labels for rendered video
• font-variant-numeric: tabular-nums on number columns

When no visual-style.md or animation direction is provided, follow house-style.md for aesthetic defaults.

Typography and Assets

• Fonts: Just write the font-family you want in CSS — the compiler embeds supported fonts automatically. If a font isn't supported, the compiler warns.
• Add crossorigin="anonymous" to external media
• For dynamic text overflow, use window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })
• All files live at the project root alongside index.html; sub-compositions use ../

Editing Existing Compositions

• Read the full composition first — match existing fonts, colors, animation patterns
• Only change what was requested
• Preserve timing of unrelated clips

Output Checklist

• npx hyperframes lint and npx hyperframes validate both pass
• Contrast warnings addressed (see Quality Checks below)
• Animation choreography verified (see Quality Checks below)
• Final result is visually correct, not just technically rendered

Render Success vs Visual Success

render_status=ready only means the pipeline produced an MP4 successfully. It does not prove the composition is good.

Before calling the work done, sanity-check for these failure modes:

• Blank or near-blank frames where only the background renders
• Blank WebGL/procedural canvas layers where DOM overlays still render, especially after screenshot-mode fallback
• A single static frame for the whole video because the timeline never animates
• Scene content offscreen because CSS was written for the animated start state instead of the hero frame
• Text or stats rendered but clipped, overlapped, or unreadable
• Missing transitions, causing scenes to feel like jump cuts

If the video is blank or visually wrong, treat it as a composition bug even if the render succeeded. Fix the HTML/CSS/GSAP and re-run the create_hyperframes_composition tool.

Quality Checks

Contrast

hyperframes validate runs a WCAG contrast audit by default. It seeks to 5 timestamps, screenshots the page, samples background pixels behind every text element, and computes contrast ratios. Failures appear as warnings:

⚠ WCAG AA contrast warnings (3):
  · .subtitle "secondary text" — 2.67:1 (need 4.5:1, t=5.3s)

If warnings appear:

• On dark backgrounds: brighten the failing color until it clears 4.5:1 (normal text) or 3:1 (large text, 24px+ or 19px+ bold)
• On light backgrounds: darken it
• Stay within the palette family — don't invent a new color, adjust the existing one
• Re-run hyperframes validate until clean

Use --no-contrast to skip if iterating rapidly and you'll check later.

Animation Map

After authoring animations, run the animation map to verify choreography:

node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \
  --out <composition-dir>/.hyperframes/anim-map

Outputs a single animation-map.json with:

• Per-tween summaries: "#card1 animates opacity+y over 0.50s. moves 23px up. fades in. ends at (120, 200)"
• ASCII timeline: Gantt chart of all tweens across the composition duration
• Stagger detection: reports actual intervals ("3 elements stagger at 120ms")
• Dead zones: periods over 1s with no animation — intentional hold or missing entrance?
• Element lifecycles: first/last animation time, final visibility
• Scene snapshots: visible element state at 5 key timestamps
• Flags: offscreen, collision, invisible, paced-fast (under 0.2s), paced-slow (over 2s)

Read the JSON. Scan summaries for anything unexpected. Check every flag — fix or justify. Verify the timeline shows the intended choreography rhythm. Re-run after fixes.

Skip on small edits (fixing a color, adjusting one duration). Run on new compositions and significant animation changes.

---

References (loaded on demand)

• references/captions.md — Captions, subtitles, lyrics, karaoke synced to audio. Tone-adaptive style detection, per-word styling, text overflow prevention, caption exit guarantees, word grouping. Read when adding any text synced to audio timing.

• references/tts.md — Text-to-speech with Kokoro-82M. Voice selection, speed tuning, TTS+captions workflow. Read when generating narration or voiceover.

• references/audio-reactive.md — Audio-reactive animation: map frequency bands and amplitude to GSAP properties. Read when visuals should respond to music, voice, or sound.

• references/css-patterns.md — CSS+GSAP marker highlighting: highlight, circle, burst, scribble, sketchout. Deterministic, fully seekable. Read when adding visual emphasis to text.

• references/typography.md — Typography: font pairing, OpenType features, dark-background adjustments, font discovery script. Always read — every composition has text.

• references/motion-principles.md — Motion design principles: easing as emotion, timing as weight, choreography as hierarchy, scene pacing, ambient motion, anti-patterns. Read when choreographing GSAP animations.

• visual-styles.md — 8 named visual styles (Swiss Pulse, Velvet Standard, Deconstructed, Maximalist Type, Data Drift, Soft Signal, Folk Frequency, Shadow Cut) with hex palettes, GSAP easing signatures, and shader pairings. Read when user names a style or when generating DESIGN.md.

• house-style.md — Default motion, sizing, and color palettes when no style is specified.

• patterns.md — PiP, title cards, slide show patterns.

• data-in-motion.md — Data, stats, and infographic patterns.

• references/transcript-guide.md — Transcription commands, whisper models, external APIs, troubleshooting.

• references/dynamic-techniques.md — Dynamic caption animation techniques (karaoke, clip-path, slam, scatter, elastic, 3D).

• shader-authoring — GLSL/WebGL technique routing, ShaderToy-to-WebGL2 adaptation, deterministic HyperFrames shader canvas pattern, and HTML/iframe artifact shader guidance. Read for shader backgrounds, ray marching, particles, procedural noise, SDF visuals, or custom WebGL layers.

• references/transitions.md — Scene transitions: crossfades, wipes, reveals, shader transitions. Energy/mood selection, CSS vs WebGL guidance. Always read for multi-scene compositions — scenes without transitions feel like jump cuts.

  • transitions/catalog.md — Hard rules, scene template, and routing to per-type implementation code.
  • Shader transitions are in @hyperframes/shader-transitions (packages/shader-transitions/) — read package source, not skill files.

GSAP patterns and effects are in the /gsap skill.

Hybrid cuts: HyperFrames + Canvas Video Studio

HyperFrames is the right surface for authoring deterministic motion graphics, title cards, end cards, and structured promo templates. It is NOT the right surface for stitching together pre-rendered MP4s from other generators (Seedance footage, agent-media talking-head).

For trailer-style or multi-beat social cuts that need both designed cards and realistic footage:

1. Author the title / end / interstitial cards here in HyperFrames (create_hyperframes_composition). Each card lands as its own video artifact + Library file.
2. Generate the realistic scene beats via Seedance (openrouter-video-create) or agent-media. Each render lands as its own Library file.
3. If the cut needs standalone narration, generate it via create_voiceover_audio_artifact.
4. Open Canvas Video Studio (create_video_project_artifact) referencing all of the rendered MP4s and audio files as sources. Edit the timeline to sequence + trim + add captions across the full cut.
5. Render preview first to verify the assembly, then full for the publish-ready output.

The assembly step belongs in Canvas Video Studio, not HyperFrames — HTML composition is the wrong abstraction for sequencing pre-rendered videos.

For purely designed video (no realism, no UGC), stay here in HyperFrames end-to-end.

For edit-only follow-ups on a finished HyperFrames render (reframe to 9:16, change captions, repurpose), hand off to Canvas Video Studio rather than re-rendering the composition with edited timing — see the canvas-video-studio skill.