text-to-speech

Text to Speech

Convert text to audio. Three engine options from instant offline to high-quality cloud.

Engines Overview

Engine	Quality	Speed	Cost	Install
say (macOS)	Decent	Instant	Free	Built-in
sherpa-onnx-tts	Good	Fast	Free	pip install
ElevenLabs API	Excellent	~2s	Paid	API key

Default: use say for quick playback, save to file with -o.

Engine 1: macOS say (Built-in, No Install)

# Speak immediately
say "Hello, world!"

Save to audio file

say "Your message here" -o output.aiff

Convert to MP3 (requires ffmpeg)

say "Your message here" -o /tmp/tts.aiff && ffmpeg -y -i /tmp/tts.aiff output.mp3

List available voices

say -v ?

Use specific voice

say -v Samantha "Hello from Samantha" say -v Daniel "Hello from Daniel" say -v Mei-Jia "Hello, this is Chinese speech" say -v Kyoko "Hello, this is Japanese"

Control speed (default 200 wpm)

say -r 150 "Slower speech" say -r 250 "Faster speech"

Read from file

say -f input.txt -o output.aiff

### Popular macOS Voices
| Language | Voice | Note |
|----------|-------|------|
| English | Samantha | Default US |
| English | Daniel | UK accent |
| Chinese | Mei-Jia | Traditional Chinese |
| Chinese | Ting-Ting | Simplified Chinese |
| Japanese | Kyoko | Japanese |

## Engine 2: sherpa-onnx-tts (Local Neural TTS)

```bash
# Install
pip install sherpa-onnx

# Download a model (example: VITS English)
# See: https://k2-fsa.github.io/sherpa/onnx/tts/index.html
sherpa-onnx-tts --help

# Generate audio
sherpa-onnx-tts \
  --vits-model=./model.onnx \
  --vits-lexicon=./lexicon.txt \
  --vits-tokens=./tokens.txt \
  --output-filename=output.wav \
  "Text to convert to speech"

Engine 3: ElevenLabs API (Highest Quality)

# Requires: export ELEVENLABS_API_KEY=your_key_here

# List voices
curl -s https://api.elevenlabs.io/v1/voices \
  -H "xi-api-key: $ELEVENLABS_API_KEY" | jq '.voices[].name'

# Generate audio (Rachel voice)
curl -s -X POST \
  "https://api.elevenlabs.io/v1/text-to-speech/21m00Tcm4TlvDq8ikWAM" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Your text here", "model_id": "eleven_monolingual_v1"}' \
  -o output.mp3

Usage Examples

"Read this out loud: Good morning" (immediate playback)

say "Good morning"

"Save 'Meeting starts in 5 minutes' to audio"

say "Meeting starts in 5 minutes" -o ~/Desktop/reminder.aiff

"Generate MP3 from this text"

say "Your text here" -o /tmp/tts_out.aiff
ffmpeg -y -i /tmp/tts_out.aiff ~/Desktop/output.mp3 2>/dev/null
echo "Saved: ~/Desktop/output.mp3"

"What voices are available?"

say -v ? | head -20

"Read this in Chinese"

say -v Mei-Jia "你好，歡迎使用語音服務"

Rules

• say is always available on macOS — use it as default, no install check needed
• For file output: default save to ~/Desktop/tts_output_<timestamp>.aiff
• Convert to MP3 only if user requests it and ffmpeg is available
• If user wants higher quality, suggest sherpa-onnx or ElevenLabs
• For ElevenLabs, check ELEVENLABS_API_KEY is set before attempting API call
• Never hardcode API keys — always read from environment variable
• Long text (>500 words): warn user it may take a moment, especially for sherpa/ElevenLabs
• For non-English, default to the appropriate system voice (Mei-Jia for ZH, Kyoko for JA)