Voice Mode

# Kokoro Text-to-Speech Service High-quality local text-to-speech service for voice-mode with multiple natural-sounding voices in various languages. ## Quick Start ```bash # macOS launchctl load ~/Library/LaunchAgents/com.voicemode.kokoro.plist # Linux systemctl --user start kokoro ``` Default endpoint: `http://127.0.0.1:8880/v1` ## Install ### Prerequisites ```bash # Ensure Python 3.8+ is installed python3 --version # Install uvx (if not already installed) pip install uvx ``` ### Download Models ```bash # Create models directory mkdir -p ~/Models/kokoro # Download models (automatic on first run) # Or manually from: https://huggingface.co/hexgrad/Kokoro-82M ``` ## Configure Environment variables in `~/.voicemode/voicemode.env`: ```bash VOICEMODE_KOKORO_PORT=8880 VOICEMODE_KOKORO_MODELS_DIR=~/Models/kokoro VOICEMODE_KOKORO_CACHE_DIR=~/.voicemode/cache/kokoro VOICEMODE_KOKORO_DEFAULT_VOICE=af_sky ``` ### LaunchAgent (macOS) Create `~/Library/LaunchAgents/com.voicemode.kokoro.plist`: ```xml <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>com.voicemode.kokoro</string> <key>ProgramArguments</key> <array> <string>/usr/local/bin/uvx</string> <string>kokoro-fastapi[cpu]</string> <string>serve</string> <string>--host</string> <string>127.0.0.1</string> <string>--port</string> <string>8880</string> <string>--models-dir</string> <string>/Users/YOUR_USERNAME/Models/kokoro</string> </array> <key>RunAtLoad</key> <true/> <key>KeepAlive</key> <true/> <key>EnvironmentVariables</key> <dict> <key>PATH</key> <string>/usr/local/bin:/usr/bin:/bin</string> </dict> </dict> </plist> ``` ### Systemd Service (Linux) Create `~/.config/systemd/user/kokoro.service`: ```ini [Unit] Description=Kokoro Text-to-Speech Service After=network.target [Service] Type=simple ExecStart=/usr/local/bin/uvx kokoro-fastapi[cpu] serve \ --host 127.0.0.1 \ --port 8880 \ --models-dir %h/Models/kokoro Restart=always RestartSec=10 Environment="PATH=/usr/local/bin:/usr/bin:/bin" [Install] WantedBy=default.target ``` ## Control ### macOS Commands ```bash # Start service launchctl load ~/Library/LaunchAgents/com.voicemode.kokoro.plist # Stop service launchctl unload ~/Library/LaunchAgents/com.voicemode.kokoro.plist # Restart service launchctl unload ~/Library/LaunchAgents/com.voicemode.kokoro.plist launchctl load ~/Library/LaunchAgents/com.voicemode.kokoro.plist # Enable at startup launchctl load -w ~/Library/LaunchAgents/com.voicemode.kokoro.plist # Disable at startup launchctl unload -w ~/Library/LaunchAgents/com.voicemode.kokoro.plist # Check status launchctl list | grep kokoro ``` ### Linux Commands ```bash # Start service systemctl --user start kokoro # Stop service systemctl --user stop kokoro # Restart service systemctl --user restart kokoro # Enable at startup systemctl --user enable kokoro # Disable at startup systemctl --user disable kokoro # Check status systemctl --user status kokoro # View logs journalctl --user -u kokoro -f ``` ## Available Voices ### English - `af_sky`, `af_sarah` - American Female - `am_adam`, `am_michael` - American Male - `bf_emma`, `bf_isabella` - British Female - `bm_george`, `bm_lewis` - British Male ### Other Languages - Spanish: `ef_dora`, `em_alex` - French: `ff_siwis`, `fm_gabriel` - Italian: `if_sara`, `im_nicola` - Portuguese: `pf_dora`, `pm_alex` - Chinese: `zf_xiaobei`, `zm_yunjian` - Japanese: `jf_alpha`, `jm_kumo` - Hindi: `hf_alpha`, `hm_omega` ## Troubleshooting ### Service won't start - Check if port 8880 is already in use: `lsof -i :8880` - Verify uvx is installed: `which uvx` - Check Python version: `python3 --version` (requires 3.8+) ### Models not found - Ensure models directory exists and has correct permissions - Models download automatically on first request - Manual download from: https://huggingface.co/hexgrad/Kokoro-82M ### Performance issues - Use CPU version for most systems: `kokoro-fastapi[cpu]` - GPU version available for CUDA-enabled systems - Adjust cache directory location for faster SSD access