Communitygithub.com

Emasoft/ai-maestro-webdesign

Komposition von HTML in MP4-Videodateien über das externe Hyperframes-Monorepo. Wird durch Ausdrücke wie "HTML als Video rendern", "HTML zu MP4", "Website zu Video", "Video aus HTML erstellen" oder "Komposition zu MP4 rastern" ausgelöst.

Was ist ai-maestro-webdesign?

Dieses Skill fungiert als Brücke zwischen einem KI-Agenten (z. B. Claude Code, Cursor, Codex) und dem externen Hyperframes-Monorepo, das HTML-Kompositionen in MP4-Videos umwandelt. Es wird nur dann verwendet, wenn der Benutzer explizit eine Videoausgabe aus einer HTML-Datei anfordert – etwa durch Phrasen wie „HTML als Video rendern“ oder „HTML zu MP4“. Der Kern des Skills ist ein reiner Shell-Out-Prozess: Zuerst wird das externe Repository auf Vollständigkeit geprüft, dann ein optionaler Projektordner oder eine temporäre HTML-Szene vorbereitet, danach eine vordefinierte Vorab-Prüfungssequenz (Lint, Validierung, Inspection) und schließlich der eigentliche Render-Befehl `npx hyperframes render` ausgeführt. Das Ergebnis ist eine MP4-Datei und ein Job-Abschlussbericht. Das Skill ist autonom und kann von jedem Agenten direkt über diese SKILL.md genutzt werden, ohne auf spezielle Slash-Befehle angewiesen zu sein. Es unterstützt Node.js >=22, Git, Bun und FFmpeg als Laufzeitabhängigkeiten und klont das Hyperframes-Repository bei Bedarf selbstständig.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Emasoft/ai-maestro-webdesign/tree/HEAD/skills/amw-hyperframes-bridge

In Ihrer bevorzugten KI fragen

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

Dokumentation

Hyperframes Bridge

Orchestriert von: SKILL. Wrapper für externe Abhängigkeit. Das eigentliche Hyperframes-Monorepo befindet sich unter ../../external/hyperframes/ (geklont durch /amw-init Schritt 6, falls der Benutzer zustimmt, ODER durch dieses Skill beim ersten Rendern als Fallback). Dieses Skill dokumentiert das Shell-Out-Muster; es enthält das Monorepo NICHT selbst.

Überblick

Rendert HTML-Kompositionen in MP4-Videos, indem es an das Hyperframes-Monorepo (external/hyperframes/) auslagert. Akzeptiert eine einzelne HTML-Szenendatei oder ein vollständiges Hyperframes-Projektverzeichnis. Führt die obligatorische Vorab-Prüfungssequenz (Lint → Validierung → Inspection → Rendern) aus, bevor npx hyperframes render --output <mp4> aufgerufen wird. Gibt den MP4-Pfad und einen Job-Abschlussbericht zurück. Keine Neuimplementierung der Hyperframes-Pipeline innerhalb des Plugins – nur Shell-Out.

Anleitung

  1. Überprüfen Sie das externe Repository mit zwei Prüfungen: external/hyperframes/package.json muss existieren, und npx hyperframes render --help muss antworten; brechen Sie sofort ab, wenn eine Prüfung fehlschlägt.
  2. Lösen Sie das Projektverzeichnis auf: verwenden Sie project_dir, falls angegeben, oder richten Sie ein temporäres Projekt aus html_scene_path ein; brechen Sie sofort ab, wenn keines von beidem angegeben ist.
  3. Führen Sie die Vorab-Prüfungssequenz in der angegebenen Reihenfolge aus: Lint → Validierung → Inspection → Rendern (abbrechen, wenn ein Schritt einen Nicht-Null-Exit-Code liefert).
  4. Führen Sie cd "$HF_PROJ_DIR" && npx hyperframes render --output <mp4> aus; sammeln Sie den Ausgabepfad.
  5. Bestätigen Sie, dass die MP4-Datei existiert und nicht leer ist; melden Sie den Ausgabepfad und etwaige Warnungen aus der Inspection.
  6. Siehe den Abschnitt ## Aufrufmuster unten für die maßgeblichen Ausführungsschritte.

Aktivierung

Kein dedizierter Slash-Befehl – dieses Skill hat keine passende /amw-* Abkürzung. Wird vom design-principles-Orchestrator als letzter Phase-B-Schritt im Main-Agent-Modus aufgerufen, wenn das genehmigte Design eine MP4-Videoausgabe erfordert. Der Orchestrator darf die vollständige Hyperframes-Shell-Out-Pipeline und die Kompositionstechniken dieses Skills ohne Einschränkungen durch die Befehlsebene anwenden.

