openai-tts-tool
A command-line interface for OpenAI Text-to-Speech API.
Features
- Convert text to natural-sounding speech
- Six high-quality voices with different characteristics
- Two TTS models (tts-1 and tts-1-hd) for speed vs quality
- Multiple audio formats: mp3, opus, aac, flac
- Stream to speakers or save to files
- Adjustable speech speed (0.25 to 4.0)
- Multi-level verbosity logging
- Shell completion support
Installation
# Prerequisites
# - Python 3.14+
# - uv package manager
# Clone and install globally
git clone https://github.com/dnvriend/openai-tts-tool.git
cd openai-tts-tool
uv tool install .
# Verify installation
openai-tts-tool --version
Configuration
Set the OpenAI API key:
export OPENAI_API_KEY="your-api-key-here"
# Add to shell profile for persistence
echo 'export OPENAI_API_KEY="your-api-key-here"' >> ~/.bashrc # or ~/.zshrc
source ~/.bashrc # or ~/.zshrc
Usage
# Basic synthesis (stream to speakers)
openai-tts-tool synthesize "Hello, world!"
# Save to file with specific voice
openai-tts-tool synthesize "Hello, world!" --voice nova --output hello.mp3
# High-quality synthesis with custom settings
openai-tts-tool synthesize "Welcome" \
--voice alloy \
--model tts-1-hd \
--output welcome.mp3 \
--format mp3 \
--speed 1.2
# Read from stdin
echo "Hello from stdin" | openai-tts-tool synthesize --stdin --output hello.mp3
# List available voices and models
openai-tts-tool list-voices
openai-tts-tool list-models
# Multi-level verbosity for debugging
openai-tts-tool -v synthesize "Test" # INFO level
openai-tts-tool -vv synthesize "Test" # DEBUG level
openai-tts-tool -vvv synthesize "Test" # TRACE with library logs
Options
Synthesize Command
| Option | Short | Description |
|---|
--voice | -v | Voice to use (alloy, echo, fable, onyx, nova, shimmer) |
--model | -m | TTS model (tts-1, tts-1-hd) |
--output | -o | Output file path (default: stream to speakers) |
--format | -f | Audio format (mp3, opus, aac, flac) |
--speed | -s | Speech speed (0.25 to 4.0) |
--stdin | | Read text from stdin |
Global Options
| Option | Short | Description |
|---|
--verbose | -v | Verbose output: -v (INFO), -vv (DEBUG), -vvv (TRACE with library logs) |
--version | | Show version information |
--help | -h | Show help message |
Voices and Models
Voices
| Voice | Description |
|---|
| alloy | Balanced, natural voice (default) |
| echo | Deeper, authoritative voice |
| fable | Warm, engaging storyteller |
| onyx | Deep, confident voice |
| nova | Clear, professional voice |
| shimmer | Softer, expressive voice |
Models
| Model | Quality | Speed | Use Case |
|---|
| tts-1 | Standard | Fast | Real-time applications |
| tts-1-hd | High | Slower | High-quality audio production |
Audio Formats
| Format | Quality | Use Case |
|---|
| mp3 | Good | Maximum compatibility |
| opus | Excellent | Streaming, low bandwidth |
| aac | Very Good | Apple devices |
| flac | Lossless | High-fidelity production |
Library Usage
from openai_tts_tool import TTSClient
client = TTSClient(api_key="your-key")
# Stream to speakers
client.synthesize("Hello, world!", voice="alloy")
# Save to file
client.synthesize(
"Hello, world!",
voice="nova",
model="tts-1-hd",
output="hello.mp3",
speed=1.2
)
Development
make install # Install dependencies
make format # Format code with ruff
make lint # Run linting with ruff
make typecheck # Run type checking with mypy
make test # Run tests with pytest
make security # Run all security checks
make check # Run all checks (lint, typecheck, test, security)
make pipeline # Run full pipeline
make build # Build package
make run ARGS="..." # Run openai-tts-tool locally
License
MIT License - see the LICENSE file for details.
Author
