elevenlabs-tts-tool 0.2.0

Professional command-line tool for ElevenLabs text-to-speech synthesis

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
  • Shell Completion
  • Verbosity Levels
• Usage
  • Synthesize Command
  • List Voices
  • Update Voices
  • Model Selection
  • Subscription Info
• Advanced Features
  • Emotion Control
  • Pause Control (SSML)
• 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:

1. Immediate Productivity: Run commands without writing wrapper code
2. Automation Ready: Pipe commands together in shell scripts
3. Agent Integration: AI agents can invoke commands directly
4. 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

Install from source

# Clone the repository
git clone https://github.com/dnvriend/elevenlabs-tts-tool.git
cd elevenlabs-tts-tool

# Install globally with uv
uv tool install .

Verify installation

elevenlabs-tts-tool --version

Configuration

Set API Key

# Export API key (required for all commands)
export ELEVENLABS_API_KEY='your-api-key-here'

# Or add to your shell profile (~/.zshrc, ~/.bashrc)
echo 'export ELEVENLABS_API_KEY="your-api-key"' >> ~/.zshrc

Get your API key from: https://elevenlabs.io/app/settings/api-keys

Shell Completion

Enable tab completion for bash, zsh, or fish shells:

Bash (add to ~/.bashrc):

eval "$(elevenlabs-tts-tool completion bash)"

Zsh (add to ~/.zshrc):

eval "$(elevenlabs-tts-tool completion zsh)"

Fish (save to completion file):

mkdir -p ~/.config/fish/completions
elevenlabs-tts-tool completion fish > ~/.config/fish/completions/elevenlabs-tts-tool.fish

For better performance, save completion to a file:

# Bash
elevenlabs-tts-tool completion bash > ~/.elevenlabs-tts-tool-complete.bash
echo 'source ~/.elevenlabs-tts-tool-complete.bash' >> ~/.bashrc

# Zsh
elevenlabs-tts-tool completion zsh > ~/.elevenlabs-tts-tool-complete.zsh
echo 'source ~/.elevenlabs-tts-tool-complete.zsh' >> ~/.zshrc

Once installed, you can tab-complete commands, options, and even voice names!

Verbosity Levels

Control logging output with progressive verbosity levels:

# Default (WARNING only) - quiet mode
elevenlabs-tts-tool synthesize "Hello world"

# -v (INFO) - show high-level operations
elevenlabs-tts-tool -v synthesize "Hello world"

# -vv (DEBUG) - show detailed steps, API calls, validation
elevenlabs-tts-tool -vv synthesize "Hello world"

# -vvv (TRACE) - show full API requests/responses, library internals
elevenlabs-tts-tool -vvv synthesize "Hello world"

Verbosity Breakdown:

• No flag (default): Only warnings and errors
• -v: INFO level - operation status, file names, progress
• -vv: DEBUG level - validation steps, API call details, timing
• -vvv: TRACE level - full HTTP requests/responses, ElevenLabs SDK internals

Note: Verbosity applies to all commands:

elevenlabs-tts-tool -v list-voices      # INFO level
elevenlabs-tts-tool -vv list-models     # DEBUG level
elevenlabs-tts-tool -vvv info           # TRACE level with API details

Usage

Synthesize Command

Convert text to speech with various options:

# Basic usage - play through speakers
elevenlabs-tts-tool synthesize "Hello world"

# Use a different voice
elevenlabs-tts-tool synthesize "Hello world" --voice adam
elevenlabs-tts-tool synthesize "Cheerio mate" --voice charlotte

# Read from stdin
echo "Hello from stdin" | elevenlabs-tts-tool synthesize --stdin
cat article.txt | elevenlabs-tts-tool synthesize --stdin

# Save to MP3 file (default format)
elevenlabs-tts-tool synthesize "Save this" --output speech.mp3

# Save to WAV file (PCM format)
elevenlabs-tts-tool synthesize "Save this" --output speech.wav --format pcm_24000

# Lower quality MP3 (smaller file size)
elevenlabs-tts-tool synthesize "Save this" --output speech.mp3 --format mp3_22050_32

# Combine options
cat blog-post.txt | elevenlabs-tts-tool synthesize --stdin \
    --voice rachel --output narration.mp3 --format mp3_44100_128

Output Formats

The --format option controls audio quality and file size. Different formats require different ElevenLabs subscription tiers:

