OpenMinis/MinisSkills

HyperFrames

Zum ersten Mal? Führen Sie vor dem Start die Umgebungsprüfung durch:

python3 /var/minis/skills/hyperframes-cli/scripts/check-env.py

Dies überprüft, ob minis-browser-use, ffmpeg und die erforderlichen Fähigkeiten installiert sind. Wenn die hyperframes-cli-Fähigkeit fehlt, installieren Sie sie:

python3 /var/minis/skills/hyperframes-cli/scripts/install-skill.py \
  hyperframes-cli --repo heygen-com/hyperframes --subdir skills

HTML ist die Quelle der Wahrheit für Video. Eine Komposition ist eine HTML-Datei mit data-*-Attributen für das Timing, einer GSAP-Timeline für Animationen und CSS für das Erscheinungsbild. Das Framework kümmert sich um die Sichtbarkeit von Clips, die Medienwiedergabe und die Synchronisation der Timeline.

Vorgehensweise

Bevor Sie HTML schreiben, denken Sie auf einer hohen Ebene:

1. Was – was soll der Betrachter erleben? Identifizieren Sie den erzählerischen Bogen, die Schlüsselmomente und die emotionalen Höhepunkte.
2. Struktur – wie viele Kompositionen, welche davon sind Sub-Kompositionen vs. inline, welche Spuren tragen was (Video, Audio, Overlays, Untertitel).
3. Timing – welche Clips bestimmen die Dauer, wo liegen die Übergänge, wie ist das Tempo.
4. Layout – bauen Sie zuerst den Endzustand. Siehe "Layout vor der Animation" unten.
5. Animieren – fügen Sie dann Bewegung mit den folgenden Regeln hinzu.

Für kleine Änderungen (eine Farbe korrigieren, Timing anpassen, ein Element hinzufügen) überspringen Sie direkt die Regeln.

Visuelle Identitätsprüfung

Überprüfen Sie in dieser Reihenfolge:

1. Existiert DESIGN.md im Projekt? → Lesen Sie es. Verwenden Sie seine exakten Farben, Schriftarten, Bewegungsregeln und "Was NICHT zu tun"-Einschränkungen.
2. Existiert visual-style.md? → Lesen Sie es. Wenden Sie seinen style_prompt_full und die strukturierten Felder an. (Hinweis: visual-style.md ist eine projektspezifische Datei. visual-styles.md ist die Stilbibliothek mit 8 benannten Vorlagen – es handelt sich um verschiedene Dateien.)
3. Hat der Benutzer einen Stil genannt (z.B. "Swiss Pulse", "dunkel und technisch", "Luxusmarke")? → Lesen Sie die visual-styles.md für die 8 benannten Vorlagen. Erstellen Sie ein minimales DESIGN.md mit: ## Style Prompt (ein Absatz), ## Colors (3-5 Hex-Werte mit Rollen), ## Typography (1-2 Schriftfamilien), ## What NOT to Do (3-5 Anti-Patterns).
4. Keines der oben genannten? → Stellen Sie 3 Fragen, bevor Sie HTML schreiben:
   • Was ist die Stimmung? (explosiv / filmisch / fließend / technisch / chaotisch / warm)
   • Helle oder dunkle Leinwand?
   • Gibt es spezifische Markenfarben, Schriftarten oder visuelle Referenzen? Erstellen Sie dann aus den Antworten ein minimales DESIGN.md.

Jede Komposition muss ihre Palette und Typografie auf ein DESIGN.md, visual-style.md oder eine explizite Benutzeranweisung zurückführen. Wenn Sie nach #333, #3b82f6 oder Roboto greifen – haben Sie diesen Schritt übersprungen.

Für Bewegungsvorgaben, Größenanpassung, Eintrittsmuster und Easing – folgen Sie house-style.md. Der Hausstil kümmert sich darum, WIE sich Dinge bewegen. Das DESIGN.md kümmert sich darum, WIE Dinge aussehen.

Layout vor der Animation

Positionieren Sie jedes Element dort, wo es in seinem sichtbarsten Moment sein soll – dem Frame, in dem es vollständig eingetreten, korrekt platziert und noch nicht im Austritt ist. Schreiben Sie dies zuerst als statisches HTML+CSS. Noch kein GSAP.

