QtScrcpy: A Qt Front End for scrcpy, With Key Mapping and Group Control

What QtScrcpy Is For, and Who Ends Up Using It

QtScrcpy displays an Android device's screen on a desktop and lets you control it with a mouse and keyboard. The README states it works over USB or over the network and does not require root privileges. It runs on GNU/Linux, Windows and macOS. The stated goals are lightness, 30 to 60 fps, 1920x1080 or above, 35 to 70ms latency, roughly one second to first frame, and non-intrusiveness: nothing is installed on the device. Those numbers come from the project's own description, not from independent measurement, and latency in particular depends on the encoder, the cable and the host GPU. The audience is narrow and specific. It is someone who wants a windowed Android screen on a desktop, wants to drive it with a keyboard, and is willing to enable ADB debugging. The key mapping feature points at a second audience: people playing mobile games who want keyboard and mouse input, which the README addresses directly with default scripts for TikTok and PUBG Mobile. The group control feature, shown in the README as an animated demo, points at a third: anyone operating several phones from one machine.

It Is a Qt Reimplementation of scrcpy, Not a Fork in Name Only

The README is explicit that QtScrcpy is based on Genymobile's scrcpy, and it publishes a comparison table. That table is the most useful document in the repository because it states exactly where the two diverge. The UI layer differs: scrcpy uses SDL, QtScrcpy uses Qt. Video encoding is ffmpeg in both. Video rendering differs: SDL in scrcpy, OpenGL in QtScrcpy. Cross-platform support is self-implemented in scrcpy and provided by Qt in QtScrcpy. The language is C versus C++. The programming style is described as sync versus async. Key mapping is listed as absent in scrcpy and present as custom key mapping in QtScrcpy. The build systems are meson plus gradle for scrcpy and qmake or CMake for QtScrcpy. The README also lists multi-touch support as an addition. This matters for anyone evaluating the project, because it means the device-side protocol work is inherited. The Android server component comes from the scrcpy lineage. What QtScrcpy owns is the desktop client: the Qt window, the OpenGL render path, the asynchronous signal and slot plumbing, the key map engine and the group control logic. If you hit a protocol-level problem, the relevant code may not live in this repository at all.

How Key Mapping Scripts Actually Work

Key mapping is the feature that separates QtScrcpy from a plain screen mirror. The README points to docs/KeyMapDes.md for the script writing rules, which means the mapping format is a text file, not a GUI. The workflow it describes is a fixed sequence. Write a custom script and put it in the keymap directory. Click refresh script to make it appear. Select the script. Connect the phone, start the service, and click apply. Press the tilde key, which the README calls the SwitchKey in the key map script, to toggle into custom mapping mode, and press it again to return to normal mode. That toggle is the part worth understanding before adopting: the mapping is a mode you enter, not a global input remap. For games with vehicle controls, the README notes that moving with STEER_WHEEL keys requires setting the move mode to single rocker mode. The default PUBG Mobile mapping is shown as a screenshot rather than described in text, so the exact binding set is only visible in the image. The README states that scripts for TikTok and some other games ship by default. If you do not want to write the format by hand, the README points to a separate tool by the same author, QuickAssistant, which offers interface-based editing of key mapping scripts. That tool is not part of this repository.

Getting It Running: Prebuilt Archives, AUR, or Your Own Build

The README gives three acquisition paths. On Windows and macOS, prebuilt archives with all dependencies, including ADB, are available from the GitHub Releases page, and a Gitee mirror is listed. On Arch Linux, the README gives the AUR command yay -Syu qtscrcpy and warns that the package may be outdated, naming yochananmarqos as maintainer. For everything else, you build it yourself. The requirements section is short: Android API 21 (Android 5.0) or higher, and ADB debugging enabled on the device, with a link to Google's documentation on enabling it. The build system is the part to read carefully. The comparison table lists qmake or CMake as the build options, and the README does not state which one is preferred or which one is tested on which platform. That ambiguity is a real cost. A C++ Qt project with an OpenGL render path and ffmpeg as a dependency will need matching Qt and ffmpeg versions, and the repository does not spell out a version matrix in the README. The current default branch is dev, while releases are tagged separately, so building from a clone and building from a release tarball are not the same thing.

Group Control and Where the Design Stops

Group control lets you drive all connected phones at once, and the README shows it as a GIF rather than describing the synchronization model. That is a gap. What the README does not say is how input is broadcast, whether devices are addressed individually within a group, or what happens when one device in the group drops off ADB mid-session. None of that is documented in the README, so treat group control as a feature to verify on your own hardware rather than one to plan around. There is a second boundary worth naming. The README devotes a section to the author's other product, QuickMirror, which it describes as a more professional screen casting tool. The listed QuickMirror features include batch screen casting with individual and batch control, group management, WiFi and OTG mirroring, an adb shell shortcut, file transfer and apk installation, and a claim that in OTG mode a single computer can manage 500 or more phones. The README states the free version of QuickMirror casts up to 10 screens. This is a commercial product promoted inside the open source repository, and that shapes what the open source project is likely to receive. Features that overlap with the paid product are the ones least likely to be deepened here.

The Honest Alternative: Upstream scrcpy

The real alternative is scrcpy itself, and the difference is not cosmetic. Upstream scrcpy is the C project QtScrcpy is built on, with an SDL UI, an SDL render path, a self-implemented cross-platform layer, meson plus gradle as the build system, and no custom key mapping. If your need is a fast window showing one phone's screen with mouse and keyboard passthrough, and you are comfortable in a terminal, upstream scrcpy is the smaller dependency and the one whose protocol code is authoritative. QtScrcpy earns its place when you need the things the table marks as absent upstream: a Qt widget you can extend, custom key map scripts, multi-touch, and group control across several devices. The trade is that you take on the Qt and OpenGL stack, the qmake-or-CMake build ambiguity, and a client whose Android-side behavior is inherited from a project with a different release cadence. Choosing between them is a question of whether you want a GUI toolkit you can code against or a command you can script.

Licence, Maintenance and What to Check Before You Commit

QtScrcpy is Apache-2.0, and the repository is not archived, with a last push in August 2026. The release history in the repository shows v4.1.1 and v4.1.0 in August 2026 and v3.3.3 in November 2025, which is a reasonably active cadence over that window. Apache-2.0 is permissive and includes an explicit patent grant, which matters if you redistribute a modified build. It also carries attribution and notice obligations, and it does not grant trademark rights. None of that is legal advice; read the licence text and the NOTICE requirements for your own distribution. Two practical costs stand out. First, the build matrix is undocumented for the self-build path, so budget time for matching Qt and ffmpeg versions against whichever of qmake or CMake you pick. Second, the README's promotion of QuickMirror and of paid video lessons means the open source project and a commercial product share an author and a feature surface. That is not disqualifying, but it is a reason to check whether the specific thing you need is one the author has an incentive to keep in the free build. The concrete next step is to clone the dev branch, build it with one of the two documented systems, and confirm that a key map script you write under keymap/ appears after refresh script and activates on the tilde key.

Editorial conclusion

Adopt QtScrcpy if you need a Qt-based desktop front end for scrcpy with scriptable key mapping and group control, and you are willing to build it with qmake or CMake when the prebuilt archives do not fit. Do not adopt it if you want a maintained library to embed, or if the upstream scrcpy command line already covers your workflow. Before committing, verify three things yourself: that your target devices run Android API 21 or higher with ADB debugging enabled, that a key map script you write actually loads after clicking refresh script and apply, and that the dev branch builds cleanly on your platform, since the README documents qmake and CMake as alternatives rather than naming one supported path.

Official sources

1. barry-ran/QtScrcpy on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases