Metadata-Version: 2.5
Name: miragea-audiobook
Version: 0.1.0
Summary: Open-source AI audiobook maker: turn an EPUB, Markdown or text file into a chaptered M4B audiobook (chapter markers, cue sheet, per-chapter MP3) in a cloned narrator voice. CLI, no GPU. Voiced by Miragea.
Project-URL: Homepage, https://codeberg.org/miragea-voice/miragea-audiobook
Project-URL: Documentation, https://codeberg.org/miragea-voice/miragea-audiobook#readme
Project-URL: Issues, https://codeberg.org/miragea-voice/miragea-audiobook/issues
Project-URL: Changelog, https://codeberg.org/miragea-voice/miragea-audiobook/src/branch/main/CHANGELOG.md
Project-URL: Miragea API, https://miragea.ai
Author: miragea-audiobook contributors
License-Expression: MIT
License-File: LICENSE
Keywords: ai-voice,audible-alternative,audiobook,audiobook-generator,audiobookshelf,chapters,cli,cue-sheet,ebook,ebook2audiobook-alternative,epub,epub-to-audiobook,epub-to-m4b,m4b,miragea,narrator,text-to-speech,tts,voice-cloning,voiceover
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# miragea-audiobook

![miragea-audiobook banner: turn an EPUB, Markdown or text file into a chaptered M4B audiobook in a cloned narrator voice](https://codeberg.org/miragea-voice/miragea-audiobook/raw/branch/main/docs/images/cover.png)

**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](https://miragea.ai) 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`](examples/demo/the-salt-road.m4b), plus the [chapter MP3s](examples/demo/).
- 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

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

![Flow diagram: read the book, chunk sentences, voice with Miragea, assemble with ffmpeg, package M4B with chapter markers](https://codeberg.org/miragea-voice/miragea-audiobook/raw/branch/main/docs/images/flow.png)

## Real output

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

![Terminal capture of miragea-audiobook plan and make producing the-salt-road.m4b with two chapters](https://codeberg.org/miragea-voice/miragea-audiobook/raw/branch/main/docs/images/terminal-make.png)

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

![Waveform of the generated audiobook with orange chapter markers at 0 seconds and 16 seconds](https://codeberg.org/miragea-voice/miragea-audiobook/raw/branch/main/docs/images/waveform.png)

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

## Options

| Flag | Meaning |
|---|---|
| `--chapters 1-3,5` | only these chapters (1-based) |
| `--voice` | `actor:<id>` or `https://sample.wav\|exact reference text` |
| `--speed 1.1` | 0.25 to 4.0 |
| `--format m4b\|mp3` | chaptered M4B (default) or one MP3 |
| `--split` | also write one tagged MP3 per chapter |
| `--gap 0.8` | seconds of silence between chapters |
| `--no-announce` | do not read chapter titles aloud |
| `--max-chars 900` | largest text per request (capped by the API limit) |
| `--preview` | offline timing check, no API calls |
| `--json` | machine-readable output for scripts and agents |

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

| | miragea-audiobook | [ebook2audiobook](https://github.com/DrewThomasson/ebook2audiobook) | [audiblez](https://github.com/santinic/audiblez) |
|---|---|---|---|
| Licence | MIT | Apache-2.0 | MIT |
| GitHub stars (2026-11-13 / 2026-11-08) | new | 20.5k | 8.9k |
| Runs TTS | hosted (Miragea API) | locally | locally (Kokoro) |
| GPU / large model download | none | recommended | optional |
| Voice cloning | yes, from a short sample | yes (local models) | no (fixed voices) |
| Chaptered M4B | yes | yes | yes |
| Offline | no (needs API) | yes | yes |

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

```bash
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](https://codeberg.org/miragea-voice/miragea-voice-mcp/src/branch/main/examples/voices/README.md) for attribution). Related: [miragea-podcast](https://codeberg.org/miragea-voice/miragea-podcast), [miragea-dub](https://codeberg.org/miragea-voice/miragea-dub), [miragea-skills](https://codeberg.org/miragea-voice/miragea-skills).
