README.md

metadata

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:

cd video_bot_python
pip install -r requirements.txt

2. Configure environment:

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:

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

# 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:

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

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:

pytest tests/test_api.py -v

Integration test:

# 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

{
  "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:

{
  "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:

pip install pytest pytest-asyncio httpx black

Format code:

black .

📄 License

MIT

🙏 Credits

• Original Node.js version by David Gyori
• Remotion → MoviePy
• Whisper → faster-whisper
• Pexels for video content
• FFmpeg for media processing