osay - AI Text-to-Speech

A CLI tool for AI-powered speech synthesis. Convert text to natural-sounding speech for various use cases.

Quick Reference

bash
1# Show all available options
2osay --help
3
4# Basic usage - speak text
5osay "Hello, world!"
6
7# Check pronunciation of unfamiliar words
8osay "ephemeral"
9osay "Nietzsche"
10osay "queue"
11
12# With specific voice
13osay -v coral "Welcome to the presentation."
14
15# Save as audio file
16osay -o output.mp3 "This will be saved to a file."
17
18# Replay last audio
19osay -p

Use Cases

1. Pronunciation Queries

Quickly hear correct pronunciation of unfamiliar words:

bash
1# English words
2osay "pronunciation"
3osay "worcestershire"
4
5# Names and proper nouns
6osay "Dostoevsky"
7osay "Nguyen"
8
9# Technical terms
10osay "asynchronous"
11osay "kubernetes"

2. Content Reading

Read articles, documentation, or text content aloud:

bash
1# Read a paragraph
2osay "The quick brown fox jumps over the lazy dog."
3
4# With neutral tone (no default cheerfulness)
5osay --no-instructions "This is a factual news report."
6
7# Slow and clear for comprehension
8osay --instructions "Speak slowly and clearly" "Complex technical content here."

3. Audio Generation

Create audio files for various purposes:

bash
1# Podcast intro
2osay -v onyx -o intro.mp3 "Welcome to the show."
3
4# Notification sounds
5osay -o alert.mp3 "Task completed successfully."
6
7# Voice memo
8osay -o memo.mp3 "Remember to review the pull request tomorrow."

4. Language Learning

Practice pronunciation and listening comprehension:

bash
1# Practice sentences
2osay -v coral "I'd like a cup of coffee, please."
3
4# Slow speed for beginners
5osay --instructions "Speak slowly, pausing between phrases" \
6  "Could you repeat that more slowly?"
7
8# Natural native speed
9osay --instructions "Speak at natural native speed" \
10  "I'm gonna grab a coffee real quick."

See examples/english/SENTENCES.md for practice sentence collections.

Voices

List available voices with osay -v '?'

Speech Instructions

Control tone and delivery style:

bash
1# Natural conversation
2osay --instructions "Speak naturally, like talking to a friend" "Hey, what's up?"
3
4# Professional presentation
5osay --instructions "Speak clearly and professionally" "Q4 results exceeded expectations."
6
7# Emphatic
8osay --instructions "Speak with enthusiasm" "This is amazing news!"
9
10# Neutral (disable default tone)
11osay --no-instructions "Objective statement."

Cache Management

Audio files are cached automatically in ~/.osay/audios/:

bash
1# List cached audio with metadata
2osay --list-cached
3
4# Replay most recent
5osay -p
6osay --prev
7
8# Select from cache interactively (with fzf)
9osay --play-cached
10
11# Play specific cached audio by ID
12osay --play-cached abc123

Output Formats

Use --format to specify audio format:

bash
1osay -o output.mp3 "Default format"
2osay -o speech.wav --format wav "High quality audio"
3osay -o compressed.opus --format opus "Small file size"

Input Methods

Multiple ways to provide text:

bash
1# Direct text argument
2osay "Hello, world!"
3
4# Read from file
5osay -f mytext.txt
6osay -f document.txt -v nova
7
8# Pipe from stdin
9echo "Hello from a pipe" | osay
10cat article.txt | osay -v coral
11
12# Combine with other commands
13curl -s https://example.com/quote.txt | osay

Streaming Mode

Use --no-cache for lowest latency (live streaming, no cache):

bash
1# Quick response without caching
2osay --no-cache "Instant playback!"
3
4# Useful for real-time applications
5osay --no-cache -v coral "This plays immediately"

Batch Processing

Process multiple texts:

bash
1# From file (one per line)
2while IFS= read -r line; do
3  osay "$line"
4  sleep 0.5
5done < texts.txt
6
7# Generate multiple files
8osay -o file1.mp3 "First message"
9osay -o file2.mp3 "Second message"

Configuration

API Key Management

bash
1# Setup OpenAI API key interactively
2osay --setup
3
4# Check if key is configured
5osay --show-key
6
7# Remove stored key
8osay --remove-key

Environment

• Config file: ~/.config/osay/config
• Audio cache: ~/.osay/audios/
• Environment variable: OPENAI_API_KEY (overrides config file)

Falls back to macOS say command if no OpenAI key is available.