README.md

---
title: Short Video Maker
emoji: 🎬
colorFrom: purple
colorTo: pink
sdk: docker
app_port: 8880
---

# Short Video Maker - Python FastAPI 🎬

Complete Python/FastAPI migration of the short-video-maker for Hugging Face Spaces Docker deployment.

## ✨ Features

- 🎙️ Text-to-speech narration via Kokoro (cloud API)
- 📝 Automatic caption generation using Whisper
- 🎥 Background videos from Pexels API  
- 🎵 Background music with mood selection
- 📱 Portrait (9:16) and landscape (16:9) support
- 🌐 Web UI and REST API
- 🚀 Optimized for Hugging Face Spaces deployment

## 🏗️ Project Structure

```
video_bot_python/
├── app.py                      # Main FastAPI application
├── config.py                   # Configuration management
├── requirements.txt            # Python dependencies
├── Dockerfile                  # HF Spaces Docker config
├── models/
│   └── schemas.py             # Pydantic models
├── routers/
│   └── api.py                 # REST API endpoints
├── video_creator/
│   ├── short_creator.py       # Main orchestrator
│   ├── music_manager.py       # Music file management
│   └── libraries/
│       ├── tts_client.py      # Kokoro TTS client
│       ├── whisper_client.py  # Faster-whisper integration
│       ├── pexels_client.py   # Pexels API client
│       ├── ffmpeg_utils.py    # Audio processing
│       └── video_composer.py  # MoviePy video composition
├── static/
│   ├── index.html             # Web UI
│   ├── style.css              # UI styles
│   ├── app.js                 # UI logic
│   └── music/                 # Background music files
└── tests/
    ├── test_api.py            # Unit tests
    └── integration_test.py    # E2E test
```

## 🚀 Quick Start

### Local Development

1. **Clone and install:**
```bash
cd video_bot_python
pip install -r requirements.txt
```

2. **Configure environment:**
```bash
cp .env.example .env
# Edit .env with your API keys:
# - PEXELS_API_KEY (from https://www.pexels.com/api/)
# - HF_TTS (your TTS endpoint URL)
```

3. **Run the server:**
``` bash
python app.py
# Or with uvicorn:
uvicorn app:app --host 0.0.0.0 --port 8880 --reload
```

4. **Access:**
- Web UI: http://localhost:8880
- API docs: http://localhost:8880/docs
- Health: http://localhost:8880/health

### Docker

```bash
# Build
docker build -t short-video-maker-python .

# Run
docker run -p 8880:8880 \
  -e PEXELS_API_KEY="your_key" \
  -e HF_TTS="https://your-tts.hf.space" \
  -v $(pwd)/data:/data \
  short-video-maker-python
```

### Hugging Face Spaces (Deploy)

1. **Create Space:**
   - Go to https://huggingface.co/new-space
   - Select "Docker" SDK
   - Clone your space repository

2. **Push code:**
```bash
git clone https://huggingface.co/spaces/YOUR_USERNAME/short-video-maker
cp -r video_bot_python/* short-video-maker/
cd short-video-maker
git add .
git commit -m "Initial Python FastAPI version"
git push
```

3. **Configure secrets:**
   - Go to Space Settings → Repository Secrets
   - Add: `PEXELS_API_KEY`
   - Add: `HF_TTS`

4. **Wait for build and access:**
   - `https://YOUR_USERNAME-short-video-maker.hf.space`

## 📡 API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Health check |
| `/api/short-video` | POST | Create new video |
| `/api/short-video/{id}/status` | GET | Check video status |
| `/api/short-video/{id}` | GET | Download video |
| `/api/short-videos` | GET | List all videos |
| `/api/short-video/{id}` | DELETE | Delete video |
| `/api/voices` | GET | List TTS voices |
| `/api/music-tags` | GET | List music moods |

### Example: Create Video

```bash
curl -X POST http://localhost:8880/api/short-video \
  -H "Content-Type: application/json" \
  -d '{
    "scenes": [
      {
        "text": "Hello world!",
        "searchTerms": ["nature", "forest"]
      }
    ],
    "config": {
      "voice": "af_heart",
      "music": "chill",
      "orientation": "portrait"
    }
  }'
```

## ⚙️ Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `PEXELS_API_KEY` | ✅ Yes | - | Pexels API key |
| `HF_TTS` | ✅ Yes | - | TTS service URL |
| `PORT` | No | 8880 | Server port |
| `LOG_LEVEL` | No | info | Logging level |
| `WHISPER_MODEL` | No | tiny.en | Whisper model |
| `DATA_DIR_PATH` | No | auto | Data directory |
| `DOCKER` | No | false | Docker mode |

## 🧪 Testing

**Unit tests:**
```bash
pytest tests/test_api.py -v
```

**Integration test:**
```bash
# Set environment variables first
export PEXELS_API_KEY="your_key"
export HF_TTS="https://your-tts.hf.space"

python tests/integration_test.py
```

## 🔄 Migration from Node.js

This Python version maintains API compatibility with the original Node.js version:

| Component | Node.js | Python |
|-----------|---------|--------|
| Framework | Express.js | FastAPI |
| Video composition | Remotion | MoviePy |
| Captions | Whisper.cpp | faster-whisper |
| TTS | Kokoro-js | HTTP client (cloud) |
| Media search | Pexels API | Pexels API |
| Audio | FFmpeg | FFmpeg |

**API endpoints remain identical** - existing clients will work without changes!

## 📝 Configuration Options

```python
{
  "voice": "af_heart",           # TTS voice
  "music": "chill",              # Music mood (sad/happy/chill/dark/etc)
  "musicVolume": "high",         # low/medium/high/muted
  "orientation": "portrait",     # portrait/landscape
  "captionPosition": "bottom",   # top/center/bottom
  "captionBackgroundColor": "blue",
  "paddingBack": 1000           # End padding in milliseconds
}
```

## 🎵 Adding Music

1. Copy MP3 files to `static/music/`
2. (Optional) Create `static/music/music_metadata.json`:
```json
{
  "song1.mp3": {"mood": "chill"},
  "song2.mp3": {"mood": "happy"}
}
```

## 🐛 Troubleshooting

**"PEXELS_API_KEY is required"**
- Set the environment variable or add to `.env` file

**"HF_TTS is required"**
- Set your TTS endpoint URL (must be accessible)

**"No music files found"**
- Copy MP3 files to `static/music/` directory

**Video processing takes too long**
- Use `tiny.en` Whisper model (faster)
- Reduce video length
- Use fewer scenes

**Out of memory during rendering**
- Increase container memory
- Reduce `VIDEO_CACHE_SIZE_IN_BYTES`
- Use shorter videos

## 🏗️ Development

Install dev dependencies:
```bash
pip install pytest pytest-asyncio httpx black
```

Format code:
```bash
black .
```

## 📄 License

MIT

## 🙏 Credits

- Original Node.js version by [David Gyori](https://github.com/gyoridavid/short-video-maker)
- [Remotion](https://remotion.dev/) → [MoviePy](https://zulko.github.io/moviepy/)
- [Whisper](https://github.com/ggml-org/whisper.cpp) → [faster-whisper](https://github.com/SYSTRAN/faster-whisper)
- [Pexels](https://www.pexels.com/) for video content
- [FFmpeg](https://ffmpeg.org/) for media processing