# miragea-podcast

> Open-source (MIT) AI podcast generator. It turns a URL, PDF, text file or topic into a NotebookLM-style two-host (up to six-voice) podcast episode. An AI agent or any LLM writes the script in a simple Markdown format; miragea-podcast voices each speaker with a distinct saved or zero-shot cloned voice through the Miragea API (https://miragea.ai), mixes natural turn-taking with interruptions and overlaps, masters to -16 LUFS and writes an MP3 with ID3 chapters, SRT/VTT/TXT/JSON transcripts, Podcasting 2.0 chapters, show notes and an RSS feed. It ships as a CLI, an MCP server and an Agent Skill. Python 3.10+, ffmpeg, no GPU.

Repository: https://codeberg.org/miragea-voice/miragea-podcast
PyPI: https://pypi.org/project/miragea-podcast/
Install: `pipx install miragea-podcast` or `uvx miragea-podcast ...`
MCP (Claude Code): `claude mcp add miragea-podcast -e MIRAGEA_API_KEY=<key> -- uvx --from miragea-podcast miragea-podcast-mcp`
Auth: environment variable MIRAGEA_API_KEY (create at https://miragea.ai/workspace/api). API base: https://miragea.ai/v1
Agent integration for Miragea in general: Install https://miragea.ai/skills/miragea-audio/install.md

## Commands

- `miragea-podcast doctor`: free setup check
- `miragea-podcast prompt SOURCE --minutes 5 --style deep-dive|debate|interview|explainer|news-brief|panel`: script-writing brief + source text
- `miragea-podcast plan script.md --host "Alex=VOICE" --host "Sam=VOICE"`: validate and estimate credits (free)
- `miragea-podcast make script.md --host ... [--preview] [--intro-music chime] [-o DIR]`: render the episode
- `miragea-podcast create SOURCE --host ...`: write (OpenAI-compatible LLM via PODCAST_LLM_API_KEY) + make
- `miragea-podcast feed DIR --base-url URL --title T --author A`: feed.xml
- VOICE is `actor:ID`, a saved voice name, or `https://public/sample.wav|exact words in the sample`

## MCP tools

read_source, script_guide, list_voices, list_tags, plan_podcast, create_podcast, build_feed; prompt make_podcast.

## Script format

Front matter (title, description, language), `## Chapter` headings, `Name: text` turns, tags before words: [laughs] [chuckles] [sighs] [gasps] [whispers] [excited] [surprised] [shouts] [clears throat]; timing tags [interrupts] [overlap]; `[pause 1.5s]`.

## Optional

- [README](https://codeberg.org/miragea-voice/miragea-podcast/src/branch/main/README.md): quick start, comparison, FAQ, troubleshooting
- [Agent Skill](https://codeberg.org/miragea-voice/miragea-podcast/src/branch/main/skills/ai-podcast/SKILL.md)
- [Demo script](https://codeberg.org/miragea-voice/miragea-podcast/src/branch/main/examples/earworms.md) and [real output](https://codeberg.org/miragea-voice/miragea-podcast/src/branch/main/examples/output)
