Narrate

narrate

narrate is the narration half of spitfire-storybook — a privacy-first, local-only, open-source tool. It doesn't just help write your book, it reads it to you. Every byte of synthesis happens on your own hardware via a bundled local Kokoro server. There is no hosted version and nothing is ever uploaded.

The script lives at cli/narrate.py (relative to the repo root). Run it with your system Python:

python3 cli/narrate.py <mode> [args] [flags]

Prerequisites

• A local Kokoro server. The CLI talks to it over HTTP. Start one from cli/kokoro/ (./start.sh, or python3 cli/kokoro/server.py). First run downloads the ~330 MB Kokoro-82M model and caches it locally. See cli/kokoro/README.md.
• python3 + ffmpeg on your PATH. That's it — synthesis is dependency-light; all audio decode/concat/encode goes through ffmpeg (no numpy/soundfile). PIL is optional and only used to auto-generate a book cover.
• The CLI auto-detects the server at http://localhost:8081 (and http://127.0.0.1:8081). Override the endpoint with the KOKORO_URL environment variable or the --server flag. KOKORO_VOICE overrides the default voice. If no server is reachable, the CLI exits with a message telling you to start one.

Three modes

1. say — speak a string

python3 cli/narrate.py say "Welcome to the first chapter." -o intro.mp3 --play

Speaks the given text. Defaults to narration.mp3 when -o is omitted.

2. file — narrate a .txt/.md file

python3 cli/narrate.py file notes.md -o notes.mp3

Reads the file, applies Markdown cleaning, and synthesizes it. The default output name is the input filename with an .mp3 extension.

3. book — build a chaptered .m4b audiobook

python3 cli/narrate.py book ./my-book \
  --title "The Fictional Field Guide" \
  --subtitle "An Imaginary Manual" \
  --author "A. N. Author" \
  --year 2026

The input is either:

• a directory of .md/.txt files (sorted recursively). Each file becomes a chapter; its title is the first # H1 heading, or the filename if there's none.
• a manifest manifest.json: a list of [{title, text|src|text_inline, ...}] entries, giving explicit chapter order, titles, and content.

It synthesizes each chapter, then muxes them into a single .m4b with embedded chapter markers, metadata, and (by default) an auto-generated cover. Output defaults to a slugified title with the .m4b extension.

Book mode is resumable. Chapter WAVs are cached in a .narrate_build/ directory next to the output; if a chapter file already exists, it's skipped on the next run. Delete that directory (or a single chapter WAV) to force a re-synthesis.

Flags

Common to all modes:

Flag	Meaning
-o, --out PATH	Output file (.mp3 / .wav / .m4a / .m4b). Sensible default per mode.
--voice NAME	Kokoro voice (default af_heart = "Heart").
--gap SECONDS	Pause inserted between chunks (default 0.3).
--play	Play the result when done (macOS afplay).
--server URL	Override the Kokoro endpoint (else auto-detect / KOKORO_URL).

file and book also accept:

Flag	Meaning
--clean md|plain|none	Markdown cleaning mode (default md).

Book-only:

Flag	Meaning
--title	Book / album title.
--subtitle	Subtitle (stored as comment).
--author	Author.
--narrator	Narrator credit (default Heart · Kokoro TTS).
--year	Publication year.
--cover auto|none|PATH	auto generates a cover (needs PIL); default auto.
--bitrate	AAC bitrate for the .m4b (default 96k).

Markdown → spoken cleaning

With --clean md (the default), the text is converted from Markdown into something that reads naturally aloud before synthesis:

• strips YAML frontmatter, code fences, inline code, HTML, images, and bare URLs
• turns links into their visible text
• linearizes tables into spoken rows and flattens list markers / blockquotes into sentences
• converts headings into spoken lines with a terminal period
• removes emphasis markers (**, *, _)
• expands symbols Kokoro otherwise mispronounces: % → "percent", $1,500 → "1500 dollars", $5k → "5 thousand dollars", 3x → "3 times", & → "and", →/-> → "leads to", 24/7 → "twenty-four seven", plus common abbreviations (e.g., i.e., etc., vs., approx., w/).

Use --clean plain to just collapse whitespace (keeps the raw text), or --clean none to feed the text through untouched. In book mode, .txt chapters are always treated as plain regardless of --clean.

Long text is automatically split into ~1500-character chunks at paragraph and sentence boundaries, synthesized chunk-by-chunk, and stitched together with the configured gap.

Importing the .m4b into Apple Books

1. Open the Books app on macOS.
2. Drag the generated .m4b onto the Books window, or use File → Add to Library… and select it.
3. It appears under Audiobooks with chapter navigation, the embedded cover, and resume-where-you-left-off playback. It syncs to your iPhone/iPad via the same Apple ID.

(.m4b is a standard AAC audiobook container, so the same file also imports into Podcasts and most third-party audiobook players.)