SPACE_SETUP.md

# Hugging Face Space Setup Guide (Gradio + Zero GPU)

This guide will help you deploy sub200 to a Hugging Face Space with **zero GPU** (H200 dynamic allocation) using Gradio SDK.

## Quick Start

1. **Create a new Space on Hugging Face**
   - Go to https://huggingface.co/spaces
   - Click "Create new Space"
   - Name: `sub200` (or your preferred name)
   - SDK: **Gradio** (not Docker!)
   - Hardware: **Zero GPU** (H200 dynamic allocation)
   - Visibility: Public or Private

2. **Push this repository to the Space**
   ```bash
   git remote add huggingface https://huggingface.co/spaces/YOUR_USERNAME/sub200
   git push huggingface main
   ```

   Or use the Hugging Face web interface to upload files.

## Required Files

The following files are already configured:
- ✅ `README.md` - Space metadata with Gradio SDK configuration
- ✅ `app.py` - Gradio application
- ✅ `requirements.txt` - Python dependencies
- ✅ `download_models.py` - Model download script
- ✅ `.gitignore` - Git exclusions

## Zero GPU Configuration

**Zero GPU** (H200 dynamic allocation) means:
- GPU is allocated **only when needed** (e.g., when using Coqui TTS)
- No GPU needed for other engines (Piper, Edge TTS, eSpeak, etc.)
- More efficient resource usage
- **Only works with Gradio SDK**, not Docker

## GPU Usage

The GPU is automatically used when:
- **Coqui TTS** is selected - GPU accelerates neural TTS models
- Other engines (Piper, Edge TTS, eSpeak, gTTS, pyttsx3) work without GPU

## Model Files

### Piper Models
- Models are downloaded automatically at runtime if not present
- Or you can include them in the repository (they're ~60MB each)

### Coqui Models
- Models are downloaded automatically on first use
- They're cached in the Space's storage
- First download may take a few minutes

## Environment Variables

Hugging Face Spaces automatically sets:
- `PORT` - Server port (default: 7860)
- `SPACE_ID` - Your Space ID
- GPU is allocated dynamically when needed

## Customization

### Change Default Engine
Edit `app.py` and change the default value in `engine_select`:
```python
value=available_engines[0] if available_engines else "espeak",
```

### Add More Models
1. Add model files to `models/` directory
2. Or modify `download_models.py` to download additional models

### Update Dependencies
Edit `requirements.txt` and rebuild the Space.

## Troubleshooting

### Build Fails
- Check `requirements.txt` syntax
- Verify all dependencies are compatible
- Check Space logs for specific errors

### GPU Not Working
- Confirm **Zero GPU** is enabled in Space settings
- Check that Coqui TTS is selected
- Verify PyTorch CUDA availability in logs

### Models Not Loading
- Ensure models directory exists
- Check file permissions
- Verify model file paths
- Check internet connection for model downloads

### Audio Not Playing
- Check browser console for errors
- Verify audio format is supported
- Try a different TTS engine

## Performance Tips

1. **Use Zero GPU** - Efficient resource usage with dynamic allocation
2. **Choose Right Engine**:
   - **Piper** - Fastest, lowest latency, offline
   - **Edge TTS** - Best quality, requires internet
   - **Coqui** - High quality, GPU accelerated (uses GPU dynamically)
   - **eSpeak** - Fastest, basic quality, offline

3. **Cache Models** - Models are cached after first download

## Monitoring

- Check Space logs in the Hugging Face interface
- Monitor GPU usage in Space metrics (when GPU is allocated)
- Check engine status in the UI accordion

## Differences from Docker Version

- Uses **Gradio SDK** instead of Docker
- Requires **Zero GPU** instead of persistent GPU
- GPU is allocated dynamically only when needed
- Simpler deployment (no Dockerfile needed)
- Automatic port configuration (7860)

## Support

For issues or questions:
- Check the main README.md
- Review Space logs
- Open an issue on GitHub (if applicable)