yapbook

Your books can yap. Yap back.

Any PDF, EPUB, or arXiv paper becomes a natural-voice audiobook on your machine.
Tap your earbuds mid-listen, ask a question out loud, get an answer grounded at the
exact sentence you paused on — no spoilers past your playhead — and keep moving.

Quickstart · How it works · Browse by ear · Podcast · Agents · Roadmap

100% local. Zero accounts. Zero cloud. Zero telemetry.

Listen to your own textbooks, hands-free. Tap your earbuds, ask a question, keep moving.

yapbook turns a textbook PDF you own into a natural-voice audiobook and plays it through your earbuds while you cook, walk, or work out. When something doesn't click, you tap your earbuds: yapbook pauses, listens to your spoken question, answers it from the book, at the exact spot you were listening to, and resumes where it left off.

Think of it as a local NotebookLM Interactive Mode for your own textbooks — except it reads you the actual book, not a podcast about it, and nothing ever leaves your machine.

• 100% local. Kokoro TTS + faster-whisper + Ollama. No accounts, no uploads, no meters, no telemetry. Your books and your questions stay on your laptop.
• Math that sounds like a tutor, not symbol soup. Mainstream read-aloud tools get the majority of mathematical text wrong (0.51–0.62 word-error rate on equations). yapbook extracts formulas as LaTeX and verbalizes them ("the expectation over x of…"), and describes figures with a local vision model — built for dense ML/STEM books.
• Position-aware answers. "Wait — what did it just say?" works, because the assistant is grounded at your playhead. It won't spoil what you haven't heard yet.
• A real media session. Your earbud tap routes to yapbook like it would to Spotify — on Windows via SMTC, on macOS via Now Playing. No accessibility hacks.

Status

v0.1.0 (July 2026). The whole loop — add a PDF, listen, tap, ask, resume — works end to end and is tested against a real 548-page textbook. Windows first, macOS next.

Quickstart

# 1. Install Ollama (https://ollama.com) and pull the local models:
ollama pull qwen3:4b-instruct   # the brain
ollama pull qwen3-vl:8b-instruct              # figure descriptions (4b/2b for low-RAM machines)

# 2. Install yapbook (from GitHub until the PyPI release lands):
uv tool install "yapbook[all] @ git+https://github.com/Abinesh-L/yapbook"
# once on PyPI: uv tool install "yapbook[all]"  or  pipx install "yapbook[all]"

# 3. Check your setup:
yapbook doctor

# 4. Add a book you own — or an arXiv paper by id/URL (one-time preprocessing):
yapbook add ~/books/my-textbook.pdf
yapbook add ~/books/novel.epub        # EPUB, DOCX, PPTX, HTML, MD all work
yapbook add 2501.07088                # any arXiv id or arxiv.org URL

# 5. Put your earbuds in and go:
yapbook listen my-textbook
yapbook preview my-textbook           # or browse by ear first (see below)

Back matter nobody wants narrated (References, Acknowledgments, Index…) is auto-marked at ingest and skipped by both listen and podcast — the chapters stay in the knowledge base for Q&A. Review, toggle any chapter, or undo with yapbook skip <book> (--auto re-detects, --clear unmarks everything).

First-run footprint is roughly 10–12 GB of local models (Ollama models + Kokoro + Whisper). Everything runs on CPU; a GPU just makes it snappier.

How it works

PDF ──docling──▶ knowledge base (prose + LaTeX + figure descriptions, per chapter)
                     │
                     ▼
              Kokoro TTS ──▶ 🎧 earbuds (A2DP stereo, never degraded)
                     ▲                │ tap = play/pause (real media session)
                     │                ▼
              answer speech ◀── Ollama (chapter context, KV-prewarmed,
                                grounded at your playhead)
                                      ▲
                     laptop mic ──▶ faster-whisper (+ chapter jargon)

Design details and the reasoning behind every decision: ARCHITECTURE.md.

Why the laptop mic? Opening a Bluetooth earbud mic drops the whole headset from stereo A2DP to 8–16 kHz mono Hands-Free mode with multi-second glitches — you'd hear your book through a tin can. Your laptop is in the room; its mic hears you fine and your audio never degrades. (--earbud-mic exists if you really want it.)

The web UI — no terminal after install

pip install "yapbook[ui]"   # included in [all]
yapbook ui                  # opens http://127.0.0.1:8765 in your browser

Everything point-and-click, on a page served from your own machine (it also works in VS Code's built-in Simple Browser): drag-and-drop a PDF/EPUB/DOCX onto the page to ingest it with live progress, see your library with reading positions, edit chapter skip lists with checkboxes, generate and read chapter previews, and export a podcast with a QR code — point your phone's camera at it and the book is in your podcast app. The [▶ Listen] button opens the earbud session in its own window.

Local-only by design: the UI binds 127.0.0.1 and rejects foreign Host/Origin headers (DNS-rebinding protection); the podcast feed on its own port is the only thing your network can see, and only while you're sharing it.

Browse by ear

Not sure where to dive in? yapbook preview my-textbook speaks a ~30-second summary of each chapter — generated locally from the chapter's own text, never from the title — so you can find the chapter you want without opening a screen. --chapter 7 previews one chapter, --text prints instead of speaking (handy for scripts and agents). Summaries are cached per book and regenerate automatically if you change the brain model.

Listen on your phone (podcast export)

Every book can become a private podcast — one episode per chapter, plus an RSS feed:

yapbook podcast my-rl-book --serve
# Serving on http://192.168.1.23:8321/feed.xml
# Add that URL in your podcast app (same WiFi). Ctrl+C to stop.

Any podcast app then gives you offline downloads, background play, and lock-screen controls — no yapbook client on the phone at all. Chapters you've already listened to export instantly from the audio cache. MP3 episodes need the podcast extra (pip install "yapbook[podcast]"); without it you get (much larger) WAV files. Hosting the folder somewhere instead? --base-url bakes your URL into the feed.

Use it from your AI agent

yapbook speaks both agent dialects — a SKILL.md for skill-based agents (Claude Code, OpenClaw, Codex CLI: same file works in all three) and an MCP server (yapbook-mcp, via the mcp extra) for Claude Desktop, Odysseus, and any other MCP host: list_books, reading_status, ask_book, add_book. There's also a plain yapbook ask <book> "question" for scripts and shell-first agents.

Answers stay grounded at your listening position — an agent can't spoil what you haven't heard. Setup for each host: integrations/.

// e.g. in an MCP client config:
{ "mcpServers": { "yapbook": { "command": "yapbook-mcp" } } }

Roadmap

• v0.1 — the loop: PDF ingest, listen, tap, ask, resume (Windows + hotkey fallback); EPUB/DOCX/PPTX/HTML/MD ingest, arXiv ingest, chapter previews, skip lists, MCP server, agent skill, podcast export with LAN serving
• v0.2 — macOS Now Playing listener, cross-chapter retrieval
• v0.3 — richer phone story (streaming beyond podcasts), voice picker, more voices

Models & licenses

yapbook's code is Apache-2.0. Model weights are downloaded by you at first run, directly from their sources, under their own licenses:

Disclaimer

yapbook is a tool for personal use with documents you lawfully own. It does not circumvent DRM and will not process DRM-protected files. You are responsible for complying with the laws and license terms that apply to your documents in your jurisdiction. The generated knowledge base and audio are stored only on your machine, in your user data directory — treat them with the same care as the book itself.

Built in the open as a fun side project. Issues and PRs welcome.