Self-host voice-chat-ai

voice-chat-ai README

How to install voice-chat-ai

MODEL_PROVIDER, TTS_PROVIDER, OPENAI_API_KEY, ELEVENLABS_API_KEY

docker pull bigsk1/voice-chat-ai:latest

docker run -d -e "PULSE_SERVER=/mnt/wslg/PulseServer" -v /mnt/wslg/:/mnt/wslg/ -v ./elevenlabs_voices.json:/app/elevenlabs_voices.json --env-file .env --name voice-chat-ai -p 8000:8000 bigsk1/voice-chat-ai:latest

.env (MODEL_PROVIDER, TTS_PROVIDER, API keys)

services:
  voice-chat-ai:
    image: bigsk1/voice-chat-ai:latest
    container_name: voice-chat-ai
    environment:
      - PULSE_SERVER=/mnt/wslg/PulseServer
    env_file:
      - .env
    volumes:
      - \\wsl$\Ubuntu\mnt\wslg:/mnt/wslg/
    ports:
      - "8000:8000"
    restart: unless-stopped
    tty: true
    stdin_open: true

docker-compose up -d

git clone https://github.com/bigsk1/voice-chat-ai.git
cd voice-chat-ai

python -m venv venv
source venv/bin/activate

pip install torch torchaudio torchvision --index-url https://download.pytorch.org/whl/cpu

pip install -r requirements.txt

How to configure voice-chat-ai

• ALSA_CARDSuppress ALSA warnings in WSL2

  Suppress ALSA warnings in WSL2

• ANTHROPIC_API_KEY
• ANTHROPIC_MODEL=claude-sonnet-4-6Anthropic Configuration: claude-sonnet-4-6, claude-sonnet-4-5, claude-haiku-4-5-20251001

  Anthropic Configuration: claude-sonnet-4-6, claude-sonnet-4-5, claude-haiku-4-5-20251001

• AUDIODEV
• CHARACTER_NAME=bigfootCharacter to use - Options: alien_scientist, anarchist, ant_anarchist, bigfoot, bipolar_ai, capo_mio, chatgpt, clumsyhero, conandoyle, conspiracy, cyberpunk, detective, dog, dream_weaver, drill_sergeant, einstein, elon_musk, femme_fatale, fight_club, fitness_trainer, ghost, granny, grok_xai, hal9000, haunted_teddybear, insult, joker, method_actor, morpheus, mouse, mumbler, nebula_barista, nerd, ne

  Character to use - Options: alien_scientist, anarchist, ant_anarchist, bigfoot, bipolar_ai, capo_mio, chatgpt, clumsyhero, conandoyle, conspiracy, cyberpunk, detective, dog, dream_weaver, drill_sergeant, einstein, elon_musk, femme_fatale, fight_club, fitness_trainer, ghost, granny, grok_xai, hal9000, haunted_teddybear, insult, joker, method_actor, morpheus, mouse, mumbler, nebula_barista, nerd, ne

• DEBUG=falseDebug settings - true or false Set to true to enable extensive debug output

  Debug settings - true or false Set to true to enable extensive debug output

• DEBUG_AUDIO_LEVELS=falseSet to true to see audio level readings during recording

  Set to true to see audio level readings during recording

• ELEVENLABS_API_KEYElevenLabs Configuration: (replace with your actual API key)

  ElevenLabs Configuration: (replace with your actual API key)

• ELEVENLABS_TTS_MODEL=eleven_multilingual_v2ElevenLabs TTS Model eleven_multilingual_v2 , eleven_flash_v2_5 is faster but less quality

  ElevenLabs TTS Model eleven_multilingual_v2 , eleven_flash_v2_5 is faster but less quality

• ELEVENLABS_TTS_VOICEDefault voice ID - find voice id's in your elevenlabs account

  Default voice ID - find voice id's in your elevenlabs account

• FASTER_WHISPER_LOCAL=falseLocal Transcription settings - true or false Set to false to skip loading Faster Whisper on startup and use OpenAI transcription

  Local Transcription settings - true or false Set to false to skip loading Faster Whisper on startup and use OpenAI transcription

• KOKORO_BASE_URLKokoro API base URL - default is localhost, change if running on another machine or in docker

  Kokoro API base URL - default is localhost, change if running on another machine or in docker

