Voicemode Parameters Reference

Voicemode Parameters Reference

Core Parameters

message (required)

Type: string The message to speak to the user.

wait_for_response

Type: boolean (default: true) Whether to listen for a voice response after speaking.

Timing Parameters

listen_duration_max

Type: number (default: 120.0 seconds) Maximum time to listen for response. The tool handles silence detection well.

When to override:

• Silence detection is disabled and you need specific timeout
• Response will be exceptionally long (>120s)
• Special timing requirements

Usually: Let default and silence detection handle it.

listen_duration_min

Type: number (default: 2.0 seconds) Minimum recording time before silence detection can stop.

Use cases:

• Complex questions: 2-3 seconds
• Open-ended prompts: 3-5 seconds
• Quick responses: 0.5-1 second

timeout (DEPRECATED)

Use listen_duration_max instead. Only applies to LiveKit transport.

Voice & TTS Parameters

voice

Type: string (optional) Override TTS voice selection.

When to specify:

• User explicitly requests specific voice
• Speaking non-English languages (see languages resource)

Examples:

• OpenAI: nova, shimmer, alloy, echo, fable, onyx
• Kokoro: af_sky, af_sarah, am_adam, ef_dora, etc.

Important: Never use 'coral' voice.

tts_provider

Type: "openai" | "kokoro" (optional) TTS provider selection.

When to specify:

• User explicitly requests provider
• Failover testing
• Non-English languages (usually kokoro)

Usually: Let system auto-select.

tts_model

Type: string (optional) TTS model selection.

Options:

• tts-1 - Standard quality (OpenAI)
• tts-1-hd - High definition (OpenAI)
• gpt-4o-mini-tts - Emotional speech support (OpenAI)

When to specify:

• Need HD quality
• Want emotional speech (with tts_instructions)

Usually: Let system auto-select.

tts_instructions

Type: string (optional) Tone/style instructions for emotional speech.

Requirements: Only works with tts_model="gpt-4o-mini-tts"

Examples:

• "Speak in a cheerful tone"
• "Sound angry"
• "Be extremely sad"
• "Sound urgent and concerned"

Note: Uses OpenAI API, incurs costs (~$0.02/minute)

speed

Type: number (0.25 to 4.0, optional) Speech playback rate.

Examples:

• 0.5 = half speed
• 1.0 = normal speed (default)
• 1.5 = 1.5x speed
• 2.0 = double speed

Supported by: Both OpenAI and Kokoro

Audio & Silence Detection

disable_silence_detection

Type: boolean (default: false) Disable automatic silence detection.

When to use:

• User reports being cut off
• Noisy environments
• Dictation mode where pauses are expected

Usually: Leave enabled (false).

vad_aggressiveness

Type: integer 0-3 (optional) Voice Activity Detection strictness level.

Levels:

• 0 - Least aggressive, includes more audio, may include non-speech
• 1 - Slightly stricter filtering
• 2 - Balanced - good for most environments
• 3 - Most aggressive, strict detection (default) - best for filtering background noise

When to adjust:

• Quiet room: Use 0-1 to catch all speech
• Normal home/office: Use default (3)
• Noisy cafe/outdoors: Use 3

chime_leading_silence

Type: number (seconds, optional) Time to add before audio chime starts.

Use case: Bluetooth devices that need audio buffer (e.g., 1.0 seconds)

Default: Uses VOICEMODE_CHIME_LEADING_SILENCE env var (0.1s)

chime_trailing_silence

Type: number (seconds, optional) Time to add after audio chime ends.

Use case: Prevent chime cutoff (e.g., 0.5 seconds)

Default: Uses VOICEMODE_CHIME_TRAILING_SILENCE env var (0.2s)

Vocabulary Biasing (STT Prompt)

VOICEMODE_STT_PROMPT

Type: environment variable (string, optional)

Bias Whisper's speech recognition toward specific words and names using a prompt hint. This helps improve recognition of technical terms, proper names, and domain-specific vocabulary that Whisper might otherwise mishear.

How it works:

Whisper uses a "prompt" field to condition its recognition. By providing words and phrases you frequently use, the model is primed to hear them correctly. This is especially useful for:

• Names: People, pets, places (Tali, Mike, Brisbane)
• Technical terms: Command names, tools (tmux, kubectl, pytest)
• Project vocabulary: Your codebase-specific terms
• Acronyms: Common abbreviations in your domain

Format flexibility:

All of these formats work equivalently:

# Comma-separated
export VOICEMODE_STT_PROMPT="tmux, Tali, VoiceMode, kubectl"

# Space-separated
export VOICEMODE_STT_PROMPT="tmux Tali VoiceMode kubectl"

# Sentence-style (can help with context)
export VOICEMODE_STT_PROMPT="The user often talks about Tali, tmux sessions, and VoiceMode features."

Examples:

# Developer working with Kubernetes and tmux
export VOICEMODE_STT_PROMPT="kubectl, tmux, pytest, FastAPI, VoiceMode"

# User with a pet named Tali
export VOICEMODE_STT_PROMPT="Tali, my dog Tali, taking Tali for a walk"

# Mix of technical and personal vocabulary
export VOICEMODE_STT_PROMPT="tmux, neovim, Tali, Brisbane, taskmaster"

Token limit:

Whisper uses the last 224 tokens of the prompt. In practice, this means:

• Short word lists: No problem (most use cases)
• Long prompts: Only the end matters, so put important words last
• Typical vocabulary: 50-100 words fits easily within the limit

When to use:

• Whisper consistently mishears specific words
• You use unusual names or technical jargon
• Domain-specific vocabulary isn't recognized

Troubleshooting tip:

If a word is still misrecognized after adding it to the prompt, try including it in context: instead of just "Tali", use "my dog Tali" or "Tali is a Rottweiler".

See also: Troubleshooting - Words Misrecognized

Audio Format & Feedback

audio_format

Type: string (optional) Override audio format.

Options: pcm, mp3, wav, flac, aac, opus

Default: Uses VOICEMODE_TTS_AUDIO_FORMAT env var

chime_enabled

Type: boolean | string (optional) Enable or disable audio feedback chimes.

Default: Uses VOICEMODE_CHIME_ENABLED env var

skip_tts

Type: boolean (optional) Skip text-to-speech, show text only.

Values:

• true - Skip TTS, faster response, text-only
• false - Always use TTS
• null (default) - Follow VOICEMODE_SKIP_TTS env var

Use cases:

• Rapid development iterations
• When voice isn't needed
• Text-only mode

Transport Parameters

transport

Type: "auto" | "local" | "livekit" (default: "auto") Transport method selection.

Options:

• auto - Try LiveKit first, fallback to local
• local - Direct microphone access
• livekit - Room-based communication

room_name

Type: string (optional) LiveKit room name.

Only for: livekit transport Default: Auto-discovered if empty

Endpoint Requirements

STT/TTS services must expose OpenAI-compatible endpoints:

• Whisper/Kokoro must serve on:
  • /v1/audio/transcriptions (STT)
  • /v1/audio/speech (TTS)

Connection errors will clearly report attempted endpoints.