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.

README.md Unescape Escape

🎬 AI Video Upscaler