heygen-com/hyperframes

Plugin-Installation: Führe vor Setup- oder Aktualisierungsbefehlen die Plugin-Ausführungsregeln aus, wenn sich dieser Skill innerhalb eines HyperFrames-Plugins befindet. Eigenständige Installationen behalten die folgenden Aktualisierungshinweise.

HyperFrames Core

Agent-Fallstricke (zuerst lesen):

• Zentriere mit flex/inset, nicht mit CSS transform: translate(-50%,-50%) auf einem Knoten, den du dann mit GSAP x/y animierst. Lint: gsap_css_transform_conflict. Verwende fromTo oder xPercent/yPercent.
• Füge keine Szenen-Exit-tl.set(..., {visibility:"hidden"}) hinzu. Die Laufzeit blendet getimte Clips bereits aus. Opazitäts-Fade-Effekte auf inneren Knoten (oder opacity auf .clip) sind ausreichend. Caption-Hard-Kills unterliegen einer anderen Regel.
• window.__timelines["id"] muss mit der Wurzel-data-composition-id übereinstimmen.
• Lies nach dem render die zweite Zeile der Zusammenfassung: beginframe vs. screenshot, GPU-Modus, Stage-Timings. screenshot + software gpu auf Linux ist der langsame Pfad.

HyperFrames rendert Video aus HTML. Eine Komposition ist eine HTML-Datei, deren DOM Timing mit data-*-Attributen deklariert, deren Animations-Laufzeit suchbar ist und deren Medienwiedergabe vom Framework verwaltet wird.

Dieser Skill ist der technische Vertrag – wie man ein HyperFrames-Projekt erstellt. Der folgende Text ist der Bauleitfaden; detaillierte Informationen zu einzelnen Themen finden sich in references/ (Index siehe unten), bei Bedarf lesen. Prozessdokumente (Briefing, Storyboard, Review, Produktion, Dispatch, Frame-Worker) befinden sich in /hyperframes → references/. Andere Belange leben in den verwandten Skill-Domänen – hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. Die Fähigkeitsübersicht in /hyperframes sagt, was jeder abdeckt.

Referenzen

Datei	Zielsetzung
references/minimal-composition.md	Starte mit dem kleinstmöglichen renderbaren Kompositions-Grundgerüst.
references/composition-patterns.md	Wähle monolithisch vs. modular; strukturiere eine modulare index.html; wähle einen Sub-Kompositions-Archetyp.
references/data-attributes.md	Schlage jedes data-* nach (Root / Clip / Sub-Kompositions-Host / Legacy-Aliase); verwende class="clip".
references/tracks-and-clips.md	Verstehe, was data-track-index steuert (und was nicht), z-Index, Timing eines Clips relativ zu einem anderen; liste jeden Track und Clip mit npx hyperframes timeline auf.
references/creator-editing-recipes.md	Kopiere wahrheitsgemäße Ausschneiden/Trimmen/Neu anordnen/Neu timen/Einfrieren/Kamera/Maske/Überblendung/Audio-Bearbeitungsrezepte und deren Grenzen.
references/sub-compositions.md	Verdrahte eine Sub-Komposition (Host-Attribute, <template>, pro-Instanz-Variablen) und animiere darin.
references/variables-and-media.md	Deklariere Variablen; platziere <video>/<audio>, setze Lautstärke, trimme.
references/determinism-rules.md	Erstelle eine suchbare Timeline; Determinismus-Verbote; Layout / Textanpassung.
references/full-screen-motion.md	Erstelle Vollbild-Bewegung mit geteilten Hintergründen.
references/tailwind.md	Arbeite in einem Tailwind v4-Projekt (init --tailwind; Laufzeitvertrag unterscheidet sich von Studios v3).

Für Animations-Laufzeitspezifika (GSAP-API, Lottie, Three.js, etc.) gehe zu hyperframes-animation → adapters/<runtime>.md.

Erstellen einer Komposition

Zwei Wurzelformen (nicht austauschbar)

• Eigenständig (top-level index.html): Wurzel-<div data-composition-id="…"> sitzt direkt im <body>, kein <template>-Wrapper. Das Einwickeln einer eigenständigen Wurzel verbirgt den gesamten Inhalt und lint lehnt es ab (standalone_composition_wrapped_in_template, Fehler).
• Sub-Komposition (geladen über data-composition-src): Wickle die Wurzel in <template>. Dies ist die zu schreibende Form: Der Loader akzeptiert auch ein einfaches vollständiges Dokument und greift auf dessen <body> zurück, aber die Template-Form wird von den Beispielen und Werkzeugen angenommen.

