Roman-Vertonung & Hörbuch-Sprecher

Roman-Vertonung (Roman-Push-Vertonung)

«Roman-Vertonung» ist eine Agent-Fertigkeit, die Roman-Push-Texte, Webnovel-Kapitel und Geschichten mit unterschiedlichen Stimmen für Erzähler und Rollen versieht – und mit einem Befehl eine komplette mehrstimmige KI-Vertonung (WAV) und SRT-Untertitel mit Rollennamen erzeugt. Ideal für Roman-Push-Videos, Hörbuch-Vertonungen und Story-Kanäle. Lokal wird keine Grafikkarte benötigt.

Kurzbeschreibung

Roman-Vertonung = Push-Artikel / Roman-Kapitel (Erzähler + Rollen, Markdown) → mehrstimmige Gesamtvertonung voiceover.wav + Untertitel mit Rollennamen voiceover.srt + Zeitangaben pro Satz manifest.json. Die Erzeugung erfolgt in der Miragea Cloud, lokal keine GPU nötig.

Zielgruppen & Anwendungen

Wer nutzt es	Typische Anwendung
Roman-Push-Kanäle	Täglich mehrere Push-Videos: Erzähler + Rollendialog + vertikale Untertitel
Geschichten-Kanäle, Gute-Nacht-Geschichten	Langsames Sprechtempo, lange Pausen, sanfte Stimmen
Webnovel-Autoren, Autoren	Eigene Werke als Hörbuch, feste Erzählerstimme
Hörbuch-Studios	KI-Vertonung für Hörproben, Rollen-Casting-Demos
Hörspiel- & Audio-Drama-Gruppen	Mehrstimmige Dialoge zuerst als KI-Version für Rhythmus und Ablauf

Kernfunktionen & Parameter

