Communitygithub.com

leocosta/octopus

Verwandelt eine laufende App in ein hochwertiges, dynamisches Werbevideo, indem das echte Produkt (Headless Chrome) gesteuert, saubere Screenshots erfasst und ein Motion-Design-Schnitt (kinetische Typografie, cineastische Zooms, Spotlight-Highlights, Handyrahmen, vertont) mit HyperFrames + GSAP erstellt wird. App-unabhängig: Liest eine projektspezifische promo.config und eine Beat-Liste; extrahiert automatisch das Designsystem der Ziel-App, sodass Overlays zur Marke passen. Liefert einen 16:9 Master + 9:16 Schnitt.

Was ist octopus?

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-Pendant 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. Warum HyperFrames (HTML→MP4) und keine Bildschirmaufnahme: deterministisch, wiederholbar, markenkontrolliert und es umgeht die Fehlermodi der Live-Navigation. Die App wird nur verwendet, um Standbilder + Design-Tokens zu erzeugen; alle Bewegungen sind erstellt. Das Skill unterstützt sowohl authentifizierte Apps mit nativen Login-Rezepten (token-basiert oder interaktiver SSO-Flow) als auch unbeaufsichtigte Szenarien. Es ist ideal für Landing Pages, Feature-Ankündigungen und Produktdemos, die eine echte, live aussehende Benutzeroberfläche mit professionellem Motion-Design-Schnitt erfordern.

Funktioniert mit~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/leocosta/octopus/tree/HEAD/skills/motion-promo

In Ihrer bevorzugten KI fragen

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

Dokumentation

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:

  1. promo.config.mjs – der Vertrag (siehe templates/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.
  2. beats.json – die geordnete Aufnahmeliste (siehe templates/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_date ist, 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. networkidle2 kann 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 in localStorage/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.

Verwandte Skills