# netristv/ws-scrcpy architecture

> Architecture diagram of the GitHub repository netristv/ws-scrcpy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/netristv/ws-scrcpy
- Repository: https://github.com/netristv/ws-scrcpy

## Overview

##### Project type and purpose
- This is a full‑stack single‑page web application (“ws‑scrcpy”) whose purpose is to remotely mirror and control Android (scrcpy) and experimental iOS devices in the browser.
- The README confirms it serves static UI assets over HTTP, exposes a WebSocket API, proxies to device‐side scrcpy/WebDriverAgent, and decodes H.264 frames in the browser via multiple pluggable decoders.

##### File structure
- Top level:
- config examples, lint & build files, docs/
- package.json, tsconfig.json, webpack/
- src/ layers:
- src/app/ → frontend application code (UI components, event handlers, video players, device‐specific clients & toolboxes)
- src/common/ → shared constants, message/channel definitions, typed event emitter
- src/packages/multiplexer/ → multiplexing logic for WS channels
- src/public/ → static assets (index.html, images)
- src/style/ → CSS styles
- src/server/ → backend code (HTTP/WebSocket servers, middleware, services for appl‑device & goog‑device, multiplexer)
- src/types/ → TypeScript definitions for messages, params, device descriptors
- webpack/ holds build configurations with override mechanism for feature flags.