Available on all tiers:

• mp3_44100_128 - MP3 at 44.1kHz, 128kbps (default, ~17KB for short text)
• mp3_22050_32 - MP3 at 22.05kHz, 32kbps (lower quality, ~6KB for short text)
• pcm_16000 - PCM/WAV at 16kHz
• pcm_22050 - PCM/WAV at 22.05kHz
• pcm_24000 - PCM/WAV at 24kHz (~67KB for short text)
• ulaw_8000 - μ-law at 8kHz (for Twilio)

Creator tier and above:

• mp3_44100_192 - MP3 at 44.1kHz, 192kbps (higher quality)

Pro tier and above:

• pcm_44100 - PCM/WAV at 44.1kHz (highest quality, largest file size)

Examples:

# Default MP3 (works on all tiers)
elevenlabs-tts-tool synthesize "Text" --output audio.mp3

# High-quality WAV (Pro tier required)
elevenlabs-tts-tool synthesize "Text" --output audio.wav --format pcm_44100

# Lower bandwidth (works on all tiers)
elevenlabs-tts-tool synthesize "Text" --output audio.mp3 --format mp3_22050_32

List Voices

Discover available voices with characteristics:

# List all 42 available voices
elevenlabs-tts-tool list-voices

# Find specific voices with grep
elevenlabs-tts-tool list-voices | grep British
elevenlabs-tts-tool list-voices | grep "female.*young"
elevenlabs-tts-tool list-voices | grep male

Popular Voices:

• rachel - Calm and friendly American female (default)
• adam - Deep, authoritative American male
• charlotte - Seductive and calm British female
• antoni - Well-rounded American male
• bella - Soft and pleasant American female
• daniel - Deep and authoritative British male

Update Voices

Update the voice lookup table from ElevenLabs API:

# Update default voice lookup (saves to ~/.config/elevenlabs-tts-tool/)
elevenlabs-tts-tool update-voices

# Save to custom location
elevenlabs-tts-tool update-voices --output custom_voices.json

The voice lookup is stored in ~/.config/elevenlabs-tts-tool/voices_lookup.json and takes precedence over the package default.

Model Selection

ElevenLabs offers multiple TTS models optimized for different use cases. Use the --model option with the synthesize command to select a model.

List Available Models

# Show all available models with characteristics
elevenlabs-tts-tool list-models

Current Generation Models

Eleven Turbo v2.5 (Default) - eleven_turbo_v2_5

• Balanced quality and speed (~250ms latency)
• 32 languages, 40,000 char limit
• 50% cheaper per character
• Best for: General-purpose TTS

elevenlabs-tts-tool synthesize "Hello world" --model eleven_turbo_v2_5

Eleven Multilingual v2 - eleven_multilingual_v2

• Highest production quality
• 29 languages, 10,000 char limit
• Medium latency
• Best for: Professional content, e-learning

elevenlabs-tts-tool synthesize "Professional narration" --model eleven_multilingual_v2

Eleven Flash v2.5 - eleven_flash_v2_5

• Ultra-low latency (~75ms)
• 32 languages, 40,000 char limit
• 50% cheaper per character
• Best for: Real-time agents, bulk processing

elevenlabs-tts-tool synthesize "Quick response" --model eleven_flash_v2_5

Eleven v3 (Alpha) - eleven_v3

• Most emotionally expressive
• 70+ languages, 5,000 char limit
• Higher latency
• Best for: Emotional dialogue, audiobooks
• Note: Supports emotional tags ([happy], [sad], etc.)

elevenlabs-tts-tool synthesize "[happy] Welcome!" --model eleven_v3

Model Selection Examples

# Use highest quality model
elevenlabs-tts-tool synthesize "Professional presentation" \
    --voice rachel --model eleven_multilingual_v2

# Ultra-fast real-time generation
elevenlabs-tts-tool synthesize "Quick notification" \
    --voice adam --model eleven_flash_v2_5

# Emotional expression (requires v3)
elevenlabs-tts-tool synthesize "[excited] Congratulations!" \
    --voice charlotte --model eleven_v3 --output celebration.mp3

# Pipe with model selection
echo "Article content" | elevenlabs-tts-tool synthesize --stdin \
    --voice daniel --model eleven_multilingual_v2 --output article.mp3

Legacy Models

The following models are deprecated but still available:

