Communitygithub.com

zengbaocheng/hermes-tech-hub

Erstelle HTML-basierte Videokompositionen, animierte Titelcards, Social-Overlays, Videos mit Untertiteln, audio-reaktive Visualisierungen und Shader-Übergänge mit HyperFrames. HTML ist die Quelle der Wahrheit für Video.

Was ist hermes-tech-hub?

Dieses Skill ermöglicht es, aus HTML-, CSS- und JavaScript-Elementen deterministisch MP4- oder WebM-Videos zu rendern. Es nutzt HyperFrames, einen Frameworks, das jede Szene als HTML-Datei mit `data-*`-Attributen für Timing und einer GSAP-Timeline für Animationen definiert. Der Engine erfasst die Seite Bild für Bild und codiert sie mittels FFmpeg in ein Video. Der Skill deckt eine breite Palette von Anwendungsfällen ab: animierte Titelcards, gesprochene Erzählungen mit Untertiteln, audio-reaktive Visuals (Bass-Sync, Spektrum), Produkt-Touren, Social-Overlays und Shader-Übergänge. Er unterstützt auch die Umwandlung ganzer Websites in Promo-Videos über einen 7-Schritte-Workflow. Ein harter Gate vor dem Schreiben von HTML stellt sicher, dass eine visuelle Identität (Farben, Schriftarten, Bewegungscharakter) definiert ist – entweder aus einer vorhandenen DESIGN.md oder nach Rückfrage beim Benutzer. Das Skill bietet umfangreiche Prüfungen: Lint, Validierung (WCAG-Kontrast), visuelles Layout-Inspizieren und eine Animations-Map zur Choreografie-Prüfung. Wichtige Fallstricke sind unter anderem die Vermeidung von `repeat: -1`, asynchronen Timeline-Aufbauten und externen `play()`-Aufrufen. Dieses Skill ist eine ideale Ergänzung zu `manim-video`: Manim für mathematische/geometrische Erklärungen, HyperFrames für bewegte Grafiken, Untertitel und mediengetriebene Inhalte.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/zengbaocheng/hermes-tech-hub/tree/HEAD/creative/hyperframes

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

HyperFrames

HTML ist die Quelle der Wahrheit für Video. Eine Komposition ist eine HTML-Datei mit data-*-Attributen für Timing, einer GSAP-Timeline für Animationen und CSS für das Aussehen. Die HyperFrames-Engine erfasst die Seite Bild für Bild und codiert sie mit FFmpeg in MP4/WebM.

Ergänzung zu manim-videos: Verwende manim-video für mathematische/geometrische Erklärungen (Gleichungen, 3B1B-Stil). Verwende hyperframes für Bewegtgrafiken, Sprechervideos mit Untertiteln, Produkt-Touren, Social-Overlays, Shader-Übergänge und alles, was von echten Video-/Audiomedien gesteuert wird.

Wann verwenden

  • Benutzer wünscht ein gerendertes Video aus Text, einem Skript oder einer Website
  • Animierte Titelcards, Lower Thirds oder typografische Intros
  • Video mit gesprochener Erzählung und Untertiteln (TTS + Untertitel synchron zur Wellenform)
  • Audio-reaktive Visuals (Beat-Sync, Spektrumbalken, pulsierendes Leuchten)
  • Szenenübergänge (Überblendung, Wisch, Shader-Warp, Durch-Blitz-zu-Weiß)
  • Social-Overlays (Instagram/TikTok/YouTube-Stil)
  • Website-zu-Video-Pipeline (URL erfassen, Promo produzieren)
  • Jede HTML/CSS/JS-Animation, die deterministisch zu einer Videodatei gerendert werden muss

Verwende dieses Skill nicht für:

  • Reine Mathematik-/Gleichungsanimationen (→ manim-video)
  • Bildgenerierung oder Memes (→ meme-generation, Bildmodelle)
  • Live-Videokonferenzen oder Streaming

Kurzreferenz

npx hyperframes init my-video               # Projekt erstellen
cd my-video
npx hyperframes lint                        # Vor Vorschau/Render validieren
npx hyperframes preview                     # Live-Reload-Browservorschau (Port 3002)
npx hyperframes render --output final.mp4   # In MP4 rendern
npx hyperframes doctor                      # Umgebungsprobleme diagnostizieren

Render-Flags: --quality draft|standard|high · --fps 24|30|60 · --format mp4|webm · --docker (reproduzierbar) · --strict.

Vollständige CLI-Referenz: references/cli.md.

Einrichtung (einmalig)

bash "$(dirname "$(find ~/.hermes/skills -path '*/hyperframes/SKILL.md' 2>/dev/null | head -1)")/scripts/setup.sh"

