Voice Mode Configuration Reference

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

tools-only Updated Sep 29, 2026 7 repo stars

Coding & Dev Tools

Install

Press C to copy

$ npx skillmds@latest add tools-only/voice-mode-configuration-reference

Installs into ~/.claude/skills (or .claude/skills inside a project). Restart Claude Code to pick it up.

＋ Add to plugin

README badge

[![SkillMD](https://skillmd.com/badge/tools-only/voice-mode-configuration-reference.svg)](https://skillmd.com/skills/tools-only/voice-mode-configuration-reference)

Trust & safety

1 of 3 audits passed

Last audited Sep 23, 2026 · commit 91c5a1b

Works with: Claude Code Claude.ai OpenAI Codex +

File contents

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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)

# 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

# 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

# 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

# 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

# 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

# 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

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

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)

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

VOICEMODE_PREFER_LOCAL=true
VOICEMODE_AUTO_START_KOKORO=true

High-quality audio settings

VOICEMODE_TTS_AUDIO_FORMAT=opus
VOICEMODE_OPUS_BITRATE=64000
VOICEMODE_TTS_MODELS=tts-1-hd

Debug configuration

VOICEMODE_DEBUG=true
VOICEMODE_SAVE_AUDIO=true
VOICEMODE_EVENT_LOG_ENABLED=true

---name: voice-mode-configuration-referencedescription: This is a comprehensive reference of all configuration options available in Voice Mode.---# Voice Mode Configuration ReferenceThis 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 endpointsOPENAI_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 preferenceVOICEMODE_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_isabellaVOICEMODE_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 compatibilityVOICEMODE_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/v1VOICEMODE_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-v2VOICEMODE_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: 2022VOICEMODE_WHISPER_PORT=2022```## LiveKit Configuration```bash# LiveKit Server WebSocket URL# Default: ws://127.0.0.1:7880# For LiveKit Cloud: wss://your-project.livekit.cloudLIVEKIT_URL=ws://127.0.0.1:7880# LiveKit API Credentials# Default: devkey/secret (for local development)LIVEKIT_API_KEY=devkeyLIVEKIT_API_SECRET=secret```## Audio Configuration```bash# Default Audio Format# Default: pcm# Supported: pcm, opus, mp3, wav, flac, aacVOICEMODE_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 SettingsVOICEMODE_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: trueVOICEMODE_AUDIO_FEEDBACK=true# Audio Feedback Style (Note: Currently not implemented)# Default: whisper# Options: whisper, shoutVOICE_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: trueVOICEMODE_STREAMING_ENABLED=true# Streaming Buffer SettingsVOICEMODE_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 cloudVOICEMODE_PREFER_LOCAL=true# Always Try Local Services# Default: true# Always attempt local providers even if marked unhealthyVOICEMODE_ALWAYS_TRY_LOCAL=true# Auto-start Kokoro TTS# Default: false# Automatically starts Kokoro TTS service on first use if not runningVOICEMODE_AUTO_START_KOKORO=false# Simple Failover Mode# Default: true# Try each endpoint in order without health checksVOICEMODE_SIMPLE_FAILOVER=true```## Silence Detection / Voice Activity Detection (VAD)```bash# Enable Silence Detection# Default: true# Automatically stops recording when silence is detectedVOICEMODE_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 environmentsVOICEMODE_VAD_AGGRESSIVENESS=2# Silence Threshold (milliseconds)# Default: 1000 (1 second)# How long to wait after speech stops before ending recordingVOICEMODE_SILENCE_THRESHOLD_MS=1000# Minimum Recording Duration (seconds)# Default: 0.5# Prevents premature cutoff for very short responsesVOICEMODE_MIN_RECORDING_DURATION=0.5# Initial Silence Grace Period (seconds)# Default: 4.0# How long to wait for user to start speaking before timing outVOICEMODE_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 personasVOICEMODE_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 thinkingVOICEMODE_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 rapidlyVOICEMODE_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 filesVOICEMODE_SAVE_TRANSCRIPTIONS=false# Save All (master switch)# Default: false# Enables both audio and transcription savingVOICEMODE_SAVE_ALL=false```## Event Logging```bash# Enable Event Logging# Default: true# Logs voice interaction events in JSONL format for analysisVOICEMODE_EVENT_LOG_ENABLED=true# Event Log Directory# Default: ~/voicemode_logsVOICEMODE_EVENT_LOG_DIR=/path/to/logs# Event Log Rotation# Default: daily# Currently only 'daily' is supportedVOICEMODE_EVENT_LOG_ROTATION=daily```## Service Configuration```bash# Kokoro Port# Default: 8880VOICEMODE_KOKORO_PORT=8880# Kokoro Models Directory# Default: ~/.voicemode/models/kokoroVOICEMODE_KOKORO_MODELS_DIR=~/.voicemode/models/kokoro# Kokoro Cache Directory# Default: ~/.voicemode/cache/kokoroVOICEMODE_KOKORO_CACHE_DIR=~/.voicemode/cache/kokoro# Default Kokoro Voice# Default: af_skyVOICEMODE_KOKORO_DEFAULT_VOICE=af_sky# Service Auto-enable# Default: true# Automatically enable services after installationVOICEMODE_SERVICE_AUTO_ENABLE=true```## Directory Structure```bash# Base directory for all voicemode data# Default: ~/.voicemodeVOICEMODE_BASE_DIR=~/.voicemode# Models directory# Default: ~/.voicemode/modelsVOICEMODE_MODELS_DIR=~/.voicemode/models# Whisper models path# Default: ~/.voicemode/models/whisperVOICEMODE_WHISPER_MODEL_PATH=~/.voicemode/models/whisper```## Example Configurations### Use Kokoro TTS with OpenAI STT```bashVOICEMODE_TTS_BASE_URLS=http://127.0.0.1:8880/v1,https://api.openai.com/v1VOICEMODE_VOICES=af_sky,af_novaVOICEMODE_STT_BASE_URLS=https://api.openai.com/v1OPENAI_API_KEY=your-key-here```### Use local Whisper STT with OpenAI TTS```bashVOICEMODE_STT_BASE_URLS=http://127.0.0.1:2022/v1,https://api.openai.com/v1VOICEMODE_TTS_BASE_URLS=https://api.openai.com/v1VOICEMODE_VOICES=nova,alloyOPENAI_API_KEY=your-key-here```### Use both local services (Kokoro + Whisper)```bashVOICEMODE_TTS_BASE_URLS=http://127.0.0.1:8880/v1VOICEMODE_VOICES=af_sky,af_novaVOICEMODE_STT_BASE_URLS=http://127.0.0.1:2022/v1```### Enable auto-start and local preference```bashVOICEMODE_PREFER_LOCAL=trueVOICEMODE_AUTO_START_KOKORO=true```### High-quality audio settings```bashVOICEMODE_TTS_AUDIO_FORMAT=opusVOICEMODE_OPUS_BITRATE=64000VOICEMODE_TTS_MODELS=tts-1-hd```### Debug configuration```bashVOICEMODE_DEBUG=trueVOICEMODE_SAVE_AUDIO=trueVOICEMODE_EVENT_LOG_ENABLED=true```

tools-only/X-Skills/tree/main/development/1456-configuration-reference_c9254e97 commit 91c5a1bbcf

Frequently asked questions

npx skillmds@latest add tools-only/voice-mode-configuration-reference