voice-generation

Voice Generation Skill

Generate realistic speech using AI (Google Gemini TTS, ElevenLabs, OpenAI TTS).

Prerequisites

At least one API key is required:

• GOOGLE_API_KEY - For Google Gemini TTS (same key as video/image/music) ✅
• ELEVENLABS_API_KEY - For ElevenLabs high-quality voice synthesis
• OPENAI_API_KEY - For OpenAI TTS voices

Available APIs

Google Gemini TTS (Recommended - Same API Key)

• Best for: Podcasts, dialogues, audiobooks with style control
• Voices: 30 voices with natural language style control
• Multi-speaker: Up to 2 speakers for dialogues ✅
• Languages: 24 languages (auto-detected)
• Features: Control style, accent, pace via prompts
• Output: 24kHz WAV
• API Key: Same GOOGLE_API_KEY as video/image/music ✅

ElevenLabs (Best Quality)

• Best for: Natural-sounding voices, voice cloning, long-form content
• Voices: 100+ pre-made voices + custom voice cloning
• Languages: 29+ languages
• Models: Eleven Multilingual v2, Eleven Turbo v2

OpenAI TTS (Simplest)

• Best for: Quick, reliable text-to-speech with consistent quality
• Voices: alloy, echo, fable, onyx, nova, shimmer
• Models: tts-1 (fast), tts-1-hd (high quality)
• Output: MP3, Opus, AAC, FLAC

Workflow

Step 1: Understand the Request

Parse the user's voice request for:

• Text content: What should be spoken?
• Voice type: Male, female, specific character?
• Tone: Professional, casual, dramatic, cheerful?
• Use case: Narration, voiceover, audiobook, notification?
• Language: English, Spanish, other?
• Speed: Normal, slow, fast?

Step 2: Select Voice and API

Choose based on requirements:

Use Case	Recommended API	Reason
Default / Same key as video	Gemini TTS	Same GOOGLE_API_KEY ✅
Multi-speaker dialogue	Gemini TTS	Up to 2 speakers built-in
Style/accent control	Gemini TTS	Natural language prompts
Voice cloning	ElevenLabs	Only API with cloning
100+ voice options	ElevenLabs	Widest selection
Audiobook/podcast	ElevenLabs or Gemini	Both excellent for long content
Quick narration	OpenAI TTS	Fast, reliable
Budget-conscious	OpenAI TTS	Lower cost

Step 3: Prepare the Text

Optimize text for speech:

1. Add pauses: Use commas, periods for natural rhythm
2. Spell out numbers: "1,234" → "one thousand two hundred thirty-four" (if needed)
3. Handle acronyms: "NASA" vs "N.A.S.A." depending on pronunciation
4. Mark emphasis: Some APIs support emphasis markers

Example transformation:

• Original: "The Q4 2024 results show a 15% YoY increase."
• Optimized: "The Q4 2024 results show a fifteen percent year-over-year increase."

Step 4: Generate the Audio

Execute the appropriate script from ${CLAUDE_PLUGIN_ROOT}/skills/voice-generation/scripts/:

For Google Gemini TTS (single speaker):

python3 ${CLAUDE_PLUGIN_ROOT}/skills/voice-generation/scripts/gemini_tts.py \
  --text "Welcome to our podcast!" \
  --voice "Charon"

Gemini TTS with style direction:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/voice-generation/scripts/gemini_tts.py \
  --text "Have a wonderful day!" \
  --voice "Puck" \
  --style "Say cheerfully with a British accent:"

Gemini TTS multi-speaker (dialogue):

python3 ${CLAUDE_PLUGIN_ROOT}/skills/voice-generation/scripts/gemini_tts.py \
  --multi \
  --speaker "Host:Charon" \
  --speaker "Guest:Aoede" \
  --text "Host: Welcome to the show!
Guest: Thanks for having me!"

For ElevenLabs:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/voice-generation/scripts/elevenlabs.py \
  --text "Your text here" \
  --voice "Rachel" \
  --model "eleven_multilingual_v2"