Warum das wichtig ist: Wenn Sie Elemente in ihrem animierten Startzustand positionieren (außerhalb des Bildschirms, auf 0 skaliert, Deckkraft 0) und sie dann dorthin tweenen, wo Sie glauben, dass sie landen sollen, raten Sie das endgültige Layout. Überlappungen bleiben unsichtbar, bis das Video gerendert wird. Indem Sie zuerst den Endzustand erstellen, können Sie Layoutprobleme erkennen und beheben, bevor Sie Bewegung hinzufügen.

Der Prozess

1. Identifizieren Sie den Helden-Frame für jede Szene – den Moment, in dem die meisten Elemente gleichzeitig sichtbar sind. Dies ist das Layout, das Sie erstellen.
2. Schreiben Sie statisches CSS für diesen Frame. Der .scene-content-Container MUSS die gesamte Szene mit width: 100%; height: 100%; padding: Npx; füllen, mit display: flex; flex-direction: column; gap: Npx; box-sizing: border-box. Verwenden Sie Padding, um den Inhalt nach innen zu verschieben – verwenden Sie NIEMALS position: absolute; top: Npx auf einem Inhaltscontainer. Absolut positionierte Inhaltscontainer laufen über, wenn der Inhalt größer ist als der verbleibende Platz. Reservieren Sie position: absolute nur für dekorative Elemente.
3. Fügen Sie Eintritte mit gsap.from() hinzu – animieren Sie VON außerhalb des Bildschirms/unsichtbar ZUR CSS-Position. Die CSS-Position ist die Grundwahrheit; der Tween beschreibt die Reise dorthin.
4. Fügen Sie Austritte mit gsap.to() hinzu – animieren Sie ZU außerhalb des Bildschirms/unsichtbar VON der CSS-Position.

Beispiel

/* scene-content füllt die Szene, Padding positioniert den Inhalt */
.scene-content {
  display: flex;
  flex-direction: column;
  justify-content: center;
  width: 100%;
  height: 100%;
  padding: 120px 160px;
  gap: 24px;
  box-sizing: border-box;
}
.title {
  font-size: 120px;
}
.subtitle {
  font-size: 42px;
}
/* Container füllt jede Szenengröße (1920x1080, 1080x1920, usw.).
   Padding positioniert den Inhalt. Flex + Gap handhabt die Abstände. */

FALSCH – fest codierte Abmessungen und absolute Positionierung:

.scene-content {
  position: absolute;
  top: 200px;
  left: 160px;
  width: 1920px;
  height: 1080px;
  display: flex; /* ... */
}

// Schritt 3: IN diese Positionen animieren
ld.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);

// Schritt 4: VON diesen Positionen AUS animieren
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);

Multi-Szenen-Kompositionen: ein Container pro Szene

Wenn eine Komposition mehrere Szenen hat, die nacheinander erscheinen (A geht raus, dann B geht rein), legen Sie niemals alle Elemente aller Szenen in einen einzigen gemeinsamen Flex-Container. Auch wenn jedes Element mit opacity: 0 beginnt, reserviert Flex dennoch Höhe für jedes Kind. Mit dem Inhalt von 5 Szenen in einem Container übersteigt die Gesamthöhe des Containers die Bühnenhöhe bei weitem – Flex justify-content: center zentriert den Inhalt dann relativ zu diesem überdimensionierten Container und schiebt den sichtbaren Inhalt außerhalb des Screenshot-Ausschnitts.

FALSCH – alle Szenen in einem Flex-Container:

<div class="scene-content"> <!-- Flex-Spalte, height:100% -->
  <!-- Szenen A Elemente -->
  <div id="title-a" style="opacity:0">Titel A</div>
  <div id="body-a"  style="opacity:0">Textkörper A</div>
  <!-- Szenen B Elemente – nehmen auch Flex-Höhe ein, auch wenn unsichtbar -->
  <div id="title-b" style="opacity:0">Titel B</div>
  <div id="body-b"  style="opacity:0">Textkörper B</div>
  <!-- Szene C ... -->