##### README for additional insights
- Confirms HTTP server for UI, WebSocket server with multiple “channels” (video, control messages, file listing, shell, devtools) using a multiplexer.
- Lists supported frontend decoders (MSE, Broadway, TinyH264, WebCodecs).
- Describes device backends: scrcpy over WS for Android, optional MJPEG server, WebDriverAgent for iOS, file push, remote shell.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser Layer
    subgraph "Browser (Frontend)"
        direction TB
        UI["UI Layer"]:::frontend
        Toolbox["Toolbox"]:::frontend
        subgraph "Video Decoder Modules"
            direction TB
            BasePlayer["BasePlayer"]:::frontend
            BroadwayPlayer["BroadwayPlayer"]:::frontend
            MsePlayer["MsePlayer"]:::frontend
            MsePlayerQV["MsePlayerForQVHack"]:::frontend
            TinyH264Player["TinyH264Player"]:::frontend
            WebCodecsPlayer["WebCodecsPlayer"]:::frontend
            MjpegPlayer["MjpegPlayer"]:::frontend
        end
        subgraph "Interaction Handlers"
            direction TB
            IH["InteractionHandler"]:::frontend
            SimpleIH["SimpleInteractionHandler"]:::frontend
            FeaturedIH["FeaturedInteractionHandler"]:::frontend
        end
        ShellClient["ShellClient"]:::frontend
        ScrcpyClient["StreamClientScrcpy"]:::frontend
        ScrcpyReceiver["StreamReceiverScrcpy"]:::frontend
        WdaClient["WdaProxyClient"]:::frontend
        MJPEGClient["StreamClientMJPEG"]:::frontend
        CommonMux["Common Messages & Multiplexer Interface"]:::shared
    end

    %% Backend Layer
    subgraph "Node.js Server (Backend)"
        direction TB
        HTTPServer["HTTP Server"]:::backend
        WebSocketServer["WebSocket Server"]:::backend
        WSMultiplexer["WebsocketMultiplexer"]:::backend
        subgraph "Google-device Middleware"
            direction TB
            GP1["WebsocketProxyOverAdb"]:::backend
            GP2["DeviceTracker"]:::backend
            GP3["FileListing"]:::backend
            GP4["RemoteShell"]:::backend
            GP5["RemoteDevtools"]:::backend
        end
        subgraph "Google-device Services"
            direction TB
            GService1["ScrcpyServer"]:::backend
            GService2["ControlCenter"]:::backend
        end
        subgraph "Apple-device Middleware"
            direction TB
            AP1["WebDriverAgentProxy"]:::backend
            AP2["QVHStreamProxy"]:::backend
            AP3["DeviceTracker"]:::backend
        end
        subgraph "Apple-device Services"
            direction TB
            AService1["WDARunner"]:::backend
            AService2["QvhackRunner"]:::backend
            AService3["ControlCenter"]:::backend
        end
        SharedUtils["Config & Utils"]:::shared
        subgraph "Core Backend Processes"
            direction TB
            ProcRunner["ProcessRunner"]:::backend
            BaseControl["BaseControlCenter"]:::backend
            ServiceBase["Service"]:::backend
        end
    end

    %% Device Layer
    subgraph "Device-side"
        direction TB
        ScrcpyServerJar["scrcpy-server.jar"]:::device
        WSqvh["ws-qvh MJPEG server"]:::device
        WDA["WebDriverAgent"]:::device
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        ADB["adb CLI"]:::external
        ScrcpyBin["scrcpy binary"]:::external
        NodeGyp["node-gyp addons"]:::external
        WASM["WASM Decoder Modules"]:::external
    end

    %% Type Definitions & Build
    subgraph "Supporting Files"
        direction TB
        StaticAssets["Static Assets (HTML/CSS/Images)"]:::shared
        BuildConfig["Build & Feature-Flag Config"]:::shared
        TypeDefs["Type Definitions"]:::shared
    end

    %% Connections - Frontend to Backend
    HTTPServer -->|"serves UI assets"| UI
    HTTPServer -->|"serves JS/CSS"| Toolbox
    WebSocketServer -->|"upgrades WS"| WSMultiplexer
    UI -->|"WS video/control/etc"| WebSocketServer
    CommonMux -->|"interfaces WS channels"| WSMultiplexer

    %% Frontend internal flows
    UI -->|"uses decoders"| BasePlayer
    UI -->|"touch & keyboard"| IH
    IH -->|"delegates"| SimpleIH
    IH -->|"delegates"| FeaturedIH
    BasePlayer --> BroadwayPlayer
    BasePlayer --> MsePlayer
    BasePlayer --> MsePlayerQV
    BasePlayer --> TinyH264Player
    BasePlayer --> WebCodecsPlayer
    BasePlayer --> MjpegPlayer
    UI --> ShellClient
    UI --> ScrcpyClient
    UI --> ScrcpyReceiver
    UI --> WdaClient
    UI --> MJPEGClient

    %% Backend WS channels to middleware
    WSMultiplexer --> GP1
    WSMultiplexer --> GP2
    WSMultiplexer --> GP3
    WSMultiplexer --> GP4
    WSMultiplexer --> GP5
    WSMultiplexer --> AP1
    WSMultiplexer --> AP2
    WSMultiplexer --> AP3

    %% Middleware to services
    GP1 --> GService1
    GP4 --> ProcRunner
    AP1 --> AService1
    AP2 --> AService2

    %% Services to devices and external
    GService1 -->|"spawns"| ScrcpyServerJar
    GService1 -->|"uses"| ScrcpyBin
    GService1 -->|"forwards ADB"| ADB
    AService1 --> WDA
    AService2 --> WSqvh
    ProcRunner -->|"runs"| ServiceBase
    ServiceBase --> BaseControl
    BaseControl --> SharedUtils

    %% Supporting files usage
    HTTPServer --> StaticAssets
    BuildConfig --> UI
    BuildConfig --> HTTPServer
    TypeDefs --> CommonMux
    TypeDefs --> SharedUtils

    %% Click Events
    click UI "https://github.com/netristv/ws-scrcpy/tree/master/src/app/ui"
    click Toolbox "https://github.com/netristv/ws-scrcpy/tree/master/src/app/toolbox"
    click BasePlayer "https://github.com/netristv/ws-scrcpy/blob/master/src/app/player/BasePlayer.ts"
    click BroadwayPlayer "https://github.com/netristv/ws-scrcpy/blob/master/src/app/player/BroadwayPlayer.ts"
    click MsePlayer "https://github.com/netristv/ws-scrcpy/blob/master/src/app/player/MsePlayer.ts"
    click MsePlayerQV "https://github.com/netristv/ws-scrcpy/blob/master/src/app/player/MsePlayerForQVHack.ts"
    click TinyH264Player "https://github.com/netristv/ws-scrcpy/blob/master/src/app/player/TinyH264Player.ts"
    click WebCodecsPlayer "https://github.com/netristv/ws-scrcpy/blob/master/src/app/player/WebCodecsPlayer.ts"
    click MjpegPlayer "https://github.com/netristv/ws-scrcpy/blob/master/src/app/player/MjpegPlayer.ts"
    click IH "https://github.com/netristv/ws-scrcpy/blob/master/src/app/interactionHandler/InteractionHandler.ts"
    click SimpleIH "https://github.com/netristv/ws-scrcpy/blob/master/src/app/interactionHandler/SimpleInteractionHandler.ts"
    click FeaturedIH "https://github.com/netristv/ws-scrcpy/blob/master/src/app/interactionHandler/FeaturedInteractionHandler.ts"
    click ShellClient "https://github.com/netristv/ws-scrcpy/blob/master/src/app/googDevice/client/ShellClient.ts"
    click ScrcpyClient "https://github.com/netristv/ws-scrcpy/blob/master/src/app/googDevice/client/StreamClientScrcpy.ts"
    click ScrcpyReceiver "https://github.com/netristv/ws-scrcpy/blob/master/src/app/googDevice/client/StreamReceiverScrcpy.ts"
    click WdaClient "https://github.com/netristv/ws-scrcpy/blob/master/src/app/applDevice/client/WdaProxyClient.ts"
    click MJPEGClient "https://github.com/netristv/ws-scrcpy/blob/master/src/app/applDevice/client/StreamClientMJPEG.ts"
    click CommonMux "https://github.com/netristv/ws-scrcpy/blob/master/src/packages/multiplexer/Multiplexer.ts"
    click HTTPServer "https://github.com/netristv/ws-scrcpy/blob/master/src/server/services/HttpServer.ts"
    click WebSocketServer "https://github.com/netristv/ws-scrcpy/blob/master/src/server/services/WebSocketServer.ts"
    click WSMultiplexer "https://github.com/netristv/ws-scrcpy/blob/master/src/server/mw/WebsocketMultiplexer.ts"
    click GP1 "https://github.com/netristv/ws-scrcpy/blob/master/src/server/goog-device/mw/WebsocketProxyOverAdb.ts"
    click GP2 "https://github.com/netristv/ws-scrcpy/blob/master/src/server/goog-device/mw/DeviceTracker.ts"
    click GP3 "https://github.com/netristv/ws-scrcpy/blob/master/src/server/goog-device/mw/FileListing.ts"
    click GP4 "https://github.com/netristv/ws-scrcpy/blob/master/src/server/goog-device/mw/RemoteShell.ts"
    click GP5 "https://github.com/netristv/ws-scrcpy/blob/master/src/server/goog-device/mw/RemoteDevtools.ts"
    click GService1 "https://github.com/netristv/ws-scrcpy/blob/master/src/server/goog-device/services/ScrcpyServer.ts"
    click GService2 "https://github.com/netristv/ws-scrcpy/blob/master/src/server/goog-device/services/ControlCenter.ts"
    click AP1 "https://github.com/netristv/ws-scrcpy/blob/master/src/server/appl-device/mw/WebDriverAgentProxy.ts"
    click AP2 "https://github.com/netristv/ws-scrcpy/blob/master/src/server/appl-device/mw/QVHStreamProxy.ts"
    click AP3 "https://github.com/netristv/ws-scrcpy/blob/master/src/server/appl-device/mw/DeviceTracker.ts"
    click AService1 "https://github.com/netristv/ws-scrcpy/blob/master/src/server/appl-device/services/WDARunner.ts"
    click AService2 "https://github.com/netristv/ws-scrcpy/blob/master/src/server/appl-device/services/QvhackRunner.ts"
    click AService3 "https://github.com/netristv/ws-scrcpy/blob/master/src/server/appl-device/services/ControlCenter.ts"
    click SharedUtils "https://github.com/netristv/ws-scrcpy/blob/master/src/server/Config.ts"
    click ProcRunner "https://github.com/netristv/ws-scrcpy/blob/master/src/server/services/ProcessRunner.ts"
    click ServiceBase "https://github.com/netristv/ws-scrcpy/blob/master/src/server/services/Service.ts"
    click BuildConfig "https://github.com/netristv/ws-scrcpy/blob/master/webpack/ws-scrcpy.common.ts"
    click StaticAssets "https://github.com/netristv/ws-scrcpy/blob/master/src/public/index.html"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef backend fill:#D5F5E3,stroke:#196F3D,color:#145A32
    classDef device fill:#FCF3CF,stroke:#B9770E,color:#6E2C00
    classDef external fill:#E5E7E9,stroke:#566573,color:#1C2833
    classDef shared fill:#F2F3F4,stroke:#7B7D7D,color:#17202A
```
