# 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](../guides/soundfonts.md) 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` |

### Control Channel

See the [Control Channel reference](control-channel.md) for the command surface
(`voicemode control pause|resume|stop|skip-back`) and worked Stream Deck /
media-key / keyword examples.

| Variable | Description | Default | Example |
|----------|-------------|---------|---------|
| `VOICEMODE_CONTROL_CHANNEL_ENABLED` | Bind the control socket while speaking (pause/resume/stop/skip-back an utterance) | `false` | `true` |
| `VOICEMODE_CONTROL_SOCKET` | Path to the control Unix domain socket | `~/.voicemode/control.sock` | `/tmp/vm-control.sock` |
| `VOICEMODE_HISTORY_BUFFER_SIZE` | How many recent utterances `skip_back` can replay (history ring-buffer depth, ≥1) | `8` | `16` |

### 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`:
```bash
export OPENAI_API_KEY="sk-..."
export VOICEMODE_VOICES="nova,shimmer"
export VOICEMODE_DEBUG=false
```

### Project Configuration
Create `.voicemode.env` in project root:
```bash
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:

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

## Debugging Environment

To see all active environment variables:
```bash
voicemode config show --env
```

To test with specific variables:
```bash
VOICEMODE_DEBUG=true VOICEMODE_LOG_LEVEL=debug voicemode converse
```
