Usage

Two ways to work

One-shot — parse, auto-cast, compile, render, and master in a single command:

audiobooker make mybook.epub --acx --format m4b

Staged — full control at each step (recommended when you care about casting):

audiobooker new mybook.epub        # parse (EPUB/PDF/DOCX/TXT/MD or a folder)
audiobooker compile                # dialogue, speakers, emotion
audiobooker speakers               # who did compile find?
audiobooker speakers merge "Dr. Merrin" Merrin   # fold duplicate names
audiobooker cast --interactive     # guided per-character casting
audiobooker report                 # unattributed + guessed rates, worst lines
audiobooker review-export          # human-editable script
audiobooker review-import mybook_review.txt
audiobooker render --acx
audiobooker master-check mybook.m4b

Casting

Casting is the one creative decision in the pipeline. Audiobooker gives you several routes:

audiobooker cast Alice af_bella --emotion warm   # assign one voice directly
audiobooker cast-suggest                          # ranked, explainable suggestions
audiobooker audition Alice --render               # A/B the top candidates as audio
audiobooker cast --interactive                    # walk each uncast speaker
audiobooker cast-fill --gender female --voices af_bella,af_sky,af_nova
audiobooker cast-apply --auto                     # apply the top suggestion to all
audiobooker speakers --suggest-aliases            # Dr. Merrin / Merrin / The Doctor
audiobooker speakers merge "Dr. Merrin" Merrin    # one slot, one voice

Reuse a cast across a series with presets, and hand a CSV to a collaborator:

audiobooker cast-preset save mystery-series
audiobooker cast-preset apply mystery-series      # on book 2
audiobooker cast-export --format csv cast.csv     # edit in a spreadsheet
audiobooker cast-import --format csv cast.csv

Mastering to the ACX audio spec

audiobooker render --acx --format mp3 --bitrate 192k
audiobooker master-check book.mp3  # PASS/FAIL: RMS [-23,-18], peak <= -3 dB, floor <= -60 dB
audiobooker sample --duration 180  # a mastered retail sample clip
audiobooker podcast --base-url https://cdn.example.com/   # per-chapter audio + RSS

ACX gates on unweighted RMS, not LUFS. The mastering pass targets −20 LUFS because that is what ffmpeg loudnorm can aim at, and it lands inside the −23..−18 dBFS RMS window for speech — master-check then measures the RMS itself. --acx sets the sample rate but not the codec, hence --format mp3 --bitrate 192k for the full spec.

Meeting the spec is not the same as being accepted. ACX’s standard submission flow is for human narration. Routes that do take AI-narrated titles, generally with disclosure, include Amazon’s Virtual Voice via KDP and aggregators such as Spotify Audiobooks for Authors, Author’s Republic and Kobo Writing Life — check their current terms, which move quickly.

Output formats

--format m4b (chapter markers + cover + series tags) · mp3 · opus · flac. Add --split for one file per chapter, --bitrate 192k to override quality, and export-chapters for a cue/ffmetadata/json chapter sheet.

Review workflow

Dialogue attribution is hard; human correction is fast. Export a script, fix it, re-import — nothing is silently changed (you’re warned if an edited block matches no chapter).

audiobooker review-export
# === Chapter 1 === [id:ab12cd]   <- don't edit the [id:...] tag
#
# @narrator
# The door creaked open.
#
# @Unknown              <-- change to @Marcus
# "Hello?" he whispered.
#
# @Sarah (worried:0.7)  <-- emotion + optional intensity
# "Is anyone there?"
audiobooker review-import mybook_review.txt

Configuration

Set defaults once in .audiobookerrc (TOML) next to your book, or [tool.audiobooker] in pyproject.toml. Precedence: CLI flag > project config > ~/.audiobookerrc > defaults.

output_format = "m4b"
output_profile = "acx"
lang = "en"
jobs = 4
booknlp_mode = "auto"

Pluggable TTS engines

audiobooker render --engine piper      # or set AUDIOBOOKER_ENGINE=piper

A plugin package registers itself via the audiobooker.tts_engines entry-point group — no fork required.

Python API

from audiobooker import AudiobookProject

project = AudiobookProject.from_epub("mybook.epub")   # or from_docx / from_pdf / from_folder / from_string
project.cast("narrator", "bm_george", emotion="calm")
project.cast("Alice", "af_bella", emotion="warm")
project.compile()                                     # dialogue, speakers, emotion
project.render("mybook.m4b")                          # resumes from cache on re-run
project.save("mybook.audiobooker")

render(...) and compile(...) accept an injected engine= (any object implementing the TTSEngine protocol) and a progress_callback= — so you can embed Audiobooker in a GUI or service.