Dieses Skill ist autonom und in sich geschlossen – jeder Agent (der Haupt-Agent, ein Unter-Agent oder ein externer Orchestrator) kann es verwenden, indem er diese SKILL.md und ihre Referenzen liest. Die Techniken des Skills sind NICHT auf diejenigen beschränkt, die durch passende Befehle offengelegt werden.

Position im Ablauf

AUSGABE (Phase B — terminal). HTML-zu-MP4-Videorender-Pipeline. Wird nur ausgelöst, wenn der Benutzer explizit eine HTML-Komposition in eine Videodatei gerastert haben möchte. Läuft zuletzt, nach Abschluss der Kompositionserstellung.

Auslösebedingungen

Rufen Sie dieses Skill NUR auf, wenn die Anfrage mit einem der folgenden Punkte übereinstimmt:

  • "rendere dieses HTML als Video" / "rendere zu MP4"
  • "HTML zu MP4" / "Website zu Video" / "Seite zu Video"
  • "erstelle ein Video aus dieser HTML-Komposition"
  • "rastere die Komposition zu Video"
  • Explizite Erwähnung von Hyperframes / hyperframes render / .hf.html

NICHT aufrufen bei allgemeinen Erwähnungen von "Animation", "Bewegung", "Videowiedergabe" oder "animierte Komponente" – diese gehören zu:

  • ../amw-design-principles/starter-components/animations.html (In-Browser Stage + Sprite-Zeitleiste)
  • ../amw-pretext/ (typografische Bewegung – pretext-art/ ist eine veraltete Weiterleitung)
  • Der eigenen Pipeline des Benutzers

Voraussetzungen

  • Laufzeit-Binärdateien (Systemvoraussetzungen): Node.js >= 22, git

  • Laufzeit-Binärdateien (installiert durch /amw-init): Bun (Hyperframes Paketmanager), FFmpeg. Chrome wird von Hyperframes selbst verwaltet über hyperframes browser ensure (verwendet intern Puppeteer + @puppeteer/browsers – NICHT Playwright).

  • Externe Quelle: ../../external/hyperframes/ – das Hyperframes-Monorepo, geklont von https://github.com/heygen-com/hyperframes. Auf v0.4.30 oder neuer festlegen für Unterstützung von inspect, --hdr und data-variable-values. Falls der Ordner nicht existiert, MUSS /amw-init oder dieses Skill ihn vor dem Fortfahren klonen:

    git clone --branch v0.4.30 --depth 1 https://github.com/heygen-com/hyperframes.git external/hyperframes
    cd external/hyperframes && bun install
    

Eingabevertrag

Die Brücke akzeptiert zwei sich gegenseitig ausschließende Eingaben. Geben Sie genau eine an:

FeldTypBeschreibung
html_scene_pathstring (optional)Absoluter Pfad zu einer einzelnen HTML-Datei. Die Brücke richtet ein temporäres Hyperframes-Projektverzeichnis über mktemp -d -t hf-XXXXXX (POSIX-kompatibel) ein, schreibt das HTML als index.html, rendert und räumt auf, nachdem der Bericht geschrieben wurde.
project_dirstring (optional)Absoluter Pfad zu einem bereits bestehenden Hyperframes-Projektverzeichnis (enthält index.html und optional compositions/, assets/). Die Brücke wechselt direkt dorthin – keine Einrichtung. Unterstützt Unterkompositionen, Audio und externe Assets.

Wenn beide angegeben sind, gewinnt project_dir. Wenn keines angegeben ist, sofort abbrechen.