• eleven_turbo_v2 - Superseded by Turbo v2.5 (50% cost savings)
• eleven_flash_v2 - Superseded by Flash v2.5
• eleven_monolingual_v1 - English-only (use eleven_multilingual_v2 instead)
• eleven_multilingual_v1 - Use eleven_multilingual_v2 instead

Warning: Using deprecated models will show a deprecation notice. Migrate to current generation models for better performance and pricing.

For detailed model information, see: references/models.md

Subscription Info

View your ElevenLabs subscription status and usage statistics:

# View subscription info with last 7 days of usage
elevenlabs-tts-tool info

# View last 30 days of usage
elevenlabs-tts-tool info --days 30

# Quick quota check
elevenlabs-tts-tool info --days 1

Information Displayed:

• Subscription Details: Tier, status, voice slots, currency
• Character Usage: Used/limit/remaining with percentage and visual bar
• Quota Reset: When your character quota resets
• Historical Usage: Daily usage breakdown for specified period
• Usage Statistics: Average daily usage and projected monthly consumption
• Warnings: Alerts when approaching quota limits (>75% or >90%)

Example Output:

================================================================================
ElevenLabs Subscription Information
================================================================================

Tier:           Free
Status:         Active

Character Usage:
  Used:         8,543 characters
  Limit:        10,000 characters
  Remaining:    1,457 characters
  Percentage:   85.4%
  [████████████████████████████████████░░░░]

Quota Resets:   2025-11-22 00:00:00
                (Friday, November 22, 2025)

Voice Slots:    3
Currency:       USD

================================================================================
Historical Usage (Last 7 Days)
================================================================================

Date            Characters Used      Bar
--------------------------------------------------------------------------------
2025-11-15           1,234 chars    ██████████████████████████████
2025-11-14             892 chars    ████████████████████
2025-11-13           1,567 chars    ██████████████████████████████
...
--------------------------------------------------------------------------------
Total:               8,543 chars

Average daily usage: 1,220 characters
Projected monthly:   36,600 characters

================================================================================

Use Cases:

• Monitor character quota consumption
• Track usage patterns over time
• Plan when to upgrade subscription tier
• Avoid hitting quota limits unexpectedly
• Understand daily/monthly usage trends

Advanced Features

Emotion Control

ElevenLabs v3 model (eleven_v3) supports emotional tags for expressive speech:

# Happy greeting (requires eleven_v3 model)
elevenlabs-tts-tool synthesize "[happy] Welcome! We're excited to have you here." --model eleven_v3

# Sad message
elevenlabs-tts-tool synthesize "[sad] I'm sorry to hear that..." --model eleven_v3

# Excited announcement
elevenlabs-tts-tool synthesize "[excited] Amazing news! Your project is approved!" --model eleven_v3

Available Emotions: [happy], [excited], [sad], [angry], [nervous], [curious], [cheerfully], [playfully], [mischievously], [resigned tone], [flatly], [deadpan]

Speech Characteristics: [whispers], [laughs], [gasps], [sighs], [pauses], [hesitates], [stammers]

Important: Emotional tags only work with the eleven_v3 model. They will be ignored on other models (v2.5, v2, etc.).

Pause Control (SSML)

Add natural pauses using SSML break tags:

# Add 1-second pause
elevenlabs-tts-tool synthesize "Welcome <break time=\"1.0s\" /> to our service."

# Multiple pauses
elevenlabs-tts-tool synthesize "First point <break time=\"0.5s\" /> Second point <break time=\"0.5s\" /> Third point."

Note: Keep pauses under 3 seconds and limit to 2-4 breaks per generation for best results.

Combining Emotions and Pauses

# Emotional speech with pauses
elevenlabs-tts-tool synthesize "[happy] Good morning! <break time=\"0.5s\" /> [cheerfully] I hope you're having a great day."

For comprehensive documentation on emotions, pauses, SSML, and voice settings, see:

• Emotions and Pauses Guide

Free Tier Limitations

ElevenLabs Free Tier:

• ✅ 10,000-20,000 characters per month (as of 2024-2025)
• ✅ Access to all 42 premade voices
• ✅ Create up to 3 custom voices
• ✅ MP3 formats (all bitrates)
• ✅ Basic SSML support
• ✅ Emotional tags (v3 models)
• ❌ No commercial license
• ❌ PCM 44.1kHz format requires Pro tier
• ⚠️ Max 2,500 characters per single generation

