DEPLOYMENT.md

# HuggingFace Spaces Deployment Guide

## Quick Deploy to HuggingFace Spaces

### Prerequisites
- HuggingFace account (create at https://huggingface.co/join)
- Git installed on your machine
- Git LFS installed (for large files)

### Method 1: Web Upload (Easiest)

1. **Create New Space**
   - Go to https://huggingface.co/new-space
   - Name: `ace-step-custom` (or your choice)
   - License: MIT
   - SDK: Gradio
   - Hardware: A10G Small (or better)
   - Click "Create Space"

2. **Upload Files**
   - Click "Files and versions" tab
   - Click "Add file" → "Upload files"
   - Upload all files from `d:\2025-vibe-coding\ACE-Step-Custom\`:
     - `app.py`
     - `requirements.txt`
     - `config.yaml`
     - `README.md` (with YAML frontmatter)
     - `LICENSE`
     - `.gitignore`
     - Entire `src/` directory
     - Entire `scripts/` directory
   - Commit changes

3. **Configure Space**
   - Go to "Settings" tab
   - Set Python version: 3.10
   - Enable GPU: A10G Small (minimum) or A100 (recommended)
   - Set timeout: 30 minutes (for long generations)
   - Save settings

4. **Wait for Build**
   - Space will automatically build and deploy
   - First build takes 5-10 minutes
   - Model will download on first run (~7GB)

### Method 2: Git Push (For Developers)

1. **Create Space on HuggingFace**
   - Go to https://huggingface.co/new-space
   - Create space as above

2. **Clone and Push**
   ```powershell
   # Navigate to project
   cd d:\2025-vibe-coding\ACE-Step-Custom

   # Initialize git (if not already)
   git init
   git add .
   git commit -m "Initial commit"

   # Add HuggingFace remote
   git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/ace-step-custom

   # Push to HuggingFace
   git push hf main
   ```

3. **Configure Git LFS for Large Files**
   ```powershell
   git lfs install
   git lfs track "*.wav"
   git lfs track "*.pth"
   git lfs track "*.bin"
   git lfs track "models/**"
   git add .gitattributes
   git commit -m "Add LFS tracking"
   git push hf main
   ```

### Method 3: HuggingFace CLI (Fastest)

1. **Install HuggingFace CLI**
   ```powershell
   pip install huggingface_hub
   ```

2. **Login**
   ```powershell
   huggingface-cli login
   # Enter your HuggingFace token
   ```

3. **Create and Upload**
   ```powershell
   cd d:\2025-vibe-coding\ACE-Step-Custom
   
   # Create space
   huggingface-cli repo create ace-step-custom --type space --space_sdk gradio
   
   # Upload files
   huggingface-cli upload YOUR_USERNAME/ace-step-custom . --repo-type space
   ```

## Space Configuration

### Hardware Recommendations

| GPU | VRAM | Cost | Performance | Recommended For |
|-----|------|------|-------------|-----------------|
| CPU | - | Free | Very Slow | Testing only |
| T4 Small | 16GB | ~$0.60/hr | Slow | Light testing |
| **A10G Small** | **24GB** | **~$1.05/hr** | **Good** | **Recommended** |
| A10G Large | 24GB | ~$3.15/hr | Good | Production |
| A100 Large | 40GB | ~$4.13/hr | Excellent | Best quality |

**Recommendation:** Start with A10G Small for testing, upgrade to A100 for production.

### Environment Variables (Optional)

In Space settings, you can add:

```
GRADIO_SERVER_NAME=0.0.0.0
GRADIO_SERVER_PORT=7860
HF_HOME=/data/huggingface
TORCH_HOME=/data/torch
```

### Secrets (If Needed)

For API keys or sensitive data:
- Go to Space Settings → Repository secrets
- Add secrets like `HF_TOKEN`, `API_KEY`, etc.
- Access in code: `os.environ.get("SECRET_NAME")`

## Post-Deployment Setup

### First Launch

1. **Wait for Model Download**
   - First launch downloads ACE-Step model (~7GB)
   - Takes 5-10 minutes depending on connection
   - Model cached for subsequent runs

2. **Test Basic Generation**
   - Go to Tab 1 (Standard ACE-Step)
   - Enter simple prompt: "Happy pop song"
   - Set duration to 10 seconds
   - Click Generate

3. **Test Timeline**
   - Go to Tab 2 (Timeline Workflow)
   - Enter prompt and lyrics
   - Set context length to 30s
   - Generate first clip

4. **Test LoRA Training**
   - Go to Tab 3 (LoRA Training)
   - Upload 2-3 test audio files
   - Run quick training (2-3 epochs)

### Monitoring

**View Logs:**
- Click "Logs" tab in your Space
- Monitor for errors or warnings
- Check GPU usage and memory

**Performance Metrics:**
- Generation time
- Memory usage
- Error rate
- User feedback

### Troubleshooting

**Space Not Building:**
- Check requirements.txt for conflicts
- Verify Python 3.10 compatibility
- Check logs for specific errors

**Out of Memory:**
- Upgrade to larger GPU
- Reduce batch size in LoRA training
- Limit generation duration

**Model Not Loading:**
- Check HuggingFace Hub access
- Verify model ID in config.yaml
- Check internet connectivity

**Slow Performance:**
- Upgrade GPU tier
- Reduce concurrent users
- Optimize generation parameters

## Optimization Tips

### Reduce Startup Time

1. **Cache Models**
   ```python
   # In app.py, add before model loading:
   os.environ["HF_HOME"] = "/data/huggingface"
   ```

2. **Preload on Startup**
   - Models download on first run
   - Cached for subsequent uses
   - Consider pre-downloading to Space

### Improve Response Time

1. **Use Queuing**
   - Gradio automatically queues requests
   - Set `max_size` in `app.launch()`

2. **Optimize Generation**
   - Lower default duration
   - Reduce sampling steps
   - Use FP16 precision

### Cost Optimization

1. **Auto-Sleep**
   - Space sleeps after inactivity
   - Wakes on first request
   - Configure in Space settings

2. **Usage Limits**
   - Set max concurrent users
   - Limit generation duration
   - Add rate limiting if needed

## Going Live

### Before Public Release

- [ ] Test all three tabs thoroughly
- [ ] Verify LoRA training works
- [ ] Test with different prompts and styles
- [ ] Check error handling
- [ ] Review logs for issues
- [ ] Test on mobile devices
- [ ] Add usage examples
- [ ] Create demo video

### Public Space Settings

1. **Enable Discussions**
   - Let users report issues
   - Gather feedback

2. **Add Examples**
   - Create example prompts
   - Show best practices
   - Include sample outputs

3. **Update README**
   - Clear usage instructions
   - Feature highlights
   - Limitations and known issues

4. **Pin Space**
   - Makes it discoverable
   - Shows on your profile

## Maintenance

### Regular Updates

```powershell
# Update code
cd d:\2025-vibe-coding\ACE-Step-Custom
git add .
git commit -m "Update description"
git push hf main
```

### Monitor Usage

- Check Space analytics
- Review user feedback
- Monitor error rates
- Track popular features

### Scaling

**If Space Gets Popular:**
1. Upgrade GPU tier
2. Add request queuing
3. Implement caching
4. Consider duplicate Spaces for load balancing

## Support & Community

### Get Help

- HuggingFace Forums: https://discuss.huggingface.co/
- Discord: https://discord.gg/huggingface
- Docs: https://huggingface.co/docs/hub/spaces

### Share Your Space

- Post on Twitter/X with #HuggingFace #ACEStep
- Share in AI music communities
- Add to your portfolio
- Write blog post about it

## Advanced Configuration

### Custom Domain (Pro)

HuggingFace Pro users can set custom domains:
1. Go to Space settings
2. Add custom domain
3. Configure DNS

### Persistent Storage

For saving user data:
```python
import os
PERSIST_DIR = os.environ.get("SPACE_ID", "local")
# Save to /data/{SPACE_ID}/
```

### Analytics Integration

Add Google Analytics or similar:
```python
# In app.py
analytics_code = """
<script async src="https://www.googletagmanager.com/gtag/js?id=YOUR-ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'YOUR-ID');
</script>
"""
```

## Success Checklist

Before announcing your Space:

- ✅ All features working
- ✅ Clear documentation
- ✅ Example outputs included
- ✅ Error handling robust
- ✅ Performance optimized
- ✅ Mobile-friendly UI
- ✅ Clear limitations stated
- ✅ License properly attributed
- ✅ Usage guidelines clear
- ✅ Contact/support info provided

## Your Space URL

After deployment, your Space will be available at:
```
https://huggingface.co/spaces/YOUR_USERNAME/ace-step-custom
```

Share it with the world! 🎵🚀