2605 Parameters 2c1ded6c

# 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:
```bash
# 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:**
```bash
# 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](troubleshooting.md#specific-words-consistently-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.