narrapy 0.1.0__tar.gz

narrapy-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python virtual environment
+.venv/
+__pycache__/
+
+# Local notes
+command.txt
+
+# Books
+*.pdf
+
+# Generated audio and work folders
+*.m4b
+*.mp3
+*.wav
+*_audiobook_work/
+*.cleaned.txt
+
+# Downloaded Piper voice models (large; re-download with piper.download_voices)
+voices/
+
+# Voice samples
+voice_samples/
+
+# Build output
+dist/
+build/
+*.egg-info/
+
+# Backup of the pre-package scripts (kept locally, not pushed)
+previous_version/

narrapy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rakesh Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

narrapy-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.5
+Name: narrapy
+Version: 0.1.0
+Summary: Turn PDFs into audiobooks with chapters, using local neural text-to-speech (Kokoro or Piper).
+Project-URL: Homepage, https://github.com/rakishere/narrapy
+Project-URL: Issues, https://github.com/rakishere/narrapy/issues
+Author: Rakesh Sharma
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audiobook,kokoro,m4b,pdf,piper,text-to-speech,tts
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: <3.13,>=3.10
+Requires-Dist: kokoro
+Requires-Dist: numpy
+Requires-Dist: piper-tts
+Requires-Dist: pymupdf
+Requires-Dist: soundfile
+Description-Content-Type: text/markdown
+
+# Narrapy
+
+Turn any text-based PDF into an audiobook on your own computer. Narrapy reads the PDF, cleans up the text, detects chapters, narrates each chapter with a local neural voice ([Kokoro](https://huggingface.co/hexgrad/Kokoro-82M) or [Piper](https://github.com/rhasspy/piper)), and packages everything into a single `.m4b` audiobook with chapter markers, title, and author.
+
+No cloud services, no API keys. After the first run it works fully offline.
+
+## Features
+
+- **Chapters, automatically.** Uses the PDF's built-in table of contents first. If there isn't one, it looks for "Chapter 3" or "Part Two" style headings. As a last resort it splits the book into 15-page parts so you can still skip around.
+- **Clean narration.** Removes running headers and footers, page numbers, and citation markers like `[12]`. Rejoins hyphenated words and replaces URLs with the word "link" so they aren't read out letter by letter.
+- **Resumable.** A long book can take hours on CPU. If a run stops, run the same command again and finished chapters are skipped.
+- **Voice sampler.** Listen to a short sample of every voice before choosing one.
+- **Two engines.** Kokoro (default, higher quality) or Piper (faster, lighter).
+- **M4B or MP3.** One `.m4b` with chapters for audiobook players, or one MP3 per chapter.
+
+## Requirements
+
+- Python 3.10, 3.11, or 3.12 (Kokoro doesn't support 3.13+ yet)
+- [ffmpeg](https://ffmpeg.org/) on your PATH
+- [espeak-ng](https://github.com/espeak-ng/espeak-ng/releases) (Kokoro uses it for unusual words)
+- A PDF with a real text layer. Scanned PDFs need OCR first, for example with [ocrmypdf](https://github.com/ocrmypdf/OCRmyPDF).
+
+Installing pulls in PyTorch for Kokoro, so expect a download of several hundred MB. On the first Kokoro run the voice model (about 330 MB) downloads once from Hugging Face.
+
+## Install
+
+Install the tools first:
+
+```powershell
+# Windows
+winget install Gyan.FFmpeg
+winget install eSpeak-NG.eSpeak-NG
+# then open a new terminal so ffmpeg is on your PATH
+```
+
+On macOS use `brew install ffmpeg espeak-ng`; on Debian/Ubuntu use `sudo apt install ffmpeg espeak-ng`.
+
+Then install Narrapy into a Python 3.10-3.12 virtual environment:
+
+```bash
+python -m venv .venv
+# Windows: .venv\Scripts\activate    macOS/Linux: source .venv/bin/activate
+pip install narrapy
+```
+
+### From source
+
+```bash
+git clone https://github.com/rakishere/narrapy.git
+cd narrapy
+python -m venv .venv
+pip install -e .
+```
+
+On Windows, `run.ps1` runs Narrapy with the project's `.venv` without activating it, e.g. `.\run.ps1 "book.pdf" --preview`.
+
+## Usage
+
+```bash
+narrapy --help                                     # all options and the list of voices
+narrapy "book.pdf" --list-chapters                 # check the chapters look right
+narrapy "book.pdf" --dump-text                     # review the cleaned text
+narrapy "book.pdf" --preview --voice am_michael    # 1-minute voice sample from the book
+narrapy "book.pdf" --voice am_michael --speed 1.1  # make the audiobook
+```
+
+The result is saved next to the PDF as `book.m4b`.
+
+Skip front or back matter (preface, notes, index) with `--start-page` and `--end-page`:
+
+```bash
+narrapy "book.pdf" --voice bf_emma --start-page 9 --end-page 212
+```
+
+Use Piper instead of Kokoro (download a voice into `./voices` first):
+
+```bash
+python -m piper.download_voices --download-dir voices en_US-lessac-medium
+narrapy "book.pdf" --engine piper --piper-model voices/en_US-lessac-medium.onnx
+```
+
+### Choosing a voice
+
+Play a short sample of each voice (Ctrl+C stops):
+
+```bash
+narrapy voices --group best             # the 6 best voices
+narrapy voices                          # all English Kokoro voices + Piper voices in ./voices
+narrapy voices --group british          # also: american, piper
+narrapy voices am_michael bm_george     # only these voices
+narrapy voices --text "Your own sentence" --speed 1.1
+```
+
+Samples are saved in `~/.cache/narrapy/voice_samples` and reused, so replaying is instant. Playback is built in on Windows; on other systems the WAV files are saved for you to open.
+
+| Group | Kokoro voices |
+|---|---|
+| American female | af_heart (default), af_bella, af_nicole, af_aoede, af_kore, af_sarah, af_nova, af_sky, af_alloy, af_jessica, af_river |
+| American male | am_michael, am_fenrir, am_puck, am_echo, am_eric, am_liam, am_onyx, am_adam, am_santa |
+| British female | bf_emma, bf_isabella, bf_alice, bf_lily |
+| British male | bm_george, bm_fable, bm_lewis, bm_daniel |
+
+Good starting points: af_heart, af_bella, am_michael, am_fenrir, bf_emma, bm_george.
+
+### All options
+
+| Option | Description |
+|---|---|
+| `--engine {kokoro,piper}` | Text-to-speech engine (default: kokoro) |
+| `--voice VOICE` | Kokoro voice (default: af_heart) |
+| `--piper-model PATH` | Piper `.onnx` voice file (required with `--engine piper`) |
+| `--speed SPEED` | Reading speed, e.g. 0.9 or 1.15 |
+| `--format {m4b,mp3}` | One `.m4b` with chapters, or one MP3 per chapter |
+| `--bitrate BITRATE` | Audio bitrate (default: 64k, plenty for speech) |
+| `--output PATH` | Output file (m4b) or folder (mp3) |
+| `--title`, `--author` | Override the PDF metadata |
+| `--start-page`, `--end-page` | Page range to read (1-based) |
+| `--pages-per-part N` | Part size when the PDF has no chapters (default: 15) |
+| `--no-announce` | Don't read the chapter title at the start of each chapter |
+| `--list-chapters` | Show detected chapters and exit |
+| `--dump-text` | Save the cleaned text to `book.cleaned.txt` and exit |
+| `--preview` | Make a ~1 minute sample from the first chapter and exit |
+| `--keep-work` | Keep the per-chapter WAV files after finishing |
+| `--version` | Show the version |
+
+## How long does it take?
+
+Kokoro runs on the CPU. On a 10-core laptop it produces about 1.5 minutes of audio per minute, so a 285-page book (about 8.5 hours of audio) takes roughly 6 hours. Piper is several times faster. Runs are resumable, so you can stop and continue later - just keep the same `--voice` and `--speed`.
+
+## Troubleshooting
+
+- **`No module named 'soundfile'` (or similar)** - you ran the system Python. Activate the virtual environment first, or use `run.ps1` from a source checkout.
+- **"An Application Control policy has blocked this file"** - Windows Smart App Control blocked a new, unsigned spaCy DLL. Install an older build: `pip install "spacy==3.8.7"`.
+- **"No module named pip" on the first Kokoro run** - Kokoro downloads the spaCy English model with pip. Environments made by `uv venv` have no pip; run `python -m ensurepip` or `uv pip install pip`, then retry.
+- **"Cleanup: removed ... espeak-ng.dll temp folder(s)"** - harmless and Windows-only. Kokoro's phonemizer copies espeak-ng.dll to a temp folder and can't delete it at exit while it is still loaded, so Narrapy removes those folders on the next run.
+- **"Almost no text found"** - the PDF is scanned images. Run OCR on it first.
+
+## Project layout
+
+| File | Purpose |
+|---|---|
+| `src/narrapy/cli.py` | The converter: text extraction, cleanup, chapters, TTS, packaging |
+| `src/narrapy/voices.py` | `narrapy voices`: make and play short samples of each voice |
+| `src/narrapy/espeak_fix.py` | Quiets a harmless Windows espeak-ng cleanup error |
+| `run.ps1` | Windows launcher for a source checkout |
+
+## License
+
+MIT. Kokoro-82M is Apache 2.0; Piper voices have their own licenses listed on their model pages. Only convert books you have the right to use.

narrapy-0.1.0/README.md

@@ -0,0 +1,149 @@
+# Narrapy
+
+Turn any text-based PDF into an audiobook on your own computer. Narrapy reads the PDF, cleans up the text, detects chapters, narrates each chapter with a local neural voice ([Kokoro](https://huggingface.co/hexgrad/Kokoro-82M) or [Piper](https://github.com/rhasspy/piper)), and packages everything into a single `.m4b` audiobook with chapter markers, title, and author.
+
+No cloud services, no API keys. After the first run it works fully offline.
+
+## Features
+
+- **Chapters, automatically.** Uses the PDF's built-in table of contents first. If there isn't one, it looks for "Chapter 3" or "Part Two" style headings. As a last resort it splits the book into 15-page parts so you can still skip around.
+- **Clean narration.** Removes running headers and footers, page numbers, and citation markers like `[12]`. Rejoins hyphenated words and replaces URLs with the word "link" so they aren't read out letter by letter.
+- **Resumable.** A long book can take hours on CPU. If a run stops, run the same command again and finished chapters are skipped.
+- **Voice sampler.** Listen to a short sample of every voice before choosing one.
+- **Two engines.** Kokoro (default, higher quality) or Piper (faster, lighter).
+- **M4B or MP3.** One `.m4b` with chapters for audiobook players, or one MP3 per chapter.
+
+## Requirements
+
+- Python 3.10, 3.11, or 3.12 (Kokoro doesn't support 3.13+ yet)
+- [ffmpeg](https://ffmpeg.org/) on your PATH
+- [espeak-ng](https://github.com/espeak-ng/espeak-ng/releases) (Kokoro uses it for unusual words)
+- A PDF with a real text layer. Scanned PDFs need OCR first, for example with [ocrmypdf](https://github.com/ocrmypdf/OCRmyPDF).
+
+Installing pulls in PyTorch for Kokoro, so expect a download of several hundred MB. On the first Kokoro run the voice model (about 330 MB) downloads once from Hugging Face.
+
+## Install
+
+Install the tools first:
+
+```powershell
+# Windows
+winget install Gyan.FFmpeg
+winget install eSpeak-NG.eSpeak-NG
+# then open a new terminal so ffmpeg is on your PATH
+```
+
+On macOS use `brew install ffmpeg espeak-ng`; on Debian/Ubuntu use `sudo apt install ffmpeg espeak-ng`.
+
+Then install Narrapy into a Python 3.10-3.12 virtual environment:
+
+```bash
+python -m venv .venv
+# Windows: .venv\Scripts\activate    macOS/Linux: source .venv/bin/activate
+pip install narrapy
+```
+
+### From source
+
+```bash
+git clone https://github.com/rakishere/narrapy.git
+cd narrapy
+python -m venv .venv
+pip install -e .
+```
+
+On Windows, `run.ps1` runs Narrapy with the project's `.venv` without activating it, e.g. `.\run.ps1 "book.pdf" --preview`.
+
+## Usage
+
+```bash
+narrapy --help                                     # all options and the list of voices
+narrapy "book.pdf" --list-chapters                 # check the chapters look right
+narrapy "book.pdf" --dump-text                     # review the cleaned text
+narrapy "book.pdf" --preview --voice am_michael    # 1-minute voice sample from the book
+narrapy "book.pdf" --voice am_michael --speed 1.1  # make the audiobook
+```
+
+The result is saved next to the PDF as `book.m4b`.
+
+Skip front or back matter (preface, notes, index) with `--start-page` and `--end-page`:
+
+```bash
+narrapy "book.pdf" --voice bf_emma --start-page 9 --end-page 212
+```
+
+Use Piper instead of Kokoro (download a voice into `./voices` first):
+
+```bash
+python -m piper.download_voices --download-dir voices en_US-lessac-medium
+narrapy "book.pdf" --engine piper --piper-model voices/en_US-lessac-medium.onnx
+```
+
+### Choosing a voice
+
+Play a short sample of each voice (Ctrl+C stops):
+
+```bash
+narrapy voices --group best             # the 6 best voices
+narrapy voices                          # all English Kokoro voices + Piper voices in ./voices
+narrapy voices --group british          # also: american, piper
+narrapy voices am_michael bm_george     # only these voices
+narrapy voices --text "Your own sentence" --speed 1.1
+```
+
+Samples are saved in `~/.cache/narrapy/voice_samples` and reused, so replaying is instant. Playback is built in on Windows; on other systems the WAV files are saved for you to open.
+
+| Group | Kokoro voices |
+|---|---|
+| American female | af_heart (default), af_bella, af_nicole, af_aoede, af_kore, af_sarah, af_nova, af_sky, af_alloy, af_jessica, af_river |
+| American male | am_michael, am_fenrir, am_puck, am_echo, am_eric, am_liam, am_onyx, am_adam, am_santa |
+| British female | bf_emma, bf_isabella, bf_alice, bf_lily |
+| British male | bm_george, bm_fable, bm_lewis, bm_daniel |
+
+Good starting points: af_heart, af_bella, am_michael, am_fenrir, bf_emma, bm_george.
+
+### All options
+
+| Option | Description |
+|---|---|
+| `--engine {kokoro,piper}` | Text-to-speech engine (default: kokoro) |
+| `--voice VOICE` | Kokoro voice (default: af_heart) |
+| `--piper-model PATH` | Piper `.onnx` voice file (required with `--engine piper`) |
+| `--speed SPEED` | Reading speed, e.g. 0.9 or 1.15 |
+| `--format {m4b,mp3}` | One `.m4b` with chapters, or one MP3 per chapter |
+| `--bitrate BITRATE` | Audio bitrate (default: 64k, plenty for speech) |
+| `--output PATH` | Output file (m4b) or folder (mp3) |
+| `--title`, `--author` | Override the PDF metadata |
+| `--start-page`, `--end-page` | Page range to read (1-based) |
+| `--pages-per-part N` | Part size when the PDF has no chapters (default: 15) |
+| `--no-announce` | Don't read the chapter title at the start of each chapter |
+| `--list-chapters` | Show detected chapters and exit |
+| `--dump-text` | Save the cleaned text to `book.cleaned.txt` and exit |
+| `--preview` | Make a ~1 minute sample from the first chapter and exit |
+| `--keep-work` | Keep the per-chapter WAV files after finishing |
+| `--version` | Show the version |
+
+## How long does it take?
+
+Kokoro runs on the CPU. On a 10-core laptop it produces about 1.5 minutes of audio per minute, so a 285-page book (about 8.5 hours of audio) takes roughly 6 hours. Piper is several times faster. Runs are resumable, so you can stop and continue later - just keep the same `--voice` and `--speed`.
+
+## Troubleshooting
+
+- **`No module named 'soundfile'` (or similar)** - you ran the system Python. Activate the virtual environment first, or use `run.ps1` from a source checkout.
+- **"An Application Control policy has blocked this file"** - Windows Smart App Control blocked a new, unsigned spaCy DLL. Install an older build: `pip install "spacy==3.8.7"`.
+- **"No module named pip" on the first Kokoro run** - Kokoro downloads the spaCy English model with pip. Environments made by `uv venv` have no pip; run `python -m ensurepip` or `uv pip install pip`, then retry.
+- **"Cleanup: removed ... espeak-ng.dll temp folder(s)"** - harmless and Windows-only. Kokoro's phonemizer copies espeak-ng.dll to a temp folder and can't delete it at exit while it is still loaded, so Narrapy removes those folders on the next run.
+- **"Almost no text found"** - the PDF is scanned images. Run OCR on it first.
+
+## Project layout
+
+| File | Purpose |
+|---|---|
+| `src/narrapy/cli.py` | The converter: text extraction, cleanup, chapters, TTS, packaging |
+| `src/narrapy/voices.py` | `narrapy voices`: make and play short samples of each voice |
+| `src/narrapy/espeak_fix.py` | Quiets a harmless Windows espeak-ng cleanup error |
+| `run.ps1` | Windows launcher for a source checkout |
+
+## License
+
+MIT. Kokoro-82M is Apache 2.0; Piper voices have their own licenses listed on their model pages. Only convert books you have the right to use.

narrapy-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "narrapy"
+version = "0.1.0"
+description = "Turn PDFs into audiobooks with chapters, using local neural text-to-speech (Kokoro or Piper)."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Rakesh Sharma" }]
+requires-python = ">=3.10,<3.13"
+keywords = ["pdf", "audiobook", "tts", "text-to-speech", "kokoro", "piper", "m4b"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+]
+dependencies = [
+    "pymupdf",
+    "soundfile",
+    "numpy",
+    "kokoro",
+    "piper-tts",
+]
+
+[project.urls]
+Homepage = "https://github.com/rakishere/narrapy"
+Issues = "https://github.com/rakishere/narrapy/issues"
+
+[project.scripts]
+narrapy = "narrapy.cli:main"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/narrapy", "README.md", "LICENSE", "pyproject.toml"]

narrapy-0.1.0/src/narrapy/__init__.py

@@ -0,0 +1,3 @@
+"""narrapy - Turn PDFs into audiobooks with local neural text-to-speech."""
+
+__version__ = "0.1.0"

narrapy-0.1.0/src/narrapy/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

narrapy-0.1.0/src/narrapy/cli.py

@@ -0,0 +1,450 @@
+#!/usr/bin/env python3
+"""
+narrapy - Convert a PDF into an audiobook (M4B with chapters, or MP3s)
+using fully local text-to-speech: Kokoro or Piper.
+
+Usage examples:
+    narrapy book.pdf
+    narrapy book.pdf --voice am_michael --speed 1.1
+    narrapy book.pdf --engine piper --piper-model voices/en_US-lessac-medium.onnx
+    narrapy book.pdf --list-chapters          (preview chapters, no audio)
+    narrapy book.pdf --preview                (short voice sample)
+    narrapy book.pdf --start-page 5 --end-page 250 --format mp3
+    narrapy voices --group best               (listen to voices before choosing)
+
+ffmpeg must be installed and on your PATH, and espeak-ng for Kokoro.
+
+Long books take a while. If the run stops, run the same command again:
+finished chapters are kept in the work folder and skipped.
+"""
+
+import argparse
+import re
+import shutil
+import subprocess
+import sys
+import wave
+from collections import Counter
+from pathlib import Path
+
+import numpy as np
+import pymupdf
+import soundfile as sf
+
+from . import __version__
+from .espeak_fix import quiet_espeak_cleanup
+from .voices import main as voices_main, voice_list_text
+
+
+# ---------------------------------------------------------------------------
+# 1. Text extraction and cleanup
+# ---------------------------------------------------------------------------
+
+def normalize_for_compare(line):
+    """Turn a line into a pattern so 'Page 12' and 'Page 13' look identical."""
+    return re.sub(r"\d+", "#", line.strip().lower())
+
+
+def page_blocks(page):
+    """Return the text blocks of a page, in reading order, as plain strings."""
+    blocks = page.get_text("blocks", sort=True)
+    return [b[4].strip() for b in blocks if b[6] == 0 and b[4].strip()]
+
+
+def find_repeated_edges(doc, first, last):
+    """Detect running headers and footers: short blocks that repeat at the top
+    or bottom of many pages."""
+    counts = Counter()
+    pages = 0
+    for i in range(first, last + 1):
+        blocks = page_blocks(doc[i])
+        if not blocks:
+            continue
+        pages += 1
+        edges = set(blocks[:2] + blocks[-2:])
+        for b in edges:
+            if len(b) < 120:
+                counts[normalize_for_compare(b)] += 1
+    if pages < 4:
+        return set()
+    return {text for text, n in counts.items() if n >= max(3, pages * 0.3)}
+
+
+PAGE_NUMBER = re.compile(r"^(page\s*)?\d+(\s*(of|/)\s*\d+)?$", re.IGNORECASE)
+
+
+def clean_block(text):
+    """Make one block of PDF text speakable."""
+    text = re.sub(r"(\w)-\n(\w)", r"\1\2", text)        # re-join hyphenated words
+    text = text.replace("\n", " ")                       # lines -> one paragraph
+    text = re.sub(r"https?://\S+|www\.\S+", "link", text)  # don't read URLs aloud
+    text = re.sub(r"\[\d+(,\s*\d+)*\]", "", text)        # citation markers [12]
+    text = text.replace("\u00ad", "")                    # soft hyphens
+    text = re.sub(r"[\u2013\u2014]", ", ", text)         # long dashes -> pause
+    text = re.sub(r"\s+", " ", text)
+    text = re.sub(r"\s+([.,;:!?])", r"\1", text)          # "link ." -> "link."
+    return text.strip()
+
+
+def extract_pages(doc, first, last):
+    """Return {page_index: [clean paragraphs]} for the page range."""
+    repeated = find_repeated_edges(doc, first, last)
+    pages = {}
+    for i in range(first, last + 1):
+        paragraphs = []
+        for block in page_blocks(doc[i]):
+            if PAGE_NUMBER.match(block.strip()):
+                continue
+            if normalize_for_compare(block) in repeated:
+                continue
+            cleaned = clean_block(block)
+            if len(re.sub(r"\W", "", cleaned)) >= 2:
+                paragraphs.append(cleaned)
+        pages[i] = paragraphs
+    return pages
+
+
+# ---------------------------------------------------------------------------
+# 2. Chapter detection
+# ---------------------------------------------------------------------------
+
+HEADING = re.compile(
+    r"^(chapter|part|section|book)\s+([0-9ivxlcdm]+|one|two|three|four|five|six|"
+    r"seven|eight|nine|ten|eleven|twelve)\b",
+    re.IGNORECASE,
+)
+
+
+def chapters_from_toc(doc, first, last):
+    """Use the PDF's built-in table of contents (bookmarks), top level only."""
+    toc = [t for t in doc.get_toc(simple=True) if t[2] > 0]
+    if not toc:
+        return []
+    top = min(t[0] for t in toc)
+    entries = [(title.strip(), page - 1) for lvl, title, page in toc if lvl == top]
+    entries = [(t, p) for t, p in entries if first <= p <= last]
+    if len(entries) < 2:
+        return []
+    chapters = []
+    if entries[0][1] > first:
+        chapters.append(("Opening", first, entries[0][1] - 1))
+    for n, (title, start) in enumerate(entries):
+        end = entries[n + 1][1] - 1 if n + 1 < len(entries) else last
+        if end < start:            # two chapters starting on the same page
+            end = start
+        chapters.append((title, start, end))
+    return chapters
+
+
+def chapters_from_headings(pages):
+    """Fallback: look for short blocks like 'Chapter 3' or 'PART TWO'."""
+    starts = []
+    for i, paragraphs in pages.items():
+        for p in paragraphs[:3]:
+            if len(p) < 80 and HEADING.match(p):
+                starts.append((p, i))
+                break
+    if len(starts) < 2:
+        return []
+    keys = sorted(pages)
+    first, last = keys[0], keys[-1]
+    chapters = []
+    if starts[0][1] > first:
+        chapters.append(("Opening", first, starts[0][1] - 1))
+    for n, (title, start) in enumerate(starts):
+        end = starts[n + 1][1] - 1 if n + 1 < len(starts) else last
+        chapters.append((title, start, end))
+    return chapters
+
+
+def chapters_by_page_count(first, last, size):
+    """Last resort: fixed-size parts so the player still has navigation."""
+    chapters = []
+    for n, start in enumerate(range(first, last + 1, size), 1):
+        chapters.append((f"Part {n}", start, min(start + size - 1, last)))
+    return chapters
+
+
+def build_chapters(doc, pages, first, last, pages_per_part):
+    chapters = chapters_from_toc(doc, first, last)
+    source = "PDF table of contents"
+    if not chapters:
+        chapters = chapters_from_headings(pages)
+        source = "chapter headings in the text"
+    if not chapters:
+        chapters = chapters_by_page_count(first, last, pages_per_part)
+        source = f"fixed parts of {pages_per_part} pages"
+
+    result = []
+    for title, start, end in chapters:
+        text = "\n".join(p for i in range(start, end + 1) for p in pages.get(i, []))
+        if text.strip():
+            result.append({"title": title, "start": start, "end": end, "text": text})
+    return result, source
+
+
+# ---------------------------------------------------------------------------
+# 3. Text-to-speech engines (both run locally)
+# ---------------------------------------------------------------------------
+
+class KokoroEngine:
+    """Kokoro-82M. Model downloads once from Hugging Face on first run,
+    then works offline from the local cache."""
+
+    sample_rate = 24000
+
+    def __init__(self, voice, speed):
+        from kokoro import KPipeline
+        lang = voice[0] if voice and voice[0] in "abefhijpz" else "a"
+        self.pipeline = KPipeline(lang_code=lang)
+        self.voice = voice
+        self.speed = speed
+        self.pause = np.zeros(int(self.sample_rate * 0.25), dtype=np.float32)
+
+    def synthesize(self, text, wav_path):
+        with sf.SoundFile(wav_path, "w", samplerate=self.sample_rate,
+                          channels=1, subtype="PCM_16") as out:
+            for result in self.pipeline(text, voice=self.voice, speed=self.speed,
+                                        split_pattern=r"\n+"):
+                audio = result[2] if isinstance(result, tuple) else result.audio
+                if audio is None:
+                    continue
+                if hasattr(audio, "cpu"):
+                    audio = audio.cpu().numpy()
+                out.write(np.asarray(audio, dtype=np.float32))
+                out.write(self.pause)
+
+
+class PiperEngine:
+    """Piper. Needs a voice file (.onnx) with its .onnx.json next to it."""
+
+    def __init__(self, model_path, speed):
+        from piper import PiperVoice
+        model = Path(model_path)
+        if not model.exists():
+            sys.exit(f"Piper voice not found: {model}")
+        self.voice = PiperVoice.load(str(model))
+        self.length_scale = 1.0 / speed
+        self.sample_rate = self.voice.config.sample_rate
+
+    def synthesize(self, text, wav_path):
+        with wave.open(str(wav_path), "wb") as wav_file:
+            if hasattr(self.voice, "synthesize_wav"):          # piper-tts 1.3+
+                from piper import SynthesisConfig
+                cfg = SynthesisConfig(length_scale=self.length_scale)
+                self.voice.synthesize_wav(text, wav_file, syn_config=cfg)
+            else:                                              # piper-tts 1.2
+                self.voice.synthesize(text, wav_file, length_scale=self.length_scale,
+                                      sentence_silence=0.25)
+
+
+# ---------------------------------------------------------------------------
+# 4. Packaging with ffmpeg
+# ---------------------------------------------------------------------------
+
+def ffmeta_escape(value):
+    return re.sub(r"([=;#\\\n])", r"\\\1", str(value))
+
+
+def safe_name(text, limit=60):
+    text = re.sub(r'[<>:"/\\|?*\x00-\x1f]', "", text).strip().rstrip(".")
+    return (text or "untitled")[:limit]
+
+
+def run_ffmpeg(args):
+    cmd = ["ffmpeg", "-hide_banner", "-loglevel", "error", "-y"] + args
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        sys.exit(f"ffmpeg failed:\n{result.stderr}")
+
+
+def build_m4b(chapter_wavs, titles, out_path, work_dir, book_title, author, bitrate):
+    list_file = work_dir / "concat.txt"
+    list_file.write_text(
+        "".join(f"file '{w.resolve().as_posix()}'\n" for w in chapter_wavs),
+        encoding="utf-8")
+
+    lines = [";FFMETADATA1",
+             f"title={ffmeta_escape(book_title)}",
+             f"album={ffmeta_escape(book_title)}",
+             f"artist={ffmeta_escape(author)}",
+             "genre=Audiobook", ""]
+    position = 0
+    for wav, title in zip(chapter_wavs, titles):
+        length = int(sf.info(str(wav)).duration * 1000)
+        lines += ["[CHAPTER]", "TIMEBASE=1/1000",
+                  f"START={position}", f"END={position + length}",
+                  f"title={ffmeta_escape(title)}", ""]
+        position += length
+    meta_file = work_dir / "chapters.txt"
+    meta_file.write_text("\n".join(lines), encoding="utf-8")
+
+    run_ffmpeg(["-f", "concat", "-safe", "0", "-i", str(list_file),
+                "-i", str(meta_file), "-map", "0:a",
+                "-map_metadata", "1", "-map_chapters", "1",
+                "-c:a", "aac", "-b:a", bitrate, "-ac", "1",
+                "-movflags", "+faststart", "-f", "mp4", str(out_path)])
+    return position / 1000
+
+
+def build_mp3s(chapter_wavs, titles, out_dir, book_title, author, bitrate):
+    out_dir.mkdir(parents=True, exist_ok=True)
+    total = 0.0
+    for n, (wav, title) in enumerate(zip(chapter_wavs, titles), 1):
+        target = out_dir / f"{n:02d} - {safe_name(title)}.mp3"
+        run_ffmpeg(["-i", str(wav), "-c:a", "libmp3lame", "-b:a", bitrate,
+                    "-metadata", f"title={title}", "-metadata", f"album={book_title}",
+                    "-metadata", f"artist={author}", "-metadata", f"track={n}",
+                    "-metadata", "genre=Audiobook", str(target)])
+        total += sf.info(str(wav)).duration
+    return total
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+EXAMPLES = """examples:
+  narrapy book.pdf --list-chapters              check the detected chapters
+  narrapy book.pdf --dump-text                  review the cleaned text
+  narrapy book.pdf --preview --voice bf_emma    1-minute voice sample
+  narrapy book.pdf --voice am_michael --speed 1.1 --end-page 212
+  narrapy book.pdf --engine piper --piper-model voices/en_US-lessac-medium.onnx
+
+listen to voices before choosing one (plays a ~10 second sample of each):
+  narrapy voices --group best                   the 6 best (also: all, american, british, piper)
+  narrapy voices af_heart bm_george             only these voices
+  narrapy voices --help                         all sample options
+"""
+
+
+def parse_args(argv=None):
+    p = argparse.ArgumentParser(
+        prog="narrapy",
+        description="Convert a PDF into an audiobook with local TTS.",
+        epilog=EXAMPLES + "\n" + voice_list_text(),
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("pdf", help="Path to the PDF file")
+    p.add_argument("--engine", choices=["kokoro", "piper"], default="kokoro")
+    p.add_argument("--voice", default="af_heart",
+                   help="Kokoro voice, e.g. af_heart, af_bella, am_michael, am_fenrir, "
+                        "bf_emma, bm_george (default: af_heart)")
+    p.add_argument("--piper-model", help="Path to a Piper .onnx voice file")
+    p.add_argument("--speed", type=float, default=1.0, help="Reading speed, e.g. 0.9 or 1.15")
+    p.add_argument("--format", choices=["m4b", "mp3"], default="m4b")
+    p.add_argument("--bitrate", default="64k", help="Audio bitrate (64k is plenty for speech)")
+    p.add_argument("--output", help="Output file (m4b) or folder (mp3)")
+    p.add_argument("--title", help="Book title (default: PDF metadata or file name)")
+    p.add_argument("--author", help="Author (default: PDF metadata)")
+    p.add_argument("--start-page", type=int, default=1, help="First page to read (1-based)")
+    p.add_argument("--end-page", type=int, help="Last page to read (1-based)")
+    p.add_argument("--pages-per-part", type=int, default=15,
+                   help="Part size when the PDF has no chapters (default: 15)")
+    p.add_argument("--no-announce", action="store_true",
+                   help="Don't read the chapter title at the start of each chapter")
+    p.add_argument("--list-chapters", action="store_true",
+                   help="Show detected chapters and exit (no audio)")
+    p.add_argument("--dump-text", action="store_true",
+                   help="Save the cleaned text to a .txt file to review, then exit")
+    p.add_argument("--preview", action="store_true",
+                   help="Make a ~1 minute sample from the first chapter and exit")
+    p.add_argument("--keep-work", action="store_true",
+                   help="Keep the per-chapter WAV files after finishing")
+    p.add_argument("--version", action="version", version=f"narrapy {__version__}")
+    return p.parse_args(argv)
+
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else argv
+    if argv and argv[0] == "voices":
+        return voices_main(argv[1:])
+    quiet_espeak_cleanup()
+    args = parse_args(argv)
+    pdf_path = Path(args.pdf)
+    if not pdf_path.exists():
+        sys.exit(f"File not found: {pdf_path}")
+    if shutil.which("ffmpeg") is None and not (args.list_chapters or args.dump_text):
+        sys.exit("ffmpeg was not found. Install it and make sure it is on your PATH.")
+    if args.engine == "piper" and not args.piper_model:
+        sys.exit("--piper-model is required with --engine piper")
+
+    doc = pymupdf.open(str(pdf_path))
+    first = max(args.start_page, 1) - 1
+    last = min(args.end_page or doc.page_count, doc.page_count) - 1
+    meta = doc.metadata or {}
+    book_title = args.title or (meta.get("title") or "").strip() or pdf_path.stem
+    author = args.author or (meta.get("author") or "").strip() or "Unknown"
+
+    print(f"Reading '{pdf_path.name}' pages {first + 1} to {last + 1}...")
+    pages = extract_pages(doc, first, last)
+    total_chars = sum(len(p) for ps in pages.values() for p in ps)
+    if total_chars < 200:
+        sys.exit("Almost no text found. This PDF is probably scanned images and "
+                 "needs OCR first (for example with ocrmypdf).")
+
+    chapters, source = build_chapters(doc, pages, first, last, args.pages_per_part)
+    print(f"Found {len(chapters)} chapters using {source}.")
+    print(f"About {total_chars:,} characters, roughly {total_chars / 900 / 60:.1f} hours of audio.\n")
+
+    if args.list_chapters:
+        for n, ch in enumerate(chapters, 1):
+            print(f"{n:3d}. {ch['title'][:60]:<60} pages {ch['start'] + 1}-{ch['end'] + 1}"
+                  f" ({len(ch['text']):,} chars)")
+        return
+
+    if args.dump_text:
+        txt_path = pdf_path.with_suffix(".cleaned.txt")
+        with open(txt_path, "w", encoding="utf-8") as f:
+            for ch in chapters:
+                f.write(f"===== {ch['title']} =====\n\n{ch['text']}\n\n")
+        print(f"Cleaned text saved to {txt_path}")
+        return
+
+    if args.engine == "kokoro":
+        engine = KokoroEngine(args.voice, args.speed)
+    else:
+        engine = PiperEngine(args.piper_model, args.speed)
+
+    if args.preview:
+        sample = chapters[0]["text"][:1000].rsplit(" ", 1)[0]
+        out = pdf_path.with_name(f"{pdf_path.stem}_preview.wav")
+        engine.synthesize(sample, out)
+        print(f"Preview saved to {out}")
+        return
+
+    work_dir = pdf_path.with_name(f"{pdf_path.stem}_audiobook_work")
+    work_dir.mkdir(exist_ok=True)
+
+    chapter_wavs, titles = [], []
+    for n, ch in enumerate(chapters, 1):
+        wav = work_dir / f"{n:03d}.wav"
+        titles.append(ch["title"])
+        chapter_wavs.append(wav)
+        if wav.exists():
+            print(f"[{n}/{len(chapters)}] {ch['title'][:50]} (already done, skipping)")
+            continue
+        print(f"[{n}/{len(chapters)}] {ch['title'][:50]}...", flush=True)
+        text = ch["text"] if args.no_announce else f"{ch['title']}.\n{ch['text']}"
+        tmp = work_dir / f"{n:03d}.partial.wav"
+        engine.synthesize(text, tmp)
+        tmp.replace(wav)             # only mark done once the chapter is complete
+
+    print("\nPackaging audiobook...")
+    if args.format == "m4b":
+        out_path = Path(args.output) if args.output else pdf_path.with_suffix(".m4b")
+        seconds = build_m4b(chapter_wavs, titles, out_path, work_dir,
+                            book_title, author, args.bitrate)
+    else:
+        out_path = Path(args.output) if args.output else pdf_path.with_name(
+            f"{safe_name(book_title)} - MP3")
+        seconds = build_mp3s(chapter_wavs, titles, out_path, book_title, author, args.bitrate)
+
+    if not args.keep_work:
+        shutil.rmtree(work_dir, ignore_errors=True)
+
+    h, m = divmod(int(seconds) // 60, 60)
+    print(f"Done! {out_path} ({h}h {m}m, {len(chapters)} chapters)")
+
+
+if __name__ == "__main__":
+    main()

narrapy-0.1.0/src/narrapy/espeak_fix.py

@@ -0,0 +1,56 @@
+"""
+Quiet a harmless Windows-only cleanup error from phonemizer (used by Kokoro).
+
+phonemizer copies espeak-ng.dll into a temp folder and tries to delete it at
+exit while the DLL is still loaded, which prints "Access is denied" tracebacks
+and leaves the folder behind. We silence that cleanup and, on the next run,
+remove the folders earlier runs left behind (their DLLs are unloaded by then).
+"""
+
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+
+def _patch_phonemizer():
+    try:
+        from phonemizer.backend.espeak.api import EspeakAPI
+    except ImportError:
+        return
+    delete = EspeakAPI._delete
+
+    def quiet_delete_win32(self):
+        try:
+            delete(self._library, self._tempdir)
+        except OSError:
+            pass
+
+    EspeakAPI._delete_win32 = quiet_delete_win32
+
+
+def _remove_leftovers():
+    removed = 0
+    for folder in Path(tempfile.gettempdir()).glob("tmp*"):
+        try:
+            files = list(folder.iterdir()) if folder.is_dir() else []
+        except OSError:
+            continue
+        if len(files) == 1 and files[0].name == "espeak-ng.dll":
+            try:
+                shutil.rmtree(folder)   # fails if another run still has it loaded
+                removed += 1
+            except OSError:
+                pass
+    if removed:
+        print(f"Cleanup: removed {removed} leftover espeak-ng.dll temp folder(s) from earlier runs.\n"
+              "  Kokoro's phonemizer copies espeak-ng.dll to a temp folder while it runs and\n"
+              "  cannot delete it at exit because Windows keeps a loaded DLL locked.\n"
+              "  This is harmless and does not affect the audio.\n")
+
+
+def quiet_espeak_cleanup():
+    if sys.platform != "win32":
+        return
+    _remove_leftovers()
+    _patch_phonemizer()

narrapy-0.1.0/src/narrapy/voices.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""
+narrapy voices - Make and play a short sample of each voice so you can pick one.
+
+Usage examples:
+    narrapy voices                         (all English Kokoro voices + Piper voices)
+    narrapy voices af_heart bm_george      (only these voices)
+    narrapy voices --group british         (american, british, best, piper)
+    narrapy voices --text "Chapter one. It was a bright cold day in April."
+    narrapy voices --no-play               (just save the WAV files)
+    narrapy voices --list                  (print the voice list and exit)
+
+Samples are saved in ~/.cache/narrapy/voice_samples and reused, so replaying is instant.
+"""
+
+import argparse
+import hashlib
+import sys
+from pathlib import Path
+
+SAMPLE_DIR = Path.home() / ".cache" / "narrapy" / "voice_samples"
+PIPER_DIR = Path("voices")   # Piper voices are looked up in ./voices of the current folder
+
+KOKORO_VOICES = {
+    "American female": ["af_heart", "af_bella", "af_nicole", "af_aoede", "af_kore", "af_sarah",
+                        "af_nova", "af_sky", "af_alloy", "af_jessica", "af_river"],
+    "American male": ["am_michael", "am_fenrir", "am_puck", "am_echo", "am_eric", "am_liam",
+                      "am_onyx", "am_adam", "am_santa"],
+    "British female": ["bf_emma", "bf_isabella", "bf_alice", "bf_lily"],
+    "British male": ["bm_george", "bm_fable", "bm_lewis", "bm_daniel"],
+}
+BEST = ["af_heart", "af_bella", "am_michael", "am_fenrir", "bf_emma", "bm_george"]
+
+DEFAULT_TEXT = ("It was a quiet evening when the letter finally arrived. She read it twice, "
+                "smiled, and put the kettle on. Some news deserves a cup of tea.")
+
+KOKORO_CACHE = Path.home() / ".cache/huggingface/hub/models--hexgrad--Kokoro-82M/snapshots"
+
+
+def all_kokoro():
+    return [v for group in KOKORO_VOICES.values() for v in group]
+
+
+def piper_models():
+    return sorted(PIPER_DIR.glob("*.onnx"))
+
+
+def voice_list_text():
+    downloaded = {p.stem for p in KOKORO_CACHE.glob("*/voices/*.pt")}
+    lines = ["Kokoro voices for --voice (default engine; af_heart is the default voice):"]
+    for label, names in KOKORO_VOICES.items():
+        shown = [f"{n}*" if n in downloaded else n for n in names]
+        lines.append(f"  {label + ':':<19}{', '.join(shown)}")
+    lines += [
+        f"  Best quality: {', '.join(BEST)}.",
+        "  * = already downloaded. Others download once (~0.5 MB) on first use.",
+        "  The first letter sets the language (a/b = English); use those for English books.",
+        "  Other languages exist (e.g. ef_dora Spanish, ff_siwis French, hf_alpha Hindi,",
+        "  if_sara Italian, pf_dora Portuguese); Japanese/Chinese voices need extra packages.",
+        "",
+        "Piper voices for --piper-model (in ./voices):",
+    ]
+    models = piper_models()
+    lines += [f"  {m.as_posix()}" for m in models] or ["  (none downloaded)"]
+    lines += [
+        "  Get more: python -m piper.download_voices --download-dir voices <name>",
+        "  Browse names at https://huggingface.co/rhasspy/piper-voices",
+    ]
+    return "\n".join(lines)
+
+
+def pick_voices(args):
+    """Return a list of (name, kind) where kind is 'kokoro' or a Piper model path."""
+    piper = {m.stem: m for m in piper_models()}
+    if args.voices:
+        picked = []
+        for v in args.voices:
+            if v in piper:
+                picked.append((v, piper[v]))
+            elif Path(v).suffix == ".onnx" and Path(v).exists():
+                picked.append((Path(v).stem, Path(v)))
+            elif v in all_kokoro() or (len(v) > 3 and v[2] == "_"):
+                picked.append((v, "kokoro"))
+            else:
+                sys.exit(f"Unknown voice: {v}. Run with --list to see the voices.")
+        return picked
+    group = args.group
+    if group == "american":
+        names = KOKORO_VOICES["American female"] + KOKORO_VOICES["American male"]
+    elif group == "british":
+        names = KOKORO_VOICES["British female"] + KOKORO_VOICES["British male"]
+    elif group == "best":
+        names = BEST
+    elif group == "piper":
+        names = []
+    else:
+        names = all_kokoro()
+    picked = [(n, "kokoro") for n in names]
+    if group in ("all", "piper"):
+        picked += [(m.stem, m) for m in piper_models()]
+    return picked
+
+
+def play(wav_path):
+    try:
+        import winsound
+        winsound.PlaySound(str(wav_path), winsound.SND_FILENAME)
+    except ImportError:
+        print("  (playback is only built in on Windows; open the WAV file to listen)")
+
+
+def main(argv=None):
+    try:
+        run(argv)
+    except KeyboardInterrupt:
+        print("\nStopped.")
+
+
+def run(argv=None):
+    p = argparse.ArgumentParser(prog="narrapy voices",
+                                description="Make and play a short sample of each voice.")
+    p.add_argument("voices", nargs="*",
+                   help="Voices to sample, e.g. af_heart bm_george en_US-lessac-medium "
+                        "(default: every voice in --group)")
+    p.add_argument("--group", choices=["all", "american", "british", "best", "piper"],
+                   default="all", help="Which voices to sample when none are named (default: all)")
+    p.add_argument("--text", default=DEFAULT_TEXT, help="Sentence to read in each sample")
+    p.add_argument("--speed", type=float, default=1.0, help="Reading speed, e.g. 0.9 or 1.15")
+    p.add_argument("--no-play", action="store_true", help="Only save the samples, don't play them")
+    p.add_argument("--regenerate", action="store_true", help="Remake samples even if saved ones exist")
+    p.add_argument("--list", action="store_true", help="Print the available voices and exit")
+    args = p.parse_args(argv)
+
+    if args.list:
+        print(voice_list_text())
+        return
+
+    picked = pick_voices(args)
+    if not picked:
+        sys.exit("No voices to sample.")
+
+    # Import the engines only when needed; they pull in torch and friends.
+    from .cli import KokoroEngine, PiperEngine
+    from .espeak_fix import quiet_espeak_cleanup
+    quiet_espeak_cleanup()
+
+    SAMPLE_DIR.mkdir(parents=True, exist_ok=True)
+    # Different text or speed gets its own files, so saved samples always match.
+    tag = hashlib.sha1(f"{args.text}|{args.speed}".encode()).hexdigest()[:8]
+    kokoro_by_lang = {}   # one Kokoro pipeline per language, voice switched per sample
+
+    print(f"Sampling {len(picked)} voice(s). Press Ctrl+C to stop.\n")
+    for i, (name, kind) in enumerate(picked, 1):
+        wav = SAMPLE_DIR / f"{name}_{tag}.wav"
+        if args.regenerate or not wav.exists():
+            if kind == "kokoro":
+                lang = name[0]
+                if lang not in kokoro_by_lang:
+                    kokoro_by_lang[lang] = KokoroEngine(name, args.speed)
+                engine = kokoro_by_lang[lang]
+                engine.voice = name
+            else:
+                engine = PiperEngine(kind, args.speed)
+            tmp = wav.with_suffix(".partial.wav")
+            engine.synthesize(args.text, tmp)
+            tmp.replace(wav)
+        label = "Piper" if kind != "kokoro" else "Kokoro"
+        print(f"[{i}/{len(picked)}] {name} ({label})", flush=True)
+        if not args.no_play:
+            play(wav)
+
+    print(f"\nSamples saved in {SAMPLE_DIR}")
+    print('Use one with: narrapy "book.pdf" --voice <name>')
+    print('  (Piper:     narrapy "book.pdf" --engine piper --piper-model voices/<name>.onnx)')