Initial commit
This commit is contained in:
Zhongwei Li
14
.claude-plugin/plugin.json
Normal file
14
.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,14 @@
|
|||||||
|
{
|
||||||
|
"name": "elevenlabs-tts-tool",
|
||||||
|
"description": "CLI tool for ElevenLabs text-to-speech synthesis",
|
||||||
|
"version": "0.2.0",
|
||||||
|
"author": {
|
||||||
|
"name": "Dennis Vriend"
|
||||||
|
},
|
||||||
|
"skills": [
|
||||||
|
"./skills"
|
||||||
|
],
|
||||||
|
"commands": [
|
||||||
|
"./commands"
|
||||||
|
]
|
||||||
|
}
|
||||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
|||||||
|
# elevenlabs-tts-tool
|
||||||
|
|
||||||
|
CLI tool for ElevenLabs text-to-speech synthesis
|
||||||
32
commands/info.md
Normal file
32
commands/info.md
Normal file
@@ -0,0 +1,32 @@
|
|||||||
|
---
|
||||||
|
description: Show subscription and usage information
|
||||||
|
---
|
||||||
|
|
||||||
|
Display ElevenLabs subscription tier, character usage, and historical stats.
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
elevenlabs-tts-tool info [--days N]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Arguments
|
||||||
|
|
||||||
|
- `--days, -d N`: Number of days of historical usage (default: 7)
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# View subscription with last 7 days
|
||||||
|
elevenlabs-tts-tool info
|
||||||
|
|
||||||
|
# View last 30 days
|
||||||
|
elevenlabs-tts-tool info --days 30
|
||||||
|
|
||||||
|
# Quick quota check
|
||||||
|
elevenlabs-tts-tool info --days 1
|
||||||
|
```
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
Subscription tier, quota usage, remaining characters, and daily usage breakdown.
|
||||||
28
commands/list-models.md
Normal file
28
commands/list-models.md
Normal file
@@ -0,0 +1,28 @@
|
|||||||
|
---
|
||||||
|
description: List ElevenLabs TTS models
|
||||||
|
---
|
||||||
|
|
||||||
|
List all available ElevenLabs TTS models with characteristics.
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
elevenlabs-tts-tool list-models
|
||||||
|
```
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# List all models
|
||||||
|
elevenlabs-tts-tool list-models
|
||||||
|
|
||||||
|
# Filter by status
|
||||||
|
elevenlabs-tts-tool list-models | grep stable
|
||||||
|
|
||||||
|
# Find specific features
|
||||||
|
elevenlabs-tts-tool list-models | grep -i "ultra-low"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
Detailed model information with IDs, features, languages, and use cases.
|
||||||
28
commands/list-voices.md
Normal file
28
commands/list-voices.md
Normal file
@@ -0,0 +1,28 @@
|
|||||||
|
---
|
||||||
|
description: List available ElevenLabs voices
|
||||||
|
---
|
||||||
|
|
||||||
|
List all available ElevenLabs voices with characteristics.
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
elevenlabs-tts-tool list-voices
|
||||||
|
```
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# List all voices
|
||||||
|
elevenlabs-tts-tool list-voices
|
||||||
|
|
||||||
|
# Filter by gender
|
||||||
|
elevenlabs-tts-tool list-voices | grep female
|
||||||
|
|
||||||
|
# Filter by accent
|
||||||
|
elevenlabs-tts-tool list-voices | grep British
|
||||||
|
```
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
Table format with voice name, gender, age, accent, and description.
|
||||||
44
commands/synthesize.md
Normal file
44
commands/synthesize.md
Normal file
@@ -0,0 +1,44 @@
|
|||||||
|
---
|
||||||
|
description: Convert text to speech with ElevenLabs
|
||||||
|
argument-hint: text
|
||||||
|
---
|
||||||
|
|
||||||
|
Convert TEXT to speech using ElevenLabs API. Play through speakers or save to file.
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
elevenlabs-tts-tool synthesize TEXT [OPTIONS]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Arguments
|
||||||
|
|
||||||
|
- `TEXT`: Text to synthesize (required, or use --stdin)
|
||||||
|
- `--stdin, -s`: Read text from stdin instead
|
||||||
|
- `--voice, -v NAME`: Voice name or ID (default: rachel)
|
||||||
|
- `--model, -m ID`: Model ID (default: eleven_turbo_v2_5)
|
||||||
|
- `--output, -o PATH`: Save to file instead of playing
|
||||||
|
- `--format, -f FORMAT`: Output format (default: mp3_44100_128)
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Basic usage
|
||||||
|
elevenlabs-tts-tool synthesize "Hello world"
|
||||||
|
|
||||||
|
# Different voice
|
||||||
|
elevenlabs-tts-tool synthesize "Hello" --voice adam
|
||||||
|
|
||||||
|
# Emotional expression (requires eleven_v3)
|
||||||
|
elevenlabs-tts-tool synthesize "[happy] Welcome!" --model eleven_v3
|
||||||
|
|
||||||
|
# Read from stdin
|
||||||
|
echo "Text" | elevenlabs-tts-tool synthesize --stdin
|
||||||
|
|
||||||
|
# Save to file
|
||||||
|
elevenlabs-tts-tool synthesize "Text" --output speech.mp3
|
||||||
|
```
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
Plays audio through speakers or saves to file in specified format.
|
||||||
29
commands/update-voices.md
Normal file
29
commands/update-voices.md
Normal file
@@ -0,0 +1,29 @@
|
|||||||
|
---
|
||||||
|
description: Update voice lookup table from API
|
||||||
|
---
|
||||||
|
|
||||||
|
Fetch latest voices from ElevenLabs API and update local lookup table.
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
elevenlabs-tts-tool update-voices [--output PATH]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Arguments
|
||||||
|
|
||||||
|
- `--output, -o PATH`: Output file path (default: ~/.config/elevenlabs-tts-tool/voices_lookup.json)
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Update default voice lookup
|
||||||
|
elevenlabs-tts-tool update-voices
|
||||||
|
|
||||||
|
# Save to custom location
|
||||||
|
elevenlabs-tts-tool update-voices --output custom_voices.json
|
||||||
|
```
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
Updates voice lookup table with latest premade voices from API.
|
||||||
65
plugin.lock.json
Normal file
65
plugin.lock.json
Normal file
@@ -0,0 +1,65 @@
|
|||||||
|
{
|
||||||
|
"$schema": "internal://schemas/plugin.lock.v1.json",
|
||||||
|
"pluginId": "gh:dnvriend/elevenlabs-tts-tool:plugins/elevenlabs-tts-tool",
|
||||||
|
"normalized": {
|
||||||
|
"repo": null,
|
||||||
|
"ref": "refs/tags/v20251128.0",
|
||||||
|
"commit": "af6dbbf9d00e77221dff2948d4a9dd0d85fb4757",
|
||||||
|
"treeHash": "9c64c06848bb9bad601398f1bdd70a5c82baba3504d8082912013e797185497c",
|
||||||
|
"generatedAt": "2025-11-28T10:16:35.061579Z",
|
||||||
|
"toolVersion": "publish_plugins.py@0.2.0"
|
||||||
|
},
|
||||||
|
"origin": {
|
||||||
|
"remote": "git@github.com:zhongweili/42plugin-data.git",
|
||||||
|
"branch": "master",
|
||||||
|
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
|
||||||
|
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
|
||||||
|
},
|
||||||
|
"manifest": {
|
||||||
|
"name": "elevenlabs-tts-tool",
|
||||||
|
"description": "CLI tool for ElevenLabs text-to-speech synthesis",
|
||||||
|
"version": "0.2.0"
|
||||||
|
},
|
||||||
|
"content": {
|
||||||
|
"files": [
|
||||||
|
{
|
||||||
|
"path": "README.md",
|
||||||
|
"sha256": "a602d7c5d4fa70f019df3a98b6e81dfb7ccbec08cb20fa9906e215365bc8cd45"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": ".claude-plugin/plugin.json",
|
||||||
|
"sha256": "b411b622f0e84565462a8dc82777db75b12764b515bcbd6cee9b1a0aa37f3a24"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "commands/list-models.md",
|
||||||
|
"sha256": "9d1bb3256b03bdfc4701f02798107fce1359cc2fad75f4bf2673dfaf19687f1b"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "commands/synthesize.md",
|
||||||
|
"sha256": "737e53c0fc16da6d7bd9e477dfa78d5915ecccc612f950c4e93112b5a9063f88"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "commands/info.md",
|
||||||
|
"sha256": "0dfebaa8979423847ebebeea9d4d0e7e0f77edba431a52f44091a1fc2c9b650e"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "commands/update-voices.md",
|
||||||
|
"sha256": "2e9d8d6c71fd3bc190d4602fb712277f28703bb2958474f59df77c700347b9ba"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "commands/list-voices.md",
|
||||||
|
"sha256": "e3a78b3bcbc3961f7b8badc6c4c4beaf18f2505636a58e0577e9e747a9c021c2"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/elevenlabs-tts-tool/SKILL.md",
|
||||||
|
"sha256": "7500946a945804d0f4c91895a592eeee17890f5e69334ce2545b83af3fe83aeb"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"dirSha256": "9c64c06848bb9bad601398f1bdd70a5c82baba3504d8082912013e797185497c"
|
||||||
|
},
|
||||||
|
"security": {
|
||||||
|
"scannedAt": null,
|
||||||
|
"scannerVersion": null,
|
||||||
|
"flags": []
|
||||||
|
}
|
||||||
|
}
|
||||||
776
skills/elevenlabs-tts-tool/SKILL.md
Normal file
776
skills/elevenlabs-tts-tool/SKILL.md
Normal file
@@ -0,0 +1,776 @@
|
|||||||
|
---
|
||||||
|
name: skill-elevenlabs-tts-tool
|
||||||
|
description: ElevenLabs text-to-speech CLI tool guide
|
||||||
|
---
|
||||||
|
|
||||||
|
# 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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><strong>📖 Core Commands (Click to expand)</strong></summary>
|
||||||
|
|
||||||
|
### synthesize - Convert Text to Speech
|
||||||
|
|
||||||
|
Convert text to speech using ElevenLabs API. Supports direct playback or file output.
|
||||||
|
|
||||||
|
**Usage:**
|
||||||
|
```bash
|
||||||
|
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:**
|
||||||
|
```bash
|
||||||
|
# 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.
|
||||||
|
|
||||||
|
**Available Formats:**
|
||||||
|
- `mp3_44100_128` (default): MP3, 44.1kHz, 128kbps
|
||||||
|
- `mp3_44100_64`: MP3, 44.1kHz, 64kbps
|
||||||
|
- `mp3_22050_32`: MP3, 22.05kHz, 32kbps
|
||||||
|
- `pcm_44100`: PCM WAV, 44.1kHz (requires Pro tier)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### list-voices - Show Available Voices
|
||||||
|
|
||||||
|
List all available ElevenLabs voices with characteristics.
|
||||||
|
|
||||||
|
**Usage:**
|
||||||
|
```bash
|
||||||
|
elevenlabs-tts-tool list-voices
|
||||||
|
```
|
||||||
|
|
||||||
|
**Examples:**
|
||||||
|
```bash
|
||||||
|
# List all voices
|
||||||
|
elevenlabs-tts-tool list-voices
|
||||||
|
|
||||||
|
# Filter by gender
|
||||||
|
elevenlabs-tts-tool list-voices | grep female
|
||||||
|
elevenlabs-tts-tool list-voices | grep male
|
||||||
|
|
||||||
|
# Filter by accent
|
||||||
|
elevenlabs-tts-tool list-voices | grep British
|
||||||
|
elevenlabs-tts-tool list-voices | grep American
|
||||||
|
|
||||||
|
# Filter by age
|
||||||
|
elevenlabs-tts-tool list-voices | grep young
|
||||||
|
elevenlabs-tts-tool list-voices | grep middle_aged
|
||||||
|
|
||||||
|
# Combine filters
|
||||||
|
elevenlabs-tts-tool list-voices | grep "female.*young.*British"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output:**
|
||||||
|
```
|
||||||
|
Voice Gender Age Accent Description
|
||||||
|
====================================================================================================
|
||||||
|
rachel female young American Calm and friendly American voice...
|
||||||
|
adam male middle_aged American Deep, authoritative American male...
|
||||||
|
charlotte female middle_aged British Smooth, professional British voice...
|
||||||
|
...
|
||||||
|
====================================================================================================
|
||||||
|
Total: 42 voices available
|
||||||
|
```
|
||||||
|
|
||||||
|
**Popular Voices:**
|
||||||
|
- **rachel**: Calm, friendly American female (default)
|
||||||
|
- **adam**: Deep, authoritative American male
|
||||||
|
- **charlotte**: Professional British female
|
||||||
|
- **josh**: Young, casual American male
|
||||||
|
- **bella**: Expressive Italian female
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### list-models - Show TTS Models
|
||||||
|
|
||||||
|
List all available ElevenLabs TTS models with characteristics and use cases.
|
||||||
|
|
||||||
|
**Usage:**
|
||||||
|
```bash
|
||||||
|
elevenlabs-tts-tool list-models
|
||||||
|
```
|
||||||
|
|
||||||
|
**Examples:**
|
||||||
|
```bash
|
||||||
|
# List all models
|
||||||
|
elevenlabs-tts-tool list-models
|
||||||
|
|
||||||
|
# Filter by status
|
||||||
|
elevenlabs-tts-tool list-models | grep stable
|
||||||
|
elevenlabs-tts-tool list-models | grep deprecated
|
||||||
|
|
||||||
|
# Find low-latency models
|
||||||
|
elevenlabs-tts-tool list-models | grep -i "ultra-low"
|
||||||
|
|
||||||
|
# Find multilingual models
|
||||||
|
elevenlabs-tts-tool list-models | grep -i "multilingual"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output:**
|
||||||
|
Comprehensive model information including:
|
||||||
|
- Model ID and version
|
||||||
|
- Quality and latency characteristics
|
||||||
|
- Language support (mono vs multilingual)
|
||||||
|
- Character limits
|
||||||
|
- Best use cases
|
||||||
|
- Special features (emotions, etc.)
|
||||||
|
|
||||||
|
**Key Models:**
|
||||||
|
- **eleven_turbo_v2_5**: Fast, high-quality (default, best value)
|
||||||
|
- **eleven_flash_v2_5**: Ultra-low latency (real-time applications)
|
||||||
|
- **eleven_multilingual_v2**: 29 languages, production quality
|
||||||
|
- **eleven_v3**: Most expressive with emotion tags (alpha, 2x cost)
|
||||||
|
|
||||||
|
**Cost Multipliers:**
|
||||||
|
- Turbo/Flash models: 1x cost
|
||||||
|
- Multilingual v2: 1x cost
|
||||||
|
- v3 models: 2x cost (half the minutes/tokens)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### info - Show Subscription Info
|
||||||
|
|
||||||
|
Display subscription tier, character usage, quota limits, and historical usage.
|
||||||
|
|
||||||
|
**Usage:**
|
||||||
|
```bash
|
||||||
|
elevenlabs-tts-tool info [--days N]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Arguments:**
|
||||||
|
- `--days, -d N`: Number of days of historical usage to display (default: 7)
|
||||||
|
|
||||||
|
**Examples:**
|
||||||
|
```bash
|
||||||
|
# View subscription 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 (1 day)
|
||||||
|
elevenlabs-tts-tool info --days 1
|
||||||
|
|
||||||
|
# Check usage before long generation
|
||||||
|
elevenlabs-tts-tool info --days 1 && elevenlabs-tts-tool synthesize "Long text..."
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output Information:**
|
||||||
|
- Subscription tier and status
|
||||||
|
- Character usage (used/limit/remaining)
|
||||||
|
- Quota reset date
|
||||||
|
- Historical usage breakdown by day
|
||||||
|
- Average daily usage
|
||||||
|
- Projected monthly usage
|
||||||
|
- Warnings when approaching quota limits
|
||||||
|
|
||||||
|
**Use Cases:**
|
||||||
|
- Monitor character quota consumption
|
||||||
|
- Track usage patterns over time
|
||||||
|
- Plan when to upgrade subscription tier
|
||||||
|
- Avoid hitting quota limits unexpectedly
|
||||||
|
- Identify high-usage periods
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### update-voices - Update Voice Table
|
||||||
|
|
||||||
|
Fetch latest voices from ElevenLabs API and update local lookup table.
|
||||||
|
|
||||||
|
**Usage:**
|
||||||
|
```bash
|
||||||
|
elevenlabs-tts-tool update-voices [--output PATH]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Arguments:**
|
||||||
|
- `--output, -o PATH`: Output file path (default: ~/.config/elevenlabs-tts-tool/voices_lookup.json)
|
||||||
|
|
||||||
|
**Examples:**
|
||||||
|
```bash
|
||||||
|
# Update default voice lookup (user config directory)
|
||||||
|
elevenlabs-tts-tool update-voices
|
||||||
|
|
||||||
|
# Save to custom location
|
||||||
|
elevenlabs-tts-tool update-voices --output custom_voices.json
|
||||||
|
|
||||||
|
# Update before listing voices
|
||||||
|
elevenlabs-tts-tool update-voices && elevenlabs-tts-tool list-voices
|
||||||
|
```
|
||||||
|
|
||||||
|
**Behavior:**
|
||||||
|
- Fetches all premade voices from ElevenLabs API
|
||||||
|
- Saves to user config directory by default (`~/.config/elevenlabs-tts-tool/`)
|
||||||
|
- Creates config directory if it doesn't exist
|
||||||
|
- Updates take precedence over package default
|
||||||
|
- Persists across package reinstalls
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### pricing - Show Pricing Information
|
||||||
|
|
||||||
|
Display ElevenLabs pricing tiers and feature comparison.
|
||||||
|
|
||||||
|
**Usage:**
|
||||||
|
```bash
|
||||||
|
elevenlabs-tts-tool pricing
|
||||||
|
```
|
||||||
|
|
||||||
|
**Examples:**
|
||||||
|
```bash
|
||||||
|
# View full pricing table
|
||||||
|
elevenlabs-tts-tool pricing
|
||||||
|
|
||||||
|
# Find specific tier information
|
||||||
|
elevenlabs-tts-tool pricing | grep Creator
|
||||||
|
elevenlabs-tts-tool pricing | grep "44.1kHz PCM"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output Information:**
|
||||||
|
- Pricing tiers (Free, Starter, Creator, Pro, Scale, Business)
|
||||||
|
- Minutes included per tier
|
||||||
|
- Additional minute costs
|
||||||
|
- Audio quality options
|
||||||
|
- Concurrency limits
|
||||||
|
- Priority levels
|
||||||
|
- API formats by tier
|
||||||
|
- Model cost multipliers
|
||||||
|
|
||||||
|
**Key Insights:**
|
||||||
|
- Free tier: 10,000-20,000 characters/month
|
||||||
|
- v3 models cost 2x (half the minutes/tokens)
|
||||||
|
- Use Flash v2.5 for high-volume integrations
|
||||||
|
- Reserve v3 for content requiring emotional expression
|
||||||
|
- PCM 44.1kHz requires Pro tier
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### completion - Shell Completion
|
||||||
|
|
||||||
|
Generate shell completion scripts for bash, zsh, or fish.
|
||||||
|
|
||||||
|
**Usage:**
|
||||||
|
```bash
|
||||||
|
elevenlabs-tts-tool completion [bash|zsh|fish]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Installation:**
|
||||||
|
```bash
|
||||||
|
# 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)
|
||||||
|
elevenlabs-tts-tool completion fish > ~/.config/fish/completions/elevenlabs-tts-tool.fish
|
||||||
|
```
|
||||||
|
|
||||||
|
**Features:**
|
||||||
|
- Tab-complete commands and subcommands
|
||||||
|
- Tab-complete options and flags
|
||||||
|
- Context-aware completion for file paths
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><strong>⚙️ Advanced Features (Click to expand)</strong></summary>
|
||||||
|
|
||||||
|
### 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:**
|
||||||
|
```bash
|
||||||
|
# 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 `<break>` tags.
|
||||||
|
|
||||||
|
**Syntax:**
|
||||||
|
```xml
|
||||||
|
<break time="X.Xs" />
|
||||||
|
```
|
||||||
|
|
||||||
|
**Examples:**
|
||||||
|
```bash
|
||||||
|
# 1-second pause
|
||||||
|
elevenlabs-tts-tool synthesize "Welcome <break time=\"1.0s\" /> to our service."
|
||||||
|
|
||||||
|
# Multiple pauses
|
||||||
|
elevenlabs-tts-tool synthesize "Point one <break time=\"0.5s\" /> Point two <break time=\"0.5s\" /> Point three."
|
||||||
|
|
||||||
|
# Short pause for emphasis
|
||||||
|
elevenlabs-tts-tool synthesize "Think about this <break time=\"0.3s\" /> carefully."
|
||||||
|
|
||||||
|
# Combine with emotions (requires eleven_v3)
|
||||||
|
elevenlabs-tts-tool synthesize "[happy] Hello! <break time=\"0.5s\" /> [cheerfully] How are you?" --model eleven_v3
|
||||||
|
```
|
||||||
|
|
||||||
|
**Limitations:**
|
||||||
|
- Maximum pause duration: 3 seconds
|
||||||
|
- Recommended: 2-4 breaks per generation
|
||||||
|
- Too many breaks can cause:
|
||||||
|
- AI speedup
|
||||||
|
- Audio artifacts
|
||||||
|
- Background noise
|
||||||
|
- Generation instability
|
||||||
|
|
||||||
|
**Alternative Methods:**
|
||||||
|
- Dashes (`-` or `—`) for shorter pauses (less consistent)
|
||||||
|
- Ellipses (`...`) for hesitation (may add nervous tone)
|
||||||
|
- SSML `<break>` is most reliable
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Verbosity Control
|
||||||
|
|
||||||
|
Multi-level verbosity for progressive detail control.
|
||||||
|
|
||||||
|
**Verbosity Levels:**
|
||||||
|
- **No flag** (default): WARNING level - only critical issues
|
||||||
|
- **`-v`**: INFO level - high-level operations, important events
|
||||||
|
- **`-vv`**: DEBUG level - detailed operations, API calls, validation steps
|
||||||
|
- **`-vvv`**: TRACE level - full HTTP requests/responses, ElevenLabs SDK internals
|
||||||
|
|
||||||
|
**Usage:**
|
||||||
|
```bash
|
||||||
|
# Quiet mode (warnings only)
|
||||||
|
elevenlabs-tts-tool synthesize "Hello world"
|
||||||
|
|
||||||
|
# INFO level
|
||||||
|
elevenlabs-tts-tool -v synthesize "Hello world"
|
||||||
|
|
||||||
|
# DEBUG level (detailed operations)
|
||||||
|
elevenlabs-tts-tool -vv synthesize "Hello world"
|
||||||
|
|
||||||
|
# TRACE level (shows HTTP requests/responses)
|
||||||
|
elevenlabs-tts-tool -vvv synthesize "Hello world"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Dependent Library Logging:**
|
||||||
|
At trace level (`-vvv`), the following libraries enable DEBUG logging:
|
||||||
|
- `elevenlabs` - ElevenLabs SDK internals
|
||||||
|
- `httpx` / `httpcore` - HTTP request/response details
|
||||||
|
- `urllib3` - Low-level HTTP operations
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Pipeline Integration
|
||||||
|
|
||||||
|
The tool is designed for composition with other CLI tools.
|
||||||
|
|
||||||
|
**Design Principles:**
|
||||||
|
- JSON output to stdout, logs/errors to stderr
|
||||||
|
- Stdin support for text input
|
||||||
|
- Exit codes for success/failure detection
|
||||||
|
- Shell completion for productivity
|
||||||
|
|
||||||
|
**Examples:**
|
||||||
|
```bash
|
||||||
|
# Read from file
|
||||||
|
cat document.txt | elevenlabs-tts-tool synthesize --stdin --output audio.mp3
|
||||||
|
|
||||||
|
# Combine with other tools
|
||||||
|
gemini-google-search-tool query "AI news" | \
|
||||||
|
elevenlabs-tts-tool synthesize --stdin --voice charlotte --output news.mp3
|
||||||
|
|
||||||
|
# Conditional execution
|
||||||
|
make build && elevenlabs-tts-tool synthesize "[cheerfully] Build successful!" || \
|
||||||
|
elevenlabs-tts-tool synthesize "[sad] Build failed. Check logs."
|
||||||
|
|
||||||
|
# Process multiple texts
|
||||||
|
for text in "First" "Second" "Third"; do
|
||||||
|
elevenlabs-tts-tool synthesize "$text" --output "${text}.mp3"
|
||||||
|
done
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Claude Code Integration
|
||||||
|
|
||||||
|
Use `elevenlabs-tts-tool` as notification system for Claude Code hooks.
|
||||||
|
|
||||||
|
**Use Cases:**
|
||||||
|
|
||||||
|
1. **Task Completion Alerts**
|
||||||
|
```bash
|
||||||
|
# After long-running task
|
||||||
|
elevenlabs-tts-tool synthesize "[excited] Task completed successfully!"
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Error Notifications**
|
||||||
|
```bash
|
||||||
|
# On build failure
|
||||||
|
elevenlabs-tts-tool synthesize "[nervous] Error detected. Please check output."
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Custom Workflows**
|
||||||
|
```bash
|
||||||
|
# Shell script integration
|
||||||
|
make build && elevenlabs-tts-tool synthesize "[cheerfully] Build successful!" || \
|
||||||
|
elevenlabs-tts-tool synthesize "[sad] Build failed. Check logs."
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Multi-Tool Integration**
|
||||||
|
```bash
|
||||||
|
# Combine with other CLI tools
|
||||||
|
gemini-google-search-tool query "AI news" | \
|
||||||
|
elevenlabs-tts-tool synthesize --stdin --voice charlotte --output news.mp3
|
||||||
|
```
|
||||||
|
|
||||||
|
**Hook Configuration:**
|
||||||
|
|
||||||
|
Create hooks in `~/.config/claude-code/hooks.json`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"hooks": {
|
||||||
|
"after_command": {
|
||||||
|
"type": "bash",
|
||||||
|
"command": "elevenlabs-tts-tool synthesize \"[happy] Task completed!\" --voice rachel"
|
||||||
|
},
|
||||||
|
"on_error": {
|
||||||
|
"type": "bash",
|
||||||
|
"command": "elevenlabs-tts-tool synthesize \"[nervous] Error occurred!\" --voice adam"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Benefits:**
|
||||||
|
- Audio alerts for completed tasks without monitoring terminal
|
||||||
|
- Error notifications while away from screen
|
||||||
|
- Multi-step automation with voice feedback
|
||||||
|
- Voice-enabled AI agent pipelines
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><strong>🔧 Troubleshooting (Click to expand)</strong></summary>
|
||||||
|
|
||||||
|
### Common Issues
|
||||||
|
|
||||||
|
**Issue: "API key not found" error**
|
||||||
|
```bash
|
||||||
|
# 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:
|
||||||
|
```bash
|
||||||
|
export ELEVENLABS_API_KEY='your-api-key'
|
||||||
|
```
|
||||||
|
3. Add to shell profile for persistence:
|
||||||
|
```bash
|
||||||
|
echo 'export ELEVENLABS_API_KEY="your-api-key"' >> ~/.bashrc
|
||||||
|
source ~/.bashrc
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Issue: "Voice not found" error**
|
||||||
|
```bash
|
||||||
|
# Symptom
|
||||||
|
ValueError: Voice 'unknown' not found in lookup table
|
||||||
|
```
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
1. List available voices:
|
||||||
|
```bash
|
||||||
|
elevenlabs-tts-tool list-voices
|
||||||
|
```
|
||||||
|
2. Update voice table if needed:
|
||||||
|
```bash
|
||||||
|
elevenlabs-tts-tool update-voices
|
||||||
|
```
|
||||||
|
3. Use correct voice name (case-insensitive):
|
||||||
|
```bash
|
||||||
|
elevenlabs-tts-tool synthesize "Hello" --voice rachel
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Issue: Character quota exceeded**
|
||||||
|
```bash
|
||||||
|
# Symptom
|
||||||
|
Error: Character quota exceeded for this month
|
||||||
|
```
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
1. Check current usage:
|
||||||
|
```bash
|
||||||
|
elevenlabs-tts-tool info
|
||||||
|
```
|
||||||
|
2. Wait until quota reset date
|
||||||
|
3. Consider upgrading subscription tier:
|
||||||
|
```bash
|
||||||
|
elevenlabs-tts-tool pricing
|
||||||
|
```
|
||||||
|
4. Use more efficient models (Flash/Turbo vs v3)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Issue: Audio quality issues**
|
||||||
|
|
||||||
|
**Symptom:** Poor audio quality or artifacts
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
1. Try different output format:
|
||||||
|
```bash
|
||||||
|
elevenlabs-tts-tool synthesize "Text" --format mp3_44100_128
|
||||||
|
```
|
||||||
|
2. Use higher-quality model:
|
||||||
|
```bash
|
||||||
|
elevenlabs-tts-tool synthesize "Text" --model eleven_multilingual_v2
|
||||||
|
```
|
||||||
|
3. For professional content, use PCM format (requires Pro tier):
|
||||||
|
```bash
|
||||||
|
elevenlabs-tts-tool synthesize "Text" --format pcm_44100
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Issue: Emotional tags not working**
|
||||||
|
|
||||||
|
**Symptom:** Emotion tags like `[happy]` are spoken literally
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
1. Ensure using v3 model:
|
||||||
|
```bash
|
||||||
|
elevenlabs-tts-tool synthesize "[happy] Text" --model eleven_v3
|
||||||
|
```
|
||||||
|
2. Place tags at beginning of phrases
|
||||||
|
3. Test with different voices (some work better than others)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Issue: Too many SSML breaks causing issues**
|
||||||
|
|
||||||
|
**Symptom:** Audio artifacts, speedup, or noise with multiple `<break>` tags
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
1. Limit to 2-4 breaks per generation
|
||||||
|
2. Use maximum 3 seconds per break
|
||||||
|
3. Consider splitting into multiple generations:
|
||||||
|
```bash
|
||||||
|
elevenlabs-tts-tool synthesize "Part 1" --output part1.mp3
|
||||||
|
elevenlabs-tts-tool synthesize "Part 2" --output part2.mp3
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Getting Help
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Main help
|
||||||
|
elevenlabs-tts-tool --help
|
||||||
|
|
||||||
|
# Command-specific help
|
||||||
|
elevenlabs-tts-tool synthesize --help
|
||||||
|
elevenlabs-tts-tool list-voices --help
|
||||||
|
elevenlabs-tts-tool info --help
|
||||||
|
|
||||||
|
# Version information
|
||||||
|
elevenlabs-tts-tool --version
|
||||||
|
```
|
||||||
|
|
||||||
|
**Additional Resources:**
|
||||||
|
- **GitHub Issues**: https://github.com/dnvriend/elevenlabs-tts-tool/issues
|
||||||
|
- **ElevenLabs Docs**: https://elevenlabs.io/docs
|
||||||
|
- **API Reference**: https://elevenlabs.io/docs/api-reference
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
## 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
|
||||||
Reference in New Issue
Block a user