Skip to content

environment.md

Latest commit

 

History

History
224 lines (171 loc) · 8.67 KB

environment.md

File metadata and controls

224 lines (171 loc) · 8.67 KB

Environment Variables Reference

Complete reference of all environment variables used by VoiceMode.

Variable Precedence

Environment variables are processed in this order (highest to lowest priority):

  1. Command-line environment (OPENAI_API_KEY=xxx voicemode)
  2. MCP host configuration
  3. Shell environment variables
  4. Project .voicemode.env file
  5. User ~/.voicemode/voicemode.env file
  6. Built-in defaults

Core Configuration

API Keys

Variable Description Default Example
OPENAI_API_KEY OpenAI API key for cloud TTS/STT None sk-proj-...

Voice Services

Text-to-Speech (TTS)

Variable Description Default Example
VOICEMODE_TTS_BASE_URLS Comma-separated TTS service URLs http://127.0.0.1:8880/v1,https://api.openai.com/v1 http://localhost:8880/v1
VOICEMODE_VOICES Comma-separated voice preferences af_sky,alloy nova,shimmer
VOICEMODE_TTS_VOICE Default TTS voice First from VOICES nova
VOICEMODE_TTS_MODELS Comma-separated TTS models tts-1-hd,tts-1 gpt-4o-mini-tts,tts-1
VOICEMODE_TTS_MODEL Default TTS model First from MODELS tts-1-hd
VOICEMODE_TTS_SPEED Speech speed (0.25-4.0) 1.0 1.5

Speech-to-Text (STT)

Variable Description Default Example
VOICEMODE_STT_BASE_URLS Comma-separated STT service URLs https://api.openai.com/v1 http://localhost:2022/v1
VOICEMODE_STT_MODEL STT model whisper-1 whisper-1
VOICEMODE_STT_PROMPT Vocabulary biasing for Whisper (names, terms) None tmux, Tali, kubectl

Whisper Configuration

Variable Description Default Example
VOICEMODE_WHISPER_MODEL Whisper model size large-v2 base.en
VOICEMODE_WHISPER_LANGUAGE Language code or 'auto' auto en
VOICEMODE_WHISPER_PORT Whisper server port 2022 2023
VOICEMODE_WHISPER_MODEL_PATH Path to Whisper models ~/.voicemode/models/whisper /models/whisper

Kokoro Configuration

Variable Description Default Example
VOICEMODE_KOKORO_PORT Kokoro server port 8880 8881
VOICEMODE_KOKORO_MODELS_DIR Kokoro models directory ~/Models/kokoro /models/kokoro
VOICEMODE_KOKORO_CACHE_DIR Kokoro cache directory ~/.voicemode/cache/kokoro /cache/kokoro
VOICEMODE_KOKORO_DEFAULT_VOICE Default Kokoro voice af_sky am_adam

Soundfonts

Variable Description Default Example
VOICEMODE_SOUNDFONTS_ENABLED Enable/disable soundfont playback true false
VOICEMODE_HOOK_DEBUG Enable debug output from hook receiver unset 1

VOICEMODE_SOUNDFONTS_ENABLED can be set in ~/.voicemode/voicemode.env or the shell environment. The sentinel file (~/.voicemode/soundfonts-disabled, managed by voicemode soundfonts on/off) takes priority when present.

See the Soundfonts Guide for details.

Audio Configuration

Audio Formats

Variable Description Default Example
VOICEMODE_AUDIO_FORMAT Global audio format pcm mp3
VOICEMODE_TTS_AUDIO_FORMAT TTS-specific format pcm opus
VOICEMODE_STT_AUDIO_FORMAT STT-specific format mp3 wav

Supported formats: pcm, opus, mp3, wav, flac, aac

Audio Quality

Variable Description Default Example
VOICEMODE_SAMPLE_RATE Sample rate in Hz 24000 48000
VOICEMODE_OPUS_BITRATE Opus bitrate in bps 32000 64000
VOICEMODE_MP3_BITRATE MP3 bitrate 64k 128k
VOICEMODE_AAC_BITRATE AAC bitrate 64k 96k

Audio Feedback

Variable Description Default Example
VOICEMODE_AUDIO_FEEDBACK Enable recording chimes true false
VOICEMODE_FEEDBACK_STYLE Chime style whisper shout
VOICEMODE_CHIME_PRE_DELAY Silence before chime (seconds) 0.1 1.0
VOICEMODE_CHIME_POST_DELAY Silence after chime (seconds) 0.2 0.5

