elevenlabs-tts-tool
A command-line tool for ElevenLabs text-to-speech synthesis with human-friendly voice selection.
Table of Contents
- About
- Why CLI-First?
- Use Cases
- Features
- Installation
- Configuration
- Usage
- Advanced Features
- Free Tier Limitations
- Claude Code Integration
- Library Usage
- Development
- Resources
- License
About
What is ElevenLabs?
ElevenLabs provides cutting-edge AI voice synthesis technology that generates natural-sounding speech from text. Their Turbo v2.5 model offers fast, high-quality text-to-speech with a wide variety of realistic voices.
What is elevenlabs-tts-tool?
elevenlabs-tts-tool transforms the ElevenLabs API into a professional, composable CLI tool designed for:
- Agent-Friendly Design: Structured commands and error messages enable AI agents (like Claude Code) to reason and act effectively in ReAct loops
- Composable Architecture: JSON output to stdout, logs to stderr - perfect for piping and automation
- Reusable Building Blocks: Commands serve as foundations for Claude Code skills, MCP servers, shell scripts, or custom workflows
- Dual-Mode Operation: Use as both CLI tool and Python library
- Production Quality: Type-safe with strict mypy checks, comprehensive tests, and clear error handling with suggested fixes
Why CLI-First?
Traditional API wrappers force you to write code for every interaction. CLI-first design provides:
- Immediate Productivity: Run commands without writing wrapper code
- Automation Ready: Pipe commands together in shell scripts
- Agent Integration: AI agents can invoke commands directly
- Human & Machine Friendly: Works equally well for developers and automation
Use Cases
- 🎙️ Voice Notifications: Add TTS to CI/CD pipelines and monitoring systems
- 📚 Content Creation: Generate audiobooks, podcasts, and video narration
- 🤖 AI Agent Integration: Build voice-enabled Claude Code skills and MCP servers
- 🛠️ Development Workflows: Create audio alerts for long-running processes
- 🎯 Accessibility: Convert text content to audio for accessibility features
- 🔊 Testing: Test voice UIs and audio systems
- 🔔 Claude Code Hooks: Use as notification system for Claude Code events (see Claude Code Integration)
Features
- ✅ Two Synthesis Modes: Play through speakers or save to audio file
- ✅ 8 TTS Models: Choose from quality, speed, or emotional expression models
- ✅ 42 Premium Voices: Curated selection with human-friendly names (rachel, adam, charlotte, etc.)
- ✅ Voice & Model Discovery: List voices and models with characteristics
- ✅ Emotional Expression: Use
[happy],[sad], etc. tags with v3 model - ✅ Flexible Input: Accept text from arguments or stdin (pipe support)
- ✅ CLI & Library: Use as command-line tool or import as Python library
- ✅ Type Safety: Strict mypy checks throughout
- ✅ Comprehensive Tests: Full test coverage with pytest
- ✅ Agent-Friendly Errors: Clear error messages with suggested fixes
- ✅ Modern Tooling: Built with uv, mise, click, and Python 3.13+
Installation
Prerequisites
- Python 3.13 or higher
- uv package manager
- ElevenLabs API key (get yours here)
- macOS users: FFmpeg for audio playback
# macOS: Install FFmpeg via Homebrew
brew install ffmpeg
# Linux: Install via package manager
sudo apt-get install ffmpeg # Debian/Ubuntu
sudo yum install ffmpeg # RedHat/CentOS