Introducing a new way to review your PRs.

Read the announcement

genymobile / scrcpy

Display and control your Android device

View on GitHub

13 documents · Updated Nov 16, 2026

overview

Knowledge Base updated: 2026-11-16

Knowledge Base Index

1. Orientation

This repository is scrcpy, a native desktop client plus Android server that mirrors and controls an Android device over ADB/USB. The highest-level flow is: the desktop client starts and pushes the server, the Android server captures video/audio and accepts control messages, and the client decodes/renders media while sending user input back.

Main parts:

  • Native client under app/: CLI, ADB/server bootstrap, media decode/render/playback, input/control, recording, file push, and platform utilities.
  • Android server under server/: runtime entrypoint, capture/encode pipelines, device actions, control protocol, wrappers around Android services, and model/util support.
  • Build and release surface at repo root, app/deps/, app/tests/, server/src/test/, and release/: Meson/Gradle integration, dependency scripts, test entrypoints, packaging, and release automation.

Critical state is mostly transient/in-memory rather than persisted in databases: sockets/tunnels carry media and control streams, ADB identifies and launches devices, SDL/OpenGL/client buffers hold runtime media state, and Android framework wrappers expose device/display/input state.

2. Architecture diagrams

flowchart LR
  User[Desktop user] --> ClientCLI[app native client]
  ClientCLI --> ADB[ADB transport]
  ADB --> AndroidDevice[Android device]

  subgraph Client[app/ native client]
    ClientCLI --> ClientVideo[video decode/render]
    ClientCLI --> ClientAudio[audio playback]
    ClientCLI --> ClientControl[input/control]
    ClientCLI --> Recording[recording/file push]
    ClientVideo --> Utilities[platform utilities/traits]
    ClientAudio --> Utilities
    ClientControl --> Utilities
  end

  subgraph Server[server/ Android server]
    ServerRuntime[Server runtime] --> ServerVideo[video capture/encode]
    ServerRuntime --> ServerAudio[audio capture/encode]
    ServerRuntime --> ServerControl[control/device actions]
    ServerRuntime --> Wrappers[Android wrappers/models/utils]
  end

  ADB <--> ServerRuntime
  ServerVideo --> ClientVideo
  ServerAudio --> ClientAudio
  ClientControl --> ServerControl

  subgraph Build[build/test/release]
    Meson[Meson native build]
    Gradle[Gradle server build]
    Release[release scripts]
  end
  Meson --> ClientCLI
  Gradle --> ServerRuntime
  Release --> Meson
  Release --> Gradle
sequenceDiagram
  participant User
  participant Client as app client
  participant ADB as adb/tunnel
  participant Server as Android Server
  participant Device as Android services

  User->>Client: run scrcpy with options
  Client->>ADB: select device and start tunnel
  Client->>Server: push/launch server with options
  Server->>Device: initialize wrappers and capture/control services
  Server-->>Client: video/audio/control sockets ready
  Server-->>Client: encoded media streams
  Client-->>User: render video and play audio
flowchart TD
  AndroidCapture[server video/audio capture] --> Encoders[server encoders]
  Encoders --> Streams[desktop connection streams]
  Streams --> ClientDemux[client demux/packet handling]
  ClientDemux --> VideoDecode[video decoder]
  ClientDemux --> AudioDecode[audio player/regulator]
  VideoDecode --> FrameBuffer[frame buffer]
  FrameBuffer --> Screen[SDL/OpenGL screen]
  AudioDecode --> AudioOut[SDL audio output]
  ClientDemux --> Recorder[optional recorder]
sequenceDiagram
  participant SDL as SDL/input events
  participant Client as client input/controller
  participant Wire as control channel
  participant Server as server controller
  participant Android as Android wrappers

  SDL->>Client: keyboard/mouse/gamepad event
  Client->>Client: map coordinates/backends
  Client->>Wire: serialize ControlMessage
  Wire->>Server: read/decode message
  Server->>Android: inject input or perform device action
  Server-->>Wire: optional DeviceMessage
  Wire-->>Client: clipboard/display/status response

3. Glossary

  • scrcpy: the product implemented by this repo; a desktop client that mirrors and controls Android devices.
  • AOA: Android Open Accessory input path used by some client USB/HID control backends under app/src/usb/**.
  • UHID: user-space HID input path used by both client-side control plumbing and server-side HID management.
  • Server: the Android-side Java process launched by the desktop client from server/…/Server.java.

4. Codebase-wide invariants

  • The repository is split into a native client and Android server: client sources live under app/src/**, while Android server sources live under server/src/main/java/com/genymobile/scrcpy/**.
  • Native client public/internal C module boundaries are generally paired .c/.h files, visible across examples like app/…/controller.c + app/…/controller.h and app/…/decoder.c + app/…/decoder.h.
  • Server feature areas are Java packages under server/src/main/java/com/genymobile/scrcpy/, with major domains represented by audio/, video/, control/, display/, device/, model/, util/, and wrappers/.
  • Build/release is intentionally dual-stack: native/client build configuration is rooted in meson.build and app/meson.build, while Android server build configuration is rooted in build.gradle, settings.gradle, and server/build.gradle.

5. Routing table