⚠ Transportregel: Bei einer template-basierten Sub-Komposition verwirft der Assembler die eigenen <head>-<style>/<script>-Elemente der Datei (packages/core/src/compiler/compositionAssembly.ts, das hasTemplate-Gate), also platziere <style>/<script> innerhalb des Templates. <link> wird in beiden Fällen hochgezogen. ⚠ Host-ID-Konvention: Gib dem Host-Slot, dem inneren Template und dem window.__timelines["<id>"]-Schlüssel die gleiche ID. Eine andere lokale ID wird unterstützt (der Assembler greift auf die erste Wurzel in der Datei zurück), aber die Nichtübereinstimmung ist still, also stimme sie überein, es sei denn, du hast einen Grund dagegen.

Dateiform, Host-Verdrahtung und die Pre-Render-Checkliste → references/sub-compositions.md.

Wurzel muss dimensioniert sein (stiller Layout-Fehler)

Die eigenständige Wurzel setzt width/height: 100%. Die Leinwandgröße ist data-width/data-height. Die Laufzeit stempelt diese Pixel auf den Kompositionsstamm. Harte 1920px/1080px auf #root vermeiden. Grundgerüst → references/minimal-composition.md.

Eine pausierte Timeline

Jede Komposition registriert genau eine gsap.timeline({ paused: true }) bei window.__timelines["<id>"] (Schlüssel = Wurzel-data-composition-id). Das Erstellen innerhalb eines asynchronen Callbacks (document.fonts.ready) wird unterstützt; wichtig ist, dass du sie erst nach Abschluss des Builds registrierst. Die Renderlänge ist die data-duration der Wurzel, nicht die Länge der Timeline: Eine Timeline, die darüber hinausläuft, wird abgeschnitten, und eine, die früh endet, hält ihren letzten Frame. Fehlt die Wurzel-data-duration, wird die Länge stattdessen abgeleitet (Timeline, Medienfenster oder Adapter). Du brauchst kein window.__timelines = window.__timelines || {}: Die Laufzeit erstellt das Register, bevor deine Inline-Skripte ausgeführt werden, und lint fragt nicht mehr danach. Verschachtele Unter-Timelines nicht manuell in den Host; die Laufzeit verschachtelt registrierte Kind-Timelines automatisch. Vollständiger Vertrag (inkl. Nicht-GSAP-Laufzeiten) → references/determinism-rules.md + hyperframes-animation/adapters/.

First-Pass-Lint-Fallstricke (ein garantiert erster Build-Fehler)

Regeln, die lint zwar abfängt, aber erst im Nachhinein. Schreibe sie gleich richtig:

• Kombiniere niemals eine anfängliche CSS-transform mit einem GSAP-Tween auf der gleichen Eigenschaft – der CSS-Wert und der Start des Tweens kämpfen, und lint lehnt es mit gsap_css_transform_conflict ab. Setze den Anfangszustand innerhalb des Tweens mit gsap.fromTo(el, { x: -40 }, { x: 0 }) anstelle einer CSS transform: translateX(-40px).
• Setze niemals crossorigin auf <video>/<audio>. lint lehnt es bedingungslos mit media_crossorigin_breaks_preview (Fehler) ab, auch für Canvas/WebGL/WebAudio-Rücklesungen. Es gibt keine Unterdrückung.
• Gib einem <video data-start> niemals einen Vorfahren, der ebenfalls data-start trägt. lint lehnt es mit video_nested_in_timed_element (Fehler) ab. Timing auf den Wrapper oder das Video, nicht beides.
• Jedes <audio> braucht eine id. lint lehnt es mit media_missing_id ab, und ein <audio> ohne ID wird vom Mixer nie aufgegriffen, daher ist der Render stumm.
• Tweene niemals einen .clip mit autoAlpha oder visibility – lint lehnt es mit gsap_animates_clip_element ab. Animiere stattdessen ein Kind.
• Eine benannte CSS font-family benötigt ein @font-face in derselben Datei für eine ausgelieferte lokale Datei, sonst feuert lint font_family_without_font_face.
• Sub-Komposition #root verwendet width/height: 100% (oder inset: 0), nicht hartcodiert 1920px/1080px. Die Leinwandgröße ist data-width/data-height.

Ein Lint-Fehler schaltet auch die Layout- und Kontrastprüfungen aus: check meldet dann 0 sample(s) und 0/0 text checks, was wie eine saubere Datei aussieht, aber bedeutet, dass nichts gelaufen ist. Behebe Lint-Fehler, bevor du diesen Zahlen vertraust.

Unverhandelbare Regeln (stille Fehler, die automatisierte Gates übersehen können)

Hier aufgeführt; vollständige Begründung in der verlinkten Referenz. Nicht verletzen:

