chatterbox-ui/ENVIRONMENT_SETUP.md

Environment Configuration Guide

This guide explains how to configure the Chatterbox TTS application for different environments using environment variables.

Quick Setup

1. Run the setup script:

   python setup.py
   

2. Install backend dependencies:

   cd backend
   pip install -r requirements.txt
   

3. Start the servers:

   # Terminal 1 - Backend
   cd backend
   python start_server.py
   
   # Terminal 2 - Frontend
   cd frontend
   python start_dev_server.py
   

4. Open the application: Open http://127.0.0.1:8001 in your browser

Manual Configuration

Environment Files

The application uses environment variables for configuration. Three .env files control different aspects:

• Root .env: Global configuration
• backend/.env: Backend-specific settings
• frontend/.env: Frontend-specific settings

Key Configuration Options

Paths

• PROJECT_ROOT: Base directory for the project
• SPEAKER_SAMPLES_DIR: Directory containing speaker audio samples
• TTS_TEMP_OUTPUT_DIR: Temporary directory for TTS processing
• DIALOG_GENERATED_DIR: Directory for generated dialog audio files

Server Configuration

• HOST: Backend server host (default: 0.0.0.0)
• PORT: Backend server port (default: 8000)
• RELOAD: Enable auto-reload for development (default: true)

Frontend Configuration

• VITE_API_BASE_URL: Backend API base URL
• VITE_DEV_SERVER_PORT: Frontend development server port
• VITE_DEV_SERVER_HOST: Frontend development server host

CORS Configuration

• CORS_ORIGINS: Comma-separated list of allowed origins

Device Configuration

• DEVICE: Device for TTS model (auto, cpu, cuda, mps)

Example Configurations

Development Environment

# .env
PROJECT_ROOT=/Users/yourname/chatterbox-ui
BACKEND_PORT=8000
FRONTEND_PORT=8001
DEVICE=auto
CORS_ORIGINS=http://localhost:8001,http://127.0.0.1:8001

Production Environment

# .env
PROJECT_ROOT=/opt/chatterbox-ui
BACKEND_HOST=0.0.0.0
BACKEND_PORT=8000
FRONTEND_PORT=3000
DEVICE=cuda
CORS_ORIGINS=https://yourdomain.com

Docker Environment

# .env
PROJECT_ROOT=/app
BACKEND_HOST=0.0.0.0
BACKEND_PORT=8000
DEVICE=cpu
CORS_ORIGINS=http://localhost:3000

Troubleshooting

Common Issues

1. Permission Errors: Ensure the PROJECT_ROOT directory is writable
2. CORS Errors: Check that your frontend URL is in CORS_ORIGINS
3. Model Loading Errors: Verify DEVICE setting matches your hardware
4. Path Errors: Ensure all path variables point to existing, accessible directories

Debugging

Enable debug logging by setting:

export PYTHONPATH="${PYTHONPATH}:$(pwd)"
export DEBUG=1

Resetting Configuration

To reset to defaults:

rm .env backend/.env frontend/.env
python setup.py

File Structure

chatterbox-ui/
├── .env                          # Global configuration
├── .env.example                  # Template for global config
├── setup.py                      # Automated setup script
├── backend/
│   ├── .env                      # Backend configuration
│   ├── .env.example              # Template for backend config
│   ├── start_server.py           # Backend startup script
│   └── app/
│       └── config.py             # Configuration loader
├── frontend/
│   ├── .env                      # Frontend configuration
│   ├── .env.example              # Template for frontend config
│   ├── start_dev_server.py       # Frontend dev server
│   └── js/
│       └── config.js             # Frontend configuration loader
└── speaker_data/
    └── speaker_samples/          # Speaker audio files

Security Notes

• Never commit .env files to version control
• Use strong, unique values for production
• Restrict CORS origins in production
• Use HTTPS in production environments
• Regularly update dependencies