🎬 Animated Photo - AI Video Generator

Transform static photos into short animated videos using Stable Video Diffusion, running 100% locally on your hardware with a modern microservices architecture.

Perfect for bringing vintage photos to life with smooth, natural motion!

🏗️ Architecture

This project uses a microservices architecture with separate containers:

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│  React Frontend │ ───▶ │  FastAPI Backend│ ───▶ │  Model Service  │
│   Port: 3000    │      │   Port: 5000    │      │   Port: 5001    │
│                 │      │                 │      │   (GPU-powered) │
│  • Upload UI    │      │  • File handling│      │  • SVD Model    │
│  • Parameters   │      │  • Job queue    │      │  • Video gen    │
│  • Progress     │      │  • API routes   │      │  • Docker       │
└─────────────────┘      └─────────────────┘      └─────────────────┘

Components:

Frontend: React + TypeScript for modern UI
Backend: FastAPI for async API with auto-documentation
Model Service: Flask + PyTorch running Stable Video Diffusion in Docker
Orchestration: Docker Compose for easy deployment

🚀 Features

Modern Tech Stack: React + FastAPI + Docker
Microservices: Each component runs independently
GPU Accelerated: Uses your RTX 5070 Ti through Docker
Latest AI Model: CogVideoX-5B (August 2024) - best open-source quality
Async Processing: Non-blocking video generation
Auto Documentation: FastAPI provides /docs endpoint
Easy Deployment: Single docker-compose up command
Customizable Parameters:
- Prompt: Describe desired motion (NEW!)
- Duration (1-6 seconds)
- Frame rate (6-10 FPS, optimal: 8)
- Quality (30-100 inference steps)
- Guidance scale (prompt adherence)

📋 Prerequisites

Required Software

Python 3.11 or 3.12
- Download: https://www.python.org/downloads/
- ⚠️ Check "Add Python to PATH" during installation
Node.js 20+ (LTS)
- Download: https://nodejs.org/
- Includes npm package manager
Docker Desktop
- Download: https://www.docker.com/products/docker-desktop/
- Required for GPU access and containerization
- Enable WSL 2 backend on Windows

Hardware Requirements

GPU: NVIDIA RTX 5070 Ti (or any CUDA GPU with 8GB+ VRAM)
RAM: 16GB+ recommended
Storage: ~20GB for models and cache
Internet: Required for initial model download (~15GB)

🛠️ Quick Setup

Automated Setup (Recommended)

# Run the setup script
.\setup.ps1

This will:

Check prerequisites
Create Python virtual environment
Install all dependencies
Prepare for deployment

Manual Setup

See SETUP.md for detailed manual installation steps.

🎯 Running the Application

Option A: Docker Compose (Recommended)

Easiest way - runs everything in containers:

# Build and start all services
docker-compose up --build

# Or run in background
docker-compose up -d --build

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Access the app:

Frontend: http://localhost:3000
Backend API: http://localhost:5000
API Documentation: http://localhost:5000/docs (auto-generated!)
Model Service: http://localhost:5001/health

Option B: Local Development

Run each service separately (useful for development):

Terminal 1 - Model Service:

.\venv\Scripts\Activate
cd model-service
python model_service.py

Terminal 2 - Backend:

.\venv\Scripts\Activate
cd backend
python app.py

Terminal 3 - Frontend:

cd frontend
npm start

📁 Project Structure

AnimatedPhoto/
├── backend/                  # FastAPI backend
│   ├── app.py               # Main API application
│   ├── requirements.txt     # Python dependencies
│   ├── Dockerfile           # Container definition
│   ├── uploads/             # Uploaded photos (auto-created)
│   └── outputs/             # Generated videos (auto-created)
│
├── model-service/           # AI model container
│   ├── model_service.py     # Model inference API
│   ├── requirements.txt     # ML dependencies
│   ├── Dockerfile           # GPU-enabled container
│   └── .dockerignore        # Exclude from build
│
├── frontend/                # React frontend
│   ├── src/                 # Source code
│   ├── public/              # Static files
│   ├── package.json         # npm dependencies
│   └── Dockerfile           # Container definition
│
├── docker-compose.yml       # Orchestration config
├── setup.ps1                # Automated setup script
├── SETUP.md                 # Detailed setup guide
└── README.md                # This file

🎨 Using the App

Upload Photo
- Click or drag & drop your image
- Supports PNG, JPG, JPEG (max 16MB)
Adjust Parameters
- Duration: Length of video (1-5 seconds)
- Frame Rate: Smoothness (7 FPS recommended)
- Quality: Inference steps (25 = good balance)
- Motion: Low/Medium/High animation strength
Generate Video
- Click "Generate Video"
- Wait 1-3 minutes (varies by settings)
- First generation loads model (~30 sec extra)
Download Result
- Preview video in browser
- Download MP4 file

