lanceriedel/narrated-demo-skill

Kommentierte Demo

Ein Agent, ein Nachmittag, ein .mov, das ein VP auf dem Handy anschauen kann. Das Rezept (bewährt mit fünf Clips, 69–188 s je):

1. Interview — fünf Fragen, nicht mehr (siehe unten). Erstelle die Geschichte aus dem Kontext, den du bereits hast; der Benutzer redigiert, schreibt nicht.
2. Schreibe ein Szenendrehbuch (clips/<name>.yaml): 4–8 Szenen, ~25–45 Wörter Erzählung pro Szene (≈ 10–18 s gesprochen). Jede Szene hat einen Payoff – den Moment, in dem die Sache erscheint – und das Video wird so geschnitten, dass der Payoff früh, nicht zuletzt, gezeigt wird.
3. Render: scripts/render_clip.py clips/<name>.yaml. Pro Szene: TTS → Aufnahme → Video an Audio anpassen → Untertitel → Muxen; dann zusammenschneiden.
4. Überprüfe die Standbilder, die der Renderer schreibt (out/_<clip>_<scene>.png), mit dem read-Tool, bevor du es als fertig erklärst. Einzelne Szenen mit --only s2 neu rendern.
5. Poste (optional): scripts/slack_post.py <channel_id> out/<clip>.mov "<blurb>".

Alles ist wiederholbar und gecached (TTS nach Texthash, Video pro Szene), sodass die Iteration über einen Satz Sekunden kostet.

1. Das Interview (diese Fragen stellen, dann entwerfen)

Stelle alle fünf in einer Nachricht; akzeptiere Teilantworten und fülle den Rest aus dem Kontext, wobei du kennzeichnest, was du angenommen hast.

1. Für wen ist es, und wie viel Zeit haben sie? (Kollege/Ingenieur 3 min · Führungskraft 90 s · Slack-Scroll 60 s) → legt Szenenanzahl und Tempo fest.
2. Was ist die eine Sache, die sie nach dem Anschauen glauben sollen? → wird Satz 1 von Szene 1 und letzter Satz der letzten Szene.
3. Was muss auf dem Bildschirm zu sehen sein? (eine Benutzeroberfläche, ein Terminal, ein Dokument, ein Diagramm, eine Datei) → entscheidet über die Aufnahmearten. Frage nach URLs / Befehlen / Pfaden.
4. Was ist der 'Live'-Moment? Etwas, das sichtbar passiert (eine Abfrage, die zurückkommt, ein Build, der fertig wird, eine Zahl, die erscheint). Mindestens einer pro Clip.
5. Stimme und Ton? Standard: onyx, „ruhig, klar, selbstbewusste Tech-Demo-Erzählung, mittleres Tempo, leichte Betonung von Zahlen“. Biete alloy/nova an, wenn sie etwas Leichteres wollen.

Dann präsentiere das Storyboard als Tabelle (Szene · Was auf dem Bildschirm · 1-zeilige Erzählungszusammenfassung · Payoff) und hole ein Nicken ein, bevor du renderst. Das Rendern eines 5-Szenen-Clips dauert ~3–6 min; rendere nicht vor dem Nicken.

2. Szenendrehbuch

clip: 1-setup                 # Ausgabename → out/1-setup.mov
größe: 1440x900                # optional: gemeinsamer Rahmen für alle Szenen (anpassen + auffüllen) – setze ihn, wenn du Bildschirm- und Browserszenen mischst
voice: onyx
instructions: "Ruhig, klar, selbstbewusste Tech-Demo-Erzählung. Mittleres Tempo, natürliche Pausen an den Punkten. Leichte Betonung von Zahlen."
scenes:
  - id: s1                    # kurze, stabile IDs → Cache-Schlüssel
    caption: "These · ein Graph, vier Belege"     # Einblendung; ≤ 60 Zeichen
    narration: "…25–45 Wörter…"                     # schreibe Zahlen als Wörter, wenn TTS sie verzerrt ("achtzehntausend")
    # genau eine Aufnahmequelle pro Szene:
    url: "http://127.0.0.1:4300/#mode=purchase"       # (a) Browser via Playwright – plus optionale Aktionen:
    actions:                                          #     nach dem Laden ausführen, in Reihenfolge; `ready` markiert den Payoff
      - fill: ["#prompt", "Acne Studios"]
      - press: ["#prompt", "Enter"]
      - wait: ".layer-chip"                           #     Selektor (45 s Timeout) → setzt ready
      - click: "button:has-text('fit')"
      - select: ["#graph-layout", "brand"]
      - scroll_to: "#join"                            #     scrollIntoView (bei langen Dokumenten) → setzt ready
      - hover: ".card"
    # video: "cache/cr_s3"                            # (b) vorab aufgezeichnetes Verzeichnis (page.mov + marks.json) oder eine Datei – siehe record_screen.sh
    # still: "docs/figure.png"                        # (c) ein statisches Bild (Diagramm, Folie) – ohne Ken-Burns-Effekt, für die Dauer der Erzählung gehalten
    hold: 2                                           # zusätzliche Sekunden nach der letzten Aktion
    speed: 1                                          # Quelle vorab beschleunigen (8 = ein langsamer Crawl, der mit 8× gezeigt wird)
    scale: 2560                                       # pro Szene herunterskalierte Breite (Bildschirmaufnahmen); font: 28 = Untertitel-Px für diese Szene

Regeln, die die Clips gut gemacht haben:

