Metadata-Version: 2.4
Name: linux-rt-upscaler
Version: 0.1.7
Summary: Real-time AI upscaler for any Linux window using CuNNy
Author-email: Mauricio Valentín Barón Salinas <baronsmv@gmail.com>
License: GPL3.0
Project-URL: Homepage, https://github.com/baronsmv/linux-rt-upscaler
Project-URL: Repository, https://github.com/baronsmv/linux-rt-upscaler.git
Project-URL: BugTracker, https://github.com/baronsmv/linux-rt-upscaler/issues
Keywords: upscaler,ai,cunny,linux,x11,vulkan
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics :: Capture
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: compushady
Requires-Dist: ewmh
Requires-Dist: psutil
Requires-Dist: pyside6
Requires-Dist: pyyaml
Requires-Dist: numpy
Requires-Dist: xlib
Dynamic: license-file

# Real‑Time Upscaler for Linux

[![PyPI version](https://img.shields.io/pypi/v/linux-rt-upscaler.svg)](https://pypi.org/project/linux-rt-upscaler/)
[![Python versions](https://img.shields.io/pypi/pyversions/linux-rt-upscaler.svg)](https://pypi.org/project/linux-rt-upscaler/)
[![License: GPLv3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

A real‑time AI upscaler for any application window on GNU/Linux. It uses [CuNNy](https://github.com/funnyplanter/CuNNy) neural networks to perform 2× (or 4×) upscaling, then scales the result to full screen while preserving aspect ratio. Mouse clicks and motion are automatically forwarded to the original window.

## Results at 400% magnification

![](./docs/comparisons/gurikaji/w40-60_h20-50_4x_comparison.png)

![](./docs/comparisons/fatamoru/w30-50_h10-50_4x_comparison.png)

![](./docs/comparisons/konosora/w10-30_h20-50_4x_comparison.png)

![](./docs/comparisons/diagram/w40-70_h40-90_4x_comparison.png)

## Based on

Based on [RealTimeSuperResolutionScreenUpscalerforLinux](https://github.com/L65536/RealTimeSuperResolutionScreenUpscalerforLinux) by [L65536](https://github.com/L65536) (specifically its [v07linux](https://github.com/L65536/RealTimeSuperResolutionScreenUpscalerforLinux/tree/main/v07linux)), with the following differences:

- **Full‑screen scaling** – The upscaled image now fills the monitor, applying a second scaling layer while preserving aspect ratio.
- **Click/motion forwarding** – Mouse clicks and motion are forwarded to the original window with proper coordinate transformation. This can be deactivated with the `-d` option.
- **Support all CuNNy NVL models** – All NVL models have been translated to work in Compushady.

## Features

- **AI‑Powered Upscaling** – Uses the CuNNy (Convolutional upscaling Neural Network) models, trained specifically for high‑quality 2× upscaling of visual novels and illustrations.
- **Complete Model Selection** – Choose from 9 variants, offering a range of quality/performance trade‑offs:
  - `8x32` – Highest quality, slowest.
  - `4x32`
  - `4x24`
  - `4x16`
  - `4x12`
  - `3x12`
  - `fast` – Default. Recommended for slow machines.
  - `faster`
  - `veryfast` – Fastest option, lowest quality.
- **Attach to Any Window** – Either grab the currently active window, select from visible windows or launch a new program and capture its window automatically.
- **Full‑Screen Output** – The upscaled image is displayed in a transparent overlay that covers your entire monitor, scaled to fill the screen while preserving aspect ratio.
- **Input Forwarding** – Click, move, and drag on the upscaled image as if you were interacting directly with the original window.
- **Hardware Accelerated** – GPU compute via Compushady (Vulkan) works on NVIDIA, AMD, and Intel GPUs.
- **Low Overhead** – Minimal CPU/GPU usage; the final scaling pass uses hardware Lanczos2 filtering.

## Requirements

- GNU/Linux with X11 (Wayland is **not** supported currently)
- Vulkan-capable GPU from any vendor (NVIDIA, AMD, Intel)
- Vulkan drivers (`libvulkan-dev` on Debian/Ubuntu)
- X11 development libraries (`libx11-dev`)
- Python 3.8 or newer

## Installation

### Option 1: Install from PyPI (Recommended)

```bash
# Install system dependencies (Debian/Ubuntu)
sudo apt install libvulkan-dev libx11-dev

# Install with pipx (recommended)
pipx install linux-rt-upscaler

# Or with regular pip
pip install linux-rt-upscaler
```

### Option 2: Install from source

```bash
# Clone the repository
git clone https://github.com/baronsmv/linux-rt-upscaler.git
cd linux-rt-upscaler

# Install system dependencies (Debian/Ubuntu)
sudo apt install libvulkan-dev libx11-dev

# Install Python packages
pip install -r requirements.txt

# Install the package in development mode
pip install -e .
```

## Usage

After installation, the `upscale` command will be available globally:

```bash
# Upscale the currently active window
upscale

# Interactively select from visible windows at startup
upscale -s

# Run a command and upscale its window
upscale <command>

# Choose a specific model (examples)
upscale -m 8x32      # Highest quality, slowest
upscale -m 4x24      # A balanced option
upscale -m veryfast  # Maximum performance

# Disable mouse‑click forwarding (also enables dimming/click‑through)
upscale -d

# Perform two 2× passes (total 4×) (Experimental)
upscale -2

# Show help and other options
upscale -h
```

### Controls

- **Exit**: Press `Ctrl+C` in the terminal where the upscaler is running.
- **Dimming/Click‑through** (only when `-d` is used):
  - The overlay becomes semi‑transparent (20% opacity) when the mouse leaves the source window.
  - Clicks then pass through to whatever window is underneath (e.g., your desktop or other applications).

## Future Plans

- [ ] **XWayland support** – Upscale X11 windows from a Wayland environment
- [ ] **Option to force screen aspect ratio**
- [ ] **Standalone GUI application** – Create a windowed app interface for easier management of the upscaler
- [ ] **Addition of more models** – Parse and include other models and shaders

## How It Works

1. **Window Selection** – Uses X11 to find the target window by PID or WM_CLASS.
2. **Capture** – Grabs the window's pixels using a fast custom C library.
3. **AI Upscaling** – CuNNy compute shaders (written in HLSL, compiled via Compushady) produce a 2× larger image .
4. **Aspect‑Preserving Scaling** – A lightweight Lanczos2 compute shader scales the upscaled image to fill the monitor, adding black bars to maintain the original aspect ratio.
5. **Display** – The result is rendered in a transparent overlay window that bypasses the window manager (so it always stays on top).
6. **Input Forwarding** – Mouse events are transformed using the scaling ratios and sent to the original window via `XSendEvent`.

## Motivation

While real-time upscaling tools like [Magpie](https://github.com/Blinue/Magpie) and [Lossless Scaling](https://losslessscaling.com/) remain Windows-exclusive, projects such as [lsfg-vk](https://github.com/PancakeTAS/lsfg-vk) are successfully bringing their **frame generation** capabilities to Linux. This project tackles the other half of the equation: **AI-powered upscaling** to deliver a native solution Linux has been missing, a fullscreen [Gamescope](https://github.com/ValveSoftware/gamescope)-like experience that applies intelligent upscaling (similar to [Anime4K](https://github.com/bloc97/Anime4K)) to any application.

## Acknowledgments

- **[L65536](https://github.com/L65536)** – For the original [RealTimeSuperResolutionScreenUpscalerforLinux](https://github.com/L65536/RealTimeSuperResolutionScreenUpscalerforLinux) project, which provided the foundational scripts and CuNNy integration 
- **[funnyplanter](https://github.com/funnyplanter)** – For [CuNNy](https://github.com/funnyplanter/CuNNy), the neural network upscaling models, especially the Magpie NVL variants trained for visual novel content 
- **[Compushady](https://github.com/rdeioris/compushady)** – Python library for GPU compute (Vulkan backend)
- **[PySide6](https://pypi.org/project/PySide6/)** – Qt bindings used for the overlay window
- **[python‑xlib](https://github.com/python-xlib/python-xlib)** – X11 client library for window management and input forwarding
- **[pyewmh](https://github.com/parkouss/pyewmh)** – Query and control of window manager
- **[psutil](https://github.com/giampaolo/psutil)** – Library for retrieving information on running processes