• KOKORO_PASSWORD
• KOKORO_TTS_VOICE=af_bellaKokoro TTS Configuration: bm_fable, bm_daniel, bm_lewis, af_alloy, af_bella See the kokoro web url ( if you have it installed ) for more voices http://localhost:8880/web/

  Kokoro TTS Configuration: bm_fable, bm_daniel, bm_lewis, af_alloy, af_bella See the kokoro web url ( if you have it installed ) for more voices http://localhost:8880/web/

• KOKORO_USERNAMEFor remote Kokoro TTS basic auth username and password if needed

  For remote Kokoro TTS basic auth username and password if needed

• KOKORO_VOICES_LEGACYKokoro v0.4+ returns voice objects instead of plain strings; the app handles both automatically. https://github.com/remsky/Kokoro-FastAPI/blob/v0.4.0/CHANGELOG.md Set to true only if you need to force the legacy ?legacy=true voice list from Kokoro-FastAPI.

  Kokoro v0.4+ returns voice objects instead of plain strings; the app handles both automatically. https://github.com/remsky/Kokoro-FastAPI/blob/v0.4.0/CHANGELOG.md Set to true only if you need to force the legacy ?legacy=true voice list from Kokoro-FastAPI.

• LOCAL_REALTIME_SILENCE_MS=1000Wait this long after speech falls quiet before ending the user's turn.

  Wait this long after speech falls quiet before ending the user's turn.

• LOCAL_REALTIME_URLLocal Realtime settings. Used only when OPENAI_REALTIME_PROVIDER=local. see https://github.com/bigsk1/realtime This server accepts raw SDP and does not use the OpenAI API key.

  Local Realtime settings. Used only when OPENAI_REALTIME_PROVIDER=local. see https://github.com/bigsk1/realtime This server accepts raw SDP and does not use the OpenAI API key.

• LOCAL_REALTIME_VAD_THRESHOLD=0.6Lower values detect softer speech; higher values reject more background noise.

  Lower values detect softer speech; higher values reject more background noise.

• LOCAL_REALTIME_VOICE=AidenOptions: Aiden, Ryan, Vivian, Serena, Uncle_Fu, Dylan, Eric, Ono_Anna, Sohee

  Options: Aiden, Ryan, Vivian, Serena, Uncle_Fu, Dylan, Eric, Ono_Anna, Sohee

• MAX_CHAR_LENGTHAUDIO GENERATION LENGTH Maximum character length for audio generation - set to 2000+ for stories and games, 3000 for assassin story, 4000 for mars encounter interactive MAX_CHAR_LENGTH is used for openai, elevenlabs, kokoro and speechify, is also used for max tokens for chat response, if MAX_CHAR_LENGTH is 500, then 500 * 4 // 3 = 666 max tokens is sent to provider

  AUDIO GENERATION LENGTH Maximum character length for audio generation - set to 2000+ for stories and games, 3000 for assassin story, 4000 for mars encounter interactive MAX_CHAR_LENGTH is used for openai, elevenlabs, kokoro and speechify, is also used for max tokens for chat response, if MAX_CHAR_LENGTH is 500, then 500 * 4 // 3 = 666 max tokens is sent to provider

• MODEL_PROVIDER=openaiModel Provider: openai or ollama or xai or anthropic

  Model Provider: openai or ollama or xai or anthropic

• OLLAMA_BASE_URL=http://localhost:11434
• OLLAMA_MODEL=llama3.2Ollama Models Configuration: Models to use - OPTIONAL: For screen analysis, if MODEL_PROVIDER is ollama, llava will be used by default. Model to use - llama3.1 or 3.2 works well for local usage. In the UI it will get the list of models from /api/tags and display them. Not all models are supported. Uncencored model Godmoded/llama3-lexi-uncensored:latest

  Ollama Models Configuration: Models to use - OPTIONAL: For screen analysis, if MODEL_PROVIDER is ollama, llava will be used by default. Model to use - llama3.1 or 3.2 works well for local usage. In the UI it will get the list of models from /api/tags and display them. Not all models are supported. Uncencored model Godmoded/llama3-lexi-uncensored:latest

