ws-scrcpy: a browser front end for scrcpy, and what it costs to run one
Web client prototype for scrcpy.
At a glance
- What is it?
- ws-scrcpy turns a Node.js server and a modified scrcpy fork into a WebSocket screen mirroring and control stack for Android, with iOS support that depends on Appium and WebDriverAgent. The Android path is the mature one; the iOS path is experimental and not built by default.
- Who is it for?
- Adopt ws-scrcpy when you need Android mirroring and control inside a browser and can accept a Node.js process holding adb, plus a modified scrcpy fork on the device. Do not adopt it for iOS in production: the README calls that path experimental and it is not built by default, and the MJPEG server is marked temporarily suspended.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 6 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.
Star history
- NetrisTV/ws-scrcpy2,623 ★ · +49
| Repository | 2026-09-30 | 2026-11-21 |
|---|---|---|
| NetrisTV/ws-scrcpy | 2.6k | 2.6k |
49 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The gap ws-scrcpy fills between adb and a browser tab
scrcpy itself is a desktop program. You plug in a phone, run the binary, and a native window appears. That model breaks down when the machine with the USB cable is not the machine you are sitting at, or when the people who need to look at the screen cannot install desktop software. ws-scrcpy moves the rendering and the input handling into the browser and keeps the device connection on a server process.
The audience is narrow but real: QA engineers driving a rack of test devices, support staff who need to see what a user sees, and developers who want a shell and a file browser next to the mirrored screen without switching tools. The README frames it plainly as a "Web client for Genymobile/scrcpy and more", and the "more" is the part that matters in practice: remote shell, file listing with drag and drop upload, APK push, clipboard copy in both directions, and DevTools access for WebView debugging.
It is not a general remote desktop product. Everything it does runs through adb, so the device must have adb debugging enabled, must be Android 5.0 (API 21) or newer, and on some hardware needs an extra developer option before keyboard and mouse control works.
How the video path works: a scrcpy fork, NALU, and four decoders
The architecture is a server that speaks WebSocket to the browser and adb to the device. The README states that a modified version of Genymobile/scrcpy is used to stream H264 video. That fork is the piece that makes the whole thing possible: stock scrcpy pushes frames to a local display, while this variant hands the encoded stream to the Node.js process, which relays it over WebSocket.
On the browser side the NALU stream has to become something a video element can play, and ws-scrcpy ships four answers. The Mse Player builds mp4 containers from the NALU stream and feeds them to MediaSource, relying on the browser's `video/mp4; codecs="avc1.42E01E"` support; the README notes that in theory this can use hardware acceleration. Broadway and TinyH264 are software decoders compiled to WebAssembly, with TinyH264 described as a slightly updated version of Broadway; both want WebAssembly and preferably WebGL. The WebCodecs Player delegates to the browser's built-in media decoder and, per the README, is available only in Chromium and derivatives at the moment.
That spread is a compatibility strategy, not redundancy. A browser without Media Source Extensions falls back to a wasm decoder; a Chromium browser can take the WebCodecs path. The cost is that the operator has to know which decoder a given browser will pick, because the failure modes differ: a wasm decoder burns CPU on the client, while the MSE path depends on codec support the browser may not advertise.
Installing ws-scrcpy and getting a first device on screen
The README lists the prerequisites before any command: Node.js v10 or newer, node-gyp with its build tools, and an `adb` executable available in the PATH environment variable. The build tools requirement is not decorative. The dependency list includes `node-pty` and `ios-device-lib`, both native modules, so a machine without a compiler will fail during install rather than at runtime.
The documented sequence clones the repository, optionally checks out a release tag, installs, and starts. The comment in the README tells you to list tags and switch to one for a stable version, which is worth doing because the package version on the default branch reads `0.9.0-dev`.
git clone https://github.com/NetrisTV/ws-scrcpy.git
cd ws-scrcpy
# For stable version find latest tag and switch to it:
# git tag -l
# git checkout vX.Y.Z
npm install
npm startThe `start` script is `npm run dist && cd dist && npm start`, so the first run builds the webpack bundle and then launches the server from the `dist` directory. A successful start leaves a server listening and a page you open in the browser; the device list comes from adb, so a phone that does not appear here is an adb problem, not a ws-scrcpy problem.
If you need to change the build, the repository carries `build.config.override.json` at the top level and a `config.example.yaml` for runtime configuration. The iOS-only flag `USE_WDA_MJPEG_SERVER` is described as a build configuration setting, which is why the README points at a custom build rather than a runtime toggle.
One install-time detail is easy to miss: `npm install` triggers a `postinstall` script, `node scripts/setup-appium.js`. The README explains that ws-scrcpy bundles Appium as a dependency and that the postinstall step pins the XCUITest driver into a project-local `.appium-home`. Even if you only care about Android, that step runs.
The iOS path is experimental, and the README says so twice
iOS support is the clearest limitation in the project. The README labels it an experimental feature and states it is not built by default. Screen casting requires `ws-qvh` to be available in PATH, and the README gives three conditions for a stable QuickTime-over-USB stream: set the device's Auto-Lock to Never because a locked screen stops the stream, connect the iPhone directly without a USB hub, and do not run a standalone `ws-qvh` or `qvh` capture against the same device while ws-scrcpy is streaming, since only one process may hold a device.
The MJPEG server, an alternative streaming route that avoids extra software at the cost of encoding every frame as a JPEG, is marked temporarily suspended. The README explains that after the migration to a standalone Appium the WDA-MJPEG video path is not wired up and is planned to be restored in a follow-up. Anyone reading an older tutorial that enables `USE_WDA_MJPEG_SERVER` should know that the video side of it is not currently connected.
Control on iOS runs through appium/WebDriverAgent over the W3C WebDriver protocol. ws-scrcpy spawns Appium as a child process on startup and forwards commands over HTTP, so no global Appium installation is needed. Supported actions are listed as simple touch, scroll or swipe, and a home button click: a much smaller surface than the Android touch, multi-touch, keyboard, scroll and clipboard set.
The setup burden is real. WebDriverAgent has to be built, signed and trusted on the device once, by opening `WebDriverAgent.xcodeproj` under `.appium-home/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent/`, selecting the `WebDriverAgentRunner` scheme, setting a Team and a unique Bundle Identifier, and running it. The README warns that the first control action can take a couple of minutes while Appium builds and launches WDA, and that a free Apple developer account's provisioning expires every 7 days, so you re-sign weekly. It also notes that `xcodebuild failed with code 65` almost always means signing or launching failed on the device rather than a build error in ws-scrcpy.
ws-scrcpy against plain scrcpy and against Android Studio
The honest alternative for a single developer with a phone on the desk is scrcpy itself. It has no server, no browser, no Node.js, and no WebSocket hop; you run one binary and get a native window with lower latency and fewer moving parts. ws-scrcpy only wins when the browser is the point: multiple viewers, a machine that cannot run desktop software, or a workflow that already lives in a tab.
Against Android Studio's device mirroring, the difference is scope rather than quality. Studio is an IDE feature and assumes the IDE. ws-scrcpy is a standalone server that exposes a shell, a file browser with upload and download, and a DevTools route for WebView debugging, and it does not require a project to be open. The trade is that ws-scrcpy has no test runner, no layout inspector and no logcat UI.
There is also a practical difference in how the stream reaches the client. scrcpy sends video to a local display through its own protocol; ws-scrcpy relays H264 over WebSocket and then asks the browser to decode it. That extra hop and the decoder choice are where most of the operational surprises live.
Maintenance, licence and the cost of staying current
The repository is not archived. The last push was on 2026-09-10. Release history is uneven: v0.7.1 in December 2021, v0.8.0 in August 2022, v0.8.1 in March 2024, while the package version on the branch reads `0.9.0-dev`. If you pin to a tag, you are pinning to something older than the branch, and the README's own instructions acknowledge that by telling you to check tags before installing.
The upgrade cost sits mostly in the native and pinned pieces. Appium is a dependency, and the XCUITest driver version is pinned in `package.json` under `config.xcuitestDriverVersion` with a comment that it is not an npm dependency but is installed into APPIUM_HOME by the postinstall script, and that it must stay compatible with the pinned `appium` peer dependency. Updating Appium therefore means checking that pin, not just bumping a version range. The scrcpy fork is a second moving part: it lives in the repository, so upstream scrcpy changes do not reach you automatically.
Licensing is MIT, per both the repository metadata and the `license` field in `package.json`. That covers ws-scrcpy itself. It does not automatically cover what it bundles or talks to: the README names several third-party projects as decoder bases, and the iOS path pulls in Appium and WebDriverAgent, which carry their own terms. Check those separately if you redistribute a build.
Editorial conclusion
Adopt ws-scrcpy when you need Android mirroring and control inside a browser and can accept a Node.js process holding adb, plus a modified scrcpy fork on the device. Do not adopt it for iOS in production: the README calls that path experimental and it is not built by default, and the MJPEG server is marked temporarily suspended. Before committing, verify that your Node.js and node-gyp toolchain builds the native modules on your platform, that the latest git tag is the version you want, and that your browser supports the decoder you plan to rely on.
Frequently asked questions
What does ws-scrcpy do?
It is a web client for Genymobile/scrcpy: a Node.js server connects to an Android device over adb, streams H264 video to the browser over WebSocket, and forwards touch, keyboard, clipboard, shell and file operations back to the device.
Is scrcpy trustworthy?
The README makes no security claim either way. What it does state is that ws-scrcpy is MIT licensed, that adb debugging must be enabled on the device, and the repository root carries a SECURITY.md file.
How do I delete scrcpy?
The README does not document an uninstall step for ws-scrcpy. Installation is a git clone plus npm install, and the start script builds into a dist directory, so removal is a matter of deleting the cloned directory and the generated dist folder.
Is there anything better than scrcpy?
That depends on the constraint. Plain scrcpy avoids the server, the browser and the WebSocket hop entirely and runs as a single desktop binary, while ws-scrcpy adds remote shell, file listing and multi-viewer access through a browser tab.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/netristv-ws-scrcpy)Star history chart for your README
[](https://hysenlabs.com/projects/netristv-ws-scrcpy)Was this useful?