</div>

RICHTIG – jede Szene ist ihre eigene absolute Ebene:

<!-- Szene A -->
<div class="scene" id="scene-a">
  <div id="title-a" style="opacity:0">Titel A</div>
  <div id="body-a"  style="opacity:0">Textkörper A</div>
</div>
<!-- Szene B – null Höhenauswirkung auf Szene A -->
<div class="scene" id="scene-b">
  <div id="title-b" style="opacity:0">Titel B</div>
  <div id="body-b"  style="opacity:0">Textkörper B</div>
</div>

/* Jede Szene füllt die Bühne unabhängig aus */
.scene {
  position: absolute;
  inset: 0;
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  padding: 80px 120px;
  box-sizing: border-box;
  z-index: 2;
  gap: 24px;
}

Dies ist das einzig korrekte Muster für aufeinanderfolgende Szenen. Das position: absolute; inset: 0 auf jedem Szenencontainer widerspricht NICHT der Richtlinie "Layout vor der Animation" – diese Richtlinie verbietet absolute Positionierung von Inhaltselementen (Titel, Karten, Statistiken) mit fest codierten Pixel-Offsets. Szenen-Container, die die gesamte Bühne über inset: 0 füllen, sind korrekt und erforderlich.

Wenn Elemente Platz über Zeit teilen

Wenn Element A austritt, bevor Element B im selben Bereich eintritt, sollten beide korrekte CSS-Positionen für ihre jeweiligen Helden-Frames haben. Die Timeline-Reihenfolge garantiert, dass sie niemals visuell koexistieren – aber wenn Sie den Layout-Schritt überspringen, werden Sie den Fall nicht bemerken, in dem sie aufgrund eines Timing-Fehlers versehentlich überlappen.

Was als beabsichtigte Überlappung zählt

Geschichtete Effekte (Glühen hinter Text, Schattenelemente, Hintergrundmuster) und Z-Stapel-Designs (Kartenstapel, Tiefenschichten) sind beabsichtigt. Der Layout-Schritt dient dazu, unbeabsichtigte Überlappungen zu erkennen – zwei Überschriften, die übereinander landen, eine Statistik, die ein Label bedeckt, Inhalt, der aus dem Frame läuft.

Datenattribute

Alle Clips

Attribut	Erforderlich	Werte
id	Ja	Eindeutiger Identifikator
data-start	Ja	Sekunden oder Clip-ID-Referenz ("el-1", "intro + 2")
data-duration	Erforderlich für img/div/compositions	Sekunden. Video/Audio standardmäßig Mediendauer.
data-track-index	Ja	Ganze Zahl. Clips auf derselben Spur können sich nicht überlappen.
data-media-start	Nein	Trim-Offset in die Quelle (Sekunden)
data-volume	Nein	0-1 (Standard 1)

data-track-index beeinflusst NICHT die visuelle Überlagerung – verwenden Sie CSS z-index.

Composition-Clips

Attribut	Erforderlich	Werte
data-composition-id	Ja	Eindeutige Kompositions-ID
data-start	Ja	Startzeit (Root-Komposition: verwenden Sie "0")
data-duration	Ja	Hat Vorrang vor der GSAP-Timeline-Dauer
data-width / data-height	Ja	Pixelmaße (1920x1080 oder 1080x1920)
data-composition-src	Nein	Pfad zur externen HTML-Datei

Composition-Struktur

Sub-Kompositionen, die über data-composition-src geladen werden, verwenden einen <template>-Wrapper. Eigenständige Kompositionen (die main index.html) verwenden KEIN <template> – sie setzen das data-composition-id-div direkt in <body>. Die Verwendung von <template> bei einer eigenständigen Datei verbirgt den gesamten Inhalt vor dem Browser und bricht das Rendering.

Sub-Komposition-Struktur:

<template id="my-comp-template">
  <div data-composition-id="my-comp" data-width="1920" data-height="1080">
    <!-- Inhalt -->
    <style>
      [data-composition-id="my-comp"] {
        /* begrenzte Stile */
      }
    </style>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
    <script>
      window.__timelines = window.__timelines || {};
      const tl =