Skip to content

API Overview

Want to embed upscaling into your own Python applications, scripts and game launchers?

Use the API of the upscaler!

To Be or Not to Be

If you only need to run the upscaler from a terminal, the Command-Line Interface is often simpler.

The API is best when you need programmatic control.

Missing an API feature?

If you need something that isn’t exposed in the API yet (for example, a different window acquisition method, a runtime setting or a new Qt signal) please open an issue and describe your use case.

Components

Classes

Class Description
UpscalerSession Session class that manages the upscaling lifecycle.
WindowInfo Immutable dataclass describing the properties of a X11 window.
Config Dataclass containing all settings for the upscaler.

Modules

Module Description
Window Acquisition Functions for finding, listing, and acquiring target windows.
Exceptions Exceptions raised by the API.

Quick start

Ready? Let's go then!

The simplest way to use the API is to find a window and run an upscaling session inside a with block:

from upscaler import UpscalerSession
from upscaler.acquisition import find_window_by_title

win = find_window_by_title(contains="A Game")
with UpscalerSession(window=win) as session:
    session.run()

This starts the pipeline and enters the Qt event loop. session.run() calls QApplication.exec() and blocks until the session finishes. When the window closes or the session is stopped, the session automatically cleans up its resources.

Use this for simple scripts where no Qt application already exists.

Embedded mode

If your application already has a Qt event loop running, do not call run(). Instead, use start() and close():

from upscaler import UpscalerSession
from upscaler.acquisition import find_window_by_title

win = find_window_by_title(contains="A Game")
session = UpscalerSession(window=win, enable_hotkeys=False)

# Connect signals before starting
session.finished.connect(lambda: session.close())
session.error.connect(print)

session.start()
# The host event loop keeps running, while the session runs in the background

In embedded mode, session.start() uses the existing QApplication, creating the pipeline and returning immediately instead of blocking. Then, your Qt event loop can continue running normally and handle the session's signals.

The session runs in the background and notifies you via Qt signals, that you can connect and handle: finished, error, window_changed, and daemon_match.

Error handling

All API errors derive from UpscalerError. Common ones include WindowNotFound and ConfigError.

Always wrap your calls in a try block when there is a chance of failure:

from upscaler import UpscalerSession
from upscaler.acquisition import find_window_by_title
from upscaler.exceptions import UpscalerError, WindowNotFound

try:
    win = find_window_by_title(contains="A Game")
    with UpscalerSession(window=win) as session:
        session.run()
except WindowNotFound:
    print("Window not found")
except UpscalerError as e:
    print(f"Upscaler error: {e}")