# 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:**
   ```bash
   python setup.py
   ```

2. **Install backend dependencies:**
   ```bash
   cd backend
   pip install -r requirements.txt
   ```

3. **Start the servers:**
   ```bash
   # 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
```bash
# .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
```bash
# .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
```bash
# .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:
```bash
export PYTHONPATH="${PYTHONPATH}:$(pwd)"
export DEBUG=1
```

### Resetting Configuration

To reset to defaults:
```bash
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