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