Recommended for:

• Personal projects
• Experimentation
• Development and testing
• Non-commercial use

For detailed free tier information and upgrade options, see:

• Free Tier Research
• ElevenLabs Pricing

Claude Code Integration

Use elevenlabs-tts-tool as a notification system for Claude Code hooks to get audio alerts when tasks complete.

Setup Hook

Create a notification hook in ~/.config/claude-code/hooks.json:

{
  "hooks": {
    "after_command": {
      "type": "bash",
      "command": "elevenlabs-tts-tool synthesize \"[happy] Task completed successfully!\" --voice rachel"
    },
    "on_error": {
      "type": "bash",
      "command": "elevenlabs-tts-tool synthesize \"[nervous] Error detected. Please check the output.\" --voice adam"
    }
  }
}

Use Cases

Task Completion Alerts:

# After long-running build
elevenlabs-tts-tool synthesize "[excited] Build completed!" --voice rachel

Error Notifications:

# On test failure
elevenlabs-tts-tool synthesize "[sad] Tests failed. Please review." --voice adam

Custom Workflows:

# In your shell scripts
make build && elevenlabs-tts-tool synthesize "[cheerfully] Build successful!" || \
    elevenlabs-tts-tool synthesize "[nervous] Build failed!"

Integration with Other Tools:

# Combine with gemini-google-search-tool
gemini-google-search-tool query "Latest AI news" | \
    elevenlabs-tts-tool synthesize --stdin --voice charlotte --output news-summary.mp3

This allows you to:

• Get audio alerts for completed tasks without monitoring the terminal
• Hear error notifications while away from the screen
• Create multi-step automation workflows with voice feedback
• Build voice-enabled AI agent pipelines

Output Styles

Claude Code supports custom output styles via .claude/output-styles/ directory. Output styles allow you to customize how Claude Code responds to your requests. For comprehensive examples, see the Claude Code Hooks Mastery repository.

TTS Summary Output Style

The TTS Summary output style provides audio task completion announcements using elevenlabs-tts-tool. This creates a voice-enabled assistant experience where Claude Code speaks to you about what it accomplished.

How it works:

1. Claude Code responds normally to all requests
2. At the end of every response, it adds an audio summary
3. The summary is synthesized using elevenlabs-tts-tool synthesize
4. You hear what was accomplished without monitoring the terminal

Example Output Style Configuration:

Create .claude/output-styles/tts-summary.md:

---
name: TTS Summary
description: Audio task completion announcements with TTS
---

# TTS Summary Output Style

You are Claude Code with an experimental TTS announcement feature designed to communicate directly with the user about what you've accomplished.

## Standard Behavior
Respond normally to all user requests, using your full capabilities for:
- Code generation and editing
- File operations
- Running commands
- Analysis and explanations
- All standard Claude Code features

## Critical Addition: Audio Task Summary

**At the very END of EVERY response**, you MUST provide an audio summary for the user and run a Bash tool:

```bash
elevenlabs-tts-tool synthesize "SUMMARY_TO_THE_USER"

Important Rules

• ALWAYS include the audio summary, even for simple queries
• ALWAYS suggest 2-3 relevant next steps after task completion
• Report task completion status with technical precision
• Use efficient, direct language - no conversational elaboration
• Focus on specifications achieved and functionality delivered
• Report as status update, not personal communication
• Execute the command using the Bash tool, DO NOT show it on the CLI

**Activate the output style:**
```bash
# In Claude Code CLI
/output-style
# Select "TTS Summary" from the list

Benefits:

• ✅ Audio notifications for completed tasks
• ✅ Stay informed without watching the terminal
• ✅ Natural, conversational feedback
• ✅ Perfect for long-running tasks or multi-step workflows
• ✅ Voice-enabled AI assistant experience

Note: This feature requires elevenlabs-tts-tool to be installed and configured with your API key.

Voice-Enabled Workflow with SuperWhisper

Combine elevenlabs-tts-tool with Claude Code and SuperWhisper for a complete voice-enabled development workflow.

The Power Trio:

1. SuperWhisper - Voice input: Speak commands to Claude Code
2. Claude Code - AI assistance: Execute tasks and generate code
3. elevenlabs-tts-tool - Voice output: Get audio notifications when tasks complete