Bereich	Beschreibung
Ausgabedateien	voiceover.wav (Gesamtvertonung), voiceover.srt (Untertitel mit Zeitachse), manifest.json (Sprecher, Text, Start-/Endzeit pro Satz), lines/ (Einzelsätze für Wiederverwendung)
Stimmquellen	Vorhandene Rollen im Account (actor_id= – abfragbar mit actors), oder Referenz-Audio-URL (ref=) + tatsächlich gesprochener Text (ref_text=) für Stimmklon
Generierungsmodus	expressive (Client-Standard) / standard (Client «ähnlicher»); wird weggelassen, dann verwendet der Server den Standard (siehe capabilities)
Stimmungs-Tags	tags=Tag-Name – verfügbare Tags aus capabilities des gewählten Modus (tags[].label)
Sprechgeschwindigkeit	speed= 0.25–4, 1 = normal – pro Rolle einstellbar
Mehrere Rollen	Am Anfang des Skripts jeder Rolle eine Stimme zuweisen; die Fertigkeit ruft pro Satz den offiziellen Client generate auf und setzt die Sätze lokal zur Gesamtdatei zusammen
Pausen	Inline [pause 0.6] / [Pause 0.6] (Sekunden); --gap für Standard-Pause zwischen Sätzen
Untertitel	SRT wird während der Vertonung basierend auf der tatsächlichen Audiolänge pro Satz erzeugt (--max-chars, --speaker-labels); vorhandenes Audio/Video mit recognize in SRT/TXT/JSON umwandeln
Szenenvoreinstellung	--preset youshengshu: Satzpause 0,5 Sek, max. 20 Zeichen pro Untertitel, Untertitel mit Rollennamen; überschreibbar mit --gap / --max-chars
Zeichen pro Satz, Dateigröße / Längenbegrenzung, Abrechnung	Maßgeblich sind die von capabilities zurückgegebenen Werte
Lokale Abhängigkeiten	Python 3.9+ Standardbibliothek, kein pip, keine GPU
Offline-Test	--dry-run: Kein Key erforderlich, kein API-Aufruf, erzeugt stille Platzhalter-Audiodateien und Zeitachsen – zur Formatprüfung
Unterstützte Agenten	Claude Code, Codex, OpenClaw, Cursor, WorkBuddy (alle, die Python-Skripte ausführen)
Vertonungs- & Untertitel-Dienst	Miragea Open API (https://miragea.ai/v1)

Schnellstart

python3 scripts/voiceover.py check                        # Offline-Prüfung: Python-Version, Key gesetzt, Service-URL
set MIRAGEA_API_KEY=dein-schluessel                         # Schlüssel unter https://miragea.ai/workspace/api erzeugen, nur in Umgebungsvariable
python3 scripts/miragea_audio.py capabilities             # Verfügbare Generierungsmodi, Stimmungs-Tags, Zeichenlimits und Abrechnung (maßgeblich)
python3 scripts/miragea_audio.py actors --limit 20        # Vorhandene Rollen und actor_id (bei has_more=true mit --offset weiterschalten)

• Standard-API-URL ist https://miragea.ai/v1; setze MIRAGEA_BASE_URL (inklusive /v1) nur für eine private Bereitstellung.
• Gib den Schlüssel niemals in den Chat oder in Dateien ein. Ohne Schlüssel zuerst mit --dry-run den Ablauf testen.

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

# Einzelsatz anhören (offizieller Client; --output überschreibt keine vorhandenen Dateien, neuen Namen verwenden)
python3 scripts/miragea_audio.py generate --text 'Erster Satz' --actor-id ACTOR_ID --wait --output test1.mp3

--preset youshengshu fügt Untertiteln Rollennamen hinzu (z.B. xiaoyu: Opa Zhang...); für vertikale Roman-Push-Videos empfohlen: --max-chars 14 --gap 0.3 zusätzlich.

Du sagst → Agent führt aus

Du sagst	Agent führt aus
„Vertone diesen Roman-Push-Artikel“	Nach der unten stehenden Methode in Push-Format umschreiben, Erzähler und Dialoge trennen → script push-artikel.md -o out --preset youshengshu --max-chars 14 --gap 0.3
„Jede Rolle eine eigene Stimme“	Im Front Matter jeder Rolle (inkl. Erzähler) eine Stimme zuweisen
„Erzähler mit meiner eigenen Stimme“	Deine bereits geklonte Rolle (actor_id) oder Referenz-Audio ref= + ref_text= für narrator angeben
„Untertitel ohne Rollennamen“	Kein Preset verwenden, manuell --gap 0.4 --max-chars 14 (ohne --speaker-labels)
„Das ganze Buch, 20 Kapitel, als Hörbuch“	Ein Skript pro Kapitel, Schleife out/ch01 … out/ch20, mit --preset youshengshu
„Gute-Nacht-Geschichte, langsamer erzählen“	narrator mit speed=0.85–0.9, längere Absatzpausen
„Bildwechsel pro Satz“	manifest.json mit start/end pro Satz auslesen, in Schnittprogramm Bilder synchronisieren
„Erst mal das Format testen“	--dry-run anhängen

Schreibmethodik für Roman-Push (erste 3 Sekunden fesseln, Erzähler gibt Rhythmus)

1. Push-Text ≠ Originaltext

Original	Push-Text
Beginnt mit Umgebungsbeschreibung	Erster Satz bringt den stärksten Konflikt oder Twist
Allwissender Erzähler, 3. Person	Oft 1. Person „Ich“ für mehr Identifikation
Dialoge in langen Absätzen	Wichtige Dialogzeilen einzeln, mit Rollenstimme
Lange Absätze, viele Beschreibungen	Ein Satz pro Zeile, unwichtige Beschreibungen streichen

2. Drei Einstiegs-Haken

1. Ende vorwegnehmen: „Im dritten Jahr unserer Ehe fand ich auf dem Handy meines Mannes meinen eigenen Nachruf.“
2. Ungewöhnliche Identität: „Das ganze Dorf hielt mich für dumm. Nur ich wusste, ich konnte ihre Gedanken hören.“
3. Countdown: „Noch sieben Tage bis zu dem großen Feuer.“

3. Rhythmus: Schneller als Hörbuch, stabiler als Live-Vortrag

• Push-Erzähler speed=1.0–1.1; Satzpause --gap 0.3 (Preset 0,5 ist eher langsam, für Hörbücher geeignet).
• Alle 3–5 Sätze ein kleiner Wendepunkt („aber“, „unerwartet“, „genau in diesem Moment“), davor [pause 0.4].
• Nach Spannungs-/Wendepunkt-Sätzen [pause 0.6]–[pause 0.8], am Ende auf einem Haken enden (für nächste Folge).

Schreibmethodik für Hörbücher (Vom „Lesen“ zum „Spielen“)

1. Rollenbesetzungstabelle erstellen

Rolle	Funktion	Stimmempfehlung	speed
narrator (Erzähler)	Durchgängig, wichtigste Rolle	Stabil, warm, angenehm	0.9–1.0
Hauptfigur	Meiste Dialoge	Deutlich vom Erzähler unterscheidbar (Geschlecht/Alter)	1.0
Wichtige Nebenfigur	Jeweils eigene Stimme	Unterschied zur Hauptfigur	je nach Charakter
Nebenfiguren	Wenig Dialog	Gemeinsame „Nebenrolle“-Stimme möglich	1.0

Die Besetzungstabelle ins Front Matter jedes Kapitels schreiben – im gesamten Buch konsistent. Bei vielen Rollen nur jene mit nennenswerten Dialogen eine eigene Stimme geben.

2. Dialogtrennung

Original: Xiaoyu zog an seinem Ärmel und fragte leise: „Opa Zhang, ist da jemand im Leuchtturm?“

Aufteilen in:

[narrator] Xiaoyu zog an seinem Ärmel und fragte leise:
[xiaoyu]: Opa Zhang, ist da jemand im Leuchtturm?

• In Anführungszeichen gesetzter Text → Rolle; Handlungsbeschreibung außerhalb → Erzähler.
• Hinweise wie „sagte er“ / „fragte sie lächelnd“ können entfallen, wenn die Rollenstimme bereits unterscheidbar ist – das macht den Rhythmus straffer.
• Bei mehreren Dialogzeilen in einem Absatz jede Zeile einzeln mit Rollen-Tag.

3. Drei Pausenebenen: Satz, Szene, Kapitel

Position	Schreibweise	Wirkung
Zwischen Sätzen	Automatisch 0,5 Sek. (Preset)	Atem-Rhythmus
Zwischen Absätzen	[pause 0.8]	Absatzwechsel
Szenen-/Zeitsprung	[pause 1.2]–[pause 1.5]	Hörer „Szene wechseln“ lassen
Nach spannendem Satz	[pause 1.0]	Spannung halten

4. Emotion schreiben: Durch Text und Rhythmus, nicht durch Brüllen

• Spannung: Kürzere Sätze, mehr Pausen.
• Wärme: Langsamere Sprechgeschwindigkeit (eigene Rolle narrator_slow definieren), längere Absatzpausen.
• Zwei Geschwindigkeiten mit derselben Stimme:

---
narrator: actor_id=NARRATOR_ID speed=0.95
narrator_soft: actor_id=NARRATOR_ID speed=0.85
---

5. Aussprache prüfen: Namen, Orte, seltene Zeichen

• Bei erstmaligem Auftreten von Namen, Orten, seltenen Zeichen oder mehrdeutigen Schriftzeichen: Einzelsatz anhören.
• Bei falscher Aussprache im Skript durch gleichklingende häufige Zeichen oder durch eine Bezeichnung ersetzen; im gesamten Buch einheitlich.
• Zahlen und Jahreszahlen in gewünschter Lesart schreiben, z.B. „1987“.

6. Dateiorganisation für lange Werke

buch/
  k01.md  → out/k01/voiceover.wav
  k02.md  → out/k02/voiceover.wav
  ...

• Ein Skript pro Kapitel; bei sehr langen Kapiteln nach Szenen aufteilen (k01a.md, k01b.md).
• Bei Korrekturen nur die geänderte Zeile, das entsprechende Kapitel neu laufen lassen; andere Sätze werden aus Cache wiederverwendet, keine Doppelabrechnung.

7. Verwendung für Roman-Push-Videos

• --speaker-labels aktivieren: Untertitel enthalten Rollennamen, Zuschauer sehen sofort, wer spricht.
• manifest.json mit Start-/Endzeit pro Satz kann für Bildwechsel oder Rollen-Porträts im Schnittprogramm verwendet werden.

Beispiel-Skript (examples/example.md)

---
narrator: actor_id=NARRATOR_ID speed=1.05
xiaoyu: actor_id=GIRL_VOICE_ID
laozhang: actor_id=OLD_MAN_ID speed=0.9
---
# Roman-Push-Beispiel (Original-Kurzgeschichte)
[narrator] Der Leuchtturm der kleinen Stadt hatte seit dreißig Jahren nicht mehr geleuchtet.
Doch in jener Nacht sah ich deutlich, wie die Spitze aufblitzte.
[xiaoyu]: Opa Zhang, ist da jemand im Leuchtturm?
[laozhang]: Unsinn. Dieser Turm hat schon lange keine Tür mehr.
[pause 0.8]
[narrator] Kaum war das gesagt, erschien wieder ein Licht auf dem Meer.

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

Einbindung in Schnitt & Veröffentlichung

# Vertonung ersetzen (erfordert ffmpeg)
ffmpeg -i video.mp4 -i out/voiceover.wav -map 0:v -map 1:a -c:v copy -shortest vertonte-version.mp4
# Untertitel ins Video einbrennen
ffmpeg -i vertonte-version.mp4 -vf subtitles=out/voiceover.srt -c:a copy endprodukt.mp4

# Hörbuch-Veröffentlichung oft als MP3: WAV in MP3 umwandeln (erfordert ffmpeg)
ffmpeg -i out/k01/voiceover.wav -codec:a libmp3lame -q:a 2 k01.mp3

• 剪映 / CapCut: Roman-Push-Video: voiceover.wav auf Tonspur, voiceover.srt importieren, mit Illustrationen, Charakter-Porträts oder beruhigenden Hintergrundvideos kombinieren.
• Hörspiel: Soundeffekte und Umgebungsgeräusche später im Schnittprogramm hinzufügen; dieses Skill liefert nur die Sprachspur.

Vergleich: Drei Methoden für Roman-Push-Vertonung

Vergleich	Menschliche Vertonung	Lokales Open-Source-TTS-Modell	Dieses Skill
Benötigt GPU?	Nein, aber Aufnahmeraum und Sprecher-Zeitplan	Ja (kleine Modelle auf CPU, aber langsamer; Modellgewichte + Umgebung nötig)	Nein, lokal nur Python-Standardbibliothek, Generierung in der Cloud
Korrekturkosten	Ein geänderter Satz erfordert oft Neuaufnahme + Neuausrichtung	Neu generieren, aber Segmentierung + Zusammenfügen + Ausrichtung selbst	Nur die geänderte Zeile neu laufen; übrige Sätze aus out/lines/-Cache, automatisches Zusammenfügen und Untertitel-Erstellung
Mehrere Rollen	Mehrere Sprecher nötig	Abhängig vom Modell; meist selbst segmentieren und zusammenfügen	Mit [Rolle]-Tags im Skript, ein Befehl liefert gesamte Mehrspur-Vertonung
Untertitel-Zeitachse	Getrenntes Mitschreiben und Timen	Zusätzlicher Spracherkennungsdurchlauf nötig	Gleichzeitig mit der Vertonung: SRT und manifest.json mit Zeitangaben pro Satz
Serien-Konsistenz	Lange Aufnahmezeit, Sprecherzustand/-verfügbarkeit ändert sich	Konsistent möglich, aber lange Texte selbst segmentieren und zusammenfügen	Stimmfestlegung im Front Matter – jede Folge / jedes Kapitel mit gleicher Stimme

Fazit: Für tägliche Roman-Push-Posts, Hörproben und lange Serien ist dieses Skill am effizientesten. Für besonders ausdrucksstarke hochwertige Hörbücher haben menschliche Sprecher weiterhin Vorteile.

Häufige Fragen (FAQ)

Kann die Roman-Push-Vertonung mehrere Stimmen für verschiedene Rollen haben? Ja. Erzähler und jede Rolle bekommen im Front Matter eine eigene Stimme; im Text wird mit [Rolle]-Tag umgeschaltet, ein Befehl generiert die gesamte Vertonung.

Welche Stimmen werden für Roman-Push-Vertonung typischerweise verwendet? Erzähler: stabil, angenehm und zum Genre passend (romantisch: sanft, spannend: etwas tiefer). Vorher einige Rollen einzeln anhören; auf einem Account eine feste Erzählerstimme verwenden – Zuschauer erkennen den Kanal an der Stimme.

Darf ich fremde Webnovels für Push-Videos vertonen und veröffentlichen? Nur mit Lizenz des Rechteinhabers oder der Push-Plattform. Sicher verwendbar: gemeinfreie Werke, eigene Originale, oder Werke mit entsprechender Lizenz.

Kann der Erzähler im Hörbuch meine eigene Stimme sein? Ja. Verwende deine bereits geklonte Rolle oder ein Referenz-Audio. Gib diese als narrator an – das gesamte Buch nutzt diese Stimme.

Wie generiere ich mehrere Kapitel (z.B. 20) als Hörbuch in einem Durchlauf? Ein Skript pro Kapitel, Schleife: script auf jedes Skript anwenden, Ausgabe in eigenes Verzeichnis. Bei Änderungen nur die geänderten Sätze werden neu generiert.

Kann der Untertitel in Roman-Push-Videos anzeigen, wer spricht? Ja. --preset youshengshu aktiviert automatisch Rollennamen in Untertiteln. Wenn nicht gewünscht, stattdessen manuell --gap / --max-chars verwenden.

Was tun, wenn Namen oder seltene Zeichen falsch ausgesprochen werden? Zuerst als Einzelsatz anhören; bei Fehlern im Skript durch gleichklingende häufige Zeichen oder eine Bezeichnung ersetzen und nur diesen Satz neu generieren.

Wie parametriere ich Gute-Nacht-Geschichten oder Kindergeschichten? Erzähler: speed=0.85–0.9, zwischen Absätzen [pause 0.8] oder länger, kurze Sätze, einfache Wörter.

Benötigt dieses Skill eine GPU? Welche Agenten sind unterstützt? Nein, lokal reicht Python 3.9+ Standardbibliothek; Claude Code, Codex, OpenClaw, Cursor, WorkBuddy können es direkt nutzen.

Kann ich es ohne API-Key testen? Ja. Mit --dry-run werden stille Platzhalter-Audiodateien und Zeitachsen ausgegeben – kein API-Aufruf.

Skript-Syntax

• Zwischen --- am Anfang wird pro Zeile eine Rolle definiert: Rollenname: actor_id=ROLLEN-ID oder Rollenname: ref=Referenz-Audio-URL ref_text="im Referenz-Audio tatsächlich gesprochener Text"; optional: speed= (0.25–4), model=expressive|standard, tags=Tag1,Tag2, language= (Sprachhinweis für Referenz-Audio, zur automatischen Erkennung des Referenztextes).
• ref_text= nur zusammen mit ref=. Bei Weglassen erkennt der Server den Referenztext automatisch (andere Abrechnung – siehe capabilities).
• Im Text: [Rolle] Text oder [Rolle]: Text; ohne Tag wird der letzte Sprecher fortgesetzt.
• [pause 0.6] / [Pause 0.6] für Pausen (Sekunden); Zeilen mit #, Leerzeilen und <!-- Kommentare --> werden ignoriert.
• Einzelsätze, die audio.max_text_length aus capabilities überschreiten, werden abgelehnt – in kürzere Sätze aufteilen.
• Jeder Satz wird in out/lines/ zwischengespeichert; bei gleicher Konfiguration und Wiederholung wird der Cache verwendet. Ohne Cache wird derselbe idempotente Schlüssel übergeben – der Server liefert die ursprüngliche Aufgabe zurück, keine Neuerstellung. Für eine neue Version --fresh hinzufügen.

Probleme?

Symptom	Vorgehen
missing_api_key / MIRAGEA_API_KEY is not set	Schlüssel erzeugen, dann set MIRAGEA_API_KEY=...; oder zuerst --dry-run
speakers without a voice	Für diese Rolle actor_id= oder ref= ergänzen
401	Schlüssel prüfen; Schlüssel nicht in Logs schreiben
403	API-Zugriffsrechte des Accounts prüfen
400 / 413	Parameter korrigieren: Modus, Tags, Geschwindigkeit, Zeichenzahl; oder hochgeladene Datei verkleinern / Medium kürzen
409	Idempotenter Schlüssel für andere Eingabe verwendet, oder Untertitel-Gebühr geändert: erneut bestätigen und senden
429	Kontingent erschöpft oder Ratenlimit; warten oder Guthaben aufladen
Timeout / Netzwerkunterbrechung	Aufgabe könnte noch laufen: denselben Befehl erneut ausführen (gleicher idempotenter Schlüssel → alte Aufgabe abrufen); oder mit miragea_audio.py task / wait AUFGABEN-ID weiter abfragen. Schlüssel nicht tauschen und erneut senden.
WAV-Formatinkonsistenz beim Zusammenfügen	Jeder Einzelsatz liegt in out/lines/; kann mit Schnittprogramm oder ffmpeg zusammengefügt werden.

Offizieller Client-Exit-Code: 0 = Erfolg (ohne --wait kann noch Warteschlange sein), 1 = Aufgabe fehlgeschlagen, 2 = Client- oder Schnittstellenfehler.

Compliance

• Klone nur deine eigene Stimme oder Stimmen, für die du eine ausdrückliche Genehmigung hast. Keine Prominenten, Streamer, öffentliche Personen oder andere Unbefugte.
• Kennzeichne KI-generierte Inhalte gemäß den Vorschriften zur KI-Kennzeichnung und den Richtlinien von Plattformen wie Douyin, Kuaishou, Videoaccount, Xiaohongshu, Bilibili usw.
• Roman-Push und Hörbücher betreffen Bearbeitungs- und Verbreitungsrechte: Verwende nur gemeinfreie Werke, eigene Originale oder Werke mit Lizenz des Rechteinhabers / der Push-Plattform.
• scripts/miragea_audio.py ist der offizielle Client, unverändert ausgeliefert; scripts/voiceover.py (Skript-Zusammenfügung) ist originär, MIT-Lizenz (siehe LICENSE.txt). Vertonungs- und Untertitelfunktionen werden von der Miragea Open API bereitgestellt.

Englische Zusammenfassung (English Summary)

• Roman-Video & Hörbuch-Vertonung (小说推文配音 / 有声书配音): Erzähler plus eine Stimme pro Rolle, in einer WAV-Datei.
• SRT-Untertitel mit Sprecherkennung und Zeitangaben pro Satz für Roman-Push-Videos; Pausen zwischen Absätzen, Szenen und Kapiteln.
• Stimmen aus deinem Account (actor_id) oder Stimmklon aus einem Referenz-Clip für eine konsistente Erzählerstimme. --preset youshengshu = 0,5 s Pausen, 20-Zeichen-Untertitel, Sprecherkennung aktiv.
• Python 3.9+ Standardbibliothek, keine GPU, --dry-run offline. Dienst: Miragea API (https://miragea.ai/v1).

Schlagwörter: Roman-Push-Vertonung, Hörbuch-Vertonung, Mehrstimmige Vertonung, Roman-Push, Roman-Vertonung, KI-Hörbuch, Hörspiel-Vertonung, Geschichten-Vertonung, KI-Vertonung, Stimmklon, Untertitel-Generierung, SRT, Audiobook, Narration, Text-to-Speech