Was macht Demo-Narrator?
Pipeline: Frames → Verstehen → Skript-Entwurf → BENUTZERFREIGABE → SFX + TTS → Rendern → Prüfen.
Ausgabe: output_final.mp4 (H.264/AAC, −16 LUFS, Untertitel eingebrannt) + subtitles.srt.
SKILL="<absoluter Pfad des Verzeichnisses, das diese SKILL.md enthält>" # z. B. ~/.claude/skills/demo-narrator oder ./.claude/skills/demo-narrator
PY="$SKILL/.venv/bin/python"
Löse SKILL einmal zu Beginn auf (abhängig davon, wo der Skill installiert wurde) und verwende ab dann absolute Pfade.
0. Vorbereitung
- Falls
$PYnicht existiert, teile dem Benutzer mit, dass das Setup ffmpeg + espeak-ng (Homebrew/apt), eine Python 3.12-Venv, PyTorch und ~400 MB freie Modellgewichte installiert; bei Zustimmung führebash "$SKILL/setup.sh"aus (dauert ein paar Minuten; im Hintergrund ausführen). - Wähle ein Arbeitsverzeichnis neben dem Video:
WORK="<Video-Verzeichnis>/demo-narrator-work/<Video-Stammname>". Schreibe niemals in das Skill-Verzeichnis. - Frage (eine Nachricht, nur was unbekannt ist): Produktname + Funktion, Zielgruppe, Tonfall (Standard: freundlich, selbstbewusst, präzise), Sprachpräferenz (Standard
af_heart) und alles, was gesagt werden muss (CTA, URL). Blockiere nicht, wenn der Benutzer bereits „mach einfach“ gesagt hat – leite aus den Frames ab.
1. Frames extrahieren + Dauer prüfen
"$PY" "$SKILL/scripts/extract_frames.py" "<video>" --out "$WORK"
- Gibt Dauer/Auflösung aus, sampelt 1 Frame / 2 s, erkennt Szenenwechsel, erstellt 3×3-Kontaktabzüge.
- Lehnt Videos < 3 s oder > 15 min ab (
--force/--max-durationzum Überschreiben; verwende--interval 4für lange Videos). - Überprüfe zuerst
$WORK/sheets/*.jpg(jeweils mit Zeitstempeln versehen). Öffne einzelne$WORK/frames/*.jpgnur dort, wo du Details benötigst (kleiner UI-Text, genauer Moment eines Klicks). $WORK/frames.json→duration,scene_changes(beste Stellen für Whooshes), Frameliste.
Erstelle eine Beat-Liste: Was ist zu welchem Zeitpunkt auf dem Bildschirm, welche Aktionen passieren (Klick, Tippen, Seitenwechsel, Erfolgszustand) und was der Betrachter mitnehmen soll.
2. Skript $WORK/script.json entwerfen
{
"video": "/abs/pfad/zum/demo.mp4",
"voice": "af_heart",
"speed": 1.0,
"approved": false,
"segments": [
{"id": 1, "start": 0.4, "end": 4.6, "text": "Lernen Sie Relay kennen, den schnellsten Weg, um Kundenanrufe in Tickets zu verwandeln."},
{"id": 2, "start": 5.0, "end": 10.8, "text": "Laden Sie eine Aufnahme hoch, und Relay extrahiert für Sie jeden Fehler, jede Anfrage und jedes Follow-up."}
],
"sfx": [
{"name": "whoosh", "at": 4.8},
{"name": "pop", "at": 7.2, "gain_db": -12},
{"name": "ding", "at": 10.4}
]
}
Timing-Regeln
- Wortbudget pro Segment ≈
(end − start) × 2.5Wörter (Kokoro ≈ 150 Wörter/min bei Geschwindigkeit 1.0). Bleibe darunter. - Lasse ≥ 0,3 s zwischen den Segmenten; beginne die erste Zeile bei etwa 0,3–0,8 s; lasse das Video nach großen Momenten atmen.
- Verankere
startan dem Moment, in dem das Beschriebene erscheint, nicht davor. Die Erzählung kann einer Aktion um etwa 0,3 s voraus sein. - Segmente dürfen das Video nicht überschreiten; das letzte Segment sollte ≥ 1 s vor Videoende enden.
Schreiben fürs Hören
- Konversationell, zweite Person („Sie“), Kontraktionen, aktive Verben. Eine Idee pro Segment.
- Beschreibe den Nutzen dessen, was passiert, nicht die Pixel. Niemals „Hier sehen wir …“ / „Wie Sie sehen …“.
- Schreibe Dinge so, wie sie gesprochen werden sollen: „zwei-x schneller“, „A-P-I“ nur, wenn es buchstabiert werden soll, „Punkt-Com“. Vermeide Symbole, Emojis, URLs mit Schrägstrichen und Klammern.
- Kurze Sätze. Beende mit einem klaren CTA, falls der Benutzer einen angegeben hat.
SFX (whoosh, whoosh_soft, pop, click, ding) — at ist die absolute Videozeit.
whooshbei Seiten-/Bildschirmübergängen (verwendescene_changes),whoosh_softfür ein-/ausblendende Panels/Modale,popfür erscheinende Elemente/Toasts,clickfür wichtige Tastendrücke,dingfür Erfolg/Abschluss.- Zurückhaltung: max. ~1 Cue pro 4–6 s. Staple keine Cues innerhalb von 0,3 s. Standardpegel −9 dB unter der Stimme; setze
gain_db(z. B. −14) für subtile Effekte.
Stimmen (Kokoro): af_heart (warme US-amerikanische Frau, Standard), af_bella, am_michael / am_fenrir (US-Mann), bf_emma (britische Frau), bm_george (britischer Mann). Andere Stimmen werden bei erster Verwendung einmalig heruntergeladen.
3. ⛔ SKRIPT-FREIGABE — obligatorisch
Erzeuge keine Sprachausgabe, bis der Benutzer das Skript explizit freigegeben hat.
-
Präsentiere das Skript als Tabelle und stoppe:
# Zeit Wörter / Budget Erzählung SFX 1 0:00.4–0:04.6 11 / 10 ⚠ Lernen Sie Relay … — Markiere Segmente über dem Budget mit ⚠. Erwähne Stimme + gesamte Erzähldauer. Beende mit: „Genehmigen Sie dieses Skript, oder sagen Sie mir, was geändert werden soll.“
-
Beende deine Runde und warte. Stille, „sieht gut aus?“ oder die Zustimmung zu einem früheren Entwurf ist keine Zustimmung zu diesem.
-
Bei Bearbeitungen: aktualisiere
script.json, präsentiere die geänderten Zeilen erneut, warte erneut. -
Erst nach einem expliziten Ja („genehmigen“, „ja“, „los“, „raus damit“) für den aktuellen Text, stempel es:
"$PY" "$SKILL/scripts/generate_tts.py" "$WORK/script.json" --approveDer Stempel ist ein Digest des Erzählungstexts.
generate_tts.pyundrender_video.pyweigern sich, auf einem ungestempelten Skript zu laufen oder wenn sich nach dem Stempeln Text geändert hat – du musst zurück durch dieses Tor. Setzeapproved/approved_digestniemals von Hand. Änderungen an Timing (start/end) undsfxbenötigen keine erneute Freigabe.
4. SFX + Sprachausgabe generieren
"$PY" "$SKILL/scripts/generate_sfx.py" --out "$WORK/sfx"
"$PY" "$SKILL/scripts/generate_tts.py" "$WORK/script.json"
- TTS schreibt
$WORK/audio/seg_###.wav+tts.json. Engine: Kokoro, automatischer Fallback auf Piper (--engine piperzum Erzwingen). - Jeder Clip wird in seinen Slot eingepasst (bis zum Start des nächsten Segments); Überläufe werden schneller neu synthetisiert bis zu
--max-speed 1.25. - Wenn die Tabelle immer noch
ÜBERanzeigt, bevorzuge Verschieben vonstart/endoder späteren Segmenten (keine erneute Freigabe erforderlich). Wenn der Text kürzer werden muss, ist das eine Textänderung → zurück zum Tor. - Einzelne Segmente wiederholen:
--only 3 5. Andere Variation von SFX:--seed 7.
5. Rendern
"$PY" "$SKILL/scripts/render_video.py" "$WORK/script.json"
- Platziert Clips an ihrem
start, niemals überlappend; kleine Überläufe erhalten eine tonhöhenerhaltendeatempo-Stauchung (≤ 1,12×), der Rest verschiebt spätere Clips (als Drift ausgegeben). Hält das letzte Bild, wenn die Erzählung das Video überdauert. - Mischt Stimme + SFX, normalisiert die Lautstärke auf −16 LUFS, brennt Untertitel ein (mit Pillow gerenderte Karten + FFmpeg
overlay, daher kein libass nötig), schreibt$WORK/output_final.mp4undsubtitles.srt. - Optionale Hintergrundmusik (original, lokal synthetisiert, keine Lizenzierung):
"$PY" "$SKILL/scripts/generate_bgm.py" --duration <Videosekunden> --out "$WORK/bgm.wav"(Stile:positive(Standard) = akustische Gitarre mit Sechzehntel-Anschlag und klingenden leeren Saiten, warmer Akkordschlag auf jedem Schlag, Vier-Viertel-Kick, synkopierte Rim/Claps, Off-Beat-Bass, weiche Pluck-Leadstimme, 111 BPM, Pause in der Mitte, modelliert nach einer B2B-Demo-Referenz;demo-bright/demo-dorian= SaaS-Demo-Groove modelliert nach typischen Produkt-Demo-Tracks: 110 BPM, warme Akkorde, die auf Achteln pulsieren und mit einem weichen Kick pumpen, Claps auf 2 und 4, Achtel-Hi-Hats, Bass auf Akkordgrundtönen, eine gehaltene Oberstimme, eine leichte gezupfte Melodie, Intro → Groove → 8-taktige Pause in der Mitte → Groove → sauberes Ende;uke,marimba,pluck,kalimba= helle Software-Demo-Betten, ein gezupftes/Mallet-Motiv über einem einfachen weichen Kick + Snap/Clap + Shaker-Beat und etwas Bass, 100–112 BPM, Dur-Tonart;lofi(Standard) = entspannter Swing-Beat mit Drums;keys= E-Piano;upbeat= Vier-Viertel + Arpeggio;ambient= nur Pad.--bpm,--key(helle Stile),--mood(andere),--seed Nfür eine Variation). Erstelle 30–40 s Vorschauen mit--duration 40und lass den Benutzer nach Gehör auswählen, bevor du alles renderst, rendere dann mit--bgm "$WORK/bgm.wav".--bgmakzeptiert auch einen vom Benutzer bereitgestellten Track (mp3/m4a/wav): Er wird automatisch auf denselben Referenzpegel eingestellt, mit einem 2,5-s-Crossfade geloopt, wenn er kürzer als das Video ist, und am Ende ausgeblendet. Frage den Benutzer, ob er die Rechte an jedem von ihm bereitgestellten Track bestätigt. Musik duckt automatisch unter der Stimme; verstellbar mit--bgm-db(Standard −2,5) und--duck-db(Standard −5). - Nützliche Flags:
--out <pfad>,--orig-volume 0.15(Originalton leise behalten),--sfx-gain-db -12,--no-subs(schreibt trotzdemsubtitles.srt; verwende, wenn das Video bereits Bildschirmuntertitel unten hat),--font <ttf>,--font-scale 0.05,--crf 20.
6. Vor dem Melden prüfen
- Überprüfe die Render-Ausgabe: Drift-Spalte ~0, keine Hold-Frame-Warnung (oder erklären).
- Stichprobenartige Untertitelkontrolle:
ffmpeg -ss <t> -i "$WORK/output_final.mp4" -frames:v 1 "$WORK/check_<t>.jpg"an 2–3 Segment-Mittelpunkten, dann Bilder ansehen – Untertitel lesbar, verdecken keine wichtige UI. Falls sie etwas Wichtiges verdecken, erwäge--font-scaleoder teile es dem Benutzer mit. - Bericht: Ausgabepfad, Dauer, verwendete Engine/Stimme, Segmente, die beschleunigt oder verschoben wurden, und wie man anpassen kann (
script.jsonbearbeiten → Schritte 4–5 erneut ausführen; Textänderungen gehen erneut durch das Tor).
Fehlerbehebung
| Symptom | Lösung |
|---|---|
kokoro nicht verfügbar … versuche Fallback | Führe setup.sh erneut aus; überprüfe, ob Python 3.10–3.12 in .venv ist. Piper-Ausgabe ist in Ordnung, aber weniger natürlich. |
| Falsch ausgesprochenes Wort / Name | Schreibe phonetisch im text-Feld um (z. B. „Kubernetes“ → „kuu-ber-net-ees“), hole Freigabe ein, generiere das Segment mit --only neu. |
| Stimme wirkt gehetzt | Reduziere speed auf 0,95, vergrößere Segmentfenster oder kürze Text. |
| Untertitel zu klein/groß | --font-scale 0.035–0.06. |
| Falsche Farben / VFR-Stottern | Füge --fps 30 hinzu. |
| Video enthält Musik, die du behalten möchtest | --orig-volume 0.12–0.2. |
Alles läuft offline nach dem einmaligen Modell-Download. Lizenzen: Kokoro-82M Apache-2.0, Piper GPL-3.0 (piper-tts ≥1.3), Stimmen gemäß Modellkarte, FFmpeg LGPL/GPL.