Tool: speak()

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/server.py
• pyproject.toml
• src/init.py
• LICENSE

The speak() tool is a core function within the Reachy Mini MCP server, designed to give the robot a voice and enable expressive, choreographed performances. It converts text to audible speech, plays it through the robot's speaker, and can optionally trigger physical movements synchronized with the speech. This tool is central to creating interactive and life-like behaviors for the robot.

The speak() function is part of a suite of seven tools designed for AI systems to control the Reachy Mini robot, allowing for voice, listening, vision, and emotional expression. It supports multiple Text-to-Speech (TTS) providers and can be combined with a subsequent listening action to create a conversational loop. The project is licensed under the MIT License.

Sources: src/server.py:657-755, README.md:10-14, LICENSE

Core Functionality

The speak() function serves as the primary interface for the robot's vocalization. It is exposed as an MCP tool and handles various input types, from simple text to complex choreographed sequences.

Sources: src/server.py:657-679

Parameters

The tool accepts the following arguments:

Parameter	Type	Description	Default
text	str	The text to be spoken. Can contain [move:name] markers for choreography or be a path to an audio file (.wav, .mp3, .ogg).	N/A (Required)
listen_after	float	The duration in seconds to listen for a response after speaking. A value of 0 disables listening.	0
voice	Literal	The specific Grok voice to use. Only applicable when using Grok Voice TTS.	"eve"

The available Grok voices are ara, eve, leo, rex, and sal.

Sources: src/server.py:657-679, README.md:12

Execution Flow

The function's logic branches based on the content of the text parameter. It can handle direct audio file playback, simple text-to-speech, or complex choreographed speech with embedded movements.

The diagram below illustrates the main execution paths within the speak() function.

Choreographed Speech

A key feature of speak() is its ability to synchronize speech with physical movements. This is achieved by embedding move markers directly into the text string.

Sources: README.md:16-19, src/server.py:695-731

Syntax

Moves are embedded using the format [move:name], where name corresponds to a built-in emotion or a recorded move from the Pollen Robotics library.

Example:

speak("[move:curious1] What's this? [move:surprised1] Oh wow!")

Sources: README.md:18, src/server.py:663-664

Implementation

When a string with move markers is detected, the _parse_choreographed_text helper function is called to split the text into a list of text and move segments. The speak function then iterates through these segments. A move is triggered and awaited just before its corresponding text segment is spoken, ensuring synchronization.

The following sequence diagram shows the interaction for a choreographed phrase.

Text-to-Speech (TTS) Providers

The speak() tool relies on a helper function, text_to_speech, which dynamically selects a TTS provider based on environment variable configuration. It prioritizes Grok Voice and falls back to Deepgram Aura.

Sources: src/server.py:441-447, README.md:43-46

Provider Selection Logic

1. Grok Voice: If the XAI_API_KEY environment variable is set, grok_text_to_speech is used. This function interacts with the x.ai API. The specific voice (eve, ara, etc.) is chosen from the voice parameter, the GROK_VOICE environment variable, or a default.
2. Deepgram: If XAI_API_KEY is not set, the system falls back to deepgram_text_to_speech, which requires the DEEPGRAM_API_KEY. This function calls the Deepgram Aura-2 model.

This flow is visualized below:

Listening After Speaking

The listen_after parameter enables a conversational turn. If its value is greater than zero, the robot will activate its microphones to capture and transcribe audio after it has finished speaking.

To prevent the robot from transcribing its own voice, the system first waits for all active movements and audio playback to complete by calling _wait_for_moves_complete(). It then calls the internal _do_listen() helper, which records audio for the specified duration and uses speech_to_text() (via Deepgram Nova-2) to get a transcription.

The final return string from speak() will include both the confirmation of speech and the transcribed text, separated by a pipe (|).

Sources: src/server.py:734-747, 759-805

Dependencies

The speak() function and its helpers rely on several external packages and environment variables.

Dependency	Purpose	Source
fastmcp	MCP tool framework	pyproject.toml:12
reachy-mini	Robot SDK for audio playback and movement	pyproject.toml:13
openai	SDK used to connect to Grok Voice API	pyproject.toml:14
XAI_API_KEY	Env Var for Grok Voice authentication	README.md:58
DEEPGRAM_API_KEY	Env Var for Deepgram TTS/STT authentication	README.md:60

Sources: pyproject.toml:11-15, README.md:57-62, src/server.py:444, 453, 574