Advanced Dialogue Generation
Relevant source files
The following files were used as context for generating this wiki page:
This document outlines the architecture and features for generating expressive, multi-speaker speech using the ElevenLabs v3 integration within the Claude Code environment. This system provides a suite of commands for direct text-to-speech (TTS) synthesis, multi-speaker dialogue creation, and custom voice design.
The core of this functionality is exposed through several user-facing commands, including /speak, /dialogue, and /create-voice. These commands leverage the advanced features of the ElevenLabs v3 API, such as emotional audio tags, natural conversation flow, and voice design from text descriptions. The system also includes automated voice notifications triggered by system events.
Sources: README.md:8-11, README.md:25-33
Core Voice Commands
The plugin provides several commands to control voice generation.
| Command | Description | Source File |
|---|---|---|
/speak [text] | Speak text with optional emotion tags. | commands/speak.md |
/dialogue | Generate multi-speaker conversations with natural timing. | commands/dialogue.md |
/create-voice | Create a custom voice from a text description. | commands/create-voice.md |
/voices | List available ElevenLabs voices. | commands/voices.md |
/voice-config | View and modify voice settings. | commands/voice-config.md |
Sources: README.md:25-33
Multi-Speaker Dialogue (/dialogue)
The /dialogue command generates realistic, multi-speaker conversations using ElevenLabs v3's dialogue mode. It processes a simple script format to produce a single audio file with natural timing and interruptions.
Sources: commands/dialogue.md:1-5
Script Format
Dialogue is written with speaker names followed by their lines. Special syntax is used for emotional cues and interruptions.
Alice: Hey, have you seen the new feature?
Bob: [excited] Yes! It's amazing!
Alice: [laughs] I knew you'd love it.
Bob: [interrupting] Wait, there's more—
Alice: —I know, the audio tags!
Sources: commands/dialogue.md:8-15
Features
- Natural Interruptions: A speaker can cut another off by starting their line with a dash (
—). - Emotional Cues: Inline audio tags like
[excited]or[laughs]can be applied to individual lines. - Voice Assignment: By default, the first speaker uses the user's configured voice, and subsequent speakers use complementary voices. Voices can also be specified explicitly in the script (e.g.,
Alice (voice: Rachel): Hello!).
Sources: commands/dialogue.md:17-30
Processing Flow
The diagram below illustrates how a dialogue script is processed.
This diagram shows the process from the user's command to the final audio playback.
Sources: commands/dialogue.md:32-37
Expressive Speech (/speak)
The /speak command converts a single line of text to speech, with the ability to add emotional nuance using inline audio tags. This leverages the ElevenLabs v3 model.
Sources: commands/speak.md:1-5
Audio Tags
Emotions and delivery styles can be controlled by adding tags within the text.
| Tag | Description |
|---|---|
[excited] | Enthusiastic delivery |
[whispers] | Quiet, intimate tone |
[laughs] / [laughing] | Natural laughter |
[sighs] | Thoughtful pause |
[angry] | Intense, frustrated tone |
[sad] | Melancholic delivery |
[nervous] | Hesitant speech |
[shouting] | Loud, emphatic delivery |
[sarcastically] | Dry humor |
Sources: commands/speak.md:10-20, README.md:41-53
Implementation
The command can be implemented either by calling the claude-voice-notifications CLI tool or by making a direct request to the ElevenLabs API.
The diagram below shows the sequence for a direct API call.
This sequence shows the user command triggering an API call to ElevenLabs and the subsequent playback of the returned audio.
Sources: commands/speak.md:27-34
Voice Management
The plugin provides a comprehensive suite of tools for managing voices, from creation to configuration.
Voice Creation (/create-voice)
A unique AI voice can be generated from a text description using the /create-voice command, which utilizes ElevenLabs Voice Design v3. The process does not require any audio samples.
The description can include attributes such as:
- Age:
young,middle-aged - Gender:
male,female - Accent:
British,Southern US - Tone:
warm,authoritative - Quality:
clear,raspy
The command returns three voice candidates for the user to preview and select.
Sources: commands/create-voice.md:1-19
The following diagram shows the voice creation workflow.
This flowchart details the steps from providing a text description to receiving a new, usable voice ID.
Sources: commands/create-voice.md:34-39
Voice Configuration and Listing
Users can manage their voice settings using the /voice-config and /voices commands.
/voices: Lists available voices, including default options and any custom voices./voice-config: Allows viewing the current configuration, setting a new default voice ID, and testing the current setup.
The default voice can be changed by setting the ELEVENLABS_VOICE_ID environment variable or using /voice-config set-voice [voice_id].
Sources: commands/voices.md:1-5, 17-21, commands/voice-config.md:8-19
Default Voices
| Voice | ID | Style |
|---|---|---|
| George | JBFqnCBsd6RMkjVDRZzb | Natural male (default) |
| Adam | pNInz6obpgDQGcFmaJgB | Deep male |
| Rachel | 21m00Tcm4TlvDq8ikWAM | Natural female |
| Domi | AZnzlk1XvdvUeBnXmlld | Young female |
Sources: README.md:65-72, commands/voices.md:7-14
Automated Voice Integration
Beyond direct commands, the system uses hooks and agents to provide automated, hands-free voice feedback.
Voice Assistant Agent
The voice-assistant is a conversational agent designed to speak its responses aloud. It generates a concise spoken summary (1-3 sentences) of its full text response and uses ElevenLabs TTS to verbalize it, creating a more natural conversational flow.
Sources: agents/voice-assistant.md:1-13
Event-Driven Hooks
The plugin registers hooks to automatically trigger voice notifications for key events in the Claude Code lifecycle.
| Event | Description | Script |
|---|---|---|
Stop | Announces "[project]: done" when Claude finishes a task. | hooks/scripts/stop-voice.sh |
SubagentStop | Announces "[project]: [task]" when a subagent completes. | hooks/scripts/subagent-voice.sh |
Notification | Announces when Claude needs permission or input. | claude-voice-notifications |
Sources: hooks/hooks.json:2-16
The subagent-voice.sh script demonstrates this by extracting the project name and task description to build a concise spoken message, which is then sent to claude-voice-notifications.
# Build short message
if [ -n "$project" ] && [ -n "$description" ]; then
# Shorten description to ~30 chars
short_desc=$(echo "$description" | cut -c1-30 | sed 's/[[:space:]]*$//')
message="$project: $short_desc"
# ...
fi
# Send to ElevenLabs
echo "{\"hook_event_name\": \"Stop\", \"message\": \"$message\"}" | claude-voice-notifications
Sources: hooks/scripts/subagent-voice.sh:19-32
Summary
The Advanced Dialogue Generation system in the voice-elevenlabs plugin provides a powerful and flexible interface to the ElevenLabs v3 API. It supports single-line expressive speech, complex multi-speaker dialogues, and custom voice creation directly within the Claude Code environment. Combined with automated hooks and a dedicated voice agent, these features create an immersive and accessible user experience, enabling natural voice interaction for a wide range of development tasks.
Sources: README.md:8-11, skills/voice-responses.md:1-7