Command: /speak
Relevant source files
The following files were used as context for generating this wiki page:
The /speak command is a core feature of the voice-elevenlabs plugin, enabling Claude to convert text into audible speech using the ElevenLabs v3 Text-to-Speech (TTS) engine. Its primary function is to provide direct, on-demand voice output for any given text.
A key capability of the /speak command is its integration with ElevenLabs v3's audio tags, which allows for adding emotional nuance and expressiveness to the generated speech. This command is fundamental to the plugin's goal of creating a more natural, voice-enabled conversational experience. It is complemented by other commands like /voice-config for managing settings and /voices for listing available voices.
Sources: README.md:1-10, 24-26, commands/speak.md:1-5, agents/voice-assistant.md:3-5
Usage
The command is invoked by typing /speak followed by the text to be spoken. The full namespaced command is /voice-elevenlabs:speak.
Syntax:
/speak [text with optional emotion tags]
Sources: commands/speak.md:8-10, README.md:24-26
Examples:
- Basic text-to-speech:
/speak Hello! I can talk now. - Using emotion tags for expressive speech:
/speak [excited] The tests all passed! - Combining multiple tags in one sentence:
/speak [whispers] Don't tell anyone, but... [laughs] I love this feature!
Sources: demo-script.md:12, 16, 19, commands/speak.md:20-22, README.md:32-34
Audio Tags (Emotion Control)
The /speak command supports inline audio tags to control the emotional delivery of the speech, a feature of the ElevenLabs v3 model. These tags are placed within square brackets [] in the text.
Sources: commands/speak.md:12-14, README.md:29-31
| Tag | Description |
|---|---|
[excited] | Enthusiastic delivery |
[whispers] | Quiet, intimate |
[laughs] / [laughing] | Natural laughter |
[sighs] | Thoughtful pause |
[angry] | Intense, frustrated |
[sad] | Melancholic |
[nervous] | Hesitant |
[shouting] | Loud, emphatic |
[sarcastically] | Dry humor |
Sources: commands/speak.md:15-23, README.md:36-45
Implementation
The command's functionality can be implemented through two primary methods, both of which ultimately use the ElevenLabs API.
Sources: commands/speak.md:24-26
Method 1: claude-voice-notifications CLI
This method pipes a JSON payload to the claude-voice-notifications CLI tool, which handles the audio generation and playback. This is also how automated voice hooks for events like Stop are triggered.
Sources: commands/speak.md:28-30, README.md:19-21
echo '{"hook_event_name": "Stop", "message": "TEXT_HERE"}' | claude-voice-notifications
Sources: commands/speak.md:28-30
The following diagram illustrates the data flow for this implementation method.
Sources: commands/speak.md:28-30
Method 2: Direct ElevenLabs API Call
This method involves making a direct curl request to the ElevenLabs API endpoint for text-to-speech conversion. The API returns an audio file, which is then played locally using a command like afplay.
Sources: commands/speak.md:32-38
curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb" \
-H "xi-api-key: $ELEVENLABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "TEXT_HERE", "model_id": "eleven_v3_alpha"}' \
--output /tmp/speech.mp3 && afplay /tmp/speech.mp3
Sources: commands/speak.md:33-38
This sequence diagram shows the interaction between the plugin, the ElevenLabs API, and the local system.
Sources: commands/speak.md:33-38
Voice Configuration
The voice used by the /speak command is configurable. The default voice is "George", but it can be changed by setting the ELEVENLABS_VOICE_ID environment variable. The /voice-config command can be used to view the current configuration and set a new voice, while the /voices command lists all available voices from your ElevenLabs account.
Sources: README.md:65-66, commands/voice-config.md:1-5, 12-13, commands/voices.md:1-5, 15-17
The following pre-defined voices are available:
| Voice | ID | Style |
|---|---|---|
| George | JBFqnCBsd6RMkjVDRZzb | Natural male (default) |
| Adam | pNInz6obpgDQGcFmaJgB | Deep male |
| Rachel | 21m00Tcm4TlvDq8ikWAM | Natural female |
| Domi | AZnzlk1XvdvUeBnXmlld | Young female |
Sources: README.md:59-64, commands/voices.md:8-13, commands/voice-config.md:14-18
Agent Behavior Integration
The /speak capability is a core component of the voice-assistant agent. This agent is designed to speak its responses aloud, but with specific guidelines to ensure a natural conversational flow. It is instructed to generate a concise spoken summary (1-3 sentences) of its full text response and use the configured ElevenLabs voice.
This behavior is further defined by the voice-responses skill, which activates when a user asks for a verbal explanation or uses terms like "speak" or "read aloud". The skill mandates that spoken summaries should be brief (max 50 words) and use conversational language, avoiding technical syntax.
Sources: agents/voice-assistant.md:3-10, 20-22, skills/voice-responses.md:3-10, 17-21