Demo-Voiceover

Demo-Voiceover Skill

Erzeuge und synchronisiere KI-Sprachaufnahmen für Demovideos.

Einordnung

Dies ist die dritte Stufe der Demo-Video-Pipeline:

/demo-script  →  /record-demo  →  /demo-voiceover
  (planen)        (aufnehmen)         (vertonen & ausliefern)

Kann auch eigenständig verwendet werden, um einem vorhandenen Video + Zeitstempel-Log eine Erzählung hinzuzufügen.

Eingaben

Der Skill benötigt:

1. Demo-Skript JSON — von /demo-script (workspace/<Datum>/demo-script-<Name>.json)
2. Rohvideodatei — von /record-demo (workspace/<Datum>/<Name>_raw.mp4)
3. Zeitstempel-Log — von /record-demo (workspace/<Datum>/<Name>_timestamps.json)

Format des Zeitstempel-Logs (erzeugt von /record-demo):

{
  "video_file": "demo_raw.mp4",
  "start_epoch": 1739545200.0,
  "steps": [
    {
      "scene_id": "intro",
      "step_index": 0,
      "action": "navigate",
      "narration": "Willkommen bei OneTest. Erstellen wir Ihren ersten Testfall.",
      "timestamp_sec": 0.0,
      "completed_sec": 1.2
    },
    {
      "scene_id": "navigate-to-test-cases",
      "step_index": 0,
      "action": "click",
      "narration": "Öffnen Sie den Bereich Testfälle über die Seitenleiste.",
      "timestamp_sec": 3.2,
      "completed_sec": 3.8
    }
  ]
}

Ablauf

Stufe 1: Erzählplanung

Bestimmen, wann jedes Erzählsegment relativ zum Video abgespielt werden soll:

Timing-Strategien:

Strategie	Wann die Erzählung beginnt	Am besten geeignet für
on_action	Zum Zeitpunkt des Aktionsbeginns (timestamp_sec)	Erklären, was gleich passiert
after_action	Nach Abschluss der Aktion (completed_sec)	Beschreiben, was gerade passiert ist
before_action	0,5 s vor Aktionsbeginn	Spannung aufbauen
fill_pause	Im Fenster pause_after_ms	Erzählen über die bewusste Pause

Standard: fill_pause — die Erzählung wird während der Pause nach jeder Aktion abgespielt, sodass der Betrachter die Aktion sieht und dann die Erklärung hört, während der Bildschirm ruhig bleibt. Das wirkt am natürlichsten.

Planungsausgabe:

{
  "segments": [
    {
      "index": 0,
      "text": "Willkommen bei OneTest. Erstellen wir Ihren ersten Testfall.",
      "video_start_sec": 1.2,
      "max_duration_sec": 2.0
    },
    {
      "index": 1,
      "text": "Öffnen Sie den Bereich Testfälle über die Seitenleiste.",
      "video_start_sec": 3.8,
      "max_duration_sec": 1.5
    }
  ]
}

Stufe 2: Audio-Erzeugung (ElevenLabs)

Erzeuge jedes Erzählsegment mit dem ElevenLabs with-timestamps-Endpunkt:

• Liefert zeichengenaue Ausrichtung (exakte Dauer in Millisekunden)
• Ermöglicht kostenlose Untertitel-Erstellung
• Unterstützt Kontinuitätsverkettung über previous_request_ids (max. 3)

Ausführen: python scripts/generate_narration.py --plan voiceover_plan.json --voice rachel --output-dir .

Einzelheiten zur API findest du in references/elevenlabs-api.md.

Stufe 3: Zeitabstimmung

Nach der Audio-Erzeugung die geplanten mit den tatsächlichen Dauern abgleichen:

1. Audio passt in das verfügbare Fenster → an geplantem Start platzieren
2. Audio kürzer → zusätzliche Stille ist in Ordnung (Demos atmen)
3. Audio länger → beschleunigen (max. 1,15× via atempo) oder Text kürzen und neu erzeugen

Beschleunigung auf maximal 1,15× begrenzen – darüber klingt es gehetzt.

Stufe 4: Audio-Zusammenstellung

Erzählsegmente mit Video mithilfe des Hilfsskripts zusammenführen:

bash scripts/merge_audio_video.sh demo_raw.mp4 narration_results.json final_demo.mp4

Das Skript erstellt einen ffmpeg filter_complex mit adelay pro Segment und atempo für Geschwindigkeitsanpassungen.

Stufe 5: Untertitel-Erstellung

Zeichengenaue Zeitstempel von ElevenLabs ermöglichen die kostenlose SRT-Erstellung:

• Zeichen zu Wörtern, Wörter zu Untertitelzeilen gruppieren (max. 8 Wörter)
• Um video_start_sec jedes Segments verschieben
• Als Standard-SRT-Format ausgeben

Untertitel in Video einbrennen:

ffmpeg -i final_demo.mp4 -vf subtitles=demo.srt \
    -c:v libx264 -crf 18 -c:a copy \
    final_demo_subtitled.mp4

Sprachkonfiguration

Wähle die Stimme je nach Zielgruppe. Verwende eleven_turbo_v2 für Entwürfe und eleven_multilingual_v2 für die Endversion.

Details zu Stimmen-IDs, Einstellungen, Modellvergleich und Kontinuitätsverkettung findest du in references/elevenlabs-api.md.

Anpassung des Tempos

Problem	Lösung	Grenze
Audio etwas zu lang	Mit atempo-Filter beschleunigen	Max. 1,15×
Audio viel zu lang	Erzähltext kürzen, neu erzeugen	Nur Segment neu erzeugen
Audio zu kurz	Stille auffüllen (natürlich)	Stille in Demos ist in Ordnung
Unangenehme Lücke zwischen Segmenten	Pause verlängern oder Übergangsphrase einfügen	Pausen unter 3 s halten

Ausgabedateien

Datei	Beschreibung
<Name>_final.mp4	Video + Erzählung zusammengeführt
<Name>_final_subtitled.mp4	Video + Erzählung + eingebrannte Untertitel
<Name>.srt	Untertiteldatei (separat)
<Name>_narration_full.mp3	Komplette Erzähl-Audiospur (zur Wiederverwendung)
narration_NNN.mp3	Einzelne Segmente (zur Neuerzeugung)
<Name>_voiceover_plan.json	Zeitplan (zum Debuggen/Iterieren)

Alle gespeichert unter workspace/<Datum>/

Iterations-Workflow

Der Skill unterstützt die Wiederholung einzelner Segmente, ohne alles neu erzeugen zu müssen:

1. Benutzer sieht sich das Video an: „Die Erzählung in Szene 3 ist zu schnell“
2. Agent passt an: Text kürzen, nur Segment 3 neu erzeugen
3. previous_request_ids der Segmente 1–2 für Kontinuität verwenden
4. Mit ffmpeg neu zusammenführen (nur Audiospur ändert sich, Video bleibt)

Das ist schnell, weil:

• Das Video nicht neu aufgenommen werden muss
• Nur ein ElevenLabs-API-Aufruf pro geändertem Segment nötig ist
• ffmpeg-Zusammenführung Sekunden dauert