HyperFrames 中文视频实战

Was macht HyperFrames 中文视频实战?

In HTML ein Video schreiben, die Engine rendert Frame für Frame in MP4. Dieses Skill ist die praktische Essenz eines kompletten 6,5-minütigen chinesischen Wissenschaftsvideos (mit echten Daten, Sprachausgabe, Screenshots) von 2026-10. Der Schwerpunkt liegt auf den Fallstricken, die nicht in der offiziellen Dokumentation stehen und die man erst durch Erfahrung kennt.

Gesamter Workflow (Fünf Schritte)

1. Initialisierung: npx hyperframes init <dir> → Node22+, FFmpeg vorausgesetzt; lokal muss HYPERFRAMES_BROWSER_PATH=/usr/bin/google-chrome gesetzt sein (das automatische Herunterladen von chrome-headless-shell schlägt aufgrund von Netzwerkproblemen fehl, siehe pitfalls#1)
2. Struktur & Inhalt: Die Haupt-index.html verknüpft Sub-Compositions; das Inhaltsmaterial (echte Daten/Screenshots) zuerst in scripts/sources.md archivieren und dann ins Bild bringen – Informationsdichte ist das A und O eines Erklärvideos
3. Animation: Pro Szene eine pausierte GSAP-Timeline; System für satzweise Untertitel + rhythmische Hervorhebung (Rezept in references/scene-recipe.md)
4. Validierung: npx hyperframes check muss komplett grün sein, das ist die Voraussetzung für das Rendern; Lösungen in references/pitfalls.md (90% der Fehler haben dort eine fertige Lösung)
5. Sprachausgabe (optional): Mit edge-tts generieren → an die gemessene Szenenlänge angepasste Sprechgeschwindigkeit → Das Audio MUSS im Root der Haupt-index.html eingehängt werden (in Sub-Comps unwirksam, siehe pitfalls#6) → neu rendern
6. Qualitätskontrolle & Auslieferung: Nach dem Rendern npx hyperframes snapshot ausführen, um Schlüsselbilder einzeln zu prüfen (visuelle Selbstkontrolle: Rendern → Bilder prüfen → verbessern → neu rendern); Das Titelbild direkt mit snapshot erzeugen, kein separates Tool öffnen

Wichtige Befehle: Vorschau mit --background (Hot Reload); Rendern von 365s@1080p dauert ca. 9-10 Minuten (5 Worker im Screenshot-Modus, lokal ohne GPU).

Wann welches Referenzdokument lesen

• Bei Fehlern/Render-Anomalien → Zuerst references/pitfalls.md prüfen (nach Symptomen suchen, enthält die Schlussfolgerung zum ungelösten Engine-Bug der Kamera-Transformationskette)
• Neue Szenen schreiben → references/scene-recipe.md (enthält JS-Vorlage für satzweise Untertitel, Animationsmuster für Markierungen)
• Sprachausgabe hinzufügen → references/voice-pipeline.md
• Referenzvideos analysieren (Douyin etc.) → Letzter Abschnitt in references/pitfalls.md "Quantitativer Vergleich von Referenzvideos"
• Fertige Animationen, Skills gleicher Kategorie, Sprachausgaben-Upgrades, DaVinci-Schnittstellen etc. finden → references/ecosystem.md (Liste des Open-Source-Ökosystems, enthält auch das offizielle capture --video für 1:1-Nachbauten)

Mitgelieferte Skripte

• scripts/inject_subtitles.py – Masseninjektion von satzweisen Untertiteln (HTML/CSS/JS auf einmal, verhindert manuelle Fehler)
• scripts/gen_voice.py – Massengenerierung mit edge-tts + automatische Anpassung der Sprechgeschwindigkeit an die Szenenlänge (Ausführung mit uv run)
• scripts/frame_audit.py – Qualitätsprüfung von gerenderten Frames (automatische Erkennung von Bildverschiebungen/leeren Frames, unverzichtbar zur Behebung von Kameraproblemen)

Drei eherne Regeln

1. Vor jeder Änderung an Szenendateien ein grep durchführen: Studio fügt data-hf-id ein, String-Ersetzungen schlagen dann still fehl (pitfalls#2)
2. Große Canvas-Kamera-Konfigurationen vermeiden: Die Render-Pipeline der Engine verursacht Versatz bei kontinuierlichen Transformationsketten, dies wurde mehrfach als nicht behebbar bestätigt (pitfalls#8); Animationen nur auf Elementebene durchführen
3. Zuerst die narrative Zeitachse festlegen: Die Zeit der Tonuntertitel + die Länge der Sprachausgabe bestimmen den gesamten Animationsrhythmus; zuerst die Zeitachse festlegen, dann die Animationen erstellen – das spart am meisten Nacharbeit.