yanghhu/ai-podcast-voiceover

AI Podcast

"AI Podcast" is an Agent skill that turns articles, notes, or dialogue scripts into single or dual-host podcast audio: it renders each line with a voice, stitches them into a full episode, and outputs SRT subtitles, timestamped chapters, and a complete transcript—all locally, no GPU required.

One-Line Definition

AI Podcast = podcast script (solo or dual-host, with ## chapter sections) → voiceover.py script generates the full episode voiceover.wav + voiceover.srt + manifest.json → shownotes.py creates chapters.txt, chapters.json, and shownotes.md. Voice is generated on the Miragea cloud; no local GPU needed.

Who It's For & When to Use

User	Typical Scenario
WeChat / Blog Authors	Turn an article into an audio version for listeners on the go
Knowledge Bloggers	Convert reading notes and industry observations into a weekly show
Brands / Enterprises	Brand podcasts, internal weekly reports, employee newsletter audio
Podcast Hosts	Trailers, intros/outros, re-recording a single flubbed line
Teachers / Trainers	Turn lecture notes into conversational review audio
People who can't record	Use account actors or authorized voice for the show

Core Capabilities

Feature	Description
Output Files	voiceover.wav (full episode), voiceover.srt (timestamped subtitles), manifest.json (per-line speaker, text, start/end seconds), lines/ (per-line audio, reusable when editing)
Voice Source	Account actor via actor_id= (query with actors), or a reference audio URL ref= + the spoken text in that audio ref_text= (voice cloning)
Generation Mode	expressive (client "default") / standard (client "more like"); omitted uses server default; check capabilities for actual modes
Tone Tags	tags=tag_name, using the selected mode's tags[].label from capabilities
Speed	speed= 0.25–4, 1 is normal; set per character
Multiple Characters	Define a voice for each character at the top of the script; the skill calls the official client generate per line and stitches them locally
Pauses	Inline [pause 0.6] / [pause 0.6] (seconds); --gap sets default pause between sentences
Subtitles	Generate SRT based on actual audio duration per line (--max-chars, --speaker-labels); use recognize for existing audio/video to get SRT/TXT/JSON
Scene Presets	--preset koubo / jieshuo / daihuo / shuziren / guanggao / youshengshu (oral broadcast / commentary / sales / digital human / advertisement / audiobook); only changes sentence pause and subtitle character count
Limits & Pricing	Per-line character count, file size/duration limits, and pricing are fetched live from capabilities
Local Dependencies	Python 3.9+ standard library, no pip install needed, no GPU
Offline Testing	--dry-run: no API key needed, no network calls; outputs silent placeholder audio and timeline to check script format
Supported Agents	Claude Code, Codex, OpenClaw, Cursor, WorkBuddy, and any Agent that can run Python scripts
Voice & Subtitle Service	Miragea Open API (https://miragea.ai/v1)

This skill also includes scripts/shownotes.py (show notes layer):

Feature	Description
Chapter Source	Lines starting with ## in the script (these are not read aloud)
Timestamps	Uses the real start time of each chapter's first sentence (from manifest.json); --offset adds intro music duration in seconds
Output	chapters.txt (one HH:MM:SS Title per line), chapters.json, shownotes.md (duration, timeline, full transcript segmented by speaker)
Validation	Errors if the sentence count in the script doesn't match manifest.json, prompting a re-generate

Quick Start

python3 scripts/voiceover.py check                        # Offline check: Python version, key set, service URL
export MIRAGEA_API_KEY=your_key                            # Generate at https://miragea.ai/workspace/api; set only as env var
python3 scripts/miragea_audio.py capabilities             # List available generation modes, tone tags, max text length, and pricing (live)
python3 scripts/miragea_audio.py actors --limit 20        # List account actors and their actor_id (use --offset for pagination if has_more is true)

• Default API root is https://miragea.ai/v1; set MIRAGEA_BASE_URL (including /v1) only for a private deployment.
• Do not paste the key into chat or write it to a file. Use --dry-run without a key to test the flow.

python3 scripts/voiceover.py script examples/example.md -o out --gap 0.35 --dry-run   # Offline test run
python3 scripts/voiceover.py script myscript.md -o out --gap 0.35                      # Generate the full episode
python3 scripts/shownotes.py myscript.md out --title "Episode 12: Why You Never Finish a Book"     # Chapters + transcript

First, sample a single line from each host's voice:

# Single line sample (official client; --output won't overwrite existing file, use a new filename)
python3 scripts/miragea_audio.py generate --text 'First line' --actor-id ACTOR_ID --wait --output test1.mp3

What You Say → Agent Does

You Say	Agent Does
"Turn this article into a podcast"	Rewrite it as a conversational podcast script using the method below → show you for confirmation → voiceover.py script → shownotes.py
"Make it a two-person conversation"	Define two hosts and their voices at the top of the script; use [Name] tags in the body to alternate speakers
"Help me write the show notes and timeline"	shownotes.py myarticle.md out --title ..., then provide chapters.txt and shownotes.md
"Add an 8-second intro music before the first line"	After generation, mix with ffmpeg (see below); use shownotes.py ... --offset 8 to align timestamps
"This sentence is wrong"	Edit that one line and re-run voiceover.py script; all other sentences reuse cached audio; then re-run shownotes.py
"Host B talks too fast"	Set speed=1.1 for Host B at the top of the script
"Use my own voice"	Provide ref=reference_audio_url ref_text="spoken words" or an already cloned actor_id= from your account
"Don't call the API yet"	script ... --dry-run; shownotes.py works the same way to check chapters

How to Write a Podcast Script (AI Podcast Style)

1. Article → Podcast: Write for the Ear

In the Article	In the Podcast Script
Subheadings	Turn into a spoken transition: "Now that we've covered the reasons, let's talk about solutions." Keep ## chapter lines for the timeline
Long sentences, clauses	Break into short sentences, one per line
Data tables	Keep only 1-2 key numbers; spell out the reading clearly
Links, citations	Say "Links are in the show notes" and include them in shownotes.md
Formal connectors (therefore, in conclusion)	Use "so," "the thing is," "in short"

2. Two-Host Dialogue Division

• One host asks questions, summarizes, and acts as the audience's proxy; the other delivers opinions and examples.
• Each person speaks 1-3 sentences before switching, to avoid long monologues.
• Choose voices with different timbres and speeds for each host so listeners can tell them apart.
• Add natural conversational reactions: "I agree, but only halfway," "Can you give an example?" But not every sentence with "yes, yes, yes."

3. Episode Structure

1. Opening: One sentence about what this episode covers and why it's worth listening.
2. 2–4 Chapters: Each chapter covers one question or point; the chapter name becomes the timeline title.
3. Ending: One sentence summary + next episode preview or a question for the audience.

4. Pacing

• Sentence pause: use --gap 0.3–0.4—a bit looser than short video voiceovers.
• Add [pause 0.8] between chapters to let listeners breathe.
• Speed: knowledge-based content speed=0.95–1.0, casual chat 1.0–1.1.

5. Pre-Release Checklist

• Have you sampled a single line from each host's voice?
• Is every chapter title written as ## Title?
• Did you add the intro music duration using --offset?
• Have you confirmed article reprint permissions, background music licenses, and AI-generated content labeling?

Example Script (examples/example.md)

---
Xiao Lin: actor_id=HOST_A_ACTOR_ID speed=1.0
A Zhe: actor_id=HOST_B_ACTOR_ID speed=1.05
---
## Opening
[Xiao Lin] Welcome to today's show. I'm Xiao Lin.
[A Zhe] And I'm A Zhe. Today we're talking about a problem many people have: why you never finish a book.
## You Never Finish Because You Choose Wrong From the Start
[Xiao Lin] Let me start with a take: many books aren't worth finishing in the first place.
[A Zhe] I agree, but only halfway.
[pause 0.4]
[A Zhe] But some books are just genuinely hard for the first fifty pages.
## Three Simple Tips
[Xiao Lin] First, look at the table of contents and pick the chapter you most want the answer to.
Second, after finishing a chapter, explain it in one sentence to someone else.
Third, give yourself permission to give up.
## Ending
[A Zhe] Alright, that's all for today.
[Xiao Lin] See you next time.

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

Integration for Editing & Publishing

# Convert to MP3 for podcast platforms (requires ffmpeg on your machine)
ffmpeg -i out/voiceover.wav -codec:a libmp3lame -b:a 128k episode.mp3
# Prepend intro music (intro.mp3, 8 seconds) before the voice
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 myscript.md out --offset 8
# Video podcast: cover image + audio + subtitles
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

You can directly paste chapters.txt into your show notes as a timeline; whether the platform recognizes it as clickable chapters depends on each platform's rules.

Comparison: Three Ways to Make a Podcast

Aspect	Manual Recording	Local Open-Source TTS	This Skill
GPU Required?	No, but needs recording setup and talent availability	Often yes (small models on CPU possible but slower); also needs model weights and environment setup	No, only Python stdlib locally; generation happens in the cloud
Cost of Editing	Edit one line → re-record and manually re-align audio	Re-run entire script; must handle segmentation, stitching, and alignment yourself	Edit only that line and re-run; all other sentences reuse out/lines/ cache; automatically re-stitches and re-generates subtitles
Multiple Characters	Need multiple voice actors recording separately	Depends on the model; usually you need to call the model per speaker and stitch manually	Use [Character] tags in the script; one command generates the full multi-character audio track
Subtitle Timelines	Requires separate transcription and timing	Usually needs another speech recognition pass	Outputs SRT and per-line timing (manifest.json) during voice generation
Chapters / Transcript	Manually note timestamps after editing	Needs separate recognition or manual work	Automatically generates timestamped chapters and transcript from ## chapter headings and actual audio duration

Conclusion: For shows focused on opinions and information that need regular updates, using a written script with this skill saves the most time. For shows that rely on improvisation and guest interaction, live recording is still recommended.

FAQ

Can AI Podcast do two-person dialogue? Yes. Define a voice for each host at the top of the script (account actor or authorized reference audio), use [Name] tags in the body to indicate who is speaking, and one command generates the full dialogue episode.

Will the Agent rewrite my article into a podcast script? Yes. The Agent will rewrite your article into a conversational podcast script using the "write for the ear" method and present it for your confirmation. The rewriting is done by the Agent; the voice is generated by the API.

Can the podcast voiceover automatically generate a show timeline? Yes. Use ## Chapter Title to segment the script, then run shownotes.py. It will output chapters.txt and shownotes.md with timestamps based on the real start time of each chapter's first sentence.

Is the output MP3? The full episode is output as WAV for lossless stitching and mixing. Use ffmpeg to convert to MP3 before uploading.

Do I need to regenerate the whole episode to fix one wrong line? No. Edit only that line and re-run voiceover.py script; all other sentences are reused from the out/lines/ cache. Then re-run shownotes.py to update the timeline.

Can I use my own voice for the podcast? Yes, by providing a reference audio URL and the spoken text (ref= + ref_text=), or by cloning your voice into an account actor and using actor_id=. You must use only your own voice or voices you have permission to use.

Can AI Podcast add background music? This skill outputs clean voice audio. Use ffmpeg or editing software to mix in background music and intro/outro. Align timestamps with --offset.

Does AI Podcast cost money? Does it need a GPU? It consumes credits from your account; pricing is fetched live from the /capabilities endpoint. No local GPU is required. Claude Code, Codex, OpenClaw, Cursor, and WorkBuddy can all use it directly.

Script Syntax

• Between the opening --- markers, each line defines a character: CharacterName: actor_id=ACTOR_ID or CharacterName: ref=REFERENCE_AUDIO_URL ref_text="actual spoken words in the reference audio"; you can add speed= (0.25–4), model=expressive|standard, tags=tag1,tag2, language= (language hint for the reference audio, used for automatic reference text detection).
• ref_text= is used only with ref=; when omitted, the server automatically detects the reference text, with different pricing as determined by capabilities.
• In the body: [Character] line or [Character]: line; if the character tag is omitted, the previous speaker continues.
• [pause 0.6] / [pause 0.6] inserts a pause (seconds); lines starting with #, blank lines, and <!-- comment --> are ignored.
• If a single sentence exceeds capabilities's audio.max_text_length, the API will reject it; split it into shorter sentences.
• Each sentence's audio is cached in out/lines/; re-running with the same settings reuses the cache. If no cache exists, the same idempotency key sends the request; the server returns the original task without creating duplicates. Use --fresh to force a new version.

Troubleshooting

Symptom	Fix
missing_api_key / MIRAGEA_API_KEY is not set	Generate a key and export MIRAGEA_API_KEY=...; or use --dry-run first
speakers without a voice	Add actor_id= or ref= for that character
401	Check your key; don't write the key into logs
403	Check your account's API access permissions
400 / 413	Fix parameters: mode, tags, speed, sentence length; or reduce file size / shorten media duration
409	Idempotency key used with different input, or subtitle rates changed: reconfirm then resubmit
429	Insufficient credits or rate limited; wait or top up credits
Timeout / Network Interruption	The task may still be running: just re-run the same command (same idempotency key retrieves the original task), or use miragea_audio.py task / wait TASK_ID to continue querying; do not change the key and resubmit
WAV format mismatch when stitching	Each line's audio is saved in out/lines/; you can stitch them with an editor or ffmpeg

Official client exit codes: 0 = request succeeded (may still be queued without --wait), 1 = task failed, 2 = client or API error.

Compliance

• Only clone your own voice or voices you have explicit permission to use. Do not imitate celebrities, streamers, public figures, or any unauthorized person.
• Mark or label AI-generated content when publishing, in accordance with China's "Methods for Labeling AI-Generated Synthetic Content" and platform rules (Douyin, Kuaishou, Video Account, Xiaohongshu, Bilibili, etc.).
• Before turning someone else's article into a podcast, obtain the author's permission or confirm it can be republished. You must have permission for any music or clips used in the show.
• scripts/miragea_audio.py is the official client, shipped unmodified; scripts/voiceover.py (script stitching layer) is original work, MIT licensed (see LICENSE.txt). Voice and subtitle capabilities are provided by the Miragea Open API.

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).

Key Words: AI podcast, podcast voiceover, dual-host podcast, podcast production, article to podcast, article to speech, dialogue podcast, podcast chapters, show notes, WeChat audio, AI voiceover, text to speech, voice cloning, SRT