elevenlabs

name	elevenlabs
description	Text-to-speech, multi-voice dialogue, custom voice design, sound effects, music generation, and audio processing using the ElevenLabs API via the el CLI. Use for voice generation, character voices, designing new voices (e.g. children/creatures), expressive narration with audio tags, audio content creation, or sound design.
argument-hint	[tts|sfx|music|voices] [text or options]
allowed-tools	["Bash","Read"]

Variables

EL_CLI: python3 ./scripts/el.py # Path to the el CLI wrapper DEFAULT_VOICE: Aa6nEBJJMKJwJkCx8VU2 # Quentin — calm, male, narrator. Override with --voice DEFAULT_MODEL: eleven_multilingual_v2 # Steady audiobook default. Use eleven_v3 for expressive (audio tags), eleven_flash_v2_5 for low-latency EXPRESSIVE_MODEL: eleven_v3 # Most expressive: supports inline [audio tags], multi-voice dialogue VOICE_DESIGN_MODEL: eleven_ttv_v3 # Text-to-Voice: design custom voices from a prompt (e.g. a child's voice) OUTPUT_DIR: ./audio # Where generated audio files are saved OUTPUT_FORMAT: mp3_44100_128 # Options: mp3_44100_128, wav_44100, pcm_44100, opus_48000_128

References

Command syntax & flags

• IF: need full flag details or exact syntax for any command
• THEN: Read reference/commands.md
• EXAMPLES: "what flags does dialogue take", "how do I pass stems variation"

v3 audio tags, dialogue & voice design

• IF: working with eleven_v3 expressivity, multi-voice dialogue, or designing voices (the rot-prone model IDs, tag list, and limits live here, dated)
• THEN: Read reference/api-notes.md
• EXAMPLES: "make two characters talk in one clip", "design a child's voice", "which audio tags exist"

Workflow

1. Check Prerequisites

   • IF: which python3 fails → report "python3 not found" and stop (no pip packages needed — stdlib only)
   • IF: the el.py script from EL_CLI path not found → report "el CLI missing" and stop
   • IF: API key not available → run <EL_CLI> models as a lightweight auth check. If it fails with "ELEVENLABS_API_KEY not set", stop and tell the user:

     ELEVENLABS_API_KEY is not configured. Set it in one of:

     • Project-level: add ELEVENLABS_API_KEY=your-key to ./.env
     • Global (recommended for personal use): add ELEVENLABS_API_KEY=your-key to ~/.claude/.env
     • Shell: export ELEVENLABS_API_KEY=your-key

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

   • Example: python3 found, el.py exists, API key valid → proceed
   • Tool: Bash

2. Discover Voices

   • Search the ElevenLabs voice library for the right voice
   • Example: "find a calm female narrator" → <EL_CLI> voices --search "calm female narrator" --limit 5
   • Example: "list my cloned voices" → <EL_CLI> voices --category cloned --limit 10
   • Get details: <EL_CLI> voice <voice_id>
   • Tool: Bash <EL_CLI> voices [--search <query>] [--category <cat>] [--limit <n>]

3. Generate Speech (TTS)

   • Convert text to audio using a voice and model
   • IF: no --voice → use DEFAULT_VOICE
   • IF: no --model → use DEFAULT_MODEL
   • IF: default voice returns 404 or error → search for a replacement: <EL_CLI> voices --search "calm male narrator" --limit 3
   • IF: fine-tuning → add --stability, --similarity, --style, --speed
   • IF: expressive delivery wanted (storytelling, character voices) → use --model eleven_v3 with inline [audio tags]:
     • Tags are lowercase in square brackets, inline: , , , , ,

Works well with

Optional collaborators — elevenlabs runs standalone and these degrade gracefully if absent.

• speak — the provider-agnostic TTS primitive that falls back through elevenlabs first (then macOS say); use speak when you just need audio out, elevenlabs directly for voice design, dialogue, SFX, and music.
• elevenlabs-operator / elevenlabs-voice-designer (agents) — drive this skill for parallel generation and voice casting.