# sag
> Modern text-to-speech CLI using ElevenLabs voices

## Summary
Drop-in replacement for macOS `say` using ElevenLabs AI voices. Streams high-quality speech to speakers or files with voice discovery, speed control, and support for multiple TTS engines (v3, v2, v2.5 Flash/Turbo).

## Capabilities
- Stream text-to-speech audio to speakers in real-time (default behavior)
- Save audio output to MP3 or WAV files with format auto-detection
- Voice discovery and search with --try flag to preview voices
- Multiple TTS engines: v3 (most expressive), v2 (stable), v2.5 Flash (75ms latency), v2.5 Turbo
- Speed control (0.5x-2.0x), stability, similarity, and style tuning
- SSML support for v2/v2.5 and audio tags for v3
- Read text from arguments, files, or piped stdin
- Multilingual support with ISO 639-1 language codes
- Latency tier adjustment for streaming optimization
- Performance metrics output

## When to Use
- You need high-quality AI-generated speech from the command line
- Creating voiceover audio files for presentations or content
- Adding spoken notifications to scripts or automation
- Previewing and selecting from a library of AI voices
- Need lower latency than cloud TTS web interfaces

## When NOT to Use
- No ElevenLabs API key is available
- Working offline without internet access
- macOS built-in `say` command quality is sufficient
- Processing very large texts (v3 limited to 5,000 characters per request)

## Usage Patterns
### Basic speech
```
sag "Hello, world!"
```
Speaks the text aloud using the default voice and engine

### Use a specific voice
```
sag speak -v Roger "Welcome to the demo"
```
Speaks using the named voice Roger

### Save to file
```
sag -o output.mp3 "Save this as an audio file"
```
Generates speech and saves it as an MP3 file

### Search for voices
```
sag voices --search english --limit 20
```
Lists up to 20 English-language voices available

### Preview voices
```
sag voices --query "narrator" --limit 5 --try
```
Finds narrator-style voices and plays a sample of each

### Pipe text from stdin
```
echo "Read this text" | sag speak -v Roger
```
Reads and speaks text piped from stdin

### Adjust speed
```
sag speak -v Roger --speed 1.3 "A bit faster please"
```
Speaks at 1.3x speed

## Input / Output
- **stdin**: Text to be spoken (when using -f - or piping)
- **stdout**: Audio stream to speakers (default) or file
- **stderr**: Performance metrics (with --metrics) and status messages

## Installation
- **homebrew**: `brew install steipete/tap/sag`
- **go**: `go install github.com/steipete/sag/cmd/sag@latest`

---
Source: https://littlescripts.sh/tools/sag
