1456 Configuration Reference C9254e97

# Voice Mode Configuration Reference

This is a comprehensive reference of all configuration options available in Voice Mode.

**Note:** Voice Mode automatically creates `~/.voicemode/voicemode.env` on first run with basic settings. You can edit this file to customize your configuration. Environment variables always take precedence over file settings.

## API Keys and Authentication

```bash
# OpenAI API Key (Required for cloud services)
# Used for both TTS and STT services when using OpenAI-compatible endpoints
OPENAI_API_KEY=your-key-here
```

## Text-to-Speech (TTS) Configuration

```bash
# TTS Service Base URLs (comma-separated list)
# Default: http://127.0.0.1:8880/v1,https://api.openai.com/v1
# The system will try URLs in order of preference
VOICEMODE_TTS_BASE_URLS=http://127.0.0.1:8880/v1,https://api.openai.com/v1

# Voice Preferences (comma-separated list)
# Default: af_sky,alloy
# OpenAI voices: alloy, echo, fable, onyx, nova, shimmer
# Kokoro voices: af_sky, af_sarah, af_nicole, af_lilly, af_zara, am_adam, am_michael, bf_emma, bf_isabella
VOICEMODE_VOICES=af_sky,alloy

# TTS Models (comma-separated list)
# Default: gpt-4o-mini-tts,tts-1-hd,tts-1
# OpenAI models: tts-1, tts-1-hd, gpt-4o-mini-tts (emotional)
# Kokoro: uses tts-1 compatibility
VOICEMODE_TTS_MODELS=gpt-4o-mini-tts,tts-1-hd,tts-1
```

## Speech-to-Text (STT) Configuration

```bash
# STT Service Base URLs (comma-separated list)
# Default: https://api.openai.com/v1
# For local Whisper: http://127.0.0.1:2022/v1
VOICEMODE_STT_BASE_URLS=https://api.openai.com/v1

# Whisper Model (for local Whisper)
# Options: tiny, base, small, medium, large, large-v2, large-v3
# Default: large-v2
VOICEMODE_WHISPER_MODEL=large-v2

# Whisper Language
# Default: auto (automatic detection)
# Options: en, es, fr, de, it, pt, ru, zh, ja, ko, etc.
VOICEMODE_WHISPER_LANGUAGE=auto

# Whisper Port
# Default: 2022
VOICEMODE_WHISPER_PORT=2022
```

## LiveKit Configuration

```bash
# LiveKit Server WebSocket URL
# Default: ws://127.0.0.1:7880
# For LiveKit Cloud: wss://your-project.livekit.cloud
LIVEKIT_URL=ws://127.0.0.1:7880

# LiveKit API Credentials
# Default: devkey/secret (for local development)
LIVEKIT_API_KEY=devkey
LIVEKIT_API_SECRET=secret
```

## Audio Configuration

```bash
# Default Audio Format
# Default: pcm
# Supported: pcm, opus, mp3, wav, flac, aac
VOICEMODE_AUDIO_FORMAT=pcm

# TTS Audio Format (overrides default for TTS)
# Default: pcm (optimal for streaming)
VOICEMODE_TTS_AUDIO_FORMAT=pcm

# STT Audio Format (overrides default for STT)
# Default: mp3 (if global is pcm, since OpenAI doesn't support pcm)
VOICEMODE_STT_AUDIO_FORMAT=mp3

# Audio Quality Settings
VOICEMODE_OPUS_BITRATE=32000     # Opus bitrate in bps (default: 32000)
VOICEMODE_MP3_BITRATE=64k        # MP3 bitrate (default: 64k)
VOICEMODE_AAC_BITRATE=64k        # AAC bitrate (default: 64k)
```

## Audio Feedback

```bash
# Enable Audio Feedback (chimes when recording starts/stops)
# Default: true
VOICEMODE_AUDIO_FEEDBACK=true

# Audio Feedback Style (Note: Currently not implemented)
# Default: whisper
# Options: whisper, shout
VOICE_MCP_FEEDBACK_STYLE=whisper

# Skip Text-to-Speech
# Default: false
# When enabled: Skip TTS for faster text-only responses
# Can be overridden per-call with skip_tts parameter in converse()
VOICEMODE_SKIP_TTS=false
```

