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

   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:

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)