ThorCPY Linux

This is a Linux fork of ThorCPY by the_swest. All credit for the original project goes to theswest. For the Windows version, see the upstream repository.

ThorCPY Linux is a Linux-optimised fork of ThorCPY — a multi-window Scrcpy launcher designed for the AYN Thor handheld.

It launches two scrcpy windows (one per display), supports window docking on X11, and provides wireless ADB connection support. Designed for screensharing, recording or livestreaming.

Main UI	ThorCPY Screenshot

Features

Dual-screen support built for the AYN Thor (Display 0 + Display 4)
X11 Docking — embed both scrcpy windows into a single container window
Wayland Support — floating window mode (docking not possible on Wayland)
Wireless ADB Connection — native in-app overlay, no separate window (Android 11+ pairing supported)
Network Scanner — auto-discover Android devices on your local network
Layout Presets — save and restore screen positions
Screenshot capture — capture both screens into one image
Scale control — adjust scrcpy output resolution in real time
Swap screens — flip which display is top/bottom
Per-display FPS — top display runs at 120 FPS, bottom at 60 FPS
Wireless optimisation — automatically reduces FPS and applies settings when connected over WiFi

Technical features:

Automatic adb/scrcpy installation via package manager (pacman / apt)
Thread-safe window management
Graceful error handling and shutdown
Comprehensive logging with daily rotation

Requirements

System

OS: Linux with X11 (recommended) or Wayland (floating mode)
Python: 3.8–3.13 (3.14 not yet supported — pygame has no wheel for it)
Device: AYN Thor with USB Debugging enabled

System Dependencies

# Arch Linux / Manjaro / CachyOS
sudo pacman -S android-tools scrcpy python-pygame python-xlib

# Debian / Ubuntu
sudo apt install adb scrcpy python3-dev python3-xlib python3-pygame

Note: python3-pygame may not be available in older Debian/Ubuntu releases. In that case install via pip after installing the system deps above:
pip install pygame>=2.6.0

Python Dependencies

pip install -r requirements.txt

requirements.txt installs:

pygame>=2.6.0 — UI rendering
python-xlib>=0.33 — X11 window management (Linux only)

ThorCPY can also attempt to install adb and scrcpy automatically on first launch if they are missing (via pkexec).

Enable USB Debugging

Before connecting your AYN Thor:

On the device go to Settings > About device
Tap Build number seven times to enable Developer Options
Go to Settings > System > Developer Options
Enable USB Debugging

Installation

Option 1: Run from Source (Recommended)

# 1. Clone the repository
git clone https://github.com/DrSkyfaR/ThorCPY-Linux.git
cd ThorCPYLinux

# 2. Install system dependencies (see Requirements above)

# 3. Install Python dependencies
pip install -r requirements.txt

# 4. Run ThorCPY
python3 main.py

Option 2: Build a Standalone Executable

# 1. Install PyInstaller
pip install pyinstaller

# 2. Run the build script
python build.py

# 3. Find your binary in dist/ThorCPY
# The executable must be placed in a folder containing: bin/, config/, logs/

Connecting Your Device

Via USB (Automatic)

Connect your AYN Thor via USB with USB Debugging enabled. ThorCPY detects the device automatically on startup.

Via WiFi (Wireless ADB)

Click the CONNECT button in the control panel to open the wireless connection overlay. The button turns green when a wireless connection is active.

First-time Pairing (Android 11+)

On the device: Developer Options > Wireless debugging > Pair device with pairing code
Note the IP address, pairing port, and 6-digit code shown
In ThorCPY, click CONNECT → switch to the First Time Pairing tab
Enter the IP address, pairing port, and 6-digit code, then click Pair
After pairing, switch to Quick Connect, enter the IP with port 5555, then click Connect

Subsequent Connections

Enable Wireless debugging in Developer Options
Click CONNECT in ThorCPY → Quick Connect tab
Enter the device IP and port 5555, click Connect

Legacy TCP/IP Mode (Android 10 and below)

Connect via USB first
Run: adb tcpip 5555
Disconnect USB, then use Quick Connect in ThorCPY

Usage

The ThorCPY control panel appears on the right side of your screen:

Control	Description
Global Scale	Adjust resolution scale of scrcpy output (requires restart)
Top X / Top Y	Move top screen position
Bottom X / Bottom Y	Move bottom screen position
CONNECT	Open wireless connection overlay (green when connected wirelessly)
DOCK WINDOWS	Embed both windows into a single container (X11 only)
UNDOCK WINDOWS	Separate into independent floating windows
SCREENSHOT	Capture the docked view to clipboard
SAVE	Save current layout as a named preset
LOAD	Apply a saved preset
DEL	Delete a saved preset

Configuration

Layout Presets — `config/layout.json`

