SUBMISSION_GUIDE.md

# 🚀 HuggingFace Spaces Submission Guide

## Pre-Submission Checklist

Before submitting, verify:

- ✅ `README.md` has proper YAML front matter with tags
- ✅ `requirements.txt` includes all dependencies
- ✅ `packages.txt` includes `ffmpeg`
- ✅ `app.py` is the main entry point
- ✅ All Python files are present (`app.py`, `localizer_engine.py`, `server.py`)
- ✅ Code works locally without errors
- ✅ No hardcoded API keys in code

## Step 1: Prepare Your Repository

### Option A: If you haven't initialized Git yet

```bash
cd /Users/osamamoftah/Desktop/MCP-Video-Localizer

# Initialize git repository
git init

# Add all files
git add .

# Create initial commit
git commit -m "Initial commit: Global Video Localizer for MCP Hackathon"
```

### Option B: If Git is already initialized

```bash
cd /Users/osamamoftah/Desktop/MCP-Video-Localizer

# Check status
git status

# Add any new/modified files
git add .

# Commit changes
git commit -m "Ready for HuggingFace Spaces submission"
```

## Step 2: Create/Connect to HuggingFace Space

### If you already created the Space:

1. Go to your Space on HuggingFace: `https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME`
2. Click on **"Files and versions"** tab
3. Click **"Add file"** → **"Upload files"**
4. Upload all files:
   - `app.py`
   - `localizer_engine.py`
   - `server.py`
   - `requirements.txt`
   - `packages.txt`
   - `README.md`

### If you want to use Git (Recommended):

1. Go to your Space on HuggingFace
2. Click on **"Files and versions"** tab
3. Copy the **Git URL** (looks like: `https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME`)

Then in your terminal:

```bash
cd /Users/osamamoftah/Desktop/MCP-Video-Localizer

# Add HuggingFace remote (replace with your actual Space URL)
git remote add huggingface https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME

**Note**: If you get authentication errors, you may need to:
- Use a HuggingFace token: `git push https://USERNAME:TOKEN@huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME main`
- Or set up Git LFS if needed

## Step 3: Verify Space Configuration

1. Go to your Space settings
2. Verify:
   - **SDK**: Gradio
   - **SDK Version**: 4.44.0 (or latest compatible)
   - **Hardware**: CPU (or GPU if you have credits)
   - **Secrets**: Not needed (app works without API keys)

3. Check the **README.md** is rendering correctly with:
   - Title: "Global Video Localizer"
   - Emoji: 🌍
   - Tags: `mcp-in-action-track-consumer` and others

## Step 4: Test Your Space

1. Wait for the build to complete (usually 2-5 minutes)
2. Click **"App"** tab to open your app
3. Test with a short video:
   - Upload a test video (10-30 seconds)
   - Select a language (try Spanish first)
   - Click "Localize Video"
   - Verify it works without API key (should use EdgeTTS)
   - Verify it works with API key (if you add one)

4. Check logs:
   - Click **"Logs"** tab
   - Look for any errors
   - Verify dependencies installed correctly

## Step 5: Submit to Hackathon

### Find the Hackathon Page

1. Go to: https://huggingface.co/MCP-1st-Birthday
2. Or search for "MCP 1st Birthday Hackathon" on HuggingFace

### Submission Process

1. **Click "Submit Your Project"** or similar button
2. **Fill out the submission form**:
   - **Space URL**: `https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME`
   - **Track**: Select `mcp-in-action-track-consumer` (Consumer MCP Servers)
   - **Title**: "Global Video Localizer"
   - **Description**: 
     ```
     Automated video localization system that breaks language barriers. 
     Upload a video, select a language, get a professionally dubbed version in minutes.
     Full MCP integration allows Claude to localize videos programmatically.
     Works completely free with open source models.
     ```
   - **Tags**: `mcp-in-action-track-consumer`, `video`, `translation`, `tts`, `whisper`, `elevenlabs`, `gradio`, `mcp`
   - **Social Media Links**: (Optional) Your X/Twitter and LinkedIn posts

3. **Submit the form**

## Step 6: Post on Social Media (Required)

According to hackathon rules, you need to post about your project:

### X (Twitter)
- Post about your app
- Tag: `@huggingface` and `@AnthropicAI`
- Use hashtag: `#MCPHackathon`
- Include link to your Space

### LinkedIn
- Post about your app
- Tag: `@Hugging Face` and `@Anthropic`
- Use hashtag: `#MCPHackathon`
- Include link to your Space

**Sample Posts** (see `SOCIAL_MEDIA_POSTS.md` if you saved it, or create new ones)

## Step 7: Verify Submission

1. Check your Space is public and accessible
2. Verify README displays correctly
3. Test the app works on HuggingFace infrastructure
4. Confirm your submission appears on the hackathon page

## Troubleshooting

### Build Fails

**Error**: `ModuleNotFoundError`
- **Fix**: Check `requirements.txt` has all dependencies
- Verify package names are correct

**Error**: `ffmpeg not found`
- **Fix**: Ensure `packages.txt` contains `ffmpeg`

**Error**: `Gradio version mismatch`
- **Fix**: Update `sdk_version` in README.md front matter to match your `requirements.txt`

### App Doesn't Work

**Video processing fails**:
- Check logs for specific errors
- Verify `moviepy` and `pydub` are installed
- Test with a smaller video first

**TTS not working**:
- Check logs for TTS errors
- Verify fallback system is working
- Test without API key first (should use EdgeTTS)

### Git Push Issues

**Authentication error**:
```bash
# Use HuggingFace token
git push https://YOUR_USERNAME:YOUR_TOKEN@huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME main
```

**Large files**:
- HuggingFace Spaces has file size limits
- Videos should be uploaded by users, not stored in repo
- If needed, use Git LFS for large files

## Final Checklist Before Submission

- [ ] Space builds successfully
- [ ] App runs without errors
- [ ] Works without API keys (open source models)
- [ ] Works with ElevenLabs API key (optional)
- [ ] README displays correctly
- [ ] All tags are correct in README
- [ ] Social media posts are published
- [ ] Hackathon submission form is filled
- [ ] Space is public and accessible

## Quick Command Reference

```bash
# Navigate to project
cd /Users/osamamoftah/Desktop/MCP-Video-Localizer

# Check git status
git status

# Add all files
git add .

# Commit
git commit -m "Ready for submission"

# Push to HuggingFace (replace with your Space URL)
git push https://YOUR_USERNAME:YOUR_TOKEN@huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME main

# Or if remote is set up
git push huggingface main
```

## Need Help?

- **HuggingFace Docs**: https://huggingface.co/docs/hub/spaces
- **Gradio Docs**: https://www.gradio.app/docs/
- **Hackathon Info**: https://huggingface.co/MCP-1st-Birthday
- **MCP Docs**: https://modelcontextprotocol.io/

---

**Good luck with your submission! 🚀**