Use Cases and Examples
Relevant source files
The following files were used as context for generating this wiki page:This document provides an overview of the use cases and examples for the Voice ElevenLabs plugin. The plugin integrates ElevenLabs v3's text-to-speech (TTS) capabilities into the Claude Code environment, enabling natural voice output, multi-speaker dialogues, voice creation, audio transcription, and automated voice notifications.
Sources: README.md:5-6
The system is designed to be used in two primary ways: through explicit user commands (e.g., /speak) and through automated, event-driven voice responses. The voice-assistant agent and voice-responses skill define the behavior for automatic verbal feedback, such as summarizing actions or providing notifications for hands-free usage.
Sources: agents/voice-assistant.md:1-2, skills/voice-responses.md:1-5
Core Commands
The plugin offers a suite of commands to interact with the ElevenLabs API.
| Command | Description |
|---|---|
/speak [text] | Speak text with emotion tags like [excited], [whispers]. |
/dialogue | Generate multi-speaker conversations. |
/create-voice | Create a custom voice from a text description. |
/transcribe | Convert audio to text using Scribe v2. |
/voices | List available ElevenLabs voices. |
/voice-config | View and modify voice settings. |
| Sources: README.md:28-37 |
Basic Text-to-Speech (TTS)
The most fundamental use case is converting text to speech using the /speak command. This command leverages ElevenLabs v3 to produce audio, with the ability to add emotional nuance through special tags.
Sources: commands/speak.md:5-7
Emotion Tags
You can control the emotional delivery of the speech by embedding tags directly into the text.
| Tag | Description |
|---|---|
[excited] | Enthusiastic |
[whispers] | Quiet, intimate |
[laughs] / [laughing] | Natural laughter |
[sighs] | Thoughtful pause |
[angry] | Intense |
[sad] | Melancholic |
[nervous] | Hesitant |
[shouting] | Loud |
[sarcastically] | Dry humor |
| Sources: README.md:44-54, commands/speak.md:12-21 |
Examples
-
Simple Speech:
/speak Hello! I can talk now.Sources: demo-script.md:11
-
Speech with Emotion:
/speak [excited] The tests all passed!Sources: demo-script.md:15
-
Chained Emotions:
/speak [whispers] Don't tell anyone, but... [laughs] I love this feature!Sources: README.md:42-43
TTS Flow
The following diagram illustrates the process of converting text to speech with the /speak command.
This diagram shows the user initiating the /speak command, which is processed and sent to the ElevenLabs API to generate and play the corresponding audio.
Sources: commands/speak.md:25-31
Multi-Speaker Conversations
The /dialogue command generates realistic conversations between multiple speakers, complete with natural timing and interruptions.
Sources: commands/dialogue.md:5-7
The script format requires speaker names followed by their lines. Special features include:
- Interruptions: Use a trailing em-dash (
—) to have a speaker be cut off. - Emotional Cues: Each speaker can have their own
[audio tags]. - Voice Assignment: By default, voices are assigned automatically. You can also specify a voice for each speaker, e.g.,
Alice (voice: Rachel): Hello!.
Sources: commands/dialogue.md:12-28
Example
/dialogue "Alice: Hey, did you see the new feature?
Bob: [excited] Yes! It's incredible!
Alice: [laughs] I knew you'd love it."
Sources: README.md:59-62
Voice Customization
The plugin allows for both using pre-defined voices and creating new, custom ones.
Listing and Selecting Voices
You can list available voices with /voices and change the active voice by setting the ELEVENLABS_VOICE_ID environment variable or using the /voice-config set-voice command.
Sources: commands/voices.md:17-19, commands/voice-config.md:13-14
Default Voices:
| Voice | ID | Style |
|---|---|---|
| George | JBFqnCBsd6RMkjVDRZzb | Natural male (default) |
| Adam | pNInz6obpgDQGcFmaJgB | Deep male |
| Rachel | 21m00Tcm4TlvDq8ikWAM | Natural female |
| Domi | AZnzlk1XvdvUeBnXmlld | Young female |
| Sources: commands/voices.md:8-15, commands/voice-config.md:15-19 |
Creating a New Voice
The /create-voice command uses ElevenLabs Voice Design v3 to generate a unique AI voice from a text description, without needing audio samples.
Sources: commands/create-voice.md:5-6
The process involves describing the desired voice's age, gender, accent, and tone. The API returns three options for you to preview and select.
Sources: commands/create-voice.md:8-15
This flowchart depicts the workflow for creating a custom voice from a text prompt.
Sources: commands/create-voice.md:1-32
Example:
/create-voice "deep male narrator voice, gravelly, like a classic audiobook reader"
Sources: commands/create-voice.md:23-24
Audio Transcription
The /transcribe command converts audio files (from a local path or URL) into text using ElevenLabs Scribe v2. It supports multiple audio formats, speaker diarization (identifying different speakers), and word-level timestamps.
Sources: commands/transcribe.md:5-13
Use Cases:
- Transcribing meeting recordings
- Converting voice memos to text
- Generating captions for podcasts
Sources: commands/transcribe.md:30-34
Example:
/transcribe file:~/Downloads/meeting.mp3
Sources: commands/transcribe.md:25-26
Automated Voice Notifications
The plugin uses hooks to trigger voice notifications automatically for certain events within Claude Code, providing ambient, hands-free feedback.
Sources: README.md:80-85
The core events are defined in hooks.json:
| Event | Script/Command | Description |
|---|---|---|
Stop | hooks/scripts/stop-voice.sh | Announce "[project]: done" when Claude finishes. |
SubagentStop | hooks/scripts/subagent-voice.sh | Announce "[project]: [task]" when a subagent completes. |
Notification | claude-voice-notifications | Announce when Claude needs permission or input. |
| Sources: hooks/hooks.json:2-15 |
Notification Flow
This diagram shows how events trigger voice notifications.
This diagram illustrates that Claude Code events trigger specific shell scripts. These scripts format a message (e.g., "$project: done") and pipe it to the claude-voice-notifications utility, which then uses ElevenLabs to speak the message.
Sources: hooks/hooks.json, hooks/scripts/stop-voice.sh, hooks/scripts/subagent-voice.sh
For example, the subagent-voice.sh script extracts the project name from the current working directory and the task description from the transcript to create a concise spoken update like "my-project: refactor login component".
Sources: hooks/scripts/subagent-voice.sh:5-29