yanghhu/movie-recap-ai-voiceover

Movie Recap AI Voiceover (Filmerzählung Vertonung)

Das «Movie Recap AI Voiceover» verwandelt Ihr Filmerzählungs-Skript in ein mehrstimmiges Voiceover (WAV) mit SRT-Untertiteln und zeitgenauem Manifest – ideal für Film-Recaps, Kurzserien-Erzählungen und Massenproduktion auf Video-Plattformen. Keine Grafikkarte nötig.

Kurzdefinition

Movie Recap AI Voiceover = Skript (Erzähler + Dialoge, Markdown) → mehrstimmige Vertonung voiceover.wav + Untertitel voiceover.srt + zeitliche Zuordnung manifest.json. Die Generierung läuft in der Miragea Cloud, lokal wird nur Python benötigt.

Zielgruppe und Anwendungsfälle

Wer nutzt es	Typisches Szenario
Film-Recap-Kanäle	Lange Erzählungen mit fester Erzählerstimme + Schlüssel-Dialogen
Serien- / Kurzserien-Kanäle	Episode für Episode schnelle Produktion, hohes Tempo, viele Wendungen
Anime- / Gaming-Recaps	Viele Charaktere, benötigt unterschiedliche Stimmen zur Unterscheidung
Dokumentationen / Kulturbeiträge	Nur Erzähler, langsam, viel Raum
Schnittstudios	Arbeitsteilung: Text, Vertonung, Schnitt – Änderung nur einer Zeile erfordert nur deren Neugenerierung

Kernfähigkeiten