Das Skript:

  1. Überprüft, ob Node.js >= 22 und FFmpeg installiert sind (gibt ggf. Korrekturanweisungen aus).
  2. Installiert die hyperframes-CLI global (npm install -g hyperframes@>=0.4.2).
  3. Lädt chrome-headless-shell über Puppeteer vor – erforderlich für beste Renderqualität über den Chrome headlessExperimental.beginFrame-Capture-Pfad.
  4. Führt npx hyperframes doctor aus und meldet das Ergebnis.

Siehe references/troubleshooting.md, falls die Einrichtung fehlschlägt.

Vorgehensweise

1. Planung vor dem Schreiben von HTML

Bevor du Code anfasst, lege auf hoher Ebene Folgendes fest:

  • Was — Handlungsbogen, Schlüsselmomente, emotionale Höhepunkte
  • Struktur — Kompositionen, Spuren (Video/Audio/Overlays), Dauern
  • Visuelle Identität — Farben, Schriftarten, Bewegungscharakter (explosiv / kinematisch / fließend / technisch)
  • Hero-Frame — pro Szene der Moment, in dem die meisten Elemente gleichzeitig sichtbar sind. Dies ist das statische Layout, das du zuerst erstellst.

Visuelle-Identität-Gate (HARD-GATE). Bevor du IRGENDEINE Kompositions-HTML schreibst, MUSS eine visuelle Identität definiert sein. Schreibe KEINE Kompositionen mit Standard- oder generischen Farben (#333, #3b82f6, Roboto sind Anzeichen, dass dieser Schritt übersprungen wurde). Prüfe in dieser Reihenfolge:

  1. DESIGN.md im Projektstamm? → Verwende deren genaue Farben, Schriftarten, Bewegungsregeln und "Was NICHT tun"-Einschränkungen.

  2. Benutzer hat einen Stil genannt (z. B. "Swiss Pulse", "dark and techy", "luxury brand") → Generiere eine minimale DESIGN.md mit ## Style Prompt, ## Colors (3-5 Hex mit Rollen), ## Typography (1-2 Familien), ## What NOT to Do (3-5 Anti-Patterns).

  3. Nichts davon? → Stelle vor dem Schreiben von HTML 3 Fragen:

    • Stimmung? (explosiv / kinematisch / fließend / technisch / chaotisch / warm)
    • Heller oder dunkler Hintergrund?
    • Gibt es Markenfarben, Schriftarten oder visuelle Referenzen?

    Generiere dann aus den Antworten eine DESIGN.md. Jede Komposition muss ihre Palette und Typografie auf DESIGN.md oder explizite Benutzeranweisung zurückführen.

2. Gerüst erstellen

npx hyperframes init my-video --non-interactive

Vorlagen: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph. Verwende --example <name>, um eine auszuwählen, oder --video clip.mp4 bzw. --audio track.mp3, um Medien einzubringen.

3. Layout vor Animation

Schreibe zuerst das statische HTML+CSS für den Hero-Frame – noch kein GSAP. Der .scene-content-Container muss die Szene füllen (width:100%; height:100%; padding:Npx) mit display:flex + gap. Verwende Padding, um Inhalt nach innen zu drücken – niemals position: absolute; top: Npx auf einem Inhaltscontainer (Inhalt läuft über, wenn er höher als der verbleibende Platz ist).

Erst wenn der Hero-Frame richtig aussieht, füge gsap.from()-Eingänge (Animate zu der CSS-Position) und gsap.to()-Ausgänge (Animiere von ihr) hinzu.

Siehe references/composition.md für das vollständige Datenattribut-Schema und die Kompositionsregeln.

4. Mit GSAP animieren

Jede Komposition muss:

  • Ihre Timeline registrieren: window.__timelines["<composition-id>"] = tl
  • Pausiert starten: gsap.timeline({ paused: true }) – der Player steuert die Wiedergabe
  • Endliche repeat-Werte verwenden (kein repeat: -1 – zerstört die Capture-Engine). Berechne: repeat: Math.ceil(dauer / zyklusdauer) - 1.
  • Deterministisch sein – kein Math.random(), Date.now() oder Wanduhrlogik. Verwende einen gesetzten PRNG, falls Pseudozufall benötigt wird.
  • Synchron aufgebaut werden – kein async/await, setTimeout oder Promises um den Timeline-Aufbau herum.

Siehe references/gsap.md für die GSAP-Kern-API (Tweens, Easing, Stagger, Timelines).

5. Übergänge zwischen Szenen

Mehrszenen-Kompositionen erfordern Übergänge. Regeln:

  1. Verwende IMMER einen Übergang zwischen Szenen – keine Jump Cuts.
  2. Verwende IMMER Eingangsanimationen für jedes Szenenelement (gsap.from(...)).
  3. Verwende NIEMALS Ausgangsanimationen außer in der letzten Szene – der Übergang IST der Ausgang.
  4. Die letzte Szene kann ausblenden.

Verwende npx hyperframes add <übergangsname>, um Shader-Übergänge zu installieren (flash-through-white, liquid-wipe usw.). Vollständige Liste: npx hyperframes add --list.

6. Audio, Untertitel, TTS, audio-reaktiv, Hervorhebung

  • Audio: immer ein separates <audio>-Element (Video ist muted playsinline).
  • TTS: npx hyperframes tts "Skripttext" --voice af_nova --output narration.wav. Liste der Stimmen mit --list. Der erste Buchstabe der Sprach-ID kodiert die Sprache (a/b=Englisch, e=Spanisch, f=Französisch, j=Japanisch, z=Mandarin usw.) – die CLI leitet das Phonemizer-Gebietsschema automatisch ab; verwende --lang nur zum Überschreiben. Nicht-englische Phonemisierung erfordert systemweit installiertes espeak-ng.
  • Untertitel: npx hyperframes transcribe narration.wav → Transkript auf Wortebene. Wähle den Stil basierend auf dem Ton des Transkripts (Hype / Corporate / Tutorial / Storytelling / Social – siehe Tabelle in references/features.md). Sprachregel: Verwende niemals .en-Whisper-Modelle, es sei denn, das Audio ist nachweislich Englisch – .en übersetzt nicht-englisches Audio, anstatt es zu transkribieren. Jede Untertitelgruppe MUSS einen harten tl.set(el, { opacity: 0, visibility: "hidden" }, group.end)-Kill nach ihrem Ausgangs-Tween haben – sonst bleiben Gruppen sichtbar in späteren hängen.
  • Audio-reaktive Visuals: Extrahiere vorab Audio-Bänder (Bass / Mitten / Höhen) und mustere pro Frame innerhalb der Timeline mit einer for-Schleife von tl.call(draw, [], f / fps) – ein einzelner langer Tween reagiert NICHT auf Audio. Bilde Bass → scale (Puls), Höhen → textShadow/boxShadow (Glühen), Gesamtamplitude → opacity/y/backgroundColor ab. Vermeide Equalizer-Balken-Klischees – lass den Inhalt die Visualisierung leiten, das Audio sein Verhalten steuern.
  • Marker-Stil-Hervorhebung: Hervorhebungs-, Kreis-, Burst-, Kritzel-, Skizzen-Effekte für Textbetonung sind deterministisches CSS+GSAP – siehe references/features.md#marker-highlighting. Vollständig suchbar, keine animierten SVG-Filter.
  • Szenenübergänge: Jede Mehrszenen-Komposition MUSS Übergänge verwenden (keine Jump Cuts). Wähle aus CSS-Primitiven (Push-Slide, Blur-Überblendung, Zoom-Durch, gestaffelte Blöcke) oder Shader-Übergängen (flash-through-white, liquid-wipe, cross-warp-morph, chromatic-split usw.) über npx hyperframes add. Stimmungs- und Energie-Tabellen finden sich in references/features.md#transitions. Mische keine CSS- und Shader-Übergänge in derselben Komposition.

7. Linten, validieren, inspizieren, Vorschau, Rendern

npx hyperframes lint              # Erkennt fehlende data-composition-id, überlappende Spuren, nicht registrierte Timelines
npx hyperframes validate          # WCAG-Kontrast-Audit zu 5 Zeitstempeln
npx hyperframes inspect           # Visuelles Layout-Audit – Überlauf, außerhalb des Frames liegende Elemente, verdeckter Text
npx hyperframes preview           # Live-Browser-Vorschau
npx hyperframes render --quality draft --output draft.mp4    # Schnelle Iteration
npx hyperframes render --quality high --output final.mp4     # Endgültige Auslieferung

hyperframes validate samplet Hintergrundpixel hinter jedem Textelement und warnt bei Kontrastverhältnissen unter 4,5:1 (bzw. 3:1 für großen Text). hyperframes inspect ist das Layout-Seitenstück – führt die Seite zu mehreren Zeitstempeln aus und meldet Probleme, die ein statischer Lint nicht sehen kann (eine Untertitel, die nur bei 4,5s über den sicheren Bereich hinausläuft, eine Karte, die überläuft, wenn ihr Titel die längste Variante ist, ein Element, das hinter einem Übergangs-Shader landet). Führe inspect besonders bei Kompositionen mit Sprechblasen, Karten, Untertiteln oder enger Typografie aus.

8. Website-zu-Video (falls der Benutzer eine URL angibt)

Verwende den 7-Schritte-Capture-zu-Video-Workflow in references/website-to-video.md: Capturen → DESIGN.md → SCRIPT.md → Storyboard → Komposition → Rendern → Ausliefern.

Fallstricke

  • HeadlessExperimental.beginFrame' wasn't found – Chromium 147+ hat dieses Protokoll entfernt. Stelle sicher, dass du hyperframes@>=0.4.2 verwendest (erkennt automatisch und fällt auf Screenshot-Modus zurück). Notluke: export PRODUCER_FORCE_SCREENSHOT=true. Siehe hyperframes#294 und references/troubleshooting.md.
  • System-Chrome (nicht chrome-headless-shell) – Render-Vorgänge hängen 120s lang und brechen dann mit Timeout ab. Führe npx puppeteer browsers install chrome-headless-shell aus (setup.sh macht das). hyperframes doctor meldet, welche Binärdatei verwendet wird.
  • repeat: -1 irgendwo – zerstört die Capture-Engine. Berechne immer eine endliche Wiederholungsanzahl.
  • gsap.set() auf Clip-Elementen, die später erscheinen – das Element existiert beim Seitenladen nicht. Verwende stattdessen tl.set(selector, vars, timePosition) innerhalb der Timeline, zum oder nach dem data-start des Clips.
  • <br> in Inhalts-Text – erzwungene Umbrüche kennen die gerenderte Schriftbreite nicht, daher verursacht natürlicher Umbruch + <br> Doppelumbrüche. Verwende max-width, um Text umbrechen zu lassen. Ausnahme: kurze Anzeigetitel, bei denen jedes Wort bewusst in einer eigenen Zeile steht.
  • Animieren von visibility oder display – GSAP kann diese nicht tweenen. Verwende autoAlpha (handhabt sowohl Sichtbarkeit als auch Deckkraft).
  • Aufruf von video.play() oder audio.play() – das Framework steuert die Wiedergabe. Rufe diese niemals selbst auf.
  • Asynchroner Timeline-Aufbau – die Capture-Engine liest window.__timelines synchron nach dem Seitenladen. Wickle den Timeline-Aufbau niemals in async, setTimeout oder ein Promise.
  • Eigenständiges index.html, eingewickelt in <template> – verbirgt alle Inhalte vor dem Browser. Nur Unter-Kompositionen, die über data-composition-src geladen werden, verwenden <template>.
  • Verwendung von Video für Audio – verwende immer stummgeschaltetes <video> + separates <audio>.

Verifizierung

Vor und nach dem Rendern:

  1. Lint + Validate + Inspect bestehen: npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect (Lint erfasst strukturelle Probleme, Validate erfasst Kontraste, Inspect erfasst visuelle Layout-/Überlauf-Probleme – siehe troubleshooting.md, falls Warnungen auftauchen).
  2. Animations-Choreografie – bei neuen Kompositionen oder signifikanten Animationsänderungen die Animations-Map ausführen. npx hyperframes init kopiert die Skill-Skripte in das Projekt, daher ist der Pfad projektspezifisch:
    node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \
      --out <composition-dir>/.hyperframes/anim-map
    
    Erzeugt eine einzelne animation-map.json mit Zusammenfassungen pro Tween, ASCII-Gantt-Timeline, Stagger-Erkennung, toten Zonen (>1s ohne Animation), Element-Lebenszyklen und Flags (offscreen, collision, invisible, paced-fast <0,2s, paced-slow >2s). Scanne Zusammenfassungen und Flags – korrigiere oder begründe jedes. Überspringe bei kleinen Änderungen.
  3. Datei existiert + nicht Null: ls -lh final.mp4.
  4. Dauer stimmt mit data-duration überein: ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4.
  5. Visuelle Prüfung: Extrahiere einen Frame aus der Mitte der Komposition: ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png.
  6. Audio vorhanden, falls erwartet: ffprobe -v error -show_streams -select_streams a -of default=nw=1:nk=1 final.mp4 | head -1.

Falls hyperframes render fehlschlägt, führe npx hyperframes doctor aus und füge dessen Ausgabe beim Melden bei.

Referenzen

  • composition.md – Datenattribute, Timeline-Vertrag, nicht verhandelbare Regeln, Typografie-/Asset-Regeln
  • cli.md – jeder CLI-Befehl (init, capture, lint, validate, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, benchmark)
  • gsap.md – GSAP-Kern-API für HyperFrames (Tweens, Easing, Stagger, Timelines, matchMedia)
  • features.md – Untertitel, TTS, audio-reaktiv, Marker-Hervorhebung, Übergänge (bei Bedarf laden)
  • website-to-video.md – 7-Schritte-Capture-zu-Video-Workflow
  • troubleshooting.md – OpenClaw-Fix, Umgebungsvariablen, häufige Render-Fehler

Verwandte Skills