• OLLAMA_NUM_CTXOptional: increase Ollama context window (num_ctx). Leave unset to use the model default. Requires enough RAM/VRAM for large values (e.g. 128000).

  Optional: increase Ollama context window (num_ctx). Leave unset to use the model default. Requires enough RAM/VRAM for large values (e.g. 128000).

• OPENAI_API_KEYOpenAI API Key for models and speech (replace with your actual API key)

  OpenAI API Key for models and speech (replace with your actual API key)

• OPENAI_BASE_URLEndpoints: Set these below and no need to change often

  Endpoints: Set these below and no need to change often

• OPENAI_MODEL=gpt-5-miniOpenAI Configuration: gpt-4o-mini- gpt-4o, gpt-5-mini-2025-08-07, gpt-5-mini

  OpenAI Configuration: gpt-4o-mini- gpt-4o, gpt-5-mini-2025-08-07, gpt-5-mini

• OPENAI_MODEL_TTS=gpt-4o-mini-ttsOpenAI TTS Model- NEW it uses emotions see https://www.openai.fm/ Model options: gpt-4o-mini-tts, tts-1, tts-1-hd (use tts-1 for local Qwen3 — see docs/QWEN3_TTS.md)

  OpenAI TTS Model- NEW it uses emotions see https://www.openai.fm/ Model options: gpt-4o-mini-tts, tts-1, tts-1-hd (use tts-1 for local Qwen3 — see docs/QWEN3_TTS.md)

• OPENAI_REALTIME_MODEL=gpt-realtime-2.1-miniHosted OpenAI Realtime model. Options: gpt-realtime-2.1, gpt-realtime-2.1-mini (lower cost), gpt-realtime-1.5 Prefer the full model for long character prompts.

  Hosted OpenAI Realtime model. Options: gpt-realtime-2.1, gpt-realtime-2.1-mini (lower cost), gpt-realtime-1.5 Prefer the full model for long character prompts.

• OPENAI_REALTIME_PROVIDER=openaiRealtime WebRTC backend: openai (hosted default) or local (GA-compatible server)

  Realtime WebRTC backend: openai (hosted default) or local (GA-compatible server)

• OPENAI_TRANSCRIPTION_MODEL=gpt-4o-mini-transcribeOpenAI Enhanced Mode Transcription Model Model options: gpt-4o-transcribe, gpt-4o-mini-transcribe, whisper-1

  OpenAI Enhanced Mode Transcription Model Model options: gpt-4o-transcribe, gpt-4o-mini-transcribe, whisper-1

• OPENAI_TTS_URL=https://api.openai.com/v1/audio/speechOpenai compatible TTS URL ( can use custom TTS server like Qwen3 TTS see docs/QWEN3_TTS.md)

  Openai compatible TTS URL ( can use custom TTS server like Qwen3 TTS see docs/QWEN3_TTS.md)

• OPENAI_TTS_VOICE=onyxOpenAI TTS Voice - Used when TTS_PROVIDER is set to openai above Voice options: alloy, echo, fable, onyx, nova, shimmer, ash, coral, sage

  OpenAI TTS Voice - Used when TTS_PROVIDER is set to openai above Voice options: alloy, echo, fable, onyx, nova, shimmer, ash, coral, sage

• SPARKTTS_MAX_CHARS=1000
• SPARKTTS_MODEL_DIR=pretrained_models/Spark-TTS-0.5B
• SPEECHIFY_API_KEYSpeechify TTS Configuration: Get your API key at https://platform.speechify.ai/signup?utm_source=github&utm_medium=integration&utm_campaign=voice-chat-ai (see docs/SPEECHIFY.md)

  Speechify TTS Configuration: Get your API key at https://platform.speechify.ai/signup?utm_source=github&utm_medium=integration&utm_campaign=voice-chat-ai (see docs/SPEECHIFY.md)

• SPEECHIFY_TTS_LANGUAGEOptional: language of the text, e.g. fr-FR. Leave blank to use the voice's own locale.

  Optional: language of the text, e.g. fr-FR. Leave blank to use the voice's own locale.

• SPEECHIFY_TTS_MODEL=simba-3.5Model: simba-3.5 (recommended, 48 languages, works with every voice), simba-3.2 (English only) or simba-3.0 (six languages)

  Model: simba-3.5 (recommended, 48 languages, works with every voice), simba-3.2 (English only) or simba-3.0 (six languages)