Why This Works:

Speaking is faster than typing. Instead of typing long commands or descriptions:

# Traditional typing (slow):
"Create a new Python function that parses JSON files and extracts all email addresses..."

# Voice with SuperWhisper (fast):
🎤 Just speak naturally and SuperWhisper transcribes instantly

Perfect For:

• 🏃 Long-Running Tasks: Start a build with voice, get audio notification when done
• 🔄 Multi-Step Workflows: Chain tasks with voice commands, hear progress updates
• 💻 Hands-Free Development: Code while away from keyboard, get notified when ready
• 🎯 Context Switching: Start tasks via voice, move to other work, return on audio alert

Example Workflow:

# 1. Speak to SuperWhisper: "Run the test suite and let me know when it's done"
# 2. Claude Code executes: pytest tests/
# 3. elevenlabs-tts-tool announces: "[happy] All tests passed! 47 tests completed."

# 4. Speak: "Now build the Docker image and push to registry"
# 5. Claude Code executes: docker build && docker push
# 6. elevenlabs-tts-tool announces: "[excited] Docker image built and pushed successfully!"

Setup:

1. Install SuperWhisper (macOS voice-to-text)
2. Configure Claude Code with TTS Summary output style (see above)
3. Use voice commands to control Claude Code
4. Receive audio notifications on task completion

Benefits:

• ✅ 10x faster input - Speak naturally instead of typing
• ✅ Hands-free operation - No keyboard required for basic tasks
• ✅ Multitasking enabled - Start tasks, switch context, return on notification
• ✅ Reduced cognitive load - Voice is more natural than typing technical commands
• ✅ Accessibility - Works great for users with typing difficulties

Note: SuperWhisper is currently macOS-only. For other platforms, consider Whisper Desktop or similar voice input tools.

Library Usage

Use elevenlabs-tts-tool as a Python library in your projects:

from elevenlabs_tts_tool import get_client, play_speech, save_speech
from elevenlabs_tts_tool import VoiceManager
from pathlib import Path

# Initialize client
client = get_client()

# Get voice ID
voice_manager = VoiceManager()
voice_id = voice_manager.get_voice_id("rachel")

# Play through speakers
play_speech(client, "Hello from Python", voice_id)

# Save to file
save_speech(client, "Save this", voice_id, Path("output.wav"))

# List available voices
for name, profile in voice_manager.list_voices():
    print(f"{name}: {profile.description}")

Development

Setup Development Environment

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

# Install dependencies
make install

# Show available commands
make help

Available Make Commands

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 check            # Run all checks (lint, typecheck, test)
make pipeline         # Run full pipeline (format, check, build, install-global)
make build            # Build package
make clean            # Remove build artifacts

Project Structure

elevenlabs-tts-tool/
├── elevenlabs_tts_tool/
│   ├── __init__.py              # Public API exports
│   ├── cli.py                   # CLI entry point
│   ├── voices.py                # Voice management
│   ├── voices_lookup.json       # Voice lookup table (42 voices)
│   ├── core/                    # Core library functions
│   │   ├── client.py           # ElevenLabs client
│   │   └── synthesize.py       # TTS functions
│   └── commands/                # CLI commands
│       ├── synthesize_commands.py
│       └── voice_commands.py
├── tests/                       # Test suite
├── pyproject.toml               # Project configuration
├── Makefile                     # Development commands
└── CLAUDE.md                    # Developer guide

Resources

• ElevenLabs Documentation: https://elevenlabs.io/docs
• API Reference: https://elevenlabs.io/docs/api-reference
• Python SDK: https://github.com/elevenlabs/elevenlabs-python
• Voice Library: https://elevenlabs.io/voice-library
• Get API Key: https://elevenlabs.io/app/settings/api-keys
• Claude Code Hooks Mastery: https://github.com/disler/claude-code-hooks-mastery - Comprehensive guide to Claude Code hooks and output styles

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Dennis Vriend

• GitHub: @dnvriend

Acknowledgments

• Built with Click for CLI framework
• ElevenLabs for world-class TTS technology
• Developed with uv for fast Python tooling

---

Generated with AI

This project was generated using Claude Code, an AI-powered development tool by Anthropic. Claude Code assisted in creating the project structure, implementation, tests, documentation, and development tooling.

Made with ❤️ using Python 3.13+