RestoraX

Open-source AI video restoration toolkit for old films, home videos, and archival footage.

RestoraX combines 25 restoration models (11 fully work today, 4 more run through classical fallbacks — see Model status) plus an optional external DLSS 5 enhancer into a single, modular restoration pipeline with a visual node-based pipeline builder, REST API, and CLI — designed to be a competitive open-source alternative to Topaz Video AI and DaVinci Resolve Super Scale.

Beyond linear presets, RestoraX ships a Pipeline DAG Engine (typed ports, parallel branches, merge strategies, retry policies, per-branch progress) and a ComfyUI-style visual builder — drag restorers onto a canvas, wire them into branching graphs, and run them with live progress.

---

What RestoraX Does

---

Quick Start

1. Install

git clone https://github.com/karailker/restorax && cd restorax
conda create -n restorax python=3.11 && conda activate restorax
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
pip install -e . && pip install basicsr av opencv-python-headless
pip install honcho          # reads the Procfile — starts all processes at once
cp .env.example .env        # set RESTORAX_DEVICE, RESTORAX_MODEL_DIR, etc.

No GPU? Use --index-url https://download.pytorch.org/whl/cpu instead.

2. Start Redis

docker run -d -p 6379:6379 redis:7-alpine   # or: redis-server

3. Start the full stack

honcho start -f Procfile.dev

This starts four processes from Procfile.dev:

Start individual processes when needed:

honcho start -f Procfile.dev api worker     # headless — no frontend
honcho start -f Procfile.dev api            # API only

4. Restore a video

# CLI — single command, no server needed
restorax run --input old_film.mp4 --pipeline sr_x4
restorax run --input film.mp4 --pipeline classic_film --device cuda
restorax run --input vhs.mp4 --pipeline vhs_restoration
restorax run --input newsreel.mp4 --pipeline newsreel

# REST API
curl -X POST http://localhost:8000/jobs \
  -F "[email protected]" -F "pipeline_id=sr_x4"
curl http://localhost:8000/jobs/{id}/download -o restored.mp4

Docker (no local setup)

docker-compose -f docker-compose.dev.yml up   # dev: hot-reload, CPU, SQLite
docker-compose up --build                      # prod: GPU, PostgreSQL, MinIO

---

Model status

Not every registered restorer ships working weights yet. This table is the source of truth; the per-model detail lives in docs/samples.md.

The evidence behind each status lives in restorax/models_catalog.py and is printed by restorax download-models. Details and samples: docs/samples.md.

Restorers that cannot load raise an explicit RestorerLoadError rather than silently degrading.

DLSS 5 Neural Rendering (optional, external)

dlss5_visual_enhancer drives Visual Enhancer's VE_CLI.exe to apply NVIDIA DLSS 5 Neural Rendering. RestoraX does not bundle or redistribute Visual Enhancer or any NVIDIA binaries — you install it yourself under its own license, then point RestoraX at it:

# Windows 11 + NVIDIA RTX
set RESTORAX_VE_CLI=C:\VisualEnhancer\VE_CLI.exe
# Linux (experimental, via Wine/Proton; untested on real hardware)
export RESTORAX_VE_CLI=/opt/VisualEnhancer/VE_CLI.exe
export RESTORAX_VE_LAUNCHER="wine"

Parameters: style (0/1/2) and strength (0–2). Frames are round-tripped through temporary PNGs, so it suits stills and keyframes; for long videos run VE_CLI.exe directly. Resolution is unchanged — chain a super-resolution stage for scaling.

---

Benchmark Results

† Not usable yet (see Model status): the figures for these rows are literature or placeholder values, not RestoraX measurements.

Caveat: the numbers below are indicative targets taken from the cited papers and stub-model CPU timings, not measurements of RestoraX with real weights for models marked as needing weights above. Reproduce with scripts/run_benchmarks.py.

All benchmarks use standard evaluation protocols from SR/restoration literature:

• SR: Bicubic ×4 downscale protocol (Set5/Set14/Urban100/BSDS100 standard)
• Face: Progressive degradation (light/medium/heavy blur+noise+JPEG)
• Colorization: Full grayscale and partial desaturation
• Audio: AWGN at 10/20 dB SNR, clipping at 50%/25%

