Initial commit of video upscaler

2026-06-23 15:48:14 -04:00
commit 79d67ea6a5
27 changed files with 6779 additions and 0 deletions
@@ -0,0 +1,150 @@
+# 🎬 AI Video Upscaler
+
+A web-based video upscaling application powered by [Real-ESRGAN ncnn-vulkan](https://github.com/xinntao/Real-ESRGAN). 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
+
+```bash
+# 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
+
+```bash
+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](https://github.com/xinntao/Real-ESRGAN) by [xinntao](https://github.com/xinntao), licensed under the [BSD-3-Clause License](https://github.com/xinntao/Real-ESRGAN/blob/master/LICENSE).