## Streaming Configuration

```bash
# Enable Streaming Playback
# Default: true
VOICEMODE_STREAMING_ENABLED=true

# Streaming Buffer Settings
VOICEMODE_STREAM_CHUNK_SIZE=4096    # Download chunk size in bytes (default: 4096)
VOICEMODE_STREAM_BUFFER_MS=150      # Initial buffer before playback in ms (default: 150)
VOICEMODE_STREAM_MAX_BUFFER=2.0     # Maximum buffer in seconds (default: 2.0)
```

## Provider Preferences

```bash
# Prefer Local Services
# Default: true
# When enabled, prioritizes local services (Kokoro, Whisper) over cloud
VOICEMODE_PREFER_LOCAL=true

# Always Try Local Services
# Default: true
# Always attempt local providers even if marked unhealthy
VOICEMODE_ALWAYS_TRY_LOCAL=true

# Auto-start Kokoro TTS
# Default: false
# Automatically starts Kokoro TTS service on first use if not running
VOICEMODE_AUTO_START_KOKORO=false

# Simple Failover Mode
# Default: true
# Try each endpoint in order without health checks
VOICEMODE_SIMPLE_FAILOVER=true
```

## Silence Detection / Voice Activity Detection (VAD)

```bash
# Enable Silence Detection
# Default: true
# Automatically stops recording when silence is detected
VOICEMODE_ENABLE_SILENCE_DETECTION=true

# VAD Aggressiveness (0-3)
# Default: 2
# Controls how strictly WebRTC VAD filters out non-speech audio
# 0: Least aggressive filtering - more permissive, may include non-speech sounds
# 1: Slightly stricter filtering
# 2: Balanced filtering - good for most environments (default)
# 3: Most aggressive filtering - very strict, may cut off soft speech
# Use lower values (0-1) in quiet environments, higher values (2-3) in noisy environments
VOICEMODE_VAD_AGGRESSIVENESS=2

# Silence Threshold (milliseconds)
# Default: 1000 (1 second)
# How long to wait after speech stops before ending recording
VOICEMODE_SILENCE_THRESHOLD_MS=1000

# Minimum Recording Duration (seconds)
# Default: 0.5
# Prevents premature cutoff for very short responses
VOICEMODE_MIN_RECORDING_DURATION=0.5

# Initial Silence Grace Period (seconds)
# Default: 4.0
# How long to wait for user to start speaking before timing out
VOICEMODE_INITIAL_SILENCE_GRACE_PERIOD=4.0
```

## Think Out Loud Mode

```bash
# Enable Think Out Loud Mode
# Default: false
# When enabled, AI voices its internal reasoning process using multiple voice personas
VOICEMODE_THINK_OUT_LOUD=false

# Voice Persona Mappings (role:voice pairs)
# Default: analytical:am_adam,creative:af_sarah,critical:af_bella,synthesis:af_nova
# Maps thinking roles to specific voices for multi-voice reasoning
# Available roles: analytical, creative, critical, synthesis
# Kokoro voices: am_adam, af_sarah, af_bella, af_nova, af_nicole, am_michael
# Note: af_sky reserved for main conversation voice, not inner thinking
VOICEMODE_THINKING_VOICES=analytical:am_adam,creative:af_sarah,critical:af_bella,synthesis:af_nova

# Think Out Loud Style
# Default: sequential
# How thinking voices are presented
# Options:
#   sequential - Each voice speaks in turn, building on previous thoughts
#   debate - Voices engage in back-and-forth discussion
#   chorus - Multiple perspectives presented rapidly
VOICEMODE_THINKING_STYLE=sequential

# Think Out Loud Introduction
# Default: true
# Whether to announce which voice is speaking (e.g., "Analytical perspective:")
VOICEMODE_THINKING_ANNOUNCE_VOICE=true
```