• Payoff zuerst. Der Renderer beginnt jede Szene ~2,5 s vor ready, fügt den letzten Frame an, wenn die Erzählung länger ist, kürzt, wenn sie kürzer ist. Eine Szene, deren Payoff in Sekunde 40 einer 45 s Aufnahme liegt, wird zu einer 12 s Szene, die mit dem Payoff beginnt.
• Erzählung und Bildschirm stimmen überein. Jeder großgeschriebene Name und jede Zahl in der Erzählung müssen sichtbar oder gleich sichtbar sein. Streiche Sätze, die es nicht sind.
• Eine Idee pro Szene. Wenn ein Satz mit „außerdem“ beginnt, ist es eine neue Szene oder er wird gestrichen.
• Untertitel sind die Gliederung. Wenn man nur die Untertitel liest, sollte man die ganze Geschichte bekommen.
• Erfinde niemals eine Zahl für die Erzählung. Nimm sie aus einer Ergebnisdatei oder einer Live-Antwort, die du gerade erstellt hast; sage „ungefähr“, wenn gerundet.

3. Aufnahmequellen

• Browser (url + actions) — Playwright Chromium, 1440×900, headless, zeichnet webm auf. Benötigt ein Node-Projekt mit @playwright/test und installiertem Chromium; setze PW_REPO=/pfad/zu/dem/projekt (Standard: das eigene pw/ des Skills – führe scripts/setup.sh einmal aus, um es zu erstellen).
• Bildschirm / Terminal (video) — scripts/record_screen.sh <szene> <sekunden> [--rect x,y,b,h] -- <befehl…>: startet screencapture -V, führt deinen Befehl aus, schreibt marks.json mit started (ms), wenn der Befehl den Payoff durch Ausgabe von MARK signalisiert. Achtung: screencapture -V schreitet nur fort, wenn sich Pixel ändern; ein statischer Terminal-Bereich friert die Aufnahme ein. Lasse etwas ticken (eine 1-Hz-Taktzeile) oder verwende show_file.sh, das eine Datei mit einer Uhr durchblättert. Verkleinere breite Aufnahmen mit DEMO_SCALE=2560. Privatsphäre: nimm ein Rechteck auf (--rect, in Punkten; screencapture -R), sodass nur der gewünschte Bereich erfasst wird – kein Fenstertitel, keine Registerkartenleiste, Seitenleiste, Dock, Benachrichtigungen oder Hintergrundfenster. Lies vor dem Posten jedes Überprüfungs-Standbild und frage: Identifiziert irgendetwas auf dem Bildschirm einen Arbeitgeber, einen Host, eine interne URL, eine andere Person? Neutralisiere den Text, den du durchblätterst (show_file.sh) – es ist die Demo, nicht deine echten Dateien.
• Standbild (still) — ein PNG/JPG, das für die Dauer der Erzählung gehalten wird; verwende es für Diagramme, Tabellen, eine Folie.
• Vorab aufgezeichnet (video: datei.mov) — mit ready: <sekunden> in der Szene.

4. Rendern, Überprüfen, Posten

export OPENAI_API_KEY=…                     # TTS (gpt-4o-mini-tts); oder TTS_URL=https://<proxy>/v1/audio/speech TTS_API_KEY=… für einen kompatiblen Proxy
scripts/render_clip.py clips/1-setup.yaml            # vollständiger Clip → out/1-setup.mov (+ out/_1-setup_<szene>.png Standbilder)
scripts/render_clip.py clips/1-setup.yaml --only s2  # eine Szene neu rendern, neu zusammenschneiden
DEMO_FONT=26 scripts/render_clip.py …                # Untertitelgröße (22 für 1440 px, 26–30 für 2560 px Quellen)

Überprüfung: Lies zwei oder drei der Standbilder out/_*.png mit read. Wenn eine Browserszene wait failed: … Timeout protokolliert, war die App langsam oder der Selektor hat sich geändert: Die Szene wird trotzdem ab t=0 gerendert (kein Payoff-Cut) – korrigiere den Selektor oder führe die Szene einfach mit --only <id> erneut aus, wenn die App im Leerlauf ist (Startframe jeder Szene) – überprüfe, ob die Untertitel lesbar sind, der Payoff auf dem Bildschirm ist und nichts Sensibles sichtbar ist (Tokens, Käufer-Ebenen-Zeilen, Nachrichten anderer Personen). Schaue dir, wenn möglich, die ersten und letzten 5 s des .mov an.

Poste in Slack mit einem Blurb von ≤ 3 Zeilen: was es zeigt · Länge · eine Zahl. scripts/slack_post.py C0123… out/1-setup.mov "…" verwendet die slack-mcp-Browser-Sitzungsanmeldeinformationen in ~/.config/slack-mcp/credentials.json; falls nicht vorhanden, übergebe dem Benutzer die Datei und den Blurb.

5. Konventionen (Projekt sauber halten)

clips/ Drehbücher · cache/ TTS + pro Szene Video (gitignoriert) · out/ Endprodukte + Standbilder · blurbs/ Slack-Text. Benenne Clips in Wiedergabereihenfolge (0-…, 1-…, 2a-…). Halte ein storyboard.md mit der Tabelle aus dem Interview bereit; es ist das Artefakt, das Leute nach dem Video verlangen.

Abhängigkeiten: ffmpeg/ffprobe, node ≥ 18, Playwright Chromium (für Browserszenen), macOS screencapture (für Bildschirmszenen), einen TTS-Schlüssel. scripts/setup.sh überprüft und installiert, was möglich ist.