Aufrufmuster

  1. Überprüfen des externen Repositorys – zwei Prüfungen erforderlich:

    # Prüfung 1 – package.json vorhanden (Monorepo geklont)
    test -f "external/hyperframes/package.json" || exit-fail "Monorepo nicht gefunden"
    # Prüfung 2 – CLI antwortet (Installation funktionsfähig)
    # @hyperframes/cli ist NICHT auf npm veröffentlicht – muss innerhalb des Monorepo-Workspace ausgeführt werden
    (cd external/hyperframes && npx hyperframes render --help) >/dev/null 2>&1 || exit-fail "Hyperframes CLI nicht funktionsfähig – führen Sie bun install innerhalb von external/hyperframes/ aus"
    

    Wenn eine der Prüfungen fehlschlägt, sofort abbrechen. Nicht fortfahren.

  2. Projektverzeichnis auflösen.

    • Wenn project_dir angegeben ist: direkt verwenden. Setze HF_PROJ_DIR="$project_dir".
    • Wenn html_scene_path angegeben ist: temporäres Projekt einrichten:
      HF_PROJ_DIR="$(mktemp -d -t hf-XXXXXX)"
      cp "$html_scene_path" "$HF_PROJ_DIR/index.html"
      
    • Andernfalls: sofort abbrechen.
  3. Vorab-Prüfungssequenz ausführen: Lint → Validierung → Inspection → Rendern.

    cd "$HF_PROJ_DIR"
    npx hyperframes lint
    npx hyperframes validate
    npx hyperframes inspect --json  # bei Fehlern abbrechen (Nicht-Null-Exit mit --strict)
    

    Siehe TECH-hyperframes-cli-lint, TECH-hyperframes-cli-validate, TECH-hyperframes-cli-inspect.

[TECH-hyperframes-cli-inspect.md] Was es tut · Wann verwenden · Wie es funktioniert · Flags · Ausgabe (JSON-Modus) · Minimalbeispiel · Opt-out-Attribute · Fallstricke · Querverweise [TECH-hyperframes-cli-validate.md] Was es tut · Wann verwenden · Wie es funktioniert · Ausgabe · Wann Warnungen erscheinen · Minimalbeispiel · Fallstricke · Querverweise [TECH-hyperframes-cli-lint.md] Was es tut · Wann verwenden · Wie es funktioniert · Minimalbeispiel · Fallstricke · Querverweise

Anmerkung zur Sequenz: Die Sequenz der Brücke (Lint → Validierung → Inspection → Rendern) erweitert die der Upstream-Pipeline absichtlich (Lint → Inspection → Vorschau → Rendern – siehe die Upstream-Hyperframes-CLI SKILL.md im eingebundenen external/hyperframes/-Monorepo), indem validate für unbeaufsichtigte Phase-B-Pipelines hinzugefügt und preview (ein Entwickler-Schleifen-Primitiv) weggelassen wird.

  1. Rendern. Vom aufgelösten Projektverzeichnis aus:
    cd "$HF_PROJ_DIR"
    npx hyperframes render --output <abs-mp4-path>
    
    Zusätzliche Flags nach Bedarf (--fps, --quality, --format, --hdr usw.) – siehe TECH-hyperframes-cli-render.

[TECH-hyperframes-cli-render.md] Was es tut · Wann verwenden · Wie es funktioniert · Flags · Qualitätsrichtlinien · Transparentes Video · Minimalbeispiel · Worker-Tuning · Fallstricke · Querverweise

  1. MP4-Pfad an den Aufrufer zurückgeben. Wenn das Projektverzeichnis ein temporäres Gerüst war (html_scene_path-Pfad), nach dem Schreiben des Berichts entfernen.

HTML-Kompositionsregeln (Hyperframes-spezifisch)

Kompositionen verwenden einfaches HTML mit data-*-Zeitleistenattributen auf einem #stage-Root und seinen Kindern (Spuren / Clips / Overlays). Dies ist dasselbe Stage + Sprite-Konzept wie in ../amw-design-principles/starter-components/animations.html – Hyperframes erweitert es um Mehrspur-Audio/Video-Mischung und Offscreen-deterministisches Rendern.

Wichtige Attribute (das maßgebliche Schema befindet sich nach dem Klonen in external/hyperframes/packages/core/):

  • data-composition-id – Kennung auf Stage-Ebene
  • data-start, data-duration – Sekunden, pro Clip
  • data-track-index – Ebenen-Reihenfolge (Video / Overlay / Audio-Spuren)
  • data-width, data-height – Leinwandabmessungen auf Stage-Ebene

Führen Sie Framer Motion, GSAP-als-Abhängigkeit oder eine andere Drittanbieter-Animation-Laufzeit NICHT in die Brücke ein. Hyperframes hat sein eigenes Frame-Adapter-Muster; wenn der Benutzer GSAP innerhalb einer Komposition wünscht, ist das Hyperframes' Angelegenheit, nicht die der Brücke.

Referenzen

