Hyperframes Video Composition

HyperFrames video composition

Use this skill when the job is to assemble images, clips, narration, music, captions, UI captures, generated assets, or brand material into a finished HyperFrames video. Treat HyperFrames as a production composition runtime, not just a code target: the agent owns intake, the frame/design spec, media custody, timing, QA, provenance, and handoff.

This skill is provider-independent. It does not choose the image, video, TTS, or music model for you. It tells you how to turn approved assets and creative decisions into a deterministic HTML/CSS/JS/HyperFrames composition.

Source status

Documented facts below are grounded in these sources, verified 2026-07-11 unless noted:

• HyperFrames official docs and repo: Introduction, Quickstart, Prompting guide, GitHub repository, plus local HyperFrames package READMEs for CLI, core, engine, and producer.
• Local OpenMontage HyperFrames bridge: C:\Users\ishan\Documents\OpenMontage\skills\core\hyperframes.md, tools\video\hyperframes_compose.py, and lib\hyperframes_style_bridge.py.
• WCAG 2.2 Quick Reference: captions, audio description, contrast, audio control, flashing, and non-text contrast: W3C WCAG 2.2 Quickref.
• Browser media behavior: MDN Autoplay guide, MDN <video>, and MDN <audio>.
• Provenance terminology: C2PA Technical Specification and C2PA overview.

Volatile facts: HyperFrames CLI commands, package names, Node/FFmpeg requirements, registry block names, cloud render support, browser capture behavior, platform delivery specs, and social platform safe areas can change. Re-check the installed package docs, npx hyperframes --help, npx hyperframes doctor, and target-platform delivery docs at production time.

Production stance

Separate three kinds of information in your own notes and client updates:

• Documented fact: behavior or requirement found in official/local docs or a standard.
• Empirical observation: something verified in this project by preview, render, ffprobe, frame sampling, transcription, or manual review.
• Production heuristic: a practical rule that improves output but is not a formal requirement.

Escalate rather than guess when the issue is rights, licensing, privacy, likeness, client brand approval, platform policy, medical/legal/financial claims, political persuasion, regulated ads, or unverified provenance. Do not provide legal advice; identify the risk and ask for client, counsel, platform, or rights-holder approval.

1. Intake: lock the composition contract

Before authoring HTML, produce a short composition brief with these fields:

• Intent: what the video must make the viewer understand, feel, or do.
• Audience and context: where and how it will be watched.
• Deliverables: aspect ratio, resolution, duration, fps, audio/no-audio, caption requirement, transparent overlay requirement, and required file formats.
• Runtime: HyperFrames, with a note that it is appropriate because the piece benefits from HTML/CSS/JS composition, seekable browser animation, kinetic type, UI motion, generated media assembly, or registry/block-style composition.
• Inputs: approved assets, generated assets to create, brand materials, script, source footage, captions, audio stems, fonts, data, references, and rights constraints.
• Review gates: script/beat plan, design frame, rough preview, audio/caption pass, final render.
• Non-negotiables: brand rules, disclaimers, accessibility targets, platform rules, client approvals, and forbidden treatments.

If the request is still ambiguous, ask only for choices that materially change the result: target duration, aspect ratio/platform, narration vs. text-led, brand/style references, and whether source assets are approved for use.

2. Design the frame before the timeline

HyperFrames compositions are browser frames captured into video. Design for a camera, not a scrolling page.

Create a frame/design spec before coding:

• Canvas: width, height, fps, aspect ratio, safe regions, and bleed policy.
• Visual system: background, foreground, accent palette, typefaces, type scale, corner radii, stroke weights, shadows, texture/grain, and motion intensity.
• Layout grammar: grid, margins, title zones, lower-thirds, caption rail, logo zone, product/device zone, and chart/data zone.
• Scene density: maximum words on screen, maximum simultaneous claims, minimum hold time for reading, and hierarchy rules.
• Motion grammar: entrance, emphasis, transition, exit, camera/parallax, and reduced-motion alternative when relevant.
• Audio grammar: narration role, music role, sound-effect restraint, silence beats, stem names, and target loudness policy if one is specified by the client.
• Accessibility targets: captions for spoken audio, contrast targets, no unsafe flashing, no critical information conveyed by color alone, and transcript or alternate description when required.

For platform deliverables, reserve safe areas for UI overlays and captions. Treat platform safe-area dimensions as volatile; re-check the target platform's current creator/ad specs before final crop and delivery.

3. Scene architecture

Plan the piece as timed scenes and layers. A useful scene plan includes:

