miragea-audiobook banner

If you have searched for "EPUB to audiobook" you have probably met tools that want PyTorch, a few gigabytes of model weights and a GPU. This tutorial does the same job from a plain command line: miragea-audiobook reads an EPUB, Markdown or text file, narrates it through the Miragea API in a voice cloned from a short sample, and gives you one chaptered .m4b.

What you need

  • Python 3.10+ and ffmpeg (brew install ffmpeg or apt install ffmpeg)
  • A Miragea API key from https://miragea.ai/workspace/api
  • A clean 5-30 second recording of the voice you want, hosted at a public https URL, and the exact words spoken in it

1. Install and set the key 

pipx install miragea-audiobook export MIRAGEA_API_KEY=...

2. Check what it found (offline) 

miragea-audiobook chapters book.epub miragea-audiobook plan book.epub

EPUB chapters come from the spine and each file's first heading. Covers and copyright stubs under 20 words are skipped. For Markdown, each ## heading is a chapter; for plain text, lines starting with "Chapter", "Part", "Prologue" and similar.

How the pipeline works: read, chunk, voice, assemble, package

3. Make the audiobook 

miragea-audiobook make book.epub \ --voice 'https://example.com/my-voice.wav|Exact words spoken in that sample.' --split

The text is cut into whole-sentence chunks (900 characters by default), voiced in parallel, and cached by request hash. If something fails halfway, run the same command again: finished chunks are reused and not billed twice.

Terminal capture of a real run producing a two-chapter M4B

4. What you get

the-salt-road.m4b with chapter markers, a .cue sheet, a .chapters.txt list ready for YouTube descriptions, a JSON manifest and one MP3 per chapter. Here is the real waveform of the demo book, with the markers at the chapter starts:

Waveform of the demo audiobook with chapter markers

Listen to the real demo: https://codeberg.org/miragea-voice/miragea-audiobook/raw/branch/main/examples/demo/the-salt-road.m4b

I ran chapter 1 back through speech recognition and it matched the source text word for word.

Tips

  • Use --preview first on a big book: it builds the whole file offline with placeholder tones so you can check chapters and timing for free.
  • --chapters 1-3 voices just a few chapters while you audition a voice.
  • Audiobookshelf, Apple Books and VLC show the chapter list automatically.
  • Only clone a voice you have the right to use.

Source (MIT): https://codeberg.org/miragea-voice/miragea-audiobook. Package: https://pypi.org/project/miragea-audiobook/