Interactive Reader

Interactive Reader is a local-first audiobook reader and narration studio that turns Markdown and plain text into progressively generated interactive speech with character voices, dialogue attribution, pronunciation control, and explicit human corrections.

Powered by Kokoro-82M, it produces zero-server interactive reader bundles with real-time word-level highlighting and instant click-to-seek audio navigation.

Markdown / Plain Text (.md / .txt)
                │
                ▼
      ireader document.md
        ├── chapter.html               (Interactive Reader UI)
        ├── chapter.wav                (Full Assembled Audio)
        └── chapter.ireader/           (Progressive Chunks & State)

Features

• 🎧 Interactive Playback & Highlighting: Glowing word-level highlight synchronized with speech playback and instant click-to-seek navigation.
• ⚡ Local & Offline Synthesis: 100% local neural TTS powered by Kokoro-82M with auto-detected hardware acceleration (CUDA, ROCm, XPU, Apple MPS, or CPU).
• ⏩ Progressive Generation & Resume: Start reading immediately while subsequent chunks generate in the background with adaptive priority scheduling.
• 🎭 Dialogue Attribution & Character Voices: Deterministic, rule-based dialogue detection with individual Kokoro voice profiles per character.
• 🔍 Dialogue Review & Corrections: Built-in review queue with filter buckets and explicit "Not Dialogue" prose marking.
• 🗣️ Pronunciation Studio: Phoneme-level pronunciation overrides with instant Misaki G2P preview and global cross-book reuse.
• 📚 Reusable Character Roster: Maintain a central library of character voices and activate them into any book as detached snapshots.
• 🖥️ Desktop Studio & Browser Viewing: Native desktop window mode with live Studio controls, or standalone offline browser viewing.

Installation

We recommend using uv for fast, reliable Python environment management:

git clone https://github.com/OblivCode/interactive-reader.git
cd interactive-reader

# Core installation (CLI + browser reader)
uv pip install -e .

# Add desktop window & Studio support
uv pip install -e ".[window]"

GPU Acceleration (Optional): Install the hardware-appropriate PyTorch build for your system (e.g. CUDA, ROCm, or XPU). Interactive Reader will automatically detect and utilize available acceleration.

Quick Start

# Open in Desktop Studio with live editing and dialogue review
uv run ireader chapter.md --window

# Generate reader and open in your default web browser
uv run ireader chapter.md --browser

# Specify default narrator voice and playback speed
uv run ireader chapter.md --voice am_fenrir --speed 1.15

# Use a specific narration configuration file
uv run ireader chapter.md -c my_narration_config.json

Command-Line Options

Option	Description
input_file	Path to markdown or plain-text file (required).
-w, --window	Open in native desktop window with Desktop Studio (.[window] required).
-b, --browser	Open generated reader in default web browser.
-c, --config	Path to explicit narration configuration JSON file.
-v, --voice	Default narrator Kokoro voice ID (default: am_fenrir).
-s, --speed	Initial playback speed multiplier (default: 1.0).
--code-reading-mode	Technical code reading mode: literal, structured, concise, or skip.

Desktop Studio

When launched with --window, Interactive Reader includes a visual Desktop Studio drawer:

• Characters & Voice: Cast narrator voices, edit book character profiles, and access your reusable global roster.
• Dialogue Review: Step through detected dialogue cards (Alt+N / Alt+P), assign character speakers, or mark quotes as non-dialogue prose.
• Pronunciation Editor: Inspect baseline phonemes, test custom pronunciation overrides, and audition ephemeral audio previews.
• On-Demand Regeneration: Persist configuration changes immediately while selectively regenerating only affected audio units via prefix-preserving invalidation.

Reusable Narration Settings

Interactive Reader separates active document settings from user-global libraries:

• Document Sidecars (chapter.ireader.json): Stores book-specific voice casting, dialogue overrides, and pronunciation rules.
• Global Pronunciation Lexicon (~/.interactive_reader/lexicon.json): Cross-book pronunciation rules automatically inherited by all documents.
• Reusable Character Roster (~/.interactive_reader/characters.json): Library of saved character voice profiles materialized into books on demand via Use in This Book.

Documentation

For in-depth guides and technical details:

• 🎨 Desktop Studio Guide — Complete guide to voice casting, dialogue review cards, and pronunciation tuning.
• ⚙️ Configuration Reference — Sidecar file schemas, global library storage, precedence rules, and persistence semantics.
• 🏗️ Architecture Overview — System architecture, canonical token model, pipeline transforms, and execution invariants.
• 📋 Engineering Handoff — Authoritative engineering milestones, active save-state, and verification baselines.

Development

To run the unit test suite:

uv run --extra dev pytest

License

Distributed under the MIT License. See LICENSE for details.