# Hugging Face Spaces Deployment Guide

## Prerequisites

This project is now ready to deploy on Hugging Face Spaces. Before deploying, ensure you have:

1. A Hugging Face account
2. Git and Git LFS installed locally (for large model files)
3. All model files and embeddings files present

## Setup Steps

### 1. Prepare Your Hugging Face Repository

```bash
# Create a new Space on Hugging Face (https://huggingface.co/new-space)
# Choose:
# - SDK: Gradio
# - License: Choose appropriate license
# - Space name: austrian-dialect-tts (or your preferred name)
```

### 2. Clone and Configure Repository

```bash
# Clone the space repository locally
git clone https://huggingface.co/spaces/YOUR_USERNAME/austrian-dialect-tts
cd austrian-dialect-tts

# Add the model files (these need to be large binary files)
# Copy the following directories:
# - InferenceInterfaces/
# - Preprocessing/
# - Utility/
# - Models/
```

### 3. Install Git LFS

For large model files, you'll need Git LFS:

```bash
# Install Git LFS
git lfs install

# Track large files
git lfs track "*.pt"     # PyTorch model files
git lfs track "*.wav"    # Audio files
git lfs track "*.pkl"    # Pickle files
```

### 4. Add Required Files

The following files are already created:
- `app.py` - Main Gradio interface
- `requirements.txt` - Python dependencies  
- `README.md` - Metadata and documentation
- `.gitignore` - Git ignore rules

### 5. Push to Hugging Face

```bash
git add .
git commit -m "Initial deployment of Austrian Dialect TTS"
git push
```

## Important Considerations

### Large Files and Model Storage

⚠️ **Critical**: Hugging Face Spaces has size limits. You'll need to:

1. **Use Git LFS** for model files (> 50 MB)
2. **Consider external storage**:
   - Host model files on Hugging Face Model Hub
   - Use `huggingface_hub` to download at runtime
   - Reference example below

### Sample Code for Dynamic Model Loading

If model files are too large, modify `app.py` to download them at startup:

```python
from huggingface_hub import hf_hub_download

def setup_models():
    """Download models from Hugging Face Hub if not present."""
    try:
        # Example: download a model file
        model_file = hf_hub_download(
            repo_id="YOUR_USERNAME/austrian-dialect-models",
            filename="Austrian_vox107_wav2vec_espeak.pt",
            cache_dir="./Models"
        )
        return model_file
    except Exception as e:
        print(f"Error downloading model: {e}")
        raise
```

### Memory and Computation

- **GPU**: Recommended for faster inference (~2-5 seconds per utterance with GPU)
- **CPU**: Possible but slower (~10-30 seconds per utterance)
- Hugging Face provides free CPU tier and paid GPU tier

### Troubleshooting

**Issue**: Large file upload fails
- **Solution**: Use Git LFS or split into smaller pieces

**Issue**: Module import errors
- **Solution**: Ensure all dependencies in `requirements.txt` are compatible with the environment

**Issue**: Model files not found at runtime
- **Solution**: Use the dynamic loading approach with `huggingface_hub`

## Directory Structure for Hugging Face

```
.
├── app.py                          # Main entry point (required by Spaces)
├── requirements.txt                # Dependencies
├── README.md                        # Space description
├── .gitignore
├── InferenceInterfaces/            # TTS implementation
├── Preprocessing/                  # Text processing and embeddings
├── Utility/                        # Utility functions
├── Models/                         # Pre-trained models (use Git LFS)
└── audios/                         # Output directory (created at runtime)
```

## Next Steps

1. Create a Hugging Face Space: https://huggingface.co/new-space
2. Clone your space repository
3. Copy project files to the space directory
4. Set up Git LFS for large files
5. Push to Hugging Face
6. Monitor the build and debug any import/dependency issues

## Additional Resources

- [Hugging Face Spaces Documentation](https://huggingface.co/docs/hub/spaces)
- [Gradio Documentation](https://gradio.app/)
- [Git LFS Guide](https://git-lfs.github.com/)

## Performance Notes

Expected inference times:
- **GPU (NVIDIA T4)**: 2-5 seconds per sentence
- **CPU**: 10-30 seconds per sentence
- **Cold start (first inference)**: +3-5 seconds for model initialization

For production use, consider:
- Deploying with GPU (paid tier)
- Pre-warming the model with example audio
- Implementing request queuing/batching