Advanced Voice Design
Relevant source files
The following files were used as context for generating this wiki page:
The voice-elevenlabs plugin leverages the ElevenLabs v3 API to provide advanced voice design capabilities directly within the Claude Code environment. This goes beyond simple text-to-speech (TTS) by enabling the creation of unique AI voices from text descriptions, controlling the emotional delivery of speech, and generating realistic multi-speaker conversations. These features allow for a more expressive, natural, and context-aware auditory experience.
The core components of Advanced Voice Design are the /create-voice command for generating new voices, the /speak command with its emotional audio tags, and the /dialogue command for crafting conversations. These tools are complemented by configuration commands like /voices and /voice-config for managing the available voice assets.
Sources: README.md:1-10, commands/create-voice.md:1-5, commands/speak.md:1-5, commands/dialogue.md:1-5
Custom Voice Creation
The plugin allows users to generate entirely new, unique AI voices using a natural language text description, eliminating the need for audio samples. This is handled by the /create-voice command, which utilizes the ElevenLabs Voice Design v3 API.
Sources: commands/create-voice.md:1-9
Voice Generation Flow
The process begins with the user providing a descriptive prompt. The system then interacts with the ElevenLabs API to generate three candidate voices. After previewing the options, the user selects their preferred voice, which is then saved to their account for future use.
The diagram below illustrates the voice creation workflow.
Voice Description Guidelines
To achieve the desired voice, descriptions should be specific. The system can interpret a range of attributes.
| Attribute | Description | Examples |
|---|---|---|
| Age | The perceived age of the speaker. | young, middle-aged, elderly |
| Gender | The gender identity of the speaker. | male, female, neutral |
| Accent | The regional or national accent. | British, Southern US, French |
| Tone | The emotional or stylistic tone. | warm, authoritative, playful |
| Quality | The physical quality of the voice. | clear, raspy, smooth, deep |
| Audio Quality | The recording environment. | perfect audio quality, slight room reverb, radio effect |
Sources: commands/create-voice.md:11-20, commands/create-voice.md:28-31
An example command to create a voice:
/create-voice "middle-aged New Yorker with rising intonation and a half-smile in his voice, like a friendly cab driver telling stories"
Sources: commands/create-voice.md:25-27
Emotional Speech Synthesis
The /speak command enables dynamic emotional control over speech output using inline "audio tags". This feature of the ElevenLabs v3 model allows for adding nuanced and expressive delivery to any text.
Sources: README.md:40-42, commands/speak.md:1-5
Available Audio Tags
A variety of tags are available to convey different emotions and actions.
| Tag | Description |
|---|---|
[excited] | Enthusiastic delivery |
[whispers] | Quiet, intimate tone |
[laughs] / [laughing] | Natural laughter |
[sighs] | A thoughtful or weary sigh |
[angry] | Intense, frustrated tone |
[sad] | Melancholic delivery |
[nervous] | Hesitant speech |
[shouting] | Loud, emphatic delivery |
[sarcastically] | Dry, sarcastic humor |
Sources: README.md:45-55, commands/speak.md:9-18
Implementation Flow
When a user invokes the /speak command, the text (including any tags) is processed and sent for synthesis. The primary method involves piping the message to the claude-voice-notifications CLI tool, which handles the API interaction.
The following sequence diagram shows the process for the /speak command.
Sources: commands/speak.md:22-24, README.md:24-26
Multi-Speaker Dialogue
The /dialogue command generates realistic, multi-speaker conversations. It leverages ElevenLabs v3's dialogue mode to manage natural timing, interruptions, and distinct voices for each speaker.
Sources: commands/dialogue.md:1-5, README.md:57-59
Dialogue Features
- Natural Interruptions: A speaker can cut another off by ending their line with a dash (
—). - Per-Speaker Emotions: Each speaker can have their own audio tags (e.g.,
[excited],[laughs]). - Voice Assignment: By default, the first speaker uses the configured voice and others are assigned complementary voices. Voices can also be assigned explicitly.
Example of explicit voice assignment:
Alice (voice: Rachel): Hello!
Bob (voice: Adam): Hi there!
Sources: commands/dialogue.md:13-26
Dialogue Generation Flow
The user provides a script, which is then parsed into speaker and line pairs. The system uses the ElevenLabs v3 dialogue API to synthesize the full conversation, applying any specified emotional tags and handling the conversational flow.
This diagram shows the process of generating a dialogue.
Sources: commands/dialogue.md:34-38
Voice Management and Configuration
The plugin provides commands to manage and configure the voices used for TTS.
Sources: commands/voice-config.md, commands/voices.md
Listing and Setting Voices
The /voices command lists available voices, while /voice-config set-voice [voice_id] changes the default voice used for synthesis. The default voice is determined by the ELEVENLABS_VOICE_ID environment variable.
Sources: commands/voices.md:1-5, commands/voice-config.md:9-11, commands/voices.md:17-19
The following default voices are provided for convenience:
| Voice | ID | Style |
|---|---|---|
| George | JBFqnCBsd6RMkjVDRZzb | Natural male (default) |
| Adam | pNInz6obpgDQGcFmaJgB | Deep male |
| Rachel | 21m00Tcm4TlvDq8ikWAM | Natural female |
| Domi | AZnzlk1XvdvUeBnXmlld | Young female |
Sources: commands/voices.md:7-15, commands/voice-config.md:12-17
To fetch all custom and pre-made voices from an account, the following API call can be used:
curl -s "https://api.elevenlabs.io/v1/voices" \
-H "xi-api-key: $ELEVENLABS_API_KEY" | jq '.voices[] | {name, voice_id}'
Sources: commands/voices.md:21-24
Summary
The Advanced Voice Design capabilities of the voice-elevenlabs plugin transform Claude Code from a text-based assistant into a versatile voice-enabled agent. By providing tools to create custom voices, inject emotion into speech, and generate complex dialogues, the plugin offers a rich and highly customizable auditory experience. This functionality is critical for creating more natural human-computer interactions, improving accessibility, and enabling hands-free use cases.
Sources: agents/voice-assistant.md:1-5, skills/voice-responses.md:1-6