Metadata-Version: 2.4
Name: spantrack
Version: 1.0.0
Summary: Convert text EPUBs into EPUB 3 with Media Overlays via local Kokoro TTS
Project-URL: homepage, https://github.com/ozefe/spantrack
Project-URL: source, https://github.com/ozefe/spantrack
Project-URL: issues, https://github.com/ozefe/spantrack/issues
Author-email: Efe Özyay <hi@efe.cv>
License-Expression: MIT
License-File: LICENSE
Keywords: audiobook,epub,kokoro,media-overlays,tts
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: Markup
Classifier: Typing :: Typed
Requires-Python: <3.13,>=3.12
Requires-Dist: ftfy==6.3.1
Requires-Dist: kokoro==0.9.4
Requires-Dist: lxml<6,>=5
Requires-Dist: misaki[en]==0.9.4
Requires-Dist: numpy<3,>=1.26
Requires-Dist: pysbd==0.3.4
Requires-Dist: soundfile<1,>=0.12
Requires-Dist: torch<3,>=2.6
Provides-Extra: progress
Requires-Dist: tqdm<5,>=4.66; extra == 'progress'
Description-Content-Type: text/markdown

# spantrack

<img alt="spantrack logo generated by Google's Nano Banana 2" align="right" src=".github/logo.png" width="150" />

Convert a text EPUB into a self-contained EPUB 3 that narrates itself and highlights each sentence as it reads — an open, fully offline take on Kindle's Immersion Reading.

## What it does

Synchronized read-along narration, text that highlights in time with spoken audio, is effectively locked to Amazon's ecosystem and its paired audiobook purchases. spantrack builds the same thing from any DRM-free text EPUB, on your own machine: it voices the book with a local neural TTS model, wires the audio into standard [EPUB 3 Media Overlays](https://www.w3.org/TR/epub/#sec-media-overlays), and hands back a single `*.narrated.epub` that plays with correct highlighting in any Media-Overlay reader — [Thorium](https://www.edrlab.org/software/thorium-reader/) on desktop, BookFusion on mobile. No account, no cloud, no network after a one-time model download.

## Demo

https://github.com/user-attachments/assets/a1d52881-4d21-45b1-997e-f201dc9d56f8

_[Watch the demo](https://github.com/ozefe/spantrack/raw/main/.github/demo.mp4) — a spantrack read-along playing in Thorium._

## How it works

The hard part of a read-along is keeping the highlight glued to the audio. Most tools synthesize or record a whole chapter and then run a _forced aligner_ to guess where each sentence begins — which drifts (seconds of lag in comparable prior art). spantrack never aligns anything.

> [!NOTE]
> **Sync is exact by construction.** Each sentence is synthesized on its own, the chapter audio is those sentences concatenated in order, and every SMIL clip offset is the running sum of real clip durations. The timestamp _is_ the audio position, so there is nothing to drift.

The pipeline is one stage per module:

1. **Ingest** — unzip a working copy, parse the OPF, and upgrade EPUB 2 to EPUB 3 (synthesizing `nav.xhtml` from the NCX) when needed.
2. **Select** — walk the spine, skip cover / nav / front-matter by `epub:type` landmarks, and print the choice; `--include` / `--exclude` / `--pick` override it.
3. **Segment & tag** — walk block elements, split each into sentences with [pysbd](https://github.com/nipunsadvilkar/pySBD), and wrap every sentence in `<span id="sNNNNN">`, preserving all inline markup.
4. **Normalize** (TTS input only — the DOM is never touched) — expand numbers, dates, currency, roman numerals, footnote markers, and URLs; apply an optional per-book pronunciation lexicon.
5. **Synthesize** — one sentence at a time through [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) at a fixed voice, so the narrator stays consistent across the whole book. Output is content-addressed by `sha256(model · voice · speed · text)`, so a killed run resumes without re-synthesizing and identical text is never voiced twice.
6. **Assemble** — concatenate sentences with natural gaps and short edge fades, then encode one mono MP3 (or Opus) per chapter with ffmpeg.
7. **Overlay** — emit one gapless SMIL per chapter, patch the OPF (media-overlay wiring, `media:duration` / `narrator`), and inject highlight CSS.
8. **Repack & validate** — zip `mimetype`-first, then optionally gate the build on epubcheck.

Publisher CSS and markup stay byte-for-byte identical outside the injected spans, so turning narration off leaves the book looking exactly like the source.

## Install

```bash
pip install spantrack
```

spantrack's grapheme-to-phoneme step also needs spaCy's `en_core_web_sm`, which isn't published to PyPI — install the pinned wheel explicitly. Pinning keeps G2P offline and deterministic; otherwise misaki downloads a model at runtime.

```bash
pip install "en_core_web_sm @ https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl"
```

You also need:

- **ffmpeg** on your `PATH`, to encode chapter audio. Not required for `--dry-run` or `--oov-report`.
- **A JRE**, only for `--validate`, which runs [epubcheck](https://www.w3.org/publishing/epubcheck/) on the output.

The first real conversion downloads the Kokoro weights once (a few hundred MB); after that it runs fully offline. CUDA is used automatically when present, otherwise synthesis falls back to CPU.

## Usage

```bash
spantrack book.epub
```

This writes `book.narrated.epub` beside the input and a `book.epub.spantrack/` work directory holding the sentence cache and per-chapter checkpoints. Re-running resumes from there; `--clean` discards it.

Handy flags:

- `--dry-run` — print the narration set and a duration/size estimate, synthesizing nothing.
- `--oov-report` — list words the voice may mispronounce, as a lexicon skeleton to fill in.
- `--voice af_heart` / `--speed 1.1` / `--lang en-us|en-gb` — narrator, pace, and accent.
- `--lexicon words.toml` — per-book pronunciation overrides in misaki IPA.
- `--include` / `--exclude` / `--pick` — steer which documents get narrated.
- `--audio-format opus` / `--bitrate 64k` — codec and size.
- `--granularity word` — experimental word-by-word highlighting (timings drift; A/B a single chapter first).
- `--validate` — run epubcheck and fail the build on errors.
- `--progress` — a per-chapter progress bar (needs `pip install 'spantrack[progress]'`).

Run `spantrack --help` for the complete list.

## Examples

The [`examples/`](examples/) directory ships four hand-written sample books, plus short, commented Python scripts that drive the API. Convert one end to end:

```bash
spantrack examples/the-lighthouse-keeper.epub --validate
```

or just inspect the plan without synthesizing:

```bash
spantrack examples/the-pocket-anthology.epub --dry-run
```

[`examples/README.md`](examples/README.md) walks through each book and script with captured output.

## Status

> [!WARNING]
> Beta. English only, one fixed-voice narrator, and word-mode highlighting is experimental. The output validates with epubcheck and plays correctly in Thorium; the mobile (BookFusion) target is not yet validated first-hand. Interfaces may change without notice.

## License

[MIT](LICENSE).
