4.2 KiB

Raw Permalink Blame History

Environment Configuration Guide

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

Quick Setup

Run the setup script:
```
python setup.py
```

Install backend dependencies:

cd backend
pip install -r requirements.txt

Start the servers:

# Terminal 1 - Backend
cd backend
python start_server.py

# Terminal 2 - Frontend
cd frontend
python start_dev_server.py

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. When using start_servers.py with the default FRONTEND_HOST=0.0.0.0 and no explicit CORS_ORIGINS, CORS will allow all origins (wildcard) to simplify development.

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

Permission Errors: Ensure the PROJECT_ROOT directory is writable
CORS Errors: Check that your frontend URL is in CORS_ORIGINS. (When using start_servers.py, your specified FRONTEND_HOST:FRONTEND_PORT will be auto‑included.)
Model Loading Errors: Verify DEVICE setting matches your hardware
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

4.2 KiB Raw Permalink Blame History Unescape Escape