speak-tts

name	speak-tts
description	Give your agent the ability to speak to you real-time. Talk to your Claude! Local TTS, text-to-speech, voice synthesis, audio generation with voice cloning on Apple Silicon. Use for reading articles aloud, audiobook narration, or voice responses. Runs entirely on-device via MLX - private, no API keys.

speak - Talk to your Claude!

Give your agent the ability to speak to you real-time. Local text-to-speech, voice cloning, and audio generation on Apple Silicon. Give your agent the ability to speak to you real-time. Local TTS with voice cloning on Apple Silicon.

Prerequisites

Requirement	Check	Install
Apple Silicon Mac	uname -m → arm64	Intel not supported
macOS 12.0+	sw_vers	-
sox	which sox	brew install sox
ffmpeg	which ffmpeg	brew install ffmpeg
poppler (PDF)	which pdftotext	brew install poppler

Input Sources

Source	Example
Text file	speak article.txt
Markdown	speak doc.md
Direct string	speak "Hello"
Clipboard	pbpaste | speak
Stdin	cat file.txt | speak

Web Articles

lynx -dump -nolist "https://example.com/article" | speak --output article.wav

Converting Formats

Format	Convert Command
PDF	pdftotext doc.pdf doc.txt
DOCX	textutil -convert txt doc.docx
HTML	pandoc -f html -t plain doc.html > doc.txt

Output Modes

Goal	Command
Save for later	speak text.txt --output file.wav
Listen now (streaming)	speak text.txt --stream
Listen now (complete)	speak text.txt --play
Both	speak text.txt --stream --output file.wav

Default Behavior

speak article.txt          # → ~/Audio/speak/article.wav (no playback)
speak "Hello"              # → ~/Audio/speak/speak_<timestamp>.wav

Directory Auto-Creation

Directory	Auto-Created?
~/Audio/speak/	✓ Yes
~/.chatter/voices/	✗ No
Custom directories	✗ No

Always create custom directories first:

mkdir -p ~/.chatter/voices/
mkdir -p ~/Audio/custom/

Voice Cloning

Voice cloning generates speech that matches your vocal characteristics (pitch, tone, cadence) from a short recording.

Quality Expectations

• Output captures general voice characteristics but is not a perfect replica
• Quality depends heavily on sample quality
• 15-25 seconds is optimal (10s minimum, 30s maximum)

Recording Your Voice

Using QuickTime:

1. Open QuickTime Player → File → New Audio Recording
2. Record 20 seconds of clear speech
3. File → Export As → Audio Only (.m4a)
4. Convert to WAV (see below)

Using sox (command line):

# -d = use default microphone
# Recording starts immediately and stops after 25 seconds
sox -d -r 24000 -c 1 ~/.chatter/voices/my_voice.wav trim 0 25

Converting to Required Format

Voice samples MUST be: WAV, 24000 Hz, mono, 10-30 seconds.

# From MP3
ffmpeg -i voice.mp3 -ar 24000 -ac 1 voice.wav

# From M4A (QuickTime)
ffmpeg -i voice.m4a -ar 24000 -ac 1 voice.wav

# Trim to 25 seconds
ffmpeg -i long.wav -t 25 -ar 24000 -ac 1 trimmed.wav

# Check sample properties
ffprobe -i voice.wav 2>&1 | grep -E "Duration|Stream"
# Should show: Duration ~15-25s, 24000 Hz, mono

Using Your Voice

# Create directory
mkdir -p ~/.chatter/voices/

# Move sample
mv voice.wav ~/.chatter/voices/my_voice.wav

# Test
speak "Testing my voice" --voice ~/.chatter/voices/my_voice.wav --stream

# Use for content
speak notes.txt --voice ~/.chatter/voices/my_voice.wav --output presentation.wav

Path requirements:

• ✓ Works: ~/.chatter/voices/my_voice.wav (tilde expanded by shell)
• ✓ Works: /Users/name/.chatter/voices/my_voice.wav
• ✗ Fails: my_voice.wav (relative path)
• ✗ Fails: ./voices/my_voice.wav (relative path)

Voice Sample Tips

Good Sample	Bad Sample
Quiet room	Background noise
Natural pace	Rushed or monotone
Clear diction	Mumbling
Varied content	Repetitive phrases

Default Voice

When --voice is omitted, a built-in default voice is used:

speak "Hello world" --stream  # Uses default voice

Emotion Tags

Tags produce audible effects (actual sounds), not spoken words:

speak "[sigh] Monday again." --stream
# Output: (sigh sound) "Monday again."

Tag	Effect
[laugh]	Laughter
[chuckle]	Light chuckle
[sigh]	Sighing
[gasp]	Gasping
[groan]	Groaning
[clear throat]	Throat clearing
[cough]	Coughing
[crying]	Crying
[singing]	Sung speech

NOT supported: [pause], [whisper] (ignored)

For pauses: Use punctuation: "Wait... let me think."

Batch Processing

mkdir -p ~/Audio/book/
speak ch01.txt ch02.txt ch03.txt --output-dir ~/Audio/book/
# Creates: ch01.wav, ch02.wav, ch03.wav

