hyperframes-generator

Restyle programmatic video templates in bulk with AI.

If you make short videos for clients (intro cards, lower-thirds, stat reveals, social posts), you've probably hit this pain: you build one version, then have to hand-restyle it for 20 different brands. Same animation, different colors, different fonts, different motion feel. Tedious by hand. Easy to break the file accidentally.

This tool automates the visual restyle. You write the video template once, give it a small JSON file describing a brand's style, and Claude produces a fully restyled version that still renders correctly. Run it once for one variant, or batch it over a hundred.

For developers using HyperFrames (HeyGen's HTML video framework): takes a structural composition + a style DNA, sends them to the Claude API, and emits a reskinned composition with the timeline registration, data attributes, and token placeholders preserved and validated.

Requires HyperFrames (proprietary, by HeyGen) installed separately to render the output HTML to video. This package only generates the HTML.

Quickstart

pip install hyperframes-generator
export ANTHROPIC_API_KEY=sk-ant-...

hfgen doctor                      # verify setup

hfgen generate \
  --template examples/templates/stat-reveal.html \
  --dna      examples/dna/neon-grid.json \
  --output   ./out/stat-reveal-neon.html

You get back an HTML file: same structure as the input template (same elements, same IDs, same GSAP timeline, same {{tokens}}), restyled with neon-grid colors, fonts, easing, and decoratives.

What gets preserved and what changes

Preserved	Changed
HTML element structure	Colors (primary, accent, bg, text)
Element IDs and class names used in GSAP selectors	Fonts (font-family, sizes)
data-composition-id, data-width, data-height, data-fps, data-duration, data-start	Border radius, shadows
window.__timelines registration	Backgrounds (gradients, textures)
gsap.timeline({ paused: true })	GSAP easing functions and durations
All {{token}} placeholders	Texture overlays (grain, scanlines, halftone)

After generation, the output is automatically validated. If any of the preserved items are missing, no file is written and the run is marked failed.

Example: one template, three styles

hfgen generate --template examples/templates/stat-reveal.html --dna examples/dna/neon-grid.json       --output ./out/neon.html
hfgen generate --template examples/templates/stat-reveal.html --dna examples/dna/editorial-cream.json --output ./out/editorial.html
hfgen generate --template examples/templates/stat-reveal.html --dna examples/dna/bauhaus-blocks.json  --output ./out/bauhaus.html

You get three HTML files. Same structure, same GSAP timeline, three completely different visual treatments. Open each in a browser to preview, or pipe through hyperframes render to get videos.

Batch mode

For more than a handful of jobs, use a manifest:

// manifest.json
[
  { "template": "examples/templates/stat-reveal.html", "dna": "examples/dna/neon-grid.json" },
  { "template": "examples/templates/stat-reveal.html", "dna": "examples/dna/editorial-cream.json" },
  { "template": "examples/templates/lower-third.html", "dna": "examples/dna/neon-grid.json" }
]

hfgen batch --manifest manifest.json --output-dir ./out/

Output is grouped by style_name:

out/
├── neon-grid/
│   ├── stat-reveal-neon-grid-synthwave-night.html
│   └── lower-third-neon-grid-synthwave-night.html
└── editorial-cream/
    └── stat-reveal-editorial-cream-magazine-spread.html

The system prompt is sent with prompt caching (cache_control: ephemeral), so a batch of N jobs pays for the system prompt once, not N times. Cost summary printed at the end.

Style DNA format

A DNA is a JSON file describing visual properties. Minimal shape:

{
  "style_name": "your-style-slug",
  "visual_style": {
    "primary_color":    "#FF00AA",
    "accent_color":     "#00FFEE",
    "background_color": "#0A0A12",
    "text_color":       "#FFFFFF",
    "font_suggestion":  "Space Grotesk",
    "headline_size":    "84px",
    "body_size":        "22px",
    "border_radius":    "4px",
    "shadow_value":     "0 0 32px rgba(255, 0, 170, 0.6)",
    "bg_value":         "radial-gradient(at top, #1a0033, #0a0a12 70%)",
    "texture":          "scanlines"
  },
  "easing_suggestion": "snappy",
  "decoratives":       ["scanlines", "neon-glow"]
}

See docs/dna-spec.md for the full field list, the texture enum, and the easing_suggestion mapping to GSAP easing values.

Structural template contract

Your templates must satisfy the HyperFrames API contract:

1. A root element with data-composition-id, data-width, data-height, data-fps, data-duration.
2. GSAP loaded from a CDN.
3. A paused timeline registered on window.__timelines.
4. Token placeholders ({{name}}) for variable content.

See docs/template-contract.md for a full example and the validation rules.

You can validate any template against the contract:

hfgen validate-template path/to/your-template.html

CLI reference

hfgen doctor                    Check prerequisites
hfgen generate                  Reskin one template with one DNA
hfgen batch                     Reskin from a manifest (one DNA per row)
hfgen validate-dna <path>       Validate a DNA JSON file
hfgen validate-template <path>  Validate a template against the contract

Run hfgen <command> --help for flags.

Installation

From PyPI (recommended)

pip install hyperframes-generator

From source

git clone https://github.com/PythonLuvr/hyperframes-generator
cd hyperframes-generator
pip install -e ".[dev]"

Optional: rendering to video

This package only generates HTML. To render the HTML to MP4, install HyperFrames separately:

npm install -g hyperframes
hyperframes render out/stat-reveal-neon.html

HyperFrames is a proprietary framework by HeyGen. See github.com/heygen-com/hyperframes for its docs and license.

Why this exists

HyperFrames templates are written in HTML+CSS+GSAP. They render deterministically. But hand-styling 20 brand variants of the same composition is tedious. This tool automates the visual restyle while preserving the parts that make HyperFrames work (timeline registration, data attributes, tokens).

The novel piece is the system prompt. It encodes:

• The HyperFrames API contract Claude must preserve
• The texture-to-CSS recipe table (grain, scanlines, halftone, etc.)
• The easing-mood-to-GSAP mapping (serene, smooth, snappy, bouncy, dramatic, chaotic)
• The "what to change vs what to leave" boundary

Without that prompt, Claude rewrites too much and breaks the rendered output. With it, the output is reliably deterministic and contract-compliant. See src/hyperframes_generator/prompts.py.

Tests

pytest                          # 39 tests across validation, DNA, generator (mocked), examples

The generator suite mocks the Anthropic client, so tests don't call the real API or cost anything.

Not affiliated with HeyGen

HyperFrames is a HeyGen product. This generator targets the public API contract but is not endorsed by, affiliated with, or supported by HeyGen.

License

MIT. See LICENSE.