epub-to-m4b

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

Sample

Crime and Punishment, Part 1, Chapter 1, narrated by the self-hosted breeze engine:

https://github.com/user-attachments/assets/1e2cdbda-f83a-4785-b955-82b9f50c354b

Quick start

Requires pixi and ffmpeg + ffprobe on PATH. pixi installs Python 3.14 and the rest.

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

From PyPI: text normalization uses NeMo text processing, which needs pynini 2.1.6.post1. PyPI has no Python 3.14 wheel of it, and no Linux aarch64 or macOS wheel of any pynini version, so take pynini from conda-forge and the package from PyPI:

pixi init e2m && cd e2m
pixi add python=3.14 pynini=2.1.6.post1 editdistance
pixi add --pypi epub-to-m4b
pixi run epub-to-m4b chapters book.epub

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=...
pixi run epub-to-m4b convert book.epub --engine openai -o out/

Example

$ pixi 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.

pixi run epub-to-m4b chapters book.epub
pixi run epub-to-m4b dump-text book.epub --chapter 3 --split
pixi run epub-to-m4b convert book.epub --engine silence -o /tmp/dry-run
OPENAI_API_KEY=... pixi 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 breeze-tts-server (from breeze-tts) and ends with the model: a local dir or a Hugging Face repo id (plus --revision), resolved by breeze-tts. --host/--port are appended. A server already listening on port is adopted instead of spawned. batch_size is clamped to the server's reported limit.

Self-hosted: Drama 3

[engine.drama]

command is the argv that starts vllm serve <model> --omni from vLLM-Omni; --host/--port are appended, and model must match the model it serves. A server already listening on port is adopted instead of spawned; a cold start takes about ten minutes. The narrator voice is cloned from reference_audio (WAV, FLAC or MP3, up to 60 s) and reference_text, its exact transcript; both are uploaded to the server once as a voice named after their content, and a changed file or transcript uploads a new one. batch_size sentences are sent at once and two batches run together; the server decodes them in one GPU batch. Drama 3 weights are under the Fish Audio Community License.

[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]
command = [
  "uv", "run", "--directory", "/path/to/breeze-tts", "breeze-tts-server",
  "BreezeBlue/Breeze-TTS-2",
]

[engine.drama]
command = [
  "/path/to/vllm-omni/.venv/bin/vllm", "serve", "fishaudio/drama-3", "--omni",
  "--init-timeout", "1800", "--stage-init-timeout", "1800",
]
reference_audio = "~/voices/narrator.wav"
reference_text = "The exact words spoken in narrator.wav."

Output

• <out_dir>/<slug>.m4b — AAC at 96 kbps and the source sample rate, loudness-normalized to -16 LUFS (EBU R128 loudnorm); 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 stops old clips being reused. Old clips stay on disk.
• A clip is one sentence, or several short ones packed together, so it always ends where a sentence ends. Only a sentence longer than the engine accepts is cut, at a comma where possible: about 125 characters for silence/tone, up to 300 for breeze, 1000 for the API engines, whatever fits drama's context after the reference voice (about 2300 at the default 8192).
• Clips are keyed by the exact sentence text. A text pipeline change (text/normalize.py, text/split.py, a new nemo-text-processing) re-synthesizes only sentences whose text it changed.
• NeMo compiles a language's grammars on first use into <cache_dir>/nemo/<version>/<lang>/ (E2M_NEMO_CACHE_DIR replaces <cache_dir>/nemo); later runs load them from there.
• A missing or damaged .m4b, or one encoded with different encode settings, is rebuilt; an up-to-date one is kept and only the .vtt is rewritten.

Troubleshooting

Development

pixi run check   # ruff check, ruff format --check, mypy --strict, pytest

Contributing

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

License

MIT.