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, and get an answer grounded at the
exact sentence you paused on. No spoilers past your playhead. Then it keeps reading.

Quickstart · Commands · How it works · Brains · Podcast · Agents

100% local by default. Zero accounts. Zero telemetry.

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

yapbook turns a book 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 library, except it reads you the actual book, not a podcast about it, and by default nothing leaves your machine.

• Local by default. Kokoro TTS + faster-whisper + Ollama. No accounts, no uploads, no meters, no telemetry. Your books and your questions stay on your laptop. (Prefer an API brain? See Choose your brain.)
• Math that sounds like a tutor, not symbol soup. Mainstream read-aloud tools get most mathematical text wrong (0.51–0.62 word-error rate on equations). yapbook extracts formulas as LaTeX, 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 the same way it would to Spotify: SMTC on Windows, Now Playing on macOS. No accessibility hacks.

Status

v0.1.1 (August 2026). The whole loop works end to end and is tested against a real 548-page textbook: add a book, listen, tap, ask, resume. Windows first, macOS next.

Quickstart

# 1. Install yapbook:
uv tool install "yapbook[all]"        # or: pipx install "yapbook[all]"

# 2. Set up the local AI stack (installs/starts Ollama, pulls models — asks first):
yapbook setup

# 3. 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

# 4. Put your earbuds in and go:
yapbook listen my-textbook
yapbook ui                            # or do everything from the browser instead

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 or toggle with yapbook skip <book>.

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. Using an API brain instead cuts that roughly in half.

Every command

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 ◀── the brain (chapter context, grounded at
                                your playhead; local Ollama by default)
                                      ▲
                     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.)

Choose your brain

The Q&A brain is pluggable. Local is the default; an API key is one config change:

# Default: local and private via Ollama (qwen3:4b-instruct)
yapbook config brain_model qwen3:8b-instruct     # or any stronger local model

# Or bring your own key — any OpenAI-compatible endpoint works
# (OpenAI, OpenRouter, Groq, LM Studio, a llama.cpp server, ...):
yapbook config brain_provider openai
yapbook config brain_api_url https://openrouter.ai/api/v1
yapbook config brain_model qwen/qwen3-30b-a3b
yapbook config brain_api_key sk-...              # or env var YAPBOOK_BRAIN_API_KEY

Good to know:

• Only the question-answering brain switches. Narration, transcription, and your library never leave your machine, whichever brain you pick.
• With an API brain, your spoken questions and the heard-so-far chapter text are sent to that provider. That's the trade; yapbook won't make it silently, you configure it.
• Figure descriptions during ingest still use the local vision model, so yapbook setup keeps Ollama around for ingest even in API mode.
• YAPBOOK_BRAIN_API_KEY beats brain_api_key, so the key can stay out of config.toml.

The web UI — no terminal after install

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 book to ingest it with live progress, see your library with reading positions, edit chapter skip lists with checkboxes, generate and read chapter previews, remove books, 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 from the chapter's own text rather than its title, so you can find the chapter you want without opening a screen. --chapter 7 previews one chapter; --text prints instead of speaking. 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, with 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 (included in [all]); 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; the 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, exposing list_books, reading_status, ask_book, and add_book. There's also plain yapbook ask <book> "question" for scripts and shell-first agents.

Answers stay grounded at your listening position, so 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: ingest (PDF/EPUB/DOCX/PPTX/HTML/MD/arXiv), listen, tap, ask, resume; web UI, chapter previews, skip lists, podcast export, MCP server, agent skill, pluggable brains, guided setup (Windows + hotkey fallback)
• 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.