Motion Promo Protocol
Überblick
Dieses Skill rendert ein dynamisches, werbefähiges Promovideo eines echten Produkts – keine Bildschirmaufnahme und kein Mockup. Es steuert die tatsächliche App in einem Headless-Browser gegen eine Demo-Umgebung, erfasst saubere Standbilder jeder Ansicht und erstellt einen Motion-Design-Schnitt darüber: kinetische Typografie, cineastische Zooms, Spotlight-Highlights, die den Zoom verfolgen, Handyrahmen für mobile Ansichten, rhythmische Szenenschnitte und einen Musikteppich. Die Ausgabe ist ein 16:9 Master und ein 9:16 vertikaler Schnitt.
Es ist das Rendering-Gegenstück zu launch-feature: launch-feature schreibt ein video-script.md (das Skript/Beats in Prosa); motion-promo verwandelt eine Beat-Liste in das fertige, vertonte Video. Wenn beide ausgeführt werden, verketten Sie sie – launch-feature-Skript → motion-promo-Beats.
Warum HyperFrames (HTML→MP4) und keine Bildschirmaufnahme: deterministisch, wiederholbar, markenkontrolliert, und es umgeht die Fehlermodi der Live-Navigation (siehe Regeln). Die App wird nur verwendet, um Standbilder + Design-Tokens zu erzeugen; alle Bewegungen sind erstellt.
Wann verwenden
- Eine Landing Page / Verkaufsseite benötigt eine Produktdemo oder ein Held-Video.
- Sie kündigen eine Funktion an und möchten das gerenderte Video, nicht nur das Skript.
- Sie haben einen Demo-/Sandbox-Tenant mit realistischen Daten, die Sie zeigen können.
Nicht verwenden für: interne Walkthroughs, bei denen es auf die Wiedergabetreue nicht ankommt (eine rohe Bildschirmaufnahme ist billiger) oder Apps ohne lauffähige Demo-Umgebung.
Voraussetzungen & Geheimnisse
Es sind keine API-Schlüssel / Geheimnisse erforderlich. HyperFrames render ist schlüssellos (lokales HTML→MP4), und Schriftarten (Google Fonts) + die Standardmusik (incompetech) sind öffentliche URLs. Die einzige Anmeldeinformation ist der Demo-Login der Ziel-App, der sich im promo.config.mjs des Ziel-Repositorys befindet – niemals in diesem Skill. Die Authentifizierung ist ein steckbares Rezept: authInject() gibt Werte zurück, die injiziert werden sollen (Token in localStorage, Cookie, API-Key, Multi-Step-Tenant-Auswahl), oder authFlow(page) TREIBT eine interaktive Login-UI (Azure AD / Entra, Okta, Google SSO) und die Engine übernimmt eine Momentaufnahme der Sitzung (localStorage + sessionStorage + Cookies, einschl. HttpOnly). SSO-Anmeldeinformationen stammen aus der Umgebung, nicht aus der Datei. Headless kann keine interaktive MFA passieren – verwenden Sie ein Demo-Konto, das von MFA ausgenommen ist (Conditional Access-Ausnahme), oder ein App-Passwort.
Systemabhängigkeiten (Sie installieren diese – das Skill kann es nicht): Node 20+, systemweites Chrome (google-chrome/Chromium), ffmpeg + ffprobe. Netzwerkzugriff für Schriftarten/Musik.
Automatische/On-Demand-Abhängigkeiten: hyperframes wird bei Bedarf per npx geholt (keine Vorabinstallation). puppeteer-core ist eine eingerüstete npm-Abhängigkeit – es verwendet das systemweite Chrome und lädt kein Chromium herunter.
Einrichtung: Gerüst templates/ in video/<slug>/ (enthält hyperframes.json; meta.json wird von compose-gen generiert), benennen Sie gitignore in .gitignore um, dann npm install und npm run preflight (überprüft Chrome, ffmpeg/ffprobe und puppeteer-core; schlägt laut fehl, wenn eines fehlt). Führen Sie die Pipeline Schritt für Schritt oder mit npm run build aus.
- Eine ausführbare Demo/Sandbox der Ziel-App.
Eingaben
Alles Projektspezifische befindet sich im Ziel-Repository, niemals in diesem Skill:
promo.config.mjs– der Vertrag (siehetemplates/promo.config.example.mjs). App-URL / wie bereitgestellt, Authentifizierungsrezept, Demo-Konto/Tenant, Ausgabepfade und Musikpräferenz. Design-Tokens werden automatisch extrahiert (Schritt 2), können aber hier überschrieben werden.beats.json– die geordnete Aufnahmeliste (siehetemplates/beats.schema.json). Jeder Beat = ein Bildschirm (Route oder erfasstes Standbild) + optionales Highlight-Ziel + Callout-Text + Viewport (Desktop/Mobil).
Gerüsten Sie beide in video/<slug>/ im Ziel-Repository aus templates/.
Protokoll
Arbeiten Sie innerhalb von video/<slug>/ im Ziel-Repository. Jeder Schritt hat eine Überprüfung.
0. Heilen Sie die Demo-Daten (tun Sie dies zuerst – es macht oder bricht das Video)
Demo-/Sandbox-Daten sind normalerweise veraltet oder für den aktuellen Zeitraum auf Null gesetzt (unbezahlte Rechnungen des aktuellen Monats, leere Trichter), was neben „im Autopilot-Modus“ wie „R$0 Umsatz“ aussieht – aktiv kontraproduktiv. Schreiben Sie vor der Erfassung einen idempotenten, auf das aktuelle Datum bezogenen Seed, der jedem Beat gesunde Zahlen gibt (siehe Regeln → Demo-Daten-Nullen). Überprüfen Sie dies, indem Sie die Metriken abfragen, die jeder Beat anzeigen wird.
1. Stellen Sie die App gegen die Demo-API bereit, auf einem CORS-erlaubten Ursprung
Erstellen/betreiben Sie die App, die auf die Demo-API zeigt. Der bereitstellende Ursprung muss in der CORS-Allow-Liste der API sein, sonst wird jeder Datenabruf blockiert und Bildschirme werden leer gerendert (siehe Regeln → CORS-Ursprung). Sondieren Sie die Allow-Liste der API und stellen Sie auf einem erlaubten Port bereit. Überprüfen Sie: Eine tiefe Route gibt 200 zurück, und eine authentifizierte /api/...-Anfrage von diesem Ursprung gibt 2xx zurück.
2. Extrahieren Sie das Designsystem der Ziel-App
Führen Sie templates/engine/extract-design.mjs gegen die bereitgestellte, authentifizierte App aus. Es sampelt berechnete Stile (Seitenhintergrund, Primär-/Akzentfarbe von Schaltflächen/Links, Überschrift + Mono-Schriftfamilien, Radius) → design.tokens.json. Diese speisen die Komposition als CSS-Variablen, sodass die kinetischen Overlays, Akzente und Schriftarten automatisch zur Marke der App passen. Überprüfen und überschreiben Sie bei Bedarf in promo.config, wenn ein gesampelter Token falsch ist.
3. Erfassen Sie saubere Standbilder pro Beat
Führen Sie templates/engine/capture.mjs aus. Es authentifiziert (über das authInject-Rezept der Konfiguration), navigiert zu jeder Beat-Route in dessen Viewport, wartet darauf, dass echte Daten eintreffen (nicht nur network-idle – siehe Regeln) und macht Screenshots zu assets/<beat>.png. Überprüfen Sie, ob jedes Standbild geladene Inhalte zeigt (Größe > ~10 KB, Stichprobe, dass das Zielelement vorhanden ist).
4. Definieren Sie Beats + generieren Sie die Komposition
Füllen Sie beats.json (Route/Standbild, Highlight {x,y,w,h,label} im Standbild-Pixelraum – oder {selector,label,padding?}, automatisch gemessen von capture.mjs und manuell abgestimmten Koordinaten vorzuziehen, Callout {kicker,headline,sub}, Viewport, Dauern). Führen Sie templates/engine/compose-gen.mjs → index.html aus templates/composition.html aus, wobei Tokens + Beats injiziert werden. Halten Sie es knackig: 3–5 s pro Beat, harte Schnitte, eine Idee pro Beat.
5. Holen Sie einen kostenlosen Musiktitel
Führen Sie templates/engine/fetch-music.mjs → assets/music.mp3 aus. Standardquelle ist CC-BY (incompetech); CC-BY erfordert eine Namensnennung (notieren Sie diese für die LP-Beschreibung). Bevorzugen Sie einen projekteigenen/CC0-Titel, wenn verfügbar.
6. Rendern
npx hyperframes render → stummes MP4. Führen Sie zuerst hyperframes lint/inspect aus; behandeln Sie dekorativen/Exit-Animation-Überlauf außerhalb der Leinwand als Rauschen, echten Text-Clipping als Fehler.
7. Rahmen überprüfen + Highlight-Ausrichtung korrigieren
Extrahieren Sie Rahmen am Anfang und Ende jedes Zooms und überprüfen Sie sie mit eigenen Augen. Der #1-Fehler: Spotlight-Highlight driftet während des Zooms von seinem Ziel ab – weil das Highlight-Feld ein Kind des skalierten Containers sein muss (siehe Regeln → Highlight-Verfolgung). Überprüfen Sie auch: keine leeren/Spinner-Bildschirme, mobile Bildschirme sitzen sauber im Handyrahmen, Text ist lesbar.
8. Muxen Sie die Musik
Führen Sie templates/engine/mux.mjs → endgültiges vertontes MP4 aus (loudnorm, Ein-/Ausblenden, -shortest). Überprüfen Sie, ob die Ausgabe einen Audiostream hat und mit der Videodauer übereinstimmt.
9. Leiten Sie den 9:16-Schnitt ab
mux.mjs --reframe erzeugt einen 1080×1920 Schnitt. Führen Sie keinen Center-Crop durch (dies schneidet unten verankerte Callouts ab) – verwenden Sie eine unscharfe Letterbox, die den gesamten Rahmen erhält; mobile Beats sitzen bereits zentriert.
Regeln (hart erarbeitet – lernen Sie sie nicht neu)
- Highlight-Verfolgung. Ein Spotlight-/Highlight-Rechteck über einem Bildschirm, der zoomen soll, MUSS ein Kind desselben Elements sein, das die
scale-Transformation erhält, im Pixel-Koordinatenraum des Standbilds. Als Geschwisterelement bleibt es fix, während das Bild heranzoomt und im Laufe der Einstellung vom Ziel abdriftet. - Demo-Daten-Nullen. Der aktuelle Zeitraum ist oft unbezahlt/leer. Heilen Sie ihn mit einem Seed, der idempotent (deterministische IDs, Löschen-dann-Einfügen) und relativ zu
current_dateist, sodass er sich jeden Zeitraum selbst heilt. - CORS-Ursprung. Ein lokal bereitgestellter Build, der eine bereitgestellte Demo-API aufruft, ist Cross-Origin. Stellen Sie auf einem Ursprung bereit, den die API allow-listet (sondieren Sie ihn) – deaktivieren Sie niemals die Browser-Websicherheit, um dies zu umgehen.
- Warten Sie auf echte Daten.
networkidle2kann aufgelöst werden, bevor die Datenanfrage der App eintrifft → Sie erfassen einen Spinner. Warten Sie zusätzlich auf eine erfolgreiche/api/...-Antwort (oder den Ziel-Content-Selektor), bevor Sie einen Screenshot machen. - HyperFrames über Live-Aufnahme. CDP Screencast stoppt die Ausgabe von Rahmen auf einer visuell statischen Seite und läuft unter der nominalen fps; das Erstellen in HTML (GSAP) vermeidet beides. Wenn Sie doch live aufnehmen müssen, ruckeln Sie den Cursor und codieren Sie mit der effektiven fps.
- Musiklizenzierung. CC-BY (incompetech/Kevin MacLeod) erfordert eine Namensnennung in der LP-Beschreibung; CC0 (Pixabay usw.) nicht. Liefern Sie niemals einen unlizenzierten, gescrapten Clip auf einer veröffentlichten Seite aus.
- Verkettung mit dem Filter, nicht mit dem Demuxer, wenn Segmente unterschiedliche fps haben – der Demuxer lässt stillschweigend Rahmen fallen.
Designsystem-Extraktion (agnostisches Branding)
Die Komposition ist markenneutral; extract-design.mjs füllt seine CSS-Variablen aus der Ziel-App selbst: --bg (Seitenhintergrund), --accent (Primär-/Linkfarbe), --fg (Überschriftfarbe), --font-hero/--font-mono (berechnete Schriftfamilien), --radius. Dies ist es, was ein Skill ermöglicht, markentreue Promos für jede App zu produzieren, ohne Tokens manuell auszuwählen. Überprüfen Sie immer die gesampelten Tokens – eine kontrastarme oder ad-hoc Farbe sampelt gelegentlich falsch; überschreiben Sie in promo.config.design.
Fehler
- App authentifiziert sich nicht im Headless-Modus → das
authInject-Rezept der Konfiguration ist falsch; überprüfen Sie, ob Tokens vor der ersten Navigation inlocalStorage/Cookies landen. - Bildschirme werden leer gerendert → CORS-Ursprung (Schritt 1) oder Warten-auf-Daten (Regel) nicht beachtet.
- Render-Fehler außerhalb der Leinwand → echtes Text-Clipping erfordert kleinere Schrift / Umbruch; dekorativer/Exit-Überlauf ist Rauschen.
- Highlight falsch ausgerichtet → es ist kein Kind des skalierten Containers (Regel).
Komposition mit der Rolle des Vermarkters
Verwenden Sie die Vermarkter-Rolle für Texte: Kicker, Überschriften und die Wertframe pro Beat sollten der Projektstimme folgen (launch-feature's voice.md / marketer-hooks.md, sofern vorhanden). Halten Sie den Text auf dem Bildschirm auf einen Kicker + eine kurze Überschrift + eine Unterzeile pro Beat.