yanghhu/ai-podcast-voiceover

KI-Podcast

KI-Podcast ist ein Agent-Skill, der Artikel, Notizen oder Dialogskripte in einzelne oder doppelte Podcast-Audioepisoden umwandelt: Satz für Satz vertont und zu einer vollständigen Episode zusammengesetzt, zusammen mit SRT-Untertiteln, Kapiteln mit Zeitstempeln und einem vollständigen Transkript – lokal ohne GPU.

Kurzbeschreibung

KI-Podcast = Podcast-Skript (einzeln oder doppelt, unterteilt mit ## Kapitel) → voiceover.py script erzeugt gesamte Episode voiceover.wav + voiceover.srt + manifest.json → shownotes.py erzeugt chapters.txt, chapters.json und shownotes.md. Die Sprachsynthese erfolgt in der Miragea Cloud, lokal wird keine GPU benötigt.

Zielgruppe und Anwendungsszenarien

Wer nutzt es	Typisches Szenario
WeChat- / Blog-Autoren	Erstelle eine Audioversion eines Artikels, die Leser auf dem Weg zur Arbeit hören können
Wissensblogger	Verwandle Lesenotizen oder Branchenbeobachtungen in wöchentliche Episoden
Marken / Unternehmen	Marken-Podcast, interne Newsletter, Audiodateien für Mitarbeiterkommunikation
Podcast-Hosts	Teaser, Intro/Outro, Nachbearbeitung von Sprachfehlern
Lehrer / Trainer	Erstelle Dialog-Audio zur Wiederholung von Vorlesungen
Personen ohne Aufnahmemöglichkeit	Nutze Charaktere aus dem Konto oder autorisierte eigene Stimme

Kernfunktionen und Parameter

Funktion	Beschreibung
Ausgabedateien	voiceover.wav (gesamte Vertonung), voiceover.srt (Untertitel mit Zeitachse), manifest.json (Sprecher, Text, Start-/Endzeiten pro Satz), lines/ (Audioclips pro Satz, können bei Skriptänderungen wiederverwendet werden)
Stimmquelle	Vorhandener Charakter im Konto (actor_id=, abfragbar mit actors) oder eine Referenz-Audio-URL (ref=) + der tatsächlich gesprochene Text (ref_text=) für Sprachklonierung
Generierungsmodus	expressive (Client-Standard) / standard (Client „ähnlicher“); wenn nicht angegeben, wird der Server-Standard verwendet, basierend auf Echtzeitdaten der capabilities
Tonfall-Tags	tags=Tag-Name, verwende die tags[].label des ausgewählten Modus aus capabilities
Sprechgeschwindigkeit	speed= 0.25–4, 1 = normale Geschwindigkeit, pro Charakter einstellbar
Mehrere Charaktere	Lege zu Beginn des Skripts eine Stimme für jeden Charakter fest; das Skill-Skript ruft den offiziellen Client generate für jeden Satz auf und setzt die gesamte Sequenz lokal zusammen
Pausen	Inline [pause 0.6] / [Pause 0.6] (Sekunden); --gap legt die Standardpause zwischen Sätzen fest
Untertitel	Während der Vertonung wird SRT basierend auf der tatsächlichen Audiolänge jedes Satzes generiert (--max-chars, --speaker-labels); vorhandene Audio-/Videodateien können mit recognize in SRT/TXT/JSON umgewandelt werden
Szenen-Voreinstellungen	--preset koubo / jieshuo / daihuo / shuziren / guanggao / youshengshu (Sprecher / Erzähler / Verkauf / Digitaler Mensch / Werbung / Hörbuch), ändert nur Satzpausen und Untertitelzeichenanzahl
Zeichenbegrenzung pro Satz, Dateigröße / Dauerlimits, Abrechnung	Basierend auf Echtzeitdaten der capabilities
Lokale Abhängigkeiten	Python 3.9+ Standardbibliothek, keine pip-Installation, keine GPU erforderlich
Offline-Test	--dry-run: Kein Key, keine API-Aufrufe, gibt stumme Platzhalter-Audio- und Zeitachsendaten aus, um das Skriptformat zu überprüfen
Unterstützte Agenten	Claude Code, Codex, OpenClaw, Cursor, WorkBuddy und andere Agenten, die Python-Skripte ausführen können
Sprach- und Untertiteldienst	Miragea Offene API (https://miragea.ai/v1)

Dieser Skill bietet zusätzlich scripts/shownotes.py (Programmnotizen-Ebene):

Funktion	Beschreibung
Kapitelquelle	Zeilen im Skript, die mit ## beginnen (werden nicht vorgelesen)
Zeitstempel	Die tatsächliche Startzeit des ersten Satzes jedes Kapitels (aus manifest.json); --offset kann verwendet werden, um Intro-Musiksekunden hinzuzufügen
Ausgabe	chapters.txt (eine Zeile pro HH:MM:SS Titel), chapters.json, shownotes.md (Dauer, Zeitachse, vollständiges Transkript nach Sprechern gegliedert)
Validierung	Fehler bei unterschiedlicher Satzanzahl zwischen Skript und manifest.json, mit Hinweis, die Vertonung erneut auszuführen

Schnellstart

python3 scripts/voiceover.py check                        # Offline-Check: Python-Version, ob Key gesetzt, Service-URL
export MIRAGEA_API_KEY=dein_key                            # Generiere unter https://miragea.ai/workspace/api (nur als Umgebungsvariable)
python3 scripts/miragea_audio.py capabilities             # Aktuelle Generierungsmodi, Tonfall-Tags, Zeichenlimits und Abrechnung (Echtzeitdaten basierend auf Rückgabe)
python3 scripts/miragea_audio.py actors --limit 20        # Vorhandene Charaktere und actor_id im Konto (bei has_more=true mit --offset für Seitenwechsel)

• Standard API-Root ist https://miragea.ai/v1; setze MIRAGEA_BASE_URL (inklusiv /v1) nur für eine private Bereitstellung.
• Nick den Key niemals in den Chat oder in Dateien ein. Wenn kein Key vorhanden ist, führe zunächst mit --dry-run den gesamten Ablauf durch.

python3 scripts/voiceover.py script examples/example.md -o out --gap 0.35 --dry-run   # Offline-Testlauf
python3 scripts/voiceover.py script aktuelles_skript.md -o out --gap 0.35             # Vollständige Episode generieren
python3 scripts/shownotes.py aktuelles_skript.md out --title "Folge 12: Warum ein Buch nie zu Ende lesen?"     # Kapitel + Transkript

Teste zuerst einzelne Sätze mit den Stimmen beider Moderatoren:

# Einzelsatz testen (offizieller Client; --output überschreibt keine vorhandenen Dateien, verwende einen neuen Dateinamen)
python3 scripts/miragea_audio.py generate --text 'Erster Satz' --actor-id ACTOR_ID --wait --output test1.mp3

Ihre Anfrage → Agent-Ausführung

Ihre Anfrage	Agent-Ausführung
„Mach diesen Artikel zu einem Podcast“	Schreibe das Skript wie unten beschrieben in ein gesprochenes Podcast-Skript um und lasse es bestätigen → script → shownotes.py
„Mach es wie ein Gespräch zwischen zwei Personen“	Definiere zu Beginn des Skripts zwei Moderatoren und deren Stimmen, verwende im Text [Name] zur Markierung des Sprechers
„Schreib mir die Programmbeschreibung und Zeitachse“	shownotes.py skript.md out --title ..., gibt dir chapters.txt und shownotes.md
„Füge 8 Sekunden Intro-Musik am Anfang hinzu“	Füge nach der Generierung mit ffmpeg zusammen (siehe unten), shownotes.py ... --offset 8 für korrekte Zeitstempel
„Dieser Satz war ein Versprecher“	Ändere nur die Zeile und führe script erneut aus, die übrigen Sätze werden aus dem Cache verwendet, dann führe shownotes.py noch einmal aus
„Moderator B soll schneller sprechen“	Setze speed=1.1 für B am Anfang des Skripts
„Verwende meine eigene Stimme als Gastgeber“	ref=Referenz-Audio-URL ref_text="Originaltext" oder vorher geklonte actor_id= im Konto
„Ruf die API noch nicht auf“	script ... --dry-run, shownotes.py kann ebenfalls zur Überprüfung der Kapitel verwendet werden

KI-Podcast-Schreibmethode

1. Artikel → Podcast-Skript: Geschrieben für die Ohren

Im Artikel	Im Podcast-Skript
Zwischenüberschriften	In einen mündlichen Übergang umwandeln: „Nachdem wir die Gründe besprochen haben, kommen wir nun zu den Lösungen.“, gleichzeitig die ## Kapitel-Zeilen für die Zeitachse beibehalten
Lange Sätze, Nebensätze	In kurze Sätze aufteilen, ein Satz pro Zeile
Datentabellen	Nur die ein oder zwei wichtigsten Zahlen behalten und ausformulieren
Links, Quellenangaben	Mündlich sagen: „Die Links findest du in der Programmbeschreibung“, in shownotes.md aufnehmen
Schreibverbindungen (daher, zusammenfassend)	„Also“, „Im Klartext“, „Kurz gesagt“

2. Aufgabenverteilung im Zwei-Moderator-Gespräch

• Ein Moderator fragt, wiederholt und fasst zusammen (wie ein Stellvertreter des Publikums), der andere präsentiert Meinungen und Beispiele.
• Jeder spricht ein bis drei Sätze, dann wechselt der andere, um lange Monologe zu vermeiden.
• Wähle für die beiden Moderatoren unterschiedliche Stimmen und Sprechgeschwindigkeiten, damit das Publikum sie leichter unterscheiden kann.
• Füge ein paar realistische Gesprächsreaktionen ein: „Da stimme ich dir zur Hälfte zu“, „Kannst du ein Beispiel nennen?“, aber nicht bei jedem Satz „Ja, genau“.

3. Episoden-Struktur

1. Intro: Ein Satz, der erklärt, worum es in dieser Folge geht und warum sie hörenswert ist.
2. 2–4 Kapitel: Jedes Kapitel eine Frage oder ein Standpunkt; der Kapitelname ist der Titel auf der Zeitachse.
3. Outro: Ein zusammenfassender Satz + Vorschau auf die nächste Folge oder eine Frage zur Interaktion.

4. Rhythmus

• Satzpausen mit --gap 0.3–0.4, etwas lockerer als bei Kurzvideo-Sprechern.
• Zwischen Kapiteln [pause 0.8] einfügen, damit das Publikum Luft holen kann.
• Sprechgeschwindigkeit: Wissensinhalte speed=0.95–1.0, lockerer Plausch 1.0–1.1.

5. Prüfung vor der Veröffentlichung

• Wurden die Stimmen beider Moderatoren einzeln getestet?
• Wurden alle Kapitelüberschriften als ## Überschrift geschrieben?
• Wurden die Sekunden der Intro-Musik mit --offset hinzugefügt?
• Wurde die Erlaubnis zur Wiederverwendung des Artikels, die Musiklizenz und die Kennzeichnung von KI-generierten Inhalten bestätigt?

Beispiel-Skript (examples/example.md)

---
Xiaolin: actor_id=MODERATOR_A_ACTOR_ID speed=1.0
Azhe: actor_id=MODERATOR_B_ACTOR_ID speed=1.05
---
## Intro
[Xiaolin] Willkommen zu unserer heutigen Folge, ich bin Xiaolin.
[Azhe] Ich bin Azhe. Heute reden wir über ein Problem, das viele haben: Warum man ein Buch nie zu Ende liest.
## Nicht zu Ende lesen, weil die falsche Wahl am Anfang
[Xiaolin] Ich möchte eine These aufstellen: Viele Bücher sind es gar nicht wert, zu Ende gelesen zu werden.
[Azhe] Da stimme ich dir zur Hälfte zu.
[Pause 0.4]
[Azhe] Aber bei manchen Büchern sind die ersten fünfzig Seiten einfach schwer.
## Drei kleine Tipps
[Xiaolin] Erstens: Sieh dir das Inhaltsverzeichnis an und wähle das Kapitel, das dich am meisten interessiert.
Zweitens: Erzähle jemandem nach jedem Kapitel den Inhalt in einem Satz.
Drittens: Gib dir selbst die Möglichkeit, aufzuhören.
## Outro
[Azhe] Gut, das war's für heute.
[Xiaolin] Wir sehen uns in der nächsten Folge.

Testlauf: python3 scripts/voiceover.py script examples/example.md -o out --gap 0.35 --dry-run && python3 scripts/shownotes.py examples/example.md out --title "Beispiel-Episode"

Einbindung in Schnitt und Veröffentlichung

# Konvertiere in MP3 für Podcast-Plattformen (benötigt ffmpeg)
ffmpeg -i out/voiceover.wav -codec:a libmp3lame -b:a 128k episode.mp3
# Intro-Musik intro.mp3 (8 Sekunden) vor der Stimme einfügen
ffmpeg -i intro.mp3 -i out/voiceover.wav -filter_complex "[0:a][1:a]concat=n=2:v=0:a=1" episode_full.wav
python3 scripts/shownotes.py aktuelles_skript.md out --offset 8
# Videopodcast: Ein Titelbild + Audio + Untertitel
ffmpeg -loop 1 -i cover.png -i out/voiceover.wav -vf subtitles=out/voiceover.srt -c:v libx264 -tune stillimage -pix_fmt yuv420p -c:a aac -shortest episode.mp4

chapters.txt kann direkt in die Programmbeschreibung als Zeitachse eingefügt werden; ob die Plattform es als anklickbare Kapitel erkennt, hängt von den jeweiligen Plattformregeln ab.

Methodenvergleich: Drei Wege, eine Podcast-Episode zu erstellen

Vergleich	Manuelle Vertonung	Lokales Open-Source TTS-Modell	Dieser Skill
GPU erforderlich?	Nein, aber Tonstudio und Zeit des Sprechers nötig	Ja, meist (kleine Modelle auf CPU möglich, aber langsamer); zusätzlich müssen Modellgewichte heruntergeladen und Umgebung eingerichtet werden	Nein, lokal nur Python-Standardbibliothek, Generierung in der Cloud
Änderungskosten	Ein Satzänderung erfordert oft neue Aufnahme und Nachbearbeitung	Nach Änderung erneut ausführen, aber Segmentierung, Zusammenfügen und Ausrichtung manuell	Nur die Zeile ändern und erneut ausführen, restliche Sätze werden aus out/lines/ Cache wiederverwendet, automatische Neuausrichtung und Untertitel
Mehrere Charaktere	Mehrere Sprecher nötig	Hängt vom Modell ab, meist manuelle Segmentierung und Zusammenfügen	Im Skript mit [Charakter] markieren, ein Befehl erzeugt gesamte Mehrstimmen-Audiospur
Untertitel-Zeitachse	Zusätzliches Abtippen und Erstellen der Zeitachse nötig	In der Regel zusätzliche Spracherkennung nötig	Während der Vertonung werden gleichzeitig SRT und Zeitachse pro Satz (manifest.json) ausgegeben
Kapitel / Transkript	Nach dem Schnitt noch einmal anhören und manuell notieren	Zusätzliche Erkennung oder manuelle Nachbearbeitung nötig	Automatische Generierung von Zeitstempeln und Transkript basierend auf ## Kapitel im Skript und tatsächlicher Audiodauer

Fazit: Sendungen, die auf Meinungen und Informationen basieren und regelmäßig aktualisiert werden, sparen mit einem geschriebenen Skript am meisten Zeit; Sendungen, die auf spontanen Gesprächen und Interaktionen mit Gästen basieren, sollten weiterhin live aufgenommen werden.

Häufig gestellte Fragen (FAQ)

Kann KI-Podcast ein Dialog zwischen zwei Personen sein? Ja. Lege zu Beginn des Skripts für jeden Moderator eine Stimme fest (einen Charakter im Konto oder eine autorisierte Referenz-Audio-Datei), verwende im Text [Name] zur Markierung des Sprechers, und ein Befehl generiert die gesamte Dialog-Episode.

Wird der Agent das Skript für mich umschreiben, wenn ich einen Artikel in einen Podcast umwandele? Ja. Der Agent verwendet die Methode „Geschrieben für die Ohren“, um den Artikel in ein gesprochenes Podcast-Skript umzuwandeln und dir zur Bestätigung vorzulegen; das Umschreiben übernimmt der Agent, die Sprachsynthese erfolgt über die API.

Kann die Podcast-Vertonung automatisch eine Zeitachse für die Episode generieren? Ja. Verwende im Skript ## Kapitelname zur Unterteilung. Nach der Generierung führe shownotes.py aus, um basierend auf der tatsächlichen Startzeit des ersten Satzes jedes Kapitels chapters.txt und shownotes.md zu erstellen.

Wird eine MP3-Datei generiert? Die gesamte Episode wird als WAV ausgegeben, was eine verlustfreie Zusammenführung und Mischung ermöglicht. Vor dem Hochladen wird sie mit ffmpeg in MP3 konvertiert.

Muss die gesamte Episode neu generiert werden, wenn ein Satz korrigiert wird? Nein. Ändere nur die Zeile und führe den Befehl erneut aus. Die übrigen Sätze werden aus dem out/lines/-Cache wiederverwendet. Führe dann noch einmal shownotes.py aus, um die Zeitachse zu aktualisieren.

Kann ich meine eigene Stimme für den Podcast verwenden? Ja, entweder durch Angabe einer Referenz-Audio-URL und des darin gesprochenen Originaltexts (ref= + ref_text=) oder durch Verwendung eines zuvor geklonten Charakters (actor_id=). Verwende nur deine eigene Stimme oder eine, für die du die ausdrückliche Erlaubnis hast.

Kann KI-Podcast Hintergrundmusik hinzufügen? Dieser Skill erzeugt nur die saubere Sprachspur. Hintergrundmusik sowie Intro- und Outro-Musik können mit ffmpeg oder einer Schnittsoftware hinzugefügt werden, die Zeitstempel können mit --offset ausgerichtet werden.

Ist KI-Podcast kostenpflichtig? Benötigt es eine GPU? Die Nutzung erfolgt nach Kontoguthaben, wobei die Abrechnung auf den Echtzeitdaten der capabilities basiert. Lokal wird keine GPU benötigt. Claude Code, Codex, OpenClaw, Cursor und WorkBuddy können alle direkt darauf zugreifen.

Skript-Syntax

• Jede Zeile zwischen den --- am Anfang definiert einen Charakter: Charaktername: actor_id=Charakter-ID oder Charaktername: ref=Referenz-Audio-URL ref_text="tatsächlich gesprochener Text im Referenzaudio"; optional speed= (0.25–4), model=expressive|standard, tags=Tag1,Tag2, language= (Sprachhinweis für das Referenzaudio, zur automatischen Erkennung des Referenztextes).
• ref_text= wird nur zusammen mit ref= verwendet; wenn nicht angegeben, erkennt der Server den Referenztext automatisch (Abrechnung kann abweichen, basierend auf capabilities).
• Im Text: [Charakter] Text oder [Charakter]: Text; ohne Markierung wird der vorherige Sprecher beibehalten.
• [pause 0.6] / [Pause 0.6] fügt eine Pause ein (Sekunden); Zeilen, die mit # beginnen, Leerzeilen und <!-- Kommentare --> werden ignoriert.
• Ein Satz, der audio.max_text_length aus capabilities überschreitet, wird von der API abgelehnt; teile ihn in kürzere Sätze auf.
• Jeder Satz-Audio wird in out/lines/ zwischengespeichert; wenn der gleiche Satz mit den gleichen Einstellungen erneut ausgeführt wird, wird er aus dem Cache wiederverwendet. Bei fehlendem Cache wird derselbe Idempotenz-Schlüssel verwendet; der Server gibt die ursprüngliche Aufgabe zurück und erstellt keine neue. Verwende --fresh für eine neue Version.

Probleme?

Problem	Lösung
missing_api_key / MIRAGEA_API_KEY is not set	Key generieren und export MIRAGEA_API_KEY=...; oder zuerst --dry-run verwenden
speakers without a voice	Für diesen Charakter actor_id= oder ref= ergänzen
401	Key überprüfen; Key nicht in Logs schreiben
403	API-Zugriffsberechtigung für das Konto überprüfen
400 / 413	Parameter korrigieren: Modus, Tags, Geschwindigkeit, Zeichenanzahl pro Satz; oder hochgeladene Datei verkleinern, Medien kürzen
409	Idempotenz-Schlüssel wurde für andere Eingabe verwendet, oder Untertitelrate hat sich geändert: Erneut prüfen und einreichen
429	Guthaben aufgebraucht oder Drosselung aktiv, warten oder Guthaben aufladen
Zeitüberschreitung / Netzwerkunterbrechung	Aufgabe läuft möglicherweise noch: Gleichen Befehl erneut ausführen (gleicher Idempotenz-Schlüssel ruft die ursprüngliche Aufgabe ab), oder miragea_audio.py task / wait Aufgabennummer verwenden, nicht mit neuem Schlüssel erneut senden
WAV-Formatinkonsistenz beim Zusammenfügen	Jeder einzelne Satz-Audio wird in out/lines/ gespeichert, kann mit Schnittsoftware oder ffmpeg zusammengefügt werden

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

Compliance

• Klone nur deine eigene Stimme oder eine, für die du die ausdrückliche Erlaubnis hast; imitiere keine Prominenten, Streamer, öffentlichen Personen oder andere nicht autorisierte Personen.
• Gemäß den „Richtlinien zur Kennzeichnung von KI-generierten Inhalten“ und den Regeln von Plattformen wie Douyin, Kuaishou, Video-Plattformen, Xiaohongshu, Bilibili usw. muss die KI-generierte Natur des Inhalts deutlich gemacht oder gekennzeichnet werden.
• Hole vor der Umwandlung eines Artikels einer anderen Person in einen Podcast die Genehmigung des Autors ein oder stelle sicher, dass eine Weiterverwendung erlaubt ist; für Musik oder Ausschnitte im Programm sind entsprechende Lizenzen erforderlich.
• scripts/miragea_audio.py ist der offizielle Client, wird unverändert ausgeliefert; scripts/voiceover.py (Skript-Zusammenfügungsschicht) ist原创, MIT-Lizenziert (siehe LICENSE.txt). Sprachsynthese- und Untertitelfunktionen werden von der offenen API von Miragea bereitgestellt.

English Summary

• AI podcast (AI播客): turn an article, notes or a dialogue script into a solo or two-host episode; each host gets a voice (account actor or an authorised reference audio).
• voiceover.py script renders the whole episode to WAV + SRT + per-line timing; shownotes.py turns the script's ## chapter lines into timestamped chapters.txt / chapters.json and a full transcript shownotes.md.
• Fix one line, re-render one line. Pricing and limits come live from capabilities. Python 3.9+ stdlib, no GPU. Service: Miragea API (https://miragea.ai/v1).

Schlüsselwörter: KI-Podcast, Podcast-Voiceover, Zwei-Moderator-Podcast, Podcast-Produktion, Artikel-zu-Podcast, Text-zu-Sprache, Dialog-Podcast, Podcast-Kapitel, Programmbeschreibung, WeChat-Artikel-Audio, KI-Voiceover, Text-zu-Sprache, Sprachklonierung, SRT, AI podcast, podcast voiceover, show notes, text to speech