Voice Activity Detection

Variable Description Default Example
VOICEMODE_VAD_AGGRESSIVENESS VAD level (0-3) 3 3
VOICEMODE_DISABLE_VAD Disable VAD false true
VOICEMODE_DISABLE_SILENCE_DETECTION Disable silence detection false true
VOICEMODE_SILENCE_THRESHOLD Silence duration (seconds) 3.0 5.0
VOICEMODE_MIN_RECORDING_TIME Minimum recording (seconds) 0.5 1.0
VOICEMODE_MAX_RECORDING_TIME Maximum recording (seconds) 120.0 60.0

File Storage

Variable Description Default Example
VOICEMODE_DATA_DIR Data directory ~/.voicemode /data/voicemode
VOICEMODE_LOG_DIR Log directory ~/.voicemode/logs /var/log/voicemode
VOICEMODE_CACHE_DIR Cache directory ~/.voicemode/cache /tmp/voicemode
VOICEMODE_SAVE_ALL Save all audio files false true
VOICEMODE_SAVE_RECORDINGS Save input recordings false true
VOICEMODE_SAVE_TTS Save TTS output false true

Logging and Debugging

Variable Description Default Example
VOICEMODE_DEBUG Enable debug mode false true
VOICEMODE_LOG_LEVEL Log level info debug
VOICEMODE_EVENT_LOG Enable event logging false true
VOICEMODE_CONVERSATION_LOG Log conversations false true
VOICEMODE_SKIP_TTS Skip TTS for testing false true

Log levels: debug, info, warning, error, critical

Advanced Features

Emotional TTS

Variable Description Default Example
VOICEMODE_ALLOW_EMOTIONS Enable emotional TTS false true
VOICEMODE_EMOTION_AUTO_UPGRADE Auto-upgrade to emotional model false true

Service Preferences

Variable Description Default Example
VOICEMODE_PREFER_LOCAL Prefer local services true false
VOICEMODE_AUTO_START_SERVICES Auto-start local services false true

Serve Command

Variable Description Default Example
VOICEMODE_SERVE_TRANSPORT MCP transport protocol (streamable-http or sse) sse streamable-http
VOICEMODE_SERVE_ALLOW_LOCAL Allow localhost connections true false
VOICEMODE_SERVE_ALLOW_ANTHROPIC Allow Anthropic IP ranges false true
VOICEMODE_SERVE_ALLOW_TAILSCALE Allow Tailscale IP range (100.64.0.0/10) false true
VOICEMODE_SERVE_ALLOWED_IPS Custom CIDR allowlist (comma-separated) None 192.168.1.0/24,10.0.0.0/8
VOICEMODE_SERVE_SECRET URL path secret segment None my-secret-uuid
VOICEMODE_SERVE_TOKEN Bearer token for authentication None my-secret-token

Legacy Variables

These variables from older versions are still supported:

Old Variable New Variable Notes
VOICE_MODE_DEBUG VOICEMODE_DEBUG Deprecated
VOICE_MODE_SAVE_AUDIO VOICEMODE_SAVE_ALL Deprecated
TTS_BASE_URL VOICEMODE_TTS_BASE_URLS Still supported
STT_BASE_URL VOICEMODE_STT_BASE_URLS Still supported
TTS_VOICE VOICEMODE_TTS_VOICE Still supported
TTS_MODEL VOICEMODE_TTS_MODEL Still supported

Configuration Files

User Configuration

Create ~/.voicemode/voicemode.env:

export OPENAI_API_KEY="sk-..."
export VOICEMODE_VOICES="nova,shimmer"
export VOICEMODE_DEBUG=false

Project Configuration

Create .voicemode.env in project root:

export VOICEMODE_VOICES="onyx"
export VOICEMODE_TTS_SPEED=0.9

MCP Host Configuration

When used as an MCP server, environment variables can be set in the host configuration:

{
  "mcpServers": {
    "voicemode": {
      "command": "uvx",
      "args": ["voice-mode"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "VOICEMODE_DEBUG": "true"
      }
    }
  }
}

Debugging Environment

To see all active environment variables:

voicemode config show --env

To test with specific variables:

VOICEMODE_DEBUG=true VOICEMODE_LOG_LEVEL=debug voicemode converse