---
name: hyperframes-integration
description: HyperFrames (HeyGen, Apache 2.0) — framework HTML→Video pra agentes. GSAP, Lottie, Three.js, CSS adapters. 50+ blocks prontos, FFmpeg backend, render determinístico.
owner: "@web-designer"
shared_with: ["@brand-director", "@web-designer"]
version: 1.2
tags: [video, hyperframes, html-to-video, heygen, gsap, lottie, three, agent-driven]
---

## Versões verificadas (2026-05-29)

| Componente | Versão | Status |
|---|---|---|
| **HyperFrames** | v0.6.58 (release HOJE 17:20 UTC) | ✅ atualíssimo · 22.239 stars no GitHub |
| **Puppeteer** (dependência core) | 25.1.0 | ✅ latest |
| **FFmpeg** (backend) | 8.1.1 | ✅ funcional (libx265 rebuilt 2026-05-29) |
| **Node mínimo** | >= 22 | ✓ Anthony tem v26.0.0 |

## Quando usar (por agent owner)

- **@web-designer** (owner) — pipeline agentic HTML→MP4, vídeo de marketing gerado de URL/PDF/CSV.
- **@brand-director** (shared) — mockup animado de brandbook (HTML brand pages → video walkthrough), motion graphics de identidade visual.
- **@web-designer** (shared) — vídeo gerado a partir de landing page HTML (showcase, demo, social-share video da própria landing).


# Skill: HyperFrames Integration

## O que é

**HyperFrames** é framework open-source (Apache 2.0) da HeyGen que renderiza HTML/CSS/JS em vídeo MP4 usando Puppeteer + FFmpeg. Foi desenhado pra agentes — CLI 100% não-interativa, render determinístico, skills system pra Claude/Cursor/Gemini.

**Frase canônica:** _"Write HTML. Render video. Built for agents."_

## Quando usar HyperFrames vs Remotion

| Cenário | HyperFrames | Remotion |
|---|---|---|
| Tem composição React | ❌ | ✅ |
| Time de design conhece CSS/HTML | ✅ | ⚠️ |
| Quer GSAP timeline | ✅ (nativo) | ⚠️ (adapter) |
| Quer 3D Three.js | ✅ (nativo) | ✅ |
| Quer Lottie | ✅ (nativo) | ✅ (@remotion/lottie) |
| Cloud render Lambda | ❌ | ✅ |
| Agente cria de zero | ✅ (HTML é universal) | ✅ |
| Captions animadas TikTok-style | ⚠️ | ✅ |
| Editor visual (Studio) | ❌ | ✅ |
| Determinismo | ✅ | ✅ |

**Regra @web-designer:**
- Vídeo pra agente gerar em pipeline automatizado a partir de URL/PDF/CSV → **HyperFrames**
- Vídeo de marca com motion graphics complexos + props tipadas + iterations no Studio → **Remotion**
- Posso combinar: gerar cenas em HyperFrames e composição final em Remotion via `remotion-to-hyperframes` skill.

## Instalação

```bash
# Requer Node.js >= 22
npx hyperframes init my-video
cd my-video
# Skills (LLM context)
npx skills add heygen-com/hyperframes
```

## CLI completo

| Comando | Uso |
|---|---|
| `npx hyperframes init <project>` | Scaffold novo projeto |
| `npx hyperframes preview` | Live-reload browser preview |
| `npx hyperframes render` | Export MP4 |
| `npx hyperframes lint` | Valida composições |
| `npx hyperframes inspect` | Debug metadata |
| `npx hyperframes doctor` | Diagnose ambiente |
| `npx hyperframes add <block>` | Instala block do catálogo |

## Estrutura mínima

```html
<!-- index.html -->
<div id="stage"
     data-composition-id="launch-video"
     data-start="0"
     data-width="1920"
     data-height="1080"
     data-duration="15"
     data-fps="30">

  <video id="bg-clip"
         data-start="0" data-duration="5" data-track-index="0"
         src="intro.mp4"></video>

  <img id="logo"
       data-start="2" data-duration="3" data-track-index="1"
       src="logo.png"/>

  <audio id="bg-music"
         data-start="0" data-duration="15" data-track-index="2"
         data-volume="0.5" src="music.mp3"></audio>

  <div id="headline"
       data-start="3" data-duration="4" data-track-index="3"
       class="hf-text-overlay">
    Aprove na Petrobras com IA
  </div>
</div>
```

**Atributos canônicos:**
- `data-composition-id` — id único
- `data-start` — segundo de início (ou frame se `data-fps` definido)
- `data-duration` — duração em segundos
- `data-track-index` — z-order (maior em cima)
- `data-width` / `data-height` / `data-fps` — config global

## Frame Adapters (6 runtimes)

### 1. GSAP (recomendado pra timelines complexas)

```js
import { gsap } from "gsap";
window.__hfGsap = gsap; // registra
const tl = gsap.timeline({ paused: true }); // SEMPRE paused — HyperFrames controla via seek
tl.from("#headline", { opacity: 0, y: 80, duration: 0.5, ease: "power3.out" })
  .from("#cta",       { scale: 0, duration: 0.4, ease: "back.out(1.7)" }, "+=0.2");
```

### 2. Anime.js

```js
window.__hfAnime = window.__hfAnime || [];
window.__hfAnime.push(anime({
  targets: '#logo',
  scale: [0, 1],
  duration: 600,
  easing: 'easeOutElastic',
  autoplay: false,
}));
```

### 3. CSS Animations (descobertas automaticamente)

