skill-elevenlabs-tts-tool

name	skill-elevenlabs-tts-tool
description	ElevenLabs text-to-speech CLI tool guide Use when this capability is needed.
metadata	{"author":"dnvriend"}

When to use

• Converting text to speech with ElevenLabs API
• Exploring available voices and models
• Managing TTS subscriptions and usage
• Integrating TTS into workflows and pipelines

ElevenLabs TTS Tool Skill

Purpose

Comprehensive guide for the elevenlabs-tts-tool CLI - a professional command-line interface for ElevenLabs text-to-speech synthesis. Provides both direct audio playback and file output with support for 42+ premium voices and multiple models.

When to Use This Skill

Use this skill when:

• Converting text to speech for notifications, audiobooks, or content creation
• Exploring and comparing different voice characteristics
• Managing ElevenLabs subscription quotas and usage
• Building voice-enabled workflows and automation
• Integrating TTS into Claude Code hooks or other tools

Do NOT use this skill for:

• Direct ElevenLabs API programming (use SDK docs instead)
• Custom voice cloning (requires ElevenLabs web interface)
• Real-time streaming TTS (tool focuses on file/playback generation)

CLI Tool: elevenlabs-tts-tool

Professional text-to-speech CLI tool built with Python 3.13+, uv, and the ElevenLabs SDK.

Installation

# Clone 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

Prerequisites

