Metadata-Version: 2.4
Name: yapbook
Version: 0.1.0
Summary: Listen to your own textbooks, hands-free. Tap your earbuds, ask a question, keep moving. 100% local.
Project-URL: Homepage, https://github.com/Abinesh-L/yapbook
Author: Abinesh Lingeswaran
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: audiobook,kokoro,local-llm,ollama,rag,study,tts,voice,whisper
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Education
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: <3.14,>=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: numpy>=1.26
Requires-Dist: platformdirs>=4.0
Requires-Dist: sounddevice>=0.4.6
Requires-Dist: soundfile>=0.12
Provides-Extra: all
Requires-Dist: docling>=2.0; extra == 'all'
Requires-Dist: espeakng-loader>=0.2; extra == 'all'
Requires-Dist: faster-whisper>=1.0; extra == 'all'
Requires-Dist: flask>=3.0; extra == 'all'
Requires-Dist: kokoro>=0.9; extra == 'all'
Requires-Dist: lameenc>=1.6; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: pyobjc-framework-mediaplayer>=10.0; (sys_platform == 'darwin') and extra == 'all'
Requires-Dist: qrcode>=7.4; extra == 'all'
Requires-Dist: winrt-runtime>=2.0; (sys_platform == 'win32') and extra == 'all'
Requires-Dist: winrt-windows-foundation>=2.0; (sys_platform == 'win32') and extra == 'all'
Requires-Dist: winrt-windows-media-playback>=2.0; (sys_platform == 'win32') and extra == 'all'
Requires-Dist: winrt-windows-media>=2.0; (sys_platform == 'win32') and extra == 'all'
Requires-Dist: winrt-windows-storage-streams>=2.0; (sys_platform == 'win32') and extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: ingest
Requires-Dist: docling>=2.0; extra == 'ingest'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: podcast
Requires-Dist: lameenc>=1.6; extra == 'podcast'
Provides-Extra: stt
Requires-Dist: faster-whisper>=1.0; extra == 'stt'
Provides-Extra: tap-macos
Requires-Dist: pyobjc-framework-mediaplayer>=10.0; (sys_platform == 'darwin') and extra == 'tap-macos'
Provides-Extra: tap-windows
Requires-Dist: winrt-runtime>=2.0; (sys_platform == 'win32') and extra == 'tap-windows'
Requires-Dist: winrt-windows-foundation>=2.0; (sys_platform == 'win32') and extra == 'tap-windows'
Requires-Dist: winrt-windows-media-playback>=2.0; (sys_platform == 'win32') and extra == 'tap-windows'
Requires-Dist: winrt-windows-media>=2.0; (sys_platform == 'win32') and extra == 'tap-windows'
Requires-Dist: winrt-windows-storage-streams>=2.0; (sys_platform == 'win32') and extra == 'tap-windows'
Provides-Extra: tts
Requires-Dist: espeakng-loader>=0.2; extra == 'tts'
Requires-Dist: kokoro>=0.9; extra == 'tts'
Provides-Extra: ui
Requires-Dist: flask>=3.0; extra == 'ui'
Requires-Dist: qrcode>=7.4; extra == 'ui'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/logo.svg" width="140" alt="yapbook logo: an open book wearing headphones, sound rising from the page" />
</p>

<h1 align="center">yapbook</h1>

<p align="center">
  <strong>Your books can yap. Yap back.</strong>
</p>

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

<p align="center">
  <a href="#quickstart">Quickstart</a> ·
  <a href="#how-it-works">How it works</a> ·
  <a href="#browse-by-ear">Browse by ear</a> ·
  <a href="#listen-on-your-phone-podcast-export">Podcast</a> ·
  <a href="#use-it-from-your-ai-agent">Agents</a> ·
  <a href="#roadmap">Roadmap</a>
</p>

<p align="center">
  <em>100% local. Zero accounts. Zero cloud. Zero telemetry.</em>
</p>

---

**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](https://arxiv.org/abs/2501.07088)).
  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

```bash
# 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](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

```bash
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:

```bash
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/](integrations/).

```jsonc
// 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](LICENSE). Model weights are downloaded by *you* at first
run, directly from their sources, under their own licenses:

| Component | Model | License |
|---|---|---|
| Text-to-speech | Kokoro-82M | Apache-2.0 |
| Q&A brain | Qwen3 4B Instruct 2507 | Apache-2.0 |
| Figure descriptions | Qwen3-VL 8B/4B/2B | Apache-2.0 |
| Speech-to-text | Whisper small.en (faster-whisper) | MIT |
| Embeddings (optional) | nomic-embed-text | Apache-2.0 |

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