epub-to-m4b

Turn an EPUB into an M4B audiobook with chapter markers, cover art, and a WebVTT transcript.

Quick start

Requires Python 3.14, uv, and ffmpeg + ffprobe on PATH.

uv tool install epub-to-m4b   # or: pipx install epub-to-m4b
epub-to-m4b chapters book.epub

From source:

git clone https://github.com/aaron-ang/epub-to-m4b && cd epub-to-m4b && uv sync
uv run epub-to-m4b chapters book.epub
uv run epub-to-m4b convert book.epub --engine silence -o out/

silence renders a silent .m4b. Speech needs an [engine.<name>] table in config.toml; see Configuration.

# ~/.config/epub-to-m4b/config.toml
[engine.openai]
base_url = "https://api.openai.com/v1"
model = "gpt-4o-mini-tts"
voice = "alloy"

export OPENAI_API_KEY=...
uv run epub-to-m4b convert book.epub --engine openai -o out/

Example

$ uv run epub-to-m4b chapters outliers.epub
Outliers the story of success — Gladwell Malcolm (14 chapters)
  #  title                                               paras    chars  docs
  1  INTRODUCTION — The Roseto Mystery                      27    12584     3
  2  CHAPTER ONE                                            65    26263     8
  3  CHAPTER TWO                                            76    33493     7
  4  THE 10,000-HOUR RULE                                   26     9883     1
  5  CHAPTER THREE                                          79    32187     7
  6  CHAPTER FOUR                                           97    38108     8
  7  CHAPTER FIVE                                           44    20923     7
  8  Lesson Number Two:Demographic Luck                     97    45529    10
  …

Chapter markers in the rendered file (ffprobe -show_chapters out/outliers-the-story-of-success.m4b), first 5 of 14:

00:00:00 → INTRODUCTION — The Roseto Mystery
00:14:12 → CHAPTER ONE
00:43:47 → CHAPTER TWO
01:22:00 → THE 10,000-HOUR RULE
01:34:37 → CHAPTER THREE

Engines

Usage

convert flags:

dump-text flags:

Flags shared by all subcommands:

--version prints the package version.

uv run epub-to-m4b chapters book.epub
uv run epub-to-m4b dump-text book.epub --chapter 3 --split
uv run epub-to-m4b convert book.epub --engine silence -o /tmp/dry-run
OPENAI_API_KEY=... uv run epub-to-m4b convert book.epub --engine openai -o ~/audiobooks

Configuration

Config file resolution, first match wins:

1. --config PATH (must exist)
2. E2M_CONFIG (must exist)
3. ~/.config/epub-to-m4b/config.toml (optional)

Only [engine.<name>] tables are read. Unknown keys, missing required keys, and values of the wrong TOML type are errors. silence and tone take no configuration.

[engine.openai]

[engine.deepgram] (table optional)

[engine.elevenlabs]

Self-hosted: Breeze

[engine.breeze]

command is the argv that starts the server; weights_dir and --host/--port are appended. A server already listening on port is adopted instead of spawned.

[engine.openai]
base_url = "https://api.openai.com/v1"
model = "gpt-4o-mini-tts"
voice = "alloy"

[engine.deepgram]
model = "aura-2-thalia-en"

[engine.elevenlabs]
voice_id = "..."

[engine.breeze]
weights_dir = "/path/to/breeze-tts-2"
command = ["uv", "run", "--directory", "/path/to/breeze-tts", "breeze-infer-api"]

Output

• <out_dir>/<slug>.m4b — chapter markers, cover, title/author tags
• <out_dir>/<slug>.vtt — sentence-level transcript

<slug> is derived from the book title.

Resume

• Rerun the same command to resume an interrupted or partial render.
• Sentence clips are cached as FLAC under <cache_dir>/clips/<engine-fingerprint>/, shared across books. Assembled chapters are cached under <out_dir>/.work/<book-id>/chapters/.
• Changing engine, voice, model, or other audio settings, or editing the text pipeline source (text/normalize.py, text/split.py, text/lang/*), stops old clips being reused. Old clips stay on disk.
• A missing or damaged .m4b is rebuilt; an up-to-date one is kept and only the .vtt is rewritten.

Troubleshooting

Development

make check   # ruff check, ruff format --check, mypy --strict, pytest

Contributing

Workflow and checks: CONTRIBUTING.md. Module layout and conventions: AGENTS.md.

License

MIT.