lazyread 0.2.0

Lazyread local-first listening library runtime

Lazyread

Turn a URL or Markdown file into a private listening article with natural local speech, synchronized word highlighting, auto-scroll, and saved highlights.

https://github.com/user-attachments/assets/df6f44ee-572a-4a08-a0d8-7d8acc78fb6b

Install

Lazyread currently supports Apple Silicon Macs running macOS 14 or newer. It also needs Node.js 20.19+, FFmpeg 6+, and UV.

Install the Lazyread skill globally:

npx --yes skills add https://github.com/jayfarei/lazyread/ --global --agent universal --yes

Restart your agent, then invoke the skill with a URL or Markdown file:

$lazyread https://example.com/article

On first use, Lazyread explains the local setup and asks before downloading about 5.4 GB of speech and alignment models. The skill then creates the article, waits for narration, verifies the reader, and returns a reusable local URL.

Update

If you installed the skills with the command above, update both the skills and the Lazyread runtime with:

npx --yes skills update lazyread defuddle --global --yes
uvx --refresh lazyread doctor

npx skills remembers the source of each installed skill and updates its managed copy and agent links in place. If Lazyread was installed as a persistent UV tool, run uv tool upgrade --reinstall lazyread instead of the uvx command. If the skills were installed by Lazyread itself, refresh those copies with lazyread install-skills --force instead of npx skills update.

Models, cache, and wait times

Lazyread installs two pinned MLX models into one shared cache for every article:

• Speech: mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16
• Word alignment: mlx-community/Qwen3-ForcedAligner-0.6B-8bit

The models use about 5.4 GB; allow at least 8 GB of working disk space during setup. They download only on first-time setup or after the model cache is removed. Model revisions are pinned per Lazyread release so the same input remains reproducible.

Narration is generated once and reused. Lazyread keeps temporary speech chunks so an interrupted job or alignment repair can resume without repeating valid speech generation. The finished FLAC audio and word timings are stored with the article. Each browser also downloads the complete finished track into its own Cache Storage before enabling Play; later listening is immediate and works offline in that browser.

The readable article appears within seconds, while narration continues in the background. Generation time depends on article length, Mac hardware, and cache hits. On the tested M4 Pro:

Article length	Generation time	Audio produced	Finished audio size
1,145 words	1:11	9:38	13 MB
10,068 words	70:16	108:04	125 MB

Each browser or device performs its own one-time preload of the finished audio. Run uvx lazyread storage to see the space used by articles, temporary chunks, and models.

What you get

• Natural speech generated locally on your Mac
• Word-by-word tracking and automatic scrolling
• Keyboard navigation, playback speed, and sentence highlights
• A durable private library at http://127.0.0.1:4242/library
• Optional private access through your Tailscale network

Article content, audio, highlights, and models remain on your Mac. Creating an article from a URL still accesses the original website for extraction.

The runtime is also published on PyPI. For development and release details, see design/ and RELEASING.md.

License

MIT. See THIRD_PARTY_NOTICES.md.