Skip to main content
The ElevenLabs integration generates professional voice narration for the Dream Awakening phase, creating audio announcements of the winning agent.

​
Overview

The module handles:
  • Text-to-speech conversion using ElevenLabs API
  • Cloned voice support for personalized narration
  • Winner announcement script generation
  • Audio file management (MP3 format)
  • Voice configuration and quality settings
Requires an ElevenLabs API key. Sign up at elevenlabs.io to get started.

​
Configuration

​
Environment Variables

​
ELEVENLABS_API_KEY
string
required
Your ElevenLabs API key for authentication
​
ELEVENLABS_CLONED_VOICE_ID
string
Optional custom voice ID. Defaults to Rachel (ElevenLabs default voice) if not provided.

​
Configuration Functions

"""Get ElevenLabs API key and voice ID from environment.

Returns:
    tuple[Optional[str], Optional[str]]: (api_key, voice_id)
"""

​
Core Functions

​
generate_audio

Convert text to speech using ElevenLabs API. 
def generate_audio(
    text: str,
    output_path: Optional[str] = None,
    voice_id: Optional[str] = None,
) -> Optional[bytes]:

​
Parameters

​
text
string
required
The text to convert to speech. Can be multi-line with natural pauses.
​
output_path
string
Optional path to save the generated MP3 file. Parent directories are created automatically.
​
voice_id
string
Optional voice ID to use. Overrides ELEVENLABS_CLONED_VOICE_ID env var.Defaults to Rachel (ID: EXAVITQu4vr4xnSDxMaL) if not provided.

​
Returns

​
audio_bytes
bytes | None
MP3 audio data as bytes if successful, None if API key not configured or request failed

​
Example

from src.elevenlabs import generate_audio

audio = generate_audio(
    text="The winner is Agent Gamma with 92.5 points.",
    output_path="outputs/announcement.mp3",
)

if audio:
    print(f"Generated {len(audio)} bytes of audio")
else:
    print("Failed to generate audio")

​
generate_winner_script

Generate a narration script for the winner announcement. 
def generate_winner_script(
    winner_name: str,
    winner_score: float,
    objective: str,
) -> str:

​
Parameters

​
winner_name
string
required
The name of the winning agent (e.g., “Agent Gamma”)
​
winner_score
float
required
The final winning score (0-100)
​
objective
string
required
The original objective from the Dreamcatcher phase

​
Returns

​
script
string
Formatted narration script ready for text-to-speech conversion

​
Example

from src.elevenlabs import generate_winner_script

script = generate_winner_script(
    winner_name="Agent Gamma",
    winner_score=92.5,
    objective="Build a Discord bot for weekly AI events",
)

print(script)
# Output:
# The winner is Agent Gamma with 92.5 points.
# 
# After competing in the arena, Agent Gamma emerged as the clear choice 
# for the objective: Build a Discord bot for weekly AI events.
# 
# The winning code has been published and is ready for review. 
# Another dream successfully forged.

​
generate_winner_audio

Convenience function that generates script and audio in one call. 
def generate_winner_audio(
    winner_name: str,
    winner_score: float,
    objective: str,
    output_path: Optional[str] = None,
) -> Optional[bytes]:

​
Parameters

​
winner_name
string
required
The name of the winning agent
​
winner_score
float
required
The final winning score (0-100)
​
objective
string
required
The original objective
​
output_path
string
Optional path to save the MP3 file

​
Returns

​
audio_bytes
bytes | None
MP3 audio data if successful, None otherwise

​
Example

from src.elevenlabs import generate_winner_audio

audio = generate_winner_audio(
    winner_name="Agent Beta",
    winner_score=95.0,
    objective="Weekly AI events for Discord",
    output_path="outputs/winner_announcement.mp3",
)

if audio:
    print("Winner announcement audio generated!")

​
Voice Configuration

The module uses the following voice settings for optimal narration quality: 
{
  "model_id": "eleven_monolingual_v1",
  "voice_settings": {
    "stability": 0.5,
    "similarity_boost": 0.75
  }
}

​
Voice Parameters

​
model_id
string
default:"eleven_monolingual_v1"
The ElevenLabs model to use. eleven_monolingual_v1 provides high-quality English narration.
​
stability
float
default:"0.5"
Controls voice consistency (0.0-1.0). Higher = more consistent, lower = more expressive.
​
similarity_boost
float
default:"0.75"
How closely to match the original voice (0.0-1.0). Higher = closer match to cloned voice.

​
Available Voices

​
Default Voices

​
Rachel
string
ID: EXAVITQu4vr4xnSDxMaLProfessional, clear female voice. Used as default if no custom voice is configured.
​
Josh
string
ID: TxGEqnHWrfWFTfGW9XjXDeep, authoritative male voice.
​
Bella
string
ID: EXAVITQu4vr4xnSDxMaLSoft, friendly female voice.

​
Custom Voices

To use a cloned voice:
  1. Visit ElevenLabs Voice Lab
  2. Create or clone a voice
  3. Copy the Voice ID
  4. Add to .env: 
    ELEVENLABS_CLONED_VOICE_ID=your_voice_id_here

​
Error Handling

if not api_key:
    return None  # Silently return None if not configured
The module uses graceful degradation - if ElevenLabs is not configured or fails, it returns None rather than raising exceptions.

​
Audio Output

​
Format Specifications

​
Format
string
MP3 (MPEG Audio Layer 3)
​
Bitrate
string
Variable (optimized by ElevenLabs)
​
Sample Rate
string
44.1 kHz (CD quality)
​
Channels
string
Mono

​
File Management

# Automatic directory creation
generate_audio(
    text="Hello",
    output_path="deep/nested/path/audio.mp3"  # Creates all parent dirs
)

# File size estimation
# ~1 KB per second of audio (varies by content)
import os
audio = generate_audio("Short text", "output.mp3")
file_size = os.path.getsize("output.mp3")
print(f"Size: {file_size / 1024:.1f} KB")

​
Best Practices

Script Length: Keep narration under 2 minutes for optimal listener engagement.
Punctuation: Use periods and commas to create natural pauses in the narration.
Voice Selection: Test different voices to find the best match for your brand tone.
Error Handling: Always check for None return values before using audio data.

​
Usage Patterns

# Most common: generate and save to disk
audio = generate_audio(
    text=script,
    output_path="announcement.mp3"
)

if audio:
    # File is saved, audio bytes also available
    pass

Build docs developers (and LLMs) love

Get started for freeTalk to us