⚙️ API Endpoints (FastAPI)

The backend provides these REST API endpoints:

GET `/api/health`

Check backend and model service status

POST `/api/upload`

Upload photo and start generation

Form data: photo, duration, fps, quality, motion_strength
Returns: job_id for tracking

GET `/api/status/{job_id}`

Get job progress and status

Returns: status, progress, download_url

GET `/api/download/{filename}`

Download generated video

GET `/api/jobs`

List all jobs (debugging)

GET `/docs`

Auto-generated API documentation (FastAPI feature!)

🐛 Troubleshooting

Python Not Found

# Verify Python installation
python --version

# If not found, reinstall and add to PATH

Docker GPU Not Working

# Check NVIDIA Docker runtime
docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

# If error, reinstall Docker Desktop and NVIDIA drivers

Model Download Fails

Check internet connection
Ensure ~20GB free disk space
Downloads resume automatically if interrupted

Port Already in Use

# Check what's using the port
netstat -ano | findstr :3000
netstat -ano | findstr :5000
netstat -ano | findstr :5001

# Kill process or change ports in docker-compose.yml

Out of Memory

Close other GPU-intensive apps
Lower quality/FPS settings
Ensure 8GB+ VRAM available

🔧 Development

Backend Development

# Activate venv
.\venv\Scripts\Activate

# Run with auto-reload
cd backend
uvicorn app:app --reload --host 0.0.0.0 --port 5000

# View API docs at http://localhost:5000/docs

Frontend Development

cd frontend
npm start  # Auto-reloads on changes
npm run build  # Production build

Model Service Development

.\venv\Scripts\Activate
cd model-service
python model_service.py  # Runs on port 5001

🔍 Technical Details

Backend (FastAPI)

Framework: FastAPI 0.109+ with async/await
Server: Uvicorn ASGI server
Features: Background tasks, CORS, file uploads, prompt control
Storage: In-memory job queue (use Redis for production)

Model Service (Flask + PyTorch)

Model: CogVideoX-5B-I2V (THUDM/Tsinghua University) - Latest 2024 model!
Framework: PyTorch 2.3+ with CUDA 12.1
Features: Prompt-controllable animation, 6-second videos, high quality
Optimization: Model CPU offload, VAE slicing & tiling
Container: NVIDIA CUDA runtime for GPU access

Frontend (React)

Framework: React 18+ with TypeScript
Styling: CSS-in-JS with modern gradients
Features: Drag-drop, progress tracking, video preview
Build: Create React App (can migrate to Vite)

🚀 Performance Tips

Faster Generation

Use quality=20 (instead of 25-30)
Lower FPS (6-7 instead of 8-10)
Shorter duration (2s instead of 3-4s)

Better Quality

Use quality=35-50 (slower!)
Higher FPS (9-10)
Lower motion strength for portraits

First Run

Model download: ~10-20 minutes
Model loading: ~30 seconds
First generation: ~2-3 minutes
Subsequent: ~1-2 minutes

📝 Environment Variables

Backend (.env)

MODEL_SERVICE_URL=http://model-service:5001  # Docker
# MODEL_SERVICE_URL=http://localhost:5001  # Local

Frontend (.env)

REACT_APP_API_URL=http://localhost:5000

🤝 Credits

Stable Video Diffusion: Stability AI
Diffusers Library: Hugging Face
FastAPI: Tiangolo
React: Meta

📄 License

This project is for educational and personal use.

Stable Video Diffusion model has its own license from Stability AI.

🎓 Learn More

Enjoy bringing your photos to life with modern microservices! 🎬✨

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
backend		backend
frontend		frontend
model-service		model-service
test		test
.gitattributes		.gitattributes
.gitignore		.gitignore
BASH_GUIDE.md		BASH_GUIDE.md
DOCKER_GUIDE.md		DOCKER_GUIDE.md
FLASH_ATTENTION_BUILD.md		FLASH_ATTENTION_BUILD.md
GETTING_STARTED.md		GETTING_STARTED.md
MODELS_COMPARISON.md		MODELS_COMPARISON.md
README.md		README.md
RUN-DOCKER-DEV.ps1		RUN-DOCKER-DEV.ps1
RUN-DOCKER.ps1		RUN-DOCKER.ps1
RUN-LOCAL.ps1		RUN-LOCAL.ps1
SETUP.md		SETUP.md
START.ps1		START.ps1
check_build_status.ps1		check_build_status.ps1
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
run-docker-dev.sh		run-docker-dev.sh
run-docker.sh		run-docker.sh
run-local.sh		run-local.sh
setup.ps1		setup.ps1
start.sh		start.sh

W1neSkin/AnimatedPhoto

Folders and files

Latest commit

History

Repository files navigation