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

Now with full XWayland support – works seamlessly under Wayland compositors!

• AI‑Powered Upscaling – Uses the CuNNy (Convolutional upscaling Neural Network) models, trained specifically for high‑quality 2x 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.
• Flexible Output Geometry – Control the overlay size, scaling mode, offset and borders.
• Input Forwarding – Click, move, and drag on the upscaled image as if interacting directly with the original window.
• Hardware Accelerated – Vulkan compute (Compushady) works on NVIDIA, AMD, and Intel GPUs.
• XWayland Compatible – Runs under Wayland compositors by automatically forcing X11 platform for Qt.
• Low Overhead – Final scaling pass uses hardware Lanczos2 filtering.

• GNU/Linux (X11 or Wayland with XWayland)
• Vulkan-capable GPU (NVIDIA, AMD, Intel)
• Vulkan drivers (libvulkan-dev)
• X11 development libraries (libx11-dev)
• Python 3.8 – 3.13

Python 3.14 compatibility: Currently not supported due to a low‑level Vulkan backend issue. Please use a Python ≤ 3.13 virtual environment if you have Python 3.14 installed. See issue #1 for details.

sudo apt update
sudo apt install libvulkan-dev libx11-dev

sudo dnf install vulkan-loader-devel libX11-devel

sudo pacman -S vulkan-devel libx11

sudo zypper install vulkan-devel libX11-devel

sudo apk add vulkan-headers libx11-dev

pipx install linux-rt-upscaler

pip install linux-rt-upscaler

# Install additional system dependencies for C compilation
sudo apt install gcc make

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

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

After installation, the upscale command will be available globally:

# Upscale the currently active window
upscale

# Interactively select from visible windows
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

# Perform 4x upscaling (two 2x passes)
upscale -2

# Set a custom overlay geometry (50% size, fitted)
upscale -o 50%

# Crop 100 pixels from top and left, then upscale
upscale --crop-top 100 --crop-left 100

# Shift the overlay 100 pixels right and 50 down
upscale --offset-x 100 --offset-y 50

For a full list of options and examples:

upscale --help

• Exit: Ctrl+C in the terminal.

You can define named configuration profiles in your YAML config file. Profiles let you quickly switch settings for different games or applications without typing long command lines each time.

Create a config file (e.g., ~/.config/linux-rt-upscaler/config.yaml) and add a top‑level profiles key. Each profile is a dictionary with an optional match section and an options section.

If no profile is selected manually, the program checks all profiles that have a match section against the title of the target window. If a profile matches (any match criterion is sufficient), its options are applied automatically.

# General defaults (lowest priority)
model: fast
select: false

profiles:
  game:
    match:
      title: "Danganronpa"      # Exact match (case-insensitive)
      title_contains: "ronp"    # Or substring match
      title_regex: "Dangan.*"   # Or regular expression
    options:
      model: 4x24
      double_upscale: true

A more detailed example is included here.

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 2x (or 4x) 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.

• Standalone GUI application – Create a windowed app interface for easier management.
• Addition of more models – Parse and include other models and shaders.
• Native Wayland support – Support pure Wayland windows without XWayland.

Some applications do not receive synthetic mouse events (clicks, motion, wheel) forwarded by the overlay. This has been observed with:

• Wine‑based games (GE-Proton10 seems to work).
• Certain native applications like Firefox.

The upscaler forwards mouse events using XSendEvent, which only delivers events to windows that have explicitly selected the corresponding event mask (e.g., ButtonPressMask). Some applications either do not request these masks or filter out synthetic events.

For more details, see issue #7.

While real-time upscaling tools like Magpie and Lossless Scaling remain Windows-exclusive, projects such as 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, an experience similar to Gamescope that applies intelligent upscaling (similar to Anime4K) to any application.

This project stands on the shoulders of several open‑source works:

• L65536 – For the original RealTimeSuperResolutionScreenUpscalerforLinux, which demonstrated the feasibility of real‑time CuNNy upscaling on Linux. This project extends that foundation with full‑screen scaling, accurate input forwarding, and support for all CuNNy NVL models and GPU vendors.
• funnyplanter – For CuNNy, the neural network upscaling models, especially the Magpie NVL variants trained for visual novel content.
• Compushady – Python library for GPU compute (Vulkan backend).
• PySide6 – Qt bindings used for the overlay window.
• python‑xlib – X11 client library for window management and input forwarding.
• pyewmh – Query and control of window manager.
• psutil – Library for retrieving information on running processes.