• scene_id: stable kebab-case identifier.
• start, duration, end: seconds, with frame-derived values checked against fps.
• purpose: hook, setup, proof, demo, transition, CTA, disclaimer, etc.
• visual: what appears and why.
• text: exact on-screen copy, not placeholders.
• media: asset IDs and how they are used.
• audio: narration segment, music cue, SFX, silence, or stem ducking.
• animation: entrance, emphasis, transition, exit, and key beats.
• accessibility: caption text, contrast risk, flashing risk, and description need.
• qa: what to check in preview/render for this scene.

Prefer a small number of strong scenes over many thin cuts. For social or launch work, build the first 1-2 seconds as a true hook; do not spend the opening on a logo unless the brief requires it.

4. HyperFrames authoring contract

Documented HyperFrames facts:

• HyperFrames defines video as HTML. Elements use timing attributes such as data-start and data-duration; layout/timeline ordering can use data-track-index.
• The current quickstart states that timed elements need class="clip" along with data-start, data-duration, and data-track-index; keep the class on timed visual elements unless the installed CLI/project docs say otherwise.
• HyperFrames supports preview in the browser with npx hyperframes preview and rendering to MP4 with npx hyperframes render.
• The local/official docs describe Node.js 22+ and FFmpeg as requirements; verify with npx hyperframes doctor.
• The core package includes parsers, generators, timing compilation, linting, runtime support, and frame adapters for seekable animation runtimes.
• The engine/producer render path uses headless Chrome plus FFmpeg to capture frames, encode video, and mix audio.

Authoring rules:

• Keep a single root composition with a clear data-composition-id, explicit canvas size, and deterministic initial state.
• Use absolute positioning or a strict grid inside the fixed video canvas; avoid page-flow surprises that depend on viewport defaults.
• Give every timed visual element a stable ID or class, a start, a duration, and a track index when layering matters.
• Stage media with relative paths inside the project workspace; never reference temp files, external URLs that may change, or another runtime's public folder.
• Register animation timelines synchronously after page load. Do not depend on unbounded timers, network races, or user interaction.
• Bound all loops. Infinite GSAP repeats, wall-clock-only animations, random values without stored seeds, and async timeline construction break deterministic capture.
• Pin external script versions or vendor local copies when the final render must be reproducible.

Example root shape:

<main id="stage" data-composition-id="launch-hero" data-start="0" data-width="1920" data-height="1080">
  <section class="scene scene-01 clip" data-start="0" data-duration="5" data-track-index="0">
    <video class="bg clip" data-start="0" data-duration="5" data-track-index="0" src="./assets/hero-loop.mp4" muted playsinline></video>
    <h1 id="headline" class="clip" data-start="0.4" data-duration="3.8" data-track-index="2">Ship the impossible demo</h1>
    <p id="subline" class="clip" data-start="1.2" data-duration="3" data-track-index="2">A launch reel assembled from approved product captures.</p>
  </section>

  <audio data-start="0" data-duration="5" data-track-index="10" data-volume="0.45" src="./assets/music-bed.wav"></audio>

  <script src="./vendor/gsap.min.js"></script>
  <script>
    const tl = gsap.timeline({ paused: true });
    tl.from("#headline", { opacity: 0, y: 48, duration: 0.55, ease: "power3.out" }, 0.4);
    tl.from("#subline", { opacity: 0, y: 24, duration: 0.45, ease: "power2.out" }, 1.2);
    window.__timelines = window.__timelines || {};
    window.__timelines["launch-hero"] = tl;
  </script>
</main>

Use this as an example of structure, not a mandatory template.

5. Media import and custody

Every asset that enters the composition needs an asset record before it is referenced by HTML.

Minimum asset manifest fields:

• asset_id: stable ID used by scene plan and HTML comments or metadata.
• type: image, video, audio, music, narration, SFX, font, data, logo, caption, LUT, transcript, etc.
• source: user-provided, generated, licensed stock, public-domain, first-party capture, synthetic, or derived.
• path: workspace-relative and absolute local path.
• rights_status: approved, pending approval, restricted, unknown, or generated-under-policy.
• generation_metadata: provider/model/version/prompt/seed/settings when generated.
• transformations: trims, crops, resizes, color conversions, denoise, upscales, transcodes, normalization, background removal.
• technical: width, height, fps, duration, codec, sample rate, channel count, alpha, color space if known.
• scene_links: scene IDs where used.
• provenance: parent assets, checksums, C2PA/content-credential status if available, and ledger row.

Empirical production checks:

• Run ffprobe or equivalent on every video/audio asset before staging.
• For full-frame background video, check active source resolution before blaming CSS. Upscaling a letterboxed low-res source into a 1920x1080 container can still leave visible black padding inside the picture.
• Re-encode heavy stock/source clips to render-friendly H.264, constant fps, short keyframe interval, and faststart when browser capture stalls or freezes. Keep the original and transformed paths in the manifest.
• Avoid remote media URLs in final HTML. Download or freeze files locally so render and audit do not depend on an external server.
• Use relative paths from the HyperFrames project root.