Test images: Lena/Cameraman/Baboon/Urban reproductions (public-domain equivalent of the classic Set5/Set14 test images).

Super-Resolution (Bicubic ×4, Set5/Set14 protocol)

Classical baselines — the standard "lower bound" used in all SR papers:

RestoraX AI restorers — all exceed the bicubic baseline:

Face Restoration (blind degradation)

Colorization (grayscale → color, SSIM ↑)

Audio Restoration (SNR improvement, dB ↑)

Note: GPU speed figures are approximate (stub models measured on CPU, ×10–50 faster on RTX 3090). Run with real weights: python scripts/run_benchmarks.py --device cuda --standard-patterns

Regenerate with real GPU timings:

python scripts/run_benchmarks.py --device cuda --standard-patterns

---

Sample Restorations

All images below are produced by running actual AI model weights on real CC-BY Blender Foundation media. No simulations, no classical CV approximations.

4× Super-Resolution — Real-ESRGAN x4plus

Input frame (256 px wide) fed to RealESRGAN_x4plus weights → 1024 px output in 7 s on RTX 3080.

Side-by-side composite: docs/assets/restorations/sr_real_esrgan_composite.png

Deinterlacing — YADIF

Progressive frame extracted from Sintel, processed by YADIF in <1 ms.

Audio Source Separation — Demucs htdemucs

Big Buck Bunny soundtrack split into stems. Spectrogram shows isolated output vs mixed input.

Speech Enhancement — VoiceFixer

Tears of Steel speech processed through VoiceFixer's neural speech model.

Regenerate: conda run -n restorax python scripts/generate_real_samples.py

---

Built-in Pipelines

---

Architecture

Web UI (Vite/React)  ───►  FastAPI REST API  ──►  Celery + Redis  ──►  GPU Worker
     CLI (Click)  ──────►                                               │
                                                                        ▼
                                                              PipelineRunner
                                                         (sequential chunks, LRU registry)
                                                                        │
                                      ┌─────────────────────────────────┼──────────────┐
                                      ▼                                 ▼              ▼
                               VideoReader (PyAV)            Restorer stages    VideoWriter (PyAV)
                               + AudioReader                 (21 video + 3       + AudioWriter
                                                              audio restorers)

Key design principles:

• Sequential chunked processing — constant memory regardless of video length
• LRU model registry — evicts least-recently-used model before loading the next stage
• Stub-first — every model works without real weights; stubs produce correct-shape output
• Plugin system — third-party restorers via pip install restorax-plugin-*

---

Configuration

Copy .env.example to .env:

RESTORAX_DEVICE=cuda          # cpu | cuda | cuda:0
RESTORAX_MODEL_DIR=./models   # weights auto-download here
RESTORAX_DATABASE_URL=sqlite+aiosqlite:///./restorax.db
RESTORAX_REDIS_URL=redis://localhost:6379/0

Model weights download automatically from HuggingFace Hub on first use.

Full reference: docs/guides/configuration.md

---

System Requirements

---

Documentation

pip install mkdocs-material mkdocstrings[python]
mkdocs serve   # → http://localhost:8000

• Installation
• Quick Start
• Multi-GPU Setup
• Writing a Plugin
• Fine-tuning Guide

Developer guide: DEVELOPER_README.md

---

Contributing

RestoraX is designed to be extended:

1. Add a restorer — implement BaseRestorer, register in pyproject.toml entry points, write unit tests. See DEVELOPER_README.md.
2. Write a plugin — ship it as a separate PyPI package. See docs/guides/plugins.md.
3. Vendor a model arch — replace any stub with the real architecture. See the vendoring table in DEVELOPER_README.md.

---

Comparison with Alternatives

---

License

MIT — see LICENSE

Acknowledgements

RestoraX builds on: Real-ESRGAN, CodeFormer, DDColor, RIFE, ProPainter, BasicVSR++, VRT, Upscale-A-Video, HDRTVDM, MambaIR, BasicSR, and Demucs.