Binge Docs 🎧

Listen to deployed MkDocs documentation from your terminal. Binge Docs removes visual content, then streams the useful prose through Kokoro.

🚀 Install

Requires Python 3.10–3.13, internet access for initial downloads, and audio output.

uv tool install .

On Debian or Ubuntu, install PortAudio first:

sudo apt-get install portaudio19-dev

For development:

uv sync
uv run binge-docs --help

The first playback downloads about 120 MB of Kokoro model files.

📚 Listen

Browse any deployed MkDocs site interactively:

binge-docs listen https://fastapi.tiangolo.com/
binge-docs listen https://doughayden.github.io/agent-foundation/

Open a page directly with a relative path or full URL:

binge-docs listen https://sqlmodel.tiangolo.com/ --page tutorial/
binge-docs listen https://typer.tiangolo.com/ \
  --page https://typer.tiangolo.com/tutorial/first-steps/

Use --voice and --speed to customize playback:

binge-docs listen https://fastapi.tiangolo.com/ \
  --page tutorial/first-steps/ --voice bf_emma --speed 1.2

Speed must be between 0.5 and 2.0. Defaults are af_heart and 1.0.

⌨️ Controls

• space: pause or resume
• + / -: change speed for upcoming audio
• q: stop cleanly
• Ctrl+C: force stop

🛠️ Commands

binge-docs listen MKDOCS_URL [--page PAGE] [--voice VOICE] [--speed SPEED]
binge-docs voices
binge-docs setup
binge-docs --version

binge-docs setup downloads or repairs checksum-verified model files.

💾 Offline Use

Catalogs and pages are cached for 24 hours. If a refresh fails, Binge Docs uses stale cached content with a warning. Pages that have never been opened cannot be played offline.

🔎 What Gets Read

Binge Docs reads headings, prose, lists, notes, link labels, and inline code. It skips navigation, code blocks, terminal output, tables, images, scripts, and other visual controls.