6. Timeline, duration, aspect, and fps

Treat time as an audited contract:

• Decide the master fps before animation. Use 24/30/60 only when the toolchain and delivery need support them; verify current producer/CLI support at production time.
• Convert all scene starts and durations to frame boundaries: frame = round(seconds * fps). Watch for cumulative drift when using decimals.
• Keep a timeline table with scene start, end, audio segment, caption segment, and transition overlap.
• Do not let CSS transition durations silently exceed the scene duration.
• If using transitions that overlap scenes, represent overlap explicitly in the plan and HTML rather than hiding it in animation code.
• For multiple aspect ratios, create separate layout specs. Do not rely on a blind center-crop from 16:9 to 9:16 unless the brief explicitly allows it.

Safe production heuristic: leave at least 5-10% of frame width/height as action-safe margin for important text and logos unless target-platform specs require a larger safe area. For vertical social, reserve extra space for captions and platform UI overlays after checking current platform specs.

7. Animation and transitions

HyperFrames rewards seekable, frame-deterministic animation.

Use animation to clarify hierarchy:

• Entrance: establish what matters now.
• Emphasis: point at the active idea, number, product feature, or evidence.
• Transition: carry the viewer from one beat to the next.
• Exit: clear the canvas; do not leave visual debris.

Good motion patterns:

• Kinetic type: word/line reveals, masked wipes, scale/perspective hits, and timed emphasis.
• Product/UI motion: cursor paths, focus rings, device pans, progressive disclosure, and callout lines.
• Data motion: axis first, mark reveal second, annotation third, takeaway last.
• Atmospheric motion: grain, light sweep, parallax, or particles at low intensity, bounded and not distracting.

Avoid:

• Random motion without a stored seed.
• Flash cuts, strobes, or high-contrast inversion without a flashing review.
• Motion that causes text to be unreadable while it is supposed to be read.
• Infinite loops or wall-clock-only timelines.
• Decorative animation that competes with narration or captions.

For transitions, choose the semantic type:

• Hard cut: urgency, comedy, list pacing.
• Match cut: same object, shape, UI element, or phrase bridges scenes.
• Wipe/mask: product reveal, data reveal, page-to-page movement.
• Crossfade: memory, softness, recap.
• White/black flash: only when flash-safe and narratively justified.

8. Typography, layout, and captions

Text is often the main visual asset in HyperFrames.

Typography rules:

• Prefer live text over rasterized text except for logos or required brand artwork.
• Set max line length and intentional line breaks; do not let browser wrapping decide the hero line.
• Use real hierarchy: title, claim, evidence, caption, label, disclaimer.
• Keep captions visually distinct from marketing copy.
• Avoid putting critical text at the extreme edges.
• Test every text state on actual background frames, not just a clean design frame.

Accessibility and legibility facts from WCAG 2.2:

• Prerecorded synchronized media with audio needs captions unless it is clearly a media alternative for text.
• WCAG AA minimum contrast for normal text is 4.5:1; large text has a 3:1 threshold.
• Non-text visual information and UI component boundaries require sufficient contrast; use at least 3:1 as the WCAG AA reference point where applicable.
• Content should not flash more than three times in any one-second period unless it is below the general/red flash thresholds. The safest production rule is no flashing beyond three flashes per second.

Caption production:

• Decide open captions, closed caption sidecar, or both based on delivery. Burned/open captions are safer for social feeds; sidecars are better for accessible players and localization.
• Captions must include dialogue and important non-speech audio when that audio conveys meaning.
• Keep captions synchronized to speech, readable, and clear of platform overlays.
• If using word-level captions, verify timing after render by watching, not just by trusting transcript timestamps.
• Keep a canonical transcript/subtitle file in the asset ledger even when captions are burned into video.

9. Audio, stems, and synchronization

Build audio as stems, not as one mystery file:

• Narration/dialogue stem.
• Music stem.
• SFX stem.
• Ambience stem if used.
• Final mix.

For each stem, record source, rights, duration, loudness/normalization if measured, sample rate, and scene links. If narration is generated, store script text, voice/provider/model/version/settings, and approval status.

Browser/media facts:

• HTML <audio> embeds sound content; HTML <video> embeds a media player for video playback.
• Browser autoplay rules restrict audible autoplay. Muted video or video with no audio track is treated differently from audible autoplay. HyperFrames render tooling drives media for capture, but the composition should still use sane browser media attributes such as muted and playsinline for background videos.

Production heuristics:

• Mix speech first; music supports, never masks, narration unless the piece is intentionally music-led.
• Duck music under narration and restore during visual-only beats.
• Use SFX sparingly for semantic events: click, reveal, transition, impact, notification.
• Verify final audio length matches video duration and no stem starts before/after its intended scene.
• After render, transcribe or spot-check narration against the approved script and caption file.