miragea-audiobook

miragea-audiobook is an open-source command-line audiobook maker. It reads an EPUB, Markdown or plain-text book, splits it into chapters and sentence-safe chunks, narrates every chunk with a cloned or saved voice through the Miragea API, and assembles a single chaptered .m4b (with a cue sheet, a YouTube-style chapter list and optional per-chapter MP3s). No GPU, no PyTorch, no local TTS model to install: just Python, ffmpeg and an API key.

• 🎧 Real demo (2 chapters, 30 s, voice cloned from a 10-second CMU ARCTIC sample): examples/demo/the-salt-road.m4b, plus the chapter MP3s.
• Chapters from the EPUB spine and headings, Markdown ## headings, or "Chapter N" lines in text files.
• Re-running after an error reuses every finished chunk (cached by request hash and sent with idempotency keys), so nothing is generated or billed twice.
• plan shows chapters, request count and an estimated length first; --preview checks the whole pipeline offline with placeholder tones.

Quick start

pipx install miragea-audiobook          # or: pip install miragea-audiobook
# ffmpeg + ffprobe must be on PATH (brew install ffmpeg / apt install ffmpeg)

export MIRAGEA_API_KEY=...              # create a key at https://miragea.ai/workspace/api

miragea-audiobook chapters book.epub    # what did it find? (offline)
miragea-audiobook plan book.epub        # chapters, requests, estimated minutes
miragea-audiobook make book.epub \
  --voice 'https://example.com/my-voice.wav|Exact words spoken in that 5-30 second sample.' \
  --split

--voice actor:<id> uses a voice saved in your Miragea account instead. Output goes to ~/miragea-audiobook/<title>/ (change with --out).

Real output

Everything below came from a real run of the command shown (the book is examples/the-salt-road.md).

The chapter markers sit exactly at the chapter boundaries of the real audio:

I checked the narration by sending chapter 1 back through speech recognition: the transcript matched the book text word for word.

Options

Files written: <title>.m4b, <title>.chapters.txt, <title>.cue, <title>.json (chapter times, task IDs) and optionally NN-<chapter>.mp3.

Play it

The M4B opens with chapter navigation in Apple Books, VLC, Audiobookshelf, Plex (with an audiobook library) and most podcast/audiobook players. Drop the folder into your Audiobookshelf library as-is.

How it compares

Pick the local tools if you must stay offline or want zero per-use cost. Pick this one if you want a small install, no model downloads and a cloned narrator on a laptop or a CI box. Licences and star counts were read from the GitHub API (ebook2audiobook) and the ecosyste.ms GitHub mirror (audiblez);

FAQ

How do I convert an EPUB to an M4B audiobook with AI? Install the package and ffmpeg, set MIRAGEA_API_KEY, then run miragea-audiobook make book.epub --voice .... You get a single .m4b with chapter markers.

Can I make an audiobook in my own voice? Yes. Give it a clean 5-30 second recording with the exact words said; the voice is cloned from that sample. Only clone voices you have the right to use.

Does it need a GPU? No. Synthesis runs on the Miragea API; the only local work is ffmpeg.

Can I turn a PDF into an audiobook? Not directly. Convert the PDF to Markdown or EPUB first (for example with Calibre or pandoc), then run it.

Why was a chapter missing? Spine items with fewer than 20 words (covers, copyright stubs) are skipped. Run miragea-audiobook chapters book.epub to see what was found.

What if it fails halfway through a long book? Run the same command again. Finished chunks are cached in .miragea-cache and are not requested again.

Can an AI agent run this? Yes, every command has --json. Install the Miragea skill with "Install https://miragea.ai/skills/miragea-audio/install.md" and let the agent call the CLI.

Troubleshooting

• ffmpeg_missing: install ffmpeg and ffprobe.
• missing_api_key: set MIRAGEA_API_KEY (key page: https://miragea.ai/workspace/api). Base URL defaults to https://miragea.ai/v1.
• Voice sounds off: use a cleaner, longer sample and the exact transcript of it.
• Out of credits (402/429): top up on miragea.ai, then re-run; cached chunks are free.

Development

pip install -e '.[dev]'
pytest      # offline, uses a mock API
ruff check .
python docs/make_images.py

Credits and licence

MIT. The demo voice sample is from CMU ARCTIC (see the voices README in miragea-voice-mcp for attribution). Related: miragea-podcast, miragea-dub, miragea-skills.