QtScrcpy: a Qt desktop front end for scrcpy with custom key mapping

What QtScrcpy does that a plain ADB session does not

The problem is mundane and constant: you have an Android device on your desk and you want its screen on your monitor, with your mouse and keyboard driving it, without unlocking developer builds or installing an agent on the phone. ADB alone gives you a shell and a file channel, not a picture. QtScrcpy fills that gap. It states that it displays and controls Android devices over USB or the network, requires no root privileges, and installs nothing on the device. That last property matters more than it sounds: nothing to uninstall, nothing that survives a factory reset, nothing the phone's security model has to be talked into.

The intended audience is not a CI pipeline. It is a person at a desk: someone testing an app on a physical phone, someone playing a mobile game with a keyboard, someone running a small rack of test devices and wanting all of them visible at once. The README is explicit about the trade-offs it optimises for, listing lightness, 30 to 60 fps, 1920x1080 or above, latency in the 35 to 70 ms range, and roughly one second to first frame. Those are the author's stated targets, not measurements I can confirm.

The repository also points at two commercial products by the same author, QuickMirror and QuickAssistant, described in the README as more professional and aimed at batch screen casting, group management and interface-based key mapping editing. That is worth knowing before you invest in QtScrcpy: the free project is the base, and parts of the ecosystem around it are paid.

The scrcpy lineage and how the Qt rewrite differs

QtScrcpy is built on Genymobile's scrcpy, and the README thanks that project directly. The comparison table in the README is the clearest statement of what changed. scrcpy uses SDL for its UI and for video rendering; QtScrcpy uses Qt for the UI and OpenGL for rendering. Both use ffmpeg for video encoding. scrcpy is written in C and is synchronous in style; QtScrcpy is C++ and asynchronous. scrcpy implements cross-platform support itself, while QtScrcpy takes it from Qt. Build systems differ too: scrcpy uses meson plus gradle, QtScrcpy uses qmake or CMake.

The README's own reasoning for the rewrite is that Qt makes a custom GUI easy, that Qt's signal and slot mechanism improves performance through asynchronous programming, that the codebase is easy to learn, and that multi-touch support was added. The keymap row is the one that matters most in practice: the README lists "no custom keymap" for scrcpy and "support custom keymap" for QtScrcpy. Everything else is an implementation preference; the key mapping is a capability difference.

That said, the async claim deserves scepticism. Qt's event loop and signal-slot dispatch do not by themselves make video decoding faster; the rendering path and the decoder are what dominate. Treat the performance row as a design rationale rather than a benchmark.

Installing QtScrcpy on Windows, macOS and Linux

The README directs most users to prebuilt archives. On Windows and macOS it states that archives with all dependencies, including ADB, are available at Releases, which means you do not need a separate ADB install. On Arch Linux the README gives an AUR package, with the caveat that it may be outdated. The AUR command as written in the README is:

yay -Syu qtscrcpy

After that, the binary is on your PATH. Note the README's own warning that the AUR package may lag behind the releases page; if you want the newest build, the prebuilt archives are the safer source.

If no prebuilt archive suits your platform, you build from source. The repository root contains a CMakeLists.txt, and the README says the build uses qmake or CMake, so either path is supported. The top-level layout also shows a ci/ directory and a QtScrcpy/ subdirectory holding the application source, with config/ and keymap/ alongside it. A CMake configure step from the repository root is the natural starting point:

cmake -S . -B build
cmake --build build

Before any of this, two prerequisites apply to every platform. The README states Android API 21 (Android 5.0) or higher, and ADB debugging enabled on the device. If the device does not appear, that is the first thing to check, not the build.

Once the app is running, the flow is: connect the phone, start the service, and the device screen appears in a window. To use a mapping script, the README gives a specific sequence. Write or choose a script, place custom scripts in the keymap directory, click refresh script, select it, connect and start the service, click apply, then press the tilde key to switch into custom mapping mode and again to return to normal mode. For games such as PUBG Mobile, the README notes that steering with the STEER_WHEEL keys requires setting the move mode to single rocker mode.

Writing a key mapping script and where the documentation thins out

The key mapping system is the reason many people choose QtScrcpy over scrcpy, and the README is honest that it is a scripting interface rather than a settings panel. The rule reference is a separate file, docs/KeyMapDes.md, and the README links to it rather than reproducing it. Default scripts for TikTok and some games ship with the project, and the PUBG Mobile default mapping is shown as a screenshot in the README.

The workflow for a custom script, as listed in the README, is: put the script in the keymap directory, click refresh script to make it appear, select it, connect the phone, start the service, click apply, then toggle with the tilde key. The tilde is described as the SwitchKey in the key map script, so it is a convention of the scripts rather than a hardcoded global shortcut. That distinction is easy to miss and will confuse anyone who assumes the toggle is fixed.