• Keine Renderzeit-Uhren / ungesäter Math.random / Netzwerk / Eingabezustand; kein repeat: -1 (endliche Anzahl verwenden). → determinism-rules.md
• Nie display, visibility oder autoAlpha auf einem .clip-Element tweenen. Das Framework verwaltet die Clip-Sichtbarkeit, und lint lehnt es ab (gsap_animates_clip_element). Animiere stattdessen ein Kind. → determinism-rules.md
• Kein <br> im Fließtext; transformierte Elemente müssen blockartig + dimensioniert sein; pulsierende absolute Dekorationen benötigen Spitzenabstand. → determinism-rules.md
• <video>/<audio> werden durch eine flache Dokumentabfrage gefunden, daher sucht und dekodiert das Framework sie in jeder Verschachtelungstiefe (auch innerhalb eines Sub-Kompositions-<template> oder Wrappers). Eine harte Grenze: lint gibt einen Fehler aus, wenn ein <video data-start> innerhalb eines anderen einfachen Elements sitzt, das ebenfalls data-start hat, und der Fehler ist real (falsche Quellframes, dann verschwindet der Clip mitten im Slot). Setze das Timing also auf den Wrapper oder auf das Video, nie beides. Sub-Kompositions-Hosts sind ausgenommen: Medien innerhalb einer Sub-Komposition werden korrekt gerendert. Der andere Vorbehalt betrifft Timelines, nicht die Platzierung: Eine Sub-Kompositions-Timeline kann keine Host-Wurzel-Elemente animieren. → variables-and-media.md
• Halte jede id über die assemblierte Seite hinweg eindeutig (präfixiere Sub-Kompositions-IDs mit der Kompositions-ID, #<id>-hero), damit deine eigenen #id-CSS- und getElementById-Aufrufe funktionieren. Die Frame-Injektion hängt nicht mehr davon ab: Der Compiler stempelt eine dokumenteindeutige data-hf-render-id auf jedes video[src]/audio[src]/img[src]. Medien, die <source>-Kinder anstelle eines src-Attributs verwenden, erhalten keinen Stempel, daher sind eindeutige IDs dort immer noch wichtig. → composition-patterns.md
• Eine Vollbildfüllung auf dem Root der Komposition ist bei einem normalen Render in Ordnung. Sie wird nur auf dem geschichteten Kompositionspfad (HDR-Inhalt oder eine Komposition mit Shader-Übergängen) entfernt, wo die Engine jede Kompositionswurzel transparent macht, damit die darunterliegende Schicht durchscheint. Wenn deine Komposition Shader-Übergänge oder HDR-Medien verwendet, platziere die Füllung auf einem vollflächigen Kind (position:absolute; inset:0). → composition-patterns.md

Bearbeiten bestehender Kompositionen

• Lies zuerst die Dateien. Bewahre nicht zusammenhängendes Timing, Tracks, IDs, Variablen, Medienpfade.
• Um zu wissen, was auf dem Timeline eines Projekts ist (Tracks, Clips, Starts, Enden, was abgespielt wird), führe npx hyperframes timeline [--json] aus, anstatt index.html und jede Sub-Kompositionsdatei zu lesen.
• Gleiche vorhandene Kompositions-IDs und Timeline-Schlüssel ab.
• Hinzufügen eines Clips: Setze data-start/data-duration absichtlich in Bezug auf die umgebenden Clips. data-track-index ist eine Studio-Anzeigespur, keine Timing-Einschränkung, daher muss sie nicht frei sein.
• Ein Clip, der über die Wurzel-data-duration hinaus endet, wird abgeschnitten: Verlängere die Wurzel-data-duration bis zum Ende des Clips im selben Edit (lint warnt clip_ends_past_root_duration).
• data-hidden auf einem beliebigen Kompositionselement verbirgt es sowohl in der Vorschau als auch im Render, wobei es sein Zeitfenster überschreibt; es ist nicht destruktiv/umkehrbar und wird durch das Timeline-Augen-Symbol von Studio umgeschaltet.
• Hinzufügen einer Sub-Komposition: Überprüfe ihre interne data-composition-id, bevor du den Host verdrahtest.

Validierung

Verwende hyperframes-cli für Befehlsdetails

• npx hyperframes check besteht (0 Funde über Lint, Laufzeit, Layout, Bewegung und Kontrast hinweg)
• Projekte mit Sub-Kompositionen: npx hyperframes snapshot --at <midpoints> und jedes Bild begutachten
• npx hyperframes preview --background zur Überprüfung (der Benutzer kann alles in Studios Timeline bearbeiten, und der Server überlebt den aufrufenden Befehl)
• npx hyperframes render nur nach Freigabe durch den Benutzer