{
    "Default": {
        "tx": 0,
        "ty": 0,
        "bx": 251,
        "by": 648,
        "global_scale": 0.6
    },
    "Streaming": {
        "tx": 100,
        "ty": 50,
        "bx": 300,
        "by": 700,
        "global_scale": 0.3
    }
}

General Config — `config/config.json`

{
    "global_scale": 0.6,
    "tx": 0,
    "ty": 0,
    "bx": 251,
    "by": 648,
    "layout_mode": "DUAL",
    "swap_screens": false,
    "wireless_connect_ip": "192.168.1.100",
    "wireless_connect_port": "5555"
}

Logging

Logs are saved to logs/ with daily rotation:

File	Content
`thorcpy_YYYYMMDD.log`	Main application log
`scrcpy_top_YYYYMMDD_HHMMSS.log`	Top window scrcpy output
`scrcpy_bottom_YYYYMMDD_HHMMSS.log`	Bottom window scrcpy output

To increase verbosity, change logging.INFO to logging.DEBUG in main.py.

Troubleshooting

Device Not Found

Ensure USB Debugging is enabled
Try a different USB cable (data cable, not charge-only)
Revoke USB debugging authorizations and reconnect: Settings > System > Developer Options > Revoke USB debugging authorizations
Check if ADB sees the device: adb devices
Restart ADB server: adb kill-server && adb start-server

Scrcpy Not Starting

Confirm scrcpy is installed: which scrcpy
Try running manually: scrcpy -s YOUR_DEVICE_SERIAL --display-id=0
Check logs in logs/ for error details
Ensure your device has display IDs 0 and 4

Windows Won't Dock (X11)

Confirm you are running under X11, not Wayland: echo $XDG_SESSION_TYPE
Wait a few seconds for scrcpy to fully initialise
Toggle Dock / Undock several times
Restart ThorCPY

Running on Wayland

Docking is not supported on Wayland (no window reparenting)
Windows will open as independent floating windows — this is expected behaviour
To use X11, start your session with an X11 display server or use XWayland

Wireless Connection Fails

Ensure both PC and device are on the same WiFi network
Disable any firewall rules blocking port 5555
For Android 11+, use the First Time Pairing flow before attempting Quick Connect
Check that Wireless debugging is enabled on the device (not just USB debugging)

Performance / Stuttering

Over WiFi: ThorCPY automatically uses 120 FPS (top) / 60 FPS (bottom)
Reduce Global Scale in the UI to lower resolution and bandwidth
Use a USB 3.0 port when connecting via cable for best performance
Close other resource-intensive applications
To manually adjust FPS limits, edit DEFAULT_MAX_FPS in src/scrcpy_manager.py

Layout Issues

Delete config/layout.json and config/config.json to reset to defaults
Reload at 0.6 scale, adjust, and save

Project Structure

ThorCPYLinux/
├── main.py                  # Entry point
├── build.py                 # PyInstaller build script
├── requirements.txt         # Python dependencies
├── assets/                  # Icons, fonts, screenshots
├── bin/                     # Local adb/scrcpy binaries (optional)
├── config/                  # Runtime configuration (auto-created)
├── logs/                    # Log files (auto-created)
└── src/
    ├── launcher.py          # Main controller: docking, layout, wireless
    ├── scrcpy_manager.py    # scrcpy process management & ADB
    ├── ui_pygame.py         # Pygame control panel UI + wireless overlay
    ├── presets.py           # Layout preset store
    ├── config.py            # Config manager
    ├── win32_dock.py        # Windows docking (Win32 API)
    ├── win32_darkmode.py    # Windows dark title bar
    └── docking/
        ├── x11.py           # X11 window docking (Linux)
        └── stateless.py     # Wayland / no-op dock manager

Bundled Software

ThorCPY can use locally bundled binaries from the bin/ folder. On Linux, system-installed packages are preferred — the bin/ folder is optional.

scrcpy by Genymobile/Romain Vimont — Apache License 2.0 Source: https://github.com/Genymobile/scrcpy

Licenses

This project is licensed under GNU General Public License v3.0 — see LICENSE
scrcpy — Apache License 2.0
Cal Sans font — SIL Open Font License 1.1 (see assets/fonts/OFL.txt)

Contributing

Contributions are welcome! This is a Linux-specific fork maintained separately.

For Linux-specific bugs or features: open an issue in this repository on GitHub
For general ThorCPY issues (Windows / upstream): see the upstream repository

Acknowledgements

the_swest — Original ThorCPY author
eldermonkey — Project logo
scrcpy by Romain Vimont — the backend that makes this all possible
Cal Sans by Cal.com Inc. — UI typography
Pygame — UI rendering and event handling

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
assets		assets
bin		bin
config		config
logs		logs
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
build.py		build.py
main.py		main.py
requirements.txt		requirements.txt
verify_linux_port.py		verify_linux_port.py

Folders and files

Latest commit

History

Repository files navigation