## Development & Debugging

```bash
# Enable Debug Mode
# Default: false
# When enabled: detailed logging and debug information
# Values: false, true, trace (trace provides detailed function call logging)
VOICEMODE_DEBUG=false

# Save Audio Files
# Default: false
# When enabled: saves audio files to ~/voicemode_audio/
VOICEMODE_SAVE_AUDIO=false

# Save Transcriptions
# Default: false
# When enabled: saves transcriptions alongside audio files
VOICEMODE_SAVE_TRANSCRIPTIONS=false

# Save All (master switch)
# Default: false
# Enables both audio and transcription saving
VOICEMODE_SAVE_ALL=false
```

## Event Logging

```bash
# Enable Event Logging
# Default: true
# Logs voice interaction events in JSONL format for analysis
VOICEMODE_EVENT_LOG_ENABLED=true

# Event Log Directory
# Default: ~/voicemode_logs
VOICEMODE_EVENT_LOG_DIR=/path/to/logs

# Event Log Rotation
# Default: daily
# Currently only 'daily' is supported
VOICEMODE_EVENT_LOG_ROTATION=daily
```

## Service Configuration

```bash
# Kokoro Port
# Default: 8880
VOICEMODE_KOKORO_PORT=8880

# Kokoro Models Directory
# Default: ~/.voicemode/models/kokoro
VOICEMODE_KOKORO_MODELS_DIR=~/.voicemode/models/kokoro

# Kokoro Cache Directory
# Default: ~/.voicemode/cache/kokoro
VOICEMODE_KOKORO_CACHE_DIR=~/.voicemode/cache/kokoro

# Default Kokoro Voice
# Default: af_sky
VOICEMODE_KOKORO_DEFAULT_VOICE=af_sky

# Service Auto-enable
# Default: true
# Automatically enable services after installation
VOICEMODE_SERVICE_AUTO_ENABLE=true
```

## Directory Structure

```bash
# Base directory for all voicemode data
# Default: ~/.voicemode
VOICEMODE_BASE_DIR=~/.voicemode

# Models directory
# Default: ~/.voicemode/models
VOICEMODE_MODELS_DIR=~/.voicemode/models

# Whisper models path
# Default: ~/.voicemode/models/whisper
VOICEMODE_WHISPER_MODEL_PATH=~/.voicemode/models/whisper
```

## Example Configurations

### Use Kokoro TTS with OpenAI STT
```bash
VOICEMODE_TTS_BASE_URLS=http://127.0.0.1:8880/v1,https://api.openai.com/v1
VOICEMODE_VOICES=af_sky,af_nova
VOICEMODE_STT_BASE_URLS=https://api.openai.com/v1
OPENAI_API_KEY=your-key-here
```

### Use local Whisper STT with OpenAI TTS
```bash
VOICEMODE_STT_BASE_URLS=http://127.0.0.1:2022/v1,https://api.openai.com/v1
VOICEMODE_TTS_BASE_URLS=https://api.openai.com/v1
VOICEMODE_VOICES=nova,alloy
OPENAI_API_KEY=your-key-here
```

### Use both local services (Kokoro + Whisper)
```bash
VOICEMODE_TTS_BASE_URLS=http://127.0.0.1:8880/v1
VOICEMODE_VOICES=af_sky,af_nova
VOICEMODE_STT_BASE_URLS=http://127.0.0.1:2022/v1
```

### Enable auto-start and local preference
```bash
VOICEMODE_PREFER_LOCAL=true
VOICEMODE_AUTO_START_KOKORO=true
```

### High-quality audio settings
```bash
VOICEMODE_TTS_AUDIO_FORMAT=opus
VOICEMODE_OPUS_BITRATE=64000
VOICEMODE_TTS_MODELS=tts-1-hd
```

### Debug configuration
```bash
VOICEMODE_DEBUG=true
VOICEMODE_SAVE_AUDIO=true
VOICEMODE_EVENT_LOG_ENABLED=true
```