---
name: "html-video-production"
description: "Editierbare Scene-basierte HTML-Videos mit HyperFrames/GSAP, Captions, deterministische MP4-Renders."
---

# html-video-production

Produce editable, scene-based HTML video projects (built on HyperFrames, an open-source HTML-to-video framework by HeyGen) — video as HTML with data-attribute timing, motion driven by GSAP, captions synced to narration.

## Wann verwenden

- User will Video das **reproduzierbar, inspizierbar, editierbar** ist
- Aus strukturierten Quellen: PDF, GitHub-Repo, CSV, Slide-Deck, Design-Doc, Website-URL
- Erwähnt: HyperFrames, GSAP timelines, kinetic typography, data-driven motion graphics, lower thirds, title cards, animated charts, lyric/karaoke captions, website-to-video
- Als **On-Screen-Text + Brand-Frame Layer über AI-generierten B-Roll**

## Wann NICHT verwenden

- ❌ Pure photoreal AI video synthesis → Skill `video-generator` (Manus native)
- ❌ AI avatar talking-head → Manus native
- ❌ Speech/Music/Images Generation selbst → `tts`, `music_generate`, `image_generate` separat

## Architektur

```
[Quellen] → [Scene-Plan] → [HTML/CSS/JS] → [Render (Playwright+ffmpeg)] → MP4
              ↓                ↑
         GSAP Timelines    TTS (Audio)
         data-time Attrs   Captions sync
```

## Workflow

### 1. Source-Ingest
- **PDF** → `pdftotext` / `pdfplumber`
- **GitHub** → `gh repo clone` oder `web_fetch` README
- **CSV** → pandas DataFrame
- **Slide-Deck** → `unoconv` zu Bildern + Text
- **Website** → `playwright` + monolith für Snapshot

### 2. Scene-Plan (JSON)

```json
{
  "title": "Project X Launch",
  "duration": 60,
  "scenes": [
    {
      "id": "intro",
      "start": 0,
      "duration": 5,
      "type": "title",
      "props": {"headline": "...", "subline": "..."}
    },
    {
      "id": "chart-1",
      "start": 5,
      "duration": 10,
      "type": "animated-chart",
      "data": [...]
    }
  ]
}
```

### 3. HTML-Template (HyperFrames-Style)

```html
<div class="scene" data-start="0" data-duration="5">
  <h1 class="headline" data-anim="fadeInUp" data-delay="0.3">
    Welcome
  </h1>
  <p class="subline" data-anim="fadeIn" data-delay="1">
    A new chapter
  </p>
</div>
```

GSAP-Timeline aus `data-*` Attributen aufbauen:

```js
gsap.utils.toArray('.scene').forEach(scene => {
  const start = +scene.dataset.start;
  const dur = +scene.dataset.duration;
  // build timeline from children data-anim/data-delay
});
```

### 4. Audio + Captions

- **TTS:** `tts` tool → narration.mp3 mit Wort-Timings
- **Captions:** SRT/VTT generieren mit Word-Level-Timing
- **Sync:** Captions als HTML-Layer mit `data-time` triggern

### 5. Render zu MP4

```bash
# Playwright records browser at fixed FPS
node render.js --html scene.html --audio narration.mp3 \
               --duration 60 --fps 30 --out video.mp4
```

Intern:
1. Playwright öffnet HTML
2. Steuert Timeline deterministisch (gsap.timeline pause + tick)
3. Screenshot pro Frame
4. ffmpeg konkateniert Frames + audio.mp3 → MP4

### 6. Registry Blocks (Reusable)

Wiederverwendbare Bausteine in `blocks/`:
- `title-card/`
- `lower-third/`
- `bar-chart-anim/`
- `kinetic-text/`
- `image-reveal/`
- `transition-wipe/`

## Best Practices

- **Deterministisch:** Keine `Math.random()` ohne Seed, keine echte Animation-Loops — alles über GSAP-Timeline-Position
- **Editierbar:** Klare HTML-Struktur, Scenes als eigene `<section>`s
- **Brand-Consistent:** CSS-Variables für Color/Font/Spacing
- **Responsive Aspect:** 16:9 / 9:16 / 1:1 als CSS-Variants
- **Multi-Pass:** erst ohne Audio rendern, dann mit Audio sync, dann finalisieren

## Fallstricke

- ⚠️ GSAP-Timeline + Browser-Tick müssen sync sein (Playwright `evaluate` für deterministic tick)
- ⚠️ Font-Loading vor Render abwarten (`document.fonts.ready`)
- ⚠️ Captions-Sync: Wort-Timing vom TTS muss exakt sein
- ⚠️ FPS: 30 für Standard, 60 nur wenn nötig (Render-Zeit verdoppelt sich)
- ⚠️ Video-Codec: H.264 für max Compat, H.265 für kleinere Files

## Tools-Stack

| Tool | Zweck |
|---|---|
| GSAP | Animation-Engine |
| Playwright | Headless-Browser für Render |
| ffmpeg | Frame-Konkatenation + Audio-Mux |
| `tts` | Narration |
| `music_generate` | Background-Music |
| `image_generate` | B-Roll/Assets |

## Lieferung

- `MEDIA:<pfad>.mp4` final
- Source-HTML im Workspace ablegen (editierbar!)
- Scene-JSON daneben (re-render möglich)
