DOCSEARCHbyAlgolia
Submit Docs

ws-scrcpy

repository·master·Indexed 25 days ago

https://github.com/netristv/ws-scrcpy

A web-based client for scrcpy that enables streaming and control of Android and iOS devices directly from a web browser via WebSockets. It supports multiple H264 decoders (Mse, Broadway, TinyH264, and WebCodecs), remote shell access, file management, and Android devtools forwarding. iOS support is provided experimentally via WebDriverAgent and Appium for screen casting and remote control.

Tokens
7.6K
Snippets
8
Records
48
Agent score
82%

What's inside ws-scrcpy

  1. Android Remote Control and File Features

    master

    The Android implementation supports the following remote operations:

    • Remote Control: Touch events (including multi-touch), multi-touch emulation (using CTRL or SHIFT + CTRL), mouse wheel/touchpad scrolling, keyboard event capturing, ASCII text injection, clipboard sync, and device rotation.
    • File Push: Drag & drop an APK to push it to /data/local/tmp.
    • Remote Shell: Access adb shell directly in the browser via an integrated terminal.
    • File Management: List files, upload via drag & drop, and download files.

  2. Android Screen Casting Players

    master

    ws-scrcpy uses a modified version of scrcpy to stream H264 video. You can choose from several decoders via custom build configuration:

    • Mse Player: Uses HTML5 Video via the Media Source API. It creates mp4 containers from NALUs. Requires video/mp4; codecs="avc1.42E01E" support. Can potentially use hardware acceleration.
    • Broadway Player: A software video-decoder compiled into a WASM module. Requires WebAssembly and preferably WebGL.
    • TinyH264 Player: A software video-decoder compiled into a WASM module (updated version of Broadway). Requires WebAssembly, WebWorkers, and WebGL.
    • WebCodecs Player: Uses the browser's built-in media decoder (software or hardware). Currently only available in Chromium-based browsers.

  3. How Devtools forwarding works in ws-scrcpy

    master

    ws-scrcpy allows you to forward and proxy a WebKit debug-socket from an Android device to your browser. This enables remote debugging of webpages or WebViews running on the device.

    Server-side process:

    1. The server identifies devtools sockets using: adb shell 'grep -a devtools_remote /proc/net/unix'.
    2. For each discovered socket, the server requests /json and /json/version.
    3. The server replaces the original WebSocket address in the response with the ws-scrcpy hostname.
    4. The server aggregates this data and transmits it to the client.

    Client-side options:

    Because the devtoolsFrontendUrl provided by a remote page might not be compatible with your specific browser version, the client provides three distinct debugging links to ensure compatibility.

  4. Understand the ws-scrcpy architecture and data flow

    master

    ws-scrcpy acts as a bridge between an Android device and a web browser. The architecture consists of three main components:

    1. Android Device: Runs scrcpy and communicates via adb (over USB or TCP).
    2. Server: A Node.js application that runs scrcpy and manages connections. It serves static files (HTML, JS) via HTTP and provides a WebSocket interface for device management. It also acts as an adb client.
    3. Client (Web Browser): Connects to the server via WebSockets to send input events and receive the video stream.

    Data Flow Summary:

    • Video Stream: Android Device $\rightarrow$ Server $\rightarrow$ Web Browser (via WebSocket).
    • Input Events: Web Browser $\rightarrow$ Server $\rightarrow$ Android Device (via WebSocket).
    • Device Management: The Server provides a list of available devices to the Client via WebSocket.
    • Static Assets: The Server serves the web client files via HTTP.

  5. Debug the Node.js server

    master

    To debug the Node.js server, build the development version, navigate to the dist directory, and start the server using the --inspect-brk flag. You can also use the DEBUG environment variable to enable detailed logging.

    npm run dist:dev
cd dist
# Standard debug
node --inspect-brk ./index.js

# Debug with verbose logging
DEBUG=* node --inspect-brk ./index.js

  7. iOS Screen Casting and Remote Control

    master

    Screen Casting

    Note: This is an experimental feature and is not built by default.

    Requires ws-qvh to be available in your PATH. For stability:

    • Set the device's Auto-Lock to Never.
    • Connect the iPhone directly (avoid USB hubs).
    • Ensure no other process (like a standalone qvh) is using the device.

    Remote Control

    Control is provided via WebDriverAgent (WDA) driven by an integrated Appium server. Supported actions include simple touch, scroll/swipe, and Home button clicks.

    One-time Device Setup (Real iOS Device)

    You must build, sign, and trust WebDriverAgent on the device once using Xcode:

    1. Open WebDriverAgent.xcodeproj located in .appium-home/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent/.
    2. Select the WebDriverAgentRunner scheme.
    3. Set your Team and a unique Bundle Identifier.
    4. Run it on the device (⌘U).
    5. On the device, trust the developer certificate in Settings → General → VPN & Device Management and enable Developer Mode (iOS 16+).

    Note: The first control action may take a few minutes as Appium builds and launches WDA on demand.

  8. Debug the Android server (scrcpy-server.jar)

    master

    Debugging the Android server requires a multi-step process involving the Node.js server, ADB, and Android Studio.

    1. Start the Node.js server.
    2. Kill the server from the UI (using the button with the cross and PID number).
    3. Push the server package to the device via ADB.
    4. Set up port forwarding.
    5. Use adb shell to run the server with JDWP enabled for remote debugging.
    6. Connect to the device using a Remote Debug configuration in Android Studio (Host: localhost, Port: 5005).

  9. Install and run ws-scrcpy

    master

    To install and run ws-scrcpy from source, ensure you have Node.js, node-gyp, and build tools installed. Follow these steps:

    1. Clone the repository.
    2. Navigate to the directory.
    3. Install dependencies.
    4. Start the server.

    For a stable version, it is recommended to check out the latest git tag.

    git clone https://github.com/NetrisTV/ws-scrcpy.git
cd ws-scrcpy

# Optional: switch to a stable version
# git tag -l
# git checkout vX.Y.Z

npm install
npm start

  10. Requirements for ws-scrcpy

    master

    Browser Requirements

    Your browser must support:

    • WebSockets
    • Media Source Extensions (MSE) and h264 decoding
    • WebWorkers
    • WebAssembly

    Server Requirements

    • Node.js v10+
    • node-gyp
    • adb executable must be available in the PATH environment variable

    Device Requirements (Android)

    • Android 5.0+ (API 21+)
    • Enabled adb debugging
    • Some devices may require an additional option to enable keyboard and mouse control.

  11. Use the three Devtools debugging links

    master

    When debugging a webpage or WebView, the client provides three different link types. Note: You cannot open the bundled or remote links by clicking them or using 'open link in new tab' due to browser restrictions. You must copy the link and paste it manually into your address bar.

    1. inspect: This is the original link provided by the remote browser (via the /json request), but with the WebSocket address updated to point to the ws-scrcpy proxy. This link only works if it points to a local version of devtools already bundled with your browser.

    2. bundled: This link uses the version of devtools bundled with your Chromium-based browser, without specifying a specific revision or version of the remote target. This mimics the behavior of the chrome://inspect page in Chromium.

      • Format: devtools://devtools/bundled/inspector.html?ws=<WebSocketAddress>

    3. remote: This link uses a bundled devtools but specifies the exact revision and version of the remote target. This is only available if the original devtoolsFrontendUrl contains a revision. This mimics the behavior of the chrome://inspect page in Google Chrome.

      • Format: devtools://devtools/remote/serve_rev/@<Revision>/inspector.html?remoteVersion=<Version>&remoteFrontend=true&ws=<WebSocketAddress>