Communitygithub.com

Demo-Narrator

Verwandle ein stummes Produkt-Demo oder eine Bildschirmaufnahme in ein erzähltes Video mit natürlicher Sprachausgabe, sauberen UI-Soundeffekten, optionaler Hintergrundmusik und Untertiteln – komplett lokal und kostenlos.

Was ist Demo-Narrator?

Demo-Narrator ist ein KI-Agenten-Skill, der aus einer stummen Bildschirmaufnahme ein professionelles, erzähltes Demo-Video erstellt. Der Workflow startet mit Frameextraktion und Szenenerkennung, gefolgt von einem KI-gestützten Skriptentwurf, der die Inhalte der Aufnahme beschreibt. Ein wichtiger Bestandteil ist der obligatorische **Skript-Gate**: Der Benutzer muss das Skript (Narration und Soundeffekte) explizit freigeben, bevor Sprachausgabe oder Effekte generiert werden. Der Skill unterstützt die Plattformen Claude Code, Cursor und Codex und läuft vollständig lokal mit FFmpeg, Kokoro-82M TTS (Fallback auf Piper) sowie numpy/scipy für Soundeffekte und Musik – es werden keine API-Keys oder kostenpflichtigen Dienste benötigt. Das Ergebnis ist eine `output_final.mp4` mit H.264/AAC, Loudness-Normalisierung auf −16 LUFS und eingebrannten Untertiteln sowie eine separate `subtitles.srt`-Datei. Der Skill bietet auch eine optionale Generierung von Hintergrundmusik in verschiedenen Stilen (z. B. positiv, Lofi, Ambient) und erlaubt die Einbindung eigener Musikstücke mit automatischer Ducking-Funktion.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/GarvitSolanki/audio-generator/tree/main/skills/demo-narrator

In Ihrer bevorzugten KI fragen

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

Dokumentation

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

  1. Falls $PY nicht 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ühre bash "$SKILL/setup.sh" aus (dauert ein paar Minuten; im Hintergrund ausführen).
  2. Wähle ein Arbeitsverzeichnis neben dem Video: WORK="<Video-Verzeichnis>/demo-narrator-work/<Video-Stammname>". Schreibe niemals in das Skill-Verzeichnis.
  3. 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-duration zum Überschreiben; verwende --interval 4 für lange Videos).
  • Überprüfe zuerst $WORK/sheets/*.jpg (jeweils mit Zeitstempeln versehen). Öffne einzelne $WORK/frames/*.jpg nur 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.5 Wö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 start an 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.

  • whoosh bei Seiten-/Bildschirmübergängen (verwende scene_changes), whoosh_soft für ein-/ausblendende Panels/Modale, pop für erscheinende Elemente/Toasts, click für wichtige Tastendrücke, ding fü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.

  1. Präsentiere das Skript als Tabelle und stoppe:

    #ZeitWörter / BudgetErzählungSFX
    10:00.4–0:04.611 / 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.“

  2. Beende deine Runde und warte. Stille, „sieht gut aus?“ oder die Zustimmung zu einem früheren Entwurf ist keine Zustimmung zu diesem.

  3. Bei Bearbeitungen: aktualisiere script.json, präsentiere die geänderten Zeilen erneut, warte erneut.

  4. 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" --approve
    

    Der Stempel ist ein Digest des Erzählungstexts. generate_tts.py und render_video.py weigern sich, auf einem ungestempelten Skript zu laufen oder wenn sich nach dem Stempeln Text geändert hat – du musst zurück durch dieses Tor. Setze approved/approved_digest niemals von Hand. Änderungen an Timing (start/end) und sfx benö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 piper zum 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 ÜBER anzeigt, bevorzuge Verschieben von start/end oder 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öhenerhaltende atempo-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.mp4 und subtitles.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 N für eine Variation). Erstelle 30–40 s Vorschauen mit --duration 40 und lass den Benutzer nach Gehör auswählen, bevor du alles renderst, rendere dann mit --bgm "$WORK/bgm.wav". --bgm akzeptiert 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 trotzdem subtitles.srt; verwende, wenn das Video bereits Bildschirmuntertitel unten hat), --font <ttf>, --font-scale 0.05, --crf 20.

6. Vor dem Melden prüfen

  1. Überprüfe die Render-Ausgabe: Drift-Spalte ~0, keine Hold-Frame-Warnung (oder erklären).
  2. 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-scale oder teile es dem Benutzer mit.
  3. Bericht: Ausgabepfad, Dauer, verwendete Engine/Stimme, Segmente, die beschleunigt oder verschoben wurden, und wie man anpassen kann (script.json bearbeiten → Schritte 4–5 erneut ausführen; Textänderungen gehen erneut durch das Tor).

Fehlerbehebung

SymptomLösung
kokoro nicht verfügbar … versuche FallbackFü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 / NameSchreibe phonetisch im text-Feld um (z. B. „Kubernetes“ → „kuu-ber-net-ees“), hole Freigabe ein, generiere das Segment mit --only neu.
Stimme wirkt gehetztReduziere speed auf 0,95, vergrößere Segmentfenster oder kürze Text.
Untertitel zu klein/groß--font-scale 0.035–0.06.
Falsche Farben / VFR-StotternFü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.

Verwandte Skills