• SPEECHIFY_TTS_VOICEDefault voice. The dashboard lists every voice your key can use with the model below.

  Default voice. The dashboard lists every voice your key can use with the model below.

• STT_SILENCE_DURATION=2.0Built-in microphone STT: how long to wait after you stop speaking (seconds of silence) Increase (e.g. 4.0–6.0) if recording cuts off while you pause mid-sentence

  Built-in microphone STT: how long to wait after you stop speaking (seconds of silence) Increase (e.g. 4.0–6.0) if recording cuts off while you pause mid-sentence

• STT_SILENCE_THRESHOLD=300Mean audio level below this counts as silence (lower = more sensitive, stops sooner)

  Mean audio level below this counts as silence (lower = more sensitive, stops sooner)

• TTS_PROVIDERText-to-Speech (TTS) Configuration: TTS Provider - Options: sparktts (local uses the custom character .wav) or openai (uses OpenAI TTS voice) or xai or elevenlabs or kokoro (your own selfhosted tts) or typecast or speechify

  Text-to-Speech (TTS) Configuration: TTS Provider - Options: sparktts (local uses the custom character .wav) or openai (uses OpenAI TTS voice) or xai or elevenlabs or kokoro (your own selfhosted tts) or typecast or speechify

• TYPECAST_API_KEYTypecast TTS Configuration: Get your API key at https://typecast.ai

  Typecast TTS Configuration: Get your API key at https://typecast.ai

• TYPECAST_EMOTION_PRESET=normalEmotion preset: normal, happy, sad, angry, whisper, toneup, tonedown

  Emotion preset: normal, happy, sad, angry, whisper, toneup, tonedown

• TYPECAST_TTS_MODEL=ssfm-v30Model: ssfm-v30 (default, supports smart emotion) or ssfm-v21

  Model: ssfm-v30 (default, supports smart emotion) or ssfm-v21

• TYPECAST_TTS_VOICEVoice ID from your Typecast account

  Voice ID from your Typecast account

• UI_SERVER_LOGS=trueDashboard-only terminal log panel (streams server output to the UI via /ws/logs)

  Dashboard-only terminal log panel (streams server output to the UI via /ws/logs)

• VOICE_SPEED=1.0Voice Speed for all TTS providers - 0.7 to 1.2, default is 1.0

  Voice Speed for all TTS providers - 0.7 to 1.2, default is 1.0

• XAI_API_KEY
• XAI_BASE_URL=https://api.x.ai/v1
• XAI_CHAT_TIMEOUTOptional request timeout override in seconds. Defaults: 45 normally, 120 for Grok 4.5.

  Optional request timeout override in seconds. Defaults: 45 normally, 120 for Grok 4.5.

• XAI_MODEL=grok-4.3XAI Configuration: Chat options: grok-4.3 (fast/no reasoning), grok-4.5 (low reasoning)

  XAI Configuration: Chat options: grok-4.3 (fast/no reasoning), grok-4.5 (low reasoning)

• XAI_TTS_BIT_RATE
• XAI_TTS_FORMAT=mp3Playable dashboard/CLI formats: mp3 or wav

  Playable dashboard/CLI formats: mp3 or wav

• XAI_TTS_LANGUAGE=enDefault language is English. Use auto for language detection.

  Default language is English. Use auto for language detection.

• XAI_TTS_SAMPLE_RATEOptional output tuning. Leave blank to use xAI defaults.

  Optional output tuning. Leave blank to use xAI defaults.

• XAI_TTS_TIMEOUT=180Increase for long story/game responses that need more time to synthesize.

  Increase for long story/game responses that need more time to synthesize.

• XAI_TTS_URL=https://api.x.ai/v1/tts
• XAI_TTS_VOICE=evexAI Grok TTS Configuration: https://x.ai/api/voice for examples to listen to The dashboard exposes the current built-in voice catalog; the default is eve.

  xAI Grok TTS Configuration: https://x.ai/api/voice for examples to listen to The dashboard exposes the current built-in voice catalog; the default is eve.

• XAI_VISION_MODEL=grok-4.3Image understanding defaults to the fast multimodal model.

  Image understanding defaults to the fast multimodal model.