skill-openai-tts-tool

What this skill does

# When to use
- When you need to convert text to speech using OpenAI's TTS API
- When you need to list available voices and models
- When you need to check API configuration

# OpenAI TTS Tool Skill

## Purpose

A comprehensive CLI utility for text-to-speech synthesis using OpenAI's advanced TTS models. Supports multiple voices, languages, and output formats with professional-grade audio quality.

## When to Use This Skill

**Use this skill when:**
- Converting text documents to audio for accessibility
- Creating voice-overs for presentations or videos
- Generating speech samples for testing or development
- Batch processing multiple text inputs to audio
- Needing high-quality TTS with natural-sounding voices

**Do NOT use this skill for:**
- Real-time streaming TTS (this tool processes complete text)
- Voice cloning or custom voice creation
- Speech recognition or transcription
- Audio editing or post-processing

## CLI Tool: openai-tts-tool

A modern Python CLI tool for accessing OpenAI's Text-to-Speech API with comprehensive features including multiple voice models, configurable output formats, and extensive customization options.

### Installation

```bash
# Clone repository
git clone https://github.com/dnvriend/openai-tts-tool.git
cd openai-tts-tool

# Install with mise
mise use -g [email protected]
uv sync
uv tool install .

# Or run locally
uv run openai-tts-tool --help
```

### Prerequisites

- Python 3.14+ installed
- OpenAI API key (set as OPENAI_API_KEY environment variable)
- `mise` for Python version management (recommended)
- `uv` package manager for modern Python dependency management

### Quick Start

```bash
# Basic text-to-speech conversion
openai-tts-tool synthesize "Hello, world!"

# Check API configuration
openai-tts-tool info

# List available voices
openai-tts-tool list-voices
```

## Progressive Disclosure

<details>
<summary><strong>📖 Core Commands (Click to expand)</strong></summary>

### synthesize - Convert Text to Speech

The primary command for converting text input into high-quality audio files using OpenAI's TTS models.

**Usage:**
```bash
openai-tts-tool synthesize TEXT [OPTIONS]
```

**Arguments:**
- `TEXT`: The text content to convert to speech (required). Can be a single word, sentence, or full paragraph.

**Options:**
- `--voice VOICE` / `-V VOICE`: Select voice model (default: alloy)
  - Available voices: alloy, echo, fable, onyx, nova, shimmer
- `--model MODEL` / `-m MODEL`: Choose TTS model (default: tts-1)
  - `tts-1`: Standard quality, lower latency
  - `tts-1-hd`: Higher quality, slightly higher cost
- `--output FILE` / `-o FILE`: Output audio file path (default: output.mp3)
  - Supports: .mp3, .wav, .ogg, .flac formats
- `--speed SPEED` / `-s SPEED`: Speech playback speed (default: 1.0)
  - Range: 0.25 (very slow) to 4.0 (very fast)
  - Recommended: 0.8-1.2 for natural speech

**Examples:**
```bash
# Basic usage with default settings
openai-tts-tool synthesize "Welcome to our presentation"

# Use specific voice and output file
openai-tts-tool synthesize "Chapter 1: Introduction" \
  --voice nova \
  --output chapter1.mp3

# High-quality model with slower speech
openai-tts-tool synthesize "Important safety information" \
  --model tts-1-hd \
  --speed 0.8 \
  --voice onyx

# Multiple sentences for narration
openai-tts-tool synthesize "In today's lecture, we will explore the fascinating world of artificial intelligence and its impact on modern society." \
  --voice shimmer \
  --output narration.mp3

# Batch processing (loop in shell)
for text in "Hello" "Goodbye" "Thank you"; do
  openai-tts-tool synthesize "$text" --output "${text}.mp3"
done
```

**Output:**
Generates an audio file in the specified format containing the synthesized speech. The file quality and characteristics depend on the selected model and voice options.

---

### list-voices - Display Available Voices

