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

Global Options

Voices and Models

Voices

Models

Audio Formats

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

Dennis Vriend - GitHub