```css
.fade-in { animation: fadeIn 0.5s forwards; animation-play-state: paused; }
@keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
```

### 4. Lottie

```html
<lottie-player src="confetti.json" data-hf-lottie autoplay="false"></lottie-player>
```

### 5. Three.js

```js
// dispatcha hf-seek e renderiza o frame correspondente
window.addEventListener("hf-seek", (e) => {
  scene.update(e.detail.time);
  renderer.render(scene, camera);
});
```

### 6. WAAPI (Web Animations API)

```js
// document.getAnimations() é discovered automaticamente
el.animate([{opacity:0},{opacity:1}], {duration:500, fill:"forwards"});
```

## Catálogo de blocks (50+)

```bash
# Listar
npx hyperframes add --list
# Instalar
npx hyperframes add vfx-iphone-device          # 3D iPhone showcase
npx hyperframes add flash-through-white         # transição shader
npx hyperframes add instagram-follow            # overlay social
npx hyperframes add data-bar-chart             # gráfico animado
npx hyperframes add cinematic-letterbox         # cinema bars
```

**Categorias:**
- **Transitions** — shader-based (flash, glitch, dissolve, swipe)
- **Overlays** — social (IG follow, TikTok like, YT subscribe), notifications
- **Data Viz** — bar, line, pie, counter, leaderboard
- **Cinematic** — letterbox, lens flare, film grain, color grade LUTs
- **VFX** — 3D devices (iPhone 15 Pro Max, MacBook Pro), particle systems
- **Social** — comment popups, like burst, share animation

## Skills system (agent integration)

```bash
npx skills add heygen-com/hyperframes
```

**Skills instaladas:**
- `hyperframes` — authoring, captions, TTS, audio-reactive
- `hyperframes-cli` — dev loop
- `hyperframes-media` — TTS Kokoro, transcription Whisper, background removal
- Adapter skills: `gsap`, `anime`, `css`, `lottie`, `three`, `waapi`
- `website-to-hyperframes` — URL → vídeo
- `remotion-to-hyperframes` — converte composições React → HTML

## Padrões de uso pra marketing

### Cold start (do zero)

```
Anthony pro agente: "Cria vídeo de 30s pra produto QBizu Petro:
- 5s hook visual com glitch text 'PETROBRAS APROVADO'
- 10s features: 3 cards staggered (3D devices iPhone)
- 10s social proof: counter 10.000 alunos
- 5s CTA com pulse button"

Agente: usa skill `hyperframes`, monta HTML com blocks `glitch-text`,
`vfx-iphone-device`, `data-counter`, `pulse-button`. Renderiza.
```

### Warm start (a partir de fonte)

```bash
# URL → vídeo de reels apresentando o site
npx skills run website-to-hyperframes --url https://qbizupetro.com --duration 30 --format reel
```

### Iterative refinement

```
"Aumenta o tempo do hook pra 7s, troca cor do CTA pra laranja Brand X,
adiciona shake na chamada final"
```

## Embeddable player

```html
<script type="module" src="https://unpkg.com/@hyperframes/player"></script>
<hyperframes-player src="my-video.html" autoplay muted loop></hyperframes-player>
```

Use em landing pages do @web-designer para reels que não precisam baixar o MP4 — renderiza no browser.

## Pipeline @web-designer (HyperFrames + MSE)

```
1. @brand-director entrega brandbook (cores, fontes, logos)
2. @copywriter entrega copy com timing (frase por segundo)
3. @web-designer:
   a) Decide: HyperFrames se pipeline agentic OR Remotion se motion complexo
   b) Se HyperFrames: scaffold com `init`, blocks do catálogo, GSAP timeline
   c) Renderiza com `render` → MP4 1080p
   d) Variações: 1080x1080 (feed), 1080x1920 (reels), 1920x1080 (YouTube)
4. @paid-traffic pega os MP4s e roda em ads
```

## Render options

```bash
# MP4 padrão (H.264)
npx hyperframes render

# Custom resolution
npx hyperframes render --width 1080 --height 1920

# Audio mix
npx hyperframes render --audio track.mp3 --audio-volume 0.6

# Quality presets
npx hyperframes render --quality high     # CRF 18
npx hyperframes render --quality medium   # CRF 23 (default)
npx hyperframes render --quality web      # CRF 28
```

## Docker (CI/CD friendly)

```bash
docker run --rm -v $(pwd):/work heygen/hyperframes:latest render
```

Útil quando @web-designer precisa renderizar em pipeline GHL/n8n/CI sem ter Node local.

## Regras (@web-designer)

1. **Sempre `data-fps` na composição** — sem isso, GSAP roda em tempo wallclock e não determinístico
2. **Sempre `paused: true` em timelines GSAP** — HyperFrames faz seek manual
3. **Sempre testar com `preview` antes de render final** — mesmo regra do Remotion
4. **Nunca `setTimeout`/`Date.now()`** — quebra determinismo
5. **Sempre rodar `lint` antes de PR** — pega `data-start` inválidos

## Combinação power: HyperFrames + Remotion

@web-designer pode usar HyperFrames como source de footage (cenas individuais geradas por agente) e Remotion como composer (timeline final com transitions, captions, audio mixing). Skill `remotion-to-hyperframes` facilita conversão bidirecional.

## Referências

- Repo: https://github.com/heygen-com/hyperframes
- Catálogo: https://hyperframes.heygen.com/catalog
- Skills: `npx skills add heygen-com/hyperframes`
- License: Apache 2.0 (zero per-render fee)
