Hyperframes Bridge
Orchestriert von: SKILL. Wrapper für externe Abhängigkeit. Das eigentliche Hyperframes-Monorepo befindet sich unter
../../external/hyperframes/(geklont durch/amw-initSchritt 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
- Überprüfen Sie das externe Repository mit zwei Prüfungen:
external/hyperframes/package.jsonmuss existieren, undnpx hyperframes render --helpmuss antworten; brechen Sie sofort ab, wenn eine Prüfung fehlschlägt. - Lösen Sie das Projektverzeichnis auf: verwenden Sie
project_dir, falls angegeben, oder richten Sie ein temporäres Projekt aushtml_scene_pathein; brechen Sie sofort ab, wenn keines von beidem angegeben ist. - 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). - Führen Sie
cd "$HF_PROJ_DIR" && npx hyperframes render --output <mp4>aus; sammeln Sie den Ausgabepfad. - Bestätigen Sie, dass die MP4-Datei existiert und nicht leer ist; melden Sie den Ausgabepfad und etwaige Warnungen aus der Inspection.
- Siehe den Abschnitt
## Aufrufmusterunten 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 überhyperframes browser ensure(verwendet intern Puppeteer +@puppeteer/browsers– NICHT Playwright). -
Externe Quelle:
../../external/hyperframes/– das Hyperframes-Monorepo, geklont vonhttps://github.com/heygen-com/hyperframes. Auf v0.4.30 oder neuer festlegen für Unterstützung voninspect,--hdrunddata-variable-values. Falls der Ordner nicht existiert, MUSS/amw-initoder 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:
| Feld | Typ | Beschreibung |
|---|---|---|
html_scene_path | string (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_dir | string (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
-
Ü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.
-
Projektverzeichnis auflösen.
- Wenn
project_dirangegeben ist: direkt verwenden. SetzeHF_PROJ_DIR="$project_dir". - Wenn
html_scene_pathangegeben 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.
- Wenn
-
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 eingebundenenexternal/hyperframes/-Monorepo), indemvalidatefür unbeaufsichtigte Phase-B-Pipelines hinzugefügt undpreview(ein Entwickler-Schleifen-Primitiv) weggelassen wird.
- Rendern. Vom aufgelösten Projektverzeichnis aus:
Zusätzliche Flags nach Bedarf (cd "$HF_PROJ_DIR" npx hyperframes render --output <abs-mp4-path>--fps,--quality,--format,--hdrusw.) – 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
- 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-Ebenedata-start,data-duration– Sekunden, pro Clipdata-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:
- Artefakte – Hyperframes-Projektordner + gerenderte MP4. Der Pfad wird aus dem Projekt abgeleitet (Benutzerpfad → Framework-Konvention →
./design/<subtype>/→ Fallback./design/videos/). - 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-exportrendert einen einzelnen Frame als PNG/PDF; Hyperframes rendert ein Multi-Frame-MP4 mit Puppeteer + Chrome (verwaltet vonhyperframes browser ensure) + FFmpeg.../amw-dev-browser/– KEIN Ersatz.dev-browserist für Eingabe/Automatisierung; Hyperframes ist der Ausgabe-Rasterizer./amw-init– installiert Bun, FFmpeg und klontexternal/hyperframes/bei erster Verwendung. Chrome zum Rendern wird von Hyperframes selbst überhyperframes browser ensurebereitgestellt.- 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-browserNICHT durch Hyperframes – sie lösen entgegengesetzte Probleme (Eingabe vs. Ausgabe). - Ersetzen Sie
html-export.pyNICHT – ein Einzelframe-PNG ist kein Video. - Der Benutzer MUSS
/amw-initvor 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.