read-aloud_skill

Overview

This skill generates a standalone HTML reader with Kokoro TTS audio and word-synced highlighting from any markdown file. It produces a single self-contained reader.html that embeds compressed audio and real-time word highlighting for listening, proofreading, or sharing. The tool runs locally and outputs a pure static file you can open in any browser.

How this skill works

The pipeline creates per-paragraph WAV chunks with Kokoro TTS, transcribes each chunk with Whisper to get drift-free word timestamps, and then assembles a single HTML file embedding an MP3 and synchronized per-word timing. The reader includes playback controls, keyboard shortcuts, and click-to-seek behavior so users can jump to any word. A small wrapper script auto-creates a virtual environment and installs dependencies on first run.

When to use it

• You want to listen to a markdown essay, article, or notes with synced highlighting.
• You need to proofread by ear to catch rhythm, tone, or awkward phrasing.
• You want a shareable, serverless audio reader (single HTML file) to distribute.
• You prefer generating lightweight, offline audio readers for accessibility testing.
• You need to convert chapters or sections into per-word-synced playback for review.

Best practices

• Run on a macOS machine with Apple Silicon (M1+) for best compatibility and performance.
• Use Python 3.13+ and install ffmpeg to produce compressed MP3 output.
• Keep paragraphs reasonably sized to improve alignment accuracy during transcription.
• Adjust --speed and --voice to match desired tone before generating the final reader.
• Use --strip-sections to exclude non-narrative headings (e.g., References) to shorten audio.

Example use cases

• Generate an audio reader for a long-form essay to proofread pacing and clarity by ear.
• Create an offline HTML reader to share a narrated version of documentation or tutorials.
• Produce a highlighted playback for accessibility reviews or user testing sessions.
• Export chapter previews from markdown files to embed in a portfolio or preview page.
• Quickly generate narrated drafts to evaluate voice, speed, and emphasis choices.