List all available OpenAI TTS voice models with their characteristics and language support.

**Usage:**
```bash
openai-tts-tool list-voices [OPTIONS]
```

**Options:**
- `--format FORMAT` / `-f FORMAT`: Output display format
  - `table`: Human-readable table format (default)
  - `json`: Machine-readable JSON format for scripting

**Examples:**
```bash
# Show voices in table format
openai-tts-tool list-voices

# Export voice information to JSON
openai-tts-tool list-voices --format json > voices.json

# Filter for English voices using jq
openai-tts-tool list-voices --format json | \
  jq '.[] | select(.language | startswith("en"))'

# Get voice descriptions only
openai-tts-tool list-voices --format json | \
  jq -r '.[] | "\(.name): \(.description)"'
```

**Output:**
Returns a list of available voices including:
- Voice name (alloy, echo, fable, onyx, nova, shimmer)
- Description of voice characteristics
- Supported languages and accents
- Recommended use cases

---

### list-models - Display Available TTS Models

Show all available OpenAI TTS models with their specifications and capabilities.

**Usage:**
```bash
openai-tts-tool list-models [OPTIONS]
```

**Options:**
- `--format FORMAT` / `-f FORMAT`: Output display format
  - `table`: Human-readable table format (default)
  - `json`: Machine-readable JSON format for scripting

**Examples:**
```bash
# Show models in table format
openai-tts-tool list-models

# Export model information to JSON
openai-tts-tool list-models --format json > models.json

# Compare model capabilities
openai-tts-tool list-models --format json | \
  jq '.[] | {name: .name, quality: .quality, latency: .latency}'

# Get HD model information only
openai-tts-tool list-models --format json | \
  jq '.[] | select(.name | contains("hd"))'
```

**Output:**
Returns available TTS models including:
- Model identifier (tts-1, tts-1-hd)
- Audio quality characteristics
- Latency and performance information
- Cost differences and use case recommendations

---

### info - System Configuration and Status

Display current configuration, API key status, and system information.

**Usage:**
```bash
openai-tts-tool info [OPTIONS]
```

**Options:**
- `--format FORMAT` / `-f FORMAT`: Output display format
  - `table`: Human-readable table format (default)
  - `json`: Machine-readable JSON format for scripting

**Examples:**
```bash
# Show basic system information
openai-tts-tool info

# Check API key status for automation
openai-tts-tool info --format json | jq '.api_key.status'

# Verify configuration before batch processing
if openai-tts-tool info --format json | jq -e '.api_key.valid'; then
  echo "API key valid, starting batch processing..."
else
  echo "API key invalid, please check configuration"
fi

# Get version information
openai-tts-tool info --format json | jq '.version'
```

**Output:**
Returns system configuration including:
- API key validation status
- Tool version information
- Supported output formats
- Network connectivity status
- Rate limiting information

---

### completion - Shell Auto-Completion

Generate shell completion scripts to enable tab completion for bash, zsh, and fish shells.

**Usage:**
```bash
openai-tts-tool completion SHELL
```

**Arguments:**
- `SHELL`: Target shell type (required)
  - `bash`: Generate bash completion script
  - `zsh`: Generate zsh completion script
  - `fish`: Generate fish completion script

**Examples:**
```bash
# Generate bash completion and eval immediately
eval "$(openai-tts-tool completion bash)"

# Save completion to permanent file
openai-tts-tool completion zsh > ~/.oh-my-zsh/completions/_openai-tts-tool

# Install fish completion
openai-tts-tool completion fish > ~/.config/fish/completions/openai-tts-tool.fish

# Add to bashrc for permanent installation
echo 'eval "$(openai-tts-tool completion bash)"' >> ~/.bashrc

# Test completion generation
openai-tts-tool completion bash | head -10
```

**Output:**
Returns a shell-specific completion script that provides:
- Command and subcommand completion
- Option flag completion
- Argument suggestions where applicable
- Help text display