Chapter Reader

Paste a chapter → hear it aloud → nothing leaves your Mac.

Local Mac listening app for manuscripts, articles, notes, and drafts.
Offline TTS · No API keys · Dock-ready

🚀 Get going	🖥 See the app	🛟 Stuck?	🤝 Hiring?
Start here	Preview	Fix it	Recruiter

---

🎯 Start here — 20% that gets you 80%

Goal: App in Dock, first paragraph spoken, under ~5 minutes after deps are ready.

🟢 One command (Mac) git clone https://github.com/heyitschien/chapter-reader.git cd chapter-reader ./install-mac-app.sh Needs once: macOS 12+ · Node 20+ · Python 3.10–3.12 · Homebrew recommended Step What happens 1 Sets up local TTS (Kokoro may download ~200MB once) 2 Builds Chapter Reader.app 3 Installs to ~/Applications 4 Opens the app After that: open from Applications / Dock.

Color key Meaning 🟢 Do this first 🟡 Optional path 🔵 Agents / dev 🔴 When broken Jump Go 🟢 Install 🟢 Everyday 🟡 Browser 🔵 AGENTS.md 🔴 Troubleshoot

⚠️ First open blocked by macOS?

Unsigned open-source build → right-click the app → Open → Open.

Keep this repo folder on disk — the app uses it for speech engines. If you move/rename the folder, run ./install-mac-app.sh again.

---

🖥 The app

_{Warm paper UI · library sidebar · read-along highlight · calm focus}

Window map (where to look)

Zone	Job	Cue
Sidebar	Navigate	Now Playing · chapters · Recent
Reading pane	Attention	Serif prose · green read-along mark
Player bar	Action	Play · speed · voice (Bella)

🎨 Design mock (full chrome + player)

---

✅ What you get

	Feature	Detail
🖥	Mac app	Electron window + Dock icon
▶️	Playback	Play / pause / stop · default 1.10×
📚	Library	Autosave · restore session · Recent
🔊	Engines	Kokoro → Piper (optional) → macOS say
🔒	Privacy	127.0.0.1 only · text never uploaded

---

🟢 Everyday use

#	Action
1	Open Chapter Reader from Applications / Dock
2	Paste or Open a chapter
3	Press Play — listen for pacing & awkward lines
4	Tweak speed / voice in the player bar

🔵 Agents / Codex: AGENTS.md · after setup run ./verify.sh to confirm speech.

---

🟡 Browser alternative

./setup.sh && ./start.sh

Opens http://127.0.0.1:8765/ · or double-click start.command after setup once.

Linux (browser only)

sudo apt-get install -y espeak-ng
./setup.sh && ./start.sh

---

🔵 Develop

./setup.sh
cd electron && npm install && npm run electron:dev

More: electron/README.md

📁 Project layout

chapter-reader/
├── install-mac-app.sh   ← fastest Mac path
├── setup.sh             ← Python TTS once
├── server.py            ← FastAPI on localhost
├── engines/             ← Kokoro / Piper / say
├── electron/            ← Mac desktop UI
├── static/              ← browser UI
├── AGENTS.md            ← Codex / agents
└── docs/brand|screenshots

---

🔴 Troubleshooting

Symptom	Fix
espeak-ng not found	brew install espeak-ng
Kokoro / Python error	brew install python@3.12 → rm -rf .venv && ./setup.sh
App blocked	Right-click → Open → Open
TTS error on launch	Re-run ./install-mac-app.sh from this clone
Moved the folder	Re-run ./install-mac-app.sh (rewrites reader-home.txt)
Slow first play	Normal — model warm-up / first download
Port 8765 busy	Quit other Chapter Reader / browser server

.venv/bin/python discover.py

---

🤝 Recruiter scan

Proves	How
Shipped Mac utility	Electron + offline TTS, MIT
Setup clarity	One install script + Gatekeeper notes
Support mindset	Troubleshooting table, engine fallbacks
Privacy-first	Localhost only, no cloud APIs
Writing workflow	Listen to drafts the way authors actually work

2-minute proof: ./install-mac-app.sh → paste a paragraph → Play.

Notes: docs/recruiter-notes.md

---

Privacy / scope

In scope	Out of scope
Local-only TTS, MIT	Cloud sync, accounts, SaaS
Offline after setup	App Store / notarized binary
Mac app + browser UI	Commercial adoption claims

Neural voice via Kokoro-82M when available.

---

MIT · LICENSE

GitHub · LinkedIn

_{Also used in the Printing Intelligence on Sand manuscript workflow.}

⬆ Back to top