AccessibleHomeworkHelper

Read-along narration for study documents. Open a PDF, EPUB, Markdown, HTML or text file and it reads aloud in your browser with the current sentence highlighted, so you can follow the text with your eyes while you hear it.

Built for reading with a visual disability. Everything runs locally — no account, no upload, no network calls after setup.

• Formats: PDF, EPUB, Markdown, HTML, plain text
• Highlighting: the sentence being spoken is highlighted as it plays
• Speed: 0.8× to 2×, adjustable while reading
• Text size: five steps, from small to very large
• Reading ruler: an optional band that tracks the current line
• Keyboard driven: space, arrows, +/-
• Resumes where you left off, per document

Requirements

• Linux or macOS
• Python 3.10 or newer
• curl (to fetch the voice model)
• poppler-utils for PDF support — provides pdftotext

On Fedora or RHEL:

sudo dnf install python3 poppler-utils curl

On Debian or Ubuntu:

sudo apt install python3 python3-venv poppler-utils curl

On macOS:

brew install poppler

Setup

git clone <your-remote> AccessibleHomeworkHelper
cd AccessibleHomeworkHelper
make setup

make setup creates a virtual environment, installs the Python dependencies, and downloads a voice model (about 61 MB). It takes a couple of minutes and only needs doing once.

Doing it by hand

If you would rather not use make:

python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -r requirements.txt

mkdir -p voices
BASE=https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium
curl -L -o voices/en_US-lessac-medium.onnx      $BASE/en_US-lessac-medium.onnx
curl -L -o voices/en_US-lessac-medium.onnx.json $BASE/en_US-lessac-medium.onnx.json

A virtual environment is required rather than optional: most current distros ship an externally managed Python and will refuse a system-wide pip install (PEP 668).

Use

./ahh.sh ~/Downloads/chapter4.pdf

Your browser opens automatically. Press space to start.

./ahh.sh notes.md              # any supported format
./ahh.sh paper.pdf -r 1.2      # render 20% faster
./ahh.sh book.epub -p 9000     # different port
./ahh.sh notes.md -n           # do not open a browser

Keyboard

Key	Action
space	play / pause
← →	previous / next sentence
↑ ↓	previous / next paragraph
f	toggle auto-scroll
+ -	text size

Click any sentence to jump straight to it.

Voices

The default is en_US-lessac-medium, a good neutral American English voice. Piper has many others, including British, Australian and Indian English, at rhasspy/piper-voices.

Download the .onnx and matching .onnx.json into voices/, then:

./ahh.sh notes.pdf -v voices/en_GB-alba-medium.onnx

Quality tiers run x_low, low, medium, high. medium is the sweet spot; high sounds better but renders more slowly.

How it works

document ──▶ ingest ──▶ segment ──▶ Piper ──▶ browser
             (per        (sentences   (wav,     (plays in order,
              format)     + kinds)     cached)   highlights current)

1. Ingest converts each format to one list of typed blocks — paragraph, heading, list item, quote, code, table, image alt text.
2. Segment splits blocks into sentences, with the abbreviation and decimal handling needed to keep Dr. Smith, Fig. 2 and 3.5 amps intact.
3. Piper renders each sentence to a wav, memoised on disk by content hash. Re-reading a document costs nothing.
4. The browser plays clips in order and highlights the one sounding. Audio and highlight come from the same index, so they cannot drift apart.

Rendering runs about twice as fast as playback (RTF ≈ 0.48 on a modest CPU), and the server keeps four sentences ahead, so playback does not stall.

Code blocks and tables

Reading source code aloud line by line is miserable, so code blocks and tables are announced rather than read — "Code block, 12 lines." The text stays visible on screen. Image alt text is read, since it is often the only description of a figure.

Caching

Rendered audio lives in ~/.cache/ahh, keyed by a hash of the text, voice and speed. Delete that directory to reclaim space; it will be rebuilt on demand.

Override the location with AHH_CACHE=/somewhere/else.

Privacy

Everything is local. The document never leaves the machine, the server binds to 127.0.0.1 only, and nothing is transmitted after the one-time voice download.

Licence

Apache License 2.0 — see LICENSE.

Voice models are downloaded separately from the Piper project and carry their own licences. They are not distributed with this software.