video_upscaler/README.md

# 🎬 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).