Was macht ak:hyperframes?
Kapselung der HeyGen hyperframes CLI
für HTML-basierte programmatische Videogenerierung. Diese Skill ist reine
Dokumentation + Wrapper — kein HeyGen-Quellcode und keine kopierten HeyGen-Agent-Skills.
Jeder unten stehende Befehl führt das veröffentlichte npm-Paket über npx aus,
fixiert auf eine bekannte, gute Version.
Verwendungszweck
- Kurze vertikale/Social-Videos (1080×1920, 9:16) gerendert aus HTML/CSS.
- Produktlaunch-Clips, Promo-Loops, Bewegtgrafiken als HTML-Komposition, nicht als React-Komponenten oder Timeline-Editoren.
- Jede Aufgabe, bei der die Komposition als HTML-Markup mit
data-composition-id/data-startTiming-Attributen vorliegt (siehe references/composition-basics.md).
Nicht geeignet für React-first Kompositionen, frame-genaue Interpolationskurven oder Remotions Audio-/Untertitel-Ökosystem — siehe auch die installierte Remotion-Skill für die Alternative (React-basierte programmatische Videos). Nicht geeignet für reine FFmpeg/ImageMagick-Encoding-Aufgaben — siehe auch die ak-media-processing-Skill.
Voraussetzungen
- Node.js 22+
- FFmpeg im
PATH - Optional: Ein HeyGen-Cloud/Lambda-API-Key (
HEYGEN_API_KEY) für Remote-Rendering; lokales Rendering funktioniert ohne.
Führen Sie vor dem Start eines Render-Vorgangs den integrierten Prüfer aus:
node scripts/verify-prereqs.mjs
# oder für maschinenlesbare Ausgabe:
node scripts/verify-prereqs.mjs --json
Siehe references/env-and-deps.md für Installationsanweisungen pro Plattform und den Hinweis zur gepinnten Version.
Gepinnte CLI-Version
Jeder Aufruf unten fixiert [email protected] – die aktuellste veröffentlichte
Version zum 2026-08-07 (npm view hyperframes version). Aktualisieren Sie diesen Pin
an einer Stelle (diese Datei + references/render-workflow.md) beim Upgrade;
verwenden Sie kein unpinned npx -y hyperframes ... in Skripten oder der Dokumentation.
Arbeitsablauf
Der Standardzyklus ist init → HTML bearbeiten → Vorschau → lint → rendern. Vollständige
konkrete Aufrufe für jede Phase finden Sie in
references/render-workflow.md; die Kurzfassung:
# 1. Neues Kompositionsprojekt anlegen.
npx -y [email protected] init my-composition --resolution portrait
# 2. Die generierte HTML-Komposition bearbeiten (siehe composition-basics.md für den
# data-composition-id / data-start / data-width / data-height Vertrag).
# 3. Vorschau in einem lokalen Dev-Server anzeigen.
npx -y [email protected] preview my-composition
# 4. Komposition vor dem Rendern linten (erkennt fehlerhafte Timing-Attribute).
npx -y [email protected] lint my-composition
# 5. In MP4 rendern.
npx -y [email protected] render my-composition --output ./assets/videos/my-composition.mp4
Führen Sie immer lint vor render aus – eine Komposition, die lint sauber
durchläuft, schlägt beim Rendern weit seltener fehl als eine, die direkt rendert.
Kompositionsvertrag
HyperFrames-Kompositionen sind einfache HTML-Dateien, die mit
data-composition-id, data-start, data-width und data-height
Attributen auf dem/den Root-Element(en) annotiert sind. Siehe
references/composition-basics.md für die
vollständige Attributreferenz und ein vollständiges vertikales 1080×1920 Beispiel.
Referenzmaterial
- references/heygen-skills.md – die 25 HeyGen-Agent-Skills,
auf die dieser Wrapper verweist, anstatt sie neu zu implementieren; installieren Sie sie
via
npx -y [email protected] skills, wenn tiefergehendes HyperFrames-spezifisches Fachwissen (Animation, Keyframes, Untertitel, Produktlaunch-Vorlagen etc.) benötigt wird. - references/composition-basics.md – HTML-Kompositions- Attributsvertrag mit einem vollständigen vertikalen Preset-Beispiel.
- references/render-workflow.md – der vollständige
init → edit → preview → lint → renderAblauf mit jedem gepinnten Aufruf. - references/env-and-deps.md – Node/FFmpeg/API-Key-Setup pro Plattform.
Fehlerbehebung
| Symptom | Aktion |
|---|---|
command not found: ffmpeg | Führen Sie node scripts/verify-prereqs.mjs aus, um die genaue Abhilfe für Ihre Plattform zu erhalten. |
npx hyperframes meldet unbekanntes Flag | Die gepinnte Version in dieser Datei könnte hinter dem Upstream liegen; führen Sie npx -y [email protected] --help aus, um die aktuellen Flags zu bestätigen, bevor Sie den Pin aktualisieren. |
render schlägt fehl mit leerem/kurzem MP4 | Führen Sie zuerst lint aus; die meisten Renderfehler werden durch fehlerhafte data-start/data-composition-id-Attribute verursacht, die von lint erkannt werden. |
| Remote/Cloud-Rendering benötigt | Setzen Sie HEYGEN_API_KEY gemäß references/env-and-deps.md und verwenden Sie dann hyperframes cloud render (einen separaten Top-Level-Befehl, kein render-Flag) – siehe references/render-workflow.md. |
Siehe auch
- Die installierte Remotion-Skill (
ak-remotion) – React-basierte programmatische Videogenerierung; verwenden Sie diese, wenn die Komposition von Natur aus ein React-Komponentenbaum und nicht HTML-Markup ist. - Die ak-html-video-Skill – ein separater HTML-zu-MP4-Wrapper
(
nexu-io/html-video) mit eigenem Template/Studio-Workflow; verwenden Sie ak-hyperframes speziell für HeyGen HyperFrames-Kompositionen. - Die ak-motion-graphics-Skill – Router über alle im Repository befindlichen Video-/Bewegtgrafiken-Skills plus externe Motion-Skills-Pakete.