Add Smart UI Auto-Detection, Dynamic Voice System, and .env Support

[kiralpoon]

This PR adds three quality-of-life improvements that simplify PersonaPlex setup and development workflow while maintaining full backward compatibility.

Features

1. Smart UI Auto-Detection

Problem: Developers had to manually specify --static client/dist flag to use custom UI builds.

Solution: Server automatically detects and serves custom UI from client/dist when available, falling back to default HuggingFace UI when not present.

Benefits:

• Zero configuration - just build and run
• Automatic fallback to default UI
• Clear log messages showing which UI is being served
• Optional manual override with --static flag

Logs example:

Found custom UI at .../client/dist, using it instead of default
static_path = /home/.../personaplex-blackwell/client/dist

2. Dynamic Custom Voice System

Problem: Adding custom voices required code changes and server restarts to make them available in the Web UI.

Solution: Automatic voice discovery system that scans voice directories and exposes all voices via /api/voices endpoint.

Benefits:

• Drop voice files and restart - no code changes needed
• Supports both HuggingFace cache and custom directories
• CUSTOM_VOICE_DIR environment variable for custom locations
• REST API for programmatic voice listing
• Frontend automatically populates dropdown from API

Voice file support:

• .pt files (voice embeddings) - appear in UI dropdown
• .wav files (source audio) - used for generating embeddings

API endpoint:

curl http://localhost:8998/api/voices

Returns categorized voice list with metadata.

3. .env File Support

Problem: Users must export HF_TOKEN=... in every terminal session or configure huggingface-cli login globally.

Solution: Support for .env files using python-dotenv library.

Why .env is Better:

Feature	export	.env
Persistence	Lost on terminal close	Set once, works forever
Loading	Manual before each run	Automatic
Security	Appears in shell history	Never in command history
Project-specific	Global to session	Per-project isolation
Documentation	No standard way	.env.example template
Multiple vars	Export each separately	All in one file

Example comparison:

# Old way (export):
export HF_TOKEN=hf_xxxxx
export CUSTOM_VOICE_DIR=./my_voices
python -m moshi.server --ssl "$SSL_DIR"
# Must repeat every terminal session

# New way (.env):
cp .env.example .env
# Edit .env once, then just:
python -m moshi.server --ssl "$SSL_DIR"
# Works in every terminal forever

Changes

Backend:

• moshi/moshi/server.py: UI auto-detection logic, voice discovery, .env loading
• moshi/moshi/offline.py: .env loading, save-voice-embeddings support
• moshi/moshi/voice_discovery.py: New VoiceDiscovery class for scanning voice files
• moshi/pyproject.toml: Added python-dotenv dependency

Frontend:

• client/src/hooks/useVoices.ts: New hook for fetching voices from API
• client/src/components/ModelParams/ModelParams.tsx: Dynamic voice dropdown
• client/src/pages/Queue/Queue.tsx: Integrated voice selection

Documentation:

• .env.example: Template with HF_TOKEN and CUSTOM_VOICE_DIR
• README.md: Updated with all three features
• QUICKSTART.md: Fast setup guide for new users
• FRONTEND_DEVELOPMENT.md: Frontend development workflow guide
• TROUBLESHOOTING.md: Common issues and solutions
• custom_voices/README.md: Custom voice creation guide

Backward Compatibility

✅ Fully backward compatible - no breaking changes:

• All existing workflows continue to work
• --static flag still works for manual override
• export HF_TOKEN still works
• huggingface-cli login still works
• .env file is optional
• Hardcoded voice prompts still work

Testing

UI Auto-Detection:

• ✅ With client/dist present - serves custom UI
• ✅ Without client/dist - falls back to HuggingFace UI
• ✅ Manual --static override works
• ✅ Log messages correctly indicate which UI is served

Voice System:

• ✅ Pre-packaged voices (NATF, NATM, VARF, VARM) load correctly
• ✅ Custom .pt voice files appear in dropdown
• ✅ CUSTOM_VOICE_DIR environment variable works
• ✅ /api/voices endpoint returns correct JSON
• ✅ Frontend dropdown populates automatically
• ✅ Voice selection persists across sessions

.env Support:

• ✅ Server starts successfully with .env file
• ✅ Server starts successfully without .env file (fallback)
• ✅ HF_TOKEN loads from .env
• ✅ CUSTOM_VOICE_DIR loads from .env
• ✅ No warnings when .env is missing
• ✅ No breaking changes to existing workflows

Statistics

• 16 files changed: 1,323 insertions, 47 deletions
• New files: 6 (voice_discovery.py, useVoices.ts, 4 documentation files)
• Modified files: 10
• New dependencies: 1 (python-dotenv)
• Breaking changes: 0

Example Usage

UI Auto-Detection

# Build frontend
cd client && npm run build && cd ..

# Server auto-detects - no flag needed!
SSL_DIR=$(mktemp -d); python -m moshi.server --ssl "$SSL_DIR"
# Logs: "Found custom UI at .../client/dist, using it instead of default"

Custom Voices

# Add voice file
cp my_voice.wav custom_voices/

# Generate embeddings
python -m moshi.offline --voice-prompt "my_voice.wav" \
  --save-voice-embeddings --input-wav "assets/test/input_assistant.wav" --output-wav "/tmp/out.wav"

# Restart server - voice appears in UI automatically!

.env Setup

# One-time setup
cp .env.example .env
# Edit .env and add: HF_TOKEN=your_token_here

# All commands now work without export
python -m moshi.server --ssl "$SSL_DIR"

Related Issues

This PR addresses user experience friction mentioned in community discussions about:

• Simplifying frontend development workflow
• Making custom voices easier to add
• Reducing setup friction for new users

---

All features have been tested and verified working. Ready for review and merge. 🚀