# With auto-chunking (for long files)
speak chapters/*.txt --output-dir ~/Audio/book/ --auto-chunk

# Skip completed files
speak chapters/*.txt --output-dir ~/Audio/book/ --skip-existing

Auto-Chunk Behavior

When using --auto-chunk with batch processing:

1. Each input file is chunked independently
2. Chunks are generated and automatically concatenated per file
3. Final output: one .wav per input file (e.g., ch01.wav)
4. Intermediate chunks deleted (unless --keep-chunks)

You don't need to manually concatenate chunks — only concatenate final chapter files.

Concatenating Audio

# Explicit order (recommended)
speak concat ch01.wav ch02.wav ch03.wav --output book.wav

# Glob pattern (REQUIRES zero-padded filenames)
speak concat audiobook/*.wav --output book.wav

Zero-Padding Rules

Critical for correct concatenation order:

Files	Correct	Wrong
1-9	01, 02, ..., 09	1, 2, ..., 9
10-99	01, 02, ..., 99	1, 10, 2, ...
100+	001, 002, ..., 999	1, 100, 2, ...

Why: Shell glob expansion sorts alphabetically. 1, 10, 2 vs 01, 02, 10.

PDF to Audiobook (Complete Workflow)

Step 1: Find Chapter Boundaries

# Preview table of contents
pdftotext -f 1 -l 5 textbook.pdf toc.txt
cat toc.txt  # Note chapter page numbers

# Or search for "Chapter" markers
pdftotext textbook.pdf - | grep -n "Chapter"

Step 2: Extract Chapters (Zero-Padded!)

# For 100-page book with ~10 chapters
pdftotext -f 1 -l 12 -layout textbook.pdf ch01.txt
pdftotext -f 13 -l 25 -layout textbook.pdf ch02.txt
pdftotext -f 26 -l 38 -layout textbook.pdf ch03.txt
# ... continue for all chapters

Step 3: Estimate Time

speak --estimate ch*.txt
# Shows: total audio duration, generation time, storage needed

# Quick estimates:
# 1 page ≈ 2 min audio ≈ 1 min generation
# 100 pages ≈ 200 min audio ≈ 100 min generation ≈ 500 MB

Step 4: Generate Audio

mkdir -p audiobook/
speak ch01.txt ch02.txt ch03.txt --output-dir audiobook/ --auto-chunk
# Creates: audiobook/ch01.wav, audiobook/ch02.wav, audiobook/ch03.wav

Step 5: Concatenate

speak concat audiobook/ch01.wav audiobook/ch02.wav audiobook/ch03.wav --output complete_audiobook.wav
# Or with glob (only if zero-padded):
speak concat audiobook/ch*.wav --output complete_audiobook.wav

PDF Troubleshooting

Issue	Solution
Empty/garbled text	Scanned PDF — use OCR: brew install tesseract
Wrong encoding	Try: pdftotext -enc UTF-8 doc.pdf
Check word count	pdftotext doc.pdf - | wc -w (should be >100)

Multi-Voice Content

mkdir -p podcast/scripts podcast/wav

echo "Welcome to the show." > podcast/scripts/01_host.txt
echo "Thanks for having me." > podcast/scripts/02_guest.txt

speak podcast/scripts/01_host.txt --voice ~/.chatter/voices/host.wav --output podcast/wav/01.wav
speak podcast/scripts/02_guest.txt --voice ~/.chatter/voices/guest.wav --output podcast/wav/02.wav

speak concat podcast/wav/01.wav podcast/wav/02.wav --output podcast.wav

Options Reference

Option	Description	Default
--stream	Stream as it generates	false
--play	Play after complete	false
--output <path>	Output file	~/Audio/speak/
--output-dir <dir>	Batch output directory	-
--voice <path>	Voice sample (full path)	default
--timeout <sec>	Timeout per file	300
--auto-chunk	Split long documents	false
--chunk-size <n>	Chars per chunk	6000
--resume <file>	Resume from manifest	-
--keep-chunks	Keep intermediate files	false
--skip-existing	Skip if output exists	false
--estimate	Show duration estimate	false
--dry-run	Preview only	false
--quiet	Suppress output	false

Commands

Command	Description
speak setup	Set up environment
speak health	Check system status
speak models	List TTS models
speak concat	Concatenate audio
speak daemon kill	Stop TTS server
speak config	Show configuration

Performance

Metric	Value
Cold start	~4-8s
Warm start	~3-8s
Speed	0.3-0.5x RTF (faster than real-time)
Storage	~2.5 MB/min, ~150 MB/hour

Resume Capability

For interrupted long generations:

# Single file with auto-chunk — use --resume
speak long.txt --auto-chunk --output book.wav
# If interrupted, manifest saved at ~/Audio/speak/manifest.json
speak --resume ~/Audio/speak/manifest.json

# Batch processing — use --skip-existing
speak ch*.txt --output-dir audiobook/ --auto-chunk
# If interrupted, re-run same command:
speak ch*.txt --output-dir audiobook/ --auto-chunk --skip-existing

Common Errors

Error	Cause	Solution
"Voice file not found"	Relative path	Use full path: ~/.chatter/voices/x.wav
"Invalid WAV format"	Wrong specs	Convert: ffmpeg -i in.wav -ar 24000 -ac 1 out.wav
"Voice sample too short"	<10 seconds	Record 15-25 seconds
"Output directory doesn't exist"	Not created	mkdir -p dirname/
"sox not found"	Not installed	brew install sox
Scrambled concat order	Non-zero-padded	Use 01, 02, not 1, 2
Timeout	>5 min generation	Use --auto-chunk or --timeout 600
"Server not running"	Stale daemon	speak daemon kill && speak health

Setup

speak "test"     # Auto-setup on first run (downloads model ~500MB)
speak setup      # Or manual setup
speak health     # Verify everything works

Server Management

Server auto-starts and shuts down after 1 hour idle.

speak health        # Check status
speak daemon kill   # Stop manually