• Python: 3.13 or higher
• API Key: ElevenLabs API key (get from https://elevenlabs.io/app/settings/api-keys)
• Environment Variable: export ELEVENLABS_API_KEY='your-api-key'

Quick Start

# Set API key
export ELEVENLABS_API_KEY='your-api-key'

# Basic text-to-speech
elevenlabs-tts-tool synthesize "Hello world"

# Use different voice
elevenlabs-tts-tool synthesize "Hello" --voice adam

# Save to file
elevenlabs-tts-tool synthesize "Text" --output speech.mp3

Progressive Disclosure

📖 Core Commands (Click to expand)

synthesize - Convert Text to Speech

Convert text to speech using ElevenLabs API. Supports direct playback or file output.

Usage:

elevenlabs-tts-tool synthesize [TEXT] [OPTIONS]

Arguments:

• TEXT: Text to synthesize (optional if --stdin used)
• --stdin, -s: Read text from stdin instead of argument
• --voice, -v NAME: Voice name or ID (default: rachel)
• --model, -m ID: Model ID (default: eleven_turbo_v2_5)
• --output, -o PATH: Save to audio file instead of playing
• --format, -f FORMAT: Output format (default: mp3_44100_128)

Examples:

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

# Use different voice
elevenlabs-tts-tool synthesize "Hello" --voice adam

# Use specific model
elevenlabs-tts-tool synthesize "Hello" --model eleven_multilingual_v2

# Emotional expression (requires eleven_v3 model)
elevenlabs-tts-tool synthesize "[happy] Welcome to our service!" --model eleven_v3

# Multiple emotions
elevenlabs-tts-tool synthesize "[excited] Great news! [cheerfully] Your project is approved!" --model eleven_v3

# Add pauses with SSML
elevenlabs-tts-tool synthesize "Point one <break time=\"0.5s\" /> Point two <break time=\"0.5s\" /> Point three."

# Read from stdin
echo "Text from pipeline" | elevenlabs-tts-tool synthesize --stdin

# Save to file
elevenlabs-tts-tool synthesize "Text" --output speech.mp3

# Pipeline integration
cat document.txt | elevenlabs-tts-tool synthesize --stdin --output audiobook.mp3

Output: Plays audio through default speakers or saves to specified file format.

⚙️ Advanced Features (Click to expand)

Emotion Control (v3 Models)

ElevenLabs v3 model (eleven_v3) supports Audio Tags for emotional expression.

Available Emotion Tags:

• Basic emotions: [happy], [excited], [sad], [angry], [nervous], [curious]
• Delivery styles: [cheerfully], [playfully], [mischievously], [resigned tone], [flatly], [deadpan]
• Speech characteristics: [whispers], [laughs], [gasps], [sighs], [pauses], [hesitates], [stammers], [gulps]

Usage Examples:

# Basic emotion (requires eleven_v3 model)
elevenlabs-tts-tool synthesize "[happy] Welcome to our service!" --model eleven_v3

# Multiple emotions in sequence
elevenlabs-tts-tool synthesize "[excited] Great news! [cheerfully] Your project is approved!" --model eleven_v3

# Combine emotions with pauses
elevenlabs-tts-tool synthesize "[happy] Hello! <break time=\"0.5s\" /> [curious] How are you today?" --model eleven_v3

# Whispered speech
elevenlabs-tts-tool synthesize "[whispers] This is a secret message." --model eleven_v3

# Playful delivery
elevenlabs-tts-tool synthesize "[playfully] Guess what I found!" --model eleven_v3

Best Practices:

• Place tags at the beginning of phrases
• Align text content with emotional intent
• Test with different voices for best results
• Use sparingly - let AI infer emotion from context when possible
• Remember: v3 models cost 2x as much (half the minutes/tokens)

---

Pause Control (SSML)

Add natural pauses using SSML tags.

🔧 Troubleshooting (Click to expand)

Common Issues

Issue: "API key not found" error

# Symptom
Error: ELEVENLABS_API_KEY environment variable not set

Solution:

1. Get API key from https://elevenlabs.io/app/settings/api-keys
2. Export as environment variable:

   export ELEVENLABS_API_KEY='your-api-key'
   

3. Add to shell profile for persistence:

   echo 'export ELEVENLABS_API_KEY="your-api-key"' >> ~/.bashrc
   source ~/.bashrc
   

---

Issue: "Voice not found" error

# Symptom
ValueError: Voice 'unknown' not found in lookup table

Solution:

1. List available voices:

   elevenlabs-tts-tool list-voices
   

2. Update voice table if needed:

   elevenlabs-tts-tool update-voices
   

3. Use correct voice name (case-insensitive):

   elevenlabs-tts-tool synthesize "Hello" --voice rachel
   

---

Issue: Character quota exceeded

# Symptom
Error: Character quota exceeded for this month

Solution:

1. Check current usage:

   elevenlabs-tts-tool info
   

2. Wait until quota reset date
3. Consider upgrading subscription tier:

   elevenlabs-tts-tool pricing
   

4. Use more efficient models (Flash/Turbo vs v3)

---

Issue: Audio quality issues

Symptom: Poor audio quality or artifacts

Free Tier Limitations

ElevenLabs Free Tier (2024-2025):

• ✅ 10,000-20,000 characters per month
• ✅ All 42 premade voices
• ✅ Create up to 3 custom voices
• ✅ MP3 formats (all bitrates)
• ✅ Basic SSML support (<break>, phonemes)
• ✅ Emotional tags (v3 models)
• ✅ Full API access
• ❌ No commercial license (personal/experimentation only)
• ❌ PCM 44.1kHz format (requires Pro tier)
• ⚠️ Max 2,500 characters per single generation

Upgrade Tiers:

• Starter ($5/month): 30,000 characters, commercial license
• Creator ($22/month): 100,000 characters, PCM formats
• Pro ($99/month): 500,000 characters, PCM 44.1kHz, highest priority
• Scale ($330/month): 2,000,000 characters
• Business (custom): Custom limits and features

Rate Limits: Not publicly documented - expect reasonable use restrictions on free tier

Exit Codes

• 0: Success
• 1: General error (validation, API error, etc.)

Output Formats

Audio Formats:

• mp3_44100_128: MP3, 44.1kHz, 128kbps (default, best quality)
• mp3_44100_64: MP3, 44.1kHz, 64kbps (good quality, smaller)
• mp3_22050_32: MP3, 22.05kHz, 32kbps (acceptable quality, smallest)
• pcm_44100: PCM WAV, 44.1kHz, uncompressed (requires Pro tier)

Text Formats:

• Human-readable tables for list commands
• Structured output with clear sections
• Errors to stderr, audio/data to stdout

Best Practices

1. Use Turbo v2.5 for High Volume: Default model offers best value (1x cost, fast, high quality)
2. Reserve v3 for Emotional Content: Use v3 only when emotion tags needed (costs 2x)
3. Monitor Quota Regularly: Check info command before large generations
4. Update Voices Periodically: Run update-voices monthly to get latest voices
5. Test Voices for Your Use Case: Different voices work better for different content types
6. Use SSML Breaks Sparingly: Limit to 2-4 breaks per generation for stability
7. Pipeline for Efficiency: Combine with other tools for automated workflows
8. Set Verbosity Appropriately: Use -vv or -vvv for debugging, default for production

Resources

• GitHub Repository: https://github.com/dnvriend/elevenlabs-tts-tool
• ElevenLabs Documentation: https://elevenlabs.io/docs
• API Reference: https://elevenlabs.io/docs/api-reference
• Voice Library: https://elevenlabs.io/voice-library
• Python SDK: https://github.com/elevenlabs/elevenlabs-python
• Claude Code: https://docs.anthropic.com/claude-code

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.