What the README does not cover: there is no documented error surface for a malformed script. It does not say what happens if a script references a key that does not exist, whether the failure is silent, whether the app logs it, or whether the mapping simply does nothing until you toggle away and back. If you plan to write scripts by hand, read docs/KeyMapDes.md before you start and budget time for trial and error, because the README will not tell you why a script did not take effect. The author's QuickAssistant is offered as the alternative for people who would rather edit mappings through a GUI, which is an implicit acknowledgement that hand-writing them is not for everyone.

Group control, and what the README does not promise

QtScrcpy supports group control, described in the README as the ability to control all your phones at the same time, with an animated demo in the docs/image directory. This is the feature that pushes the tool from a single-device convenience toward a small test-lab utility. If you have five phones on a hub and want one click to reach all of them, that is the use case.

The README stops short of specifying the mechanics. It does not state a device limit for group control, does not describe how devices are selected or excluded from a group, and does not say whether group control requires identical screen resolutions across devices. Those are the questions you would ask before wiring it into a workflow, and the README is silent on all of them. The commercial QuickMirror page makes a much larger claim, that a single computer can manage over 500 phones in OTG mirroring mode with low resolution and smoothness settings, but that is a different product with a different feature set and should not be read as a QtScrcpy capability.

A practical constraint the README does imply: everything runs over ADB, so group control inherits ADB's behaviour. Whether a device stays connected across a sleep cycle or a USB re-enumeration is an ADB question, not a QtScrcpy one, and the README does not address reconnection.

When scrcpy is the better choice

The honest alternative is the upstream project. scrcpy is what QtScrcpy is built on, and the README's comparison table is effectively a list of reasons to pick one or the other. If you want a command-line tool you can call from a script, pipe into a recording pipeline, or run on a headless machine over SSH, scrcpy is the fit and QtScrcpy is not: QtScrcpy's whole value proposition is a Qt GUI, and a GUI is dead weight in an automated context. scrcpy also has no custom key mapping, so if you need keyboard control of a game, the comparison flips.

The build difference matters for contributors rather than users. scrcpy builds with meson and gradle; QtScrcpy builds with qmake or CMake. If your team already has Qt in its toolchain, QtScrcpy slots in more naturally. If not, you are adding a large dependency tree to get a window around a tool that already works from a terminal.

One more consideration: QtScrcpy's README points to paid courses, a paid tool and Telegram groups for support. scrcpy's support model is a conventional open source issue tracker. Neither is wrong, but if your organisation requires a documented support path, the QtScrcpy README does not offer one beyond community channels.

Licence, maintenance and the cost of upgrading

QtScrcpy is Apache-2.0, and the repository carries a LICENSE file at the root. That is a permissive licence, which matters if you intend to embed the tool or ship a modified build. The README does not discuss redistribution obligations, and I am not going to give legal advice; if you plan to redistribute a modified QtScrcpy, read the LICENSE file and the Apache-2.0 terms yourself, and note that the project depends on scrcpy and ffmpeg, whose licences are separate questions the README does not address.

On maintenance: the repository is not archived, and the last push was on 2026-08-20. Releases show v4.1.1 on 2026-08-12 and v4.1.0 on 2026-08-09, with a gap back to v3.3.3 on 2025-11-06. That pattern, two releases days apart followed by a longer quiet period, is worth noting when you plan upgrades. The version jump from 3.3.3 to 4.1.0 suggests a significant change between those lines, and the README does not document a migration path or a rollback procedure for users moving across it.

Upgrade cost is mostly about the build. If you use prebuilt archives, upgrading is a download and replace. If you build from source, you carry the Qt, ffmpeg and CMake toolchain forward with each release, and a major version bump is a reasonable moment to expect build changes. The README does not publish a compatibility matrix for Qt versions, so pin your toolchain and test before replacing a working build.

Editorial conclusion

Adopt QtScrcpy if you want a GUI over scrcpy, need keyboard and mouse mapping for games on Windows, macOS or Linux, or want to drive several phones from one window. Do not adopt it if you need a headless or scriptable mirroring tool, or if you are already comfortable with scrcpy's command line and do not need key maps; the Qt layer adds a GUI you would not use. Before committing, verify that ADB debugging is enabled on your device and that your Android version is API 21 or higher, check whether the prebuilt release for your platform is current or whether you need to build from source, and read docs/KeyMapDes.md to confirm the mapping syntax covers the gestures your use case needs.

Frequently asked questions

Official sources

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