Vollständiger Referenzindex: INDEX.md – 32 TECH-*.md-Dateien, gruppiert nach Capture-Pipeline (7 Schritte), CLI-Befehle (12), Kompositionserstellung (7), Registry (4). Jede Datei hat ihr eigenes Inhaltsverzeichnis; laden Sie nur die, die Sie benötigen.

Beispiele

Siehe die ausgearbeiteten Beispiele in den pro-Schritt-Referenzdateien unter ./references/TECH-hyperframes-capture-step-*.md (7-Schritte-Website-zu-Video-Pipeline) und den Kompositionserstellungsleitfaden unter TECH-hyperframes-composition-core.

[TECH-hyperframes-composition-core.md] Was es tut · Wann verwenden · Wie es funktioniert · Ansatz (erzählerische Reihenfolge) · Einzeldatei-Gerüst · Visuelles Identitätstor (MUSS – vor dem Schreiben von HTML) · Fallstricke · Querverweise

Ausgabe

Eine gerenderte MP4-Videodatei plus einen Job-Abschlussbericht. Die MP4 wird von npx hyperframes render --output <mp4> aus dem aufgelösten Projektverzeichnis erstellt; die Brücke bestätigt, dass die Datei existiert und nicht leer ist, bevor sie den Erfolg meldet. Vollständiger Vertrag unten.

Ausgabe- und Abschlusscheckliste

Der vollständige Ausgabevertrag (Regeln zur Ableitung von Artefaktpfaden, Form des Job-Abschlussberichts, obligatorische Checkliste) befindet sich in TECH-output-contract. Zwei Ausgaben sind obligatorisch:

  1. Artefakte – Hyperframes-Projektordner + gerenderte MP4. Der Pfad wird aus dem Projekt abgeleitet (Benutzerpfad → Framework-Konvention → ./design/<subtype>/ → Fallback ./design/videos/).
  2. Job-Abschlussbericht unter $MAIN_ROOT/reports/webdesigner/<ts±tz>-amw-video-producer-<slug>-<8-char-hash>.md, der jedes Artefakt plus das Urteil pro Checklistenelement auflistet.

Vor der Meldung des Abschlusses: Jedes Checklistenelement in TECH-output-contract MUSS auf BESTANDEN oder NICHT ZUTREFFEND gesetzt sein. Jedes FEHLGESCHLAGEN löst eine Korrekturschleife aus.

Ressourcen

  • ../amw-design-principles/starter-components/animations.html – die ~50-zeilige Stage + Sprite-Zeitleisten-Engine für In-Browser-Vorschauen; Hyperframes teilt denselben Rhythmus.
  • ../../bin/amw-html-export.py – KEIN Ersatz. html-export rendert einen einzelnen Frame als PNG/PDF; Hyperframes rendert ein Multi-Frame-MP4 mit Puppeteer + Chrome (verwaltet von hyperframes browser ensure) + FFmpeg.
  • ../amw-dev-browser/ – KEIN Ersatz. dev-browser ist für Eingabe/Automatisierung; Hyperframes ist der Ausgabe-Rasterizer.
  • /amw-init – installiert Bun, FFmpeg und klont external/hyperframes/ bei erster Verwendung. Chrome zum Rendern wird von Hyperframes selbst über hyperframes browser ensure bereitgestellt.
  • Externes Repo: https://github.com/heygen-com/hyperframes

Unverhandelbar

  • Verwenden Sie das externe Monorepo per Shell-Out. Implementieren Sie seine Pipeline NICHT innerhalb des Plugins neu.
  • Kopieren Sie den Hyperframes-Quellcode NICHT in skills/ – 500+ Dateien sind für ein Skill der falsche Umfang.
  • Ersetzen Sie dev-browser NICHT durch Hyperframes – sie lösen entgegengesetzte Probleme (Eingabe vs. Ausgabe).
  • Ersetzen Sie html-export.py NICHT – ein Einzelframe-PNG ist kein Video.
  • Der Benutzer MUSS /amw-init vor der ersten Verwendung ausführen, um Bun + FFmpeg zu installieren und das externe Repo zu klonen. Chrome wird durch einmaliges Ausführen von (cd external/hyperframes && npx hyperframes browser ensure) nach dem Klonen bereitgestellt.

Fehlerbehandlung

Häufige Fehlermodi und Korrekturmaßnahmen befinden sich in TECH-error-handling. Behandelt: fehlendes externes Repo, Bereitstellung von Bun / FFmpeg / Chrome, HTML-Attribut-Parse-Fehler, Videokodierungsfehler, veraltete Klone.

Verwandte Skills