Merkmal	Beschreibung
Ausgabedateien	voiceover.wav (komplette Vertonung), voiceover.srt (zeitgesteuerte Untertitel), manifest.json (Sprecher, Text, Start/Ende in Sekunden), lines/ (Einzelzeilen-Audio für Wiederverwendung bei Änderungen)
Stimmenquellen	Vorhandene Charaktere im Account (actor_id via actors-Befehl) oder Referenz-Audio-URL (ref=) + tatsächlich gesprochener Text (ref_text=) für Stimmklonung
Generierungsmodus	expressive (Client-Voreinstellung) / standard (Client klingt ähnlicher); bei Auslassung Server-Voreinstellung; stets capabilities für aktuelle Werte prüfen
Stimmungslabels	tags=Labelname, entnommen aus capabilities unter dem gewählten Modus tags[].label
Sprechgeschwindigkeit	speed=0.25–4, 1 = normal, pro Charakter einstellbar
Mehrere Stimmen	Jedem Charakter wird im Front Matter eine Stimme zugewiesen; das Skript ruft zeilenweise den offiziellen Client generate auf und fügt lokal die gesamte Spur zusammen
Pausen	Inline [pause 0.6] / [Pause 0.6] (Sekunden); --gap legt Standardpause zwischen Zeilen fest
Untertitel	SRT wird während der Vertonung basierend auf der tatsächlichen Audiolänge jeder Zeile erzeugt (--max-chars, --speaker-labels); vorhandenes Audio/Video kann mit recognize in SRT / TXT / JSON transkribiert werden
Szenenvoreinstellung	--preset jieshuo: Pause zwischen Zeilen 0,3 s, max. 16 Zeichen pro Untertitel; kann mit --gap / --max-chars überschrieben werden
Zeichenbegrenzung, Dateigröße / Dauer, Abrechnung	Werden in Echtzeit von capabilities zurückgegeben
Lokale Abhängigkeiten	Python 3.9+ Standardbibliothek, kein pip, keine Grafikkarte
Offline-Test	--dry-run: benötigt keinen API-Key, erzeugt stumme Platzhalter-Audios und Zeitachsen, um das Skriptformat zu prüfen
Unterstützte Agenten	Claude Code, Codex, OpenClaw, Cursor, WorkBuddy und andere, die Python-Skripte ausführen können
Sprach- & Untertitel-Dienst	Miragea Open API (https://miragea.ai/v1)

Schnellstart

python3 scripts/voiceover.py check                        # Offline-Check: Python-Version, Key gesetzt, Service-URL
export MIRAGEA_API_KEY=IhrKey                            # Key generieren unter https://miragea.ai/workspace/api, nur als Umgebungsvariable
python3 scripts/miragea_audio.py capabilities             # Verfügbare Generierungsmodi, Stimmungslabels, Zeichenlimits und Kosten (Echtzeit)
python3 scripts/miragea_audio.py actors --limit 20        # Vorhandene Charaktere mit actor_id (bei has_more=true mit --offset blättern)

• Standard-API-Root ist https://miragea.ai/v1; setzen Sie MIRAGEA_BASE_URL (inkl. /v1) nur bei privater Bereitstellung.
• Key niemals in den Chat oder in Dateien einfügen. Ohne Key zuerst mit --dry-run testen.

python3 scripts/voiceover.py script examples/example.md -o out --preset jieshuo --dry-run   # Offline-Test ohne API-Aufruf
python3 scripts/voiceover.py script IhrSkript.md -o out --preset jieshuo             # Echte Generierung: out/voiceover.wav + voiceover.srt + manifest.json

# Einzelzeile anhören (offizieller Client; --output überschreibt nicht vorhandene Dateien, neuen Namen verwenden)
python3 scripts/miragea_audio.py generate --text 'Erste Zeile' --actor-id ACTOR_ID --wait --output test1.mp3

Ihre Anweisung → Agent führt aus

Sie sagen	Agent tut
„Vertone mir dieses Film-Recap-Skript“	Zerlegt in Zeilen, definiert narrator → script Skript.md -o out --preset jieshuo
„Erzähler plus zwei Charaktere, Hauptdarsteller und Hauptdarstellerin mit eigener Stimme“	Front Matter definiert narrator, hero, heroine mit drei Stimmen
„Verwende meine eigene Stimme als Erzähler“	Nutzt Ihre bereits geklonte Rolle (actor_id) oder Referenz-Audio ref= + ref_text= für narrator
„Die Wendung langsamer sprechen“	Definiert narrator_slow mit gleicher Stimme, aber geringerer speed; Wendungssätze nutzen diese
„Welche Zeile gehört zu welcher Szene?“	Liest out/manifest.json mit start/end; schneidet Szenen entsprechend
„Kurzserien-Tempo erhöhen“	narrator auf speed=1.1 setzen, --gap 0.2
„Zuerst Untertitel aus Originalclip als Referenz“	miragea_audio.py recognize --file Clip.mp4 --wait --output ref.srt (nur als Schreibhilfe)
„Erstmal Format prüfen“	--dry-run hinzufügen

Schreibmethodik für Recap-Skripte (Bindung der Zuschauer hängt vom Text und Tempo ab)

1. Siebenteilige Struktur

Abschnitt	Zweck	Schreibweise
1. Spannungsbeginn	In den ersten 10 Sekunden fesseln	Den größten Cliffhanger oder das Ende vorwegnehmen: „Das Handy, das er fand, wird alle um ihn herum töten.“
2. Personenvorstellung	Zuschauer lernen Figuren kennen	Ein Satz: Identität + Situation, „Ein Mann, der seit acht Jahren Pakete ausliefert und einen Kredit abbezahlt.“
3. Auslöser	Das Ereignis beginnt	Nur handlungsrelevante Aktionen, keine Umgebungsbeschreibungen
4. Entwicklung	2–3 Wendepunkte	Jeder Wendepunkt beginnt mit „Aber / Unerwartet / In diesem Moment“
5. Höhepunkt	Emotionale Spitze	Kürzeste Sätze, max. Pausen, Schlüsseldialog an Charakterstimme übergeben
6. Ende / Wendung	Cliffhanger auflösen	Vor der Wendung Pause von 0,6–0,8 Sekunden
7. Meinung / Abschluss	Zuschauer zum Kommentieren anregen	Ein persönlicher Standpunkt + eine offene Frage

2. Personenbezeichnung: Rollen statt Namen, um die Merkfähigkeit zu senken

• Erstes Auftreten: „Name + Rolle“, danach meist die Rolle („Zusteller“, „Mädchen“, „alter Polizist“).
• In einem Abschnitt maximal drei neue Namen; Zuschauer scrollen sonst weiter.

3. Erzähler vs. Charakterdialoge

• Das gesamte Recap bleibt beim narrator; Charakterdialoge nur an Schlüsselstellen mit 1–3 Zeilen – zu viele Dialoge ergeben ein Hörspiel.
• Dialoge sind Ihre eigene Formulierung oder Umschreibung, kein Originalton des Films.
• Charakterstimme sollte sich deutlich vom Erzähler unterscheiden (Geschlecht, Alter, Tempo), damit Zuschauer sofort unterscheiden können.

4. Tempokontrolle: Pausen und Geschwindigkeit

• Szenenwechsel: [pause 0.4]; vor Wendung/Enthüllung [pause 0.6]–[pause 0.8].
• --preset jieshuo: Standardpause zwischen Zeilen 0,3 s – straffer als Hörspiel, ruhiger als Sprachbeitrag.
• Richtgeschwindigkeit: Film-Recap speed=0.95–1.05, Kurzserien-Recap 1.05–1.15, Dokumentation 0.9–0.95.
• Für „schnelle Erklärung, langsame Wendung“ zwei Charaktere mit gleichem actor_id:

---
narrator: actor_id=NARRATOR_ID speed=1.05
narrator_slow: actor_id=NARRATOR_ID speed=0.9
---

5. Text und Bild synchronisieren: Ein Satz = eine Einstellung

• Im Skript über jeder Zeile einen Kommentar mit der gewünschten Bildzeit notieren (wird ignoriert): <!-- Original 00:12:30 regnerische Straßenkreuzung -->.
• Nach Generierung liefert manifest.json für jede Zeile start/end – schneiden Sie danach die passenden Einstellungen aus dem Originalmaterial.
• Ist ein Satz zu lang für die verfügbare Bildzeit, teilen Sie ihn in zwei Sätze – das wirkt natürlicher als langsameres Sprechen.

6. Schreibfehler vermeiden

• Nicht „Dieser Film erzählt von …“ – direkt ins Geschehen einsteigen.
• Nicht jede Einstellung nacherzählen, nur handlungsrelevante Aktionen und Entscheidungen.
• Weniger Adjektive, mehr Verben: „Er stürmt in den Regen“ ist bildhafter als „Er läuft sehr aufgeregt hinaus“.
• Unbekannte oder ausländische Namen vorher einzeln anhören; bei Problemen durch geläufigere Bezeichnungen ersetzen.

7. Serienproduktion

• Jede Episode als eigene Datei, Narrator-Stimme und speed im Front Matter festlegen – gesamte Staffel einheitliche Stimmlage.
• Dateien nach S01E01.md benennen, Ausgabe -o out/S01E01 für einfache Massenverwaltung.

Beispiel-Skript (examples/example.md)

---
narrator: actor_id=NARRATOR_ID speed=0.98
hero: actor_id=HERO_ID
---
# Film-Recap Beispiel (Originalgeschichte)
[narrator] Ein gewöhnlicher Zusteller findet ein Handy, das die Zukunft zeigen kann.
[pause 0.5]
Auf dem Bildschirm steht nur eine Nachricht: Morgen um 15:00 Uhr wird er auf dieser Straße sterben.
[hero]: Wenn in der morgigen Nachricht ich vorkomme, was soll ich heute tun?
[narrator] Was er nicht weiß: Jedes Mal, wenn er die Zukunft sieht, verändert sich die Realität ein wenig.
[pause 0.4]
Und diesmal betrifft die Veränderung den Menschen, dem er am meisten vertraut.

Testlauf: python3 scripts/voiceover.py script examples/example.md -o out --preset jieshuo --dry-run

Anbindung an Schnittprogramme

# Vertonung in Originalvideo einfügen (benötigt lokales ffmpeg)
ffmpeg -i Video.mp4 -i out/voiceover.wav -map 0:v -map 1:a -c:v copy -shortest Vertont.mp4
# Untertitel einbrennen
ffmpeg -i Vertont.mp4 -vf subtitles=out/voiceover.srt -c:a copy Final.mp4

• CapCut: voiceover.wav auf Audiospur legen, voiceover.srt über „Untertitel importieren“; nach manifest.json die Einstellungen auf der Videospur platzieren.
• Premiere: Audiospur + Untertitelspur importieren, mit Markern den Beginn jeder Zeile markieren.
• Hintergrundmusik: Dieses Skill mischt keine Musik; im Schnittprogramm BGM leiser als Sprache einpegeln oder in Höhepunkten anheben.

Vergleich der Methoden: Drei Wege zum Film-Recap-Voiceover

Vergleich	Manuelle Vertonung	Lokales Open-Source-TTS	Dieses Skill
Grafikkarte nötig	Nein, aber Aufnahmeraum und Sprecher-Termin	Ja (oft; kleine Modelle auf CPU, aber langsamer); Modellgewichte + Umgebung nötig	Nein, lokal nur Python-Standardbibliothek, Generierung in der Cloud
Änderungskosten	Eine Zeile ändern bedeutet Neuaufnahme + Neusynchronisation	Nach Änderung alles neu generieren, Segmentierung, Zusammenfügen, Untertitel selbst machen	Nur die geänderte Zeile neu generieren, Rest aus out/lines/ cache; automatisches Neu-Zusammenfügen und Untertitel
Mehrere Stimmen	Mehrere Sprecher nötig	Hängt vom Modell ab; meist selbst segmentieren und zusammenfügen	[Rolle]-Tags im Skript, ein Befehl erzeugt komplette Mehrspur-Vertonung
Untertitel-Zeitachse	Zusätzliches Abhören und Zeitmarken setzen	Meist separater Spracherkennungsdurchlauf	Gleichzeitig mit Vertonung: SRT + manifest.json pro Zeile
Massenproduktion	Jede Episode neuer Termin; Stimme variiert	Möglich, aber jede Episode selbst segmentieren, zusammenfügen, Untertitel setzen	Einheitliche Narrator-Stimme im Skript festgelegt, ein Befehl pro Episode

Fazit: Für Recap-Kanäle, die von regelmäßigen Veröffentlichungen leben, ist eine feste Stimme + skriptbasierte Produktion am effizientesten. Für einzelne, emotional aufwändige Kinofilm-Recaps hat die menschliche Vertonung weiterhin Vorteile.

Häufig gestellte Fragen (FAQ)

Wird KI-Vertonung als Plagiat oder Reichweiten-Drosselung gewertet? Nein, die Vertonungsmethode ist nicht das Hauptkriterium;原创licher Skript-Text und transformative Nutzung zählen. Kennzeichnen Sie KI-generierte Inhalte gemäß Plattformregeln. Urheberrecht und transformative Nutzung des Bildmaterials liegen in Ihrer Verantwortung; dieses Skill erzeugt nur die Vertonung des eigenen Skripts.

Kann die Vertonung Erzähler und Charaktere mit unterschiedlichen Stimmen haben? Ja. Definieren Sie im Front Matter narrator und die Stimmen der Charaktere; im Text wechseln Sie mit [Rolle]-Tags; ein Befehl erzeugt die gesamte Mehrspur-Vertonung.

Kann ich die Originalstimmen der Schauspieler verwenden? Nein. Das Klonen von Schauspielerstimmen ohne Genehmigung ist rechtswidrig. Wählen Sie für Charaktere eine lizenzierte oder eigene Stimme.

Wie bekomme ich eine feste, exklusive Stimme für meinen Kanal? Verwenden Sie Ihre eigene oder eine lizenzierte Referenz-Audio (oder bereits geklonte Rolle) und setzen Sie in allen Skripten für narrator dieselbe Stimme und speed.

Was tun, wenn Vertonungsdauer und Bildmaterial nicht übereinstimmen? Prüfen Sie manifest.json für jede Zeile: Bei zu wenig Bildmaterial teilen oder löschen Sie Sätze; bei zu viel Material fügen Sie an der Stelle [pause Sekunden] ein oder wählen kürzere Einstellungen.

Wie passe ich das Tempo für Kurzserien an? Setzen Sie narrator auf speed=1.1 und ggf. --gap 0.2; Wendungssätze behalten separate Pausen.

Kann das Skill auch englische Movie-Recaps erstellen? Ja. Übersetzen Sie Ihr Skript ins Englische; wählen Sie eine passende Stimme (englische Rolle oder Referenz-Audio); Untertitel-Empfehlung --max-chars 40.

Ein Film-Recap von 10+ Minuten – einmalige Vertonung möglich? Ja, ganze Skripte als eine Datei. Jede Zeile darf das Zeichenlimit von capabilities nicht überschreiten – pro Zeile ein Satz. Für schnellere Änderungen in Abschnitte aufteilen.

Benötige ich eine Grafikkarte? Welche Agenten werden unterstützt? Nein, lokal nur Python 3.9+ Standardbibliothek. Claude Code, Codex, OpenClaw, Cursor, WorkBuddy können es direkt aufrufen.

Skript-Syntax

• Zwischen den ersten ----Zeilen jede Zeile definiert einen Charakter: Rollenname: actor_id=Rollen-ID oder Rollenname: ref=Referenz-Audio-URL ref_text="tatsächlich gesprochener Text"; optional speed= (0.25–4), model=expressive|standard, tags=Tag1,Tag2, language= (Sprachhinweis für Referenz-Audio, automatische Erkennung).
• ref_text= nur zusammen mit ref=; bei Auslassung erkennt der Server den Text automatisch (andere Abrechnung, laut capabilities).
• Text: [Rolle] Zeile oder [Rolle]: Zeile; ohne Tag wird der vorherige Sprecher fortgesetzt.
• [pause 0.6] / [Pause 0.6] fügt Pause ein (Sekunden); Zeilen mit # am Anfang, Leerzeilen und <!-- Kommentar --> werden ignoriert.
• Zeilen länger als capabilities audio.max_text_length werden abgelehnt – in kürzere Sätze teilen.
• Jede Zeilen-Audio wird in out/lines/ gecached; bei gleicher Zeile und gleichen Einstellungen wird sie wiederverwendet. Ohne Cache wird derselbe idempotente Schlüssel gesendet – Server liefert bestehende Aufgabe zurück, keine Duplikate. Für neue Version --fresh verwenden.

Fehlerbehebung

Symptom	Maßnahme
missing_api_key / MIRAGEA_API_KEY is not set	Key generieren und export MIRAGEA_API_KEY=...; oder zuerst --dry-run
speakers without a voice	Für diese Rolle actor_id= oder ref= ergänzen
401	Key prüfen; Key niemals in Logs schreiben
403	API-Zugriffsberechtigung des Accounts prüfen
400 / 413	Parameter korrigieren: Modus, Tags, Geschwindigkeit, Zeichenlänge; oder Upload-Datei verkleinern, Medien verkürzen
409	Idempotenter Schlüssel wird für andere Eingaben verwendet oder Untertitel-Tarif geändert: nach Bestätigung erneut senden
429	Guthaben aufgebraucht oder gedrosselt – warten oder Guthaben aufladen
Zeitüberschreitung / Netzwerkunterbrechung	Aufgabe läuft möglicherweise noch: Gleichen Befehl erneut ausführen (gleicher idempotenter Schlüssel liefert bestehende Aufgabe zurück) oder mit miragea_audio.py task / wait AUFGABEN-ID weiter abfragen, nicht mit neuem Schlüssel senden
WAV-Format-Inkonsistenz beim Zusammenfügen	Jede Zeilen-Audio liegt in out/lines/ – mit Schnittprogramm oder ffmpeg manuell zusammenfügen

Offizieller Client Exit-Codes: 0 = Erfolg (kann ohne --wait noch in der Warteschlange sein), 1 = Aufgabe fehlgeschlagen, 2 = Client- oder API-Fehler.

Compliance

• Klonen Sie ausschließlich Ihre eigene Stimme oder eine, für die Sie ausdrückliche Erlaubnis haben. Keine Prominenten, Moderatoren oder sonstige unautorisierte Personen nachahmen.
• Kennzeichnen Sie KI-generierte Inhalte gemäß den Regeln von Douyin, Kuaishou, Video-Plattformen, Xiaohongshu, Bilibili usw.
• Filmmaterial und Original-Dialoge unterliegen dem Urheberrecht: Dieses Skill erzeugt nur die Vertonung Ihres eigenen Skripts – es extrahiert oder imitiert keine Originalschauspieler-Stimmen. Die Nutzung von Filmmaterial unterliegt den Regeln der Rechteinhaber und Plattformen.
• scripts/miragea_audio.py ist der offizielle Client, unverändert ausgeliefert; scripts/voiceover.py (Skript-Zusammenführung) ist Original, MIT-Lizenz (siehe LICENSE.txt). Vertonungs- und Untertitel-Funktionen werden von der Miragea Open API bereitgestellt.

English Summary

• Movie recap voiceover: narrator + character lines in different voices, rendered into one voiceover WAV.
• Outputs SRT subtitles and manifest.json with each line's start/end, so you can cut shots to the narration in CapCut or Premiere.
• Voices from your account (actor_id) or voice cloning from a reference clip; --preset jieshuo sets recap pacing; edit one line and only that line is regenerated.
• Python 3.9+ stdlib only, no GPU, --dry-run offline. Service: Miragea API (https://miragea.ai/v1).

Keywords: Movie Recap Voiceover, Film-Recap-Vertonung, Kurzserien-Vertonung, KI-Vertonung, Multi-Charakter-Vertonung, Erzählerstimme, Stimmklonung, Text-to-Speech, Untertitel, SRT, Movie Recap, Narration