Read Aloud

Generate a standalone HTML reader with high-quality TTS audio and real-time word highlighting from any markdown file.

When to Use

Invoke when user:

• Asks to "read this aloud" or "generate audio" for a markdown file
• Wants to proofread by ear (catch awkward phrasing, rhythm issues)
• Needs a shareable audio reader (single HTML file, no server needed)
• Uses /read-aloud command

Prerequisites

• macOS with Apple Silicon (M1+)
• Python 3.13+ (required for MLX)
• ffmpeg (for MP3 compression)

Core Command

SKILL_DIR="path/to/read-aloud"
$SKILL_DIR/scripts/read-aloud.sh <markdown-file> [options]

First run auto-installs dependencies to ~/.read-aloud/venv/.

Options

Pipeline

Three-stage process (~2-5 min for a typical essay):

1. Generate Audio — Kokoro TTS produces per-paragraph WAV chunks
2. Align Words — Whisper transcribes each chunk for drift-free word timestamps
3. Build Reader — Assembles standalone HTML with embedded MP3 + word sync

Output

Single reader.html file with:

• Base64-embedded MP3 audio (fully standalone, no server needed)
• Per-word highlighting synced to audio playback
• Sticky playback controls (play/pause, stop, speed, progress bar)
• Keyboard shortcuts (Space, Escape, Arrow keys)
• Click any word to seek

Available Voices

Examples

# Basic usage — generates reader at ~/.read-aloud/output/my-essay/
$SKILL_DIR/scripts/read-aloud.sh ~/Documents/my-essay.md

# Custom voice and speed
$SKILL_DIR/scripts/read-aloud.sh post.md --voice bm_george --speed 1.1

# Output to specific directory
$SKILL_DIR/scripts/read-aloud.sh draft.md --output-dir ./preview/

# Strip specific sections before generating
$SKILL_DIR/scripts/read-aloud.sh post.md --strip-sections "Brief,Links & Resources"

References

• Load references/voice-guide.md for detailed voice descriptions and speed tuning
• Load references/examples.md for worked examples with expected output
• Load references/troubleshooting.md when errors occur