🎬 AI Video Upscaler

A web-based video upscaling application powered by Real-ESRGAN ncnn-vulkan. Upload your videos through an intuitive dashboard, select an AI model, and produce high-resolution output — all accelerated by your Vulkan-compatible GPU.

---

✨ Features

Category	Details
AI Upscaling	2×/3×/4× upscaling via Real-ESRGAN ncnn-vulkan with GPU acceleration
Web Dashboard	Modern browser UI for uploading, configuring, and monitoring jobs
Multiple Models	Choose from bundled models (realesrgan-x4plus, realesrgan-x4plus-anime, realesr-animevideov3, etc.)
Custom Model Upload	Upload your own .param / .bin model files through the UI
Frame Preview	Preview a single upscaled frame before committing to a full job
Video Trimming	Trim start/end times before upscaling to process only the segment you need
Post-Processing Filters	Optional sharpening, denoising, and color-correction filters applied after upscaling
Audio & Subtitle Preservation	Original audio tracks and subtitle streams are automatically muxed into the output
Job Queue	Queue multiple jobs and track progress in real time via WebSocket
Webhook Notifications	Configure a webhook URL to receive a callback when a job completes or fails
System Diagnostics	Built-in diagnostics endpoint reports GPU info, Vulkan status, disk space, and dependency versions
Output Gallery	Browse, preview, and download completed videos from the dashboard

---

📋 Requirements

• OS: Linux x86_64
• Python: 3.10+
• FFmpeg / FFprobe: installed and available on $PATH
• GPU: Vulkan-compatible GPU (NVIDIA, AMD, or Intel) with up-to-date drivers

---

🚀 Quick Start

# 1. Clone the repository
git clone <repo-url> video_upscaler
cd video_upscaler

# 2. Run the setup script (creates venv, installs deps, downloads Real-ESRGAN binary & models)
./setup.sh

# 3. Start the server
python start.py

The dashboard will be available at http://localhost:8000 (or your machine's network IP) by default.

---

🖥️ Server Management

python start.py                        # Start on default port 8000 (binds to 0.0.0.0 for LAN access)
python start.py --port 9000             # Start on a custom port
python start.py --host 127.0.0.1        # Bind to loopback only (no LAN access)
python start.py --no-browser            # Don't open browser automatically
python stop.py                          # Stop the server
python restart.py                       # Restart the server
python restart.py --port 9000           # Restart on a custom port

---

🔌 API Endpoints

Method	Endpoint	Description
POST	/api/upload	Upload a video file for processing
POST	/api/upscale/start	Start an upscale job with the given configuration
GET	/api/upscale/status/{job_id}	Get the current status and progress of a job
POST	/api/upscale/cancel/{job_id}	Cancel a running or queued job
POST	/api/preview/generate	Generate an upscaled preview of a single frame
GET	/api/models	List all available upscaling models
POST	/api/models/upload	Upload a custom model (.param + .bin)
GET	/api/outputs	List completed output files
GET	/api/download/{filename}	Download a completed output video
GET	/api/diagnostics	System diagnostics (GPU, Vulkan, disk, dependencies)
WS	/ws/progress/{job_id}	WebSocket stream of real-time job progress updates

---

📁 Project Structure

video_upscaler/
├── app/
│   ├── main.py              # FastAPI application & API routes
│   └── upscaler.py          # Video processing pipeline
├── static/
│   ├── index.html           # Web dashboard
│   ├── styles.css           # UI styles
│   └── app.js               # Frontend logic
├── realesrgan-bin/
│   ├── realesrgan-ncnn-vulkan   # Upscaling binary (x86_64 Linux)
│   └── models/              # AI model files (.param + .bin)
├── uploads/                 # Uploaded video files (gitignored)
├── outputs/                 # Upscaled video files (gitignored)
├── temp/                    # Temporary frame data (gitignored)
├── start.py                 # Start the server
├── stop.py                  # Stop the server
├── restart.py               # Restart the server
├── setup.sh                 # First-time setup script
├── requirements.txt         # Python dependencies
└── README.md

---

🔧 Troubleshooting

Vulkan not detected

Error: vkCreateInstance failed

• Ensure your GPU drivers are up to date.
• Verify Vulkan is working: vulkaninfo | head -20.
• Install the Vulkan loader if missing: sudo apt install libvulkan1 vulkan-tools (Debian/Ubuntu).

Out of VRAM

Error: vkAllocateMemory failed

• Lower the tile size in the upscale settings (e.g., from 0 to 128 or 64).
• Close other GPU-intensive applications.
• Use a model with lower memory requirements (e.g., realesr-animevideov3).

Server won't start

• Check if the port is already in use: ss -tlnp | grep 8000.
• Review the log file: cat server.log.
• Ensure the virtual environment is activated or was created by setup.sh.

FFmpeg errors

• Confirm ffmpeg and ffprobe are installed: ffmpeg -version.
• Make sure the input video is not corrupted: ffprobe input.mp4.
• Check available disk space — upscaling generates large intermediate frame sequences.

---

📄 License

This project uses Real-ESRGAN by xinntao, licensed under the BSD-3-Clause License.