For OpenAI TTS:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/voice-generation/scripts/openai_tts.py \
  --text "Your text here" \
  --voice "nova" \
  --model "tts-1-hd"

List Gemini voices:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/voice-generation/scripts/gemini_tts.py --list-voices

Step 5: Deliver the Result

1. Provide the generated audio file path
2. Mention the voice and settings used
3. Offer to:
   • Try a different voice
   • Adjust speed or tone
   • Use a different API
   • Generate in a different format

Error Handling

Missing API key: Inform the user which key is needed:

• Gemini TTS: Same GOOGLE_API_KEY as video/image - https://aistudio.google.com/apikey
• ElevenLabs: https://elevenlabs.io
• OpenAI: https://platform.openai.com/api-keys

Gemini TTS requires google-genai package: pip install google-genai

Text too long: Split into chunks and concatenate, or suggest shorter text.

Rate limit: Suggest waiting or trying a different API.

Unsupported language: Suggest an alternative API that supports the language.

Multi-speaker limit: Gemini TTS supports max 2 speakers. For more, use ElevenLabs with multiple calls.

Voice Selection Guide

Google Gemini TTS Voices (30 voices)

Style	Voices	Best For
Bright/Upbeat	Zephyr, Puck, Aoede, Laomedeia	Marketing, cheerful content
Firm/Informative	Charon, Kore, Orus, Rasalgethi	News, tutorials, professional
Soft/Warm	Achernar, Sulafat, Vindemiatrix	Meditation, gentle narration
Smooth	Algieba, Despina, Callirrhoe	Audiobooks, storytelling
Clear	Erinome, Iapetus, Pulcherrima	Instructions, clarity
Character	Fenrir (excitable), Enceladus (breathy), Algenib (gravelly), Gacrux (mature)	Character voices, drama
Friendly	Achird, Zubenelgenubi (casual)	Casual, conversational

Gemini TTS Style Tips:

• Use natural language: --style "Say angrily:" or --style "Whisper mysteriously:"
• Specify accents: --style "Speak with a British accent from London:"
• Control pace: --style "Speak slowly and deliberately:"
• Combine: --style "Say excitedly with a Southern US accent:"

OpenAI TTS Voices

Voice	Description	Best For
alloy	Neutral, balanced	General purpose
echo	Warm, conversational	Podcasts, casual
fable	Expressive, British	Storytelling
onyx	Deep, authoritative	Narration, professional
nova	Friendly, upbeat	Marketing, tutorials
shimmer	Soft, gentle	Meditation, ASMR

ElevenLabs Popular Voices

Voice	Description	Best For
Rachel	Young female, American	Narration, audiobooks
Domi	Young female, energetic	Marketing, ads
Bella	Young female, soft	Storytelling
Antoni	Young male, well-rounded	Narration
Josh	Young male, deep	Audiobooks
Arnold	Mature male, authoritative	Documentary
Adam	Middle-aged male, deep	Narration
Sam	Young male, raspy	Character voices

Best Practices

For Narration

• Use a consistent voice throughout
• Add natural pauses between paragraphs
• Consider pacing for the content type

For Dialogue

• Use different voices for different characters
• Match voice characteristics to character descriptions
• Adjust speed for emotional scenes

For Accessibility

• Use clear, well-paced speech
• Avoid overly stylized voices
• Test with screen readers if applicable

API Comparison

Feature	Gemini TTS	ElevenLabs	OpenAI TTS
API Key	GOOGLE_API_KEY ✅	ELEVENLABS_API_KEY	OPENAI_API_KEY
Voice quality	Excellent	Excellent	Very good
Voice variety	30 voices	100+ voices	6 voices
Multi-speaker	✅ Up to 2	❌ No	❌ No
Style control	✅ Natural language	Limited	❌ No
Voice cloning	❌ No	✅ Yes	❌ No
Languages	24	29+	50+
Speed control	Via prompts	Yes	Yes (0.25-4x)
Max length	32k tokens	5,000 chars	4,096 chars
Output format	WAV (24kHz)	MP3, WAV	MP3, Opus, AAC, FLAC
Same key as video/image	✅ Yes	❌ No	❌ No